@aikdna/kdna-studio-cli 0.8.7 → 0.8.9

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>]
@@ -51,6 +83,8 @@ Create (three entry paths):
 
 Migrate (dev source or Studio project → canonical .kdna in one command):
   kdna-studio migrate <source-dir|project> --format v1 --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--allow-incomplete] [--sign] [--passphrase <pw>|--passphrase-stdin]
+  kdna-studio migrate <source-dir> --check --name <@scope/name>   # pre-flight: report which fields would block the export without writing the .kdna
+  kdna-studio audit-locks <project> [--type axiom|risk|stance|...] [--json]   # list cards with missing Human Lock fields (per-card-type, per-field)
 
 Authoring:
   kdna-studio import <project> <source-file-or-dir>               # import evidence (txt/md/json/yaml/csv/log/srt/vtt/html)
@@ -82,6 +116,7 @@ Distillation:
   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 audit-locks <project>            # list all axioms/risk/stance missing Human Lock fields
 
 Project may be a directory containing studio.project.json or a project JSON file.`);
 }
@@ -311,11 +346,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 +398,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);
@@ -445,6 +510,12 @@ function cardsFromV1Payload(payload) {
     }, 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 : [])) {
@@ -461,6 +532,7 @@ function cardsFromV1Payload(payload) {
 }
 
 function cardsFromLegacyPayload(payload) {
+  resetImportedIds();
   const cards = [];
   const judgment = payload.judgment || {};
   const core = judgment.core || {};
@@ -710,6 +782,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');
@@ -872,6 +945,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');
@@ -1353,8 +1427,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;
   }
@@ -1405,15 +1496,44 @@ function cmdCard(args) {
   if (sub === 'update') {
     const projectInput = args[1];
     const cardId = args[2];
-    if (!projectInput || !cardId) fail('Usage: kdna-studio card update <project> <card-id> --field key=value');
+    if (!projectInput || !cardId) fail('Usage: kdna-studio card update <project> <card-id> --field key=value  OR  kdna-studio card update <project> <card-id> --from-file <path.json>');
     const { projectPath, project } = readProject(projectInput);
     const idx = (project.cards || []).findIndex((c) => c.id === cardId);
     if (idx < 0) fail(`Card not found: ${cardId}`);
     const card = project.cards[idx];
     if (card.locked) fail(`Cannot update locked card: ${cardId}. Unlock first with card unlock.`);
-    const updates = parseFields(args.slice(3));
-    for (const [k, v] of Object.entries(updates)) {
-      if (card.fields) card.fields[k] = v;
+    // Bug (UX pro-20 migration): prior version only accepted
+    // --field key=value, so an author migrating 20 source-tree
+    // assets had to run one CLI invocation per field. With
+    // confidence + evidence_type as 8th / 9th required fields on
+    // axiom, a 99-axiom asset became 99 * 2 = 198 invocations.
+    // The fix accepts --from-file <path.json> so an author can
+    // write a single JSON file per card (or per project) and
+    // apply it in one call. JSON shape: {field: value, ...}.
+    //   kdna-studio card update . ax_xxx --from-file ./fills/ax_xxx.json
+    // For batched updates across many cards, see the
+    // --from-file-projects variant below, which reads a list
+    // of {id, fields} records.
+    const fromFileIdx = args.indexOf('--from-file');
+    if (fromFileIdx >= 0) {
+      const filePath = args[fromFileIdx + 1];
+      if (!filePath) fail('--from-file requires a path');
+      if (!fs.existsSync(filePath)) fail(`--from-file: file not found: ${filePath}`);
+      const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (typeof data !== 'object' || Array.isArray(data) || data === null) {
+        fail(`--from-file: expected a JSON object mapping field names to values`);
+      }
+      for (const [k, v] of Object.entries(data)) {
+        if (k === 'id' || k === 'type' || k === 'status' || k === 'locked') {
+          fail(`--from-file: cannot edit reserved field "${k}"`);
+        }
+        if (card.fields) card.fields[k] = v;
+      }
+    } else {
+      const updates = parseFields(args.slice(3));
+      for (const [k, v] of Object.entries(updates)) {
+        if (card.fields) card.fields[k] = v;
+      }
     }
     project.cards[idx] = card;
     writeProject(projectPath, project);
@@ -1562,14 +1682,32 @@ function cmdLock(args) {
 }
 
 function cmdMigrate(args) {
+  // Bug (UX pro-20 migration): prior version of `migrate` always
+  // attempted the full pipeline — read source folder, import to
+  // Studio project, lock all cards, then export. An author migrating
+  // 20 source-tree assets had no way to know in advance whether
+  // the assets would pass the v1.7.2+ Human Lock gate. The fix
+  // adds `--check` which runs the import + the critical-missing
+  // check + the lock-gate check, then prints a report and exits
+  // without writing the .kdna file. Pair with `audit-locks` for
+  // the full pre-migration report.
+  //
+  // Usage:
+  //   kdna-studio migrate <source-dir> --check --name <@scope/name>
+  //
+  // Exit codes:
+  //   0 — would succeed
+  //   2 — INPUT_ERROR (missing args)
+  //   4 — would fail (Human Lock gate or critical axiom field)
+  const checkOnly = args.includes('--check');
   const sourceDir = args[0];
   const out = option(args, '--out');
   const by = option(args, '--by');
   const statement = option(args, '--statement');
   const requestedName = option(args, '--name');
   let name = requestedName || 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 <pw>|--passphrase-stdin]');
+  if (!sourceDir || (!out && !checkOnly) || (!by && !checkOnly) || (!statement && !checkOnly)) {
+    fail('Usage: kdna-studio migrate <source-dir> --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--check] [--sign] [--passphrase <pw>|--passphrase-stdin]');
   }
 
   const sourcePath = path.resolve(sourceDir);
@@ -1636,6 +1774,42 @@ function cmdMigrate(args) {
     }
   }
 
+  // --check branch: print a pre-migration report and exit. The
+  // project object already has every card from the source tree
+  // imported, so we can run the same audit-locks logic here
+  // without re-reading the source. This is the single-call
+  // equivalent of `kdna-studio create --from-folder <src> &&
+  // kdna-studio audit-locks .` — but it requires no
+  // intermediate write.
+  if (checkOnly) {
+    const REQUIRED = {
+      axiom: ['confidence', 'evidence_type', 'one_sentence', 'full_statement', 'why',
+              'applies_when', 'does_not_apply_when', 'failure_risk'],
+      risk: ['name', 'description', 'mitigation'],
+      stance: ['statement', 'applies_when'],
+      misunderstanding: ['wrong', 'correct', 'key_distinction', 'why'],
+      boundary: ['scope', 'out_of_scope'],
+    };
+    const summary = { project: name, source: sourceDir, total: project.cards.length, by_type: {}, would_block: false };
+    for (const card of (project.cards || [])) {
+      const req = REQUIRED[card.type];
+      if (!req) continue;
+      const missing = [];
+      for (const f of req) {
+        const v = card.fields?.[f];
+        if (v === undefined || v === null || v === '' ||
+            (Array.isArray(v) && v.length === 0)) missing.push(f);
+      }
+      if (missing.length > 0) {
+        if (!summary.by_type[card.type]) summary.by_type[card.type] = [];
+        summary.by_type[card.type].push({ id: card.id, missing });
+        summary.would_block = true;
+      }
+    }
+    console.log(JSON.stringify(summary, null, 2));
+    process.exit(summary.would_block ? EXIT.HUMAN_LOCK_REQUIRED : EXIT.OK);
+  }
+
   // Step 2: approve and Human Lock all cards
   let locked = 0;
   for (let i = 0; i < (project.cards || []).length; i++) {
@@ -2162,6 +2336,135 @@ function cmdReport(args) {
   process.exit(gate.blocked ? EXIT.HUMAN_LOCK_REQUIRED : EXIT.OK);
 }
 
+// Audit-locks: list every card that would fail the v1.7.2+ Human Lock
+// gate because of missing or empty fields. Used during the
+// pre-migration review of source-tree assets (e.g. pro-20) so an
+// author can fill in the missing confidence / evidence_type / risk
+// description / stance statement BEFORE running `migrate --format v1`.
+//
+// Bug (UX pro-20 migration): prior version of `kdna-studio report`
+// returned a flat human_lock_gate.issues list, which mixed card
+// types and field names. An author migrating 20 source-tree
+// assets with 99 axioms + 140 risk cards + 70 stance cards had no
+// way to see, for a single asset, "which axioms are missing
+// confidence?" — they had to grep the project JSON. The fix adds
+// a per-type, per-field breakdown.
+function cmdAuditLocks(args) {
+  const { project } = readProject(args[0]);
+  const useJson = args.includes('--json');
+  const onlyType = option(args, '--type');  // 'axiom' | 'risk' | 'stance' | 'misunderstanding' | null
+
+  const cards = project.cards || [];
+  const findings = {
+    project: project.name,
+    card_count: cards.length,
+    locked_count: cards.filter(c => c.locked).length,
+    by_type: {},
+  };
+
+  // Per-card-type required field lists. Mirrors the v1.7.2+ lockCard
+  // gate (kdna-studio-core/src/cards/index.js) so the output is
+  // exactly the field set the gate will reject.
+  const REQUIRED = {
+    axiom: ['one_sentence', 'full_statement', 'why', 'applies_when',
+            'does_not_apply_when', 'failure_risk', 'confidence', 'evidence_type'],
+    risk: ['name', 'description', 'mitigation'],
+    stance: ['statement', 'applies_when'],
+    misunderstanding: ['wrong', 'correct', 'key_distinction', 'why'],
+    boundary: ['scope', 'out_of_scope'],
+    self_check: ['question'],
+  };
+  const THRESHOLDS = {
+    axiom: {
+      one_sentence: { min: 5, type: 'string' },
+      full_statement: { min: 20, type: 'string' },
+      why: { min: 20, type: 'string' },
+      failure_risk: { min: 1, type: 'string' },
+      confidence: { allowed: ['low', 'medium', 'high'] },
+      evidence_type: { allowed: ['case_observation', 'theoretical', 'empirical', 'analogy', 'principle'] },
+    },
+    risk: {
+      name: { min: 1, type: 'string' },
+      description: { min: 20, type: 'string' },
+      mitigation: { min: 1, type: 'string' },
+    },
+    stance: {
+      statement: { min: 1, type: 'string' },
+      applies_when: { type: 'array', minLength: 0 },
+    },
+  };
+
+  function checkField(type, fields, name, rule) {
+    const value = fields[name];
+    if (value === undefined || value === null || value === '') {
+      return { field: name, issue: 'missing' };
+    }
+    if (rule.type === 'string' && rule.min && String(value).length < rule.min) {
+      return { field: name, issue: 'too_short', have_length: String(value).length, need_min: rule.min };
+    }
+    if (rule.allowed && !rule.allowed.includes(value)) {
+      return { field: name, issue: 'invalid_value', have: value, allowed: rule.allowed };
+    }
+    if (rule.type === 'array' && !Array.isArray(value)) {
+      return { field: name, issue: 'wrong_type', have_type: typeof value, need_type: 'array' };
+    }
+    return null;
+  }
+
+  for (const card of cards) {
+    const req = REQUIRED[card.type];
+    if (!req) continue;
+    if (onlyType && card.type !== onlyType) continue;
+    const rule = THRESHOLDS[card.type] || {};
+    const missing = [];
+    for (const name of req) {
+      const issue = checkField(card.type, card.fields || {}, name, rule[name] || {});
+      if (issue) missing.push(issue);
+    }
+    if (missing.length > 0) {
+      if (!findings.by_type[card.type]) {
+        findings.by_type[card.type] = { missing_count: 0, cards: [] };
+      }
+      findings.by_type[card.type].missing_count += 1;
+      findings.by_type[card.type].cards.push({
+        id: card.id,
+        one_sentence: card.fields?.one_sentence || card.fields?.statement || card.fields?.question || '',
+        missing,
+      });
+    }
+  }
+
+  if (useJson) {
+    console.log(JSON.stringify(findings, null, 2));
+  } else {
+    console.log(`Project: ${findings.project}`);
+    console.log(`Cards: ${findings.card_count} (locked: ${findings.locked_count})`);
+    const types = Object.keys(findings.by_type);
+    if (types.length === 0) {
+      console.log('\nAll cards pass the v1.7.2+ Human Lock gate. Ready to migrate.');
+      return;
+    }
+    for (const t of types) {
+      const block = findings.by_type[t];
+      console.log(`\n${t}: ${block.missing_count} card(s) with missing fields`);
+      for (const card of block.cards) {
+        console.log(`  ${card.id}  ${(card.one_sentence || '').slice(0, 60)}`);
+        for (const m of card.missing) {
+          if (m.issue === 'missing') {
+            console.log(`    - ${m.field}: missing`);
+          } else if (m.issue === 'too_short') {
+            console.log(`    - ${m.field}: too short (have ${m.have_length}, need ≥ ${m.need_min})`);
+          } else if (m.issue === 'invalid_value') {
+            console.log(`    - ${m.field}: invalid value "${m.have}", allowed: ${m.allowed.join('|')}`);
+          } else {
+            console.log(`    - ${m.field}: ${m.issue}`);
+          }
+        }
+      }
+    }
+  }
+}
+
 // ─── Distillation Commands ──────────────────────────────────────────
 
 function cmdTarget(args) {
@@ -2254,9 +2557,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.');
 
@@ -2446,11 +2755,35 @@ async function cmdFeynman(args) {
   }
 
   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}`);
@@ -2496,18 +2829,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));
 }
 
@@ -2542,6 +2892,7 @@ try {
   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 === 'audit-locks') cmdAuditLocks(args.slice(1));
   else if (cmd === 'install') cmdStudioInstall(args.slice(1));
   else if (cmd === 'update') cmdStudioUpdate(args.slice(1));
   else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-cli",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Official KDNA Studio command-line authoring entry for creating, reviewing, compiling, and exporting .kdna judgment assets through the KDNA toolchain.",
   "type": "commonjs",
   "bin": {
@@ -45,6 +45,6 @@
     "cbor-x": "^1.6.4"
   },
   "devDependencies": {
-    "@aikdna/kdna-core": "^0.15.0"
+    "@aikdna/kdna-core": "^0.15.5"
   }
 }