@knolo/cli 3.2.2 → 4.0.0

package/README.md

@@ -1,5 +1,8 @@
 # @knolo/cli
 
+The CLI targets the Knolo v4 pack contract. Normal builds emit v4; the ICP
+legacy build path explicitly emits v3 until the canister gains a v4 profile.
+
 The official CLI for building `.knolo` knowledge packs.
 
 It indexes structured content and produces a deterministic, local-first knowledge bundle for use with `@knolo/core`.
@@ -36,6 +39,49 @@ Indexes your configured content and outputs:
 dist/knowledge.knolo
 ```
 
+Artifact workflows:
+
+```bash
+knolo inspect dist/knowledge.knolo
+knolo verify dist/knowledge.knolo
+knolo migrate old.knolo --to 4 --out new.knolo
+knolo query "billing policy" --receipt receipt.json --json
+knolo explain receipt.json --pack dist/knowledge.knolo
+knolo diff old.knolo new.knolo
+```
+
+### ICP Canister Workflow (LIVE)
+
+Deploy a Knolo knowledge canister on a local ICP replica, upload a `.knolo` pack, and query it with no middleware.
+
+```bash
+knolo icp init ./icp-knowledge-canister
+cd ./icp-knowledge-canister
+dfx start --background
+dfx deploy
+knolo icp build-pack ./knowledge --out ./dist/knowledge.knolo
+knolo icp upload ./dist/knowledge.knolo --canister knolo_knowledge --label my-docs
+knolo icp health --canister knolo_knowledge
+knolo icp info --canister knolo_knowledge
+knolo icp query "alpha beta" --canister knolo_knowledge --k 5
+# knolo icp clear --canister knolo_knowledge  # controller only
+```
+
+From the monorepo, you can also seed dummy data and open a Postman-friendly REST gateway:
+
+```bash
+npm run icp:local
+curl -sS "http://127.0.0.1:8787/search?q=billing&k=5"
+```
+
+These commands stay local-first:
+
+* No hosted service
+* No vector database
+* Lexical retrieval by default
+* Controller-only pack mutation; 2 MiB pack limit
+* Pack state survives canister upgrades
+
 ---
 
 ## 📁 Expected Project Structure
@@ -77,12 +123,13 @@ All builds are deterministic.
 
 ## 🧠 Agent Features
 
-Phase 2 includes:
+Current v4 features include:
 
 * Routing profile extraction
 * Tool policy validation
 * Mount-time registry validation
 * Deterministic selection logic
+* Pack manifests, analyzer identities, retrieval plans, receipts, and evidence spans
 
 ---
 
@@ -121,5 +168,4 @@ This section is deterministic, offline-safe, and additive; runtimes that ignore
 
 ## 📄 License
 
-MIT
-
+Apache-2.0

package/bin/knolo.mjs

@@ -1,15 +1,21 @@
 #!/usr/bin/env node
 
+import { execFileSync } from 'node:child_process';
 import {
+  chmodSync,
+  copyFileSync,
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   readdirSync,
+  rmSync,
   statSync,
   watch,
   writeFileSync,
 } from 'node:fs';
 import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -26,8 +32,13 @@ const DEFAULT_CONFIG = {
   query: { topK: 5 },
 };
 const SUPPORTED_EXTENSIONS = new Set(['.md', '.txt', '.json']);
-const SKIP_DIRS = new Set(['node_modules', 'dist', '.git']);
-const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'dev', 'semantic:index', 'semantic:inspect', 'semantic:validate']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', '.dfx', '.cargo-target']);
+const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'inspect', 'migrate', 'verify', 'explain', 'diff', 'dev', 'semantic:index', 'semantic:inspect', 'semantic:validate']);
+const ICP_SUBCOMMANDS = new Set(['init', 'build-pack', 'upload', 'query', 'health', 'info', 'clear']);
+const ICP_TEMPLATE_CANDIDATES = [
+  path.resolve(__dirname, '../templates/icp-knowledge-canister'),
+  path.resolve(__dirname, '../../../examples/icp-knowledge-canister'),
+];
 
 function createError(message) {
   return new Error(message);
@@ -71,7 +82,13 @@ Commands:
   add <name> <path>       Add or update a source entry in config
   build                   Build a .knolo pack from configured sources
   query <question>        Query a built pack and print top hits
+  inspect <pack>          Inspect pack format, sections, and manifest
+  migrate <pack>          Migrate a legacy pack to v4
+  verify <pack>           Verify pack structure and cryptographic digests
+  explain <receipt>       Verify and explain a query receipt
+  diff <pack-a> <pack-b>  Compare pack identities and source/chunk counts
   dev                     Watch config/sources and rebuild on change
+  icp                     Scaffold and operate an ICP-native knowledge canister
 
 Global options:
   --debug                 Print stack traces for errors
@@ -85,8 +102,14 @@ function printCommandHelp(command) {
     init: 'Usage: knolo init',
     add: 'Usage: knolo add <name> <path>',
     build: 'Usage: knolo build',
-    query: 'Usage: knolo query <question> [--pack <path>] [--k <number>] [--json]',
+    query: 'Usage: knolo query <question> [--pack <path>] [--k <number>] [--receipt <file>] [--json]',
+    inspect: 'Usage: knolo inspect <pack.knolo>',
+    migrate: 'Usage: knolo migrate <pack.knolo> --out <new-pack.knolo> [--to 4]',
+    verify: 'Usage: knolo verify <pack.knolo>',
+    explain: 'Usage: knolo explain <receipt.json> --pack <pack.knolo>',
+    diff: 'Usage: knolo diff <pack-a.knolo> <pack-b.knolo>',
     dev: 'Usage: knolo dev',
+    icp: 'Usage: knolo icp <command> [options]',
     'semantic:index': 'Usage: knolo semantic:index --pack <path> [--out <path>] [--model <id>] [--endpoint <url>]',
     'semantic:inspect': 'Usage: knolo semantic:inspect --sidecar <path>',
     'semantic:validate': 'Usage: knolo semantic:validate --pack <path> --sidecar <path> --model <id>',
@@ -94,6 +117,87 @@ function printCommandHelp(command) {
   console.log(help[command] ?? 'Unknown command.');
 }
 
+function printIcpHelp() {
+  console.log(`KnoLo CLI - ICP
+
+Usage:
+  knolo icp <command> [options]
+
+Commands:
+  init <dir>                                Copy the bundled ICP canister template
+  build-pack <docsDir> --out <file>         Build a lexical-only .knolo pack
+  upload <packFile> --canister <name-or-id> Upload a pack with dfx canister call set_pack
+  query <question> --canister <name-or-id>  Query the canister with search
+  health --canister <name-or-id>            Call the canister health method
+  info --canister <name-or-id>              Call the canister pack_info method
+  clear --canister <name-or-id>             Clear the loaded pack (controller only)
+
+Examples:
+  knolo icp init ./icp-knowledge-canister
+  knolo icp build-pack ./knowledge --out ./dist/knowledge.knolo
+  knolo icp upload ./dist/knowledge.knolo --canister knolo_knowledge
+  knolo icp query "alpha beta" --canister knolo_knowledge --k 5
+  knolo icp health --canister knolo_knowledge
+  knolo icp info --canister knolo_knowledge
+  knolo icp clear --canister knolo_knowledge
+
+Environment:
+  DFX_BIN                                   Override the dfx executable path
+
+Run "knolo icp <command> --help" for subcommand details.`);
+}
+
+function printIcpCommandHelp(command) {
+  const help = {
+    init: `Usage: knolo icp init <dir>
+
+Copy the bundled ICP knowledge canister template into <dir>.
+
+Example:
+  knolo icp init ./icp-knowledge-canister`,
+    'build-pack': `Usage: knolo icp build-pack <docsDir> --out <file>
+
+Build a lexical-only .knolo pack from markdown, text, or JSON docs.
+
+Examples:
+  knolo icp build-pack ./knowledge --out ./dist/knowledge.knolo
+  knolo icp build-pack ./docs --out ./packs/support.knolo`,
+    upload: `Usage: knolo icp upload <packFile> --canister <name-or-id> [--label <text>]
+
+Upload a .knolo pack through dfx canister call set_pack.
+
+Examples:
+  knolo icp upload ./dist/knowledge.knolo --canister knolo_knowledge
+  knolo icp upload ./dist/knowledge.knolo --canister ux6qi-fyaaa-aaaab-qaaaq-cai --label release-2026-04-28`,
+    query: `Usage: knolo icp query <question> --canister <name-or-id> [--k <number>]
+
+Query the canister's search method directly over dfx.
+
+Examples:
+  knolo icp query "alpha beta" --canister knolo_knowledge
+  knolo icp query "billing escalation" --canister ux6qi-fyaaa-aaaab-qaaaq-cai --k 10`,
+    health: `Usage: knolo icp health --canister <name-or-id>
+
+Call the canister health query method.
+
+Example:
+  knolo icp health --canister knolo_knowledge`,
+    info: `Usage: knolo icp info --canister <name-or-id>
+
+Call the canister pack_info query method.
+
+Example:
+  knolo icp info --canister knolo_knowledge`,
+    clear: `Usage: knolo icp clear --canister <name-or-id>
+
+Clear the loaded pack. Requires a controller identity.
+
+Example:
+  knolo icp clear --canister knolo_knowledge`,
+  };
+  console.log(help[command] ?? 'Unknown ICP command.');
+}
+
 function parseArgv(argv) {
   const args = [...argv];
   const global = { debug: false };
@@ -186,6 +290,120 @@ async function cmdAdd(args) {
   console.log(`✔ wrote ${CONFIG_FILE}`);
 }
 
+function resolveIcpTemplateDir() {
+  for (const candidate of ICP_TEMPLATE_CANDIDATES) {
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) return candidate;
+  }
+  throw createError('Bundled ICP template not found. Reinstall @knolo/cli or run from the Knolo repo checkout.');
+}
+
+function ensureDirectoryMissingOrEmpty(targetDir) {
+  if (!existsSync(targetDir)) return;
+  const stats = statSync(targetDir);
+  if (!stats.isDirectory()) throw createError(`Target path already exists and is not a directory: ${targetDir}`);
+  const visibleEntries = readdirSync(targetDir);
+  if (visibleEntries.length > 0) {
+    throw createError(`Target directory is not empty: ${targetDir}`);
+  }
+}
+
+function copyDirectoryContents(sourceDir, targetDir) {
+  mkdirSync(targetDir, { recursive: true });
+  const entries = readdirSync(sourceDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      copyDirectoryContents(sourcePath, targetPath);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    mkdirSync(path.dirname(targetPath), { recursive: true });
+    copyFileSync(sourcePath, targetPath);
+    chmodSync(targetPath, statSync(sourcePath).mode);
+  }
+}
+
+function parseFlagArgs(args, { booleanFlags = [] } = {}) {
+  const positional = [];
+  const flags = {};
+  const booleanSet = new Set(booleanFlags);
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    const name = arg.slice(2);
+    if (!name) throw createError(`Unexpected flag: ${arg}`);
+    if (booleanSet.has(name)) {
+      flags[name] = true;
+      continue;
+    }
+
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw createError(`Missing value for ${arg}`);
+    }
+    flags[name] = value;
+    i += 1;
+  }
+
+  return { positional, flags };
+}
+
+function parsePositiveInteger(value, flagName) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw createError(`${flagName} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function renderDidNat8Vec(bytes) {
+  return bytes.length ? ` ${Array.from(bytes, (value) => `${value}`).join('; ')} ` : '';
+}
+
+function withArgumentFile(prefix, contents, run) {
+  const tempDir = mkdtempSync(path.join(tmpdir(), prefix));
+  const argumentFile = path.join(tempDir, 'args.did');
+  try {
+    writeFileSync(argumentFile, contents, 'utf8');
+    return run(argumentFile);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function runDfx(args, { cwd = process.cwd() } = {}) {
+  const dfxBin = process.env.DFX_BIN || 'dfx';
+  const env = { ...process.env };
+  if (env.TERM === 'dumb') env.TERM = 'xterm-256color';
+
+  try {
+    const output = execFileSync(dfxBin, args, {
+      cwd,
+      encoding: 'utf8',
+      env,
+    });
+    if (output) process.stdout.write(output);
+    return output;
+  } catch (error) {
+    if (error?.status === 0) {
+      const recovered = typeof error?.stdout === 'string' ? error.stdout : '';
+      if (recovered) process.stdout.write(recovered);
+      return recovered;
+    }
+    const stderr = typeof error?.stderr === 'string' ? error.stderr.trim() : '';
+    const stdout = typeof error?.stdout === 'string' ? error.stdout.trim() : '';
+    const detail = stderr || stdout || error?.message || 'dfx command failed';
+    throw createError(detail);
+  }
+}
+
 async function walkDir(dir) {
   const out = [];
   const entries = await fs.readdir(dir, { withFileTypes: true });
@@ -258,6 +476,168 @@ async function cmdBuild(core) {
   await buildFromConfig(core);
 }
 
+async function collectNamedFiles(sourceName, inputPath) {
+  const resolved = path.resolve(process.cwd(), inputPath);
+  if (!existsSync(resolved)) throw createError(`Source path not found: ${inputPath}`);
+
+  const stats = await fs.lstat(resolved);
+  if (stats.isSymbolicLink()) return [];
+  if (stats.isFile()) {
+    if (!SUPPORTED_EXTENSIONS.has(path.extname(resolved).toLowerCase())) {
+      throw createError(`Unsupported file type for ${inputPath}. Expected .md, .txt, or .json.`);
+    }
+    return [{ sourceName, absolutePath: resolved }];
+  }
+  if (!stats.isDirectory()) throw createError(`Source path must be a file or directory: ${inputPath}`);
+
+  return (await walkDir(resolved))
+    .map((absolutePath) => ({ sourceName, absolutePath }))
+    .sort((a, b) => a.absolutePath.localeCompare(b.absolutePath));
+}
+
+function buildDocsFromFiles(files, rootDir) {
+  return files.map((file) => {
+    const rel = path.relative(rootDir, file.absolutePath).replace(/\\/g, '/');
+    return {
+      id: rel,
+      heading: path.basename(rel),
+      namespace: file.sourceName,
+      text: readFileSync(file.absolutePath, 'utf8'),
+    };
+  });
+}
+
+async function cmdIcpInit(args) {
+  const [targetDir] = args;
+  if (!targetDir) throw createError('Usage: knolo icp init <dir>');
+
+  const templateDir = resolveIcpTemplateDir();
+  const resolvedTarget = path.resolve(process.cwd(), targetDir);
+  ensureDirectoryMissingOrEmpty(resolvedTarget);
+  mkdirSync(resolvedTarget, { recursive: true });
+  copyDirectoryContents(templateDir, resolvedTarget);
+
+  const relativeTarget = path.relative(process.cwd(), resolvedTarget) || '.';
+  console.log(`✔ created ${relativeTarget}`);
+  console.log('Next steps:');
+  console.log(`  cd ${relativeTarget}`);
+  console.log('  dfx start --background');
+  console.log('  dfx deploy');
+  console.log('  knolo icp build-pack ./knowledge --out ./dist/knowledge.knolo');
+  console.log('  knolo icp upload ./dist/knowledge.knolo --canister knolo_knowledge');
+  console.log('  knolo icp query "alpha beta" --canister knolo_knowledge');
+}
+
+async function cmdIcpBuildPack(core, args) {
+  const { positional, flags } = parseFlagArgs(args);
+  const docsDir = positional[0];
+  if (!docsDir || !flags.out) {
+    throw createError('Usage: knolo icp build-pack <docsDir> --out <file>');
+  }
+
+  const resolvedInput = path.resolve(process.cwd(), docsDir);
+  const files = await collectNamedFiles('docs', docsDir);
+  if (!files.length) throw createError('No supported files found (.md, .txt, .json).');
+
+  const rootDir = statSync(resolvedInput).isDirectory() ? resolvedInput : path.dirname(resolvedInput);
+  const docs = buildDocsFromFiles(files, rootDir);
+  const bytes = await core.buildPack(docs, { format: 3 });
+  const outPath = path.resolve(process.cwd(), flags.out);
+
+  mkdirSync(path.dirname(outPath), { recursive: true });
+  writeFileSync(outPath, Buffer.from(bytes));
+
+  console.log(`✔ indexed ${files.length} files`);
+  console.log(`✔ wrote ${path.relative(process.cwd(), outPath)}`);
+  console.log('✔ lexical-only pack build completed');
+}
+
+function defaultPackLabel(packPath) {
+  return path.basename(packPath, path.extname(packPath)) || 'knowledge-pack';
+}
+
+async function cmdIcpUpload(args) {
+  const { positional, flags } = parseFlagArgs(args);
+  const packFile = positional[0];
+  if (!packFile || !flags.canister) {
+    throw createError('Usage: knolo icp upload <packFile> --canister <name-or-id> [--label <text>]');
+  }
+
+  const packPath = path.resolve(process.cwd(), packFile);
+  if (!existsSync(packPath)) throw createError(`Pack file not found at ${path.relative(process.cwd(), packPath)}.`);
+
+  const label = flags.label || defaultPackLabel(packPath);
+  const bytes = readFileSync(packPath);
+  const didArgs = `(vec {${renderDidNat8Vec(bytes)}}, ${JSON.stringify(label)})\n`;
+
+  withArgumentFile('knolo-icp-upload-', didArgs, (argumentFile) =>
+    runDfx(
+      ['canister', 'call', flags.canister, 'set_pack', '--argument-file', argumentFile, '--output', 'json'],
+      { cwd: process.cwd() }
+    )
+  );
+}
+
+async function cmdIcpQuery(args) {
+  const { positional, flags } = parseFlagArgs(args);
+  const question = positional.join(' ').trim();
+  if (!question || !flags.canister) {
+    throw createError('Usage: knolo icp query <question> --canister <name-or-id> [--k <number>]');
+  }
+
+  const topK = flags.k === undefined ? 5 : parsePositiveInteger(flags.k, '--k');
+  const didArgs = `(${JSON.stringify(question)}, ${topK} : nat32)\n`;
+
+  withArgumentFile('knolo-icp-query-', didArgs, (argumentFile) =>
+    runDfx(
+      ['canister', 'call', flags.canister, 'search', '--query', '--argument-file', argumentFile, '--output', 'json'],
+      { cwd: process.cwd() }
+    )
+  );
+}
+
+async function cmdIcpHealth(args) {
+  const { flags } = parseFlagArgs(args);
+  if (!flags.canister) throw createError('Usage: knolo icp health --canister <name-or-id>');
+  runDfx(['canister', 'call', flags.canister, 'health', '--query', '--output', 'json'], {
+    cwd: process.cwd(),
+  });
+}
+
+async function cmdIcpInfo(args) {
+  const { flags } = parseFlagArgs(args);
+  if (!flags.canister) throw createError('Usage: knolo icp info --canister <name-or-id>');
+  runDfx(['canister', 'call', flags.canister, 'pack_info', '--query', '--output', 'json'], {
+    cwd: process.cwd(),
+  });
+}
+
+async function cmdIcpClear(args) {
+  const { flags } = parseFlagArgs(args);
+  if (!flags.canister) throw createError('Usage: knolo icp clear --canister <name-or-id>');
+  runDfx(['canister', 'call', flags.canister, 'clear_pack', '--output', 'json'], {
+    cwd: process.cwd(),
+  });
+}
+
+async function cmdIcp(args) {
+  const [subcommand, ...rest] = args;
+  if (!subcommand) return printIcpHelp();
+  if (!ICP_SUBCOMMANDS.has(subcommand)) throw createError(`Unknown ICP command: ${subcommand}`);
+  if (rest.includes('--help') || rest.includes('-h')) return printIcpCommandHelp(subcommand);
+
+  if (subcommand === 'init') return await cmdIcpInit(rest);
+  if (subcommand === 'upload') return await cmdIcpUpload(rest);
+  if (subcommand === 'query') return await cmdIcpQuery(rest);
+  if (subcommand === 'health') return await cmdIcpHealth(rest);
+  if (subcommand === 'info') return await cmdIcpInfo(rest);
+  if (subcommand === 'clear') return await cmdIcpClear(rest);
+  if (subcommand === 'build-pack') {
+    const core = await loadCore();
+    return await cmdIcpBuildPack(core, rest);
+  }
+}
+
 function parseQueryArgs(args) {
   const opts = { json: false };
   const positional = [];
@@ -266,6 +646,7 @@ function parseQueryArgs(args) {
     if (arg === '--json') opts.json = true;
     else if (arg === '--pack') opts.pack = args[++i];
     else if (arg === '--k') opts.k = args[++i];
+    else if (arg === '--receipt') opts.receipt = args[++i];
     else if (arg.startsWith('--')) throw createError(`Unknown flag for query: ${arg}`);
     else positional.push(arg);
   }
@@ -287,7 +668,12 @@ async function cmdQuery(core, args) {
   const packBuffer = readFileSync(packPath);
   const bytes = Uint8Array.from(packBuffer);
   const kb = await mountPackFromBytes(core, bytes);
-  const hits = core.query(kb, question, { topK }).map((hit) => ({
+  const receiptResult = opts.receipt && core.queryWithReceipt ? core.queryWithReceipt(kb, question, { topK }) : null;
+  if (receiptResult && opts.receipt) {
+    writeFileSync(path.resolve(process.cwd(), opts.receipt), `${JSON.stringify(receiptResult.receipt, null, 2)}\n`);
+  }
+  const rawHits = receiptResult?.hits ?? core.query(kb, question, { topK });
+  const hits = rawHits.map((hit) => ({
     title: kb.headings?.[hit.blockId] || hit.source || `Block ${hit.blockId}`,
     source: hit.source || kb.docIds?.[hit.blockId] || 'unknown',
     score: Number(hit.score.toFixed(4)),
@@ -299,7 +685,7 @@ async function cmdQuery(core, args) {
       hits.map((h, i) => ({ blockId: i, score: h.score, text: h.snippet, source: h.source })),
       { budget: 'small' }
     );
-    console.log(JSON.stringify({ question, packPath, topK, hits, contextPatch: patch }, null, 2));
+    console.log(JSON.stringify({ question, packPath, topK, hits, receipt: receiptResult?.receipt, contextPatch: patch }, null, 2));
     return;
   }
 
@@ -316,6 +702,77 @@ async function cmdQuery(core, args) {
   });
 }
 
+function parsePackCommandArgs(args, command) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--out' || arg === '--to' || arg === '--pack') flags[arg.slice(2)] = args[++i];
+    else if (arg.startsWith('--')) throw createError(`Unknown flag for ${command}: ${arg}`);
+    else positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+async function cmdInspect(core, args) {
+  const { positional } = parsePackCommandArgs(args, 'inspect');
+  const packPath = path.resolve(process.cwd(), positional[0] || 'dist/knowledge.knolo');
+  if (!existsSync(packPath)) throw createError(`Pack file not found at ${path.relative(process.cwd(), packPath)}.`);
+  const bytes = Uint8Array.from(readFileSync(packPath));
+  const pack = await mountPackFromBytes(core, bytes);
+  const result = { format: pack.meta?.format || (pack.meta?.version === 4 ? 'v4' : `v${pack.meta?.version ?? 'unknown'}`), version: pack.meta?.version, stats: pack.meta?.stats, blocks: pack.blocks.length, semantic: Boolean(pack.semantic), claims: Boolean(pack.claimGraph) };
+  if (core.isPackV4?.(bytes.buffer)) result.container = core.inspectPackV4(bytes.buffer);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function cmdVerify(core, args) {
+  const { positional } = parsePackCommandArgs(args, 'verify');
+  const packPath = path.resolve(process.cwd(), positional[0] || 'dist/knowledge.knolo');
+  if (!existsSync(packPath)) throw createError(`Pack file not found at ${path.relative(process.cwd(), packPath)}.`);
+  const bytes = Uint8Array.from(readFileSync(packPath));
+  const pack = await mountPackFromBytes(core, bytes);
+  console.log(JSON.stringify({ verified: true, format: pack.meta?.format || (pack.meta?.version === 4 ? 'v4' : `v${pack.meta?.version}`), blocks: pack.blocks.length, terms: pack.meta?.stats?.terms ?? pack.lexicon.size }, null, 2));
+}
+
+async function cmdMigrate(core, args) {
+  const { positional, flags } = parsePackCommandArgs(args, 'migrate');
+  const input = positional[0];
+  if (!input || !flags.out) throw createError('Usage: knolo migrate <pack.knolo> --out <new-pack.knolo> --to 4');
+  if (String(flags.to || '4') !== '4') throw createError('Only migration to format 4 is currently supported.');
+  const inputPath = path.resolve(process.cwd(), input);
+  if (!existsSync(inputPath)) throw createError(`Pack file not found at ${path.relative(process.cwd(), inputPath)}.`);
+  const bytes = Uint8Array.from(readFileSync(inputPath));
+  const pack = await mountPackFromBytes(core, bytes);
+  if (core.isPackV4?.(bytes.buffer)) throw createError('Input pack is already v4.');
+  const docs = pack.blocks.map((text, i) => ({ id: pack.docIds?.[i] ?? undefined, heading: pack.headings?.[i] ?? undefined, namespace: pack.namespaces?.[i] ?? undefined, text }));
+  const migrated = core.serializePackV4(pack, docs);
+  const outPath = path.resolve(process.cwd(), flags.out);
+  mkdirSync(path.dirname(outPath), { recursive: true });
+  writeFileSync(outPath, Buffer.from(migrated));
+  console.log(`✔ migrated ${path.relative(process.cwd(), inputPath)} to ${path.relative(process.cwd(), outPath)}`);
+}
+
+async function cmdExplain(core, args) {
+  const { positional, flags } = parsePackCommandArgs(args, 'explain');
+  const receiptPath = positional[0];
+  if (!receiptPath || !flags.out && !flags.pack) throw createError('Usage: knolo explain <receipt.json> --pack <pack.knolo>');
+  const packPath = path.resolve(process.cwd(), flags.pack);
+  const receipt = JSON.parse(readFileSync(path.resolve(process.cwd(), receiptPath), 'utf8'));
+  const pack = await mountPackFromBytes(core, Uint8Array.from(readFileSync(packPath)));
+  core.verifyReceipt(receipt, pack);
+  console.log(JSON.stringify({ verified: true, decision: receipt.decision, answerability: receipt.answerability, reasons: receipt.reasons, query: receipt.normalizedQuery, hits: receipt.hits.map((hit) => ({ blockId: hit.blockId, score: hit.score, source: hit.source, spans: hit.spans })) }, null, 2));
+}
+
+async function cmdDiff(core, args) {
+  const { positional } = parsePackCommandArgs(args, 'diff');
+  if (positional.length < 2) throw createError('Usage: knolo diff <pack-a.knolo> <pack-b.knolo>');
+  const load = async (file) => { const bytes = Uint8Array.from(readFileSync(path.resolve(process.cwd(), file))); return { bytes, pack: await mountPackFromBytes(core, bytes) }; };
+  const a = await load(positional[0]); const b = await load(positional[1]);
+  const aDigest = core.packDigest(a.pack); const bDigest = core.packDigest(b.pack);
+  const aSources = new Set(a.pack.docIds?.filter(Boolean) ?? []); const bSources = new Set(b.pack.docIds?.filter(Boolean) ?? []);
+  console.log(JSON.stringify({ equal: aDigest === bDigest, a: { packDigest: aDigest, blocks: a.pack.blocks.length, terms: a.pack.lexicon.size }, b: { packDigest: bDigest, blocks: b.pack.blocks.length, terms: b.pack.lexicon.size }, addedSources: [...bSources].filter((id) => !aSources.has(id)).sort(), removedSources: [...aSources].filter((id) => !bSources.has(id)).sort() }, null, 2));
+}
+
 function parseKeyValueArgs(args) {
   const out = {};
   for (let i = 0; i < args.length; i++) {
@@ -664,15 +1121,26 @@ async function main() {
   const { global, command, commandArgs } = parseArgv(process.argv.slice(2));
   try {
     if (command === 'help') return printRootHelp();
-
-    const core = await loadCore();
+    if (command === 'icp') {
+      if (commandArgs.length === 0 || commandArgs[0] === '--help' || commandArgs[0] === '-h') {
+        return printIcpHelp();
+      }
+      return await cmdIcp(commandArgs);
+    }
 
     if (SUBCOMMANDS.has(command)) {
       if (commandArgs.includes('--help') || commandArgs.includes('-h')) return printCommandHelp(command);
       if (command === 'init') return await cmdInit();
       if (command === 'add') return await cmdAdd(commandArgs);
+
+      const core = await loadCore();
       if (command === 'build') return await cmdBuild(core);
       if (command === 'query') return await cmdQuery(core, commandArgs);
+      if (command === 'inspect') return await cmdInspect(core, commandArgs);
+      if (command === 'migrate') return await cmdMigrate(core, commandArgs);
+      if (command === 'verify') return await cmdVerify(core, commandArgs);
+      if (command === 'explain') return await cmdExplain(core, commandArgs);
+      if (command === 'diff') return await cmdDiff(core, commandArgs);
       if (command === 'dev') return await cmdDev(core);
       if (command === 'semantic:index') return await cmdSemanticIndex(core, commandArgs);
       if (command === 'semantic:inspect') return await cmdSemanticInspect(core, commandArgs);
@@ -680,6 +1148,7 @@ async function main() {
     }
 
     if (command.startsWith('-')) throw createError(`Unknown option: ${command}`);
+    const core = await loadCore();
     return await runDirectMode(core, command, commandArgs);
   } catch (error) {
     console.error(`knolo: ${error instanceof Error ? error.message : String(error)}`);

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@knolo/cli",
-  "version": "3.2.2",
+  "version": "4.0.0",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "templates/"
   ],
   "scripts": {
     "build": "node -e \"console.log('cli is executable via bin/knolo.mjs')\"",
     "test": "npm run build --prefix ../core && node --test test/cli.test.mjs"
   },
   "dependencies": {
-    "@knolo/core": "^3.2.0"
+    "@knolo/core": "^4.0.0"
   },
   "private": false
 }