@terreno/mcp 57.16.2 → 57.18.0

package/dist/docs/versioned/57.17.0/explanation/organizations.md

@@ -0,0 +1,88 @@
+# How organization tenancy works
+
+Terreno treats organizations as an optional framework primitive. Existing
+single-tenant apps do not pay a migration or authorization cost; multi-tenant
+apps opt in at the access, application, model, and admin layers. New apps
+generated by `create-terreno-app` opt in by default.
+
+## Identity and authorization layers
+
+Platform and tenant authority are separate:
+
+| Authority | Storage | Scope |
+| --- | --- | --- |
+| `superadmin` | `User.roles` | Every framework permission |
+| `operator` | `User.roles` | Organization directory and every organization |
+| `org-admin` | `Membership.roleName` | One organization |
+| `member` | `Membership.roleName` | One organization; app permissions decide actions |
+
+`user.admin` does not imply operator access. `org-admin` is deliberately not a
+global RBAC role: putting it on `User.roles` grants nothing. During an
+organization request, `createAccess({organizations: true})` adds the current
+active Membership grants to the normal role permissions.
+
+## Request context
+
+Tenant routes resolve `X-Organization-Id` after authentication. An operator or
+superadmin may enter any organization but must choose one. An org-admin with
+exactly one administered organization may omit the header; Terreno infers it.
+Ambiguous or unauthorized context fails before model queries run.
+
+The resolved organization and membership are stored in AsyncLocalStorage as
+well as `req.organization` / `req.membership`. This lets `OrgQueryFilter` add
+the server-owned organization id without trusting a client query parameter.
+
+## Isolation boundaries
+
+Tenant isolation uses multiple checks rather than one convention:
+
+1. `orgContextMiddleware({required: true})` rejects missing or unauthorized context.
+2. `OrgQueryFilter` ANDs the selected organization into list and search queries.
+3. `Permissions.IsOrganizationMember` rejects cross-org object reads and writes.
+4. Create hooks overwrite client-supplied organization ids.
+5. `orgScopedPlugin` rejects any post-create change to `organizationId` (REST, admin, sync, direct save).
+6. Sync scopes resolve active Membership rows and partition streams by organization.
+
+`AdminApp({organizations: true})` applies these boundaries automatically to
+admin models whose schema contains `organizationId`. Models without that path
+remain platform-scoped.
+
+## Disabled organizations
+
+When `Organization.disabled` is `true`, tenant context and membership mutations
+stop, but operators can still manage the organization record itself:
+
+| Surface | Disabled org behavior |
+| --- | --- |
+| `orgContextMiddleware` / inferred org context | 403 `Organization is disabled` |
+| `GET /orgs/mine` | Disabled orgs omitted from the switcher list |
+| `GET /orgs` (operator directory) | Disabled orgs still listed |
+| `GET` / `PATCH /orgs/:id` | Allowed (operators use `PATCH` with `disabled: false` to re-enable) |
+| `POST` / `PATCH` / `DELETE /orgs/:id/members` | 403 while disabled |
+| Soft-deleted orgs | Still 404 everywhere |
+
+Disabling or deleting an organization suspends its memberships. Re-enabling does
+not automatically reactivate them.
+
+## Why organizations are optional
+
+Automatically registering routes, roles, or Mongoose models would change
+existing apps merely because they upgraded `@terreno/api`. Instead:
+
+- `createAccess` omits Membership grants and the `operator` seed unless
+  `organizations: true`;
+- `TerrenoApp` does not mount `/orgs` unless organizations are enabled;
+- `AdminApp` does not scope models unless organizations are enabled;
+- Organization and Membership Mongoose models register lazily on first use.
+  Apps add fields to `Organization.settings` with `createOrganizationSettingsSchema`
+  and `registerOrganizationSettings`, not by replacing the Organization model.
+
+This keeps upgrades backward compatible while letting bootstrap generate
+multi-tenant-ready apps.
+
+## Related
+
+- [Add organizations](../how-to/add-organizations.md)
+- [API reference](../reference/api.md#organizations)
+- [Admin backend reference](../reference/admin-backend.md#organization-scoping)
+- [Admin frontend reference](../reference/admin-frontend.md#orgdirectoryscreen)

package/dist/docs/versioned/57.17.0/explanation/planning-plugins.md

@@ -0,0 +1,114 @@
+# Planning plugins
+
+Terreno ships its agentic workflows as **two host plugins**. They divide along one line:
+the lifecycle plugin knows *how to build one approved thing correctly*, and the scan
+plugin knows *what is worth building next and whether it worked*.
+
+```text
+terreno-scan                            terreno (lifecycle)
+------------                            -------------------
+Aim     charter a measurable goal
+Sweep   shard + map the repository
+Sift    reduce to verified findings
+Plot    slice findings into briefs ───►  Grow    shape IP + tasks
+                                         Pick ⇄ Roast  build and prove
+                                         Brew    submit the PR
+                                         Taste   react to CI and review
+Track   re-measure, close findings  ◄───  (merged)
+```
+
+A scan never edits product code. The lifecycle never decides what the repository should
+become. Every slice crosses that boundary exactly once, as an approved IP and task list.
+
+## terreno (lifecycle plugin)
+
+Five bounded transitions plus three outer loops. Canonical source:
+`plugins/terreno-planning/`; Claude Code consumes the generated `plugins/terreno-claude/`.
+
+| Stage | Owns | PASS next |
+| --- | --- | --- |
+| Grow | Research, grilling, approved IP and dependency-aware task list, criterion → verification map | Pick |
+| Pick | Implement one task, then Roast it, then take the next until the list is done | Roast, or Brew when done |
+| Roast | Independently prove the current task against its criteria | Pick if tasks remain, else Brew |
+| Brew | Final checks, commit, push, PR, evidence, CI trigger, wait for review bots | Taste |
+| Taste | One reaction to the current head: bots, CI on every host, conflicts, comments | null or fresh Taste |
+
+| Outer loop | Walks |
+| --- | --- |
+| `pick-roast-loop` | An approved plan through every Pick/Roast retry, one ledger, stop only at completion or a genuine human gate |
+| `planning-loop` | Grow/Pick/Brew/Taste, restrictable with `phases=` |
+| `taste-sweep` | Every open PR of yours that is conflicting or failing, until each is mergeable |
+
+Full contract: [lifecycle plugin reference](../reference/lifecycle-plugin.md) and
+[loop engineering](loop-engineering.md).
+
+## terreno-scan (scan plugin)
+
+Five bounded transitions plus two outer loops. Canonical source: `plugins/terreno-scan/`;
+Claude Code consumes the generated `plugins/terreno-scan-claude/`. It depends on the
+lifecycle plugin — Plot hands every slice to Grow.
+
+| Stage | Owns | PASS next |
+| --- | --- | --- |
+| Aim | Charter: metric with a command, measured baseline, dry-run detection rules, exclusions, validity rule, severity rubric, slice policy, review routing, budget | Sweep |
+| Sweep | Run the rules, shard hits deterministically, map fresh workers into candidate findings | Sift |
+| Sift | Dedupe, adversarially verify, drop what does not reproduce, rank, write the findings report | Plot, or Track when dry |
+| Plot | Slice findings into PR-sized units with standalone Grow briefs | Track, handing off to Grow |
+| Track | Re-measure the metric, close or reopen findings with evidence, record the round, choose the next move | Plot, Sweep, or null |
+
+| Outer loop | Walks |
+| --- | --- |
+| `campaign` | Bounded rounds: Aim → Sweep → Sift → Plot → lifecycle → Track. Stops at every gate. |
+| `loop` | Resident session: the same rounds, plus a heartbeat over open campaign PRs — route, answer review through Taste, fix red CI, Track merges — refilling work up to `wipLimit`. |
+
+Full contract: [scan plugin reference](../reference/scan-plugin.md).
+
+## Which one to invoke
+
+| Situation | Start with |
+| --- | --- |
+| You know what to build | `1-grow` |
+| You have an approved plan and want it built | `pick-roast-loop` |
+| A PR of yours is red or conflicting | `5-taste`, or `taste-sweep` for all of them |
+| You know the outcome you want, not the work | `scan 1-aim` |
+| You want that outcome pursued unattended | `scan loop` |
+
+## What each plugin persists
+
+| Artifact | Owner | Committed |
+| --- | --- | --- |
+| IP and task list | Grow | yes |
+| Execution state (`.terreno/pipeline/<slug>.json`) | Lifecycle outer loops | no |
+| Charter (`docs/scans/<goal>/charter.md`) | Aim | yes |
+| Findings report (`docs/scans/<goal>/round-<n>-findings.md`) | Sift | yes |
+| Campaign state (`.terreno/scan/<goal>.json`) | Scan outer loops | no |
+
+Both plugins emit the same shaped result — `v: 2`, `status` of `PASS` / `FAIL` /
+`BLOCKED` / `PENDING`, a `next`, and a concrete `action` — in a collapsed details block,
+with `status` / `next` / `action` as the visible lines. Neither persists
+chain-of-thought.
+
+## Why the split
+
+Three properties fall out of keeping discovery and delivery in separate plugins:
+
+- **A finding must earn its slice.** Sift drops anything that cannot be tied to the
+  goal metric, so the lifecycle only ever receives work with a stated payoff.
+- **Delivery rules stay in one place.** Review response, CI waiting, the pre-push gate,
+  and documentation obligations live in the lifecycle, so a scan cannot invent a
+  shortcut around them.
+- **Progress is measured, not asserted.** Track re-runs the metric command after the
+  work merges, so "we improved it" is always a number with its command output.
+
+## Hosts
+
+| Host | Lifecycle | Scan |
+| --- | --- | --- |
+| Cursor | `terreno-planning`, `/terreno-1-grow` | `terreno-scan`, `/terreno-scan-1-aim` |
+| Codex | `terreno-planning`, `$terreno-1-grow` | `terreno-scan`, `$terreno-scan-1-aim` |
+| Claude Code | `terreno`, `/terreno:1-grow` | `terreno-scan`, `/terreno-scan:1-aim` |
+
+Install both from the marketplaces described in
+[install agent skills](../how-to/install-agent-skills.md). Claude Code resolves a plugin
+skill's command from its frontmatter `name`, which is why the two `*-claude/` trees are
+generated with shortened names by `bun run skills:sync`.

package/dist/docs/versioned/57.17.0/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 (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) | `@terreno/jobs` `JobsApp` (`jobs/`) | [How-to](../how-to/background-jobs.md), [reference](../reference/jobs.md); optional GCP Cloud Tasks and Vercel Queues runners |
+| Migrations | No migrations framework | Schema evolution is convention plus the published `mongoose-schema-safety` skill |
+
+## 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/57.17.0/explanation/repository-settings.md

@@ -0,0 +1,72 @@
+# Repository settings (maintainers)
+
+Some GitHub settings cannot be committed to the repo. Enable these manually in
+the [Terreno repository settings](https://github.com/TerrenoLabs/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 CircleCI `repo-policies`, package CI,
+  and Rulesync Check jobs relevant to the change — see the check name map in
+  [how-to/circleci.md](../how-to/circleci.md))
+- Require branches to be up to date before merging
+- Do not allow bypassing the above settings
+
+### CircleCI checks
+
+Package CI, policy, Playwright, Maestro web, architectural review, deploy, and
+release workflows run under `.circleci/` (see
+[how-to/circleci.md](../how-to/circleci.md)). Require the path-filtered CircleCI
+check names. Remove required GitHub Action checks for workflow files whose
+trigger is `push.branches-ignore: ["**"]`; those checks cannot report anymore. Do not require the
+config-only `circleci-config` workflow. Keep Cursor Approval / Security / Bugbot
+as GitHub App checks; they are not CircleCI jobs.
+
+## GitHub Environments (GCP preview)
+
+**Path:** Settings → Environments
+
+`cd.yml` is disabled; CircleCI `gcp-cd-preview` performs GCP previews and
+halts on fork PRs. While the GitHub WIF provider still exists, keep the
+`gcp-cd-preview` environment restricted with a **deployment branch policy** or
+**required reviewers** so a fork that re-enables `cd.yml` cannot mint a prod
+WIF token.
+
+### Actions secrets for CircleCI hooks
+
+`preview-cleanup.yml` (PR close) and `publish-on-tag.yml` (manual publish demo
+redeploy) start CircleCI pipelines. Set the secret `CIRCLECI_TOKEN` and the
+variable `CIRCLECI_PIPELINE_DEFINITION_ID` under Settings → Secrets and
+variables → Actions.
+
+## Merge settings
+
+**Path:** Settings → General → Pull Requests
+
+- Allow **squash merging** only (disable merge commits and rebase merging)
+- Enable **Automatically delete head branches** after merge