@bonesofspring/ai-rules 0.2.22 → 0.2.24

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## 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/**`.
+- Source: `presets/mavis/next/` derived from `presets/cursor/next` (`adapter-map.json`, `generate-mavis-next.mjs`). `platform-contract.json` `releasedStacks: ["next"]`; nine other stacks deferred (WP-F).
+- Semi-auto orchestration: `chain-team-phases.sh` on `.mavis/team`; no shipped `hooks.json`. Human gates via `task-continue` → hook `end_human_gate`. Agents upsert `artifact-manifest.json` only — hook owns `status.json` / `metrics.json`.
+- Docs: [`docs/MAVIS.md`](docs/MAVIS.md) (consumer), [`docs/MAVIS-COMPATIBILITY.md`](docs/MAVIS-COMPATIBILITY.md) (probe evidence). Gates: `check-mavis-*`, `test-mavis-*` wired into `check:preset-structure`.
+- Consumers: re-run `npx @bonesofspring/ai-rules init mavis --preset next` after publish. Cursor/Claude installs unchanged.
+
 ### Chain-team-phases hook coverage + pipeline race fixes
 
 - `chain-team-phases.sh` (all 20 stack × platform hooks) now covers every agent that ships in its stack's `agents/` directory:

package/README.md

@@ -1,6 +1,6 @@
 # @bonesofspring/ai-rules
 
-Presets for Cursor and Claude Code: rules, commands, plus optional `agents`, `hooks`, `skills`, team artifacts, and MCP configs when the preset includes them. For Claude: `CLAUDE.md`. Install from npm into a project so you don’t have to copy files out of the repo by hand.
+Presets for Cursor, Claude Code, **Mavis / MiniMax Code (experimental Next-only)**, and **OpenCode (experimental Next-only)**:
 
 Node 18+.
 
@@ -8,7 +8,11 @@ Node 18+.
 # from the project root
 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 ...`.
@@ -54,6 +58,10 @@ Where things go on `init`:
 | **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
 | **docs/specs seed** | When `<cwd>/docs/specs/` is **absent**, copy INDEX stub + `_templates/*` from `presets/_shared/assets/docs-specs/` (never overwrite existing INDEX) | same |
 
+**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/`)
@@ -121,6 +129,6 @@ Presets are developed in this monorepo under `presets/`. If you add or change ru
 - **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh). Published npm `files` include `scripts/` so consumers can run `check-product-specs.sh` from the package.
 - **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage, shared-core drift (`AI_RULES_DRIFT_FAIL=1`)
 - **Opt-in rule eval:** `yarn check:rule-eval` + `.github/workflows/rule-eval.yml` (`workflow_dispatch` + paths-scoped PR) — **not** wired into `check:preset-structure`
-- **CLI note:** `_shared` is not an installable `--preset`; `init` copies only `presets/cursor/<name>/` or `presets/claude/<name>/`
+- **CLI note:** `_shared` is not an installable `--preset`; `init` copies `presets/cursor/<name>/`, `presets/claude/<name>/`, or `presets/mavis/<name>/` when the stack is in `releasedStacks`
 
 MIT.

package/bin/cli.js

@@ -4,11 +4,13 @@
  */
 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']);
+const TOOLS = new Set(['cursor', 'claude', 'mavis', 'opencode']);
 
 const PRESETS = {
   cursor: {
@@ -51,9 +53,9 @@ function printHelp() {
   console.log(`@bonesofspring/ai-rules
 
 Usage:
-  ai-rules init <cursor|claude> [--preset <name>]
-  ai-rules init <cursor|claude> <preset-name>
-  ai-rules clean <cursor|claude> [--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})
@@ -66,7 +68,9 @@ Notes:
   copied to a timestamped *.bak.* then replaced with the preset file. JSONC is not supported).
   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).
-  Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
+  Mavis init copies into .mavis/ (ai-rules-owned) plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into .mavis/mcp.json only (never ~/.minimax/**).
+  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".
@@ -93,6 +97,10 @@ Examples:
   npx @bonesofspring/ai-rules init claude --preset mcp-ts
   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
 `);
 }
@@ -484,9 +492,34 @@ function resolvePresetName(tool, preset, packageRoot) {
 }
 
 function cmdInit(tool, preset, cwdOption) {
+  if (tool === 'mavis') {
+    cmdInitMavis({
+      preset,
+      cwdOption,
+      helpers: {
+        resolveTargetCwd,
+        seedDocsSpecsIfAbsent,
+        installMcpJson,
+        getPackageRoot,
+      },
+    });
+    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 or claude.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, mavis, or opencode.`);
     process.exit(1);
   }
 
@@ -665,9 +698,23 @@ function rollbackInit(createdPaths, toolRootExisted, toolRootAbs) {
 }
 
 function cmdClean(tool, cwdOption) {
+  if (tool === 'mavis') {
+    cmdCleanMavis({
+      cwdOption,
+      helpers: { resolveTargetCwd },
+    });
+    return;
+  }
+  if (tool === 'opencode') {
+    cmdCleanOpencode({
+      cwdOption,
+      helpers: { resolveTargetCwd },
+    });
+    return;
+  }
   const cfg = PRESETS[tool];
   if (!cfg) {
-    console.error(`Unknown tool: ${tool}. Use cursor or claude.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, mavis, or opencode.`);
     process.exit(1);
   }
   const cwd = resolveTargetCwd(cwdOption);
@@ -737,7 +784,7 @@ function main() {
 
   if (command === 'init') {
     if (!tool || !TOOLS.has(tool)) {
-      console.error('Missing or invalid tool. Use: init cursor|claude [--preset next]');
+      console.error('Missing or invalid tool. Use: init cursor|claude|mavis|opencode [--preset next]');
       process.exit(1);
     }
     cmdInit(tool, preset, parsed.cwd);
@@ -745,7 +792,7 @@ function main() {
   }
   if (command === 'clean') {
     if (!tool || !TOOLS.has(tool)) {
-      console.error('Missing or invalid tool. Use: clean cursor|claude');
+      console.error('Missing or invalid tool. Use: clean cursor|claude|mavis|opencode');
       process.exit(1);
     }
     cmdClean(tool, parsed.cwd);

package/bin/mavis-install.js

@@ -0,0 +1,441 @@
+/**
+ * Manifest-owned Mavis init/clean. Does not write ~/.minimax/**.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_REL = path.join('.mavis', '.ai-rules-install.json');
+const CONTRACT_REL = path.join('presets', 'mavis', '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_MAVIS_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(`Mavis platform contract missing: ${contractPath}`);
+  }
+  return loadJson(contractPath);
+}
+
+function packageVersion(packageRoot) {
+  return loadJson(path.join(packageRoot, 'package.json')).version;
+}
+
+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.mcpServers !== 'object' || parsed.mcpServers === null) {
+    return [];
+  }
+  return Object.keys(parsed.mcpServers);
+}
+
+function previousManifest(cwd) {
+  const manifestPath = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    return loadJson(manifestPath);
+  } catch {
+    return null;
+  }
+}
+
+function restoreRollback(overwritten, created, rollbackRoot, mavisRoot, mavisExisted) {
+  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 (!mavisExisted && fs.existsSync(mavisRoot)) {
+    fs.rmSync(mavisRoot, { recursive: true, force: true });
+  } else if (mavisExisted && fs.existsSync(mavisRoot)) {
+    removeEmptyDirs(mavisRoot);
+  }
+}
+
+function cmdInitMavis({ preset, cwdOption, helpers }) {
+  const { resolveTargetCwd, seedDocsSpecsIfAbsent, installMcpJson, 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 mavis is not released yet.`);
+    console.error(`Released stacks: ${releasedStacks.join(', ')}`);
+    console.error('Additional stacks ship after the pilot human gate (WP-F).');
+    process.exit(1);
+  }
+  const sourceBase = path.join(packageRoot, contract.sourceRoot, stack);
+  if (!fs.existsSync(sourceBase)) {
+    console.error(`Preset "${stack}" for mavis not found.`);
+    console.error(`Looked in: ${sourceBase}`);
+    process.exit(1);
+  }
+
+  const mavisRoot = path.join(cwd, contract.managedRoot);
+  const mavisExisted = fs.existsSync(mavisRoot);
+  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(mavisRoot, '.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);
+      }
+      installMcpJson(plan.mcp.source, plan.mcp.dest, plan.mcp.rel);
+      console.log(
+        'MCP fallback staged at .mavis/mcp.json. Import it in MiniMax Code MCP JSON mode; do not write ~/.minimax/mcp.json from this CLI.',
+      );
+    }
+
+    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: 'mavis',
+      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(mavisRoot, '.rollback');
+    if (fs.existsSync(rollbackParent) && fs.readdirSync(rollbackParent).length === 0) {
+      fs.rmdirSync(rollbackParent);
+    }
+  } catch (error) {
+    restoreRollback(overwritten, created, rollbackRoot, mavisRoot, mavisExisted);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`init failed: ${message}`);
+    process.exit(1);
+  }
+
+  console.log(`Done. .mavis installed at ${mavisRoot} (preset: ${stack})`);
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+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.mcpServers)) {
+    return;
+  }
+  const nextServers = { ...parsed.mcpServers };
+  for (const id of shippedIds) {
+    delete nextServers[id];
+  }
+  writeAtomicText(mcpAbs, `${JSON.stringify({ ...parsed, mcpServers: 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 cmdCleanMavis({ cwdOption, helpers }) {
+  const { resolveTargetCwd } = helpers;
+  const cwd = resolveTargetCwd(cwdOption);
+  const manifestPath = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(manifestPath)) {
+    console.error(
+      'clean mavis: missing .mavis/.ai-rules-install.json; nothing removed (fail-safe).',
+    );
+    process.exit(1);
+  }
+  let manifest;
+  try {
+    manifest = loadJson(manifestPath);
+  } catch {
+    console.error(
+      'clean mavis: invalid .mavis/.ai-rules-install.json; nothing removed (fail-safe).',
+    );
+    process.exit(1);
+  }
+  if (!manifest || manifest.platform !== 'mavis' || !isPlainObject(manifest.managedFiles)) {
+    console.error(
+      'clean mavis: install manifest is not a Mavis 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('.mavis/mcp.json') && Array.isArray(manifest.shippedMcpServerIds)) {
+    stripShippedMcp(path.join(cwd, '.mavis', 'mcp.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, '.mavis'));
+  if (fs.existsSync(path.join(cwd, '.mavis')) && fs.readdirSync(path.join(cwd, '.mavis')).length === 0) {
+    fs.rmdirSync(path.join(cwd, '.mavis'));
+  }
+
+  console.log(
+    preserved.length > 0
+      ? `clean mavis: removed unchanged managed files; preserved ${preserved.join(', ')}`
+      : 'clean mavis: removed unchanged managed files',
+  );
+}
+
+module.exports = { cmdInitMavis, cmdCleanMavis, MANIFEST_REL };