@terreno/mcp 56.0.0-beta.0 → 56.0.0-beta.2

package/dist/docs/versioned/next/explanation/positioning.md

@@ -0,0 +1,164 @@
+# Positioning
+
+This is the single source of truth for how Terreno describes itself. The problem
+this page exists to fix is drift: the README, the docs landing page, `AGENTS.md`,
+and the npm package descriptions have historically said different things, so a
+visitor's impression of Terreno depended on which door they walked through.
+
+The rule is simple: **write the wording once, here, then reuse it verbatim
+everywhere else.** Do not paraphrase per surface.
+
+## Canonical copy blocks
+
+Copy these blocks exactly. They are in fenced code blocks so they can be lifted
+without markdown-rendering surprises.
+
+### `tagline`
+
+Used by: README H1 subtitle, docs site `tagline`, npm `description` prefix.
+
+```
+Terreno is Django/Rails for TypeScript — with universal app support.
+```
+
+### `elevator`
+
+Used by: README intro, docs landing intro, package READMEs.
+
+```
+Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
+framework where the undifferentiated 80% of an app is already written. On the
+backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
+panel, authentication, and an AI service. On the frontend you get one universal
+app — a single React Native codebase that ships to iOS, Android, and web. It is
+built to be driven by AI coding agents from the first prompt to a production
+deploy.
+```
+
+### `pillars`
+
+Used by: README, docs landing, `AGENTS.md`. Keep the order.
+
+```
+- Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
+  feature flags, and consent are already built, so your code is business logic.
+- Universal by default — one React Native codebase ships to iOS, Android, and
+  web. Not a web framework with a mobile bolt-on.
+- AI-native — agents are a first-class client of the framework, not an
+  afterthought.
+```
+
+### `aiPillar`
+
+Used wherever the AI-native pillar gets more than a bullet. It must always name
+**both** layers (see language rule 5).
+
+```
+Terreno's AI-native story has two layers. The tool layer is a Model Context
+Protocol (MCP) server that gives coding agents codegen, documentation search,
+and component reference for the framework's conventions. The process layer is the
+`/terreno-*` SDLC pipeline — plan, implement test-first, verify in a fresh
+context, submit with evidence, then own the review loop — which today runs inside
+the Terreno repository while its consumer-installable packaging is finished.
+Django gives you `manage.py startapp`; Terreno is building a reviewed path from a
+request to a mergeable pull request.
+```
+
+> **Portability gate (do not remove until cleared).** The `/terreno-*` pipeline
+> is not yet verified to run in a consumer application — that is
+> [`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5,
+> which is still open. Until it passes, describe the pipeline as in-progress
+> packaging (as the `aiPillar` block above does) and never imply a consumer can
+> install and run it today. When Task 2.5 passes, update the `aiPillar` block to
+> claim the pipeline as consumer-ready.
+
+### `pitch`
+
+Used by: blog post intros, conference abstracts, social. ~150 words.
+
+```
+Every app needs the same foundation: authentication, user management, CRUD APIs,
+an admin panel, permissions, realtime updates, feature flags, and AI. That work
+is weeks of undifferentiated effort, and it is the same in every product.
+
+Terreno is Django/Rails for TypeScript. Define a Mongoose model, register it, and
+you have a permissioned REST API with pagination, filtering, and an OpenAPI spec.
+Add the admin package and you have a working admin panel. Your app is left with
+the part that is actually yours: the business logic.
+
+The difference from Django or Rails is universal apps — one React Native codebase
+ships to iOS, Android, and web — and being AI-native. Agents are a first-class
+client: an MCP server teaches them the conventions, and a reviewed SDLC pipeline
+takes a request to a mergeable pull request. You build with AI from the first
+prompt to production.
+```
+
+## Why the Django/Rails analogy
+
+Django and Rails won by deciding that the generic parts of a web app — the ORM,
+the router, the admin, auth — belong in the framework, not in every project. They
+are opinionated, batteries-included, and productive because of it. Terreno makes
+the same bet for TypeScript: the generic 80% of an app lives in the framework so
+your codebase is the 20% that is unique to your product.
+
+The analogy earns two honest caveats. First, Terreno targets a document store
+(MongoDB via Mongoose), not a relational ORM, and it has no migrations framework.
+Second, it is younger — several Django/Rails staples (background jobs,
+server-side rendering, role-based access control) are not shipped yet. The
+comparison table below is deliberately straight about where the analogy holds and
+where it does not; being honest about the gaps is what makes the analogy credible
+rather than marketing.
+
+The two things Django and Rails do not give you, and Terreno does, are **universal
+apps** (one codebase for iOS, Android, and web) and being **AI-native** by design.
+
+## Comparison table
+
+Every "shipped" row cites where the feature lives in the source. Every "not
+shipped" row links the implementation plan or roadmap item that tracks it.
+
+| Django / Rails concept | Terreno equivalent | Honest caveat |
+|------------------------|--------------------|----------------|
+| Models + ORM | Mongoose schemas + `@terreno/api` plugins (`api/src/plugins.ts`) | Document store, not relational; no migrations framework (see the Migrations row) |
+| `ModelViewSet` / scaffolds | `modelRouter` (`api/src/api.ts`) | REST only; no GraphQL |
+| Django admin | `@terreno/admin-backend` + `@terreno/admin-frontend` / `@terreno/admin-spa` | Younger; the parity gap is tracked in [`admin-ui-v2-django-parity`](../implementationPlans/admin-ui-v2-django-parity.md) |
+| Auth + permissions | Better Auth (`api/src/betterAuthApp.ts`) + `Permissions` (`api/src/permissions.ts`) | Fine-grained RBAC is in progress ([`rbac-permissions`](../implementationPlans/rbac-permissions.md)) |
+| Templates / views | `@terreno/ui` components — one universal codebase for iOS, Android, and web | Server-side rendering for web is not shipped yet ([`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md)) |
+| `manage.py` / generators | MCP server tools — the *tool* layer (`mcp-server/src/tools.ts`) + the `/terreno-*` SDLC pipeline — the *process* layer (`plugins/terreno-planning/skills/`) | Agent-driven rather than CLI-driven; the pipeline is not yet packaged for consumer apps ([`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5) |
+| Celery / ActiveJob (background jobs) | Not shipped | On the [roadmap](../../ROADMAP.md) |
+| Migrations | No migrations framework | Schema evolution is convention plus the `mongoose-schema-safety` skill (`.claude/skills/mongoose-schema-safety/`) |
+
+## Language rules
+
+Every doc, README, landing page, and agent-facing surface follows these rules.
+
+1. **Lead with the analogy.** Say "Django/Rails for TypeScript" within the first
+   two sentences of the README and the docs landing page.
+2. **Say "universal app,"** not "cross-platform" and not "React Native app," when
+   describing the frontend. It is one codebase that ships to iOS, Android, and
+   web.
+3. **Never claim an unshipped feature as available.** If a capability is on the
+   roadmap or tracked by an open IP, say so. Grep the package source before
+   writing that something ships.
+4. **Keep superlatives off reference pages.** "The best framework for X" belongs
+   on the landing page and the pitch, never in reference documentation.
+5. **Never describe one AI layer without the other.** The tool layer (MCP server)
+   and the process layer (`/terreno-*` pipeline) are always named together, and
+   the pipeline is described honestly per the portability gate above.
+
+## Repository metadata (maintainer action)
+
+The GitHub repository description and topics cannot be set from a commit. A
+maintainer must set them in **Settings → General** and the **About** panel.
+
+**Description** (the short tagline variant):
+
+```
+Django/Rails for TypeScript, with universal iOS/Android/web apps.
+```
+
+**Topics:**
+
+```
+typescript, react-native, expo, express, mongoose, framework, mcp, ai, universal-apps, full-stack
+```

package/dist/docs/versioned/next/explanation/repository-settings.md

@@ -0,0 +1,44 @@
+# Repository settings (maintainers)
+
+Some GitHub settings cannot be committed to the repo. Enable these manually in
+the [Terreno repository settings](https://github.com/FlourishHealth/terreno/settings).
+
+## Discussions
+
+**Path:** Settings → General → Features → Discussions
+
+Enable Discussions and create these categories (see
+[public roadmap IP](../implementationPlans/public-roadmap-github.md) for
+descriptions):
+
+1. Announcements (maintainers only)
+2. Q&A
+3. Ideas
+4. Agents & AI
+5. RFCs
+6. Show and tell
+7. Docs feedback
+
+## Security
+
+**Path:** Settings → Security → Code security and analysis
+
+- Enable **Private vulnerability reporting** (GitHub PVR as the primary channel;
+  `security@terreno.app` is the email fallback — see [SECURITY.md](../../SECURITY.md))
+
+## Branch protection (`master`)
+
+**Path:** Settings → Branches → Branch protection rules → `master`
+
+- Require a pull request before merging
+- Require status checks to pass (include Repository policies, package CI, and
+  Rulesync Check jobs relevant to the change)
+- Require branches to be up to date before merging
+- Do not allow bypassing the above settings
+
+## Merge settings
+
+**Path:** Settings → General → Pull Requests
+
+- Allow **squash merging** only (disable merge commits and rebase merging)
+- Enable **Automatically delete head branches** after merge

package/dist/docs/versioned/next/explanation/roadmap-process.md

@@ -0,0 +1,330 @@
+# Public roadmap process
+
+Terreno runs its **public roadmap on GitHub** and keeps **sprint execution in Linear**.
+Implementation plans in `docs/implementationPlans/` remain the design source of truth for
+both.
+
+- **GitHub** — discussions, triaged issues, the Terreno Roadmap project board, generated
+  [`ROADMAP.md`](https://github.com/FlourishHealth/terreno/blob/master/ROADMAP.md)
+- **Linear** — estimates, assignees, sprint workflow (internal)
+- **IPs** — approved design docs before substantial cross-package work
+
+See also [CONTRIBUTING.md](https://github.com/FlourishHealth/terreno/blob/master/CONTRIBUTING.md) for the contributor intake flow.
+
+## How work flows (IP ↔ roadmap)
+
+One idea travels through discussion, a tracking issue, a design doc, implementation, and
+release. Each artifact is authoritative for exactly one thing, so nothing is entered twice.
+
+```
+Discussion (Ideas/RFC)
+    │  maintainer accepts  →  roadmap-promote
+    ▼
+Issue: Status = Shaping ─────────────────────────────┐
+                                                      │  IP approved → roadmap-item
+Blend writes IP + task list  ────────────────────────┤  (sets IP field, Shaping → Planned)
+(docs/implementationPlans/ + docs/tasks/)             ▼
+                                          Issue: Status = Planned
+                                                      │  Roast → Cupping → Pour
+                                                      ▼
+                                          PR: Fixes #NNN
+                                                      │  merge
+                                                      ▼
+                                  Issue closed · board: Shipped
+```
+
+The planning pipeline (the `terreno-planning` plugin) drives the design-and-build half;
+the roadmap skills drive the public-tracking half. They meet at one handoff: **Blend
+writes the IP, and once it is Approved hands off to `roadmap-item`.**
+
+| Transition | Who owns it | Authoritative artifact |
+| ---------- | ----------- | ---------------------- |
+| Idea debated and shaped | Community + maintainers | GitHub Discussion |
+| Discussion → first tracking issue (`Shaping`) | `roadmap-promote` | GitHub Issue + Project |
+| Design, scope, acceptance criteria | `terreno-1-blend` / `ip` | `docs/implementationPlans/<slug>.md` |
+| Task breakdown for implementation | `terreno-1-blend` / `ip` | `docs/tasks/<slug>.md` |
+| Approved IP → issue `Planned` + `IP` field set | `roadmap-item` | GitHub Issue + Project |
+| Implement, verify, submit, review | `terreno-2-roast` … `terreno-5-dialin` | the PR |
+| Sprint estimates, assignees, internal-only work | Linear | Linear |
+| Public rendered list | CI (`roadmap:generate`) | `ROADMAP.md` |
+
+**promote vs item — the one ambiguity worth stating plainly:** `roadmap-promote` opens the
+issue for community-originated work at `Shaping` and never sets the `IP` field or `Planned`.
+`roadmap-item` is the only skill that sets the `IP` field and moves an item to `Planned`,
+and it **updates the promoted issue** rather than opening a second one. Internal-origin work
+with no discussion skips promote and starts at `roadmap-item`.
+
+### Repos without a public roadmap
+
+The `terreno-planning` plugin is meant to run in any Terreno repo, including ones with no
+Discussions and no roadmap board (Flourish, most consumer apps). There, only the design-and-build
+half applies:
+
+- **Blend** still writes the IP + task list — that dual-file model is the source of truth
+  everywhere. It detects the absence of `.github/roadmap-fields.yml` and the `roadmap-item`
+  skill and **skips the roadmap handoff** instead of inventing issues or labels.
+- Sprint execution is tracked in Linear and linked from the IP header; it is never copied
+  into the plan.
+- The `roadmap-*` skills and everything under [Maintainer setup](#maintainer-setup) only
+  apply once a repo adopts the public roadmap.
+
+## Maintainer setup
+
+> **Human action required.** Cloud agents cannot mutate GitHub org/repo settings. Run these
+> steps once per environment.
+
+### Enable Discussions
+
+1. GitHub → **Settings** → **General** → **Features** → enable **Discussions**.
+2. Create the categories below in **Discussions** → **⚙️ Categories** (display order top to
+   bottom).
+
+| Order | Name | Format | Who can post | Description (paste into GitHub) |
+| ----- | ---- | ------ | ------------ | --------------------------------- |
+| 1 | Announcements | Announcement | Maintainers only | Official release notes, breaking changes, deprecations, and launch updates from the Terreno team. |
+| 2 | Q&A | Question / Answer | Anyone | Ask how to use Terreno. Search existing threads first; accepted answers may become how-to guides in `docs/how-to/`. |
+| 3 | Ideas | Open-ended | Anyone | Feature ideas and improvements before they are shaped. This is the intake funnel — do not open a tracking issue until a maintainer promotes your idea. |
+| 4 | Agents & AI | Open-ended | Anyone | MCP setup, Cursor/Claude skills, agent workflows, and prompt patterns for building with Terreno. |
+| 5 | RFCs | Open-ended | Anyone | Substantial proposals that change public API or add packages. Use the RFC discussion template; accepted RFCs become IPs. |
+| 6 | Show and tell | Open-ended | Anyone | Apps and experiments built with Terreno. Share what you shipped and what friction you hit. |
+| 7 | Docs feedback | Open-ended | Anyone | Report missing or confusing documentation. Link the page URL; recurring feedback becomes docs PRs. |
+
+### Pinned posts
+
+Pin one intro post per category after creation. Bodies below are ready to paste.
+
+#### Announcements
+
+```markdown
+Release announcements, breaking changes, and deprecation notices land here.
+
+- Do **not** file support bugs as announcements — use [Issues](https://github.com/FlourishHealth/terreno/issues/new/choose) or Q&A.
+- Security issues: see [SECURITY.md](https://github.com/FlourishHealth/terreno/blob/master/SECURITY.md) (private report only).
+```
+
+#### Q&A
+
+```markdown
+Ask **how** to use Terreno — setup, APIs, deployment, agents.
+
+1. Search [existing Q&A](https://github.com/FlourishHealth/terreno/discussions/categories/q-a) and the [docs site](https://terreno-docs.netlify.app/).
+2. For step-by-step guides, start with [`docs/how-to/`](https://github.com/FlourishHealth/terreno/tree/master/docs/how-to).
+3. Bug reports belong in [Bug report issues](https://github.com/FlourishHealth/terreno/issues/new?template=bug_report.yml), not here.
+
+When an answer repeats, maintainers turn it into a how-to doc via PR.
+```
+
+#### Ideas
+
+```markdown
+**Ideas are the intake funnel.** Share problems and rough solutions before they become roadmap items.
+
+- Do **not** open a feature issue directly — maintainers promote accepted ideas to tracked issues on the [Terreno Roadmap](https://github.com/FlourishHealth/terreno/projects) board.
+- For API/package-level design, use the **RFCs** category instead.
+- Bugs → [Bug report](https://github.com/FlourishHealth/terreno/issues/new?template=bug_report.yml).
+```
+
+#### Agents & AI
+
+```markdown
+MCP server setup, Cursor/Claude skills, and agent-driven workflows.
+
+- MCP package: [`mcp-server/`](https://github.com/FlourishHealth/terreno/tree/master/mcp-server) and hosted `terreno-mcp`.
+- Agent skills: [`.rulesync/skills/`](https://github.com/FlourishHealth/terreno/tree/master/.rulesync/skills) (mirrored to `.cursor/`, `.claude/`, etc.).
+- Terreno planning plugin: [`plugins/terreno-planning/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning).
+
+General feature ideas → **Ideas**. Doc typos → **Docs feedback** or a docs PR.
+```
+
+#### RFCs
+
+```markdown
+Propose changes to **public API**, **new published packages**, or **cross-package architecture**.
+
+Use the [RFC template](https://github.com/FlourishHealth/terreno/discussions/new?category=rfcs) (Summary, Motivation, Design, Alternatives).
+
+Accepted RFCs become implementation plans in `docs/implementationPlans/` before large code changes. Small bugs and docs fixes do not need an RFC.
+```
+
+#### Show and tell
+
+```markdown
+Show what you built with Terreno — screenshots, repos, and lessons learned welcome.
+
+Friction you discover may become Ideas, bugs, or docs PRs. This category is for celebration and learning, not support tickets.
+```
+
+#### Docs feedback
+
+```markdown
+Report missing, outdated, or confusing documentation.
+
+Include the **page URL** (docs site or `docs/` path). For quick fixes, open a PR instead.
+
+Every docs page also has a **Discuss this page** link in the footer.
+```
+
+### Project board
+
+Create one GitHub Project named **Terreno Roadmap** (repo-level is fine; org-level also
+works). Link it to `FlourishHealth/terreno`.
+
+**Fields** (single-select unless noted):
+
+| Field | Type | Options |
+| ----- | ---- | ------- |
+| Status | Single select | `Inbox`, `Shaping`, `Planned`, `In progress`, `In review`, `Shipped`, `Declined` |
+| Area | Single select | `api`, `ui`, `syncdb`, `auth`, `admin`, `ai`, `mcp`, `docs`, `deploy`, `examples`, `dx` |
+| Target | Single select | `0.28`, `0.29`, `Next`, `Future` (add version labels as releases approach) |
+| IP | Text | Slug e.g. `web-ssr-and-admin-spa` (empty when no IP yet) |
+| Impact | Single select | `Breaking`, `Feature`, `Improvement`, `Fix` |
+| Community interest | Number | 👍 count — refresh manually on triage |
+
+**Views**
+
+1. **Roadmap** — Board layout, group by `Status`, filter `Status != Declined` (default public view).
+2. **By area** — Table, group by `Area`.
+3. **Next release** — Table, filter `Target = Next` (update filter when cutting a release).
+4. **Needs shaping** — Table, filter `Status = Shaping`.
+
+**CLI (partial support)**
+
+```bash
+gh project list --owner FlourishHealth --limit 20
+gh project link <project-number> --owner FlourishHealth --repo FlourishHealth/terreno
+```
+
+Field and view creation is **UI-only** today — recreate the tables above in the Project
+settings.
+
+**Backfill:** paste tracking issues from [`roadmap-seed-issues.md`](roadmap-seed-issues.md)
+when each IP reaches **Approved**.
+
+### Labels
+
+[`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml) is the source of truth.
+
+Apply or update labels with `gh` authenticated as a maintainer:
+
+```bash
+bun run labels:sync --repo FlourishHealth/terreno --dry-run   # preview
+bun run labels:sync --repo FlourishHealth/terreno             # apply
+```
+
+[`scripts/sync-labels.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/sync-labels.ts)
+parses the YAML and passes each description to `gh` as a single argument, so descriptions
+containing commas or quotes survive intact. It refuses to run on a malformed color,
+a missing description, or a duplicate name.
+
+Delete unused GitHub defaults after the new taxonomy is applied (`gh label list`).
+
+### Secrets for roadmap generation
+
+| Name | Kind | Purpose |
+| ---- | ---- | ------- |
+| `TERRENO_PROJECT_NUMBER` | Repository variable | GitHub Project number for **Terreno Roadmap** |
+| `ROADMAP_PROJECT_TOKEN` | Repository secret | Classic PAT with `read:project` (plus `repo` for private repos) |
+
+The workflow's built-in `GITHUB_TOKEN` **cannot** be used here: it is repository-scoped and
+returns no `projectV2` data for an organization project. GitHub also reserves the name
+`GITHUB_TOKEN`, so a PAT cannot be supplied under that name — hence the separate
+`ROADMAP_PROJECT_TOKEN` secret. Pushing the regenerated `ROADMAP.md` still uses the default
+token via `permissions: contents: write`.
+
+Locally, export the PAT as `GITHUB_TOKEN` (for example `GITHUB_TOKEN=$(gh auth token)`), which
+is the variable the generator reads.
+
+## Maintainer skills
+
+Four agent skills cover the recurring roadmap work. Each one researches, proposes, and then
+**stops for a maintainer to approve** before touching GitHub — roadmap decisions are the most
+human part of the process, so none of them mutate state on their own. All four are
+`disable-model-invocation`, meaning an agent will not start them on its own initiative;
+you invoke them explicitly.
+
+| Skill | Use it when |
+| ----- | ----------- |
+| `roadmap-triage` | An inbound issue or discussion needs `area:*` / `type:*` / `status:*` labels, or a call on whether it belongs on the board |
+| `roadmap-promote` | Maintainers accepted an Ideas or RFC discussion and it needs a tracked issue that links back to the thread |
+| `roadmap-item` | An approved IP needs its public tracking issue, or an existing entry's scope changed |
+| `roadmap-review` | Recurring hygiene: status drift, stale items, untriaged backlog, promotion candidates, then regenerate `ROADMAP.md` |
+
+Sources live in `.rulesync/skills/`; run `bun run rules` after editing to regenerate the
+per-agent mirrors.
+
+### Checking an item before you file it
+
+The skills do not carry a copy of the taxonomy. They call:
+
+```bash
+bun run roadmap:check --labels "area:api,type:feature" --status Planned --target Next --impact Feature --area api
+```
+
+Run it with no arguments to print every valid label and field option. It enforces exactly one
+`area:*` and one `type:*` label, rejects labels absent from
+[`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml),
+rejects Project values absent from
+[`.github/roadmap-fields.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/roadmap-fields.yml),
+and catches an `Area` field that disagrees with the issue's `area:` label.
+
+Those two files are the single source for the taxonomy: labels in `labels.yml`, Status/Target/
+Impact options in `roadmap-fields.yml`, and Area derived from the `area:*` labels rather than
+listed a second time. The Project field options in the table above must match
+`roadmap-fields.yml`; a test asserts the roadmap generator's own ordering stays in sync with
+both files.
+
+## Linear bridge
+
+| Artifact | System of record |
+| -------- | ---------------- |
+| Public discussion, prioritization debate | GitHub Discussions |
+| Triaged work items, roadmap columns | GitHub Issues + Project |
+| Design scope, acceptance criteria | `docs/implementationPlans/*.md` |
+| Sprint estimates, assignees, internal-only work | Linear |
+
+**GitHub → Linear (one-way intake)**
+
+1. Maintainer adds the `tracked` label to a GitHub issue.
+2. Linear's GitHub integration imports the issue into the Terreno Linear team.
+3. Title and description sync on creation; **status is not synced back**.
+
+**Closing the loop:** merging PRs use `Fixes #NNN` so GitHub closes the issue and the board
+item moves to `Shipped`. Closing Linear alone does **not** change GitHub state.
+
+**Internal → public:** open a GitHub issue manually and paste the Linear URL. Internal-only
+Linear work is never mirrored.
+
+**Why not two-way status sync?** Bidirectional sync produces confusing loops between board
+columns and sprint state. One-way intake plus `Fixes #NNN` keeps public state accurate.
+
+Configure Linear: **Settings → Integrations → GitHub** → import issues with label `tracked`.
+
+## One-time backfill
+
+```bash
+gh issue list --state open --limit 200 --json number,title,labels,updatedAt
+```
+
+For each issue: assign `area:*` + `type:*`, add to board as `Inbox` if relevant, or
+`status:wontfix` / close if stale (> 6 months, no longer applies). A human must run this —
+do not claim completion until done.
+
+## Automation in this repo
+
+| Workflow | Trigger | Purpose |
+| -------- | ------- | ------- |
+| [`.github/workflows/triage.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | Regenerate `ROADMAP.md` from the Project board |
+
+Triage resolves the `area:*` label with
+[`scripts/issueAreaLabels.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/issueAreaLabels.ts),
+which owns the package-to-area table. Add new packages there, not in the workflow.
+
+Run the generator locally against the real board:
+
+```bash
+GITHUB_TOKEN=$(gh auth token) TERRENO_PROJECT_NUMBER=... bun run roadmap:generate
+```
+
+The generator exits non-zero when the project cannot be read, so a bad project number or a
+token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`.