kushi-agents 5.9.0 → 5.9.2

package/bin/cli.mjs

@@ -1,639 +1,640 @@
-#!/usr/bin/env node
-
-import { main } from '../src/main.mjs';
-import { runMultiHost } from '../src/multi-host.mjs';
-
-const args = process.argv.slice(2);
-
-// ── bare invocation (v5.4.0+) ────────────────────────────────────────────────
-// v5.4.1: on an interactive TTY, auto-launch the setup wizard (matches the
-// ergonomics of `npx create-*`). Non-TTY (CI, scripts, piped stdin) and the
-// explicit KUSHI_SKIP_WELCOME=1 still print the welcome card and exit 0, so
-// nothing is installed by side-effect.
-if (args.length === 0) {
-  const forceWelcome = process.env.KUSHI_SKIP_WELCOME === '1';
-  const forceWizard  = process.env.KUSHI_FORCE_WIZARD === '1';
-  const interactive  = forceWizard || (process.stdin.isTTY && !forceWelcome);
-  if (interactive) {
-    const { runSetupWizard } = await import('../src/setup-wizard.mjs');
-    await runSetupWizard({ args: [] });
-    process.exit(0);
-  }
-  await printWelcome();
-  process.exit(0);
-}
-
-// ── doctor verb (v5.4.0+) ───────────────────────────────────────────────────
-if (args.length > 0 && args[0] === 'doctor') {
-  const { spawnSync } = await import('node:child_process');
-  const pathMod = await import('node:path');
-  const urlMod = await import('node:url');
-  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
-  const script = pathMod.resolve(here, '..', 'plugin', 'skills', 'doctor', 'doctor.ps1');
-  const psArgs = ['-NoProfile', '-File', script];
-  if (args.includes('--json')) psArgs.push('-Json');
-  if (args.includes('--strict')) psArgs.push('-Strict');
-  const r = spawnSync('pwsh', psArgs, { stdio: 'inherit' });
-  process.exit(r.status ?? 1);
-}
-
-// ── setup-wizard flag (v5.4.0+) ─────────────────────────────────────────────
-if (args.includes('--setup-wizard')) {
-  const { runSetupWizard } = await import('../src/setup-wizard.mjs');
-  await runSetupWizard({ args });
-  process.exit(0);
-}
-
-async function printWelcome() {
-  const pathMod = await import('node:path');
-  const urlMod = await import('node:url');
-  const fsMod = await import('node:fs');
-  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
-  const repoRoot = pathMod.resolve(here, '..');
-  let version = 'unknown';
-  try { version = JSON.parse(fsMod.readFileSync(pathMod.join(repoRoot, 'package.json'), 'utf-8')).version; } catch {}
-  let skillCount = 0;
-  try {
-    const skillsDir = pathMod.join(repoRoot, 'plugin', 'skills');
-    skillCount = fsMod.readdirSync(skillsDir, { withFileTypes: true })
-      .filter((d) => d.isDirectory() && !d.name.startsWith('_'))
-      .length;
-  } catch {}
-  console.log(`
-  kushi v${version} — multi-source M365 project evidence agent
-
-  (non-interactive shell — nothing was installed)
-
-  First time?         kushi doctor
-  Bootstrap a project: kushi setup <project>
-  Ask a question:      kushi ask <project> "..."
-  Wizard install:      npx kushi-agents --setup-wizard
-  Host install:        npx kushi-agents --clawpilot | --vscode | --all-hosts
-
-  Docs:   https://gim-home.github.io/kushi/
-  Skills: ${skillCount} installed in plugin/skills/
-
-  Run  kushi --help  for the full verb list.
-`);
-}
-
-// ── skill-authoring verbs (v5.0.4+) ─────────────────────────────────────────
-// Dispatch directly to the skill-creator / skill-checker pwsh scripts.
-const SKILL_VERBS = new Set(['create-skill', 'check-skill', 'optimize-description', 'review-evals']);
-if (args.length > 0 && SKILL_VERBS.has(args[0])) {
-  const verb = args[0];
-  const rest = args.slice(1);
-  await dispatchSkillVerb(verb, rest);
-  process.exit(0);
-}
-
-// ── lint verb (v5.1.0+) ──────────────────────────────────────────────────────
-if (args.length > 0 && args[0] === 'lint') {
-  if (args.includes('--global')) {
-    const { runGlobalLint } = await import('../src/global-wiki-cli.mjs');
-    await runGlobalLint();
-    process.exit(0);
-  }
-  const project = args[1] || '';
-  if (!project) {
-    console.error('\n  Usage: kushi lint <project>\n         kushi lint --global\n');
-    process.exit(1);
-  }
-  await dispatchLint(project);
-  process.exit(0);
-}
-
-// ── global verb (v5.3.0+) ────────────────────────────────────────────────────
-if (args.length > 0 && args[0] === 'global') {
-  const sub = args[1] || '';
-  const validSubs = ['init', 'status', 'ask', 'lint'];
-  if (!validSubs.includes(sub)) {
-    console.error('\n  Usage: kushi global init           Scaffold ~/.kushi-global/State/');
-    console.error('         kushi global status         Show counts + freshness');
-    console.error('         kushi global ask <question> Ask the global wiki');
-    console.error('         kushi global lint           Lint the global wiki\n');
-    process.exit(1);
-  }
-  const { runGlobalInit, runGlobalStatus, runGlobalAsk, runGlobalLint } = await import('../src/global-wiki-cli.mjs');
-  if (sub === 'init') await runGlobalInit();
-  else if (sub === 'status') await runGlobalStatus();
-  else if (sub === 'ask') await runGlobalAsk(args.slice(2).join(' '));
-  else if (sub === 'lint') await runGlobalLint();
-  process.exit(0);
-}
-
-// ── promote verb (v5.3.0+) ───────────────────────────────────────────────────
-if (args.length > 0 && args[0] === 'promote') {
-  const project = args[1] || '';
-  const page = args[2] || '';
-  if (!project || !page) {
-    console.error('\n  Usage: kushi promote <project> <page-path>\n');
-    console.error('  Copies a project State page into the global wiki with provenance metadata.');
-    console.error('  Refuses by default if customer identifiers are detected; pass --force after review.\n');
-    process.exit(1);
-  }
-  const force = args.includes('--force');
-  const { runPromote } = await import('../src/global-wiki-cli.mjs');
-  await runPromote(project, page, { force });
-  process.exit(0);
-}
-
-// ── hooks verb (v5.2.0+) ─────────────────────────────────────────────────────
-if (args.length > 0 && args[0] === 'hooks') {
-  const sub = args[1] || '';
-  const project = args[2] || '';
-  if (!sub || !project || !['list', 'test'].includes(sub)) {
-    console.error('\n  Usage: kushi hooks list <project>\n         kushi hooks test <project> <event>\n');
-    process.exit(1);
-  }
-  await dispatchHooks(sub, project, args.slice(3));
-  process.exit(0);
-}
-
-// ── explain verb (v5.2.0+) ───────────────────────────────────────────────────
-if (args.length > 0 && args[0] === 'explain') {
-  const topic = args.slice(1).join(' ');
-  if (!topic) {
-    console.error('\n  Usage: kushi explain <topic>\n\n  Available topics: contradictions, refresh, state, hooks, parallel, otel, csc, graph, workiq, schema, install, evals\n');
-    process.exit(1);
-  }
-  await dispatchExplain(topic);
-  process.exit(0);
-}
-
-// ── remember verb (v5.2.0+) ──────────────────────────────────────────────────
-if (args.length > 0 && args[0] === 'remember') {
-  const rule = args.slice(1).join(' ');
-  if (!rule) {
-    console.error('\n  Usage: kushi remember <rule>\n\n  Example: kushi remember "always use Northwind not Healthcare Accelerator"\n');
-    process.exit(1);
-  }
-  await dispatchRemember(rule);
-  process.exit(0);
-}
-
-if (args.includes('--help') || args.includes('-h')) {
-  console.log(`
-  Usage: npx kushi-agents [options]
-
-  Installs the Kushi multi-source project-evidence + Q&A agent.
-
-  Host installs (v5.0.2+ — install into a host's user-global skill folder):
-    --clawpilot       Install to ~/.copilot/m-skills/kushi/
-    --vscode          Install to ~/.vscode/chat/skills/kushi/  (a.k.a. GitHub Copilot Chat)
-    --all-hosts       Install to BOTH hosts
-    --no-workspace    Skip the auto workspace install (host install only)
-    --uninstall [--clawpilot|--vscode|--all]
-                      Cleanly remove the kushi install + skills-metadata.json entry
-                      from the chosen host(s). Default = all detected hosts.
-
-    Note: when run from inside a project directory (any of: package.json, .git,
-    .kushi/, Evidence/, etc.), host installs ALSO refresh the workspace
-    .kushi/ install in cwd. One command covers both. Pass --no-workspace to
-    suppress, or run from a non-project directory.
-
-  Workspace install (legacy / default when no host flag is given):
-    --target vscode     Install to <cwd>/.kushi/ + update .vscode/settings.json   [default]
-    --target clawpilot  Alias for --clawpilot (kept for back-compat)
-
-  Profile (controls what gets installed):
-    --profile core      Aggregator only (pull + consolidate + ask).
-    --profile standard  Core + State/ rollup.                          [DEFAULT]
-    --profile full      Standard + report packs.
-
-  Options:
-    --force             Overwrite existing destination without asking
-    --yes, -y           Skip the project-root check
-    --no-settings       Skip .vscode/settings.json update (vscode workspace target only)
-    --no-instructions   Skip .github/copilot-instructions.md merge   (vscode workspace target only)
-    --no-prompt         Skip the post-install m365-auth quickstart (3 fields that
-                        make 'kushi discover' fast). Also disabled by KUSHI_NO_PROMPT=1.
-
-  WorkIQ (REQUIRED — Kushi cannot pull evidence without it):
-    --with-workiq           Auto-install WorkIQ via winget (Windows) / brew (macOS)
-    --workiq-path <abs>     Use this explicit path to the workiq binary
-    --skip-workiq-check     Bypass the WorkIQ pre-flight check
-
-    --help, -h          Show this help
-
-  Skill authoring (v5.0.4+):
-    create-skill <name> --type <pull|writer|orchestrator|other> --description "<d>"
-                         Scaffold a new plugin/skills/<name>/ tree.
-    check-skill <name>   Lint a skill against the agentskills.io blueprint.
-    check-skill --all [--retrofit [--apply]]
-                         Audit (or retrofit) every skill in plugin/skills/.
-    optimize-description <skill>
-                         Rewrite a skill's description per the optimizer rules.
-    review-evals <skill> Render an HTML side-by-side eval-review viewer.
-
-  Wiki maintenance (v5.1.0+):
-    lint <project>       Run wiki-lint checks on State/ (contradictions, stale claims, orphans).
-    lint --global        Lint the global wiki at ~/.kushi-global/State/.
-
-  Hooks & observability (v5.2.0+):
-    hooks list <project>           List configured hooks for a project.
-    hooks test <project> <event>   Fire a synthetic hook event for testing.
-    explain <topic>                Explain a kushi concept (pedagogical, read-only).
-    remember <rule>                Persist a project convention to CLAUDE.md.
-
-  Global wiki (v5.3.0+):
-    global init                    Scaffold ~/.kushi-global/State/ (env: KUSHI_GLOBAL_ROOT)
-    global status                  Show page counts + freshness for the global wiki.
-    global ask <question>          Search the global wiki specifically.
-    global lint                    Lint the global wiki (alias for 'lint --global').
-    promote <project> <page>       Move a project State page into global with redaction + back-link.
-                                   Refuses if customer identifiers are detected; --force after review.
-
-  Stabilization (v5.4.0+):
-    doctor                         Aggregated health check (env, self-check, evals, skill-checker, drift, global).
-                                   --json for CI; --strict to fail on yellow.
-    --setup-wizard                 Interactive first-run flow (engagement root, hosts, global wiki).
-
-  After install, talk to Kushi:
-    bootstrap <project>     First-time setup
-    refresh <project>       Incremental refresh + rebuild State/
-    state <project>         Re-render State/ from existing Evidence (deterministic
-                            inventory; LLM build-state skill does narrative synthesis)
-    references <project>    Scan Evidence for URLs and refresh the shared
-                            references pool (Evidence/_shared/references/)
-    consolidate <project>   Merge per-user evidence
-    status <project>        Show run-log
-    ask <project> <q>       Cited Q&A over Evidence/ (auto-routes, --file-back to save)
-    lint <project>          Run wiki-lint checks on State/
-
-  Workspace lifecycle (v5.9.0+):
-    uninstall [--keep-config]      Remove <cwd>/.kushi/ (preserves Evidence/, State/).
-                                   --keep-config preserves config/user/ identity files.
-    upgrade                        npm i -g kushi-agents@latest then re-seed assets
-                                   in cwd (config preserved).
-
-  In VS Code Chat the prefix is "@Kushi". In Clawpilot just say "kushi <verb>".
-`);
-  process.exit(0);
-}
-
-// ── state / refresh / bootstrap verbs (v5.9.0+) ─────────────────────────────
-// Thin shells that exec the deterministic runners. Keeps `kushi state HCA` etc.
-// runnable from the global bin without users having to know the runner paths.
-if (args.length > 0 && ['state', 'refresh-runner', 'bootstrap-runner', 'discover', 'references'].includes(args[0])) {
-  const verb = args[0];
-  const project = args[1];
-  if (!project) {
-    console.error(`\n  Usage: kushi ${verb} <project> [options]\n`);
-    process.exit(1);
-  }
-  const { spawnSync } = await import('node:child_process');
-  const pathMod = await import('node:path');
-  const urlMod = await import('node:url');
-  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
-  const runnerMap = {
-    state: 'pull-state.mjs',
-    references: 'pull-references.mjs',
-    discover: 'discover.mjs',
-    'refresh-runner': 'refresh.mjs',
-    'bootstrap-runner': 'bootstrap.mjs',
-  };
-  const runner = pathMod.resolve(here, '..', 'plugin', 'runners', runnerMap[verb]);
-  const passthrough = args.slice(2);
-  const r = spawnSync(process.execPath, [runner, '--project', project, ...passthrough], { stdio: 'inherit' });
-  process.exit(r.status ?? 1);
-}
-
-// ── workspace uninstall / upgrade verbs (v5.9.0+) ───────────────────────────
-if (args.length > 0 && args[0] === 'uninstall' && !args.includes('--clawpilot') && !args.includes('--vscode') && !args.includes('--all-hosts')) {
-  // Workspace uninstall: remove .kushi/ from cwd (preserves Evidence/, State/).
-  const fsMod = await import('node:fs');
-  const pathMod = await import('node:path');
-  const dest = pathMod.resolve(process.cwd(), '.kushi');
-  const keepConfig = args.includes('--keep-config');
-  if (!fsMod.existsSync(dest)) {
-    console.error(`\n  No .kushi/ directory found at ${dest}\n`);
-    process.exit(1);
-  }
-  if (keepConfig) {
-    const assetDirs = ['agents', 'instructions', 'prompts', 'skills', 'templates', 'reference-packs', 'lib', 'runners'];
-    let removed = 0;
-    for (const d of assetDirs) {
-      const p = pathMod.join(dest, d);
-      if (fsMod.existsSync(p)) { fsMod.rmSync(p, { recursive: true, force: true }); removed++; }
-    }
-    console.log(`\n  Removed ${removed} asset dir(s) from ${dest} (config/user/ preserved).\n`);
-  } else {
-    fsMod.rmSync(dest, { recursive: true, force: true });
-    console.log(`\n  Removed ${dest}\n  Evidence/ and State/ left untouched.\n`);
-  }
-  process.exit(0);
-}
-
-if (args.length > 0 && args[0] === 'upgrade') {
-  // Upgrade: npm i -g @latest, then re-seed assets in cwd preserving config.
-  const { spawnSync } = await import('node:child_process');
-  console.log('\n  Upgrading kushi-agents globally via npm...\n');
-  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const r1 = spawnSync(npm, ['install', '-g', 'kushi-agents@latest'], { stdio: 'inherit' });
-  if (r1.status !== 0) {
-    console.error('\n  npm install failed.\n');
-    process.exit(r1.status ?? 1);
-  }
-  console.log('\n  Refreshing assets in cwd (config preserved)...\n');
-  const fsMod = await import('node:fs');
-  if (fsMod.existsSync('.kushi')) {
-    const r2 = spawnSync(npm, ['exec', '--', 'kushi-agents', '--no-prompt', '--force'], { stdio: 'inherit' });
-    process.exit(r2.status ?? 0);
-  } else {
-    console.log('\n  No .kushi/ in cwd — global upgrade complete; cd into a project and run `kushi` to install.\n');
-    process.exit(0);
-  }
-}
-
-// ── multi-host mode (v5.0.2+) ───────────────────────────────────────────────
-// Trigger when the user passes any of: --vscode, --all-hosts, --uninstall.
-// --clawpilot ALONE continues to route through the legacy main.mjs path so
-// the existing target=clawpilot flow stays byte-identical.
-const wantsVscode = args.includes('--vscode');
-const wantsAllHosts = args.includes('--all-hosts');
-const wantsUninstall = args.includes('--uninstall');
-
-if (wantsVscode || wantsAllHosts || wantsUninstall) {
-  const hosts = [];
-  if (args.includes('--clawpilot')) hosts.push('clawpilot');
-  if (wantsVscode) hosts.push('vscode');
-  const all = wantsAllHosts || args.includes('--all');
-
-  runMultiHost({
-    hosts,
-    all,
-    uninstall: wantsUninstall,
-    profile: getFlag('--profile'),
-    includeWorkspace: !args.includes('--no-workspace'),
-    noPrompt: args.includes('--no-prompt'),
-  }).catch((err) => {
-    console.error(`\n  ${err.message}\n`);
-    process.exit(1);
-  });
-} else {
-  let target = getFlag('--target');
-  if (args.includes('--clawpilot')) {
-    if (target && target !== 'clawpilot') {
-      console.error(`\n  Conflicting flags: --target ${target} and --clawpilot.\n`);
-      process.exit(1);
-    }
-    target = 'clawpilot';
-  }
-
-  const options = {
-    force: args.includes('--force'),
-    yes: args.includes('--yes') || args.includes('-y'),
-    noSettings: args.includes('--no-settings'),
-    noInstructions: args.includes('--no-instructions'),
-    noPrompt: args.includes('--no-prompt'),
-    target,
-    profile: getFlag('--profile'),
-    withWorkiq: args.includes('--with-workiq'),
-    workiqPath: getFlag('--workiq-path'),
-    skipWorkiqCheck: args.includes('--skip-workiq-check'),
-  };
-
-  main(options).catch((err) => {
-    console.error(`\n  ${err.message}\n`);
-    process.exit(1);
-  });
-}
-
-function getFlag(flag) {
-  const idx = args.indexOf(flag);
-  if (idx !== -1 && idx + 1 < args.length) {
-    return args[idx + 1];
-  }
-  const prefix = flag + '=';
-  const match = args.find((a) => a.startsWith(prefix));
-  return match ? match.slice(prefix.length) : undefined;
-}
-
-// ── skill-authoring verb dispatch (v5.0.4+) ─────────────────────────────────
-async function dispatchSkillVerb(verb, rest) {
-  const { spawnSync } = await import('node:child_process');
-  const path = await import('node:path');
-  const url = await import('node:url');
-  const here = path.dirname(url.fileURLToPath(import.meta.url));
-  const repoRoot = path.resolve(here, '..');
-  const creatorDir = path.join(repoRoot, 'plugin', 'skills', 'skill-creator');
-  const checkerDir = path.join(repoRoot, 'plugin', 'skills', 'skill-checker');
-
-  let script, scriptArgs = [];
-  switch (verb) {
-    case 'create-skill': {
-      // Usage: kushi create-skill <name> [--type <t>] [--description "<d>"] [--force]
-      const name = rest.find((a) => !a.startsWith('-'));
-      if (!name) {
-        console.error('Usage: kushi-agents create-skill <name> --type <pull|writer|orchestrator|other> --description "USE WHEN ... DO NOT USE FOR ..."');
-        process.exit(1);
-      }
-      const type = pickFlag(rest, '--type') || 'other';
-      const desc = pickFlag(rest, '--description') || `USE WHEN ${name} is invoked. DO NOT USE FOR unrelated tasks.`;
-      script = path.join(creatorDir, 'scaffold.ps1');
-      scriptArgs = ['-Name', name, '-Type', type, '-Description', desc];
-      if (rest.includes('--force')) scriptArgs.push('-Force');
-      if (rest.includes('--dry-run')) scriptArgs.push('-DryRun');
-      break;
-    }
-    case 'check-skill': {
-      // Usage: kushi check-skill <name> | --all  [--retrofit] [--apply]
-      script = path.join(checkerDir, 'check-skill.ps1');
-      const allFlag = rest.includes('--all') || rest.includes('-All');
-      const name = rest.find((a) => !a.startsWith('-'));
-      if (allFlag) scriptArgs.push('-All');
-      else if (name) scriptArgs.push('-Skill', name);
-      else {
-        console.error('Usage: kushi-agents check-skill <name> | --all  [--retrofit] [--apply] [--dry-run]');
-        process.exit(1);
-      }
-      if (rest.includes('--retrofit')) scriptArgs.push('-Retrofit');
-      if (rest.includes('--apply')) scriptArgs.push('-Apply');
-      if (rest.includes('--dry-run')) scriptArgs.push('-DryRun');
-      if (rest.includes('--json')) scriptArgs.push('-Json');
-      break;
-    }
-    case 'optimize-description': {
-      // Usage: kushi optimize-description <skill>
-      const name = rest.find((a) => !a.startsWith('-'));
-      if (!name) {
-        console.error('Usage: kushi-agents optimize-description <skill>');
-        process.exit(1);
-      }
-      script = path.join(checkerDir, 'check-skill.ps1');
-      scriptArgs = ['-Skill', name, '-OptimizeDescription'];
-      break;
-    }
-    case 'review-evals': {
-      // Usage: kushi review-evals <skill>
-      const name = rest.find((a) => !a.startsWith('-'));
-      if (!name) {
-        console.error('Usage: kushi-agents review-evals <skill>');
-        process.exit(1);
-      }
-      script = path.join(checkerDir, 'check-skill.ps1');
-      scriptArgs = ['-Skill', name, '-Review'];
-      break;
-    }
-    default:
-      console.error(`Unknown skill verb: ${verb}`);
-      process.exit(1);
-  }
-
-  const result = spawnSync('pwsh', ['-NoProfile', '-File', script, ...scriptArgs], { stdio: 'inherit' });
-  process.exit(result.status ?? 1);
-}
-
-async function dispatchLint(project) {
-  const { spawn } = await import('node:child_process');
-  const { resolve } = await import('node:path');
-  const { fileURLToPath } = await import('node:url');
-  const __dirname = fileURLToPath(new URL('.', import.meta.url));
-  const scriptPath = resolve(__dirname, '..', 'plugin', 'skills', 'lint-state', 'lint.ps1');
-
-  const cwd = process.cwd();
-  const { readdirSync, existsSync } = await import('node:fs');
-  let stateDir = '';
-
-  const evidenceDir = resolve(cwd, project, 'Evidence');
-  if (existsSync(evidenceDir)) {
-    const aliases = readdirSync(evidenceDir, { withFileTypes: true })
-      .filter(d => d.isDirectory() && !d.name.startsWith('_'));
-    for (const alias of aliases) {
-      const candidate = resolve(evidenceDir, alias.name, 'State');
-      if (existsSync(candidate)) { stateDir = candidate; break; }
-    }
-  }
-
-  if (!stateDir) {
-    const direct = resolve(cwd, project, 'State');
-    if (existsSync(direct)) { stateDir = direct; }
-  }
-
-  if (!stateDir) {
-    console.error(`\n  Could not find State/ directory for project '${project}'.`);
-    console.error(`  Looked in: ${evidenceDir}/*/State/ and ${resolve(cwd, project, 'State')}/`);
-    console.error(`  Run 'kushi state ${project}' first to build State/.\n`);
-    process.exit(1);
-  }
-
-  const child = spawn('pwsh', ['-NoProfile', '-File', scriptPath, '-StateDir', stateDir], {
-    stdio: 'inherit',
-    cwd: resolve(__dirname, '..'),
-  });
-
-  return new Promise((res, rej) => {
-    child.on('close', (code) => {
-      if (code !== 0) rej(new Error(`lint-state exited with code ${code}`));
-      else res();
-    });
-    child.on('error', rej);
-  });
-}
-
-function pickFlag(args, flag) {
-  const idx = args.indexOf(flag);
-  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
-  const prefix = flag + '=';
-  const m = args.find((a) => a.startsWith(prefix));
-  return m ? m.slice(prefix.length) : undefined;
-}
-
-// ── v5.2.0 dispatch helpers ──────────────────────────────────────────────────
-
-async function dispatchHooks(sub, project, extra) {
-  const { spawn } = await import('node:child_process');
-  const { resolve } = await import('node:path');
-  const { fileURLToPath } = await import('node:url');
-  const __dirname = fileURLToPath(new URL('.', import.meta.url));
-  const invokeHooks = resolve(__dirname, '..', 'plugin', 'skills', '_shared', 'Invoke-Hooks.ps1');
-
-  if (sub === 'list') {
-    // List hooks from .kushi/hooks.yml
-    const { existsSync, readFileSync } = await import('node:fs');
-    const hooksYml = resolve(process.cwd(), project, '.kushi', 'hooks.yml');
-    if (!existsSync(hooksYml)) {
-      console.log(`\n  No hooks configured for '${project}'. Create ${hooksYml} to add hooks.\n`);
-      return;
-    }
-    console.log(`\n  Hooks for '${project}' (${hooksYml}):\n`);
-    console.log(readFileSync(hooksYml, 'utf8'));
-  } else if (sub === 'test') {
-    const event = extra[0] || 'post-pull';
-    const script = `
-      $payload = @{ project = '${project}'; source = 'test'; success = $true; duration_ms = 0; event = '${event}' }
-      & '${invokeHooks.replace(/\\/g, '\\\\')}' -ProjectRoot '${resolve(process.cwd(), project).replace(/\\/g, '\\\\')}' -Event '${event}' -Payload $payload
-    `;
-    const child = spawn('pwsh', ['-NoProfile', '-Command', script], { stdio: 'inherit' });
-    return new Promise((res, rej) => {
-      child.on('close', (code) => { if (code !== 0) rej(new Error(`hooks test exited ${code}`)); else res(); });
-      child.on('error', rej);
-    });
-  }
-}
-
-async function dispatchExplain(topic) {
-  const { resolve } = await import('node:path');
-  const { existsSync, readFileSync } = await import('node:fs');
-  const { fileURLToPath } = await import('node:url');
-  const __dirname = fileURLToPath(new URL('.', import.meta.url));
-  const repoRoot = resolve(__dirname, '..');
-  const instructionsDir = resolve(repoRoot, 'plugin', 'instructions');
-
-  const topicMap = {
-    contradictions: 'living-wiki.instructions.md',
-    conflicts: 'living-wiki.instructions.md',
-    refresh: 'parallel-execution.instructions.md',
-    pull: 'parallel-execution.instructions.md',
-    state: 'living-wiki.instructions.md',
-    'build-state': 'living-wiki.instructions.md',
-    wiki: 'living-wiki.instructions.md',
-    hooks: 'hooks.instructions.md',
-    events: 'hooks.instructions.md',
-    webhooks: 'hooks.instructions.md',
-    parallel: 'parallel-execution.instructions.md',
-    workers: 'parallel-execution.instructions.md',
-    otel: 'otel.instructions.md',
-    telemetry: 'otel.instructions.md',
-    tracing: 'otel.instructions.md',
-    csc: 'comprehensive-structured-capture.instructions.md',
-    capture: 'comprehensive-structured-capture.instructions.md',
-    graph: 'entity-graph.instructions.md',
-    entities: 'entity-graph.instructions.md',
-    workiq: 'workiq-only.instructions.md',
-    schema: 'schema-evolve.instructions.md',
-    conventions: 'schema-evolve.instructions.md',
-    remember: 'schema-evolve.instructions.md',
-    install: 'multi-host-install.instructions.md',
-    setup: 'multi-host-install.instructions.md',
-    evals: 'skill-evals.instructions.md',
-  };
-
-  const key = Object.keys(topicMap).find(k => topic.toLowerCase().includes(k));
-  if (!key) {
-    console.log(`\n  Topic not found: "${topic}"\n`);
-    console.log('  Available topics:', Object.keys(topicMap).filter((v, i, a) => a.indexOf(v) === i).join(', '));
-    console.log('');
-    return;
-  }
-
-  const docFile = resolve(instructionsDir, topicMap[key]);
-  if (!existsSync(docFile)) {
-    console.error(`  Doctrine file missing: ${topicMap[key]}`);
-    process.exit(1);
-  }
-
-  const content = readFileSync(docFile, 'utf8');
-  const lines = content.split('\n').slice(0, 40);
-  console.log(`\n  📖 Topic: ${key} → ${topicMap[key]}\n`);
-  console.log(lines.join('\n'));
-  console.log(`\n  ... (full doctrine at: plugin/instructions/${topicMap[key]})\n`);
-}
-
-async function dispatchRemember(rule) {
-  console.log(`\n  ✅ Rule noted: "${rule}"`);
-  console.log('  To persist this rule, run schema-evolve from within a project context:');
-  console.log('    @Kushi remember ' + rule);
-  console.log('  This will write to Evidence/<alias>/State/CLAUDE.md\n');
-}
+#!/usr/bin/env node
+
+import { main } from '../src/main.mjs';
+import { runMultiHost } from '../src/multi-host.mjs';
+
+const args = process.argv.slice(2);
+
+// ── bare invocation (v5.4.0+) ────────────────────────────────────────────────
+// v5.4.1: on an interactive TTY, auto-launch the setup wizard (matches the
+// ergonomics of `npx create-*`). Non-TTY (CI, scripts, piped stdin) and the
+// explicit KUSHI_SKIP_WELCOME=1 still print the welcome card and exit 0, so
+// nothing is installed by side-effect.
+if (args.length === 0) {
+  const forceWelcome = process.env.KUSHI_SKIP_WELCOME === '1';
+  const forceWizard  = process.env.KUSHI_FORCE_WIZARD === '1';
+  const interactive  = forceWizard || (process.stdin.isTTY && !forceWelcome);
+  if (interactive) {
+    const { runSetupWizard } = await import('../src/setup-wizard.mjs');
+    await runSetupWizard({ args: [] });
+    process.exit(0);
+  }
+  await printWelcome();
+  process.exit(0);
+}
+
+// ── doctor verb (v5.4.0+) ───────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'doctor') {
+  const { spawnSync } = await import('node:child_process');
+  const pathMod = await import('node:path');
+  const urlMod = await import('node:url');
+  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
+  const script = pathMod.resolve(here, '..', 'plugin', 'skills', 'doctor', 'doctor.ps1');
+  const psArgs = ['-NoProfile', '-File', script];
+  if (args.includes('--json')) psArgs.push('-Json');
+  if (args.includes('--strict')) psArgs.push('-Strict');
+  const r = spawnSync('pwsh', psArgs, { stdio: 'inherit' });
+  process.exit(r.status ?? 1);
+}
+
+// ── setup-wizard flag (v5.4.0+) ─────────────────────────────────────────────
+if (args.includes('--setup-wizard')) {
+  const { runSetupWizard } = await import('../src/setup-wizard.mjs');
+  await runSetupWizard({ args });
+  process.exit(0);
+}
+
+async function printWelcome() {
+  const pathMod = await import('node:path');
+  const urlMod = await import('node:url');
+  const fsMod = await import('node:fs');
+  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
+  const repoRoot = pathMod.resolve(here, '..');
+  let version = 'unknown';
+  try { version = JSON.parse(fsMod.readFileSync(pathMod.join(repoRoot, 'package.json'), 'utf-8')).version; } catch {}
+  let skillCount = 0;
+  try {
+    const skillsDir = pathMod.join(repoRoot, 'plugin', 'skills');
+    skillCount = fsMod.readdirSync(skillsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.startsWith('_'))
+      .length;
+  } catch {}
+  console.log(`
+  kushi v${version} — multi-source M365 project evidence agent
+
+  (non-interactive shell — nothing was installed)
+
+  First time?         kushi doctor
+  Bootstrap a project: kushi setup <project>
+  Ask a question:      kushi ask <project> "..."
+  Wizard install:      npx kushi-agents --setup-wizard
+  Host install:        npx kushi-agents --clawpilot | --vscode | --all-hosts
+
+  Docs:   https://gim-home.github.io/kushi/
+  Skills: ${skillCount} installed in plugin/skills/
+
+  Run  kushi help  for the full command list.
+`);
+}
+
+// ── skill-authoring verbs (v5.0.4+) ─────────────────────────────────────────
+// Dispatch directly to the skill-creator / skill-checker pwsh scripts.
+const SKILL_VERBS = new Set(['create-skill', 'check-skill', 'optimize-description', 'review-evals']);
+if (args.length > 0 && SKILL_VERBS.has(args[0])) {
+  const verb = args[0];
+  const rest = args.slice(1);
+  await dispatchSkillVerb(verb, rest);
+  process.exit(0);
+}
+
+// ── lint verb (v5.1.0+) ──────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'lint') {
+  if (args.includes('--global')) {
+    const { runGlobalLint } = await import('../src/global-wiki-cli.mjs');
+    await runGlobalLint();
+    process.exit(0);
+  }
+  const project = args[1] || '';
+  if (!project) {
+    console.error('\n  Usage: kushi lint <project>\n         kushi lint --global\n');
+    process.exit(1);
+  }
+  await dispatchLint(project);
+  process.exit(0);
+}
+
+// ── one-shot wiki verb (v5.9.1+) ─────────────────────────────────────────────
+// `kushi wiki` — deterministic do-the-wiki: resolve root, init if missing,
+// print path + status + clickable file:// URL. Idempotent across
+// "create wiki" / "do wiki" / "refresh wiki" / "update wiki".
+if (args.length > 0 && args[0] === 'wiki') {
+  const cliMod = await import('../src/global-wiki-cli.mjs');
+  await cliMod.runWiki();
+  process.exit(0);
+}
+
+// ── global verb (v5.3.0+) ────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'global') {
+  const sub = args[1] || '';
+  const validSubs = ['init', 'status', 'ask', 'lint', 'migrate', 'set-root', 'show-root'];
+  if (!validSubs.includes(sub)) {
+    console.error('\n  Usage: kushi global init                    Scaffold State/ at the resolved root');
+    console.error('         kushi global status                  Show counts + freshness');
+    console.error('         kushi global ask <question>          Ask the global wiki');
+    console.error('         kushi global lint                    Lint the global wiki');
+    console.error('         kushi global show-root               Show how the root path is resolved');
+    console.error('         kushi global set-root <path> [--scope workspace|home]');
+    console.error('                                              Persist root (workspace shared by default,');
+    console.error('                                              falls back to ~/.kushi/config.json)');
+    console.error('         kushi global migrate <new-path>      Copy wiki to a new root + persist setting\n');
+    console.error('  Tip: Set the root to a OneDrive-synced SharePoint folder to share');
+    console.error('       the wiki across a team. See docs/how-to/wiki-on-sharepoint.md.\n');
+    process.exit(1);
+  }
+  const cliMod = await import('../src/global-wiki-cli.mjs');
+  if (sub === 'init') await cliMod.runGlobalInit();
+  else if (sub === 'status') await cliMod.runGlobalStatus();
+  else if (sub === 'ask') await cliMod.runGlobalAsk(args.slice(2).join(' '));
+  else if (sub === 'lint') await cliMod.runGlobalLint();
+  else if (sub === 'migrate') await cliMod.runGlobalMigrate(args[2]);
+  else if (sub === 'set-root') {
+    const scopeIdx = args.indexOf('--scope');
+    const scope = scopeIdx > 0 && args[scopeIdx + 1] ? args[scopeIdx + 1] : null;
+    const target = args.find((a, i) => i >= 2 && !a.startsWith('--') && args[i - 1] !== '--scope');
+    await cliMod.runGlobalSetRoot(target, { scope });
+  }
+  else if (sub === 'show-root') await cliMod.runGlobalShowRoot();
+  process.exit(0);
+}
+
+// ── promote verb (v5.3.0+) ───────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'promote') {
+  const project = args[1] || '';
+  const page = args[2] || '';
+  if (!project || !page) {
+    console.error('\n  Usage: kushi promote <project> <page-path>\n');
+    console.error('  Copies a project State page into the global wiki with provenance metadata.');
+    console.error('  Refuses by default if customer identifiers are detected; pass --force after review.\n');
+    process.exit(1);
+  }
+  const force = args.includes('--force');
+  const { runPromote } = await import('../src/global-wiki-cli.mjs');
+  await runPromote(project, page, { force });
+  process.exit(0);
+}
+
+// ── hooks verb (v5.2.0+) ─────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'hooks') {
+  const sub = args[1] || '';
+  const project = args[2] || '';
+  if (!sub || !project || !['list', 'test'].includes(sub)) {
+    console.error('\n  Usage: kushi hooks list <project>\n         kushi hooks test <project> <event>\n');
+    process.exit(1);
+  }
+  await dispatchHooks(sub, project, args.slice(3));
+  process.exit(0);
+}
+
+// ── explain verb (v5.2.0+) ───────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'explain') {
+  const topic = args.slice(1).join(' ');
+  if (!topic) {
+    console.error('\n  Usage: kushi explain <topic>\n\n  Available topics: contradictions, refresh, state, hooks, parallel, otel, csc, graph, workiq, schema, install, evals\n');
+    process.exit(1);
+  }
+  await dispatchExplain(topic);
+  process.exit(0);
+}
+
+// ── remember verb (v5.2.0+) ──────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'remember') {
+  const rule = args.slice(1).join(' ');
+  if (!rule) {
+    console.error('\n  Usage: kushi remember <rule>\n\n  Example: kushi remember "always use Northwind not Healthcare Accelerator"\n');
+    process.exit(1);
+  }
+  await dispatchRemember(rule);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h') || args.includes('-help') || args[0] === 'help') {
+  await printHelp();
+  process.exit(0);
+}
+
+async function printHelp() {
+  const pathMod = await import('node:path');
+  const urlMod = await import('node:url');
+  const fsMod = await import('node:fs');
+  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
+  const repoRoot = pathMod.resolve(here, '..');
+  let version = 'unknown';
+  try { version = JSON.parse(fsMod.readFileSync(pathMod.join(repoRoot, 'package.json'), 'utf-8')).version; } catch {}
+  console.log(`
+Usage:  kushi [COMMAND] [ARGS...]
+        npx kushi-agents [INSTALL OPTIONS]
+
+Kushi v${version} — multi-source M365 project evidence + Q&A agent.
+
+Common Commands:
+  bootstrap <project>        First-time setup for a project (full pull)
+  refresh <project>          Incremental refresh + rebuild State/
+  ask <project> <question>   Cited Q&A over Evidence/ (auto-routes; --file-back to save)
+  status <project>           Show run-log for a project
+  wiki                       Resolve + scaffold + open the global wiki (one-shot)
+  doctor                     Aggregated health check (env, drift, evals, etc.)
+
+Project Commands:
+  state <project>            Re-render State/ from existing Evidence
+  references <project>       Refresh shared references pool from Evidence URLs
+  consolidate <project>      Merge per-user evidence into _Consolidated
+  lint <project>             Run wiki-lint checks on State/
+  promote <project> <page>   Move a project page into the global wiki (with redaction)
+  setup [<project>]          Run the onboarding wizard / fill missing config
+
+Global Wiki Commands:
+  global init                Scaffold ~/.kushi-global/State/ (or KUSHI_GLOBAL_ROOT)
+  global status              Page counts + freshness
+  global ask <question>      Search the global wiki specifically
+  global lint                Privacy + freshness scan
+  global show-root           Show the 4-tier resolution chain
+  global set-root <path>     Persist globalRoot (--scope workspace|home)
+  global migrate <new-path>  Copy State/ to a new root + re-persist
+
+Lifecycle Commands:
+  upgrade                    npm i -g kushi-agents@latest then re-seed assets in cwd
+  uninstall [--keep-config]  Remove <cwd>/.kushi/ (preserves Evidence/, State/)
+
+Authoring Commands:
+  create-skill <name>        Scaffold a new plugin/skills/<name>/ tree
+  check-skill <name|--all>   Lint a skill (or all skills) against the blueprint
+  optimize-description <s>   Rewrite a skill's description per optimizer rules
+  review-evals <skill>       Render an HTML eval-review viewer
+  explain <topic>            Explain a kushi concept (read-only)
+  remember <rule>            Persist a project convention to CLAUDE.md
+  hooks list|test <project>  Inspect or fire hook events
+
+Install (run via npx — first-time / host install):
+  npx kushi-agents --clawpilot     Install to ~/.copilot/m-skills/kushi/
+  npx kushi-agents --vscode        Install to ~/.vscode/chat/skills/kushi/
+  npx kushi-agents --all-hosts     Install to BOTH hosts
+  npx kushi-agents --setup-wizard  Interactive first-run flow
+  npx kushi-agents --uninstall     Cleanly remove host install + skills-metadata entry
+
+  Profile:   --profile core | standard (default) | full
+  Other:     --force, --yes, --no-workspace, --no-settings, --no-instructions, --no-prompt
+  WorkIQ:    --with-workiq | --workiq-path <abs> | --skip-workiq-check
+
+Run 'kushi <command> --help' for more information on a command (where supported).
+Docs: https://gim-home.github.io/kushi/
+
+In VS Code Chat the prefix is "@Kushi". In Clawpilot just say "kushi <verb>".
+`);
+}
+
+
+// ── state / refresh / bootstrap verbs (v5.9.0+) ─────────────────────────────
+// Thin shells that exec the deterministic runners. Keeps `kushi state HCA` etc.
+// runnable from the global bin without users having to know the runner paths.
+if (args.length > 0 && ['state', 'refresh-runner', 'bootstrap-runner', 'discover', 'references'].includes(args[0])) {
+  const verb = args[0];
+  const project = args[1];
+  if (!project) {
+    console.error(`\n  Usage: kushi ${verb} <project> [options]\n`);
+    process.exit(1);
+  }
+  const { spawnSync } = await import('node:child_process');
+  const pathMod = await import('node:path');
+  const urlMod = await import('node:url');
+  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
+  const runnerMap = {
+    state: 'pull-state.mjs',
+    references: 'pull-references.mjs',
+    discover: 'discover.mjs',
+    'refresh-runner': 'refresh.mjs',
+    'bootstrap-runner': 'bootstrap.mjs',
+  };
+  const runner = pathMod.resolve(here, '..', 'plugin', 'runners', runnerMap[verb]);
+  const passthrough = args.slice(2);
+  const r = spawnSync(process.execPath, [runner, '--project', project, ...passthrough], { stdio: 'inherit' });
+  process.exit(r.status ?? 1);
+}
+
+// ── workspace uninstall / upgrade verbs (v5.9.0+) ───────────────────────────
+if (args.length > 0 && args[0] === 'uninstall' && !args.includes('--clawpilot') && !args.includes('--vscode') && !args.includes('--all-hosts')) {
+  // Workspace uninstall: remove .kushi/ from cwd (preserves Evidence/, State/).
+  const fsMod = await import('node:fs');
+  const pathMod = await import('node:path');
+  const dest = pathMod.resolve(process.cwd(), '.kushi');
+  const keepConfig = args.includes('--keep-config');
+  if (!fsMod.existsSync(dest)) {
+    console.error(`\n  No .kushi/ directory found at ${dest}\n`);
+    process.exit(1);
+  }
+  if (keepConfig) {
+    const assetDirs = ['agents', 'instructions', 'prompts', 'skills', 'templates', 'reference-packs', 'lib', 'runners'];
+    let removed = 0;
+    for (const d of assetDirs) {
+      const p = pathMod.join(dest, d);
+      if (fsMod.existsSync(p)) { fsMod.rmSync(p, { recursive: true, force: true }); removed++; }
+    }
+    console.log(`\n  Removed ${removed} asset dir(s) from ${dest} (config/user/ preserved).\n`);
+  } else {
+    fsMod.rmSync(dest, { recursive: true, force: true });
+    console.log(`\n  Removed ${dest}\n  Evidence/ and State/ left untouched.\n`);
+  }
+  process.exit(0);
+}
+
+if (args.length > 0 && args[0] === 'upgrade') {
+  // Upgrade: npm i -g @latest, then re-seed assets in cwd preserving config.
+  const { spawnSync } = await import('node:child_process');
+  console.log('\n  Upgrading kushi-agents globally via npm...\n');
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const r1 = spawnSync(npm, ['install', '-g', 'kushi-agents@latest'], { stdio: 'inherit' });
+  if (r1.status !== 0) {
+    console.error('\n  npm install failed.\n');
+    process.exit(r1.status ?? 1);
+  }
+  console.log('\n  Refreshing assets in cwd (config preserved)...\n');
+  const fsMod = await import('node:fs');
+  if (fsMod.existsSync('.kushi')) {
+    const r2 = spawnSync(npm, ['exec', '--', 'kushi-agents', '--no-prompt', '--force'], { stdio: 'inherit' });
+    process.exit(r2.status ?? 0);
+  } else {
+    console.log('\n  No .kushi/ in cwd — global upgrade complete; cd into a project and run `kushi` to install.\n');
+    process.exit(0);
+  }
+}
+
+// ── multi-host mode (v5.0.2+) ───────────────────────────────────────────────
+// Trigger when the user passes any of: --vscode, --all-hosts, --uninstall.
+// --clawpilot ALONE continues to route through the legacy main.mjs path so
+// the existing target=clawpilot flow stays byte-identical.
+const wantsVscode = args.includes('--vscode');
+const wantsAllHosts = args.includes('--all-hosts');
+const wantsUninstall = args.includes('--uninstall');
+
+if (wantsVscode || wantsAllHosts || wantsUninstall) {
+  const hosts = [];
+  if (args.includes('--clawpilot')) hosts.push('clawpilot');
+  if (wantsVscode) hosts.push('vscode');
+  const all = wantsAllHosts || args.includes('--all');
+
+  runMultiHost({
+    hosts,
+    all,
+    uninstall: wantsUninstall,
+    profile: getFlag('--profile'),
+    includeWorkspace: !args.includes('--no-workspace'),
+    noPrompt: args.includes('--no-prompt'),
+  }).catch((err) => {
+    console.error(`\n  ${err.message}\n`);
+    process.exit(1);
+  });
+} else {
+  let target = getFlag('--target');
+  if (args.includes('--clawpilot')) {
+    if (target && target !== 'clawpilot') {
+      console.error(`\n  Conflicting flags: --target ${target} and --clawpilot.\n`);
+      process.exit(1);
+    }
+    target = 'clawpilot';
+  }
+
+  const options = {
+    force: args.includes('--force'),
+    yes: args.includes('--yes') || args.includes('-y'),
+    noSettings: args.includes('--no-settings'),
+    noInstructions: args.includes('--no-instructions'),
+    noPrompt: args.includes('--no-prompt'),
+    target,
+    profile: getFlag('--profile'),
+    withWorkiq: args.includes('--with-workiq'),
+    workiqPath: getFlag('--workiq-path'),
+    skipWorkiqCheck: args.includes('--skip-workiq-check'),
+  };
+
+  main(options).catch((err) => {
+    console.error(`\n  ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+function getFlag(flag) {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length) {
+    return args[idx + 1];
+  }
+  const prefix = flag + '=';
+  const match = args.find((a) => a.startsWith(prefix));
+  return match ? match.slice(prefix.length) : undefined;
+}
+
+// ── skill-authoring verb dispatch (v5.0.4+) ─────────────────────────────────
+async function dispatchSkillVerb(verb, rest) {
+  const { spawnSync } = await import('node:child_process');
+  const path = await import('node:path');
+  const url = await import('node:url');
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const repoRoot = path.resolve(here, '..');
+  const creatorDir = path.join(repoRoot, 'plugin', 'skills', 'skill-creator');
+  const checkerDir = path.join(repoRoot, 'plugin', 'skills', 'skill-checker');
+
+  let script, scriptArgs = [];
+  switch (verb) {
+    case 'create-skill': {
+      // Usage: kushi create-skill <name> [--type <t>] [--description "<d>"] [--force]
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (!name) {
+        console.error('Usage: kushi-agents create-skill <name> --type <pull|writer|orchestrator|other> --description "USE WHEN ... DO NOT USE FOR ..."');
+        process.exit(1);
+      }
+      const type = pickFlag(rest, '--type') || 'other';
+      const desc = pickFlag(rest, '--description') || `USE WHEN ${name} is invoked. DO NOT USE FOR unrelated tasks.`;
+      script = path.join(creatorDir, 'scaffold.ps1');
+      scriptArgs = ['-Name', name, '-Type', type, '-Description', desc];
+      if (rest.includes('--force')) scriptArgs.push('-Force');
+      if (rest.includes('--dry-run')) scriptArgs.push('-DryRun');
+      break;
+    }
+    case 'check-skill': {
+      // Usage: kushi check-skill <name> | --all  [--retrofit] [--apply]
+      script = path.join(checkerDir, 'check-skill.ps1');
+      const allFlag = rest.includes('--all') || rest.includes('-All');
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (allFlag) scriptArgs.push('-All');
+      else if (name) scriptArgs.push('-Skill', name);
+      else {
+        console.error('Usage: kushi-agents check-skill <name> | --all  [--retrofit] [--apply] [--dry-run]');
+        process.exit(1);
+      }
+      if (rest.includes('--retrofit')) scriptArgs.push('-Retrofit');
+      if (rest.includes('--apply')) scriptArgs.push('-Apply');
+      if (rest.includes('--dry-run')) scriptArgs.push('-DryRun');
+      if (rest.includes('--json')) scriptArgs.push('-Json');
+      break;
+    }
+    case 'optimize-description': {
+      // Usage: kushi optimize-description <skill>
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (!name) {
+        console.error('Usage: kushi-agents optimize-description <skill>');
+        process.exit(1);
+      }
+      script = path.join(checkerDir, 'check-skill.ps1');
+      scriptArgs = ['-Skill', name, '-OptimizeDescription'];
+      break;
+    }
+    case 'review-evals': {
+      // Usage: kushi review-evals <skill>
+      const name = rest.find((a) => !a.startsWith('-'));
+      if (!name) {
+        console.error('Usage: kushi-agents review-evals <skill>');
+        process.exit(1);
+      }
+      script = path.join(checkerDir, 'check-skill.ps1');
+      scriptArgs = ['-Skill', name, '-Review'];
+      break;
+    }
+    default:
+      console.error(`Unknown skill verb: ${verb}`);
+      process.exit(1);
+  }
+
+  const result = spawnSync('pwsh', ['-NoProfile', '-File', script, ...scriptArgs], { stdio: 'inherit' });
+  process.exit(result.status ?? 1);
+}
+
+async function dispatchLint(project) {
+  const { spawn } = await import('node:child_process');
+  const { resolve } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const __dirname = fileURLToPath(new URL('.', import.meta.url));
+  const scriptPath = resolve(__dirname, '..', 'plugin', 'skills', 'lint-state', 'lint.ps1');
+
+  const cwd = process.cwd();
+  const { readdirSync, existsSync } = await import('node:fs');
+  let stateDir = '';
+
+  const evidenceDir = resolve(cwd, project, 'Evidence');
+  if (existsSync(evidenceDir)) {
+    const aliases = readdirSync(evidenceDir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !d.name.startsWith('_'));
+    for (const alias of aliases) {
+      const candidate = resolve(evidenceDir, alias.name, 'State');
+      if (existsSync(candidate)) { stateDir = candidate; break; }
+    }
+  }
+
+  if (!stateDir) {
+    const direct = resolve(cwd, project, 'State');
+    if (existsSync(direct)) { stateDir = direct; }
+  }
+
+  if (!stateDir) {
+    console.error(`\n  Could not find State/ directory for project '${project}'.`);
+    console.error(`  Looked in: ${evidenceDir}/*/State/ and ${resolve(cwd, project, 'State')}/`);
+    console.error(`  Run 'kushi state ${project}' first to build State/.\n`);
+    process.exit(1);
+  }
+
+  const child = spawn('pwsh', ['-NoProfile', '-File', scriptPath, '-StateDir', stateDir], {
+    stdio: 'inherit',
+    cwd: resolve(__dirname, '..'),
+  });
+
+  return new Promise((res, rej) => {
+    child.on('close', (code) => {
+      if (code !== 0) rej(new Error(`lint-state exited with code ${code}`));
+      else res();
+    });
+    child.on('error', rej);
+  });
+}
+
+function pickFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  const prefix = flag + '=';
+  const m = args.find((a) => a.startsWith(prefix));
+  return m ? m.slice(prefix.length) : undefined;
+}
+
+// ── v5.2.0 dispatch helpers ──────────────────────────────────────────────────
+
+async function dispatchHooks(sub, project, extra) {
+  const { spawn } = await import('node:child_process');
+  const { resolve } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const __dirname = fileURLToPath(new URL('.', import.meta.url));
+  const invokeHooks = resolve(__dirname, '..', 'plugin', 'skills', '_shared', 'Invoke-Hooks.ps1');
+
+  if (sub === 'list') {
+    // List hooks from .kushi/hooks.yml
+    const { existsSync, readFileSync } = await import('node:fs');
+    const hooksYml = resolve(process.cwd(), project, '.kushi', 'hooks.yml');
+    if (!existsSync(hooksYml)) {
+      console.log(`\n  No hooks configured for '${project}'. Create ${hooksYml} to add hooks.\n`);
+      return;
+    }
+    console.log(`\n  Hooks for '${project}' (${hooksYml}):\n`);
+    console.log(readFileSync(hooksYml, 'utf8'));
+  } else if (sub === 'test') {
+    const event = extra[0] || 'post-pull';
+    const script = `
+      $payload = @{ project = '${project}'; source = 'test'; success = $true; duration_ms = 0; event = '${event}' }
+      & '${invokeHooks.replace(/\\/g, '\\\\')}' -ProjectRoot '${resolve(process.cwd(), project).replace(/\\/g, '\\\\')}' -Event '${event}' -Payload $payload
+    `;
+    const child = spawn('pwsh', ['-NoProfile', '-Command', script], { stdio: 'inherit' });
+    return new Promise((res, rej) => {
+      child.on('close', (code) => { if (code !== 0) rej(new Error(`hooks test exited ${code}`)); else res(); });
+      child.on('error', rej);
+    });
+  }
+}
+
+async function dispatchExplain(topic) {
+  const { resolve } = await import('node:path');
+  const { existsSync, readFileSync } = await import('node:fs');
+  const { fileURLToPath } = await import('node:url');
+  const __dirname = fileURLToPath(new URL('.', import.meta.url));
+  const repoRoot = resolve(__dirname, '..');
+  const instructionsDir = resolve(repoRoot, 'plugin', 'instructions');
+
+  const topicMap = {
+    contradictions: 'living-wiki.instructions.md',
+    conflicts: 'living-wiki.instructions.md',
+    refresh: 'parallel-execution.instructions.md',
+    pull: 'parallel-execution.instructions.md',
+    state: 'living-wiki.instructions.md',
+    'build-state': 'living-wiki.instructions.md',
+    wiki: 'living-wiki.instructions.md',
+    hooks: 'hooks.instructions.md',
+    events: 'hooks.instructions.md',
+    webhooks: 'hooks.instructions.md',
+    parallel: 'parallel-execution.instructions.md',
+    workers: 'parallel-execution.instructions.md',
+    otel: 'otel.instructions.md',
+    telemetry: 'otel.instructions.md',
+    tracing: 'otel.instructions.md',
+    csc: 'comprehensive-structured-capture.instructions.md',
+    capture: 'comprehensive-structured-capture.instructions.md',
+    graph: 'entity-graph.instructions.md',
+    entities: 'entity-graph.instructions.md',
+    workiq: 'workiq-only.instructions.md',
+    schema: 'schema-evolve.instructions.md',
+    conventions: 'schema-evolve.instructions.md',
+    remember: 'schema-evolve.instructions.md',
+    install: 'multi-host-install.instructions.md',
+    setup: 'multi-host-install.instructions.md',
+    evals: 'skill-evals.instructions.md',
+  };
+
+  const key = Object.keys(topicMap).find(k => topic.toLowerCase().includes(k));
+  if (!key) {
+    console.log(`\n  Topic not found: "${topic}"\n`);
+    console.log('  Available topics:', Object.keys(topicMap).filter((v, i, a) => a.indexOf(v) === i).join(', '));
+    console.log('');
+    return;
+  }
+
+  const docFile = resolve(instructionsDir, topicMap[key]);
+  if (!existsSync(docFile)) {
+    console.error(`  Doctrine file missing: ${topicMap[key]}`);
+    process.exit(1);
+  }
+
+  const content = readFileSync(docFile, 'utf8');
+  const lines = content.split('\n').slice(0, 40);
+  console.log(`\n  📖 Topic: ${key} → ${topicMap[key]}\n`);
+  console.log(lines.join('\n'));
+  console.log(`\n  ... (full doctrine at: plugin/instructions/${topicMap[key]})\n`);
+}
+
+async function dispatchRemember(rule) {
+  console.log(`\n  ✅ Rule noted: "${rule}"`);
+  console.log('  To persist this rule, run schema-evolve from within a project context:');
+  console.log('    @Kushi remember ' + rule);
+  console.log('  This will write to Evidence/<alias>/State/CLAUDE.md\n');
+}