feat(tooling): add Astro prototype preview command

.agents/skills/planning/SKILL.md

@@ -45,6 +45,7 @@ For executable refinement of an outline, [advance the planning horizon](referenc
 ## Execute or resume
 
 Resume the recorded operation. Resuming planning or revision does not mean starting implementation.
+For an authorized interactive browser prototype, read [Browser prototypes with Astro](references/browser-prototypes.md) before choosing its source layout, preview command, and handoff checks.
 
 1. Read the overview, selected plans, dependency records, and applicable repository instructions.
    Inspect the branch, working tree, commits, and actual source. For a linked PR, [read current plan feedback](references/github-review.md#read-the-feedback) and revise relevant changes within existing authorization.

.agents/skills/planning/references/browser-prototypes.md

@@ -0,0 +1,37 @@
+# Browser prototypes with Astro
+
+Use the repository's pinned Astro dependency for interactive browser experiments unless the user selects another format or the experiment requires one.
+This procedure supports an authorized prototype; it does not authorize implementation during planning-only work or choose the eventual native app architecture.
+
+## Set up the experiment
+
+- Keep the project beside its numbered plan, usually `Plans/YYYY-MM-DD-topic/Prototype/`. Give its README the exact working directory, start/check/build commands, sample-data limits, and reset behavior.
+- Reuse the root `package.json`, `package-lock.json`, and installed `node_modules`. If dependencies are missing, run `mise exec -- npm ci` from the repository root. Do not scaffold a second dependency tree or fetch a newer Astro release.
+- Put the active page in `src/pages/index.astro` and its client code/styles in Astro's watched import graph. Do not serve the whole editable app as an unprocessed file under `public/`; that bypasses the intended development loop.
+- Keep Astro/Vite caches and build output ignored and local to the prototype. Restrict dev-server file access to the prototype's sources and required dependencies, rather than exposing the repository root. Historical artifacts stay clearly labeled; identify one current source.
+
+## Run and share the preview
+
+Use the repository command from the repository root (see [`./prototype --help`](../../../../prototype) and [tooling details](../../../../Tools/README.md#browser-prototypes)):
+
+```sh
+./prototype start Plans/YYYY-MM-DD-topic/Prototype --lan
+./prototype status Plans/YYYY-MM-DD-topic/Prototype
+./prototype logs Plans/YYYY-MM-DD-topic/Prototype
+./prototype stop Plans/YYYY-MM-DD-topic/Prototype
+```
+
+The command owns pinned tooling, absolute project paths, background lifecycle, ownership checks, port conflicts, HTTP readiness, and current reachable IPv4 URLs. Run `status` again at handoff; network addresses can change while the server stays running. Give the user the verified local and network URLs. A phone uses the latter on the same network. Keep this a development preview; do not add public hosting or a tunnel unless requested.
+
+Leave the review server running for an interactive handoff and provide its stop command; stop temporary verification servers. Record its worktree/project and owner in the execution checkpoint, including the coordinator's reporting duty under [Delegated execution handoff](../SKILL.md#delegated-execution-handoff).
+
+## Verify the development loop
+
+```sh
+./prototype check Plans/YYYY-MM-DD-topic/Prototype
+./prototype build Plans/YYYY-MM-DD-topic/Prototype
+```
+
+Exercise the served prototype in a browser at the intended viewport sizes. Make and revert a small visible source edit and observe automatic updates without manually reloading. Cover the edited source kinds, such as route markup, client code, and CSS; a successful HTTP response or build alone does not establish live reload. Record whether an update preserves the sample session or performs a full reload that resets it.
+
+Check both loopback and the actual LAN address, including live reload when reachable. A request from the host to its own LAN address is not physical-phone verification; distinguish that evidence from an actual device test. Confirm the served final content and source revision after reverting the probe, then record checks, URLs, remaining limits, and publication state in the plan before the completion notice.

.agents/skills/planning/references/develop-plan.md

@@ -32,6 +32,7 @@ Record sources, covered revisions/versions, implications, and unresolved claims
 Compare meaningful alternatives against requirements, integration cost, and maintenance burden. Route unresolved product trade-offs through the question loop before selecting an approach.
 Record the decision source and why alternatives were rejected, without inventing alternatives for routine choices.
 If feasibility needs a prototype, plan an [experiment deliverable](../../../../Plans/AGENTS.md#experiment-deliverables); execute it only within existing authorization.
+For an interactive browser experiment, use [Browser prototypes with Astro](browser-prototypes.md) to specify the development loop and device-preview evidence.
 Stop when material decisions have enough evidence and remaining uncertainty is explicit. Record when repository evidence suffices without external research.
 
 ## Resolve questions

AGENTS.md

@@ -30,6 +30,7 @@ Read the matching reference before implementation or review. Read only relevant
 - Regenerate with `./ide --no-open`. Never open Xcode or bypass the setup with `tuist generate`.
 - Use `./test` for iOS bundles. Never hand-roll `tuist test` or `xcodebuild` for them.
 - Use root commands for their owned state. Read `--help` instead of reimplementing a command.
+- Use `./prototype` for Astro prototype servers and checks; see [tooling details](Tools/README.md#browser-prototypes).
 - Use `./icons` for icon catalogs and manifests. Never hand-edit them or add icon Swift.
 - Run `./attribution` after adding or updating a package, external skill, or development tool. Commit the report.
 - Run `./test --architecture-only` after a Where dependency, composition-root, or documented concurrency-boundary change.

README.md

@@ -205,6 +205,7 @@ sync-agents         Link Claude skills to .agents/skills/; remove legacy instruc
 simulator           Resolve/create this checkout's simulator, boot it, print its UDID
 worktree            Check or update against origin/main; remove owned worktree caches
 profile             Report build/test hot spots (see `./profile --help`)
+prototype           Run, inspect, check, and build plan-local Astro prototypes
 flyover             Export, preview, and develop Where's native Flyover QA atlas with Astro
 flaky               Detect flaky tests, update FLAKY_TESTS.md (see `./flaky --help`)
 circleci-artifacts   Download every artifact for a CircleCI job

Tools/AGENTS.md

@@ -75,6 +75,14 @@ These rules also apply when changing a root command or installer that calls this
   Count UTF-8 bytes with directory override precedence. Check Markdown links from both canonical and Claude skill paths.
   Guards: [agent_guidance_test.rb](Tests/agent_guidance_test.rb), [agent_markdown_test.rb](Tests/agent_markdown_test.rb), and [sync_agents_command_test.rb](Tests/sync_agents_command_test.rb).
 
+## Prototype servers
+
+Use Astro's own background lifecycle and the shared `astro_site.py` launcher.
+Keep status read-only; distinguish missing or dead processes from inspection errors.
+Before reuse or stop, require the Astro command, absolute project argument, and working directory to agree.
+Discover and HTTP-check current network addresses at handoff; cached startup URLs are not current evidence.
+Guards: [test_prototype.py](Tests/test_prototype.py) and [test_prototype_command.py](Tests/test_prototype_command.py).
+
 ## Installer publication
 
 Both websites share the root npm workspace and `astro_site.py` launcher.

Tools/README.md

@@ -11,6 +11,53 @@ The shared lint command checks formatting without changing files. Keep formattin
 CSS uses the standard Stylelint preset. The configuration preserves three Safari-prefixed properties without disabling the prefix rule.
 The standard duplicate-property rule permits different CSS syntaxes, but rejects repeated declarations with different values in the same syntax.
 
+## Browser prototypes
+
+`./prototype` manages an existing Astro project, usually beside its plan in `Plans/`.
+It reuses the root lockfile, installed dependencies, pinned Node, and `astro_site.py` launcher.
+Install missing dependencies once with `mise exec -- npm ci`; the command does not install or scaffold them.
+The project needs `astro.config.mjs` and a working route at `/`.
+For another route or Astro `base`, pass `--path /demo/` to both `start` and `status`.
+This selects the URL to verify/share; it does not change Astro configuration or persist a preference.
+Astro's server metadata omits its configured base, so the command does not infer it.
+
+```sh
+./prototype start Plans/YYYY-MM-DD-topic/Prototype --lan
+./prototype status Plans/YYYY-MM-DD-topic/Prototype
+./prototype logs Plans/YYYY-MM-DD-topic/Prototype
+./prototype check Plans/YYYY-MM-DD-topic/Prototype
+./prototype build Plans/YYYY-MM-DD-topic/Prototype
+./prototype stop Plans/YYYY-MM-DD-topic/Prototype
+```
+
+Paths resolve from the caller's directory; absolute paths work across checkouts.
+The command always selects tools from its own checkout. `start` defaults to port 4321,
+loopback only; `--lan` binds all IPv4 interfaces. Use `--port NUMBER` to choose another port.
+An existing owned server is reused. Changing its port or enabling LAN on a loopback server
+requires an explicit stop/start. Port conflicts fail without stopping another process.
+Use `vite.server.strictPort: true` in the prototype config to also reject a startup port race.
+
+Astro owns the daemon, `.astro/dev.json`, and `.astro/dev.log`.
+The wrapper serializes its start/stop operations with `.astro/prototype-command.lock`;
+use the wrapper consistently and keep project paths stable during lifecycle operations.
+Before reusing or stopping a live PID, it checks the Astro executable, absolute project argument,
+and working directory. It supports macOS and Linux; unusual manually launched commands are refused.
+Inspection errors and malformed records remain errors. `status` is read-only, including stale records;
+`logs` can read failure output after the server exits. `stop` is idempotent when nothing is running.
+
+`start` waits for Astro's bounded startup and then checks HTTP readiness.
+`status` checks HTTP again and reports currently reachable IPv4 interface URLs, ignoring cached
+startup addresses. These checks bypass proxies and do not follow redirects.
+Run status again before sharing a URL. Interface names distinguish local-network and VPN addresses;
+a successful host request does not establish physical-phone connectivity or browser live reload.
+A failed HTTP/LAN check leaves the server available for diagnosis through `logs` and `stop`.
+`status` exits 1 when absent or unhealthy; check/build and native lifecycle failures preserve child status.
+
+Keep `.astro/`, `dist/`, and Vite state ignored and local to the project.
+Keep source inside Astro's watched import graph and restrict `vite.server.fs.allow` to the
+prototype and required dependencies. The [planning guidance](../.agents/skills/planning/references/browser-prototypes.md)
+owns experiment design, browser verification, and handoff evidence.
+
 ## Daily Flyover publication
 
 `.github/flyover-apps.json` owns hosted capture registration. `flyover_apps.py` validates it before capture.