@terreno/mcp 0.26.0 → 0.28.0

package/dist/docs/versioned/next/tasks/agentic-sdlc-plugin.md

@@ -0,0 +1,163 @@
+# Task List: Publish and Document the Agentic SDLC Plugin
+
+See: [`docs/implementationPlans/agentic-sdlc-plugin.md`](../implementationPlans/agentic-sdlc-plugin.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` update the frontend-verification path lists, which name `rtk/` today and must name `syncdb/` after PR #869. Everything else is safe to implement now.
+
+## Instructions for the implementing agent
+
+- Read all five skill files under `plugins/terreno-planning/skills/` before changing any of them. The stages reference each other's scope boundaries, so an edit to one often requires a matching edit elsewhere.
+- Do not change what a stage *does*. This IP is packaging, portability, and documentation. If you believe a stage's procedure is wrong, note it and propose it separately.
+- When you remove Flourish-specific content, do not remove the underlying judgment. "Apply PHI minimum-necessary handling" becomes a rule about sensitive data, not nothing.
+- Test portability claims by actually running the pipeline outside this repository. A portability fix you did not exercise in a consumer app is unverified.
+- Run `bun run rules:check` after touching `.rulesync/`, and `bun run check` before each commit.
+
+## Phase 1: Decide and sanitize
+
+- [ ] **Task 1.1**: Audit the plugin for repo- and org-specific content
+  - Description: Grep all five skills for Flourish-specific and monorepo-specific content: `rg -n -i "phi|hipaa|flourish|dcb3|example-frontend|admin-spa|bun run|docs/implementationPlans"` across `plugins/`. Produce a table: file, line, category (org-specific / repo-path / hardcoded value / tool assumption), and the proposed replacement. Include the `.cursor-plugin/*.json` files (owner email, marketplace description). Do not change anything yet.
+  - Files: none (findings in the PR body)
+  - Depends on: none
+  - Acceptance: every hit is categorized with a proposed replacement; the table covers all five skills plus both JSON files.
+
+- [ ] **Task 1.2**: Generalize sensitive-data handling
+  - Description: Per IP question AP2, replace PHI/HIPAA-specific language with generalized sensitive-data language across `terreno-1-blend`, `terreno-4-pour`, and `terreno-5-dialin`. The rule must survive the rewrite: PR text, review replies, and attached evidence media must not contain sensitive data (PHI, PII, credentials, customer data). Keep it concrete — a vague "be careful with data" is not a usable instruction for an agent.
+  - Files: `plugins/terreno-planning/skills/terreno-1-blend/SKILL.md`, `terreno-4-pour/SKILL.md`, `terreno-5-dialin/SKILL.md`
+  - Depends on: Task 1.1
+  - Acceptance: `rg -n -i "phi|hipaa" plugins/` returns nothing; each rewritten rule names the specific artifacts it applies to (PR body, comments, screenshots, recordings) and the data categories.
+
+- [ ] **Task 1.3**: Fix the hardcoded branch suffix
+  - Description: `terreno-4-pour` documents the branch convention as `cursor/<descriptive-name>-dcb3`. The suffix is per-agent-run, not a fixed literal, so this will produce wrong branch names. Replace it with a description of the convention (a `cursor/` prefix plus the run-specific suffix the agent was given) and instruct the agent to use the suffix from its own run instructions rather than any literal in the skill.
+  - Files: `plugins/terreno-planning/skills/terreno-4-pour/SKILL.md`
+  - Depends on: Task 1.1
+  - Acceptance: no literal run suffix appears anywhere in `plugins/`; the convention is described such that an agent in any run produces a correctly-suffixed branch.
+
+- [ ] **Task 1.4**: Clean up plugin metadata
+  - Description: Update `.cursor-plugin/marketplace.json` and `plugins/terreno-planning/.cursor-plugin/plugin.json`: adjust the marketplace description per the AP1 decision (it currently says "Team marketplace"), review whether a personal email is the right contact for a public plugin versus a role address, and add a field or README note declaring which Terreno versions the plugin targets (IP question AP7). Add `plugins/terreno-planning/LICENSE` matching the root license.
+  - Files: `.cursor-plugin/marketplace.json`, `plugins/terreno-planning/.cursor-plugin/plugin.json`, `plugins/terreno-planning/LICENSE` (new)
+  - Depends on: Task 1.1
+  - Acceptance: both JSON files are valid and consistent with the AP1 decision; the contact address is a deliberate choice; the targeted Terreno version range is declared; the LICENSE matches the root license.
+
+## Phase 2: Portability
+
+- [ ] **Task 2.1**: Remove repo-root-relative sibling-skill paths
+  - Description: `terreno-4-pour` step 6 instructs reading `plugins/terreno-planning/skills/terreno-5-dialin/SKILL.md` "from the repository root", and `terreno-5-dialin` does the same for Pour. That path only resolves when the workspace happens to be this repository — an installed plugin lives in the agent's plugin cache. Replace with guidance that resolves in both cases: reference the sibling skill relative to the current skill's own location, and keep the existing note that Cursor may not resolve plugin skill names alone. Verify the replacement actually works by running Pour's handoff from a workspace that is not this repo.
+  - Files: `plugins/terreno-planning/skills/terreno-4-pour/SKILL.md`, `terreno-5-dialin/SKILL.md`
+  - Depends on: Task 1.3
+  - Acceptance: the handoff resolves both inside this repo and in a consumer app; no absolute or repo-root-relative path to a sibling skill remains; the fix was exercised in a non-Terreno workspace.
+
+- [ ] **Task 2.2**: Resolve the `verify-ui-changes` dependency
+  - Description: Four stages invoke `verify-ui-changes` by name, but that skill lives in this repo's `.rulesync/skills/` and a consumer installing the plugin does not get it. Choose and implement one resolution: bundle a consumer-appropriate copy inside the plugin, or declare it as a prerequisite with installation instructions, or have `terreno_bootstrap_app` generate it into consumer apps. Whichever is chosen, a consumer running the pipeline must end up with a working frontend-verification step rather than a reference to a skill they do not have.
+  - Files: `plugins/terreno-planning/skills/*/SKILL.md`, plus the bundled skill or the bootstrap template
+  - Depends on: Task 2.1
+  - Acceptance: a consumer app that installed only the plugin can execute the frontend-verification step; the resolution is documented in `plugins/README.md`; no stage references a skill the user cannot obtain.
+
+- [ ] **Task 2.3**: `[RTK]` Derive frontend paths from project layout
+  - Description: The frontend gates in Roast, Pour, and Dial In hardcode Terreno monorepo package names (`ui/`, `demo/`, `example-frontend/`, `admin-frontend/`, `admin-spa/`, `rtk/`). Replace with layout detection: describe how to identify frontend paths in the two shapes that matter — this monorepo, and a bootstrapped consumer app (which uses `frontend/`/`backend/`) — and instruct the agent to determine the set rather than assume it. Update the path list to name `syncdb/` instead of `rtk/` per PR #869, keeping `rtk/` for the deprecation window.
+  - Files: `plugins/terreno-planning/skills/terreno-2-roast/SKILL.md`, `terreno-4-pour/SKILL.md`, `terreno-5-dialin/SKILL.md`
+  - Depends on: Task 2.2, PR #869 merged
+  - Acceptance: the gates fire correctly in both a bootstrapped consumer app and this monorepo, verified by running Roast on a frontend change in each; `syncdb/` is included and `rtk/` retained.
+
+- [ ] **Task 2.4**: Make Blend's conventions portable
+  - Description: `terreno-1-blend` assumes `docs/implementationPlans/` and `docs/tasks/`, a project registry containing only `flourishhealth/terreno`, and this repo's `bun run` command set. Generalize: describe where planning artifacts go with a documented default and a way to detect an existing convention, replace the hardcoded registry with a resolution procedure, and describe the command set as "the project's lint/compile/test commands" discovered from `package.json`. Keep the question-first behavior exactly as it is — that is the stage's most valuable property.
+  - Files: `plugins/terreno-planning/skills/terreno-1-blend/SKILL.md`
+  - Depends on: Task 2.1
+  - Acceptance: Blend produces an IP in a consumer app with no Terreno-specific directory assumptions; the question-first clarification gate is unchanged; the registry is a procedure rather than a fixed list.
+
+- [ ] **Task 2.5**: Verify the pipeline in a consumer app
+  - Description: Scaffold an app with `terreno_bootstrap_app`, install the plugin, and take one small feature from request to open PR through all five stages. Record every place the pipeline assumed something untrue about the project. Fix each. This task is the actual acceptance test for Phase 2 — the previous tasks are hypotheses until this passes.
+  - Files: any plugin skill needing correction
+  - Depends on: Task 2.3, Task 2.4
+  - Acceptance: all five stages complete in a consumer app; a PR is opened with evidence attached; every assumption failure found is fixed; the run is summarized in the PR body.
+
+## Phase 3: Resolve overlap with repo skills
+
+- [ ] **Task 3.1**: Map the overlap precisely
+  - Description: For each plugin stage, read its repo-skill counterparts (`submit`, `commit`, `create-pr`, `check-watcher`, `respond-to-review`, `autobot`, `ip`, `design-blend`, `implement`) and produce a table: plugin stage, overlapping skill, rules that agree, rules that **disagree**. The disagreements matter most — two documented processes with different rules is worse than either alone. Report in the PR body.
+  - Files: none (findings in the PR body)
+  - Depends on: none
+  - Acceptance: every stage is mapped to its counterparts; all rule disagreements are listed explicitly with both wordings.
+
+- [ ] **Task 3.2**: Make Brew self-contained; inline Taste review loop per AP5
+  - Description: Per IP question AP5, rewrite **Taste** (`terreno-5-taste`) to inline the full submit → CI → review loop (former `autobot` behavior) rather than delegating to repo skills — delegation has been unreliable inside the plugin. **Brew** (`terreno-4-brew`) may orchestrate `commit`/`create-pr` where those resolve from the plugin cache, but must not depend on monorepo-only paths. Resolve every disagreement from Task 3.1 in favor of one wording, in one place. Deprecate `submit` and `autobot` repo skills once Taste ships.
+  - Files: `plugins/terreno-planning/skills/terreno-4-brew/SKILL.md`, `terreno-5-taste/SKILL.md`, and deprecated `.rulesync/skills/submit/`, `autobot/`
+  - Depends on: Task 3.1, Task 2.5
+  - Acceptance: Taste completes a full review loop without delegating to repo skills; no rule appears in both a plugin stage and a repo skill with different wording; `submit`/`autobot` are marked deprecated; `bun run rules:check` exits 0.
+
+- [ ] **Task 3.3**: Cross-reference deprecated repo skills
+  - Description: Add a short deprecation note to `.rulesync/skills/submit/SKILL.md` and `autobot/SKILL.md` pointing to the plugin pipeline (Brew/Taste) as the supported path. Regenerate mirrors. Document in `plugins/README.md` that the individual repo skills are legacy once the plugin is public.
+  - Files: `.rulesync/skills/submit/SKILL.md`, `.rulesync/skills/autobot/SKILL.md`, generated mirrors, `plugins/README.md`
+  - Depends on: Task 3.2, Task 4.1
+  - Acceptance: both skills state they are deprecated in favor of Brew/Taste; the plugin README references them as legacy; `bun run rules:check` exits 0.
+
+## Phase 4: Documentation
+
+- [ ] **Task 4.1**: Write `plugins/README.md`
+  - Description: Under 150 lines. Cover: what the pipeline is in two sentences; the five stages in a table with the plain-language meaning of each coffee name per IP question AP3; installation (marketplace, per the AP1 decision); a quickstart showing one feature going through all five stages; prerequisites (the skill dependency from Task 2.2, the Terreno version range from Task 1.4); how it relates to the individual repo skills; and how to use a single stage without the full pipeline. Every command must be one you ran.
+  - Files: `plugins/README.md` (new)
+  - Depends on: Task 2.5
+  - Acceptance: under 150 lines; every coffee name is glossed; the installation steps were performed from a fresh state; the quickstart matches a run you completed.
+
+- [ ] **Task 4.2**: Write `docs/explanation/agentic-sdlc.md`
+  - Description: The conceptual case, no commands. Cover: the process layer versus the MCP tool layer, and why both are needed; why planning is a separate stage with a question-first gate (agents confidently plan the wrong thing); why review happens in a **fresh context** rather than by asking the implementing agent to check its own work; why verification is a separate stage from implementation; why the frontend gate demands evidence rather than a claim; and why flaky CI must be classified rather than guessed at. Then an honest limits section: what the pipeline does not do, where a human must decide, and the 15-minute review timeout. Reuse the mermaid diagram from the IP.
+  - Files: `docs/explanation/agentic-sdlc.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 4.1
+  - Acceptance: no commands; all six design rationales explained; a limits section naming at least three things the pipeline will not do; linked from the explanation index.
+
+- [ ] **Task 4.3**: Write `docs/how-to/use-the-terreno-plugin.md`
+  - Description: Task-focused: install the plugin, take a small feature from request to merged PR through all five stages, with the real output of each stage. Include what to do when a stage stops and asks a question (Blend's clarification gate), when Roast's review sub-agent flags something, and when Dial In reports blocked. Include a "using one stage on its own" section — most people will start with Pour or Dial In on existing work rather than adopting the whole pipeline at once.
+  - Files: `docs/how-to/use-the-terreno-plugin.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 4.2
+  - Acceptance: the walkthrough was performed and the outputs shown are real; all three interruption cases documented; the single-stage section is present; listed in the how-to index.
+
+- [ ] **Task 4.4**: Write `docs/reference/sdlc-plugin.md`
+  - Description: Per-stage reference: name, slash command, plain-language purpose, preconditions, inputs, outputs, scope boundary (what it explicitly does not own), handoff target, and failure/exit conditions. Include the `disable-model-invocation` behavior — several stages are deliberately not auto-invocable and must be called explicitly — and explain why. Add the plugin to `docs/reference/README.md`.
+  - Files: `docs/reference/sdlc-plugin.md` (new), `docs/reference/README.md`
+  - Depends on: Task 4.1
+  - Acceptance: all five stages documented with all eight fields; the auto-invocation behavior matches each skill's frontmatter; listed in the reference index.
+
+## Phase 5: Positioning
+
+- [ ] **Task 5.1**: Add the pipeline to the positioning copy
+  - Description: Update `docs/explanation/positioning.md` (from [`positioning-django-rails-universal`](../implementationPlans/positioning-django-rails-universal.md)): name the pipeline in the AI-native pillar's `pillars` block, and rewrite the comparison table's generator row so it credits the pipeline — Django gives you `manage.py startapp`, Terreno gives you a reviewed path from request to mergeable PR. Add the tool-layer/process-layer distinction to the `pitch` block. Keep the copy blocks internally consistent, since every other surface copies them verbatim.
+  - Files: `docs/explanation/positioning.md`
+  - Depends on: Task 4.2
+  - Acceptance: the pipeline appears in the pillars block and the comparison table; the tool/process distinction is in the pitch; the blocks remain consistent with each other.
+
+- [ ] **Task 5.2**: Surface the pipeline in the README and docs landing
+  - Description: Add the pipeline to `README.md`'s AI section (currently only describes the MCP server) and to `docs/README.md`'s pillars, each with a link to the explainer and the how-to. Keep it to a short paragraph in each — the detail lives in the docs. Make sure the AI section names both layers so a reader understands they are complementary rather than alternatives.
+  - Files: `README.md`, `docs/README.md`
+  - Depends on: Task 5.1
+  - Acceptance: both surfaces name the pipeline and the MCP server as the two halves of the AI story; both link the explainer; neither exceeds a paragraph.
+
+- [ ] **Task 5.3**: Make agents aware of the pipeline
+  - Description: Add the pipeline to `.rulesync/rules/00-root.md` (source for `AGENTS.md`, `CLAUDE.md`, and the copilot instructions) and to `CLAUDE-consumer.md`, so an agent working in this repo or in a consumer app knows the pipeline exists and when to use it. Currently no root agent file mentions `plugins/` at all. Regenerate mirrors.
+  - Files: `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`, generated mirrors
+  - Depends on: Task 5.2
+  - Acceptance: `AGENTS.md` and `CLAUDE.md` both describe the pipeline and when to use it; `bun run rules:check` exits 0.
+
+- [ ] **Task 5.4**: Use the pipeline in the dogfooding harness
+  - Description: If AP1 made the plugin public, update `.rulesync/skills/build-terreno-app/SKILL.md` to install and use the pipeline during the dogfooding run — it is exactly the kind of public tooling that harness is meant to exercise, and the run will find portability problems that Task 2.5 missed. Add the plugin to the skill's list of permitted public sources, and add a friction-log section for pipeline-specific gaps. Regenerate mirrors.
+  - Files: `.rulesync/skills/build-terreno-app/SKILL.md`, generated mirrors
+  - Depends on: Task 5.3
+  - Acceptance: the harness installs and uses the pipeline; the plugin is listed among permitted sources; the friction log has a pipeline section; `bun run rules:check` exits 0.
+
+## Phase 6: Distribution
+
+- [ ] **Task 6.1**: Verify a fresh install
+  - Description: From a clean agent environment with no plugin cache, install the plugin per `plugins/README.md` and confirm all five stages are available and invocable. Record what the install experience actually looks like, including whether the stages appear as slash commands and whether the sibling-skill handoff from Task 2.1 resolves from the cache rather than the workspace.
+  - Files: `plugins/README.md` (corrections)
+  - Depends on: Task 4.1, Task 1.4
+  - Acceptance: a fresh install exposes all five stages; the handoff resolves from the plugin cache; every install-guide inaccuracy is fixed.
+
+- [ ] **Task 6.2**: Generate non-Cursor variants
+  - Description: Per IP question AP6, make the pipeline available outside Cursor by routing it through `.rulesync/`, which already generates skills for cursor, claude, devin, copilot, and agents targets. Decide whether the plugin skills become rulesync sources (generated into the plugin directory) or whether a parallel rulesync copy is maintained — prefer one source of truth. Document which runtimes are supported and any behavioral differences (notably that the `disable-model-invocation` and slash-command behavior is Cursor-specific).
+  - Files: `.rulesync/skills/` or the plugin skills, `plugins/README.md`, `docs/reference/sdlc-plugin.md`, generated mirrors
+  - Depends on: Task 6.1
+  - Acceptance: the pipeline is invocable in at least one non-Cursor runtime; there is a single source of truth per skill, not two divergent copies; runtime differences are documented; `bun run rules:check` exits 0.
+
+- [ ] **Task 6.3**: Extend license coverage to `plugins/`
+  - Description: Update `scripts/check-license-coverage.ts` (from [`oss-governance-baseline`](../implementationPlans/oss-governance-baseline.md)) so `plugins/terreno-planning/` is covered by the license check. Confirm the plugin ships a LICENSE and that its declared license matches the root license.
+  - Files: `scripts/check-license-coverage.ts`
+  - Depends on: Task 1.4, `oss-governance-baseline` Task 1.6
+  - Acceptance: `bun run check:licenses` covers the plugin; deleting `plugins/terreno-planning/LICENSE` makes it fail and name the plugin.

package/dist/docs/versioned/next/tasks/ai-dev-loop-boost.md

@@ -0,0 +1,120 @@
+# Task List: The AI Development Loop (Boost)
+
+See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai-dev-loop-boost.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` rename `get_rtk_state` and relocate `installTerrenoDevConsoleLogger`; they require PR #869 merged in addition to PR #802. Unmarked tasks require only #802.
+
+## Instructions for the implementing agent
+
+- **Phase 1 gates everything.** PR #802 was in draft when this IP was written. Verify every tool name, parameter, and environment variable against the merged source in `mcp-server/src/local/` and `mcp-server/src/tools.ts` before documenting anything.
+- Every tool output shown in documentation must be real output from a real run, not a plausible-looking example.
+- Do not add new MCP tools. This IP documents and renames; it does not expand the surface.
+- Run `bun run mcp:build`, `bun run lint`, and `bun run compile` before each commit. Run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Reconcile with merged #802
+
+- [ ] **Task 1.1**: Inventory the actual MCP surface
+  - Description: Read `mcp-server/src/tools.ts`, `mcp-server/src/prompts.ts`, `mcp-server/src/resources.ts`, `mcp-server/src/local/localTools.ts`, and every file under `mcp-server/src/local/tools/`. Produce a table of every tool with its exact name, input schema, and which server hosts it. Separately list every environment variable the servers read (`TERRENO_MCP_EVAL`, `TERRENO_METRO_URL`, `TERRENO_PROJECT_ROOT`, `TERRENO_LOG_FILE`, `TERRENO_BROWSER_LOGS`, and any others found). Compare against the tool table in the IP and correct the IP where it is wrong. Put the deltas in the PR body.
+  - Files: `docs/implementationPlans/ai-dev-loop-boost.md`
+  - Depends on: PR #802 merged
+  - Acceptance: every tool in the corrected table is greppable in the source; every environment variable cites its reading file; the PR body lists what differed from the pre-merge IP.
+
+- [ ] **Task 1.2**: Verify the log pipeline end to end
+  - Description: Start the example backend and frontend, then exercise each `read_logs` source and record real output: `backend` (winston JSONL file transport), `app` (console output over Metro CDP), `metro` (bundler events), and `browser` (POST fallback). Deliberately break something to produce an error and confirm `last_error` returns it with a stack. Note which sources required extra setup and what happens when Metro is not running. Save the real outputs for use in the documentation tasks.
+  - Files: none (findings recorded for later tasks)
+  - Depends on: Task 1.1
+  - Acceptance: all four sources produced output, or any that did not is documented with the reason; `last_error` output captured verbatim including a stack trace.
+
+- [ ] **Task 1.3**: Reproduce the Hermes CDP contention symptom
+  - Description: With `read_logs` connected and streaming `app` source entries, open React Native DevTools (press `j` in Metro) and observe what happens to the log tool. Record the exact status message or failure the tool reports. Then close DevTools and confirm whether the tool recovers automatically. This becomes the documented symptom and workaround.
+  - Files: none (findings recorded for later tasks)
+  - Depends on: Task 1.2
+  - Acceptance: the symptom is recorded verbatim; recovery behavior (automatic or requiring a retry) is confirmed by observation.
+
+## Phase 2: Reference completeness
+
+- [ ] **Task 2.1**: Update `docs/reference/mcp-server.md`
+  - Description: Rewrite the tool sections to match the Task 1.1 inventory exactly. Split clearly into "Hosted server (`terreno-mcp`)" and "Local server (`terreno-mcp-local`)" sections. For each tool: name, purpose, input schema table, example call, and example output. Add an "Environment variables" section listing every variable from Task 1.1 with its effect and default. Add a "What the local server can and cannot see" section — it reads `package.json`/lockfiles, connects to Mongo via the consumer's `.env`, tails log files, and attaches over CDP; it never imports consumer code. Document the Hermes limitation from Task 1.3. Update the hosted URL per IP question AI6 if the domain decision has been made.
+  - Files: `docs/reference/mcp-server.md`
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: tool list matches the inventory one-to-one; every environment variable documented; the can/cannot-see section is present; the Hermes symptom is quoted from Task 1.3.
+
+- [ ] **Task 2.2**: Sync `mcp-server/README.md`
+  - Description: Bring the package README's tool list in line with the reference page (it is known to omit `terreno_search_docs`, `terreno_get_component_docs`, and `terreno_get_upgrade_guide`). Keep the README short — the six-section template from [`docs-reference-coverage`](../implementationPlans/docs-reference-coverage.md) — and link the reference page for full detail.
+  - Files: `mcp-server/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: the README and reference page list identical tool sets; the README follows the standard template; all links absolute.
+
+- [ ] **Task 2.3**: Document the browser-log route
+  - Description: Add `POST /__terreno/browser-logs` to `docs/reference/api.md` (or the appropriate reference page) documenting: that it is registered only when `NODE_ENV !== "production"`, that it 404s in production, the `TERRENO_BROWSER_LOGS=false` override, the JSONL file it appends to, and the payload shape. Verify all of this against `api/src/browserLogsRoute.ts` in the merged tree.
+  - Files: `docs/reference/api.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 1.1
+  - Acceptance: every behavior claimed matches `api/src/browserLogsRoute.ts`; the production 404 behavior is stated; the env var appears in the environment reference.
+
+## Phase 3: The loop explainer
+
+- [ ] **Task 3.1**: Write `docs/explanation/ai-development-loop.md`
+  - Description: Explainer covering the five stages (Ask, Generate, Run, Observe, Fix) with the mermaid diagram from the IP. For each stage, name the tools involved and what they contribute. Then a "Tool layer versus process layer" section using the table from the IP, stating that this page covers the tool layer and that the `/terreno-*` SDLC pipeline is the process layer, with a link to `docs/explanation/agentic-sdlc.md` — do not duplicate that page's content. Then a "What makes this different" section built on one narrow, defensible claim: the agent observes what the app actually did rather than a description of it. Then a "What the agent cannot see" section — production logs, native crash reports outside the dev loop, anything requiring a physical device not attached to a dev server, and the Hermes single-connection limitation. Then a "How this composes" section covering `expo-mcp` for simulator interaction, Playwright MCP for web, and Maestro for durable E2E flows, with the division of labor. No commands — this is conceptual.
+  - Files: `docs/explanation/ai-development-loop.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: all five stages present with real tool names from the inventory; the tool/process table is present and links the companion page; the cannot-see section has at least four honest limitations; no shell commands; listed in the explanation index.
+
+- [ ] **Task 3.2**: Write `docs/explanation/agent-guidelines.md`
+  - Description: Explainer on how conventions reach an agent: the hosted server's docs resources and search, per-package `.ai/guidelines/` shipped in npm tarballs (verify whether #802 Phase 2 shipped this before documenting it — if not, describe only what exists and note the rest as planned), `terreno_bootstrap_ai_rules` for generating editor-specific rule files, and the `.rulesync/` source-of-truth pattern with its generated targets. Add a section for consumers on extending the generated rules with their own project conventions without losing them on regeneration.
+  - Files: `docs/explanation/agent-guidelines.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: every mechanism described is verified present in the merged tree, with anything unshipped clearly labeled as planned; the consumer-extension section gives a concrete pattern.
+
+## Phase 4: Setup and debug how-tos
+
+- [ ] **Task 4.1**: Write `docs/how-to/set-up-terreno-mcp.md`
+  - Description: Per-editor setup for both Terreno servers. Cover at minimum Cursor (`.cursor/mcp.json`) and Claude Code, with the exact JSON for each including the hosted HTTP entry and the `bunx terreno-mcp-local` stdio entry. Then: what `terreno-mcp-local` needs to work (project root discovery and the `TERRENO_PROJECT_ROOT` override, a reachable `MONGO_URI`, the backend log file, Metro running for app logs); an optional section on adding `expo-mcp` and Playwright MCP with the division of labor from Task 3.1; and a verification section — ask the agent to call `application_info` and confirm it reports the project's `@terreno/*` versions. Compare the JSON against what `terreno_bootstrap_app` actually generates and make them identical.
+  - Files: `docs/how-to/set-up-terreno-mcp.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: configuration for at least two editors, each verified by actually loading it; the JSON matches bootstrap output byte-for-byte in structure; the `application_info` verification step works.
+
+- [ ] **Task 4.2**: Write `docs/how-to/debug-with-mcp.md`
+  - Description: Task-focused guide using the real failure and real outputs captured in Task 1.2. Structure: the symptom; `last_error` to locate it; `read_logs` with source filtering to see the surrounding context; `database_query` to check the data; `get_client_state` to check the client; `navigate` plus a screenshot from the composed server to confirm the fix. Include a "which tool for which symptom" table (app crashes on a screen; API returns 403; data looks wrong; screen renders empty; bundler fails). Use verbatim tool output.
+  - Files: `docs/how-to/debug-with-mcp.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 1.2, Task 4.1
+  - Acceptance: all tool outputs are verbatim from Task 1.2; the symptom-to-tool table has at least five rows; the walkthrough ends with a verified fix.
+
+- [ ] **Task 4.3**: Add discovery paths for the local server
+  - Description: Nothing currently tells a developer that `terreno-mcp-local` exists. Add links to `docs/how-to/set-up-terreno-mcp.md` from: the README's MCP section, `docs/README.md` quick links, `docs/tutorials/README.md`, and the `terreno://docs/overview` MCP resource. Also confirm `terreno_bootstrap_app` output includes a comment or README line pointing at the setup guide.
+  - Files: `README.md`, `docs/README.md`, `docs/tutorials/README.md`, `mcp-server/src/docs/resources/overview.md`, `mcp-server/src/docs/templates/bootstrap/**`
+  - Depends on: Task 4.1
+  - Acceptance: at least four discovery paths link the setup guide; bootstrap output references it; `bun run mcp:build` succeeds.
+
+## Phase 5: Gap fixes
+
+- [ ] **Task 5.1**: `[RTK]` Rename `get_rtk_state` to `get_client_state`
+  - Description: Per IP question AI1, rename the tool to `get_client_state` and extend it to detect either store type, returning a field identifying which layer it found (RTK Query cache versus syncdb store). Keep `get_rtk_state` registered as an alias whose description marks it deprecated and names the replacement. Update the tool description to explain what it returns for each layer. Add tests covering: syncdb store present, RTK store present, neither present, and the alias resolving to the same handler.
+  - Files: `mcp-server/src/local/tools/runtime.ts`, `mcp-server/src/local/localTools.ts`, tests under `mcp-server/src/local/`
+  - Depends on: Task 1.1, PR #869 merged
+  - Acceptance: both names work; the response identifies the detected layer; the alias description marks it deprecated; all four test cases pass; `bun run mcp:build` succeeds.
+
+- [ ] **Task 5.2**: `[RTK]` Relocate the dev console logger
+  - Description: Per IP question AI2, move `installTerrenoDevConsoleLogger` from `rtk/src/devConsoleLogger.ts` to the syncdb package, keeping a re-export from `@terreno/rtk` for the deprecation window so existing consumers are unaffected. Move its tests with it. Update the bootstrap `_layout` template and `example-frontend/app/_layout.tsx` to import from the new location. Add the re-export to the RTK deprecation notes.
+  - Files: `syncdb/src/devConsoleLogger.ts` (moved), `rtk/src/devConsoleLogger.ts` (re-export), `rtk/src/index.ts`, `syncdb/src/index.ts`, `mcp-server/src/docs/templates/bootstrap/frontend/app/_layout.template.tsx`, `example-frontend/app/_layout.tsx`, tests
+  - Depends on: Task 5.1
+  - Acceptance: both import paths work; tests pass from the new location; `bun run compile` succeeds across the workspace; the example app still ships browser logs to the backend route (verify by producing a `console.error` and reading it back with `read_logs`).
+
+- [ ] **Task 5.3**: Add rate limiting to the hosted MCP server
+  - Description: Per IP question AI5 — a launch prerequisite. Add per-IP rate limiting to the hosted server's JSON-RPC endpoint. Choose limits appropriate to the workload (search and codegen are cheap per call; the index is built once at startup) and make them configurable by environment variable with a sensible default. Return a clear JSON-RPC error when exceeded, naming the limit and the retry window. Add tests for under-limit, at-limit, and over-limit behavior. Document the limit in `docs/reference/mcp-server.md`.
+  - Files: `mcp-server/src/index.ts`, tests under `mcp-server/src/`, `docs/reference/mcp-server.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 2.1
+  - Acceptance: exceeding the limit returns a structured error naming the limit and retry window; the limit is configurable by environment variable; three test cases pass; the limit is documented.
+
+- [ ] **Task 5.4**: Handle the MCP domain change
+  - Description: If program question P4 / IP question AI6 was answered in favor of moving off `mcp.terreno.flourish.health`, update every occurrence of the URL: `README.md`, `docs/reference/mcp-server.md`, `mcp-server/README.md`, `mcp-server/src/**` defaults, bootstrap templates, and `infra/flourish/` deployment config. Keep the old hostname serving with a redirect or CNAME for at least one release and document the cutover. If the decision was to keep the current domain, make no change and record that.
+  - Files: various (grep `rg -n "mcp\.terreno"`)
+  - Depends on: Task 2.1
+  - Acceptance: `rg -n "mcp\.terreno\.flourish\.health"` returns only intentional legacy references; a bootstrapped app's `mcp.json` uses the new URL; the cutover plan is documented; or the no-change decision is recorded in the PR body.
+
+## Phase 6: Verification
+
+- [ ] **Task 6.1**: Run the loop end to end and capture evidence
+  - Description: In a fresh agent session with both MCP servers configured per `docs/how-to/set-up-terreno-mcp.md`, complete a full loop: ask for a small feature, let the agent generate it, run the app, introduce a bug, use `last_error` and `read_logs` to find it, fix it, and verify with `navigate` plus a screenshot. Capture the transcript highlights and screenshots to `/opt/cursor/artifacts/`. Fix any documentation gap the run exposed.
+  - Files: any documentation needing correction
+  - Depends on: Task 4.2, Task 5.1, Task 5.3
+  - Acceptance: the full loop completed in one session using only the public docs; artifacts captured showing the `last_error` output and the verified fix; every gap fixed.

package/dist/docs/versioned/next/tasks/build-terreno-app-validation.md

@@ -0,0 +1,121 @@
+# Task List: Dogfooding Run and Launch Blog Post
+
+See: [`docs/implementationPlans/build-terreno-app-validation.md`](../implementationPlans/build-terreno-app-validation.md)
+
+**RTK deprecation flag:** **Blocked.** The run must target syncdb + Better Auth. Do not start until PR #869 has merged and [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md), [`docs-reference-coverage`](docs-reference-coverage.md), and [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md) are complete — the run tests those documents, so running earlier tests nothing.
+
+## Instructions for the implementing agent
+
+- **The public-sources-only rule is the experiment.** Read the [`build-terreno-app`](../../.rulesync/skills/build-terreno-app/SKILL.md) skill and follow its restrictions exactly. Reading `.rulesync/`, `docs/implementationPlans/`, or Terreno source to unblock yourself invalidates the run. If you do it accidentally, say so in the friction log — a disclosed contamination is recoverable, a hidden one is not.
+- Work outside the Terreno monorepo. Fresh directory, fresh environment.
+- Log friction as it happens, with timestamps. Do not reconstruct the log at the end.
+- Do not fix Terreno during a run. Record the gap, work around it, keep going. Fixes happen between runs, in the owning IPs.
+- Never claim a step succeeded without evidence.
+
+## Phase 1: Run 1
+
+- [ ] **Task 1.1**: Confirm the concept and prerequisites
+  - Description: Confirm which app concept to build (IP question B1 — **Pantry**). Record the environment: OS, Bun version, editor and agent model with version (required per IP question B6), installed Terreno version, and the resolved stack mode. Confirm the stack mode is syncdb + Better Auth; if it is not, stop — the run is premature.
+  - Files: `FRICTION_LOG.md` in the working directory (outside this repo)
+  - Depends on: PR #869 merged; the three prerequisite IPs complete
+  - Acceptance: the log header is complete including the agent model and version; the stack mode is confirmed as syncdb + Better Auth; the working directory is outside the Terreno monorepo.
+
+- [ ] **Task 1.2**: Execute run 1
+  - Description: Run the `build-terreno-app` skill through all seven of its phases: learn the framework as a newcomer, scaffold, build the slices in the concept's order, exercise the six differentiators, use the AI debug loop on a deliberate bug, deploy, and report. Log every gap with severity, phase, what was missing, the workaround, and a suggested fix. Capture the required artifacts as you go rather than at the end.
+  - Files: `FRICTION_LOG.md`, the demo app source, artifacts in `/opt/cursor/artifacts/`
+  - Depends on: Task 1.1
+  - Acceptance: all seven skill phases attempted; every gap logged with all five fields; the artifact checklist from the blog outline is complete or each missing item has a logged reason.
+
+- [ ] **Task 1.3**: Record the debug-loop measurement
+  - Description: The deliberate bug in skill phase 5 is the most important single measurement in this IP. Record: the bug introduced, the symptom observed, which tools were called in what order, the elapsed time from symptom to fix, and — critically — whether framework source had to be read or print statements added. Quote the `last_error` output verbatim.
+  - Files: `FRICTION_LOG.md`
+  - Depends on: Task 1.2
+  - Acceptance: elapsed time recorded; the tool call sequence recorded; the source-reading question answered explicitly yes or no; `last_error` output quoted verbatim.
+
+## Phase 2: Triage
+
+- [ ] **Task 2.1**: Classify and route every gap
+  - Description: For each gap in the run 1 log, assign a severity (blocking / major / minor) and route it to the owning IP using the routing table in the IP. Produce a triage table: gap, severity, owning IP, proposed issue title, proposed labels. Flag any gap that does not fit an existing IP — it may indicate a missing IP.
+  - Files: `FRICTION_LOG.md`, a triage section in the run report
+  - Depends on: Task 1.3
+  - Acceptance: every gap has a severity and an owning IP or is flagged as unrouted; the routing matches the IP's table; unrouted gaps are called out with a recommendation.
+
+- [ ] **Task 2.2**: Prepare the issue set
+  - Description: Write ready-to-file issue bodies for every blocking and major gap, following the repo's issue-form fields from [`oss-governance-baseline`](../implementationPlans/oss-governance-baseline.md). Each must be understandable by someone who did not do the run: the expected behavior, what actually happened, the exact step in the exact document, and the suggested fix. Do not file them unless explicitly asked — list them for a maintainer.
+  - Files: a section in the run report
+  - Depends on: Task 2.1
+  - Acceptance: one issue body per blocking and major gap; each names the specific document and step; each is comprehensible without the friction log.
+
+- [ ] **Task 2.3**: Update the owning IPs' task lists
+  - Description: For each routed gap, add a task to the owning IP's task file in `docs/tasks/` describing the fix, referencing the run's finding. This is the only writing this IP does inside the Terreno repo during the fix cycle — the fixes themselves belong to the owning IPs.
+  - Files: `docs/tasks/*.md` for the owning IPs
+  - Depends on: Task 2.2
+  - Acceptance: every blocking and major gap has a corresponding task in an owning IP's task file; each new task cites the run finding.
+
+## Phase 3: Fix cycle
+
+- [ ] **Task 3.1**: Track fix completion
+  - Description: Wait for the owning IPs to land the fixes. Maintain a tracking table in the run report: gap, owning IP, fix status, PR link. Do not perform the fixes here — doing so scatters ownership and means the fix is not covered by the owning IP's acceptance criteria.
+  - Files: the run report
+  - Depends on: Task 2.3
+  - Acceptance: every blocking and major gap shows a landed fix with a PR link, or an explicit decision to accept it with reasoning.
+
+## Phase 4: Run 2
+
+- [ ] **Task 4.1**: Execute run 2 in a fresh environment
+  - Description: Repeat Task 1.2 in a genuinely fresh session and environment — no cached dependencies, no carried-over context, ideally a different agent session with no memory of run 1. Build the same concept so the runs are comparable. Produce a second independent friction log.
+  - Files: `FRICTION_LOG_2.md`, the demo app source, artifacts
+  - Depends on: Task 3.1
+  - Acceptance: run 2 was performed in a fresh environment with no carried context; the same concept was built; a second complete friction log exists.
+
+- [ ] **Task 4.2**: Repeat-gap analysis
+  - Description: Compare both logs. Produce three lists: gaps fixed (present in run 1, absent in run 2), gaps that survived (present in both — for each, explain why the fix did not work), and new gaps (only in run 2, which often means a fix introduced a problem). Report the total counts by severity for each run.
+  - Files: a comparison section in the run report
+  - Depends on: Task 4.1
+  - Acceptance: all three lists produced; every surviving gap has an explanation; severity counts for both runs are stated.
+
+- [ ] **Task 4.3**: Evaluate the launch gate
+  - Description: Check run 2 against the pass thresholds in the IP: zero blocking gaps, zero major gaps, every concept slice working on web and one native target, all six differentiators with artifacts, deployment with all four checks passing, and the debug loop completed without reading framework source. State pass or fail per gate. If any gate fails, return to Phase 3 — do not proceed to the blog post.
+  - Files: the run report
+  - Depends on: Task 4.2
+  - Acceptance: every gate has an explicit pass or fail with evidence; a failure sends the work back to Phase 3 rather than proceeding.
+
+## Phase 5: Blog post
+
+- [ ] **Task 5.1**: Draft the post
+  - Description: Write `BLOG_DRAFT.md` following the nine-section outline in the skill's blog reference. Use real elapsed times, real code from the built app, and real artifacts. The "what did not work" section takes the three most instructive gaps from the logs — pick genuinely instructive ones, not three trivial gaps chosen to look candid. Name the agent model and version. Include the debug-loop measurement from Task 1.3 (and its run 2 equivalent) as a concrete number.
+  - Files: `BLOG_DRAFT.md`
+  - Depends on: Task 4.3
+  - Acceptance: all nine sections present; 1,800–2,500 words; every superlative quantified; three real gaps in the "what did not work" section with their fixes and PR links; the model and version named.
+
+- [ ] **Task 5.2**: Artifact and fact review
+  - Description: Have someone who did not perform the run verify every claim in the draft against an artifact. Produce a checklist: claim, backing artifact, verified yes/no. Remove or correct any claim without backing. Also verify no claim describes an unshipped feature by checking each against the public docs.
+  - Files: `BLOG_DRAFT.md`, a review checklist
+  - Depends on: Task 5.1
+  - Acceptance: every claim has a verified backing artifact; the reviewer is not the person who did the build; no claim references an unshipped feature.
+
+- [ ] **Task 5.3**: Publish the demo app repository
+  - Description: Per IP question B2, publish the demo app to its own repository with a README stating what it is, which Terreno version it was built against, that it is a blog-post artifact rather than a maintained example, and a link to the post. Include the app's own setup instructions so a reader can run it. Do not add it to the Terreno monorepo.
+  - Files: a new repository (outside this repo)
+  - Depends on: Task 5.2
+  - Acceptance: the repository is public with a complete README; the app runs from a fresh clone following its README; the unmaintained status is stated; it is not added to the monorepo.
+
+- [ ] **Task 5.4**: Publish the dogfooding results
+  - Description: Create `docs/explanation/dogfooding-results.md` in the Terreno repo summarizing both runs publicly: what was tested, gap counts by severity per run, what changed between them, and what remains known-imperfect. This is the durable, honest artifact — the blog post is marketing that happens to be true, this is the engineering record. Link it from `CONTRIBUTING.md` as evidence of how the project evaluates its own developer experience.
+  - Files: `docs/explanation/dogfooding-results.md` (new), `docs/explanation/README.md`, `CONTRIBUTING.md`
+  - Depends on: Task 4.2
+  - Acceptance: both runs' counts published; remaining known gaps listed rather than omitted; linked from the explanation index and `CONTRIBUTING.md`.
+
+## Phase 6: Retrospective
+
+- [ ] **Task 6.1**: Improve the harness
+  - Description: Record what the `build-terreno-app` skill itself got wrong: steps that were ambiguous, phases that were mis-scoped, artifacts that turned out not to be worth capturing, and measurements that should have been taken but were not. Update the skill and its references, then regenerate mirrors with `bun run rules`.
+  - Files: `.rulesync/skills/build-terreno-app/SKILL.md`, `.rulesync/skills/build-terreno-app/references/*`, generated mirrors
+  - Depends on: Task 4.2
+  - Acceptance: at least three concrete skill improvements landed from real experience; `bun run rules:check` exits 0.
+
+- [ ] **Task 6.2**: Recommend a cadence
+  - Description: Based on the actual effort of both runs, recommend how often this should be repeated and what triggers an unscheduled run (a major version, a data-layer change, a docs restructure). Add the recommendation to `docs/explanation/dogfooding-results.md`. Do not create a recurring commitment the team cannot keep — an abandoned cadence is worse than no cadence.
+  - Files: `docs/explanation/dogfooding-results.md`
+  - Depends on: Task 6.1
+  - Acceptance: the recommendation states an interval and the unscheduled triggers, and is justified by the measured effort of the two runs.

package/dist/docs/versioned/next/tasks/deploy-to-gcp.md

@@ -0,0 +1,99 @@
+# Task List: Deploy to GCP (Generalized) + `deploy-gcp` Skill
+
+See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy-to-gcp.md)
+
+**RTK deprecation flag:** None. The only client-side surface is `EXPO_PUBLIC_API_URL`, which is unchanged by PR #869. Safe to implement before #869 merges.
+
+## Instructions for the implementing agent
+
+- Use placeholder variables in all documentation: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$WEB_BUCKET`, `$UPLOADS_BUCKET`. Never hardcode a real project ID, bucket, or URL.
+- Grep for `flourish` in every file you write or edit before committing: `rg -i flourish <file>`. The only permitted matches are inside `infra/flourish/`.
+- Do **not** run `gcloud` commands that create or modify resources unless the user has explicitly named a target project in the request.
+- Verify every `gcloud` flag you document against `gcloud run deploy --help` before writing it. Do not guess flag names.
+- Run `bun run lint` before each commit; run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Generalize the how-to guides
+
+- [ ] **Task 1.1**: Write `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Description: New guide covering: prerequisites (gcloud installed and authenticated, billing enabled, required APIs — `run`, `artifactregistry`, `secretmanager`, `compute`); creating an Artifact Registry repo; building and pushing the backend image; creating Secret Manager secrets for `MONGO_URI`, `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, and `BETTER_AUTH_SECRET`; creating the runtime service account with least-privilege roles; the `gcloud run deploy` invocation with `--session-affinity`, `--timeout`, `--min-instances`, `--set-secrets`, and `--set-env-vars`; and verification via `curl $SERVICE_URL/health`. Use placeholder variables throughout. Read `example-backend/src/server.ts` and `docs/reference/environment-variables.md` to get the env var list right — do not copy it from this task description without checking.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md` (new)
+  - Depends on: none
+  - Acceptance: `rg -i flourish docs/how-to/deploy-backend-to-cloud-run.md` returns nothing; every env var named exists in `docs/reference/environment-variables.md` or the backend source; every `gcloud` flag used appears in `gcloud run deploy --help`.
+
+- [ ] **Task 1.2**: Add the production constraints section
+  - Description: Add a "Production constraints" section to the backend guide as a symptom → cause → fix table covering at minimum: (a) websockets disconnect every few requests → no session affinity → add `--session-affinity`; (b) long-lived socket connections drop at 5 minutes → default request timeout → raise `--timeout`; (c) realtime and live feature flags stop working → MongoDB is not a replica set → use Atlas or a replica set, because change streams require one; (d) first request after idle is slow and sockets churn → scaled to zero → `--min-instances=1`; (e) browser requests fail CORS → `corsOrigin` in `setupServer` and Better Auth `trustedOrigins` do not include the web origin. Verify claim (c) against `feature-flags` live-update code before writing it.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Depends on: Task 1.1
+  - Acceptance: all five rows present with a concrete symptom; the change-streams claim is verified against the source and the source path is cited in the guide.
+
+- [ ] **Task 1.3**: Write `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Description: New guide covering: building the web bundle (`bunx expo export -p web` — confirm the exact command against `example-frontend/package.json` scripts), the requirement to set `EXPO_PUBLIC_API_URL` at build time because it is inlined into the bundle, creating and configuring the GCS bucket with public read and `notFoundPage=index.html` for client-side routing, the five CDN resources (backend bucket, URL map, static IP, HTTP(S) proxy, forwarding rule), pointing DNS at the IP, and cache invalidation after each deploy. Include a note that this is a static-only path and link [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md) for the SSR future.
+  - Files: `docs/how-to/deploy-web-to-gcs-cdn.md` (new)
+  - Depends on: none
+  - Acceptance: no Flourish strings; the export command matches an actual script in `example-frontend/package.json`; the guide explains why `EXPO_PUBLIC_API_URL` must be set before building, not after.
+
+- [ ] **Task 1.4**: Write the architecture explainer
+  - Description: Create `docs/explanation/deployment-architecture-gcp.md` explaining the reference topology (reuse the mermaid diagram from the IP), what each component is responsible for, why Cloud Run rather than App Engine or GKE, why Atlas rather than self-hosted Mongo, and the tradeoffs of static web hosting versus a server-rendered deployment. Keep it conceptual — no commands.
+  - Files: `docs/explanation/deployment-architecture-gcp.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: contains the topology diagram; contains no shell commands; explains at least three explicit tradeoffs.
+
+- [ ] **Task 1.5**: Rewire the existing GCP how-to and index
+  - Description: Replace `docs/how-to/deploy-to-gcp.md` with a short index page linking the two new guides and the explainer, preserving the old anchor names where practical so existing links do not break. Update `docs/how-to/README.md` to list the new guides. Check `website/` for any hardcoded reference to the old page path and update it.
+  - Files: `docs/how-to/deploy-to-gcp.md`, `docs/how-to/README.md`, `website/` (as needed)
+  - Depends on: Task 1.1, Task 1.3, Task 1.4
+  - Acceptance: `bun run website:build` succeeds with no new broken-link warnings introduced by this change.
+
+## Phase 2: Terraform module and Flourish separation
+
+- [ ] **Task 2.1**: Extract the generic backend module
+  - Description: Create `terraform/modules/terreno-backend/` with `main.tf`, `variables.tf`, `outputs.tf`, and `README.md`. Resources: Artifact Registry repository, Cloud Run v2 service (session affinity, timeout, min/max instances, secret env refs), Secret Manager secrets (created empty, values supplied out-of-band), runtime service account with `secretmanager.secretAccessor` and object admin on a supplied uploads bucket, and optional Workload Identity Federation pool for CI. Every value that could differ between users must be a variable with a description and no Flourish default. Outputs: service URL, service account email, registry path.
+  - Files: `terraform/modules/terreno-backend/main.tf`, `variables.tf`, `outputs.tf`, `README.md` (all new)
+  - Depends on: Task 1.1
+  - Acceptance: `terraform init && terraform validate` passes in the module directory; `rg -i flourish terraform/modules/` returns nothing; every variable has a `description`.
+
+- [ ] **Task 2.2**: Relocate Flourish-specific terraform
+  - Description: Move Flourish's environment configuration from `terraform/` to `infra/flourish/`, leaving only `terraform/modules/` behind. Update every path reference: `.github/workflows/cd.yml`, `terraform/README.md` (split into a generic module README and `infra/flourish/README.md`), `AGENTS.md` / `CLAUDE.md` if they reference `terraform/README.md`, and any script under `scripts/`. Use `git mv` so history is preserved.
+  - Files: `infra/flourish/**` (moved), `terraform/README.md`, `.github/workflows/cd.yml`, `AGENTS.md`, `CLAUDE.md`, `scripts/**`
+  - Depends on: Task 2.1
+  - Acceptance: `rg -n "terraform/" --glob '!infra/**' --glob '!terraform/**'` shows no stale paths pointing at moved files; the `cd.yml` workflow references the new location; `bun run rules:check` exits 0 after regenerating rules.
+
+- [ ] **Task 2.3**: Parameterize the GCS hosting script
+  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, and `--bucket` arguments (or positional equivalents) with a usage message and a check that all are present. Remove every hardcoded Flourish project, bucket, and service-account value. Keep the resource-creation logic intact. Add a `--dry-run` flag that prints commands without executing them.
+  - Files: `scripts/setup-gcs-hosting.sh`
+  - Depends on: Task 1.3
+  - Acceptance: running with no arguments prints usage and exits non-zero; `--dry-run` produces commands containing the supplied values and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
+
+## Phase 3: The `deploy-gcp` skill
+
+- [ ] **Task 3.1**: Author the skill
+  - Description: Create `.rulesync/skills/deploy-gcp/SKILL.md` with frontmatter (`name: deploy-gcp`, a `description` that names the trigger phrases "deploy to GCP", "deploy to Cloud Run", "ship the backend", and `targets: ['*']`). Body sections in this order: When to use / When not to use; Preflight checks (project layout detection, `gcloud config get-value project`, required APIs, replica-set verification of `MONGO_URI`); **Plan and confirm** — print target project, region, service name, and every resource to be created or updated, then stop and require explicit user confirmation before any mutating command; Backend deploy steps; Frontend deploy steps; Verification (`curl $SERVICE_URL/health` expecting `"healthy":true`, fetch web root); Troubleshooting (link the reference file). Include an explicit prohibition: never deploy to a project the user did not name in the request, and never create or modify secrets without echoing which secret names will change.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: frontmatter has `name`, `description`, and `targets`; the confirmation gate appears before the first mutating command; every command in the skill also appears in the how-to guides (no skill-only knowledge).
+
+- [ ] **Task 3.2**: Add the troubleshooting reference
+  - Description: Create `.rulesync/skills/deploy-gcp/references/troubleshooting.md` containing the symptom → cause → fix table from Task 1.2 plus deploy-time failures: image push permission denied, secret access denied at cold start, Cloud Run revision failing health checks because `PORT` is not read from the environment, and CDN serving a stale bundle after deploy. For each, give the exact log line or error message the user will see.
+  - Files: `.rulesync/skills/deploy-gcp/references/troubleshooting.md` (new)
+  - Depends on: Task 3.1
+  - Acceptance: at least nine rows; each row quotes an actual error string rather than paraphrasing.
+
+- [ ] **Task 3.3**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit every generated file under `.cursor/skills/`, `.claude/skills/`, `.devin/skills/`, `.github/skills/`, and `.agents/skills/`. Do not hand-edit generated files.
+  - Files: generated skill mirrors
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: `bun run rules:check` exits 0; `deploy-gcp` appears under each configured target directory.
+
+## Phase 4: Validation
+
+- [ ] **Task 4.1**: Dry-run the guide end to end
+  - Description: Following **only** `docs/how-to/deploy-backend-to-cloud-run.md` and `docs/how-to/deploy-web-to-gcs-cdn.md` (no internal knowledge, no `infra/flourish/`), deploy `example-backend` and `example-frontend` to a scratch GCP project. Record every point where the guide was wrong, incomplete, or required outside knowledge. Fix the guides. Capture the successful `curl $SERVICE_URL/health` output and the loaded web app as artifacts under `/opt/cursor/artifacts/`.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`, `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Depends on: Task 1.1, Task 1.3, Task 2.3
+  - Acceptance: the deploy succeeds; `/health` returns `"healthy":true`; the web app loads and can log in against the deployed backend; every guide correction is committed.
+
+- [ ] **Task 4.2**: Exercise the skill against the validated guide
+  - Description: Run the `deploy-gcp` skill in a fresh agent session against the same scratch project and confirm it reaches the same result, including the confirmation gate firing before any mutation. Note any step where the skill needed information the guide did not provide and fix the skill.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` plus mirrors
+  - Depends on: Task 3.3, Task 4.1
+  - Acceptance: the skill run produces a working deploy; the confirmation gate is observed in the transcript; `bun run rules:check` exits 0 after any skill edits.