Updated readme files

templates/basic/README.md.tmpl

@@ -7,31 +7,42 @@ in PATH -- the Anvil binary is not required for day-to-day work.
 
 ## Quick Start
 
+On **Linux/macOS**:
 ```bash
-# Compile only (verify)
-./build.sh
-
-# Compile and upload to board
-./upload.sh
-
-# Compile, upload, and open serial monitor
-./upload.sh --monitor
-
-# Open serial monitor (no compile)
-./monitor.sh
-
-# Persistent monitor (reconnects after reset/replug)
-./monitor.sh --watch
-
-# Run host-side unit tests (no board needed)
-./test/run_tests.sh
+./build.sh                  # compile only (verify)
+./upload.sh                 # compile + upload to board
+./upload.sh --monitor       # compile, upload, open serial monitor
+./monitor.sh                # serial monitor (no compile)
+./monitor.sh --watch        # persistent monitor (reconnects after reset)
+./test/run_tests.sh         # host-side unit tests (no board needed)
 ```
 
-On Windows, use `build.bat`, `upload.bat`, `monitor.bat`, and
-`test\run_tests.bat` instead.
+On **Windows**:
+```bat
+build                       REM compile only
+upload                      REM compile + upload
+upload --monitor            REM compile, upload, open serial monitor
+monitor                     REM serial monitor
+test\run_tests              REM host-side unit tests
+```
 
-All scripts read settings from `.anvil.toml` -- edit it to change
-the board, baud rate, include paths, or compiler flags.
+All scripts read settings from `.anvil.toml` and port config from
+`.anvil.local` (if present).
+
+## Selecting a Board
+
+The scripts auto-detect your board when you run `upload` or `monitor`.
+To save a specific device so it persists across sessions:
+
+```bash
+anvil devices               # see what's connected
+anvil devices --set COM3    # save that port (also captures VID:PID)
+anvil devices --get         # check what's saved
+```
+
+This writes `.anvil.local`, which is gitignored. Each machine keeps its own.
+The VID:PID is captured automatically so the scripts can find your device
+even if the COM port number changes after a replug.
 
 ## Project Structure
 
@@ -51,12 +62,13 @@ the board, baud rate, include paths, or compiler flags.
             sim_hal.h              Stateful simulator HAL
         test_unit.cpp              Unit tests
         CMakeLists.txt             Test build system
-        run_tests.sh               Test runner (Linux/Mac)
-        run_tests.bat              Test runner (Windows)
+        run_tests.sh / .bat        Test runner
     build.sh / build.bat           Compile sketch
     upload.sh / upload.bat         Compile + upload to board
     monitor.sh / monitor.bat       Serial monitor
-    .anvil.toml                    Project configuration
+    _detect_port.ps1               Port detection helper (Windows)
+    .anvil.toml                    Project config (tracked by git)
+    .anvil.local                   Machine-specific config (gitignored)
 ```
 
 ## Architecture
@@ -72,7 +84,9 @@ Two HAL implementations:
 
 ## Configuration
 
-Edit `.anvil.toml` to change board, baud rate, or build settings:
+### .anvil.toml (tracked by git)
+
+Shared project settings:
 
 ```toml
 [build]
@@ -85,6 +99,15 @@ extra_flags = ["-Werror"]
 baud = 115200
 ```
 
+### .anvil.local (not tracked by git)
+
+Machine-specific port assignment, created by `anvil devices --set`:
+
+```toml
+port = "COM3"
+vid_pid = "0403:6001"
+```
+
 ## Prerequisites
 
 - `arduino-cli` in PATH with `arduino:avr` core installed