@ionivetech/mugiwara 0.5.3 → 0.5.5

package/dist/mugiwara.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { existsSync as existsSync6, realpathSync, rmSync as rmSync3 } from "node:fs";
+import { existsSync as existsSync7, readdirSync as readdirSync3, rmSync as rmSync3 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { join as join8, resolve } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // src/args.ts
 var VALUE_FLAGS = { "--project": "project", "--target": "target" };
@@ -15,6 +15,7 @@ var BOOL_FLAGS = {
   "--force": "force",
   "--dry-run": "dryRun",
   "--keep-logs": "keepLogs",
+  "--check": "check",
   "--help": "help",
   "-h": "help",
   "--version": "version",
@@ -93,10 +94,10 @@ function parseFrontmatter(text) {
   for (const line of m[1].split(/\r?\n/)) {
     if (!line.trim())
       continue;
-    const i = line.indexOf(":");
+    const i = line.indexOf(": ");
     if (i === -1)
-      throw new Error(`Bad frontmatter line: ${line}`);
-    data[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+      throw new Error(`Bad frontmatter line (missing ': ' separator): ${line}`);
+    data[line.slice(0, i).trim()] = line.slice(i + 2).trim();
   }
   return { data, body: text.slice(m[0].length) };
 }
@@ -151,7 +152,11 @@ var target = {
 };
 
 // src/targets/opencode.ts
-import { join as join2 } from "node:path";
+import { existsSync as existsSync2, readdirSync, copyFileSync as copyFileSync2, mkdirSync as mkdirSync2 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var here2 = dirname2(fileURLToPath2(import.meta.url));
+var COMMANDS_SRC = join2(here2, "..", "..", ".opencode", "commands");
 var CREW = {
   "luffy-orchestrator": { color: "#ef4444", temperature: 0.2, steps: 15 },
   "usopp-brainstorm": { color: "#f59e0b", temperature: 0.6, steps: 15 },
@@ -206,6 +211,25 @@ ${body}` };
   refsDir({ scope, projectDir, home }, skillName) {
     const root = scope === "global" ? join2(home, ".config", "opencode") : join2(projectDir, ".opencode");
     return join2(root, "skills", skillName, "references");
+  },
+  postInstall({ scope, projectDir, home, dryRun }) {
+    const root = scope === "global" ? join2(home, ".config", "opencode") : join2(projectDir, ".opencode");
+    const dstDir = join2(root, "commands");
+    if (dryRun)
+      return { written: [], notes: [] };
+    if (!existsSync2(COMMANDS_SRC))
+      return { written: [], notes: [] };
+    mkdirSync2(dstDir, { recursive: true });
+    const written = [];
+    for (const f of readdirSync(COMMANDS_SRC)) {
+      if (!f.endsWith(".md"))
+        continue;
+      const src = join2(COMMANDS_SRC, f);
+      const dst = join2(dstDir, f);
+      copyFileSync2(src, dst);
+      written.push(dst);
+    }
+    return { written, notes: [] };
   }
 };
 
@@ -237,7 +261,7 @@ var target3 = {
 };
 
 // src/targets/generic.ts
-import { existsSync as existsSync2, writeFileSync } from "node:fs";
+import { existsSync as existsSync3, writeFileSync } from "node:fs";
 import { join as join4 } from "node:path";
 function makeGeneric(opts) {
   const { id, label, rulesDir, bootstrapFile, bootstrapPointer, tier = bootstrapPointer ? 2 : 3 } = opts;
@@ -320,7 +344,7 @@ ${body}` };
       const notes = [];
       const written = [];
       const file = join4(projectDir, bootstrapFile);
-      if (!existsSync2(file)) {
+      if (!existsSync3(file)) {
         if (!dryRun)
           writeFileSync(file, `${bootstrapPointer}
 `);
@@ -397,19 +421,20 @@ var targets = { claude: target, opencode: target2, copilot: target3, gemini: tar
 var TARGET_IDS = Object.keys(targets);
 
 // src/installer.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, writeFileSync as writeFileSync2, copyFileSync as copyFileSync2, rmSync } from "node:fs";
-import { dirname as dirname2, join as join5 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2, copyFileSync as copyFileSync3, rmSync } from "node:fs";
+import { dirname as dirname3, join as join5 } from "node:path";
 import { homedir } from "node:os";
-var CONTENT_DIR = join5(import.meta.dirname, "..", "content");
-var pkg = JSON.parse(readFileSync2(join5(import.meta.dirname, "..", "package.json"), "utf8"));
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+var CONTENT_DIR = join5(dirname3(fileURLToPath3(import.meta.url)), "..", "content");
+var pkg = JSON.parse(readFileSync2(join5(dirname3(fileURLToPath3(import.meta.url)), "..", "package.json"), "utf8"));
 var VERSION = pkg.version;
 function collectContent() {
-  const skillNames = readdirSync(join5(CONTENT_DIR, "skills"), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  const skillNames = readdirSync2(join5(CONTENT_DIR, "skills"), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
   const skills = skillNames.map((name) => {
     const { data, body } = parseFrontmatter(readFileSync2(join5(CONTENT_DIR, "skills", name, "SKILL.md"), "utf8"));
     return { name, data, body, refs: collectRefs(join5(CONTENT_DIR, "skills", name)) };
   });
-  const agents = readdirSync(join5(CONTENT_DIR, "agents")).filter((f) => f.endsWith(".md")).map((f) => {
+  const agents = readdirSync2(join5(CONTENT_DIR, "agents")).filter((f) => f.endsWith(".md")).map((f) => {
     const { data, body } = parseFrontmatter(readFileSync2(join5(CONTENT_DIR, "agents", f), "utf8"));
     return { name: f.replace(/\.md$/, ""), data, body, refs: [] };
   });
@@ -417,9 +442,9 @@ function collectContent() {
 }
 function collectRefs(skillDir) {
   const refsDir = join5(skillDir, "references");
-  if (!existsSync3(refsDir))
+  if (!existsSync4(refsDir))
     return [];
-  return readdirSync(refsDir, { recursive: true }).map((f) => String(f)).filter((f) => f.endsWith(".md")).map((rel) => ({ relPath: rel, text: readFileSync2(join5(refsDir, rel), "utf8") }));
+  return readdirSync2(refsDir, { recursive: true }).map((f) => String(f)).filter((f) => f.endsWith(".md")).map((rel) => ({ relPath: rel, text: readFileSync2(join5(refsDir, rel), "utf8") }));
 }
 function installTo(target10, opts) {
   const { scope, projectDir, dryRun = false, force = false } = opts;
@@ -429,7 +454,7 @@ function installTo(target10, opts) {
   const backupRoot = join5(scope === "global" ? home : projectDir, ".mugiwara");
   const result = { written: [], skipped: [], backedUp: [], notes: [] };
   const writeOne = (absPath, text) => {
-    if (existsSync3(absPath)) {
+    if (existsSync4(absPath)) {
       if (readFileSync2(absPath, "utf8") === text) {
         result.skipped.push(absPath);
         return;
@@ -440,15 +465,17 @@ function installTo(target10, opts) {
         return;
       }
       const ts = new Date().toISOString().replace(/[:.]/g, "-");
-      const backupFile = join5(backupRoot, "backup", ts, absPath.replace(/[^a-zA-Z0-9]+/g, "_"));
+      const fileName = absPath.replace(/[^a-zA-Z0-9]+/g, "_");
+      const backupDir = join5(backupRoot, "backup", `${ts}-${target10.id}`);
+      const backupFile = join5(backupDir, fileName);
       if (!dryRun) {
-        mkdirSync2(dirname2(backupFile), { recursive: true });
-        copyFileSync2(absPath, backupFile);
+        mkdirSync3(backupDir, { recursive: true });
+        copyFileSync3(absPath, backupFile);
       }
       result.backedUp.push(absPath);
     }
     if (!dryRun) {
-      mkdirSync2(dirname2(absPath), { recursive: true });
+      mkdirSync3(dirname3(absPath), { recursive: true });
       writeFileSync2(absPath, text);
     }
     result.written.push(absPath);
@@ -488,7 +515,7 @@ function installTo(target10, opts) {
 function removeInstalled(manifest, { dryRun = false } = {}) {
   const removed = [];
   for (const f of manifest.files) {
-    if (existsSync3(f)) {
+    if (existsSync4(f)) {
       if (!dryRun)
         rmSync(f);
       removed.push(f);
@@ -496,13 +523,12 @@ function removeInstalled(manifest, { dryRun = false } = {}) {
   }
   if (!dryRun) {
     for (const f of manifest.files) {
-      let d = dirname2(f);
-      while (existsSync3(d) && readdirSync(d).length === 0) {
-        rmSync(d, { recursive: true });
-        const parent = dirname2(d);
-        if (parent === d)
+      let d = dirname3(f);
+      while (existsSync4(d) && readdirSync2(d).length === 0) {
+        if (d.endsWith("/.mugiwara") || d === dirname3(d))
           break;
-        d = parent;
+        rmSync(d, { recursive: true, force: true });
+        d = dirname3(d);
       }
     }
   }
@@ -510,26 +536,26 @@ function removeInstalled(manifest, { dryRun = false } = {}) {
 }
 
 // src/manifest.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname3, join as join6 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname4, join as join6 } from "node:path";
 function manifestPath({ scope, projectDir, home }) {
   return scope === "global" ? join6(home, ".mugiwara", "manifest.json") : join6(projectDir, ".mugiwara", "manifest.json");
 }
 function readManifest(file) {
-  return existsSync4(file) ? JSON.parse(readFileSync3(file, "utf8")) : null;
+  return existsSync5(file) ? JSON.parse(readFileSync3(file, "utf8")) : null;
 }
 function writeManifest(file, data) {
-  mkdirSync3(dirname3(file), { recursive: true });
+  mkdirSync4(dirname4(file), { recursive: true });
   writeFileSync3(file, JSON.stringify(data, null, 2) + `
 `);
 }
 
 // src/mission.ts
-import { existsSync as existsSync5, rmSync as rmSync2, readFileSync as readFileSync4 } from "node:fs";
+import { existsSync as existsSync6, rmSync as rmSync2, readFileSync as readFileSync4 } from "node:fs";
 import { join as join7 } from "node:path";
 function activeActor(projectDir) {
   const stateFile = join7(projectDir, ".mugiwara", "state.json");
-  if (!existsSync5(stateFile))
+  if (!existsSync6(stateFile))
     return null;
   try {
     const state = JSON.parse(readFileSync4(stateFile, "utf8"));
@@ -540,7 +566,7 @@ function activeActor(projectDir) {
 }
 function resetMission(projectDir, keepLogs, force) {
   const root = join7(projectDir, ".mugiwara");
-  if (!existsSync5(root))
+  if (!existsSync6(root))
     return { removed: [], kept: [] };
   if (!force) {
     const actor = activeActor(projectDir);
@@ -552,29 +578,29 @@ function resetMission(projectDir, keepLogs, force) {
   const kept = [];
   for (const dir of ["spec", "plans", "results", "review", "issues", "reports"]) {
     const p = join7(root, dir);
-    if (existsSync5(p)) {
+    if (existsSync6(p)) {
       rmSync2(p, { recursive: true, force: true });
       removed.push(dir);
     }
   }
   for (const f of ["state.json"]) {
     const p = join7(root, f);
-    if (existsSync5(p)) {
+    if (existsSync6(p)) {
       rmSync2(p);
       removed.push(f);
     }
   }
   if (!keepLogs) {
     const p = join7(root, "logs");
-    if (existsSync5(p)) {
+    if (existsSync6(p)) {
       rmSync2(p, { recursive: true, force: true });
       removed.push("logs");
     }
-  } else if (existsSync5(join7(root, "logs"))) {
+  } else if (existsSync6(join7(root, "logs"))) {
     kept.push("logs");
   }
   for (const f of ["config", "manifest.json", "backup"]) {
-    if (existsSync5(join7(root, f)))
+    if (existsSync6(join7(root, f)))
       kept.push(f);
   }
   return { removed, kept };
@@ -623,25 +649,31 @@ function resetCmd(flags) {
 }
 async function resolveOptions(flags) {
   const interactive = !flag(flags.yes);
+  if (interactive && !process.stdin.isTTY) {
+    throw new Error("Not a terminal. Run with --yes and --global or --project <dir> --target <ids|all>");
+  }
   const rl = interactive ? createRl() : null;
   try {
     let scope = flag(flags.global) ? "global" : str(flags.project) ? "project" : null;
     if (!scope) {
-      if (!interactive)
-        throw new Error("Specify --global or --project <dir> with --yes");
-      scope = await choose(rl, "Install scope?", ["global (user-wide)", "project (this repo)"]) === 0 ? "global" : "project";
+      if (!interactive) {
+        scope = "project";
+      } else
+        scope = await choose(rl, "Install scope?", ["global (user-wide)", "project (this repo)"]) === 0 ? "global" : "project";
     }
     const projectDir = resolve(str(flags.project) ?? process.cwd());
-    if (scope === "project" && !existsSync6(projectDir))
+    if (scope === "project" && !existsSync7(projectDir))
       throw new Error(`Project dir not found: ${projectDir}`);
     let targetIds = str(flags.target)?.split(",").map((s) => s.trim()) ?? null;
     if (targetIds && targetIds.includes("all"))
       targetIds = [...TARGET_IDS];
     if (!targetIds) {
-      if (!interactive)
-        throw new Error("Specify --target <ids|all> with --yes");
-      const idx = await multiChoose(rl, "Target AI agents?", ["all targets", ...TARGET_IDS]);
-      targetIds = idx.includes(0) ? [...TARGET_IDS] : idx.map((i) => TARGET_IDS[i - 1]);
+      if (!interactive) {
+        targetIds = [...TARGET_IDS];
+      } else {
+        const idx = await multiChoose(rl, "Target AI agents?", ["all targets", ...TARGET_IDS]);
+        targetIds = idx.includes(0) ? [...TARGET_IDS] : idx.map((i) => TARGET_IDS[i - 1]);
+      }
     }
     for (const id of targetIds) {
       if (!targets[id])
@@ -701,6 +733,14 @@ async function uninstall(flags) {
   const file = manifestPath({ scope, projectDir, home });
   const manifest = readManifest(file);
   if (!manifest) {
+    if (scope === "project") {
+      const globalFile = manifestPath({ scope: "global", projectDir, home });
+      if (existsSync7(globalFile)) {
+        console.log(`No project manifest found, but a global install exists. Try:
+  mugiwara uninstall --global`);
+        return;
+      }
+    }
     console.log("Nothing installed (no manifest found).");
     return;
   }
@@ -715,8 +755,20 @@ async function uninstall(flags) {
     }
   }
   const removed = removeInstalled(manifest, { dryRun: flag(flags.dryRun) });
-  if (!flag(flags.dryRun))
+  if (!flag(flags.dryRun)) {
     rmSync3(file);
+    const mugiDir = join8(scope === "global" ? home : projectDir, ".mugiwara");
+    if (existsSync7(mugiDir) && readdirSync3(mugiDir).length === 0) {
+      rmSync3(mugiDir, { recursive: true, force: true });
+    }
+    if (manifest.targets.includes("opencode")) {
+      const opencodeCache = join8(home, ".cache", "opencode", "packages", "@ionivetech");
+      if (existsSync7(opencodeCache)) {
+        rmSync3(opencodeCache, { recursive: true, force: true });
+        console.log("   cleared opencode npm cache (stale plugin versions)");
+      }
+    }
+  }
   console.log(`OK removed ${removed.length} files`);
 }
 function list(flags) {
@@ -731,7 +783,12 @@ function list(flags) {
     if (!m)
       continue;
     found = true;
-    console.log(`${label}: v${m.version} targets=${m.targets.join(",")} files=${m.files.length} installed=${m.installedAt}`);
+    if (flag(flags.check)) {
+      const missing = m.files.filter((f) => !existsSync7(f));
+      console.log(`${label}: v${m.version} targets=${m.targets.join(",")} files=${m.files.length} missing=${missing.length} installed=${m.installedAt}`);
+    } else {
+      console.log(`${label}: v${m.version} targets=${m.targets.join(",")} files=${m.files.length} installed=${m.installedAt}`);
+    }
   }
   if (!found)
     console.log("No mugiwara installation found.");
@@ -740,10 +797,11 @@ function help() {
   console.log(`mugiwara ${VERSION} — the Straw Hat crew for AI agents
 
 Usage:
-  mugiwara [install]     install the crew (default; wizard when flags missing)
+  mugiwara [install]     install the crew (wizard; with --yes uses project + all)
   mugiwara update        replace existing files (backs up differences first)
   mugiwara uninstall     remove installed files via manifest
   mugiwara list          show installations
+  mugiwara list --check  health check: show installations + missing files
   mugiwara reset         wipe mission state (spec/plans/results/review/issues[/logs])
   mugiwara --help        this help
   mugiwara --version     print version
@@ -752,18 +810,13 @@ Flags:
   --global               user-wide install
   --project <dir>        project install (default: cwd)
   --target <ids|all>     comma-separated: ${TARGET_IDS.join(", ")}
-  --yes, -y              non-interactive (needs --global/--project, --target)
+  --yes, -y              non-interactive (defaults: project, all targets)
   --force                overwrite differing files (with backup)
   --dry-run              print actions without writing
+  --check                with list: report missing files (health check)
   --keep-logs            with reset: keep .mugiwara/logs (lessons ledger survives)`);
 }
-var entry = process.argv[1] !== undefined ? resolve(process.argv[1]) : undefined;
-if (entry !== undefined) {
-  try {
-    entry = realpathSync(entry);
-  } catch {}
-}
-var isMain = entry !== undefined && import.meta.url === pathToFileURL(entry).href;
+var isMain = process.argv[1] !== undefined && fileURLToPath4(import.meta.url) === resolve(process.argv[1]);
 if (isMain) {
   run(process.argv.slice(2)).catch((err) => {
     console.error(`mugiwara: ${err.message}`);

package/docs/{modes.md → concepts/modes.md}

@@ -1,8 +1,7 @@
 # Modes
 
 The crew's autonomy level. Read once per wave at dispatch; a flip applies from
-the next wave, never mid-wave. Single source of truth: the `mugiwara-mode`
-skill.
+the next wave, never mid-wave.
 
 **Mode owns autonomy, config owns writing standards.** Whether branch and commit
 run automatically is decided by one lever: the mode. The config only shapes HOW

package/docs/{skills.md → concepts/skills.md}

@@ -52,4 +52,4 @@ it embodies a role.
 ## Anatomy
 
 Every skill is a `SKILL.md` with frontmatter + playbook body. See
-[skill-anatomy.md](skill-anatomy.md).
+[skill-anatomy.md](../reference/skill-anatomy.md).

package/docs/getting-started.md

@@ -111,7 +111,7 @@ Almost nothing in `guided` mode:
   PR, merges, or deploys.
 
 Switch to `semi` or `auto` if you want the crew to self-manage branch, commits,
-and ambiguities. See [modes](modes.md).
+and ambiguities. See [modes](concepts/modes.md).
 
 ## 4. The `.mugiwara/` workspace
 
@@ -133,7 +133,7 @@ Every mission writes to `.mugiwara/` at the repo root:
 
 **Savepoint** runs at every wave boundary — `state.json` carries lane, wave,
 files, blockers, heal cycle, and token budget. Resume reads one file instead of
-six. See [audit-trail.md](audit-trail.md) for the full artifact map.
+six. See [audit-trail.md](concepts/audit-trail.md) for the full artifact map.
 
 ## 5. Configuration
 
@@ -150,9 +150,9 @@ six. See [audit-trail.md](audit-trail.md) for the full artifact map.
 
 ## 6. Next steps
 
-- Meet the [crew](agents.md) — 14 agents with permission boundaries.
-- Browse the [skills](skills.md) — 26 skills with the 3-layer disclosure model.
-- Understand the [lanes](lanes.md) — how work is sized before it runs.
-- Set your [mode](modes.md) — guided/semi/auto.
-- Read the [audit trail](audit-trail.md) — every artifact and how to review it.
-- See the [compliance matrix](compliance-matrix.md) — rule compliance per model.
+- Meet the [crew](concepts/agents.md) — 14 agents with permission boundaries.
+- Browse the [skills](concepts/skills.md) — 26 skills with the 3-layer disclosure model.
+- Understand the [lanes](concepts/lanes.md) — how work is sized before it runs.
+- Set your [mode](concepts/modes.md) — guided/semi/auto.
+- Read the [audit trail](concepts/audit-trail.md) — every artifact and how to review it.
+- See the [compliance matrix](reference/compliance-matrix.md) — rule compliance per model.

package/docs/index.md

@@ -15,39 +15,39 @@ claim.
 | Doc | What it covers |
 |-----|----------------|
 | [Getting started](getting-started.md) | Install, first mission, what you see in the chat |
-| [Adoption guide](adoption-guide.md) | Pick the harness, pick the mode, fit the crew to your workflow |
-| [Modes](modes.md) | guided / semi / auto — the autonomy levels, what each asks you |
-| [Config](config.md) | Full reference for `.mugiwara/config` keys and commit styles |
-| [Auto-PR](pr-summary.md) | What the crew hands off at closure: push + a ready-to-paste PR summary (it never creates a PR) |
-| [The crew](agents.md) | All 14 agents and when to summon each |
-| [The techniques](skills.md) | All 32 skills and what each enforces |
-| [The wave pipeline](workflow.md) | How a mission flows Wave 0 → Wave 9 |
-| [Execution model](execution-model.md) | Inline-by-default: why the crew runs in your main conversation |
-| [Lanes & sizing](lanes.md) | How Luffy sizes work at triage: Lane 0–4, escalation, budget |
-| [Enforcement](enforcement.md) | Skip gates, evidence over claims, and capability tiers |
-| [Git discipline](git-strategy.md) | Commits, branches, save-points — and why the executor commits |
+| [Adoption guide](reference/adoption-guide.md) | Pick the harness, pick the mode, fit the crew to your workflow |
+| [Modes](concepts/modes.md) | guided / semi / auto — the autonomy levels, what each asks you |
+| [Config](concepts/config.md) | Full reference for `.mugiwara/config` keys and commit styles |
+| [Auto-PR](concepts/pr-summary.md) | What the crew hands off at closure: push + a ready-to-paste PR summary (it never creates a PR) |
+| [The crew](concepts/agents.md) | All 14 agents and when to summon each |
+| [The techniques](concepts/skills.md) | All 32 skills and what each enforces |
+| [The wave pipeline](concepts/workflow.md) | How a mission flows Wave 0 → Wave 9 |
+| [Execution model](concepts/execution-model.md) | Inline-by-default: why the crew runs in your main conversation |
+| [Lanes & sizing](concepts/lanes.md) | How Luffy sizes work at triage: Lane 0–4, escalation, budget |
+| [Enforcement](reference/enforcement.md) | Skip gates, evidence over claims, and capability tiers |
+| [Git discipline](concepts/git-strategy.md) | Commits, branches, save-points — and why the executor commits |
 
 ## Install by harness
 
 | Harness | Guide |
 |---------|-------|
-| Claude Code | [claude-setup.md](claude-setup.md) |
-| opencode | [opencode-setup.md](opencode-setup.md) |
-| GitHub Copilot | [copilot-setup.md](copilot-setup.md) |
-| Gemini CLI | [gemini-setup.md](gemini-setup.md) |
-| Codex | [codex-setup.md](codex-setup.md) |
-| Cursor | [cursor-setup.md](cursor-setup.md) |
-| Windsurf | [windsurf-setup.md](windsurf-setup.md) |
-| Cline / Kilo / Antigravity | [rule-based-setup.md](rule-based-setup.md) |
+| Claude Code | [install/claude.md](install/claude.md) |
+| opencode | [install/opencode.md](install/opencode.md) |
+| GitHub Copilot | [install/copilot.md](install/copilot.md) |
+| Gemini CLI | [install/gemini.md](install/gemini.md) |
+| Codex | [install/codex.md](install/codex.md) |
+| Cursor | [install/cursor.md](install/cursor.md) |
+| Windsurf | [install/cli.md](install/cli.md) |
+| Cline / Kilo / Antigravity | [install/cli.md](install/cli.md) |
 
 ## Reference
 
 | Doc | What it covers |
 |-----|----------------|
-| [Skill anatomy](skill-anatomy.md) | How a mugiwara skill file is structured |
-| [Agent anatomy](agent-anatomy.md) | How a mugiwara agent file is structured |
+| [Skill anatomy](reference/skill-anatomy.md) | How a mugiwara skill file is structured |
+| [Agent anatomy](reference/agent-anatomy.md) | How a mugiwara agent file is structured |
 | [Troubleshooting](troubleshooting.md) | Common problems and how to fix them |
-| [Developer onboarding](developer-onboarding.md) | Repo layout, validation, tests, contributing |
+| [Developer onboarding](reference/developer-onboarding.md) | Repo layout, validation, tests, contributing |
 
 ## Resources
 

package/docs/{install-antigravity.md → install/antigravity.md}

@@ -42,4 +42,4 @@ agy plugin uninstall mugiwara
 ## Configuration
 
 After install, configure mugiwara in `.mugiwara/config` (project) or
-`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+`~/.mugiwara/config` (global). See [config.md](../concepts/config.md).

package/docs/{install-claude.md → install/claude.md}

@@ -11,7 +11,7 @@ session-start hook.
 ## Install
 
 ```bash
-/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara@mugiwara
+/plugin marketplace add ionivetech/mugiwara && /plugin install mugiwara
 ```
 
 ## How it works
@@ -52,10 +52,12 @@ Or start any task — the crew auto-activates at session start.
 ## Configuration
 
 After install, configure mugiwara in `.mugiwara/config` (project) or
-`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+`~/.mugiwara/config` (global). See [config.md](../concepts/config.md).
 
 Switch autonomy mode with `/mugiwara-mode guided|semi|auto`.
 
+Or set permanently in `.mugiwara/config`: `mode=guided`.
+
 ## Troubleshooting
 
 ### Plugin not showing up

package/docs/{install-cli.md → install/cli.md}

@@ -66,14 +66,25 @@ what mugiwara crew members are available?
 ## Update
 
 ```bash
-mugiwara update
-# or: npx @ionivetech/mugiwara@latest update
+npx @ionivetech/mugiwara@latest update --project . --target <id> --yes
+```
+
+Or with global CLI:
+
+```bash
+mugiwara update --project . --target <id> --yes
 ```
 
 ## Uninstall
 
 ```bash
-mugiwara uninstall
+npx @ionivetech/mugiwara@latest uninstall --project .
+```
+
+Or with global CLI:
+
+```bash
+mugiwara uninstall --project .
 ```
 
 ## Global install
@@ -88,16 +99,17 @@ Installs to `~/.devin/rules/` (Windsurf), `~/.clinerules/` (Cline), or
 ## Configuration
 
 After install, configure mugiwara in `.mugiwara/config` (project) or
-`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+`~/.mugiwara/config` (global). See [config.md](../concepts/config.md).
 
 ## CLI reference
 
 ```bash
 mugiwara install                                  # wizard (interactive)
-mugiwara install --project . --target all --yes   # non-interactive
-mugiwara update                                   # replace existing files
-mugiwara uninstall                                # remove what manifest recorded
+npx @ionivetech/mugiwara@latest install --yes     # non-interactive (project + all)
+mugiwara update --project . --target <id> --yes   # replace existing files
+mugiwara uninstall --project .                    # remove what manifest recorded
 mugiwara list                                     # show installations
+mugiwara list --check                             # health check (missing files)
 mugiwara reset --keep-logs                        # wipe mission state, keep lessons
 mugiwara reset --force                            # override multi-actor guard
 ```

package/docs/{install-codex.md → install/codex.md}

@@ -41,4 +41,4 @@ codex plugin remove mugiwara
 ## Configuration
 
 After install, configure mugiwara in `.mugiwara/config` (project) or
-`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+`~/.mugiwara/config` (global). See [config.md](../concepts/config.md).

package/docs/{install-copilot.md → install/copilot.md}

@@ -42,4 +42,4 @@ copilot plugin uninstall mugiwara
 ## Configuration
 
 After install, configure mugiwara in `.mugiwara/config` (project) or
-`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+`~/.mugiwara/config` (global). See [config.md](../concepts/config.md).

package/docs/{install-cursor.md → install/cursor.md}

@@ -42,4 +42,4 @@ Re-run:
 ## Configuration
 
 After install, configure mugiwara in `.mugiwara/config` (project) or
-`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+`~/.mugiwara/config` (global). See [config.md](../concepts/config.md).

package/docs/{install-gemini.md → install/gemini.md}

@@ -41,4 +41,4 @@ gemini extensions remove mugiwara
 ## Configuration
 
 After install, configure mugiwara in `.mugiwara/config` (project) or
-`~/.mugiwara/config` (global). See [docs/config.md](config.md).
+`~/.mugiwara/config` (global). See [config.md](../concepts/config.md).

package/docs/{install.md → install/index.md}

@@ -9,16 +9,16 @@ Requires **Node.js >= 20.11** on the host machine.
 
 | Platform | Install doc | Native plugin? |
 |----------|-------------|:---:|
-| Claude Code | [install-claude](install-claude.md) | ✅ |
-| OpenCode | [install-opencode](install-opencode.md) | ✅ |
-| Gemini CLI | [install-gemini](install-gemini.md) | ✅ |
-| Codex | [install-codex](install-codex.md) | ✅ |
-| GitHub Copilot | [install-copilot](install-copilot.md) | ✅ |
-| Cursor | [install-cursor](install-cursor.md) | ✅ |
-| Antigravity | [install-antigravity](install-antigravity.md) | ✅ |
-| Kimi Code | [install-kimi](install-kimi.md) | ✅ |
-| Pi | [install-pi](install-pi.md) | ✅ |
-| Windsurf / Cline / Kilo | [install-cli](install-cli.md) | CLI-based |
+| Claude Code | [claude](claude.md) | ✅ |
+| OpenCode | [opencode](opencode.md) | ✅ |
+| Gemini CLI | [gemini](gemini.md) | ✅ |
+| Codex | [codex](codex.md) | ✅ |
+| GitHub Copilot | [copilot](copilot.md) | ✅ |
+| Cursor | [cursor](cursor.md) | ✅ |
+| Antigravity | [antigravity](antigravity.md) | ✅ |
+| Kimi Code | [kimi](kimi.md) | ✅ |
+| Pi | [pi](pi.md) | ✅ |
+| Windsurf / Cline / Kilo | [cli](cli.md) | CLI-based |
 
 ## One-liner
 
@@ -46,7 +46,7 @@ what mugiwara crew members are available?
 
 ## Configuration
 
-See [docs/config.md](config.md) for all `.mugiwara/config` options.
+See [config.md](../concepts/config.md) for all `.mugiwara/config` options.
 
 ## Report issues