@terreno/mcp 0.25.0 → 0.26.0

package/src/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/src/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

package/src/docs/versioned/0.25.0/how-to/call-external-apis.md

@@ -0,0 +1,101 @@
+# Call external APIs
+
+How to talk to third-party HTTP APIs (payment processors, health integrations, meeting providers, etc.) from a `@terreno/api` backend using the shared HTTP client utilities, instead of hand-rolling axios setup, token caching, retry, and error handling per integration.
+
+## When to use each piece
+
+| You are... | Use |
+|---|---|
+| Calling a third-party REST API that needs a bearer token, OAuth2 client-credentials, or API-key auth | `createAuthenticatedClient` |
+| Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
+| Logging or classifying a caught error from any external call | `normalizeApiError` |
+| Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
+| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+
+**Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
+
+## Create a client
+
+```typescript
+import {createAuthenticatedClient} from "@terreno/api";
+
+const widgetApi = createAuthenticatedClient({
+  apiName: "widgetService", // used in logs and normalized errors; defaults to baseURL
+  auth: {
+    credentials: {clientId: process.env.WIDGET_CLIENT_ID!, clientSecret: process.env.WIDGET_CLIENT_SECRET!},
+    refreshOn401: true,
+    tokenUrl: "https://api.widgets.example/oauth/token",
+    type: "oauth2",
+  },
+  baseURL: "https://api.widgets.example/v2",
+});
+
+const response = await widgetApi.axios.get("/widgets/123");
+```
+
+Auth strategies:
+
+- `{type: "bearer", getToken}` — you supply an async token fetcher; the client caches the result until `invalidateToken()` is called.
+- `{type: "oauth2", tokenUrl, credentials, refreshOn401}` — the client performs the client-credentials grant itself (HTTP Basic auth, form-encoded). With `refreshOn401: true`, a 401 response invalidates the cached token and retries the request exactly once with a fresh one.
+- `{type: "apiKey", header, getKey}` — the key is sent on the header you name.
+
+Tokens are fetched lazily and concurrent first requests share a single fetch. Create the client once per service at module scope — not per request — so the token cache is actually shared.
+
+## What you get for free
+
+- **Retry with backoff** for transient failures (429 rate limits, 5xx, network errors), honoring `Retry-After`, capped by `maxDelayMs`. Defaults: 3 total attempts, 250ms base delay, 30s delay ceiling — override via the `retry` option.
+- **Idempotency safety**: only GET/HEAD/OPTIONS are retried by default. Retrying a failed POST can duplicate side effects (a payment, a prescription, a meeting). If a specific POST/PUT/DELETE is genuinely safe to repeat, opt it in per request:
+
+  ```typescript
+  import {markRetryUnsafe} from "@terreno/api";
+
+  // Safe to repeat: the upstream endpoint is idempotent on externalId.
+  await widgetApi.axios.post("/widgets", {externalId, name}, markRetryUnsafe());
+  ```
+
+  The request body must be replayable — JSON is fine; streams/FormData are consumed on first send.
+- **Quiet transport logging**: the client logs retries and token refreshes at debug level only and always rejects with the original axios error. Error-level logging belongs to the call site (next section) so composed usage logs each failure exactly once.
+
+## Handle failures at the call site
+
+Wrap calls with `withApiErrorHandling` to normalize, log once, and rethrow:
+
+```typescript
+import {withApiErrorHandling} from "@terreno/api";
+
+export const getWidget = async (id: string): Promise<Widget> => {
+  const response = await withApiErrorHandling(() => widgetApi.axios.get(`/widgets/${id}`), {
+    apiName: "widgetService",
+    operation: "getWidget",
+  });
+  return response.data;
+};
+```
+
+- Default (`rethrowAs: "raw"`): logs the normalized shape (status code, classification, extracted messages) and rethrows the original error for callers that need it.
+- `rethrowAs: "apiError"`: throws a terreno `APIError` (stable title, per-occurrence `detail`) so route handlers surface a clean JSONAPI error instead of a raw axios failure. In this mode the `APIError` constructor does the logging.
+
+For SDK-based integrations where `createAuthenticatedClient` doesn't apply, `withApiErrorHandling` still works — `normalizeApiError` classifies non-axios errors as `"unknown"` while preserving the message.
+
+## Sensitive response data
+
+`normalizeApiError` never logs raw payload bodies: it extracts only recognized message fields (`{message}`, JSONAPI `{errors: [{title, detail}]}`, plain strings truncated to 500 chars). If the upstream service puts sensitive data *inside* those message fields, supply a `redactError` hook (available on both `createAuthenticatedClient` and `withApiErrorHandling`):
+
+```typescript
+redactError: (normalized) => ({
+  ...normalized,
+  messages: normalized.messages.map((message) => message.replace(PATIENT_ID_PATTERN, "[redacted]")),
+}),
+```
+
+Note the hook's output classification also feeds the client's retry decision — redact messages, don't rewrite classifications, unless changing retry behavior is intended.
+
+## When not to use this
+
+- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
+- **Webhook notifiers** — `sendSlackMessage`/`sendGoogleChatMessage`/`sendZoomMessage` already exist; see [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
+
+## Related
+
+- [@terreno/api reference — HTTP Client](../reference/api.md#http-client)

package/src/docs/versioned/0.25.0/implementationPlans/IP_TEMPLATE.md

@@ -0,0 +1,47 @@
+# Implementation plan template
+
+Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with `docs/tasks/<slug>.md`.
+
+**Status:** Draft | Approved | In progress | Complete | Deferred  
+**Branch:**  
+**Owner:**  
+**Created:** YYYY-MM-DD  
+
+## Goal
+
+## Non-Goals
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+
+## Architecture
+
+## Models
+
+## APIs
+
+## Notifications
+
+## UI
+
+(Admin v2: document `home.slots` — `navGlobal`, `contentTop`, `main`, `sidebar` — if applicable.)
+
+## Phases
+
+## Feature Flags & Migrations
+
+## Activity Log & User Updates
+
+## Not Included / Future Work
+
+## Files to Create / Modify
+
+## Task List
+
+Link to `docs/tasks/<slug>.md`.
+
+## Acceptance Criteria
+
+- [ ]

package/src/docs/versioned/0.25.0/implementationPlans/PLAN_INDEX.md

@@ -0,0 +1,21 @@
+# Implementation plan index
+
+Tracks active and completed implementation plans (IP) for Terreno. File paths are relative to `docs/implementationPlans/`.
+
+## Active
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
+
+## Completed
+
+*(Move rows here from Active when the IP status becomes Complete.)*
+
+## Deferred / Closed
+
+*(Plans parked or superseded.)*
+
+## Backlog
+
+*(Links to ideas not yet promoted to a full IP.)*

package/src/docs/versioned/0.25.0/implementationPlans/README.md

@@ -0,0 +1,42 @@
+# 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
+
+- **[Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md)** — Config-driven admin shell (sidebar, home widgets, changelist, forms, bulk + background actions); tasks in [`docs/tasks/admin-ui-v2-django-parity.md`](../tasks/admin-ui-v2-django-parity.md)
+- **[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 |
+|------|--------|----------------|------------|
+| Admin UI v2 (Django parity) | ✅ Approved | TBD | — |
+| 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.