@aikdna/kdna-cli 0.17.0 → 0.19.0

package/src/cmds/explain.js

@@ -0,0 +1,119 @@
+const { error, EXIT } = require('./_common');
+const { parseName } = require('../registry');
+const { getInstalled, readContainer } = require('../package-store');
+
+function cmdExplain(args) {
+  const target = args.filter((a) => !a.startsWith('--'))[1];
+  if (!target) {
+    error(
+      'Usage: kdna explain <domain> [--locale zh-CN]\n\n' +
+        '  Produces a natural language explanation of what a domain covers,\n' +
+        '  its key axioms, applicable scenarios, and intended model types.',
+      EXIT.INPUT_ERROR,
+    );
+  }
+
+  const parsed = parseName(target);
+  if (!parsed) {
+    error(`Invalid domain name: ${target}`, EXIT.INPUT_ERROR);
+  }
+
+  const installed = getInstalled(parsed.full);
+  if (!installed) {
+    error(`${parsed.full} is not installed.\nRun: kdna install ${target}`, EXIT.INPUT_ERROR);
+  }
+
+  const { core, patterns, scenarios } = readContainer(installed.asset_path);
+
+  if (!core) {
+    error(`Failed to load KDNA_Core.json from ${installed.asset_path}`, EXIT.VALIDATION_FAILED);
+  }
+
+  const m = core.meta || {};
+  const purpose = m.purpose || '(not specified)';
+  const domain = m.domain || parsed.ident;
+  const version = m.version || 'unknown';
+  const axioms = core.axioms || [];
+  const bannedTerms = patterns?.terminology?.banned_terms || [];
+  const selfChecks = patterns?.self_checks || patterns?.self_check || [];
+  const standardTerms = patterns?.terminology?.standard_terms || [];
+  const misunderstandings = patterns?.misunderstandings || [];
+
+  console.log('');
+  console.log(`╔══════════════════════════════════════════════════════════════╗`);
+  console.log(`║  KDNA Domain: ${domain.padEnd(46)}║`);
+  console.log(`║  Package:     ${parsed.full.padEnd(46)}║`);
+  console.log(`║  Version:     ${version.padEnd(46)}║`);
+  console.log(`╚══════════════════════════════════════════════════════════════╝`);
+  console.log('');
+
+  console.log('── Purpose ──');
+  console.log(`  ${purpose}`);
+  console.log('');
+
+  console.log(`── Axioms (${axioms.length} core principles) ──`);
+  for (const ax of axioms) {
+    console.log(`  • ${ax.one_sentence || ax.id}`);
+    const applies = (ax.applies_when || []).join('; ');
+    if (applies) console.log(`    Applies when: ${applies.slice(0, 120)}`);
+    const notApply = (ax.does_not_apply_when || []).join('; ');
+    if (notApply) console.log(`    NOT when:    ${notApply.slice(0, 120)}`);
+    console.log('');
+  }
+
+  if (standardTerms.length) {
+    console.log(`── Standard Terms (${standardTerms.length}) ──`);
+    for (const t of standardTerms.slice(0, 8)) {
+      const def = t.definition ? `: ${t.definition.slice(0, 80)}` : '';
+      console.log(`  • ${t.term}${def}`);
+    }
+    console.log('');
+  }
+
+  if (misunderstandings.length) {
+    console.log(`── Common Misunderstandings (${misunderstandings.length}) ──`);
+    for (const mm of misunderstandings.slice(0, 5)) {
+      console.log(`  ✗ "${mm.mistake || mm.id}"`);
+    }
+    console.log('');
+  }
+
+  if (bannedTerms.length) {
+    console.log(`── Banned Terms (${bannedTerms.length} — do not use) ──`);
+    for (const b of bannedTerms.slice(0, 6)) {
+      const why = b.why ? ` → ${b.why.slice(0, 60)}` : '';
+      console.log(`  ✗ "${b.term}"${why}`);
+    }
+    console.log('');
+  }
+
+  if (selfChecks.length) {
+    console.log(`── Self-Checks (${selfChecks.length} — verify before responding) ──`);
+    for (const sc of selfChecks.slice(0, 8)) {
+      console.log(`  ✓ ${sc.question || sc.id || sc}`);
+    }
+    console.log('');
+  }
+
+  if (scenarios && scenarios.scenarios && scenarios.scenarios.length) {
+    console.log(`── Scenarios (${scenarios.scenarios.length} — strategy shifts) ──`);
+    for (const s of scenarios.scenarios.slice(0, 6)) {
+      const desc = s.description ? s.description.slice(0, 80) : '';
+      console.log(`  ▶ ${s.signal || s.id}: ${desc}`);
+    }
+    console.log('');
+  }
+
+  console.log('── Model Compatibility ──');
+  console.log('  Works with any LLM/agent that loads context before reasoning.');
+  console.log('  Tested: Claude, GPT, Gemini, Qwen, MiniMax');
+  console.log('');
+
+  console.log('── Quick Start ──');
+  console.log(`  kdna verify ${target} --judgment`);
+  console.log(`  kdna compare ${target} --input "<your task>"`);
+  console.log(`  kdna trace --domain ${target.slice(0, 40)}`);
+  console.log('');
+}
+
+module.exports = { cmdExplain };

package/src/cmds/governance.js

@@ -36,7 +36,8 @@ function cmdProposalCreate(args = []) {
   if (!fs.existsSync(absTest)) error(`Test run file not found: ${absTest}`, EXIT.INPUT_ERROR);
 
   const runData = readJson(absTest);
-  if (!runData || !runData.test_id) error(`Not a valid test run file: ${absTest}`, EXIT.INPUT_ERROR);
+  if (!runData || !runData.test_id)
+    error(`Not a valid test run file: ${absTest}`, EXIT.INPUT_ERROR);
 
   const absDomain = path.resolve(domainPath);
 
@@ -63,7 +64,10 @@ function cmdProposalCreate(args = []) {
   };
 
   // Auto-detect suggested changes from test result gaps
-  if (runData.expected?.classification && runData.expected.classification !== runData.results?.classification) {
+  if (
+    runData.expected?.classification &&
+    runData.expected.classification !== runData.results?.classification
+  ) {
     proposal.suggested_changes.push({
       what: 'axiom',
       field: 'applies_when',
@@ -80,7 +84,17 @@ function cmdProposalCreate(args = []) {
   writeJson(outFile, proposal);
 
   if (jsonMode) {
-    console.log(JSON.stringify({ proposal_id: proposal.proposal_id, saved: outFile, suggested_changes: proposal.suggested_changes.length }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          proposal_id: proposal.proposal_id,
+          saved: outFile,
+          suggested_changes: proposal.suggested_changes.length,
+        },
+        null,
+        2,
+      ),
+    );
     return;
   }
 
@@ -98,7 +112,8 @@ function cmdProposalCreate(args = []) {
 
 function cmdProposalValidate(args = []) {
   const jsonMode = args.includes('--json');
-  const target = args.filter((a) => !a.startsWith('--'))[2] || args.filter((a) => !a.startsWith('--'))[1];
+  const target =
+    args.filter((a) => !a.startsWith('--'))[2] || args.filter((a) => !a.startsWith('--'))[1];
   if (!target) error('Usage: kdna proposal validate <proposal.json>', EXIT.INPUT_ERROR);
 
   const abs = path.resolve(target);
@@ -113,7 +128,8 @@ function cmdProposalValidate(args = []) {
   if (!proposal.source) issues.push('missing source');
   if (!proposal.domain) issues.push('missing domain');
   if (!proposal.trigger?.test_id) issues.push('missing trigger.test_id');
-  if (!proposal.reasoning || proposal.reasoning.length < 10) issues.push('reasoning too short (min 10 chars)');
+  if (!proposal.reasoning || proposal.reasoning.length < 10)
+    issues.push('reasoning too short (min 10 chars)');
   if (!proposal.suggested_changes || proposal.suggested_changes.length === 0) {
     issues.push('no suggested changes');
   } else {
@@ -124,11 +140,17 @@ function cmdProposalValidate(args = []) {
   }
 
   if (jsonMode) {
-    console.log(JSON.stringify({
-      proposal_id: proposal.proposal_id,
-      valid: issues.length === 0,
-      issues,
-    }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          proposal_id: proposal.proposal_id,
+          valid: issues.length === 0,
+          issues,
+        },
+        null,
+        2,
+      ),
+    );
     process.exit(issues.length ? EXIT.VALIDATION_FAILED : EXIT.OK);
   }
 
@@ -184,12 +206,18 @@ function cmdReview(args = []) {
   writeJson(abs, proposal);
 
   if (jsonMode) {
-    console.log(JSON.stringify({
-      proposal_id: proposal.proposal_id,
-      decision: sub,
-      by,
-      reason,
-    }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          proposal_id: proposal.proposal_id,
+          decision: sub,
+          by,
+          reason,
+        },
+        null,
+        2,
+      ),
+    );
     process.exit(sub === 'reject' ? EXIT.POLICY_VIOLATION : EXIT.OK);
   }
 
@@ -217,7 +245,10 @@ function cmdLockCard(args = []) {
   // Lock card in the current studio project (finds studio.project.json)
   const projectPath = path.resolve('studio.project.json');
   if (!fs.existsSync(projectPath)) {
-    error('No studio.project.json found in current directory. Run: kdna studio scaffold', EXIT.INPUT_ERROR);
+    error(
+      'No studio.project.json found in current directory. Run: kdna studio scaffold',
+      EXIT.INPUT_ERROR,
+    );
   }
 
   const project = readJson(projectPath);
@@ -240,11 +271,17 @@ function cmdLockCard(args = []) {
     found = true;
 
     if (jsonMode) {
-      console.log(JSON.stringify({
-        card: `${type}.${id}`,
-        locked: true,
-        lock: card.human_lock,
-      }, null, 2));
+      console.log(
+        JSON.stringify(
+          {
+            card: `${type}.${id}`,
+            locked: true,
+            lock: card.human_lock,
+          },
+          null,
+          2,
+        ),
+      );
     } else {
       console.log(`✓ Locked: ${type}.${id}`);
       console.log(`  By:     ${by}`);
@@ -254,7 +291,10 @@ function cmdLockCard(args = []) {
   }
 
   if (!found) {
-    error(`Card not found: ${cardId}. Check the card ID and that a studio project exists.`, EXIT.INPUT_ERROR);
+    error(
+      `Card not found: ${cardId}. Check the card ID and that a studio project exists.`,
+      EXIT.INPUT_ERROR,
+    );
   }
 }
 
@@ -320,17 +360,23 @@ function cmdEvolutionReport(domainPath, jsonMode) {
   const pending = evolution.pending || [];
 
   if (jsonMode) {
-    console.log(JSON.stringify({
-      domain: path.basename(abs),
-      total_stages: stages.length,
-      pending_changes: pending.length,
-      stages: stages.map((s) => ({
-        stage: s.stage,
-        version: s.version,
-        date: s.date,
-        changes: s.changes?.length || 0,
-      })),
-    }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          domain: path.basename(abs),
+          total_stages: stages.length,
+          pending_changes: pending.length,
+          stages: stages.map((s) => ({
+            stage: s.stage,
+            version: s.version,
+            date: s.date,
+            changes: s.changes?.length || 0,
+          })),
+        },
+        null,
+        2,
+      ),
+    );
     return;
   }
 
@@ -362,7 +408,10 @@ function cmdRegression(args = []) {
   const evalsDir = evalsIdx >= 0 ? args[evalsIdx + 1] : null;
 
   if (!oldPath || !newPath) {
-    error('Usage: kdna regression <old-domain> <new-domain> --evals <dir> [--json]', EXIT.INPUT_ERROR);
+    error(
+      'Usage: kdna regression <old-domain> <new-domain> --evals <dir> [--json]',
+      EXIT.INPUT_ERROR,
+    );
   }
 
   const absOld = path.resolve(oldPath);
@@ -421,8 +470,18 @@ function cmdRegression(args = []) {
 
   const result = {
     domain: path.basename(absOld),
-    old: { axioms: oldAxiomCount, misunderstandings: oldMisCount, self_checks: oldSelfCheckCount, governance_coverage: oldGov },
-    new: { axioms: newAxiomCount, misunderstandings: newMisCount, self_checks: newSelfCheckCount, governance_coverage: newGov },
+    old: {
+      axioms: oldAxiomCount,
+      misunderstandings: oldMisCount,
+      self_checks: oldSelfCheckCount,
+      governance_coverage: oldGov,
+    },
+    new: {
+      axioms: newAxiomCount,
+      misunderstandings: newMisCount,
+      self_checks: newSelfCheckCount,
+      governance_coverage: newGov,
+    },
     delta: {
       axioms: newAxiomCount - oldAxiomCount,
       misunderstandings: newMisCount - oldMisCount,
@@ -442,12 +501,22 @@ function cmdRegression(args = []) {
 
   console.log(`Regression check: ${path.basename(absOld)} → ${path.basename(absNew)}`);
   console.log('');
-  console.log(`  Axioms:                  ${oldAxiomCount} → ${newAxiomCount}  (${result.delta.axioms >= 0 ? '+' : ''}${result.delta.axioms})`);
-  console.log(`  Misunderstandings:       ${oldMisCount} → ${newMisCount}  (${result.delta.misunderstandings >= 0 ? '+' : ''}${result.delta.misunderstandings})`);
-  console.log(`  Self-checks:             ${oldSelfCheckCount} → ${newSelfCheckCount}  (${result.delta.self_checks >= 0 ? '+' : ''}${result.delta.self_checks})`);
-  console.log(`  Governance coverage:     ${oldGov}% → ${newGov}%  (${result.delta.governance_coverage >= 0 ? '+' : ''}${result.delta.governance_coverage}%)`);
+  console.log(
+    `  Axioms:                  ${oldAxiomCount} → ${newAxiomCount}  (${result.delta.axioms >= 0 ? '+' : ''}${result.delta.axioms})`,
+  );
+  console.log(
+    `  Misunderstandings:       ${oldMisCount} → ${newMisCount}  (${result.delta.misunderstandings >= 0 ? '+' : ''}${result.delta.misunderstandings})`,
+  );
+  console.log(
+    `  Self-checks:             ${oldSelfCheckCount} → ${newSelfCheckCount}  (${result.delta.self_checks >= 0 ? '+' : ''}${result.delta.self_checks})`,
+  );
+  console.log(
+    `  Governance coverage:     ${oldGov}% → ${newGov}%  (${result.delta.governance_coverage >= 0 ? '+' : ''}${result.delta.governance_coverage}%)`,
+  );
   if (totalEvals) {
-    console.log(`  Evals:                   ${passedEvals} passed, ${failedEvals} failed out of ${totalEvals}`);
+    console.log(
+      `  Evals:                   ${passedEvals} passed, ${failedEvals} failed out of ${totalEvals}`,
+    );
   }
   console.log('');
   const mark = result.safe ? '✓' : '✗';

package/src/cmds/legacy.js

@@ -2,10 +2,9 @@ const { error } = require('./_common');
 
 function cmdPreview() {
   // Removed in v0.9 — no real user scenario for browser preview.
-  // To inspect a .kdna file, use: kdna inspect <path>
+  // To inspect a .kdna file, use: kdna inspect <file.kdna>
   error(
-    'kdna preview was removed in v0.9.\n' +
-      'Use: kdna inspect <path>  to view a .kdna file or domain directory.',
+    'kdna preview was removed in v0.9.\n' + 'Use: kdna inspect <file.kdna> to view a .kdna asset.',
   );
 }
 
@@ -18,8 +17,8 @@ function cmdProject() {
     'kdna project was removed in v0.9. The .kdna/config.json file is no\n' +
       'longer read by the kdna-loader skill — it would have forced KDNA\n' +
       'loading on tasks where the user did not ask for it.\n\n' +
-      'The agent now discovers KDNA on demand by reading ~/.kdna/domains/\n' +
-      'and matching the task against v2.1 applies_when fields.\n\n' +
+      'The agent now discovers KDNA on demand through kdna available/load,\n' +
+      'which read installed .kdna assets from the package index.\n\n' +
       'If you have stale .kdna/config.json files in your projects, you\n' +
       'can delete them — nothing reads them anymore.',
   );
@@ -32,7 +31,7 @@ function cmdEval() {
   error(
     'kdna eval was removed in v0.9.\n' +
       'To compare with/without KDNA reasoning, use:\n' +
-      '  kdna compare <name> --input "<task>"\n' +
+      '  kdna compare <name|file.kdna> --input "<task>"\n' +
       'To inspect a domain, use:\n' +
       '  kdna info <name>',
   );
@@ -53,17 +52,17 @@ function cmdSelect() {
 }
 
 function cmdExport() {
-  // Removed in v0.9 — was an alias for `kdna pack`.
+  // Removed in v0.9 — was an alias for the old top-level pack command.
   error(
     'kdna export was removed in v0.9 (it was an alias for pack).\n' +
-      'Use: kdna pack <path> [--output <dir>]',
+      'Use: kdna dev pack <source-dir> [--output <dir>]',
   );
 }
 
 function cmdDemo() {
   // Removed in v0.9 — internal demo, not a user feature. To see
   // before/after on a real input, use:
-  //   kdna compare <name> --input "<task>"   (requires LLM API key)
+  //   kdna compare <name|file.kdna> --input "<task>"   (requires LLM API key)
   error(
     'kdna demo was removed in v0.9.\n' +
       'To see KDNA before/after on a real input, use:\n' +