@terreno/mcp 57.3.0 → 57.6.0

package/src/docs/versioned/next/explanation/loop-engineering.md

@@ -49,8 +49,10 @@ the inner loop until the approved task list is done. Roast never invokes Pick. B
 Taste additionally wait while async review bots are running, preferring provider CLI
 watch hooks or harness event subscriptions over timer polling. Taste also waits in a
 loop for product CI with `gh` or `circleci` until jobs are terminal or the wait times
-out. Before any push it always pulls latest `master`, then lints in a no-context
-subagent, then pushes and watches CI.
+out. Before any push it always pulls latest `master`, then records last-run failed tests
+and re-verifies them locally, then runs the repository's root
+`prepush` package script in a no-context subagent when present (falling back to affected
+package lint, typecheck, and tests), then pushes and watches CI.
 
 Invocable outer loops in the plugin:
 
@@ -81,9 +83,10 @@ daemon. It waits until async review bots (Bugbot, CodeQL, and similar) on the cu
 head have reported, then waits in a loop for product CI using GitHub CLI
 (`gh pr checks --watch`, `gh run watch`) or CircleCI CLI (`circleci run watch`) until
 jobs are terminal or the wait times out. Before any push it always pulls latest
-`master`, then proves lint, typecheck, and affected tests in a fresh subagent with no
-parent conversation, then pushes and watches CI. It emits `PASS`, `FAIL`, `BLOCKED`, or
-`PENDING`, and exits.
+`master`, records last-run failed tests and re-verifies them locally, then runs root
+`prepush` when present in a fresh subagent with no parent
+conversation. If absent, it proves affected-package lint, typecheck, and tests instead.
+It then pushes and watches CI, emits `PASS`, `FAIL`, `BLOCKED`, or `PENDING`, and exits.
 
 Brew review-bot waits use only hooks targeted to the matched bot so ordinary CI cannot
 extend Brew. Taste's product-CI wait uses unfiltered GitHub/CircleCI watches on purpose.
@@ -118,7 +121,7 @@ include:
 | UI/app | `terreno-ui`, `building-terreno-apps`, `verify-ui-changes` |
 | AI/prompts | `ai-prompt-governance` |
 | Docs/submission | `update-docs`, Brew, `fix-conflicts` |
-| GitHub issues | `create-github-issue`, `work-github-issues`, `implement-ready-for-dev` (Pick plan comment is the Roast contract) |
+| GitHub issues | `create-github-issue`, `work-github-issues`, `implement-ready-for-dev` (Pick plan comment is the Roast contract; unattended Grow may also write an IP) |
 | Deployment/runtime | `deploy-gcp`, Expo deployment/workflow skills |
 
 This inventory is descriptive, not a plugin dependency list. Stages inspect the actual
@@ -158,5 +161,5 @@ contain chain-of-thought or transcripts.
   terminal/non-failing, no conflicts, and no actionable review findings.
 
 The detailed contract, schemas, and three execution scenarios live under
-[`plugins/terreno-planning/references/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning/references).
+[`plugins/terreno-planning/references/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-planning/references).
 

package/src/docs/versioned/next/explanation/model-router-actions.md

@@ -6,18 +6,35 @@ CRUD **create, update, and delete** (not named actions) share one write pipeline
 
 ## When to use actions
 
+Use `collectionActions` / `instanceActions` for every application GET or POST that is not
+plain document CRUD. Do **not** register `app.get`, `app.post`, `router.get`, or
+`router.post` for those endpoints.
+
 Use actions when an endpoint performs an operation that is not a plain create/read/update/delete on the model document:
 
 - **Collection scope** (`POST /todos/bulkComplete`) — operate on many documents or the collection as a whole.
 - **Instance scope** (`POST /todos/:id/markComplete`) — operate on one loaded document.
 
-Use [custom routes with `createOpenApiBuilder`](./modular-api-design.md) when the URL does not fit the `/:id/{actionName}` or `/{actionName}` pattern.
+Leave Express `app.get` / `app.post` only for:
+
+- Inbound webhooks (`WebhooksApp`)
+- Static SPA / file serving
+- Framework auth, health, and version-check plugins
+- SSE or other streaming handlers that write the response themselves
+- Tests and harnesses
+
+PATCH and DELETE are CRUD (or a POST action that performs the same work). Do not add a
+hand-rolled DELETE next to a modelRouter.
+
+Use [custom routes with `createOpenApiBuilder`](./modular-api-design.md) only when the
+URL cannot be `/{actionName}` or `/:id/{actionName}` **and** the exceptions above do not
+apply.
 
 ## Example
 
 ```typescript
 import {modelRouter, Permissions, z} from "@terreno/api";
-import {Todo} from "../models";
+import {Todo} from "../models/todo";
 
 export const todoRouter = modelRouter("/todos", Todo, {
   permissions: {

package/src/docs/versioned/next/explanation/modular-api-design.md

@@ -228,7 +228,7 @@ Migration will be supported with:
 ## Learn More
 
 - 📖 [Implementation plan](../implementationPlans/ModularAPI.md) — Full technical specification
-- 💬 [GitHub PR #149](https://github.com/FlourishHealth/terreno/pull/149) — Discussion and feedback
+- 💬 [GitHub PR #149](https://github.com/TerrenoLabs/terreno/pull/149) — Discussion and feedback
 
 ## Related
 

package/src/docs/versioned/next/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/src/docs/versioned/next/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/src/docs/versioned/next/explanation/positioning.md

@@ -103,8 +103,8 @@ 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
+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.
@@ -125,7 +125,7 @@ shipped" row links the implementation plan or roadmap item that tracks it.
 | 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) |
+| 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

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

@@ -1,7 +1,7 @@
 # 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).
+the [Terreno repository settings](https://github.com/TerrenoLabs/terreno/settings).
 
 ## Discussions
 
@@ -31,8 +31,9 @@ descriptions):
 **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 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
 
@@ -42,7 +43,7 @@ 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 `on: []`; those checks cannot report anymore. Do not require the
+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.
 
@@ -50,9 +51,9 @@ as GitHub App checks; they are not CircleCI jobs.
 
 **Path:** Settings → Environments
 
-Same-repo PR jobs in `cd.yml` (`Terraform preview`, `Backend deploy (preview)`)
-skip when `head.repo.full_name != github.repository`. Also restrict the
-`gcp-cd-preview` environment (create it on first deploy if missing) with a
+Same-repo PR jobs in `cd.yml` (`Terraform preview`, `Tasks deploy (preview)`,
+`Backend deploy (preview)`) skip when `head.repo.full_name != github.repository`.
+Also restrict the `gcp-cd-preview` environment (create it on first deploy if missing) with a
 **deployment branch policy** or **required reviewers** so a fork that edits
 `cd.yml` cannot mint a prod WIF token.
 

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

@@ -5,11 +5,11 @@ Implementation plans in `docs/implementationPlans/` remain the design source of
 both.
 
 - **GitHub** — discussions, triaged issues, the Terreno Roadmap project board, generated
-  [`ROADMAP.md`](https://github.com/FlourishHealth/terreno/blob/master/ROADMAP.md)
+  [`ROADMAP.md`](https://github.com/TerrenoLabs/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.
+See also [CONTRIBUTING.md](https://github.com/TerrenoLabs/terreno/blob/master/CONTRIBUTING.md) for the contributor intake flow.
 Issue-sized work that is not a public roadmap item uses
 [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md)
 (`create-github-issue` → `work-github-issues`, or `status:ready-for-dev` →
@@ -88,10 +88,11 @@ half applies:
 | 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. |
+| 4 | Hacktoberfest | Open-ended | Anyone | Pitch something to build during Hacktoberfest and upvote the ideas you want. Popular, well-scoped ideas become `hacktoberfest` issues anyone can pick up. |
+| 5 | Agents & AI | Open-ended | Anyone | MCP setup, Cursor/Claude skills, agent workflows, and prompt patterns for building with Terreno. |
+| 6 | RFCs | Open-ended | Anyone | Substantial proposals that change public API or add packages. Use the RFC discussion template; accepted RFCs become IPs. |
+| 7 | Show and tell | Open-ended | Anyone | Apps and experiments built with Terreno. Share what you shipped and what friction you hit. |
+| 8 | Docs feedback | Open-ended | Anyone | Report missing or confusing documentation. Link the page URL; recurring feedback becomes docs PRs. |
 
 ### Pinned posts
 
@@ -102,8 +103,8 @@ Pin one intro post per category after creation. Bodies below are ready to paste.
 ```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).
+- Do **not** file support bugs as announcements — use [Issues](https://github.com/TerrenoLabs/terreno/issues/new/choose) or Q&A.
+- Security issues: see [SECURITY.md](https://github.com/TerrenoLabs/terreno/blob/master/SECURITY.md) (private report only).
 ```
 
 #### Q&A
@@ -111,9 +112,9 @@ Release announcements, breaking changes, and deprecation notices land here.
 ```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.
+1. Search [existing Q&A](https://github.com/TerrenoLabs/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/TerrenoLabs/terreno/tree/master/docs/how-to).
+3. Bug reports belong in [Bug report issues](https://github.com/TerrenoLabs/terreno/issues/new?template=bug_report.yml), not here.
 
 When an answer repeats, maintainers turn it into a how-to doc via PR.
 ```
@@ -123,19 +124,36 @@ When an answer repeats, maintainers turn it into a how-to doc via PR.
 ```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.
+- Do **not** open a feature issue directly — maintainers promote accepted ideas to tracked issues on the [Terreno Roadmap](https://github.com/TerrenoLabs/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).
+- Bugs → [Bug report](https://github.com/TerrenoLabs/terreno/issues/new?template=bug_report.yml).
 ```
 
+#### Hacktoberfest
+
+```markdown
+**Pitch Hacktoberfest ideas here, and 👍 the ones you want built.**
+
+1. [Start a Hacktoberfest discussion](https://github.com/TerrenoLabs/terreno/discussions/new?category=hacktoberfest) — the form asks for the idea, area, rough size, and what "done" looks like.
+2. Upvote and comment on other pitches. Upvotes are how maintainers rank them.
+3. Maintainers turn popular, well-scoped ideas into issues labeled [`hacktoberfest`](https://github.com/TerrenoLabs/terreno/issues?q=is%3Aissue+is%3Aopen+label%3Ahacktoberfest) and link them back here. Pick one up by commenting on the issue.
+
+Longer-term feature ideas → **Ideas**. Bugs → [Bug report](https://github.com/TerrenoLabs/terreno/issues/new?template=bug_report.yml).
+```
+
+Promotion follows the Ideas path, with one change: a Hacktoberfest idea small enough to finish
+in a weekend becomes a `hacktoberfest` + `good first issue` work item directly (see
+[GitHub issue lifecycle](../how-to/github-issue-lifecycle.md)) instead of a `Shaping` roadmap
+item. Larger ones go through `roadmap-promote` like any other idea.
+
 #### 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 into editor-specific copies).
-- Terreno planning plugin: [`plugins/terreno-planning/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning).
+- MCP package: [`mcp-server/`](https://github.com/TerrenoLabs/terreno/tree/master/mcp-server) and hosted `terreno-mcp`.
+- Agent skills: [`.rulesync/skills/`](https://github.com/TerrenoLabs/terreno/tree/master/.rulesync/skills) (mirrored into editor-specific copies).
+- Terreno planning plugin: [`plugins/terreno-planning/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-planning).
 
 General feature ideas → **Ideas**. Doc typos → **Docs feedback** or a docs PR.
 ```
@@ -145,7 +163,7 @@ General feature ideas → **Ideas**. Doc typos → **Docs feedback** or a docs P
 ```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).
+Use the [RFC template](https://github.com/TerrenoLabs/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.
 ```
@@ -170,7 +188,7 @@ Every docs page also has a **Discuss this page** link in the footer.
 
 ### Project board
 
-The board must be an **organization** project under `FlourishHealth`. The generator queries
+The board must be an **organization** project under `TerrenoLabs`. The generator queries
 `organization(login:).projectV2`, so a repo-level project returns no data.
 
 `bun run roadmap:sync` creates the project, its fields, and its items from repo data — no
@@ -187,8 +205,8 @@ What it reads, and therefore what you edit to change the board:
 
 | Source | Drives |
 | ------ | ------ |
-| [`.github/roadmap-fields.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/roadmap-fields.yml) | `Status`, `Target`, `Impact` options |
-| `area:*` labels in [`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml) | `Area` options |
+| [`.github/roadmap-fields.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/roadmap-fields.yml) | `Status`, `Target`, `Impact` options |
+| `area:*` labels in [`.github/labels.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/labels.yml) | `Area` options |
 | [`roadmap-seed-issues.md`](roadmap-seed-issues.md) | one item per roadmap entry, plus its field values and issue labels |
 
 **Fields** (single-select unless noted):
@@ -205,7 +223,7 @@ What it reads, and therefore what you edit to change the board:
 `Target` answers *which release*, never *what state* — `Status` carries state. Already-shipped
 work uses `Target = Released` so it groups at the bottom of `ROADMAP.md` instead of inflating
 an upcoming version. `TARGET_ORDER` in
-[`scripts/generate-roadmap/lib.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/generate-roadmap/lib.ts)
+[`scripts/generate-roadmap/lib.ts`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/generate-roadmap/lib.ts)
 must stay deep-equal to the yaml list; a test enforces it.
 
 **Views** — still UI-only; there is no GitHub API for creating project views.
@@ -227,29 +245,29 @@ before applying a rewrite.
 
 ### Labels
 
-[`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml) is the source of truth.
+[`.github/labels.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/labels.yml) is the source of truth.
 
 Every issue on the board carries the **`roadmap`** label. That label — not a title prefix — is
 how roadmap work is filtered:
 
 ```bash
-gh issue list --repo FlourishHealth/terreno --label roadmap --state all
+gh issue list --repo TerrenoLabs/terreno --label roadmap --state all
 ```
 
 `roadmap:sync` adds it to every issue it declares, so seed entries do not repeat it on their
 `**Labels:**` line. Tracking issues used to be titled `[Roadmap] <outcome>`; titles are now
 just the outcome, and `displayTitle` in
-[`scripts/generate-roadmap/lib.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/generate-roadmap/lib.ts)
+[`scripts/generate-roadmap/lib.ts`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/generate-roadmap/lib.ts)
 strips the legacy prefix wherever it survives.
 
 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
+bun run labels:sync --repo TerrenoLabs/terreno --dry-run   # preview
+bun run labels:sync --repo TerrenoLabs/terreno             # apply
 ```
 
-[`scripts/sync-labels.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/sync-labels.ts)
+[`scripts/sync-labels.ts`](https://github.com/TerrenoLabs/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.
@@ -266,8 +284,11 @@ Delete unused GitHub defaults after the new taxonomy is applied (`gh label list`
 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`.
+`ROADMAP_PROJECT_TOKEN` secret. The same PAT also pushes the regenerated `ROADMAP.md`: the
+`master` ruleset requires a pull request and the default `GITHUB_TOKEN` is not a bypass actor
+on it, so the PAT needs `repo` scope and its owner must be listed as a ruleset bypass actor.
+[`.github/scripts/git-auth-roadmap-pat.sh`](https://github.com/TerrenoLabs/terreno/blob/master/.github/scripts/git-auth-roadmap-pat.sh)
+applies that credential only for the fetch/push steps, so `bun install` never sees it.
 
 Locally, export the PAT as `GITHUB_TOKEN` (for example `GITHUB_TOKEN=$(gh auth token)`), which
 is the variable the generator reads.
@@ -325,9 +346,9 @@ bun run roadmap:check --on-board --labels "roadmap,area:api,type:feature" --stat
 Run it with no arguments to print every valid label and field option. It enforces exactly one
 `area:*` and one `type:*` label, requires the `roadmap` label under `--on-board` (omit the
 flag when triaging an issue that is not headed for the board), rejects labels absent from
-[`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml),
+[`.github/labels.yml`](https://github.com/TerrenoLabs/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),
+[`.github/roadmap-fields.yml`](https://github.com/TerrenoLabs/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/
@@ -376,11 +397,10 @@ do not claim completion until done.
 
 | 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 + `type:*` from Kind when present |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board |
-| [`.github/workflows/roadmap-sync.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
-| [`.github/workflows/roadmap-reconcile.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, push to the board, regenerate `ROADMAP.md` |
-
+| [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when it changes |
+| [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
+| [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving
 them produces confusing partial states. After the group lock is acquired, each job refreshes
 to the latest branch HEAD so a queued `roadmap-sync` cannot overwrite statuses that
@@ -443,7 +463,7 @@ Two headers keep a plan out of that accounting:
 | Task file `**Status:** Closed` | The checklist is history — the IP finished by another route, so its unchecked boxes are not outstanding work and never contradict a `Shipped` status |
 
 Triage resolves the `area:*` label with
-[`scripts/issueAreaLabels.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/issueAreaLabels.ts),
+[`scripts/issueAreaLabels.ts`](https://github.com/TerrenoLabs/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: