@bonesofspring/ai-rules 0.2.23 → 0.2.24

package/presets/cursor/php-hexagonal/rules/preset-twin-sync.mdc

@@ -42,6 +42,20 @@ _shared/core  →  cursor/<stack>  →  mavis/<stack>
 
 Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
 
+## OpenCode derivation (not a Claude twin)
+
+| Stack | Cursor SoT | OpenCode derive | Manifest |
+|-------|------------|-----------------|----------|
+| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode-next.mjs` | **Required** `adapter-map.json` |
+
+OpenCode is a **fourth platform adapter** with a **native** install root (`.opencode/`), not a Claude-style topic twin and not an owned overlay like `.mavis/`:
+
+```text
+_shared/core  →  cursor/<stack>  →  opencode/<stack>
+```
+
+Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
+
 ## Same-PR checklist
 
 1. Edit Cursor rule first (body + frontmatter).
@@ -49,6 +63,7 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 3. Update mapping table row if stem/path changed.
 4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
 5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`).
+6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`).
 
 ## Twin depth
 
@@ -70,5 +85,6 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 - **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
 - **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
 - **mavis/next:** `cursor/next` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
+- **opencode/next:** `cursor/next` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/cursor/php-laravel/rules/preset-layering.mdc

@@ -18,14 +18,14 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
-| **Platform** | Cursor `.mdc` / Claude `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule
 
 1. Shared principles for all stacks → **core** + adapters with `<!-- shared-core: … -->`.
 2. Only one of the installable stacks (`next` / `nuxt` / `svelte` / `ios-swift` / `android-kotlin` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (not in `_shared`).
-3. Only Cursor or only Claude packaging → platform artifact / frontmatter; do not duplicate semantics.
+3. Only Cursor, Claude, Mavis, or OpenCode packaging → platform artifact / frontmatter; do not duplicate semantics.
 
 ## SoT
 

package/presets/cursor/php-laravel/rules/preset-no-cross-stack-leakage.mdc

@@ -96,4 +96,4 @@ Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`,
 
 ## Chain fork
 
-`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform). Released Mavis/OpenCode stacks must also differ from the Cursor and Claude twins of the same stack.

package/presets/cursor/php-laravel/rules/preset-pr-checklist.mdc

@@ -19,17 +19,18 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
 - [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`; see `preset-twin-sync` § Mavis derivation)
+- [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
 - [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
 - [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.
-- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` across the 10 stacks × 2 platforms (20 hooks) holds. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
+- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` holds pairwise among the 10 stacks × Cursor/Claude platforms, and each released Mavis/OpenCode stack hook must also differ from the Cursor and Claude twins of the same stack. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
 - [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
 - [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
 - [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
 - [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
-- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (or document intentional skip) when maintaining this monorepo
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (and `sync-dogfood-mavis.sh` / `sync-dogfood-opencode.sh` when those platforms changed), or document an intentional skip, when maintaining this monorepo
 - [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
 
 ## Pointers
@@ -39,6 +40,6 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - Budget: `preset-token-budget`
 - Leakage: `preset-no-cross-stack-leakage`
 - Validation: stack `agents/build-verifier.md` → preset-structure section
-- Dogfood script: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`
+- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
 - Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
 - Orchestrator: when editing presets, load this checklist + twin-sync

package/presets/cursor/php-laravel/rules/preset-token-budget.mdc

@@ -19,6 +19,8 @@ Invariants for rule loading in an **installed** preset (consumer app).
 |----------|-----------|-----|
 | Cursor | `alwaysApply: true` | **≤ 4** |
 | Claude | rules **without** `paths:` | **exactly 3** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
 
 **Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
 
@@ -27,6 +29,7 @@ Invariants for rule loading in an **installed** preset (consumer app).
 Session-start body budget:
 - Claude trio: ≤140 lines total (stretch ≤120).
 - Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
+- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 

package/presets/cursor/php-laravel/rules/preset-twin-sync.mdc

@@ -42,6 +42,20 @@ _shared/core  →  cursor/<stack>  →  mavis/<stack>
 
 Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
 
+## OpenCode derivation (not a Claude twin)
+
+| Stack | Cursor SoT | OpenCode derive | Manifest |
+|-------|------------|-----------------|----------|
+| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode-next.mjs` | **Required** `adapter-map.json` |
+
+OpenCode is a **fourth platform adapter** with a **native** install root (`.opencode/`), not a Claude-style topic twin and not an owned overlay like `.mavis/`:
+
+```text
+_shared/core  →  cursor/<stack>  →  opencode/<stack>
+```
+
+Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
+
 ## Same-PR checklist
 
 1. Edit Cursor rule first (body + frontmatter).
@@ -49,6 +63,7 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 3. Update mapping table row if stem/path changed.
 4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
 5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`).
+6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`).
 
 ## Twin depth
 
@@ -70,5 +85,6 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 - **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
 - **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
 - **mavis/next:** `cursor/next` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
+- **opencode/next:** `cursor/next` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/cursor/svelte/rules/preset-layering.mdc

@@ -18,14 +18,14 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
-| **Platform** | Cursor `.mdc` / Claude `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule
 
 1. Shared principles for all stacks → **core** + adapters with `<!-- shared-core: … -->`.
 2. Only one of the installable stacks (`next` / `nuxt` / `svelte` / `ios-swift` / `android-kotlin` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (not in `_shared`).
-3. Only Cursor or only Claude packaging → platform artifact / frontmatter; do not duplicate semantics.
+3. Only Cursor, Claude, Mavis, or OpenCode packaging → platform artifact / frontmatter; do not duplicate semantics.
 
 ## SoT
 

package/presets/cursor/svelte/rules/preset-no-cross-stack-leakage.mdc

@@ -96,4 +96,4 @@ Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`,
 
 ## Chain fork
 
-`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform). Released Mavis/OpenCode stacks must also differ from the Cursor and Claude twins of the same stack.

package/presets/cursor/svelte/rules/preset-pr-checklist.mdc

@@ -19,17 +19,18 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
 - [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`; see `preset-twin-sync` § Mavis derivation)
+- [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
 - [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
 - [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.
-- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` across the 10 stacks × 2 platforms (20 hooks) holds. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
+- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` holds pairwise among the 10 stacks × Cursor/Claude platforms, and each released Mavis/OpenCode stack hook must also differ from the Cursor and Claude twins of the same stack. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
 - [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
 - [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
 - [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
 - [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
-- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (or document intentional skip) when maintaining this monorepo
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (and `sync-dogfood-mavis.sh` / `sync-dogfood-opencode.sh` when those platforms changed), or document an intentional skip, when maintaining this monorepo
 - [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
 
 ## Pointers
@@ -39,6 +40,6 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - Budget: `preset-token-budget`
 - Leakage: `preset-no-cross-stack-leakage`
 - Validation: stack `agents/build-verifier.md` → preset-structure section
-- Dogfood script: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`
+- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
 - Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
 - Orchestrator: when editing presets, load this checklist + twin-sync

package/presets/cursor/svelte/rules/preset-token-budget.mdc

@@ -19,6 +19,8 @@ Invariants for rule loading in an **installed** preset (consumer app).
 |----------|-----------|-----|
 | Cursor | `alwaysApply: true` | **≤ 4** |
 | Claude | rules **without** `paths:` | **exactly 3** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
 
 **Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
 
@@ -27,6 +29,7 @@ Invariants for rule loading in an **installed** preset (consumer app).
 Session-start body budget:
 - Claude trio: ≤140 lines total (stretch ≤120).
 - Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
+- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 

package/presets/cursor/svelte/rules/preset-twin-sync.mdc

@@ -42,6 +42,20 @@ _shared/core  →  cursor/<stack>  →  mavis/<stack>
 
 Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
 
+## OpenCode derivation (not a Claude twin)
+
+| Stack | Cursor SoT | OpenCode derive | Manifest |
+|-------|------------|-----------------|----------|
+| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode-next.mjs` | **Required** `adapter-map.json` |
+
+OpenCode is a **fourth platform adapter** with a **native** install root (`.opencode/`), not a Claude-style topic twin and not an owned overlay like `.mavis/`:
+
+```text
+_shared/core  →  cursor/<stack>  →  opencode/<stack>
+```
+
+Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
+
 ## Same-PR checklist
 
 1. Edit Cursor rule first (body + frontmatter).
@@ -49,6 +63,7 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 3. Update mapping table row if stem/path changed.
 4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
 5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`).
+6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`).
 
 ## Twin depth
 
@@ -70,5 +85,6 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 - **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
 - **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
 - **mavis/next:** `cursor/next` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
+- **opencode/next:** `cursor/next` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/mavis/next/REPO_AGENTS.md

@@ -1,7 +1,7 @@
 # Next.js — agent instructions
 
 Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md`,
-`.claude/CLAUDE.md`, and `.mavis/AGENTS.md`.
+`.claude/CLAUDE.md`, `.mavis/AGENTS.md`, and `.opencode/AGENTS.md`.
 
 **.mavis/** is an ai-rules-owned namespace, not a MiniMax-native discovery path.
 When this Mavis preset is installed, read `.mavis/AGENTS.md` on every turn.
@@ -12,13 +12,14 @@ owns those files.
 ## Cross-tool setup
 
 - Treat this file as the **shared** entry for any agent (Cursor, Claude Code,
-  Mavis / MiniMax Code, or other).
+  Mavis / MiniMax Code, OpenCode, or other).
 - Install:
 
 ```bash
 npx @bonesofspring/ai-rules init cursor --preset next
 npx @bonesofspring/ai-rules init claude --preset next
 npx @bonesofspring/ai-rules init mavis --preset next
+npx @bonesofspring/ai-rules init opencode --preset next
 ```
 
 `init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`).
@@ -66,16 +67,17 @@ After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent
 | Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
 | Claude Code | `.claude/CLAUDE.md` (optional if Claude Code not installed) |
 | Mavis | `.mavis/AGENTS.md` (optional if Mavis not installed) |
+| OpenCode | `.opencode/AGENTS.md` (optional if OpenCode not installed) |
 
-Rules: `.cursor/rules/`, `.claude/rules/`, or `.mavis/rules/`.
-Skills: `.cursor/skills/`, `.claude/skills/`, or `.mavis/skills/`.
+Rules: `.cursor/rules/`, `.claude/rules/`, `.mavis/rules/`, or `.opencode/rules/`.
+Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/skills/`.
 
 ## Living conventions
 
 Gotchas, local patterns, and team decisions:
-**`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**, and/or
-**`.mavis/team/conventions.md`** (fill after init; not overwritten on every
-dogfood sync when already present).
+**`.cursor/team/conventions.md`**, **`.claude/team/conventions.md`**,
+**`.mavis/team/conventions.md`**, and/or **`.opencode/team/conventions.md`**
+(fill after init; not overwritten on every dogfood sync when already present).
 
 ## Local overlay (`.ai.local/`) — MANDATORY
 

package/presets/mavis/next/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "mavis",
   "stack": "next",
   "semanticSource": "cursor/next",
-  "sourceRevision": "784415cc56d70b38489f7515cdbc8d557bbfcdcba517e22c2e3e0b8b03f44c7f",
+  "sourceRevision": "be606e26d6d0e3f27c2a753e4025925670bc42f6e41d53ec9efc47cdb3a7be7f",
   "entries": [
     {
       "source": "AGENTS.md",

package/presets/mavis/next/agents/build-verifier.md

@@ -40,13 +40,15 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 7. **Embed drift (hard in `check:preset-structure`):** run `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1` (bundled by the structure orchestrator). Lineage stems are excluded from body equality.
 8. **Dogfood (monorepo soft):** if root `.cursor/` is in the PR, prefer sync via `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass deletion of tracked dogfood without migration doc → note as risk / FAIL for maintainers.
 
-9. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|nuxt|svelte|ios-swift|go|java|mcp-ts|php-hexagonal|php-laravel`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
+9. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|nuxt|svelte|ios-swift|go|java|mcp-ts|php-hexagonal|php-laravel`, plus released `mavis/<stack>` and `opencode/<stack>`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
 10. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
 11. **Performance skill by stack:** next → `react-performance`; nuxt → `vue-performance`. **No react-performance/vue-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel → **FAIL** (leakage). Prefer `check:preset-leakage`.
 12. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.
 
 13. **Product-specs assets (FAIL):** package must ship `presets/_shared/assets/docs-specs/INDEX.md`, `_templates/page.md`, `_templates/feature.md`. Cursor+Claude twins for `product-specs` and `product-specs-authoring` must embed matching shared-core markers; both stems **requestable** (`alwaysApply: false` / Claude `paths: docs/specs/**`) — never session-start.
 14. **Optional consumer check (WARN default):** `scripts/check-product-specs.sh` + schema stub may exist for opt-in consumer CI; **FAIL** only with `--strict` or AC that requires named specs — do not force consumer CI.
+15. **Mavis derive (next):** when `presets/mavis/**` or mapped `cursor/next` sources change, run `check:mavis-adapter-map`, `check:mavis-token-budget`, `check:mavis-local-overlay`, and `check:mavis-platform-contract`. Adapter-map `sourceRevision` drift → **FAIL**.
+16. **OpenCode derive (next):** when `presets/opencode/**` or mapped `cursor/next` sources change, run `check:opencode-adapter-map`, `check:opencode-token-budget`, `check:opencode-local-overlay`, `check:opencode-platform-contract`, and `test:opencode-context-budget`. Adapter-map `sourceRevision` drift → **FAIL**.
 
 
 **mockup-reviewer (UI):** `agents/mockup-reviewer.md` and `skills/mockup-review/` must exist (Cursor + Claude). Missing → **FAIL**. Backend stacks must **not** ship that agent file or a required `mockup-reviewer` chain handoff → **FAIL** if present.

package/presets/mavis/next/rules/agent-team-orchestrator.md

@@ -194,9 +194,9 @@ If `pipeline.json` is missing, fall back to fixed phases: analysis → developme
 
 Do **not** run `/task` + router for:
 
-- Pure questions (“how does X work”, “explain”) — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners.
+- Pure questions («как работает X» (how does X work), «объясни» (explain)) — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners. <!-- i18n-keep: E4 -->
 - Typo / one-file fix / trivial config with no architecture risk.
-- User explicitly says “no pipeline”, “just do it”, or continues an active slug.
+- User explicitly says «без pipeline» (no pipeline), «просто сделай» (just do it), or continues an active slug. <!-- i18n-keep: E4 -->
 - Single-line `docs-only` with no code impact.
 
 Borderline work requests — see **agent-team-intake**.

package/presets/mavis/next/rules/ai-local-overlay.md

@@ -26,7 +26,7 @@ Keep files ≤ 120 lines. Match the style of preset rules (short sections, bulle
 
 ## Limitations (read this)
 
-- Cursor/Claude do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
+- Cursor, Claude, Mavis, and OpenCode do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
 - If a user adds a file to `.ai.local/` mid-session, **restart the session** to be sure it is picked up.
 - "Priority" is **contextual**, not enforced. Always re-read the local rule before answering questions that touch it.
 

package/presets/mavis/next/rules/preset-layering.md

@@ -9,14 +9,14 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
-| **Platform** | Cursor `.mdc` / Claude `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule
 
 1. Shared principles for all stacks → **core** + adapters with `<!-- shared-core: … -->`.
 2. Only one of the installable stacks (`next` / `nuxt` / `svelte` / `ios-swift` / `android-kotlin` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (not in `_shared`).
-3. Only Cursor or only Claude packaging → platform artifact / frontmatter; do not duplicate semantics.
+3. Only Cursor, Claude, Mavis, or OpenCode packaging → platform artifact / frontmatter; do not duplicate semantics.
 
 ## SoT
 

package/presets/mavis/next/rules/preset-no-cross-stack-leakage.md

@@ -87,4 +87,4 @@ Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`,
 
 ## Chain fork
 
-`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform). Released Mavis/OpenCode stacks must also differ from the Cursor and Claude twins of the same stack.

package/presets/mavis/next/rules/preset-pr-checklist.md

@@ -10,17 +10,18 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
 - [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`; see `preset-twin-sync` § Mavis derivation)
+- [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
 - [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
 - [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.
-- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` across the 10 stacks × 2 platforms (20 hooks) holds. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
+- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` holds pairwise among the 10 stacks × Cursor/Claude platforms, and each released Mavis/OpenCode stack hook must also differ from the Cursor and Claude twins of the same stack. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
 - [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
 - [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
 - [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
 - [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
-- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (or document intentional skip) when maintaining this monorepo
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (and `sync-dogfood-mavis.sh` / `sync-dogfood-opencode.sh` when those platforms changed), or document an intentional skip, when maintaining this monorepo
 - [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
 
 ## Pointers
@@ -30,6 +31,6 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - Budget: `preset-token-budget`
 - Leakage: `preset-no-cross-stack-leakage`
 - Validation: stack `agents/build-verifier.md` → preset-structure section
-- Dogfood script: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`
+- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
 - Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
 - Orchestrator: when editing presets, load this checklist + twin-sync

package/presets/mavis/next/rules/preset-token-budget.md

@@ -10,6 +10,8 @@ Invariants for rule loading in an **installed** preset (consumer app).
 |----------|-----------|-----|
 | Cursor | `alwaysApply: true` | **≤ 4** |
 | Claude | rules **without** `paths:` | **exactly 3** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
 
 **Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
 
@@ -18,6 +20,7 @@ Invariants for rule loading in an **installed** preset (consumer app).
 Session-start body budget:
 - Claude trio: ≤140 lines total (stretch ≤120).
 - Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
+- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 

package/presets/mavis/next/rules/preset-twin-sync.md

@@ -33,6 +33,20 @@ _shared/core  →  cursor/<stack>  →  mavis/<stack>
 
 Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
 
+## OpenCode derivation (not a Claude twin)
+
+| Stack | Cursor SoT | OpenCode derive | Manifest |
+|-------|------------|-----------------|----------|
+| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode-next.mjs` | **Required** `adapter-map.json` |
+
+OpenCode is a **fourth platform adapter** with a **native** install root (`.opencode/`), not a Claude-style topic twin and not an owned overlay like `.mavis/`:
+
+```text
+_shared/core  →  cursor/<stack>  →  opencode/<stack>
+```
+
+Regenerate with `node packages/ai-rules/scripts/generate-opencode-next.mjs`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
+
 ## Same-PR checklist
 
 1. Edit Cursor rule first (body + frontmatter).
@@ -40,6 +54,7 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 3. Update mapping table row if stem/path changed.
 4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
 5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`).
+6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode-next.mjs` + `check-opencode-adapter-map.mjs` for `next`).
 
 ## Twin depth
 
@@ -61,5 +76,6 @@ Regenerate with `node packages/ai-rules/scripts/generate-mavis-next.mjs`; valida
 - **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
 - **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
 - **mavis/next:** `cursor/next` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
+- **opencode/next:** `cursor/next` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/opencode/README.md

@@ -0,0 +1,61 @@
+# OpenCode platform adapter
+
+Sibling of `presets/cursor/`, `presets/claude/`, and `presets/mavis/`.
+Platform id is **`opencode`**. The external runtime executable is **`opencode`**.
+
+This directory is the **source** tree. Consumer installs land under **`.opencode/`**
+(native OpenCode discovery for agents, skills, and commands) plus root
+`AGENTS.md` and `opencode.json`.
+
+Do not write `~/.config/opencode/**` from init, clean, or probes.
+
+## Status
+
+`platform-contract.json` `releasedStacks` lists installable stacks. **`next`**
+is released (`npx @bonesofspring/ai-rules init opencode --preset next`).
+Additional stacks ship after the Next pilot.
+
+Derivation (approved architecture):
+
+```text
+_shared/core  →  cursor/<stack>  →  opencode/<stack>
+                 cursor/<stack>  →  claude/<stack>   (unchanged twin)
+                 cursor/<stack>  →  mavis/<stack>    (unchanged)
+```
+
+OpenCode sources are **not** derived from Claude. Cursor remains the semantic
+source of truth.
+
+## Compatibility floor
+
+See [`docs/OPENCODE.md`](../../docs/OPENCODE.md) (consumer guide) and
+[`docs/OPENCODE-COMPATIBILITY.md`](../../docs/OPENCODE-COMPATIBILITY.md).
+Statuses come from official OpenCode docs until a live CLI probe exists.
+`unknown` / `no-equivalent` capabilities must not declare a native path.
+
+Native (documented):
+
+- root `AGENTS.md`
+- `.opencode/agents/`, `.opencode/skills/`, `.opencode/commands/`
+- `opencode.json` `mcp`
+
+Fallback (no Cursor-style rule engine / no `hooks.json`):
+
+- `.opencode/rules/**` — lazy `Read` from `AGENTS.md` catalog
+- pipeline lifecycle — `bash .opencode/hooks/chain-team-phases.sh` after receipts
+
+## Files
+
+| Path | Role |
+|------|------|
+| `platform-contract.json` | Machine-readable adapter declaration |
+| `next/` | Released Next.js stack (`releasedStacks: ["next"]`) |
+
+Validate:
+
+```bash
+node scripts/check-opencode-platform-contract.mjs
+node scripts/check-opencode-platform-contract.mjs --self-test
+node scripts/generate-opencode-next.mjs
+node scripts/check-opencode-adapter-map.mjs
+```

package/presets/opencode/next/MCP.md

@@ -0,0 +1,36 @@
+# MCP (preset `next`, OpenCode)
+
+Merged into project `opencode.json` `mcp` on `ai-rules init opencode --preset next`.
+
+## Servers
+
+| Name | Package | Purpose |
+|------|---------|---------|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Next/React/TS and library docs (fewer stale APIs in agent answers) |
+| `playwright` | `@playwright/mcp` | Browser automation for e2e agents (`playwright-test-*`) and selector checks |
+| `chrome-devtools` | `chrome-devtools-mcp` | Live DOM/network/performance when debugging UI |
+| `figma` | remote `https://mcp.figma.com/mcp` | Design context → code (layouts, tokens, Code Connect); OAuth in OpenCode (operator MCP config) |
+
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment — higher Context7 rate limits. Figma — OAuth on first connect (do not write the token into config).
+
+
+## Agent usage
+
+Load requestable rule `mcp-usage`. The **session MCP catalog** is source of truth (this file and `mcp.json` are hints). Discover tool schemas before calling; never invent them.
+
+**Context7 (shipped):** query docs when a third-party API is not confirmed by lockfile + sibling files. Use the installed major. Cap ≤3 doc queries per question. If Context7 is down, mark `// VERIFY` and continue — do not block.
+
+## Local overlay (not shipped)
+
+`init` **merges** `mcpServers`: preset keys are updated; extra local servers are kept. User-level MCP is never touched. Prefer user-level MCP if you do not want overlay servers in the project file.
+
+Use an overlay only when it is **ready** (`serverStatus` not `error` / `needsAuth` / `loading`) **and** the task fits. Absence is not a blocker unless the user required that MCP as source of truth.
+
+| Kind | Typical aliases | When |
+|------|-----------------|------|
+| Observability | `sentry`, `datadog`, `plugin-datadog-*` | production error, event/trace id, APM |
+| Tickets | `linear`, `jira`, `notion`, `plugin-notion-*` | ticket/page URL; read-only; task-folder artifacts remain SoT |
+| GitHub MCP | `github` | optional; native `gh` remains SoT for PRs and checks |
+| Storybook | `storybook`, `user-storybook`, `plugin-storybook`, `storybook-mcp-addon` | component docs/stories/controls; needs Storybook running; not shipped |
+
+**Browser split (this preset):** Playwright MCP → e2e agents and selectors. Chrome DevTools MCP → `debugger` / `performance-auditor` against a running app. Not interchangeable.