@bonesofspring/ai-rules 0.2.23 → 0.2.24

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+### OpenCode platform (experimental Next-only)
+
+- New platform **`opencode`**: `npx @bonesofspring/ai-rules init opencode --preset next` installs **`.opencode/**`** plus root `AGENTS.md` and merges MCP into **`opencode.json`**. `clean opencode` is manifest/hash-safe. The CLI never writes `~/.config/opencode/**`.
+- Source: `presets/opencode/next/` derived from `presets/cursor/next` (`adapter-map.json`, `generate-opencode-next.mjs`). `platform-contract.json` `releasedStacks: ["next"]`; nine other stacks deferred.
+- Native OpenCode discovery for agents, skills, and slash commands. Rules under `.opencode/rules/` are lazy-loaded from `AGENTS.md` (no `alwaysApply`/`globs` engine). Pipeline hook is manual `chain-team-phases.sh` (no `hooks.json` plugin in v1).
+- Docs: [`docs/OPENCODE.md`](docs/OPENCODE.md) (consumer), [`docs/OPENCODE-COMPATIBILITY.md`](docs/OPENCODE-COMPATIBILITY.md) (docs-floor evidence). Gates: `check-opencode-*`, `test-opencode-context-budget` wired into `check:preset-structure`.
+- Review follow-up: team-agent write-scope lead-in is role-specific; consumer `OPENCODE.md` no longer uses broken relative doc links; orchestrator uses OpenCode `mode`/`permission` wording; `build-verifier` preset-structure lists OpenCode/Mavis derive gates; Cursor/Claude `REPO_AGENTS.md` keep OpenCode/Mavis pointers so mixed-tool `init` does not drop them.
+- Consumers: re-run `npx @bonesofspring/ai-rules init opencode --preset next` after publish. Cursor/Claude/Mavis installs unchanged.
+
 ### Mavis platform (MiniMax Code, experimental Next-only)
 
 - New platform **`mavis`** (`mcode` runtime): `npx @bonesofspring/ai-rules init mavis --preset next` installs **`.mavis/**`** plus root `AGENTS.md`. `clean mavis` is manifest/hash-safe. MCP merges to **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`.

package/README.md

@@ -1,6 +1,6 @@
 # @bonesofspring/ai-rules
 
-Presets for Cursor, Claude Code, and **Mavis / MiniMax Code (experimental Next-only)**:
+Presets for Cursor, Claude Code, **Mavis / MiniMax Code (experimental Next-only)**, and **OpenCode (experimental Next-only)**:
 
 Node 18+.
 
@@ -9,8 +9,10 @@ Node 18+.
 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
 npx @bonesofspring/ai-rules clean cursor
 npx @bonesofspring/ai-rules clean mavis
+npx @bonesofspring/ai-rules clean opencode
 ```
 
 Global: `npm i -g @bonesofspring/ai-rules`, then `ai-rules ...`.
@@ -58,6 +60,8 @@ Where things go on `init`:
 
 **Mavis (MiniMax Code, experimental Next-only):** `ai-rules init mavis --preset next` writes ai-rules-owned **`.mavis/**`** plus root `AGENTS.md`. MCP merges into **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`. `clean mavis` is manifest-owned: unchanged hashes are removed; modified files stay. See [`docs/MAVIS.md`](docs/MAVIS.md), [`presets/mavis/README.md`](presets/mavis/README.md), and [`docs/MAVIS-COMPATIBILITY.md`](docs/MAVIS-COMPATIBILITY.md).
 
+**OpenCode (experimental Next-only):** `ai-rules init opencode --preset next` writes native **`.opencode/**`** plus root `AGENTS.md` and merges MCP into **`opencode.json`**. `clean opencode` is manifest-owned. The CLI never writes `~/.config/opencode/**`. Last `init` wins on root `AGENTS.md` if several tools are installed. See [`docs/OPENCODE.md`](docs/OPENCODE.md), [`presets/opencode/README.md`](presets/opencode/README.md), and [`docs/OPENCODE-COMPATIBILITY.md`](docs/OPENCODE-COMPATIBILITY.md).
+
 Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `mockup-review` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — Figma mockup reviewer via agent `mockup-reviewer`); `ux-design` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — behavioral UX via `task-analyst`, no agent); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
 
 ## Product specs (`docs/specs/`)

package/bin/cli.js

@@ -5,11 +5,12 @@
 const fs = require('fs');
 const path = require('path');
 const { cmdInitMavis, cmdCleanMavis } = require('./mavis-install');
+const { cmdInitOpencode, cmdCleanOpencode } = require('./opencode-install');
 
 /** Single path segment: letters, digits, dot, underscore, hyphen; no separators or "..". */
 const PRESET_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const DEFAULT_PRESET = 'next';
-const TOOLS = new Set(['cursor', 'claude', 'mavis']);
+const TOOLS = new Set(['cursor', 'claude', 'mavis', 'opencode']);
 
 const PRESETS = {
   cursor: {
@@ -52,9 +53,9 @@ function printHelp() {
   console.log(`@bonesofspring/ai-rules
 
 Usage:
-  ai-rules init <cursor|claude|mavis> [--preset <name>]
-  ai-rules init <cursor|claude|mavis> <preset-name>
-  ai-rules clean <cursor|claude|mavis> [--cwd <dir>]
+  ai-rules init <cursor|claude|mavis|opencode> [--preset <name>]
+  ai-rules init <cursor|claude|mavis|opencode> <preset-name>
+  ai-rules clean <cursor|claude|mavis|opencode> [--cwd <dir>]
 
 Options:
   --preset <name>   Preset name (default: ${DEFAULT_PRESET})
@@ -68,7 +69,8 @@ Notes:
   Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
   Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
   Mavis init copies into .mavis/ (ai-rules-owned) plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into .mavis/mcp.json only (never ~/.minimax/**).
-  Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
+  OpenCode init copies into .opencode/ plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into <cwd>/opencode.json (never ~/.config/opencode/**).
+  All init targets also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
   When <cwd>/docs/specs/ is absent, init also seeds INDEX.md stub + _templates/* from package assets (never overwrites an existing INDEX).
   clean removes tool dirs/files and <cwd>/AGENTS.md (shared across tools — re-init the other tool to restore).
   Command forms: "init cursor --preset next", "init cursor next", "--preset next init cursor", "cursor init --preset next".
@@ -96,7 +98,9 @@ Examples:
   npx @bonesofspring/ai-rules init claude --preset php-hexagonal
   npx @bonesofspring/ai-rules init claude --preset php-laravel
   npx @bonesofspring/ai-rules init mavis --preset next
+  npx @bonesofspring/ai-rules init opencode --preset next
   npx @bonesofspring/ai-rules clean mavis
+  npx @bonesofspring/ai-rules clean opencode
   npx @bonesofspring/ai-rules clean cursor
 `);
 }
@@ -501,9 +505,21 @@ function cmdInit(tool, preset, cwdOption) {
     });
     return;
   }
+  if (tool === 'opencode') {
+    cmdInitOpencode({
+      preset,
+      cwdOption,
+      helpers: {
+        resolveTargetCwd,
+        seedDocsSpecsIfAbsent,
+        getPackageRoot,
+      },
+    });
+    return;
+  }
   const cfg = PRESETS[tool];
   if (!cfg) {
-    console.error(`Unknown tool: ${tool}. Use cursor, claude, or mavis.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, mavis, or opencode.`);
     process.exit(1);
   }
 
@@ -689,9 +705,16 @@ function cmdClean(tool, cwdOption) {
     });
     return;
   }
+  if (tool === 'opencode') {
+    cmdCleanOpencode({
+      cwdOption,
+      helpers: { resolveTargetCwd },
+    });
+    return;
+  }
   const cfg = PRESETS[tool];
   if (!cfg) {
-    console.error(`Unknown tool: ${tool}. Use cursor, claude, or mavis.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, mavis, or opencode.`);
     process.exit(1);
   }
   const cwd = resolveTargetCwd(cwdOption);
@@ -761,7 +784,7 @@ function main() {
 
   if (command === 'init') {
     if (!tool || !TOOLS.has(tool)) {
-      console.error('Missing or invalid tool. Use: init cursor|claude|mavis [--preset next]');
+      console.error('Missing or invalid tool. Use: init cursor|claude|mavis|opencode [--preset next]');
       process.exit(1);
     }
     cmdInit(tool, preset, parsed.cwd);
@@ -769,7 +792,7 @@ function main() {
   }
   if (command === 'clean') {
     if (!tool || !TOOLS.has(tool)) {
-      console.error('Missing or invalid tool. Use: clean cursor|claude|mavis');
+      console.error('Missing or invalid tool. Use: clean cursor|claude|mavis|opencode');
       process.exit(1);
     }
     cmdClean(tool, parsed.cwd);

package/bin/opencode-install.js

@@ -0,0 +1,531 @@
+/**
+ * Manifest-owned OpenCode init/clean. Does not write ~/.config/opencode/**.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_REL = path.join('.opencode', '.ai-rules-install.json');
+const CONTRACT_REL = path.join('presets', 'opencode', 'platform-contract.json');
+const SKIP_STACK_ROOT = new Set(['adapter-map.json', 'README.md']);
+
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function failPhase() {
+  return process.env.AI_RULES_OPENCODE_FAIL_PHASE || '';
+}
+
+function throwIfPhase(name) {
+  if (failPhase() === name) {
+    throw new Error(`injected failure at ${name}`);
+  }
+}
+
+function loadJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function walkFiles(root) {
+  const files = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(full);
+      } else if (entry.isFile()) {
+        files.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  if (fs.existsSync(root)) {
+    visit(root);
+  }
+  return files.sort();
+}
+
+function writeAtomicCopy(source, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.ai-rules-tmp`;
+  fs.copyFileSync(source, tmp);
+  if (dest.endsWith('.sh')) {
+    fs.chmodSync(tmp, 0o755);
+  }
+  fs.renameSync(tmp, dest);
+}
+
+function writeAtomicText(dest, text) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.ai-rules-tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, dest);
+}
+
+function loadContract(packageRoot) {
+  const contractPath = path.join(packageRoot, CONTRACT_REL);
+  if (!fs.existsSync(contractPath)) {
+    throw new Error(`OpenCode platform contract missing: ${contractPath}`);
+  }
+  return loadJson(contractPath);
+}
+
+function packageVersion(packageRoot) {
+  return loadJson(path.join(packageRoot, 'package.json')).version;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function ownKeys(object) {
+  return Object.keys(object).filter((key) => Object.hasOwn(object, key));
+}
+
+function buildPlan({ contract, sourceBase, cwd }) {
+  const files = [];
+  const seen = new Set();
+  const addFile = (source, destRel) => {
+    if (seen.has(destRel)) {
+      return;
+    }
+    seen.add(destRel);
+    files.push({
+      source,
+      dest: path.join(cwd, destRel),
+      rel: destRel,
+    });
+  };
+
+  for (const entry of contract.entryFiles || []) {
+    const source = path.join(sourceBase, entry.source);
+    if (fs.existsSync(source)) {
+      addFile(source, entry.destination);
+    }
+  }
+
+  for (const mapping of contract.directoryMappings || []) {
+    const sourceDir = path.join(sourceBase, mapping.source);
+    if (!fs.existsSync(sourceDir)) {
+      continue;
+    }
+    for (const rel of walkFiles(sourceDir)) {
+      addFile(path.join(sourceDir, rel), `${mapping.destination}/${rel}`);
+    }
+  }
+
+  const mcpMd = path.join(sourceBase, 'MCP.md');
+  if (fs.existsSync(mcpMd)) {
+    addFile(mcpMd, path.join(contract.managedRoot, 'MCP.md'));
+  }
+
+  const mcpSource = path.join(sourceBase, contract.mcp.source);
+  const mcp = fs.existsSync(mcpSource)
+    ? {
+        source: mcpSource,
+        dest: path.join(cwd, contract.mcp.fallbackDestination),
+        rel: contract.mcp.fallbackDestination,
+      }
+    : null;
+
+  for (const skip of SKIP_STACK_ROOT) {
+    const skipped = path.join(sourceBase, skip);
+    if (fs.existsSync(skipped)) {
+      const accidental = files.find((item) => item.source === skipped);
+      if (accidental) {
+        throw new Error(`refusing to install stack-root ${skip}`);
+      }
+    }
+  }
+
+  return { files, mcp };
+}
+
+function capabilityModes(contract) {
+  const modes = {};
+  for (const [key, value] of Object.entries(contract.nativeCapabilities || {})) {
+    modes[key] = value.status;
+  }
+  return modes;
+}
+
+function shippedMcpIds(mcpSource) {
+  if (!mcpSource || !fs.existsSync(mcpSource)) {
+    return [];
+  }
+  const parsed = loadJson(mcpSource);
+  if (!parsed || typeof parsed.mcp !== 'object' || parsed.mcp === null) {
+    return [];
+  }
+  return Object.keys(parsed.mcp);
+}
+
+function previousManifest(cwd) {
+  const manifestPath = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    return loadJson(manifestPath);
+  } catch {
+    return null;
+  }
+}
+
+function mergeServerEntry(existingEntry, presetEntry) {
+  if (!isPlainObject(existingEntry) || !isPlainObject(presetEntry)) {
+    return presetEntry;
+  }
+  const merged = { ...existingEntry, ...presetEntry };
+  for (const nested of ['env', 'headers', 'environment']) {
+    const existingNested = existingEntry[nested];
+    const presetNested = presetEntry[nested];
+    if (isPlainObject(existingNested) && isPlainObject(presetNested)) {
+      merged[nested] = { ...existingNested, ...presetNested };
+    } else if (isPlainObject(existingNested) && presetNested === undefined) {
+      merged[nested] = existingNested;
+    }
+  }
+  return merged;
+}
+
+function mergeOpencodeConfig(presetObj, existingObj) {
+  const preset = isPlainObject(presetObj) ? presetObj : {};
+  const existing = isPlainObject(existingObj) ? existingObj : {};
+  const existingServersInvalid = Object.hasOwn(existing, 'mcp') && !isPlainObject(existing.mcp);
+  const presetMcp = isPlainObject(preset.mcp) ? preset.mcp : {};
+  const existingMcp =
+    !existingServersInvalid && isPlainObject(existing.mcp) ? existing.mcp : {};
+  const extrasKept = ownKeys(existingMcp).filter((key) => !Object.hasOwn(presetMcp, key));
+  const mergedMcp = { ...existingMcp };
+  for (const key of ownKeys(presetMcp)) {
+    mergedMcp[key] = mergeServerEntry(existingMcp[key], presetMcp[key]);
+  }
+  const merged = { ...existing };
+  if (!merged.$schema && preset.$schema) {
+    merged.$schema = preset.$schema;
+  }
+  merged.mcp = mergedMcp;
+  return { merged, extrasKept, existingServersInvalid };
+}
+
+function backupFile(destAbs) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const bak = `${destAbs}.bak.${stamp}`;
+  fs.copyFileSync(destAbs, bak);
+  return bak;
+}
+
+function installOpencodeJson(mcpFrom, mcpDestAbs, destLabel) {
+  const presetObj = loadJson(mcpFrom);
+  if (!fs.existsSync(mcpDestAbs)) {
+    fs.mkdirSync(path.dirname(mcpDestAbs), { recursive: true });
+    fs.copyFileSync(mcpFrom, mcpDestAbs);
+    console.log(`Copied ${path.basename(mcpFrom)} → ${destLabel}`);
+    return;
+  }
+  let existingObj;
+  try {
+    existingObj = loadJson(mcpDestAbs);
+  } catch {
+    const bak = backupFile(mcpDestAbs);
+    fs.copyFileSync(mcpFrom, mcpDestAbs);
+    console.warn(`Existing ${destLabel} was not valid JSON; backed up to ${bak} and replaced.`);
+    return;
+  }
+  if (!isPlainObject(existingObj)) {
+    const bak = backupFile(mcpDestAbs);
+    fs.copyFileSync(mcpFrom, mcpDestAbs);
+    console.warn(`Existing ${destLabel} was not a JSON object; backed up to ${bak} and replaced.`);
+    return;
+  }
+  const { merged, extrasKept, existingServersInvalid } = mergeOpencodeConfig(
+    presetObj,
+    existingObj,
+  );
+  if (existingServersInvalid) {
+    const bak = backupFile(mcpDestAbs);
+    console.warn(
+      `Existing ${destLabel} mcp was not a JSON object; backed up to ${bak} and merging as empty extras.`,
+    );
+  }
+  writeAtomicText(mcpDestAbs, `${JSON.stringify(merged, null, 2)}\n`);
+  if (extrasKept.length > 0) {
+    console.log(
+      `Merged ${path.basename(mcpFrom)} → ${destLabel} (kept extra servers: ${extrasKept.join(', ')})`,
+    );
+  } else {
+    console.log(`Merged ${path.basename(mcpFrom)} → ${destLabel}`);
+  }
+}
+
+function restoreRollback(overwritten, created, rollbackRoot, managedRoot, rootExisted) {
+  for (const item of overwritten) {
+    try {
+      if (fs.existsSync(item.backup)) {
+        fs.mkdirSync(path.dirname(item.dest), { recursive: true });
+        fs.copyFileSync(item.backup, item.dest);
+      }
+    } catch {
+      // Best-effort restore; caller already reports the failure.
+    }
+  }
+  const createdPaths = [...created].sort((a, b) => b.length - a.length);
+  for (const dest of createdPaths) {
+    try {
+      if (!fs.existsSync(dest)) {
+        continue;
+      }
+      const stat = fs.lstatSync(dest);
+      if (stat.isDirectory()) {
+        fs.rmSync(dest, { recursive: true, force: true });
+      } else {
+        fs.unlinkSync(dest);
+      }
+    } catch {
+      // Best-effort.
+    }
+  }
+  if (fs.existsSync(rollbackRoot)) {
+    fs.rmSync(rollbackRoot, { recursive: true, force: true });
+  }
+  if (!rootExisted && fs.existsSync(managedRoot)) {
+    fs.rmSync(managedRoot, { recursive: true, force: true });
+  } else if (rootExisted && fs.existsSync(managedRoot)) {
+    removeEmptyDirs(managedRoot);
+  }
+}
+
+function cmdInitOpencode({ preset, cwdOption, helpers }) {
+  const { resolveTargetCwd, seedDocsSpecsIfAbsent, getPackageRoot } = helpers;
+  const packageRoot = getPackageRoot();
+  const cwd = resolveTargetCwd(cwdOption);
+  const contract = loadContract(packageRoot);
+  const stack = preset || 'next';
+  const releasedStacks = Array.isArray(contract.releasedStacks) ? contract.releasedStacks : [];
+  if (releasedStacks.length > 0 && !releasedStacks.includes(stack)) {
+    console.error(`Preset "${stack}" for opencode is not released yet.`);
+    console.error(`Released stacks: ${releasedStacks.join(', ')}`);
+    process.exit(1);
+  }
+  const sourceBase = path.join(packageRoot, contract.sourceRoot, stack);
+  if (!fs.existsSync(sourceBase)) {
+    console.error(`Preset "${stack}" for opencode not found.`);
+    console.error(`Looked in: ${sourceBase}`);
+    process.exit(1);
+  }
+
+  const managedRoot = path.join(cwd, contract.managedRoot);
+  const rootExisted = fs.existsSync(managedRoot);
+  const docsSpecsDir = path.join(cwd, 'docs', 'specs');
+  const docsSpecsExisted = fs.existsSync(docsSpecsDir);
+  const prior = previousManifest(cwd);
+  const runId = new Date().toISOString().replace(/[:.]/g, '-');
+  const rollbackRoot = path.join(managedRoot, '.rollback', runId);
+  const created = new Set();
+  const overwritten = [];
+
+  try {
+    throwIfPhase('validate');
+    const plan = buildPlan({ contract, sourceBase, cwd });
+    for (const item of plan.files) {
+      if (!fs.existsSync(item.source)) {
+        throw new Error(`Source missing: ${item.source}`);
+      }
+    }
+
+    throwIfPhase('snapshot');
+    for (const item of plan.files) {
+      if (!fs.existsSync(item.dest)) {
+        continue;
+      }
+      const backup = path.join(rollbackRoot, item.rel);
+      fs.mkdirSync(path.dirname(backup), { recursive: true });
+      fs.copyFileSync(item.dest, backup);
+      overwritten.push({ dest: item.dest, backup });
+      const priorHash = prior && prior.managedFiles ? prior.managedFiles[item.rel] : null;
+      const currentHash = sha256File(item.dest);
+      if (priorHash && priorHash !== currentHash) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const reported = `${item.dest}.bak.${stamp}`;
+        fs.copyFileSync(item.dest, reported);
+        console.warn(`Modified managed file ${item.rel} backed up to ${reported} before overwrite.`);
+      }
+    }
+    if (plan.mcp && fs.existsSync(plan.mcp.dest)) {
+      const backup = path.join(rollbackRoot, plan.mcp.rel);
+      fs.mkdirSync(path.dirname(backup), { recursive: true });
+      fs.copyFileSync(plan.mcp.dest, backup);
+      overwritten.push({ dest: plan.mcp.dest, backup });
+    }
+
+    throwIfPhase('write');
+    for (const item of plan.files) {
+      if (!fs.existsSync(item.dest)) {
+        created.add(item.dest);
+      }
+      writeAtomicCopy(item.source, item.dest);
+      console.log(`Copied ${path.basename(item.source)} → ${item.rel}`);
+    }
+
+    throwIfPhase('mcp');
+    if (plan.mcp) {
+      if (!fs.existsSync(plan.mcp.dest)) {
+        created.add(plan.mcp.dest);
+      }
+      installOpencodeJson(plan.mcp.source, plan.mcp.dest, plan.mcp.rel);
+    }
+
+    throwIfPhase('docs');
+    const seeded = seedDocsSpecsIfAbsent(packageRoot, cwd);
+    if (seeded && !docsSpecsExisted) {
+      created.add(docsSpecsDir);
+    }
+
+    throwIfPhase('manifest');
+    const managedFiles = {};
+    for (const item of plan.files) {
+      managedFiles[item.rel] = sha256File(item.dest);
+    }
+    if (plan.mcp && fs.existsSync(plan.mcp.dest)) {
+      managedFiles[plan.mcp.rel] = sha256File(plan.mcp.dest);
+    }
+    const manifest = {
+      schemaVersion: 1,
+      packageVersion: packageVersion(packageRoot),
+      platform: 'opencode',
+      preset: stack,
+      installedAt: new Date().toISOString(),
+      managedFiles,
+      managedDirectories: (contract.directoryMappings || []).map((entry) => entry.destination),
+      shippedMcpServerIds: plan.mcp ? shippedMcpIds(plan.mcp.source) : [],
+      docsSeed: seeded
+        ? { seeded: true }
+        : { seeded: false, reason: docsSpecsExisted ? 'directory-exists' : 'assets-missing' },
+      capabilityModes: capabilityModes(contract),
+    };
+    const manifestAbs = path.join(cwd, MANIFEST_REL);
+    if (!fs.existsSync(manifestAbs)) {
+      created.add(manifestAbs);
+    }
+    writeAtomicText(manifestAbs, `${JSON.stringify(manifest, null, 2)}\n`);
+
+    if (fs.existsSync(rollbackRoot)) {
+      fs.rmSync(rollbackRoot, { recursive: true, force: true });
+    }
+    const rollbackParent = path.join(managedRoot, '.rollback');
+    if (fs.existsSync(rollbackParent) && fs.readdirSync(rollbackParent).length === 0) {
+      fs.rmdirSync(rollbackParent);
+    }
+  } catch (error) {
+    restoreRollback(overwritten, created, rollbackRoot, managedRoot, rootExisted);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`init failed: ${message}`);
+    process.exit(1);
+  }
+
+  console.log(`Done. .opencode installed at ${managedRoot} (preset: ${stack})`);
+}
+
+function stripShippedMcp(mcpAbs, shippedIds) {
+  if (!fs.existsSync(mcpAbs) || shippedIds.length === 0) {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = loadJson(mcpAbs);
+  } catch {
+    console.warn(`Preserved ${mcpAbs} (not valid JSON); shipped MCP keys not stripped.`);
+    return;
+  }
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.mcp)) {
+    return;
+  }
+  const nextServers = { ...parsed.mcp };
+  for (const id of shippedIds) {
+    delete nextServers[id];
+  }
+  writeAtomicText(mcpAbs, `${JSON.stringify({ ...parsed, mcp: nextServers }, null, 2)}\n`);
+}
+
+function removeEmptyDirs(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return;
+  }
+  for (const name of fs.readdirSync(dir)) {
+    removeEmptyDirs(path.join(dir, name));
+  }
+  if (fs.readdirSync(dir).length === 0) {
+    fs.rmdirSync(dir);
+  }
+}
+
+function cmdCleanOpencode({ cwdOption, helpers }) {
+  const { resolveTargetCwd } = helpers;
+  const cwd = resolveTargetCwd(cwdOption);
+  const manifestPath = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(manifestPath)) {
+    console.error(
+      'clean opencode: missing .opencode/.ai-rules-install.json; nothing removed (fail-safe).',
+    );
+    process.exit(1);
+  }
+  let manifest;
+  try {
+    manifest = loadJson(manifestPath);
+  } catch {
+    console.error(
+      'clean opencode: invalid .opencode/.ai-rules-install.json; nothing removed (fail-safe).',
+    );
+    process.exit(1);
+  }
+  if (!manifest || manifest.platform !== 'opencode' || !isPlainObject(manifest.managedFiles)) {
+    console.error(
+      'clean opencode: install manifest is not an OpenCode ownership record; nothing removed.',
+    );
+    process.exit(1);
+  }
+
+  const preserved = [];
+  for (const [rel, installedHash] of Object.entries(manifest.managedFiles)) {
+    if (rel === MANIFEST_REL) {
+      continue;
+    }
+    const abs = path.join(cwd, rel);
+    if (!fs.existsSync(abs)) {
+      continue;
+    }
+    const current = sha256File(abs);
+    if (current === installedHash) {
+      fs.unlinkSync(abs);
+    } else {
+      preserved.push(rel);
+      console.warn(`Preserved modified managed file ${rel}`);
+    }
+  }
+
+  if (preserved.includes('opencode.json') && Array.isArray(manifest.shippedMcpServerIds)) {
+    stripShippedMcp(path.join(cwd, 'opencode.json'), manifest.shippedMcpServerIds);
+  }
+
+  for (const dirRel of [...(manifest.managedDirectories || [])].sort((a, b) => b.length - a.length)) {
+    removeEmptyDirs(path.join(cwd, dirRel));
+  }
+
+  fs.unlinkSync(manifestPath);
+  removeEmptyDirs(path.join(cwd, '.opencode'));
+  if (
+    fs.existsSync(path.join(cwd, '.opencode')) &&
+    fs.readdirSync(path.join(cwd, '.opencode')).length === 0
+  ) {
+    fs.rmdirSync(path.join(cwd, '.opencode'));
+  }
+
+  console.log(
+    preserved.length > 0
+      ? `clean opencode: removed unchanged managed files; preserved ${preserved.join(', ')}`
+      : 'clean opencode: removed unchanged managed files',
+  );
+}
+
+module.exports = { cmdInitOpencode, cmdCleanOpencode, MANIFEST_REL };