@terreno/mcp 57.20.0 → 57.22.0

package/dist/docs/versioned/57.20.0/explanation/account-linking.md

@@ -0,0 +1,169 @@
+# Account linking
+
+One person can sign in to a Terreno app in several ways: email and password, Google, GitHub,
+Apple, or a passkey. Account linking decides what happens when a new sign-in method arrives with
+an email that already belongs to an account. Done carelessly, it is an account takeover. This page
+explains the three modes, why Terreno asks for proof of the email before it links anything, and
+how apps that started on JWT auth move their users over.
+
+Setup: [Auth features](../how-to/configure-better-auth.md#auth-features). Reference:
+[`GET {basePath}/terreno/methods`](../reference/api.md#better-auth-authentication).
+
+## Two layers of accounts
+
+A Terreno app with Better Auth has two records per person:
+
+- **The Better Auth user** (`user` collection) owns sign-in. Each sign-in method is an `account`
+  row under it: `credential` for email and password, `google`, `github`, and so on. Better Auth
+  keeps emails unique, so there is at most one Better Auth user per email.
+- **The app `User`** (your Mongoose model) owns everything else: permissions, `admin`,
+  `disabled`, org memberships, and your data. It points at its Better Auth user through
+  `betterAuthId`.
+
+Linking happens at both layers. Better Auth decides whether a new provider `account` joins an
+existing Better Auth user. Terreno decides whether a Better Auth user may claim an existing app
+`User` (`syncBetterAuthUser`).
+
+## The three modes
+
+Set `accountLinking: {mode}` on `BetterAuthConfig`. The mode controls the Better Auth layer.
+
+| Mode | A same-email sign-in with a new method | `POST {basePath}/link-social` |
+| --- | --- | --- |
+| `verified-email` (default) | Joins the account when both emails are verified | Links |
+| `explicit` | Refused with `account_not_linked`; nothing is created | Links, from a signed-in session |
+| `never` | Refused with `account_not_linked`; nothing is created | Refused with 403 `LINKING_DISABLED` |
+
+- **`verified-email`** is the least friction: someone who signed up with email and password and
+  later taps "Continue with Google" on the same address lands in the same account.
+- **`explicit`** makes the user prove they own the existing account first. They sign in the old
+  way, open the Security screen, and link the provider there. A login screen should turn
+  `account_not_linked` into "sign in with your original method, then link this one".
+- **`never`** keeps every sign-in method separate. Because Better Auth keeps emails unique, a
+  second method on the same email cannot sign in at all. Pick it when a shared inbox must not
+  join two people's records.
+
+`/terreno/methods` reports the mode so clients can word their guidance. Unlinking the only
+remaining sign-in method is refused in every mode (400 `FAILED_TO_UNLINK_LAST_ACCOUNT`), so a user
+cannot lock themselves out. rtk's `TerrenoAccountSecurityScreen` checks the same rule before it
+asks, and a social-only user can add a password there (`POST {basePath}/terreno/set-password`) to
+gain a second method before unlinking a provider.
+
+### What the refusals look like
+
+| Path | `account_not_linked` | Unverified email matches an app `User` |
+| --- | --- | --- |
+| OAuth redirect (`/callback/{provider}`) | Redirect with `?error=account_not_linked` | Redirect with `?error=VERIFY_EMAIL_TO_USE_ACCOUNT` |
+| ID-token sign-in (`/sign-in/social` with `idToken`) | 401, `message: "account not linked"` | 409, `code: "VERIFY_EMAIL_TO_USE_ACCOUNT"` |
+| Email sign-up or sign-in | n/a | 409, `code: "VERIFY_EMAIL_TO_USE_ACCOUNT"`, `message: "Verify your email to use this account"` |
+
+## Why both emails must be verified
+
+Linking by email trusts that whoever controls the email controls the account. That trust has to
+hold on both sides:
+
+- **The new method's email.** A provider that reports an unverified email has not checked that
+  the person owns it. Linking on it lets anyone who types your address into that provider into
+  your account. An unverified provider email never links, in any mode. `trustedProviders` turns
+  this check off for the providers it lists, so list only providers that prove email ownership.
+- **The existing account's email.** If the existing account was itself created without proving
+  the email, an attacker can **pre-register**: sign up with the victim's address and a password
+  the attacker knows, wait for the victim to sign in with Google, and share the account.
+  Terreno keeps Better Auth's `requireLocalEmailVerified: true` in every mode, so an unverified
+  local account never absorbs a new method.
+
+The same rule applies one layer down. A Better Auth user claims an existing app `User` only when
+the provider verified its email, or when the user proves they own that `User` another way (see
+the migration below). Terreno checks this **before the Better Auth user is created**. An
+unverified sign-up for someone else's address gets 409 "Verify your email to use this account"
+and leaves nothing behind: no Better Auth user, no `account` row, no verification email. That
+matters because a Better Auth user left behind would be a pre-registration one layer down: once
+anyone verified that email (the victim clicking the mail the attacker's sign-up triggered, or an
+admin), the attacker's password would open the victim's `User`. Terreno never inserts a second
+`User` for the same email either.
+
+Two more rules hold whichever way the claim is proven. A `User` that already carries another
+Better Auth account's `betterAuthId` is never relinked by email (409 `ACCOUNT_ALREADY_EXISTS`).
+And when a verified email links a `User` whose own `emailVerified` is not `true`, the `User`'s
+legacy password is removed and its `tokenEpoch` bumped: whoever set that password never proved
+they own the mailbox, so it and the JWT refresh tokens issued from it stop working. A link proven
+by the legacy password itself keeps that password. Operator seeds pass `trustEmail` to
+`syncBetterAuthUser`, which skips these checks for accounts the seed created itself.
+
+Emails are compared ignoring case, so a legacy `User` stored as `Jane@Example.com` is protected
+from a sign-up as `jane@example.com`, and claiming it never creates a second `User`.
+
+**Trade-off: the 409 reveals that an account exists.** A sign-up that gets 409
+`VERIFY_EMAIL_TO_USE_ACCOUNT` tells the caller that an app `User` already has that email. Terreno
+accepts this account-existence signal: refusing silently would either leave the
+pre-registration hole open or leave legitimate users stuck with no explanation, and Better Auth's
+own sign-up already answers `USER_ALREADY_EXISTS` for emails it knows. Apps that must hide
+membership (for example, where an account implies care) should rate-limit sign-up (the `auth`
+bucket) and word the client message neutrally.
+
+The guard needs a user model on the Better Auth instance. `BetterAuthApp` uses its own
+`userModel`, or adopts `TerrenoApp`'s when it was given none, before it creates Better Auth. If you
+call `createBetterAuth` yourself, pass `userModel` to it whenever a session middleware links app
+`User`s.
+
+Terreno then syncs the app `User` as each Better Auth session is created, while the request that
+proves who the user is (its password, its provider) is still in hand. That is also when
+`oauthProvider` is recorded. The session check repeats the claim rule as a second guard, and a
+password-proven link that fails to save fails the sign-in (500 `APP_USER_LINK_FAILED`) instead of
+leaving a session that every request would refuse.
+
+## Apple private-relay emails
+
+Sign in with Apple lets users hide their address. Apple then reports a relay address such as
+`abc123@privaterelay.appleid.com`, marked verified, that forwards to the real inbox. It never
+matches the email the person used elsewhere, so Apple sign-in creates a separate account in every
+mode. Users who want one account sign in their usual way and link Apple from the Security screen
+(`/link-social`). That link works only when Apple shares the real address ("Share My Email"):
+Better Auth refuses a link whose email differs from the account's unless `allowDifferentEmails`
+is on. Do not merge relay accounts by name: a name proves nothing.
+
+## Several accounts on one device
+
+Linking answers "is this the same person?". Some people really have several accounts, for example
+a parent with their own login and a child's. They should not merge them. `multiSession` lets one
+device hold several signed-in accounts and switch between them without signing out, and
+`signUp: {mode: "closed"}` stops new accounts altogether. Together with the linking mode, these
+are the three knobs an app has over "multiple accounts".
+
+## Migrating users from JWT auth
+
+Apps that started on Terreno's JWT and passport auth already have app `User`s with
+passport-local-mongoose password hashes. When such a user first signs in through Better Auth with
+the same email, Terreno links the new Better Auth user to their existing `User` if either:
+
+- the sign-in comes from a provider (Google, GitHub, Apple, ...) that reports the email as
+  verified, or
+- the password they sign up with verifies against the `User`'s existing passport hash. The
+  plaintext is checked only during that request and never stored. The check does not count as a
+  failed JWT login, so with passport's `limitAttempts` a stranger signing up with the victim's
+  email cannot lock the victim out.
+
+Otherwise the sign-up answers 409 "Verify your email to use this account" and nothing is created.
+Verifying the email afterwards cannot link anything, because there is no Better Auth user to
+verify. Before this change, any unverified sign-up claimed the `User` with the same email, which
+let anyone take over a legacy account by signing up with its address.
+
+Users who signed in with GitHub through JWT have no password hash. They get in one of three ways:
+
+- a provider sign-in whose email the provider verified;
+- a password reset sent to their email through the JWT forgot-password flow
+  (`POST /auth/forgotPassword`), then a Better Auth sign-up with the new password;
+- an admin-issued account recovery link (see [account security](../reference/api.md#better-auth-authentication)
+  once recovery is enabled) that sets their password and creates the Better Auth user.
+
+To migrate smoothly:
+
+1. Keep the JWT auth routes mounted while users move over, so forgot-password still works.
+2. Tell users to sign up with the email and password they already use; those link at once.
+3. Point users without a password at a provider sign-in or at JWT forgot-password.
+
+## Learn more
+
+- [Authentication architecture](authentication.md)
+- [Configure Better Auth](../how-to/configure-better-auth.md)
+- [Better Auth: users and accounts](https://www.better-auth.com/docs/concepts/users-accounts#account-linking)

package/dist/docs/versioned/57.20.0/explanation/admin-interface.md

@@ -0,0 +1,88 @@
+# How admin interfaces are shaped
+
+Prefer existing admin packages over a new dashboard. `@terreno/admin-backend`
+exposes `/admin/config` plus per-model CRUD. `@terreno/admin-frontend` renders that
+config as a sidebar, home dashboard, tables, and forms. `@terreno/admin-spa` is the
+same UI served from the API origin.
+
+Consumer screens are thin routes. They wrap `AdminProvider` + `AdminShellLayout` and
+let `AdminHome`, `AdminScreenRouter`, `AdminModelTable`, and `AdminModelForm` do the
+work. Hand-write a route only when the generic table/form cannot express the
+workflow (consent publish, comms message detail, password-on-create).
+
+## Two hosts
+
+| Host | When to use | Route prefix (`routeBase`) | API prefix (`apiBase`) | Fetch auth |
+| --- | --- | --- | --- | --- |
+| Embedded (`example-frontend/app/admin`) | Admin lives inside the product Expo app | `"/admin"` | `"/admin"` | `getAuthHeaders` → Bearer, plus `apiOrigin` = RTK `baseUrl` so RPC does not hit the Expo origin |
+| Standalone (`@terreno/admin-spa`) | Same-origin console served by `AdminSpaServeApp` | `""` (SPA root; mount is `/console`) | `"/admin"` | `credentials="same-origin"`; empty `getAuthHeaders`; omit `apiOrigin` |
+
+`apiBase` is the HTTP path for `/config` and CRUD. `routeBase` is the Expo Router
+prefix the sidebar concatenates onto `/{model.name}` and `/{screen.name}`. Mixing
+them puts nav on the wrong URL. Embedded hosts must also set `apiOrigin` (the
+backend origin, e.g. `http://localhost:4000`) on `AdminProvider`. Native `fetch`
+RPC uses that origin to prefix `/admin/config` and `/rbac/roles`. Do not put the
+origin in `apiBase` — that would rewrite in-app navigation.
+
+## Screen kinds
+
+| Kind | Source of truth | Frontend |
+| --- | --- | --- |
+| Model changelist / form | `modelRouter({admin: ...})` or plugin `adminContribution()` | `AdminScreenRouter` → `AdminModelTable` / `AdminModelForm` (list filters live on `DataTable`, not a side drawer) |
+| Custom screen | `AdminApp.customScreens` or plugin `customScreens` (`name` + `displayName`) | Matching `AdminProvider.widgets.screens[name]`, or a dedicated Expo route |
+| Platform tool | Built-in (`scripts`, `roles`, `version`, `configuration`, audit log, feature flags, jobs) | Sidebar **Platform** section; visibility from `/admin/config.platformTools` (jobs is lifted from `customScreens`) |
+| Home widget | `AdminApp.home.slots` IDs | `AdminProvider.widgets.home` (built-ins already registered) |
+
+`GET /admin/config` is caller-specific. Models and custom screens without read
+access are omitted. The sidebar must not invent links the config did not return.
+
+## Navigation chrome
+
+`AdminShell` (via `AdminShellLayout`) always owns the sidebar. Do not add a second
+app-level nav inside admin.
+
+Order in the rail:
+
+1. **Home** → `{routeBase}/`
+2. **Models** grouped by `admin.group` (ungrouped models land in **General**). Custom screens with `group` render inside the matching group **before** model links for that group. A grouped screen with no models still gets its own group heading.
+3. **Screens** — only `customScreens` **without** `group` (plus optional host extras)
+4. **Platform** — Scripts (`/__scripts`), Migrations (`/__migrations` when
+   `migrations.enabled`), Roles, Version, Audit Log, Feature Flags, Jobs, Configuration
+
+Audit log and Feature Flags are models, but the shell lifts them into Platform so
+operators do not hunt for them among business collections. The Platform Audit Log
+row is `AuditEvent` when `AuditApp` is registered. `isAuditLogModel` also matches
+legacy `AdminAuditLog`, `audit-log`, and `audit-events` names. Jobs is a custom
+screen (`name: "jobs"`); the shell lifts it the same way.
+
+Below the desktop floor (1024pt) the rail becomes a hamburger drawer. The main column is a body-style
+canvas (`neutral-050`, or `neutral-900` in dark mode so `surface.base` cards stand out).
+The colorful teal rail has no dark palette, so dark mode always uses the clinical rail.
+Host apps must give React Navigation a theme that follows the Terreno color scheme
+(the example app uses `buildNavigationTheme` with a transparent background inside the
+admin `Stack`); otherwise its default light screen containers cover the canvas. Nested `Page` screens use `color="transparent"` and
+`padding={0}` so cards sit on that canvas. Custom screens wrap content in
+`AdminScreenPage`; the back arrow uses `router.push(routeBase)` rather than
+`router.back()` because sidebar clicks do not always leave history on web.
+
+## Where code goes
+
+| Concern | Location |
+| --- | --- |
+| Which models appear | `modelRouter` `admin` block, or plugin `adminContribution()` |
+| Extra non-CRUD pages | `AdminApp.customScreens` + `widgets.screens` with the **same** `name`. Optional `group` places the screen in that sidebar group (see **Models** above). |
+| Home dashboard composition | `AdminApp.home.slots` |
+| Field widgets | `admin.fieldOverrides.widget` + `widgets.fields` |
+| Expo files | `app/admin/_layout.tsx` (shell once) or per-route shell in admin-spa |
+| Dedicated extra segments (`/comms/:id`) | Explicit Expo files so `[model]/[id]` does not treat them as generic forms |
+| Data fetching | REST remains membership/search/sort/pagination. String `_id` models with `adminBroadcast` overlay TinyBase and write through syncdb when the host passes a window client + fetch auth. Framework RPC uses host-bound fetch; ObjectId/API-only CRUD keeps RTK compatibility in Terreno 57. |
+
+## Related
+
+- [Build admin screens](../how-to/build-admin-screens.md)
+- [Add a model to the admin](../how-to/admin-add-model.md)
+- [Customize the admin home](../how-to/admin-custom-home.md)
+- [Add a custom admin field widget](../how-to/admin-custom-widget.md)
+- [Admin plugin frontend widgets](admin-plugin-frontend.md)
+- [admin-frontend reference](../reference/admin-frontend.md)
+- [admin-config reference](../reference/admin-config.md)

package/dist/docs/versioned/57.20.0/explanation/agent-guidelines.md

@@ -0,0 +1,173 @@
+# Agent guidelines
+
+An agent writes Terreno-shaped code only when Terreno's conventions are in its context.
+Those conventions reach it through four channels. Each one has a single source of truth,
+and every other copy is generated from it.
+
+| Channel | Source of truth | How the agent gets it | Status |
+| --- | --- | --- | --- |
+| Hosted MCP docs | `docs/`, `website/versioned_docs/`, `mcp-server/src/docs/resources/` | `terreno_search_docs`, `terreno_get_component_docs`, `terreno://docs/*` resources | Shipped |
+| Per-package guidelines | `<package>/.ai/guidelines/core.md` | Merged into the files `terreno_bootstrap_ai_rules` returns | Shipped |
+| App rule files | The app's `.rulesync/rules/` | Generated per editor by `rulesync generate` | Shipped |
+| Agent skills | `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, `.rulesync/skills/` | `npx skills add TerrenoLabs/terreno` or a host plugin | Shipped |
+
+The runtime side of the loop, meaning what the agent can see in a running app, is covered
+in [AI development loop](ai-development-loop.md). This page covers only conventions.
+
+## Hosted docs and search
+
+The hosted server (`terreno-mcp`) bundles the docs at build time. `sync-versioned-docs`
+copies `docs/` as the `next` version and each `website/versioned_docs/version-*` tree as a
+released version. `sync-ui-docs` copies the component type data.
+
+`terreno_search_docs` runs BM25 over that corpus and the resource pages. It takes several
+queries in one call, an optional package filter, and an optional lockstep `version`. With a
+version, it answers from the nearest retained snapshot, so an app on an older release gets
+that release's guidance.
+
+Resources are the fixed entry points: `terreno://docs/overview`, `api`, `ui`, `syncdb`,
+`rtk`, `patterns`, plus one page per `@terreno/ui` component. A client can read them
+without a tool call.
+
+Search is pull-based. The agent sees nothing until it asks. That is why the search tool's
+own description tells the agent to call it before guessing at Terreno APIs.
+
+## Per-package `.ai/` guidelines
+
+Each core package keeps a short `.ai/guidelines/core.md` next to its code, so a change to
+the package and a change to its guidance land in the same PR. Two packages also carry skill
+copies under `.ai/skills/`.
+
+| Package | `.ai/` contents | In the npm tarball |
+| --- | --- | --- |
+| `@terreno/api` | `guidelines/core.md`, `skills/mongoose-schema-safety/` | Yes (no `files` field) |
+| `@terreno/ui` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+| `@terreno/rtk` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+| `@terreno/syncdb` | `guidelines/core.md`, `skills/debug-syncdb-with-mcp/` | No (`files` is `dist` and `src` only) |
+| `@terreno/admin-backend` | `guidelines/core.md` | Yes (no `files` field) |
+| `@terreno/admin-frontend` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+
+The path that matters today runs through the MCP server, not `node_modules`.
+`mcp-server/scripts/sync-package-guidelines.ts` copies every `.ai/` tree into
+`mcp-server/src/docs/guidelines/<package>/`. `@terreno/mcp` publishes that directory, and
+`terreno_bootstrap_ai_rules` reads it.
+
+Nothing in Terreno reads `node_modules/@terreno/*/.ai/` in a consumer project yet; the
+tarball copies are available to any tool that looks for vendor guidelines there.
+
+Planned (from the per-package guidelines phase of the MCP parity plan, not built):
+
+- Versioned guidelines (`.ai/guidelines/<major>/core.md`) picked by the app's installed
+  version. Guidelines are a single flat `core.md` per package today.
+- Shipping `@terreno/syncdb`'s `.ai/` in its tarball. Its `files` field leaves it out.
+
+## `terreno_bootstrap_ai_rules`
+
+This hosted tool turns the package guidelines into rule files for one app. It does not
+write files. It returns their contents and instructions, and the agent writes them.
+
+| File | Contents |
+| --- | --- |
+| `.rulesync/rules/00-root.md` | The one root rule, for Cursor, Claude Code, Copilot, and `AGENTS.md`: app description, code style, and the merged `core.md` of `api`, `ui`, `rtk`, `syncdb` |
+| `backend/AGENTS.md`, `backend/CLAUDE.md` | Backend conventions, plus the `admin-backend` guidelines when requested |
+| `frontend/AGENTS.md`, `frontend/CLAUDE.md` | Frontend conventions, the MCP servers to use, plus the `admin-frontend` guidelines when requested |
+| `rulesync.jsonc` | rulesync config: `rules` feature, targets `cursor`, `claudecode`, `copilot`, `agentsmd`, `delete: true` |
+
+`packages` narrows the merge. Pass the app's `@terreno/*` dependencies so a project without
+the admin panel gets no admin guidance. Unknown ids are dropped, and an empty result falls
+back to all six packages.
+
+The root rules go through rulesync. The `backend/` and `frontend/` files do not: they are
+direct output, written as-is.
+
+`bunx create-terreno-app` writes its own `.cursorrules` and `CLAUDE.md`. The
+`terreno_bootstrap` prompt tells the agent to run `create-terreno-app` first and this tool
+second.
+
+The returned instructions run `bunx rulesync@9 generate`, the major this repository pins.
+A test in `mcp-server` runs `rulesync generate` on the returned files. From `00-root.md`,
+rulesync writes `.cursor/rules/00-root.mdc`, `CLAUDE.md`, `.github/copilot-instructions.md`,
+and `AGENTS.md`. Windsurf, Codex, and other agents read
+`AGENTS.md`; rulesync 9 has no `windsurf` target. The generated `CLAUDE.md` replaces the
+one `create-terreno-app` wrote, and `.cursor/rules/00-root.mdc` supersedes its
+`.cursorrules`, so delete that file. The root rule contains everything both files said,
+including the "Adding Features" steps.
+
+Earlier versions of the tool also returned `.rulesync/rules/01-claudecode-root.md`, a
+`localRoot` rule that rulesync 9 rejects without a Claude Code `root` rule. Delete that file
+when you re-bootstrap. The root rule now covers Claude Code.
+
+## The `.rulesync/` pattern
+
+This repository and the apps the tool bootstraps follow the same rule. Agent instructions
+are written once under `.rulesync/`, and every editor-specific file is generated from them.
+
+In this repository:
+
+| Source | Generated targets |
+| --- | --- |
+| `.rulesync/rules/**` | `CLAUDE.md`, `.claude/rules/`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.github/instructions/`, `.devin/rules/` |
+| `.rulesync/skills/`, `.rulesync/subagents/`, `.rulesync/hooks.json` | Per-host skill, subagent, and hook directories (`.claude/`, `.cursor/`, `.github/`, `.devin/`, `.agents/`) |
+| `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, plus `.rulesync/skills/` | `skills/` (installable set), `plugins/terreno-claude/` and `plugins/terreno-scan-claude/` (Claude Code plugins) |
+
+`rulesync.jsonc` maps each target to its features. `bun run rules` regenerates the rulesync
+targets. `bun run skills:sync` regenerates `skills/` and the Claude plugin. The
+`rulesync-check` workflow regenerates and fails on any diff, and `bun run skills:check` does
+the same for skills.
+
+The config sets `delete: true`. rulesync removes stale generated files before it writes, so
+a generated file holds only what its source says. A hand edit to a generated file is lost
+on the next run.
+
+## Extending the rules in your app
+
+Regeneration replaces two kinds of file. rulesync replaces every generated editor file. A
+re-run of `terreno_bootstrap_ai_rules` returns fresh copies of everything in its table,
+including `00-root.md`, `rulesync.jsonc`, and the `backend/`/`frontend/` agent files. Anything you add to those files is lost.
+
+`rulesync generate` runs with `delete: true`. It overwrites the root `CLAUDE.md`,
+`AGENTS.md`, and `.github/copilot-instructions.md`. It deletes every file under
+`.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, and `.agents/memories/` that
+it did not generate. Before the first `rulesync generate`, and before every later one,
+move any edits to those root files and any hand-written files in those directories into
+`.rulesync/rules/10-project.md` or another `.rulesync/rules/*.md` source. Otherwise they
+are lost.
+
+Keep your conventions in rulesync sources the tool never emits:
+
+1. Leave `00-root.md` untouched. Treat it as Terreno-owned.
+2. Add one or more files such as `.rulesync/rules/10-project.md`. Use a number above `00`
+   and a name the tool does not use.
+3. Scope with `globs` instead of editing `backend/AGENTS.md` or `frontend/AGENTS.md`. A rule
+   with `globs: ["backend/**"]` applies to backend files in every editor.
+4. Run `bunx rulesync@9 generate` and commit the sources and the output together.
+
+```markdown
+---
+targets: ["*"]
+description: "Acme backend conventions"
+globs: ["backend/**"]
+---
+
+# Acme backend
+
+- Store money as integer cents in fields named `*Cents`.
+- Every tenant-scoped model has an `orgId` index.
+```
+
+From one source, rulesync 9 writes `.cursor/rules/10-project.mdc` (`globs`),
+`.claude/rules/10-project.md` (`paths`), `.github/instructions/10-project.instructions.md`
+(`applyTo`), and `.agents/memories/10-project.md` (linked from `AGENTS.md`). A re-bootstrap
+followed by `rulesync generate` leaves these files in place and
+replaces only the Terreno-owned ones.
+
+If you changed `rulesync.jsonc`, for example to add a target, reapply that change after a
+re-bootstrap. The tool returns the default config.
+
+## Related
+
+- [AI development loop](ai-development-loop.md): what the agent sees at runtime
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md): connect both servers to your editor
+- [MCP server reference](../reference/mcp-server.md#terreno_bootstrap_ai_rules): tool parameters
+- [Install agent skills](../how-to/install-agent-skills.md): the skills channel
+- [Planning plugins](planning-plugins.md): how the lifecycle skills are packaged