@terreno/mcp 58.0.0 → 58.0.2

package/dist/docs/versioned/57.18.0/explanation/explicit-any-policy.md

@@ -1,90 +0,0 @@
-# Explicit `any` policy
-
-Terreno discourages `any` in TypeScript. Biome blocks **new** unsuppressed explicit `any` at lint time; this document describes how we inventory existing usages and track remediation.
-
-## Why
-
-- **Type safety**: `any` disables checking and hides bugs at compile time.
-- **Refactor confidence**: precise types make API and UI changes safer.
-- **Consistency**: one convention for when `any` is acceptable and how it is documented.
-
-Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as any as T` when a cast is unavoidable.
-
-## Allowed uses
-
-Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
-
-- Mongoose model boundaries that inspect consumer-defined schemas (`api/src/populate.ts`)
-- RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
-- Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
-- Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
-
-Every allowed use must be **lint-clean** and **documented** (see below).
-
-## Remediation status
-
-The audit script (`bun run check:explicit-any`) classifies each explicit `any`:
-
-| Status | Meaning |
-|--------|---------|
-| `violation` | No `biome-ignore` — fails Biome lint |
-| `suppressed-only` | Has `biome-ignore` but missing `// noExplicitAny:` rationale |
-| `fully-documented` | Has both `biome-ignore` and `// noExplicitAny:` |
-| `file-blanket` | File-level `biome-ignore-all` without file-level `noExplicitAny:` |
-| `out-of-scope` | In Biome-excluded source (e.g. `api/src/populate.ts`) |
-
-## How to document an `any`
-
-When `any` cannot be removed, add **both** comments on the line above (or a file header for tests):
-
-```typescript
-// noExplicitAny: RTK Query generates hook names dynamically; not statically expressible
-// biome-ignore lint/suspicious/noExplicitAny: dynamic hook lookup on RTK Query enhanced API
-const hook = (api as any)[`useGet${name}Query`];
-```
-
-For test files with many mocks, a file-level header is fine:
-
-```typescript
-// noExplicitAny: test mocks use type-erased RTK Query API doubles
-// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
-```
-
-## Commands
-
-```bash
-bun run check:explicit-any                         # summary report
-bun run check:explicit-any:json                    # JSON inventory
-bun run check:explicit-any:lint                    # fail on unmarked or unsuppressed any
-bun run check:explicit-any:baseline                # fail if global or per-file counts regress
-bun run check:explicit-any -- --undocumented       # only suppressed-but-undocumented
-bun run check:explicit-any -- --list --undocumented  # file:line list for remediation
-bun run check:explicit-any -- --production-only --undocumented --list
-bun run check:explicit-any -- --package=api        # filter to one package
-bun run check:explicit-any -- --include-excluded   # include Biome-excluded files
-bun run check:explicit-any -- --write-baseline     # refresh scripts/check-explicit-any/baseline.json
-bun run check:explicit-any:remediate               # auto-add missing noExplicitAny: comments
-```
-
-## Enforcement
-
-| Layer | What it does |
-|-------|----------------|
-| **Biome `noExplicitAny: error`** | Blocks new unsuppressed `any` in every linted package |
-| **`bun run check:explicit-any:lint`** | Blocks suppressions without a `noExplicitAny:` rationale, including undocumented file-level suppressions |
-| **`bun run check:explicit-any:baseline`** | CI ratchet — total, per-file, undocumented, and violation counts must not increase; a new file starts with an allowance of zero |
-| **`bun run lint`** | Runs package lint, then the strict explicit-any marker check |
-
-Baseline file: `scripts/check-explicit-any/baseline.json`. Its per-file counts prevent a new or existing file from adding explicit `any` even when another file removes the same number. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
-
-## Remediation workflow
-
-1. Run `bun run check:explicit-any -- --list --undocumented --production-only` for a work queue.
-2. For each hit, either **replace** `any` with a proper type or **document** with `noExplicitAny:` + `biome-ignore`.
-3. Prefer line-level suppressions over file-level `biome-ignore-all` in production code.
-4. Run `bun run check:explicit-any:baseline` before opening a PR.
-5. If counts decreased, run `--write-baseline` and commit the new baseline.
-
-## Exclusions
-
-The audit skips generated and template files (`openApiSdk.ts`, `*.template.ts`). Biome-excluded paths (see `!!` patterns in `biome.jsonc`) are omitted unless `--include-excluded` is passed.

package/dist/docs/versioned/57.18.0/explanation/gcp-hosting-architecture.md

@@ -1,319 +0,0 @@
-# GCP Hosting Architecture
-
-This document explains the architecture and design decisions behind Terreno's Google Cloud Platform hosting setup for static web apps.
-
-## Overview
-
-The Terreno monorepo hosts two static web applications on Google Cloud Storage (GCS) with Cloud CDN:
-
-- **Demo app** (`demo/`) — UI component showcase
-- **Example frontend** (`example-frontend/`) — Full-stack example with API integration
-
-Both apps use the same architecture pattern optimized for single-page applications (SPAs) with client-side routing.
-
-## Architecture Diagram
-
-``````
-┌─────────────────────────────────────────────────────────────┐
-│                        Client Browser                        │
-└───────────────────────────┬─────────────────────────────────┘
-                            │ HTTP Request
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│               Global Forwarding Rule (Static IP)             │
-│              (e.g., 34.120.xxx.xxx)                          │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                       HTTP Proxy                             │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                         URL Map                              │
-│           (Routes to default backend bucket)                 │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                   Backend Bucket (CDN-enabled)               │
-│          (e.g., terreno-demo-backend)                        │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    GCS Bucket (Origin)                       │
-│   (e.g., gs://your-project-terreno-demo)                    │
-│                                                              │
-│   ├── index.html                                            │
-│   ├── _expo/                                                │
-│   │   └── static/                                           │
-│   │       ├── js/                                           │
-│   │       ├── css/                                          │
-│   │       └── media/                                        │
-│   └── _previews/                                            │
-│       └── pr-123/                                           │
-│           └── index.html                                    │
-└─────────────────────────────────────────────────────────────┘
-``````
-
-## Components
-
-### 1. GCS Bucket (Origin)
-
-**Purpose**: Store static assets (HTML, JS, CSS, images).
-
-**Configuration**:
-- **Public access**: `allUsers:objectViewer` IAM binding
-- **Static website config**: `notFoundPage=index.html` for SPA routing
-- **No `mainPageSuffix`**: Avoids GCS 301 redirects that break client routing
-
-**Key Feature**: The `notFoundPage` directive serves `index.html` for any 404, enabling client-side routing. When a user visits `/about` directly, GCS returns `index.html`, and the React Router or Expo Router handles the route client-side.
-
-### 2. Backend Bucket (CDN)
-
-**Purpose**: Serve bucket content with Cloud CDN caching.
-
-**Configuration**:
-- **CDN enabled**: Responses are cached at Google edge locations worldwide
-- **Negative caching disabled**: Prevents Cloud CDN from caching 404 responses, which would cause stale 404s for newly-deployed asset hashes
-- **Linked to GCS bucket**: Single bucket per backend
-
-**Performance**: CDN reduces latency by serving cached content from edge locations closest to users.
-
-### 3. URL Map
-
-**Purpose**: Route incoming requests to the backend bucket.
-
-**Configuration**:
-- **Default service**: Points to the backend bucket
-- **Path-based routing**: All paths (`/*`) route to the same backend
-
-**Extensibility**: URL maps support path-based routing (e.g., `/api/*` → backend service, `/*` → frontend), but Terreno uses a single backend per app.
-
-### 4. HTTP Proxy
-
-**Purpose**: Terminate HTTP connections and forward to the URL map.
-
-**Configuration**:
-- **Protocol**: HTTP (can be upgraded to HTTPS with certificates)
-- **Forwarding**: Passes requests to URL map
-
-**HTTPS Support**: To enable HTTPS, create an SSL certificate and attach it to an HTTPS proxy instead.
-
-### 5. Global Forwarding Rule (Static IP)
-
-**Purpose**: Assign a static external IP address to the HTTP proxy.
-
-**Configuration**:
-- **IP address**: Reserved global static IP (e.g., `34.120.xxx.xxx`)
-- **Port**: 80 (HTTP)
-
-**DNS**: Point your domain's A record to this IP for custom domains.
-
-## Design Decisions
-
-### Why Google Cloud Storage over Netlify?
-
-**Pros**:
-- **Cost**: GCS + CDN is cheaper at scale (no bandwidth limits on free tier ending)
-- **Control**: Full control over caching, CDN configuration, and infrastructure
-- **Integration**: Native integration with other GCP services (Cloud Run backend, Cloud Build, etc.)
-- **Flexibility**: URL maps enable complex routing if needed
-
-**Cons**:
-- **Setup complexity**: Requires manual GCP resource provisioning
-- **No built-in forms/functions**: Netlify provides these; GCS does not
-- **DNS management**: Requires separate DNS configuration (Netlify provides DNS)
-
-**Decision**: GCS is better for Terreno because it's a showcase/demo project with minimal dynamic needs, and cost/control outweigh convenience.
-
-### Cache Strategy
-
-| File Type | Cache-Control Header | Rationale |
-|-----------|----------------------|-----------|
-| **Hashed assets** (e.g., `main.abc123.js`) | `public, max-age=31536000, immutable` | Content hash in filename ensures uniqueness; safe to cache forever |
-| **index.html** | `no-cache, no-store, must-revalidate` | Entry point must never be cached to ensure users get the latest app shell |
-
-**Implementation**: Deployment workflows use `gsutil -h` to set headers during upload:
-``````bash
-# Sync hashed assets with long cache
-gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
-  rsync -r -d -x '.*\.html$' dist/ gs://BUCKET/
-
-# Upload index.html with no-cache
-gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
-  cp dist/index.html gs://BUCKET/index.html
-``````
-
-### SPA Routing Implementation
-
-**Challenge**: SPAs use client-side routing (e.g., `/about`, `/profile`), but GCS has no such files.
-
-**Solution**:
-1. **GCS `notFoundPage`**: Configure bucket with `notFoundPage=index.html`
-2. **CDN behavior**: When a request for `/about` results in a 404, GCS serves `index.html`
-3. **Client-side routing**: The app's router (Expo Router, React Router) reads the URL and renders the correct component
-
-**Why not `mainPageSuffix`?**
-- `mainPageSuffix=index.html` causes GCS to 301 redirect `/demo/` → `/demo/index.html`, breaking client routing and creating duplicate URLs.
-- `notFoundPage` returns 200 with `index.html` content, preserving the original URL.
-
-### Preview Deployment Strategy
-
-**Goal**: Deploy PR previews to unique URLs without polluting production.
-
-**Approach**:
-- **Path-based isolation**: Previews deploy to `_previews/pr-{number}/` within the same bucket
-- **Bare route objects**: Upload HTML files as bare objects (no `.html` extension) for SPA routing
-- **Dynamic baseUrl**: Inject `expo.experiments.baseUrl = /_previews/pr-123` during build
-
-**Example**:
-``````
-gs://bucket/
-  ├── index.html                         (production)
-  ├── _expo/static/js/main.abc.js        (production)
-  └── _previews/
-      ├── pr-123                         (bare object, serves preview index.html)
-      └── pr-123/
-          ├── index.html                 (preview root)
-          └── _expo/static/js/main.def.js
-``````
-
-**CDN Limitation**: The CDN's `notFoundPage` always serves the root `index.html`, not the preview's. To work around this:
-1. Upload preview routes as bare objects (e.g., `_previews/pr-123/about` → `about.html` uploaded without extension)
-2. Set `Content-Type: text/html` manually
-
-**Trade-off**: This adds complexity but keeps previews in the same bucket, simplifying cleanup.
-
-## Deployment Flow
-
-### Production Deploy
-
-1. **Trigger**: Push to `master` branch with changes to `demo/**`, `ui/**`, `example-frontend/**`, `rtk/**`
-2. **Build**: GitHub Actions runs `bun run export` to generate static files
-3. **Ensure negative caching disabled**: Update backend bucket to prevent cached 404s
-4. **Upload**:
-   - Sync new hashed assets (additive, no deletions) so old bundles remain available
-   - Upload `index.html` with no-cache header, atomically switching to new bundle hashes
-5. **Invalidate CDN**: `gcloud compute url-maps invalidate-cdn-cache --path "/*"` clears all cached paths
-6. **Cleanup**: Sync with deletions (`-d`) to remove old assets no longer referenced
-
-### Preview Deploy
-
-1. **Trigger**: Open PR with changes to relevant paths
-2. **Build**: Inject `baseUrl` and run `bun run export`
-3. **Upload**:
-   - Upload to `_previews/pr-{number}/`
-   - Create bare route objects for SPA routing
-4. **GitHub Deployment**: Create deployment with preview URL
-5. **Comment**: Bot comments on PR with the preview link
-
-### Preview Cleanup
-
-1. **Trigger**: PR closed or merged
-2. **Delete**: `gsutil -m rm -r gs://BUCKET/_previews/pr-{number}/`
-3. **Deactivate**: Mark GitHub deployments as inactive
-
-## Security Considerations
-
-### Public Read Access
-
-**Risk**: Anyone can access bucket contents.
-
-**Mitigation**: Only public-facing demo apps are hosted. No sensitive data or credentials are stored in GCS.
-
-### Service Account Permissions
-
-**Principle of Least Privilege**: The CI service account has:
-- `roles/storage.objectAdmin` on specific buckets (not project-wide)
-- `roles/compute.loadBalancerAdmin` for CDN cache invalidation only
-
-**Key Storage**: `GCP_SA_KEY` secret is encrypted in GitHub Secrets and never logged.
-
-## Cost Optimization
-
-### Storage Costs
-
-- **GCS Standard**: ~$0.02/GB/month
-- **Typical app size**: ~5-10 MB
-- **Monthly cost**: < $0.01/month per app
-
-### CDN Costs
-
-- **Cache hit**: ~$0.08/GB
-- **Cache miss**: ~$0.12/GB (includes origin fetch)
-- **Expected traffic**: Low (demo/example apps)
-- **Monthly cost**: < $5/month for both apps
-
-### Optimization Strategies
-
-1. **Maximize cache hits**: Long cache headers on hashed assets
-2. **Minimize origin fetches**: CDN caches effectively
-3. **Compress assets**: Expo build automatically gzips/brotlis assets
-4. **Delete old previews**: Cleanup workflow prevents accumulation
-
-## Monitoring and Observability
-
-### Metrics
-
-Monitor via GCP Console:
-- **Storage**: Bucket size, object count
-- **CDN**: Cache hit rate, request count, bandwidth
-- **Costs**: Cloud Billing dashboard
-
-### Alerts
-
-Set up budget alerts in GCP:
-``````bash
-gcloud billing budgets create \
-  --billing-account=BILLING_ACCOUNT_ID \
-  --display-name="Terreno Hosting Budget" \
-  --budget-amount=20USD \
-  --threshold-rule=percent=90
-``````
-
-### Logs
-
-- **Access logs**: Enable bucket access logging if needed
-- **CDN logs**: Enable Cloud CDN logging for request analysis
-
-## Future Improvements
-
-### HTTPS Support
-
-1. Reserve a domain (e.g., `demo.terreno.dev`)
-2. Create an SSL certificate:
-   ``````bash
-   gcloud compute ssl-certificates create terreno-demo-cert \
-     --domains=demo.terreno.dev \
-     --global
-   ``````
-3. Create HTTPS proxy and forwarding rule
-4. Update DNS A record
-
-### Custom Domains
-
-Point DNS A records to the static IPs:
-``````
-demo.terreno.dev.     A     34.120.xxx.xxx
-example.terreno.dev.  A     34.149.xxx.xxx
-``````
-
-### CDN Performance Tuning
-
-- **Geo-routing**: Use Cloud Load Balancing for region-specific backends
-- **Compression**: Enable brotli/gzip at CDN level
-- **Pre-warming**: Warm CDN cache after deployments
-
-### Multi-Region Redundancy
-
-- Replicate buckets to multiple regions
-- Use Cloud Load Balancing to route to nearest region
-
-## Related Documentation
-
-- [Deploy to GCP](../how-to/deploy-to-gcp.md) — Step-by-step deployment guide
-- [Environment Variables Reference](../reference/environment-variables.md) — Configure runtime settings
-- [GCP Documentation: Hosting a Static Website](https://cloud.google.com/storage/docs/hosting-static-website) — Official GCS guide

package/dist/docs/versioned/57.18.0/explanation/local-first-data.md

@@ -1,65 +0,0 @@
-# Local-first data in Terreno
-
-Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching with RTK Query.
-
-## What local-first means here
-
-In `@terreno/syncdb`, a TinyBase `MergeableStore` on the device is the **UI source of truth**. When a user taps "save," the mutation applies to local state immediately and lands in a durable outbox. The client then pushes the change to `@terreno/api` over the sync protocol (socket deltas with HTTP snapshot catch-up). The server remains the **authority** for permissions, validation, and conflict resolution — but the UI does not wait on the network for every write.
-
-There is no server-first mode and no opt-in flag: if you use syncdb, you adopt this model for every synced collection.
-
-## Mental model shift
-
-| Server-first (RTK Query) | Local-first (syncdb) |
-|--------------------------|----------------------|
-| UI reads from cache filled by HTTP | UI reads from the local store |
-| Writes call the API, then invalidate/refetch | Writes apply locally, then reconcile |
-| Loading spinners track request lifecycle | Sync status tracks outbox + connectivity |
-| Optimistic updates are manual and fragile | Optimistic state is the default path |
-| Conflicts are rare / ignored | Conflicts are explicit and must be resolved |
-
-Think **apply locally, then reconcile** instead of **request, wait, update cache**.
-
-## What you stop doing
-
-1. **Manual optimistic updates** — `onQueryStarted` patches, temporary IDs, and rollback logic for writes.
-2. **Write-level loading spinners** — `isLoading` on mutations for "saving…" UX; the row updates instantly.
-3. **Refetch orchestration** — `invalidatesTags`, `refetch()`, and list/detail cache coordination after mutations.
-4. **Treating the network as the read path** — list screens blocked on `isLoading` for every navigation.
-
-RTK Query remains appropriate for **non-synced generated** endpoints such as
-`/auth/me` and AI routes. Built-in admin RPC stays request/response through its
-host-bound fetch client; ObjectId/API-only admin CRUD keeps RTK compatibility in
-Terreno 57.
-
-## What you start doing
-
-1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
-2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
-3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
-4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
-5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.
-6. **Collections too large to sync whole** — List them in `createSyncDb({queryCollections})`. They skip snapshot bootstrap; screens load server-filtered *query windows* (`useWindowQuery`) from the `modelRouter` list endpoint. A window stores only membership (ordered ids); rows live once in the shared entity table. Overlapping windows therefore share rows — one delta updates both views — while each view lists only its own query's members, plus cached rows that newly match its `where` inside the loaded range. Live deltas still arrive on the user's normal streams; windows on screen refetch on reconnect to cover deltas missed offline.
-
-## First load and reconnects
-
-A fresh device has to download every row the user can see before the UI is complete. The
-client asks for all of the user's streams in one batched request per round, writes each
-round while the next one downloads, and writes rows in small chunks so the screen stays
-responsive. Reconnects use the same path: when nothing changed, catching up costs two
-requests however many collections the app syncs. Collections too large to download whole
-belong in `queryCollections` instead.
-
-## Tradeoffs
-
-**Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).
-
-**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for existing RTK Query screens.
-
-Server-first fetching is simpler when you only need online CRUD with no offline requirement — but Terreno's blessed path for collection data is local-first.
-
-## Related docs
-
-- [syncdb reference](../reference/syncdb.md) — API ground truth
-- [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) — step-by-step migration
-- [Authentication architecture](authentication.md) — Better Auth + socket sessions

package/dist/docs/versioned/57.18.0/explanation/loop-engineering.md

@@ -1,194 +0,0 @@
-# Loop engineering
-
-Terreno separates engineering method from orchestration:
-
-```text
-                 LOOP
-       orchestrate / persist / wait
-          retry / stop / escalate
-                  |
-                  v
-               GROW
-               shape
-                  |
-                  v
-         PICK ⇄ ROAST  (inner loop)
-         one task, prove it, next task
-                  |
-                  v
-               BREW
-              submit
-                  |
-                  v
-              TASTE
-             react once
-```
-
-Repository knowledge composes underneath every invocation:
-
-```text
-lifecycle stage + project skills + IP/task/state + evidence
-```
-
-## Why fresh invocations
-
-One enormous agent context accumulates assumptions, stale external state, and confidence
-in its own implementation. The lifecycle instead makes every stage reconstructable from
-durable artifacts. Pick can retry from exact Roast evidence; Roast can verify without the
-implementer's assumptions; Taste can react to the current PR head rather than an old
-green result.
-
-Pick continues across tasks in one invocation. Roast proves the current task and
-returns. Each Roast cycle still reconstructs from artifacts and prefers a fresh context
-with a task-scoped briefing (criteria, file list, and patch). Fresh context is for
-independence, not for two children to each reload the repository.
-
-The outer loop decides **when, who, what next, when to retry Taste `PENDING`, and when
-to escalate**. Stages decide how to perform one transition correctly. Pick continues
-the inner loop until the approved task list is done. Roast never invokes Pick. Brew and
-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 fetches latest `master` (merging it only when needed), 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:
-
-- `/terreno-pick-roast-loop` works an approved plan until every task passes Roast or a
-  genuine human decision is required. It resumes only Pick or Roast. Stored `next: brew`
-  completes the loop without launching Brew. It keeps one run ledger and reports all
-  task, retry, evidence, and risk details at the end. A human question includes the
-  overall state, options/impact, and recommendation.
-- `/terreno-planning-loop` runs Grow, then Pick (Pick owns the pick-roast inner loop),
-  then optional Brew/Taste; pass `phases=` to restrict.
-- `/terreno-taste-sweep` drives the author's broken open PRs by reinvoking Taste.
-
-None is a sixth stage.
-
-## The five transitions
-
-| Stage | Question | Primary evidence |
-| --- | --- | --- |
-| Grow | Is the work shaped and approved? | IP/tasks, decisions, criterion→verification map |
-| Pick | Was this slice implemented carefully? | red/green tests, checks, internal reviews; then Roast |
-| Roast | Does this task actually satisfy its criteria? | independent requirement→evidence verdict; emit next Pick or Brew |
-| Brew | Is the verified result correctly submitted? | final checks, commit/head, PR, artifacts |
-| Taste | What is actionable on the current PR head now? | CI on every discovered host, mergeability, reviews, bounded fixes |
-
-Roast is not another implementation review. It independently proves or disproves
-acceptance criteria. Taste is one reactive iteration, not an unbounded fix-until-green
-daemon. It waits until async review bots (Bugbot, CodeQL, and similar) on the current
-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 fetches latest
-`master` (merging it only when needed), 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.
-A host with a documented path/config reason not to run is terminal `skipped`; an
-unexplained missing run is never green.
-
-## Combined plugin, local knowledge
-
-The reusable plugin defines contracts, invariants, evidence, and transitions and bundles
-Terreno's reusable API/UI/data/schema/admin/docs/upgrade/deploy workflows. Repo-local
-skills define only project-specific roadmap, release, and maintenance operations.
-
-Each stage inspects available skills and loads those whose descriptions match the
-affected domain. A useful skill is optional when absent; a capability required by
-repository policy is a hard gate and produces `BLOCKED` if unavailable.
-
-Stages also load architecture docs before acting. Docs are the design; code implements
-them. Missing docs for a user-visible or architectural change is `FAIL`.
-
-This lets the same plugin install provide Pick/Roast plus backend API, test-environment,
-UI, and real-app verification knowledge in consumer projects.
-
-### Terreno's bundled skill layer
-
-Reusable framework skills are canonical inside `plugins/terreno-planning/skills/`.
-Repository-only skills remain under `.rulesync/skills/`. High-value composition points
-include:
-
-| Domain | Repo-local skills stages may discover |
-| --- | --- |
-| Backend/API/data | `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `generate-sdk`, `terreno-data-fetching` |
-| UI/app | `terreno-ui`, `building-terreno-apps`, `verify-ui-changes` |
-| AI/prompts | `ai-prompt-governance` — new features also follow [Develop an AI feature](../how-to/ai-feature-development.md) |
-| 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; 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
-catalog on every invocation.
-
-## State and evidence
-
-The IP remains the design/scope source of truth. The task file remains the execution
-checklist. Lightweight loop-owned state stores only current stage/attempt/task,
-branch/head/PR, the previous structured result, artifacts, attempted approaches, and next
-transition.
-
-The fallback state location is `.terreno/pipeline/<slug>.json`; the outer loop preserves
-or transports it and Brew excludes it from commits unless repository policy says
-otherwise. Stage results follow the plugin's JSON-schema-backed YAML contract and never
-contain chain-of-thought or transcripts.
-
-## Commits and pushes
-
-Every pushed commit starts a full CI run. Harnesses such as Cursor cloud agents push
-every commit automatically, so commit count turns directly into CI runs. Before these
-rules, one 30-commit dashboard PR had ten "mark slice roasted" commits and ten "harden"
-follow-ups, and `ui-ci` stayed red on every commit after the first.
-
-- One behavior-scoped commit per task, after Roast `PASS`: code, tests, docs, and the
-  task-file mark together. Roast-driven fixes fold into that commit.
-- Progress lives in execution state, not in standalone task-file commits.
-- Pick and Roast never push. Brew pushes once. Taste pushes at most once per reaction.
-- Pick does not continue on a head whose product CI shows a branch-caused failure.
-- Pick lists a behavior's edge cases before coding, so Roast proves them instead of
-  discovering them.
-- Roast runs the gate CI will run (root `prepush`, which mirrors the triggered CI jobs),
-  not only the task's test file.
-- Taste fetches `master` before every push but merges it only when the PR conflicts, a
-  failure traces to base drift, or the branch is otherwise merge-ready.
-
-## Direct invocation
-
-Outer loops (`terreno-planning-loop`, `terreno-taste-sweep`) consume Taste `PENDING`
-and invoke Taste again. When a human invokes Taste directly, no loop is waiting, so a
-`PENDING` would only tell them to come back later. In that case Taste uses
-**standalone entry**: it waits in-process with native watches and reacts again. It
-stops on `PASS`, `BLOCKED`, or `FAIL`, or after 3 fix pushes or 3 hours of waiting,
-which ends as `BLOCKED` with one concrete human action. A directly invoked Brew
-starts Taste as its next stage instead of exiting.
-
-## Retry and stop rules
-
-- Pick implements one task, Roast proves it, then Pick takes the next unblocked task.
-  Do not start the next task until Roast PASS. Roast never invokes Pick. Exactly one
-  driver continues after each Roast. Do not pick every task and roast once.
-- Roast failure returns exact expected/actual evidence to Pick for the same task.
-- Engineering retries require a new hypothesis and preserve failed approaches.
-- The focused Pick–Roast outer loop continues through ordinary implementation, test,
-  lint, and Roast failures while a concrete safe engineering action remains. It asks
-  for human input only when evidence cannot choose a product, architecture, security,
-  data, destructive, compatibility, permission, or policy outcome.
-- Taste `PENDING` is for review-bot timeout, product-CI wait timeout, or a second
-  post-fix push. The outer loop then uses native provider watch hooks or harness
-  subscriptions where available and a timer only as fallback, then invokes fresh Taste.
-- Brew waits in-process while Bugbot, CodeQL, or similar review bots are running.
-  Taste waits in-process for those bots and for product CI (`gh` / `circleci` watch
-  loop), then continues without a loop reinvocation unless it timed out.
-- Human decisions are `BLOCKED`, never arbitrary retries.
-- Taste `PASS` requires all current-head jobs on every discovered CI host
-  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/TerrenoLabs/terreno/tree/master/plugins/terreno-planning/references).
-