@aikdna/kdna-cli 0.9.0

package/src/diff.js

@@ -0,0 +1,288 @@
+/**
+ * kdna diff <name>@<ver1> <name>@<ver2> — Judgment-level diff between versions.
+ *
+ * Downloads two .kdna packages from the registry, extracts to temp dirs,
+ * compares axioms / misunderstandings / banned_terms / stances / boundary,
+ * and surfaces what would change for an agent loading the new version.
+ *
+ * Not a structural file diff — a judgment diff:
+ *   - Added/removed/changed axioms with their applies_when boundaries
+ *   - Added/removed/changed misunderstandings
+ *   - Added/removed banned terms
+ *   - judgment_version bump (if declared)
+ *
+ * Usage:
+ *   kdna diff @aikdna/writing@0.7.1 @aikdna/writing@0.7.2
+ *   kdna diff @aikdna/writing                              # latest vs installed
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, execFileSync } = require('child_process');
+const { RegistryResolver, parseName } = require('./registry');
+
+const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
+const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
+const TMP_DIR = '/tmp';
+
+function error(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ─── Parse "<name>@<ver>" ──────────────────────────────────────────────
+
+function parseNameVersion(input) {
+  // accept @scope/name@version OR @scope/name OR bare@ver OR bare
+  const atSplit = input.split('@');
+  if (input.startsWith('@')) {
+    // @scope/name OR @scope/name@version
+    if (atSplit.length === 2) return { full: input, version: null };
+    if (atSplit.length === 3) return { full: '@' + atSplit[1], version: atSplit[2] };
+  } else {
+    if (atSplit.length === 1) return { full: input, version: null };
+    if (atSplit.length === 2) return { full: atSplit[0], version: atSplit[1] };
+  }
+  return null;
+}
+
+// ─── Download specific version ────────────────────────────────────────
+
+function downloadVersion(entry, version, destDir) {
+  // entry.kdna_url is for the registry-current version. For older versions
+  // we infer the URL pattern from the registry-current URL.
+  if (entry.version === version) {
+    return downloadAndExtract(entry.kdna_url, destDir);
+  }
+
+  // Infer pattern: replace v<current> in the URL with v<requested>
+  const inferredUrl = entry.kdna_url
+    .replace(`/v${entry.version}/`, `/v${version}/`)
+    .replace(`-${entry.version}.kdna`, `-${version}.kdna`);
+
+  return downloadAndExtract(inferredUrl, destDir);
+}
+
+function downloadAndExtract(url, destDir) {
+  const tmpFile = `${destDir}.kdna.tmp`;
+  try {
+    execFileSync('curl', ['-fsSL', '--retry', '2', '-o', tmpFile, url], {
+      timeout: 60000,
+      stdio: 'pipe',
+    });
+  } catch (e) {
+    error(`Failed to download ${url}: ${e.stderr?.toString().trim() || e.message}`);
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+  try {
+    execSync(`unzip -q -o "${tmpFile}" -d "${destDir}"`, { stdio: 'pipe' });
+  } catch {
+    const script = `import zipfile
+zf = zipfile.ZipFile(${JSON.stringify(tmpFile)}, 'r')
+zf.extractall(${JSON.stringify(destDir)})`;
+    execSync(`python3 -c ${JSON.stringify(script)}`, { stdio: 'pipe' });
+  }
+  fs.unlinkSync(tmpFile);
+  return destDir;
+}
+
+// ─── Extract judgment artifacts ────────────────────────────────────────
+
+function loadJudgment(domainDir) {
+  const core = readJson(path.join(domainDir, 'KDNA_Core.json')) || {};
+  const pat = readJson(path.join(domainDir, 'KDNA_Patterns.json')) || {};
+  const manifest = readJson(path.join(domainDir, 'kdna.json')) || {};
+
+  return {
+    version: manifest.version || '?',
+    judgment_version: manifest.judgment_version || null,
+    axioms: Object.fromEntries((core.axioms || []).map((a) => [a.id, a])),
+    ontology: Object.fromEntries((core.ontology || []).map((o) => [o.id, o])),
+    stances: (core.stances || [])
+      .map((s) => (typeof s === 'string' ? s : s.stance))
+      .filter(Boolean),
+    misunderstandings: Object.fromEntries((pat.misunderstandings || []).map((m) => [m.id, m])),
+    banned_terms: Object.fromEntries((pat.terminology?.banned_terms || []).map((t) => [t.term, t])),
+  };
+}
+
+// ─── Set diff helpers ─────────────────────────────────────────────────
+
+function diffMaps(label, oldMap, newMap, render) {
+  const oldIds = new Set(Object.keys(oldMap));
+  const newIds = new Set(Object.keys(newMap));
+  const added = [...newIds].filter((id) => !oldIds.has(id));
+  const removed = [...oldIds].filter((id) => !newIds.has(id));
+  const both = [...newIds].filter((id) => oldIds.has(id));
+  const changed = both.filter((id) => JSON.stringify(oldMap[id]) !== JSON.stringify(newMap[id]));
+
+  const out = { label, added, removed, changed };
+
+  console.log('');
+  console.log('─'.repeat(64));
+  console.log(`  ${label.toUpperCase()}`);
+  console.log(`  added:${added.length}  removed:${removed.length}  changed:${changed.length}`);
+  console.log('─'.repeat(64));
+
+  for (const id of added) {
+    console.log(`  + ${id}`);
+    if (render) console.log(`    "${render(newMap[id])}"`);
+  }
+  for (const id of removed) {
+    console.log(`  - ${id}`);
+    if (render) console.log(`    (was) "${render(oldMap[id])}"`);
+  }
+  for (const id of changed) {
+    console.log(`  ~ ${id}`);
+    if (render) {
+      console.log(`    was: "${render(oldMap[id])}"`);
+      console.log(`    now: "${render(newMap[id])}"`);
+    }
+    // Surface key diffs in v2.1 boundary fields
+    const a = oldMap[id],
+      b = newMap[id];
+    for (const field of ['applies_when', 'does_not_apply_when', 'failure_risk', 'confidence']) {
+      const before = JSON.stringify(a[field] ?? null);
+      const after = JSON.stringify(b[field] ?? null);
+      if (before !== after) {
+        console.log(`    [${field}] ${before} → ${after}`);
+      }
+    }
+  }
+
+  return out;
+}
+
+function diffStanceList(oldList, newList) {
+  const oldSet = new Set(oldList);
+  const newSet = new Set(newList);
+  const added = newList.filter((s) => !oldSet.has(s));
+  const removed = oldList.filter((s) => !newSet.has(s));
+  console.log('');
+  console.log('─'.repeat(64));
+  console.log(`  STANCES   added:${added.length}  removed:${removed.length}`);
+  console.log('─'.repeat(64));
+  for (const s of added) console.log(`  + "${s}"`);
+  for (const s of removed) console.log(`  - "${s}"`);
+}
+
+// ─── Main ──────────────────────────────────────────────────────────────
+
+async function cmdDiff(a, b) {
+  if (!a) error('Usage: kdna diff <name>@<v1> <name>@<v2>  or  kdna diff <name>');
+
+  const aParsed = parseNameVersion(a);
+  const bParsed = b ? parseNameVersion(b) : null;
+  if (!aParsed) error(`Cannot parse "${a}"`);
+
+  const resolver = new RegistryResolver({ allowNetwork: true });
+  let entryA;
+  try {
+    ({ entry: entryA } = resolver.resolve(aParsed.full));
+  } catch (e) {
+    error(e.message);
+  }
+
+  // Determine targets
+  let oldVersion, newVersion, oldEntry, newEntry;
+  if (bParsed) {
+    let entryB;
+    try {
+      ({ entry: entryB } = resolver.resolve(bParsed.full));
+    } catch (e) {
+      error(e.message);
+    }
+    if (aParsed.full !== bParsed.full)
+      error('Comparing across different domains is not supported.');
+    oldVersion = aParsed.version || entryA.version;
+    newVersion = bParsed.version || entryB.version;
+    oldEntry = entryA;
+    newEntry = entryB;
+  } else {
+    // single-arg form: installed vs registry-current
+    const parsed = parseName(aParsed.full);
+    const localDir = path.join(INSTALL_DIR, parsed.scope, parsed.ident);
+    if (!fs.existsSync(localDir)) {
+      error(`${aParsed.full} not installed. Run: kdna install ${aParsed.full}`);
+    }
+    const localManifest = readJson(path.join(localDir, 'kdna.json'));
+    oldVersion = localManifest?.version || '?';
+    newVersion = entryA.version;
+    oldEntry = entryA;
+    newEntry = entryA;
+    if (oldVersion === newVersion) {
+      console.log(
+        `${aParsed.full}@${oldVersion}: only one version found.\n` +
+          `To compare across versions, specify two: kdna diff ${aParsed.full}@${oldVersion} ${aParsed.full}@<other>`,
+      );
+      return;
+    }
+  }
+
+  console.log('═'.repeat(64));
+  console.log(`  kdna diff  ${aParsed.full}`);
+  console.log(`  ${oldVersion}  →  ${newVersion}`);
+  console.log('═'.repeat(64));
+
+  // Download both versions to temp dirs
+  const tmpOld = path.join(TMP_DIR, `kdna-diff-${Date.now()}-old`);
+  const tmpNew = path.join(TMP_DIR, `kdna-diff-${Date.now()}-new`);
+
+  console.log('Downloading old version...');
+  downloadVersion(oldEntry, oldVersion, tmpOld);
+  console.log('Downloading new version...');
+  downloadVersion(newEntry, newVersion, tmpNew);
+
+  const oldJ = loadJudgment(tmpOld);
+  const newJ = loadJudgment(tmpNew);
+
+  console.log('');
+  console.log(
+    '  judgment_version: ' +
+      (oldJ.judgment_version || '(not declared)') +
+      '  →  ' +
+      (newJ.judgment_version || '(not declared)'),
+  );
+
+  diffMaps('axioms', oldJ.axioms, newJ.axioms, (a) => a.one_sentence || a.id);
+  diffMaps('ontology', oldJ.ontology, newJ.ontology, (o) => o.one_sentence || o.id);
+  diffMaps(
+    'misunderstandings',
+    oldJ.misunderstandings,
+    newJ.misunderstandings,
+    (m) => m.wrong || m.id,
+  );
+  diffMaps('banned_terms', oldJ.banned_terms, newJ.banned_terms, (t) => t.term || '');
+  diffStanceList(oldJ.stances, newJ.stances);
+
+  // Cleanup
+  try {
+    fs.rmSync(tmpOld, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+  try {
+    fs.rmSync(tmpNew, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+
+  console.log('');
+  console.log('═'.repeat(64));
+  const drift = Object.keys(newJ.axioms).length - Object.keys(oldJ.axioms).length;
+  const note = drift !== 0 ? ` (axiom count drift: ${drift > 0 ? '+' : ''}${drift})` : '';
+  console.log(`  Judgment surface change: ${oldVersion} → ${newVersion}${note}`);
+  console.log(`  Agent loading the new version may classify, diagnose, or recommend differently.`);
+  console.log('═'.repeat(64));
+}
+
+module.exports = { cmdDiff, loadJudgment, parseNameVersion };

package/src/identity.js

@@ -0,0 +1,211 @@
+/**
+ * KDNA Identity — Ed25519 key pair generation and management.
+ *
+ * Commands:
+ *   identity init           Generate key pair
+ *   identity show           Display public key and buyer_id
+ *   identity export [--out]  Backup private key (age-encrypted)
+ *   identity import <file>   Restore from backup
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const IDENTITY_DIR =
+  process.env.KDNA_IDENTITY_DIR ||
+  path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna', 'identity');
+
+const PRIVATE_KEY_PATH = path.join(IDENTITY_DIR, 'kdna.key');
+const PUBLIC_KEY_PATH = path.join(IDENTITY_DIR, 'kdna.pub');
+
+function error(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+// ─── Key Generation ────────────────────────────────────────────────────
+
+function generateKeyPair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return { publicKey, privateKey };
+}
+
+function deriveBuyerId(publicKeyPem) {
+  return crypto.createHash('sha256').update(publicKeyPem).digest('hex').substring(0, 16);
+}
+
+function fingerprint(publicKeyPem) {
+  return crypto.createHash('sha256').update(publicKeyPem).digest('hex').substring(0, 12);
+}
+
+function cmdIdentityInit() {
+  if (fs.existsSync(PRIVATE_KEY_PATH)) {
+    const pub = fs.readFileSync(PUBLIC_KEY_PATH, 'utf8');
+    const id = deriveBuyerId(pub);
+    console.log(`Identity already exists.`);
+    console.log(`  Buyer ID:  ${id}`);
+    console.log(`  Public:    ${PUBLIC_KEY_PATH}`);
+    console.log(`  Private:   ${PRIVATE_KEY_PATH}`);
+    return;
+  }
+
+  fs.mkdirSync(IDENTITY_DIR, { recursive: true });
+
+  const { publicKey, privateKey } = generateKeyPair();
+
+  fs.writeFileSync(PRIVATE_KEY_PATH, privateKey, { mode: 0o600 });
+  fs.writeFileSync(PUBLIC_KEY_PATH, publicKey, { mode: 0o644 });
+
+  const id = deriveBuyerId(publicKey);
+  const fp = fingerprint(publicKey);
+
+  console.log(`✓ Identity created.`);
+  console.log(`  Buyer ID:     ${id}`);
+  console.log(`  Fingerprint:  ${fp}`);
+  console.log(`  Public key:   ${PUBLIC_KEY_PATH}`);
+  console.log(`  Private key:  ${PRIVATE_KEY_PATH} (chmod 600)`);
+  console.log('');
+  console.log(`  Backup your private key immediately:`);
+  console.log(`    kdna identity export --out kdna-identity-backup.age`);
+}
+
+// ─── Show ──────────────────────────────────────────────────────────────
+
+function cmdIdentityShow() {
+  if (!fs.existsSync(PUBLIC_KEY_PATH)) {
+    error('No identity found. Run: kdna identity init');
+  }
+
+  const pub = fs.readFileSync(PUBLIC_KEY_PATH, 'utf8');
+  const id = deriveBuyerId(pub);
+  const fp = fingerprint(pub);
+
+  console.log(`Buyer ID:     ${id}`);
+  console.log(`Fingerprint:  ${fp}`);
+  console.log(`Public key:   ${PUBLIC_KEY_PATH}`);
+  console.log(
+    `Private key:  ${PRIVATE_KEY_PATH} ${fs.existsSync(PRIVATE_KEY_PATH) ? '(exists)' : '(MISSING!)'}`,
+  );
+}
+
+// ─── Export (backup) ───────────────────────────────────────────────────
+
+function cmdIdentityExport(outFile) {
+  if (!fs.existsSync(PRIVATE_KEY_PATH)) {
+    error('No private key found. Run: kdna identity init');
+  }
+
+  const outPath = path.resolve(outFile || 'kdna-identity-backup.age');
+  const privateKey = fs.readFileSync(PRIVATE_KEY_PATH, 'utf8');
+
+  // Simple passphrase-encrypted backup using built-in crypto
+  // Uses AES-256-CBC with PBKDF2 key derivation
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+
+  rl.question('Enter passphrase (or leave empty to abort): ', (passphrase) => {
+    rl.close();
+    if (!passphrase) {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+
+    const salt = crypto.randomBytes(16);
+    const key = crypto.pbkdf2Sync(passphrase, salt, 100000, 32, 'sha256');
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
+
+    const header = JSON.stringify({
+      alg: 'pbkdf2+aes-256-cbc',
+      salt: salt.toString('base64'),
+      iv: iv.toString('base64'),
+    });
+    const headerB64 = Buffer.from(header).toString('base64');
+
+    const encrypted = Buffer.concat([cipher.update(privateKey, 'utf8'), cipher.final()]);
+
+    const output = `-----BEGIN KDNA IDENTITY BACKUP-----\n${headerB64}\n${encrypted.toString('base64')}\n-----END KDNA IDENTITY BACKUP-----\n`;
+
+    fs.writeFileSync(outPath, output, { mode: 0o600 });
+    console.log(`✓ Identity exported to: ${outPath}`);
+    console.log(`  Keep this file safe. It is encrypted with your passphrase.`);
+    process.exit(0);
+  });
+}
+
+// ─── Import (restore) ──────────────────────────────────────────────────
+
+function cmdIdentityImport(filePath) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) error(`File not found: ${abs}`);
+
+  const content = fs.readFileSync(abs, 'utf8');
+  const match = content.match(
+    /-----BEGIN KDNA IDENTITY BACKUP-----\n(.+?)\n(.+?)\n-----END KDNA IDENTITY BACKUP-----/s,
+  );
+  if (!match) error('Invalid backup file format.');
+
+  const header = JSON.parse(Buffer.from(match[1], 'base64').toString('utf8'));
+  if (header.alg !== 'pbkdf2+aes-256-cbc') error(`Unsupported algorithm: ${header.alg}`);
+
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+
+  rl.question('Enter passphrase: ', (passphrase) => {
+    rl.close();
+    if (!passphrase) {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+
+    const salt = Buffer.from(header.salt, 'base64');
+    const iv = Buffer.from(header.iv, 'base64');
+    const key = crypto.pbkdf2Sync(passphrase, salt, 100000, 32, 'sha256');
+    const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+
+    try {
+      const encrypted = Buffer.from(match[2], 'base64');
+      const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]).toString(
+        'utf8',
+      );
+
+      fs.mkdirSync(IDENTITY_DIR, { recursive: true });
+      fs.writeFileSync(PRIVATE_KEY_PATH, decrypted, { mode: 0o600 });
+
+      // Derive public key from private
+      const privateKeyObj = crypto.createPrivateKey({
+        key: decrypted,
+        format: 'pem',
+        type: 'pkcs8',
+      });
+      const publicKey = crypto
+        .createPublicKey(privateKeyObj)
+        .export({ type: 'spki', format: 'pem' });
+      fs.writeFileSync(PUBLIC_KEY_PATH, publicKey, { mode: 0o644 });
+
+      const id = deriveBuyerId(publicKey);
+      console.log(`✓ Identity restored.`);
+      console.log(`  Buyer ID:  ${id}`);
+    } catch {
+      console.log('Error: Incorrect passphrase or corrupted backup.');
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+}
+
+module.exports = {
+  cmdIdentityInit,
+  cmdIdentityShow,
+  cmdIdentityExport,
+  cmdIdentityImport,
+  PRIVATE_KEY_PATH,
+  PUBLIC_KEY_PATH,
+  IDENTITY_DIR,
+  fingerprint,
+  deriveBuyerId,
+};

package/src/init.js

@@ -0,0 +1,168 @@
+/**
+ * kdna init <name>        — Scaffold a new KDNA domain from template.
+ * kdna cluster init <name> — Scaffold a new KDNA cluster from template.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Recursively copy a directory, applying string replacements.
+ */
+function copyRecursive(src, dest, replacements) {
+  const entries = fs.readdirSync(src);
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    if (fs.statSync(srcPath).isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath, replacements);
+    } else {
+      let content = fs.readFileSync(srcPath, 'utf8');
+      for (const [pattern, to] of Object.entries(replacements)) {
+        content = content.replaceAll(pattern, to);
+      }
+      fs.writeFileSync(destPath, content);
+    }
+  }
+}
+
+function cmdInit(name) {
+  if (!name) {
+    console.error('Error: Domain name required. Usage: kdna init <name>');
+    process.exit(1);
+  }
+
+  if (!/^[a-z][a-z0-9_]*$/.test(name)) {
+    console.error(
+      `Error: Invalid domain name "${name}". Must be lowercase letters, numbers, underscores. Start with a letter.`,
+    );
+    process.exit(1);
+  }
+
+  const templateDir = path.resolve(__dirname, '..', 'templates', 'minimal-domain');
+  const targetDir = path.resolve(name);
+
+  if (fs.existsSync(targetDir)) {
+    console.error(`Error: Directory already exists: ${targetDir}`);
+    process.exit(1);
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  copyRecursive(templateDir, targetDir, {
+    example_domain: name,
+    'YYYY-MM-DD': today,
+  });
+
+  console.log(`✓ Created KDNA domain: ${targetDir}/`);
+  console.log(`  Files: KDNA_Core.json, KDNA_Patterns.json, kdna.json, tests/before-after.json`);
+
+  // Run structural validation (lint + schema only). Content quality checks
+  // are for publish time, not scaffold time — the template contains placeholders
+  // marked [TODO] that the author is expected to replace.
+  try {
+    const { execSync } = require('child_process');
+    const cli = process.argv[1];
+    const validCmd = `node "${cli}" validate "${targetDir}"`;
+    const { status } = execSync(validCmd, { stdio: 'pipe', encoding: 'utf8' });
+    // Structural validation passed (non-zero exit means purely structural failure)
+    if (status === null || status === undefined) {
+      console.log(`  ✓ Structural validation passed (lint + schema OK)`);
+    }
+  } catch (e) {
+    console.error(`  ⚠ Structural validation had issues:`);
+    const stderr = e.stderr?.toString() || e.stdout?.toString() || '';
+    if (stderr)
+      console.error(
+        stderr
+          .trim()
+          .split('\n')
+          .map((l) => `    ${l}`)
+          .join('\n'),
+      );
+  }
+
+  console.log('');
+  console.log(`Next steps:`);
+  console.log(`  1. Edit ${targetDir}/KDNA_Core.json — replace all [TODO] placeholders`);
+  console.log(
+    `  2. Edit ${targetDir}/KDNA_Patterns.json — replace terminology and misunderstandings`,
+  );
+  console.log(`  3. Edit ${targetDir}/kdna.json — set author, description, repo`);
+  console.log(`  4. Run: kdna validate ${name}               (structural check)`);
+  console.log(`  5. Run: kdna publish --check ${name}         (content quality gate)`);
+  console.log(`  6. Run: kdna verify ${name}                  (full judgment scoring)`);
+}
+
+/**
+ * kdna cluster init <name> — Scaffold a new KDNA cluster from template.
+ */
+function cmdClusterInit(name) {
+  if (!name) {
+    console.error('Error: Cluster name required. Usage: kdna cluster init <name>');
+    process.exit(1);
+  }
+
+  if (!/^[a-z][a-z0-9_]*$/.test(name)) {
+    console.error(
+      `Error: Invalid cluster name "${name}". Must be lowercase letters, numbers, underscores. Start with a letter.`,
+    );
+    process.exit(1);
+  }
+
+  const clusterTemplateDir = path.resolve(__dirname, '..', 'templates', 'cluster');
+  const domainTemplateDir = path.resolve(__dirname, '..', 'templates', 'minimal-domain');
+  const targetDir = path.resolve(name);
+
+  if (fs.existsSync(targetDir)) {
+    console.error(`Error: Directory already exists: ${targetDir}`);
+    process.exit(1);
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  // Copy cluster manifest with replacements
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  let clusterContent = fs.readFileSync(path.join(clusterTemplateDir, 'KDNA_Cluster.json'), 'utf8');
+  clusterContent = clusterContent.replace(/example_cluster/g, name);
+  clusterContent = clusterContent.replace(
+    /sub_domain_/g,
+    `${name.replace(/_cluster$/, '')}_domain_`,
+  );
+  fs.writeFileSync(path.join(targetDir, 'KDNA_Cluster.json'), clusterContent);
+
+  // Copy cluster README
+  const clusterReadme = fs.readFileSync(path.join(clusterTemplateDir, 'README.md'), 'utf8');
+  fs.writeFileSync(
+    path.join(targetDir, 'README.md'),
+    clusterReadme.replace(/example_cluster/g, name),
+  );
+
+  // Create first example sub-domain from domain template
+  const subDir = path.join(targetDir, 'domain_one');
+  fs.mkdirSync(subDir, { recursive: true });
+  copyRecursive(domainTemplateDir, subDir, {
+    example_domain: `${name.replace(/_cluster$/, '')}_domain_one`,
+    'YYYY-MM-DD': today,
+  });
+
+  console.log(`✅ Created KDNA cluster: ${targetDir}/`);
+  console.log(`   Files: KDNA_Cluster.json, domain_one/ (6 KDNA files + kdna.json + tests/)`);
+  console.log('');
+  console.log(`Next steps:`);
+  console.log(
+    `  1. Edit ${targetDir}/KDNA_Cluster.json — set packages, composition rules, routing`,
+  );
+  console.log(
+    `  2. Edit ${targetDir}/domain_one/KDNA_Core.json — fill in axioms, concepts, stances`,
+  );
+  console.log(
+    `  3. Add more sub-domains: cp -r ${targetDir}/domain_one ${targetDir}/your_new_domain`,
+  );
+  console.log(`  4. Run: kdna validate ${name}              (check all sub-domains)`);
+}
+
+module.exports = { cmdInit, cmdClusterInit };