@terreno/mcp 0.28.0 → 0.29.0

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

@@ -0,0 +1,146 @@
+# 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.28.0/implementationPlans/public-roadmap-github.md

@@ -0,0 +1,204 @@
+# 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.