Placing scripts in the generated project

README.md

@@ -2,9 +2,13 @@
 
 **Arduino project generator and build tool -- forges clean embedded projects.**
 
-A single binary that scaffolds testable Arduino projects with hardware abstraction,
-Google Mock infrastructure, and a streamlined build/upload/monitor workflow. Works on
-Linux and Windows.
+A single binary that scaffolds self-contained Arduino projects with hardware
+abstraction, Google Mock infrastructure, and a streamlined build/upload/monitor
+workflow. Works on Linux and Windows.
+
+Generated projects are fully standalone -- they only need `arduino-cli` in
+PATH. The Anvil binary is a scaffolding and diagnostic tool, not a runtime
+dependency.
 
 Anvil is a [Nexus Workshops](https://nxlearn.net) project.
 
@@ -36,20 +40,37 @@ your system is ready.
 # Create a new project
 anvil new blink
 
-# Check system health
-anvil doctor
+# Enter the project
+cd blink
 
-# Find your board
-anvil devices
+# Compile (verify only)
+./build.sh
+
+# Compile and upload to board
+./upload.sh
 
 # Compile, upload, and open serial monitor
-cd blink
-anvil build --monitor blink
+./upload.sh --monitor
 
 # Run host-side tests (no board needed)
-cd test && ./run_tests.sh
+./test/run_tests.sh
 ```
 
+On Windows, use `build.bat`, `upload.bat`, `monitor.bat`, and
+`test\run_tests.bat`.
+
+## What Anvil Does vs. What the Project Does
+
+| Need Anvil for                | Don't need Anvil for          |
+|-------------------------------|-------------------------------|
+| `anvil new` (create project)  | `./build.sh` (compile)        |
+| `anvil doctor` (diagnose)     | `./upload.sh` (flash)         |
+| `anvil setup` (install core)  | `./monitor.sh` (serial)       |
+| `anvil devices` (port scan)   | `./test/run_tests.sh` (test)  |
+
+Once a project is created, Anvil is optional. Students clone the repo,
+plug in a board, and run `./upload.sh`.
+
 ## Commands
 
 | Command           | Description                                    |
@@ -58,9 +79,12 @@ cd test && ./run_tests.sh
 | `anvil doctor`    | Check system prerequisites                      |
 | `anvil setup`     | Install arduino-cli and AVR core                |
 | `anvil devices`   | List connected boards and serial ports          |
-| `anvil build DIR` | Compile and upload a sketch                     |
-| `anvil upload DIR`| Upload cached build (no recompile)              |
-| `anvil monitor`   | Open serial monitor (`--watch` for persistent)  |
+| `anvil build DIR` | Compile and upload a sketch (convenience)       |
+| `anvil upload DIR`| Upload cached build (convenience)               |
+| `anvil monitor`   | Open serial monitor (convenience)               |
+
+The `build`, `upload`, and `monitor` commands are convenience wrappers.
+They do the same thing as the generated scripts.
 
 ## Project Architecture
 
@@ -74,6 +98,9 @@ your-project/
     lib/app/your-project_app.h      -- app logic (testable)
     test/mocks/mock_hal.h           -- Google Mock HAL
     test/test_unit.cpp              -- unit tests
+    build.sh / build.bat            -- compile
+    upload.sh / upload.bat          -- compile + flash
+    monitor.sh / monitor.bat        -- serial monitor
     .anvil.toml                     -- project config
 ```