@terreno/mcp 57.18.0 → 57.19.2

package/src/docs/versioned/57.18.0/implementationPlans/deployment-foundation.md

@@ -0,0 +1,133 @@
+# Implementation Plan: Deployment Foundation
+
+**Status:** Complete — blocking questions resolved 2026-07-29; all tasks executed
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1011
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** none (soft: [`docs-reference-coverage`](docs-reference-coverage.md) for the env var reference page)
+**RTK deprecation flag:** **Partial** — the client environment-variable section and the web build output depend on the frontend data layer. Tasks touching client env vars and Better Auth origins are `[RTK]` marked.
+
+## Goal
+
+Establish the provider-agnostic layer that every deployment guide needs, so [`deploy-to-vercel`](deploy-to-vercel.md) and [`deploy-to-gcp`](deploy-to-gcp.md) can be short and specific instead of each re-explaining the same eight concepts. Right now there is no canonical answer to "what does a Terreno app need in order to run in production?" — the environment variables are spread across `docs/reference/environment-variables.md`, `AGENTS.md`, package rules, and several `.env.example` files; there is no backend Dockerfile in the repo for consumers to copy; and nothing explains the choice between Expo's three web output modes.
+
+## Non-Goals
+
+- Provider-specific instructions (separate IPs per provider).
+- Implementing SSR (that is [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md); this IP only documents that `single` is today's default and what the alternatives mean).
+- CI/CD pipeline templates for consumers.
+- Monitoring, alerting, or log aggregation setup.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| DF1 | Reference backend `Dockerfile`? | **A** — canonical `example-backend/Dockerfile`; docs reference it |
+| DF2 | Base image | **A** — `oven/bun:1-slim` |
+| DF3 | Default web output mode | **A** — `single` (SPA) today + decision table for `static` / `server` |
+| DF4 | Health endpoint required? | **A** — require `@terreno/api-health` |
+| DF5 | Staging environment | **B** — short two-environment section |
+| DF6 | File uploads default | **C** — document GCS; verify backends before writing |
+
+## Architecture
+
+### The deployment baseline
+
+Every Terreno production deployment needs these seven things. The foundation doc names them once; provider guides map them to provider primitives.
+
+| # | Requirement | Why | Where it is configured |
+|---|-------------|-----|------------------------|
+| 1 | MongoDB **replica set** | Change streams power realtime and live feature flags; a standalone server fails at startup | `MONGO_URI` |
+| 2 | Auth secrets | JWT signing and sessions | `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`; Better Auth adds `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` |
+| 3 | A long-lived process for the backend | Socket.io connections; not compatible with short-timeout serverless | Provider service config |
+| 4 | Correct origins | CORS (`corsOrigin`) plus Better Auth `trustedOrigins` including native deep-link schemes | Backend config |
+| 5 | Build-time client config | `EXPO_PUBLIC_API_URL` is inlined into the web bundle at build time; it cannot be changed after the fact | Web build environment |
+| 6 | A health endpoint | Readiness and liveness probes | `@terreno/api-health` |
+| 7 | File storage | Uploads must not live on ephemeral container disk | GCS bucket + credentials |
+
+Requirements 1, 3, and 5 are the ones people get wrong. Each needs its failure symptom documented, not just the rule.
+
+### Web output modes
+
+Expo Router offers three, and the choice determines what hosting works:
+
+| Mode | Output | API routes | SSR | Hosting | Status in Terreno |
+|------|--------|-----------|-----|---------|-------------------|
+| `single` | one `index.html` SPA | no | no | any static host | **current default** |
+| `static` | per-route HTML | no | no | any static host | usable now; better SEO |
+| `server` | `dist/client` + `dist/server` | yes | yes (alpha, SDK ≥ 55) | needs a Node/Bun/edge runtime | not yet — see the SSR IP |
+
+The repo is currently on Expo `~54.0.29` (root `package.json` catalog), so `server` output with SSR requires the SDK upgrade tracked in PR [#779](https://github.com/TerrenoLabs/terreno/pull/779). The foundation doc must state this rather than implying SSR is available.
+
+### Backend container
+
+A multi-stage Bun build that works for a monorepo consumer *and* for the repo's own `example-backend`:
+
+1. Stage 1: install with the lockfile, compile workspace packages.
+2. Stage 2: copy the built output, run as a non-root user, read `PORT` from the environment (platforms assign it), expose the health endpoint.
+
+The critical detail platforms trip on: the server must bind `0.0.0.0` and read `PORT` from the environment rather than hardcoding 4000. Verify how `example-backend` currently resolves its port before writing the Dockerfile.
+
+### Environment variable reference
+
+`docs/reference/environment-variables.md` exists but must become the single source of truth: every variable, which package reads it, required or optional, default, whether it is a secret, and whether it is build-time (client) or runtime (server). The build-time/runtime distinction is the one that causes production incidents, because `EXPO_PUBLIC_*` values are baked into the bundle.
+
+## Models / APIs / Notifications / UI
+
+None.
+
+## Phases
+
+1. **Environment variable reference** — audit every variable in every package and complete the reference table.
+2. **Deployment baseline explainer** — the seven requirements, the output-mode table, environment differences.
+3. **Backend container** — `example-backend/Dockerfile`, a `.dockerignore`, and a CI job that builds it.
+4. **Web build documentation** — how to build for web, build-time config, the output-mode decision.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- Consumer CI/CD templates.
+- Monitoring, tracing, and log aggregation guidance (Sentry is already wired; a production-observability guide is a good follow-up).
+- Blue/green or canary deployment patterns.
+- Database backup and restore procedures.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/explanation/deployment-baseline.md`
+- `docs/how-to/build-for-web.md`
+- `example-backend/Dockerfile`, `example-backend/.dockerignore`
+- `.github/workflows/example-backend-docker.yml`
+
+**Modify**
+
+- `docs/reference/environment-variables.md`
+- `docs/how-to/README.md`, `docs/explanation/README.md`
+- `example-backend/.env.example`, `example-frontend/.env.example`
+- `example-backend/src/server.ts` (only if it does not already read `PORT` and bind `0.0.0.0`)
+
+## Task List
+
+See [`docs/tasks/deployment-foundation.md`](../tasks/deployment-foundation.md).
+
+## Acceptance Criteria
+
+- [ ] `docs/reference/environment-variables.md` lists every environment variable read anywhere in the repo, with reading package, required/optional, default, secret flag, and build-time versus runtime.
+- [ ] A grep for `process.env.` and `EXPO_PUBLIC_` across all packages finds no variable absent from the reference.
+- [ ] `docs/explanation/deployment-baseline.md` documents all seven baseline requirements, each with the symptom that occurs when it is missed.
+- [ ] The web output-mode table states Terreno's current default and that `server` output requires Expo SDK ≥ 55.
+- [ ] `example-backend/Dockerfile` builds successfully and the container serves `/health` returning `"healthy":true` against an external MongoDB.
+- [ ] The container reads `PORT` from the environment and binds `0.0.0.0`, verified by running it with `PORT=9999`.
+- [ ] The container runs as a non-root user.
+- [ ] A CI job builds the Docker image on changes to `example-backend/` or `api/`.
+- [ ] `docs/how-to/build-for-web.md` explains that `EXPO_PUBLIC_API_URL` is inlined at build time and shows the symptom when it is set only at runtime.
+- [ ] Both `.env.example` files contain every required variable with safe placeholder values and no real secrets.

package/src/docs/versioned/57.18.0/implementationPlans/describe-model-schema.md

@@ -0,0 +1,124 @@
+# `describeModel()` schema metadata
+
+**Status:** Complete — shipped in #1154  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [api.md](../reference/api.md) OpenAPI / model conventions, [create-a-model.md](../how-to/create-a-model.md), [pluggable-database-sqlite.md](pluggable-database-sqlite.md) (adapters need shared path metadata; this is that core, not a second DSL)  
+**Task list:** [describe-model-schema.md](../tasks/describe-model-schema.md)  
+**Depends on:** none (can parallel unified-mutation-executors)  
+**Consumed by:** OpenAPI (`getOpenApiSpecForModel`), admin `extractFieldMeta`, MCP `schemaGenerator`
+
+## Goal
+
+Walk each Mongoose schema **once**. OpenAPI, admin field widgets, and MCP Zod tools consume a `ModelDescription` instead of each re-interpreting `schema.paths` / mongoose-to-swagger / OpenAPI `$ref` hacks.
+
+Evidence: `api/src/populate.ts` `getOpenApiSpecForModel` uses mongoose-to-swagger; `admin-backend/src/adminApp.ts` `extractFieldMeta` (~469) walks OpenAPI properties; `api/src/mcp/schemaGenerator.ts` walks `schema.paths` into Zod. `AdminFieldMeta` (backend) and `AdminFieldConfig` (frontend) duplicate shapes.
+
+## Non-Goals
+
+- Replacing Mongoose as the authoring format (SQLite IP D1).
+- Generating TypeScript document types (five-type pattern stays hand-written).
+- Unifying admin frontend/backend **component** trees; only the **field descriptor** they share.
+- MCP operator-hint copy and OpenAPI prose beyond field facts.
+- Widget registry / admin screen router ([admin-improvements.md](admin-improvements.md) owns AdminApp carve-up).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — `describeModel(model, {populatePaths?, extraProperties?}) → ModelDescription`.** Surfaces format that graph. Not B (OpenAPI JSON as the canonical model) — OpenAPI drops refs/widget hints MCP and admin need; it is a **view**. |
+| Field graph | Paths with `kind`, `required`, `description`, `enum`, `ref`, `isArray`, `item` (nested description or primitive kind), `system` (created/updated/deleted/_id/__v). |
+| Write exclusions | `writableOnCreate` / `writableOnUpdate` derived from the same rules MCP `SYSTEM_FIELDS` + router `validation` / field views **when those options are passed in**. `describeModel` on the model alone does not know field views; `describeModelForRouter(model, options)` adds write masks. Two functions, one module. |
+| OpenAPI | `getOpenApiSpecForModel` builds swagger **from** `ModelDescription` (or merges m2s output with description for populate — Phase 2 may keep m2s for compatibility then replace). Compatibility: existing OpenAPI snapshots in `example-backend` / api tests must stay equal or have an explicit, reviewed diff. |
+| Admin | `extractFieldMeta` maps `ModelDescription` (+ OpenAPI only if still required for nested quirks). Prefer description → `AdminFieldMeta` directly. |
+| MCP | `mongooseTypeToZod` maps `FieldDescription`, not raw SchemaType. |
+| Compatibility | Public OpenAPI HTTP body stable. Admin `/admin/config` field types stable unless a bugfix is documented. |
+
+## Interface shapes considered
+
+**A (chosen).** Canonical graph in `@terreno/api`, adapters in OpenAPI/admin/MCP.
+
+**B (rejected).** Canonical OpenAPI document. Admin already loses `ref` (see `format === "objectid"` comment in `extractFieldMeta`). MCP would parse OpenAPI into Zod — another shallow wrapper.
+
+## Architecture
+
+```
+Mongoose schema.paths
+        │
+        ▼
+describeModel / describeModelForRouter
+        │
+        ├──► getOpenApiSpecForModel (components, populate)
+        ├──► Admin extractFieldMeta /config
+        └──► MCP Zod tool schemas
+```
+
+Deletion test: deleting `extractFieldMeta`’s OpenAPI walk and MCP’s SchemaType switch **into** `describeModel` concentrates “what is this field?”. Splitting `adminApp.ts` without this only moves the walk.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/explanation/` new short page `schema-metadata.md` | Why one descriptor; OpenAPI/admin/MCP are views. |
+| `docs/reference/api.md` | `describeModel` export, field kinds table. |
+| `docs/how-to/create-a-model.md` | Field `description` still required; it feeds the descriptor. |
+| Admin reference | Config fields come from `describeModel`, not a second OpenAPI parse. |
+
+## Testing
+
+Seam: `describeModel` snapshots for a fixture model (string, enum, bool, date, ObjectId ref, array of primitives, subdocument array, Mixed).
+
+Surface tests:
+
+- OpenAPI: existing `openApi.test.ts` / example-backend snapshot — update only with reviewed diffs.
+- MCP: tool schema tests compare Zod shape to descriptor, not SchemaType.
+- Admin: `extractFieldMeta` tests (or new) for ref + enum + required.
+
+No mongoose-schema-safety schema **changes**; this reads schemas.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| OpenAPI snapshot churn | Phase 1: descriptor + tests; Phase 2: OpenAPI switches with snapshot review as its own task. |
+| Mixed / virtuals / populate | Populate stays a `getOpenApiSpecForModel` concern using `populatePaths`; descriptor records `ref` on the local path only. |
+| Admin widget heuristics | Keep widget choice in admin; descriptor supplies type/enum/ref only. |
+
+## Phases
+
+1. `describeModel` + snapshots; MCP Zod uses it (highest drift vs SchemaType).
+2. Admin `extractFieldMeta` uses it.
+3. OpenAPI uses it; delete duplicate walks; docs.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- SQLite adapter reading `ModelDescription` for DDL ([pluggable-database-sqlite.md](pluggable-database-sqlite.md) follow-on).
+- Generating admin `AdminFieldConfig` types from the same module published to the frontend (shared type package later).
+
+## Files to Create / Modify
+
+- `api/src/schemaMetadata.ts` (new)
+- `api/src/schemaMetadata.test.ts`
+- `api/src/mcp/schemaGenerator.ts`
+- `api/src/populate.ts` (`getOpenApiSpecForModel`)
+- `admin-backend/src/adminApp.ts` (`extractFieldMeta`)
+- `api/src/index.ts` export
+- Docs listed above
+
+## Acceptance Criteria
+
+- [ ] One module describes paths; MCP, admin, and OpenAPI do not walk `schema.paths` independently.
+- [ ] Fixture snapshot covers enum, ref, array, subdocument, system fields.
+- [ ] OpenAPI compatibility tests pass (or reviewed snapshot update).
+- [ ] Admin config still exposes type, required, enum, ref, description.
+- [ ] MCP create tool schemas still hide system fields.
+- [ ] Docs explain the descriptor; `update-docs` pages listed above.
+
+## Task List
+
+[docs/tasks/describe-model-schema.md](../tasks/describe-model-schema.md)

package/src/docs/versioned/57.18.0/implementationPlans/design-blend-skill.md

@@ -0,0 +1,191 @@
+# Implementation Plan: design-blend Skill
+
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1083  
+**Status:** Complete
+
+## Goal
+
+Create a new `design-blend` skill that converts a Claude design file into a Terreno implementation blueprint and execution steps, with these hard constraints:
+
+1. REST-first APIs via `modelRouter` CRUD by default.
+2. Model actions only when REST is a poor fit (command, aggregation, or performance path).
+3. Maximum reuse of existing `@terreno/ui` components.
+4. New UI components only when the design cannot be expressed with existing Terreno primitives/components.
+5. Two-stage flow in the skill: (a) plan with task list, then (b) implementation using a subagent with per-task plan comparison.
+
+## Scope
+
+- Add canonical skill definition at `.rulesync/skills/design-blend/SKILL.md`.
+- Preserve planning artifacts:
+  - `docs/implementationPlans/design-blend-skill.md` (this file)
+  - `docs/tasks/design-blend-skill.md` (bot task list)
+- Sync generated mirrors for all configured `rulesync` targets.
+
+## Required Outputs Enforced by the Skill (Contract)
+
+The `design-blend` skill must require the following explicit outputs whenever it is used.
+
+### 1) Models Output (Required)
+
+For every entity inferred from the design, output a model spec with:
+
+- `modelName`
+- `fields` (name, type, required, default, description)
+- `relations` (`ref`, cardinality)
+- `indexes`
+- `plugins`
+- `ownership/multitenancy` notes (`ownerId`, tenant key, soft delete)
+
+Required format in skill output:
+
+1. A "Model Inventory" table.
+2. A per-model schema checklist.
+3. A "No model needed" rationale when a design section is purely presentational.
+
+### 2) modelRouter REST Output (Required)
+
+For each model, output a modelRouter plan with:
+
+- Route base path (for example `/orders`)
+- CRUD endpoints:
+  - `POST /resource`
+  - `GET /resource`
+  - `GET /resource/:id`
+  - `PATCH /resource/:id`
+  - `DELETE /resource/:id` (or explicit disable rationale)
+- `permissions` per method
+- `queryFields`
+- `queryFilter` (ownership/tenant filter when relevant)
+- `sort`
+- `populatePaths` where needed
+
+Required format in skill output:
+
+1. "REST Endpoint Matrix" (method/path/permission/purpose).
+2. "modelRouter Options Block" for each model.
+3. Explicit statement if any CRUD endpoint is disabled and why.
+
+### 3) Model Actions Output (Conditional, Strictly Gated)
+
+Actions are allowed only if one of these is true:
+
+1. Non-resource command semantics (`publish`, `approve`, `submit`, `duplicate`).
+2. Aggregation/read-model endpoint where CRUD cannot express required shape efficiently.
+3. Performance-motivated path (batch operation or optimized read route) with measurable benefit.
+
+For each action, require:
+
+- `actionName`
+- `method` + `path`
+- `whyRestIsInsufficient` (mandatory)
+- `requestSchema` + `responseSchema`
+- `permissions`
+- `performanceNote` (mandatory if performance-motivated)
+
+Required format in skill output:
+
+1. "Action Decision Gate" checklist.
+2. "Approved Actions" table.
+3. "Rejected Candidate Actions" table (to prove REST-first evaluation happened).
+
+### 4) UI Composition Output (Required)
+
+For each screen/state in the design:
+
+- Map to existing `@terreno/ui` components first (for example `Page`, `Box`, `Card`, `DataTable`, `TextField`, `SelectField`, `Button`, `Modal`, `Spinner`, `Toast`).
+- Include loading, empty, error, and success states.
+- Note navigation and interaction flow.
+
+Required format in skill output:
+
+1. "Terreno Component Mapping" table by screen section.
+2. "State Coverage Matrix" (loading/empty/error/success).
+3. "Accessibility/Testability Notes" (testIDs and semantics).
+
+### 5) New UI Components Output (Conditional)
+
+No mandatory net-new UI components are required by this IP itself. New components are conditional and must only be created when a clear gap exists.
+
+If a gap exists, the skill must require:
+
+- `componentName`
+- `whyExistingTerrenoComponentsDoNotFit`
+- `propsApi`
+- `states`
+- `reusabilityTargets` (at least one additional use-case)
+
+Required format in skill output:
+
+1. "New Component Candidates" table.
+2. "Approved New Components" section with API contract.
+3. "Rejected Candidate Components" section with fallback composition.
+
+## Skill Behavior Requirements
+
+The skill must guide users through this order:
+
+1. Parse design file.
+2. Produce implementation plan covering models/APIs/actions/UI/new components.
+3. Produce structured task list.
+4. Wait for confirmation of plan/task list.
+5. Execute tasks using a subagent.
+6. After each task, publish "Plan vs Actual" comparison with:
+   - status (`match`, `partial`, `deviation`)
+   - notes
+   - corrective action (if needed)
+
+## Phases
+
+### Phase 1: Planning Artifacts
+
+- Finalize this IP with explicit contract sections.
+- Produce `docs/tasks/design-blend-skill.md`.
+
+### Phase 2: Skill Authoring
+
+- Implement `.rulesync/skills/design-blend/SKILL.md` with:
+  - REST-first gate
+  - required output templates
+  - subagent execution step
+  - per-task plan comparison requirement
+
+### Phase 3: Rulesync + Validation
+
+- Run `bun run rules`.
+- Verify synced files are generated for all targets.
+- Validate markdown quality and requirement coverage.
+
+## Acceptance Criteria
+
+1. `design-blend` skill exists in `.rulesync/skills/design-blend/SKILL.md`.
+2. Skill text explicitly enforces:
+   - models output format
+   - modelRouter CRUD matrix
+   - action gating and schemas
+   - Terreno-first UI mapping
+   - conditional new component contract
+3. Skill requires subagent execution after confirmed plan/task list.
+4. Skill requires per-task "Plan vs Actual" comparison.
+5. `bun run rules` succeeds and mirrors are generated.
+
+## Deliverables
+
+1. `docs/implementationPlans/design-blend-skill.md`
+2. `docs/tasks/design-blend-skill.md`
+3. `.rulesync/skills/design-blend/SKILL.md`
+4. Synced generated skill files from `rulesync`
+
+## Risks
+
+- Skill may drift into generic advice and skip enforceable output structure.
+- Users may bypass REST-first design and overuse actions.
+- New component proposals may be accepted too early without proving Terreno composition limits.
+- Mirror files may drift if rulesync is skipped.
+
+## Mitigations
+
+- Add strict required-output templates and checklists in the skill.
+- Require explicit "why REST is insufficient" text per action.
+- Require rejected-component table before approving any net-new component.
+- Run `bun run rules` in the same implementation flow and verify generated artifacts.
+

package/src/docs/versioned/57.18.0/implementationPlans/docs-reference-coverage.md

@@ -0,0 +1,142 @@
+# Implementation Plan: Reference Documentation Coverage
+
+**Status:** Complete
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1009
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md), [`positioning-django-rails-universal`](positioning-django-rails-universal.md) (supplies the shared package-README intro block)
+**RTK deprecation flag:** **Blocked** — `syncdb.md` cannot be written before #869, and the package README rewrites reference the frontend data layer.
+
+## Goal
+
+Give every published package a public reference page and a real README. Today four package READMEs are one-line stubs pointing at `.claude/rules/...` — paths that do not exist in a published npm tarball and that leak an internal agent-tooling layout to consumers. Meanwhile the substantive documentation for those packages *does* exist, in `.cursor/rules/*/00-*.mdc` files, and is genuinely good; it is just published to the wrong audience.
+
+| Package | README | `docs/reference/` page |
+|---------|--------|------------------------|
+| `api` | good (~290 lines) | `api.md` |
+| `ui` | good (~187 lines) | `ui.md` |
+| `rtk` | good (~103 lines) | `rtk.md` → legacy |
+| `mcp-server` | good (~267 lines) | `mcp-server.md` |
+| `admin-spa` | good (~126 lines) | **missing** |
+| `ai` | **stub → `.claude/`** | **missing** |
+| `admin-backend` | **stub → `.claude/`** | `admin-backend.md` |
+| `admin-frontend` | **stub → `.claude/`** | `admin-frontend.md` |
+| `api-health` | **stub ("see source")** | `api-health.md` |
+| `feature-flags` | **missing** | `feature-flags.md` |
+| `test` | **missing** | **missing** |
+| `syncdb` | (from #869) | **missing** |
+
+## Non-Goals
+
+- Writing tutorials or how-to guides (that is [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md)).
+- Auto-generating API reference from TypeScript types — the existing `docs-audit` skill and TypeDoc-driven component pages already partially cover `@terreno/ui`; expanding that is future work.
+- Changing any package's public API.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Decision |
+|---|----------|
+| RF1 | **`docs/reference/<pkg>.md` canonical**; README is short intro + link |
+| RF2 | Keep **`.cursor/rules/*/00-*.mdc`** agent-optimized; add drift check |
+| RF3 | **`@terreno/test` gets public docs** |
+| RF4 | README links **`.ai/guidelines/core.md`** when Boost Phase 2 ships |
+| RF5 | Keep `docs/implementationPlans/` + `docs/tasks/` in repo; **README on `docs/tasks/`** explaining planning artifacts |
+
+## Architecture
+
+### Standard package README template
+
+Every published package's README follows the same six-section shape:
+
+1. Title + one-line description (from the positioning IP's standard pattern)
+2. `Install` — the exact install command including peer dependencies
+3. `Quick start` — the shortest complete working example, runnable
+4. `What's included` — bullets, 5–8 items
+5. `Documentation` — link to `docs/reference/<pkg>.md` on the docs site (absolute URL, since npm renders it outside the repo)
+6. `License` + `Contributing` links (absolute URLs)
+
+Rule: **no relative links to repository-internal paths.** A README rendered on npmjs.com must not link `../.claude/rules/...` or `../docs/`.
+
+### Standard reference page shape
+
+Follow the existing `docs/reference/api.md` and `docs/reference/rtk.md` structure, which is already good: Commands → Architecture/file structure → Key exports → Usage per feature area → Options tables → Conventions → Testing. New pages must match it so the reference tree reads as one document.
+
+### Content sources
+
+Do not write from scratch. The content exists:
+
+| Target | Source |
+|--------|--------|
+| `docs/reference/ai.md` | `.cursor/rules/ai/00-ai.mdc` (comprehensive: AIService, methods table, temperature presets, models, routes, integration, testing) |
+| `docs/reference/admin-spa.md` | `admin-spa/README.md` + `admin-spa/src/` |
+| `docs/reference/syncdb.md` | written by [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) — do not duplicate |
+| `docs/reference/test.md` | `test/src/` + the preload/bunfig patterns in `admin-backend/AGENTS.md` |
+| `ai/README.md` | new, from `docs/reference/ai.md` |
+| `admin-backend/README.md` | `.cursor/rules/admin-backend/00-admin-backend.mdc` + existing `docs/reference/admin-backend.md` |
+| `admin-frontend/README.md` | `.cursor/rules/admin-frontend/00-admin-frontend.mdc` + existing `docs/reference/admin-frontend.md` |
+| `feature-flags/README.md` | `docs/reference/feature-flags.md` |
+| `api-health/README.md` | `api-health/src/` |
+
+### Sanitization pass
+
+Every public page must be checked for internal leakage: `flourish` strings, GCP project IDs, Cloud Run URLs, Slack references, `.claude/` or `.cursor/` paths, and internal Linear ticket IDs (`PRO-`, `FH-`).
+
+## Models / APIs / Notifications / UI
+
+None.
+
+## Phases
+
+1. **Missing reference pages** — `ai.md`, `admin-spa.md`, `test.md`; fix the reference index.
+2. **De-stub package READMEs** — `ai`, `admin-backend`, `admin-frontend`, `api-health`, plus new READMEs for `feature-flags`, `test`, `demo`, `website`.
+3. **Sanitization** — sweep every public doc for internal leakage.
+4. **Drift protection** — extend the `docs-audit` skill and workflow to catch a published package without a README or reference page, and to flag reference/rule divergence.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- TypeDoc-generated API reference for `api`, `rtk`/`syncdb`, and `ai`.
+- Translating docs.
+- A searchable reference index beyond what Docusaurus provides.
+- Consolidating agent rules and reference docs into one generated source (see RF2).
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/reference/ai.md`, `docs/reference/admin-spa.md`, `docs/reference/test.md`
+- `feature-flags/README.md`, `test/README.md`, `demo/README.md`, `website/README.md`
+- `docs/tasks/README.md`
+
+**Modify**
+
+- `ai/README.md`, `admin-backend/README.md`, `admin-frontend/README.md`, `api-health/README.md`
+- `api/README.md`, `ui/README.md`, `mcp-server/README.md`, `admin-spa/README.md` (apply the standard template; convert relative links to absolute)
+- `docs/reference/README.md`, `docs/README.md`
+- `docs/reference/mcp-server.md` (tool list is behind the live server — reconcile)
+- `.rulesync/skills/docs-audit/SKILL.md`, `.github/workflows/docs-audit.yml`
+
+## Task List
+
+See [`docs/tasks/docs-reference-coverage.md`](../tasks/docs-reference-coverage.md).
+
+## Acceptance Criteria
+
+- [ ] Every package published by `publish-on-tag.yml` has both a README following the standard template and a `docs/reference/<pkg>.md` page.
+- [ ] No published package README links to a path outside its own package directory using a relative link.
+- [ ] `rg -n "\.claude/|\.cursor/" -- */README.md` returns nothing.
+- [ ] `rg -ni "flourish|a\.run\.app|PRO-[0-9]|FH-[0-9]" docs/reference/ docs/how-to/ docs/tutorials/ docs/explanation/ */README.md` returns nothing (excluding `infra/flourish/`).
+- [ ] `docs/reference/ai.md` documents every public export of `@terreno/ai`, including all `AIService` methods, temperature presets, both models, and all three route registrars.
+- [ ] `docs/reference/mcp-server.md` and `mcp-server/README.md` list the same tools as the live hosted server.
+- [ ] `docs/reference/README.md` lists every reference page, and every listed page exists.
+- [ ] `docs/tasks/README.md` states that the directory holds agent task lists, not user documentation.
+- [ ] The `docs-audit` workflow fails when a published package is missing a README or reference page.
+- [ ] `bun run website:build` produces no new broken-link warnings.