@aikdna/kdna-studio-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,10 @@
 # @aikdna/kdna-studio-cli
 
-Official Studio command-line authoring entry for KDNA.
+Official Studio command-line entry for KDNA judgment asset creation — turns your notes, documents, works, and feedback into loadable .kdna domains.
+
+Two authoring paths: interview-first (articulate your judgment directly) and distillation-first (provide content, find the patterns, confirm what's really you).
+
+Distillation-first authoring is domain-first: declare the target domain, owner scope, granularity, task scope, include areas, exclude areas, and load condition before extracting candidates. A single `.kdna` should stay scoped; complex work should compose multiple domain assets through a KDNA Cluster.
 
 This package provides the `kdna-studio` command. It creates Studio projects,
 imports evidence, manages judgment cards, checks Human Lock, compiles locked
@@ -25,6 +29,18 @@ npm install -g @aikdna/kdna-studio-cli
 ```bash
 kdna-studio create my_domain --name @yourscope/my_domain
 kdna-studio import my_domain ./notes.md
+kdna-studio target declare my_domain \
+  --category expression_writing \
+  --scope personal \
+  --granularity core_principles \
+  --task "longform article review" \
+  --include "argument structure,tone,revision" \
+  --exclude "life habits,food preference"
+kdna-studio source classify my_domain
+kdna-studio distill my_domain --candidates candidates.json
+kdna-studio candidate list my_domain
+kdna-studio candidate accept my_domain <candidate-id>
+kdna-studio candidate promote my_domain
 kdna-studio card add my_domain axiom \
   --field one_sentence="Prefer specific evidence over broad claims" \
   --field applies_when='["reviewing content"]' \
@@ -35,6 +51,8 @@ kdna-studio lock my_domain
 kdna-studio export my_domain --out dist/my_domain.kdna --sign
 ```
 
+Candidate promotion is scope-gated: only candidates with `status == accepted` and `scope_fit == true` are promoted to cards by default. Use `kdna-studio candidate override <project> <candidate-id>` only when a human intentionally overrides the scope gate.
+
 After export, use the runtime CLI:
 
 ```bash
@@ -44,3 +62,27 @@ kdna publish dist/my_domain.kdna
 
 `kdna-studio` is the CLI entry for trusted KDNA creation. `kdna` is the runtime
 control plane for existing `.kdna` assets.
+
+## Identity
+
+```bash
+kdna-studio identity init --name "Your Name"
+kdna-studio identity show
+```
+
+## Import from existing KDNA or legacy folders
+
+```bash
+# Fork an existing .kdna asset (cards imported as draft — re-lock required)
+kdna-studio create forked --from-kdna ./parent.kdna --name @scope/forked
+
+# Migrate a legacy JSON source folder
+kdna-studio create migrated --from-folder ./old-domain-json --name @scope/migrated
+```
+
+## Related
+
+- [KDNA Protocol](https://github.com/aikdna/kdna) — specification and schemas
+- [kdna-cli](https://github.com/aikdna/kdna-cli) — runtime CLI for verify, install, load, publish
+- [kdna-studio-core](https://github.com/aikdna/kdna-studio-core) — authoring SDK used by this CLI
+- [kdna-studio-swift](https://github.com/aikdna/kdna-studio-swift) — native Swift counterpart

package/bin/kdna-studio.js

@@ -12,13 +12,21 @@ const {
   compile: compileApi,
   quality,
   creator: creatorApi,
+  distillation: distillationApi,
 } = require('@aikdna/kdna-studio-core');
 
+const llm = require('../src/llm');
+const ai = require('../src/ai');
+
 const EXIT = { OK: 0, INPUT_ERROR: 2, HUMAN_LOCK_REQUIRED: 4, TRUST_FAILED: 5 };
 
 function usage() {
   console.log(`kdna-studio — Studio-compatible KDNA authoring CLI
 
+LLM (AI-powered authoring):
+  kdna-studio llm config [--provider <name>] [--model <name>] [--key <api-key>] [--url <base-url>]
+  kdna-studio llm show
+
 Identity:
   kdna-studio identity init [--name <display-name>]
   kdna-studio identity show
@@ -28,15 +36,39 @@ Create (three entry paths):
   kdna-studio create <project-dir> --from-kdna <file.kdna> --name <@scope/name>
   kdna-studio create <project-dir> --from-folder <source-dir> --name <@scope/name>
 
+Migrate (dev source → trusted .kdna in one command):
+  kdna-studio migrate <source-dir> --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--sign]
+
 Authoring:
-  kdna-studio import <project> <source-file>
+  kdna-studio import <project> <source-file-or-dir>               # import evidence (txt/md/json/yaml/csv/log/srt/vtt/html)
+  kdna-studio filter <project>                                    # check evidence for sensitive content
+  kdna-studio source classify <project>                            # classify evidence against declared target
   kdna-studio card list <project>
   kdna-studio card add <project> <type> --field key=value [--field key=value]
-  kdna-studio card approve <project> <card-id> --by <id> --statement <text> [--sign]
+  kdna-studio card approve <project> <card-id> --by <id> --statement <text> [--sign] [--passphrase <pass>]
   kdna-studio lock <project>
   kdna-studio compile <project> --out <dir>
   kdna-studio export <project> --out <file.kdna> [--sign]
+
+AI Authoring (requires LLM config: kdna-studio llm config):
+  kdna-studio distill <project> --ai                             # AI-driven candidate extraction from evidence
+  kdna-studio distill <project> --candidates <file.json>          # load pre-generated AI candidates
+  kdna-studio interview <project> [--stage <name>]               # 4-stage guided AI interview
+  kdna-studio feynman <project> <card-id>                        # AI Feynman evaluation (5-dimension)
+  kdna-studio test <project> --input "<text>" [--preset baseline|edge|contradiction]
+
+Distillation:
+  kdna-studio target declare <project>                           # declare distillation target interactively
+  kdna-studio target declare <project> --category <cat> --scope <scope> --granularity <gran> --task <task> [--include <area,area>] [--exclude <area,area>] [--load-condition <condition>]
+  kdna-studio target show <project>                              # show current distillation target
+  kdna-studio candidate list <project>                           # list candidates with scope and status
+  kdna-studio candidate accept <project> <candidate-id>
+  kdna-studio candidate reject <project> <candidate-id>
+  kdna-studio candidate override <project> <candidate-id>        # override scope gate
+  kdna-studio candidate promote <project>                        # promote accepted+scope_fit → cards
   kdna-studio report <project>
+  kdna-studio install <@scope/name|file.kdna> [--trusted]
+  kdna-studio update <@scope/name>
 
 Project may be a directory containing studio.project.json or a project JSON file.`);
 }
@@ -157,7 +189,7 @@ function cmdCreate(args) {
     }
   } else if (fromFolder) {
     sourceMode = 'source_folder';
-    importFromFolder(fromFolder, abs, name);
+    importFromFolder(fromFolder, abs, name, creatorIdentity);
     return;
   }
 
@@ -253,13 +285,14 @@ function importFromKdna(kdnaPath) {
  * Reads KDNA_*.json files and converts entries to draft judgment cards.
  * Outputs a schema audit report.
  */
-function importFromFolder(sourceDir, projectDir, projectName) {
+function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
   const absSource = path.resolve(sourceDir);
   if (!fs.existsSync(absSource)) fail(`Source folder not found: ${absSource}`);
   if (!fs.statSync(absSource).isDirectory()) fail('--from-folder requires a directory');
 
   const audit = { filesFound: [], cardsImported: 0, missingFields: [], schemaWarnings: [] };
   const importedCards = [];
+  const manifestData = {};
 
   function loadJson(filename) {
     const p = path.join(absSource, filename);
@@ -269,6 +302,17 @@ function importFromFolder(sourceDir, projectDir, projectName) {
     catch { audit.schemaWarnings.push(`${filename}: invalid JSON`); return null; }
   }
 
+  // Load manifest for version/languages/description
+  const manifest = loadJson('kdna.json');
+  if (manifest) {
+    if (manifest.version) manifestData.version = manifest.version;
+    if (manifest.judgment_version) manifestData.judgment_version = manifest.judgment_version;
+    if (manifest.languages) manifestData.languages = manifest.languages;
+    if (manifest.default_language) manifestData.default_language = manifest.default_language;
+    if (manifest.description) manifestData.description = manifest.description;
+    if (manifest.name) manifestData.name = manifest.name;
+  }
+
   const core = loadJson('KDNA_Core.json');
   const patterns = loadJson('KDNA_Patterns.json');
   const scenarios = loadJson('KDNA_Scenarios.json');
@@ -301,9 +345,38 @@ function importFromFolder(sourceDir, projectDir, projectName) {
     for (const r of (core.risks || core.risk_model || [])) {
       importedCards.push(cardApi.createCard('risk', r.fields || r));
     }
+    // NEW: import stances
+    for (const s of (core.stances || [])) {
+      const text = typeof s === 'string' ? s : s.stance || '';
+      importedCards.push(cardApi.createCard('stance', {
+        statement: text,
+        applies_when: s.applies_when || [],
+        does_not_apply_when: s.does_not_apply_when || [],
+      }));
+    }
+    // NEW: import frameworks
+    for (const fw of (core.frameworks || [])) {
+      importedCards.push(cardApi.createCard('framework', {
+        name: fw.name || '', when_to_use: fw.when_to_use || '',
+        steps: fw.steps || [],
+      }));
+    }
   }
 
   if (patterns) {
+    // NEW: import terminology
+    if (patterns.terminology) {
+      for (const t of (patterns.terminology.standard_terms || [])) {
+        importedCards.push(cardApi.createCard('term', {
+          term: t.term || '', definition: t.definition || '',
+        }));
+      }
+      for (const bt of (patterns.terminology.banned_terms || [])) {
+        importedCards.push(cardApi.createCard('banned_term', {
+          term: bt.term || '', why: bt.why || '', replace_with: bt.replace_with || '',
+        }));
+      }
+    }
     for (const ms of (patterns.misunderstandings || [])) {
       importedCards.push(cardApi.createCard('misunderstanding', {
         wrong: ms.wrong || '', correct: ms.correct || '',
@@ -316,14 +389,70 @@ function importFromFolder(sourceDir, projectDir, projectName) {
     }
   }
 
+  // NEW: import scenarios
+  if (scenarios && scenarios.scenes) {
+    for (const scene of scenarios.scenes) {
+      importedCards.push(cardApi.createCard('scenario', {
+        name: scene.name || scene.id || '',
+        trigger: scene.trigger || '', action: scene.action || '',
+      }));
+    }
+  }
+
+  // NEW: import cases
+  if (cases && cases.cases) {
+    for (const c of cases.cases) {
+      importedCards.push(cardApi.createCard('case', {
+        title: c.title || c.id || '',
+        scenario: c.scenario || '', expected: c.expected || '',
+      }));
+    }
+  }
+
+  // NEW: import reasoning chains
+  if (reasoning && reasoning.reasoning_chains) {
+    for (const rc of reasoning.reasoning_chains) {
+      importedCards.push(cardApi.createCard('reasoning', {
+        name: rc.name || rc.id || '', conclusion: rc.conclusion || '',
+        so_what: rc.so_what || '',
+      }));
+    }
+  }
+
+  // NEW: import evolution stages
+  if (evolution && evolution.stages) {
+    for (const stage of evolution.stages) {
+      importedCards.push(cardApi.createCard('evolution_stage', {
+        name: stage.name || stage.id || '',
+        level: stage.level || '', description: stage.description || '',
+      }));
+    }
+  }
+
   audit.cardsImported = importedCards.length;
 
   const project = projectApi.createProject(projectName, 'domain', {
     sourceMode: 'source_folder',
     sourcePath: absSource,
-    creatorIdentity: null,
-    lineage: { type: 'migrated', parent_name: null, parent_asset_uid: null, parent_version: null, parent_asset_digest: null },
+    creatorIdentity: creatorIdentity || null,
+    lineage: { type: 'migrated', parent_name: manifestData.name || null, parent_asset_uid: null, parent_version: manifestData.version || null, parent_asset_digest: null },
   });
+  // Preserve manifest metadata
+  if (manifestData.version) {
+    if (!project.release) project.release = {};
+    project.release.version = manifestData.version;
+  }
+  if (manifestData.judgment_version) {
+    if (!project.release) project.release = {};
+    project.release.judgment_version = manifestData.judgment_version;
+  }
+  if (manifestData.description) {
+    if (!project.release) project.release = {};
+    project.release.description = manifestData.description;
+  }
+  if (manifestData.languages) project.languages = manifestData.languages;
+  if (manifestData.default_language) project.default_language = manifestData.default_language;
+
   project.cards = importedCards;
   if (project.stages?.judgment_cards) {
     project.stages.judgment_cards.total = importedCards.length;
@@ -333,6 +462,7 @@ function importFromFolder(sourceDir, projectDir, projectName) {
   fs.mkdirSync(projectDir, { recursive: true });
   writeProject(path.join(projectDir, 'studio.project.json'), project);
   console.log(JSON.stringify({ audit, imported: importedCards.length, source_mode: 'source_folder' }, null, 2));
+  return { project, projectPath: path.join(projectDir, 'studio.project.json'), audit };
 }
 
 /**
@@ -380,17 +510,85 @@ function readZipEntries(buf) {
   return entries;
 }
 
+const aiFilter = require('../src/ai/filter');
+
 function cmdImport(args) {
   const [projectInput, source] = args;
-  if (!projectInput || !source) fail('Usage: kdna-studio import <project> <source-file>');
+  if (!projectInput || !source) fail('Usage: kdna-studio import <project> <source-file-or-dir>');
   const { projectPath, project } = readProject(projectInput);
+
   const sourcePath = path.resolve(source);
-  if (!fs.existsSync(sourcePath)) fail(`Source file not found: ${sourcePath}`);
-  const content = fs.readFileSync(sourcePath, 'utf8');
-  const evidence = evidenceApi.createEvidenceEntry('text', path.basename(sourcePath), content, sourcePath);
-  evidenceApi.addEvidence(project, evidence);
+  if (!fs.existsSync(sourcePath)) fail(`Source not found: ${sourcePath}`);
+
+  const TEXT_EXTS = new Set(['.txt', '.md', '.json', '.jsonl', '.yaml', '.yml', '.csv', '.log', '.srt', '.vtt', '.html', '.xml', '.rst']);
+  const BINARY_EXTS = new Set(['.pdf', '.docx', '.rtf']);
+  let imported = 0;
+  let skipped = 0;
+
+  function importFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const name = path.basename(filePath);
+
+    if (BINARY_EXTS.has(ext)) {
+      console.warn(`Skipping binary format (not yet supported in CLI): ${name}`);
+      skipped++;
+      return;
+    }
+
+    let content;
+    try { content = fs.readFileSync(filePath, 'utf8'); } catch { console.warn(`Cannot read: ${name}`); skipped++; return; }
+
+    if (content.length > 120000) {
+      console.warn(`File too large (${content.length} chars, max 120000): ${name}`);
+      skipped++;
+      return;
+    }
+
+    const evidence = evidenceApi.createEvidenceEntry('text', name, content, filePath);
+    evidenceApi.addEvidence(project, evidence);
+    imported++;
+  }
+
+  if (fs.statSync(sourcePath).isDirectory()) {
+    const files = fs.readdirSync(sourcePath).map(f => path.join(sourcePath, f)).filter(f => fs.statSync(f).isFile());
+    for (const f of files) {
+      if (imported >= 300) { console.warn('Reached 300 file limit.'); break; }
+      importFile(f);
+    }
+  } else {
+    importFile(sourcePath);
+  }
+
   writeProject(projectPath, project);
-  console.log(`Imported evidence: ${evidence.id}`);
+
+  // Check for sensitive content
+  const evidenceList = project.evidence_materials || [];
+  const flagged = aiFilter.checkEvidence(evidenceList);
+  if (flagged.length > 0) {
+    console.warn(`\nSensitive content detected in ${flagged.length} file(s):`);
+    for (const f of flagged) console.warn(`  ${f.filename}: ${f.flagged.join(', ')}`);
+  }
+
+  console.log(`Imported: ${imported} file(s)${skipped > 0 ? `, ${skipped} skipped` : ''}`);
+}
+
+function cmdFilter(args) {
+  const projectInput = args[0];
+  if (!projectInput) fail('Usage: kdna-studio filter <project>');
+  const { project } = readProject(projectInput);
+  const evidenceList = project.evidence_materials || [];
+  if (evidenceList.length === 0) { console.log('No evidence to filter.'); return; }
+
+  const flagged = aiFilter.checkEvidence(evidenceList);
+  if (flagged.length === 0) {
+    console.log(`All ${evidenceList.length} evidence file(s) passed sensitive content filter.`);
+  } else {
+    console.log(`Sensitive content detected in ${flagged.length}/${evidenceList.length} file(s):`);
+    for (const f of flagged) {
+      console.log(`  ${f.filename}: ${f.flagged.join(', ')}`);
+      for (const [domain, match] of Object.entries(f.matches)) console.log(`    ${domain}: "${match}"`);
+    }
+  }
 }
 
 function cmdCard(args) {
@@ -420,46 +618,66 @@ function cmdCard(args) {
   if (sub === 'approve') {
     const projectInput = args[1];
     const cardId = args[2];
-    if (!projectInput || !cardId) {
+    const approveAll = args.includes('--all');
+    if (!projectInput || (!cardId && !approveAll)) {
       fail('Usage: kdna-studio card approve <project> <card-id> --by <id> --statement <text> [--sign]');
     }
     const by = option(args, '--by');
     const statement = option(args, '--statement');
     if (!by || !statement) fail('card approve requires --by and --statement');
     const { projectPath, project } = readProject(projectInput);
-    const idx = (project.cards || []).findIndex((c) => c.id === cardId);
-    if (idx < 0) fail(`Card not found: ${cardId}`);
-    let card = project.cards[idx];
-    if (card.status === 'draft') card = cardApi.transitionCard(card, 'revised', { by });
 
-    const lockPayload = {
-      by,
-      statement,
-      checked: { applies_when: true, does_not_apply_when: true, failure_risk: true },
+    const lockOneCard = (card) => {
+      if (card.status === 'draft') card = cardApi.transitionCard(card, 'revised', { by });
+      const lockPayload = {
+        by,
+        statement,
+        checked: { applies_when: true, does_not_apply_when: true, failure_risk: true },
+      };
+      if (args.includes('--sign')) {
+        const identity = creatorApi.loadIdentity();
+        if (!identity) fail('No creator identity. Run: kdna-studio identity init --name "Your Name"', EXIT.TRUST_FAILED);
+        lockPayload.creator_id = identity.creator_id;
+        const passphrase = option(args, '--passphrase');
+        try {
+          if (identity.encrypted && !passphrase) {
+            fail('Private key is encrypted — provide --passphrase to sign.', EXIT.TRUST_FAILED);
+          }
+          lockPayload.signature = creatorApi.signHumanLock(
+            card.id, statement, cardApi.cardJudgmentFingerprint(card), null, passphrase,
+          );
+        } catch (e) {
+          fail(`Failed to sign Human Lock: ${e.message}`, EXIT.TRUST_FAILED);
+        }
+      }
+      return [card, cardApi.lockCard(card, lockPayload)];
     };
 
-    // Sign Human Lock with creator identity if --sign is passed
-    if (args.includes('--sign')) {
-      const identity = creatorApi.loadIdentity();
-      if (!identity) fail('No creator identity. Run: kdna-studio identity init --name "Your Name"', EXIT.TRUST_FAILED);
-      lockPayload.creator_id = identity.creator_id;
-      try {
-        lockPayload.signature = creatorApi.signHumanLock(
-          cardId, statement, cardApi.cardJudgmentFingerprint(card),
-        );
-      } catch (e) {
-        fail(`Failed to sign Human Lock: ${e.message}`, EXIT.TRUST_FAILED);
+    if (cardId) {
+      const idx = (project.cards || []).findIndex((c) => c.id === cardId);
+      if (idx < 0) fail(`Card not found: ${cardId}`);
+      const [, locked] = lockOneCard(project.cards[idx]);
+      project.cards[idx] = locked;
+      const signed = args.includes('--sign') ? ' (signed)' : '';
+      console.log(`Approved and Human Locked: ${cardId}${signed}`);
+    } else {
+      let approved = 0;
+      for (let i = 0; i < (project.cards || []).length; i++) {
+        const card = project.cards[i];
+        if (card.locked) continue;
+        const [, locked] = lockOneCard(card);
+        project.cards[i] = locked;
+        approved++;
       }
+      if (approved === 0) fail('No unlocked cards to approve.');
+      const signed = args.includes('--sign') ? ' (signed)' : '';
+      console.log(`Approved and Human Locked: ${approved} cards${signed}`);
     }
-
-    project.cards[idx] = cardApi.lockCard(card, lockPayload);
     if (project.stages?.judgment_cards) {
       project.stages.judgment_cards.locked = project.cards.filter((c) => c.locked).length;
       project.stages.judgment_cards.total = project.cards.length;
     }
     writeProject(projectPath, project);
-    const signed = lockPayload.signature ? ' (signed)' : '';
-    console.log(`Approved and Human Locked: ${cardId}${signed}`);
     return;
   }
   fail('Usage: kdna-studio card <list|add|approve> ...');
@@ -476,6 +694,83 @@ function cmdLock(args) {
   console.log(`Human Lock Gate passed: ${gate.lockedJudgmentCards} locked judgment cards`);
 }
 
+function cmdMigrate(args) {
+  const sourceDir = args[0];
+  const out = option(args, '--out');
+  const by = option(args, '--by');
+  const statement = option(args, '--statement');
+  const name = option(args, '--name') || path.basename(path.resolve(sourceDir || '.'));
+  if (!sourceDir || !out || !by || !statement) {
+    fail('Usage: kdna-studio migrate <source-dir> --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--sign] [--passphrase <pass>]');
+  }
+
+  // Step 1: create temp project and import everything from dev source
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-migrate-'));
+  let creatorIdentity = null;
+  try { creatorIdentity = creatorApi.loadIdentity(); } catch { /* proceed without */ }
+  const { project } = importFromFolder(sourceDir, tmpDir, name, creatorIdentity);
+
+  // Step 2: approve and Human Lock all cards
+  let locked = 0;
+  for (let i = 0; i < (project.cards || []).length; i++) {
+    let card = project.cards[i];
+    if (card.locked) { locked++; continue; }
+    if (card.status === 'draft') card = cardApi.transitionCard(card, 'revised', { by });
+    const lockPayload = {
+      by,
+      statement,
+      checked: { applies_when: true, does_not_apply_when: true, failure_risk: true },
+    };
+    if (args.includes('--sign')) {
+      const identity = creatorApi.loadIdentity();
+      if (!identity) fail('No creator identity. Run: kdna-studio identity init --name "Your Name"', EXIT.TRUST_FAILED);
+      lockPayload.creator_id = identity.creator_id;
+      const passphrase = option(args, '--passphrase');
+      try {
+        lockPayload.signature = creatorApi.signHumanLock(
+          card.id, statement, cardApi.cardJudgmentFingerprint(card), null, passphrase,
+        );
+      } catch (e) {
+        fail(`Failed to sign Human Lock for ${card.id}: ${e.message}`, EXIT.TRUST_FAILED);
+      }
+    }
+    project.cards[i] = cardApi.lockCard(card, lockPayload);
+    locked++;
+  }
+  if (project.stages?.judgment_cards) {
+    project.stages.judgment_cards.locked = locked;
+    project.stages.judgment_cards.total = project.cards.length;
+  }
+  writeProject(path.join(tmpDir, 'studio.project.json'), project);
+  console.log(`Approved and Human Locked: ${locked} cards`);
+
+  // Step 3: verify Human Lock gate
+  const gate = projectApi.checkHumanLockGate(project);
+  if (gate.blocked) {
+    const reasons = gate.issues.map((i) => `${i.cardId}: ${i.reason}`).join('\n  - ');
+    fail(`Human Lock Gate blocked: ${reasons}`, EXIT.HUMAN_LOCK_REQUIRED);
+  }
+
+  // Step 4: compile and export as .kdna
+  const { result } = compileProject(tmpDir);
+  const files = { ...result.files };
+  files['README.md'] = compileApi.generateReadme(project);
+  files.LICENSE = project.license?.type || 'UNSPECIFIED';
+  files.mimetype = 'application/vnd.aikdna.kdna+zip';
+
+  if (args.includes('--sign')) applySignature(files, option(args, '--passphrase'));
+  const absOut = path.resolve(out);
+  buildZip(files, absOut);
+  console.log(`Exported: ${absOut}`);
+  console.log(`  Name: ${name}`);
+  console.log(`  Cards: ${project.cards.length} (${locked} locked)`);
+  console.log(`  Files: ${Object.keys(files).length}`);
+  console.log(`  Build ID: ${result.identity.build_id}`);
+
+  // Cleanup temp
+  try { fs.rmSync(tmpDir, { recursive: true }); } catch { /* best effort */ }
+}
+
 function compileProject(projectInput) {
   const { project } = readProject(projectInput);
   const gate = projectApi.checkHumanLockGate(project);
@@ -623,7 +918,7 @@ function publicKeyFingerprint(publicKeyPem) {
   return `ed25519:${crypto.createHash('sha256').update(publicKeyPem).digest('hex')}`;
 }
 
-function applySignature(files) {
+function applySignature(files, passphrase = null) {
   const paths = identityPaths();
   if (!fs.existsSync(paths.privateKey) || !fs.existsSync(paths.publicKey)) {
     fail('Signing requires KDNA identity keys. Run: kdna identity init', EXIT.TRUST_FAILED);
@@ -636,7 +931,13 @@ function applySignature(files) {
   files['kdna.json'] = JSON.stringify(manifest, null, 2);
 
   const payload = canonicalPayload(files);
-  const privateKeyPem = fs.readFileSync(paths.privateKey, 'utf8');
+  let privateKeyPem = fs.readFileSync(paths.privateKey, 'utf8');
+  if (creatorApi.isEncryptedKey(privateKeyPem)) {
+    if (!passphrase) {
+      fail('Private key is encrypted. Export with: kdna-studio export ... --sign --passphrase <your-passphrase>', EXIT.TRUST_FAILED);
+    }
+    privateKeyPem = creatorApi.decryptPrivateKey(privateKeyPem, passphrase);
+  }
   manifest.signature = `ed25519:${crypto.sign(null, Buffer.from(payload), privateKeyPem).toString('hex')}`;
   files['kdna.json'] = JSON.stringify(manifest, null, 2);
 }
@@ -673,7 +974,7 @@ function cmdExport(args) {
   provenance.content_fingerprint = finalDigest;
   files['reports/provenance-report.json'] = JSON.stringify(provenance, null, 2);
 
-  if (args.includes('--sign')) applySignature(files);
+  if (args.includes('--sign')) applySignature(files, option(args, '--passphrase'));
 
   const entries = [['mimetype', files.mimetype]];
   for (const name of Object.keys(files).filter(k => k !== 'mimetype').sort()) {
@@ -700,18 +1001,80 @@ function cmdExport(args) {
   console.log(`Build ID: ${result.identity.build_id}`);
 }
 
+function cmdStudioInstall(args) {
+  // Delegate to kdna CLI for runtime install operations
+  const target = args[0];
+  if (!target) fail('Usage: kdna-studio install <@scope/name|file.kdna>');
+  try {
+    const kdnaArgs = ['install', target, '--yes'];
+    if (args.includes('--trusted')) kdnaArgs.push('--trusted');
+    const result = require('child_process').spawnSync('kdna', kdnaArgs, {
+      stdio: 'inherit', encoding: 'utf8',
+    });
+    if (result.status !== 0) process.exit(result.status);
+  } catch {
+    fail('kdna CLI not found. Install with: npm install -g @aikdna/kdna-cli');
+  }
+}
+
+function cmdStudioUpdate(args) {
+  const target = args[0];
+  if (!target) fail('Usage: kdna-studio update <@scope/name>');
+  try {
+    const result = require('child_process').spawnSync('kdna', ['update', target], {
+      stdio: 'inherit', encoding: 'utf8',
+    });
+    if (result.status !== 0) process.exit(result.status);
+  } catch {
+    fail('kdna CLI not found. Install with: npm install -g @aikdna/kdna-cli');
+  }
+}
+
+function cmdLlm(args) {
+  const sub = args[0];
+  if (sub === 'show') {
+    const cfg = llm.config();
+    console.log(`Provider : ${cfg.provider || '(not set)'}`);
+    console.log(`Model    : ${cfg.model || '(not set)'}`);
+    console.log(`Base URL : ${cfg.baseURL || '(not set)'}`);
+    console.log(`API Key  : ${cfg.apiKey ? '********' + cfg.apiKey.slice(-4) : '(not set)'}`);
+    return;
+  }
+  if (sub === 'config') {
+    const provider = option(args, '--provider') || option(args, '-p');
+    const model = option(args, '--model') || option(args, '-m');
+    const apiKey = option(args, '--key') || option(args, '-k');
+    const baseURL = option(args, '--url') || option(args, '-u');
+    const updates = {};
+    if (provider) updates.provider = provider;
+    if (model) updates.model = model;
+    if (apiKey) updates.apiKey = apiKey;
+    if (baseURL) updates.baseURL = baseURL;
+    if (Object.keys(updates).length === 0) fail('Usage: kdna-studio llm config --provider <name> [--model <name>] [--key <api-key>] [--url <base-url>]');
+    const cfg = llm.configure(updates);
+    console.log(JSON.stringify({ provider: cfg.provider, model: cfg.model, baseURL: cfg.baseURL }, null, 2));
+    return;
+  }
+  fail('Usage: kdna-studio llm <config|show>');
+}
+
 function cmdIdentity(args) {
   const sub = args[0];
   if (sub === 'init') {
     const name = option(args, '--name', process.env.USER || process.env.USERNAME || '');
+    const passphrase = option(args, '--passphrase');
     try {
-      const identity = creatorApi.initIdentity(name);
+      const identity = creatorApi.initIdentity(name, null, passphrase);
       console.log(`Creator identity initialized:`);
       console.log(`  creator_id: ${identity.creator_id}`);
       console.log(`  display_name: ${identity.display_name}`);
       console.log(`  identity_dir: ${identity.identity_dir}`);
       console.log(`  public_key saved: ${identity.public_key_path}`);
+      console.log(`  encrypted: ${identity.encrypted}`);
       console.log(`\nBack up your private key at: ${creatorApi.privateKeyPath()}`);
+      if (identity.encrypted) {
+        console.log(`  Private key is encrypted — keep your passphrase safe.`);
+      }
     } catch (err) {
       fail(`Identity already exists. Use 'kdna-studio identity show' to view. ${err.message}`);
     }
@@ -739,6 +1102,269 @@ function cmdReport(args) {
   process.exit(gate.blocked ? EXIT.HUMAN_LOCK_REQUIRED : EXIT.OK);
 }
 
+// ─── Distillation Commands ──────────────────────────────────────────
+
+function cmdTarget(args) {
+  const sub = args[0];
+  if (sub === 'declare') {
+    const projectInput = args[1];
+    if (!projectInput) fail('Usage: kdna-studio target declare <project> --category <cat> --scope <scope> --granularity <gran> --task <task>');
+    const { projectPath, project } = readProject(projectInput);
+    const category = option(args, '--category', 'expression_writing');
+    const scope = option(args, '--scope', 'personal');
+    const granularity = option(args, '--granularity', 'core_principles');
+    const taskScope = option(args, '--task', 'general content creation');
+    const include = option(args, '--include');
+    const exclude = option(args, '--exclude');
+    const loadCondition = option(args, '--load-condition');
+    const domainName = project.name || path.basename(path.dirname(projectPath), '.json');
+
+    const target = distillationApi.createDistillationTarget({
+      domainName,
+      domainCategory: category,
+      ownerScope: scope,
+      granularity,
+      taskScope,
+      includeAreas: include ? include.split(',').map(s => s.trim()).filter(Boolean) : [],
+      excludeAreas: exclude ? exclude.split(',').map(s => s.trim()).filter(Boolean) : [],
+      loadCondition: loadCondition || '',
+    });
+
+    const validation = distillationApi.validateDistillationTarget(target);
+    if (!validation.valid) fail(`Invalid target: ${validation.errors.join('; ')}`);
+
+    project.distillation_target = target;
+    writeProject(projectPath, project);
+    console.log(JSON.stringify({ declared: true, target }, null, 2));
+    return;
+  }
+  if (sub === 'show') {
+    const { project } = readProject(args[1]);
+    const target = project.distillation_target;
+    if (!target) fail('No distillation target declared. Run: kdna-studio target declare <project>');
+    console.log(JSON.stringify(target, null, 2));
+    return;
+  }
+  fail('Usage: kdna-studio target <declare|show>');
+}
+
+function cmdSourceClassify(args) {
+  const projectInput = args[0];
+  if (!projectInput) fail('Usage: kdna-studio source classify <project>');
+  const { projectPath, project } = readProject(projectInput);
+  const target = project.distillation_target;
+  if (!target) fail('Declare a distillation target first: kdna-studio target declare <project>');
+
+  const evidence = project.evidence || [];
+  const results = evidence.map(e => {
+    const text = (e.content || e.title || '').toLowerCase();
+    const domainWords = (target.include_areas || []).concat([target.domain_category, target.task_scope]);
+    const hitCount = domainWords.filter(w => text.includes(w.toLowerCase())).length;
+    let relevance;
+    if (hitCount >= 2) relevance = 'relevant';
+    else if (hitCount === 1) relevance = 'weakly_relevant';
+    else {
+      const otherHits = Object.keys(distillationApi.DOMAIN_CATEGORIES)
+        .filter(k => k !== target.domain_category)
+        .filter(k => text.includes(k)).length;
+      relevance = otherHits > 0 ? 'split_domain' : 'weakly_relevant';
+    }
+    return { id: e.id, title: e.title, relevance };
+  });
+
+  const summary = {};
+  for (const r of results) { summary[r.relevance] = (summary[r.relevance] || 0) + 1; }
+
+  project.distillation_evidence_relevance = results;
+  writeProject(projectPath, project);
+  console.log(JSON.stringify({ summary, results }, null, 2));
+}
+
+async function cmdDistill(args) {
+  const projectInput = args[0];
+  const candidatesFile = option(args, '--candidates');
+  const useAI = args.includes('--ai');
+  const provider = option(args, '--provider');
+  const model = option(args, '--model');
+  const apiKey = option(args, '--key');
+  if (!projectInput) fail('Usage: kdna-studio distill <project> [--ai] [--candidates <file.json>]');
+  if (!candidatesFile && !useAI) fail('Either --ai or --candidates <file.json> required.');
+
+  const { projectPath, project } = readProject(projectInput);
+  const target = project.distillation_target;
+  if (!target) fail('Declare a distillation target first: kdna-studio target declare <project>');
+
+  let rawCandidates;
+  if (useAI) {
+    const evidence = (project.evidence_materials || []).map(e => ({ filename: e.filename || e.name, content: e.raw_text || e.content || '' }));
+    if (evidence.length === 0) console.warn('No evidence materials found. AI distillation works best with imported evidence. Run: kdna-studio import <project> <file>');
+
+    console.log('Running AI distillation...');
+    rawCandidates = await ai.distill(llm.config(), evidence, target, { provider, model, apiKey });
+    console.log(`AI extracted ${rawCandidates.length} candidates.`);
+  } else {
+    const rawPath = path.resolve(candidatesFile);
+    if (!fs.existsSync(rawPath)) fail(`Candidates file not found: ${rawPath}`);
+    rawCandidates = JSON.parse(fs.readFileSync(rawPath, 'utf8'));
+    if (!Array.isArray(rawCandidates)) fail('Candidates file must contain a JSON array');
+  }
+
+  const candidates = rawCandidates.map(c => {
+    const base = {
+      id: c.candidate_id || c.id || `cand_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      one_sentence: c.one_sentence || c.oneSentence || '',
+      full_statement: c.full_statement || c.fullStatement || '',
+      suggested_card_type: c.type || c.suggested_card_type || 'axiom',
+      supporting_evidence_ids: (c.evidence_ids || c.evidenceIds || c.supporting_evidence_ids || []).map(String),
+      confidence: c.confidence || 'medium',
+      candidate_status: 'proposed',
+      scope_fit: c.scope_fit ?? c.scopeFit ?? true,
+    };
+    return distillationApi.applyScopeGate(base, target);
+  });
+
+  const summary = distillationApi.candidateStatusSummary(candidates);
+  project.distillation_candidates = candidates;
+  writeProject(projectPath, project);
+  console.log(JSON.stringify({ summary, count: candidates.length }, null, 2));
+}
+
+function cmdCandidate(args) {
+  const sub = args[0];
+  const projectInput = args[1];
+  if (!sub || !projectInput) fail('Usage: kdna-studio candidate <list|accept|reject|override|promote>');
+
+  const { projectPath, project } = readProject(projectInput);
+  const candidates = project.distillation_candidates || [];
+
+  if (sub === 'list') {
+    for (const c of candidates) {
+      const scopeMarker = c.scope_fit ? '' : ' [OUT_OF_SCOPE]';
+      const split = c.suggested_split_domain ? ` → ${c.suggested_split_domain}` : '';
+      console.log(`${c.id}\t${c.candidate_status}\t${c.suggested_card_type}\t${c.confidence}\t${c.one_sentence.substring(0,60)}${scopeMarker}${split}`);
+    }
+    console.log(JSON.stringify(distillationApi.candidateStatusSummary(candidates), null, 2));
+    return;
+  }
+
+  if (sub === 'accept' || sub === 'reject') {
+    const candId = args[2];
+    if (!candId) fail(`Usage: kdna-studio candidate ${sub} <project> <candidate-id>`);
+    const idx = candidates.findIndex(c => c.id === candId);
+    if (idx < 0) fail(`Candidate not found: ${candId}`);
+    candidates[idx].candidate_status = sub === 'accept' ? 'accepted' : 'rejected';
+    project.distillation_candidates = candidates;
+    writeProject(projectPath, project);
+    console.log(`${sub === 'accept' ? 'Accepted' : 'Rejected'}: ${candId}`);
+    return;
+  }
+
+  if (sub === 'override') {
+    const candId = args[2];
+    if (!candId) fail('Usage: kdna-studio candidate override <project> <candidate-id>');
+    const idx = candidates.findIndex(c => c.id === candId);
+    if (idx < 0) fail(`Candidate not found: ${candId}`);
+    candidates[idx].scope_fit = true;
+    candidates[idx].domain_relevance_score = 50;
+    candidates[idx].relevance_evidence = 'User explicitly overrode scope gate via CLI';
+    candidates[idx].suggested_split_domain = null;
+    project.distillation_candidates = candidates;
+    writeProject(projectPath, project);
+    console.log(`Scope gate overridden: ${candId}`);
+    return;
+  }
+
+  if (sub === 'promote') {
+    const accepted = candidates.filter(c => c.candidate_status === 'accepted' && c.scope_fit !== false);
+    if (accepted.length === 0) fail('No candidates to promote. Accept some candidates first.');
+
+    for (const c of accepted) {
+      const card = cardApi.createCard(c.suggested_card_type, {
+        one_sentence: c.one_sentence,
+        full_statement: c.full_statement,
+        why: '',
+        applies_when: '',
+        does_not_apply_when: '',
+        failure_risk: '',
+      });
+      card.evidence_refs = c.supporting_evidence_ids;
+      project.cards = project.cards || [];
+      project.cards.push(card);
+    }
+    if (project.stages?.judgment_cards) {
+      project.stages.judgment_cards.total = project.cards.length;
+      project.stages.judgment_cards.status = 'in_progress';
+    }
+    writeProject(projectPath, project);
+    console.log(`Promoted ${accepted.length} candidates → ${accepted.length} Studio cards`);
+    return;
+  }
+
+  fail('Usage: kdna-studio candidate <list|accept|reject|override|promote>');
+}
+
+async function cmdInterview(args) {
+  const projectInput = args[0];
+  const stage = option(args, '--stage');
+  if (!projectInput) fail('Usage: kdna-studio interview <project> [--stage distill|clarify|correct|replay]');
+  const { project } = readProject(projectInput);
+
+  if (stage) {
+    const result = await ai.interview.runInterview(llm.config(), project, stage, '', {});
+    console.log(`\n=== ${result.label} ===\n${result.content}`);
+  } else {
+    await ai.interview.runInterviewInteractive(llm.config(), project, {});
+  }
+}
+
+async function cmdFeynman(args) {
+  const projectInput = args[0];
+  const cardId = args[1];
+  if (!projectInput || !cardId) fail('Usage: kdna-studio feynman <project> <card-id>');
+  const { projectPath, project } = readProject(projectInput);
+  const cardIdx = (project.cards || []).findIndex(c => c.id === cardId);
+  if (cardIdx < 0) fail(`Card not found: ${cardId}`);
+  const card = project.cards[cardIdx];
+
+  if (!card.feynman_text) fail(`Card ${cardId} has no Feynman restatement. Use card approve first with --statement to set it.`);
+
+  console.log(`Evaluating Feynman restatement for card: ${cardId}`);
+  const result = await ai.feynman.evaluate(llm.config(), card, {});
+  const score = result.score || 0;
+  const passed = score >= 4;
+
+  console.log(`Score: ${score}/5 ${passed ? '✓ publishable' : '✗ below threshold (need 4/5)'}`);
+  for (const [criterion, desc] of Object.entries(ai.feynman.CRITERIA)) {
+    const r = (result.criteria || {})[criterion] ? '✓' : '✗';
+    console.log(`  ${r} ${criterion}`);
+  }
+  if (result.suggestions && result.suggestions.length > 0) {
+    console.log('\nSuggestions:');
+    result.suggestions.forEach(s => console.log(`  - ${s}`));
+  }
+
+  card.feynman_evaluation = { score, criteria: result.criteria, suggestions: result.suggestions, evaluated_at: new Date().toISOString() };
+  project.cards[cardIdx] = card;
+  writeProject(projectPath, project);
+}
+
+async function cmdTest(args) {
+  const projectInput = args[0];
+  const input = option(args, '--input');
+  const preset = option(args, '--preset', 'baseline');
+  if (!projectInput || !input) fail('Usage: kdna-studio test <project> --input "<text>" [--preset baseline|edge|contradiction]');
+  const { project } = readProject(projectInput);
+  const domainName = project.name || 'Untitled Project';
+  const domainPrompt = `Domain: ${domainName}\n${project.description || ''}`;
+
+  console.log(`Testing: ${domainName} [${preset}]`);
+  const prompt = preset === 'baseline' ? `Test the core judgment: ${input}`
+    : preset === 'edge' ? `Test a boundary case: ${input}`
+    : `Test for contradiction: ${input}`;
+  const result = await ai.testlab.compare(llm.config(), domainName, prompt, domainPrompt, {});
+  console.log(JSON.stringify(result, null, 2));
+}
+
 const args = process.argv.slice(2);
 const cmd = args[0];
 if (!cmd || cmd === '--help' || cmd === '-h') {
@@ -746,15 +1372,28 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   process.exit(EXIT.OK);
 }
 
+(async () => {
 try {
   if (cmd === 'create') cmdCreate(args.slice(1));
+  else if (cmd === 'migrate') cmdMigrate(args.slice(1));
   else if (cmd === 'import') cmdImport(args.slice(1));
+  else if (cmd === 'filter') cmdFilter(args.slice(1));
+  else if (cmd === 'target') cmdTarget(args.slice(1));
+  else if (cmd === 'source') cmdSourceClassify(args.slice(1));
+  else if (cmd === 'distill') await cmdDistill(args.slice(1));
+  else if (cmd === 'candidate') cmdCandidate(args.slice(1));
+  else if (cmd === 'interview') await cmdInterview(args.slice(1));
+  else if (cmd === 'feynman') await cmdFeynman(args.slice(1));
+  else if (cmd === 'test') await cmdTest(args.slice(1));
   else if (cmd === 'card') cmdCard(args.slice(1));
   else if (cmd === 'lock') cmdLock(args.slice(1));
   else if (cmd === 'compile') cmdCompile(args.slice(1));
   else if (cmd === 'export') cmdExport(args.slice(1));
+  else if (cmd === 'llm') cmdLlm(args.slice(1));
   else if (cmd === 'identity') cmdIdentity(args.slice(1));
   else if (cmd === 'report') cmdReport(args.slice(1));
+  else if (cmd === 'install') cmdStudioInstall(args.slice(1));
+  else if (cmd === 'update') cmdStudioUpdate(args.slice(1));
   else {
     usage();
     fail(`Unknown command: ${cmd}`);
@@ -762,3 +1401,4 @@ try {
 } catch (err) {
   fail(err.message || String(err));
 }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official KDNA Studio command-line authoring entry for creating, locking, compiling, and exporting trusted .kdna assets.",
   "type": "commonjs",
   "bin": {
@@ -37,6 +37,9 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-studio-core": "^1.4.0"
+    "@aikdna/kdna-studio-core": "^1.5.0"
+  },
+  "devDependencies": {
+    "@aikdna/kdna-core": "^0.7.1"
   }
 }

package/tests/cli.test.js

@@ -5,6 +5,9 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const test = require('node:test');
 
+let kdnaCore = null;
+try { kdnaCore = require('@aikdna/kdna-core'); } catch { /* optional — runtime digest cross-verification */ }
+
 const root = path.resolve(__dirname, '..');
 const cli = path.join(root, 'bin', 'kdna-studio.js');
 
@@ -446,3 +449,220 @@ test('export includes creator and lineage in kdna.json', (t) => {
   assert.ok(exportedManifest.lineage, 'must have lineage');
   assert.equal(exportedManifest.lineage.type, 'original');
 });
+
+// ── E2E: Blank workflow with runtime content_digest check ──────────
+
+test('E2E blank: create → approve → lock → export → runtime digest match', (t) => {
+  const tmp = tmpDir();
+  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  const projectDir = path.join(tmp, 'project');
+  let result = run(['create', projectDir, '--name', '@test/e2e-blank'], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  // Add axiom with full fields
+  result = run([
+    'card', 'add', projectDir, 'axiom',
+    '--field', 'one_sentence=E2E blank axiom.',
+    '--field', 'full_statement=A complete testable explanation for the end-to-end blank workflow test.',
+    '--field', 'why=Without this axiom the end-to-end test would not validate blank creation.',
+    '--field', 'applies_when=["e2e testing"]',
+    '--field', 'does_not_apply_when=["production"]',
+    '--field', 'failure_risk=e2e test may incorrectly pass',
+  ], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+  const cardId = result.stdout.match(/Added card: (\S+)/)?.[1];
+
+  // Add a misunderstanding
+  result = run([
+    'card', 'add', projectDir, 'misunderstanding',
+    '--field', 'wrong=E2E tests are unnecessary.',
+    '--field', 'correct=E2E tests catch integration issues not visible in unit tests.',
+    '--field', 'key_distinction=E2E tests validate the full pipeline, not individual functions.',
+  ], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  // Approve all cards
+  let cards = run(['card', 'list', projectDir], { tmp });
+  for (const line of cards.stdout.trim().split('\n')) {
+    const id = line.split(/\s+/)[0];
+    result = run(['card', 'approve', projectDir, id, '--by', 'tester', '--statement', 'Confirmed.'], { tmp });
+    assert.equal(result.status, 0, result.stderr);
+  }
+
+  // Lock and export
+  result = run(['lock', projectDir], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  const outFile = path.join(tmp, 'blank.kdna');
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  result = run(['export', projectDir, '--out', outFile], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  // ── Verify: source_mode, lineage, digest chain ────────────
+  const distDir = path.dirname(outFile);
+  const manifest = JSON.parse(fs.readFileSync(path.join(distDir, 'kdna.json'), 'utf8'));
+  const receipt = JSON.parse(fs.readFileSync(path.join(distDir, 'build-receipt.json'), 'utf8'));
+  const provenance = JSON.parse(fs.readFileSync(path.join(distDir, 'provenance-report.json'), 'utf8'));
+
+  assert.equal(manifest.authoring.source_mode, 'blank');
+  assert.equal(manifest.lineage.type, 'original');
+  assert.match(manifest.content_digest, /^sha256:[0-9a-f]{64}$/);
+  assert.equal(manifest.content_digest, receipt.content_digest, 'manifest vs receipt digest mismatch');
+  assert.equal(manifest.content_digest, provenance.content_digest, 'manifest vs provenance digest mismatch');
+  assert.equal(manifest.authoring.compiler, '@aikdna/kdna-studio-core');
+  assert.equal(manifest.authoring.human_confirmed, true);
+
+  // ── Runtime cross-verification: content digest consistency ──
+  // Compute content digest from the .kdna ZIP entries and verify it
+  // matches the manifest, receipt, and provenance report.
+  if (kdnaCore) {
+    const reader = kdnaCore.createKdnaAssetReader();
+    const asset = reader.openSync(outFile);
+    const runtimeResult = reader.verifySync(asset);
+    const runtimeDigest = runtimeResult.content_digest;
+
+    assert.ok(runtimeDigest, 'runtime content_digest must be present');
+    assert.match(runtimeDigest, /^sha256:[0-9a-f]{64}$/, 'runtime content_digest must be valid sha256');
+
+    // Read ZIP-internal manifest (avoid sidecar timing issues)
+    const zipManifest = JSON.parse(asset.readEntry('kdna.json').toString());
+    assert.equal(zipManifest.content_digest, receipt.content_digest,
+      `ZIP manifest digest != receipt digest`);
+    assert.equal(zipManifest.content_digest, provenance.content_digest,
+      `ZIP manifest digest != provenance digest`);
+
+    // Verify: runtime computed digest matches ZIP manifest
+    assert.equal(zipManifest.content_digest, runtimeDigest,
+      `ZIP manifest content_digest (${zipManifest.content_digest.slice(0, 20)}...) != runtime computed (${runtimeDigest.slice(0, 20)}...) — trust chain broken`);
+  } else {
+    console.log('  (kdna-core not available, skipping runtime assetReader cross-verification)');
+  }
+});
+
+// ── E2E: Fork workflow ────────────────────────────────────────────
+
+test('E2E fork: parent → fork → approve → export → lineage check', (t) => {
+  const tmp = tmpDir();
+  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  // Step 1: Create and export a parent domain
+  const parentDir = path.join(tmp, 'parent');
+  let result = run(['create', parentDir, '--name', '@test/parent-domain'], { tmp });
+  result = run([
+    'card', 'add', parentDir, 'axiom',
+    '--field', 'one_sentence=Parent axiom for forking test.',
+    '--field', 'full_statement=A complete testable explanation from the parent domain for fork lineage verification.',
+    '--field', 'why=Without this parent axiom the fork test would have no source to verify lineage against.',
+    '--field', 'applies_when=["fork testing"]',
+    '--field', 'does_not_apply_when=["not forking"]',
+    '--field', 'failure_risk=forked content may lose lineage',
+  ], { tmp });
+  const pCards = run(['card', 'list', parentDir], { tmp });
+  for (const line of pCards.stdout.trim().split('\n')) {
+    const id = line.split(/\s+/)[0];
+    run(['card', 'approve', parentDir, id, '--by', 'tester', '--statement', 'Parent OK.'], { tmp });
+  }
+  run(['lock', parentDir], { tmp });
+  const parentKdna = path.join(tmp, 'parent.kdna');
+  fs.mkdirSync(path.dirname(parentKdna), { recursive: true });
+  result = run(['export', parentDir, '--out', parentKdna], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  // Step 2: Fork from parent
+  const forkDir = path.join(tmp, 'forked');
+  result = run(['create', forkDir, '--from-kdna', parentKdna, '--name', '@test/forked-domain'], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  const fProject = JSON.parse(fs.readFileSync(path.join(forkDir, 'studio.project.json'), 'utf8'));
+  assert.equal(fProject.source_mode, 'kdna_asset');
+  assert.equal(fProject.lineage.type, 'fork');
+  assert.equal(fProject.lineage.parent_name, '@test/parent-domain');
+
+  // Step 3: Approve and export fork
+  const fCards = run(['card', 'list', forkDir], { tmp });
+  for (const line of fCards.stdout.trim().split('\n')) {
+    const id = line.split(/\s+/)[0];
+    run(['card', 'approve', forkDir, id, '--by', 'tester', '--statement', 'Fork confirmed.'], { tmp });
+  }
+  run(['lock', forkDir], { tmp });
+  const forkKdna = path.join(tmp, 'forked.kdna');
+  fs.mkdirSync(path.dirname(forkKdna), { recursive: true });
+  result = run(['export', forkDir, '--out', forkKdna], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  // Step 4: Verify lineage in exported fork
+  const fManifest = JSON.parse(fs.readFileSync(path.join(tmp, 'kdna.json'), 'utf8'));
+  assert.equal(fManifest.authoring.source_mode, 'kdna_asset');
+  assert.equal(fManifest.lineage.type, 'fork');
+  assert.equal(fManifest.lineage.parent_name, '@test/parent-domain');
+  assert.match(fManifest.content_digest, /^sha256:/);
+});
+
+// ── E2E: Migrate workflow ─────────────────────────────────────────
+
+test('E2E migrate: source folder → import → approve → export → verify', (t) => {
+  const tmp = tmpDir();
+  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  // Step 1: Create legacy source folder
+  const sourceDir = path.join(tmp, 'legacy');
+  fs.mkdirSync(sourceDir, { recursive: true });
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Core.json'), JSON.stringify({
+    meta: { domain: 'legacy_test', version: '0.3.0', created: '2026-01-01', purpose: 'Legacy migrate test', load_condition: 'always' },
+    axioms: [{
+      id: 'ax_mig', one_sentence: 'Migrated axiom for E2E test.',
+      full_statement: 'A complete testable explanation for the migrated legacy axiom in the end-to-end workflow.',
+      why: 'Without this migrated axiom the e2e test cannot verify legacy folder migration.',
+      applies_when: ['legacy migration testing'], does_not_apply_when: ['not migrating'],
+      failure_risk: 'migrated content may not be re-locked',
+    }],
+    ontology: [],
+    stances: [],
+  }));
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Patterns.json'), JSON.stringify({
+    meta: { domain: 'legacy_test', version: '0.3.0', created: '2026-01-01', purpose: 'legacy patterns', load_condition: 'always' },
+    misunderstandings: [{ id: 'ms_mig', wrong: 'Legacy wrong belief.', correct: 'Correct understanding.', key_distinction: 'The key difference between legacy wrong and correct behavior.' }],
+    self_check: ['Is the migrated content properly re-locked?'],
+  }));
+
+  // Step 2: Import via --from-folder
+  const projectDir = path.join(tmp, 'imported');
+  let result = run(['create', projectDir, '--from-folder', sourceDir, '--name', '@test/e2e-migrate'], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+  const audit = JSON.parse(result.stdout);
+  assert.ok(audit.imported > 0, `No cards imported: ${result.stdout}`);
+  assert.equal(audit.source_mode, 'source_folder');
+
+  // Verify project has source_folder mode
+  const project = JSON.parse(fs.readFileSync(path.join(projectDir, 'studio.project.json'), 'utf8'));
+  assert.equal(project.source_mode, 'source_folder');
+  assert.equal(project.lineage.type, 'migrated');
+
+  // Step 3: Approve and export
+  const cards = run(['card', 'list', projectDir], { tmp });
+  for (const line of cards.stdout.trim().split('\n')) {
+    const id = line.split(/\s+/)[0];
+    result = run(['card', 'approve', projectDir, id, '--by', 'tester', '--statement', 'Migrated content confirmed.'], { tmp });
+    assert.equal(result.status, 0, result.stderr);
+  }
+  result = run(['lock', projectDir], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  const outFile = path.join(tmp, 'migrated.kdna');
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  result = run(['export', projectDir, '--out', outFile], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  // Verify exported manifest
+  const distDir = path.dirname(outFile);
+  const manifest = JSON.parse(fs.readFileSync(path.join(distDir, 'kdna.json'), 'utf8'));
+  assert.equal(manifest.authoring.source_mode, 'source_folder');
+  assert.equal(manifest.lineage.type, 'migrated');
+  assert.match(manifest.content_digest, /^sha256:/);
+  assert.equal(manifest.authoring.human_confirmed, true);
+
+  // Digest chain
+  const receipt = JSON.parse(fs.readFileSync(path.join(distDir, 'build-receipt.json'), 'utf8'));
+  assert.equal(manifest.content_digest, receipt.content_digest);
+});