From afea0f26f238086145b2c03e00565ab486ce8b34 Mon Sep 17 00:00:00 2001
From: jabahum <jabajnan8@gmail.com>
Date: Sat, 24 Oct 2026 19:51:21 +0300
Subject: [PATCH] Align project commands and document all workflows

---
 .github/workflows/ci.yml                      |  24 +-
 .github/workflows/release.yml                 |   4 +-
 CHANGELOG.md                                  |   5 +
 Makefile                                      |  56 +--
 README.md                                     |  76 ++--
 assets.go                                     |   6 +-
 docs/commands.md                              | 327 ++++++++++++++++++
 internal/add/add.go                           |   8 +-
 internal/cli/cli.go                           |  75 +++-
 internal/cli/cli_test.go                      |  62 ++++
 internal/doctor/doctor.go                     |   2 +-
 internal/generator/generator_test.go          |   4 +-
 internal/generator/scripts_test.go            | 175 ++++++++++
 scripts/build-release.sh                      |  75 ++--
 scripts/smoke.sh                              |  40 +++
 templates/flutter_foundations/README.md       |  52 ++-
 templates/flutter_foundations/pubspec.yaml    |  16 +-
 .../flutter_foundations/scripts/run_flavor.sh |  20 +-
 .../flutter_foundations/scripts/setup.sh      |   8 +-
 .../scripts/validate_bricks.sh                |   9 +-
 templates/go-foundations/Makefile             |  63 +++-
 templates/go-foundations/README.md            |  34 ++
 .../scripts/generate-dev-keys.sh              |   7 +
 templates/react-foundations/README.md         |  22 ++
 templates/react-foundations/package.json      |   3 +-
 templates/react-foundations/scripts/clean.js  |   7 +
 templates/rust-foundations/README.md          |  47 ++-
 templates/rust-foundations/scripts/check.ps1  |  33 ++
 templates/rust-foundations/scripts/check.sh   |  17 +
 templates/vanilla-js-foundations/README.md    |  22 ++
 templates/vanilla-js-foundations/package.json |   3 +-
 .../vanilla-js-foundations/scripts/clean.js   |   7 +
 32 files changed, 1140 insertions(+), 169 deletions(-)
 create mode 100644 docs/commands.md
 create mode 100644 internal/generator/scripts_test.go
 create mode 100755 scripts/smoke.sh
 create mode 100644 templates/react-foundations/scripts/clean.js
 create mode 100644 templates/rust-foundations/scripts/check.ps1
 create mode 100755 templates/rust-foundations/scripts/check.sh
 create mode 100644 templates/vanilla-js-foundations/scripts/clean.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a580660..859642a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -24,6 +24,9 @@ jobs:
       - run: go test ./...
       - run: go vet ./...
       - run: go build -trimpath ./cmd/foundry
+      - name: Embedded generation smoke check
+        if: runner.os == 'Linux'
+        run: make smoke
 
   formatting:
     name: Formatting
@@ -34,7 +37,7 @@ jobs:
         with:
           go-version: '1.23.x'
           cache: true
-      - run: test -z "$(gofmt -l .)"
+      - run: make format-check
 
   cross-compile:
     name: Cross-compile release targets
@@ -45,7 +48,7 @@ jobs:
         with:
           go-version: '1.23.x'
           cache: true
-      - run: ./scripts/build-release.sh ci
+      - run: make release VERSION=ci
 
   web-templates:
     name: Web template (${{ matrix.template }}, Node ${{ matrix.node }})
@@ -86,6 +89,8 @@ jobs:
             toolchain: '1.85.0'
     env:
       RUSTDOCFLAGS: -D warnings
+      RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }}
+      CARGO_NET_OFFLINE: 'true'
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
@@ -96,13 +101,12 @@ jobs:
         run: rustup toolchain install ${{ matrix.toolchain }} --profile minimal --component rustfmt --component clippy
       - name: Generate the bundled template
         run: go run ./cmd/foundry new rust-check --template rust --destination "${{ runner.temp }}/foundry-rust" --no-hooks
-      - run: cargo +${{ matrix.toolchain }} fmt --all -- --check
+      - name: Rust quality gate (POSIX)
+        if: runner.os != 'Windows'
+        run: bash scripts/check.sh
         working-directory: ${{ runner.temp }}/foundry-rust
-      - run: cargo +${{ matrix.toolchain }} test --locked --offline
-        working-directory: ${{ runner.temp }}/foundry-rust
-      - run: cargo +${{ matrix.toolchain }} clippy --locked --offline --all-targets -- -D warnings
-        working-directory: ${{ runner.temp }}/foundry-rust
-      - run: cargo +${{ matrix.toolchain }} doc --locked --offline --no-deps
-        working-directory: ${{ runner.temp }}/foundry-rust
-      - run: cargo +${{ matrix.toolchain }} build --release --locked --offline
+      - name: Rust quality gate (PowerShell)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: ./scripts/check.ps1
         working-directory: ${{ runner.temp }}/foundry-rust
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5ab1e9a..32c3492 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -37,8 +37,8 @@ jobs:
           else
             echo "value=$INPUT_VERSION" >> "$GITHUB_OUTPUT"
           fi
-      - name: Test
-        run: go test ./...
+      - name: Check Foundry
+        run: make check
       - name: Build archives and checksums
         env:
           RELEASE_VERSION: ${{ steps.version.outputs.value }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b945e8..042f06a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Align quality command meanings across the CLI repository and all five foundations; retain existing Make/Melos aliases.
+- Add comprehensive command/workflow documentation, script help, CWD-independent helpers, and native PowerShell Rust checks.
+- Make Go contract generation explicit, isolate smoke tests, and checksum only the current release's six executable archives.
+- Correct use-case argument parsing so a trailing --project flag is honored; return success for command help.
+
 - Add embedded Rust 2024 foundations with a thin CLI, reusable library, feature modules, typed errors, unit/integration/doc tests, rustfmt, and Clippy.
 - Validate generated Rust projects across Linux, macOS, Windows, and the minimum Rust version.
 
diff --git a/Makefile b/Makefile
index 5088b65..b17e427 100644
--- a/Makefile
+++ b/Makefile
@@ -1,45 +1,47 @@
 BINARY := bin/foundry
 VERSION ?= dev
 LDFLAGS := -s -w -X github.com/jabahum/foundry/internal/cli.Version=$(VERSION)
+.DEFAULT_GOAL := help
 
-.PHONY: build test fmt fmt-check vet check smoke install release-snapshot clean
+.PHONY: help build test format format-check lint check ci smoke install release clean fmt fmt-check vet release-snapshot
 
-build:
+help: ## Show commands; see docs/commands.md for prerequisites and side effects.
+	@awk 'BEGIN {FS = ":.*## "; print "Foundry commands:"} /^[a-zA-Z_-]+:.*## / {printf "  make %-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+build: ## Build bin/foundry for this machine (VERSION defaults to dev).
 	mkdir -p bin
 	CGO_ENABLED=0 go build -trimpath -ldflags "$(LDFLAGS)" -o $(BINARY) ./cmd/foundry
 
-test:
+test: ## Run Foundry tests, including embedded generation for all five templates.
 	go test ./...
 
-fmt:
-	gofmt -w cmd internal
+format: ## Format Foundry's Go source; does not format generated template projects.
+	gofmt -w assets.go cmd internal
 
-fmt-check:
-	test -z "$$(gofmt -l .)"
+format-check: ## Check Foundry formatting without rewriting source.
+	test -z "$$(gofmt -l assets.go cmd internal)"
 
-vet:
+lint: ## Run go vet on Foundry packages.
 	go vet ./...
 
-check: fmt-check test vet
-
-smoke: build
-	./$(BINARY) version
-	./$(BINARY) list
-	rm -rf .tmp-smoke
-	./$(BINARY) new .tmp-smoke --template go --module example.com/smoke --no-hooks
-	test -f .tmp-smoke/go.mod
-	grep -q 'module example.com/smoke' .tmp-smoke/go.mod
-	./$(BINARY) add migration create_smoke --project .tmp-smoke
-	test -f .tmp-smoke/migrations/000007_create_smoke.up.sql
-	./$(BINARY) add service smoke --project .tmp-smoke
-	test -f .tmp-smoke/api/proto/smoke/v1/smoke.proto
-	rm -rf .tmp-smoke
-
-install:
+check: format-check lint test build ## Check formatting, lint, tests, and the native build.
+
+ci: check smoke ## Run Foundry checks and the isolated generation/add smoke test.
+
+smoke: build ## Generate all five templates and exercise Go add commands in a temporary folder.
+	./scripts/smoke.sh
+
+install: ## Install Foundry into GOBIN or GOPATH/bin.
 	go install -trimpath -ldflags "$(LDFLAGS)" ./cmd/foundry
 
-release-snapshot:
+release: ## Build six executable archives and checksums; does not publish (VERSION=dev).
 	./scripts/build-release.sh "$(VERSION)"
 
-clean:
-	rm -rf bin dist .tmp-smoke
+clean: ## Remove local bin/ and dist/ artifacts.
+	rm -rf bin dist
+
+# Compatibility aliases. Prefer the canonical names above in new automation.
+fmt: format
+fmt-check: format-check
+vet: lint
+release-snapshot: release
diff --git a/README.md b/README.md
index 3d21e90..3e7fb4e 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@ Install directly from source with Go 1.23 or newer:
 go install github.com/jabahum/foundry/cmd/foundry@latest
 ```
 
+For the complete CLI, script, template, and release reference, see [Commands and workflows](docs/commands.md). Each generated template also documents its own commands in its README.
+
 For local development:
 
 ```bash
@@ -68,14 +70,20 @@ foundry new users-service \
   --module github.com/your-org/users-service
 ```
 
-Flutter app:
+Flutter workspace and app:
 
 ```bash
-foundry new mediguide \
-  --template flutter \
-  --org ug.go.health
+foundry new mediguide --template flutter --no-hooks
+cd mediguide
+bash scripts/setup.sh
+fvm dart pub global run mason_cli:mason make flutter_app \
+  --name mediguide --organization ug.go.health
+# Add apps/mediguide to workspace: in pubspec.yaml.
+fvm dart pub get
 ```
 
+Configure native platform folders, permissions, and signing in the app before a platform build. The template README explains the remaining app setup.
+
 Vanilla JavaScript:
 
 ```bash
@@ -108,7 +116,7 @@ cargo lint
 
 The Rust starter has no third-party dependencies. Its toolchain file selects stable Rust with rustfmt and Clippy, and its minimum supported version is Rust 1.85. Domain rules live in feature modules, with CLI input/output at the boundary. Foundry does not run Cargo automatically.
 
-All templates are available offline. Optional generation hooks may invoke installed SDKs and their package managers; use `--no-hooks` to skip them.
+All templates are available offline. For the FVM/Mason workflow, generate Flutter with `--no-hooks` and run `bash scripts/setup.sh` explicitly. Optional generation hooks may invoke installed SDKs and their package managers; use `--no-hooks` to skip them.
 
 ## Extend an existing project
 
@@ -150,33 +158,27 @@ Template changes ship with a new Foundry build/release. There is no external tem
 
 To update a template, edit its source files and rebuild Foundry with `make build`.
 
-## Commands
+## Commands and workflows
 
-```text
-foundry
-foundry new <name> --template <go|flutter|vanilla-js|react|rust>
-foundry add service <name>
-foundry add migration <name>
-foundry add feature <name>
-foundry add package <name>
+[The command reference](docs/commands.md) documents every CLI command and flag, each template's native commands, setup requirements, generated outputs, side effects, Windows alternatives, and CI/release behavior.
+
+```sh
+foundry help
+foundry new --help
 foundry template list
-foundry list
-foundry info <template>
-foundry doctor
-foundry version
+make help
 ```
 
-## Project-generation flags
+The shared quality workflow is format → lint/analyze → test → build where a generic build exists:
 
-```text
---module       Go module path
---org          Flutter organization identifier
---package      Flutter package token
---version      require this bundled template version
---destination  output path
---force        generate into a non-empty directory
---no-hooks     skip post-generation hooks
-```
+| Project | Full quality gate |
+| --- | --- |
+| Foundry / generated Go | `make check` |
+| Flutter workspace | `fvm dart run melos run check` (build the chosen app/platform separately) |
+| Vanilla JS / React | `npm run check` |
+| Rust | `bash scripts/check.sh` or `./scripts/check.ps1` |
+
+Formatting checks do not fix source; regeneration is explicit. Use `make format`, `npm run format`, `fvm dart run melos run format`, or `cargo fmt --all` to fix formatting. Existing `fmt`, `fmt-check`, `vet`, `proto`, `run`, `quality`, and `release-snapshot` aliases remain available in their relevant projects.
 
 ## Architecture
 
@@ -200,29 +202,27 @@ Foundry CLI
    `-- doctor
 ```
 
-Authentication/RBAC choices belong to the generated Go foundation, not to Foundry itself. Flutter's platform folders are generated using the installed Flutter SDK before the foundation overlay is applied when Flutter is available.
+Authentication/RBAC choices belong to the generated Go foundation, not to Foundry itself. Legacy Flutter hooks use the installed Flutter executable before the foundation overlay, only when hooks are enabled. The recommended FVM-first setup is explicit after `--no-hooks`.
 
 ## Development
 
 ```bash
-make fmt
-make check
-make build
-make smoke
+make format
+make ci
 ```
 
-`go test ./...` checks generation of all five bundled templates, project setting substitution, CLI behavior, and the Go/Flutter add generators. Web-template CI generates fresh projects and runs `npm ci` and `npm run check` on Node 22 and 24. Rust-template CI runs formatting, tests, Clippy, documentation, and release builds on stable Rust across Linux/macOS/Windows and on Rust 1.85 for minimum-version compatibility.
+`go test ./...` checks generation of all five bundled templates, project setting substitution, CLI behavior, and the Go/Flutter add generators. Web-template CI generates fresh projects and runs `npm ci` and `npm run check` on Node 22 and 24. Rust-template CI invokes the same POSIX/PowerShell check scripts for formatting, tests, Clippy, documentation, and release builds on stable Rust across Linux/macOS/Windows and on Rust 1.85 for minimum-version compatibility.
 
 ### Releases
 
 Create all supported archives and checksums locally:
 
 ```bash
-make clean
-make release-snapshot VERSION=1.2.0
+make ci
+make release VERSION=1.2.0
 ```
 
-Pushing a tag such as `v1.2.0` runs tests, produces static Linux, macOS, and
+Pushing a tag such as `v1.2.0` runs Foundry checks, produces static Linux, macOS, and
 Windows archives, injects the tag into `foundry version`, generates SHA-256
 checksums, and publishes a GitHub Release. The release workflow can also be run
 manually to validate packaging without publishing a release.
@@ -245,8 +245,8 @@ foundry add usecase orders create
 foundry add proto billing
 ```
 
-Flutter Mason bricks can be invoked consistently through Foundry:
+With a Mason executable configured on PATH, Foundry forwards brick arguments to `mason make`:
 
 ```bash
-foundry mason feature --name profile
+foundry mason feature --app mediguide --name profile
 ```
diff --git a/assets.go b/assets.go
index c5db468..479add5 100644
--- a/assets.go
+++ b/assets.go
@@ -38,15 +38,15 @@ import "embed"
 //go:embed all:templates/flutter_foundations/pubspec.lock
 //go:embed all:templates/flutter_foundations/pubspec.yaml
 //go:embed all:templates/flutter_foundations/scripts
-//go:embed templates/vanilla-js-foundations/src templates/vanilla-js-foundations/index.html templates/vanilla-js-foundations/package*.json
+//go:embed templates/vanilla-js-foundations/src templates/vanilla-js-foundations/scripts templates/vanilla-js-foundations/index.html templates/vanilla-js-foundations/package*.json
 //go:embed templates/vanilla-js-foundations/*.config.js templates/vanilla-js-foundations/README.md all:templates/vanilla-js-foundations/public
 //go:embed templates/vanilla-js-foundations/.editorconfig templates/vanilla-js-foundations/.env.example templates/vanilla-js-foundations/.gitignore
 //go:embed templates/vanilla-js-foundations/.nvmrc templates/vanilla-js-foundations/.prettierignore templates/vanilla-js-foundations/.prettierrc.json
-//go:embed templates/react-foundations/src templates/react-foundations/index.html templates/react-foundations/package*.json
+//go:embed templates/react-foundations/src templates/react-foundations/scripts templates/react-foundations/index.html templates/react-foundations/package*.json
 //go:embed templates/react-foundations/*.config.js templates/react-foundations/README.md all:templates/react-foundations/public
 //go:embed templates/react-foundations/.editorconfig templates/react-foundations/.env.example templates/react-foundations/.gitignore
 //go:embed templates/react-foundations/.nvmrc templates/react-foundations/.prettierignore templates/react-foundations/.prettierrc.json
-//go:embed templates/rust-foundations/src templates/rust-foundations/tests templates/rust-foundations/Cargo.*
+//go:embed templates/rust-foundations/src templates/rust-foundations/tests templates/rust-foundations/scripts templates/rust-foundations/Cargo.*
 //go:embed templates/rust-foundations/rust-toolchain.toml templates/rust-foundations/README.md
 //go:embed templates/rust-foundations/.gitignore templates/rust-foundations/.editorconfig templates/rust-foundations/.cargo
 var Templates embed.FS
diff --git a/docs/commands.md b/docs/commands.md
new file mode 100644
index 0000000..899f2e1
--- /dev/null
+++ b/docs/commands.md
@@ -0,0 +1,327 @@
+# Command and script reference
+
+This guide covers the Foundry executable, development of Foundry itself, and commands inside generated projects. Run `foundry help` for CLI syntax, `make help` in either Make-based project for targets, and a shell script with `--help` for its inputs. Rust's PowerShell script uses `-Help`.
+
+## 1. Shared command meanings
+
+Use each ecosystem's native command. The names differ where the ecosystem already has a standard; their responsibilities are consistent.
+
+| Task | Foundry repository | Generated Go | Flutter workspace | Vanilla JS / React | Rust project |
+| --- | --- | --- | --- | --- | --- |
+| Set up | Go 1.23+, then `make build` | Go 1.23+, `go mod download`; optional `make tools` | `bash scripts/setup.sh` | `npm ci` | Install Rust via rustup |
+| Format source | `make format` | `make format` | `fvm dart run melos run format` | `npm run format` | `cargo fmt --all` |
+| Check formatting | `make format-check` | `make format-check` | `fvm dart run melos run format:check` | `npm run format:check` | `cargo fmt --all -- --check` |
+| Lint / analyze | `make lint` | `make lint` | `fvm dart run melos run lint` | `npm run lint` | `cargo lint` |
+| Run tests | `make test` | `make test` | `fvm dart run melos run test` | `npm test` | `cargo test --locked` |
+| Full quality gate | `make check` | `make check` | `fvm dart run melos run check` | `npm run check` | `bash scripts/check.sh` or `./scripts/check.ps1` |
+| Build | `make build` | `make build` | `fvm flutter build <platform>` from the app folder | `npm run build` | `cargo build --release --locked` |
+| Run locally | `./bin/foundry help` | `make dev` | `bash scripts/run_flavor.sh <app> [environment]` | `npm run dev` | `cargo run --locked -- greet World` |
+| Clean build outputs | `make clean` | `make clean` | `fvm dart run melos run clean` | `npm run clean` | `cargo clean` |
+
+Formatting intentionally rewrites source. Formatting checks and linting do not fix source. Quality gates stop on failure and do not intentionally regenerate tracked source; they do create ordinary compiler, test, documentation, or build outputs. Fix a failed step and rerun the gate. `make ci` in Go and `melos run ci` in Flutter additionally regenerate code; review those changes before committing.
+
+Flutter has no generic workspace build because each app needs a platform target, native project files, and platform SDKs. Its `check` covers workspace formatting, analysis, and tests. Build the selected app/platform separately.
+
+**Rust distinction:** native `cargo check` only type-checks code. It is not the full quality gate. Use the supplied check script for formatting, Clippy, unit/integration/doc tests, documentation, and release build.
+
+## 2. Prerequisites and working directories
+
+| Work | Required tooling |
+| --- | --- |
+| Foundry source | Go 1.23+; Make and a POSIX shell for Make targets; `awk` for `make help` |
+| Foundry executable | No language runtime; generated projects require their own SDKs |
+| Release archives | Go, POSIX shell, `tar`, `zip`, and either `sha256sum` or `shasum` |
+| Go project checks | Go and a C compiler supported by Go's race detector; project dependencies |
+| Go code generation | Buf and the generators installed by `make tools`, on `PATH`; registry access when dependencies are uncached |
+| Go runtime / database | PostgreSQL, development JWT keys when local auth is enabled, exported environment configuration; Docker Compose for the included stack; `migrate` for local migration commands; OpenSSL for key generation |
+| Flutter | FVM, its pinned Flutter SDK, resolved packages; Mason CLI activated with the same SDK; native SDKs/devices for app builds/runs |
+| Web templates | Node 22.18+ on 22.x, Node 24, or a newer supported even-numbered release; npm |
+| Rust | Rust via rustup with rustfmt, Clippy, and the platform linker; stable selected by `rust-toolchain.toml`; Rust 1.85 minimum |
+
+Run Make, npm, Melos, and Cargo commands from the corresponding project/workspace root unless a row says otherwise. The provided shell scripts resolve their own repository/project root and can be invoked by path from another directory. Rust's PowerShell script and web cleanup script do the same.
+
+Commands that install SDKs, packages, tools, containers, or uncached Go dependencies may use the network. Offline **generation** does not mean a machine without SDKs/dependencies can build the result. Installing dependencies is explicit except for the legacy best-effort Go/Flutter generation hooks described below.
+
+### Windows
+
+The Foundry executable, npm commands, and Cargo commands work natively. Make and Bash helpers require a POSIX environment such as Git Bash or WSL with the listed tools. Rust also has a native PowerShell quality gate:
+
+```powershell
+./scripts/check.ps1
+```
+
+Native alternatives for Foundry source checks:
+
+```powershell
+$files = gofmt -l assets.go cmd internal
+if ($files) { throw "Unformatted files: $files" }
+go vet ./...
+if ($LASTEXITCODE) { exit $LASTEXITCODE }
+go test ./...
+if ($LASTEXITCODE) { exit $LASTEXITCODE }
+go build -trimpath -o bin/foundry.exe ./cmd/foundry
+```
+
+For a generated Go project, run `gofmt -l ./cmd ./internal ./gen`, `go vet ./...`, `go test -race ./...`, and `go build -trimpath -o bin/server.exe ./cmd/server`. The race detector requires a supported C toolchain. A bare `go build` does not start a server or database.
+
+## 3. Foundry CLI
+
+### Inspect and generate
+
+| Command | Behavior |
+| --- | --- |
+| `foundry` | Ask for a project name and one of five templates, then generate it |
+| `foundry help`, `--help`, `-h` | Show commands without generating anything |
+| `foundry version`, `--version`, `-v` | Print the Foundry executable version |
+| `foundry list` | Print bundled IDs, versions, and descriptions |
+| `foundry template list` | Same bundled listing; `templates` is a command alias and `foundry template` also lists |
+| `foundry info <template>` | Show its canonical ID, version, aliases, and description |
+| `foundry doctor` | Report OS and tool availability on `PATH`; it does not install tools or validate all tool versions |
+| `foundry new <name> --template <template> [flags]` | Copy the selected bundled foundation and write `.foundry.yaml` |
+
+| Template ID | Accepted short aliases |
+| --- | --- |
+| `go-foundations` | `go`, `grpc`, `backend` |
+| `flutter-foundations` | `flutter`, `mobile`, `app` |
+| `vanilla-js-foundations` | `vanilla-js`, `vanilla`, `javascript`, `js` |
+| `react-foundations` | `react` |
+| `rust-foundations` | `rust`, `rs` |
+
+Put the project name before flags: `foundry new portal --template react --destination ./apps/portal`. Flags-first form is also supported when the project name is last. Unexpected leftover arguments are rejected rather than silently ignored.
+
+| Flag | Default and effect |
+| --- | --- |
+| `--template` | Required ID or alias |
+| `--version` | Bundled version by default; if specified, it must equal that bundled version. It does not download another release |
+| `--destination` | Project name as output path; an explicit path changes the output location |
+| `--module` | Go module override; otherwise the normalized project name is used |
+| `--org` | Flutter organization placeholder; native Flutter scaffolding defaults to `com.example` if omitted |
+| `--package` | Flutter package placeholder/metadata token; Mason app variables are configured separately when generating a Mason app |
+| `--no-hooks` | False; when true, skip optional pre/post generation tools |
+| `--force` | False; allow writing into a non-empty destination. Matching template files can be overwritten; unrelated files are retained |
+
+Generation copies embedded source files, removes file suffixes such as `.go.tmpl`, substitutes project tokens, and restores executable shell-script permissions. JavaScript manifests, HTML, configuration and lockfiles receive the project name. Rust manifests, source, tests and lockfiles receive a valid crate identifier; reserved names and digit-leading names are prefixed with `app_`.
+
+The optional Go hook attempts `go fmt ./...`. Legacy Flutter hooks attempt native scaffolding with `flutter` from `PATH`, rename the scaffolded app, and bootstrap with `melos` from `PATH` when available. Hook errors are warnings and may still return generation success. For the FVM/Mason workflow, generate Flutter with `--no-hooks`, then run its setup and app-generation steps explicitly. JS/React/Rust do not install dependencies or run package-manager hooks.
+
+`.foundry.yaml` records project name, template ID/version/kind, and supplied module/org/package settings. Template versions and the Foundry binary version are separate: updating a binary does not rewrite an existing project.
+
+### Extend a project
+
+All `add` commands default to the current folder; `--project <path>` chooses another root. They create source scaffolds and print the remaining implementation/wiring steps. They refuse to overwrite existing files. A command can have written earlier files before a later collision is found; inspect changes after any failure.
+
+| Command | Outputs / follow-up |
+| --- | --- |
+| `foundry add service <name>` | Go proto, domain/repository port, application service, gRPC handler; implement persistence, run `make codegen`, wire the handler |
+| `foundry add grpc-service <name>` | Alias for `add service` |
+| `foundry add repository <name>` | Go repository port and PostgreSQL adapter skeleton; define the entity, implement SQL, wire it |
+| `foundry add usecase <domain> [name]` | Go application use case; omitted name defaults to `execute`; supply the domain/entity/repository and implement behavior |
+| `foundry add proto <name>` | Go protobuf service contract; run `make codegen` and implement/register the service |
+| `foundry add migration <name>` | Next numbered SQL up/down pair; edit SQL and apply it explicitly |
+| `foundry add feature <name>` | Flutter feature domain/application/data/presentation skeleton in the detected app; wire routing and add tests |
+| `foundry add package <name>` | Flutter package skeleton under `packages/`; resolve workspace dependencies afterward |
+
+Examples:
+
+```sh
+foundry add service orders --project ./backend
+foundry add usecase orders create --project ./backend
+foundry add usecase orders --project ./backend cancel
+foundry add migration add_order_status --project ./backend
+```
+
+Flutter `add feature` selects the first app (alphabetical directory order) under apps/ with a pubspec.yaml. For explicit app selection in a multi-app workspace, use the Mason feature brick with `--app <name>`.
+
+There are no `add` generators for JavaScript/React/Rust yet. Create feature modules using each template's documented structure.
+
+`foundry mason <brick> [arguments...]` runs **`mason make` from PATH** with inherited input/output and arguments. It requires Mason installed and the correct workspace as the current directory. For FVM-managed workspaces the explicit equivalent is `fvm dart pub global run mason_cli:mason make <brick> ...`, which guarantees the selected SDK.
+
+### Maintenance and errors
+
+`foundry upgrade --project <root> --check` reads `.foundry.yaml` and compares the recorded template version to the bundled registry. It reports an available update and changes no files. `--check` defaults to true; disabling it is rejected because automatic upgrades are not implemented.
+
+Exit codes: `0` for success/help, `1` for operational failures, and `2` for invalid usage/flags. Optional generation-hook warnings do not necessarily change the exit code. Use `foundry new --help`, `foundry add --help`, `foundry template --help`, `foundry upgrade --help`, or `foundry mason --help` for command-specific help.
+
+Template pack/update/cache delivery commands and `--offline` are retired. Templates always ship as embedded files. `npm ci` is a dependency installation command; it does not mean `npm run check`.
+
+## 4. Develop and release Foundry
+
+All Make targets below run from the Foundry repository root.
+
+| Command | What runs / outputs |
+| --- | --- |
+| `make`, `make help` | List canonical targets and descriptions |
+| `make format` | Rewrite `assets.go`, `cmd/`, and `internal/` with gofmt |
+| `make format-check` | Fail if those Go sources need formatting; does not scan node_modules or template implementations |
+| `make lint` | `go vet ./...` |
+| `make test` | `go test ./...`, including generation tests for all five embedded templates |
+| `make build` | Static native `bin/foundry`; injects `VERSION`, default `dev` |
+| `make check` | Formatting check, lint, tests, native build |
+| `make smoke` | Build then run `scripts/smoke.sh` |
+| `make ci` | `check` plus `smoke`; template SDK checks are separate CI jobs |
+| `make install VERSION=...` | Build/install to `GOBIN`, or Go's `GOPATH/bin` default |
+| `make release VERSION=...` | Run release helper; create six executable archives plus checksum manifest; no publishing |
+| `make clean` | Remove repository `bin/` and `dist/`; leaves sources, SDKs, and package caches |
+
+Compatibility aliases remain: `fmt` → `format`, `fmt-check` → `format-check`, `vet` → `lint`, `release-snapshot` → `release`.
+
+### `scripts/smoke.sh`
+
+Needs a built Foundry executable. It prints version/list, generates Go/Flutter/Vanilla JS/React/Rust into a fresh temporary directory with hooks disabled, checks their manifests and metadata, then adds a Go migration and service. It does not install template dependencies or run generated app tests. The temporary directory is removed on success, failure, or interruption; it does not reuse or delete a fixed `.tmp-smoke` folder.
+
+| Input | Effect |
+| --- | --- |
+| `FOUNDRY_BIN` | Optional **absolute** path to a compiled Foundry; default repository `bin/foundry` |
+| `TMPDIR` | Parent for temporary validation workspace; system `/tmp` fallback |
+| `--help` | Print usage, perform no builds or generation |
+
+### `scripts/build-release.sh [version]`
+
+The script resolves the repository root, validates a plain version label, and builds with `CGO_ENABLED=0`, `-trimpath`, and linker flags that inject the version and strip Go debug symbols. Version labels may contain letters, digits, `.`, `_`, and `-`, and cannot start with `.`, `_`, or `-`; default is `dev`.
+
+It stages Linux/macOS/Windows × amd64/arm64 builds in its own temporary directory. Linux/macOS archives use `.tar.gz`; Windows uses `.zip` and contains `foundry.exe`. Each archive includes the executable, README, changelog, and this `docs/` directory. On successful completion it moves all six archives and `SHA256SUMS` to the output folder and removes staging. A failed build cleans its staging folder without publishing staged partial artifacts.
+
+`FOUNDRY_DIST_DIR` chooses the output folder, default `dist/`. Relative paths are resolved from the repository root even when the script is called elsewhere. Existing archives with the same version/target names are replaced. Older versions may coexist, but `SHA256SUMS` lists **only the six archives from the latest successful invocation**.
+
+```sh
+make ci
+make release VERSION=1.2.0
+(cd dist && shasum -a 256 -c SHA256SUMS)
+# Linux alternative: (cd dist && sha256sum -c SHA256SUMS)
+```
+
+These archives deliver the **Foundry executable**; they are not template ZIP delivery. Running this script does not test, tag, or publish. The release workflow runs `make check`, packages on a `v*` tag (stripping `v` from the version label), uploads artifacts, and publishes a GitHub Release only for tags. A manual workflow run builds/uploads artifacts without publishing. Template SDK checks run in the separate CI workflow, so check their status before tagging.
+
+## 5. Generated Go commands
+
+Run inside a **generated** Go project. The template source folder has `.go.tmpl`/`go.mod.tmpl` files and is not itself the runnable module.
+
+| Command | Responsibility / side effects |
+| --- | --- |
+| `make help` | List targets |
+| `make tools` | Install pinned Buf/protobuf/gateway tooling and current grpcurl; may download and change GOBIN/GOPATH/bin; does not install the local `migrate` CLI |
+| `make format`, `make format-check` | Format/check `cmd`, `internal`, and generated Go under `gen` |
+| `make lint` | Vet using existing generated bindings |
+| `make test` | Race-enabled tests using existing bindings; no regeneration or database migration |
+| `make build` | Compile to `bin/server` (`BINARY` can override output path) |
+| `make dev` | `go run ./cmd/server`; stays running until stopped; requires configuration and PostgreSQL |
+| `make check` | Formatting check, vet, race tests, build; may fetch uncached Go modules, but no Buf tooling or live database is needed for current tests |
+| `make codegen` | Regenerate Go/gRPC/Gateway/OpenAPI files with Buf; changes generated files |
+| `make contracts-check` | Buf protobuf lint |
+| `make ci` | Sequentially codegen → contract lint → check; requires tool installation; review generated changes |
+| `make keys` | Create missing dev RSA key pair in `secrets/`; preserves existing key files |
+| `make docker-up` | Ensure keys, build/start Compose stack; Compose runs migrations and initializes configured bootstrap data |
+| `make docker-down` | Stop/remove Compose containers/networks, preserve named database volume |
+| `make logs` | Follow API logs; interrupt to stop following |
+| `make migrate-up` | Apply all pending SQL migrations to `DATABASE_URL` |
+| `make migrate-down` | Roll back **one** migration; changes the selected database |
+| `make migrate-create name=...` | Local `migrate` CLI creates numbered up/down files |
+| `make tidy` | Rewrite module manifests to match imports |
+| `make clean` | Remove `bin/` and `coverage.out`, preserve source/generated contracts/keys |
+
+Aliases: `fmt` → `format`, `proto` → `codegen`, `run` → `dev`. Tests and dev no longer regenerate contracts implicitly.
+
+For local execution, export `DATABASE_URL` (and any overrides) into the process environment. The server does **not** automatically load `configs/.env.example` or `.env`. `make migrate-up DATABASE_URL='...'` overrides only the Make migration connection; it does not export application configuration for other commands. The Compose file supplies its own container configuration.
+
+`make docker-up` is the easiest complete local stack. To run the Go process separately, start/configure PostgreSQL, apply migrations, generate keys, export configuration, then `make dev`. A project generated with `--no-hooks` may need `make format` after module-name substitution before its first formatting check. After contract changes run `make codegen`, review outputs, then `make check`.
+
+## 6. Flutter commands and scripts
+
+Use FVM for all Dart/Flutter/Melos/Mason invocations. From the workspace root:
+
+```sh
+bash scripts/setup.sh
+fvm dart pub global run mason_cli:mason make flutter_app --name my_app --description "My application"
+# Add apps/my_app to workspace: in pubspec.yaml.
+fvm dart pub get
+fvm dart run melos run check
+```
+
+Mason generates application source, not a complete native platform deployment. Create/configure the desired Flutter native platforms in the app folder and follow the generated README before running or building it.
+
+| `fvm dart run melos run <task>` | Effect |
+| --- | --- |
+| `bootstrap`, `pub:get` | Resolve workspace packages with `fvm dart pub get`; writes tool caches and may update pubspec.lock |
+| `format` / `format:check` | Format/check `apps/` and `packages/` |
+| `analyze` / `lint` | Analyze each workspace package; `lint` aliases `analyze` |
+| `test` | Run flutter tests in Flutter packages with test folders and dart tests in non-Flutter packages with test folders; skips packages without tests |
+| `test:coverage` | Flutter test coverage for Flutter packages with tests; does not produce Dart-only package coverage |
+| `codegen` / `codegen:watch` | Run build_runner in packages declaring it; watch keeps running; writes generated source |
+| `check` | Formatting check → lint → test; no code generation or app build |
+| `quality` | Compatibility alias for `check` |
+| `ci` | Codegen → check → all-brick validation; can fetch dependencies and generate source |
+| `bricks:list` | List configured bricks through FVM's Mason CLI |
+| `bricks:validate` | Run the brick validation script below |
+| `outdated` | Report newer dependency versions; does not upgrade constraints |
+| `clean` | `flutter clean` in Flutter workspace packages; does not remove source, lockfiles, all Dart caches, or globally installed SDKs |
+
+| Script | Inputs, work, and outputs |
+| --- | --- |
+| `scripts/setup.sh` | No arguments. Resolve workspace root; require FVM; install configured Flutter SDK; activate Mason CLI globally in Dart's package cache; resolve packages; fetch local bricks. Requires network if uncached |
+| `scripts/run_flavor.sh <app> [environment]` | Default `development`; also `staging` / `production`. Require an existing lowercase app directory and `env/<environment>.json`; run `fvm flutter run` from that app with Dart defines. It does not select a native `--flavor` build variant |
+| `scripts/validate_bricks.sh` | Require installed SDK and FVM-activated Mason. Fetch bricks; render every brick in a temporary workspace; resolve packages; format-check; generate code; analyze and test generated app/package; remove the workspace on exit. SDK/pub/Mason caches can remain |
+
+Copy staging/production example JSON to its corresponding ignored JSON file before using those environments. Values embedded in a client app are public; keep server secrets outside them. SDKs, emulators/devices, native permissions, signing, and app registration remain app-specific prerequisites. All three scripts accept `--help` before running setup or validation.
+
+## 7. Vanilla JavaScript and React commands
+
+Both templates expose the same scripts. From a generated project:
+
+| Command | Behavior / output |
+| --- | --- |
+| `nvm install` | Optional convenience for nvm users; select the Node major in `.nvmrc` |
+| `npm ci` | Install exactly the lockfile dependency tree; replaces node_modules; fails if dependency manifests disagree; does not change the lockfile |
+| `npm run dev` | Vite development server, stays running; terminal shows URL/port |
+| `npm run build` | Production static assets under `dist/` |
+| `npm run preview` | Local preview of the already-built dist; run build first; not a production hosting service |
+| `npm run format` / `format:check` | Rewrite/check files using Prettier; build/dependency outputs and lockfile are excluded |
+| `npm run lint` | ESLint with warnings treated as failures |
+| `npm test` / `npm run test:watch` | One Vitest pass / interactive watch process |
+| `npm run check` | Formatting check → lint → tests → production build |
+| `npm run clean` | Run scripts/clean.js; remove only this project's dist/, coverage/, and .vitest/; preserve node_modules, source, and lockfile |
+
+`src/shared/config/env.js` reads public `VITE_` variables with defaults. Copy `.env.example` to `.env.local` for overrides. Vite applies them at startup/build time; rebuilding is required to change deployed values. `npm install` is for intentional dependency updates; commit its resulting package-lock.json and rerun check. The source templates use a project placeholder in both manifests; generated projects receive the normalized name.
+
+## 8. Rust commands and scripts
+
+Run in a generated Rust project. `rust-toolchain.toml` selects stable and requests rustfmt/Clippy. `Cargo.lock` is committed, and the initial project has no third-party crates.
+
+| Command | Behavior / output |
+| --- | --- |
+| `cargo run --locked -- greet World` | Build debug executable if necessary and run greeting; arguments after `--` go to the app |
+| `cargo run --locked -- --help` | App help (different from `cargo --help`) |
+| `cargo fmt --all` / `cargo fmt --all -- --check` | Format/check package Rust source |
+| `cargo check --locked` | Fast type-check only; not the full quality gate |
+| `cargo lint` | .cargo/config.toml alias for Clippy across all targets with locked dependencies and warnings denied |
+| `cargo test --locked` | Unit, real executable integration, and documentation tests |
+| `cargo doc --locked --no-deps` | Generate target/doc/; the check scripts also deny documentation warnings |
+| `cargo build --release --locked` | Optimized executable under target/release/; Windows adds .exe |
+| `cargo clean` | Remove Cargo target artifacts including docs and builds; preserve Cargo.lock/source |
+| `bash scripts/check.sh` | POSIX full gate below |
+| `./scripts/check.ps1` | Native PowerShell full gate below |
+
+Both check scripts resolve the project root, stop at the first failure, and run **format check → cargo lint → cargo test → documentation (warnings denied) → release build**. They do not fix source or update the lockfile. The PowerShell script restores the caller's location and RUSTDOCFLAGS on exit. Help uses `--help` for the shell script and `-Help` for PowerShell.
+
+| Environment variable | Use |
+| --- | --- |
+| `RUSTUP_TOOLCHAIN` | Select a preinstalled toolchain; CI uses stable or 1.85.0 |
+| `CARGO_NET_OFFLINE=true` | Disable crate downloads for the full gate; toolchain installation is a separate concern |
+| `RUSTDOCFLAGS` | Existing doc flags are retained; the gate adds `-D warnings` for doc generation |
+
+Do not append `--offline` to `cargo lint`: the alias already contains `--` and later arguments would be forwarded to Clippy/rustc. Use the offline environment variable, or write the expanded command with Cargo options before `--`:
+
+```sh
+CARGO_NET_OFFLINE=true bash scripts/check.sh
+cargo clippy --locked --offline --all-targets -- -D warnings
+```
+
+## 9. How CI maps to local work
+
+- Foundry OS jobs run native Go tests, vet, and build on Linux/macOS/Windows; Linux also runs the isolated smoke helper.
+- Formatting calls `make format-check` and cross-compilation calls `make release VERSION=ci`.
+- Web jobs generate fresh projects from the bundled binary, install with npm ci, and run the same npm check gate on Node 22 and 24.
+- Rust jobs generate fresh projects and invoke the same POSIX/PowerShell check scripts. Stable runs on all three OSes; Rust 1.85 runs on Linux. Cargo is offline after toolchain installation.
+- Flutter CI-equivalent local validation is `fvm dart run melos run ci` after setup. Native app builds require a chosen platform. There is no automated Flutter SDK job in the current repository CI workflow.
+- Go-foundation full local validation is `make ci` in a generated project after installing code-generation tools. Foundry Go tests check generation, not all backend integration behavior. There is no separate automated generated-backend test job in the current workflow.
+
+For template changes, generate a fresh project and run its native gate. Passing Foundry's Go tests alone does not prove a template's runtime code builds. No release script automatically merges a PR or upgrades existing generated projects.
diff --git a/internal/add/add.go b/internal/add/add.go
index 983b8cc..60d62aa 100644
--- a/internal/add/add.go
+++ b/internal/add/add.go
@@ -103,7 +103,7 @@ func (h *%sHandler) Get%s(ctx context.Context, req *pb.Get%sRequest) (*pb.Get%sR
 	if err != nil {
 		return Result{}, err
 	}
-	return Result{Files: written, Next: []string{"implement a persistence adapter for internal/domain/" + name + ".Repository", "run: make proto", "wire New" + pascal + "Handler into cmd/server/main.go"}}, nil
+	return Result{Files: written, Next: []string{"implement a persistence adapter for internal/domain/" + name + ".Repository", "run: make codegen", "wire New" + pascal + "Handler into cmd/server/main.go"}}, nil
 }
 
 func GoMigration(root, name string) (Result, error) {
@@ -187,7 +187,7 @@ class %sPage extends StatelessWidget {
 	if err != nil {
 		return Result{}, err
 	}
-	return Result{Files: written, Next: []string{"add the feature route to your go_router configuration", "run: melos bootstrap", "add feature-specific tests"}}, nil
+	return Result{Files: written, Next: []string{"add the feature route to your go_router configuration", "run: fvm dart run melos run bootstrap", "add feature-specific tests"}}, nil
 }
 
 func FlutterPackage(root, name string) (Result, error) {
@@ -205,7 +205,7 @@ func FlutterPackage(root, name string) (Result, error) {
 	if err != nil {
 		return Result{}, err
 	}
-	return Result{Files: written, Next: []string{"run: melos bootstrap"}}, nil
+	return Result{Files: written, Next: []string{"run: fvm dart run melos run bootstrap"}}, nil
 }
 
 func writeFiles(root string, files map[string]string) ([]string, error) {
@@ -406,5 +406,5 @@ message Get%sResponse { string id = 1; }
 	if err != nil {
 		return Result{}, err
 	}
-	return Result{Files: written, Next: []string{"run: make proto", "implement and register the generated service server"}}, nil
+	return Result{Files: written, Next: []string{"run: make codegen", "implement and register the generated service server"}}, nil
 }
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index a5ee399..4fd432d 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -24,6 +24,13 @@ var Version = "1.2.0"
 type App struct{ FS fs.FS }
 
 func (a App) Run(args []string) int {
+	if len(args) > 1 {
+		switch args[0] {
+		case "list", "doctor", "version", "--version", "-v", "help", "--help", "-h":
+			fmt.Fprintln(os.Stderr, "unexpected arguments; use foundry help")
+			return 2
+		}
+	}
 	if len(args) == 0 {
 		return a.interactive()
 	}
@@ -42,7 +49,11 @@ func (a App) Run(args []string) int {
 		printTemplates()
 		return 0
 	case "info":
-		if len(args) < 2 {
+		if len(args) == 2 && (args[1] == "--help" || args[1] == "-h") {
+			fmt.Println("Usage: foundry info <template>")
+			return 0
+		}
+		if len(args) != 2 {
 			fmt.Fprintln(os.Stderr, "usage: foundry info <template>")
 			return 2
 		}
@@ -118,10 +129,18 @@ func (a App) newCmd(args []string) int {
 	force := f.Bool("force", false, "allow generation into non-empty directory")
 	noHooks := f.Bool("no-hooks", false, "skip post-generation hooks")
 	if err := f.Parse(args); err != nil {
+		if err == flag.ErrHelp {
+			return 0
+		}
 		return 2
 	}
-	if name == "" && len(f.Args()) > 0 {
-		name = f.Args()[0]
+	remaining := f.Args()
+	if name == "" && len(remaining) > 0 {
+		name, remaining = remaining[0], remaining[1:]
+	}
+	if len(remaining) > 0 {
+		fmt.Fprintln(os.Stderr, "unexpected arguments; use: foundry new <name> [flags]")
+		return 2
 	}
 	if name == "" {
 		fmt.Fprintln(os.Stderr, "usage: foundry new <name> --template <go|flutter|vanilla-js|react|rust>")
@@ -157,6 +176,10 @@ func (a App) newCmd(args []string) int {
 }
 
 func addCmd(args []string) int {
+	if (len(args) == 1 && (args[0] == "--help" || args[0] == "-h")) || (len(args) == 2 && (args[1] == "--help" || args[1] == "-h")) {
+		fmt.Println("Usage: foundry add <service|repository|proto|migration|feature|package> <name> [--project path]\n       foundry add usecase <domain> [name] [--project path]")
+		return 0
+	}
 	if len(args) < 2 {
 		fmt.Fprintln(os.Stderr, "usage: foundry add <service|repository|usecase|proto|migration|feature|package> <name> [--project path]")
 		return 2
@@ -165,7 +188,23 @@ func addCmd(args []string) int {
 	f := flag.NewFlagSet("add", flag.ContinueOnError)
 	f.SetOutput(os.Stderr)
 	project := f.String("project", ".", "project root")
-	if err := f.Parse(args[2:]); err != nil {
+	rest := args[2:]
+	usecase := ""
+	if kind == "usecase" && len(rest) > 0 && !strings.HasPrefix(rest[0], "-") {
+		usecase, rest = rest[0], rest[1:]
+	}
+	if err := f.Parse(rest); err != nil {
+		if err == flag.ErrHelp {
+			return 0
+		}
+		return 2
+	}
+	remaining := f.Args()
+	if kind == "usecase" && usecase == "" && len(remaining) > 0 {
+		usecase, remaining = remaining[0], remaining[1:]
+	}
+	if len(remaining) > 0 {
+		fmt.Fprintln(os.Stderr, "unexpected arguments; use foundry add --help")
 		return 2
 	}
 	root, err := filepath.Abs(*project)
@@ -181,9 +220,9 @@ func addCmd(args []string) int {
 		result, err = addgen.GoRepository(root, name)
 	case "usecase":
 		domain := name
-		uc := "execute"
-		if extra := f.Args(); len(extra) > 0 {
-			uc = extra[0]
+		uc := usecase
+		if uc == "" {
+			uc = "execute"
 		}
 		result, err = addgen.GoUsecase(root, domain, uc)
 	case "proto":
@@ -216,7 +255,11 @@ func addCmd(args []string) int {
 }
 
 func templateCmd(args []string) int {
-	if len(args) == 0 || args[0] == "list" {
+	if len(args) == 1 && (args[0] == "--help" || args[0] == "-h") {
+		fmt.Println("Usage: foundry template list (also: foundry list)")
+		return 0
+	}
+	if len(args) == 0 || (len(args) == 1 && args[0] == "list") {
 		printTemplates()
 		return 0
 	}
@@ -239,9 +282,19 @@ func upgradeCmd(args []string) int {
 	project := f.String("project", ".", "project root")
 	check := f.Bool("check", true, "check for a newer template version")
 	if err := f.Parse(args); err != nil {
+		if err == flag.ErrHelp {
+			return 0
+		}
+		return 2
+	}
+	if !*check {
+		fmt.Fprintln(os.Stderr, "upgrade supports read-only check mode only; omit --check or set it to true")
+		return 2
+	}
+	if f.NArg() != 0 {
+		fmt.Fprintln(os.Stderr, "unexpected arguments; use foundry upgrade --help")
 		return 2
 	}
-	_ = check
 	root, err := filepath.Abs(*project)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
@@ -260,6 +313,10 @@ func upgradeCmd(args []string) int {
 }
 
 func masonCmd(args []string) int {
+	if len(args) == 1 && (args[0] == "--help" || args[0] == "-h") {
+		fmt.Println("Usage: foundry mason <brick> [mason arguments...] (runs mason make from PATH)")
+		return 0
+	}
 	if len(args) == 0 {
 		fmt.Fprintln(os.Stderr, "usage: foundry mason <brick> [mason arguments...]")
 		return 2
diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go
index 7f2b578..baff400 100644
--- a/internal/cli/cli_test.go
+++ b/internal/cli/cli_test.go
@@ -60,3 +60,65 @@ func TestRetiredDeliveryCommandsAreRejected(t *testing.T) {
 		}
 	}
 }
+
+func TestCommandHelpSucceedsWithoutGenerating(t *testing.T) {
+	app := App{FS: foundry.Templates}
+	for _, args := range [][]string{{"new", "--help"}, {"add", "--help"}, {"add", "service", "--help"}, {"template", "--help"}, {"upgrade", "--help"}, {"mason", "--help"}, {"info", "--help"}} {
+		if code := app.Run(args); code != 0 {
+			t.Fatalf("%v: exit %d, want 0", args, code)
+		}
+	}
+}
+
+func TestUsecaseProjectFlagBeforeOrAfterName(t *testing.T) {
+	caller := t.TempDir()
+	previous, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(caller); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := os.Chdir(previous); err != nil {
+			t.Error(err)
+		}
+	})
+	for _, order := range []string{"name-first", "flags-first", "default-name"} {
+		t.Run(order, func(t *testing.T) {
+			project := t.TempDir()
+			if err := os.WriteFile(filepath.Join(project, "go.mod"), []byte("module example.org/service\n\ngo 1.23\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			args := []string{"usecase", "orders"}
+			want := "create"
+			switch order {
+			case "name-first":
+				args = append(args, "create", "--project", project)
+			case "flags-first":
+				args = append(args, "--project", project, "create")
+			case "default-name":
+				args = append(args, "--project", project)
+				want = "execute"
+			}
+			if code := addCmd(args); code != 0 {
+				t.Fatalf("add %v: exit %d", args, code)
+			}
+			if _, err := os.Stat(filepath.Join(project, "internal", "application", "orders", want+".go")); err != nil {
+				t.Fatal(err)
+			}
+			if _, err := os.Stat(filepath.Join(caller, "internal")); !os.IsNotExist(err) {
+				t.Fatal("generator wrote to the caller instead of --project")
+			}
+		})
+	}
+}
+
+func TestUnexpectedArgumentsAndWriteUpgradeModeAreRejected(t *testing.T) {
+	app := App{FS: foundry.Templates}
+	for _, args := range [][]string{{"list", "extra"}, {"template", "list", "extra"}, {"info", "go", "extra"}, {"upgrade", "--check=false"}, {"add", "migration", "name", "unexpected"}, {"new", "demo", "--template", "rust", "extra"}} {
+		if code := app.Run(args); code != 2 {
+			t.Fatalf("%v: exit %d, want 2", args, code)
+		}
+	}
+}
diff --git a/internal/doctor/doctor.go b/internal/doctor/doctor.go
index a668d03..21ce625 100644
--- a/internal/doctor/doctor.go
+++ b/internal/doctor/doctor.go
@@ -15,7 +15,7 @@ func Run() []Check {
 	checks := []Check{{Name: "OS", Detail: runtime.GOOS + "/" + runtime.GOARCH, OK: true}}
 	for _, c := range []struct{ Name, Bin string }{
 		{"Git", "git"}, {"Rust", "rustc"}, {"Cargo", "cargo"}, {"Node.js", "node"}, {"npm", "npm"}, {"Go", "go"}, {"Docker", "docker"}, {"Buf", "buf"},
-		{"grpcurl", "grpcurl"}, {"Flutter", "flutter"}, {"Dart", "dart"}, {"Melos", "melos"}, {"Mason", "mason"},
+		{"grpcurl", "grpcurl"}, {"FVM", "fvm"}, {"OpenSSL", "openssl"}, {"Migrations", "migrate"}, {"Flutter", "flutter"}, {"Dart", "dart"}, {"Melos", "melos"}, {"Mason", "mason"},
 	} {
 		p, err := exec.LookPath(c.Bin)
 		checks = append(checks, Check{Name: c.Name, Detail: p, OK: err == nil})
diff --git a/internal/generator/generator_test.go b/internal/generator/generator_test.go
index 32f5205..42cbb67 100644
--- a/internal/generator/generator_test.go
+++ b/internal/generator/generator_test.go
@@ -49,10 +49,12 @@ func TestBundledTemplatesGenerate(t *testing.T) {
 					t.Fatal(err)
 				}
 			}
-			if runtime.GOOS != "windows" && (name == "go" || name == "flutter") {
+			if runtime.GOOS != "windows" && (name == "go" || name == "flutter" || name == "rust") {
 				script := "scripts/setup.sh"
 				if name == "go" {
 					script = "scripts/generate-dev-keys.sh"
+				} else if name == "rust" {
+					script = "scripts/check.sh"
 				}
 				info, err := os.Stat(filepath.Join(dest, script))
 				if err != nil {
diff --git a/internal/generator/scripts_test.go b/internal/generator/scripts_test.go
new file mode 100644
index 0000000..cf0ea5a
--- /dev/null
+++ b/internal/generator/scripts_test.go
@@ -0,0 +1,175 @@
+package generator
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/jabahum/foundry"
+)
+
+func copyEmbeddedScript(t *testing.T, template, script string) (string, string) {
+	t.Helper()
+	if runtime.GOOS == "windows" {
+		t.Skip("POSIX helper test; native PowerShell gate is covered by CI")
+	}
+	root := t.TempDir()
+	path := filepath.Join(root, "scripts", script)
+	data, err := foundry.Templates.ReadFile("templates/" + template + "/scripts/" + script)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, data, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return root, path
+}
+
+func fakeFVM(t *testing.T) (string, string) {
+	t.Helper()
+	bin := t.TempDir()
+	log := filepath.Join(t.TempDir(), "calls.log")
+	data := "#!/bin/sh\nprintf '%s|%s\\n' \"$PWD\" \"$*\" >> \"$FOUNDRY_COMMAND_LOG\"\nif [ \"$*\" = \"${FOUNDRY_FAIL_COMMAND:-}\" ]; then exit 23; fi\n"
+	if err := os.WriteFile(filepath.Join(bin, "fvm"), []byte(data), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return bin, log
+}
+
+func TestFlutterSetupAnchorsItsRootAndStopsOnFailure(t *testing.T) {
+	for _, fail := range []bool{false, true} {
+		t.Run(map[bool]string{false: "success", true: "failure"}[fail], func(t *testing.T) {
+			root, script := copyEmbeddedScript(t, "flutter_foundations", "setup.sh")
+			bin, log := fakeFVM(t)
+			cmd := exec.Command("bash", script)
+			cmd.Dir = t.TempDir()
+			cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "FOUNDRY_COMMAND_LOG="+log)
+			if fail {
+				cmd.Env = append(cmd.Env, "FOUNDRY_FAIL_COMMAND=dart pub global activate mason_cli")
+			}
+			output, err := cmd.CombinedOutput()
+			if fail && err == nil {
+				t.Fatal("setup continued after installer failure")
+			}
+			if !fail && err != nil {
+				t.Fatalf("setup: %v\n%s", err, output)
+			}
+			data, err := os.ReadFile(log)
+			if err != nil {
+				t.Fatal(err)
+			}
+			lines := strings.Split(strings.TrimSpace(string(data)), "\n")
+			want := 4
+			if fail {
+				want = 2
+			}
+			if len(lines) != want {
+				t.Fatalf("unexpected setup calls: %s", data)
+			}
+			resolved, err := filepath.EvalSymlinks(root)
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, line := range lines {
+				parts := strings.SplitN(line, "|", 2)
+				actual, err := filepath.EvalSymlinks(parts[0])
+				if err != nil {
+					t.Fatal(err)
+				}
+				if actual != resolved {
+					t.Fatalf("setup used the caller directory: %s", line)
+				}
+			}
+		})
+	}
+}
+
+func TestFlutterRunEnvironmentUsesTheAppAndValidatesArguments(t *testing.T) {
+	root, script := copyEmbeddedScript(t, "flutter_foundations", "run_flavor.sh")
+	for _, dir := range []string{"apps/demo", "env"} {
+		if err := os.MkdirAll(filepath.Join(root, dir), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(root, "env/development.json"), []byte("{}"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	bin, log := fakeFVM(t)
+	for _, args := range [][]string{{"demo"}, {"demo", "unknown"}, {"../outside"}, {"missing"}} {
+		cmd := exec.Command("bash", append([]string{script}, args...)...)
+		cmd.Dir = t.TempDir()
+		cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "FOUNDRY_COMMAND_LOG="+log)
+		output, err := cmd.CombinedOutput()
+		if args[0] == "demo" && len(args) == 1 {
+			if err != nil {
+				t.Fatalf("run: %v\n%s", err, output)
+			}
+		} else if err == nil {
+			t.Fatalf("accepted invalid args: %v", args)
+		}
+	}
+	data, err := os.ReadFile(log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	app, err := filepath.EvalSymlinks(filepath.Join(root, "apps/demo"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	parts := strings.SplitN(strings.TrimSpace(string(data)), "|", 2)
+	if len(parts) != 2 {
+		t.Fatalf("unexpected FVM invocation: %s", data)
+	}
+	actual, err := filepath.EvalSymlinks(parts[0])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if actual != app || parts[1] != "flutter run --dart-define-from-file=../../env/development.json" {
+		t.Fatalf("unexpected FVM invocation: %s", data)
+	}
+}
+
+func TestDevelopmentKeysAreProjectLocalAndPreserved(t *testing.T) {
+	root, script := copyEmbeddedScript(t, "go-foundations", "generate-dev-keys.sh")
+	if _, err := exec.LookPath("openssl"); err != nil {
+		t.Skip("OpenSSL not installed")
+	}
+	caller := t.TempDir()
+	run := func() {
+		cmd := exec.Command("sh", script)
+		cmd.Dir = caller
+		if output, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("keys: %v\n%s", err, output)
+		}
+	}
+	run()
+	private := filepath.Join(root, "secrets/jwt_private.pem")
+	before, err := os.ReadFile(private)
+	if err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(private)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("private mode %o", info.Mode().Perm())
+	}
+	run()
+	after, err := os.ReadFile(private)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(before) != string(after) {
+		t.Fatal("existing private key was replaced")
+	}
+	if _, err := os.Stat(filepath.Join(caller, "secrets")); !os.IsNotExist(err) {
+		t.Fatal("keys were written in the caller directory")
+	}
+}
diff --git a/scripts/build-release.sh b/scripts/build-release.sh
index d4bfe02..b6a4af8 100755
--- a/scripts/build-release.sh
+++ b/scripts/build-release.sh
@@ -1,52 +1,67 @@
 #!/bin/sh
 set -eu
 
-version="${1:-dev}"
-output_dir="${FOUNDRY_DIST_DIR:-dist}"
-ldflags="-s -w -X github.com/jabahum/foundry/internal/cli.Version=${version}"
-
+case "${1:-}" in
+  -h|--help)
+    printf '%s\n' 'Usage: scripts/build-release.sh [version]' \
+      'Builds static Foundry executables for Linux/macOS/Windows on amd64/arm64.' \
+      'Writes six executable archives and SHA256SUMS to FOUNDRY_DIST_DIR (default: repository dist/).' \
+      'Version defaults to dev. Does not test, create a tag, or publish a release.'
+    exit 0 ;;
+esac
+[ "$#" -le 1 ] || { echo 'Expected at most one version; use --help.' >&2; exit 2; }
+version=${1:-dev}
 case "$version" in
-  ""|[._-]*|*[!0-9A-Za-z._-]*)
-    echo "invalid version: $version" >&2
-    exit 2
-    ;;
+  ""|[._-]*|*[!0-9A-Za-z._-]*) echo "invalid version: $version" >&2; exit 2 ;;
 esac
-
+repo_root=$(CDPATH= cd "$(dirname "$0")/.." && pwd)
+cd "$repo_root"
+for tool in go tar zip; do
+  command -v "$tool" >/dev/null || { echo "Required tool not found: $tool" >&2; exit 127; }
+done
+if ! command -v sha256sum >/dev/null && ! command -v shasum >/dev/null; then
+  echo 'sha256sum or shasum is required.' >&2; exit 127
+fi
+output_dir=${FOUNDRY_DIST_DIR:-dist}
 mkdir -p "$output_dir"
+output_dir=$(CDPATH= cd "$output_dir" && pwd)
+scratch=$(mktemp -d "$output_dir/.foundry-release.XXXXXX")
+trap 'rm -rf "$scratch"' EXIT HUP INT TERM
+ldflags="-s -w -X github.com/jabahum/foundry/internal/cli.Version=${version}"
+set --
 
-for target in \
-  linux/amd64 linux/arm64 \
-  darwin/amd64 darwin/arm64 \
-  windows/amd64 windows/arm64
-do
+for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
   goos=${target%/*}
   goarch=${target#*/}
   archive="foundry_${version}_${goos}_${goarch}"
-  stage="$output_dir/$archive"
-  binary="foundry"
-
-  if [ "$goos" = "windows" ]; then
-    binary="foundry.exe"
-  fi
-
+  stage="$scratch/$archive"
+  binary=foundry
+  [ "$goos" != windows ] || binary=foundry.exe
   mkdir -p "$stage"
   CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
     go build -trimpath -ldflags "$ldflags" -o "$stage/$binary" ./cmd/foundry
   cp README.md CHANGELOG.md "$stage/"
-
-  if [ "$goos" = "windows" ]; then
-    (cd "$output_dir" && zip -qr "$archive.zip" "$archive")
+  cp -R docs "$stage/"
+  if [ "$goos" = windows ]; then
+    filename="$archive.zip"
+    (cd "$scratch" && zip -qr "$filename" "$archive")
   else
-    tar -C "$output_dir" -czf "$output_dir/$archive.tar.gz" "$archive"
+    filename="$archive.tar.gz"
+    tar -C "$scratch" -czf "$scratch/$filename" "$archive"
   fi
+  set -- "$@" "$filename"
   rm -r "$stage"
 done
 
+# Hash only the six archives from this invocation, even if dist contains older releases.
 (
-  cd "$output_dir"
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum ./*.tar.gz ./*.zip > SHA256SUMS
+  cd "$scratch"
+  if command -v sha256sum >/dev/null; then
+    sha256sum "$@"
   else
-    shasum -a 256 ./*.tar.gz ./*.zip > SHA256SUMS
+    shasum -a 256 "$@"
   fi
-)
+) > "$scratch/SHA256SUMS"
+for filename in "$@"; do mv "$scratch/$filename" "$output_dir/$filename"; done
+mv "$scratch/SHA256SUMS" "$output_dir/SHA256SUMS"
+printf 'Release artifacts: %s\n' "$output_dir"
diff --git a/scripts/smoke.sh b/scripts/smoke.sh
new file mode 100755
index 0000000..53fdfe5
--- /dev/null
+++ b/scripts/smoke.sh
@@ -0,0 +1,40 @@
+#!/bin/sh
+set -eu
+
+case "${1:-}" in
+  -h|--help)
+    printf '%s\n' 'Usage: [FOUNDRY_BIN=/absolute/path/to/foundry] scripts/smoke.sh' \
+      'Generates all five templates without hooks, checks their manifests, and exercises Go add commands.' \
+      'Uses a temporary folder which is removed on success or failure. Build Foundry first with make build.'
+    exit 0 ;;
+esac
+[ "$#" -eq 0 ] || { echo 'Unexpected argument; use --help.' >&2; exit 2; }
+repo_root=$(CDPATH= cd "$(dirname "$0")/.." && pwd)
+binary=${FOUNDRY_BIN:-"$repo_root/bin/foundry"}
+[ -x "$binary" ] || { echo 'Foundry executable not found; run make build or set FOUNDRY_BIN.' >&2; exit 1; }
+scratch=$(mktemp -d "${TMPDIR:-/tmp}/foundry-smoke.XXXXXX")
+trap 'rm -rf "$scratch"' EXIT HUP INT TERM
+
+"$binary" version
+"$binary" template list
+for template in go flutter vanilla-js react rust; do
+  project="$scratch/$template"
+  if [ "$template" = go ]; then
+    "$binary" new smoke --template go --module smoke --destination "$project" --no-hooks
+    grep -q '^module smoke$' "$project/go.mod"
+  else
+    "$binary" new smoke --template "$template" --destination "$project" --no-hooks
+  fi
+  test -f "$project/.foundry.yaml"
+  case "$template" in
+    flutter) test -f "$project/pubspec.yaml" ;;
+    vanilla-js|react) grep -q '"name": "smoke"' "$project/package.json" ;;
+    rust) grep -q '^name = "smoke"$' "$project/Cargo.toml" ;;
+  esac
+done
+"$binary" add migration create_smoke --project "$scratch/go"
+set -- "$scratch/go"/migrations/*_create_smoke.up.sql
+test -f "$1"
+"$binary" add service smoke --project "$scratch/go"
+test -f "$scratch/go/api/proto/smoke/v1/smoke.proto"
+printf '%s\n' 'Smoke checks passed for all five templates.'
diff --git a/templates/flutter_foundations/README.md b/templates/flutter_foundations/README.md
index eb2254d..89cba9b 100644
--- a/templates/flutter_foundations/README.md
+++ b/templates/flutter_foundations/README.md
@@ -61,20 +61,20 @@ fvm dart pub global run mason_cli:mason get
 ## Example workflow
 
 ```bash
-mason make flutter_app --name mediguide --description "Clinical Guidelines"
+fvm dart pub global run mason_cli:mason make flutter_app --name mediguide --description "Clinical Guidelines"
 # Add `apps/mediguide` under `workspace:` in the root pubspec.yaml.
-mason make feature --app mediguide --name guidelines
-mason make model --app mediguide --feature guidelines --name guideline
-mason make repository --app mediguide --feature guidelines --name guidelines
-mason make form --app mediguide --feature guidelines --name guideline_search
-mason make page --app mediguide --feature guidelines --name guidelines
-mason make offline_feature --app mediguide --feature guidelines --name guidelines
-mason make scanner --app mediguide --feature guidelines --name guideline_qr
-mason make test_suite --app mediguide --feature guidelines
+fvm dart pub global run mason_cli:mason make feature --app mediguide --name guidelines
+fvm dart pub global run mason_cli:mason make model --app mediguide --feature guidelines --name guideline
+fvm dart pub global run mason_cli:mason make repository --app mediguide --feature guidelines --name guidelines
+fvm dart pub global run mason_cli:mason make form --app mediguide --feature guidelines --name guideline_search
+fvm dart pub global run mason_cli:mason make page --app mediguide --feature guidelines --name guidelines
+fvm dart pub global run mason_cli:mason make offline_feature --app mediguide --feature guidelines --name guidelines
+fvm dart pub global run mason_cli:mason make scanner --app mediguide --feature guidelines --name guideline_qr
+fvm dart pub global run mason_cli:mason make test_suite --app mediguide --feature guidelines
 
 fvm dart pub get
 fvm dart run melos run codegen
-fvm dart run melos run quality
+fvm dart run melos run check
 fvm dart run melos run bricks:validate
 ```
 
@@ -102,7 +102,7 @@ fvm dart run melos run bricks:validate
 
 ```bash
 ./scripts/run_flavor.sh mediguide development
-fvm flutter run --project-dir apps/mediguide --dart-define-from-file=env/staging.json
+./scripts/run_flavor.sh mediguide staging
 ```
 
 Do not place secrets in committed Dart-define JSON files. Use secure runtime retrieval or CI secret injection for sensitive values.
@@ -114,9 +114,37 @@ fvm dart run melos run format:check
 fvm dart run melos run analyze
 fvm dart run melos run test
 fvm dart run melos run codegen
-fvm dart run melos run quality
+fvm dart run melos run check
 ```
 
 ## Platform setup still required per app
 
 Some plugins require native configuration (camera/photo/notification permissions, notification icons/channels, background execution, iOS usage descriptions, etc.). Keep that configuration in the generated app's Android/iOS projects and document any product-specific requirements there.
+
+## Command reference
+
+Run Melos commands from this workspace root through FVM: `fvm dart run melos run <task>`. The scripts below resolve their own project root and also accept `--help` without performing setup or validation.
+
+| Task | Work and side effects |
+| --- | --- |
+| `bootstrap`, `pub:get` | Resolve workspace packages; writes tool caches and may update pubspec.lock |
+| `format` / `format:check` | Rewrite/check Dart under apps/ and packages/ |
+| `analyze`, `lint` | Analyze every workspace package; lint is an alias |
+| `test` | Run Flutter tests in Flutter packages with test/ and Dart tests in non-Flutter packages with test/ |
+| `test:coverage` | Flutter coverage only, in Flutter packages with tests; not Dart-only coverage |
+| `codegen` / `codegen:watch` | Run build_runner in packages declaring it; writes generated source; watch stays running |
+| `check` | Format check → lint → test; no code generation or native app build |
+| `quality` | Compatibility alias for check |
+| `ci` | Codegen → check → bricks:validate; may download dependencies and change generated source |
+| `bricks:list` | List bricks through FVM-activated Mason |
+| `bricks:validate` | Render/generate/analyze/test every brick using the script below |
+| `outdated` | Report newer packages without upgrading constraints |
+| `clean` | Run flutter clean in Flutter packages; preserve source, lockfiles, Dart-only caches and installed SDKs |
+
+- `bash scripts/setup.sh`: require FVM, install the configured SDK, activate Mason CLI in Dart's global package cache, resolve packages, and fetch bricks. It may use the network. Equivalent manual steps are in Setup above.
+- `bash scripts/run_flavor.sh <app> [development|staging|production]`: default to development; require apps/<app> and env/<environment>.json; run the app using Dart defines. This selects JSON configuration, not a native `--flavor` build variant. Copy/configure the ignored staging/production JSON from its example first.
+- `bash scripts/validate_bricks.sh`: require fvm install and FVM-activated Mason; fetch bricks, render every generator in a temporary workspace, resolve dependencies, format-check, generate code, analyze and test the sample app/package, and remove the temporary workspace on exit. SDK/pub/Mason caches remain.
+
+Generate/register an app before running it: create it with FVM's Mason CLI, add apps/<name> to workspace: in pubspec.yaml, and run fvm dart pub get. Configure native platform folders, permissions and signing inside that app. Build with `fvm flutter build <platform>` from apps/<app>. Workspace check deliberately does not guess a platform or build every app.
+
+Mason commands in these instructions use `fvm dart pub global run mason_cli:mason` so they use the selected SDK. `foundry mason` is an optional wrapper around `mason make` from PATH; use it only when that global executable is configured for the workspace SDK. Shell scripts need Bash; FVM/Dart commands can also be run natively on Windows.
diff --git a/templates/flutter_foundations/pubspec.yaml b/templates/flutter_foundations/pubspec.yaml
index 1aa60ad..81fc0e5 100644
--- a/templates/flutter_foundations/pubspec.yaml
+++ b/templates/flutter_foundations/pubspec.yaml
@@ -47,16 +47,22 @@ melos:
     outdated:
       description: Show outdated dependencies.
       run: fvm dart run melos exec -- fvm dart pub outdated
+    lint:
+      description: Analyze all workspace packages (alias for analyze).
+      run: fvm dart run melos run analyze
+    check:
+      description: Check formatting, analysis, and tests without generating code.
+      run: fvm dart run melos run format:check && fvm dart run melos run lint && fvm dart run melos run test
     quality:
-      description: Run formatting, analysis, and tests.
-      run: fvm dart run melos run format:check && fvm dart run melos run analyze && fvm dart run melos run test
+      description: Compatibility alias for check.
+      run: fvm dart run melos run check
     ci:
-      description: CI quality gate including generated code.
-      run: fvm dart run melos run codegen && fvm dart run melos run quality
+      description: Generate code, run checks, and validate every Mason brick.
+      run: fvm dart run melos run codegen && fvm dart run melos run check && fvm dart run melos run bricks:validate
 
     bricks:list:
       description: List available Mason bricks.
-      run: mason list
+      run: fvm dart pub global run mason_cli:mason list
     bricks:validate:
       description: Render, generate, analyze, and test every Mason brick.
       run: bash scripts/validate_bricks.sh
diff --git a/templates/flutter_foundations/scripts/run_flavor.sh b/templates/flutter_foundations/scripts/run_flavor.sh
index d66490b..2bf7346 100755
--- a/templates/flutter_foundations/scripts/run_flavor.sh
+++ b/templates/flutter_foundations/scripts/run_flavor.sh
@@ -1,7 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
-APP=${1:?Usage: ./scripts/run_flavor.sh <app> <development|staging|production>}
-FLAVOR=${2:-development}
-ENV_FILE="env/${FLAVOR}.json"
-[[ -f "$ENV_FILE" ]] || { echo "Missing $ENV_FILE"; exit 1; }
-(cd "apps/$APP" && fvm flutter run --dart-define-from-file="../../$ENV_FILE")
+case "${1:-}" in
+  -h|--help) printf '%s\n' 'Usage: scripts/run_flavor.sh <app> [development|staging|production]' 'Runs an existing Flutter app with env/<environment>.json. Default: development.' 'The selected JSON must exist; staging/production examples must be copied and configured first.'; exit 0 ;;
+esac
+[[ $# -ge 1 && $# -le 2 ]] || { echo 'Usage: scripts/run_flavor.sh <app> [development|staging|production]' >&2; exit 2; }
+app=$1
+flavor=${2:-development}
+[[ "$app" =~ ^[a-z][a-z0-9_]*$ ]] || { echo 'App must be a lowercase Dart package name.' >&2; exit 2; }
+case "$flavor" in development|staging|production) ;; *) echo 'Environment must be development, staging, or production.' >&2; exit 2 ;; esac
+project_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$project_root"
+env_file="env/$flavor.json"
+[[ -f "$env_file" ]] || { echo "Missing $env_file; configure it from the corresponding example." >&2; exit 1; }
+[[ -d "apps/$app" ]] || { echo "Missing apps/$app; generate and register the app first." >&2; exit 1; }
+cd "apps/$app"
+fvm flutter run --dart-define-from-file="../../$env_file"
diff --git a/templates/flutter_foundations/scripts/setup.sh b/templates/flutter_foundations/scripts/setup.sh
index 72c0af8..58cc685 100755
--- a/templates/flutter_foundations/scripts/setup.sh
+++ b/templates/flutter_foundations/scripts/setup.sh
@@ -1,5 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail
+case "${1:-}" in
+  -h|--help) printf '%s\n' 'Usage: scripts/setup.sh' 'Installs the pinned Flutter SDK, activates Mason CLI, resolves workspace packages, and fetches bricks.'; exit 0 ;;
+esac
+[[ $# -eq 0 ]] || { echo 'Unexpected argument; use --help.' >&2; exit 2; }
+project_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$project_root"
 
 command -v fvm >/dev/null || { echo "FVM is required: https://fvm.app"; exit 1; }
 
@@ -9,4 +15,4 @@ fvm dart pub get
 fvm dart pub global run mason_cli:mason get
 
 echo "Flutter Foundation workspace is ready."
-echo "Create an app: mason make flutter_app --name my_app"
+echo "Create an app: fvm dart pub global run mason_cli:mason make flutter_app --name my_app"
diff --git a/templates/flutter_foundations/scripts/validate_bricks.sh b/templates/flutter_foundations/scripts/validate_bricks.sh
index ebebe01..d174f64 100755
--- a/templates/flutter_foundations/scripts/validate_bricks.sh
+++ b/templates/flutter_foundations/scripts/validate_bricks.sh
@@ -1,5 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
+case "${1:-}" in
+  -h|--help) printf '%s\n' 'Usage: scripts/validate_bricks.sh' 'Fetches bricks, renders examples in a temporary workspace, resolves dependencies, generates code, formats, analyzes, and tests.' 'Requires fvm install and Mason CLI activated through FVM. Removes the temporary workspace on exit.'; exit 0 ;;
+esac
+[[ $# -eq 0 ]] || { echo 'Unexpected argument; use --help.' >&2; exit 2; }
 
 repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 dart_bin="$repo_root/.fvm/flutter_sdk/bin/dart"
@@ -17,10 +21,11 @@ trap cleanup EXIT
 }
 
 export PATH="$repo_root/.fvm/flutter_sdk/bin:$PATH"
-command -v mason >/dev/null || {
-  echo "Activate Mason with 'fvm dart pub global activate mason_cli'."
+"$dart_bin" pub global run mason_cli:mason --version >/dev/null || {
+  echo "Activate Mason with 'fvm dart pub global activate mason_cli'." >&2
   exit 1
 }
+mason() { "$dart_bin" pub global run mason_cli:mason "$@"; }
 
 cd "$repo_root"
 mason get
diff --git a/templates/go-foundations/Makefile b/templates/go-foundations/Makefile
index 0c6c693..3fd1833 100644
--- a/templates/go-foundations/Makefile
+++ b/templates/go-foundations/Makefile
@@ -1,8 +1,13 @@
 DATABASE_URL ?= postgres://grpc:grpc@localhost:5432/go_foundation?sslmode=disable
+BINARY ?= bin/server
+.DEFAULT_GOAL := help
 
-.PHONY: tools proto fmt test run keys docker-up docker-down logs migrate-up migrate-down migrate-create tidy
+.PHONY: help tools codegen contracts-check format format-check lint test build dev check ci clean keys docker-up docker-down logs migrate-up migrate-down migrate-create tidy proto fmt run
 
-tools:
+help: ## Show project commands and their purpose.
+	@awk 'BEGIN {FS = ":.*## "; print "Go foundation commands:"} /^[a-zA-Z_-]+:.*## / {printf "  make %-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+tools: ## Install Buf, protobuf generators, gateway generators, and grpcurl into GOBIN/GOPATH/bin.
 	go install github.com/bufbuild/buf/cmd/buf@v1.47.2
 	go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.1
 	go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.5.1
@@ -10,39 +15,67 @@ tools:
 	go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@v2.23.0
 	go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
 
-proto:
+codegen: ## Regenerate protobuf, gRPC, gateway, and OpenAPI outputs; requires tools.
 	buf generate
 
-fmt:
-	gofmt -w ./cmd ./internal
+contracts-check: ## Lint protobuf sources without regenerating them; requires Buf.
+	buf lint
+
+format: ## Format application and generated Go source.
+	gofmt -w ./cmd ./internal ./gen
+
+format-check: ## Check Go formatting without rewriting source.
+	test -z "$$(gofmt -l ./cmd ./internal ./gen)"
 
-test: proto
+lint: ## Run go vet against the checked-in generated contracts.
+	go vet ./...
+
+test: ## Run all Go tests with the race detector; does not regenerate contracts.
 	go test -race ./...
 
-run: proto
+build: ## Build bin/server using existing generated contracts.
+	mkdir -p bin
+	go build -trimpath -o $(BINARY) ./cmd/server
+
+dev: ## Run the server; requires configured PostgreSQL and development keys.
 	go run ./cmd/server
 
-keys:
+check: format-check lint test build ## Check formatting, vet, tests, and build without changing contracts.
+
+ci: ## Regenerate contracts, lint them, then run check; requires generation tools.
+	$(MAKE) codegen
+	$(MAKE) contracts-check
+	$(MAKE) check
+
+clean: ## Remove local binaries and coverage output; preserve generated contracts.
+	rm -rf bin coverage.out
+
+keys: ## Create missing development JWT keys in secrets/; preserve existing keys.
 	./scripts/generate-dev-keys.sh
 
-docker-up: keys
+docker-up: keys ## Build and start Compose services, apply migrations, and initialize the API.
 	docker compose up --build -d
 
-docker-down:
+docker-down: ## Stop Compose services; preserve the named PostgreSQL volume.
 	docker compose down
 
-logs:
+logs: ## Follow the API container's logs until interrupted.
 	docker compose logs -f api
 
-migrate-up:
+migrate-up: ## Apply pending database migrations using DATABASE_URL.
 	migrate -path migrations -database "$(DATABASE_URL)" up
 
-migrate-down:
+migrate-down: ## Roll back one migration using DATABASE_URL; changes the database.
 	migrate -path migrations -database "$(DATABASE_URL)" down 1
 
-migrate-create:
+migrate-create: ## Create paired SQL migration files (name=create_something).
 	@test -n "$(name)" || (echo "usage: make migrate-create name=create_something" && exit 1)
 	migrate create -ext sql -dir migrations -seq $(name)
 
-tidy:
+tidy: ## Update go.mod/go.sum to match imports; may download dependencies.
 	go mod tidy
+
+# Compatibility aliases.
+proto: codegen
+fmt: format
+run: dev
diff --git a/templates/go-foundations/README.md b/templates/go-foundations/README.md
index 71eab47..99eb888 100644
--- a/templates/go-foundations/README.md
+++ b/templates/go-foundations/README.md
@@ -368,3 +368,37 @@ The server marks gRPC health `NOT_SERVING` before graceful shutdown.
 ## Suggested production extensions
 
 This starter intentionally gives you the core service platform. Depending on the application, typical next extensions are refresh-token/session rotation, a separate `user_identities` table for multi-provider account linking, Redis permission caching with invalidation, rate limiting, database integration tests via Testcontainers, TLS/mTLS, and generated API documentation.
+
+## Command reference
+
+Run these commands from this generated project's root. `make` and `make help` list targets. Make helpers need Make, a POSIX shell, and awk; native Go commands work on Windows too.
+
+| Command | What it does |
+| --- | --- |
+| `make format` / `make format-check` | Rewrite/check Go under cmd/, internal/, and gen/ |
+| `make lint` | Run go vet with existing generated contracts |
+| `make test` | Run race-enabled tests without generating contracts; requires a C toolchain for the race detector |
+| `make build` | Build bin/server; override BINARY if needed |
+| `make dev` | Start the Go process using exported environment values; needs PostgreSQL and configured JWT keys |
+| `make check` | Format check → lint → race tests → build; does not regenerate tracked contracts |
+| `make tools` | Install pinned Buf/protobuf/gateway tooling and current grpcurl; modifies Go's tool bin and may download modules |
+| `make codegen` | Regenerate protobuf, gRPC, gateway and OpenAPI outputs; requires tools on PATH; modifies generated files |
+| `make contracts-check` | Buf lint without code generation |
+| `make ci` | Sequential codegen → contract lint → check; review generated changes |
+| `make keys` | Run scripts/generate-dev-keys.sh; create only missing development RSA key files under secrets/ |
+| `make docker-up` | Ensure keys, build/start Compose stack, run migrations and API bootstrap |
+| `make docker-down` | Stop/remove Compose services; retain the named database volume |
+| `make logs` | Follow API container logs until interrupted |
+| `make migrate-up` | Apply pending migrations to DATABASE_URL using the local migrate CLI |
+| `make migrate-down` | Roll back one migration in that database |
+| `make migrate-create name=...` | Create paired SQL files using the migrate CLI |
+| `make tidy` | Update go.mod/go.sum to match imports; may download dependencies |
+| `make clean` | Remove bin/ and coverage.out; preserve contracts and secrets/ |
+
+Compatibility aliases: `fmt` → `format`, `proto` → `codegen`, `run` → `dev`. Tests and dev no longer regenerate bindings as a side effect. After changing a contract, run codegen explicitly, review its output, then check. After generation with `--no-hooks`, run format once if module substitution changed import order.
+
+The server reads process environment variables; it does not load configs/.env.example automatically. Export DATABASE_URL and overrides before make dev. The Make DATABASE_URL default is for migration commands, not automatic application configuration. Compose supplies its own container environment. Local migration commands additionally require the migrate CLI; make tools does not install it.
+
+The key script accepts `--help`, resolves its project root regardless of caller directory, preserves existing keys, and sets the private key to mode 600 when creating it. OpenSSL is required. Database migrations and Docker startup are explicit actions; check/test do not run them.
+
+On Windows without Make, use `gofmt -l ./cmd ./internal ./gen`, `go vet ./...`, `go test -race ./...`, and `go build -trimpath -o bin/server.exe ./cmd/server`. Use a POSIX environment for shell helpers, or configure development keys and services through your own platform tooling.
diff --git a/templates/go-foundations/scripts/generate-dev-keys.sh b/templates/go-foundations/scripts/generate-dev-keys.sh
index ae81e60..7293d45 100755
--- a/templates/go-foundations/scripts/generate-dev-keys.sh
+++ b/templates/go-foundations/scripts/generate-dev-keys.sh
@@ -1,5 +1,12 @@
 #!/usr/bin/env sh
 set -eu
+case "${1:-}" in
+  -h|--help) printf '%s\n' 'Usage: scripts/generate-dev-keys.sh' 'Creates missing development RSA keys in the project secrets/ directory; keeps existing keys.'; exit 0 ;;
+esac
+[ "$#" -eq 0 ] || { echo 'Unexpected argument; use --help.' >&2; exit 2; }
+project_root=$(CDPATH= cd "$(dirname "$0")/.." && pwd)
+cd "$project_root"
+command -v openssl >/dev/null || { echo 'OpenSSL is required.' >&2; exit 127; }
 mkdir -p secrets
 if [ ! -f secrets/jwt_private.pem ]; then
   openssl genrsa -out secrets/jwt_private.pem 2048 >/dev/null 2>&1
diff --git a/templates/react-foundations/README.md b/templates/react-foundations/README.md
index 737e845..2e39edc 100644
--- a/templates/react-foundations/README.md
+++ b/templates/react-foundations/README.md
@@ -51,3 +51,25 @@ Use `requestJSON` from `src/shared/lib/http.js` for JSON endpoints, passing an `
 ## Foundry delivery
 
 This template is embedded directly in Foundry. Generation needs no network connection; installing dependencies requires npm registry access or a populated npm cache. No dependencies are installed automatically.
+
+## Command reference
+
+Run npm commands from this project's root. The same scripts are available in the Vanilla JavaScript and React foundations.
+
+| Command                | Behavior and outputs                                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `npm ci`               | Replace node_modules with the exact locked dependency tree; fail if manifests disagree; do not update the lockfile |
+| `npm run dev`          | Start Vite's development server; terminal prints its URL; stop with Ctrl+C                                         |
+| `npm run build`        | Write a production static build to dist/                                                                           |
+| `npm run preview`      | Preview an existing dist/ locally; run build first; not production hosting                                         |
+| `npm run format`       | Rewrite files with Prettier; excludes lockfile/build/dependency outputs                                            |
+| `npm run format:check` | Fail on formatting differences without rewriting files                                                             |
+| `npm run lint`         | ESLint, with warnings treated as failures                                                                          |
+| `npm test`             | Run Vitest once; user interactions and HTTP failure/cancellation are covered                                       |
+| `npm run test:watch`   | Keep tests running interactively                                                                                   |
+| `npm run check`        | Format check → lint → tests → production build                                                                     |
+| `npm run clean`        | Run scripts/clean.js and remove only this project's dist/, coverage/, and .vitest/                                 |
+
+The cleanup script resolves paths relative to its own location and preserves source, node_modules and package-lock.json. All npm scripts work on Windows as well as POSIX platforms. Use npm install only for intentional dependency changes, commit the resulting lockfile, then run check. npm ci installs dependencies; it is separate from the quality gate.
+
+The development/preview processes keep running until stopped. Build/check write dist/ but do not deploy. VITE_ values are public and applied at dev startup/build time, so rebuild after changing deployed configuration. Generation from Foundry remains offline; initial dependency installation may require npm registry access.
diff --git a/templates/react-foundations/package.json b/templates/react-foundations/package.json
index b4b4636..d60aaf9 100644
--- a/templates/react-foundations/package.json
+++ b/templates/react-foundations/package.json
@@ -15,7 +15,8 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check": "npm run format:check && npm run lint && npm test && npm run build"
+    "check": "npm run format:check && npm run lint && npm test && npm run build",
+    "clean": "node ./scripts/clean.js"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
diff --git a/templates/react-foundations/scripts/clean.js b/templates/react-foundations/scripts/clean.js
new file mode 100644
index 0000000..72b6df0
--- /dev/null
+++ b/templates/react-foundations/scripts/clean.js
@@ -0,0 +1,7 @@
+import { rmSync } from 'node:fs';
+
+// Resolve from this file so only this project's generated artifacts are removed.
+const projectRoot = new URL('../', import.meta.url);
+for (const directory of ['dist/', 'coverage/', '.vitest/']) {
+  rmSync(new URL(directory, projectRoot), { recursive: true, force: true });
+}
diff --git a/templates/rust-foundations/README.md b/templates/rust-foundations/README.md
index 0b776f6..b64a402 100644
--- a/templates/rust-foundations/README.md
+++ b/templates/rust-foundations/README.md
@@ -36,11 +36,25 @@ The executable consumes the same public library API as other callers. Domain val
 
 ## Checks
 
+Full gate on macOS/Linux (or a POSIX environment):
+
+```sh
+bash scripts/check.sh
+```
+
+Native Windows PowerShell:
+
+```powershell
+./scripts/check.ps1
+```
+
+The equivalent individual commands are:
+
 ```sh
 cargo fmt --all -- --check
-cargo test --locked
 cargo lint
-cargo doc --locked --no-deps
+cargo test --locked
+RUSTDOCFLAGS="${RUSTDOCFLAGS:-} -D warnings" cargo doc --locked --no-deps
 cargo build --release --locked
 ```
 
@@ -51,3 +65,32 @@ Commit `Cargo.lock` for this application. Review dependency and toolchain change
 ## Foundry delivery
 
 Foundry embeds these source files directly. Generating this project needs no network access. Once its Rust toolchain is installed, the initial application can also build with `cargo build --locked --offline` because it has no external crates. Installing or updating Rust itself can require network access. Foundry does not invoke Cargo automatically.
+
+## Command reference
+
+Run Cargo commands from this generated project root. Both check scripts resolve the root from their own path and stop at the first failure.
+
+| Command | What it does |
+| --- | --- |
+| `cargo run --locked -- greet World` | Build/debug-run the application; values after -- are application arguments |
+| `cargo run --locked -- --help` | Show application help; different from cargo --help |
+| `cargo fmt --all` / `cargo fmt --all -- --check` | Format/check Rust source |
+| `cargo check --locked` | Type-check only; not the full quality gate |
+| `cargo lint` | Alias for clippy --locked --all-targets -- -D warnings |
+| `cargo test --locked` | Unit, executable integration, and documentation tests |
+| `cargo doc --locked --no-deps` | Write API documentation under target/doc/ |
+| `cargo build --release --locked` | Write optimized executable under target/release/; Windows adds .exe |
+| `cargo clean` | Remove Cargo target artifacts, preserving Cargo.lock and source |
+| `bash scripts/check.sh` | Format check → Clippy → all tests → docs (warnings denied) → release build |
+| `./scripts/check.ps1` | Same full gate using native PowerShell |
+
+Help: `bash scripts/check.sh --help` or `./scripts/check.ps1 -Help`. Scripts do not fix formatting or change the lockfile. Cargo's normal build/test/doc outputs are created under target/.
+
+Use RUSTUP_TOOLCHAIN to select a preinstalled compiler (CI uses stable or 1.85.0). Set CARGO_NET_OFFLINE=true to disable crate downloads for the whole gate; toolchain installation is separate. Existing RUSTDOCFLAGS are preserved, with -D warnings added for documentation. The PowerShell script restores both the caller's working directory and doc flags.
+
+Do not append --offline to cargo lint: the alias already contains --, so appended options go to the compiler. Instead use the offline environment variable or the expanded command:
+
+```sh
+CARGO_NET_OFFLINE=true bash scripts/check.sh
+cargo clippy --locked --offline --all-targets -- -D warnings
+```
diff --git a/templates/rust-foundations/scripts/check.ps1 b/templates/rust-foundations/scripts/check.ps1
new file mode 100644
index 0000000..f84f2bb
--- /dev/null
+++ b/templates/rust-foundations/scripts/check.ps1
@@ -0,0 +1,33 @@
+[CmdletBinding()]
+param([switch]$Help)
+
+$ErrorActionPreference = 'Stop'
+if ($Help) {
+    Write-Output 'Usage: scripts/check.ps1 [-Help]'
+    Write-Output 'Checks formatting, Clippy, all tests, documentation, and the release build in order.'
+    Write-Output 'Set RUSTUP_TOOLCHAIN to select a compiler or CARGO_NET_OFFLINE=true to disable downloads.'
+    exit 0
+}
+
+function Invoke-Cargo {
+    param([string[]]$CargoArgs)
+    & cargo @CargoArgs
+    if ($LASTEXITCODE -ne 0) {
+        throw "cargo $($CargoArgs -join ' ') failed with exit code $LASTEXITCODE"
+    }
+}
+
+$previousRustdocFlags = $env:RUSTDOCFLAGS
+Push-Location (Split-Path -Parent $PSScriptRoot)
+try {
+    Invoke-Cargo -CargoArgs @('fmt', '--all', '--', '--check')
+    Invoke-Cargo -CargoArgs @('lint')
+    Invoke-Cargo -CargoArgs @('test', '--locked')
+    $env:RUSTDOCFLAGS = "$previousRustdocFlags -D warnings"
+    Invoke-Cargo -CargoArgs @('doc', '--locked', '--no-deps')
+    Invoke-Cargo -CargoArgs @('build', '--release', '--locked')
+}
+finally {
+    $env:RUSTDOCFLAGS = $previousRustdocFlags
+    Pop-Location
+}
diff --git a/templates/rust-foundations/scripts/check.sh b/templates/rust-foundations/scripts/check.sh
new file mode 100755
index 0000000..908ccab
--- /dev/null
+++ b/templates/rust-foundations/scripts/check.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+case "${1:-}" in
+  -h|--help)
+    printf '%s\n' 'Usage: scripts/check.sh' \
+      'Checks formatting, Clippy, all tests, documentation, and the release build in order.' \
+      'Stops at the first failure. Set RUSTUP_TOOLCHAIN to select a compiler or CARGO_NET_OFFLINE=true to disable downloads.'
+    exit 0 ;;
+esac
+[ "$#" -eq 0 ] || { echo 'Unexpected argument; use --help.' >&2; exit 2; }
+project_root=$(CDPATH= cd "$(dirname "$0")/.." && pwd)
+cd "$project_root"
+cargo fmt --all -- --check
+cargo lint
+cargo test --locked
+RUSTDOCFLAGS="${RUSTDOCFLAGS:-} -D warnings" cargo doc --locked --no-deps
+cargo build --release --locked
diff --git a/templates/vanilla-js-foundations/README.md b/templates/vanilla-js-foundations/README.md
index 9d37de5..b8cd01d 100644
--- a/templates/vanilla-js-foundations/README.md
+++ b/templates/vanilla-js-foundations/README.md
@@ -51,3 +51,25 @@ Use `requestJSON` from `src/shared/lib/http.js` for JSON endpoints, passing an `
 ## Foundry delivery
 
 This template is embedded directly in Foundry. Generation needs no network connection; installing dependencies requires npm registry access or a populated npm cache. No dependencies are installed automatically.
+
+## Command reference
+
+Run npm commands from this project's root. The same scripts are available in the Vanilla JavaScript and React foundations.
+
+| Command                | Behavior and outputs                                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `npm ci`               | Replace node_modules with the exact locked dependency tree; fail if manifests disagree; do not update the lockfile |
+| `npm run dev`          | Start Vite's development server; terminal prints its URL; stop with Ctrl+C                                         |
+| `npm run build`        | Write a production static build to dist/                                                                           |
+| `npm run preview`      | Preview an existing dist/ locally; run build first; not production hosting                                         |
+| `npm run format`       | Rewrite files with Prettier; excludes lockfile/build/dependency outputs                                            |
+| `npm run format:check` | Fail on formatting differences without rewriting files                                                             |
+| `npm run lint`         | ESLint, with warnings treated as failures                                                                          |
+| `npm test`             | Run Vitest once; user interactions and HTTP failure/cancellation are covered                                       |
+| `npm run test:watch`   | Keep tests running interactively                                                                                   |
+| `npm run check`        | Format check → lint → tests → production build                                                                     |
+| `npm run clean`        | Run scripts/clean.js and remove only this project's dist/, coverage/, and .vitest/                                 |
+
+The cleanup script resolves paths relative to its own location and preserves source, node_modules and package-lock.json. All npm scripts work on Windows as well as POSIX platforms. Use npm install only for intentional dependency changes, commit the resulting lockfile, then run check. npm ci installs dependencies; it is separate from the quality gate.
+
+The development/preview processes keep running until stopped. Build/check write dist/ but do not deploy. VITE_ values are public and applied at dev startup/build time, so rebuild after changing deployed configuration. Generation from Foundry remains offline; initial dependency installation may require npm registry access.
diff --git a/templates/vanilla-js-foundations/package.json b/templates/vanilla-js-foundations/package.json
index 2656276..bc87669 100644
--- a/templates/vanilla-js-foundations/package.json
+++ b/templates/vanilla-js-foundations/package.json
@@ -15,7 +15,8 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check": "npm run format:check && npm run lint && npm test && npm run build"
+    "check": "npm run format:check && npm run lint && npm test && npm run build",
+    "clean": "node ./scripts/clean.js"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
diff --git a/templates/vanilla-js-foundations/scripts/clean.js b/templates/vanilla-js-foundations/scripts/clean.js
new file mode 100644
index 0000000..72b6df0
--- /dev/null
+++ b/templates/vanilla-js-foundations/scripts/clean.js
@@ -0,0 +1,7 @@
+import { rmSync } from 'node:fs';
+
+// Resolve from this file so only this project's generated artifacts are removed.
+const projectRoot = new URL('../', import.meta.url);
+for (const directory of ['dist/', 'coverage/', '.vitest/']) {
+  rmSync(new URL(directory, projectRoot), { recursive: true, force: true });
+}