@terreno/mcp 57.18.0 → 57.20.0

package/README.md

@@ -1,295 +1,58 @@
 # @terreno/mcp
 
-MCP server for Terreno - provides documentation, tools, and prompts for building full-stack apps.
-
-## Features
-
-### Resources
-
-Documentation resources accessible via MCP:
-
-- `terreno://docs/overview` - Overview of the Terreno monorepo
-- `terreno://docs/api` - @terreno/api documentation
-- `terreno://docs/ui` - @terreno/ui documentation
-- `terreno://docs/rtk` - @terreno/rtk documentation
-- `terreno://docs/patterns` - Common patterns and best practices
-
-### Tools
-
-Code generation tools:
-
-- `terreno_search_docs` - Search bundled Terreno documentation (call before guessing APIs). Optional `version` selects a retained docs snapshot; omit for current `next` docs.
-- `terreno_get_component_docs` - Full `@terreno/ui` props table for one component
-- `terreno_get_upgrade_guide` - Lockstep upgrade notes between two `@terreno/*` versions
-- `terreno_search_update_notes` - Search bundled upgrade markdown and optional backend announcement help API
-- `terreno_get_update_note` - Fetch one full update note by id (`upgrade:<semver>` or `announcement:<mongoId>`)
-- `terreno_ask_update_help` - Ask a natural-language question; returns ranked matches with full update bodies
-- `terreno_bootstrap_ai_rules` - Scaffold AI assistant rules files for Cursor, Claude Code, etc.
-- `terreno_generate_model` - Generate a Mongoose model with proper Terreno conventions
-- `terreno_generate_route` - Generate a modelRouter route configuration
-- `terreno_generate_screen` - Generate a React Native screen component
-- `terreno_generate_form_fields` - Generate form field components
-- `terreno_validate_model_schema` - Validate a Mongoose schema follows conventions
-- `terreno_install_admin` - Generate admin panel integration files and instructions
-
-Local runtime tools (`terreno-mcp-local`):
-
-- `get_syncdb_state` - Inspect live SyncDB entities, outbox, conflicts, cursors,
-  streams, repair markers, status, and debugger events
-- `syncdb_snapshot` - Capture, list, read, compare, and delete SyncDB snapshots
-- `syncdb_action` - Mutate/edit local state, flush, reconcile/resync,
-  resolve/retry, toggle offline mode, clear events, and merge snapshots
-
-Create the SyncDB client with `debug: true`. State changes require
-`TERRENO_MCP_EVAL=1`; reads and snapshots do not.
-
-### Prompts
-
-Code generation prompts:
-
-- `terreno_bootstrap` - Prompt workflow for scaffolding a new Terreno application
-- `terreno_create_crud_feature` - Generate complete CRUD feature (model, routes, screens)
-- `terreno_create_api_endpoint` - Generate custom API endpoint with OpenAPI docs
-- `terreno_create_ui_component` - Generate reusable UI component
-- `terreno_create_form_screen` - Generate form screen with validation
-- `terreno_add_authentication` - Generate authentication setup
-- `terreno_migrate_to_terreno_app` - Migrate from setupServer to TerrenoApp pattern
-- `terreno_style_guide` - Get the Terreno code style guide
-- `terreno_upgrade` - Lockstep Terreno upgrade workflow
+MCP servers that give coding agents Terreno docs, code generators, and live app diagnostics — part of
+Terreno, the batteries-included TypeScript framework for universal apps.
 
 ## Install
 
-```bash
-# From the monorepo root
-bun install
-bun run mcp:build
-```
-
-## Usage
-
-### With Claude Desktop
-
-Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "terreno": {
-      "command": "bun",
-      "args": ["/path/to/terreno/mcp-server/dist/index.js"]
-    }
-  }
-}
-```
-
-### With Claude Code CLI
-
-Add to your project's `.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "terreno": {
-      "command": "bun",
-      "args": ["./mcp-server/dist/index.js"]
-    }
-  }
-}
-```
-
-### Update help (optional)
-
-When `TERRENO_HELP_API_URL` points at a Terreno backend with `AnnouncementsApp({help: {enabled: true}})`, the update-note tools also search live product announcements (published by default; pass `includeArchived: true` for archived notes). Set `TERRENO_HELP_API_TOKEN` when the help routes require authentication.
-
-## Development
-
-```bash
-# Build
-bun run build
-
-# Watch mode
-bun run dev
-
-# Start server
-bun run start
-
-# Run tests
-bun run test
-
-# Lint
-bun run lint
-```
-
-## Docker
-
-Build and run the MCP server in Docker:
+The hosted server needs no install: point your editor at `https://mcp.terreno.app/mcp` (MCP
+Streamable HTTP). Install the package in your app for the local stdio server:
 
 ```bash
-# Build the image
-docker build -t terreno-mcp-server ./mcp-server
-
-# Run the container
-docker run --rm terreno-mcp-server
-```
-
-## CI/CD
-
-The MCP server includes GitHub Actions workflows:
-
-### CI Workflow (`.github/workflows/mcp-server-ci.yml`)
-- Runs on every push/PR to `mcp-server/**`
-- Lints, builds, and tests the code
-- Builds Docker image to verify it works
-
-### Deploy Workflow (`.github/workflows/mcp-server-deploy.yml`)
-- Runs on push to `master`/`main` branch
-- Deploys to Google Cloud Run
-
-### Required GitHub Secrets for Deployment
-
-Configure these secrets in your GitHub repository:
-
-| Secret | Description |
-|--------|-------------|
-| `GCP_PROJECT_ID` | Your Google Cloud project ID |
-| `GCP_WORKLOAD_IDENTITY_PROVIDER` | Workload Identity Federation provider |
-| `GCP_SERVICE_ACCOUNT` | Service account email for deployment |
-| `GCP_ARTIFACT_REGISTRY` | Artifact Registry repository name |
-
-### Setting up GCP for Deployment
-
-1. Create an Artifact Registry repository:
-   ```bash
-   gcloud artifacts repositories create terreno \
-     --repository-format=docker \
-     --location=us-central1
-   ```
-
-2. Set up Workload Identity Federation for GitHub Actions:
-   ```bash
-   # Create workload identity pool
-   gcloud iam workload-identity-pools create "github" \
-     --location="global" \
-     --display-name="GitHub Actions"
-
-   # Create provider
-   gcloud iam workload-identity-pools providers create-oidc "github" \
-     --location="global" \
-     --workload-identity-pool="github" \
-     --display-name="GitHub" \
-     --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository" \
-     --issuer-uri="https://token.actions.githubusercontent.com"
-   ```
-
-3. Grant permissions to the service account:
-   ```bash
-   # Cloud Run deployment
-   gcloud projects add-iam-policy-binding PROJECT_ID \
-     --member="serviceAccount:SA_EMAIL" \
-     --role="roles/run.admin"
-
-   # Artifact Registry push
-   gcloud artifacts repositories add-iam-policy-binding terreno \
-     --location=us-central1 \
-     --member="serviceAccount:SA_EMAIL" \
-     --role="roles/artifactregistry.writer"
-   ```
-
-## How Tools Work
-
-**Important**: MCP tools return generated code as text content. They do not create files directly. When using these tools with an AI assistant (like Claude in Cursor), the assistant should:
-
-1. Call the appropriate tool to generate code
-2. Take the returned code text and write it to the appropriate file in your project
-3. Follow up with any necessary steps (registering routes, regenerating SDK, etc.)
-
-This design allows the AI assistant to:
-- Review and adapt the generated code to your project structure
-- Make any necessary modifications before writing
-- Handle file paths based on your project's conventions
-
-## Example Tool Usage
-
-### Generate a Model
-
-```json
-{
-  "name": "terreno_generate_model",
-  "arguments": {
-    "name": "Product",
-    "fields": [
-      { "name": "title", "type": "String", "required": true },
-      { "name": "price", "type": "Number", "required": true },
-      { "name": "active", "type": "Boolean", "default": "true" }
-    ],
-    "hasOwner": true,
-    "softDelete": true
-  }
-}
+bun add -d @terreno/mcp
 ```
 
-The tool returns TypeScript code that should be written to `backend/src/models/product.ts` (or your project's model directory).
+The local server needs Bun 1.4 or newer for its `browser` tool.
 
-### Generate a Route
+## Quick start
 
-```json
-{
-  "name": "terreno_generate_route",
-  "arguments": {
-    "modelName": "Product",
-    "routePath": "/products",
-    "permissions": {
-      "create": "authenticated",
-      "list": "any",
-      "read": "any",
-      "update": "owner",
-      "delete": "admin"
-    },
-    "queryFields": ["active", "category"],
-    "ownerFiltered": true,
-    "sort": "-created"
-  }
-}
-```
-
-The tool returns route configuration code that should be written to `backend/src/api/product.ts`, then exported from `backend/src/api/index.ts` and registered in your server setup.
-
-### Generate a Screen
+Add both servers to `.cursor/mcp.json` (or `.mcp.json` for Claude Code) at the app repository root:
 
 ```json
 {
-  "name": "terreno_generate_screen",
-  "arguments": {
-    "name": "ProductList",
-    "type": "list",
-    "modelName": "Product",
-    "fields": ["title", "price"]
+  "mcpServers": {
+    "terreno": {"type": "http", "url": "https://mcp.terreno.app/mcp"},
+    "terreno-local": {"command": "bunx", "args": ["terreno-mcp-local"]}
   }
 }
 ```
 
-The tool returns React Native screen code that should be written to `frontend/src/screens/ProductListScreen.tsx` (or your project's screen directory).
-
-## Example Prompt Usage
-
-### Create CRUD Feature
+Restart the editor, then ask the agent to call `terreno_search_docs` or `application_info`.
 
-```
-Prompt: terreno_create_crud_feature
-Arguments:
-  - name: "Product"
-  - fields: "title:string,price:number,description:string,active:boolean"
-  - hasOwner: "yes"
-```
+## What's included
 
-This will generate a comprehensive prompt with instructions for creating:
-- Backend model with proper schema
-- API routes with permissions
-- Frontend list, detail, and form screens
+- Hosted `terreno-mcp` tools (14): `terreno_bootstrap_ai_rules`, `terreno_search_docs`,
+  `terreno_get_component_docs`, `terreno_get_upgrade_guide`, `terreno_search_update_notes`,
+  `terreno_get_update_note`, `terreno_ask_update_help`, `terreno_generate_model`,
+  `terreno_generate_route`, `terreno_generate_screen`, `terreno_generate_form_fields`,
+  `terreno_validate_model_schema`, `terreno_validate_ui_blocks`, `terreno_install_admin`
+- Local `terreno-mcp-local` tools (13): `application_info`, `database_schema`, `database_query`,
+  `read_logs`, `last_error`, `get_client_state`, `get_rtk_state` (deprecated alias of
+  `get_client_state`), `get_syncdb_state`, `syncdb_snapshot`, `syncdb_action`, `evaluate`,
+  `navigate`, `browser`
+- Nine workflow prompts (`terreno_bootstrap`, `terreno_create_crud_feature`, `terreno_upgrade`, and
+  more) and `terreno://docs/*` documentation resources on the hosted server
+- Code generators return text with a target path; the agent writes the files
+- Rate limiting: the hosted server allows 120 requests per 60 seconds per client IP by default and
+  answers `429` with `Retry-After` beyond that
+- `TERRENO_MCP_EVAL` gate: `evaluate`, `navigate`, `syncdb_action`, and the `browser` `evaluate`
+  action run only when the local server's environment sets `TERRENO_MCP_EVAL=1` (or `true`)
 
 ## Documentation
 
-Full API reference: [docs/reference/mcp-server.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/mcp-server.md)
+- Reference (every tool, parameter, and environment variable): [docs/reference/mcp-server.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/mcp-server.md)
+- How-to: [Set up Terreno MCP](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/set-up-terreno-mcp.md)
+- How-to: [Debug a Terreno app with MCP](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/debug-with-mcp.md)
 
 ## License and Contributing
 

package/dist/bootstrap.d.ts

@@ -9,6 +9,18 @@ export interface BootstrapAiRulesArgs extends BootstrapArgs {
     /** Optional `@terreno/*` package ids to include (e.g. `["api","ui"]`). Omits others from merged guidelines. */
     packages?: string[];
 }
+/**
+ * rulesync targets the generated config and root rule share. Every entry must be a target
+ * rulesync 9 accepts (it dropped `windsurf`; Windsurf reads the `agentsmd` output).
+ */
+export declare const RULESYNC_TARGETS: readonly ["cursor", "claudecode", "copilot", "agentsmd"];
+/**
+ * Warning shown before every `rulesync generate`: with `delete: true` rulesync overwrites the
+ * root files and deletes anything else in the rule directories it owns.
+ */
+export declare const RULESYNC_OVERWRITE_WARNING = "`rulesync generate` overwrites the root `CLAUDE.md`, `AGENTS.md`, and `.github/copilot-instructions.md` and deletes every file under `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, and `.agents/memories/` that it did not generate. Move any edits you made to those root files, and any hand-written files in those directories, into `.rulesync/rules/10-project.md` (or other `.rulesync/rules/*.md` sources) first, or they are lost.";
+/** Command that regenerates editor files; pinned to the rulesync major the output is tested on. */
+export declare const RULESYNC_GENERATE_COMMAND = "bunx rulesync@9 generate";
 interface AiRulesFile {
     path: string;
     content: string;

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,8BAA8B,CAAC;AAUvD,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,cAAc,EAAE,IAAI,EA+BhC,CAAC;AAEF,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAgVD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,oBAAoB,GAAI,MAAM,oBAAoB,KAAG,WAAW,EA6B5E,CAAC;AAiFF,eAAO,MAAM,uBAAuB,GAClC,MAAM,MAAM,EACZ,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B;IAAC,OAAO,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAQ/C,CAAC;AAGF,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,eAAO,MAAM,gBAAgB,EAAE,eAAe,EAkB7C,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,MAAM,MAAM,EACZ,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3B;IAAC,QAAQ,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC,CAAA;CA8DzE,CAAC"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,8BAA8B,CAAC;AAUvD,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,cAAc,EAAE,IAAI,EA+BhC,CAAC;AAEF,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AACD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,0DAA2D,CAAC;AAEzF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,8bACsZ,CAAC;AAE9b,mGAAmG;AACnG,eAAO,MAAM,yBAAyB,6BAA6B,CAAC;AAkRpE,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,oBAAoB,GAAI,MAAM,oBAAoB,KAAG,WAAW,EAyB5E,CAAC;AAsFF,eAAO,MAAM,uBAAuB,GAClC,MAAM,MAAM,EACZ,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B;IAAC,OAAO,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAQ/C,CAAC;AAGF,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,eAAO,MAAM,gBAAgB,EAAE,eAAe,EAkB7C,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,MAAM,MAAM,EACZ,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC3B;IAAC,QAAQ,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC,CAAA;CA8DzE,CAAC"}

package/dist/bootstrap.js

@@ -1,7 +1,7 @@
 import { composePackageGuidelinesForRules, filterGuidelineIdsForRootRules, loadPackageGuidelineMarkdown, resolveBootstrapGuidelinePackages, } from "./packageGuidelines.js";
 export const bootstrapTools = [
     {
-        description: "Bootstrap AI coding assistant rules for a Terreno project. Creates configuration files for Cursor, Windsurf, Claude Code, and GitHub Copilot with Terreno-specific guidelines adapted for the project.",
+        description: "Bootstrap AI coding assistant rules for a Terreno project. Creates rulesync sources that generate rules for Cursor, Claude Code, GitHub Copilot, and AGENTS.md readers (Codex, Windsurf, and others) with Terreno-specific guidelines adapted for the project.",
         inputSchema: {
             properties: {
                 appDisplayName: {
@@ -28,13 +28,25 @@ export const bootstrapTools = [
         name: "terreno_bootstrap_ai_rules",
     },
 ];
+/**
+ * rulesync targets the generated config and root rule share. Every entry must be a target
+ * rulesync 9 accepts (it dropped `windsurf`; Windsurf reads the `agentsmd` output).
+ */
+export const RULESYNC_TARGETS = ["cursor", "claudecode", "copilot", "agentsmd"];
+/**
+ * Warning shown before every `rulesync generate`: with `delete: true` rulesync overwrites the
+ * root files and deletes anything else in the rule directories it owns.
+ */
+export const RULESYNC_OVERWRITE_WARNING = "`rulesync generate` overwrites the root `CLAUDE.md`, `AGENTS.md`, and `.github/copilot-instructions.md` and deletes every file under `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, and `.agents/memories/` that it did not generate. Move any edits you made to those root files, and any hand-written files in those directories, into `.rulesync/rules/10-project.md` (or other `.rulesync/rules/*.md` sources) first, or they are lost.";
+/** Command that regenerates editor files; pinned to the rulesync major the output is tested on. */
+export const RULESYNC_GENERATE_COMMAND = "bunx rulesync@9 generate";
+const RULESYNC_TARGETS_FRONTMATTER = `[${RULESYNC_TARGETS.map((t) => `"${t}"`).join(", ")}]`;
 const generateRulesyncConfig = () => {
     return JSON.stringify({
         $schema: "https://raw.githubusercontent.com/dyoshikawa/rulesync/refs/heads/main/config-schema.json",
-        baseDirs: ["."],
         delete: true,
         features: ["rules"],
-        targets: ["cursor", "windsurf", "claudecode", "copilot"],
+        targets: [...RULESYNC_TARGETS],
         verbose: false,
     }, null, 2);
 };
@@ -73,14 +85,49 @@ ${appDescription}
 Uses [Bun](https://bun.sh/) as the package manager.
 
 \`\`\`bash
+# Install dependencies
+cd backend && bun install
+cd frontend && bun install
+
 # Backend
 cd backend && bun run dev    # Start backend on port 4000
 
 # Frontend
-cd frontend && bun run web   # Start web frontend
+cd frontend && bun run web   # Start web frontend on port 8082
 cd frontend && bun run sdk   # Regenerate SDK after backend changes
 \`\`\`
 
+## Adding Features
+
+1. Create model in \`backend/src/models/\`
+2. Create route in \`backend/src/api/\`
+3. Register route in \`backend/src/server.ts\`
+4. Regenerate SDK: \`cd frontend && bun run sdk\`
+5. Create screens in \`frontend/app/\`
+
+## Backend Conventions
+
+- Use \`modelRouter\` for CRUD endpoints
+- Use \`APIError\` for error responses
+- Use \`logger.info/warn/error/debug\` for logging
+- Use \`Model.findExactlyOne\` or \`Model.findOneOrNone\` (not \`Model.findOne\`)
+
+## Frontend Conventions
+
+- Use \`@terreno/syncdb/react\` hooks (\`useQuery\`, \`useMutate\`) for synced collection CRUD
+- Use generated SDK hooks from \`@/store/openApiSdk\` for non-synced routes only
+- Use @terreno/ui components (Box, Page, Button, TextField, etc.)
+- Never modify \`openApiSdk.ts\` manually - regenerate with \`bun run sdk\`
+- Use Redux Toolkit for state management (Better Auth session and the RTK Query SDK)
+
+## AI Assistance
+
+This project is configured to use the Terreno MCP server for AI-assisted development.
+Use the MCP tools and prompts for:
+- Generating new models and routes
+- Creating screens and forms
+- Following Terreno patterns and best practices
+
 ## Code Style
 
 ### TypeScript/JavaScript
@@ -124,23 +171,11 @@ const generateRootRulesFile = (args, packageIds) => {
     const body = buildSharedRootRulesMarkdownBody(args, filterGuidelineIdsForRootRules(packageIds));
     return `---
 root: true
-targets: ["cursor", "windsurf", "copilot"]
+targets: ${RULESYNC_TARGETS_FRONTMATTER}
 description: "${appDisplayName} root guidelines"
 globs: ["**/*"]
 ---
 
-${body}`;
-};
-const generateClaudeCodeRootRulesFile = (args, packageIds) => {
-    const { appDisplayName } = args;
-    const body = buildSharedRootRulesMarkdownBody(args, filterGuidelineIdsForRootRules(packageIds));
-    return `---
-localRoot: true
-targets: ["claudecode"]
-description: "${appDisplayName} Claude Code guidelines"
-globs: ["**/*"]
----
-
 ${body}`;
 };
 const appendAdminBackendGuidelines = (packageIds) => {
@@ -161,8 +196,6 @@ const generateBackendRulesFile = (args, packageIds) => {
     const { appDisplayName } = args;
     const admin = appendAdminBackendGuidelines(packageIds);
     return `---
-root: true
-targets: ["cursor", "windsurf", "copilot"]
 description: "${appDisplayName} backend guidelines"
 globs: ["**/*"]
 ---
@@ -202,51 +235,10 @@ Use \`AppConfig.updateConfig(updates)\` to write. All values are persisted in Mo
 6. Optionally add to \`AdminApp\` in \`src/server.ts\` for admin panel access
 `;
 };
-const _generateBackendClaudeRulesFile = (args) => {
-    const { appDisplayName } = args;
-    return `---
-localRoot: true
-targets: ["claudecode"]
-description: "${appDisplayName} backend Claude Code guidelines"
-globs: ["**/*"]
----
-
-# ${appDisplayName} Backend
-
-Express/Mongoose backend using @terreno/api.
-
-## Development
-
-\`\`\`bash
-bun run dev      # Start on port 4000
-bun run test     # Run tests
-bun run lint     # Lint code
-\`\`\`
-
-## Backend Conventions
-
-- Use \`modelRouter\` for CRUD endpoints
-- Use \`APIError\` for error responses: \`throw new APIError({status: 400, title: "Message"})\`
-- Use \`logger.info/warn/error/debug\` for logging
-- Use \`Model.findExactlyOne\` or \`Model.findOneOrNone\` (not \`Model.findOne\`)
-- All model types live in \`src/types/models/\`
-- In routes: \`req.user\` is \`UserDocument | undefined\`
-
-## Adding a New Model
-
-1. Create model in \`src/models/yourModel.ts\`
-2. Create types in \`src/types/models/yourModelTypes.ts\`
-3. Export from \`src/models/index.ts\` and \`src/types/models/index.ts\`
-4. Create route in \`src/api/yourModel.ts\`
-5. Register route in \`src/server.ts\`
-`;
-};
 const generateFrontendRulesFile = (args, packageIds) => {
     const { appDisplayName } = args;
     const admin = appendAdminFrontendGuidelines(packageIds);
     return `---
-root: true
-targets: ["cursor", "windsurf", "copilot"]
 description: "${appDisplayName} frontend guidelines"
 globs: ["**/*"]
 ---
@@ -285,44 +277,6 @@ ${admin}## Expo SDK upgrades
 
 ## Adding a New Screen
 
-1. Regenerate SDK if backend changed: \`bun run sdk\`
-2. Create screen in \`app/\` directory
-3. Use @terreno/ui components for layout
-4. Use SDK hooks for non-synced routes; use syncdb hooks for synced collections
-`;
-};
-const _generateFrontendClaudeRulesFile = (args) => {
-    const { appDisplayName } = args;
-    return `---
-localRoot: true
-targets: ["claudecode"]
-description: "${appDisplayName} frontend Claude Code guidelines"
-globs: ["**/*"]
----
-
-# ${appDisplayName} Frontend
-
-Expo/React Native frontend using @terreno/ui, @terreno/syncdb, and @terreno/rtk.
-
-## Development
-
-\`\`\`bash
-bun run web      # Start web frontend on port 8082
-bun run sdk      # Regenerate SDK from backend OpenAPI spec
-bun run lint     # Lint code
-\`\`\`
-
-## Frontend Conventions
-
-- Use \`@terreno/syncdb/react\` hooks for synced collection CRUD
-- Use generated SDK hooks from \`@/store/openApiSdk\` for non-synced routes only
-- Use @terreno/ui components (Box, Page, Button, TextField, etc.)
-- Never modify \`openApiSdk.ts\` manually - regenerate with \`bun run sdk\`
-- Use Luxon for date operations
-- Better Auth session: \`generateBetterAuthSlice\` + \`lib/betterAuth.ts\`
-
-## Adding a New Screen
-
 1. Regenerate SDK if backend changed: \`bun run sdk\`
 2. Create screen in \`app/\` directory
 3. Use @terreno/ui components for layout
@@ -338,12 +292,8 @@ export const generateAiRulesFiles = (args) => {
     const backendContent = stripFrontmatter(generateBackendRulesFile(args, packageIds));
     const frontendContent = stripFrontmatter(generateFrontendRulesFile(args, packageIds));
     return [
-        // .rulesync/rules/ source files (these are the source of truth for root)
+        // .rulesync/rules/ source file (the source of truth for root rules in every editor)
         { content: generateRootRulesFile(args, packageIds), path: ".rulesync/rules/00-root.md" },
-        {
-            content: generateClaudeCodeRootRulesFile(args, packageIds),
-            path: ".rulesync/rules/01-claudecode-root.md",
-        },
         // Direct output files for backend (AGENTS.md and CLAUDE.md in backend/)
         { content: backendContent, path: "backend/AGENTS.md" },
         { content: backendContent, path: "backend/CLAUDE.md" },
@@ -380,30 +330,35 @@ ${fileList}
 
 1. **Create all the files listed above.** Each file's content is provided below.
 
-2. **Install rulesync** (required for syncing root-level rules to all AI tools):
-   \`\`\`bash
-   npm install -g rulesync
-   \`\`\`
+2. **If \`.rulesync/rules/01-claudecode-root.md\` exists from an earlier bootstrap, delete it.** The root rule now covers Claude Code.
+
+3. **Before generating, move hand-written rules into \`.rulesync/rules/\`.** ${RULESYNC_OVERWRITE_WARNING}
 
-3. **Run rulesync to generate root-level AI tool configs:**
+4. **Delete the stale \`.cursorrules\`** that \`create-terreno-app\` wrote. \`.cursor/rules/00-root.mdc\` supersedes it, and the root rule contains everything it said.
+
+5. **Generate the editor files with rulesync:**
    \`\`\`bash
-   rulesync sync
+   ${RULESYNC_GENERATE_COMMAND}
    \`\`\`
-   
+
    This generates root-level files from \`.rulesync/rules/\`:
-   - \`.cursorrules\`, \`.windsurfrules\`, \`.github/copilot-instructions.md\`, \`.claude/CLAUDE.local.md\`, \`AGENTS.md\`
+   - \`.cursor/rules/00-root.mdc\` (Cursor)
+   - \`CLAUDE.md\` (Claude Code; replaces the one \`create-terreno-app\` wrote)
+   - \`.github/copilot-instructions.md\` (GitHub Copilot)
+   - \`AGENTS.md\` (Codex, Windsurf, and other AGENTS.md readers)
 
 ## How It Works
 
-- **\`.rulesync/rules/\`** - Source of truth for root-level AI coding guidelines
-- **\`rulesync.jsonc\`** - Configuration for rulesync tool (root only)
+- **\`.rulesync/rules/00-root.md\`** - Source of truth for root-level AI coding guidelines (Terreno-owned; regenerated on re-bootstrap)
+- **\`rulesync.jsonc\`** - rulesync config: \`rules\` feature, targets ${RULESYNC_TARGETS.map((t) => `\`${t}\``).join(", ")}, \`delete: true\`
 - **\`backend/AGENTS.md\` & \`backend/CLAUDE.md\`** - Direct context files for backend
 - **\`frontend/AGENTS.md\` & \`frontend/CLAUDE.md\`** - Direct context files for frontend
 
 ## Keeping Rules Updated
 
-- **Root rules**: Edit \`.rulesync/rules/\` and run \`rulesync sync\`
-- **Backend/Frontend rules**: Edit \`backend/AGENTS.md\` or \`frontend/AGENTS.md\` directly (and copy to CLAUDE.md)
+- **Project rules**: Add your own sources such as \`.rulesync/rules/10-project.md\` (scope with \`globs\`, e.g. \`["backend/**"]\`) and run \`${RULESYNC_GENERATE_COMMAND}\`. Re-bootstrapping never overwrites them.
+- **Terreno rules**: Re-run \`terreno_bootstrap_ai_rules\` to refresh \`00-root.md\` and the \`backend/\`/\`frontend/\` files, then run \`${RULESYNC_GENERATE_COMMAND}\`
+- Never hand-edit the root-level generated files (\`CLAUDE.md\`, \`AGENTS.md\`, \`.cursor/rules/\`, \`.github/copilot-instructions.md\`); rulesync replaces them
 
 ---
 
@@ -488,16 +443,16 @@ The application should include:
 - Cursor rules for AI assistance
 - MCP integration for development assistance
 
-**IMPORTANT: After the CLI writes the app, also run the \`terreno_bootstrap_ai_rules\` tool** with the same appName and appDisplayName to set up AI coding assistant rules for Cursor, Windsurf, Claude Code, and GitHub Copilot. This will create:
-- AGENTS.md files for each directory
-- .cursorrules and .windsurfrules files
-- GitHub Copilot instructions
-- Claude Code local rules
+**IMPORTANT: After the CLI writes the app, also run the \`terreno_bootstrap_ai_rules\` tool** with the same appName and appDisplayName to set up AI coding assistant rules for Cursor, Claude Code, GitHub Copilot, and AGENTS.md readers. This will create:
+- \`.rulesync/rules/00-root.md\`, the root rule source for every editor
+- AGENTS.md and CLAUDE.md files for \`backend/\` and \`frontend/\`
 - rulesync.jsonc for keeping rules in sync
 
-Then install rulesync to keep AI rules synchronized:
+Before generating, delete the stale root \`.cursorrules\` (\`.cursor/rules/00-root.mdc\` supersedes it). ${RULESYNC_OVERWRITE_WARNING}
+
+Then generate the editor files from the rulesync sources:
 \`\`\`bash
-npm install -g rulesync
+${RULESYNC_GENERATE_COMMAND}
 \`\`\``;
     return {
         messages: [