@terreno/mcp 0.28.0 → 0.29.0

package/dist/docs/versioned/0.28.0/explanation/README.md

@@ -0,0 +1,14 @@
+# Explanation
+
+Understanding-oriented documentation: concepts, architecture, and context.
+
+## Contents
+
+- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
+- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
+- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
+- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
+- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
+- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels

package/dist/docs/versioned/0.28.0/explanation/explicit-any-policy.md

@@ -0,0 +1,88 @@
+# Explicit `any` policy
+
+Terreno discourages `any` in TypeScript. Biome blocks **new** unsuppressed explicit `any` at lint time; this document describes how we inventory existing usages and track remediation.
+
+## Why
+
+- **Type safety**: `any` disables checking and hides bugs at compile time.
+- **Refactor confidence**: precise types make API and UI changes safer.
+- **Consistency**: one convention for when `any` is acceptable and how it is documented.
+
+Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as any as T` when a cast is unavoidable.
+
+## Allowed uses
+
+Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
+
+- Mongoose `Schema<any, …>` accepting arbitrary consumer schemas (`api/src/plugins.ts`)
+- RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
+- Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
+- Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
+
+Every allowed use must be **lint-clean** and **documented** (see below).
+
+## Remediation status
+
+The audit script (`bun run check:explicit-any`) classifies each explicit `any`:
+
+| Status | Meaning |
+|--------|---------|
+| `violation` | No `biome-ignore` — fails Biome lint |
+| `suppressed-only` | Has `biome-ignore` but missing `// noExplicitAny:` rationale |
+| `fully-documented` | Has both `biome-ignore` and `// noExplicitAny:` |
+| `file-blanket` | File-level `biome-ignore-all` without file-level `noExplicitAny:` |
+| `out-of-scope` | In Biome-excluded source (e.g. `api/src/populate.ts`) |
+
+## How to document an `any`
+
+When `any` cannot be removed, add **both** comments on the line above (or a file header for tests):
+
+```typescript
+// noExplicitAny: RTK Query generates hook names dynamically; not statically expressible
+// biome-ignore lint/suspicious/noExplicitAny: dynamic hook lookup on RTK Query enhanced API
+const hook = (api as any)[`useGet${name}Query`];
+```
+
+For test files with many mocks, a file-level header is fine:
+
+```typescript
+// noExplicitAny: test mocks use type-erased RTK Query API doubles
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
+```
+
+## Commands
+
+```bash
+bun run check:explicit-any                         # summary report
+bun run check:explicit-any:json                    # JSON inventory
+bun run check:explicit-any:baseline                # fail if counts regress vs baseline
+bun run check:explicit-any -- --undocumented       # only suppressed-but-undocumented
+bun run check:explicit-any -- --list --undocumented  # file:line list for remediation
+bun run check:explicit-any -- --production-only --undocumented --list
+bun run check:explicit-any -- --package=api        # filter to one package
+bun run check:explicit-any -- --include-excluded   # include Biome-excluded files
+bun run check:explicit-any -- --write-baseline     # refresh scripts/check-explicit-any/baseline.json
+bun run check:explicit-any:remediate               # auto-add missing noExplicitAny: comments
+```
+
+## Enforcement
+
+| Layer | What it does |
+|-------|----------------|
+| **Biome `noExplicitAny: error`** | Blocks new unsuppressed `any` in every linted package |
+| **`bun run check:explicit-any:baseline`** | CI ratchet — total, undocumented, and violation counts must not increase |
+| **`bun run lint`** | Per-package lint including `noExplicitAny` |
+
+Baseline file: `scripts/check-explicit-any/baseline.json`. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
+
+## Remediation workflow
+
+1. Run `bun run check:explicit-any -- --list --undocumented --production-only` for a work queue.
+2. For each hit, either **replace** `any` with a proper type or **document** with `noExplicitAny:` + `biome-ignore`.
+3. Prefer line-level suppressions over file-level `biome-ignore-all` in production code.
+4. Run `bun run check:explicit-any:baseline` before opening a PR.
+5. If counts decreased, run `--write-baseline` and commit the new baseline.
+
+## Exclusions
+
+The audit skips generated and template files (`openApiSdk.ts`, `*.template.ts`). Biome-excluded paths (see `!!` patterns in `biome.jsonc`) are omitted unless `--include-excluded` is passed.

package/dist/docs/versioned/0.28.0/explanation/no-barrel-imports.md

@@ -0,0 +1,49 @@
+# No barrel imports
+
+Terreno avoids **barrel imports** — imports that resolve through an `index.ts` / `index.tsx` file that only re-exports other modules.
+
+## Why
+
+- **Clearer dependencies**: each import names the file that defines the symbol.
+- **Faster tooling**: bundlers and TypeScript do less re-export chasing.
+- **Fewer cycles**: internal barrels (especially package `index` files) are a common source of circular dependencies.
+
+## Allowed
+
+- **Published package APIs** — cross-package imports like `@terreno/api`, `@terreno/ui`, and `@terreno/rtk` use each package's public `src/index` entry. That is intentional.
+- **Package public entry files** — `api/src/index.ts`, `ui/src/index.tsx`, etc. may re-export for npm consumers. Do not import those barrels from *inside* the same package.
+- **Expo Router routes** — `app/**/index.tsx` files are route entries, not barrels.
+
+## Not allowed
+
+Internal barrel `index` files do not exist in this repo — the Biome `noBarrelFile` override bans creating them, so a directory import like `../models` has nothing to resolve to and fails to compile.
+
+Importing a directory that resolves to a re-exporting index file:
+
+```typescript
+// Bad — resolves to models/index.ts
+import {User} from "../models";
+
+// Good — imports the defining module
+import {User} from "../models/user";
+```
+
+```typescript
+// Bad — store/index.ts was a barrel of sdk/appState/utils
+import {useGetMeQuery} from "@/store";
+
+// Good
+import {useGetMeQuery} from "@/store/sdk";
+import store, {useAppDispatch} from "@/store/index";
+```
+
+## Enforcement
+
+No generation step is required — internal barrel `index` files are banned outright, so there is never a list of barrels to keep in sync.
+
+- **Biome `noBarrelFile` override** (root `biome.jsonc`): bans internal barrel `index.ts` / `index.tsx` files during lint. Package public entries (`src/index.ts[x]`) and Expo Router routes (`app/**`) are exempt.
+- **Biome plugin**: `biome/plugins/no-barrel-imports.grit` — a small static GritQL plugin that flags path-alias directory imports (`@/store`, `@components`, …) in the packages that define those aliases (`example-frontend`, `admin-spa`, `demo`).
+- **CI**: `bun run check:no-barrel-imports` — resolution-based safety net that fails if any internal barrel index file exists or any import resolves through one (see root `package.json` → `terreno.policies.noBarrelImports`).
+- **AI rules**: `.rulesync/rules/00-root.md` and package `.ai/guidelines/core.md` files
+
+When scaffolding new code (MCP bootstrap, examples), always generate direct module paths — never `models/index`, `@/store`, or `@components` without a concrete file.

package/dist/docs/versioned/0.28.0/how-to/README.md

@@ -0,0 +1,21 @@
+# How-to Guides
+
+Problem-oriented, practical steps. Use these when you know what you want to do.
+
+## Contents
+
+- [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
+- [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
+
+## Coming Soon
+
+- [Add feature flags](add-feature-flags.md) — Add feature flags and A/B testing to your app
+- Add custom permissions
+- Implement file uploads
+- Configure email notifications
+- Customize AI workflows
+- Set up custom CI/CD pipelines

package/dist/docs/versioned/0.28.0/how-to/call-external-apis.md

@@ -0,0 +1,101 @@
+# Call external APIs
+
+How to talk to third-party HTTP APIs (payment processors, health integrations, meeting providers, etc.) from a `@terreno/api` backend using the shared HTTP client utilities, instead of hand-rolling axios setup, token caching, retry, and error handling per integration.
+
+## When to use each piece
+
+| You are... | Use |
+|---|---|
+| Calling a third-party REST API that needs a bearer token, OAuth2 client-credentials, or API-key auth | `createAuthenticatedClient` |
+| Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
+| Logging or classifying a caught error from any external call | `normalizeApiError` |
+| Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
+| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+
+**Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
+
+## Create a client
+
+```typescript
+import {createAuthenticatedClient} from "@terreno/api";
+
+const widgetApi = createAuthenticatedClient({
+  apiName: "widgetService", // used in logs and normalized errors; defaults to baseURL
+  auth: {
+    credentials: {clientId: process.env.WIDGET_CLIENT_ID!, clientSecret: process.env.WIDGET_CLIENT_SECRET!},
+    refreshOn401: true,
+    tokenUrl: "https://api.widgets.example/oauth/token",
+    type: "oauth2",
+  },
+  baseURL: "https://api.widgets.example/v2",
+});
+
+const response = await widgetApi.axios.get("/widgets/123");
+```
+
+Auth strategies:
+
+- `{type: "bearer", getToken}` — you supply an async token fetcher; the client caches the result until `invalidateToken()` is called.
+- `{type: "oauth2", tokenUrl, credentials, refreshOn401}` — the client performs the client-credentials grant itself (HTTP Basic auth, form-encoded). With `refreshOn401: true`, a 401 response invalidates the cached token and retries the request exactly once with a fresh one.
+- `{type: "apiKey", header, getKey}` — the key is sent on the header you name.
+
+Tokens are fetched lazily and concurrent first requests share a single fetch. Create the client once per service at module scope — not per request — so the token cache is actually shared.
+
+## What you get for free
+
+- **Retry with backoff** for transient failures (429 rate limits, 5xx, network errors), honoring `Retry-After`, capped by `maxDelayMs`. Defaults: 3 total attempts, 250ms base delay, 30s delay ceiling — override via the `retry` option.
+- **Idempotency safety**: only GET/HEAD/OPTIONS are retried by default. Retrying a failed POST can duplicate side effects (a payment, a prescription, a meeting). If a specific POST/PUT/DELETE is genuinely safe to repeat, opt it in per request:
+
+  ```typescript
+  import {markRetryUnsafe} from "@terreno/api";
+
+  // Safe to repeat: the upstream endpoint is idempotent on externalId.
+  await widgetApi.axios.post("/widgets", {externalId, name}, markRetryUnsafe());
+  ```
+
+  The request body must be replayable — JSON is fine; streams/FormData are consumed on first send.
+- **Quiet transport logging**: the client logs retries and token refreshes at debug level only and always rejects with the original axios error. Error-level logging belongs to the call site (next section) so composed usage logs each failure exactly once.
+
+## Handle failures at the call site
+
+Wrap calls with `withApiErrorHandling` to normalize, log once, and rethrow:
+
+```typescript
+import {withApiErrorHandling} from "@terreno/api";
+
+export const getWidget = async (id: string): Promise<Widget> => {
+  const response = await withApiErrorHandling(() => widgetApi.axios.get(`/widgets/${id}`), {
+    apiName: "widgetService",
+    operation: "getWidget",
+  });
+  return response.data;
+};
+```
+
+- Default (`rethrowAs: "raw"`): logs the normalized shape (status code, classification, extracted messages) and rethrows the original error for callers that need it.
+- `rethrowAs: "apiError"`: throws a terreno `APIError` (stable title, per-occurrence `detail`) so route handlers surface a clean JSONAPI error instead of a raw axios failure. In this mode the `APIError` constructor does the logging.
+
+For SDK-based integrations where `createAuthenticatedClient` doesn't apply, `withApiErrorHandling` still works — `normalizeApiError` classifies non-axios errors as `"unknown"` while preserving the message.
+
+## Sensitive response data
+
+`normalizeApiError` never logs raw payload bodies: it extracts only recognized message fields (`{message}`, JSONAPI `{errors: [{title, detail}]}`, plain strings truncated to 500 chars). If the upstream service puts sensitive data *inside* those message fields, supply a `redactError` hook (available on both `createAuthenticatedClient` and `withApiErrorHandling`):
+
+```typescript
+redactError: (normalized) => ({
+  ...normalized,
+  messages: normalized.messages.map((message) => message.replace(PATIENT_ID_PATTERN, "[redacted]")),
+}),
+```
+
+Note the hook's output classification also feeds the client's retry decision — redact messages, don't rewrite classifications, unless changing retry behavior is intended.
+
+## When not to use this
+
+- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
+- **Webhook notifiers** — `sendSlackMessage`/`sendGoogleChatMessage`/`sendZoomMessage` already exist; see [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
+
+## Related
+
+- [@terreno/api reference — HTTP Client](../reference/api.md#http-client)

package/dist/docs/versioned/0.28.0/implementationPlans/PLAN_INDEX.md

@@ -0,0 +1,75 @@
+# Implementation plan index
+
+Tracks active and completed implementation plans (IP) for Terreno. File paths are relative to `docs/implementationPlans/`.
+
+## Programs
+
+Umbrella plans that coordinate several IPs.
+
+| Program | Status | Created | IPs |
+|---------|--------|---------|-----|
+| [Open source launch](oss-launch-program.md) | Draft — decisions recorded; Vercel spike open | 2026-07-27 | 15 |
+
+## Active
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
+| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
+| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
+| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
+
+## Open source launch IPs
+
+All part of the [launch program](oss-launch-program.md). The **RTK flag** column marks dependence on the `@terreno/rtk` → `@terreno/syncdb` migration in PR #869: `None` is safe to implement now, `Partial` has some blocked tasks, `Blocked` cannot start until #869 merges.
+
+### Wave 0 — unblocked
+
+| Plan | Status | RTK flag | Tasks |
+|------|--------|----------|-------|
+| [OSS governance baseline](oss-governance-baseline.md) | Draft | None | [tasks](../tasks/oss-governance-baseline.md) |
+| [Public roadmap on GitHub](public-roadmap-github.md) | Draft | None | [tasks](../tasks/public-roadmap-github.md) |
+| [Deploy to GCP (generalized)](deploy-to-gcp.md) | Draft | None | [tasks](../tasks/deploy-to-gcp.md) |
+| [Agentic SDLC plugin (`/terreno-*`)](agentic-sdlc-plugin.md) | Draft | Partial | [tasks](../tasks/agentic-sdlc-plugin.md) |
+
+### Wave 1 — gated on PR #869
+
+| Plan | Status | RTK flag | Tasks |
+|------|--------|----------|-------|
+| [RTK deprecation and syncdb migration docs](rtk-to-syncdb-migration-docs.md) | Draft | **Blocked** (gating IP) | [tasks](../tasks/rtk-to-syncdb-migration-docs.md) |
+| [Positioning — Django/Rails for TypeScript](positioning-django-rails-universal.md) | Draft | Partial | [tasks](../tasks/positioning-django-rails-universal.md) |
+| [Reference documentation coverage](docs-reference-coverage.md) | Draft | Blocked | [tasks](../tasks/docs-reference-coverage.md) |
+| [AI-first tutorials](docs-tutorials-ai-first.md) | Draft | Blocked | [tasks](../tasks/docs-tutorials-ai-first.md) |
+| [Deployment foundation](deployment-foundation.md) | Draft | Partial | [tasks](../tasks/deployment-foundation.md) |
+| [Deploy to Vercel](deploy-to-vercel.md) | Draft | Partial | [tasks](../tasks/deploy-to-vercel.md) |
+| [Upgrade guides and skill](upgrade-guides-and-skill.md) | Draft | Blocked | [tasks](../tasks/upgrade-guides-and-skill.md) |
+| [The AI development loop (Boost)](ai-dev-loop-boost.md) | Draft | Partial | [tasks](../tasks/ai-dev-loop-boost.md) |
+| [Dogfooding run and launch blog post](build-terreno-app-validation.md) | Draft | Blocked | [tasks](../tasks/build-terreno-app-validation.md) |
+| [Examples, demo, and test coverage](examples-demo-coverage.md) | Draft | Partial | [tasks](../tasks/examples-demo-coverage.md) |
+
+### Wave 2 — independent
+
+| Plan | Status | RTK flag | Tasks |
+|------|--------|----------|-------|
+| [Web SSR and admin SPA](web-ssr-and-admin-spa.md) | Draft | Partial | [tasks](../tasks/web-ssr-and-admin-spa.md) |
+
+## Completed
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [APIError redesign — standards-first extension of Error](apierror-standard-error-redesign.md) | Complete | 2026-07-28 | n/a |
+
+## Deferred / Closed
+
+*(Plans parked or superseded.)*
+
+## Backlog
+
+*(Links to ideas not yet promoted to a full IP.)*
+
+| Idea | Notes |
+|------|-------|
+| [Langfuse integration](terreno-langfuse-integration.md) | AI observability plugin |
+| [modelRouter MCP tools](model-router-mcp.md) | MCP surface for consumer app APIs |
+| [Offline mode](offline-mode.md) | Superseded in large part by [syncdb](syncdb-local-first.md) — confirm and close |
+| [modelRouter actions](model-router-actions.md) | — |

package/dist/docs/versioned/0.28.0/implementationPlans/agentic-sdlc-plugin.md

@@ -0,0 +1,177 @@
+# Implementation Plan: Publish and Document the Agentic SDLC Plugin
+
+**Status:** Draft — key decisions recorded (2026-07-29)
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`positioning-django-rails-universal`](positioning-django-rails-universal.md) (shared copy blocks), [`oss-governance-baseline`](oss-governance-baseline.md) (license coverage for `plugins/`)
+**RTK deprecation flag:** **Partial** — the pipeline's frontend-verification gates name `rtk/` in their path lists and must be updated to name `syncdb/` after PR #869.
+
+## Goal
+
+Terreno ships a five-stage agentic SDLC pipeline as an installable Cursor plugin, and **nobody outside the team knows it exists.** `.cursor-plugin/marketplace.json` declares a team marketplace; `plugins/terreno-planning/` contains five skills that take work from a raw request all the way to a mergeable PR. There is no `plugins/README.md`, no page in `docs/`, no mention in `README.md` or `AGENTS.md`, and the marketplace is scoped to the team.
+
+This matters more than a normal documentation gap. The pipeline is the most concrete evidence for the AI-native pillar. Any framework can claim "works great with AI"; very few ship an opinionated, reviewed, test-driven delivery process as installable tooling. In the Django/Rails analogy it is the missing half of `manage.py`: not just "generate a model" but "take this ticket to a mergeable PR with tests and independent review".
+
+The audit that produced this program missed the plugin entirely. If an agent reading the whole repository missed it, every prospective user will too.
+
+## Non-Goals
+
+- Redesigning the pipeline. The five stages work; this is packaging, documentation, and positioning.
+- Porting the pipeline to every agent runtime. Cursor is the reference; note what would be required for others.
+- Replacing the repo's existing `.rulesync/skills/` (`submit`, `autobot`, `check-watcher`, `respond-to-review`) — but the overlap needs resolving, because right now two pipelines cover similar ground.
+- Building a plugin marketplace of our own.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (see program [P11](oss-launch-program.md#blocking-questions-program-level)).
+
+| # | Question | Decision |
+|---|----------|----------|
+| AP1 | Marketplace public or team-only? | **A** — public at launch (gated on portability) |
+| AP2 | PHI/HIPAA handling | **B** — generalize to "sensitive data (PHI, PII, secrets)" |
+| AP3 | Stage names | **Coffee theme retained.** New five-stage flow: **grow → harvest → roast → brew → taste**. Skills: `/terreno-1-grow`, `/terreno-2-harvest`, `/terreno-3-roast`, `/terreno-4-brew`, `/terreno-5-taste`. **Aliases required** in docs and skill frontmatter (see mapping below) |
+| AP4 | Consumer apps or monorepo only? | **B** — must work in consumer apps |
+| AP5 | Overlap with `submit` / `autobot` | **A** — deprecate `submit` and `autobot` in favor of the plugin. **Fold all `autobot` behavior into Taste (`/terreno-5-taste`)**. Taste should be **self-contained** (inline the full submit → CI → review loop) rather than delegating to other skills — delegation has been unreliable inside the plugin (sub-agents and cross-skill calls do not always resolve). Accept larger skill files / context cost over broken orchestration |
+| AP6 | Agent runtimes | **B** — Cursor + rulesync-generated variants |
+| AP7 | Plugin versioning | **A** — independent versioning; declare compatible Terreno versions |
+
+### Stage mapping (rename + aliases)
+
+| # | New name | Role | Replaces | Aliases (docs + deprecated skill names) |
+|---|----------|------|----------|----------------------------------------|
+| 1 | **grow** | Plan — IP + tasks, blocking questions first | blend | `plan`, `blend`, `terreno-1-blend` |
+| 2 | **harvest** | Implement — strict TDD, drift detection | roast (implement) | `implement`, `terreno-2-roast` |
+| 3 | **roast** | Verify — independent evidence in fresh context | cupping | `verify`, `cupping`, `terreno-3-cupping` |
+| 4 | **brew** | Submit — checks, commit, push, draft PR, evidence | pour | `submit`, `pour`, `terreno-4-pour` |
+| 5 | **taste** | Review loop — CI + bot/human comments until mergeable; **includes former `autobot`** | dialin | `review`, `dialin`, `terreno-5-dialin` |
+
+## Architecture
+
+### The pipeline
+
+```mermaid
+flowchart LR
+  REQ["Request<br/>ticket / spec / idea"]
+  G["/terreno-1-grow<br/>(plan)"]
+  H["/terreno-2-harvest<br/>(implement)"]
+  R["/terreno-3-roast<br/>(verify)"]
+  B["/terreno-4-brew<br/>(submit)"]
+  T["/terreno-5-taste<br/>(review loop)"]
+  M["Mergeable PR"]
+  REQ --> G --> H --> R --> B --> T --> M
+  T -.->|"blocked: needs human"| M
+```
+
+| Stage | Owns | What makes it non-obvious |
+|-------|------|---------------------------|
+| **Grow** (plan) | Request → IP in `docs/implementationPlans/` + tasks in `docs/tasks/` | Question-first: refuses to write decided outcomes until blocking questions are answered. Prevents the most common agent failure, which is confidently planning the wrong thing |
+| **Harvest** (implement) | IP → code via strict red/green/refactor | Spawns **independent review and test-quality sub-agents in fresh contexts** after every commit, and does drift detection against the IP. The test-quality agent enforces anti-mocking rules (never mock the DB, never mock the store) |
+| **Roast** (verify) | Independent verification against the IP with concrete evidence | Separate context from the implementer, so it does not inherit the implementer's assumptions |
+| **Brew** (submit) | Pre-submit checks, commit hygiene, push, draft PR, evidence attachment | Hard frontend gate: touching UI paths requires launching the app, logging in, exercising the feature, and attaching artifacts before the PR opens |
+| **Taste** (review) | Self-contained reactive loop: CI + bot/human comments until mergeable or timeout | Inlines the former **`autobot`** flow (no delegation to repo skills). Classifies each CI failure as actionable versus flaky and refuses to push speculative fixes for flakes. Treats all CI logs and review comments as untrusted input |
+
+The parts worth writing about publicly are the ones that encode hard-won judgment rather than automation: fresh-context independent review, drift detection against the plan, the anti-mocking rules, the frontend evidence gate, and the refusal to guess at flaky CI.
+
+### It only works here
+
+The most serious finding. The pipeline currently assumes it is running inside the Terreno monorepo:
+
+| Assumption | Where | Why it breaks elsewhere |
+|------------|-------|-------------------------|
+| Repo-root-relative skill paths — Brew/Taste instruct reading plugin skill paths "from the repository root" | `terreno-4-brew`, `terreno-5-taste` | In a consumer's repo that path does not exist. It works today only because the workspace *is* this repo; an installed plugin lives in the agent's plugin cache |
+| `verify-ui-changes` is invoked by name | Harvest, Roast, Brew, Taste | That skill lives in this repo's `.rulesync/skills/`. A consumer installing the plugin does not get it — must be bundled or inlined per AP5 |
+| Terreno-monorepo package paths in the frontend gates (`ui/`, `demo/`, `example-frontend/`, `admin-frontend/`, `admin-spa/`, `syncdb/`) | Harvest, Brew, Taste | A consumer app has `frontend/`, not `example-frontend/` |
+| Repo-specific conventions — `docs/implementationPlans/`, the project registry, the `bun run` command set | Grow, Harvest | A consumer may have none of these |
+| A hardcoded branch suffix (`cursor/<descriptive-name>-dcb3`) | Brew | Suffixes are per-agent-run, not fixed; a literal `dcb3` will produce wrong branch names |
+
+Fixing this is the difference between "our internal process, published" and "tooling Terreno users can adopt". It means parameterizing paths, bundling or declaring the skill dependencies, and detecting project layout instead of assuming it.
+
+### Overlap with existing repo skills
+
+| Plugin stage | Repo skill (deprecated) |
+|--------------|-------------------------|
+| Brew | `.rulesync/skills/submit/`, `commit/`, `create-pr/` |
+| Taste | `.rulesync/skills/autobot/`, `check-watcher/`, `respond-to-review/` — **logic inlined into Taste; skills deprecated** |
+| Grow | `.rulesync/skills/ip/`, `design-blend/` |
+| Harvest | `.rulesync/skills/implement/` |
+
+Per AP5, **`submit` and `autobot` are deprecated** once Taste ships self-contained. Do not document two parallel pipelines.
+
+### Positioning
+
+The pipeline belongs in the **AI-native** pillar, alongside the MCP server. They are complementary and the distinction should be stated plainly:
+
+- **MCP server** = the *tool* layer. What an agent can see and do: search docs, generate conventional code, read merged logs, inspect client state, drive the running app.
+- **SDLC plugin** = the *process* layer. How an agent should sequence work: plan before coding, test-drive, review in a fresh context, verify independently, gate on evidence, then own the review loop.
+
+In the Django/Rails comparison table, this fills the row that currently reads "MCP server tools + skills — agent-driven rather than CLI-driven". Better framing: Django gives you `manage.py startapp`; Terreno gives you a reviewed path from ticket to mergeable PR.
+
+## Models / APIs / Notifications / UI
+
+None.
+
+## Phases
+
+1. **Decide and sanitize** — answer AP2, generalize PHI language, remove Flourish specifics, fix the hardcoded branch suffix.
+2. **Rename stages** — grow/harvest/roast/brew/taste with aliases; bump plugin minor version (AP3).
+3. **Make it portable** — parameterize paths, bundle `verify-ui-changes` (or equivalent), detect project layout (AP4).
+4. **Consolidate Taste** — inline `autobot` + review-loop behavior; deprecate `submit`/`autobot` repo skills (AP5).
+5. **Document** — `plugins/README.md`, docs-site explainer and how-to, per-stage reference with alias callouts.
+6. **Position** — README, docs landing, comparison table, agent context files.
+7. **Distribute** — publish the marketplace; generate non-Cursor variants via rulesync (AP6).
+
+## Feature Flags & Migrations
+
+None. Renaming or aliasing stages (AP3) is a breaking change for anyone with the plugin installed — bump the plugin minor version and note it in `plugins/README.md`.
+
+## Not Included / Future Work
+
+- A healthcare-specific plugin variant retaining explicit PHI handling (AP2 option C).
+- Additional stages (design review, release, incident response).
+- Telemetry on stage usage or success rates.
+- Publishing to a public Cursor plugin directory beyond this repo's marketplace, if one exists.
+
+## Files to Create / Modify
+
+**Create**
+
+- `plugins/README.md`
+- `docs/explanation/agentic-sdlc.md`
+- `docs/how-to/use-the-terreno-plugin.md`
+- `docs/reference/sdlc-plugin.md`
+- `plugins/terreno-planning/LICENSE`
+
+**Modify**
+
+- `plugins/terreno-planning/skills/*/SKILL.md` (all five: sanitization, portability, delegation)
+- `plugins/terreno-planning/.cursor-plugin/plugin.json`, `.cursor-plugin/marketplace.json`
+- `README.md`, `docs/README.md`, `docs/explanation/positioning.md`
+- `AGENTS.md` / `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`
+- `.rulesync/skills/submit/SKILL.md`, `autobot/SKILL.md` (cross-reference the plugin)
+- `scripts/check-license-coverage.ts` (cover `plugins/`)
+- `.rulesync/skills/build-terreno-app/SKILL.md` (use the pipeline if public)
+
+## Task List
+
+See [`docs/tasks/agentic-sdlc-plugin.md`](../tasks/agentic-sdlc-plugin.md).
+
+## Acceptance Criteria
+
+- [ ] `plugins/README.md` explains the five stages, installation, and when to use each, in under 150 lines.
+- [ ] No plugin skill contains Flourish-specific vocabulary; sensitive-data handling is generalized per AP2.
+- [ ] No plugin skill contains a hardcoded branch suffix or a repo-root-relative path to a sibling skill.
+- [ ] The pipeline runs end to end in a **consumer app scaffolded by `terreno_bootstrap_app`**, not just in this monorepo — verified by taking one small feature from request to open PR.
+- [ ] Every skill dependency (`verify-ui-changes` at minimum) is either bundled with the plugin or declared with installation instructions.
+- [ ] Frontend path gates are derived from the project's actual layout rather than hardcoded monorepo package names.
+- [ ] Pour and Taste are self-contained per AP5; deprecated `submit`/`autobot` repo skills point to the plugin; no rule is stated in two places with different wording.
+- [ ] `docs/explanation/agentic-sdlc.md` explains the process layer versus the MCP tool layer and why fresh-context independent review matters.
+- [ ] `docs/how-to/use-the-terreno-plugin.md` takes a reader from installation to a merged PR.
+- [ ] `docs/reference/sdlc-plugin.md` documents each stage's scope, inputs, outputs, and boundaries.
+- [ ] `README.md` and `docs/README.md` name the pipeline under the AI-native pillar; the Django/Rails comparison table's generator row cites it.
+- [ ] Every public reference to a coffee-named stage gives its plain-language meaning at least once per page.
+- [ ] The marketplace is installable by the audience chosen in AP1, verified by a fresh install.
+- [ ] `plugins/` is covered by the license-coverage check.
+- [ ] `bun run rules:check` and `bun run check` pass.