@terreno/mcp 0.25.0 → 0.26.0

package/src/docs/versioned/0.25.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/src/docs/versioned/0.25.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/src/docs/versioned/next/explanation/README.md

@@ -11,3 +11,4 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [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
+- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels

package/src/docs/versioned/next/explanation/no-barrel-imports.md

@@ -0,0 +1,49 @@
+# No barrel imports
+
+Terreno avoids **barrel imports** — imports that resolve through an `index.ts` / `index.tsx` file that only re-exports other modules.
+
+## Why
+
+- **Clearer dependencies**: each import names the file that defines the symbol.
+- **Faster tooling**: bundlers and TypeScript do less re-export chasing.
+- **Fewer cycles**: internal barrels (especially package `index` files) are a common source of circular dependencies.
+
+## Allowed
+
+- **Published package APIs** — cross-package imports like `@terreno/api`, `@terreno/ui`, and `@terreno/rtk` use each package's public `src/index` entry. That is intentional.
+- **Package public entry files** — `api/src/index.ts`, `ui/src/index.tsx`, etc. may re-export for npm consumers. Do not import those barrels from *inside* the same package.
+- **Expo Router routes** — `app/**/index.tsx` files are route entries, not barrels.
+
+## Not allowed
+
+Internal barrel `index` files do not exist in this repo — the Biome `noBarrelFile` override bans creating them, so a directory import like `../models` has nothing to resolve to and fails to compile.
+
+Importing a directory that resolves to a re-exporting index file:
+
+```typescript
+// Bad — resolves to models/index.ts
+import {User} from "../models";
+
+// Good — imports the defining module
+import {User} from "../models/user";
+```
+
+```typescript
+// Bad — store/index.ts was a barrel of sdk/appState/utils
+import {useGetMeQuery} from "@/store";
+
+// Good
+import {useGetMeQuery} from "@/store/sdk";
+import store, {useAppDispatch} from "@/store/index";
+```
+
+## Enforcement
+
+No generation step is required — internal barrel `index` files are banned outright, so there is never a list of barrels to keep in sync.
+
+- **Biome `noBarrelFile` override** (root `biome.jsonc`): bans internal barrel `index.ts` / `index.tsx` files during lint. Package public entries (`src/index.ts[x]`) and Expo Router routes (`app/**`) are exempt.
+- **Biome plugin**: `biome/plugins/no-barrel-imports.grit` — a small static GritQL plugin that flags path-alias directory imports (`@/store`, `@components`, …) in the packages that define those aliases (`example-frontend`, `admin-spa`, `demo`).
+- **CI**: `bun run check:no-barrel-imports` — resolution-based safety net that fails if any internal barrel index file exists or any import resolves through one (see root `package.json` → `terreno.policies.noBarrelImports`).
+- **AI rules**: `.rulesync/rules/00-root.md` and package `.ai/guidelines/core.md` files
+
+When scaffolding new code (MCP bootstrap, examples), always generate direct module paths — never `models/index`, `@/store`, or `@components` without a concrete file.

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

@@ -1,29 +0,0 @@
-# Terreno Documentation
-
-Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
-
-## Structure
-
-- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
-- **[How-to guides](how-to/)** — Problem-oriented, practical steps
-- **[Reference](reference/)** — Technical reference for APIs and packages
-- **[Explanation](explanation/)** — Concepts and context
-- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
-
-## Packages
-
-| Package | Description |
-|---------|-------------|
-| [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
-| [@terreno/ui](reference/ui.md) | React Native UI component library |
-| [@terreno/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/dist/docs/versioned/0.20.0/explanation/ai-workflows.md

@@ -1,270 +0,0 @@
-# AI-Powered Workflows
-
-Understanding Terreno's autonomous AI workflows for continuous improvement.
-
-## Overview
-
-Terreno uses GitHub Actions with AI agents to maintain code quality, documentation, and developer experience. These workflows run automatically and create pull requests when improvements are needed.
-
-## Workflow Categories
-
-### Documentation Workflows
-
-#### Update Docs
-**Trigger:** Push to master  
-**Purpose:** Keeps documentation synchronized with code changes
-
-Analyzes code diffs after each merge to identify:
-- New or changed APIs, functions, classes
-- Missing or outdated documentation
-- Documentation gaps that need attention
-
-**Output:** Draft pull requests with documentation updates following the Diátaxis framework (tutorials, how-to guides, reference, explanation).
-
-**Philosophy:** Treats documentation gaps like failing tests — they must be fixed.
-
-#### Update Rules
-**Trigger:** Push to master  
-**Purpose:** Keeps AI assistant rules synchronized with codebase changes
-
-Maintains the single source of truth in `.rulesync/rules/` and ensures:
-- `.cursorrules` (Cursor IDE)
-- `.windsurfrules` (Windsurf IDE)
-- `AGENTS.md` (Claude Code, Copilot)
-- `.github/copilot-instructions.md` (GitHub Copilot)
-
-**Workflow:**
-1. Detects package changes, new APIs, or convention updates
-2. Updates source files in `.rulesync/rules/`
-3. Creates PR with instructions to run `bun run rules` to regenerate outputs
-4. Ensures `rulesync-check` CI passes
-
-**Key insight:** Rule files are code — they must be kept in sync with implementation.
-
-### Code Quality Workflows
-
-#### Daily JSDoc Improver
-**Trigger:** Daily schedule + push to master  
-**Purpose:** Systematically improves JSDoc documentation across the codebase
-
-**Two modes:**
-- **Targeted (on push):** Improves JSDoc for files changed in recent commits
-- **Systematic (daily):** Three-phase approach covering entire codebase
-
-**Output:** Draft PRs with improved JSDoc comments on exported functions, methods, and classes.
-
-#### Daily Test Improver
-**Trigger:** Daily schedule  
-**Purpose:** Enhances test coverage and test quality
-
-Analyzes test files and implementation to:
-- Add missing test cases
-- Improve test clarity and coverage
-- Identify edge cases that need testing
-- Ensure tests follow best practices
-
-**Output:** Draft PRs with test improvements.
-
-### Maintenance Workflows
-
-#### Agentic Maintenance
-**Trigger:** Daily at 00:37 UTC  
-**Purpose:** Cleans up expired issues, discussions, and pull requests
-
-Automatically closes expired entities based on the `expires` field in safe-outputs configuration. Schedule is determined by the shortest expiration time across all workflows.
-
-**Prevents:** Stale issues and PRs from accumulating.
-
-#### RulesSync Check
-**Trigger:** Pull request  
-**Purpose:** Validates that generated rule files are synchronized with sources
-
-**Validation steps:**
-1. Runs `bun run rules` to regenerate outputs
-2. Checks for uncommitted changes
-3. Fails if generated files don't match committed versions
-
-**Prevents:** Merging PRs with out-of-sync rule files.
-
-## CI/CD Workflows
-
-### Package Testing
-
-Each package has its own CI workflow that runs on pull requests and pushes:
-
-| Workflow | Package | Tests |
-|----------|---------|-------|
-| `api-ci.yml` | @terreno/api | Unit tests, type checking, linting |
-| `ui-ci.yml` | @terreno/ui | Component tests, type checking, linting |
-| `rtk-ci.yml` | @terreno/rtk | Unit tests, type checking, linting |
-| `mcp-server-ci.yml` | @terreno/mcp-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

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

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

package/dist/docs/versioned/0.20.0/implementationPlans/README.md

@@ -1,40 +0,0 @@
-# Implementation Plans
-
-Forward-looking implementation plans for significant features and architectural changes to Terreno packages.
-
-## Purpose
-
-This directory contains detailed technical plans for major features **before implementation**. Each plan documents:
-
-- Design goals and rationale
-- Architecture and file structure
-- Configuration interfaces
-- Usage examples
-- Breaking changes and migration paths
-- Implementation tasks and phases
-
-## Current Plans
-
-- **[Modular API (TerrenoApp)](ModularAPI.md)** — New fluent builder API to replace `setupServer` in `@terreno/api`
-- **[Offline Mode](offline-mode.md)** — Placeholder plan for offline queueing, replay, conflict handling, and UI surfaces
-- **[MCP Boost Parity](mcp-boost-parity.md)** — Docs search tools, local stdio MCP with runtime introspection, browser log capture, per-package guidelines, and upgrade prompts (inspired by laravel/boost)
-- **[Docs Site & Versioning](docs-site-and-versioning.md)** — Docusaurus site, versioned docs per release, UI demo embeds, and docs-maintenance skills
-
-## Status Tracking
-
-| Plan | Status | Target Version | Discussion |
-|------|--------|----------------|------------|
-| Modular API | 📝 Planning | 2.0.0 | [#149](https://github.com/FlourishHealth/terreno/pull/149) |
-| Offline Mode | Placeholder | TBD | TBD |
-| MCP Boost Parity | 📝 Planning | TBD | TBD |
-| Docs Site & Versioning | 📝 Planning | TBD | TBD |
-
-## Process
-
-1. **Planning**: Implementation plan merged to master
-2. **Discussion**: Community feedback in linked PR/issue
-3. **Implementation**: Feature developed in feature branch with tests
-4. **Documentation**: How-to guides and migration docs updated
-5. **Release**: Plan moves to `docs/explanation/` as architectural documentation
-
-Plans that are fully implemented should be moved to `docs/explanation/` and updated to reflect the actual implementation.