@terreno/mcp 0.21.0

package/src/docs/versioned/0.19.0/tasks/offline-mode.md

@@ -0,0 +1,139 @@
+# Task List: Offline Mode
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: RTK Core Offline Framework
+
+- [ ] **Task 1.1**: Formalize offline state and queue record types
+  - Description: Extend the offline slice state to represent connection quality, auth-blocked replay, queue record statuses, base timestamps, optimistic/server IDs, and persisted queue versioning. Keep the slice default inert until offline mode is mounted by a consuming app.
+  - Files: `rtk/src/offlineSlice.ts`, `rtk/src/useOfflineStatus.ts`, `rtk/src/index.ts`, related `rtk/src/*.test.ts`
+  - Depends on: none
+  - Acceptance: Unit tests cover enqueue/dequeue/status transitions, conflict storage, auth-blocked state, queue version defaults, and selectors for `online`, `spotty`, `offline`, queued mutations, conflicts, and replay-paused state.
+
+- [ ] **Task 1.2**: Replace endpoint-name-only offline gating with modelRouter config
+  - Description: Introduce a typed `OfflineModelRouterConfig` that maps model names and modelRouter operations to generated RTK Query endpoint names. Preserve a migration path for existing endpoint-name configuration only if it is already shipped behavior; otherwise replace it with the modelRouter config.
+  - Files: `rtk/src/offlineGate.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/index.ts`, `rtk/src/offlineGate.test.ts`
+  - Depends on: Task 1.1
+  - Acceptance: Tests prove disabled/default config never defers mutations, enabled modelRouter endpoints are deferred while offline, unconfigured custom routes are not deferred, and array operations can be configured separately from create/update/delete.
+
+- [ ] **Task 1.3**: Add optimistic create ID strategy
+  - Description: Add default ObjectId-compatible ID generation for optimistic modelRouter creates, inject the generated ID into the configured request field, and support per-model overrides for `generateId`, request field, and server ID reconciliation strategy.
+  - Files: `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineGate.ts`, `rtk/src/offlineIds.ts` (new if useful), `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.2
+  - Acceptance: Tests verify default IDs are stable and ObjectId-shaped, custom generators are used, optimistic create cache entries use the same local ID as the queued mutation, and a server-returned replacement ID can be mapped when explicitly configured.
+
+- [ ] **Task 1.4**: Harden optimistic cache update strategies
+  - Description: Make optimistic cache updates explicit per modelRouter operation while providing safe defaults for create, update, delete, array push, array update, and array remove. Expose an override hook so app teams can customize cache updates for complex list filters or response shapes.
+  - Files: `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineOptimistic.ts` (new if useful), `rtk/src/useOfflineStatus.ts`, related tests
+  - Depends on: Task 1.3
+  - Acceptance: Tests cover optimistic insert, patch, remove, and array mutations against RTK Query cache entries, including rollback or conflict marking when replay fails with a non-network/non-auth error.
+
+- [ ] **Task 1.5**: Pause replay on auth refresh failure without clearing cache
+  - Description: Separate token-refresh failure from explicit logout. If refresh cannot complete because the server/network is unavailable or refresh returns a retryable failure, mark replay as auth-blocked and keep RTK Query cache, queue, conflicts, and optimistic records intact. Reserve destructive cleanup for the actual logout action.
+  - Files: `rtk/src/emptyApi.ts`, `rtk/src/authSlice.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineSlice.ts`, related tests
+  - Depends on: Task 1.1
+  - Acceptance: Tests simulate expired access tokens with unreachable refresh endpoint and verify queued mutations are held, cache data remains, and replay resumes after auth is refreshed; explicit logout still clears tokens and configured offline/cache state.
+
+- [ ] **Task 1.6**: Implement keep-mine and use-server conflict resolution
+  - Description: Add conflict resolution actions/helpers. `useServer` should discard the queued mutation and patch cache to the server value. `keepMine` should update the queued mutation with the latest server timestamp, reapply the local optimistic value, and retry replay with fresh precondition headers.
+  - Files: `rtk/src/offlineSlice.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/useOfflineStatus.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.4
+  - Acceptance: Tests cover `409 Conflict` replay responses, stored local/server values, resolving with `useServer`, resolving with `keepMine`, and preventing duplicate conflict records for the same queued mutation.
+
+## Phase 2: Connection Quality and UI
+
+- [ ] **Task 2.1**: Upgrade server status monitoring to connection quality
+  - Description: Extend `useServerStatus` to compute `online`, `spotty`, and `offline` from browser/native reachability events, health-check failures, latency, and recent failure rate. Make health URL, interval, timeout, latency threshold, failure count, and failure-rate thresholds configurable.
+  - Files: `rtk/src/useServerStatus.ts`, `rtk/src/offlineSlice.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.1
+  - Acceptance: Tests cover all three connection states, threshold overrides, transition from spotty back to online, transition to offline after configured consecutive failures, and no polling when status monitoring is disabled.
+
+- [ ] **Task 2.2**: Expose richer offline status hooks
+  - Description: Expand `useOfflineStatus` to return connection quality, queue length, syncing state, auth-blocked state, conflicts, local-only helpers, and conflict resolution callbacks while preserving low-level selectors for custom UI.
+  - Files: `rtk/src/useOfflineStatus.ts`, `rtk/src/offlineSlice.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.6, Task 2.1
+  - Acceptance: Hook tests or focused unit tests verify returned state and callbacks for queued, syncing, auth-blocked, conflicted, local-only, and healthy states.
+
+- [ ] **Task 2.3**: Update offline banner for online, spotty, offline, syncing, and auth-blocked states
+  - Description: Evolve `OfflineBanner` so apps can show offline, spotty connection, syncing queued changes, pending changes, and auth-blocked sync messaging. Keep props simple enough for custom state sources.
+  - Files: `ui/src/OfflineBanner.tsx`, `ui/src/index.tsx`, `ui/src/OfflineBanner.test.tsx` (new if absent), `demo/stories/OfflineBanner.stories.tsx` (new or update)
+  - Depends on: Task 2.1
+  - Acceptance: UI tests or stories cover hidden/online, spotty, offline, syncing, pending queue, and auth-blocked variants with clear copy and accessible test IDs.
+
+- [ ] **Task 2.4**: Add conflict resolution UI components
+  - Description: Add reusable conflict UI that renders unresolved conflicts and lets users choose "Keep mine" or "Use server". Keep it generic by accepting display renderers for local and server values.
+  - Files: `ui/src/OfflineConflictList.tsx` (new), `ui/src/OfflineConflictCard.tsx` (new), `ui/src/index.tsx`, `ui/src/*.test.tsx`, `demo/stories/OfflineConflict*.stories.tsx`
+  - Depends on: Task 2.2
+  - Acceptance: Tests or stories cover no-conflict, single-conflict, multiple-conflict, keep-mine click, use-server click, dismissed/resolved conflict filtering, and custom value rendering.
+
+## Phase 3: modelRouter Backend Contract
+
+- [ ] **Task 3.1**: Verify client-provided modelRouter create IDs
+  - Description: Add backend tests that prove modelRouter create accepts a client-provided ObjectId-compatible `_id` when the schema allows it and rejects invalid IDs through existing validation/error handling.
+  - Files: `api/src/api.ts`, `api/src/tests/*.test.ts` or existing modelRouter test file, `api/src/tests.ts`
+  - Depends on: Task 1.3
+  - Acceptance: API tests pass for create with client `_id`, returned document keeps that `_id`, duplicate IDs fail safely, and invalid IDs return a clear validation/error response.
+
+- [ ] **Task 3.2**: Formalize conflict response tests for modelRouter updates
+  - Description: Add/extend modelRouter tests for `If-Unmodified-Since` and `X-Unmodified-Since-ISO` headers to guarantee stale updates return `409 Conflict` with the current server document and fresh updates succeed.
+  - Files: `api/src/api.ts`, `api/src/tests/*.test.ts` or existing modelRouter test file
+  - Depends on: none
+  - Acceptance: API tests cover conflict by HTTP-date header, conflict by ISO header, success with current timestamp, missing timestamp behavior, and response body shape consumed by `@terreno/rtk`.
+
+- [ ] **Task 3.3**: Document the modelRouter offline contract
+  - Description: Add docs for modelRouter offline compatibility: supported CRUD/array endpoints, client-provided IDs, conflict headers, expected `409` response shape, permissions behavior, and explicit non-support for custom sync endpoints in v1.
+  - Files: `api/README.md` or package docs, `rtk/README.md` or package docs, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: Docs show a modelRouter route configuration and matching frontend offline config, and clearly state that custom route sync is future work.
+
+## Phase 4: Example App Integration
+
+- [ ] **Task 4.1**: Enable offline mode for example todos
+  - Description: Wire the example frontend store to mount the offline reducer, persist the offline slice, configure todos modelRouter endpoints for offline create/update/delete, and keep API cache persistence consistent with the offline plan.
+  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/_layout.tsx`, `example-frontend/package.json` if scripts need updates
+  - Depends on: Task 1.6, Task 2.2
+  - Acceptance: Example app can create, update, and delete todos while offline; queued todos survive app reload when persistence is enabled; replay syncs after the backend is reachable again.
+
+- [ ] **Task 4.2**: Integrate connection banner and sync state in the example app
+  - Description: Add root-level status monitoring and display `OfflineBanner` for offline, spotty, syncing, pending queue, and auth-blocked states. Ensure copy is visible without disrupting auth navigation.
+  - Files: `example-frontend/app/_layout.tsx`, `example-frontend/app/(tabs)/_layout.tsx`, `example-frontend/app/(tabs)/index.tsx`
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: Manual test can trigger offline/spotty/syncing/auth-blocked states and see the correct banner copy and pending queue count.
+
+- [ ] **Task 4.3**: Add example conflict resolution flow
+  - Description: Show unresolved todo conflicts in the example app and wire "Keep mine" / "Use server" actions to the RTK conflict resolution helpers.
+  - Files: `example-frontend/app/(tabs)/index.tsx`, `example-frontend/components/*` if a local wrapper is useful
+  - Depends on: Task 2.4, Task 4.1
+  - Acceptance: Manual test can create a stale update conflict, see local/server values, choose "Use server" to accept server state, and choose "Keep mine" to replay local state.
+
+- [ ] **Task 4.4**: Add example backend support tests or fixtures for offline scenarios
+  - Description: Ensure the example backend todo model and route can support client IDs and conflict timestamps. Add tests or fixtures that make the example integration verifiable without modifying generated SDK files manually.
+  - Files: `example-backend/src/models/todo.ts`, `example-backend/src/api/todos.ts`, `example-backend/src/**/*.test.ts`
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: Example backend tests pass and confirm todos work with the modelRouter offline contract.
+
+## Phase 5: Verification, Documentation, and Release Readiness
+
+- [ ] **Task 5.1**: Add package-level offline mode docs
+  - Description: Write consumer documentation for enabling offline mode, configuring modelRouter endpoints, selecting ID strategy, configuring connection quality, handling auth-blocked replay, and rendering conflict UI.
+  - Files: `rtk/README.md`, `ui/README.md` if present, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 1.6, Task 2.4, Task 3.3
+  - Acceptance: Docs include copy-pasteable store setup, model config, status hook usage, `OfflineBanner`, and conflict resolution examples.
+
+- [ ] **Task 5.2**: Add end-to-end manual verification guide
+  - Description: Document the exact local steps to verify offline create/update/delete, replay, auth-blocked behavior, spotty status, and conflict resolution using example backend and frontend.
+  - Files: `docs/offline-mode-verification.md` (new) or relevant docs directory, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 4.3
+  - Acceptance: Guide lists setup commands, offline simulation steps, expected UI states, and cleanup steps; it does not require editing generated SDK files manually.
+
+- [ ] **Task 5.3**: Run focused validation suite
+  - Description: Run and fix failures for the focused packages touched by offline mode.
+  - Files: no source changes expected unless validation finds failures
+  - Depends on: Task 5.1, Task 5.2
+  - Acceptance: `bun run rtk:compile` or equivalent package compile passes, `bun run ui:test` passes for new UI tests, `bun run api:test` passes for modelRouter tests, and example package checks used by the repo pass or have documented blockers.
+
+- [ ] **Task 5.4**: Regenerate SDK only if backend API surface changes
+  - Description: If implementation changes OpenAPI output for modelRouter conflict responses or example backend route schemas, regenerate `example-frontend/store/openApiSdk.ts` using the SDK generation workflow. If no OpenAPI surface changed, explicitly skip this task in the implementation PR notes.
+  - Files: `example-frontend/store/openApiSdk.ts`, `example-frontend/openapi-config.ts`
+  - Depends on: Task 3.3, Task 4.4
+  - Acceptance: Generated SDK is updated only from the backend OpenAPI spec and never edited manually; PR notes state whether SDK regeneration was required.

package/src/docs/versioned/0.19.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/src/docs/versioned/0.19.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/src/docs/versioned/0.19.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/src/docs/versioned/0.20.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-server](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.20.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.20.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-server | 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-server
+
+## 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