phronesis 1.0.0

package/src/cli.js

@@ -0,0 +1,1893 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { DEFAULT_DOMAIN } from './layout.js';
+import { COVERAGE_FLOOR_RANGE, MAX_K, QUALITY_FLOOR_RANGE } from './skills-bump.js';
+
+const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+if (nodeMajor < 18) {
+  console.error(`phronesis requires Node.js 18 or later. You're running ${process.versions.node}.`);
+  process.exit(1);
+}
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === '--help' || cmd === '-h') return { command: 'help' };
+  if (cmd === '--version' || cmd === '-v') return { command: 'version' };
+  if (cmd === 'init') return parseInitArgs(rest);
+  if (cmd === 'export') return parseExportArgs(rest);
+  if (cmd === 'validate') return parseValidateArgs(rest);
+  if (cmd === 'links') return parseLinksArgs(rest);
+  if (cmd === 'event') return parseEventArgs(rest);
+  if (cmd === 'events') return parseEventsArgs(rest);
+  if (cmd === 'act') return parseActArgs(rest);
+  if (cmd === 'ingest') return parseIngestArgs(rest);
+  if (cmd === 'compile') return parseCompileArgs(rest);
+  if (cmd === 'active-context') return parseActiveContextArgs(rest);
+  if (cmd === 'registry') return parseRegistryArgs(rest);
+  if (cmd === 'skills') return parseSkillsArgs(rest);
+  if (cmd === 'hooks') return parseHooksArgs(rest);
+  if (cmd === 'adapter') return parseAdapterArgs(rest);
+  if (cmd === 'guard') return parseGuardArgs(rest);
+  if (cmd === 'search') return parseRetrievalArgs(rest, 'search');
+  if (cmd === 'query') return parseRetrievalArgs(rest, 'query');
+  if (cmd === 'lint') return parseLintArgs(rest);
+  if (cmd === 'doctor') return parseDoctorArgs(rest);
+  if (cmd === 'due') return parseDueArgs(rest);
+  if (cmd === 'eval') return parseEvalArgs(rest);
+  if (cmd === 'index') return parseIndexArgs(rest);
+  return { command: 'unknown', input: cmd };
+}
+
+function parseInitArgs(args) {
+  let dir;
+  let force = false;
+  // domain + the minimal-profile value flags (core-0039). Each accepts `--flag value` and `--flag=value`.
+  const VALUE_FLAGS = ['domain', 'name', 'role', 'company', 'working-style'];
+  const values = {};
+
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') return { command: 'init-help' };
+    if (a === '--force' || a === '-f') {
+      force = true;
+      continue;
+    }
+    let matched = false;
+    for (const f of VALUE_FLAGS) {
+      if (a === `--${f}`) {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith('--')) return { command: 'invalid', error: `Missing value for --${f}` };
+        values[f] = v;
+        i += 1;
+        matched = true;
+        break;
+      }
+      if (a.startsWith(`--${f}=`)) {
+        values[f] = a.slice(`--${f}=`.length);
+        matched = true;
+        break;
+      }
+    }
+    if (matched) continue;
+    if (a.startsWith('-')) {
+      return { command: 'invalid', error: `Unknown option for init: ${a}` };
+    }
+    if (dir) return { command: 'invalid', error: 'init accepts at most one <dir> argument.' };
+    dir = a;
+  }
+
+  return {
+    command: 'init',
+    dir,
+    force,
+    domain: values.domain,
+    name: values.name,
+    role: values.role,
+    company: values.company,
+    workingStyle: values['working-style'],
+  };
+}
+
+function parseExportArgs(args) {
+  let dir;
+  let out;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') return { command: 'export-help' };
+    if (a === '--out' || a === '-o') {
+      out = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--out=')) {
+      out = a.slice('--out='.length);
+      continue;
+    }
+    if (a.startsWith('-')) {
+      return { command: 'invalid', error: `Unknown option for export: ${a}` };
+    }
+    if (dir) return { command: 'invalid', error: 'export accepts at most one <dir> argument.' };
+    dir = a;
+  }
+
+  return { command: 'export', dir, out };
+}
+
+function parseValidateArgs(args) {
+  let dir;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') return { command: 'validate-help' };
+    if (a.startsWith('-')) {
+      return { command: 'invalid', error: `Unknown option for validate: ${a}` };
+    }
+    if (dir) return { command: 'invalid', error: 'validate accepts at most one <dir> argument.' };
+    dir = a;
+  }
+  return { command: 'validate', dir };
+}
+
+function parseLinksArgs(args) {
+  let object;
+  let dir;
+  let hops = 2;
+  let direction = 'both';
+  let json = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') return { command: 'links-help' };
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a === '--dir') {
+      dir = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--dir=')) {
+      dir = a.slice('--dir='.length);
+      continue;
+    }
+    if (a === '--hops') {
+      hops = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--hops=')) {
+      hops = a.slice('--hops='.length);
+      continue;
+    }
+    if (a === '--direction') {
+      direction = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--direction=')) {
+      direction = a.slice('--direction='.length);
+      continue;
+    }
+    if (a.startsWith('-')) {
+      return { command: 'invalid', error: `Unknown option for links: ${a}` };
+    }
+    if (object) return { command: 'invalid', error: 'links accepts at most one <object> argument.' };
+    object = a;
+  }
+
+  const hopsNum = Number(hops);
+  if (!Number.isInteger(hopsNum) || hopsNum < 0) {
+    return { command: 'invalid', error: `links --hops must be a non-negative integer (got "${hops}").` };
+  }
+  if (!['out', 'in', 'both'].includes(direction)) {
+    return { command: 'invalid', error: `links --direction must be out | in | both (got "${direction}").` };
+  }
+
+  return { command: 'links', object, dir, hops: hopsNum, direction, json };
+}
+
+// Compact option parser shared by the event commands (`--name value` / `--name=value` for
+// `values`, presence flags for `flags`, the rest positional). The older parsers above predate
+// it and stay hand-rolled; new multi-option commands use this to avoid the per-flag boilerplate.
+function parseOptions(args, { values = [], flags = [] } = {}) {
+  const valueSet = new Set(values);
+  const flagSet = new Set(flags);
+  const out = { values: {}, flags: {}, positionals: [] };
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') return { help: true };
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const name = eq === -1 ? a.slice(2) : a.slice(2, eq);
+      if (flagSet.has(name)) {
+        out.flags[name] = true;
+        continue;
+      }
+      if (valueSet.has(name)) {
+        if (eq === -1) {
+          // A bare `--name` at the end, or one followed by another `--option`, is a missing
+          // value — not "consume the next token". Swallowing it silently mislabels the next
+          // flag as this one's value and surfaces a misleading downstream error.
+          const next = args[i + 1];
+          if (next === undefined || next.startsWith('--')) {
+            return { error: `Missing value for --${name}` };
+          }
+          out.values[name] = next;
+          i += 1;
+        } else {
+          out.values[name] = a.slice(eq + 1);
+        }
+        continue;
+      }
+      return { error: `Unknown option: ${a}` };
+    }
+    if (a.startsWith('-') && a !== '-') return { error: `Unknown option: ${a}` };
+    out.positionals.push(a);
+  }
+  return out;
+}
+
+function parseEventArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'event-help' };
+  if (sub === 'emit') {
+    const p = parseOptions(rest, { values: ['session', 'payload', 'actor', 'surface', 'dir'] });
+    if (p.help) return { command: 'event-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for event emit.` };
+    if (p.positionals.length > 1) {
+      return { command: 'invalid', error: 'event emit takes one <type> argument.' };
+    }
+    return {
+      command: 'event-emit',
+      type: p.positionals[0],
+      session: p.values.session,
+      payload: p.values.payload,
+      actor: p.values.actor,
+      surface: p.values.surface,
+      dir: p.values.dir,
+    };
+  }
+  if (sub === 'tail') {
+    const p = parseOptions(rest, { values: ['type', 'since', 'dir'], flags: ['follow'] });
+    if (p.help) return { command: 'event-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for event tail.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'event tail takes no positional arguments.' };
+    }
+    return {
+      command: 'event-tail',
+      type: p.values.type,
+      since: p.values.since,
+      dir: p.values.dir,
+      follow: Boolean(p.flags.follow),
+    };
+  }
+  return { command: 'invalid', error: `Unknown event subcommand: ${sub} (expected: emit | tail).` };
+}
+
+// `act` is plumbing, not porcelain (ontology.md:163): parse-only here — semantic action
+// inputs travel exclusively inside --json (a `--title`-style flag is an unknown option
+// and is rejected); flags carry execution context only. The approval signal is env
+// (PHRONESIS_APPROVAL_SOURCE), set by an approving adapter — deliberately not a flag.
+function parseActArgs(args) {
+  const p = parseOptions(args, { values: ['json', 'session', 'domain', 'actor', 'surface', 'dir', 'invocation-id'] });
+  if (p.help) return { command: 'act-help' };
+  if (p.error) return { command: 'invalid', error: `${p.error} for act.` };
+  if (p.positionals.length > 1) {
+    return { command: 'invalid', error: 'act takes one <type> argument (semantic inputs go inside --json).' };
+  }
+  const parsed = {
+    command: 'act',
+    type: p.positionals[0],
+    json: p.values.json,
+    session: p.values.session,
+    domain: p.values.domain,
+    actor: p.values.actor,
+    surface: p.values.surface,
+    dir: p.values.dir,
+  };
+  if (p.values['invocation-id'] !== undefined) parsed.invocationId = p.values['invocation-id'];
+  return parsed;
+}
+
+function parseIngestArgs(args) {
+  const p = parseOptions(args, {
+    values: ['domain', 'trust', 'lane', 'dir', 'source-connector', 'source-external-id', 'source-timestamp', 'title', 'slug'],
+    flags: ['paste', 'json'],
+  });
+  if (p.help) return { command: 'ingest-help' };
+  if (p.error) return { command: 'invalid', error: `${p.error} for ingest.` };
+  if (p.positionals.length > 1) {
+    return { command: 'invalid', error: 'ingest takes one <url|file|dir> argument, or --paste / - for stdin.' };
+  }
+  return {
+    command: 'ingest',
+    source: p.positionals[0],
+    paste: Boolean(p.flags.paste),
+    domain: p.values.domain,
+    trust: p.values.trust,
+    lane: p.values.lane || 'inbox',
+    dir: p.values.dir,
+    json: Boolean(p.flags.json),
+    sourceConnector: p.values['source-connector'],
+    sourceExternalId: p.values['source-external-id'],
+    sourceTimestamp: p.values['source-timestamp'],
+    title: p.values.title,
+    slug: p.values.slug,
+  };
+}
+
+// `compile accept|reject <draft>` — the operator review primitives (core-0017 H9). The
+// draft path is the one positional; execution context (session/actor/surface/dir) and the
+// approval signal (env, like act) ride flags/env, never the payload.
+function parseCompileArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'compile-help' };
+  // accept/reject are operator-driven by contract — no --actor (the events are always
+  // actor: operator; the approval signal rides env PHRONESIS_APPROVAL_SOURCE, like act).
+  if (sub === 'accept') {
+    const p = parseOptions(rest, { values: ['session', 'surface', 'dir'] });
+    if (p.help) return { command: 'compile-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for compile accept.` };
+    if (p.positionals.length !== 1) {
+      return { command: 'invalid', error: 'compile accept takes one <draft_path> argument.' };
+    }
+    return {
+      command: 'compile-accept',
+      draftPath: p.positionals[0],
+      session: p.values.session,
+      surface: p.values.surface,
+      dir: p.values.dir,
+    };
+  }
+  if (sub === 'reject') {
+    const p = parseOptions(rest, { values: ['session', 'reason', 'surface', 'dir'] });
+    if (p.help) return { command: 'compile-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for compile reject.` };
+    if (p.positionals.length !== 1) {
+      return { command: 'invalid', error: 'compile reject takes one <draft_path> argument.' };
+    }
+    return {
+      command: 'compile-reject',
+      draftPath: p.positionals[0],
+      reason: p.values.reason,
+      session: p.values.session,
+      surface: p.values.surface,
+      dir: p.values.dir,
+    };
+  }
+  if (sub === 'review') {
+    const p = parseOptions(rest, {
+      values: ['domain', 'session', 'surface', 'dir', 'rationale'],
+      flags: ['approve-all', 'resume', 'json'],
+    });
+    if (p.help) return { command: 'compile-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for compile review.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'compile review takes no positional arguments (use --domain, --approve-all, --resume).' };
+    }
+    return {
+      command: 'compile-review',
+      domain: p.values.domain,
+      session: p.values.session,
+      surface: p.values.surface,
+      dir: p.values.dir,
+      rationale: p.values.rationale,
+      approveAll: Boolean(p.flags['approve-all']),
+      resume: Boolean(p.flags.resume),
+      json: Boolean(p.flags.json),
+    };
+  }
+  return { command: 'invalid', error: `Unknown compile subcommand: ${sub} (expected: accept | reject | review).` };
+}
+
+// `active-context refresh --domain <slug>` — regenerate a domain's tracked projection
+// (core-0017 H5). The post-compile hook shells out to it; operators rarely call it directly.
+function parseActiveContextArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'active-context-help' };
+  if (sub === 'refresh') {
+    const p = parseOptions(rest, { values: ['domain', 'dir'], flags: ['json'] });
+    if (p.help) return { command: 'active-context-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for active-context refresh.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'active-context refresh takes no positional arguments.' };
+    }
+    return {
+      command: 'active-context-refresh',
+      domain: p.values.domain,
+      dir: p.values.dir,
+      json: Boolean(p.flags.json),
+    };
+  }
+  return { command: 'invalid', error: `Unknown active-context subcommand: ${sub} (expected: refresh).` };
+}
+
+function parseRegistryArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'registry-help' };
+  if (sub === 'status') {
+    const p = parseOptions(rest, { values: ['dir'], flags: ['json'] });
+    if (p.help) return { command: 'registry-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for registry status.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'registry status takes no positional arguments.' };
+    }
+    return { command: 'registry-status', dir: p.values.dir, json: Boolean(p.flags.json) };
+  }
+  return { command: 'invalid', error: `Unknown registry subcommand: ${sub} (expected: status).` };
+}
+
+function parseSkillsArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'skills-help' };
+  if (sub === 'status') {
+    const p = parseOptions(rest, { values: ['dir'], flags: ['json'] });
+    if (p.help) return { command: 'skills-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for skills status.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'skills status takes no positional arguments.' };
+    }
+    return { command: 'skills-status', dir: p.values.dir, json: Boolean(p.flags.json) };
+  }
+  if (sub === 'bump') {
+    const p = parseOptions(rest, {
+      values: ['to', 'repo', 'k', 'coverage-floor', 'quality-floor', 'rationale', 'accepted-by', 'judge-model', 'goldens-dir', 'domain'],
+      flags: ['accept-regression', 'rebaseline', 'shape-change', 'json'],
+    });
+    if (p.help) return { command: 'skills-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for skills bump.` };
+    if (p.positionals.length !== 1) {
+      return { command: 'invalid', error: 'skills bump takes exactly one skill name: phronesis skills bump <skill> --to <pin>.' };
+    }
+    if (!p.values.to) {
+      return { command: 'invalid', error: 'skills bump requires --to <model_id>@<date> (the proposed prompt_pin).' };
+    }
+    let k;
+    if (p.values.k !== undefined) {
+      k = Number(p.values.k);
+      if (!Number.isInteger(k) || k < 1) {
+        return { command: 'invalid', error: '--k must be a positive integer.' };
+      }
+      if (k > MAX_K) {
+        return { command: 'invalid', error: `--k must not exceed ${MAX_K} — each run is k × goldens model+judge calls; a larger value is almost always a typo.` };
+      }
+    }
+    const coverageFloor = p.values['coverage-floor'] !== undefined ? Number(p.values['coverage-floor']) : undefined;
+    const qualityFloor = p.values['quality-floor'] !== undefined ? Number(p.values['quality-floor']) : undefined;
+    if (coverageFloor !== undefined && (!Number.isFinite(coverageFloor) || coverageFloor < COVERAGE_FLOOR_RANGE[0] || coverageFloor > COVERAGE_FLOOR_RANGE[1])) {
+      return { command: 'invalid', error: `--coverage-floor must be a number within [${COVERAGE_FLOOR_RANGE.join(', ')}] (a warranted-capture hit-rate); a negative floor would disable the coverage axis.` };
+    }
+    if (qualityFloor !== undefined && (!Number.isFinite(qualityFloor) || qualityFloor < QUALITY_FLOOR_RANGE[0] || qualityFloor > QUALITY_FLOOR_RANGE[1])) {
+      return { command: 'invalid', error: `--quality-floor must be a number within [${QUALITY_FLOOR_RANGE.join(', ')}] (judge scores are integers 1-5); a floor outside the scale would disable the quality axis.` };
+    }
+    if ((p.flags['accept-regression'] || p.flags.rebaseline) && (p.values.rationale === undefined || String(p.values.rationale).trim() === '')) {
+      const flag = p.flags.rebaseline ? '--rebaseline' : '--accept-regression';
+      return { command: 'invalid', error: `${flag} requires a non-empty --rationale (the audit trail for the escape hatch).` };
+    }
+    return {
+      command: 'skills-bump',
+      skill: p.positionals[0],
+      to: p.values.to,
+      repo: p.values.repo,
+      k,
+      coverageFloor,
+      qualityFloor,
+      rationale: p.values.rationale,
+      acceptedBy: p.values['accepted-by'],
+      judgeModel: p.values['judge-model'],
+      goldensDir: p.values['goldens-dir'],
+      domain: p.values.domain,
+      acceptRegression: Boolean(p.flags['accept-regression']),
+      rebaseline: Boolean(p.flags.rebaseline),
+      shapeChange: Boolean(p.flags['shape-change']),
+      json: Boolean(p.flags.json),
+    };
+  }
+  return { command: 'invalid', error: `Unknown skills subcommand: ${sub} (expected: status, bump).` };
+}
+
+function parseEvalArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'eval-help' };
+  if (sub === 'view') {
+    const p = parseOptions(rest, {
+      values: ['repo', 'skill', 'goldens-dir', 'port', 'host'],
+      flags: ['json', 'no-serve'],
+    });
+    if (p.help) return { command: 'eval-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for eval view.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'eval view takes no positional arguments (use --skill <name>).' };
+    }
+    let port;
+    if (p.values.port !== undefined) {
+      port = Number(p.values.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        return { command: 'invalid', error: '--port must be an integer in 0..65535.' };
+      }
+    }
+    return {
+      command: 'eval-view',
+      repo: p.values.repo,
+      skill: p.values.skill,
+      goldensDir: p.values['goldens-dir'],
+      port,
+      host: p.values.host,
+      json: Boolean(p.flags.json),
+      serve: !p.flags['no-serve'],
+    };
+  }
+  return { command: 'invalid', error: `Unknown eval subcommand: ${sub} (expected: view).` };
+}
+
+function parseHooksArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'hooks-help' };
+  if (sub === 'due-check') {
+    const p = parseOptions(rest, { values: ['session', 'dir', 'actor', 'surface'] });
+    if (p.help) return { command: 'hooks-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for hooks due-check.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'hooks due-check takes no positional arguments.' };
+    }
+    return {
+      command: 'hooks-due-check',
+      session: p.values.session,
+      dir: p.values.dir,
+      actor: p.values.actor,
+      surface: p.values.surface,
+    };
+  }
+  if (sub === 'sweep-status') {
+    const p = parseOptions(rest, { values: ['session', 'dir'], flags: ['json'] });
+    if (p.help) return { command: 'hooks-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for hooks sweep-status.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'hooks sweep-status takes no positional arguments.' };
+    }
+    return {
+      command: 'hooks-sweep-status',
+      session: p.values.session,
+      dir: p.values.dir,
+      json: Boolean(p.flags.json),
+    };
+  }
+  if (sub === 'skill-start') {
+    const p = parseOptions(rest, { values: ['dir', 'payload'] });
+    if (p.help) return { command: 'hooks-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for hooks skill-start.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'hooks skill-start takes no positional arguments.' };
+    }
+    return { command: 'hooks-skill-start', dir: p.values.dir, payload: p.values.payload };
+  }
+  if (sub === 'skill-complete') {
+    const p = parseOptions(rest, { values: ['session', 'dir', 'payload', 'boundary-event'], flags: ['json'] });
+    if (p.help) return { command: 'hooks-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for hooks skill-complete.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'hooks skill-complete takes no positional arguments.' };
+    }
+    return {
+      command: 'hooks-skill-complete',
+      session: p.values.session,
+      dir: p.values.dir,
+      payload: p.values.payload,
+      boundaryEvent: p.values['boundary-event'],
+      json: Boolean(p.flags.json),
+    };
+  }
+  if (sub === 'skill-abandon') {
+    const p = parseOptions(rest, { values: ['dir', 'payload'], flags: ['json'] });
+    if (p.help) return { command: 'hooks-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for hooks skill-abandon.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'hooks skill-abandon takes no positional arguments.' };
+    }
+    return {
+      command: 'hooks-skill-abandon',
+      dir: p.values.dir,
+      payload: p.values.payload,
+      json: Boolean(p.flags.json),
+    };
+  }
+  if (sub === 'skill-sweep-stale') {
+    const p = parseOptions(rest, { values: ['session', 'dir'], flags: ['json'] });
+    if (p.help) return { command: 'hooks-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for hooks skill-sweep-stale.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'hooks skill-sweep-stale takes no positional arguments.' };
+    }
+    return {
+      command: 'hooks-skill-sweep-stale',
+      session: p.values.session,
+      dir: p.values.dir,
+      json: Boolean(p.flags.json),
+    };
+  }
+  return {
+    command: 'invalid',
+    error:
+      `Unknown hooks subcommand: ${sub} ` +
+      '(expected: due-check | sweep-status | skill-start | skill-complete | skill-abandon | skill-sweep-stale).',
+  };
+}
+
+// `adapter test <surface>` — the per-surface adapter self-check (specs/tech-stack.md
+// §"Adapter test command"; change 0028 / core-0034). V1 ships `adapter test codex`.
+function parseAdapterArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'adapter-help' };
+  if (sub === 'test') {
+    const p = parseOptions(rest, { values: ['dir', 'domain'], flags: ['json'] });
+    if (p.help) return { command: 'adapter-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for adapter test.` };
+    if (p.positionals.length !== 1) {
+      return { command: 'invalid', error: 'adapter test takes one <surface> argument (V1: codex).' };
+    }
+    return {
+      command: 'adapter-test',
+      surface: p.positionals[0],
+      dir: p.values.dir,
+      domain: p.values.domain,
+      json: Boolean(p.flags.json),
+    };
+  }
+  return { command: 'invalid', error: `Unknown adapter subcommand: ${sub} (expected: test).` };
+}
+
+function parseGuardArgs(args) {
+  const p = parseOptions(args, { values: ['dir', 'session', 'surface', 'actor', 'domain'], flags: ['json'] });
+  if (p.help) return { command: 'guard-help' };
+  if (p.error) return { command: 'invalid', error: `${p.error} for guard.` };
+  if (p.positionals.length) {
+    return { command: 'invalid', error: 'guard takes no positional prompt argument; pass the prompt on stdin.' };
+  }
+  return {
+    command: 'guard',
+    dir: p.values.dir,
+    session: p.values.session,
+    surface: p.values.surface,
+    actor: p.values.actor,
+    domain: p.values.domain,
+    json: Boolean(p.flags.json),
+  };
+}
+
+// search/query share one parser (core-0014 / T5.2): one positional (the query string),
+// scope flags (--domain | --all-domains — contradictory together), --limit, and for
+// query --hops. Semantic defaults (limit 10, hops 1) live in @phronesis/core, not here —
+// omitted flags stay undefined so the library is the single source of the defaults.
+function parseRetrievalArgs(args, which) {
+  const values = ['dir', 'domain', 'limit'];
+  if (which === 'query') values.push('hops');
+  const p = parseOptions(args, { values, flags: ['json', 'all-domains', 'include-artifacts'] });
+  if (p.help) return { command: `${which}-help` };
+  if (p.error) return { command: 'invalid', error: `${p.error} for ${which}.` };
+  if (p.positionals.length > 1) {
+    return { command: 'invalid', error: `${which} takes one quoted <query> argument.` };
+  }
+  if (p.values.domain !== undefined && p.flags['all-domains']) {
+    return { command: 'invalid', error: `${which}: --domain and --all-domains contradict — pick one scope.` };
+  }
+  let limit;
+  if (p.values.limit !== undefined) {
+    limit = Number(p.values.limit);
+    if (!Number.isInteger(limit) || limit < 1) {
+      return { command: 'invalid', error: `${which} --limit must be a positive integer (got "${p.values.limit}").` };
+    }
+  }
+  let hops;
+  if (which === 'query' && p.values.hops !== undefined) {
+    hops = Number(p.values.hops);
+    if (!Number.isInteger(hops) || hops < 0) {
+      return { command: 'invalid', error: `query --hops must be a non-negative integer (got "${p.values.hops}").` };
+    }
+  }
+  const parsed = {
+    command: which,
+    query: p.positionals[0],
+    dir: p.values.dir,
+    domain: p.values.domain,
+    allDomains: Boolean(p.flags['all-domains']),
+    limit,
+    hops,
+    json: Boolean(p.flags.json),
+  };
+  if (p.flags['include-artifacts']) parsed.includeArtifacts = true;
+  return parsed;
+}
+
+function parseIndexArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'index-help' };
+  if (sub === 'rebuild') {
+    const p = parseOptions(rest, { values: ['dir'], flags: ['json'] });
+    if (p.help) return { command: 'index-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for index rebuild.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'index rebuild takes no positional arguments.' };
+    }
+    return { command: 'index-rebuild', dir: p.values.dir, json: Boolean(p.flags.json) };
+  }
+  return { command: 'invalid', error: `Unknown index subcommand: ${sub} (expected: rebuild).` };
+}
+
+function parseLintArgs(args) {
+  const p = parseOptions(args, { values: ['dir', 'domain', 'stale-months'], flags: ['json', 'all-domains'] });
+  if (p.help) return { command: 'lint-help' };
+  if (p.error) return { command: 'invalid', error: `${p.error} for lint.` };
+  if (p.positionals.length) {
+    return { command: 'invalid', error: 'lint takes no positional arguments.' };
+  }
+  if (p.values.domain !== undefined && p.flags['all-domains']) {
+    return { command: 'invalid', error: 'lint: --domain and --all-domains contradict — pick one scope.' };
+  }
+  let staleMonths;
+  if (p.values['stale-months'] !== undefined) {
+    staleMonths = Number(p.values['stale-months']);
+    if (!Number.isInteger(staleMonths) || staleMonths < 1) {
+      return { command: 'invalid', error: `lint --stale-months must be a positive integer (got "${p.values['stale-months']}").` };
+    }
+  }
+  return {
+    command: 'lint',
+    dir: p.values.dir,
+    domain: p.values.domain,
+    allDomains: Boolean(p.flags['all-domains']),
+    staleMonths,
+    json: Boolean(p.flags.json),
+  };
+}
+
+function parseDoctorArgs(args) {
+  const p = parseOptions(args, { values: ['dir'], flags: ['json'] });
+  if (p.help) return { command: 'doctor-help' };
+  if (p.error) return { command: 'invalid', error: `${p.error} for doctor.` };
+  if (p.positionals.length) {
+    return { command: 'invalid', error: 'doctor takes no positional arguments (pass --dir <install>).' };
+  }
+  return { command: 'doctor', dir: p.values.dir, json: Boolean(p.flags.json) };
+}
+
+// `phronesis due [--json]` (pure read of the schedule registry), `phronesis due complete
+// <schedule_id>` (the explicit completion floor), and `phronesis due run <schedule_id>`
+// (operator-invoked deterministic executor). core-0051/core-0058 / change 0042.
+function parseDueArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === 'complete' || sub === 'run') {
+    const p = parseOptions(rest, { values: ['dir'] });
+    if (p.help) return { command: 'due-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for due ${sub}.` };
+    if (p.positionals.length !== 1) {
+      return { command: 'invalid', error: `due ${sub} takes exactly one <schedule_id> (e.g. \`phronesis due ${sub} lint-weekly\`).` };
+    }
+    return { command: sub === 'complete' ? 'due-complete' : 'due-run', scheduleId: p.positionals[0], dir: p.values.dir };
+  }
+  const p = parseOptions(args, { values: ['dir'], flags: ['json'] });
+  if (p.help) return { command: 'due-help' };
+  if (p.error) return { command: 'invalid', error: `${p.error} for due.` };
+  if (p.positionals.length) {
+    return { command: 'invalid', error: `Unknown due subcommand: ${p.positionals[0]} (expected: complete | run, or no subcommand for the overdue list).` };
+  }
+  return { command: 'due', dir: p.values.dir, json: Boolean(p.flags.json) };
+}
+
+function parseEventsArgs(args) {
+  const [sub, ...rest] = args;
+  if (sub === undefined || sub === '--help' || sub === '-h') return { command: 'events-help' };
+  if (sub === 'purge') {
+    const p = parseOptions(rest, { values: ['before', 'dir'], flags: ['archive'] });
+    if (p.help) return { command: 'events-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for events purge.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'events purge takes no positional arguments.' };
+    }
+    return { command: 'events-purge', before: p.values.before, archive: Boolean(p.flags.archive), dir: p.values.dir };
+  }
+  if (sub === 'rotate') {
+    const p = parseOptions(rest, { values: ['dir'] });
+    if (p.help) return { command: 'events-help' };
+    if (p.error) return { command: 'invalid', error: `${p.error} for events rotate.` };
+    if (p.positionals.length) {
+      return { command: 'invalid', error: 'events rotate takes no positional arguments.' };
+    }
+    return { command: 'events-rotate', dir: p.values.dir };
+  }
+  return {
+    command: 'invalid',
+    error: `Unknown events subcommand: ${sub} (expected: purge | rotate).`,
+  };
+}
+
+function showHelp() {
+  console.log(
+    `
+phronesis v${version} — phronesis-grounded workspace architecture
+
+Usage: phronesis <command>
+
+Commands:
+  init [dir]      Create a Phronesis installation (default dir: phronesis-installation)
+  export [dir]    Tar an installation into a portable archive (default dir: current)
+  validate [dir]  Check compiled + codex objects against the ontology contract
+  search <query>  Stage 1 retrieval — BM25 over active-domain compiled/ + shared codex
+  query <query>   Stage 1+2 retrieval — BM25 seeds expanded through typed links, sources cited
+  index <sub>     Maintain the derived machine search index (rebuild)
+  lint             Read-only deterministic workspace health report
+  doctor          Read-only install-health overview (is my install wired?)
+  due [sub]       Show overdue schedule entries; complete or run one
+  links <object>  Walk typed links from an object — the N-hop connected subgraph
+  event <sub>     Emit (emit) or read (tail) the typed event stream
+  events <sub>    Maintain the event stream (purge, rotate)
+  registry <sub>  Show the install's action-type + hook registry (status)
+  skills <sub>    Show the install's skill registry (status)
+  eval <sub>      Local eval data viewer (view) — goldens, scores, candidate output
+  hooks <sub>     Session-boundary hooks: due-check, sweep-status
+  adapter <sub>   Per-surface adapter self-check (test codex)
+  guard           Prompt-submit recall guard (stdin-only)
+  ingest <source> Stage one URL, file, or stdin paste into domain raw/
+
+Options:
+  --help, -h       Show this help
+  --version, -v    Show version number
+
+Run 'phronesis <command> --help' for command options.
+`.trim(),
+  );
+}
+
+function showInitHelp() {
+  console.log(
+    `
+Usage: phronesis init [dir] [--force] [--domain <slug>]
+                      [--name <name>] [--role <role>] [--company <co>] [--working-style <style>]
+
+Creates a three-layer installation at [dir]:
+  codex/             shared principles across all domains (seed + personal)
+  domains/<slug>/    a domain workspace (raw + compiled)
+  skills/  .phronesis/
+
+A minimal operator profile (name + role) fills USER.md and AGENTS.md so a fresh
+install does not load [Name]/[Role] placeholders. On an interactive terminal, a
+missing name/role is prompted; a non-interactive (scripted/CI) init never prompts
+or blocks — it completes and leaves the placeholders.
+
+Options:
+  --force, -f          Replace a non-empty target directory
+  --domain <slug>      Domain workspace to create (default: pm)
+  --name <name>        Operator name (fills USER.md + AGENTS.md §1)
+  --role <role>        Operator role
+  --company <co>       Operator company (USER.md only; optional)
+  --working-style <s>  Operator working style (USER.md only; optional)
+`.trim(),
+  );
+}
+
+function showExportHelp() {
+  console.log(
+    `
+Usage: phronesis export [dir] [--out <file>]
+
+Tars a Phronesis installation into a portable gzip archive. The export is a
+faithful snapshot — plain Markdown plus config, relative symlinks preserved —
+that opens in Obsidian or VS Code with no Phronesis runtime present.
+
+Arguments:
+  dir                The installation to export (default: current directory)
+
+Options:
+  --out, -o <file>   Archive path (default: <dir>.tar.gz beside the installation)
+`.trim(),
+  );
+}
+
+function showValidateHelp() {
+  console.log(
+    `
+Usage: phronesis validate [dir]
+
+Checks every typed object in domains/*/compiled/ and the installation codex/ against
+the ontology frontmatter contract (specs/ontology.md): required fields, enums, dates,
+link vocabulary, and link-target grammar + resolution. Raw sources are not validated.
+
+Exits 0 when the workspace is valid; non-zero with a per-object error report otherwise.
+
+Arguments:
+  dir                The installation to validate (default: current directory)
+`.trim(),
+  );
+}
+
+function showLinksHelp() {
+  console.log(
+    `
+Usage: phronesis links <object> [--dir <install>] [--hops N] [--direction out|in|both] [--json]
+
+Walks typed links (specs/ontology.md) from an object across domains/*/compiled/ and the
+installation codex/, returning the N-hop connected subgraph — Stage 2 retrieval. A
+substrate command: skills and the operator-facing query compose the same walk.
+
+<object> may be an install-relative path, a bare object name, or a {type-dir}/{name} suffix.
+Raw-source and not-yet-compiled (forward) targets appear as terminal leaves.
+
+Arguments:
+  object               The object to walk from
+
+Options:
+  --dir <install>      The installation to read (default: current directory)
+  --hops N             How many hops to walk (default: 2)
+  --direction <d>      Edge directions to follow: out | in | both (default: both)
+  --json               Emit the subgraph as JSON
+`.trim(),
+  );
+}
+
+function showEventHelp() {
+  console.log(
+    `
+Usage:
+  phronesis event emit <type> --session <id> [--payload '<json>'] [--actor <a>] [--surface <s>] [--dir <install>]
+  phronesis event tail [--type <t>] [--since <iso-ts>] [--follow] [--dir <install>]
+
+The universal emission + read path over the typed event stream (specs/event-log.md). Every
+surface and agent shells out to 'event emit'. The installation root is discovered by walking
+up from the current directory to the nearest .phronesis/registry.json; --dir overrides.
+
+emit:
+  <type>             A V1 event type or a connector.<name>.<event> extension. Reserved types
+                     are refused: file.* (the V1.5 daemon's filesystem watch) and outcome.due
+                     (the session-start due-check, 'phronesis hooks due-check').
+  --session <id>     Session the event belongs to (required).
+  --payload '<json>' Event payload object (default {}). Message text / recall query are
+                     dropped unless event_log.capture_message_text is enabled in config.json.
+  --actor <a>        Defaults to $PHRONESIS_ACTOR, else 'agent'.
+  --surface <s>      Defaults to 'cli'.
+
+tail:
+  --type <t>         Only show events of this type.
+  --since <iso-ts>   Only show events at or after this ISO-8601 timestamp.
+  --follow           Stream new events as they are appended.
+`.trim(),
+  );
+}
+
+function showActHelp() {
+  console.log(
+    `
+Usage: phronesis act <type> --json '<payload>' --session <id> [--domain <slug>] [--actor <a>] [--surface <s>] [--invocation-id <id>] [--dir <install>]
+
+The action-type execution floor (specs/ontology.md §"Action type contract") — plumbing,
+not porcelain: skills compose it; it is not a promoted operator verb. One shared core
+runs every action: schema validation, permission gate, action_type.requested/committed
+events, and a staged atomic write that must pass the ontology contract before it lands.
+
+Registered types: log_decision, enrich_person, update_project_state,
+track_commitment, record_outcome, promote_to_codex (handlers: core-0009/0010),
+compile (the agentic quality-gate writer for insight + organization, core-0017 — review
+its untrusted drafts with 'phronesis compile accept|reject'). The install's EFFECTIVE
+table (operator overrides in .phronesis/registry.json action_types) is shown by
+'phronesis registry status'.
+
+  <type>             The action type to run.
+  --json '<payload>' The action's SEMANTIC inputs (title, insight, links, …), schema-
+                     validated. Execution context never goes here.
+  --session <id>     Session the action belongs to (required).
+  --domain <slug>    Domain workspace (default: the domains/<slug>/ the cwd is inside,
+                     else "pm"). Must be registered in the installation.
+  --actor <a>        Defaults to $PHRONESIS_ACTOR, else 'agent'.
+  --surface <s>      Defaults to 'cli'.
+  --invocation-id <i> Attribution provenance for a surrounding skill invocation. It is
+                     caller-controlled (not an authority); adapters and the eval harness
+                     may supply it. PHRONESIS_INVOCATION_ID is the equivalent env input.
+  --dir <install>    Installation root (default: walk up to .phronesis/registry.json).
+
+Approval-gated actions refuse without an approval signal: the env var
+PHRONESIS_APPROVAL_SOURCE (e.g. operator:interactive), set by an approving adapter and
+recorded verbatim as approval_source on action_type.committed.
+`.trim(),
+  );
+}
+
+function showIngestHelp() {
+  console.log(
+    `
+Usage:
+  phronesis ingest <url|file|dir> --domain <slug> [--lane <lane>] [--trust trusted|untrusted] [--json] [--dir <install>]
+  phronesis ingest --paste --domain <slug> [--lane <lane>] [--dir <install>]
+  phronesis ingest - --domain <slug> --title <title> [--slug <slug>] [--lane <lane>] [--dir <install>]
+  phronesis ingest - --domain <slug> --lane <lane> --source-connector <name>
+    --source-external-id <id> --source-timestamp <iso> --title <title> [--slug <slug>] [--json]
+
+Stages one operator-pointed source, or every readable text file under a directory,
+into domains/<slug>/raw/<lane>/ with connector provenance frontmatter, then stops.
+V1 ingest writes no compiled/ or codex/ state, emits no events, and does not auto-run
+compile.
+
+Arguments:
+  <url|file|dir>   http(s) URL to fetch, local file to read, or directory to bulk-stage.
+                   Use - for titled stdin.
+
+Options:
+  --domain <slug>  Registered domain to write into (required)
+  --lane <lane>    Raw content lane (default: inbox; e.g. transcripts)
+  --paste          Read source text from stdin
+  --trust <tier>   untrusted by default. trusted is honored only for local files.
+  --title <title>  Required when source is -; used to derive the staged filename slug.
+  --slug <slug>    Optional exact filename slug override for titled stdin.
+  --source-connector <name>      Bridge provenance connector name.
+  --source-external-id <id>      Bridge stable external item id.
+  --source-timestamp <iso>       Bridge source timestamp.
+  --json           Emit the ingest report as JSON
+  --dir <install>  Installation root (default: walk up to .phronesis/registry.json)
+`.trim(),
+  );
+}
+
+function showCompileHelp() {
+  console.log(
+    `
+Usage:
+  phronesis compile accept <draft_path> --session <id> [--dir <install>] [--surface <s>]
+  phronesis compile reject <draft_path> --session <id> [--reason '<why>'] [--dir <install>] [--surface <s>]
+  phronesis compile review --session <id> [--domain <slug>] [--approve-all --rationale '<why>'] [--resume] [--json]
+
+The operator review primitives over a compile candidate (specs/security.md draft
+lifecycle; core-0017 H9). An untrusted compile stages a draft under .phronesis/drafts/ and
+emits compile.candidate — no canonical state changes until you accept it. Both events are
+operator-attributed by contract — there is no --actor flag.
+
+accept:  Validate the draft AS its canonical compiled/ shape, move it into compiled/
+         (overwriting on an update, fresh-writing on a create), discard the draft, and
+         emit action_type.requested → action_type.committed (approval_source recorded —
+         acceptance IS the approval) → compile.accepted. The committed event refreshes the
+         domain's active-context projection (the post-compile hook).
+reject:  Discard the draft and emit compile.rejected { draft_path, reason }. No canonical
+         state changes. A draft is transient (a temp), so discarding it is permitted.
+review:  The batch-approval UX over the same per-draft accept move (T7.5). Lists pending
+         drafts and their fail-closed classification; --approve-all promotes the
+         provably-clean set as ONE logical approval — every compile.accepted shares one
+         batch_id + the operator's one --rationale (change 0025). A draft is EXCLUDED from
+         approve-all (left for individual review) when its LATEST compile.candidate is
+         suspicious_payload-flagged; when it has NO compile.candidate event at all; when that
+         latest candidate carries NO content_digest (not provably clean); or when the on-disk
+         draft's sha-256 no longer matches that digest (the bytes were edited after the clean
+         candidate — change 0027). A benign re-draft (several clean candidates, latest clean,
+         digest matching the current bytes) stays eligible. A mid-batch crash is recoverable:
+         --resume re-drives the batch from a durable .phronesis/ journal, reconciling every
+         missing post-move boundary in order (committed -> projection -> compile.accepted).
+
+  <draft_path>       (accept/reject) The .phronesis/drafts/{domain}/{type-dir}/{name}.md candidate.
+  --session <id>     Review session the events belong to (required).
+  --reason '<why>'   (reject) recorded on compile.rejected.
+  --domain <slug>    (review) Domain whose drafts to review (default: pm).
+  --approve-all      (review) Promote the provably-clean set as one batch.
+  --rationale '<why>'(review) Required with --approve-all; recorded on every batch compile.accepted.
+  --resume           (review) Reconcile a crashed batch from the durable journal.
+  --json             (review) Emit the plan / result as JSON.
+
+accept consumes the approval signal from env PHRONESIS_APPROVAL_SOURCE (the same channel
+as 'phronesis act'); when unset it records 'operator:compile-accept'.
+`.trim(),
+  );
+}
+
+function showActiveContextHelp() {
+  console.log(
+    `
+Usage: phronesis active-context refresh --domain <slug> [--dir <install>] [--json]
+
+Regenerate a domain's tracked active-context projection,
+domains/<slug>/ACTIVE_CONTEXT.md (specs/compile-retrieve-loop.md §"Generated-state
+hygiene"; core-0017 H5) — a derived-but-tracked summary of the domain's compiled state,
+distinct from the gitignored machine index under .phronesis/index/. The post-compile hook
+shells out to this on every compile commit; 'phronesis validate' flags the projection
+stale when a compiled object is newer than its entry.
+
+Options:
+  --domain <slug>    The domain whose projection to refresh (required; must be registered)
+  --dir <install>    Installation root (default: walk up to .phronesis/registry.json)
+  --json             Emit the refresh result as JSON
+`.trim(),
+  );
+}
+
+function showRegistryHelp() {
+  console.log(
+    `
+Usage: phronesis registry status [--dir <install>] [--json]
+
+Shows the install's action-type registry (specs/ontology.md §"Action type contract";
+specs/trust-scopes.md Scope 1): where the table comes from (.phronesis/registry.json
+action_types vs built-in defaults), every type's effective permission and its relation
+to the code default, the registered target layout, and the payload schema.
+
+Operator overrides live in .phronesis/registry.json within a safety lattice whose floor
+is compiled into @phronesis/core: tightening any permission is allowed, loosening a
+floor action (record_outcome, promote_to_codex) fails closed at load, layouts and
+schema loosenings are refused. On an invalid registry this prints the load errors and
+exits non-zero — the action layer is disabled until the registry is fixed.
+
+Options:
+  --dir <install>    Installation root (default: walk up to .phronesis/registry.json)
+  --json             Emit the effective registry as JSON
+`.trim(),
+  );
+}
+
+function showSkillsHelp() {
+  console.log(
+    `
+Usage: phronesis skills status [--dir <install>] [--json]
+       phronesis skills bump <skill> --to <model_id>@<date> [options]
+
+status — Shows the install's skill registry (specs/skills.md §"Skill registry"): every
+skill declared in .phronesis/registry.json's skills section, loaded from
+skills/{name}/SKILL.md and validated against the frontmatter contract (skills.md
+§"Frontmatter contract") plus the runtime-free degrade contract (§"Runtime-free
+invocation", change 0013).
+
+On an invalid registry or any invalid registered skill this prints the load errors and
+exits non-zero — the skills layer is disabled until it is fixed. skills/ dirs without a
+registry entry are listed as unregistered (they do not load).
+
+  --dir <install>    Installation root (default: walk up to .phronesis/registry.json)
+  --json             Emit the resolved skill records as JSON
+
+bump — The deployment-unit gate (specs/eval-discipline.md §"Prompt + model is the
+deployment unit"). Runs the candidate-execution substrate (core-0028) k times under the
+proposed prompt_pin, aggregates to a STRICT-min floor on BOTH axes (quality + coverage),
+refuses the comparison if the evaluation identity drifted, blocks an either-axis
+regression vs the previous accepted pin, increments the skill version, and writes the new
+pin to skills/<skill>/SKILL.md ONLY on pass — appending a baseline record to
+skills/<skill>/evals/PINS.md. A bare model bump that regresses is caught before it ships
+(the Voiceflow safeguard). bump is a dev/release op on git-tracked source: it runs against
+a repo root (skills/ + changes/ present), never an install.
+
+  --to <pin>           Proposed prompt_pin: {model_id}@{date} (required)
+  --repo <path>        Repo root (default: cwd; must carry skills/ and changes/)
+  --k <n>              Reliability runs per golden (default: 5; floor, not mean)
+  --shape-change       The prompt edit changes output shape → MAJOR version bump
+                       (default: model-only swap → MINOR, skills.md:43)
+  --accept-regression  Proceed over a real, stable-identity regression; logs a structured
+                       override record to PINS.md (does NOT bypass identity drift or
+                       fabrication)
+  --rebaseline         Reset the comparison basis after evaluation-identity drift: re-seed
+                       the baseline under the new identity (absolute floor on both axes,
+                       no regression check) and write a rebaseline record
+  --coverage-floor <f> Min per-run warranted-capture hit-rate (default: 1.0)
+  --quality-floor <f>  Min per-criterion score across k runs (default: 4)
+  --rationale <text>   Recorded on an override / rebaseline record
+  --accepted-by <who>  Recorded on the PINS.md record (default: operator)
+  --judge-model <m>    Judge model for the L2 scores (default: sonnet)
+  --goldens-dir <path> Override the golden corpus dir (default:
+                       $PHRONESIS_INSTALL/corpus/skill-goldens/<skill>)
+  --domain <name>      Active domain the goldens run under (default: pm)
+  --json               Emit the gate decision as JSON
+
+A fabrication in any run, a quality score below the rubric floor (≥4), or a missed
+absolute floor on a first-bump/--rebaseline seed is a hard block — never overridable by
+--accept-regression (which overrides only a relative dip that stays above the floor). A
+non-completing substrate run (timeout/error) blocks the gate rather than counting as a
+candidate. An unsigned corpus still runs the gate; the result carries gate_status:
+provisional (never skipped, never a false green). bump is single-flight: do not run two
+bumps of the same skill concurrently (it writes git-tracked source; serialization is the
+daemon's job, T4.1/V1.5).
+`.trim(),
+  );
+}
+
+function showEvalHelp() {
+  console.log(
+    `
+Usage: phronesis eval view [--skill <name>] [--repo <path>] [options]
+
+The tiny LOCAL eval data viewer (specs/eval-discipline.md §"Custom data viewer"). Serves a
+localhost-only page rendering, per skill: the golden list; input -> expected ->
+model_default (from the goldens); L2 per-criterion means + below-floor (failed) criteria
+(from results/aggregate.json). The "actual" (candidate output) column appears only once
+core-0028's candidate runner has persisted output to results/candidates/ — it is never read
+from runs/*.json (judge scores only) and never invented.
+
+It binds localhost ONLY, writes nothing into the repo, and exposes nothing over the network
+(the operator's goldens carry real names). The repo root (skills/ + changes/) locates the
+rubrics + gitignored candidate results; goldens resolve from the install
+($PHRONESIS_INSTALL/corpus/skill-goldens/<skill>, change 0023). Refuses outside a repo root.
+
+Options:
+  --skill <name>       Render only this skill (default: all skills with eval data)
+  --repo <path>        Repo root (default: cwd; must carry skills/ and changes/)
+  --goldens-dir <path> Override the golden corpus dir (default:
+                       $PHRONESIS_INSTALL/corpus/skill-goldens/<skill>)
+  --port <n>           Localhost port (default: an ephemeral port)
+  --host <addr>        Bind address (default: 127.0.0.1; off-localhost is refused)
+  --no-serve           Print the rendered HTML to stdout instead of serving
+  --json               List the skills that would be rendered, as JSON
+`.trim(),
+  );
+}
+
+function showHooksHelp() {
+  console.log(
+    `
+Usage:
+  phronesis hooks due-check --session <id> [--actor <a>] [--surface <s>] [--dir <install>]
+  phronesis hooks sweep-status --session <id> [--json] [--dir <install>]
+  phronesis hooks skill-start --payload '<hook-json>' [--dir <install>]
+  phronesis hooks skill-complete --session <id> [--payload '<hook-json>'] [--boundary-event <Stop|SubagentStop>] [--json] [--dir <install>]
+  phronesis hooks skill-abandon --payload '<hook-json>' [--json] [--dir <install>]
+  phronesis hooks skill-sweep-stale --session <id> [--json] [--dir <install>]
+
+Session-boundary hook support (specs/hooks.md §"Emission discipline"; change 0010 D4).
+The scaffolded Claude Code hooks (.phronesis/hooks/session-start.sh, session-sweep.sh,
+skill-lifecycle.sh) shell out to these; any Tier-1 surface adapter can do the same.
+
+due-check:      Computes due review_dates across every domain's decisions (review_date
+                <= today, no outcome recorded), emits one outcome.due per due decision
+                (the V1 authoritative emitter — the daemon's date-watch takes over at
+                V1.5), and prints the due list with a record_outcome pointer. Run it at
+                session start; the printout is the review surface.
+
+sweep-status:   Reports whether this session has emitted its capture-sweep marker — a
+                session.end event with a sweep payload ({"sweep":{"candidates":N}};
+                candidates 0 is the honest negative). Prints "swept" (exit 0) or
+                "pending" (exit 1); the scaffolded Stop hook keys its block-once
+                capture prompt on it.
+
+skill-start / skill-complete / skill-abandon / skill-sweep-stale:
+                Claude Code skill lifecycle adapter plumbing. skill-start consumes
+                PreToolUse(Skill) or UserPromptExpansion hook JSON, mints an
+                adapter-owned invocation_id, emits skill.invoked, and writes the
+                transient .phronesis/invocations/ record that act reads. Complete emits
+                skill.completed and clears it; abandon/stale-sweep clear without a
+                synthetic completion.
+`.trim(),
+  );
+}
+
+function showAdapterHelp() {
+  console.log(
+    `
+Usage: phronesis adapter test <surface> [--dir <install>] [--domain <slug>] [--json]
+
+The per-surface adapter self-check (specs/tech-stack.md §"Adapter test command";
+specs/event-log.md §"Adapter test"). V1 ships the Codex adapter test.
+
+adapter test codex — asserts the deterministic mechanics of the project-local Codex
+wiring (change 0028 / core-0034): domains/<slug>/.codex/hooks.json wires each native
+event to its bare-path launcher, the launchers resolve the install root and hand off to
+the shared .phronesis/hooks/ scripts, and an unswept Stop yields {"decision":"block"}.
+It reports the compliance LEVEL — Level 1 (reinforcement: recall / due-check / sweep) and
+Level 2 (skill-lifecycle), which is PARTIAL on Codex (no UserPromptExpansion/StopFailure;
+no fabricated skill.invoked/completed) — and points at the operator-verified desktop-app
+checklist section in docs/surface-setup.md, the half a CLI cannot auto-assert.
+It is read-only: no canonical state is written and no events are emitted.
+
+Open Codex AT the domain workspace dir (Codex loads .codex/ only from the opened
+directory, no parent-walk) and trust the project hooks (CLI /hooks, or the app's
+Settings → Coding → Hooks). Editing the config re-hashes the hooks → re-trust required.
+
+Options:
+  --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
+  --domain <slug>      Check one domain's .codex/ (default: every registered domain)
+  --json               Emit the compliance report as JSON
+`.trim(),
+  );
+}
+
+function showGuardHelp() {
+  console.log(
+    `
+Usage: phronesis guard --dir <install> --session <id> [--surface <s>] [--actor <a>] [--domain <slug>] [--json]
+
+Pre-answer context relevance guard (specs/compile-retrieve-loop.md §"Context relevance
+guard"). The prompt is read from stdin only: raw text, or a JSON envelope with
+{"prompt":"...", "session_id":"..."} mirroring a surface UserPromptSubmit payload.
+There is no --prompt flag, so prompt text never rides argv.
+
+When an owned-context advice/action prompt is detected, the guard emits
+recall.candidate, runs in-process @phronesis/core retrieval over the active domain plus
+codex/personal, emits recall.injected, and returns either a recall packet or an
+honest-negative packet. Not-fired prompts return {"fired":false} and emit no events.
+
+Options:
+  --dir <install>      Installation root (required; cwd is not trusted)
+  --session <id>       Session id (required)
+  --surface <s>        Surface name (default: cli)
+  --actor <a>          Actor (default: $PHRONESIS_ACTOR, else agent)
+  --domain <slug>      Domain scope override
+  --json               Emit the machine-readable guard result
+`.trim(),
+  );
+}
+
+function showSearchHelp() {
+  console.log(
+    `
+Usage: phronesis search "<query>" [--domain <slug> | --all-domains] [--include-artifacts] [--limit N] [--json] [--dir <install>]
+
+Stage 1 retrieval (specs/compile-retrieve-loop.md §"Two-stage retrieval"): in-process
+BM25 over the active domain's compiled/ objects plus the shared codex. Freshness is
+read-time — the derived machine index (.phronesis/index/) is verified against disk and
+repaired on every load, so results always reflect current state (no daemon needed).
+
+Zero hits is an honest negative, not an error: empty_result: true, exit 0.
+
+Arguments:
+  query                The search text (quote it)
+
+Options:
+  --domain <slug>      Domain scope (default: the domains/<slug>/ the cwd is inside, else "${DEFAULT_DOMAIN}")
+  --all-domains        Search every domain (default scope is one domain + codex)
+  --include-artifacts  Explicitly include durable artifacts for this search (not indexed by default)
+  --limit N            Max results (default: 10)
+  --json               Emit the contract envelope as JSON
+  --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
+`.trim(),
+  );
+}
+
+function showQueryHelp() {
+  console.log(
+    `
+Usage: phronesis query "<question>" [--domain <slug> | --all-domains] [--include-artifacts] [--limit N] [--hops N] [--json] [--dir <install>]
+
+Two-stage retrieval (specs/compile-retrieve-loop.md): Stage 1 BM25 finds seed objects,
+Stage 2 walks each seed's typed links into its connected subgraph — the related
+decisions, the people involved, and the raw sources they cite (per-result "sources").
+Semantic rerank (Stage 3) is V1.5+/BYO; this surface stays the same.
+
+Options:
+  --domain <slug>      Domain scope (default: the domains/<slug>/ the cwd is inside, else "${DEFAULT_DOMAIN}")
+  --all-domains        Query every domain (default scope is one domain + codex)
+  --include-artifacts  Explicitly include durable artifacts for this query (not indexed by default)
+  --limit N            Max seed results (default: 10)
+  --hops N             Link-walk depth from each seed (default: 1)
+  --json               Emit the contract envelope as JSON
+  --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
+`.trim(),
+  );
+}
+
+function showLintHelp() {
+  console.log(
+    `
+Usage: phronesis lint [--domain <slug> | --all-domains] [--stale-months N] [--json] [--dir <install>]
+
+Read-only deterministic workspace health report over the active domain's compiled/
+objects plus the shared codex. This is the mechanical foundation for the lint skill:
+orphans, supersedes/superseded-by gaps, stale forward refs, codex citation defects,
+seed-adoption hygiene, and relationships value drift.
+
+It writes nothing: no compiled edits, no raw/degraded captures, no events, no drafts,
+and no machine-index repair.
+
+Options:
+  --domain <slug>      Domain scope (default: the active domain, else "${DEFAULT_DOMAIN}")
+  --all-domains        Lint every registered domain
+  --stale-months N     Staleness threshold for forward refs and seed adoption (default: 6)
+  --json               Emit the machine-readable lint envelope
+  --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
+`.trim(),
+  );
+}
+
+function showDoctorHelp() {
+  console.log(
+    `
+Usage: phronesis doctor [--dir <install>] [--json]
+
+Read-only install-health overview — the dogfood "is my install wired correctly?"
+command. Composes existing diagnostics into a one-screen OK / warn / fail report:
+install root, registered domain(s), skill registry, hook wiring, Codex surface-adapter
+status, USER.md placeholder check, and pending-draft count.
+
+It writes nothing to the install and emits no events (the install is byte-identical
+after a run). It reports; it does not fix.
+
+Exit is non-zero only on a FAIL check (no/invalid/unreadable install, an invalid skill
+registry). WARN checks (incomplete hook wiring, a non-compliant Codex adapter, USER.md
+placeholders, pending drafts) are informational and never fail the command.
+
+Options:
+  --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
+  --json               Emit the machine-readable report: { root, checks, summary, exit }
+`.trim(),
+  );
+}
+
+function showDueHelp() {
+  console.log(
+    `
+Usage: phronesis due [--json] [--dir <install>]
+       phronesis due complete <schedule_id> [--dir <install>]
+       phronesis due run <schedule_id> [--dir <install>]
+
+The V1 cadence primitive (change 0042). Recurring work is declared in the schedule
+registry (.phronesis/schedule.json) — one typed entry per recurrence (id / kind /
+target / cadence). \`phronesis due\` is a PURE READ: it computes overdue entries from the
+registry + the clock and prints them. It emits nothing and writes nothing — the
+\`schedule.due\` events are the session-start due-check's job (phronesis hooks due-check).
+
+\`phronesis due complete <id>\` is the explicit completion floor: it advances the entry's
+last-completed date so it stops surfacing until its next cadence boundary. (A domain-
+agnostic \`kind: skill\` entry also completes automatically when its target skill runs; a
+domain-scoped one is confirmed with \`due complete\`, since a skill completion carries no domain.)
+
+\`phronesis due run <id>\` is the operator-invoked one-key executor for deterministic
+\`cli_verb\` and \`connector_pull\` entries. \`kind: skill\` is refused; run the skill in the
+operator session, then \`due complete <id>\`. A successful run advances through the same
+audit-first completion primitive as \`due complete\`; a failing target leaves the schedule due.
+
+Nothing here ever invokes a model — a schedule only surfaces or runs deterministic work under
+operator presence.
+
+Options:
+  --json               Emit the overdue list as JSON: [{ schedule_id, target, kind, days_overdue }]
+  --dir <install>      Installation root (default: walk up to .phronesis/registry.json)
+`.trim(),
+  );
+}
+
+function showIndexHelp() {
+  console.log(
+    `
+Usage: phronesis index rebuild [--json] [--dir <install>]
+
+Regenerates the derived machine search index (.phronesis/index/) from domains/*/compiled/
+and the shared codex/ (change 0008: the machine index is derived, gitignored, and
+rebuildable — never source of truth). Losing it never loses data; search/query also
+self-repair the index on every load, so rebuild is the explicit full-regeneration verb.
+`.trim(),
+  );
+}
+
+function showEventsHelp() {
+  console.log(
+    `
+Usage:
+  phronesis events purge --before YYYY-MM-DD [--archive] [--dir <install>]
+  phronesis events rotate [--dir <install>]
+
+Maintain the local event stream (specs/event-log.md). Automatic scheduling is the daemon's
+job (T4.1); these are the explicitly-invokable mechanisms. Both verbs ALSO apply the same
+boundary to the hook audit log (.phronesis/audit.log) — one retention story, one verb family
+(core-0027). The audit log is a single append file, so it is filtered line-by-line: rotated
+or purged lines past the boundary move to .phronesis/audit.log.archive (or drop on a plain
+purge).
+
+Run these when no session is actively writing the install (the standing one-writer-per-
+installation model — see actions.js). The audit-log filter rewrites the single live file in
+place, so an audit line appended by a concurrent hook fire DURING the rewrite can be lost; the
+daemon serializes this at V1.5. The day-file event stream is unaffected (only inactive past
+days are touched).
+
+purge:   DELETE day files before --before (operator wipe / privacy). --archive moves them to
+         .phronesis/events/archive/ instead of deleting. Audit lines before --before are
+         dropped too (or archived with --archive).
+rotate:  ARCHIVE day files older than event_log.retention_days (default 90) to archive/, and
+         audit lines past the same window to audit.log.archive.
+`.trim(),
+  );
+}
+
+async function run(argv) {
+  const parsed = parseArgs(argv);
+
+  switch (parsed.command) {
+    case 'help':
+      showHelp();
+      break;
+    case 'init-help':
+      showInitHelp();
+      break;
+    case 'export-help':
+      showExportHelp();
+      break;
+    case 'validate-help':
+      showValidateHelp();
+      break;
+    case 'links-help':
+      showLinksHelp();
+      break;
+    case 'event-help':
+      showEventHelp();
+      break;
+    case 'events-help':
+      showEventsHelp();
+      break;
+    case 'act-help':
+      showActHelp();
+      break;
+    case 'ingest-help':
+      showIngestHelp();
+      break;
+    case 'compile-help':
+      showCompileHelp();
+      break;
+    case 'active-context-help':
+      showActiveContextHelp();
+      break;
+    case 'registry-help':
+      showRegistryHelp();
+      break;
+    case 'skills-help':
+      showSkillsHelp();
+      break;
+    case 'eval-help':
+      showEvalHelp();
+      break;
+    case 'hooks-help':
+      showHooksHelp();
+      break;
+    case 'adapter-help':
+      showAdapterHelp();
+      break;
+    case 'guard-help':
+      showGuardHelp();
+      break;
+    case 'search-help':
+      showSearchHelp();
+      break;
+    case 'query-help':
+      showQueryHelp();
+      break;
+    case 'lint-help':
+      showLintHelp();
+      break;
+    case 'doctor-help':
+      showDoctorHelp();
+      break;
+    case 'due-help':
+      showDueHelp();
+      break;
+    case 'index-help':
+      showIndexHelp();
+      break;
+    case 'version':
+      console.log(version);
+      break;
+    case 'init': {
+      const { init } = await import('./init.js');
+      await init({
+        dir: parsed.dir,
+        force: parsed.force,
+        domain: parsed.domain,
+        name: parsed.name,
+        role: parsed.role,
+        company: parsed.company,
+        workingStyle: parsed.workingStyle,
+      });
+      break;
+    }
+    case 'export': {
+      const { exportInstallation } = await import('./export.js');
+      await exportInstallation({ dir: parsed.dir, out: parsed.out });
+      break;
+    }
+    case 'validate': {
+      const { validateInstallation } = await import('./validate.js');
+      await validateInstallation({ dir: parsed.dir });
+      break;
+    }
+    case 'links': {
+      const { runLinks } = await import('./links.js');
+      await runLinks({
+        dir: parsed.dir,
+        object: parsed.object,
+        hops: parsed.hops,
+        direction: parsed.direction,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'event-emit': {
+      const { runEventEmit } = await import('./event.js');
+      await runEventEmit({
+        type: parsed.type,
+        session: parsed.session,
+        payload: parsed.payload,
+        actor: parsed.actor,
+        surface: parsed.surface,
+        dir: parsed.dir,
+        invocationId: parsed.invocationId,
+      });
+      break;
+    }
+    case 'event-tail': {
+      const { runEventTail } = await import('./event.js');
+      await runEventTail({
+        type: parsed.type,
+        since: parsed.since,
+        follow: parsed.follow,
+        dir: parsed.dir,
+      });
+      break;
+    }
+    case 'events-purge': {
+      const { runEventsPurge } = await import('./event.js');
+      await runEventsPurge({ before: parsed.before, archive: parsed.archive, dir: parsed.dir });
+      break;
+    }
+    case 'events-rotate': {
+      const { runEventsRotate } = await import('./event.js');
+      await runEventsRotate({ dir: parsed.dir });
+      break;
+    }
+    case 'act': {
+      const { runAct } = await import('./act.js');
+      await runAct({
+        type: parsed.type,
+        json: parsed.json,
+        session: parsed.session,
+        domain: parsed.domain,
+        actor: parsed.actor,
+        surface: parsed.surface,
+        dir: parsed.dir,
+        invocationId: parsed.invocationId,
+      });
+      break;
+    }
+    case 'ingest': {
+      const { runIngest } = await import('./ingest.js');
+      await runIngest({
+        source: parsed.source,
+        paste: parsed.paste,
+        trust: parsed.trust,
+        lane: parsed.lane,
+        domain: parsed.domain,
+        dir: parsed.dir,
+        json: parsed.json,
+        sourceConnector: parsed.sourceConnector,
+        sourceExternalId: parsed.sourceExternalId,
+        sourceTimestamp: parsed.sourceTimestamp,
+        title: parsed.title,
+        slug: parsed.slug,
+      });
+      break;
+    }
+    case 'compile-accept': {
+      const { runCompileAccept } = await import('./compile.js');
+      await runCompileAccept({
+        draftPath: parsed.draftPath,
+        session: parsed.session,
+        surface: parsed.surface,
+        dir: parsed.dir,
+      });
+      break;
+    }
+    case 'compile-reject': {
+      const { runCompileReject } = await import('./compile.js');
+      await runCompileReject({
+        draftPath: parsed.draftPath,
+        reason: parsed.reason,
+        session: parsed.session,
+        surface: parsed.surface,
+        dir: parsed.dir,
+      });
+      break;
+    }
+    case 'compile-review': {
+      const { runCompileReview } = await import('./compile.js');
+      await runCompileReview({
+        domain: parsed.domain,
+        session: parsed.session,
+        surface: parsed.surface,
+        dir: parsed.dir,
+        rationale: parsed.rationale,
+        approveAll: parsed.approveAll,
+        resume: parsed.resume,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'active-context-refresh': {
+      const { runActiveContextRefresh } = await import('./active-context.js');
+      await runActiveContextRefresh({ dir: parsed.dir, domain: parsed.domain, json: parsed.json });
+      break;
+    }
+    case 'registry-status': {
+      const { runRegistryStatus } = await import('./registry.js');
+      await runRegistryStatus({ dir: parsed.dir, json: parsed.json });
+      break;
+    }
+    case 'skills-status': {
+      const { runSkillsStatus } = await import('./skills.js');
+      await runSkillsStatus({ dir: parsed.dir, json: parsed.json });
+      break;
+    }
+    case 'eval-view': {
+      const { runEvalView } = await import('./eval.js');
+      await runEvalView({
+        repo: parsed.repo,
+        skill: parsed.skill,
+        goldensDir: parsed.goldensDir,
+        port: parsed.port,
+        host: parsed.host,
+        json: parsed.json,
+        serve: parsed.serve,
+      });
+      break;
+    }
+    case 'skills-bump': {
+      const { runSkillsBump } = await import('./skills.js');
+      await runSkillsBump({
+        skill: parsed.skill,
+        to: parsed.to,
+        repo: parsed.repo,
+        k: parsed.k,
+        acceptRegression: parsed.acceptRegression,
+        rebaseline: parsed.rebaseline,
+        shapeChange: parsed.shapeChange,
+        qualityFloor: parsed.qualityFloor,
+        coverageFloor: parsed.coverageFloor,
+        rationale: parsed.rationale,
+        acceptedBy: parsed.acceptedBy,
+        judgeModel: parsed.judgeModel,
+        goldensDir: parsed.goldensDir,
+        domain: parsed.domain,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'hooks-due-check': {
+      const { runHooksDueCheck } = await import('./hooks.js');
+      await runHooksDueCheck({
+        session: parsed.session,
+        dir: parsed.dir,
+        actor: parsed.actor,
+        surface: parsed.surface,
+      });
+      break;
+    }
+    case 'hooks-sweep-status': {
+      const { runHooksSweepStatus } = await import('./hooks.js');
+      await runHooksSweepStatus({ session: parsed.session, dir: parsed.dir, json: parsed.json });
+      break;
+    }
+    case 'hooks-skill-start': {
+      const { runHooksSkillStart } = await import('./hooks.js');
+      await runHooksSkillStart({ dir: parsed.dir, payload: parsed.payload });
+      break;
+    }
+    case 'hooks-skill-complete': {
+      const { runHooksSkillComplete } = await import('./hooks.js');
+      await runHooksSkillComplete({
+        session: parsed.session,
+        dir: parsed.dir,
+        payload: parsed.payload,
+        boundaryEvent: parsed.boundaryEvent,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'hooks-skill-abandon': {
+      const { runHooksSkillAbandon } = await import('./hooks.js');
+      await runHooksSkillAbandon({ dir: parsed.dir, payload: parsed.payload, json: parsed.json });
+      break;
+    }
+    case 'hooks-skill-sweep-stale': {
+      const { runHooksSkillSweepStale } = await import('./hooks.js');
+      await runHooksSkillSweepStale({ session: parsed.session, dir: parsed.dir, json: parsed.json });
+      break;
+    }
+    case 'adapter-test': {
+      const { runAdapterTest } = await import('./adapter.js');
+      await runAdapterTest({
+        surface: parsed.surface,
+        dir: parsed.dir,
+        domain: parsed.domain,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'guard': {
+      const { runGuard } = await import('./guard.js');
+      await runGuard({
+        dir: parsed.dir,
+        session: parsed.session,
+        surface: parsed.surface,
+        actor: parsed.actor,
+        domain: parsed.domain,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'search': {
+      const { runSearch } = await import('./search.js');
+      await runSearch({
+        query: parsed.query,
+        dir: parsed.dir,
+        domain: parsed.domain,
+        allDomains: parsed.allDomains,
+        includeArtifacts: parsed.includeArtifacts,
+        limit: parsed.limit,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'query': {
+      const { runQuery } = await import('./search.js');
+      await runQuery({
+        query: parsed.query,
+        dir: parsed.dir,
+        domain: parsed.domain,
+        allDomains: parsed.allDomains,
+        includeArtifacts: parsed.includeArtifacts,
+        limit: parsed.limit,
+        hops: parsed.hops,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'lint': {
+      const { runLint } = await import('./lint.js');
+      await runLint({
+        dir: parsed.dir,
+        domain: parsed.domain,
+        allDomains: parsed.allDomains,
+        staleMonths: parsed.staleMonths,
+        json: parsed.json,
+      });
+      break;
+    }
+    case 'doctor': {
+      const { runDoctor } = await import('./doctor.js');
+      await runDoctor({ dir: parsed.dir, json: parsed.json });
+      break;
+    }
+    case 'due': {
+      const { runDue } = await import('./due.js');
+      await runDue({ dir: parsed.dir, json: parsed.json });
+      break;
+    }
+    case 'due-complete': {
+      const { runDueComplete } = await import('./due.js');
+      await runDueComplete({ dir: parsed.dir, scheduleId: parsed.scheduleId });
+      break;
+    }
+    case 'due-run': {
+      const { runDueRun } = await import('./due.js');
+      await runDueRun({ dir: parsed.dir, scheduleId: parsed.scheduleId });
+      break;
+    }
+    case 'index-rebuild': {
+      const { runIndexRebuild } = await import('./search.js');
+      await runIndexRebuild({ dir: parsed.dir, json: parsed.json });
+      break;
+    }
+    case 'invalid':
+      console.error(parsed.error);
+      console.log();
+      showHelp();
+      process.exitCode = 1;
+      break;
+    case 'unknown':
+      console.error(`Unknown command: ${parsed.input}`);
+      console.log();
+      showHelp();
+      process.exitCode = 1;
+      break;
+  }
+}
+
+export { parseArgs, run, showHelp, showInitHelp };
+
+if (process.argv[1]) {
+  try {
+    const arg1Real = realpathSync(resolve(process.argv[1]));
+    const selfReal = fileURLToPath(import.meta.url);
+    if (arg1Real === selfReal) run();
+  } catch {
+    // realpathSync can fail if the path doesn't exist; skip silently
+  }
+}