@aikdna/kdna-studio-cli 0.5.1 → 0.5.3

package/README.md

@@ -58,12 +58,14 @@ Candidate promotion is scope-gated: only candidates with `status == accepted` an
 After export, use the runtime CLI:
 
 ```bash
-kdna verify dist/my_domain.kdna --judgment
-kdna publish dist/my_domain.kdna
+kdna validate dist/my_domain.kdna
+kdna load dist/my_domain.kdna --profile=compact --as=prompt
 ```
 
-`kdna-studio` is the CLI entry for trusted KDNA creation. `kdna` is the runtime
-control plane for existing `.kdna` assets.
+`kdna-studio` is the CLI entry for confirmed KDNA authoring. `kdna` is the
+runtime control plane for inspecting, validating, packing, unpacking, and
+loading existing `.kdna` assets. Signature, encryption, registry publishing,
+and private assets are future/gated phases, not the current Core v1 baseline.
 
 ## Identity
 
@@ -85,6 +87,6 @@ kdna-studio create migrated --from-folder ./old-domain-json --name @scope/migrat
 ## Related
 
 - [KDNA Core](https://github.com/aikdna/kdna) — Official format specification
-- [kdna-cli](https://github.com/aikdna/kdna-cli) — runtime CLI for verify, install, load, publish
+- [kdna-cli](https://github.com/aikdna/kdna-cli) — runtime CLI for inspect, validate, pack, unpack, and load
 - [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

@@ -4,6 +4,7 @@ const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
 const zlib = require('zlib');
+const cbor = require('cbor-x');
 
 const {
   project: projectApi,
@@ -14,6 +15,7 @@ const {
   creator: creatorApi,
   distillation: distillationApi,
 } = require('@aikdna/kdna-studio-core');
+const { buildChecksumsV1 } = require('@aikdna/kdna-core/v1');
 
 const llm = require('../src/llm');
 const ai = require('../src/ai');
@@ -37,7 +39,7 @@ Create (three entry paths):
   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]
+  kdna-studio migrate <source-dir|project> --format v1 --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--sign]
 
 Authoring:
   kdna-studio import <project> <source-file-or-dir>               # import evidence (txt/md/json/yaml/csv/log/srt/vtt/html)
@@ -48,7 +50,8 @@ Authoring:
   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]
+  kdna-studio export <project> --format v1 --out <file.kdna>
+  kdna-studio export <project> --out <file.kdna> [--sign]                  # legacy v2
 
 AI Authoring (requires LLM config: kdna-studio llm config):
   kdna-studio distill <project> --ai                             # AI-driven candidate extraction from evidence
@@ -149,6 +152,391 @@ function parseFields(args) {
   return fields;
 }
 
+function arrayValue(value) {
+  if (Array.isArray(value)) return value;
+  if (value === undefined || value === null || value === '') return [];
+  return [value];
+}
+
+function semverValue(value, fallback = '1.0.0') {
+  const raw = String(value || '').trim();
+  if (/^[0-9]+\.[0-9]+\.[0-9]+([+-].+)?$/.test(raw)) return raw;
+  const twoPart = raw.match(/^([0-9]+)\.([0-9]+)$/);
+  if (twoPart) return `${twoPart[1]}.${twoPart[2]}.0`;
+  return fallback;
+}
+
+function isoDateTime(value) {
+  if (!value) return new Date().toISOString();
+  const raw = String(value);
+  if (/^\d{4}-\d{2}-\d{2}$/.test(raw)) return `${raw}T00:00:00.000Z`;
+  const d = new Date(raw);
+  return Number.isNaN(d.getTime()) ? new Date().toISOString() : d.toISOString();
+}
+
+function slugSegment(value, fallback = 'asset') {
+  const s = String(value || fallback)
+    .trim()
+    .replace(/^@/, '')
+    .replace(/[^a-zA-Z0-9_.-]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return s || fallback;
+}
+
+function assetIdFromName(name) {
+  const raw = String(name || '').trim();
+  if (/^[a-zA-Z][a-zA-Z0-9_-]*(:[a-zA-Z0-9_.-]+)+$/.test(raw)) return raw;
+  const scoped = raw.match(/^@?([^/:\s]+)\/([^/:\s]+)$/);
+  if (scoped) return `kdna:${slugSegment(scoped[1], 'scope')}:${slugSegment(scoped[2], 'asset')}`;
+  const parts = raw.split(':').filter(Boolean);
+  if (parts.length >= 2) return `kdna:${parts.map((p) => slugSegment(p)).join(':')}`;
+  return `kdna:studio:${slugSegment(raw, 'asset')}`;
+}
+
+function titleFromName(name, assetId) {
+  const raw = String(name || '').trim();
+  if (raw) return raw.replace(/^@/, '').replace('/', ' / ');
+  return assetId;
+}
+
+function publicManifestMetadata(raw = {}) {
+  const copy = { ...raw };
+  delete copy.registry;
+  delete copy.quality_badge;
+  delete copy.signature;
+  delete copy.media_type;
+  return copy;
+}
+
+function cardPayload(card) {
+  return { id: card.id, ...(card.fields || {}) };
+}
+
+function cleanFields(fields = {}) {
+  const cleaned = {};
+  for (const [key, value] of Object.entries(fields || {})) {
+    if (value !== undefined && value !== null) cleaned[key] = value;
+  }
+  return cleaned;
+}
+
+function importedCard(type, fields = {}, id = null) {
+  try {
+    return cardApi.createCard(type, cleanFields(fields), id || null);
+  } catch (_) {
+    return null;
+  }
+}
+
+function pushImportedCard(cards, type, fields = {}, id = null) {
+  const card = importedCard(type, fields, id);
+  if (card) cards.push(card);
+}
+
+function decodePayload(bytes, manifest = {}) {
+  const raw = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  const encoding = manifest.payload?.encoding || manifest.container?.payload_encoding || null;
+  if (encoding === 'json' || raw[0] === 0x7b || raw[0] === 0x5b) {
+    return JSON.parse(raw.toString('utf8'));
+  }
+  return cbor.decode(raw);
+}
+
+function cardsFromV1Payload(payload) {
+  const cards = [];
+  for (const sourceCard of (payload.source_cards || [])) {
+    pushImportedCard(cards, sourceCard.type, sourceCard.fields || {}, sourceCard.id || null);
+  }
+  if (cards.length > 0) return cards;
+
+  for (const ax of (payload.core?.axioms || [])) {
+    pushImportedCard(cards, 'axiom', {
+      one_sentence: ax.one_sentence || '',
+      full_statement: ax.full_statement || '',
+      why: ax.why || '',
+      applies_when: ax.applies_when || [],
+      does_not_apply_when: ax.does_not_apply_when || [],
+      failure_risk: ax.failure_risk || '',
+    }, ax.id || null);
+  }
+  for (const boundary of (payload.core?.boundaries || [])) {
+    pushImportedCard(cards, 'boundary', boundary, boundary.id || null);
+  }
+  for (const risk of (payload.core?.risk_model?.risks || [])) {
+    pushImportedCard(cards, 'risk', risk, risk.id || null);
+  }
+  for (const pattern of (payload.patterns || [])) {
+    if (!pattern.type) continue;
+    const { type, ...fields } = pattern;
+    pushImportedCard(cards, type, fields, pattern.id || null);
+  }
+  for (const scenario of (payload.scenarios || [])) {
+    pushImportedCard(cards, 'scenario', scenario, scenario.id || null);
+  }
+  for (const item of (payload.cases || [])) {
+    pushImportedCard(cards, 'case', item, item.id || null);
+  }
+  for (const selfCheck of (payload.reasoning?.self_checks || [])) {
+    const fields = typeof selfCheck === 'string' ? { question: selfCheck } : selfCheck;
+    pushImportedCard(cards, 'self_check', fields, fields.id || null);
+  }
+  for (const failureMode of (payload.reasoning?.failure_modes || [])) {
+    pushImportedCard(cards, 'misunderstanding', {
+      wrong: failureMode.mode || failureMode.wrong || '',
+      correct: failureMode.correct || '',
+      key_distinction: failureMode.key_distinction || '',
+      why: failureMode.why || '',
+    }, failureMode.id || null);
+  }
+  for (const chain of (payload.reasoning?.reasoning_chains || [])) {
+    pushImportedCard(cards, 'reasoning', chain, chain.id || null);
+  }
+  for (const stage of (payload.evolution?.stages || [])) {
+    pushImportedCard(cards, 'evolution_stage', stage, stage.id || null);
+  }
+  return cards;
+}
+
+function cardsFromLegacyPayload(payload) {
+  const cards = [];
+  const judgment = payload.judgment || {};
+  const core = judgment.core || {};
+  const patterns = judgment.patterns || {};
+
+  for (const ax of (core.axioms || [])) {
+    pushImportedCard(cards, 'axiom', {
+      one_sentence: ax.one_sentence || '',
+      full_statement: ax.full_statement || '',
+      why: ax.why || '',
+      applies_when: ax.applies_when || [],
+      does_not_apply_when: ax.does_not_apply_when || [],
+      failure_risk: ax.failure_risk || '',
+    }, ax.id || null);
+  }
+  for (const ont of (core.ontology || [])) {
+    pushImportedCard(cards, 'ontology', {
+      one_sentence: ont.one_sentence || ont.essence || '',
+      essence: ont.essence || '',
+      boundary: ont.boundary || '',
+      trigger_signal: ont.trigger_signal || '',
+    }, ont.id || null);
+  }
+  for (const boundary of (core.boundaries || [])) {
+    pushImportedCard(cards, 'boundary', {
+      scope: boundary.scope || '',
+      out_of_scope: boundary.out_of_scope || '',
+      acceptable_exceptions: boundary.acceptable_exceptions || [],
+    }, boundary.id || null);
+  }
+  for (const risk of (core.risks || [])) {
+    pushImportedCard(cards, 'risk', risk, risk.id || null);
+  }
+  for (const term of (patterns.terminology?.standard_terms || [])) {
+    pushImportedCard(cards, 'term', term, term.id || null);
+  }
+  for (const banned of (patterns.terminology?.banned_terms || [])) {
+    pushImportedCard(cards, 'banned_term', banned, banned.id || null);
+  }
+  for (const ms of (patterns.misunderstandings || [])) {
+    pushImportedCard(cards, 'misunderstanding', {
+      wrong: ms.wrong || '',
+      correct: ms.correct || '',
+      key_distinction: ms.key_distinction || '',
+      why: ms.why || '',
+      applies_when: ms.applies_when || [],
+      does_not_apply_when: ms.does_not_apply_when || [],
+      failure_risk: ms.failure_risk || '',
+    }, ms.id || null);
+  }
+  for (const sc of (patterns.self_check || [])) {
+    const question = typeof sc === 'string' ? sc : sc.question || '';
+    pushImportedCard(cards, 'self_check', { question }, sc.id || null);
+  }
+  for (const aesthetic of (patterns.aesthetics || [])) {
+    pushImportedCard(cards, 'aesthetic', aesthetic, aesthetic.id || null);
+  }
+  for (const scene of (judgment.scenarios?.scenes || [])) {
+    pushImportedCard(cards, 'scenario', scene, scene.id || null);
+  }
+  for (const item of (judgment.cases?.cases || [])) {
+    pushImportedCard(cards, 'case', item, item.id || null);
+  }
+  for (const chain of (judgment.reasoning?.reasoning_chains || [])) {
+    pushImportedCard(cards, 'reasoning', chain, chain.id || null);
+  }
+  for (const stage of (judgment.evolution?.stages || [])) {
+    pushImportedCard(cards, 'evolution_stage', stage, stage.id || null);
+  }
+  return cards;
+}
+
+function cardsFromPayload(payload) {
+  if (!payload || typeof payload !== 'object') return [];
+  if (payload.profile === 'judgment-profile-v1' || payload.core || payload.source_cards) {
+    return cardsFromV1Payload(payload);
+  }
+  if (payload.kind === 'kdna.payload' || payload.judgment) {
+    return cardsFromLegacyPayload(payload);
+  }
+  return [];
+}
+
+function buildV1Payload(project) {
+  const locked = (project.cards || []).filter((c) => c.locked);
+  const byType = (type) => locked.filter((c) => c.type === type);
+  const source = project.source_manifest || {};
+
+  const axioms = byType('axiom').map((c) => ({
+    id: c.id,
+    one_sentence: c.fields?.one_sentence || '',
+    full_statement: c.fields?.full_statement || '',
+    why: c.fields?.why || '',
+    applies_when: arrayValue(c.fields?.applies_when),
+    does_not_apply_when: arrayValue(c.fields?.does_not_apply_when),
+    failure_risk: c.fields?.failure_risk || '',
+    status: c.status || null,
+    human_lock: c.human_lock || null,
+  }));
+
+  const boundaries = [
+    ...byType('boundary').map((c) => ({ type: 'explicit_boundary', ...cardPayload(c) })),
+    ...byType('axiom').map((c) => ({
+      id: `${c.id}_applicability`,
+      type: 'axiom_applicability',
+      axiom_id: c.id,
+      one_sentence: c.fields?.one_sentence || '',
+      applies_when: arrayValue(c.fields?.applies_when),
+      does_not_apply_when: arrayValue(c.fields?.does_not_apply_when),
+      failure_risk: c.fields?.failure_risk || '',
+    })),
+    ...byType('ontology')
+      .filter((c) => c.fields?.boundary || c.fields?.applies_when || c.fields?.does_not_apply_when)
+      .map((c) => ({
+        id: `${c.id}_boundary`,
+        type: 'ontology_boundary',
+        concept_id: c.id,
+        one_sentence: c.fields?.one_sentence || '',
+        boundary: c.fields?.boundary || '',
+        applies_when: arrayValue(c.fields?.applies_when),
+        does_not_apply_when: arrayValue(c.fields?.does_not_apply_when),
+        trigger_signal: c.fields?.trigger_signal || '',
+      })),
+    ...byType('stance')
+      .filter((c) => c.fields?.applies_when || c.fields?.does_not_apply_when)
+      .map((c) => ({
+        id: `${c.id}_boundary`,
+        type: 'stance_boundary',
+        stance_id: c.id,
+        stance: c.fields?.stance || c.fields?.statement || c.fields?.one_sentence || '',
+        applies_when: arrayValue(c.fields?.applies_when),
+        does_not_apply_when: arrayValue(c.fields?.does_not_apply_when),
+      })),
+  ];
+
+  const patterns = [
+    ...byType('ontology').map((c) => ({ type: 'ontology', ...cardPayload(c) })),
+    ...byType('misunderstanding').map((c) => ({ type: 'misunderstanding', ...cardPayload(c) })),
+    ...byType('term').map((c) => ({ type: 'term', ...cardPayload(c) })),
+    ...byType('banned_term').map((c) => ({ type: 'banned_term', ...cardPayload(c) })),
+    ...byType('framework').map((c) => ({ type: 'framework', ...cardPayload(c) })),
+    ...byType('stance').map((c) => ({ type: 'stance', ...cardPayload(c) })),
+  ];
+
+  const failureModes = byType('misunderstanding').map((c) => ({
+    id: c.id,
+    mode: c.fields?.wrong || c.fields?.key_distinction || c.id,
+    correct: c.fields?.correct || '',
+    key_distinction: c.fields?.key_distinction || '',
+    why: c.fields?.why || '',
+  }));
+
+  return {
+    profile: 'judgment-profile-v1',
+    core: {
+      highest_question: source.core_insight || project.release?.description || '',
+      axioms,
+      boundaries,
+      risk_model: {
+        risks: byType('risk').map((c) => cardPayload(c)),
+        source_risk_level: source.risk_level || null,
+        fitness_for_purpose: source.fitness_for_purpose || null,
+      },
+    },
+    patterns,
+    scenarios: byType('scenario').map((c) => cardPayload(c)),
+    cases: byType('case').map((c) => cardPayload(c)),
+    reasoning: {
+      self_checks: byType('self_check').map((c) => c.fields?.question || c.fields?.one_sentence || c.id),
+      failure_modes: failureModes,
+      reasoning_chains: byType('reasoning').map((c) => cardPayload(c)),
+    },
+    evolution: {
+      stages: byType('evolution_stage').map((c) => cardPayload(c)),
+      changelog: locked.map((c) => ({
+        id: `locked_${c.id}`,
+        card_id: c.id,
+        type: c.type,
+        event: 'locked',
+        at: c.human_lock?.at || null,
+      })),
+      version_notes: source.judgment_version ? [`Migrated from source judgment_version ${source.judgment_version}`] : [],
+    },
+    source_cards: locked.map((c) => ({
+      id: c.id,
+      type: c.type,
+      status: c.status,
+      fields: c.fields || {},
+      human_lock: c.human_lock || null,
+    })),
+  };
+}
+
+function buildV1Manifest(project, name) {
+  const source = project.source_manifest || {};
+  const assetId = assetIdFromName(name || source.name || project.name);
+  const author = source.author || project.author || {};
+  return {
+    kdna_version: '1.0',
+    asset_id: assetId,
+    asset_uid: project.asset_uid || 'urn:uuid:' + crypto.randomUUID(),
+    asset_type: project.type === 'cluster' ? 'cluster' : 'domain',
+    source_asset_type: source.asset_type || null,
+    title: titleFromName(source.name || name || project.name, assetId),
+    version: semverValue(project.release?.version || source.version, '1.0.0'),
+    judgment_version: semverValue(project.release?.judgment_version || source.judgment_version || source.version, '1.0.0'),
+    created_at: isoDateTime(source.created || project.created),
+    updated_at: isoDateTime(source.updated || project.updated),
+    creator: {
+      name: author.name || project.author?.name || 'Studio Export',
+      id: author.id || project.author?.id || undefined,
+    },
+    compatibility: { min_loader_version: '1.0.0', profile: 'judgment-profile-v1' },
+    payload: { path: 'payload.kdnab', encoding: 'json', encrypted: false },
+    summary: source.core_insight || project.release?.description || source.description || '',
+    description: source.description || project.release?.description || '',
+    language: source.default_language || project.default_language || (Array.isArray(source.languages) ? source.languages[0] : undefined),
+    languages: source.languages || project.languages || undefined,
+    license: source.license || project.license || undefined,
+    keywords: source.keywords || [],
+    lineage: {
+      type: project.lineage?.type === 'migrated' ? 'adaptation' : (project.lineage?.type || 'original'),
+      fork_of: null,
+      derived_from: source.name || project.lineage?.parent_name || null,
+      source_lineage_type: project.lineage?.type || null,
+    },
+    load_contract: {
+      default_profile: 'compact',
+      profiles: {
+        index: { requires_decryption: false, max_tokens_hint: 500, selection: 'manifest metadata', intended_for: ['discovery'] },
+        compact: { requires_decryption: false, max_tokens_hint: 2000, selection: 'core judgment summary', intended_for: ['agent prompt'] },
+        scenario: { requires_decryption: false, max_tokens_hint: 3000, selection: 'scenario cards', intended_for: ['situational loading'] },
+        full: { requires_decryption: false, max_tokens_hint: 12000, selection: 'full manifest and payload', intended_for: ['audit', 'migration'] },
+      },
+    },
+    source_manifest: publicManifestMetadata(source),
+  };
+}
+
 function cmdCreate(args) {
   const dir = args[0];
   if (!dir) fail('Usage: kdna-studio create <project-dir> --name <name> [--from-kdna <file> | --from-folder <dir>]');
@@ -171,13 +559,30 @@ function cmdCreate(args) {
     const kdnaData = importFromKdna(fromKdna);
     lineage = kdnaData.lineage;
     if (kdnaData.cards) {
+      const sourceAuthor = kdnaData.source_manifest?.author || {};
       const project = projectApi.createProject(name, 'domain', {
-        author: { name: option(args, '--author-name', ''), id: option(args, '--author-id', '') },
+        author: {
+          name: option(args, '--author-name', sourceAuthor.name || ''),
+          id: option(args, '--author-id', sourceAuthor.id || ''),
+        },
         sourceMode,
         creatorIdentity,
         lineage,
       });
       project.cards = kdnaData.cards;
+      if (kdnaData.source_manifest) project.source_manifest = publicManifestMetadata(kdnaData.source_manifest);
+      if (kdnaData.source_manifest?.version) {
+        if (!project.release) project.release = {};
+        project.release.version = kdnaData.source_manifest.version;
+      }
+      if (kdnaData.source_manifest?.judgment_version) {
+        if (!project.release) project.release = {};
+        project.release.judgment_version = kdnaData.source_manifest.judgment_version;
+      }
+      if (kdnaData.source_manifest?.description) {
+        if (!project.release) project.release = {};
+        project.release.description = kdnaData.source_manifest.description;
+      }
       if (project.stages?.judgment_cards) {
         project.stages.judgment_cards.total = kdnaData.cards.length;
         project.stages.judgment_cards.status = 'in_progress';
@@ -232,10 +637,10 @@ function importFromKdna(kdnaPath) {
   const manifest = JSON.parse(entries.get('kdna.json').toString());
   const lineage = {
     type: 'fork',
-    parent_name: manifest.name || null,
+    parent_name: manifest.name || manifest.title || manifest.asset_id || null,
     parent_asset_uid: manifest.asset_uid || null,
     parent_version: manifest.version || null,
-    parent_asset_digest: manifest.content_digest || null,
+    parent_asset_digest: manifest.content_digest || manifest.asset_digest || null,
   };
 
   // Extract cards from KDNA files
@@ -277,7 +682,16 @@ function importFromKdna(kdnaPath) {
     }
   }
 
-  return { lineage, cards: importedCards };
+  if (importedCards.length === 0 && entries.has('payload.kdnab')) {
+    try {
+      const payload = decodePayload(entries.get('payload.kdnab'), manifest);
+      importedCards.push(...cardsFromPayload(payload));
+    } catch (e) {
+      fail(`Could not import cards from payload.kdnab: ${e.message}`);
+    }
+  }
+
+  return { lineage, cards: importedCards, source_manifest: manifest };
 }
 
 /**
@@ -305,12 +719,22 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
   // Load manifest for version/languages/description
   const manifest = loadJson('kdna.json');
   if (manifest) {
+    manifestData.raw = 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;
+    if (manifest.keywords) manifestData.keywords = manifest.keywords;
+    if (manifest.license) manifestData.license = manifest.license;
+    if (manifest.author) manifestData.author = manifest.author;
+    if (manifest.asset_type) manifestData.asset_type = manifest.asset_type;
+    if (manifest.core_insight) manifestData.core_insight = manifest.core_insight;
+    if (manifest.created) manifestData.created = manifest.created;
+    if (manifest.updated) manifestData.updated = manifest.updated;
+    if (manifest.risk_level) manifestData.risk_level = manifest.risk_level;
+    if (manifest.fitness_for_purpose) manifestData.fitness_for_purpose = manifest.fitness_for_purpose;
   }
 
   const core = loadJson('KDNA_Core.json');
@@ -450,8 +874,11 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
     if (!project.release) project.release = {};
     project.release.description = manifestData.description;
   }
+  if (manifestData.license) project.license = manifestData.license;
+  if (manifestData.author) project.author = manifestData.author;
   if (manifestData.languages) project.languages = manifestData.languages;
   if (manifestData.default_language) project.default_language = manifestData.default_language;
+  if (manifestData.raw) project.source_manifest = publicManifestMetadata(manifestData.raw);
 
   project.cards = importedCards;
   if (project.stages?.judgment_cards) {
@@ -699,16 +1126,33 @@ function cmdMigrate(args) {
   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 || '.'));
+  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 <pass>]');
   }
 
-  // Step 1: create temp project and import everything from dev source
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-migrate-'));
+  const sourcePath = path.resolve(sourceDir);
+  const format = option(args, '--format');
+  const isStudioProject = fs.existsSync(path.join(sourcePath, 'studio.project.json'));
+  let tmpDir = null;
+  let projectPath = null;
+  let project = null;
+
+  // Step 1: import dev source, or use an existing Studio project directly.
   let creatorIdentity = null;
   try { creatorIdentity = creatorApi.loadIdentity(); } catch { /* proceed without */ }
-  const { project } = importFromFolder(sourceDir, tmpDir, name, creatorIdentity);
+  if (format === 'v1' && isStudioProject) {
+    const loaded = readProject(sourcePath);
+    project = loaded.project;
+    projectPath = loaded.projectPath;
+    if (!requestedName && project.name) name = project.name;
+  } else {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-migrate-'));
+    const imported = importFromFolder(sourceDir, tmpDir, name, creatorIdentity);
+    project = imported.project;
+    projectPath = path.join(tmpDir, 'studio.project.json');
+  }
 
   // Reject if critical judgment fields are missing from axioms
   const criticalMissing = [];
@@ -762,7 +1206,7 @@ function cmdMigrate(args) {
     project.stages.judgment_cards.locked = locked;
     project.stages.judgment_cards.total = project.cards.length;
   }
-  writeProject(path.join(tmpDir, 'studio.project.json'), project);
+  writeProject(projectPath, project);
   console.log(`Approved and Human Locked: ${locked} cards`);
 
   // Step 3: verify Human Lock gate
@@ -774,37 +1218,11 @@ function cmdMigrate(args) {
 
   const absOut = path.resolve(out);
   // Step 4: v1 export or v2 compile + export
-  if (args.includes('--format') && option(args, '--format') === 'v1') {
-    let core;
-    try { core = require('@aikdna/kdna-core'); } catch (e) {
-      fail('@aikdna/kdna-core@0.11.0+ is required for v1 export.', 2);
+  if (format === 'v1') {
+    exportProjectV1(project, name, absOut);
+    if (tmpDir) {
+      try { fs.rmSync(tmpDir, { recursive: true }); } catch { /* cleanup */ }
     }
-    const lockedAxioms = (project.cards || []).filter(c => c.type === 'axiom' && c.locked);
-    const v1Dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-v1-'));
-    fs.writeFileSync(path.join(v1Dir, 'mimetype'), 'application/vnd.kdna.asset');
-    fs.writeFileSync(path.join(v1Dir, 'kdna.json'), JSON.stringify({
-      kdna_version: '1.0', asset_id: name || 'studio:v1-export',
-      asset_uid: 'urn:uuid:' + crypto.randomUUID(), asset_type: 'domain',
-      title: name || 'Studio v1 Export', version: '1.0.0',
-      judgment_version: '1.0.0',
-      created_at: new Date().toISOString(), updated_at: new Date().toISOString(),
-      creator: { name: 'Studio Export' },
-      compatibility: { min_loader_version: '1.0.0', profile: 'judgment-profile-v1' },
-      payload: { path: 'payload.kdnab', encoding: 'json', encrypted: false },
-      lineage: { type: 'original', fork_of: null, derived_from: null },
-    }, null, 2));
-    fs.writeFileSync(path.join(v1Dir, 'payload.kdnab'), JSON.stringify({
-      profile: 'judgment-profile-v1',
-      core: { highest_question: '', axioms: lockedAxioms.map(c => ({ one_sentence: c.fields?.one_sentence || c.summary || '' })), boundaries: [], risk_model: {} },
-      patterns: [], scenarios: [], cases: [], reasoning: { self_checks: [], failure_modes: [] },
-    }, null, 2));
-    core.pack(v1Dir, absOut);
-    const vr = core.validate(absOut);
-    if (!vr.overall_valid) fail('v1 export validation failed: ' + (vr.problems || []).join('; '));
-    console.log('Exported (v1): ' + absOut);
-    console.log('  Name: ' + name + '  Axioms: ' + lockedAxioms.length + '  Validated: all gates pass');
-    try { fs.rmSync(v1Dir, { recursive: true }); } catch { /* cleanup */ }
-    try { fs.rmSync(tmpDir, { recursive: true }); } catch { /* cleanup */ }
     return;
   }
   const { result } = compileProject(tmpDir);
@@ -827,7 +1245,37 @@ function cmdMigrate(args) {
   console.log(`  Build ID: ${result.identity.build_id}`);
 
   // Cleanup temp
-  try { fs.rmSync(tmpDir, { recursive: true }); } catch { /* best effort */ }
+  if (tmpDir) {
+    try { fs.rmSync(tmpDir, { recursive: true }); } catch { /* best effort */ }
+  }
+}
+
+function exportProjectV1(project, name, outPath) {
+  let core;
+  try { core = require('@aikdna/kdna-core'); } catch (e) {
+    fail('@aikdna/kdna-core@0.11.0+ is required for v1 export.', 2);
+  }
+  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 v1 export:\n  - ${reasons}`, EXIT.HUMAN_LOCK_REQUIRED);
+  }
+  const lockedCards = (project.cards || []).filter(c => c.locked);
+  const v1Dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-v1-'));
+  try {
+    fs.writeFileSync(path.join(v1Dir, 'mimetype'), 'application/vnd.kdna.asset');
+    fs.writeFileSync(path.join(v1Dir, 'kdna.json'), JSON.stringify(buildV1Manifest(project, name), null, 2));
+    fs.writeFileSync(path.join(v1Dir, 'payload.kdnab'), JSON.stringify(buildV1Payload(project), null, 2));
+    fs.writeFileSync(path.join(v1Dir, 'checksums.json'), JSON.stringify(buildChecksumsV1(v1Dir), null, 2));
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    core.pack(v1Dir, outPath);
+    const vr = core.validate(outPath);
+    if (!vr.overall_valid) fail('v1 export validation failed: ' + (vr.problems || []).join('; '));
+    console.log('Exported (v1): ' + outPath);
+    console.log('  Name: ' + name + '  Cards: ' + lockedCards.length + '  Validated: all gates pass');
+  } finally {
+    try { fs.rmSync(v1Dir, { recursive: true }); } catch { /* cleanup */ }
+  }
 }
 
 function compileProject(projectInput) {
@@ -1004,7 +1452,12 @@ function applySignature(files, passphrase = null) {
 function cmdExport(args) {
   const projectInput = args[0];
   const out = option(args, '--out');
-  if (!projectInput || !out) fail('Usage: kdna-studio export <project> --out <file.kdna> [--sign]');
+  if (!projectInput || !out) fail('Usage: kdna-studio export <project> --out <file.kdna> [--format v1] [--sign]');
+  if (option(args, '--format') === 'v1') {
+    const { project } = readProject(projectInput);
+    exportProjectV1(project, option(args, '--name') || project.name, path.resolve(out));
+    return;
+  }
   const { project, result } = compileProject(projectInput);
   const files = { ...result.files };
   files['README.md'] = compileApi.generateReadme(project);
@@ -1430,6 +1883,10 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   usage();
   process.exit(EXIT.OK);
 }
+if (cmd === '--version' || cmd === '-v') {
+  console.log(require('../package.json').version);
+  process.exit(EXIT.OK);
+}
 
 (async () => {
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-cli",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Official KDNA Studio command-line authoring entry for creating, locking, compiling, and exporting .kdna judgment assets through the KDNA toolchain.",
   "type": "commonjs",
   "bin": {
@@ -38,10 +38,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-studio-core": "^1.5.0",
-    "@aikdna/kdna-core": "^0.11.0"
+    "@aikdna/kdna-core": "^0.11.1",
+    "@aikdna/kdna-studio-core": "^1.5.3",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "cbor-x": "^1.6.4"
   },
   "devDependencies": {
-    "@aikdna/kdna-core": "^0.11.0"
+    "@aikdna/kdna-core": "^0.11.1"
   }
 }

package/tests/cli.test.js

@@ -309,6 +309,133 @@ test('create --from-folder imports legacy JSON source, outputs audit', (t) => {
   assert.equal(project.lineage.type, 'migrated');
 });
 
+test('migrate --format v1 maps scoped name, writes checksums, and preserves source cards', (t) => {
+  assert.ok(kdnaCore, '@aikdna/kdna-core is required for v1 export verification');
+  const tmp = tmpDir();
+  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  const sourceDir = path.join(tmp, 'legacy-source');
+  fs.mkdirSync(sourceDir, { recursive: true });
+  fs.writeFileSync(path.join(sourceDir, 'kdna.json'), JSON.stringify({
+    name: '@test/legacy-import',
+    version: '0.7.3',
+    judgment_version: '2026.05',
+    asset_type: 'domain_judgment',
+    description: 'Legacy import fixture.',
+    core_insight: 'Preserve real judgment structure.',
+    author: { name: 'Test Author', id: 'test-author' },
+    license: { type: 'CC-BY-4.0' },
+    keywords: ['legacy', 'v1'],
+    languages: ['en'],
+    default_language: 'en',
+    quality_badge: 'tested',
+    registry: { repo: 'https://example.invalid/legacy' },
+  }));
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Core.json'), JSON.stringify({
+    axioms: [{
+      id: 'ax_legacy',
+      one_sentence: 'Prefer specific evidence over broad claims.',
+      full_statement: 'When evaluating a claim the agent must preserve specific evidence and not collapse it into generic advice.',
+      why: 'Without this judgment the agent produces plausible but weak summaries.',
+      applies_when: ['reviewing content'],
+      does_not_apply_when: ['pure formatting'],
+      failure_risk: 'May over-diagnose simple copy edits.',
+    }],
+    ontology: [{ id: 'on_legacy', essence: 'Specificity anchor', boundary: 'Not generic polish', trigger_signal: 'abstract claim' }],
+    frameworks: [{ id: 'fw_legacy', name: 'Diagnose before rewrite', when_to_use: 'reviewing drafts', steps: ['diagnose', 'rewrite'] }],
+    stances: [{ id: 'st_legacy', stance: 'Structure first', applies_when: ['draft review'], does_not_apply_when: ['grammar only'] }],
+  }));
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Patterns.json'), JSON.stringify({
+    terminology: {
+      standard_terms: [{ term: 'specificity anchor', definition: 'A concrete detail.' }],
+      banned_terms: [{ term: 'make it better', why: 'Non-diagnostic.', replace_with: 'name the structural issue' }],
+    },
+    misunderstandings: [{ wrong: 'Smooth means good.', correct: 'Smooth can hide weak thinking.', key_distinction: 'surface vs structure', why: 'Prevents false praise.' }],
+    self_check: ['Did I preserve the structural judgment?'],
+  }));
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Scenarios.json'), JSON.stringify({ scenes: [{ id: 'sc_legacy', name: 'Draft review', trigger: 'user asks for review', action: 'diagnose first' }] }));
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Cases.json'), JSON.stringify({ cases: [{ id: 'ca_legacy', title: 'Smooth but empty', scenario: 'draft reads well', expected: 'flag missing claim' }] }));
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Reasoning.json'), JSON.stringify({ reasoning_chains: [{ id: 're_legacy', name: 'structure-first', conclusion: 'diagnose structure first', so_what: 'avoid surface polish' }] }));
+  fs.writeFileSync(path.join(sourceDir, 'KDNA_Evolution.json'), JSON.stringify({ stages: [{ id: 'ev_legacy', name: 'Structural reviewer', description: 'Moves beyond surface editing.' }] }));
+
+  const outFile = path.join(tmp, 'legacy.kdna');
+  const result = run([
+    'migrate', sourceDir,
+    '--out', outFile,
+    '--name', '@test/legacy-import',
+    '--by', 'tester',
+    '--statement', 'I confirm this v1 migration fixture.',
+    '--format', 'v1',
+  ], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+
+  const validation = kdnaCore.validate(outFile);
+  assert.equal(validation.overall_valid, true, JSON.stringify(validation.problems));
+  const inspected = kdnaCore.inspect(outFile);
+  assert.equal(inspected.asset_id, 'kdna:test:legacy-import');
+  assert.equal(inspected.checksums_present, true);
+
+  const full = kdnaCore.loadV1(outFile, { profile: 'full', as: 'json' }).content;
+  assert.equal(full.manifest.creator.name, 'Test Author');
+  assert.equal(full.manifest.version, '0.7.3');
+  assert.equal(full.manifest.judgment_version, '2026.05.0');
+  assert.equal(full.payload.core.axioms.length, 1);
+  assert.equal(full.payload.core.boundaries.length, 3);
+  assert.ok(full.payload.core.boundaries.some((b) => b.type === 'axiom_applicability'));
+  assert.ok(full.payload.core.boundaries.some((b) => b.type === 'ontology_boundary'));
+  assert.ok(full.payload.core.boundaries.some((b) => b.type === 'stance_boundary'));
+  assert.equal(full.payload.patterns.filter((p) => p.type === 'term').length, 1);
+  assert.equal(full.payload.patterns.filter((p) => p.type === 'banned_term').length, 1);
+  assert.equal(full.payload.scenarios.length, 1);
+  assert.equal(full.payload.cases.length, 1);
+  assert.equal(full.payload.reasoning.self_checks.length, 1);
+  assert.equal(full.payload.reasoning.failure_modes.length, 1);
+  assert.equal(full.payload.reasoning.reasoning_chains.length, 1);
+  assert.equal(full.payload.evolution.stages.length, 1);
+  assert.equal(full.payload.source_cards.length, 12);
+  assert.equal(JSON.stringify(full).includes('quality_badge'), false);
+  assert.equal(JSON.stringify(full).includes('registry'), false);
+});
+
+test('export --format v1 exports a Studio project as a valid non-empty v1 asset', (t) => {
+  assert.ok(kdnaCore, '@aikdna/kdna-core is required for v1 export verification');
+  const { tmp, projectDir } = createLockedProject(t);
+  const outFile = path.join(tmp, 'project-v1.kdna');
+
+  const result = run(['export', projectDir, '--format', 'v1', '--out', outFile], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Exported \(v1\)/);
+
+  const validation = kdnaCore.validate(outFile);
+  assert.equal(validation.overall_valid, true, JSON.stringify(validation.problems));
+  const loaded = kdnaCore.loadV1(outFile, { profile: 'full', as: 'json' }).content;
+  assert.equal(loaded.payload.core.axioms.length, 1);
+  assert.equal(loaded.payload.source_cards.length, 1);
+  assert.ok(loaded.payload.core.boundaries.some((b) => b.type === 'axiom_applicability'));
+});
+
+test('migrate --format v1 accepts an existing Studio project without dropping cards', (t) => {
+  assert.ok(kdnaCore, '@aikdna/kdna-core is required for v1 export verification');
+  const { tmp, projectDir } = createLockedProject(t);
+  const outFile = path.join(tmp, 'project-migrated-v1.kdna');
+
+  const result = run([
+    'migrate', projectDir,
+    '--format', 'v1',
+    '--out', outFile,
+    '--by', 'tester',
+    '--statement', 'I confirm this project v1 migration.',
+  ], { tmp });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Cards: 1/);
+
+  const validation = kdnaCore.validate(outFile);
+  assert.equal(validation.overall_valid, true, JSON.stringify(validation.problems));
+  const loaded = kdnaCore.loadV1(outFile, { profile: 'full', as: 'json' }).content;
+  assert.equal(loaded.payload.core.axioms.length, 1);
+  assert.equal(loaded.payload.source_cards.length, 1);
+});
+
 // ── Create from KDNA ────────────────────────────────────────────────
 
 test('create --from-kdna forks an existing .kdna asset', (t) => {