@knolo/cli 6.2.0 → 6.2.2

package/bin/skill.mjs

@@ -0,0 +1,1308 @@
+/**
+ * knolo skill
+ *
+ * Creates a Knolo skill pack: guidance plus an optional pinned V5 image.
+ * The pack names no host and no home directory. The Knolo hub stores packs.
+ * It does not run a model and it does not answer questions.
+ * SATISFIED means evidence requirements were met.
+ */
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  normalizeRegistryUrl,
+  registryApiUrl,
+  resolveRegistryUrl,
+} from './registry/config.mjs';
+import { loadCredentials } from './registry/credentials.mjs';
+import { getJson, postJson, putBytes } from './registry/http.mjs';
+import { findOnPath } from './setup.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const SKILL_PACK_FORMAT = 'knolo-skill-pack-v1';
+export const MAX_KNOWLEDGE_FILES = 100;
+export const MAX_KNOWLEDGE_BYTES = 1024 * 1024;
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const EXTENSIONS = new Set(['.md', '.txt', '.json']);
+
+const USAGE = `Usage: knolo skill <init|check|pack|publish|install|search|info|list> [options]
+
+  knolo skill init <name> [--dir <parent>]
+  knolo skill check [<dir>] [--query <text>] [--json]
+  knolo skill pack [<dir>] [--out <dir>] [--json]
+  knolo skill publish <pack> [--registry <url>] [--json]
+  knolo skill publish <pack> --hub <dir> [--json]
+  knolo skill install <publisher>/<name> [--dir <path>] [--registry <url>] [--json]
+  knolo skill install <name> --hub <dir> [--dir <path>] [--json]
+  knolo skill install --pack <pack> [--dir <path>] [--json]
+  knolo skill search <query> [--registry <url>] [--json]
+  knolo skill info <publisher>/<name> [--registry <url>] [--json]
+  knolo skill list [--registry <url>] [--json]
+
+A skill is guidance for the host agent. Knolo does not call a model.
+check searches the skill's own knowledge and returns a receipt id.
+A receipt is an integrity check. It does not mean a claim is proven.
+SATISFIED means the evidence requirements were met.
+publish sends the pack to https://hub.knolo.dev unless --hub names a
+local directory. install checks the pin before it writes. It writes into
+--dir, or into ~/.knolo/skills when --dir is omitted. A pin mismatch
+writes nothing. When that folder is a skills root and knolo-box is on
+PATH, install runs one knolo-box build.
+list prints every publisher/name from the public catalog. It does not
+send a token.
+The hub stores packs. It does not answer questions.`;
+
+export async function runSkillCli(argv) {
+  const { positionals, flags } = parseArgs(argv);
+  const sub = positionals[0] ?? '';
+  if (!sub || sub === 'help' || flags.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (sub === 'init') return initSkill(positionals[1], flags);
+  if (sub === 'check') return checkSkill(positionals[1], flags);
+  if (sub === 'pack') return packSkill(positionals[1], flags);
+  if (sub === 'publish') return publishSkill(positionals[1], flags);
+  if (sub === 'install') return installSkill(positionals[1], flags);
+  if (sub === 'search') return searchSkills(positionals.slice(1).join(' '), flags);
+  if (sub === 'info') return infoSkill(positionals[1], flags);
+  if (sub === 'list') return listSkills(flags);
+  throw new Error(`Unknown skill command "${sub}".\n${USAGE}`);
+}
+
+export function skillNameError(name) {
+  if (typeof name !== 'string' || !NAME.test(name)) {
+    return 'SKILL_NAME: use lowercase letters, digits, and single hyphens.';
+  }
+  return null;
+}
+
+const ABSOLUTE_PATH =
+  /(?:^|[\s`"'(])(?:~\/|\/(?:home|Users|opt|var|tmp)\/|[A-Za-z]:\\)/u;
+
+function hostLayoutError(text) {
+  if (ABSOLUTE_PATH.test(text)) {
+    return 'SKILL_GUIDANCE: a skill pack cannot name a home directory or an absolute path.';
+  }
+  return null;
+}
+
+export function guidanceError(body) {
+  const layout = hostLayoutError(body);
+  if (layout) return layout;
+  const patterns = [
+    /\b(?:skip|ignore|omit|bypass)\b[^.\n]{0,48}\b(?:pin|receipt)\b/giu,
+    /\bwithout (?:a |the )?(?:pin|receipt)\b/giu,
+    /\b(?:do not|don't|never) (?:cite|include|return)\b[^.\n]{0,48}\breceipt\b/giu,
+  ];
+  for (const pattern of patterns) pattern.lastIndex = 0;
+  for (const pattern of patterns) {
+    for (const match of body.matchAll(pattern)) {
+      const start = Math.max(0, match.index - 20);
+      const prefix = body.slice(start, match.index).toLowerCase();
+      const negated = /\b(?:not|never)\s*$/u.test(prefix);
+      const tellsYouToDropTheReceipt = /\b(?:cite|include|return)\b/iu.test(
+        match[0]
+      );
+      if (negated && !tellsYouToDropTheReceipt) continue;
+      return `SKILL_GUIDANCE: the skill tells the agent to skip a pin or a receipt (${match[0]}).`;
+    }
+  }
+  if (!/\breceipt\b/iu.test(body)) {
+    return 'SKILL_GUIDANCE: the skill must tell the agent to cite a receipt.';
+  }
+  if (
+    !/\bintegrity\b/iu.test(body) &&
+    !/does not mean a claim is proven/iu.test(body)
+  ) {
+    return 'SKILL_GUIDANCE: the skill must say that a receipt is an integrity check.';
+  }
+  return null;
+}
+
+function initSkill(name, flags) {
+  const nameError = skillNameError(name);
+  if (nameError) throw new Error(nameError);
+  const parent = path.resolve(process.cwd(), flags.dir ?? '.');
+  const dir = path.join(parent, name);
+  return prepareSkillDir(dir, name, flags);
+}
+
+async function prepareSkillDir(dir, name, flags) {
+  try {
+    await lstat(dir);
+    throw new Error(`SKILL_NAME: ${dir} already exists.`);
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+  }
+  await mkdir(path.join(dir, 'knowledge'), { recursive: true });
+  const skill = skillTemplate(name);
+  await writeFile(path.join(dir, 'SKILL.md'), skill, { mode: 0o644 });
+  const summary = { ok: true, name, dir };
+  if (flags.json) console.log(JSON.stringify(summary));
+  else console.log(`wrote ${dir}`);
+}
+
+function skillTemplate(name) {
+  return `---
+name: ${name}
+description: Cite the pinned Knolo image for ${name} before answering.
+---
+
+# ${name}
+
+The host owns the model. This skill does not call one.
+
+1. Search the pinned image for this skill.
+2. Include the receipt id in the reply.
+3. A receipt is an integrity check. It does not mean a claim is proven. SATISFIED means the evidence requirements were met.
+4. Do not skip the pin. Do not invent a passage.
+`;
+}
+
+async function checkSkill(dirArg, flags) {
+  const loaded = await loadSkillDir(dirArg);
+  const report = await inspectSkill(loaded, flags.query);
+  if (flags.json) console.log(JSON.stringify(report));
+  else {
+    console.log(`skill            ${report.name}`);
+    console.log(`receipt          ${report.receiptId ?? 'none'}`);
+    console.log(`hits             ${report.hits}`);
+    if (report.stateRoot) console.log(`state root       ${report.stateRoot}`);
+  }
+}
+
+async function packSkill(dirArg, flags) {
+  const loaded = await loadSkillDir(dirArg);
+  const built = await buildSkill(loaded, flags.query);
+  const out = path.resolve(
+    process.cwd(),
+    flags.out ??
+      path.join(loaded.dir, 'dist', `${loaded.parsed.name}.knolo-skill`)
+  );
+  try {
+    await lstat(out);
+    throw new Error(`SKILL_PACK: refusing to overwrite ${out}.`);
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+  }
+  await writePack(out, built);
+  const summary = packSummary(built, out);
+  if (flags.json) console.log(JSON.stringify(summary));
+  else {
+    console.log(`skill            ${summary.name}`);
+    console.log(`wrote            ${out}`);
+    console.log(`skill sha256     ${summary.skillSha256}`);
+    if (summary.image) {
+      console.log(`image sha256     ${summary.image.sha256}`);
+      console.log(`state root       ${summary.image.stateRoot}`);
+    }
+  }
+}
+
+async function publishSkill(packArg, flags) {
+  if (!packArg) throw new Error('SKILL_HUB: pass the pack directory.');
+  if (flags.hub) {
+    if (flags.registry) {
+      throw new Error(
+        'SKILL_HUB: --hub is a local directory. Use --registry for the Knolo hub.'
+      );
+    }
+    return publishSkillDirectory(packArg, flags);
+  }
+  const credentials = await loadCredentials();
+  const registry = resolveSkillRegistry(flags.registry, credentials.registry);
+  const summary = await publishSkillToRegistry(
+    path.resolve(process.cwd(), packArg),
+    { registry, token: credentials.token }
+  );
+  if (flags.json) console.log(JSON.stringify(summary));
+  else if (summary.unchanged) console.log(`unchanged        ${summary.name}`);
+  else console.log(`published        ${summary.name}`);
+}
+
+async function publishSkillDirectory(packArg, flags) {
+  const packDir = path.resolve(process.cwd(), packArg ?? '');
+  if (!packArg) throw new Error('SKILL_HUB: pass the pack directory.');
+  const pack = await readVerifiedPack(packDir);
+  const hub = path.resolve(process.cwd(), flags.hub);
+  const dest = path.join(hub, pack.manifest.name);
+  await rejectHostPath(dest);
+  try {
+    const existing = await readVerifiedPack(dest);
+    if (
+      existing.manifest.skillSha256 !== pack.manifest.skillSha256 ||
+      !sameImage(existing.manifest.image, pack.manifest.image)
+    ) {
+      throw new Error(
+        `SKILL_HUB: ${pack.manifest.name} is already in the catalog with a different pin.`
+      );
+    }
+    const summary = {
+      ok: true,
+      name: pack.manifest.name,
+      hub: dest,
+      unchanged: true,
+    };
+    if (flags.json) console.log(JSON.stringify(summary));
+    else console.log(`unchanged        ${dest}`);
+    return;
+  } catch (error) {
+    if (!(error && error.code === 'ENOENT')) throw error;
+  }
+  await writePackFiles(dest, pack);
+  const summary = {
+    ok: true,
+    name: pack.manifest.name,
+    hub: dest,
+    unchanged: false,
+  };
+  if (flags.json) console.log(JSON.stringify(summary));
+  else console.log(`published        ${dest}`);
+}
+
+export async function installSkill(nameArg, flags) {
+  const env = flags.env ?? process.env;
+  const home = flags.homeDir || env.HOME || homedir();
+  const destRoot = path.resolve(
+    flags.dir ?? path.join(home, '.knolo', 'skills')
+  );
+  if (flags.hub && flags.registry) {
+    throw new Error(
+      'SKILL_HUB: --hub is a local directory. Use --registry for the Knolo hub.'
+    );
+  }
+  if (!flags.pack && !flags.hub) {
+    if (flags.hub === undefined && nameArg && nameArg.includes('/')) {
+      const registry = resolveRegistryUrl({
+        value: flags.registry,
+        env: flags.env ?? process.env,
+      });
+      const summary = await installSkillFromRegistry(nameArg, destRoot, {
+        registry,
+        fetchImpl: flags.fetchImpl ?? globalThis.fetch,
+      });
+      return reportInstall(summary, destRoot, flags);
+    }
+    throw new Error(
+      'SKILL_HUB: pass publisher/name, or --hub for a directory catalog.'
+    );
+  }
+  let pack;
+  if (flags.pack) {
+    pack = await readVerifiedPack(path.resolve(process.cwd(), flags.pack));
+  } else {
+    if (!nameArg) throw new Error('SKILL_HUB: pass a skill name or --pack.');
+    if (!flags.hub) throw new Error('Missing --hub');
+    const nameError = skillNameError(nameArg);
+    if (nameError) throw new Error(nameError);
+    pack = await readVerifiedPack(
+      path.join(path.resolve(process.cwd(), flags.hub), nameArg)
+    );
+    if (pack.manifest.name !== nameArg) {
+      throw new Error(
+        `SKILL_HUB: catalog entry ${nameArg} is a pack named ${pack.manifest.name}.`
+      );
+    }
+  }
+  const dest = path.join(destRoot, pack.manifest.name);
+  await rejectHostPath(dest);
+  try {
+    await lstat(dest);
+    throw new Error(`SKILL_PACK: refusing to overwrite ${dest}.`);
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+  }
+  await writePackFiles(dest, pack);
+  const summary = { ok: true, name: pack.manifest.name, dir: dest };
+  return reportInstall(summary, destRoot, flags);
+}
+
+async function reportInstall(summary, destRoot, flags) {
+  const print = flags.print ?? console.log;
+  if (flags.json) print(JSON.stringify(summary));
+  else print(`installed        ${summary.dir}`);
+  await indexInstalledSkill(destRoot, flags);
+  return summary;
+}
+
+async function indexInstalledSkill(destRoot, flags) {
+  const printError = flags.printError ?? console.error;
+  const env = flags.env ?? process.env;
+  const home = flags.homeDir || env.HOME || homedir();
+  const configPath = path.join(home, '.knolo', 'box', 'box.config.json');
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch {
+    config = null;
+  }
+  const roots = skillRootsFromConfig(config, env, home);
+  const dest = await canonicalDir(destRoot);
+  let indexed = false;
+  for (const root of roots) {
+    if (typeof root !== 'string' || root.length === 0) continue;
+    if ((await canonicalDir(root)) === dest) {
+      indexed = true;
+      break;
+    }
+  }
+  if (!indexed) {
+    printError(
+      'This folder is not a Knolo skills root, so the install was not indexed.'
+    );
+    return;
+  }
+  const box = await findOnPath('knolo-box', env.PATH);
+  if (!box) {
+    printError('knolo-box is not on PATH. The install was not indexed.');
+    return;
+  }
+  const status = await spawnBox(box, ['build', '--config', configPath], env);
+  if (status !== 0) {
+    printError(
+      `knolo-box build exited with status ${status}. The install was not indexed.`
+    );
+  }
+}
+
+function skillRootsFromConfig(config, env, home) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return [];
+  const fallbackGrok = path.resolve(
+    expandBoxPath(env.GROK_HOME?.trim() || path.join(home, '.grok'), home, '')
+  );
+  const grokHome = path.resolve(
+    expandBoxPath(
+      typeof config.grokHome === 'string' ? config.grokHome : fallbackGrok,
+      home,
+      fallbackGrok
+    )
+  );
+  const scopes = config.scopes;
+  if (scopes !== undefined) {
+    if (!scopes || typeof scopes !== 'object' || Array.isArray(scopes)) {
+      return [];
+    }
+  }
+  const skills =
+    scopes && typeof scopes === 'object' ? scopes.skills : undefined;
+  if (skills === undefined) {
+    return [
+      path.join(grokHome, 'skills'),
+      path.join(grokHome, 'bundled', 'skills'),
+    ];
+  }
+  if (!skills || typeof skills !== 'object' || Array.isArray(skills)) return [];
+  if (!Array.isArray(skills.roots)) return [];
+  const roots = [];
+  for (const item of skills.roots) {
+    if (typeof item !== 'string' || item.length === 0) continue;
+    roots.push(path.resolve(expandBoxPath(item, home, grokHome)));
+  }
+  return roots;
+}
+
+function expandBoxPath(input, home, grokHome) {
+  const withHome = input
+    .replaceAll('${GROK_HOME}', grokHome)
+    .replaceAll('$GROK_HOME', grokHome);
+  if (withHome === '~') return home;
+  if (withHome.startsWith('~/')) return path.join(home, withHome.slice(2));
+  return withHome;
+}
+
+async function canonicalDir(candidate) {
+  try {
+    return await realpath(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+function spawnBox(command, args, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env,
+      stdio: ['ignore', 'ignore', 'inherit'],
+    });
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (signal) reject(new Error(`knolo-box exited from ${signal}.`));
+      else resolve(code ?? 1);
+    });
+  });
+}
+
+async function loadSkillDir(dirArg) {
+  const dir = path.resolve(process.cwd(), dirArg ?? '.');
+  const raw = await readFile(path.join(dir, 'SKILL.md'));
+  const parsed = parseSkill(raw.toString('utf8'));
+  if (path.basename(dir) !== parsed.name) {
+    throw new Error(
+      `SKILL_NAME: directory ${path.basename(dir)} does not match frontmatter name ${parsed.name}.`
+    );
+  }
+  return { dir, raw, parsed };
+}
+
+function parseSkill(text) {
+  if (!text.startsWith('---\n')) {
+    throw new Error(
+      'SKILL_FRONTMATTER: SKILL.md must start with a frontmatter block.'
+    );
+  }
+  const end = text.indexOf('\n---\n', 4);
+  if (end < 0)
+    throw new Error('SKILL_FRONTMATTER: SKILL.md frontmatter does not close.');
+  const fields = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    if (!line.trim()) continue;
+    const match = /^([a-z]+):[ ]*(.*)$/u.exec(line);
+    if (!match) throw new Error(`SKILL_FRONTMATTER: cannot read "${line}".`);
+    fields[match[1]] = match[2].trim();
+  }
+  const keys = Object.keys(fields).sort();
+  if (keys.join(',') !== 'description,name') {
+    throw new Error('SKILL_FRONTMATTER: use only name and description.');
+  }
+  const nameError = skillNameError(fields.name);
+  if (nameError) throw new Error(nameError);
+  if (!fields.description)
+    throw new Error('SKILL_FRONTMATTER: description is empty.');
+  const described = hostLayoutError(fields.description);
+  if (described) throw new Error(described);
+  const body = text.slice(end + '\n---\n'.length);
+  const guidance = guidanceError(body);
+  if (guidance) throw new Error(guidance);
+  return { name: fields.name, description: fields.description, body };
+}
+
+async function inspectSkill(loaded, queryFlag) {
+  const files = await listKnowledge(loaded.dir);
+  if (files.length === 0) {
+    return {
+      ok: true,
+      name: loaded.parsed.name,
+      receiptId: null,
+      hits: 0,
+      stateRoot: null,
+    };
+  }
+  const built = await buildFromFiles(loaded, files, queryFlag);
+  if (built.hits < 1) {
+    throw new Error(
+      'SKILL_CHECK: the knowledge search returned no hits. Pass --query with words from the source.'
+    );
+  }
+  return {
+    ok: true,
+    name: loaded.parsed.name,
+    receiptId: built.receiptId,
+    hits: built.hits,
+    stateRoot: built.image.stateRoot,
+  };
+}
+
+async function buildSkill(loaded, queryFlag) {
+  const files = await listKnowledge(loaded.dir);
+  return buildFromFiles(loaded, files, queryFlag);
+}
+
+async function buildFromFiles(loaded, files, queryFlag) {
+  const policy = skillPolicy(loaded.parsed.name);
+  const policyBytes = Buffer.from(`${JSON.stringify(policy, null, 2)}\n`);
+  let image = null;
+  let hits = 0;
+  let receiptId = null;
+  if (files.length > 0) {
+    const core = await loadCore();
+    const objects = [];
+    for (const file of files) {
+      const bytes = await readFile(file.full);
+      objects.push({
+        kind: 'chunk',
+        bytes,
+        meta: { namespace: loaded.parsed.name, source: file.source },
+      });
+    }
+    image = core.createKnowledgeImageV5({
+      actor: 'knolo-skill',
+      policy,
+      objects,
+    });
+    const query = queryFlag ?? (await defaultQuery(files));
+    assertQuery(query);
+    const result = core.queryKnowledgeImageV5(
+      image,
+      `FROM chunk SEARCH ${JSON.stringify(query)} LIMIT 5`
+    );
+    hits = result.hits.length;
+    if (hits < 1) {
+      throw new Error(
+        'SKILL_CHECK: the knowledge search returned no hits. Pass --query with words from the source.'
+      );
+    }
+    receiptId = `sr_${createHash('sha256')
+      .update(`${image.stateRoot}\n${result.resultRoot}`)
+      .digest('hex')
+      .slice(0, 24)}`;
+  }
+  const manifest = {
+    format: SKILL_PACK_FORMAT,
+    name: loaded.parsed.name,
+    description: loaded.parsed.description,
+    skillSha256: sha256(loaded.raw),
+    policySha256: sha256(policyBytes),
+    image: image
+      ? { sha256: sha256(image.bytes), stateRoot: image.stateRoot }
+      : null,
+  };
+  const manifestBytes = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+  assertNoHost(manifestBytes.toString('utf8'));
+  assertNoHost(policyBytes.toString('utf8'));
+  return {
+    manifest,
+    manifestBytes,
+    skillBytes: loaded.raw,
+    policyBytes,
+    imageBytes: image ? Buffer.from(image.bytes) : null,
+    image,
+    hits,
+    receiptId,
+  };
+}
+
+function skillPolicy(name) {
+  const principal = `skill:${name}`;
+  return {
+    version: 1,
+    default: 'deny',
+    rules: [
+      { effect: 'allow', action: 'query', principal, kind: 'chunk' },
+      { effect: 'allow', action: 'read', principal, kind: 'chunk' },
+    ],
+  };
+}
+
+async function listKnowledge(dir) {
+  const root = path.join(dir, 'knowledge');
+  const info = await lstat(root);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new Error('SKILL_CHECK: knowledge/ must be a real directory.');
+  }
+  const files = [];
+  async function walk(current) {
+    const entries = await readdir(current, { withFileTypes: true });
+    entries.sort((left, right) => compareText(left.name, right.name));
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const full = path.join(current, entry.name);
+      const stat = await lstat(full);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`SKILL_CHECK: refusing symlink ${entry.name}.`);
+      }
+      if (stat.isDirectory()) {
+        await walk(full);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      if (!EXTENSIONS.has(path.extname(entry.name).toLowerCase())) continue;
+      if (stat.size > MAX_KNOWLEDGE_BYTES) {
+        throw new Error(`SKILL_CHECK: ${entry.name} is larger than 1 MiB.`);
+      }
+      const source = path.relative(root, full).split(path.sep).join('/');
+      files.push({ full, source });
+    }
+  }
+  await walk(root);
+  if (files.length > MAX_KNOWLEDGE_FILES) {
+    throw new Error(
+      `SKILL_CHECK: a skill can contain ${MAX_KNOWLEDGE_FILES} knowledge files.`
+    );
+  }
+  files.sort((left, right) => compareText(left.source, right.source));
+  return files;
+}
+
+async function defaultQuery(files) {
+  const text = (await readFile(files[0].full)).toString('utf8');
+  const words = text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((word) => word.length >= 3)
+    .slice(0, 3);
+  if (words.length === 0) {
+    throw new Error(
+      'SKILL_CHECK: pass --query. The first knowledge file has no words.'
+    );
+  }
+  return words.join(' ');
+}
+
+function assertQuery(query) {
+  if (
+    typeof query !== 'string' ||
+    !/^[\p{L}\p{N} ]+$/u.test(query) ||
+    !query.trim()
+  ) {
+    throw new Error('SKILL_CHECK: --query must be words separated by spaces.');
+  }
+}
+
+async function writePack(out, built) {
+  await writePackFiles(out, {
+    manifestBytes: built.manifestBytes,
+    skillBytes: built.skillBytes,
+    policyBytes: built.policyBytes,
+    imageBytes: built.imageBytes,
+  });
+}
+
+async function writePackFiles(out, pack) {
+  await mkdir(out, { recursive: true });
+  await writeFile(path.join(out, 'manifest.json'), pack.manifestBytes, {
+    mode: 0o644,
+  });
+  await writeFile(path.join(out, 'SKILL.md'), pack.skillBytes, { mode: 0o644 });
+  await writeFile(path.join(out, 'policy.json'), pack.policyBytes, {
+    mode: 0o644,
+  });
+  if (pack.imageBytes) {
+    await writeFile(path.join(out, 'knowledge.v5'), pack.imageBytes, {
+      mode: 0o644,
+    });
+  }
+}
+
+async function readVerifiedPack(packDir) {
+  let manifestBytes;
+  let skillBytes;
+  let policyBytes;
+  try {
+    manifestBytes = await readFile(path.join(packDir, 'manifest.json'));
+    skillBytes = await readFile(path.join(packDir, 'SKILL.md'));
+    policyBytes = await readFile(path.join(packDir, 'policy.json'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      const missing = new Error(`SKILL_HUB: no skill pack at ${packDir}.`);
+      missing.code = 'ENOENT';
+      throw missing;
+    }
+    throw error;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestBytes.toString('utf8'));
+  } catch {
+    throw new Error('SKILL_PIN: manifest.json is not valid JSON.');
+  }
+  if (!manifest || manifest.format !== SKILL_PACK_FORMAT) {
+    throw new Error('SKILL_PIN: manifest format is not a Knolo skill pack.');
+  }
+  const nameError = skillNameError(manifest.name);
+  if (nameError) throw new Error(nameError);
+  if (sha256(skillBytes) !== manifest.skillSha256) {
+    throw new Error('SKILL_PIN: SKILL.md does not match its SHA-256 pin.');
+  }
+  if (sha256(policyBytes) !== manifest.policySha256) {
+    throw new Error('SKILL_PIN: policy.json does not match its SHA-256 pin.');
+  }
+  const parsed = parseSkill(skillBytes.toString('utf8'));
+  if (
+    parsed.name !== manifest.name ||
+    parsed.description !== manifest.description
+  ) {
+    throw new Error(
+      'SKILL_PIN: SKILL.md does not match the manifest name and description.'
+    );
+  }
+  const policy = parsePolicy(policyBytes);
+  let imageBytes = null;
+  if (manifest.image) {
+    try {
+      imageBytes = await readFile(path.join(packDir, 'knowledge.v5'));
+    } catch (error) {
+      if (error && error.code === 'ENOENT') {
+        throw new Error('SKILL_PIN: knowledge.v5 is missing.');
+      }
+      throw error;
+    }
+    if (sha256(imageBytes) !== manifest.image.sha256) {
+      throw new Error(
+        'SKILL_PIN: knowledge.v5 does not match its SHA-256 pin.'
+      );
+    }
+    const core = await loadCore();
+    let opened;
+    try {
+      opened = core.mountKnowledgeImageV5(imageBytes);
+    } catch {
+      throw new Error('SKILL_PIN: knowledge.v5 is not a V5 Knowledge Image.');
+    }
+    if (opened.stateRoot !== manifest.image.stateRoot) {
+      throw new Error('SKILL_PIN: knowledge.v5 does not match its state root.');
+    }
+    let policyRoot;
+    try {
+      policyRoot = core.knowledgePolicyRootV5(policy);
+    } catch {
+      throw new Error('SKILL_PIN: policy.json is not a V5 policy.');
+    }
+    if (opened.commit.policyRoot !== policyRoot) {
+      throw new Error(
+        'SKILL_PIN: policy.json does not match the image policy root.'
+      );
+    }
+  } else {
+    try {
+      await lstat(path.join(packDir, 'knowledge.v5'));
+      throw new Error(
+        'SKILL_PIN: knowledge.v5 is present but the manifest has no image pin.'
+      );
+    } catch (error) {
+      if (!(error && error.code === 'ENOENT')) throw error;
+    }
+  }
+  assertNoHost(manifestBytes.toString('utf8'));
+  return { manifest, manifestBytes, skillBytes, policyBytes, imageBytes };
+}
+
+function packSummary(built, out) {
+  return {
+    ok: true,
+    name: built.manifest.name,
+    out,
+    skillSha256: built.manifest.skillSha256,
+    image: built.manifest.image,
+    receiptId: built.receiptId,
+  };
+}
+
+function sameImage(left, right) {
+  if (left === null || right === null) return left === right;
+  return left.sha256 === right.sha256 && left.stateRoot === right.stateRoot;
+}
+
+function assertNoHost(text) {
+  if (ABSOLUTE_PATH.test(text) || text.includes('managed-skills')) {
+    throw new Error(
+      'SKILL_PACK: the pack names a home directory or a host layout.'
+    );
+  }
+}
+
+function compareText(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+async function rejectHostPath(target) {
+  const home = process.env.HOME;
+  if (home && (target === home || target.startsWith(`${home}${path.sep}`))) {
+    // A user can install into a directory under their home. The pack itself
+    // must not record that path. This check only rejects the home directory
+    // as the catalog or install root.
+    if (target === home) {
+      throw new Error(
+        'SKILL_PACK: pass a directory inside the destination, not the home directory itself.'
+      );
+    }
+  }
+}
+
+function parsePolicy(policyBytes) {
+  try {
+    const policy = JSON.parse(policyBytes.toString('utf8'));
+    if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+      throw new Error('not an object');
+    }
+    return policy;
+  } catch {
+    throw new Error('SKILL_PIN: policy.json is not valid JSON.');
+  }
+}
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+async function loadCore() {
+  const candidates = [
+    path.resolve(__dirname, '../../core/dist/index.js'),
+    '@knolo/core',
+  ];
+  for (const candidate of candidates) {
+    try {
+      const href = candidate.startsWith('@')
+        ? candidate
+        : pathToFileURL(candidate).href;
+      const loaded = await import(href);
+      if (
+        loaded.createKnowledgeImageV5 &&
+        loaded.queryKnowledgeImageV5 &&
+        loaded.mountKnowledgeImageV5 &&
+        loaded.knowledgePolicyRootV5
+      ) {
+        return loaded;
+      }
+    } catch {
+      // Try the next candidate.
+    }
+  }
+  throw new Error('Could not load @knolo/core. Build packages/core first.');
+}
+
+const SKILL_ARCHIVE_FORMAT = 'knolo-skill-archive-v1';
+const ARCHIVE_SECTIONS = ['manifest.json', 'SKILL.md', 'policy.json', 'knowledge.v5'];
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+function resolveSkillRegistry(requested, stored) {
+  const storedUrl = normalizeRegistryUrl(stored);
+  if (!requested) return storedUrl;
+  const requestedUrl = normalizeRegistryUrl(requested);
+  if (requestedUrl !== storedUrl) {
+    throw new Error(
+      `Stored credentials belong to ${storedUrl}; refusing to send them to ${requestedUrl}. Log in to the requested registry first.`
+    );
+  }
+  return requestedUrl;
+}
+
+export function encodeSkillArchive(pack) {
+  const sections = [
+    ['manifest.json', Buffer.from(pack.manifestBytes)],
+    ['SKILL.md', Buffer.from(pack.skillBytes)],
+    ['policy.json', Buffer.from(pack.policyBytes)],
+    ['knowledge.v5', Buffer.from(pack.imageBytes ?? Buffer.alloc(0))],
+  ];
+  const parts = [Buffer.from(`${SKILL_ARCHIVE_FORMAT}\n`)];
+  for (const [name, bytes] of sections) {
+    parts.push(Buffer.from(`${name} ${bytes.length}\n`));
+    if (bytes.length) parts.push(bytes);
+  }
+  return Buffer.concat(parts);
+}
+
+export function decodeSkillArchive(bytes) {
+  const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  let offset = 0;
+  const header = readArchiveLine(buffer, offset);
+  offset = header.next;
+  if (header.line !== SKILL_ARCHIVE_FORMAT) {
+    throw new Error('SKILL_PIN: skill archive format is not a Knolo skill pack.');
+  }
+  const files = {};
+  for (const name of ARCHIVE_SECTIONS) {
+    const section = readArchiveSection(buffer, offset, name);
+    files[name] = section.body;
+    offset = section.next;
+  }
+  if (offset !== buffer.length) {
+    throw new Error('SKILL_PIN: skill archive has trailing bytes.');
+  }
+  const image = files['knowledge.v5'];
+  return {
+    manifestBytes: files['manifest.json'],
+    skillBytes: files['SKILL.md'],
+    policyBytes: files['policy.json'],
+    imageBytes: image.length ? image : null,
+  };
+}
+
+export async function publishSkillToRegistry(
+  packDir,
+  { fetchImpl = globalThis.fetch, registry, token }
+) {
+  const pack = await readVerifiedPack(packDir);
+  const archive = encodeSkillArchive(pack);
+  const archiveSha256 = sha256(archive);
+  const auth = { Authorization: `Bearer ${token}` };
+  await getJson(registryApiUrl(registry, ['account']), {
+    fetchImpl,
+    headers: auth,
+  });
+  const grant = await postJson(
+    registryApiUrl(registry, ['skills', 'uploads']),
+    { sha256: archiveSha256, contentLength: archive.length },
+    { fetchImpl, headers: auth }
+  );
+  const expected = `sha256/${archiveSha256}.knolo-skill`;
+  if (grant?.pathname !== expected) {
+    throw new Error(`SKILL_HUB: upload pathname is not locked to ${expected}.`);
+  }
+  let blobUrl;
+  if (grant.reused && typeof grant.artifact?.url === 'string') {
+    blobUrl = assertSkillBlobUrl(grant.artifact.url, archiveSha256);
+  } else {
+    const putUrl = assertSkillPutUrl(grant.upload?.url);
+    const uploaded = await putBytes(putUrl, archive, {
+      fetchImpl,
+      headers: blobPutHeaders(grant.upload?.headers, archive.length),
+    });
+    blobUrl = assertSkillBlobUrl(uploaded.url, archiveSha256);
+  }
+  let listed;
+  try {
+    listed = await postJson(
+      registryApiUrl(registry, ['skills']),
+      { archiveSha256, url: blobUrl, sizeBytes: archive.length },
+      { fetchImpl, headers: auth }
+    );
+  } catch (error) {
+    if (error?.code === 'pin_conflict' || error?.status === 409) {
+      throw new Error(
+        `SKILL_HUB: ${pack.manifest.name} is already in the catalog with a different pin.`
+      );
+    }
+    throw error;
+  }
+  if (typeof listed?.publisher !== 'string' || !listed.publisher) {
+    throw new Error('SKILL_HUB: the catalog did not name a publisher.');
+  }
+  return {
+    ok: true,
+    name: `${listed.publisher}/${pack.manifest.name}`,
+    hub: registry,
+    unchanged: Boolean(listed.unchanged),
+    skillSha256: pack.manifest.skillSha256,
+    image: pack.manifest.image,
+  };
+}
+
+export async function installSkillFromRegistry(
+  id,
+  destRoot,
+  { fetchImpl = globalThis.fetch, registry }
+) {
+  const { publisher, name } = parseSkillId(id);
+  const listed = await getJson(
+    registryApiUrl(registry, ['skills', publisher, name]),
+    { fetchImpl }
+  );
+  if (listed?.publisher !== publisher || listed?.slug !== name) {
+    throw new Error('SKILL_HUB: catalog id does not match the manifest.');
+  }
+  const url = assertSkillBlobUrl(listed.url, listed.archiveSha256);
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('This Node runtime does not provide fetch.');
+  }
+  const response = await fetchImpl(url, { method: 'GET', redirect: 'follow' });
+  if (!response?.ok) {
+    throw new Error(
+      `SKILL_HUB: skill pack download failed with HTTP ${response?.status ?? 'error'}.`
+    );
+  }
+  assertSkillBlobUrl(response.url || url, listed.archiveSha256);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (sha256(bytes) !== listed.archiveSha256) {
+    throw new Error(
+      'SKILL_PIN: downloaded skill pack does not match its SHA-256 pin.'
+    );
+  }
+  const decoded = decodeSkillArchive(bytes);
+  const parent = await mkdtemp(path.join(tmpdir(), 'knolo-skill-'));
+  try {
+    const temp = path.join(parent, name);
+    await writePackFiles(temp, decoded);
+    const pack = await readVerifiedPack(temp);
+    if (
+      pack.manifest.name !== name ||
+      pack.manifest.skillSha256 !== listed.skillSha256 ||
+      pack.manifest.policySha256 !== listed.policySha256 ||
+      !sameImage(pack.manifest.image, listed.image ?? null)
+    ) {
+      throw new Error(
+        'SKILL_PIN: downloaded skill pack does not match the catalog pin.'
+      );
+    }
+    const dest = path.resolve(destRoot, pack.manifest.name);
+    await rejectHostPath(dest);
+    try {
+      await lstat(dest);
+      throw new Error(`SKILL_PACK: refusing to overwrite ${dest}.`);
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') throw error;
+    }
+    await writePackFiles(dest, pack);
+    return { ok: true, name: `${publisher}/${name}`, dir: dest };
+  } finally {
+    await rm(parent, { recursive: true, force: true });
+  }
+}
+
+function parseSkillId(id) {
+  if (typeof id !== 'string') {
+    throw new Error('SKILL_HUB: pass publisher/name.');
+  }
+  const slash = id.indexOf('/');
+  if (slash <= 0 || slash !== id.lastIndexOf('/')) {
+    throw new Error('SKILL_HUB: pass publisher/name.');
+  }
+  const publisher = id.slice(0, slash);
+  const name = id.slice(slash + 1);
+  if (skillNameError(publisher) || skillNameError(name)) {
+    throw new Error('SKILL_HUB: pass publisher/name.');
+  }
+  return { publisher, name };
+}
+
+function assertSkillBlobUrl(value, digest) {
+  if (typeof digest !== 'string' || !SHA256_HEX.test(digest)) {
+    throw new Error('SKILL_HUB: archive pin is not a SHA-256.');
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('SKILL_HUB: skill pack URL is invalid.');
+  }
+  if (
+    url.protocol !== 'https:' ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname.includes('..') ||
+    url.pathname.includes('\\')
+  ) {
+    throw new Error('SKILL_HUB: skill pack URL must be a public HTTPS Blob URL.');
+  }
+  const host = url.hostname.toLowerCase();
+  const blobHost =
+    host === 'blob.vercel-storage.com' || host.endsWith('.blob.vercel-storage.com');
+  const privateHost =
+    host === 'private.blob.vercel-storage.com' ||
+    host.endsWith('.private.blob.vercel-storage.com') ||
+    host.includes('.private.');
+  if (!blobHost || privateHost) {
+    throw new Error('SKILL_HUB: skill pack URL must be a public Vercel Blob URL.');
+  }
+  const pathname = `sha256/${digest}.knolo-skill`;
+  if (url.pathname !== `/${pathname}` && !url.pathname.endsWith(`/${pathname}`)) {
+    throw new Error(`SKILL_HUB: skill pack URL is not locked to ${pathname}.`);
+  }
+  return url.toString();
+}
+
+function assertSkillPutUrl(value) {
+  if (typeof value !== 'string' || !value) {
+    throw new Error('SKILL_HUB: upload URL is missing.');
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('SKILL_HUB: upload URL is invalid.');
+  }
+  if (url.protocol !== 'https:') {
+    throw new Error('SKILL_HUB: upload URL must use HTTPS.');
+  }
+  const host = url.hostname.toLowerCase().replace(/\.$/, '');
+  if (
+    host === 'localhost' ||
+    host.endsWith('.localhost') ||
+    host.endsWith('.local') ||
+    host.includes('.private.') ||
+    host === 'private.blob.vercel-storage.com' ||
+    host.endsWith('.private.blob.vercel-storage.com') ||
+    isPrivateSkillHost(host)
+  ) {
+    throw new Error('SKILL_HUB: refusing a private upload URL.');
+  }
+  return url.toString();
+}
+
+function isPrivateSkillHost(host) {
+  if (host === '0.0.0.0' || host === '127.0.0.1' || host === '::1') return true;
+  const octets = host.split('.').map(Number);
+  if (
+    octets.length !== 4 ||
+    octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)
+  ) {
+    return false;
+  }
+  const [first, second] = octets;
+  return (
+    first === 10 ||
+    first === 127 ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168)
+  );
+}
+
+function blobPutHeaders(headers, length) {
+  const next = { 'content-type': 'application/octet-stream' };
+  if (headers && typeof headers === 'object') {
+    for (const [key, value] of Object.entries(headers)) {
+      if (key.toLowerCase() === 'authorization') continue;
+      if (typeof value === 'string') next[key.toLowerCase()] = value;
+    }
+  }
+  next['content-length'] = String(length);
+  return next;
+}
+
+function readArchiveLine(bytes, offset) {
+  const newline = bytes.indexOf(0x0a, offset);
+  if (newline < 0) throw new Error('SKILL_PIN: skill archive is truncated.');
+  let line;
+  try {
+    line = new TextDecoder('utf8', { fatal: true }).decode(
+      bytes.subarray(offset, newline)
+    );
+  } catch {
+    throw new Error('SKILL_PIN: skill archive header is not text.');
+  }
+  if (line.includes('\u0000')) {
+    throw new Error('SKILL_PIN: skill archive header is not text.');
+  }
+  return { line, next: newline + 1 };
+}
+
+function readArchiveSection(bytes, offset, name) {
+  const header = readArchiveLine(bytes, offset);
+  const match = /^([A-Za-z0-9.]+) ([0-9]+)$/u.exec(header.line);
+  if (!match || match[1] !== name || String(Number(match[2])) !== match[2]) {
+    throw new Error(`SKILL_PIN: skill archive is missing ${name}.`);
+  }
+  const length = Number(match[2]);
+  if (!Number.isSafeInteger(length) || header.next + length > bytes.length) {
+    throw new Error('SKILL_PIN: skill archive is truncated.');
+  }
+  return {
+    body: bytes.subarray(header.next, header.next + length),
+    next: header.next + length,
+  };
+}
+
+export async function listSkills(flags = {}) {
+  const print = flags.print ?? console.log;
+  const registry = resolveRegistryUrl({
+    value: flags.registry,
+    env: flags.env ?? process.env,
+  });
+  const body = await getJson(String(registryApiUrl(registry, ['skills'])), {
+    fetchImpl: flags.fetchImpl ?? globalThis.fetch,
+  });
+  if (!body || !Array.isArray(body.skills)) {
+    throw new Error('SKILL_HUB: skill catalog response is invalid.');
+  }
+  const skills = body.skills.map(catalogSkill);
+  if (flags.json) print(JSON.stringify(skills, null, 2));
+  else if (skills.length === 0) print('no skills');
+  else {
+    for (const skill of skills) print(`${skill.publisher}/${skill.slug}`);
+  }
+  return { registry, skills };
+}
+
+export async function searchSkills(query, flags = {}) {
+  const print = flags.print ?? console.log;
+  const text = typeof query === 'string' ? query.trim() : '';
+  if (!text) throw new Error('SKILL_HUB: pass a search query.');
+  const registry = resolveRegistryUrl({
+    value: flags.registry,
+    env: flags.env ?? process.env,
+  });
+  const body = await getJson(String(registryApiUrl(registry, ['skills'])), {
+    fetchImpl: flags.fetchImpl ?? globalThis.fetch,
+  });
+  if (!body || !Array.isArray(body.skills)) {
+    throw new Error('SKILL_HUB: skill catalog response is invalid.');
+  }
+  const terms = text.toLowerCase().split(/\s+/u);
+  const skills = body.skills
+    .filter((skill) => skillMatches(skill, terms))
+    .map(catalogSkill);
+  if (flags.json) print(JSON.stringify({ skills }, null, 2));
+  else if (skills.length === 0) print('no skills');
+  else {
+    for (const skill of skills) {
+      print(`${skill.publisher}/${skill.slug}`);
+      print(`  ${skill.description}`);
+    }
+  }
+  return { registry, skills };
+}
+
+export async function infoSkill(id, flags = {}) {
+  const print = flags.print ?? console.log;
+  const { publisher, name } = parseSkillId(id);
+  const registry = resolveRegistryUrl({
+    value: flags.registry,
+    env: flags.env ?? process.env,
+  });
+  let body;
+  try {
+    body = await getJson(
+      String(registryApiUrl(registry, ['skills', publisher, name])),
+      { fetchImpl: flags.fetchImpl ?? globalThis.fetch }
+    );
+  } catch (error) {
+    if (error?.status === 404) {
+      throw new Error(`SKILL_HUB: ${publisher}/${name} was not found.`);
+    }
+    throw error;
+  }
+  if (flags.json) print(JSON.stringify(body, null, 2));
+  else {
+    print(`name             ${publisher}/${name}`);
+    print(`description      ${body?.description ?? ''}`);
+    print(`skill sha256     ${body?.skillSha256 ?? ''}`);
+    print(`policy sha256    ${body?.policySha256 ?? ''}`);
+    if (body?.image) {
+      print(`image sha256     ${body.image.sha256 ?? ''}`);
+      print(`state root       ${body.image.stateRoot ?? ''}`);
+    }
+    print(`archive sha256   ${body?.archiveSha256 ?? ''}`);
+    print(`size             ${body?.sizeBytes ?? ''}`);
+    print(`url              ${body?.url ?? ''}`);
+  }
+  return { registry, skill: body };
+}
+
+function skillMatches(skill, terms) {
+  const haystack = [skill?.name, skill?.slug, skill?.publisher, skill?.description]
+    .filter((value) => typeof value === 'string')
+    .join('\n')
+    .toLowerCase();
+  return terms.every((term) => haystack.includes(term));
+}
+
+function catalogSkill(skill) {
+  return {
+    name: skill?.name,
+    publisher: skill?.publisher,
+    slug: skill?.slug,
+    description: skill?.description,
+    skillSha256: skill?.skillSha256,
+    policySha256: skill?.policySha256,
+    image: skill?.image ?? null,
+  };
+}
+
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') flags.json = true;
+    else if (arg === '--help' || arg === '-h') flags.help = true;
+    else if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error(`Missing value for --${key}`);
+      }
+      flags[key] = value;
+      index += 1;
+    } else positionals.push(arg);
+  }
+  return { positionals, flags };
+}