@terreno/mcp 0.24.0 → 0.26.0

package/dist/docs/versioned/0.24.0/tasks/admin-ui-v2-django-parity.md

@@ -0,0 +1,135 @@
+# Task List: Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+**Status:** All phases below are complete. See `docs/implementationPlans/admin-ui-v2-django-parity.md` for acceptance criteria (also marked complete) and verification pointers.
+
+**Companion:** **Admin script runner** — `docs/implementationPlans/admin-script-runner.md` + `docs/tasks/admin-script-runner.md` (same delivery; documents `/admin/scripts/*`, `BackgroundTask`, and UI).
+
+See: `docs/implementationPlans/admin-ui-v2-django-parity.md` for full plan.
+
+## Phase 1: Admin config contract (backend)
+
+- [x] **Task 1.1**: Extend `AdminConfigResponse` / `GET /admin/config` for schema v2  
+  - Description: Add `schemaVersion`, per-model `group`, `listDisplay`, `listDisplayLinks`, `sortableFields`, `searchFields`, `filters` (typed: boolean, choice, text, dateRange, ref), `fieldsets`, `readonlyFields`, `hiddenFields`, declared `actions` (sync vs `background: true`), `permissions` (`create`/`update`/`delete` booleans), `pageSize`, `realtime`, `home` with **`title` + `slots`** (`navGlobal?`, `contentTop?`, `main?`, `sidebar?` — each an ordered `string[]` of widget ids; Django template-block analogue). Optionally accept legacy `home.widgets[]` for migration → normalize into `slots.main` + `recentActivity` forced last in `sidebar`. Include `customScreens`, existing `scripts`. Preserve v1 config fields for backward compatibility.  
+  - Files: `admin-backend/src/adminApp.ts`, `admin-backend/src/index.ts` (exports if needed), tests under `admin-backend/src/*.test.ts`  
+  - Depends on: none  
+  - Acceptance: Typed response; tests assert v1 fields still present; new fields optional-safe for old clients.
+
+- [x] **Task 1.2**: Document OpenAPI for extended config  
+  - Description: Ensure generated OpenAPI documents the new response shape (or manual `openApiBuilder` attachment on config route if required).  
+  - Files: `admin-backend/src/adminApp.ts`  
+  - Depends on: 1.1  
+  - Acceptance: `openapi.json` from a test server includes `/admin/config` response schema additions.
+
+## Phase 2: Bulk patch + background tasks (backend)
+
+- [x] **Task 2.1**: Implement `POST {basePath}{routePath}/bulk-patch`  
+  - Description: Body `{ ids: string[]; patch: Record<string, unknown> }`. Enforce **max 1000** ids. Allowlist patch keys per model from config (or from schema paths). Use `updateMany` / batched updates with per-id validation where needed. Return `{ updated: number; failures?: ... }`.  
+  - Files: `admin-backend/src/adminApp.ts`, new helper module if >300 LOC, tests  
+  - Depends on: 1.1  
+  - Acceptance: Tests for cap, unknown keys rejected, partial failure reporting; `IsAdmin` only.
+
+- [x] **Task 2.2**: Implement `POST /admin/background-tasks` (name finalized in code)  
+  - Description: Map prototype `background: true` actions to enqueue `BackgroundTask` (or existing script runner) with `kind`, target route, ids, metadata. Return `{ taskId }`. Reuse logging/error patterns from script routes.  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 1.1, 2.1 (shared validation helpers optional)  
+  - Acceptance: Test covers enqueue + 403 non-admin; OpenAPI entry exists.
+
+## Phase 3: modelRouter metadata parity (backend / examples)
+
+- [x] **Task 3.1**: Align `modelRouter` registration options with config lists  
+  - Description: For each model exposed in `example-backend` (or chosen demo), set `queryFields`, `sort`, `defaultLimit`/`maxLimit`, `responseHandler` for hidden fields, and `permissions.delete: []` for DotPhrase-style demo.  
+  - Files: `example-backend/src/**`, any consumer `AdminApp` registration  
+  - Depends on: 1.1  
+  - Acceptance: List queries accept filters used in UI; delete disabled where specified.
+
+## Phase 4: Admin frontend — shell + navigation
+
+- [x] **Task 4.1**: Admin shell (sidebar groups, screens, tools, user footer)  
+  - Description: New layout components using `@terreno/ui`; consume config for groups and `customScreens`; support `apiBase`/`routeBase` from prior admin-spa work.  
+  - Files: `admin-frontend/src/**` (new shell module + exports in `index.tsx`)  
+  - Depends on: 1.1  
+  - Acceptance: Lint/compile; story or test renders grouped nav from mock config.
+
+- [x] **Task 4.2**: Top bar breadcrumbs + contextual actions  
+  - Description: Match prototype routes (home, list, form, tool, screen); “Add {singular}” when `permissions.create !== false`.  
+  - Files: `admin-frontend/src/**`  
+  - Depends on: 4.1  
+  - Acceptance: Unit test for breadcrumb labels from route + model meta.
+
+## Phase 5: Admin frontend — list (changelist)
+
+- [x] **Task 5.1**: List view v2 — search, filters, sort, pagination  
+  - Description: Wire `DataTable` to server sort/page; debounced search; typed filters mapped to query params; `listDisplayLinks` drives link columns; inline boolean uses PATCH.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, hooks, types  
+  - Depends on: 1.1, 3.1, 4.1  
+  - Acceptance: Tests with MSW or harness for query serialization; loading/error/empty states.
+
+- [x] **Task 5.2**: Bulk selection + action menu  
+  - Description: Sync actions call `bulk-patch`; confirm modals for `confirm` strings; background actions call enqueue endpoint; cap selection client-side at 1000 with user-visible message.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, possibly `AdminScriptRunModal.tsx` reuse  
+  - Depends on: 2.1, 2.2, 5.1  
+  - Acceptance: Tests for confirm + request bodies.
+
+## Phase 6: Admin frontend — form (change view)
+
+- [x] **Task 6.1**: Fieldsets + readonly + exclude/hidden fields  
+  - Description: Render `fieldsets` with `Accordion`/`Card`; readonly fields not submitted; hidden fields omitted from form and detail panels as specified.  
+  - Files: `admin-frontend/src/AdminModelForm.tsx`, types  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Test that PATCH body excludes readonly keys.
+
+- [x] **Task 6.2**: Autocomplete ref picker  
+  - Description: Debounced fetch against referenced model list endpoint; keyboard/accessibility basics.  
+  - Files: `admin-frontend/src/AdminRefField.tsx` or new component, tests  
+  - Depends on: 5.1 (shared debounce util optional)  
+  - Acceptance: Unit test uses mock list API.
+
+## Phase 7: Home dashboard widgets
+
+- [x] **Task 7.1**: Widget registry + **`home.slots`** layout  
+  - Description: Implement built-ins: `modelStats`, `modelsGrid`, `feature-flags-overrides` (or generic “quick toggles” plugin slot), `versionConfig` summary, `scriptRunner`, `recentActivity`. Render regions in order: **`navGlobal`** (horizontal strip) → **`contentTop`** (full-width above grid) → **`main` | `sidebar`** (two-column). Enforce **`recentActivity` last within `sidebar`** when present. Validate unknown widget ids in dev.  
+  - Files: `admin-frontend/src/**` (new `AdminHome.tsx` or similar), exports  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Tests: (1) `scriptRunner` only in `navGlobal` does not mount inside `main` model grid; (2) `recentActivity` is last in `sidebar` when configured.
+
+## Phase 8: admin-spa + example integration
+
+- [x] **Task 8.1**: Wire new shell + routes in `admin-spa`  
+  - Description: Routes for home v2, list, form, tools, deep links to plugin URLs for screens; regenerate admin SDK if needed.  
+  - Files: `admin-spa/app/**`, `admin-spa/store/**`  
+  - Depends on: 4.x–7.x  
+  - Acceptance: `bun run admin-spa:compile` / smoke script; manual checklist in plan.
+
+- [x] **Task 8.2**: Example-backend registration + seed  
+  - Description: Register illustrative models + `AdminApp` config entries matching v2 demo shape (subset acceptable).  
+  - Files: `example-backend/**`  
+  - Depends on: 3.1  
+  - Acceptance: Running example + admin-spa exercises list/form/home.
+
+## Phase 9 (last): Audit log + recent actions
+
+- [x] **Task 9.1**: `AdminAuditLog` model + persistence (consumer or example-backend)  
+  - Description: Schema with descriptions, indexes on `created`, `modelName`, `actorId`. Optional TTL for retention.  
+  - Files: `example-backend/src/models/**` (or consumer app), types  
+  - Depends on: 8.2 (demo path)  
+  - Acceptance: Model compiles; `checkModelsStrict` happy in non-prod.
+
+- [x] **Task 9.2**: `modelRouter` or read-only list route for audit entries  
+  - Description: `GET` list with pagination, `IsAdmin`, sort `-created`. Consider create-only via internal hooks (no public POST from browser) — prefer server-side logging middleware writing entries.  
+  - Files: `example-backend/src/api/**`, tests  
+  - Depends on: 9.1  
+  - Acceptance: supertest list route returns inserted fixture rows.
+
+- [x] **Task 9.3**: Emit audit rows from admin mutations  
+  - Description: Hook `postUpdate`/`postCreate`/`postDelete` on registered admin models or central middleware in `AdminApp` to write `AdminAuditLog` with verb + label resolution.  
+  - Files: `admin-backend/src/adminApp.ts` and/or example-backend hooks  
+  - Depends on: 9.2  
+  - Acceptance: `onAdminAudit` fires after POST/PATCH/DELETE on admin model routes — **`admin-backend/src/adminApp.models.test.ts`** (`describe("AdminApp onAdminAudit")`). Consumer persistence: `example-backend/src/server.ts` (`AdminAuditLog.create` in `onAdminAudit`).
+
+- [x] **Task 9.4**: Home `recentActivity` widget backed by API  
+  - Description: Fetch latest N audit rows; render as the **final widget in `home.slots.sidebar`**; empty/error states.  
+  - Files: `admin-frontend/src/**` (home widget), `useAdminApi` or dedicated hook  
+  - Depends on: 7.1, 9.3  
+  - Acceptance: UI or integration test shows `recentActivity` below other **sidebar** widgets when multiple sidebar ids are configured.

package/dist/docs/versioned/0.24.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.25.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/dist/docs/versioned/0.25.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

package/dist/docs/versioned/0.25.0/how-to/README.md

@@ -0,0 +1,21 @@
+# How-to Guides
+
+Problem-oriented, practical steps. Use these when you know what you want to do.
+
+## Contents
+
+- [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
+- [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
+
+## Coming Soon
+
+- [Add feature flags](add-feature-flags.md) — Add feature flags and A/B testing to your app
+- Add custom permissions
+- Implement file uploads
+- Configure email notifications
+- Customize AI workflows
+- Set up custom CI/CD pipelines