fix(#804): reject unknown installer arguments

docs/scratchpads/804-install-unknown-flags.md

@@ -43,12 +43,44 @@ Implement Part 1 of Gitea issue #804 only: `tools/install.sh` must reject every
 - 2026-07-17: Confirmed the parser has no legitimate positional arguments and currently drops all unmatched input via `*) shift ;;`.
 - 2026-07-17: Installed locked workspace dependencies with a worktree-local pnpm store; no lockfile changes.
 - 2026-07-17: Added the process-level unknown-argument regression with an isolated `$HOME` and npm shim.
+- 2026-07-17: Replaced the silent catch-all with STDERR error + usage output and exit 2 before preflight or installation.
+- 2026-07-17: Initial Codex code review found an unknown option could still be consumed as the `--ref` value. Added a second RED reproducer, then rejected option-shaped/missing `--ref` values without changing valid `--ref <branch>` behavior. The review's launcher-state note is handled by excluding both `.mosaic/orchestrator/` files from commits.
+- 2026-07-17: Updated README, user guide, and packaged framework README with the fail-closed argument contract. No API, auth, admin, sitemap/navigation, or publishing surface changed.
 
 ## Verification
 
 - RED: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts` — expected failure: installer exited `0` instead of nonzero at the exit-status assertion; confirms the test reproduces the silent-drop defect before production changes.
+- Remediation RED: the added `--cli --ref --bogus` case exited `0`, proving `--ref` could swallow an unknown option before the guard was added.
+- GREEN: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts src/commands/install-heading.spec.ts` — 2 files, 3 tests passed.
+- Situational process check: unknown positional input exited 2, named the input on STDERR, printed usage, and did not call the npm shim.
+- `bash -n tools/install.sh` — passed.
+- Bare `--ref` process check — exited 2 with `Missing value for --ref` and usage.
+- `pnpm --filter @mosaicstack/mosaic test` — 69 files, 1,287 tests passed; framework shell checks passed. The first attempt lacked generated `dist/cli.js`; `pnpm --filter @mosaicstack/mosaic build` restored the required test precondition and the full rerun passed.
+- `pnpm lint` — 23/23 tasks passed.
+- `pnpm typecheck` — 42/42 tasks passed.
+- `pnpm format:check` — passed.
+- Codex code re-review against `origin/main` — `approve`, 0 blockers/should-fix/suggestions.
+- Codex security re-review against `origin/main` — risk `none`, 0 findings.
+
+## Acceptance evidence
+
+| Criterion | Evidence |
+| --- | --- |
+| Unknown input is named on STDERR | Process-level Vitest assertions for `--bogus`, including after `--ref` |
+| Short usage hint is printed on STDERR | Vitest usage regex + manual process output |
+| Exit is nonzero | Vitest status assertions and manual exit 2 |
+| Installation does not proceed | Isolated npm shim marker remains absent |
+| Recognized behavior is preserved | Parser cases are unchanged except validation of malformed `--ref`; full Mosaic package suite passed |
+| Part 2 is excluded | No `--next`, `MOSAIC_NEXT`, dist-tag, or prerelease routing changes |
+
+## Documentation checklist
+
+- Current canonical `docs/PRD.md` remains unchanged; issue #804 and the coordinator brief supply this bounded defect's acceptance contract.
+- Updated installer behavior in root README, user guide, and packaged framework README in the same logical change set.
+- API/OpenAPI, auth/permissions, admin operations, developer architecture, sitemap/navigation, and external publishing are not affected.
+- Scratchpad remains under `docs/scratchpads/`; no root-hygiene changes.
 
 ## Risks and blockers
 
 - Part 2 remains owner-gated under #805 and is intentionally excluded.
-- Test harness must isolate `$HOME` and shim npm so the pre-fix installer cannot mutate operator state or contact the registry.
+- No implementation blocker remains. Independent coordinator RoR, CI, merge, and issue closure remain pending after worker handoff.