sneakoscope 0.9.11 → 0.9.13

package/src/cli/output.mjs

@@ -0,0 +1,9 @@
+import { PACKAGE_VERSION } from '../core/version.mjs';
+
+export function sksTextLogo() {
+  return `SKS\nSNEAKOSCOPE CODEX v${PACKAGE_VERSION}`;
+}
+
+export function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}

package/src/cli/router.mjs

@@ -0,0 +1,30 @@
+import { COMMAND_ALIASES, COMMANDS } from './command-registry.mjs';
+
+function normalizeCommand(args = []) {
+  const cmd = args[0];
+  if (!cmd) return { command: null, args };
+  const mapped = COMMAND_ALIASES[cmd] || cmd;
+  return {
+    command: mapped,
+    args: mapped === cmd ? args.slice(1) : args.slice(1)
+  };
+}
+
+export async function dispatch(args = []) {
+  const { command, args: rest } = normalizeCommand(args);
+  if (!command) {
+    const legacy = await import('./legacy-main.mjs');
+    return legacy.main(args);
+  }
+  const entry = COMMANDS[command];
+  if (!entry) {
+    console.error(`Unknown command: ${command}`);
+    process.exitCode = 1;
+    return;
+  }
+  const mod = await entry.lazy();
+  const runner = mod.run || mod.main || mod.default;
+  if (typeof runner !== 'function') throw new Error(`Command ${command} has no run/main export`);
+  if (mod.IS_LEGACY_CLI) return runner([command, ...rest]);
+  return runner(command, rest);
+}

package/src/commands/all-features.mjs

@@ -0,0 +1,6 @@
+import { allFeaturesCommand } from '../cli/feature-commands.mjs';
+
+export async function run(_command, args = []) {
+  const [sub, ...rest] = args;
+  return allFeaturesCommand(sub, rest);
+}

package/src/commands/codex-app.mjs

@@ -0,0 +1,30 @@
+import { flag } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+import { codexAccessTokenStatus, codexAppIntegrationStatus, formatCodexAppStatus } from '../core/codex-app.mjs';
+import { codexAppRemoteControlCommand } from '../cli/codex-app-command.mjs';
+
+export async function run(_command, args = []) {
+  const action = args[0] || 'check';
+  if (action === 'remote-control' || action === 'remote') return codexAppRemoteControlCommand(args.slice(1));
+  if (action === 'pat') {
+    const status = codexAccessTokenStatus();
+    if (flag(args, '--json')) return printJson(status);
+    console.log('Codex App PAT status');
+    console.log(`Status: ${status.status}`);
+    for (const entry of status.access_token_env_vars) console.log(`${entry.name}: ${entry.present ? entry.value : 'missing'}`);
+    return;
+  }
+  if (action === 'check' || action === 'status') {
+    const status = await codexAppIntegrationStatus();
+    if (flag(args, '--json')) {
+      printJson(status);
+      if (!status.ok) process.exitCode = 1;
+      return;
+    }
+    console.log(formatCodexAppStatus(status, { includeRaw: flag(args, '--verbose') }));
+    if (!status.ok) process.exitCode = 1;
+    return;
+  }
+  console.error('Usage: sks codex-app check|status|pat status|remote-control [--json]');
+  process.exitCode = 1;
+}

package/src/commands/codex-lb.mjs

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { projectRoot } from '../core/fsx.mjs';
+import { flag, readOption } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+import { codexLbMetrics, readCodexLbCircuit, recordCodexLbHealthEvent, resetCodexLbCircuit } from '../core/codex-lb-circuit.mjs';
+
+export async function run(command, args = []) {
+  const root = await projectRoot();
+  const action = args[0] || 'status';
+  if (action === 'metrics') {
+    const result = codexLbMetrics(await readCodexLbCircuit(root));
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`codex-lb circuit: ${result.circuit.state}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'doctor' && flag(args, '--deep')) {
+    const result = { schema: 'sks.codex-lb-doctor.v1', deep: true, ...codexLbMetrics(await readCodexLbCircuit(root)) };
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`codex-lb deep doctor: ${result.ok ? 'ok' : 'blocked'} (${result.circuit.state})`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'circuit' && args[1] === 'reset') {
+    const result = await resetCodexLbCircuit(root);
+    if (flag(args, '--json')) return printJson({ ok: true, circuit: result });
+    console.log('codex-lb circuit reset');
+    return;
+  }
+  if (action === 'circuit' && args[1] === 'record-fixture') {
+    const fixturePath = args[2] || readOption(args, '--fixture', null);
+    if (!fixturePath) {
+      console.error('Usage: sks codex-lb circuit record-fixture <fixture.json> [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const { readJson } = await import('../core/fsx.mjs');
+    const event = await readJson(path.isAbsolute(fixturePath) ? fixturePath : path.resolve(root, fixturePath), {});
+    const circuit = await recordCodexLbHealthEvent(root, event);
+    const result = { schema: 'sks.codex-lb-circuit-record-fixture.v1', ok: true, fixture: fixturePath, circuit };
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`codex-lb circuit: ${circuit.state}`);
+    return;
+  }
+  const legacy = await import('../cli/legacy-main.mjs');
+  return legacy.main([command, ...args]);
+}

package/src/commands/db.mjs

@@ -0,0 +1,6 @@
+import { dbCommand } from '../cli/maintenance-commands.mjs';
+
+export async function run(_command, args = []) {
+  const [sub = 'policy', ...rest] = args;
+  return dbCommand(sub, rest);
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,46 @@
+import { projectRoot, dirSize, exists, formatBytes } from '../core/fsx.mjs';
+import { flag } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+import { getCodexInfo } from '../core/codex-adapter.mjs';
+import { rustInfo } from '../core/rust-accelerator.mjs';
+import { codexAppIntegrationStatus } from '../core/codex-app.mjs';
+import { codexLbMetrics, readCodexLbCircuit } from '../core/codex-lb-circuit.mjs';
+
+export async function run(_command, args = []) {
+  if (flag(args, '--fix')) {
+    const legacy = await import('../cli/legacy-main.mjs');
+    return legacy.main(['doctor', ...args]);
+  }
+  const root = await projectRoot();
+  const codex = await getCodexInfo().catch((err) => ({ available: false, error: err.message }));
+  const rust = await rustInfo().catch((err) => ({ available: false, error: err.message }));
+  const codexApp = await codexAppIntegrationStatus({ codex }).catch((err) => ({ ok: false, error: err.message }));
+  const codexLb = codexLbMetrics(await readCodexLbCircuit(root).catch(() => ({})));
+  const pkgBytes = await dirSize(root).catch(() => 0);
+  const result = {
+    schema: 'sks.doctor-status.v1',
+    ok: Boolean(codex.bin) && codexApp.ok && codexLb.ok,
+    root,
+    node: { ok: Number(process.versions.node.split('.')[0]) >= 20, version: process.version },
+    codex,
+    rust,
+    codex_app: codexApp,
+    codex_lb: codexLb,
+    sneakoscope: { ok: await exists(`${root}/.sneakoscope`) },
+    package: { bytes: pkgBytes, human: formatBytes(pkgBytes) }
+  };
+  if (flag(args, '--json')) {
+    printJson(result);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  console.log('SKS Doctor');
+  console.log(`Root:      ${root}`);
+  console.log(`Node:      ${result.node.ok ? 'ok' : 'fail'} ${result.node.version}`);
+  console.log(`Codex:     ${codex.bin ? 'ok' : 'missing'} ${codex.version || ''}`);
+  console.log(`Rust acc.: ${rust.available ? rust.version : 'optional-missing'}`);
+  console.log(`Codex App: ${codexApp.ok ? 'ok' : 'needs setup'}`);
+  console.log(`codex-lb:  ${codexLb.ok ? 'ok' : `blocked ${codexLb.circuit?.state || 'unknown'}`}`);
+  console.log(`Ready:     ${result.ok ? 'yes' : 'no'}`);
+  if (!result.ok) process.exitCode = 1;
+}

package/src/commands/features.mjs

@@ -0,0 +1,6 @@
+import { featuresCommand } from '../cli/feature-commands.mjs';
+
+export async function run(_command, args = []) {
+  const [sub, ...rest] = args;
+  return featuresCommand(sub, rest);
+}

package/src/commands/help.mjs

@@ -0,0 +1,77 @@
+import { COMMANDS } from '../cli/command-registry.mjs';
+import { flag } from '../cli/args.mjs';
+import { printJson, sksTextLogo } from '../cli/output.mjs';
+
+const FALLBACK_CATALOG = [
+  { name: 'help', usage: 'sks help [stable|beta|labs|all]', description: 'Show concise SKS help.' },
+  { name: 'version', usage: 'sks version | sks --version', description: 'Print the installed version.' },
+  { name: 'commands', usage: 'sks commands [--json]', description: 'List the command registry.' },
+  { name: 'root', usage: 'sks root [--json]', description: 'Show the active SKS root.' },
+  { name: 'doctor', usage: 'sks doctor [--json]', description: 'Check local SKS readiness.' },
+  { name: 'features', usage: 'sks features check --json', description: 'Validate feature coverage and fixtures.' },
+  { name: 'all-features', usage: 'sks all-features selftest --mock --json', description: 'Run mock feature fixture checks.' },
+  { name: 'proof', usage: 'sks proof show|validate|latest|export [--json|--md]', description: 'Inspect completion proof.' },
+  { name: 'wiki', usage: 'sks wiki image-ingest|image-validate|image-summary ...', description: 'Manage TriWiki and image voxel ledgers.' },
+  { name: 'hooks', usage: 'sks hooks explain|status|trust-report|replay ...', description: 'Inspect Codex hook policy and trust evidence.' },
+  { name: 'codex-lb', usage: 'sks codex-lb status|metrics|doctor|circuit ...', description: 'Inspect codex-lb readiness and circuit state.' },
+  { name: 'perf', usage: 'sks perf cold-start --json', description: 'Measure CLI cold-start budgets.' },
+  { name: 'team', usage: 'sks team "task"', description: 'Create and observe Team missions.' },
+  { name: 'qa-loop', usage: 'sks qa-loop prepare|run|status ...', description: 'Run QA loop missions.' },
+  { name: 'research', usage: 'sks research prepare|run|status ...', description: 'Run research missions.' },
+  { name: 'ppt', usage: 'sks ppt build|status ...', description: 'Build or inspect PPT route artifacts.' },
+  { name: 'image-ux-review', usage: 'sks image-ux-review status ...', description: 'Inspect image UX review artifacts.' },
+  { name: 'db', usage: 'sks db policy|scan|check ...', description: 'Inspect database safety policy.' },
+  { name: 'gx', usage: 'sks gx init|render|validate|drift|snapshot ...', description: 'Create and verify visual context cartridges.' },
+  { name: 'goal', usage: 'sks goal create|status|pause|resume|clear ...', description: 'Manage the Goal bridge.' }
+];
+
+export async function run(command, args = []) {
+  if (command === 'commands') return commands(args);
+  const topic = args[0];
+  if (topic === 'all') return printHelp('all');
+  if (['stable', 'beta', 'labs'].includes(topic)) return printHelp(topic);
+  if (topic) return printTopic(topic);
+  return printHelp('default');
+}
+
+function commands(args = []) {
+  const commands = commandRows('all');
+  if (flag(args, '--json')) {
+    return printJson({
+      schema: 'sks.command-registry.v1',
+      aliases: ['sks', 'sneakoscope'],
+      commands
+    });
+  }
+  console.log(`${sksTextLogo()}\n\nCommands\n`);
+  const width = Math.max(...commands.map((entry) => entry.usage.length));
+  for (const entry of commands) console.log(`${entry.usage.padEnd(width)}  ${entry.description}`);
+}
+
+function printHelp(filter) {
+  const rows = commandRows(filter === 'default' ? 'stable-beta' : filter);
+  console.log(`${sksTextLogo()}\n\nUsage\n`);
+  console.log('  sks help [stable|beta|labs|all]');
+  console.log('  sks commands [--json]');
+  console.log('  sks root [--json]');
+  console.log('  sks proof show --json');
+  console.log('');
+  for (const row of rows) console.log(`  ${row.usage.padEnd(54)} ${row.description}`);
+  console.log('\nCore promises: image-based Voxel TriWiki, Codex App/codex-lb readiness, and completion proof for serious routes.');
+}
+
+function printTopic(topic) {
+  const row = commandRows('all').find((entry) => entry.name === topic);
+  if (!row) return printHelp('default');
+  console.log(`${sksTextLogo()}\n\n${row.name}\n`);
+  console.log(`Usage: ${row.usage}`);
+  console.log(row.description);
+}
+
+function commandRows(filter) {
+  const maturityByName = new Map(Object.entries(COMMANDS).map(([name, meta]) => [name, meta.maturity || 'labs']));
+  const rows = FALLBACK_CATALOG.map((entry) => ({ ...entry, maturity: maturityByName.get(entry.name) || 'labs' }));
+  if (filter === 'all') return rows;
+  if (filter === 'stable-beta') return rows.filter((row) => row.maturity === 'stable' || row.maturity === 'beta');
+  return rows.filter((row) => row.maturity === filter);
+}

package/src/commands/hooks.mjs

@@ -0,0 +1,6 @@
+import { hooksCommand } from '../cli/feature-commands.mjs';
+
+export async function run(_command, args = []) {
+  const [sub, ...rest] = args;
+  return hooksCommand(sub, rest);
+}

package/src/commands/perf.mjs

@@ -0,0 +1,91 @@
+import { performance } from 'node:perf_hooks';
+import { spawnSync } from 'node:child_process';
+import { PACKAGE_VERSION, projectRoot } from '../core/fsx.mjs';
+import { flag } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+
+export const DEFAULT_COLD_START_ITERATIONS = 20;
+
+const COLD_START_COMMANDS = Object.freeze([
+  { cmd: 'sks --version', args: ['--version'], budget_p95_ms: 80 },
+  { cmd: 'sks help', args: ['help'], budget_p95_ms: 150 },
+  { cmd: 'sks root --json', args: ['root', '--json'], budget_p95_ms: 150 },
+  { cmd: 'sks features check --json', args: ['features', 'check', '--json'], budget_p95_ms: 1500 }
+]);
+
+export async function run(_command, args = []) {
+  const action = args[0] || 'run';
+  if (action === 'cold-start') {
+    const root = await projectRoot();
+    const iterations = resolveColdStartIterations(readArg(args, '--iterations', process.env.SKS_COLD_START_ITERATIONS));
+    const result = runColdStart({ root, iterations });
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Cold-start: ${result.ok ? 'pass' : 'fail'}`);
+    for (const row of result.commands) console.log(`- ${row.cmd}: p95=${row.p95_ms}ms budget=${row.budget_p95_ms}ms ${row.ok ? 'ok' : 'blocked'}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  const legacy = await import('../cli/legacy-main.mjs');
+  return legacy.main(['perf', ...args]);
+}
+
+export function runColdStart({ root = process.cwd(), iterations = DEFAULT_COLD_START_ITERATIONS } = {}) {
+  const script = new URL('../../bin/sks.mjs', import.meta.url).pathname;
+  const measuredIterations = resolveColdStartIterations(iterations);
+  const commands = COLD_START_COMMANDS.map((spec) => measureCommand(root, script, spec, measuredIterations));
+  return {
+    schema: 'sks.perf.cold-start.v1',
+    version: PACKAGE_VERSION,
+    node: process.version,
+    platform: `${process.platform}-${process.arch}`,
+    commands,
+    ok: commands.every((row) => row.ok)
+  };
+}
+
+export function resolveColdStartIterations(value = DEFAULT_COLD_START_ITERATIONS) {
+  const parsed = Number(value ?? DEFAULT_COLD_START_ITERATIONS);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_COLD_START_ITERATIONS;
+  return Math.max(1, Math.floor(parsed));
+}
+
+function measureCommand(root, script, spec, iterations) {
+  const values = [];
+  const failures = [];
+  for (let i = 0; i < iterations; i += 1) {
+    const t0 = performance.now();
+    const res = spawnSync(process.execPath, [script, ...spec.args], {
+      cwd: root,
+      env: { ...process.env, SKS_SKIP_UPDATE_CHECK: '1', CI: 'true' },
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+      shell: false
+    });
+    values.push(performance.now() - t0);
+    if (res.status !== 0) failures.push({ status: res.status, stderr: String(res.stderr || '').slice(0, 400) });
+  }
+  values.sort((a, b) => a - b);
+  const p50 = percentile(values, 50);
+  const p95 = percentile(values, 95);
+  const p95Rounded = Math.round(p95);
+  return {
+    cmd: spec.cmd,
+    iterations,
+    p50_ms: Math.round(p50),
+    p95_ms: p95Rounded,
+    budget_p95_ms: spec.budget_p95_ms,
+    ok: failures.length === 0 && p95Rounded <= spec.budget_p95_ms,
+    failures
+  };
+}
+
+function percentile(values, p) {
+  if (!values.length) return 0;
+  const idx = Math.min(values.length - 1, Math.ceil((p / 100) * values.length) - 1);
+  return values[idx];
+}
+
+function readArg(args, name, fallback) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}

package/src/commands/proof.mjs

@@ -0,0 +1,103 @@
+import { projectRoot } from '../core/fsx.mjs';
+import { flag } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+import { collectProofEvidence } from '../core/proof/evidence-collector.mjs';
+import { findLatestMission } from '../core/mission.mjs';
+import { readLatestProof, readLatestProofMarkdown, readRouteProof } from '../core/proof/proof-reader.mjs';
+import { writeRouteCompletionProof } from '../core/proof/route-adapter.mjs';
+import { renderProofMarkdown, writeCompletionProof } from '../core/proof/proof-writer.mjs';
+import { validateCompletionProof } from '../core/proof/validation.mjs';
+
+export async function run(_command, args = []) {
+  const root = await projectRoot();
+  const action = args[0] || 'show';
+  const rest = args.slice(1);
+  if (action === 'show' || action === 'latest') {
+    const proof = await withFreshSummaries(root, await readLatestProof(root));
+    if (flag(args, '--json') || action === 'latest') return printJson(proof);
+    process.stdout.write(renderProofMarkdown(proof));
+    return;
+  }
+  if (action === 'validate') {
+    const proof = await withFreshSummaries(root, await readLatestProof(root));
+    const validation = validateCompletionProof(proof);
+    const result = { schema: 'sks.completion-proof-validation.v1', ok: validation.ok, status: validation.status, issues: validation.issues, proof_status: proof.status };
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Completion proof validation: ${result.ok ? 'pass' : 'fail'} (${result.proof_status})`);
+    for (const issue of result.issues) console.log(`- ${issue}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'route') {
+    const missionArg = rest.find((arg) => !String(arg).startsWith('--')) || 'latest';
+    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const proof = await readRouteProof(root, missionId);
+    const result = proof
+      ? { schema: 'sks.completion-proof-route.v1', ok: true, mission_id: missionId, proof }
+      : { schema: 'sks.completion-proof-route.v1', ok: false, mission_id: missionId, status: 'blocked', issues: ['completion_proof_missing'] };
+    if (flag(args, '--json')) return printJson(result);
+    if (proof) process.stdout.write(renderProofMarkdown(proof));
+    else console.log(`Completion proof missing for mission ${missionId || 'latest'}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'export' && (flag(rest, '--md') || flag(args, '--md'))) {
+    process.stdout.write(await readLatestProofMarkdown(root));
+    return;
+  }
+  if (action === 'repair' && rest[0] === 'latest') {
+    const missionId = await findLatestMission(root);
+    const evidence = await collectProofEvidence(root);
+    const result = await writeRouteCompletionProof(root, {
+      missionId,
+      route: '$SKS',
+      status: 'verified_partial',
+      evidence,
+      summary: {
+        files_changed: evidence.files?.length || 0,
+        commands_run: 1,
+        manual_review_required: true
+      },
+      claims: [{ id: 'proof-repair-latest', status: 'supported', evidence: '.sneakoscope/proof/latest.json' }],
+      unverified: ['Repair proof records current local evidence and remains verified_partial until a route-specific gate passes.']
+    });
+    if (flag(args, '--json')) return printJson({ schema: 'sks.completion-proof-repair.v1', ok: result.ok, mission_id: missionId, files: result.files, validation: result.validation });
+    console.log(`Completion proof repaired: ${result.files.latest_json}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'smoke') {
+    const evidence = await collectProofEvidence(root);
+    const result = await writeCompletionProof(root, {
+      route: '$SKS',
+      status: 'verified_partial',
+      summary: {
+        files_changed: evidence.files?.length || 0,
+        commands_run: 1,
+        tests_passed: 1,
+        tests_failed: 0,
+        manual_review_required: true
+      },
+      evidence,
+      claims: [{ id: 'proof-smoke', status: 'supported', evidence: '.sneakoscope/proof/latest.json' }],
+      unverified: ['Smoke proof is fixture evidence, not a real route completion.']
+    }, { command: { cmd: 'sks proof smoke', status: 'verified_partial' } });
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Completion proof written: ${result.files.latest_json}`);
+    return;
+  }
+  console.error('Usage: sks proof show|latest|validate|route <mission-id|latest>|export --md|repair latest|smoke [--json]');
+  process.exitCode = 1;
+}
+
+async function withFreshSummaries(root, proof) {
+  const evidence = await collectProofEvidence(root);
+  return {
+    ...proof,
+    evidence: {
+      ...proof.evidence,
+      image_voxels: proof.evidence?.image_voxels || evidence.image_voxels,
+      triwiki: proof.evidence?.triwiki || evidence.triwiki
+    }
+  };
+}

package/src/commands/root.mjs

@@ -0,0 +1,24 @@
+import { findProjectRoot, globalSksRoot, sksRoot } from '../core/fsx.mjs';
+import { flag } from '../cli/args.mjs';
+import { printJson, sksTextLogo } from '../cli/output.mjs';
+
+export async function run(_command, args = []) {
+  const project = await findProjectRoot();
+  const global = globalSksRoot();
+  const active = await sksRoot();
+  const result = {
+    cwd: process.cwd(),
+    mode: project ? 'project' : 'global',
+    active_root: active,
+    project_root: project,
+    global_root: global,
+    using_global_root: !project
+  };
+  if (flag(args, '--json')) return printJson(result);
+  console.log(`${sksTextLogo()}\n\nRoot\n`);
+  console.log(`Mode:        ${result.mode}`);
+  console.log(`Active root: ${active}`);
+  console.log(`Project:     ${project || 'none'}`);
+  console.log(`Global root: ${global}`);
+  if (!project) console.log('\nNo project marker was found here, so SKS will use the per-user global runtime root. Run `sks bootstrap` to initialize the current directory as a project.');
+}

package/src/commands/version.mjs

@@ -0,0 +1,5 @@
+import { PACKAGE_VERSION } from '../core/version.mjs';
+
+export async function run() {
+  console.log(`sneakoscope ${PACKAGE_VERSION}`);
+}

package/src/commands/wiki.mjs

@@ -0,0 +1,95 @@
+import path from 'node:path';
+import { projectRoot } from '../core/fsx.mjs';
+import { flag, readOption } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+import { addImageRelation, addVisualAnchor, ingestImage, imageVoxelSummary, readImageVoxelLedger } from '../core/wiki-image/image-voxel-ledger.mjs';
+import { imageVoxelProofEvidence } from '../core/wiki-image/proof-linker.mjs';
+import { validateImageVoxelLedger } from '../core/wiki-image/validation.mjs';
+
+export async function run(_command, args = []) {
+  const root = await projectRoot();
+  const action = args[0] || 'help';
+  if (action === 'image-ingest') {
+    const imagePath = args.find((arg, i) => i > 0 && !String(arg).startsWith('--'));
+    const result = await ingestImage(root, imagePath, {
+      source: readOption(args, '--source', 'manual'),
+      missionId: readOption(args, '--mission-id', null)
+    });
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Image ingested: ${result.image.id}`);
+    console.log(`Ledger: ${path.relative(root, path.join(root, '.sneakoscope', 'wiki', 'image-voxel-ledger.json'))}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'image-validate') {
+    const ledgerPath = args.find((arg, i) => i > 0 && !String(arg).startsWith('--'));
+    const ledger = await readImageVoxelLedger(root, ledgerPath ? path.resolve(root, ledgerPath) : undefined);
+    const result = { schema: 'sks.image-voxel-validation.v1', ...validateImageVoxelLedger(ledger, {
+      requireAnchors: flag(args, '--require-anchors'),
+      requireRelations: flag(args, '--require-relations'),
+      route: readOption(args, '--route', '$Wiki')
+    }) };
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Image voxel ledger: ${result.ok ? 'pass' : 'blocked'}`);
+    for (const issue of result.issues) console.log(`- ${issue}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'image-summary') {
+    const result = await imageVoxelSummary(root);
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Images: ${result.images}`);
+    console.log(`Anchors: ${result.anchors}`);
+    console.log(`Relations: ${result.relations}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'anchor-add') {
+    const result = await addVisualAnchor(root, {
+      imageId: readOption(args, '--image-id', null),
+      bbox: parseBbox(readOption(args, '--bbox', '')),
+      label: readOption(args, '--label', 'Visual anchor'),
+      source: readOption(args, '--source', 'manual'),
+      evidencePath: readOption(args, '--evidence', null),
+      route: readOption(args, '--route', '$Wiki'),
+      claimId: readOption(args, '--claim-id', null),
+      missionId: readOption(args, '--mission-id', null)
+    });
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Visual anchor: ${result.ok ? 'added' : 'blocked'} ${result.anchor.id}`);
+    for (const issue of result.validation.issues) console.log(`- ${issue}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'relation-add') {
+    const result = await addImageRelation(root, {
+      type: readOption(args, '--type', 'before_after'),
+      beforeImageId: readOption(args, '--before', null),
+      afterImageId: readOption(args, '--after', null),
+      anchors: String(readOption(args, '--anchors', '') || '').split(',').map((x) => x.trim()).filter(Boolean),
+      verification: readOption(args, '--verification', 'changed-screen-recheck'),
+      status: readOption(args, '--status', 'verified_partial'),
+      route: readOption(args, '--route', '$Wiki'),
+      missionId: readOption(args, '--mission-id', null)
+    });
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Image relation: ${result.ok ? 'added' : 'blocked'} ${result.relation.type}`);
+    for (const issue of result.validation.issues) console.log(`- ${issue}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'image-link-proof') {
+    const result = await imageVoxelProofEvidence(root);
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`Image voxel proof link: ${result.ok ? 'ok' : 'blocked'}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  const legacy = await import('../cli/legacy-main.mjs');
+  return legacy.main(['wiki', ...args]);
+}
+
+function parseBbox(raw) {
+  const parts = String(raw || '').split(',').map((part) => Number(part.trim()));
+  return parts.length === 4 && parts.every(Number.isFinite) ? parts : null;
+}