@terreno/mcp 0.24.0 → 0.25.0

package/dist/docs/versioned/0.24.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.24.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.24.0/how-to/add-feature-flags.md

@@ -0,0 +1,115 @@
+# Add Feature Flags
+
+Add feature flags and A/B testing to your Terreno app using `@terreno/feature-flags`.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- `@terreno/admin-backend` registered for the admin panel (optional but recommended)
+
+## Steps
+
+### 1. Install the package
+
+```bash
+bun add @terreno/feature-flags
+```
+
+### 2. Register the backend plugin
+
+In your server file, register `FeatureFlagsApp` and add the admin config:
+
+```typescript
+import {TerrenoApp} from "@terreno/api";
+import {AdminApp} from "@terreno/admin-backend";
+import {FeatureFlagsApp, featureFlagAdminConfig} from "@terreno/feature-flags";
+
+// Define segment functions to classify users for targeting rules
+const segments = {
+  "pro-users": (user) => user.plan === "pro",
+  "beta-testers": (user) => user.betaTester === true,
+  "internal-team": (user) => user.email?.endsWith("@mycompany.com"),
+};
+
+new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp({segments}))
+  .register(
+    new AdminApp({
+      models: [
+        featureFlagAdminConfig,  // adds Feature Flags to the admin panel
+        // ...your other models
+      ],
+    })
+  )
+  .start();
+```
+
+`featureFlagAdminConfig` is a pre-configured admin model config exported by the package. It sets up the display name, list fields, route path, and model reference so you don't need to configure them manually.
+
+### 3. Regenerate the frontend SDK
+
+After adding the backend routes, regenerate the SDK so the frontend can call the new endpoints (with the example backend running, or set `OPENAPI_URL` to your deployed `openapi.json`):
+
+```bash
+cd your-frontend && bun run sdk
+```
+
+Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/rtk` so OpenFeature domain, cache keying, and optional socket refetch stay consistent.
+
+### 4. Use feature flags in the frontend
+
+**Recommended (OpenFeature):** add `@openfeature/react-sdk` to the app, wrap the tree (or the subtree that reads flags) in `<OpenFeatureProvider domain="feature-flags">`, and call `useTerrenoFeatureFlags(terrenoApi, {userId, socket})` once after auth so the OpenFeature client receives `GET /feature-flags/flagConfiguration`. Then use standard hooks such as `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
+
+**Back-compat:** `useFeatureFlags(terrenoApi)` from `@terreno/rtk` still returns `{flags, getFlag, getVariant, isLoading, …}` with the same semantics as before; it uses `/flagConfiguration` under the hood. You do not need to call a generated RTK hook for `/flagConfiguration` directly.
+
+```typescript
+import {useBooleanFlagValue} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags, useSelectCurrentUserId} from "@terreno/rtk";
+import {terrenoApi} from "@/store/sdk";
+
+const GatedBanner: React.FC = () => {
+  const userId = useSelectCurrentUserId();
+  useTerrenoFeatureFlags(terrenoApi, {userId, skip: !userId});
+  const showBanner = useBooleanFlagValue("new-ui", false);
+  return showBanner ? <NewUI /> : null;
+};
+```
+
+```typescript
+import {useFeatureFlags} from "@terreno/rtk";
+import {terrenoApi} from "@/store/sdk";
+
+const LegacyStyle: React.FC = () => {
+  const {getFlag, isLoading} = useFeatureFlags(terrenoApi);
+
+  if (isLoading) {
+    return <Spinner />;
+  }
+
+  const showNewUI = getFlag("new-ui");
+
+  return showNewUI ? <NewUI /> : <OldUI />;
+};
+```
+
+### 4b. Live updates (optional)
+
+To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
+
+On the client, pass the same Socket.io **client** into `useTerrenoFeatureFlags` / `useFeatureFlags` as `socket`; the hook listens for `featureFlagsChanged` (or `socketEventName`) and refetches `/flagConfiguration`. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
+
+### 5. Create flags via the admin panel
+
+Navigate to the admin panel in your app. The "Feature Flags" card appears automatically. Create a flag with:
+
+- **Key**: unique identifier, e.g. `new-ui`
+- **Name**: human-readable label
+- **Type**: `boolean` for on/off toggles, `variant` for A/B tests
+- **Enabled**: global kill switch
+- **Rules**: optional targeting (field-based or segment-based)
+- **Rollout Percentage**: gradual rollout for boolean flags (default 100%)
+
+## Next steps
+
+- See the [reference docs](../reference/feature-flags.md) for the full API, targeting rules, and variant flags
+- See `example-backend/src/server.ts` for a complete working example

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