chainlesschain 0.162.101 → 0.162.103

package/src/commands/fusion.js

@@ -3,6 +3,7 @@
  */
 
 import { Command } from "commander";
+import { intArg, floatArg } from "../lib/cli-arg.js";
 
 import {
   PROTOCOL,
@@ -145,7 +146,7 @@ export function registerFusionCommand(program) {
   fu.command("messages")
     .description("List unified messages")
     .option("-p, --protocol <name>", "Filter by protocol")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(fu);
@@ -203,7 +204,7 @@ export function registerFusionCommand(program) {
 
   fu.command("identities")
     .description("List identity mappings")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(fu);
@@ -269,7 +270,7 @@ export function registerFusionCommand(program) {
   fu.command("quality-scores")
     .description("List quality scores")
     .option("-l, --level <level>", "Filter by quality level")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(fu);

package/src/commands/git.js

@@ -4,6 +4,7 @@
  */
 
 import chalk from "chalk";
+import { numericOption } from "../lib/cli-numeric.js";
 import { resolve } from "path";
 import { logger } from "../lib/logger.js";
 import {
@@ -165,7 +166,7 @@ export function registerGitCommand(program) {
         }
 
         const analysis = gitHistoryAnalyze(dir);
-        const recentLog = gitLog(dir, parseInt(options.limit));
+        const recentLog = gitLog(dir, numericOption(options.limit, { name: "--limit", integer: true, min: 1, fallback: 10 }));
 
         if (options.json) {
           console.log(

package/src/commands/governance.js

@@ -6,6 +6,7 @@
  */
 
 import chalk from "chalk";
+import { intArg, floatArg } from "../lib/cli-arg.js";
 import { logger } from "../lib/logger.js";
 import { parseJsonOption } from "../lib/parse-json-option.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
@@ -290,8 +291,8 @@ export function registerGovernanceCommand(program) {
   gov
     .command("close <proposal-id>")
     .description("Close voting — auto-resolves to passed/rejected")
-    .option("-q, --quorum <n>", "Quorum threshold (0-1)", parseFloat)
-    .option("-t, --threshold <n>", "Pass threshold (0-1)", parseFloat)
+    .option("-q, --quorum <n>", "Quorum threshold (0-1)", floatArg("--quorum"))
+    .option("-t, --threshold <n>", "Pass threshold (0-1)", floatArg("--threshold"))
     .option(
       "-n, --total-voters <n>",
       "Total eligible voters (for quorum)",
@@ -402,9 +403,9 @@ export function registerGovernanceCommand(program) {
   gov
     .command("tally <proposal-id>")
     .description("Show vote tally with quorum/threshold check")
-    .option("-q, --quorum <n>", "Quorum threshold (0-1)", parseFloat)
-    .option("-t, --threshold <n>", "Pass threshold (0-1)", parseFloat)
-    .option("-n, --total-voters <n>", "Total eligible voters", parseInt)
+    .option("-q, --quorum <n>", "Quorum threshold (0-1)", floatArg("--quorum"))
+    .option("-t, --threshold <n>", "Pass threshold (0-1)", floatArg("--threshold"))
+    .option("-n, --total-voters <n>", "Total eligible voters", intArg("--total-voters"))
     .option("--json", "Output as JSON")
     .action(async (proposalId, options) => {
       try {

package/src/commands/hardening.js

@@ -4,6 +4,7 @@
  */
 
 import chalk from "chalk";
+import { intArg, floatArg } from "../lib/cli-arg.js";
 import { logger } from "../lib/logger.js";
 import { parseJsonOption } from "../lib/parse-json-option.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
@@ -556,8 +557,8 @@ export function registerHardeningCommand(program) {
   hardening
     .command("complete-audit <audit-id>")
     .description("Complete a RUNNING audit")
-    .option("-p, --passed <n>", "Passed check count", parseInt)
-    .option("-f, --failed <n>", "Failed check count", parseInt)
+    .option("-p, --passed <n>", "Passed check count", intArg("--passed"))
+    .option("-f, --failed <n>", "Failed check count", intArg("--failed"))
     .option("-w, --warning-threshold <n>", "Score threshold for WARNING (0–1)")
     .option("--json", "JSON output")
     .action(async (auditId, opts) => {

package/src/commands/hmemory.js

@@ -4,6 +4,7 @@
  */
 
 import chalk from "chalk";
+import { numericOption } from "../lib/cli-numeric.js";
 import ora from "ora";
 import { logger } from "../lib/logger.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
@@ -661,7 +662,7 @@ export function registerHmemoryCommand(program) {
           maxAge: parseFloat(options.maxAge) || 720,
           threshold:
             options.threshold !== undefined
-              ? parseFloat(options.threshold)
+              ? numericOption(options.threshold, { name: "--threshold", min: 0, max: 1 })
               : undefined,
         });
         if (options.json) console.log(JSON.stringify(result, null, 2));

package/src/commands/hub.js

@@ -173,12 +173,28 @@ async function cmdRetrieveContext(question, options) {
 
 async function cmdStats(options) {
   try {
-    const hub = await getHub();
+    // Default to the minimal hub: stats' core payload (vault row counts +
+    // hubDir) only needs the vault, so the full 77-adapter registry + KG/RAG
+    // sinks + email-account auto-load is wasted work for a quick `cc hub
+    // stats`. Pass --full to also list registered adapters and the resolved
+    // LLM, which require the full hub init. (The adapter list is also
+    // available standalone via `cc hub list-adapters`.) getHubMinimal()
+    // transparently returns the full hub if one was already built this
+    // process, so --full is only needed on a cold stats call. Tests stub
+    // via _getHub.
+    const wantFull = options.full === true;
+    const hub = options._getHub
+      ? await options._getHub()
+      : wantFull
+        ? await getHub()
+        : await getHubMinimal();
+    const adapters = hub.registry ? hub.registry.list() : null;
     const out = {
       vault: hub.vault.stats(),
-      adapters: hub.registry.list(),
+      adapters,
       hubDir: hub.hubDir,
       llm: hub.llm ? { name: hub.llm.name, isLocal: hub.llm.isLocal } : null,
+      minimal: !!hub.minimal,
     };
     if (options.json) {
       printJson(out);
@@ -190,9 +206,17 @@ async function cmdStats(options) {
       logger.log(`  places:   ${v.places}`);
       logger.log(`  items:    ${v.items}`);
       logger.log(`  topics:   ${v.topics}`);
-      logger.log(chalk.bold(`\nadapters (${out.adapters.length}):`));
-      for (const a of out.adapters) {
-        logger.log(`  ${chalk.cyan(a.name)} v${a.version}`);
+      if (out.adapters) {
+        logger.log(chalk.bold(`\nadapters (${out.adapters.length}):`));
+        for (const a of out.adapters) {
+          logger.log(`  ${chalk.cyan(a.name)} v${a.version}`);
+        }
+      } else {
+        logger.log(
+          chalk.gray(
+            "\nadapters: (run `cc hub stats --full` or `cc hub list-adapters`)",
+          ),
+        );
       }
       logger.log(chalk.gray(`\nhubDir: ${out.hubDir}`));
       if (out.llm) {
@@ -200,6 +224,8 @@ async function cmdStats(options) {
           ? chalk.green("[local]")
           : chalk.yellow("[remote]");
         logger.log(chalk.gray(`llm: ${out.llm.name} ${tag}`));
+      } else if (out.minimal) {
+        logger.log(chalk.gray("llm: (run `cc hub stats --full` to resolve)"));
       } else {
         logger.log(chalk.yellow("llm: (none)"));
       }
@@ -213,18 +239,39 @@ async function cmdStats(options) {
 
 async function cmdHealth(options) {
   try {
-    const hub = await getHub();
+    // Full hub is the default: health's whole job is verifying that hub init
+    // wired every component (llm / kgSink / ragSink), which a minimal hub
+    // deliberately leaves null — reporting those as ✗ would be a false
+    // negative, not a faster check. `--quick` opts into a vault-only probe
+    // on the minimal hub (skips the 77-adapter registry + sink wiring) for
+    // when you just need "is the vault openable / what schema". Tests stub
+    // via _getHub.
+    const quick = options.quick === true;
+    const hub = options._getHub
+      ? await options._getHub()
+      : quick
+        ? await getHubMinimal()
+        : await getHub();
     const out = {
+      quick,
       vault: {
         ok: !!hub.vault.db,
         schemaVersion: hub.vault.schemaVersion(),
       },
-      llm: hub.llm
-        ? { ok: true, isLocal: hub.llm.isLocal, name: hub.llm.name }
-        : { ok: false, reason: "LLM unavailable" },
-      kgSink: { ok: !!hub.kgSink },
-      ragSink: { ok: !!hub.ragSink },
     };
+    if (quick) {
+      // Minimal hub intentionally has no llm / kgSink / ragSink — mark them
+      // "not probed" rather than reporting a misleading down state.
+      out.llm = { probed: false };
+      out.kgSink = { probed: false };
+      out.ragSink = { probed: false };
+    } else {
+      out.llm = hub.llm
+        ? { ok: true, isLocal: hub.llm.isLocal, name: hub.llm.name }
+        : { ok: false, reason: "LLM unavailable" };
+      out.kgSink = { ok: !!hub.kgSink };
+      out.ragSink = { ok: !!hub.ragSink };
+    }
     if (options.json) {
       printJson(out);
     } else {
@@ -232,17 +279,25 @@ async function cmdHealth(options) {
       logger.log(
         `${mark(out.vault.ok)} vault    schema=${out.vault.schemaVersion}`,
       );
-      logger.log(
-        `${mark(out.llm.ok)} llm      ${out.llm.name || out.llm.reason}${
-          out.llm.ok
-            ? out.llm.isLocal
-              ? chalk.green(" [local]")
-              : chalk.yellow(" [remote]")
-            : ""
-        }`,
-      );
-      logger.log(`${mark(out.kgSink.ok)} kgSink`);
-      logger.log(`${mark(out.ragSink.ok)} ragSink`);
+      if (quick) {
+        logger.log(
+          chalk.gray(
+            "· llm / kgSink / ragSink not probed (run without --quick)",
+          ),
+        );
+      } else {
+        logger.log(
+          `${mark(out.llm.ok)} llm      ${out.llm.name || out.llm.reason}${
+            out.llm.ok
+              ? out.llm.isLocal
+                ? chalk.green(" [local]")
+                : chalk.yellow(" [remote]")
+              : ""
+          }`,
+        );
+        logger.log(`${mark(out.kgSink.ok)} kgSink`);
+        logger.log(`${mark(out.ragSink.ok)} ragSink`);
+      }
     }
   } catch (err) {
     fail(null, err, options.json);
@@ -468,7 +523,11 @@ async function cmdRederive(options) {
 
 async function cmdQueryEvents(options) {
   try {
-    const hub = await getHub();
+    // Read-only vault query — needs no adapters / sinks / llm. Minimal hub
+    // skips the 77-adapter registry build (and is crash-resilient to a
+    // partial pdh install). getHubMinimal() returns the full hub if one was
+    // already built this process, so the vault instance is identical.
+    const hub = await getHubMinimal();
     const q = {};
     if (options.subtype) q.subtype = options.subtype;
     if (options.since) q.since = Number(options.since);
@@ -528,7 +587,8 @@ function importEventsInto(vault, events) {
       imported += 1;
     } catch (e) {
       failed += 1;
-      if (errors.length < 10) errors.push({ id: ev && ev.id, error: e.message });
+      if (errors.length < 10)
+        errors.push({ id: ev && ev.id, error: e.message });
     }
   }
   return { ok: failed === 0, imported, failed, errors };
@@ -536,7 +596,8 @@ function importEventsInto(vault, events) {
 
 async function cmdExportEvents(options) {
   try {
-    const hub = await (options._getHub || getHub)();
+    // Vault-only raw-event export — no adapters needed, use the minimal hub.
+    const hub = await (options._getHub || getHubMinimal)();
     const all = exportAllEvents(hub.vault);
     if (options.output) {
       require("fs").writeFileSync(options.output, JSON.stringify(all), "utf-8");
@@ -566,7 +627,8 @@ async function cmdImportEvents(options) {
     if (!Array.isArray(events)) {
       throw new Error("import-events: expected a JSON array of events");
     }
-    const hub = await (options._getHub || getHub)();
+    // Vault-only idempotent upsert — no adapters needed, use the minimal hub.
+    const hub = await (options._getHub || getHubMinimal)();
     const result = importEventsInto(hub.vault, events);
     if (options.json) {
       jsonAndExit(result);
@@ -585,7 +647,8 @@ async function cmdImportEvents(options) {
 // (Android LocalCcRunner.searchEvents calls this; CI smoke too).
 async function cmdSearchEvents(options) {
   try {
-    const hub = await getHub();
+    // Read-only vault FTS search — vault-only, use the minimal hub.
+    const hub = await getHubMinimal();
     const q = {};
     if (options.q) q.q = String(options.q);
     if (options.adapter) q.adapter = options.adapter;
@@ -628,7 +691,8 @@ async function cmdSearchEvents(options) {
 
 async function cmdFacetCounts(options) {
   try {
-    const hub = await getHub();
+    // Read-only vault facet aggregation — vault-only, use the minimal hub.
+    const hub = await getHubMinimal();
     const q = {};
     if (options.q) q.q = String(options.q);
     if (options.since) q.since = Number(options.since);
@@ -657,7 +721,8 @@ async function cmdFacetCounts(options) {
 
 async function cmdRecentAudit(options) {
   try {
-    const hub = await getHub();
+    // Read-only vault audit log query — vault-only, use the minimal hub.
+    const hub = await getHubMinimal();
     const q = {};
     if (options.since) q.since = Number(options.since);
     if (options.action) q.action = options.action;
@@ -722,7 +787,8 @@ async function cmdEventDetail(eventId, options) {
     process.exit(1);
   }
   try {
-    const hub = await getHub();
+    // Read-only single-event lookup — vault-only, use the minimal hub.
+    const hub = await getHubMinimal();
     const event = hub.vault.getEvent(eventId);
     if (!event) {
       const result = { found: false, eventId };
@@ -774,7 +840,8 @@ async function cmdExport(options) {
   try {
     const fs = await import("node:fs");
     const path = await import("node:path");
-    const hub = await getHub();
+    // Vault-file snapshot copy — vault-only, use the minimal hub.
+    const hub = await getHubMinimal();
     const src = hub.vault.path;
     if (!src) throw new Error("vault path unavailable (hub not initialized?)");
 
@@ -2606,14 +2673,24 @@ export function registerHubCommand(program) {
 
   hub
     .command("stats")
-    .description("Vault row counts + registered adapter list + hub paths")
+    .description(
+      "Vault row counts + hub paths (use --full to also list adapters + LLM)",
+    )
     .option("--json", "Output JSON")
+    .option(
+      "--full",
+      "Include registered adapter list + resolved LLM (loads the full hub)",
+    )
     .action(cmdStats);
 
   hub
     .command("health")
     .description("Component health: vault / llm / kgSink / ragSink")
     .option("--json", "Output JSON")
+    .option(
+      "--quick",
+      "Vault-only probe via the minimal hub (skips llm/kgSink/ragSink wiring)",
+    )
     .action(cmdHealth);
 
   hub
@@ -3175,6 +3252,8 @@ export function registerHubCommand(program) {
 export const _internal = {
   cmdAsk,
   cmdRetrieveContext,
+  cmdStats,
+  cmdHealth,
   parsePositiveInt,
   cmdAIChatList,
   cmdAIChatLogin,

package/src/commands/inference.js

@@ -3,6 +3,7 @@
  */
 
 import { Command } from "commander";
+import { intArg, floatArg } from "../lib/cli-arg.js";
 
 import {
   NODE_STATUS,
@@ -95,7 +96,7 @@ export function registerInferenceCommand(program) {
     .description("Register inference node")
     .option("-e, --endpoint <url>", "Node endpoint URL")
     .option("-c, --capabilities <list>", "Comma-separated capabilities")
-    .option("-g, --gpu <mb>", "GPU memory in MB", parseInt)
+    .option("-g, --gpu <mb>", "GPU memory in MB", intArg("--gpu"))
     .option("--json", "JSON output")
     .action((nodeId, opts) => {
       const db = _dbFromCtx(inf);
@@ -176,7 +177,7 @@ export function registerInferenceCommand(program) {
     .description("List inference nodes")
     .option("-s, --status <status>", "Filter by status")
     .option("-c, --capability <cap>", "Filter by capability")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);
@@ -200,7 +201,7 @@ export function registerInferenceCommand(program) {
     .command("submit <model>")
     .description("Submit inference task")
     .option("-i, --input <text>", "Input data")
-    .option("-p, --priority <n>", "Priority (1-10)", parseInt)
+    .option("-p, --priority <n>", "Priority (1-10)", intArg("--priority"))
     .option("-m, --mode <mode>", "Privacy mode (standard/encrypted/federated)")
     .option("--json", "JSON output")
     .action((model, opts) => {
@@ -223,7 +224,7 @@ export function registerInferenceCommand(program) {
     .command("complete <task-id>")
     .description("Mark task as complete")
     .option("-o, --output <text>", "Task output")
-    .option("-d, --duration <ms>", "Duration in ms", parseInt)
+    .option("-d, --duration <ms>", "Duration in ms", intArg("--duration"))
     .option("--json", "JSON output")
     .action((taskId, opts) => {
       const db = _dbFromCtx(inf);
@@ -279,7 +280,7 @@ export function registerInferenceCommand(program) {
     .option("-s, --status <status>", "Filter by status")
     .option("-m, --model <model>", "Filter by model")
     .option("-p, --privacy <mode>", "Filter by privacy mode")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);
@@ -437,7 +438,7 @@ export function registerInferenceCommand(program) {
     .command("submit-v2 <model>")
     .description("Submit task (V2, creates queued no assignment)")
     .option("-i, --input <text>", "Input data")
-    .option("-p, --priority <n>", "Priority (1-10)", parseInt)
+    .option("-p, --priority <n>", "Priority (1-10)", intArg("--priority"))
     .option("-m, --mode <mode>", "Privacy mode")
     .option("--json", "JSON output")
     .action((model, opts) => {
@@ -501,7 +502,7 @@ export function registerInferenceCommand(program) {
     .command("complete-v2 <task-id>")
     .description("Complete running task (running → complete)")
     .option("-o, --output <text>", "Task output")
-    .option("-d, --duration <ms>", "Duration in ms", parseInt)
+    .option("-d, --duration <ms>", "Duration in ms", intArg("--duration"))
     .option("--json", "JSON output")
     .action((taskId, opts) => {
       const db = _dbFromCtx(inf);
@@ -543,7 +544,7 @@ export function registerInferenceCommand(program) {
     .command("set-task-status <task-id> <status>")
     .description("Generic state-machine-guarded task status setter")
     .option("-o, --output <text>", "Patch: output")
-    .option("-d, --duration <ms>", "Patch: durationMs", parseInt)
+    .option("-d, --duration <ms>", "Patch: durationMs", intArg("--duration"))
     .option("-e, --error <text>", "Patch: errorMessage")
     .option("--json", "JSON output")
     .action((taskId, status, opts) => {

package/src/commands/infra.js

@@ -3,6 +3,7 @@
  */
 
 import { Command } from "commander";
+import { intArg, floatArg } from "../lib/cli-arg.js";
 
 import {
   DEAL_STATUS,
@@ -115,8 +116,8 @@ export function registerInfraCommand(program) {
     .requiredOption("-c, --cid <cid>", "Content CID")
     .requiredOption("-s, --size <bytes>", "Size in bytes", parseInt)
     .option("-m, --miner <id>", "Miner ID")
-    .option("-p, --price <fil>", "Price in FIL", parseFloat)
-    .option("-d, --duration <epochs>", "Duration in epochs", parseInt)
+    .option("-p, --price <fil>", "Price in FIL", floatArg("--price"))
+    .option("-d, --duration <epochs>", "Duration in epochs", intArg("--duration"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);
@@ -180,7 +181,7 @@ export function registerInfraCommand(program) {
     .command("deals")
     .description("List storage deals")
     .option("-s, --status <status>", "Filter by status")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);
@@ -205,7 +206,7 @@ export function registerInfraCommand(program) {
     .requiredOption("-c, --cid <cid>", "Content CID")
     .option("-p, --parent <cid>", "Parent CID")
     .option("-d, --dag <json>", "DAG structure")
-    .option("-n, --peers <n>", "Peer count", parseInt)
+    .option("-n, --peers <n>", "Peer count", intArg("--peers"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);
@@ -242,7 +243,7 @@ export function registerInfraCommand(program) {
     .command("versions")
     .description("List content versions")
     .option("-c, --cid <cid>", "Filter by content CID")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);
@@ -282,8 +283,8 @@ export function registerInfraCommand(program) {
       "Route type (tor/domain_front/mesh_ble/mesh_wifi/direct)",
     )
     .option("-e, --endpoint <url>", "Endpoint URL")
-    .option("-l, --latency <ms>", "Latency in ms", parseInt)
-    .option("-r, --reliability <0-1>", "Reliability score", parseFloat)
+    .option("-l, --latency <ms>", "Latency in ms", intArg("--latency"))
+    .option("-r, --reliability <0-1>", "Reliability score", floatArg("--reliability"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);
@@ -346,7 +347,7 @@ export function registerInfraCommand(program) {
     .description("List anti-censorship routes")
     .option("-t, --type <type>", "Filter by route type")
     .option("-s, --status <status>", "Filter by status")
-    .option("--limit <n>", "Max results", parseInt)
+    .option("--limit <n>", "Max results", intArg("--limit"))
     .option("--json", "JSON output")
     .action((opts) => {
       const db = _dbFromCtx(inf);

package/src/commands/instinct.js

@@ -9,6 +9,8 @@ import { bootstrap, shutdown } from "../runtime/bootstrap.js";
 import {
   getInstincts,
   getStrongInstincts,
+  exportInstincts,
+  importInstincts,
   resetInstincts,
   deleteInstinct,
   decayInstincts,
@@ -104,6 +106,70 @@ export function registerInstinctCommand(program) {
       }
     });
 
+  // instinct export — §8.3 cross-device backup: full dump of the instincts table
+  instinct
+    .command("export")
+    .description("Export all instincts as JSON (module 101 §8.3 backup)")
+    .option("--output <file>", "Write JSON array to file (default: stdout)")
+    .option("--json", "Output JSON ({ok,count} with --output; array otherwise)")
+    .action(async (options) => {
+      try {
+        const ctx = await bootstrap({ verbose: program.opts().verbose });
+        if (!ctx.db) {
+          logger.error("Database not available");
+          process.exit(1);
+        }
+        const rows = exportInstincts(ctx.db.getDatabase());
+        if (options.output) {
+          const fs = await import("fs");
+          fs.writeFileSync(options.output, JSON.stringify(rows), "utf-8");
+          if (options.json) {
+            console.log(JSON.stringify({ ok: true, count: rows.length, output: options.output }));
+          } else {
+            logger.log(`exported ${rows.length} instincts → ${options.output}`);
+          }
+        } else {
+          console.log(JSON.stringify(rows));
+        }
+        await shutdown();
+      } catch (err) {
+        logger.error(`instinct export failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // instinct import — §8.3 restore: idempotent upsert by id from a JSON-array file
+  instinct
+    .command("import")
+    .description("Import instincts from a JSON array file (idempotent upsert by id; §8.3)")
+    .requiredOption("--input <file>", "JSON array of instincts to import")
+    .option("--json", "Output JSON result")
+    .action(async (options) => {
+      try {
+        const fs = await import("fs");
+        const rows = JSON.parse(fs.readFileSync(options.input, "utf-8"));
+        if (!Array.isArray(rows)) {
+          throw new Error("import: expected a JSON array of instincts");
+        }
+        const ctx = await bootstrap({ verbose: program.opts().verbose });
+        if (!ctx.db) {
+          logger.error("Database not available");
+          process.exit(1);
+        }
+        const result = importInstincts(ctx.db.getDatabase(), rows);
+        if (options.json) {
+          console.log(JSON.stringify(result));
+        } else {
+          logger.log(`imported ${result.imported}, failed ${result.failed}`);
+        }
+        await shutdown();
+        if (!result.ok) process.exitCode = 1;
+      } catch (err) {
+        logger.error(`instinct import failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
   // instinct categories
   instinct
     .command("categories")