@terreno/mcp 57.17.0 → 57.18.0

package/src/docs/versioned/0.30.0/implementationPlans/oss-launch-program.md

@@ -1,195 +0,0 @@
-# Program: Open Source Launch
-
-**Status:** Draft — decisions recorded (defaults accepted 2026-07-29)
-**Priority:** High
-**Effort:** Epic (multiple IPs)
-**Owner:** unassigned
-**Created:** 2026-07-27
-
-Umbrella program for taking Terreno from "internal Flourish monorepo that happens to publish npm packages" to a credible public open-source framework. This document is the index, sequencing plan, and single place where cross-IP decisions get recorded.
-
-Individual IPs live alongside this file; each has a companion task list in `docs/tasks/`.
-
-## Positioning
-
-Every IP in this program must use one consistent positioning statement. The agreed framing:
-
-> **Terreno is Django/Rails for TypeScript — with universal app support.**
->
-> Batteries-included full-stack framework: models, migrations-free schema conventions, auto-generated REST APIs, permissions, admin panel, auth, and an AI service on the backend; one React Native codebase that ships to iOS, Android, and web on the frontend. Built to be driven by AI coding agents from the first prompt to production deploy.
-
-Three pillars, in priority order:
-
-1. **Batteries included** (the Django/Rails claim) — the undifferentiated 80% of an app is already written: auth, CRUD, admin, permissions, AI, realtime, feature flags, consent.
-2. **Universal by default** (the differentiator vs Django/Rails) — one codebase, three platforms. Not a web framework with a mobile bolt-on.
-3. **AI-native** (the differentiator vs everything) — two layers, and the docs must present them as complementary:
-   - the **tool layer**: an MCP server with codegen, docs search, and runtime introspection (logs, client state, navigation), plus per-package agent guidelines;
-   - the **process layer**: the `/terreno-*` agentic SDLC pipeline shipped as an installable plugin — plan, implement test-first, verify in a fresh context, submit with evidence, then own the review loop to mergeable.
-
-   Agents are a first-class client of the framework, not an afterthought. Django gives you `manage.py startapp`; Terreno gives you a reviewed path from a request to a mergeable PR.
-
-Language rules for all docs:
-
-- Say "Django/Rails for TypeScript" in the first two sentences of the README and docs landing page.
-- Say "universal app" (not "cross-platform", not "React Native app") when describing the frontend.
-- Never claim features listed under "Where Terreno is headed" as shipped.
-- Avoid "the best framework for X" superlatives in reference docs; keep those to the landing page.
-
-## RTK deprecation gate
-
-**`@terreno/rtk` is being replaced.** PR [#869](https://github.com/TerrenoLabs/terreno/pull/869) (`@terreno/syncdb` local-first data layer) makes **Better Auth + `@terreno/syncdb`** the supported frontend platform. RTK Query becomes legacy.
-
-**Program-wide rule: IPs flagged `Blocked` may not be implemented until #869 merges.** Writing docs against RTK now guarantees a rewrite. Planning (this program) proceeds; implementation of `None`-flagged IPs may start before #869; `Partial` IPs proceed except for `[RTK]`-marked tasks.
-
-Each IP carries an explicit flag:
-
-| Flag | Meaning |
-|------|---------|
-| **None** | No RTK/Better Auth surface. Safe to implement before #869. |
-| **Partial** | Mostly RTK-independent, but specific tasks touch RTK. Those tasks are marked `[RTK]` in the task file. |
-| **Blocked** | Core content is RTK-shaped. Do not start until #869 merges. |
-
-Every `[RTK]`-marked task in every task file must be reviewed against the merged #869 surface before implementation. The migration content itself is owned by [`rtk-to-syncdb-migration-docs.md`](rtk-to-syncdb-migration-docs.md), which gates most of Wave 1.
-
-### Known RTK-shaped surfaces to re-verify after #869
-
-| Surface | Location | Post-#869 expectation |
-|---------|----------|-----------------------|
-| Frontend data-fetching narrative | `README.md`, `docs/README.md`, `docs/tutorials/getting-started.md` | syncdb local-first reads/mutations |
-| SDK codegen loop | `.rulesync/skills/generate-sdk/SKILL.md`, `example-frontend/openapi-config.ts` | `@terreno/syncdb-codegen` descriptors |
-| Auth story | `docs/how-to/configure-better-auth.md`, `docs/explanation/authentication.md` | Better Auth primary, JWT legacy |
-| `docs/reference/rtk.md` | reference tree | **Removed from launch reference** (P7 A); migration guide only |
-| `get_rtk_state` MCP tool | `mcp-server/src/local/tools/runtime.ts` (PR #802) | Rename/extend to syncdb store inspection |
-| `installTerrenoDevConsoleLogger` | `rtk/src/devConsoleLogger.ts` (PR #802) | Move to syncdb or a shared client package |
-| Feature-flag client hooks | `docs/reference/feature-flags.md`, `rtk/src/` | OpenFeature provider fed by syncdb |
-| Offline queue | `rtk/src/` offline middleware | Superseded by syncdb outbox |
-
-## Boost dependency (AI story)
-
-PR [#802](https://github.com/TerrenoLabs/terreno/pull/802) (MCP Boost parity, Phases 4–6) is **assumed merged** by the AI-facing IPs. It delivers the runtime half of the AI story:
-
-- `read_logs` merging backend / app (CDP) / Metro / browser sources
-- `last_error` across sources
-- `get_rtk_state` (→ syncdb state post-#869)
-- `evaluate` and `navigate` over CDP, gated by `TERRENO_MCP_EVAL=1`
-- Dev-only `POST /__terreno/browser-logs` ingestion in `@terreno/api`
-
-Combined with the already-shipped hosted tools (`terreno_search_docs`, `terreno_get_component_docs`, `terreno_bootstrap_app`, generators, `terreno_get_upgrade_guide`), this is the "agent can build, run, observe, and fix a Terreno app without a human reading logs" claim. [`ai-dev-loop-boost.md`](ai-dev-loop-boost.md) owns telling that story.
-
-## The `/terreno-*` SDLC pipeline
-
-The repo already ships the process half of the AI story and **has never documented it**: `.cursor-plugin/marketplace.json` plus `plugins/terreno-planning/` define an installable five-stage pipeline — **`/terreno-1-grow`** (plan), **`/terreno-2-harvest`** (implement), **`/terreno-3-roast`** (verify), **`/terreno-4-brew`** (submit), **`/terreno-5-taste`** (review loop until mergeable). Legacy names (`blend`, `cupping`, `pour`, `dialin`) remain as aliases during the rename — see [`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md).
-
-It encodes real judgment rather than automation: a question-first planning gate that refuses to commit to decisions before they are answered, independent review and test-quality sub-agents spawned in **fresh contexts** after every commit, drift detection against the plan, anti-mocking rules, a hard frontend-evidence gate, and a refusal to push speculative fixes for flaky CI.
-
-Two problems block using it as a launch asset, both owned by [`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md):
-
-1. **It is invisible.** No `plugins/README.md`, no docs page, no mention in `README.md` or `AGENTS.md`. The audit that produced this program missed it entirely — which is exactly what every prospective user will do.
-2. **It only works inside this monorepo.** Repo-root-relative sibling-skill paths, a dependency on a `verify-ui-changes` skill that lives in `.rulesync/`, hardcoded monorepo package names in the frontend gates, and a hardcoded branch suffix. Publishing it without fixing these ships tooling that breaks on first use in a consumer app.
-
-## IP index
-
-### Wave 0 — unblocked, can start immediately
-
-| IP | Title | RTK flag | Why now |
-|----|-------|----------|---------|
-| [oss-governance-baseline](oss-governance-baseline.md) | License, contributing, security, changelog, templates | None | Legal blocker for any public launch; zero framework surface |
-| [public-roadmap-github](public-roadmap-github.md) | GitHub Discussions + Projects roadmap + Linear bridge | None | Needed before inviting outside contributors; process-only |
-| [deploy-to-gcp](deploy-to-gcp.md) | Generalized GCP deploy docs + `deploy-gcp` skill | None | Backend + static hosting only; no client data layer |
-| [agentic-sdlc-plugin](agentic-sdlc-plugin.md) | Publish, port, and document the `/terreno-*` pipeline | Partial | Already built and shipping; only the frontend path lists touch the data layer |
-
-### Wave 1 — gated on #869 (syncdb) merging
-
-| IP | Title | RTK flag | Depends on |
-|----|-------|----------|------------|
-| [rtk-to-syncdb-migration-docs](rtk-to-syncdb-migration-docs.md) | Deprecation policy, migration guide, reference restructure | Blocked | #869 |
-| [positioning-django-rails-universal](positioning-django-rails-universal.md) | Positioning rewrite across README, docs site, agent rules | Partial | rtk-to-syncdb-migration-docs |
-| [docs-reference-coverage](docs-reference-coverage.md) | `ai.md`, `syncdb.md`, `admin-spa.md`, de-stub package READMEs | Blocked | rtk-to-syncdb-migration-docs |
-| [docs-tutorials-ai-first](docs-tutorials-ai-first.md) | Getting-started rewrite + 4 new tutorials | Blocked | docs-reference-coverage, ai-dev-loop-boost |
-| [deployment-foundation](deployment-foundation.md) | Deployment architecture, env reference, backend Dockerfile | Partial | — |
-| [deploy-to-vercel](deploy-to-vercel.md) | Vercel deploy docs + `deploy-vercel` skill | Partial | deployment-foundation |
-| [upgrade-guides-and-skill](upgrade-guides-and-skill.md) | `upgrading-terreno` skill, backfill 0.22–0.26 notes, release gate | Blocked | rtk-to-syncdb-migration-docs |
-| [ai-dev-loop-boost](ai-dev-loop-boost.md) | AI-native story built on Boost #802 | Partial | #802 |
-| [build-terreno-app-validation](build-terreno-app-validation.md) | `build-terreno-app` skill run + blog post | Blocked | docs-tutorials-ai-first, ai-dev-loop-boost |
-| [examples-demo-coverage](examples-demo-coverage.md) | Demo README, missing stories, CI coverage gates | Partial | — |
-
-### Wave 2 — independent feature work
-
-| IP | Title | RTK flag | Notes |
-|----|-------|----------|-------|
-| [web-ssr-and-admin-spa](web-ssr-and-admin-spa.md) | Server-side rendering for universal web + admin-spa migration | Partial | Can be planned/prototyped in parallel; ships after Wave 1 docs stabilize |
-
-## Suggested sequencing
-
-```mermaid
-flowchart TD
-  subgraph w0 ["Wave 0 — now"]
-    gov["oss-governance-baseline"]
-    road["public-roadmap-github"]
-    gcp["deploy-to-gcp"]
-    plug["agentic-sdlc-plugin"]
-  end
-  syncdb["PR #869 syncdb merges"]
-  boost["PR #802 Boost merges"]
-  subgraph w1 ["Wave 1 — after #869"]
-    mig["rtk-to-syncdb-migration-docs"]
-    pos["positioning-django-rails-universal"]
-    ref["docs-reference-coverage"]
-    ai["ai-dev-loop-boost"]
-    tut["docs-tutorials-ai-first"]
-    upg["upgrade-guides-and-skill"]
-    dep["deployment-foundation"]
-    ver["deploy-to-vercel"]
-    demo["examples-demo-coverage"]
-    build["build-terreno-app-validation"]
-  end
-  ssr["web-ssr-and-admin-spa"]
-  syncdb --> mig
-  boost --> ai
-  mig --> pos
-  mig --> ref
-  mig --> upg
-  ref --> tut
-  ai --> tut
-  dep --> ver
-  tut --> build
-  ai --> build
-  plug --> pos
-  plug --> build
-  ref --> ssr
-```
-
-Launch gate: Wave 0 complete **and** `rtk-to-syncdb-migration-docs`, `positioning-django-rails-universal`, `docs-reference-coverage`, `docs-tutorials-ai-first`, `deploy-to-vercel`, `deploy-to-gcp`, `upgrade-guides-and-skill` complete. `build-terreno-app-validation` is the acceptance test for the whole program — if an agent following only public docs and skills cannot build and deploy the demo app, the launch is not ready.
-
-`agentic-sdlc-plugin` feeds two others: it supplies the process half of the AI-native pillar to `positioning-django-rails-universal`, and once public it becomes something the dogfooding harness in `build-terreno-app-validation` should exercise.
-
-## Blocking questions (program level)
-
-**Recorded 2026-07-29** (defaults accepted for all unspecified items).
-
-| # | Question | Decision |
-|---|----------|----------|
-| P1 | License for the whole monorepo | **MIT everywhere** — relicense `api`/`ui` from Apache-2.0; align `@terreno/mcp` and all published packages |
-| P2 | Copyright / governance model | **B** — Flourish + **DCO** sign-off (`Signed-off-by` on external PRs) |
-| P3 | Public support channel | **A** — GitHub Discussions only at launch |
-| P4 | Hosted MCP URL | **`https://mcp.terreno.app`** — retire `mcp.terreno.flourish.health` before launch |
-| P5 | Flourish-specific infra in the public repo | **C now** — move under `infra/flourish/`; **note to migrate to B** (private repo, generic modules only) post-launch |
-| P6 | Publish `@terreno/rtk` after #869 | **A** — keep publishing with deprecation notice through the current major line; **stop publishing in the next major** |
-| P7 | Launch documentation stack | **A** — **syncdb + Better Auth only** in tutorials, reference, and positioning (no parallel RTK/JWT path in public docs) |
-| P8 | Docs site versioning at launch | **B** — latest + one previous major |
-| P9 | Target npm version for launch | **C** — stay on 0.x; launch on **`0.56.x`** aligned with Expo SDK 56; promise 1.0 after syncdb stabilizes |
-| P10 | Blog post venue | **A** — docs site blog only |
-| P11 | `/terreno-*` SDLC plugin marketplace | **A** — public at launch, gated on portability work in [`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md) |
-
-**Brand / domain:** public surfaces use **`terreno.app`** (MCP at `mcp.terreno.app`, contacts at `@terreno.app`).
-
-Per-IP blocking questions live in each IP file under `## Blocking questions`.
-
-## Not included / future work
-
-- **Vercel deployment topology spike** — whether `@terreno/api` (Socket.io, change streams, SSE) can run on Vercel in one platform with the web app and file storage, or whether a split host remains required. Tracked as open TODOs in [`deploy-to-vercel.md`](deploy-to-vercel.md); do not document a finalized topology until the spike lands.
-- Actual 1.0 API-stability audit.
-- Trademark/brand review of the "Terreno" name.
-- Paid support, sponsorship, or OpenCollective setup.
-- Conference talks / launch-day marketing beyond the blog post.
-- Migrating internal Flourish apps onto syncdb (tracked separately from the OSS launch).

package/src/docs/versioned/0.30.0/implementationPlans/positioning-django-rails-universal.md

@@ -1,146 +0,0 @@
-# Implementation Plan: Positioning — "Django/Rails for TypeScript, with Universal Apps"
-
-**Status:** Draft — blocking questions open
-**Priority:** High
-**Effort:** Small 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) (the architecture diagram and frontend story must be correct before it is repeated everywhere)
-**RTK deprecation flag:** **Partial** — tasks that touch architecture diagrams, package lists, and the integration flow are `[RTK]` marked and must run after #869.
-
-## Goal
-
-Say the same thing about Terreno everywhere, and say it well. Today the README makes a strong, well-written case ("batteries-included framework… Django for Python web development") but the docs landing page says "shared packages for full-stack applications with React Native and Express/Mongoose", `AGENTS.md` says "a monorepo containing shared packages", and npm package descriptions vary. A visitor's impression depends on which door they came through.
-
-The agreed framing, from the program doc:
-
-> **Terreno is Django/Rails for TypeScript — with universal app support.**
-
-Three pillars in priority order: **batteries included**, **universal by default**, **AI-native**.
-
-## Non-Goals
-
-- Adding governance files (that is [`oss-governance-baseline`](oss-governance-baseline.md)).
-- Writing new tutorials or reference pages (those are separate IPs).
-- Visual redesign of the docs site or a logo/brand refresh.
-- Renaming packages or the project.
-
-## Blocking questions
-
-**Recorded 2026-07-29** (defaults accepted).
-
-| # | Decision |
-|---|----------|
-| PO1 | Tagline **A** for README/docs H1; short variant **C** for social/repo description |
-| PO2 | Lead with **Django/Rails** |
-| PO3 | **Universal app** (not cross-platform) |
-| PO4 | AI-native pillar **co-equal** with batteries-included |
-| PO5 | README roadmap: **two-line summary + link `ROADMAP.md`** |
-| PO6 | **Trim README** — move maintainer content to CONTRIBUTING/docs |
-| PO7 | AI pillar names **both** MCP tools and `/terreno-*` pipeline, always paired |
-
-## Architecture
-
-### Canonical copy blocks
-
-Define the wording once, in `docs/explanation/positioning.md`, and have every other surface reuse it verbatim:
-
-| Block | Length | Used by |
-|-------|--------|---------|
-| `tagline` | one line | README H1 subtitle, docs site `tagline`, GitHub repo description, npm `description` prefix |
-| `elevator` | 2–3 sentences | README intro, docs landing intro, package READMEs |
-| `pillars` | three bullets | README, docs landing, `AGENTS.md` |
-| `aiPillar` | 2–3 sentences | Expansion of the third pillar wherever it gets more than a bullet. Must name **both** layers per PO7: the MCP tool layer and the `/terreno-*` process layer |
-| `pitch` | ~150 words | Blog post intro, conference abstracts, social |
-
-### Surfaces to align
-
-| Surface | Current | Action |
-|---------|---------|--------|
-| `README.md` | Strong but long and mixed-audience | Restructure: tagline → elevator → pillars → quickstart → packages → links. Move maintainer content out |
-| `docs/README.md` | "shared packages… React Native and Express/Mongoose" | Replace with tagline + elevator + pillars; add the complete package table |
-| `website/docusaurus.config.ts` | `tagline` field | Set to the canonical tagline; check `title` and og metadata |
-| `website/src/pages/index.tsx` (if present) | unknown | Landing hero uses tagline + pillars + one code sample |
-| `AGENTS.md` / `CLAUDE.md` | "monorepo containing shared packages" | Lead with the positioning so agents describe Terreno correctly to users |
-| `CLAUDE-consumer.md` | consumer-facing template | Lead with the positioning |
-| Every published `package.json` `description` | inconsistent | Standardize: `<what it does> — part of Terreno, the batteries-included TypeScript framework for universal apps.` |
-| Package READMEs | some are stubs pointing at `.claude/` | Handled by [`docs-reference-coverage`](docs-reference-coverage.md); this IP supplies the shared intro block |
-| GitHub repo description + topics | unknown | Set description to the short variant; add topics (`typescript`, `react-native`, `expo`, `express`, `mongoose`, `framework`, `mcp`, `ai`, `universal-apps`) |
-
-### The comparison table
-
-The Django/Rails claim invites the obvious question. `docs/explanation/positioning.md` should answer it head-on with an honest table — what maps, what does not:
-
-| Django / Rails concept | Terreno equivalent | Honest caveat |
-|------------------------|--------------------|----------------|
-| Models + ORM | Mongoose schemas + `@terreno/api` plugins | Document store, not relational; no migrations framework |
-| `ModelViewSet` / scaffolds | `modelRouter` | REST only; no GraphQL |
-| Django admin | `@terreno/admin-backend` + `admin-frontend` / `admin-spa` | Younger; see the admin parity IP for the gap list |
-| Auth + permissions | Better Auth + `Permissions` | RBAC is in progress (`rbac-permissions.md`) |
-| Templates / views | `@terreno/ui` components, one codebase for iOS/Android/web | SSR is not shipped yet — see [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md) |
-| `manage.py` / generators | MCP server tools (the *tool* layer) + the `/terreno-*` SDLC pipeline (the *process* layer) | Agent-driven rather than CLI-driven. Django gives you `manage.py startapp`; Terreno gives you a reviewed path from a request to a mergeable PR |
-| Celery / ActiveJob | Not shipped | On the roadmap |
-| Migrations | No migrations framework | Schema evolution is convention + the `mongoose-schema-safety` skill |
-
-Being straight about the gaps is what makes the analogy credible rather than marketing.
-
-## Models / APIs / Notifications
-
-None.
-
-## UI
-
-Docs site landing page and README only. No application UI.
-
-## Phases
-
-1. **Canonical copy** — write `docs/explanation/positioning.md` with the five copy blocks and the comparison table.
-2. **README restructure** — apply the new structure, move maintainer content out.
-3. **Docs site** — landing page, config tagline, docs index.
-4. **Agent surfaces** — `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`, and the MCP overview resource.
-5. **Metadata** — `package.json` descriptions, GitHub repo description and topics.
-
-## Feature Flags & Migrations
-
-None. Moving README sections to `CONTRIBUTING.md` and `docs/` requires checking for inbound links from the docs site and agent rules.
-
-## Not Included / Future Work
-
-- Logo, brand palette, or docs site visual redesign.
-- Landing-page marketing site separate from the docs site.
-- Case studies or testimonials.
-- Renaming `@terreno/*` packages.
-
-## Files to Create / Modify
-
-**Create**
-
-- `docs/explanation/positioning.md`
-
-**Modify**
-
-- `README.md`
-- `docs/README.md`
-- `website/docusaurus.config.ts`, `website/src/pages/index.tsx` (if it exists)
-- `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`, `.rulesync/rules/00-root.md`
-- `CONTRIBUTING.md` (receives the maintainer content moved out of the README)
-- `mcp-server/src/docs/resources/overview.md`
-- Every published `package.json` (`description` field)
-
-## Task List
-
-See [`docs/tasks/positioning-django-rails-universal.md`](../tasks/positioning-django-rails-universal.md).
-
-## Acceptance Criteria
-
-- [ ] `docs/explanation/positioning.md` defines the five copy blocks and the honest comparison table.
-- [ ] The canonical tagline appears verbatim in `README.md`, `docs/README.md`, `website/docusaurus.config.ts`, and the GitHub repo description.
-- [ ] The phrase "Django/Rails for TypeScript" appears within the first two sentences of both `README.md` and `docs/README.md`.
-- [ ] "universal app" is the term used for the frontend in all five surfaces; no surface says "cross-platform".
-- [ ] The three pillars appear in the same order with consistent wording in `README.md`, `docs/README.md`, and `AGENTS.md`.
-- [ ] `README.md` contains no Flourish-internal instructions, GCP project names, or the feature-flag migration walkthrough; that content lives in `CONTRIBUTING.md`, `infra/flourish/`, or `docs/how-to/`.
-- [ ] Every published package's `description` follows the standard pattern and mentions Terreno.
-- [ ] The comparison table lists at least three honest gaps and links the IPs tracking them.
-- [ ] No surface claims an unshipped feature as available.
-- [ ] `bun run website:build` and `bun run rules:check` pass.

package/src/docs/versioned/0.30.0/implementationPlans/public-roadmap-github.md

@@ -1,204 +0,0 @@
-# Implementation Plan: Public Roadmap on GitHub
-
-**Status:** Approved — decisions recorded (2026-07-29)
-**Priority:** High
-**Effort:** Small batch
-**Owner:** unassigned
-**Created:** 2026-07-27
-**Program:** [OSS launch](oss-launch-program.md)
-**Depends on:** [`oss-governance-baseline`](oss-governance-baseline.md) (issue templates land there)
-**RTK deprecation flag:** None — process and metadata only. Safe to implement before PR #869.
-
-## Goal
-
-Run Terreno's roadmap in public on GitHub while keeping Linear as the internal execution tracker. Outside users need to see what is planned, argue about priorities, and file well-shaped requests; Flourish engineers need to keep sprinting in Linear without double-entry.
-
-The design principle: **one direction of truth per artifact.** Public discussion and roadmap state live on GitHub. Sprint execution, estimates, and assignees live in Linear. IPs in `docs/implementationPlans/` remain the design source of truth for both.
-
-## Non-Goals
-
-- Migrating Flourish's internal work off Linear.
-- Building a custom sync service between Linear and GitHub.
-- Publishing internal Flourish product roadmap items that happen to touch Terreno.
-- Public sprint planning or estimates.
-
-## Blocking questions
-
-**Recorded 2026-07-29** (defaults accepted).
-
-| # | Decision |
-|---|----------|
-| R1 | Target **release version** on the roadmap (`0.28`, `0.29`, `Future`) — no calendar dates |
-| R2 | GitHub Project board + **generated `ROADMAP.md`** |
-| R3 | Linear GitHub sync on issues labeled **`tracked`** (one-way GitHub → Linear) |
-| R4 | **Maintainers only** open board items; users file Ideas discussions |
-| R5 | **One tracking issue per IP**, opened manually when IP reaches Approved |
-| R6 | **Post-moderated** Discussions |
-| R7 | Lightweight **RFC** discussion category → graduates to IP |
-
-## Architecture
-
-### Three surfaces, one flow
-
-```mermaid
-flowchart LR
-  subgraph public ["Public (GitHub)"]
-    D["Discussions<br/>Ideas / Q&A / RFC"]
-    I["Issues<br/>triaged work"]
-    P["Project: Terreno Roadmap"]
-    RM["ROADMAP.md<br/>generated"]
-  end
-  subgraph design ["Design (repo)"]
-    IP["docs/implementationPlans/*.md"]
-  end
-  subgraph internal ["Internal"]
-    L["Linear"]
-  end
-  D -->|"maintainer promotes"| I
-  I -->|"triage: add to board"| P
-  P -->|"nightly generate"| RM
-  I -->|"label: tracked"| L
-  IP -->|"Approved → tracking issue"| I
-  D -->|"RFC accepted"| IP
-```
-
-### Discussion categories
-
-| Category | Format | Purpose | Who posts |
-|----------|--------|---------|-----------|
-| **Announcements** | Announcement | Releases, breaking changes, deprecations (including the RTK → syncdb deprecation), launch posts | Maintainers only |
-| **Q&A** | Question / Answer | "How do I…" support questions. Answers marked accepted; recurring ones graduate into `docs/how-to/` | Anyone |
-| **Ideas** | Open-ended | Feature requests before they are shaped. The intake funnel — nothing goes straight to an issue | Anyone |
-| **RFCs** | Open-ended | Proposals that change public API or add a package. Graduates into an IP when accepted | Anyone, template-guided |
-| **Show and tell** | Open-ended | Apps built with Terreno. Social proof, and a source of real-world friction reports | Anyone |
-| **Agents & AI** | Open-ended | MCP setup, skills, agent workflows, prompt patterns. Deliberately separate — it is the differentiator and deserves a visible home | Anyone |
-| **Docs feedback** | Open-ended | Per-page feedback; linked from every docs page footer | Anyone |
-
-Category ordering in the UI should be: Announcements, Q&A, Ideas, Agents & AI, RFCs, Show and tell, Docs feedback.
-
-### Project board
-
-One org- or repo-level Project named **Terreno Roadmap**, board layout, grouped by `Status`.
-
-**Fields**
-
-| Field | Type | Values | Notes |
-|-------|------|--------|-------|
-| `Status` | single select | `Inbox`, `Shaping`, `Planned`, `In progress`, `In review`, `Shipped`, `Declined` | `Inbox` = triaged but not committed |
-| `Area` | single select | `api`, `ui`, `syncdb`, `auth`, `admin`, `ai`, `mcp`, `docs`, `deploy`, `examples`, `dx` | Mirrors package boundaries plus cross-cutting areas |
-| `Target` | single select | `0.28`, `0.29`, `Next`, `Future` | Per R1; add versions as releases approach |
-| `IP` | text | e.g. `web-ssr-and-admin-spa` | Slug of the IP file, empty if no IP yet |
-| `Impact` | single select | `Breaking`, `Feature`, `Improvement`, `Fix` | Drives changelog grouping |
-| `Community interest` | number | 👍 count, refreshed on triage | Makes prioritization legible |
-
-**Views**
-
-1. **Roadmap** (board, grouped by `Status`, filtered to `Status != Declined`) — the default public view.
-2. **By area** (table, grouped by `Area`) — for contributors looking for something to pick up.
-3. **Next release** (table, filtered to `Target = <current+1>`) — what is actually landing.
-4. **Needs shaping** (table, filtered to `Status = Shaping`) — where community input changes outcomes.
-
-### Label taxonomy
-
-Keep it small enough to be used consistently.
-
-| Prefix | Labels | Purpose |
-|--------|--------|---------|
-| `area:` | `area:api`, `area:ui`, `area:syncdb`, `area:auth`, `area:admin`, `area:ai`, `area:mcp`, `area:docs`, `area:deploy`, `area:examples`, `area:dx` | Matches the `Area` project field |
-| `type:` | `type:bug`, `type:feature`, `type:docs`, `type:chore`, `type:rfc` | Set by issue forms where possible |
-| `status:` | `status:needs-triage`, `status:needs-info`, `status:blocked`, `status:wontfix` | Workflow state that is not board state |
-| (bare) | `good first issue`, `help wanted`, `breaking`, `tracked`, `deprecation` | `tracked` triggers the Linear sync; `deprecation` marks RTK-migration work |
-
-### Linear bridge
-
-- Linear's GitHub integration is configured to import GitHub issues labeled `tracked` into the Terreno Linear team.
-- Direction: GitHub → Linear for creation and title/description; status is **not** synced automatically. When a Linear issue closes, the engineer closes the GitHub issue in the same PR (`Fixes #NNN`), which moves the board to `Shipped`.
-- Linear issues created internally that will become public work get a GitHub issue opened manually and the Linear URL pasted into it. No automation in that direction.
-- Internal-only Linear work is never mirrored.
-
-Rationale: two-way status sync between trackers reliably produces confusing loops. One-way intake plus `Fixes #NNN` on merge gives correct public state with no maintenance.
-
-### Automation
-
-Three GitHub Actions workflows:
-
-1. **`roadmap-generate.yml`** — on a schedule and on Project item changes, query the Project via the GraphQL API and regenerate `ROADMAP.md` (grouped by `Target`, then `Area`, with links to issues and IPs). Commits only when the content changes.
-2. **`triage.yml`** — on issue open: apply `status:needs-triage`, and apply the `area:*` label derived from the issue form's package dropdown.
-3. **`discussion-to-issue.yml`** — optional; when a maintainer adds the `promote` label to a Discussion (or comments `/promote`), open a linked issue pre-filled from the discussion body. Skip in v1 if the GraphQL surface proves fiddly; manual promotion is acceptable.
-
-## Models
-
-None (GitHub metadata only).
-
-## APIs
-
-GitHub GraphQL API (`ProjectV2` queries) is used read-only by `roadmap-generate.yml`. Requires a token with `project: read` and `contents: write`; use the built-in `GITHUB_TOKEN` if org settings permit Projects access, otherwise a fine-grained PAT stored as a secret and validated at job start per the repo's required-secret-validation convention.
-
-## Notifications
-
-None beyond GitHub's own subscriptions. Announcements category posts should be the release channel; the `release` skill gains a step to post one for releases with breaking changes.
-
-## UI
-
-- `ROADMAP.md` at the repo root, linked from `README.md` and the docs site sidebar.
-- A "Discuss this page" footer link on docs pages pointing at the Docs feedback category (implemented in the Docusaurus theme config).
-
-## Phases
-
-1. **Discussions** — enable, create categories, seed each with a pinned intro post, add the RFC template.
-2. **Project board** — create the Project, fields, and views; backfill items from `PLAN_INDEX.md` and the IPs in this program.
-3. **Labels and triage** — create the label set, delete unused defaults, add `triage.yml`.
-4. **Roadmap generation** — `ROADMAP.md` + `roadmap-generate.yml`, link from README and docs site.
-5. **Linear bridge** — configure the integration, document the process in `CONTRIBUTING.md`, and record the rules in a maintainer doc.
-
-## Feature Flags & Migrations
-
-None. Existing open issues need a one-time triage pass to apply the new labels and land on the board (Task 3.3).
-
-## Activity Log & User Updates
-
-None.
-
-## Not Included / Future Work
-
-- Public voting/prioritization beyond 👍 reactions.
-- Automated changelog generation from board state.
-- A status page or uptime dashboard for the hosted MCP server.
-- Contributor recognition automation (all-contributors bot).
-
-## Files to Create / Modify
-
-**Create**
-
-- `ROADMAP.md`
-- `.github/DISCUSSION_TEMPLATE/rfc.yml`
-- `.github/DISCUSSION_TEMPLATE/ideas.yml`
-- `.github/workflows/roadmap-generate.yml`
-- `.github/workflows/triage.yml`
-- `docs/explanation/roadmap-process.md`
-- `scripts/generate-roadmap.ts`
-
-**Modify**
-
-- `README.md` (link `ROADMAP.md` and Discussions)
-- `CONTRIBUTING.md` (intake flow: Discussions → issue → board; RFC path)
-- `website/docusaurus.config.ts` (docs feedback footer link, roadmap sidebar entry)
-- `.rulesync/skills/release/SKILL.md` (post an Announcements discussion for breaking releases)
-- `.github/ISSUE_TEMPLATE/*.yml` (add `type:` labels via the `labels:` key)
-
-## Task List
-
-See [`docs/tasks/public-roadmap-github.md`](../tasks/public-roadmap-github.md).
-
-## Acceptance Criteria
-
-- [ ] All seven Discussion categories exist with the specified formats and a pinned intro post each.
-- [ ] The **Terreno Roadmap** Project exists with the six fields and four views described above.
-- [ ] Every IP in `docs/implementationPlans/PLAN_INDEX.md` marked Approved or later has a tracking issue on the board with its `IP` field set to the IP slug.
-- [ ] The label set matches the taxonomy table; no unused GitHub default labels remain.
-- [ ] `bun run scripts/generate-roadmap.ts` produces `ROADMAP.md` grouped by `Target` then `Area`, and `roadmap-generate.yml` commits it only when changed.
-- [ ] Opening a new issue applies `status:needs-triage` and the correct `area:*` label automatically.
-- [ ] Adding `tracked` to a GitHub issue creates a corresponding Linear issue; closing the Linear issue does **not** silently change GitHub state.
-- [ ] `CONTRIBUTING.md` documents the intake flow and the RFC path in under 30 lines.
-- [ ] `docs/explanation/roadmap-process.md` explains the GitHub/Linear split, including why status is not two-way synced.
-- [ ] Every docs page shows a working "Discuss this page" link.