@terreno/mcp 0.22.2 → 0.23.1

package/dist/docs/versioned/0.23.0/tasks/syncdb-local-first.md

@@ -0,0 +1,117 @@
+# Task List: SyncDB Local-First Data Layer
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: Foundation
+
+- [ ] **Task 1.1**: Scaffold `@terreno/syncdb` package
+  - Description: Create the package with core entrypoints, lifecycle interfaces, and typed configuration.
+  - Files: `syncdb/package.json` (new), `syncdb/src/index.ts` (new), `syncdb/src/types.ts` (new), `syncdb/README.md` (new)
+  - Depends on: none
+  - Acceptance: package compiles and exports `createSyncDbClient` and configuration types.
+
+- [ ] **Task 1.2**: Define storage and sync contracts
+  - Description: Add canonical interfaces for entities, outbox records, sync cursors, conflicts, and keyring entries.
+  - Files: `syncdb/src/storage/types.ts` (new), `syncdb/src/sync/types.ts` (new), `syncdb/src/crypto/types.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: type checks enforce required fields and operations.
+
+## Phase 2: Local DB and Encryption
+
+- [ ] **Task 2.1**: Implement IndexedDB adapter with migrations
+  - Description: Add object stores for entities/outbox/cursors/conflicts/keyring and schema version migration support.
+  - Files: `syncdb/src/storage/indexedDb.ts` (new), `syncdb/src/storage/migrations.ts` (new), `syncdb/src/storage/indexedDb.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: storage CRUD + migration tests pass.
+
+- [ ] **Task 2.2**: Implement key manager (Web Crypto)
+  - Description: Add DEK generation + wrap/unwrap logic and persistence integration.
+  - Files: `syncdb/src/crypto/keyManager.ts` (new), `syncdb/src/crypto/keyManager.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: key lifecycle tests pass for generate/wrap/unwrap/reload.
+
+- [ ] **Task 2.3**: Encrypt IndexedDB payloads at rest
+  - Description: Add AES-GCM envelope encryption/decryption and integrate in storage read/write paths.
+  - Files: `syncdb/src/crypto/envelope.ts` (new), `syncdb/src/storage/secureStorage.ts` (new), `syncdb/src/crypto/envelope.test.ts` (new)
+  - Depends on: Task 2.1, Task 2.2
+  - Acceptance: tests verify no plaintext persistence and successful decrypt roundtrip.
+
+## Phase 3: Local Mutation Engine
+
+- [ ] **Task 3.1**: Add optimistic local mutation application
+  - Description: Apply local patches immediately and retain inverse patches for rollback.
+  - Files: `syncdb/src/mutations/optimistic.ts` (new), `syncdb/src/mutations/optimistic.test.ts` (new)
+  - Depends on: Task 2.3
+  - Acceptance: immediate local apply and rollback tests pass.
+
+- [ ] **Task 3.2**: Implement durable outbox state machine
+  - Description: Persist queued mutations and manage transitions `queued -> inFlight -> acked/conflicted/failed`.
+  - Files: `syncdb/src/mutations/outbox.ts` (new), `syncdb/src/mutations/outbox.test.ts` (new)
+  - Depends on: Task 3.1
+  - Acceptance: replay transition and retry logic tests pass.
+
+- [ ] **Task 3.3**: Implement conflict capture and resolution
+  - Description: Persist conflict records and support `useServer` and `keepMine` resolution paths.
+  - Files: `syncdb/src/mutations/conflicts.ts` (new), `syncdb/src/mutations/conflicts.test.ts` (new)
+  - Depends on: Task 3.2
+  - Acceptance: both resolution strategies correctly update local state and queue state.
+
+## Phase 4: Websocket Delta Sync
+
+- [ ] **Task 4.1**: Build sync transport client
+  - Description: Add websocket connect/auth/reconnect lifecycle and sync event channel handling.
+  - Files: `syncdb/src/sync/transport.ts` (new), `syncdb/src/sync/transport.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: transport lifecycle tests pass including reconnect behavior.
+
+- [ ] **Task 4.2**: Implement cursor-aware delta applier
+  - Description: Apply deltas idempotently with monotonic cursor checks and gap handling.
+  - Files: `syncdb/src/sync/deltaApplier.ts` (new), `syncdb/src/sync/deltaApplier.test.ts` (new)
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: ordered delta tests pass; duplicate/out-of-order deltas are safely handled.
+
+- [ ] **Task 4.3**: Wire ack/nack replay coordinator
+  - Description: Connect outbox replay to server ack/nack responses and conflict creation.
+  - Files: `syncdb/src/sync/replayCoordinator.ts` (new), `syncdb/src/sync/replayCoordinator.test.ts` (new)
+  - Depends on: Task 3.3, Task 4.2
+  - Acceptance: ack finalizes queued mutations; nack creates conflict records.
+
+## Phase 5: App Integration and Migration Bridge
+
+- [ ] **Task 5.1**: Implement React hooks and provider
+  - Description: Add `useEntity`, `useQuery`, `useMutation`, `useSyncStatus`, and context provider wiring.
+  - Files: `syncdb/src/react/provider.tsx` (new), `syncdb/src/react/hooks.ts` (new), `syncdb/src/react/hooks.test.tsx` (new)
+  - Depends on: Task 3.3, Task 4.3
+  - Acceptance: hooks update on local mutations and remote deltas.
+
+- [ ] **Task 5.2**: Add Redux migration bridge
+  - Description: Provide optional adapter for Redux-based consumers transitioning from `@terreno/rtk`.
+  - Files: `syncdb/src/bridge/reduxBridge.ts` (new), `syncdb/src/bridge/reduxBridge.test.ts` (new)
+  - Depends on: Task 5.1
+  - Acceptance: bridge supports selector and dispatch-driven mutation usage.
+
+- [ ] **Task 5.3**: Integrate `example-frontend` todos behind `USE_SYNCDB`
+  - Description: Switch todos flow to syncdb under a feature flag while keeping legacy path available.
+  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/(tabs)/index.tsx`, `example-frontend/app/_layout.tsx`
+  - Depends on: Task 5.1, Task 5.2
+  - Acceptance: flagged path supports offline local create/update/delete and sync reconciliation.
+
+## Phase 6: Codegen and Validation
+
+- [ ] **Task 6.1**: Prototype `@terreno/syncdb-codegen`
+  - Description: Create codegen package that emits typed syncdb operation descriptors from OpenAPI.
+  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/src/index.ts` (new), `syncdb-codegen/src/*.test.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: generator produces valid descriptors for one sample domain.
+
+- [ ] **Task 6.2**: Author migration docs
+  - Description: Document migration path from `@terreno/rtk` to `@terreno/syncdb` and rollout strategy.
+  - Files: `syncdb/README.md`, `docs/implementationPlans/syncdb-local-first.md`
+  - Depends on: Task 5.3
+  - Acceptance: docs include setup, API usage, and feature-flag rollout playbook.
+
+- [ ] **Task 6.3**: Run validation suite
+  - Description: Execute compile, lint, and tests for touched packages and resolve regressions.
+  - Files: as needed in touched packages
+  - Depends on: Task 6.2
+  - Acceptance: relevant compile/lint/test commands pass with no blockers.

package/dist/docs/versioned/0.23.0/tasks/upgrade-banner.md

@@ -0,0 +1,73 @@
+# Task List: Upgrade Banner
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: Backend + Admin
+
+- [ ] **Task 1.1**: Create VersionConfig Mongoose model
+  - Description: Create the VersionConfig model with schema, interface, and TypeScript types in `@terreno/api`. Fields: webWarningVersion, webRequiredVersion, mobileWarningVersion, mobileRequiredVersion, warningMessage, requiredMessage, updateUrl. All version fields default to 0, messages have sensible defaults.
+  - Files: `api/src/models/versionConfig.ts` (create), `api/src/index.ts` (export)
+  - Depends on: none
+  - Acceptance: Model can be imported from `@terreno/api`, compiles cleanly, schema matches spec
+
+- [ ] **Task 1.2**: Add public `GET /version-check` endpoint
+  - Description: Add a built-in public route via VersionCheckPlugin (TerrenoPlugin) that handles `GET /version-check?version=N&platform=web|mobile`. Fetches the singleton VersionConfig, compares the client's build number against the platform-specific thresholds, and returns a JSON object including status and, when a config exists, version threshold fields: `{status, message?, updateUrl?, requiredVersion?, warningVersion?}`. Returns `{status: "ok"}` if no config document exists.
+  - Files: `api/src/versionCheckPlugin.ts` (create - exports VersionCheckPlugin)
+  - Depends on: Task 1.1
+  - Acceptance: Endpoint returns correct status for all combinations: no config → ok, version >= warning → ok, version < warning → warning, version < required → required. No auth required.
+
+- [ ] **Task 1.3**: Add admin `GET/PUT /admin/version-config` routes
+  - Description: Add admin-only routes for reading and upserting the singleton VersionConfig document. GET returns the current config (or defaults if none exists). PUT upserts the document. Both require `Permissions.IsAdmin`. Wire into AdminApp or as standalone admin routes.
+  - Files: `admin-backend/src/adminApp.ts` (modify) or `api/src/routes/versionCheck.ts` (extend)
+  - Depends on: Task 1.1
+  - Acceptance: Authenticated admin can GET and PUT the config. Non-admin gets 403. PUT creates if not exists, updates if exists.
+
+- [ ] **Task 1.4**: Add admin frontend Version Config screen
+  - Description: Create a custom admin screen in `@terreno/admin-frontend` for editing the singleton VersionConfig. Form with all fields, "Save" button that PUTs to `/admin/version-config`. Add it as a special entry in the admin model list or as a standalone screen.
+  - Files: `admin-frontend/src/AdminVersionConfig.tsx` (create), `admin-frontend/src/index.tsx` (export)
+  - Depends on: Task 1.3
+  - Acceptance: Admin can view and edit all version config fields. Save persists to backend. Form loads existing values on mount.
+
+- [ ] **Task 1.5**: Write unit tests for version check logic
+  - Description: Test the version check endpoint logic: no config returns ok, version comparisons for web and mobile platforms, edge cases (version = 0, version = threshold exactly, missing query params).
+  - Files: `api/src/__tests__/versionCheck.test.ts` (create)
+  - Depends on: Task 1.2
+  - Acceptance: All test cases pass covering ok/warning/required status for both platforms.
+
+- [ ] **Task 1.6**: Wire up example backend
+  - Description: Ensure the example backend includes the VersionConfig model and version-check endpoint. Verify the admin panel shows the version config screen.
+  - Files: `example-backend/src/server.ts` (modify if needed)
+  - Depends on: Task 1.3, Task 1.4
+  - Acceptance: Running the example backend exposes `/version-check` and `/admin/version-config`. Admin panel shows the config screen.
+
+## Phase 2: Client + CI
+
+- [ ] **Task 2.1**: Create `UpgradeRequiredScreen` component
+  - Description: Build a full-screen blocking component in `@terreno/ui`. Centered layout with warning icon, configurable message text, and an "Update" button. The button calls an `onUpdate` callback prop. No dismiss, no navigation escape. Props: `message: string`, `onUpdate: () => void`.
+  - Files: `ui/src/UpgradeRequiredScreen.tsx` (create), `ui/src/index.ts` (export)
+  - Depends on: none
+  - Acceptance: Component renders full-screen with message and button. Button triggers onUpdate. No way to dismiss or navigate away.
+
+- [ ] **Task 2.2**: Create `useUpgradeCheck` hook
+  - Description: Build a hook in `@terreno/rtk` that checks `GET /version-check` on mount. Gets build number from `Constants.expoConfig.extra.buildNumber`, platform from existing `IsWeb` util. On "warning": shows persistent toast with message + "Update" button + dismiss X. On "required": returns `{isRequired: true, requiredMessage, onUpdate}`. The `onUpdate` function handles platform logic: web → `window.location.reload()`, mobile → try `expo-updates` `fetchUpdateAsync()`/`reloadAsync()`, fall back to `Linking.openURL(updateUrl)`. Skips check if build number is undefined.
+  - Files: `rtk/src/useUpgradeCheck.ts` (create), `rtk/src/index.ts` (export)
+  - Depends on: Task 1.2
+  - Acceptance: Hook returns correct state for ok/warning/required. Toast appears for warning. isRequired flag set for required. onUpdate triggers appropriate platform action.
+
+- [ ] **Task 2.3**: Add `app.config.ts` build number injection
+  - Description: Create or update `app.config.ts` in the example frontend to dynamically set `expo.extra.buildNumber` from `git rev-list --count HEAD` at build time. Document the pattern for consuming apps.
+  - Files: `example-frontend/app.config.ts` (create/modify), `example-frontend/app.json` (may need adjustment)
+  - Depends on: none
+  - Acceptance: Running `expo start` or `expo build` sets `Constants.expoConfig.extra.buildNumber` to the current git commit count.
+
+- [ ] **Task 2.4**: Wire up example frontend
+  - Description: Add `useUpgradeCheck()` to the example frontend's root layout. When `isRequired` is true, render `UpgradeRequiredScreen` instead of normal app content.
+  - Files: `example-frontend/app/_layout.tsx` (modify)
+  - Depends on: Task 2.1, Task 2.2, Task 2.3
+  - Acceptance: Example app checks version on mount. Warning shows toast. Required shows blocking screen. Normal operation when version is ok or build number is missing.
+
+- [ ] **Task 2.5**: Document GitHub Actions build number pattern
+  - Description: Add a CI snippet or documentation showing how to inject the build number in GitHub Actions workflows using `git rev-list --count HEAD`. Include examples for both EAS Build and web deployments.
+  - Files: `docs/how-to/upgrade-banner.md` (create) or inline in example-frontend README
+  - Depends on: Task 2.3
+  - Acceptance: Clear instructions for consuming apps to set up automatic build numbering in CI.

package/dist/docs/versioned/0.23.0/tutorials/README.md

@@ -0,0 +1,7 @@
+# Tutorials
+
+Learning-oriented, hands-on lessons. Start here if you are new to Terreno.
+
+## Contents
+
+- [Getting started](getting-started.md) — Install, run the examples, and see the stack in action

package/dist/docs/versioned/0.23.0/tutorials/getting-started.md

@@ -0,0 +1,44 @@
+# Getting Started
+
+Run the example full stack to see Terreno in action.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) installed
+- MongoDB running (for the backend example)
+
+## Steps
+
+1. **Clone and install**
+
+   ```bash
+   bun install
+   ```
+
+2. **Start the backend** (terminal 1)
+
+   ```bash
+   bun run backend:dev
+   ```
+
+   Backend runs at `http://localhost:4000`. OpenAPI spec at `/openapi.json`.
+
+3. **Start the frontend** (terminal 2)
+
+   ```bash
+   bun run frontend:web
+   ```
+
+   Frontend runs in the browser and talks to the backend.
+
+4. **Optional: regenerate SDK** after backend route changes
+
+   ```bash
+   cd example-frontend && bun run sdk
+   ```
+
+## Next steps
+
+- [How to create a model](../how-to/create-a-model.md) — Learn model conventions including required field descriptions
+- [How-to guides](../how-to/) — Task-focused guides
+- [Reference](../reference/) — Package and API details

package/dist/docs/versioned/next/reference/environment-variables.md

@@ -146,12 +146,16 @@ The base URL is resolved in priority order:
 
 1. `Constants.expoConfig?.extra?.BASE_URL` (production/staging builds)
 2. `process.env.EXPO_PUBLIC_API_URL` (development web)
-3. `Constants.expoConfig?.hostUri` + `:3000` (dev simulator/device)
-4. `http://localhost:3000` (fallback)
+3. `Constants.expoConfig?.hostUri` + the dev API port (dev simulator/device)
+4. `http://localhost:<dev API port>` (fallback)
+
+The dev API port defaults to `4000` and is overridable per app via `EXPO_PUBLIC_DEV_API_PORT`
+or `expoConfig.extra.DEV_API_PORT` (for example `3000` or `9000`).
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `EXPO_PUBLIC_API_URL` | ❌ | Auto-detected | Backend API base URL<br/>Web: `http://localhost:3000`<br/>Simulator: Auto-detected via `hostUri`<br/>Device: Use your computer's local IP |
+| `EXPO_PUBLIC_API_URL` | ❌ | Auto-detected | Backend API base URL<br/>Web: `http://localhost:4000`<br/>Simulator: Auto-detected via `hostUri`<br/>Device: Use your computer's local IP |
+| `EXPO_PUBLIC_DEV_API_PORT` | ❌ | 4000 | Local dev API port for host/localhost resolution (also settable via `extra.DEV_API_PORT`) |
 
 ### Debug Flags
 

package/dist/docs/versioned/next/reference/rtk.md

@@ -337,8 +337,11 @@ Base RTK Query API with authentication, retry logic, and automatic token refresh
 **Base URL Resolution (priority order):**
 1. `Constants.expoConfig?.extra?.BASE_URL` (production/staging)
 2. `process.env.EXPO_PUBLIC_API_URL` (dev web)
-3. `Constants.expoConfig?.hostUri` + `:3000` (dev simulator/device)
-4. `http://localhost:3000` (fallback)
+3. `Constants.expoConfig?.hostUri` + the dev API port (dev simulator/device)
+4. `http://localhost:<dev API port>` (fallback)
+
+The dev API port defaults to `4000` and is overridable per app via `EXPO_PUBLIC_DEV_API_PORT`
+or `expoConfig.extra.DEV_API_PORT` (for example `3000` or `9000`).
 
 ## Debugging
 
@@ -396,14 +399,18 @@ Configuration for frontend apps using @terreno/rtk:
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `EXPO_PUBLIC_API_URL` | No | Auto-detected | Backend API base URL (production/staging deployments) |
+| `EXPO_PUBLIC_DEV_API_PORT` | No | 4000 | Local dev API port for host/localhost resolution (also settable via `extra.DEV_API_PORT`) |
 | `NODE_ENV` | No | `development` | Environment: `development`, `production`, `test` |
 
 **Base URL resolution priority:**
 
 1. `Constants.expoConfig?.extra?.BASE_URL` (from `app.json` `extra` field)
 2. `process.env.EXPO_PUBLIC_API_URL` (for web development)
-3. `Constants.expoConfig?.hostUri` + `:3000` (for Expo dev server - simulator/device)
-4. `http://localhost:3000` (fallback)
+3. `Constants.expoConfig?.hostUri` + the dev API port (for Expo dev server - simulator/device)
+4. `http://localhost:<dev API port>` (fallback)
+
+The dev API port defaults to `4000` and is overridable per app via `EXPO_PUBLIC_DEV_API_PORT`
+or `expoConfig.extra.DEV_API_PORT` (for example `3000` or `9000`).
 
 **Example `app.json` configuration:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terreno/mcp",
-  "version": "0.22.2",
+  "version": "0.23.1",
   "description": "MCP server for Terreno - provides documentation, tools, and prompts for building full-stack apps",
   "type": "module",
   "main": "dist/index.js",
@@ -27,13 +27,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "0.22.2",
+    "@terreno/api": "0.23.1",
     "minisearch": "^7.2.0",
     "mongoose": "8.23.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.6",
-    "@types/bun": "^1.2.4",
+    "@types/bun": "^1.3.8",
     "@types/node": "^25.3.0",
     "typescript": "~5.9.2"
   },

package/src/docs/versioned/0.23.0/README.md

@@ -0,0 +1,29 @@
+# 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/rtk](reference/rtk.md) | RTK Query utilities for API backends |
+| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
+| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
+| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
+| [@terreno/mcp](reference/mcp-server.md) | AI coding assistant integration (MCP) |
+
+## Quick links
+
+- [Getting started](tutorials/getting-started.md)
+- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
+- [.cursorrules](../.cursorrules) — Project and code style rules

package/src/docs/versioned/0.23.0/explanation/README.md

@@ -0,0 +1,13 @@
+# Explanation
+
+Understanding-oriented documentation: concepts, architecture, and context.
+
+## Contents
+
+- [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
+- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
+- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
+- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter

package/src/docs/versioned/0.23.0/explanation/ai-workflows.md

@@ -0,0 +1,270 @@
+# 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