@bonesofspring/ai-rules 0.2.25 → 0.2.26

package/presets/mavis/svelte/team/fixtures/feature-with-figma-url.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-figma",
+  "intent": "feature",
+  "profile": "full",
+  "summary": "Feature with Figma mockup URL — mockup-reviewer after analyst, before architect and developer",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" },
+    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}

package/presets/mavis/svelte/team/fixtures/feature-with-ux-no-figma.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-ux-no-figma",
+  "intent": "feature",
+  "profile": "standard",
+  "summary": "Feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; no mockup-reviewer step",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify, UX design, decompose" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; analyst skill ux-design covers behavioral UX" }
+  ]
+}

package/presets/mavis/svelte/team/fixtures/memlog.example.md

@@ -0,0 +1,9 @@
+# Memlog example
+
+Append-only. Agents write; `/task-continue` may read. The hook does not parse this file.
+
+## 2026-08-13
+
+- `decision`: specMode=generate; research-before-spec requested
+- `claim`: empty-cart copy lives in CartEmpty.tsx (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/mavis/svelte/team/fixtures/metrics-scenarios/tasks/human-gate/metrics.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "human-gate-run",
+    "slug": "human-gate",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "human-gate-run:task",
+      "type": "task_started",
+      "at": "2026-07-31T17:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "human-gate-run:gate:1",
+      "type": "human_gate_started",
+      "at": "2026-07-31T17:01:00.000Z",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "human-gate-run:gate:end",
+      "type": "human_gate_ended",
+      "at": "2026-07-31T17:11:00.000Z",
+      "gateStartedEventId": "human-gate-run:gate:1",
+      "source": "command",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "human-gate-run:1:feature-developer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T17:11:00.000Z",
+      "attemptId": "human-gate-run:step-1:feature-developer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "feature-developer",
+      "role": "implementation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "human-gate-run:1:feature-developer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T17:12:00.000Z",
+      "attemptId": "human-gate-run:step-1:feature-developer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "human-gate-run:done",
+      "type": "task_completed",
+      "at": "2026-07-31T17:12:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/mavis/svelte/team/fixtures/metrics-scenarios/tasks/missing-ledger/status.json

@@ -0,0 +1,5 @@
+{
+  "slug": "missing-ledger",
+  "state": "completed",
+  "note": "Intentional fixture: metrics.json is absent."
+}

package/presets/mavis/svelte/team/fixtures/metrics-scenarios/tasks/parallel-receipts/metrics.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "parallel-receipts-run",
+    "slug": "parallel-receipts",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "parallel-receipts-run:task",
+      "type": "task_started",
+      "at": "2026-07-31T16:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "parallel-receipts-run:1:code-reviewer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T16:00:00.000Z",
+      "attemptId": "parallel-receipts-run:step-1:code-reviewer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "code-reviewer",
+      "role": "review",
+      "attempt": 1,
+      "parallelGroupId": "parallel-receipts-run:step-1",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "parallel-receipts-run:1:security-reviewer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T16:00:00.000Z",
+      "attemptId": "parallel-receipts-run:step-1:security-reviewer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "security-reviewer",
+      "role": "review",
+      "attempt": 1,
+      "parallelGroupId": "parallel-receipts-run:step-1",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "parallel-receipts-run:1:security-reviewer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T16:01:00.000Z",
+      "attemptId": "parallel-receipts-run:step-1:security-reviewer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "agent",
+      "attributionConfidence": "fallback"
+    },
+    {
+      "eventId": "parallel-receipts-run:1:code-reviewer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T16:02:00.000Z",
+      "attemptId": "parallel-receipts-run:step-1:code-reviewer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "agent",
+      "attributionConfidence": "fallback"
+    },
+    {
+      "eventId": "parallel-receipts-run:done",
+      "type": "task_completed",
+      "at": "2026-07-31T16:02:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/mavis/svelte/team/fixtures/metrics-scenarios/tasks/serial-retry/metrics.json

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "serial-retry-run",
+    "slug": "serial-retry",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "serial-retry-run:task",
+      "type": "task_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-1",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "code-reviewer",
+      "role": "review",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:01:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-1",
+      "outcome": "changes_requested",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:retry:1",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T14:01:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-1",
+      "nextAgent": "feature-developer",
+      "retryAfterFix": "code-reviewer",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:1:feature-developer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:01:00.000Z",
+      "attemptId": "serial-retry-run:step-1:feature-developer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "feature-developer",
+      "role": "implementation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:1:feature-developer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:03:00.000Z",
+      "attemptId": "serial-retry-run:step-1:feature-developer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:retry:2",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T14:03:00.000Z",
+      "attemptId": "serial-retry-run:step-1:feature-developer:attempt-1",
+      "nextAgent": "code-reviewer",
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:2:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:03:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-2",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "code-reviewer",
+      "role": "review",
+      "attempt": 2,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:2:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:04:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-2",
+      "outcome": "completed",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:done",
+      "type": "task_completed",
+      "at": "2026-07-31T14:04:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/mavis/svelte/team/fixtures/metrics-scenarios/tasks/validation-failed/metrics.json

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "validation-failed-run",
+    "slug": "validation-failed",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "validation-failed-run:task",
+      "type": "task_started",
+      "at": "2026-07-31T15:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:00:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "build-verifier",
+      "role": "validation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "outcome": "validation_failed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:retry:1",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "nextAgent": "feature-developer",
+      "retryAfterFix": "build-verifier",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:1:feature-developer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "feature-developer",
+      "role": "implementation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:1:feature-developer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 180000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:retry:2",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "nextAgent": "build-verifier",
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:2:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-2",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "build-verifier",
+      "role": "validation",
+      "attempt": 2,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:2:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:06:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-2",
+      "outcome": "completed",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:done",
+      "type": "task_completed",
+      "at": "2026-07-31T15:06:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/mavis/svelte/team/fixtures/metrics.example.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "example-run-1",
+    "slug": "example-feature-full",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "example-run-1:task_started",
+      "type": "task_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:attempt-1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "attemptId": "example-run-1:step-0:task-analyst:attempt-1",
+      "stepIndex": 0,
+      "stepLabel": "Clarify and decompose",
+      "agent": "task-analyst",
+      "role": "planning",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:attempt-1:end",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:02:00.000Z",
+      "attemptId": "example-run-1:step-0:task-analyst:attempt-1",
+      "outcome": "completed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:task_completed",
+      "type": "task_completed",
+      "at": "2026-07-31T14:02:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/mavis/svelte/team/fixtures/mockup-review-fail-embedded-status.json

@@ -0,0 +1,8 @@
+{
+  "slug": "example-mockup-fail-gate",
+  "state": "awaiting_approval",
+  "currentAgent": "mockup-reviewer",
+  "awaitingHumanGate": true,
+  "retryAfterFix": null,
+  "note": "Embedded mockup FAIL: hook must NOT set retryAfterFix to feature-developer. Resume only via /task-continue."
+}

package/presets/mavis/svelte/team/fixtures/mockup-review-standalone.json

@@ -0,0 +1,14 @@
+{
+  "slug": "example-mockup-review-standalone",
+  "intent": "mockup-review",
+  "profile": "light",
+  "summary": "Standalone Figma mockup review (report-only)",
+  "steps": [
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone mockup-review is report-only" }
+  ]
+}

package/presets/mavis/svelte/team/fixtures/ux-design-standalone.json

@@ -0,0 +1,15 @@
+{
+  "slug": "example-ux-design-standalone",
+  "intent": "ux-design",
+  "profile": "light",
+  "summary": "Standalone behavioral UX design (analyst + skill ux-design; report-only; no developer)",
+  "steps": [
+    { "agent": "task-analyst", "label": "UX design (skill ux-design)" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone ux-design is report-only" },
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; not a mockup review" }
+  ]
+}

package/presets/opencode/README.md

@@ -1,61 +1,18 @@
 # OpenCode platform adapter
 
-Sibling of `presets/cursor/`, `presets/claude/`, and `presets/mavis/`.
-Platform id is **`opencode`**. The external runtime executable is **`opencode`**.
+Derived from **Cursor SoT**. Platform id `opencode`. Do not write `~/.config/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):
+Consumer: native **`.opencode/{agents,skills,commands}`**, lazy `.opencode/rules/`, root `AGENTS.md`, MCP in `opencode.json`. `/task` artifacts seed to **`.ai.local/team/`**. `clean opencode` is manifest-owned and does not delete `.ai.local/`.
 
 ```text
-_shared/core  →  cursor/<stack>  →  opencode/<stack>
-                 cursor/<stack>  →  claude/<stack>   (unchanged twin)
-                 cursor/<stack>  →  mavis/<stack>    (unchanged)
+_shared/core → cursor/<stack> → opencode/<stack>
 ```
 
-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:
+Chain: `bash .opencode/hooks/chain-team-phases.sh` after receipts (no `hooks.json`).
 
 ```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
+npx @bonesofspring/ai-rules init opencode --preset next
+node scripts/generate-opencode.mjs --stack next
 ```
+
+Consumer guide: [`docs/OPENCODE.md`](../../docs/OPENCODE.md). Floor: [`docs/OPENCODE-COMPATIBILITY.md`](../../docs/OPENCODE-COMPATIBILITY.md). Gates: `check-opencode-platform-contract.mjs`, `check-opencode-adapter-map.mjs`.

package/presets/opencode/android-kotlin/MCP.md

@@ -0,0 +1,35 @@
+# MCP (preset `android-kotlin`, OpenCode)
+
+Merged into project `opencode.json` `mcp` on `ai-rules init opencode --preset android-kotlin`.
+
+## Servers
+
+| Name | Package | Purpose |
+|------|---------|---------|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Kotlin / Jetpack Compose / Android SDK docs |
+| `figma` | remote `https://mcp.figma.com/mcp` | Design context → Jetpack Compose; OAuth in OpenCode (operator MCP config) |
+
+Playwright / Chrome DevTools are **not** part of the **android-kotlin preset** (browser e2e is forbidden for the agent team).
+
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token).
+
+
+## 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 |
+
+Do **not** require Storybook, Playwright, or Chrome DevTools MCP as delivery gates on this preset.