@knolo/cli 6.2.1 → 6.2.2

package/README.md

@@ -12,8 +12,9 @@ the format is still draft and compressed object/event images require a VQF-aware
 reader.
 
 `knolo compose`, `knolo attest`, and `knolo verify-attestation` cite local
-Knowledge Images and write an attestation sidecar. `@knolo/cli` `6.2.0`
-depends on `@knolo/core` `^6.2.0`. They do not fetch Hub. Verification
+Knowledge Images and write an attestation sidecar. This tree's `@knolo/cli`
+package file is `6.2.2` and depends on `@knolo/core` `^6.2.0`. npm
+`latest` is `6.2.1` until `6.2.2` is published. They do not fetch Hub. Verification
 recomputes `compositionRoot` and checks bundled excerpt bytes. A keyring key
 must fall inside `notBefore`, `notAfter`, and `revokedAt`. `used` means a
 query or evaluation ran. It does not mean `SATISFIED`, and it does not mean a
@@ -135,15 +136,22 @@ Successful installs are cached by SHA-256 and recorded in
 ## Skill packs
 
 `knolo skill` is separate from the Hub commands above. `knolo publish` still
-uploads a `.knolo` knowledge pack to `https://hub.knolo.dev`. A skill pack
-uses a directory you pass with `--hub`.
+uploads a `.knolo` knowledge pack to `https://hub.knolo.dev`. `knolo skill
+publish` sends a skill pack to that same hub. `--hub <dir>` remains a local
+directory for an offline catalog.
 
 ```bash
 knolo skill init refund-policy
 knolo skill check refund-policy
 knolo skill pack refund-policy --out dist/refund-policy.knolo-skill
+knolo skill publish dist/refund-policy.knolo-skill
+knolo skill install acme/refund-policy
 knolo skill publish dist/refund-policy.knolo-skill --hub ./catalog
 knolo skill install refund-policy --hub ./catalog --dir ./skills
+knolo skill search refund
+knolo skill list
+knolo skill info acme/refund-policy
+knolo setup --root <dir> --agent <id> --auto-rebuild
 ```
 
 `init` writes `SKILL.md` and an empty `knowledge/` directory. `check` reads
@@ -156,15 +164,40 @@ does not mean a claim is proven.
 the image state root. It does not store a home directory or a computer
 layout. The same files produce the same pins.
 
-`publish` copies the pack into `--hub/<name>`. The same pin can be published
-again. A different pin is refused, and the catalog copy stays as it was.
-`install` checks the pin before it writes. A mismatch writes nothing. The
-catalog directory name must match the manifest. `SKILL.md` must match that
-name and description, and `policy.json` must match the image policy root.
-The files land only in `--dir/<name>`.
-
-The directory catalog stores packs. It does not run a model, and it does not
-answer questions. It is not `https://hub.knolo.dev`.
+`publish` without `--hub` uses the stored `kno_…` token. The same pin can be
+published again. A different pin is refused, and the catalog copy stays as
+it was. `--hub <dir>` copies the pack into `<dir>/<name>` instead.
+`install <publisher>/<name>` downloads one pack from the hub. It does not
+read a stored token, and the download does not send one. `install` with
+`--hub` or `--pack` reads a local directory. Either install checks the pin
+before it writes. A mismatch writes nothing. The catalog id must match the
+manifest. `SKILL.md` must match that name and description, and `policy.json`
+must match the image policy root. The files land in `--dir/<name>`, or in
+`~/.knolo/skills/<name>` when `--dir` is omitted. When that folder is a
+skills root in `~/.knolo/box/box.config.json` and `knolo-box` is on `PATH`,
+install runs one `knolo-box build`. A root written as `~/...` or
+`$GROK_HOME/...` counts, and a skills scope left out of the file uses the
+default `~/.grok` skill folders. A folder outside those roots is still
+written, and install prints that it was not indexed. A failed build leaves
+the installed files in place and prints that the install was not indexed.
+`search`, `list`, and `info` read the public skill catalog. `list` prints
+every `publisher/name`. `check` reads a source directory that contains
+`knowledge/`. An installed pack contains `knowledge.v5` instead.
+
+`knolo setup` runs `knolo-box init --tolerant` and then `knolo-box build`
+when `knolo-box` is on `PATH`. It scans `~/.grok` when that directory
+exists, plus every `--root`. It does not require `~/.grok`. It always
+includes `~/.knolo/skills`. An existing `~/.knolo/box/box.config.json` is
+kept and rebuilt. `--reset` replaces it. `--agent` sets the caller name.
+`--auto-rebuild` turns on a rebuild at the next search. Those flags require
+`--reset` when a config file is already there. Setup does not prompt,
+install a pack, or call the hub. A missing `knolo-box` is one line, and
+setup still exits 0. It prints the config path, `knolo skill install <publisher>/<name>`,
+and `knolo-box mcp --config <path>`. The install path, auth, trust, and
+version rules are in [Community install](../../docs/hub/COMMUNITY.md). This
+page does not restate that contract. The hub stores packs. It does not run
+a model, and it does not answer questions. `--hub` and `--registry` cannot
+be combined.
 
 ---
 
@@ -326,7 +359,7 @@ This ensures:
 ## 🗺 Roadmap
 
 The active roadmap is maintained in [`../../docs/ROADMAP.md`](../../docs/ROADMAP.md).
-The current release is `6.2.0`. It preserves the V4 CLI, keeps V5 verification,
+The published npm release is `6.2.1`. This package file is `6.2.2`. It preserves the V4 CLI, keeps V5 verification,
 migration, diagnostics, and read-only Studio management, and adds offline
 composition, attestation, and `knolo cortex`. Cortex verification does not
 mean an answer is true.

package/bin/knolo.mjs

@@ -79,6 +79,7 @@ const SUBCOMMANDS = new Set([
   'cortex',
   'flight',
   'skill',
+  'setup',
 ]);
 const ICP_SUBCOMMANDS = new Set([
   'init',
@@ -179,6 +180,7 @@ Commands:
   cortex                  Bounded evidence retrieval with a verifiable trace
   flight                  Pack a flight-events-1 document into a V5 Knowledge Image
   skill                   Create and share a Knolo skill pack
+  setup                   Prepare a local index and print the hub next steps
   icp                     Scaffold and operate an ICP-native knowledge canister
 
 Global options:
@@ -219,22 +221,39 @@ function printCommandHelp(command) {
     attest: 'Usage: knolo attest <create|verify> [options]\n\n  knolo attest create --composition composition/composition.json --subject composition --statement mount|used|cited --out attestation.json [--sign-key key.json --principal <id> --key-id <id> --issued-at <ms> --expires-at <ms>]\n  knolo attest verify attestation.json [--composition composition.json] [--public-key key.json] [--now <ms>] [--content-only]\n\nstatement used means a query or KAR evaluation ran. It does not mean the claim is true or false. Hub attested: true is unrelated. Signing uses the supplied times. The CLI does not read the clock.',
     cortex: 'Usage: knolo cortex <find|ask|explain|verify> [options]\n\nBounded evidence retrieval. The CLI does not call a model.\n\n  knolo cortex find <image> --question "..." [--top-k 100] --out candidates.json\n  knolo cortex ask <image> --question "..." [--graph file] [--plan plan.json] [--mode find_relevant] --out answer.cortex.json\n  knolo cortex explain answer.cortex.json\n  knolo cortex verify --image <image> --answer answer.cortex.json [--graph file]\n\nVerification recomputes the trace roots. It does not mean the answer is true. A KAR status of SATISFIED means evidence requirements were met. It does not mean a claim is proven.',
     flight: 'Usage: knolo flight ingest --events <events.json> --log <file> --out <image.knolo> [--json]\n\nPacks a flight-events-1 document into a V5 Knowledge Image. The command hashes --log and writes nothing when the hash or byte length differs. It does not decode the log. log.format is ulog, dataflash, or rosbag2. A later KAR status of SATISFIED means evidence requirements were met. It does not mean a flight was safe, legal, or compliant.',
-    skill: `Usage: knolo skill <init|check|pack|publish|install>
+    setup: `Usage: knolo setup [--registry <url>] [--root <dir>] [--agent <id>] [--auto-rebuild] [--reset] [--skills <path>] [--managed-skills <path>] [--memory <path>] [--transcripts <path>]
+
+Resolves the hub the same way as the other hub commands.
+Scans ~/.grok when that directory exists, plus every --root.
+Runs knolo-box init --tolerant, then knolo-box build --config.
+Keeps an existing config and rebuilds it. Pass --reset to replace it.
+Always includes ~/.knolo/skills as a skills root.
+Pass --agent to set the caller name. Pass --auto-rebuild to rebuild on the next search.
+Does not prompt. Does not install a pack or call the hub.
+A missing knolo-box is printed, and setup still exits 0.
+When more than one skill folder matches, pass --skills or --managed-skills.`,
+    skill: `Usage: knolo skill <init|check|pack|publish|install|search|info|list>
 
   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 <name> --hub <dir> --dir <path> [--json]
-  knolo skill install --pack <pack> --dir <path> [--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]
 
 Creates a skill pack for the host agent. Knolo does not call a model.
 A receipt is an integrity check. It does not mean a claim is proven.
 SATISFIED means the evidence requirements were met.
-publish copies the pack into a directory catalog. install checks the pin
-and writes only into --dir. A pin mismatch writes nothing.
-The catalog stores packs and does not answer questions.
-It is not https://hub.knolo.dev.`,
+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. list prints every publisher/name from the public catalog.
+The hub stores packs and does not answer questions.`,
     'verify-attestation': 'Usage: knolo verify-attestation <attestation.json> [--composition composition.json] [--public-key key.json] [--keyring keyring.json] [--now <ms>] [--content-only]\n\nSame check as knolo attest verify. A bad signature exits 1 even when the content root matches. --content-only checks the content root and ignores the envelope. statement used is not a truth verdict. Hub attested: true is unrelated.',
     icp: 'Usage: knolo icp <command> [options]',
     'semantic:index':
@@ -1901,6 +1920,10 @@ async function main() {
         const { runSkillCli } = await import('./skill.mjs');
         return runSkillCli(commandArgs);
       }
+      if (command === 'setup') {
+        const { runKnoloSetup } = await import('./setup.mjs');
+        return runKnoloSetup(commandArgs);
+      }
       if (command === 'init') return await cmdInit();
       if (command === 'add') return await cmdAdd(commandArgs);
       if (command === 'search') return await runHubSearch(commandArgs);

package/bin/setup.mjs

@@ -0,0 +1,260 @@
+/**
+ * knolo setup
+ *
+ * Writes a local box config and builds it when knolo-box is on PATH.
+ * It does not install a pack, call a hub write API, or open a network
+ * connection. A missing knolo-box is one line, and setup still exits 0.
+ */
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, readFile, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { resolveRegistryUrl } from './registry/config.mjs';
+
+export const SETUP_HELP = `Usage: knolo setup [--registry <url>] [--root <dir>] [--agent <id>] [--auto-rebuild] [--reset] [--skills <path>] [--managed-skills <path>] [--memory <path>] [--transcripts <path>]
+
+Resolves the hub the same way as the other hub commands.
+Scans ~/.grok when that directory exists, plus every --root.
+Runs knolo-box init --tolerant, then knolo-box build --config.
+Keeps an existing config and rebuilds it. Pass --reset to replace it.
+Always includes ~/.knolo/skills as a skills root.
+Pass --agent to set the caller name. Pass --auto-rebuild to rebuild on the next search.
+Does not prompt. Does not install a pack or call the hub.
+A missing knolo-box is printed, and setup still exits 0.
+When more than one skill folder matches, pass --skills or --managed-skills.`;
+
+export async function runKnoloSetup(
+  args,
+  {
+    env = process.env,
+    homeDir = homedir(),
+    spawnImpl = spawnBox,
+    print = console.log,
+    printError = console.error,
+  } = {}
+) {
+  const parsed = parseSetupArgs(args);
+  if (parsed.help) {
+    print(SETUP_HELP);
+    return { ok: true, help: true };
+  }
+  const registry = resolveRegistryUrl({ value: parsed.registry, env });
+  const box = await findOnPath('knolo-box', env.PATH);
+  const configPath = path.resolve(
+    path.join(homeDir, '.knolo', 'box', 'box.config.json')
+  );
+  const hubSkills = path.resolve(path.join(homeDir, '.knolo', 'skills'));
+  const grokHome = resolveGrokHome(env, homeDir);
+  const roots = [];
+  if (await directoryExists(grokHome)) roots.push(grokHome);
+  for (const root of parsed.roots) roots.push(root);
+
+  const existing = await fileExists(configPath);
+  if (existing && !parsed.reset && requestsNewConfig(parsed)) {
+    throw new Error(
+      `Config already exists: ${configPath}. Pass --reset to replace it.`
+    );
+  }
+  const replace = !existing || parsed.reset === true;
+
+  let built = false;
+  if (!box) {
+    printError('knolo-box is not on PATH. Skipping the local index.');
+    if (existing && !parsed.reset) printError('Kept the existing config.');
+  } else if (!replace) {
+    const buildStatus = await spawnImpl(
+      box,
+      ['build', '--config', configPath],
+      { env }
+    );
+    if (buildStatus !== 0) {
+      throw new Error(`knolo-box build exited with status ${buildStatus}.`);
+    }
+    built = true;
+    printError('Kept the existing config.');
+  } else {
+    const initArgs = [
+      'init',
+      '--config',
+      configPath,
+      '--tolerant',
+      '--hub-skills',
+      hubSkills,
+    ];
+    for (const root of roots) initArgs.push('--root', root);
+    if (parsed.agent) initArgs.push('--agent', parsed.agent);
+    if (parsed.autoRebuild) initArgs.push('--auto-rebuild');
+    if (parsed.skills) initArgs.push('--skills', parsed.skills);
+    if (parsed.managedSkills) initArgs.push('--managed-skills', parsed.managedSkills);
+    if (parsed.memory) initArgs.push('--memory', parsed.memory);
+    if (parsed.transcripts) initArgs.push('--transcripts', parsed.transcripts);
+    const initStatus = await spawnImpl(box, initArgs, { env });
+    if (initStatus !== 0) {
+      throw new Error(`knolo-box init exited with status ${initStatus}.`);
+    }
+    const buildStatus = await spawnImpl(
+      box,
+      ['build', '--config', configPath],
+      { env }
+    );
+    if (buildStatus !== 0) {
+      throw new Error(`knolo-box build exited with status ${buildStatus}.`);
+    }
+    built = true;
+    if ((await skillRootsBesideHub(configPath, hubSkills)).length === 0) {
+      printError('No Grok skill folder was found.');
+    }
+  }
+
+  print(`Config: ${configPath}`);
+  print('First install: knolo skill install <publisher>/<name>');
+  print(`Connector: knolo-box mcp --config ${configPath}`);
+  print(`Publish needs a token from ${registry}/dashboard/tokens.`);
+  return { ok: true, registry, built, configPath };
+}
+
+export function resolveGrokHome(env, homeDir) {
+  const configured = typeof env.GROK_HOME === 'string' ? env.GROK_HOME.trim() : '';
+  const raw = configured || path.join(homeDir, '.grok');
+  if (raw === '~') return homeDir;
+  if (raw.startsWith('~/')) return path.resolve(path.join(homeDir, raw.slice(2)));
+  return path.resolve(raw);
+}
+
+export async function findOnPath(name, pathEnv) {
+  const dirs = String(pathEnv ?? '')
+    .split(path.delimiter)
+    .filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, name);
+    try {
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Try the next directory.
+    }
+  }
+  return null;
+}
+
+function requestsNewConfig(parsed) {
+  return (
+    parsed.roots.length > 0 ||
+    parsed.autoRebuild === true ||
+    Boolean(parsed.agent) ||
+    Boolean(parsed.skills) ||
+    Boolean(parsed.managedSkills) ||
+    Boolean(parsed.memory) ||
+    Boolean(parsed.transcripts)
+  );
+}
+
+function parseSetupArgs(args) {
+  const parsed = { roots: [], autoRebuild: false, reset: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') return { help: true };
+    if (arg === '--auto-rebuild') {
+      parsed.autoRebuild = true;
+      continue;
+    }
+    if (arg === '--reset') {
+      parsed.reset = true;
+      continue;
+    }
+    if (arg === '--root') {
+      parsed.roots.push(oneValue(args, index, arg));
+      index += 1;
+      continue;
+    }
+    const key = singleFlag(arg);
+    if (key) {
+      if (parsed[key] !== undefined) {
+        throw new Error(`${arg} accepts one value.`);
+      }
+      parsed[key] = oneValue(args, index, arg);
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument for setup: ${arg}`);
+  }
+  return parsed;
+}
+
+function singleFlag(arg) {
+  if (arg === '--registry') return 'registry';
+  if (arg === '--agent') return 'agent';
+  if (arg === '--skills') return 'skills';
+  if (arg === '--managed-skills') return 'managedSkills';
+  if (arg === '--memory') return 'memory';
+  if (arg === '--transcripts') return 'transcripts';
+  return null;
+}
+
+function oneValue(args, index, arg) {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`Missing value for ${arg}`);
+  }
+  return value;
+}
+
+async function fileExists(candidate) {
+  try {
+    await access(candidate, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function directoryExists(candidate) {
+  try {
+    return (await stat(candidate)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function skillRootsBesideHub(configPath, hubSkills) {
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch {
+    return [];
+  }
+  const roots = config?.scopes?.skills?.roots;
+  if (!Array.isArray(roots)) return [];
+  const hub = await canonicalDir(hubSkills);
+  const others = [];
+  for (const root of roots) {
+    if (typeof root !== 'string' || root.length === 0) continue;
+    if ((await canonicalDir(root)) === hub) continue;
+    others.push(root);
+  }
+  return others;
+}
+
+async function canonicalDir(candidate) {
+  try {
+    return await realpath(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+function spawnBox(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env: options.env,
+      cwd: options.cwd,
+      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);
+    });
+  });
+}

package/bin/skill.mjs

@@ -2,14 +2,24 @@
  * knolo skill
  *
  * Creates a Knolo skill pack: guidance plus an optional pinned V5 image.
- * The pack names no host and no home directory. A directory catalog stores
- * packs. It does not run a model and it does not answer questions.
+ * 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, readdir, readFile, writeFile } from 'node:fs/promises';
+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));
 
@@ -19,23 +29,32 @@ 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> [options]
+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 <name> --hub <dir> --dir <path> [--json]
-  knolo skill install --pack <pack> --dir <path> [--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 copies a pack into a directory catalog. install checks the pin
-before it writes, and it writes only into --dir.
-The catalog stores packs. It does not answer questions.
-This catalog is not https://hub.knolo.dev.`;
+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);
@@ -49,6 +68,9 @@ export async function runSkillCli(argv) {
   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}`);
 }
 
@@ -183,7 +205,27 @@ async function packSkill(dirArg, flags) {
 }
 
 async function publishSkill(packArg, flags) {
-  if (!flags.hub) throw new Error('Missing --hub');
+  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);
@@ -223,9 +265,33 @@ async function publishSkill(packArg, flags) {
   else console.log(`published        ${dest}`);
 }
 
-async function installSkill(nameArg, flags) {
-  if (!flags.dir) throw new Error('Missing --dir');
-  const destRoot = path.resolve(process.cwd(), flags.dir);
+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));
@@ -253,8 +319,122 @@ async function installSkill(nameArg, flags) {
   }
   await writePackFiles(dest, pack);
   const summary = { ok: true, name: pack.manifest.name, dir: dest };
-  if (flags.json) console.log(JSON.stringify(summary));
-  else console.log(`installed        ${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) {
@@ -677,6 +857,436 @@ async function loadCore() {
   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 = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/cli",
-  "version": "6.2.1",
+  "version": "6.2.2",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"
@@ -28,7 +28,7 @@
   },
   "scripts": {
     "build": "node -e \"console.log('cli is executable via bin/knolo.mjs')\"",
-    "test": "npm run build --prefix ../core && node --test test/cli.test.mjs test/kar.test.mjs test/kar-graph.test.mjs test/kar-produce.test.mjs test/hub.integration.test.mjs test/compose.test.mjs test/cortex.test.mjs test/flight.test.mjs test/skill.test.mjs",
+    "test": "npm run build --prefix ../core && node --test test/cli.test.mjs test/kar.test.mjs test/kar-graph.test.mjs test/kar-produce.test.mjs test/hub.integration.test.mjs test/compose.test.mjs test/cortex.test.mjs test/flight.test.mjs test/skill.test.mjs test/setup.test.mjs",
     "test:hub": "node --test test/hub.integration.test.mjs"
   },
   "dependencies": {