@aikdna/kdna-studio-cli 0.8.6 → 0.8.8

package/README.md

@@ -72,6 +72,47 @@ kdna load dist/my_domain.kdna --profile=compact --as=prompt
 runtime control plane for inspecting, validating, packing, unpacking, and
 loading existing `.kdna` assets.
 
+## 5-minute first asset
+
+If you just installed and want to ship a v1 asset without an LLM:
+
+```bash
+# 1. Init identity (required for the export signature)
+kdna-studio identity init --name "Your Name"
+
+# 2. Create a project
+kdna-studio create my_domain --name @yourscope/my_domain
+
+# 3. Add at least one judgment card
+kdna-studio card add . axiom \
+  --field one_sentence='specific evidence outranks broad claims' \
+  --field full_statement='Always cite the specific source that supports a judgment; broad claims without evidence are the most common cause of bad agent advice.' \
+  --field why='because vague advice fails in production' \
+  --field applies_when='["reviewing"]' \
+  --field does_not_apply_when='["formatting"]' \
+  --field failure_risk='praise without diagnosis' \
+  --field confidence='high' \
+  --field evidence_type='observation'
+
+# 4. Approve and lock
+kdna-studio card approve . --all --by me --statement "i confirm"
+
+# 5. Export the v1 asset
+kdna-studio export . --format v1 --out my_domain.kdna
+
+# 6. Verify with the runtime CLI
+kdna load my_domain.kdna --profile=compact
+```
+
+The first three AI commands (feynman, distill --ai, test, interview) work
+without `KDNA_LLM_PROVIDER` / `KDNA_LLM_API_KEY` by passing `--no-llm`. They
+return a structured but unsynthesised result. To enable real evaluation:
+
+```bash
+kdna-studio llm config --provider openai --model gpt-4 --key <your-key>
+# or set KDNA_LLM_PROVIDER, KDNA_LLM_API_KEY, KDNA_LLM_MODEL
+```
+
 ## Runtime Export Contract
 
 `kdna-studio export --format v1` is the canonical runtime export path. It uses

package/bin/kdna-studio.js

@@ -29,6 +29,35 @@ const {
 } = loadStudioCore();
 
 const llm = require('../src/llm');
+
+// Bug (#1 UX): the LLM-requiring commands (distill, interview, feynman,
+// test) silently fail with a stack trace when no LLM is configured.
+// First-time users hit this and have no way to know what to do. The
+// fix routes every LLM call through this helper, which:
+//   1. Checks whether an LLM is configured at all
+//   2. If not and --no-llm is given, returns a static / synthesised
+//      result so the command can still be useful (5-minute path)
+//   3. If not and --no-llm is absent, exits with a clear
+//      "configure LLM with: kdna-studio llm config" message
+function cmdNeedsLlm(args, cmdName) {
+  const cfg = llm.config();
+  const hasLlm = cfg && cfg.provider && cfg.apiKey && cfg.model;
+  if (hasLlm) return { hasLlm: true, cfg };
+  if (args.includes('--no-llm')) {
+    return {
+      hasLlm: false,
+      cfg,
+      noLlm: true,
+      message: `${cmdName} invoked with --no-llm. Output will be static / synthesised; configure an LLM with \`kdna-studio llm config\` to enable real evaluation.`,
+    };
+  }
+  fail(
+    `${cmdName} requires an LLM. Configure one with:\n` +
+    `  kdna-studio llm config --provider openai --key <api-key> --model <model>\n` +
+    `Or set env vars: KDNA_LLM_PROVIDER, KDNA_LLM_API_KEY, KDNA_LLM_MODEL.\n` +
+    `Or run with --no-llm to get a static / synthesised result.`,
+  );
+}
 const ai = require('../src/ai');
 
 const EXIT = { OK: 0, INPUT_ERROR: 2, HUMAN_LOCK_REQUIRED: 4, TRUST_FAILED: 5 };
@@ -36,9 +65,12 @@ 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):
+LLM (AI-powered authoring; every AI command accepts --no-llm for a static result):
   kdna-studio llm config [--provider <name>] [--model <name>] [--key-pipe] [--url <base-url>]
   kdna-studio llm show
+  (run 'kdna-studio llm config --provider openai --key <key> --model gpt-4' to enable
+   feynman, distill --ai, interview, and test. With --no-llm these commands
+   still produce a structured but unsynthesised result.)
 
 Identity:
   kdna-studio identity init [--name <display-name>]
@@ -311,11 +343,40 @@ function importedCard(type, fields = {}, id = null) {
   }
 }
 
+// Bug (#3 + #4 UX): payload.kdnab intentionally carries the same
+// misunderstanding card in two places — `patterns[]` (the v1 schema's
+// primary card list) and `reasoning.failure_modes[]` (the v1 schema's
+// "what bad judgment looks like" view). Both share the same `id`.
+// Prior version imported both, doubling every misunderstanding on
+// re-import. The dedup is by id: when a card with the same id is
+// pushed twice, the second push merges fields (the failure_modes
+// entry carries a different field shape than patterns; merging
+// keeps the richer failure_risk / applies_when / does_not_apply_when
+// from the patterns entry).
+const _importedIds = new Set();
 function pushImportedCard(cards, type, fields = {}, id = null) {
+  if (id && _importedIds.has(id)) {
+    // Already imported — merge richer fields into the existing card.
+    const existing = cards.find(c => c.id === id);
+    if (existing) {
+      existing.fields = existing.fields || {};
+      for (const [k, v] of Object.entries(fields || {})) {
+        if (v !== undefined && v !== null && v !== '' &&
+            (existing.fields[k] === undefined || existing.fields[k] === '' ||
+             (Array.isArray(existing.fields[k]) && existing.fields[k].length === 0))) {
+          existing.fields[k] = v;
+        }
+      }
+    }
+    return;
+  }
+  if (id) _importedIds.add(id);
   const card = importedCard(type, fields, id);
   if (card) cards.push(card);
 }
 
+function resetImportedIds() { _importedIds.clear(); }
+
 function decodePayload(bytes, manifest = {}) {
   const raw = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
   const encoding = manifest.payload?.encoding || manifest.container?.payload_encoding || null;
@@ -334,6 +395,7 @@ function decodePayload(bytes, manifest = {}) {
 // intentional. Documented here so a future reader does not "fix" it
 // by collapsing one path into the other.
 function cardsFromV1Payload(payload) {
+  resetImportedIds();
   const cards = [];
   for (const sourceCard of (Array.isArray(payload.source_cards) ? payload.source_cards : [])) {
     pushImportedCard(cards, sourceCard.type, sourceCard.fields || {}, sourceCard.id || null);
@@ -428,14 +490,29 @@ function cardsFromV1Payload(payload) {
     pushImportedCard(cards, 'self_check', fields, fields.id || null);
   }
   for (const failureMode of (Array.isArray(payload.reasoning?.failure_modes) ? payload.reasoning?.failure_modes : [])) {
+    // Bug (#145 follow-up): the prior version dropped three
+    // judgment fields (failure_risk, applies_when, does_not_apply_when)
+    // when reading failure_modes back out of a v1 asset. A Studio
+    // project that round-tripped through `migrate --format v1` lost
+    // these fields every time. The fix reads them through, matching
+    // the export-side map in kdna-studio-core's buildPayload.
     pushImportedCard(cards, 'misunderstanding', {
       wrong: failureMode.mode || failureMode.wrong || '',
       correct: failureMode.correct || '',
       key_distinction: failureMode.key_distinction || '',
       why: failureMode.why || '',
+      failure_risk: failureMode.failure_risk || '',
+      applies_when: Array.isArray(failureMode.applies_when) ? failureMode.applies_when : [],
+      does_not_apply_when: Array.isArray(failureMode.does_not_apply_when) ? failureMode.does_not_apply_when : [],
     }, failureMode.id || null);
   }
   for (const chain of (Array.isArray(payload.reasoning?.reasoning_chains) ? payload.reasoning?.reasoning_chains : [])) {
+    // Bug (#4 UX): compile/index.js synthesises one reasoning chain
+    // per locked axiom (the legacy 1.0.0 path) and tags it
+    // `source_authored: false`. Importing those synthesised chains
+    // doubled the card count on round-trip. The fix skips chains
+    // that the producer explicitly marked as synthesised.
+    if (chain.source_authored === false) continue;
     pushImportedCard(cards, 'reasoning', chain, chain.id || null);
   }
   for (const stage of (Array.isArray(payload.evolution?.stages) ? payload.evolution?.stages : [])) {
@@ -452,6 +529,7 @@ function cardsFromV1Payload(payload) {
 }
 
 function cardsFromLegacyPayload(payload) {
+  resetImportedIds();
   const cards = [];
   const judgment = payload.judgment || {};
   const core = judgment.core || {};
@@ -701,6 +779,7 @@ function cmdCreate(args) {
  * Cards are imported as draft — they do NOT inherit trust from the source.
  */
 function importFromKdna(kdnaPath) {
+  resetImportedIds();
   const absKdna = path.resolve(kdnaPath);
   if (!fs.existsSync(absKdna)) fail(`KDNA asset not found: ${absKdna}`);
   if (!absKdna.endsWith('.kdna')) fail('--from-kdna requires a .kdna file');
@@ -863,6 +942,7 @@ function importFromKdna(kdnaPath) {
  * Outputs a schema audit report.
  */
 function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
+  resetImportedIds();
   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');
@@ -1000,6 +1080,15 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
       const q = typeof sc === 'string' ? sc : sc.question || '';
       importedCards.push(cardApi.createCard('self_check', { question: q }));
     }
+    // Bug (aesthetic round-trip): prior version dropped
+    // `patterns.aesthetics` on import. `cardsFromV1Payload` and
+    // `cardsFromLegacyPayload` both read the field, so a domain
+    // that authored aesthetic cards in either format would lose
+    // them when imported through `create --from-folder`. The fix
+    // adds the missing loop here.
+    for (const aesthetic of (Array.isArray(patterns.aesthetics) ? patterns.aesthetics : [])) {
+      importedCards.push(cardApi.createCard('aesthetic', aesthetic.fields || aesthetic));
+    }
   }
 
   // NEW: import scenarios
@@ -1335,8 +1424,25 @@ function cmdCard(args) {
   const sub = args[0];
   if (sub === 'list') {
     const { project } = readProject(args[1]);
-    for (const card of project.cards || []) {
-      console.log(`${card.id}\t${card.type}\t${card.status}\t${card.locked ? 'locked' : 'unlocked'}`);
+    // Bug (#2 UX): the --json flag was accepted but ignored — the
+    // command printed the same TSV either way. A script consumer
+    // that wanted to pipe the result into `jq` or a downstream
+    // tool got garbage. The fix respects --json and emits a real
+    // JSON document.
+    const useJson = args.includes('--json');
+    const rows = (project.cards || []).map(card => ({
+      id: card.id,
+      type: card.type,
+      status: card.status,
+      locked: !!card.locked,
+      fields: card.fields || {},
+    }));
+    if (useJson) {
+      console.log(JSON.stringify({ count: rows.length, cards: rows }, null, 2));
+    } else {
+      for (const r of rows) {
+        console.log(`${r.id}\t${r.type}\t${r.status}\t${r.locked ? 'locked' : 'unlocked'}`);
+      }
     }
     return;
   }
@@ -2236,9 +2342,15 @@ 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 = resolveApiKey(args);
+  // Bug (#1 UX): prior version called resolveApiKey(args)
+  // unconditionally, which is fine when --candidates is set (the
+  // call is a no-op) but it also surfaced the env-var resolution
+  // on every run, so a caller that never asked for the LLM was
+  // still at the mercy of `resolveApiKey` warnings. Defer the
+  // LLM-key resolution to the --ai branch.
+  const provider = useAI ? option(args, '--provider') : null;
+  const model = useAI ? option(args, '--model') : null;
+  const apiKey = useAI ? resolveApiKey(args) : null;
   if (!projectInput) fail('Usage: kdna-studio distill <project> [--ai] [--candidates <file.json>]');
   if (!candidatesFile && !useAI) fail('Either --ai or --candidates <file.json> required.');
 
@@ -2401,31 +2513,62 @@ async function cmdFeynman(args) {
   // `feynman_text`. The old check was dead code (nothing writes the wrong
   // field) and made this command fail on every card.
   //
-  // Bug (#62 + #68): the prior error message pointed at "the feynman
-  // authoring command", which does not exist in this CLI. The right
-  // path is either:
-  //   - kdna-studio feynman <project> <card-id>  (evaluate an existing
-  //     restatement; what the caller is already running)
-  //   - kdna-studio card update <project> <card-id> --field feynman_restatement='<json>'
-  //     (set the restatement manually)
-  // The fix makes the second path explicit and gives a working
-  // example. Bug #62 (the field is never populated) is fixed in
-  // feynman.js: a no-restatement card now auto-generates one
-  // before the LLM call, so the bare `kdna-studio feynman` command
-  // works end-to-end.
+  // Bug (#62 + #68 follow-up): the prior `if (!card.feynman_restatement)
+  // fail(...)` block rejected every card that had no human-written
+  // restatement, even when the AI evaluator in feynman.js was
+  // prepared to auto-synthesise one. A caller without a configured
+  // LLM (no `KDNA_API_KEY`, no `kdna-studio llm config`) would
+  // get a `fail` instead of a structured note. The fix removes the
+  // guard: a missing restatement is now handed off to the evaluator
+  // (which either asks the LLM to evaluate a synthesised one or,
+  // without an LLM, returns a structured `synthesised_restatement`
+  // for the caller to use as a starting point). The error message
+  // is kept as a secondary path: only if the evaluator itself fails
+  // does the command exit non-zero, and only then with a clear
+  // pointer to the manual `card update` path.
+  //
+  // We do still need a restatement-shaped object to feed the
+  // evaluator, so we synthesise one in-memory when the card has
+  // none. This does NOT persist the synthesised restatement to the
+  // project (so the user still has to opt in via `card update` to
+  // keep one across runs), but it lets the no-LLM path return a
+  // useful result instead of a hard fail.
   if (!card.feynman_restatement) {
-    fail(
-      `Card ${cardId} has no Feynman restatement. Set it manually:\n` +
-      `  kdna-studio card update <project> ${cardId} --field feynman_restatement='{"text":"<your plain-language restatement>"}'`,
-    );
+    const synthesised = ai.feynman.synthFeynmanRestatement(card.fields || {});
+    card.feynman_restatement = { text: synthesised, synthesised: true };
+    console.warn(`No feynman_restatement on ${cardId}; using synthesised:\n  "${synthesised}"`);
   }
 
   console.log(`Evaluating Feynman restatement for card: ${cardId}`);
-  const result = await ai.feynman.evaluate(llm.config(), card, {});
+
+  // Bug (#1 UX follow-up): if no LLM is configured and the caller
+  // did not pass --no-llm, route through cmdNeedsLlm which either
+  // gives a clear "configure LLM" error or accepts the --no-llm
+  // path. Without this branch, the no-LLM caller would fall
+  // through to the LLM call below and get a stack trace.
+  const llmGate = cmdNeedsLlm(args, 'feynmann');
+
+  let result;
+  if (llmGate.noLlm) {
+    // Static evaluation: every criterion is "unsure" (✗), score 0,
+    // but the command still produces a useful structured result and
+    // saves the synthesised restatement to the card.
+    result = {
+      score: 0,
+      criteria: Object.fromEntries(Object.keys(ai.feynman.CRITERIA).map(k => [k, false])),
+      explanations: { noLlm: llmGate.message },
+      suggestions: [
+        'No LLM configured — every criterion shows ✗. Run `kdna-studio llm config` and re-evaluate for a real score.',
+        'Or set the synthesised restatement via: kdna-studio card update <project> ' + cardId + ' --field feynman_restatement=\'{"text":"<your own restatement>"}\'',
+      ],
+    };
+  } else {
+    result = await ai.feynman.evaluate(llmGate.cfg, card, {});
+  }
   const score = result.score || 0;
   const passed = score >= 4;
 
-  console.log(`Score: ${score}/5 ${passed ? '✓ publishable' : '✗ below threshold (need 4/5)'}`);
+  console.log(`Score: ${score}/5 ${passed ? '✓ publishable' : '✗ below threshold (need 4/5)'}${llmGate.noLlm ? '  (--no-llm: static result)' : ''}`);
   for (const [criterion, desc] of Object.entries(ai.feynman.CRITERIA)) {
     const r = (result.criteria || {})[criterion] ? '✓' : '✗';
     console.log(`  ${r} ${criterion}`);
@@ -2471,18 +2614,35 @@ async function cmdTest(args) {
   const canonical = PRESET_ALIASES[preset] || 'baseline';
   console.log(`Testing: ${domainName} [${preset}]`);
 
+  // Bug (#1 UX): gate LLM-requiring paths through cmdNeedsLlm.
+  // The test command always needs an LLM (it compares without/with
+  // the loaded domain). --no-llm gives a static "no-op" comparison
+  // that lists the cards that *would* be applied.
+  const llmGate = cmdNeedsLlm(args, 'test');
+  const cfg = llmGate.noLlm ? null : llmGate.cfg;
+
   if (canonical === 'baseline') {
     // Baseline is a single comparison: keep the prior single-result
     // shape so existing parsers / consumers see the same output.
     const prompt = `Test the core judgment: ${input}`;
-    const result = await ai.testlab.compare(llm.config(), domainName, prompt, domainPrompt, {});
+    if (cfg === null) {
+      // No-LLM static result
+      const cards = (project.cards || []).filter(c => c.locked).map(c => ({ type: c.type, id: c.id, one_sentence: c.fields?.one_sentence || c.fields?.question || '' }));
+      console.log(JSON.stringify({ no_llm: true, message: llmGate.message, would_apply: cards }, null, 2));
+      return;
+    }
+    const result = await ai.testlab.compare(cfg, domainName, prompt, domainPrompt, {});
     console.log(JSON.stringify(result, null, 2));
     return;
   }
   // For non-baseline presets, run the preset + the baseline so the user
   // can see both side by side. The preset prompt is the one in
   // ai/testlab.js — that's the code path that was dead before.
-  const result = await ai.testlab.testPreset(llm.config(), domainName, input, domainPrompt, {});
+  if (cfg === null) {
+    console.log(JSON.stringify({ no_llm: true, message: llmGate.message }, null, 2));
+    return;
+  }
+  const result = await ai.testlab.testPreset(cfg, domainName, input, domainPrompt, {});
   console.log(JSON.stringify(result[canonical] || result, null, 2));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-cli",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "Official KDNA Studio command-line authoring entry for creating, reviewing, compiling, and exporting .kdna judgment assets through the KDNA toolchain.",
   "type": "commonjs",
   "bin": {
@@ -39,12 +39,12 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-studio-core": "^1.7.5",
+    "@aikdna/kdna-studio-core": "^1.7.6",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "cbor-x": "^1.6.4"
   },
   "devDependencies": {
-    "@aikdna/kdna-core": "^0.15.0"
+    "@aikdna/kdna-core": "^0.15.5"
   }
 }