@terreno/mcp 57.18.0 → 57.20.0

package/src/docs/versioned/next/tasks/ai-dev-loop-boost.md

@@ -13,19 +13,19 @@ See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai
 
 ## Phase 1: Reconcile with merged #802
 
-- [ ] **Task 1.1**: Inventory the actual MCP surface
+- [x] **Task 1.1**: Inventory the actual MCP surface
   - Description: Read `mcp-server/src/tools.ts`, `mcp-server/src/prompts.ts`, `mcp-server/src/resources.ts`, `mcp-server/src/local/localTools.ts`, and every file under `mcp-server/src/local/tools/`. Produce a table of every tool with its exact name, input schema, and which server hosts it. Separately list every environment variable the servers read (`TERRENO_MCP_EVAL`, `TERRENO_METRO_URL`, `TERRENO_PROJECT_ROOT`, `TERRENO_LOG_FILE`, `TERRENO_BROWSER_LOGS`, and any others found). Compare against the tool table in the IP and correct the IP where it is wrong. Put the deltas in the PR body.
   - Files: `docs/implementationPlans/ai-dev-loop-boost.md`
   - Depends on: PR #802 merged
   - Acceptance: every tool in the corrected table is greppable in the source; every environment variable cites its reading file; the PR body lists what differed from the pre-merge IP.
 
-- [ ] **Task 1.2**: Verify the log pipeline end to end
+- [x] **Task 1.2**: Verify the log pipeline end to end
   - Description: Start the example backend and frontend, then exercise each `read_logs` source and record real output: `backend` (winston JSONL file transport), `app` (console output over Metro CDP), `metro` (bundler events), and `browser` (POST fallback). Deliberately break something to produce an error and confirm `last_error` returns it with a stack. Note which sources required extra setup and what happens when Metro is not running. Save the real outputs for use in the documentation tasks.
   - Files: none (findings recorded for later tasks)
   - Depends on: Task 1.1
   - Acceptance: all four sources produced output, or any that did not is documented with the reason; `last_error` output captured verbatim including a stack trace.
 
-- [ ] **Task 1.3**: Reproduce the Hermes CDP contention symptom
+- [x] **Task 1.3**: Reproduce the Hermes CDP contention symptom
   - Description: With `read_logs` connected and streaming `app` source entries, open React Native DevTools (press `j` in Metro) and observe what happens to the log tool. Record the exact status message or failure the tool reports. Then close DevTools and confirm whether the tool recovers automatically. This becomes the documented symptom and workaround.
   - Files: none (findings recorded for later tasks)
   - Depends on: Task 1.2
@@ -33,19 +33,19 @@ See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai
 
 ## Phase 2: Reference completeness
 
-- [ ] **Task 2.1**: Update `docs/reference/mcp-server.md`
+- [x] **Task 2.1**: Update `docs/reference/mcp-server.md`
   - Description: Rewrite the tool sections to match the Task 1.1 inventory exactly. Split clearly into "Hosted server (`terreno-mcp`)" and "Local server (`terreno-mcp-local`)" sections. For each tool: name, purpose, input schema table, example call, and example output. Add an "Environment variables" section listing every variable from Task 1.1 with its effect and default. Add a "What the local server can and cannot see" section — it reads `package.json`/lockfiles, connects to Mongo via the consumer's `.env`, tails log files, and attaches over CDP; it never imports consumer code. Document the Hermes limitation from Task 1.3. Update the hosted URL per IP question AI6 if the domain decision has been made.
   - Files: `docs/reference/mcp-server.md`
   - Depends on: Task 1.1, Task 1.3
   - Acceptance: tool list matches the inventory one-to-one; every environment variable documented; the can/cannot-see section is present; the Hermes symptom is quoted from Task 1.3.
 
-- [ ] **Task 2.2**: Sync `mcp-server/README.md`
+- [x] **Task 2.2**: Sync `mcp-server/README.md`
   - Description: Bring the package README's tool list in line with the reference page (it is known to omit `terreno_search_docs`, `terreno_get_component_docs`, and `terreno_get_upgrade_guide`). Keep the README short — the six-section template from [`docs-reference-coverage`](../implementationPlans/docs-reference-coverage.md) — and link the reference page for full detail.
   - Files: `mcp-server/README.md`
   - Depends on: Task 2.1
   - Acceptance: the README and reference page list identical tool sets; the README follows the standard template; all links absolute.
 
-- [ ] **Task 2.3**: Document the browser-log route
+- [x] **Task 2.3**: Document the browser-log route
   - Description: Add `POST /__terreno/browser-logs` to `docs/reference/api.md` (or the appropriate reference page) documenting: that it is registered only when `NODE_ENV !== "production"`, that it 404s in production, the `TERRENO_BROWSER_LOGS=false` override, the JSONL file it appends to, and the payload shape. Verify all of this against `api/src/browserLogsRoute.ts` in the merged tree.
   - Files: `docs/reference/api.md`, `docs/reference/environment-variables.md`
   - Depends on: Task 1.1
@@ -53,13 +53,13 @@ See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai
 
 ## Phase 3: The loop explainer
 
-- [ ] **Task 3.1**: Write `docs/explanation/ai-development-loop.md`
+- [x] **Task 3.1**: Write `docs/explanation/ai-development-loop.md`
   - Description: Explainer covering the five stages (Ask, Generate, Run, Observe, Fix) with the mermaid diagram from the IP. For each stage, name the tools involved and what they contribute. Then a "Tool layer versus process layer" section using the table from the IP, stating that this page covers the tool layer and that the `/terreno-*` SDLC pipeline is the process layer, with a link to `docs/explanation/agentic-sdlc.md` — do not duplicate that page's content. Then a "What makes this different" section built on one narrow, defensible claim: the agent observes what the app actually did rather than a description of it. Then a "What the agent cannot see" section — production logs, native crash reports outside the dev loop, anything requiring a physical device not attached to a dev server, and the Hermes single-connection limitation. Then a "How this composes" section covering `expo-mcp` for simulator interaction, Playwright MCP for web, and Maestro for durable E2E flows, with the division of labor. No commands — this is conceptual.
   - Files: `docs/explanation/ai-development-loop.md` (new), `docs/explanation/README.md`
   - Depends on: Task 2.1
   - Acceptance: all five stages present with real tool names from the inventory; the tool/process table is present and links the companion page; the cannot-see section has at least four honest limitations; no shell commands; listed in the explanation index.
 
-- [ ] **Task 3.2**: Write `docs/explanation/agent-guidelines.md`
+- [x] **Task 3.2**: Write `docs/explanation/agent-guidelines.md`
   - Description: Explainer on how conventions reach an agent: the hosted server's docs resources and search, per-package `.ai/guidelines/` shipped in npm tarballs (verify whether #802 Phase 2 shipped this before documenting it — if not, describe only what exists and note the rest as planned), `terreno_bootstrap_ai_rules` for generating editor-specific rule files, and the `.rulesync/` source-of-truth pattern with its generated targets. Add a section for consumers on extending the generated rules with their own project conventions without losing them on regeneration.
   - Files: `docs/explanation/agent-guidelines.md` (new), `docs/explanation/README.md`
   - Depends on: Task 1.1
@@ -67,19 +67,19 @@ See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai
 
 ## Phase 4: Setup and debug how-tos
 
-- [ ] **Task 4.1**: Write `docs/how-to/set-up-terreno-mcp.md`
+- [x] **Task 4.1**: Write `docs/how-to/set-up-terreno-mcp.md`
   - Description: Per-editor setup for both Terreno servers. Cover at minimum Cursor (`.cursor/mcp.json`) and Claude Code, with the exact JSON for each including the hosted HTTP entry and the `bunx terreno-mcp-local` stdio entry. Then: what `terreno-mcp-local` needs to work (project root discovery and the `TERRENO_PROJECT_ROOT` override, a reachable `MONGO_URI`, the backend log file, Metro running for app logs); an optional section on adding `expo-mcp` and Playwright MCP with the division of labor from Task 3.1; and a verification section — ask the agent to call `application_info` and confirm it reports the project's `@terreno/*` versions. Compare the JSON against what `terreno_bootstrap_app` actually generates and make them identical.
   - Files: `docs/how-to/set-up-terreno-mcp.md` (new), `docs/how-to/README.md`
   - Depends on: Task 2.1
   - Acceptance: configuration for at least two editors, each verified by actually loading it; the JSON matches bootstrap output byte-for-byte in structure; the `application_info` verification step works.
 
-- [ ] **Task 4.2**: Write `docs/how-to/debug-with-mcp.md`
+- [x] **Task 4.2**: Write `docs/how-to/debug-with-mcp.md`
   - Description: Task-focused guide using the real failure and real outputs captured in Task 1.2. Structure: the symptom; `last_error` to locate it; `read_logs` with source filtering to see the surrounding context; `database_query` to check the data; `get_client_state` to check the client; `navigate` plus a screenshot from the composed server to confirm the fix. Include a "which tool for which symptom" table (app crashes on a screen; API returns 403; data looks wrong; screen renders empty; bundler fails). Use verbatim tool output.
   - Files: `docs/how-to/debug-with-mcp.md` (new), `docs/how-to/README.md`
   - Depends on: Task 1.2, Task 4.1
   - Acceptance: all tool outputs are verbatim from Task 1.2; the symptom-to-tool table has at least five rows; the walkthrough ends with a verified fix.
 
-- [ ] **Task 4.3**: Add discovery paths for the local server
+- [x] **Task 4.3**: Add discovery paths for the local server
   - Description: Nothing currently tells a developer that `terreno-mcp-local` exists. Add links to `docs/how-to/set-up-terreno-mcp.md` from: the README's MCP section, `docs/README.md` quick links, `docs/tutorials/README.md`, and the `terreno://docs/overview` MCP resource. Also confirm `terreno_bootstrap_app` output includes a comment or README line pointing at the setup guide.
   - Files: `README.md`, `docs/README.md`, `docs/tutorials/README.md`, `mcp-server/src/docs/resources/overview.md`, `mcp-server/src/docs/templates/bootstrap/**`
   - Depends on: Task 4.1
@@ -87,33 +87,45 @@ See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai
 
 ## Phase 5: Gap fixes
 
-- [ ] **Task 5.1**: `[RTK]` Rename `get_rtk_state` to `get_client_state`
+- [x] **Task 5.1**: `[RTK]` Rename `get_rtk_state` to `get_client_state`
   - Description: Per IP question AI1, rename the tool to `get_client_state` and extend it to detect either store type, returning a field identifying which layer it found (RTK Query cache versus syncdb store). Keep `get_rtk_state` registered as an alias whose description marks it deprecated and names the replacement. Update the tool description to explain what it returns for each layer. Add tests covering: syncdb store present, RTK store present, neither present, and the alias resolving to the same handler.
   - Files: `mcp-server/src/local/tools/runtime.ts`, `mcp-server/src/local/localTools.ts`, tests under `mcp-server/src/local/`
   - Depends on: Task 1.1, PR #869 merged
   - Acceptance: both names work; the response identifies the detected layer; the alias description marks it deprecated; all four test cases pass; `bun run mcp:build` succeeds.
 
-- [ ] **Task 5.2**: `[RTK]` Relocate the dev console logger
+- [x] **Task 5.2**: `[RTK]` Relocate the dev console logger
   - Description: Per IP question AI2, move `installTerrenoDevConsoleLogger` from `rtk/src/devConsoleLogger.ts` to the syncdb package, keeping a re-export from `@terreno/rtk` for the deprecation window so existing consumers are unaffected. Move its tests with it. Update the bootstrap `_layout` template and `example-frontend/app/_layout.tsx` to import from the new location. Add the re-export to the RTK deprecation notes.
   - Files: `syncdb/src/devConsoleLogger.ts` (moved), `rtk/src/devConsoleLogger.ts` (re-export), `rtk/src/index.ts`, `syncdb/src/index.ts`, `mcp-server/src/docs/templates/bootstrap/frontend/app/_layout.template.tsx`, `example-frontend/app/_layout.tsx`, tests
   - Depends on: Task 5.1
   - Acceptance: both import paths work; tests pass from the new location; `bun run compile` succeeds across the workspace; the example app still ships browser logs to the backend route (verify by producing a `console.error` and reading it back with `read_logs`).
 
-- [ ] **Task 5.3**: Add rate limiting to the hosted MCP server
+- [x] **Task 5.3**: Add rate limiting to the hosted MCP server
   - Description: Per IP question AI5 — a launch prerequisite. Add per-IP rate limiting to the hosted server's JSON-RPC endpoint. Choose limits appropriate to the workload (search and codegen are cheap per call; the index is built once at startup) and make them configurable by environment variable with a sensible default. Return a clear JSON-RPC error when exceeded, naming the limit and the retry window. Add tests for under-limit, at-limit, and over-limit behavior. Document the limit in `docs/reference/mcp-server.md`.
   - Files: `mcp-server/src/index.ts`, tests under `mcp-server/src/`, `docs/reference/mcp-server.md`, `docs/reference/environment-variables.md`
   - Depends on: Task 2.1
   - Acceptance: exceeding the limit returns a structured error naming the limit and retry window; the limit is configurable by environment variable; three test cases pass; the limit is documented.
 
-- [ ] **Task 5.4**: Handle the MCP domain change
+- [x] **Task 5.4**: Handle the MCP domain change
   - Description: If program question P4 / IP question AI6 was answered in favor of moving off `mcp.terreno.flourish.health`, update every occurrence of the URL: `README.md`, `docs/reference/mcp-server.md`, `mcp-server/README.md`, `mcp-server/src/**` defaults, bootstrap templates, and `infra/flourish/` deployment config. Keep the old hostname serving with a redirect or CNAME for at least one release and document the cutover. If the decision was to keep the current domain, make no change and record that.
   - Files: various (grep `rg -n "mcp\.terreno"`)
   - Depends on: Task 2.1
   - Acceptance: `rg -n "mcp\.terreno\.flourish\.health"` returns only intentional legacy references; a bootstrapped app's `mcp.json` uses the new URL; the cutover plan is documented; or the no-change decision is recorded in the PR body.
 
+- [x] **Task 5.5**: Let `terreno-mcp-local` attach to Metro's inspector proxy
+  - Description: Found by Task 1.3. `@react-native/dev-middleware` 0.86 (Expo 57) rejects debugger WebSocket upgrades that carry no `Origin` header (`InspectorProxy.js` `verifyClient`), and neither Bun nor Node sends one, so the `app` log source and every CDP-backed tool fail with `CDP websocket error: ... Expected 101 status code`. Send an `Origin` matching the Metro base URL's loopback origin on the CDP socket, and surface Metro's close code and reason (for example `[NEW_DEBUGGER_OPENED]`) in the status hint instead of the bare `CDP disconnected`. Add tests at the session seam.
+  - Files: `mcp-server/src/local/metro/metroDevSession.ts`, its tests
+  - Depends on: Task 1.3
+  - Acceptance: against a real Metro, `read_logs` with source `app` connects to a debuggable target without a preload shim; when another debugger takes the session, the status names Metro's close reason; tests cover the header and the close-reason hint; `bun run mcp:build` succeeds.
+
+- [x] **Task 5.6**: Make the local database tools load Mongoose under Bun
+  - Description: Found by Task 2.1. `database_schema` and `database_query` call `await import("mongoose")` and read `.connection` on the namespace object; under Bun with Mongoose 9 that property is undefined, so both tools fail with `undefined is not an object (evaluating 'mongoose.connection.readyState')` whenever a Mongo URI is found. Use the module's default export, and add a test that exercises the real import path against the in-memory Mongo used by the package tests.
+  - Files: `mcp-server/src/local/tools/databaseSchema.ts`, `mcp-server/src/local/tools/databaseQuery.ts`, their tests
+  - Depends on: Task 2.1
+  - Acceptance: against the running example database, `database_schema` and `database_query` return real results through `terreno-mcp-local`; tests fail before the fix and pass after; `bun run mcp:build` succeeds.
+
 ## Phase 6: Verification
 
-- [ ] **Task 6.1**: Run the loop end to end and capture evidence
+- [x] **Task 6.1**: Run the loop end to end and capture evidence
   - Description: In a fresh agent session with both MCP servers configured per `docs/how-to/set-up-terreno-mcp.md`, complete a full loop: ask for a small feature, let the agent generate it, run the app, introduce a bug, use `last_error` and `read_logs` to find it, fix it, and verify with `navigate` plus a screenshot. Capture the transcript highlights and screenshots to `/opt/cursor/artifacts/`. Fix any documentation gap the run exposed.
   - Files: any documentation needing correction
   - Depends on: Task 4.2, Task 5.1, Task 5.3

package/src/docs/versioned/next/tasks/infra-mcp.md

@@ -34,7 +34,8 @@ Status: Blocked — Phase 1 RBAC wiring depends on the RBAC module PR ([rbac-per
 - [ ] `ProxiedAdapter`: `@modelcontextprotocol/client` (stdio + HTTP), deny-by-default `allowedTools` with mandatory tier annotations, tool name prefixing, upstream lifecycle management
 - [ ] Reference proxied integration (`@sentry/mcp-server` stdio or `@google-cloud/observability-mcp`) with parity tests against native tools
 - [ ] Expo/EAS native adapter (`EXPO_TOKEN`): build status, update status, submission status (read); trigger tools deferred to write expansion
-- [ ] Vercel native adapter (API token): deployments, logs, project info (read)
+- [ ] Vercel native adapter (one team token per team, project→team by lookup): `vercel_list_projects`, `vercel_list_deployments`, `vercel_runtime_logs` via `POST /v1/observability/events` (read); `vercel.read` RBAC scope limiting machine users to their own projects. Port from the hive dogfood implementation
+- [ ] Per-sandbox machine users for orchestrated agents: mint user + service token at sandbox create, revoke at teardown; per-resource allow-list consumed by integration scopes
 
 ## Phase 4 — OSS packaging
 

package/src/docs/versioned/next/tutorials/README.md

@@ -5,3 +5,7 @@ Learning-oriented, hands-on lessons. Start here if you are new to Terreno.
 ## Contents
 
 - [Getting started](getting-started.md) — Scaffold a new app with `create-terreno-app`, run it locally, or explore monorepo examples
+
+## Next steps
+
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md) — Connect your editor to the hosted `terreno` server and the local `terreno-mcp-local` server (logs, last error, client state, database)

package/dist/docs/versioned/57.1.0/README.md

@@ -1,43 +0,0 @@
-# Terreno Documentation
-
-Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
-
-## Structure
-
-- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
-- **[How-to guides](how-to/)** — Problem-oriented, practical steps
-- **[Reference](reference/)** — Technical reference for APIs and packages
-- **[Explanation](explanation/)** — Concepts and context
-- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
-
-## Packages
-
-| Package | Description |
-|---------|-------------|
-| [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
-| [@terreno/ui](reference/ui.md) | React Native UI component library |
-| [@terreno/syncdb](reference/syncdb.md) | Local-first data layer (offline sync, conflicts) |
-| [@terreno/ai](reference/ai.md) | AI service, GPT routes, request logging |
-| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
-| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
-| [@terreno/admin-spa](reference/admin-spa.md) | Standalone admin SPA + Express serve plugin |
-| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
-| [@terreno/comms](reference/comms.md) | Pluggable communications providers |
-| [@terreno/feature-flags](reference/feature-flags.md) | Feature flags and A/B testing plugin |
-| [@terreno/mcp](reference/mcp-server.md) | AI coding assistant integration (MCP) |
-| [@terreno/test](reference/test.md) | Bun test helpers and in-memory MongoDB |
-
-### Legacy
-
-| Package | Description |
-|---------|-------------|
-| [@terreno/rtk](reference/legacy/rtk.md) (deprecated) | RTK Query utilities — superseded by syncdb for data sync; still used for OpenAPI SDK, auth, and feature flags during migration |
-
-**Migrating from RTK?** See [How to migrate from @terreno/rtk to @terreno/syncdb](how-to/migrate-rtk-to-syncdb.md).
-
-## Quick links
-
-- [Getting started](tutorials/getting-started.md)
-- [Local-first data](explanation/local-first-data.md)
-- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
-- [ROADMAP.md](../ROADMAP.md) — Public roadmap

package/dist/docs/versioned/57.1.0/explanation/README.md

@@ -1,23 +0,0 @@
-# Explanation
-
-Understanding-oriented documentation: concepts, architecture, and context.
-
-## Deployment
-
-- [Deployment baseline](deployment-baseline.md) — seven requirements for production Terreno apps
-- [GCP deployment architecture](deployment-architecture-gcp.md) — Cloud Run + GCS/CDN topology and tradeoffs
-- [GCP hosting architecture](gcp-hosting-architecture.md) — static site hosting with GCS and Cloud CDN (legacy detail)
-
-## Contents
-
-- [Local-first data](local-first-data.md) — Why the local store is the UI source of truth
-- [Loop engineering](loop-engineering.md) — Fresh-invocation lifecycle, state, evidence, and orchestration boundaries
-- [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add TerrenoLabs/terreno`
-- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
-- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
-- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
-- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
-- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
-- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
-- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels
-- [Positioning](positioning.md) — Canonical copy blocks and the honest Django/Rails comparison

package/dist/docs/versioned/57.1.0/explanation/admin-plugin-frontend.md

@@ -1,12 +0,0 @@
-# Admin plugin frontend widgets
-
-Backend plugins contribute stable widget IDs through `adminContribution()`. Their React
-implementations ship from `@terreno/admin-frontend`, under `src/widgets/`.
-
-This keeps the first-party integration in one frontend package and avoids making backend-only
-packages depend on React Native. The built-in registry includes consent field widgets, feature
-flag home widgets, and Documents/AI custom screens. Hosts can override any ID through
-`AdminProvider.widgets`.
-
-Third-party plugins should publish their own frontend package and ask the host to spread its
-registry into `AdminProvider`; `@terreno/admin-frontend` only owns first-party Terreno widgets.

package/dist/docs/versioned/57.1.0/explanation/ai-workflows.md

@@ -1,270 +0,0 @@
-# AI-Powered Workflows
-
-Understanding Terreno's autonomous AI workflows for continuous improvement.
-
-## Overview
-
-Terreno uses GitHub Actions with AI agents to maintain code quality, documentation, and developer experience. These workflows run automatically and create pull requests when improvements are needed.
-
-## Workflow Categories
-
-### Documentation Workflows
-
-#### Update Docs
-**Trigger:** Push to master  
-**Purpose:** Keeps documentation synchronized with code changes
-
-Analyzes code diffs after each merge to identify:
-- New or changed APIs, functions, classes
-- Missing or outdated documentation
-- Documentation gaps that need attention
-
-**Output:** Draft pull requests with documentation updates following the Diátaxis framework (tutorials, how-to guides, reference, explanation).
-
-**Philosophy:** Treats documentation gaps like failing tests — they must be fixed.
-
-#### Update Rules
-**Trigger:** Push to master  
-**Purpose:** Keeps AI assistant rules synchronized with codebase changes
-
-Maintains the single source of truth in `.rulesync/rules/` and ensures:
-- `.cursorrules` (Cursor IDE)
-- `.windsurfrules` (Windsurf IDE)
-- `AGENTS.md` (Claude Code, Copilot)
-- `.github/copilot-instructions.md` (GitHub Copilot)
-
-**Workflow:**
-1. Detects package changes, new APIs, or convention updates
-2. Updates source files in `.rulesync/rules/`
-3. Creates PR with instructions to run `bun run rules` to regenerate outputs
-4. Ensures `rulesync-check` CI passes
-
-**Key insight:** Rule files are code — they must be kept in sync with implementation.
-
-### Code Quality Workflows
-
-#### Daily JSDoc Improver
-**Trigger:** Daily schedule + push to master  
-**Purpose:** Systematically improves JSDoc documentation across the codebase
-
-**Two modes:**
-- **Targeted (on push):** Improves JSDoc for files changed in recent commits
-- **Systematic (daily):** Three-phase approach covering entire codebase
-
-**Output:** Draft PRs with improved JSDoc comments on exported functions, methods, and classes.
-
-#### Daily Test Improver
-**Trigger:** Daily schedule  
-**Purpose:** Enhances test coverage and test quality
-
-Analyzes test files and implementation to:
-- Add missing test cases
-- Improve test clarity and coverage
-- Identify edge cases that need testing
-- Ensure tests follow best practices
-
-**Output:** Draft PRs with test improvements.
-
-### Maintenance Workflows
-
-#### Agentic Maintenance
-**Trigger:** Daily at 00:37 UTC  
-**Purpose:** Cleans up expired issues, discussions, and pull requests
-
-Automatically closes expired entities based on the `expires` field in safe-outputs configuration. Schedule is determined by the shortest expiration time across all workflows.
-
-**Prevents:** Stale issues and PRs from accumulating.
-
-#### RulesSync Check
-**Trigger:** Pull request  
-**Purpose:** Validates that generated rule files are synchronized with sources
-
-**Validation steps:**
-1. Runs `bun run rules` to regenerate outputs
-2. Checks for uncommitted changes
-3. Fails if generated files don't match committed versions
-
-**Prevents:** Merging PRs with out-of-sync rule files.
-
-## CI/CD Workflows
-
-### Package Testing
-
-Each package has its own CI workflow that runs on pull requests and pushes:
-
-| Workflow | Package | Tests |
-|----------|---------|-------|
-| `api-ci.yml` | @terreno/api | Unit tests, type checking, linting |
-| `ui-ci.yml` | @terreno/ui | Component tests, type checking, linting |
-| `rtk-ci.yml` | @terreno/rtk | Unit tests, type checking, linting |
-| `mcp-server-ci.yml` | @terreno/mcp | Integration tests, type checking, linting |
-| `example-backend-ci.yml` | example-backend | Integration tests, type checking |
-| `example-frontend-ci.yml` | example-frontend | Build verification, type checking |
-| `ui-demo-ci.yml` | demo | Build verification, type checking |
-
-### Deployment Workflows
-
-#### Demo Deploy
-**Trigger:** Push to master  
-**Purpose:** Deploys UI demo to Google Cloud Storage with Cloud CDN
-
-**Architecture:** Static site hosting with custom domain, SSL, and CDN acceleration.
-
-**Learn more:** [GCP Hosting Architecture](gcp-hosting-architecture.md), [Deploy to GCP](../how-to/deploy-to-gcp.md)
-
-#### Frontend Example Deploy
-**Trigger:** Push to master, pull request  
-**Purpose:** Deploys example frontend with preview environments
-
-**Features:**
-- **Production:** Deploys to production GCS bucket on master
-- **Preview:** Creates preview environments for pull requests
-- **Cleanup:** Automatically removes preview environments when PRs close
-
-#### MCP Server Deploy
-**Trigger:** Push to master  
-**Purpose:** Deploys Model Context Protocol server
-
-Builds and deploys the MCP server for AI coding assistant integration.
-
-#### Preview Cleanup
-**Trigger:** Pull request close  
-**Purpose:** Removes preview deployments when PRs are closed or merged
-
-Ensures preview environments don't accumulate and waste resources.
-
-### Security & Quality
-
-#### CodeQL Analysis
-**Trigger:** Push to master, pull request, schedule (weekly)  
-**Purpose:** Security vulnerability scanning with GitHub CodeQL
-
-**Languages analyzed:** JavaScript, TypeScript
-
-**Output:** Security alerts in the Security tab when vulnerabilities are found.
-
-#### Dependabot Auto-merge
-**Trigger:** Dependabot pull request opened  
-**Purpose:** Automatically merges dependency updates after CI passes
-
-**Requirements for auto-merge:**
-- All CI checks pass
-- Dependabot PR (created by Dependabot)
-- No conflicts
-- 7-day cooldown for security (see Dependency Management)
-
-**Learn more:** [Dependency Management](dependency-management.md)
-
-### Publishing
-
-#### Publish on Tag
-**Trigger:** Tag push matching `v*.*.*`  
-**Purpose:** Publishes packages to npm registry
-
-**Workflow:**
-1. Validates tag format and package versions match
-2. Runs full test suite
-3. Publishes to npm with appropriate tags (`latest` or `next`)
-4. Creates GitHub release with changelog
-
-**Packages published:**
-- @terreno/api
-- @terreno/ui
-- @terreno/rtk
-- @terreno/mcp
-
-## Workflow Philosophy
-
-### Single Source of Truth
-- **Documentation:** Code is truth, docs must reflect it
-- **Rules:** `.rulesync/rules/` is truth, generated files derive from it
-- **Tests:** Implementation is truth, tests verify it
-
-### Fail Fast
-- All checks must pass before merge
-- Generated files must be committed (no drift)
-- Documentation gaps are treated like failing tests
-
-### Autonomous Improvement
-- Workflows create PRs, not commits
-- PRs are drafts requiring human review
-- Workflow agents make suggestions, humans make decisions
-
-### Continuous Sync
-- Documentation syncs on every master push
-- Rules sync on every master push
-- Dependencies update daily (Dependabot)
-- Quality improvements run daily (JSDoc, tests)
-
-## Working with AI Workflows
-
-### When a Workflow Creates a PR
-
-1. **Review the changes** — AI is helpful but not perfect
-2. **Run suggested commands** — E.g., `bun run rules` for rule updates
-3. **Test locally** — Ensure changes work as intended
-4. **Approve or close** — Merge if valuable, close if not
-
-### When a Workflow Fails
-
-Check the workflow run logs in the Actions tab:
-- **Documentation updates:** May need manual clarification
-- **Rule updates:** May need manual fixes to `.rulesync/rules/`
-- **JSDoc/test improvements:** May need guidance on conventions
-
-### Customizing Workflows
-
-Workflow definitions live in `.github/workflows/*.md` files. These are compiled into `.github/workflows/*.lock.yml` by the GitHub Agentic Workflows CLI.
-
-**To customize:**
-1. Edit the `.md` source file (e.g., `update-docs.md`)
-2. Run `gh aw compile` (if using gh-aw CLI)
-3. Commit both the `.md` and regenerated `.lock.yml`
-
-**Note:** Never edit `.lock.yml` files directly — they are generated.
-
-## Best Practices
-
-### For Maintainers
-- **Review workflow PRs regularly** — Don't let them accumulate
-- **Provide feedback** — If a workflow generates bad suggestions, close with a comment explaining why
-- **Tune prompts** — If a workflow consistently misses the mark, update the `.md` file
-
-### For Contributors
-- **Run CI before pushing** — `bun run lint && bun run test`
-- **Update rules if needed** — `bun run rules` after changing `.rulesync/rules/`
-- **Check workflow status** — Ensure your PR doesn't break workflows
-
-### For Users
-- **Check Actions tab** — See what's running and what's pending
-- **Review draft PRs** — Workflow-generated PRs may contain useful improvements
-- **Report issues** — If a workflow behaves unexpectedly, open an issue
-
-## Troubleshooting
-
-### Workflow doesn't run when expected
-- Check `.github/workflows/*.yml` trigger configuration
-- Verify branch name matches (usually `master`)
-- Check workflow permissions and safe-outputs limits
-
-### RulesSync check fails on PR
-- Run `bun run rules` locally
-- Commit any generated file changes
-- Ensure `.rulesync/rules/` files have valid YAML frontmatter
-
-### Dependabot PR doesn't auto-merge
-- Verify all CI checks pass (green checkmarks)
-- Check 7-day cooldown hasn't been violated
-- Ensure no merge conflicts exist
-
-### AI workflow creates poor quality PR
-- Review the workflow definition in `.github/workflows/*.md`
-- Consider customizing the prompt or instructions
-- Close the PR with feedback for future improvements
-
-## Related Documentation
-
-- [Dependency Management](dependency-management.md) — Dependabot configuration and auto-merge
-- [Deploy to GCP](../how-to/deploy-to-gcp.md) — Manual deployment guide
-- [GCP Hosting Architecture](gcp-hosting-architecture.md) — Static site hosting design
-- [Environment Variables](../reference/environment-variables.md) — Configuration reference