@knolo/cli 6.1.0 → 6.2.1

package/README.md

@@ -12,13 +12,30 @@ 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.1.0`
-depends on `@knolo/core` `^6.1.0`. They do not fetch Hub. Verification
+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
 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
 claim is true or false. Hub `attested: true` is a listing flag.
 
+`knolo cortex find`, `knolo cortex ask`, `knolo cortex explain`, and
+`knolo cortex verify` run bounded evidence retrieval. The CLI does not call a
+model and does not take an API key. A verified trace matches the image. It
+does not mean the answer is true.
+
+`knolo flight ingest` packs a `flight-events-1` document into a V5 Knowledge
+Image and binds it to the SHA-256 of one log file. It does not decode the log.
+`log.format` is `ulog`, `dataflash`, or `rosbag2`. Optional producers live in
+`scripts/flight/` and are not part of `npm test`. `SATISFIED` on a later KAR
+check means the evidence requirements were met. It does not mean a flight was
+safe, legal, or compliant. See `docs/flight/README.md`.
+
+`knolo skill` creates a skill pack for the host agent. The CLI 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. See
+[Skills](../../docs/skills/README.md).
+
 The official CLI for building `.knolo` knowledge packs.
 
 It indexes structured content and produces a deterministic, local-first knowledge bundle for use with `@knolo/core`.
@@ -115,6 +132,40 @@ Successful installs are cached by SHA-256 and recorded in
 `knolo.lock.json`. A yanked version or an existing conflicting pin requires
 `--force`; digest and artifact validation cannot be bypassed.
 
+## 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`.
+
+```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 --hub ./catalog
+knolo skill install refund-policy --hub ./catalog --dir ./skills
+```
+
+`init` writes `SKILL.md` and an empty `knowledge/` directory. `check` reads
+that directory. When `knowledge/` has files, `check` builds a V5 image, runs
+one search, and prints a receipt id. The receipt is an integrity check. It
+does not mean a claim is proven.
+
+`pack` writes `manifest.json`, `SKILL.md`, `policy.json`, and, when
+`knowledge/` has files, `knowledge.v5`. The manifest stores SHA-256 pins and
+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`.
+
 ---
 
 ## 🚀 Commands
@@ -275,9 +326,10 @@ This ensures:
 ## 🗺 Roadmap
 
 The active roadmap is maintained in [`../../docs/ROADMAP.md`](../../docs/ROADMAP.md).
-The current release is `6.1.0`. It preserves the V4 CLI, keeps V5 verification,
+The current release is `6.2.0`. It preserves the V4 CLI, keeps V5 verification,
 migration, diagnostics, and read-only Studio management, and adds offline
-composition and attestation.
+composition, attestation, and `knolo cortex`. Cortex verification does not
+mean an answer is true.
 
 ---
 

package/bin/cortex.mjs

@@ -0,0 +1,125 @@
+/**
+ * knolo cortex
+ *
+ * Bounded evidence retrieval. The CLI does not call a model and does not
+ * take an API key. Verification recomputes roots. It does not mean the
+ * answer is true.
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { KAR_CLI_MAX_IMAGE_BYTES, KAR_CLI_MAX_TEXT_BYTES, readBounded, readBoundedJson } from './kar-limits.mjs';
+
+const USAGE = `Usage:
+  knolo cortex find <image> --question "..." [--top-k 100] [--policy policy.json] --out candidates.json
+  knolo cortex ask <image> --question "..." [--graph file] [--plan plan.json] [--mode find_relevant] [--policy policy.json] [--created-at text] --out answer.cortex.json
+  knolo cortex explain <answer.cortex.json>
+  knolo cortex verify --image <image> --answer answer.cortex.json [--graph file] [--question "..."]
+
+The CLI does not load a model. Hosts inject a model through createCortexSession.
+Verification checks the trace against the image. It does not mean the answer is true.
+SATISFIED on a KAR reference means evidence requirements were met. It does not mean a claim is proven.`;
+
+export async function runCortexCli(args) {
+  const sub = args[0];
+  if (sub === 'find') return writeTrace(await runAsk(parseFlags(args.slice(1)), 'find_relevant'));
+  if (sub === 'ask') return writeTrace(await runAsk(parseFlags(args.slice(1)), undefined));
+  if (sub === 'explain') return explain(parseFlags(args.slice(1)));
+  if (sub === 'verify') return verify(parseFlags(args.slice(1)));
+  throw new Error(`Unknown cortex command.\n${USAGE}`);
+}
+
+async function runAsk(flags, forcedMode) {
+  const imagePath = flags._[0];
+  if (!imagePath) throw new Error(USAGE);
+  const question = required(flags, 'question');
+  const api = await loadCortex();
+  const policy = flags.policy ? readBoundedJson(flags.policy) : {};
+  if (flags['top-k'] !== undefined) {
+    const topK = Number(flags['top-k']);
+    if (!Number.isInteger(topK) || topK < 1) throw new Error('--top-k must be a positive integer.');
+    policy.maxCandidatesPerRound = topK;
+  }
+  const session = await api.createCortexSession({
+    image: new Uint8Array(readBounded(imagePath, KAR_CLI_MAX_IMAGE_BYTES)),
+    ...(flags.graph ? { graph: readBoundedJson(flags.graph) } : {}),
+    ...(flags.plan ? { plan: readBoundedJson(flags.plan) } : {}),
+    policy,
+  });
+  const mode = forcedMode ?? flags.mode ?? 'evidence_answer';
+  const trace = await api.askCortex(session, {
+    question,
+    mode,
+    ...(flags['created-at'] ? { createdAt: flags['created-at'] } : {}),
+  });
+  return { flags, trace };
+}
+
+async function writeTrace(result) {
+  const json = `${JSON.stringify(result.trace, null, 2)}\n`;
+  if (result.flags.out) {
+    const out = path.resolve(process.cwd(), result.flags.out);
+    if (existsSync(out)) throw new Error(`Refusing to overwrite ${out}`);
+    writeFileSync(out, json);
+    console.log(`${result.trace.answer.status} ${result.trace.receipt.traceRoot}`);
+    return;
+  }
+  console.log(json);
+}
+
+async function explain(flags) {
+  const file = flags._[0] ?? flags.answer;
+  if (!file) throw new Error(USAGE);
+  const api = await loadCortex();
+  const trace = readBoundedJson(file);
+  console.log(`${JSON.stringify(api.explainCortexAnswer(trace), null, 2)}\n`);
+}
+
+async function verify(flags) {
+  const api = await loadCortex();
+  const answer = required(flags, 'answer');
+  const image = required(flags, 'image');
+  const trace = readBoundedJson(answer, KAR_CLI_MAX_TEXT_BYTES);
+  const verified = await api.verifyCortexAnswer({
+    image: new Uint8Array(readBounded(image, KAR_CLI_MAX_IMAGE_BYTES)),
+    question: flags.question ?? trace.question,
+    result: trace,
+    ...(flags.graph ? { graph: readBoundedJson(flags.graph) } : {}),
+  });
+  if (!verified.ok) throw new Error(`${verified.code}: ${verified.message}`);
+  console.log(`ok ${verified.traceRoot}`);
+}
+
+async function loadCortex() {
+  const candidate = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../core/dist/cortex/index.js');
+  const loaded = await import(pathToFileURL(candidate).href);
+  if (!loaded.createCortexSession || !loaded.askCortex || !loaded.verifyCortexAnswer) {
+    throw new Error('Could not load @knolo/core/cortex. Build packages/core first.');
+  }
+  return loaded;
+}
+
+function required(flags, name) {
+  if (!flags[name]) throw new Error(`Missing --${name}.\n${USAGE}`);
+  return flags[name];
+}
+
+function parseFlags(args) {
+  const flags = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--question') flags.question = args[++i];
+    else if (arg === '--graph') flags.graph = args[++i];
+    else if (arg === '--plan') flags.plan = args[++i];
+    else if (arg === '--mode') flags.mode = args[++i];
+    else if (arg === '--policy') flags.policy = args[++i];
+    else if (arg === '--out') flags.out = args[++i];
+    else if (arg === '--top-k') flags['top-k'] = args[++i];
+    else if (arg === '--created-at') flags['created-at'] = args[++i];
+    else if (arg === '--image') flags.image = args[++i];
+    else if (arg === '--answer') flags.answer = args[++i];
+    else if (arg.startsWith('--')) throw new Error(`Unknown flag ${arg}.\n${USAGE}`);
+    else flags._.push(arg);
+  }
+  return flags;
+}

package/bin/flight.mjs

@@ -0,0 +1,367 @@
+/**
+ * knolo flight ingest
+ *
+ * Packs a flight-events-1 document into a V5 Knowledge Image.
+ * It does not decode the log. log.format is ulog, dataflash, or rosbag2.
+ * SATISFIED is not a statement that a flight was safe or compliant.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readBounded } from './kar-limits.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const FLIGHT_EVENTS_FORMAT = 'flight-events-1';
+export const MAX_FLIGHT_EVENTS = 10_000;
+export const MAX_FLIGHT_EVENT_BYTES = 2 * 1024 * 1024;
+export const FLIGHT_ACTOR = 'knolo-flight';
+
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const PHRASE = /^[a-z0-9][a-z0-9 -]{0,160}$/;
+const DIGEST = /^sha256-[0-9a-f]{64}$/;
+const TOP_KEYS = ['format', 'parser', 'log', 'events'];
+const EVENT_KEYS = ['id', 'kind', 'timestampUs', 'byteStart', 'byteEnd', 'fields', 'text'];
+const KIND_FIELDS = {
+  arming: ['state'],
+  'nav-mode': ['mode'],
+  'failsafe-assert': ['name'],
+  'failsafe-clear': ['name'],
+  'geofence-breach': ['name'],
+  'geofence-clear': [],
+  'battery-threshold': ['level'],
+  'link-loss': [],
+  'link-restored': [],
+  'scan-summary': ['phrase'],
+};
+
+const USAGE = `Usage: knolo flight ingest --events <events.json> --log <file> --out <image.knolo> [--json]
+
+Packs a flight-events-1 document into a V5 Knowledge Image.
+The command hashes --log and refuses the image when the hash or byte length differs.
+It does not decode a flight log. Parsing stays in an external producer.
+A later KAR status of SATISFIED means evidence requirements were met.
+It does not mean a flight was safe, legal, or compliant.`;
+
+export async function runFlightCli(argv) {
+  const { positionals, flags } = parseArgs(argv);
+  const sub = positionals[0] ?? '';
+  if (!sub || sub === 'help' || flags.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (sub !== 'ingest') throw new Error(`Unknown flight command "${sub}".\n${USAGE}`);
+  const eventsPath = required(flags, 'events');
+  const logPath = required(flags, 'log');
+  const outPath = required(flags, 'out');
+  const resolvedOut = path.resolve(process.cwd(), outPath);
+  if (existsSync(resolvedOut)) throw new Error(`Refusing to overwrite ${outPath}. Choose a new --out path.`);
+  const document = readEvents(eventsPath);
+  const log = await inspectLog(logPath);
+  if (log.byteLength !== document.log.byteLength || log.sha256 !== document.log.sha256) {
+    throw new Error('FLIGHT_LOG_MISMATCH: log bytes do not match events.log.sha256 or events.log.byteLength.');
+  }
+  const image = await flightImageFromDocument(document);
+  writeFileSync(resolvedOut, image.bytes);
+  if (flags.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      stateRoot: image.stateRoot,
+      events: document.events.length,
+      wrote: outPath,
+    }, null, 2));
+    return;
+  }
+  console.log(`FLIGHT IMAGE\nstate root       ${image.stateRoot}\nevents           ${document.events.length}\nwrote            ${outPath}\n\nEvidence requirements are not a safety or compliance determination.`);
+}
+
+export function readEvents(file) {
+  const resolved = path.resolve(process.cwd(), file);
+  const stat = statSync(resolved);
+  if (!stat.isFile()) throw new Error(`FLIGHT_EVENTS_INVALID: ${file} is not a file.`);
+  if (stat.size > MAX_FLIGHT_EVENT_BYTES) {
+    throw new Error(`FLIGHT_EVENTS_TOO_LARGE: ${file} is ${stat.size} bytes; limit is ${MAX_FLIGHT_EVENT_BYTES}.`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readBounded(file, MAX_FLIGHT_EVENT_BYTES).toString('utf8'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`FLIGHT_EVENTS_INVALID: ${message}`);
+  }
+  const document = parseFlightEvents(parsed);
+  if (!document.ok) throw new Error(`${document.code}: ${document.message}`);
+  return document.document;
+}
+
+export function parseFlightEvents(value) {
+  if (!isPlain(value) || !sameKeys(value, TOP_KEYS)) {
+    return fail('FLIGHT_EVENTS_INVALID', 'Document must be flight-events-1 with parser, log, and events.');
+  }
+  if (value.format !== FLIGHT_EVENTS_FORMAT) {
+    return fail('FLIGHT_EVENTS_INVALID', 'format must be flight-events-1.');
+  }
+  const parser = parseParser(value.parser);
+  if (!parser.ok) return parser;
+  const log = parseLog(value.log);
+  if (!log.ok) return log;
+  if (!Array.isArray(value.events)) return fail('FLIGHT_EVENTS_INVALID', 'events must be an array.');
+  if (value.events.length > MAX_FLIGHT_EVENTS) {
+    return fail('FLIGHT_TOO_MANY_EVENTS', `event count ${value.events.length} exceeds ${MAX_FLIGHT_EVENTS}.`);
+  }
+  const events = [];
+  const ids = new Set();
+  for (const [index, raw] of value.events.entries()) {
+    const parsed = parseEvent(raw, index, log.log.byteLength);
+    if (!parsed.ok) return parsed;
+    if (ids.has(parsed.event.id)) return fail('FLIGHT_EVENTS_INVALID', `Duplicate event id ${parsed.event.id}.`);
+    ids.add(parsed.event.id);
+    events.push(parsed.event);
+  }
+  for (let index = 1; index < events.length; index += 1) {
+    if (compareEvents(events[index - 1], events[index]) > 0) {
+      return fail('FLIGHT_EVENTS_INVALID', 'events must be sorted by timestampUs, kind, byteStart, and id.');
+    }
+  }
+  return { ok: true, document: { format: FLIGHT_EVENTS_FORMAT, parser: parser.parser, log: log.log, events } };
+}
+
+export function renderEventText(event) {
+  const time = event.timestampUs;
+  const fields = event.fields;
+  switch (event.kind) {
+    case 'arming':
+      return `ARMING_STATE ${fields.state} at ${time} us.`;
+    case 'nav-mode':
+      return `NAV_STATE ${fields.mode} at ${time} us.`;
+    case 'failsafe-assert':
+      return `FAILSAFE ${fields.name} asserted at ${time} us.`;
+    case 'failsafe-clear':
+      return `FAILSAFE ${fields.name} cleared at ${time} us.`;
+    case 'geofence-breach':
+      return `GEOFENCE_BREACH ${fields.name} at ${time} us.`;
+    case 'geofence-clear':
+      return `GEOFENCE clear at ${time} us.`;
+    case 'battery-threshold':
+      return `battery threshold crossed at ${time} us. level ${fields.level}.`;
+    case 'link-loss':
+      return `link loss recorded at ${time} us.`;
+    case 'link-restored':
+      return `LINK_RESTORED at ${time} us.`;
+    case 'scan-summary':
+      return `${fields.phrase} at ${time} us.`;
+    default:
+      return '';
+  }
+}
+
+export async function flightImageFromDocument(document) {
+  const api = await loadImageApi();
+  const encoder = new TextEncoder();
+  const objects = [
+    {
+      kind: 'metadata',
+      bytes: encoder.encode(metadataText(document)),
+      meta: {
+        source: 'flight-log.txt',
+        role: 'flight-log',
+        logSha256: document.log.sha256,
+        byteLength: String(document.log.byteLength),
+        parserId: document.parser.id,
+        parserVersion: document.parser.version,
+        eventCount: String(document.events.length),
+        logFormat: document.log.format,
+      },
+    },
+    ...document.events.map((event) => ({
+      kind: 'chunk',
+      bytes: encoder.encode(event.text),
+      meta: {
+        source: `${event.id}.txt`,
+        eventKind: event.kind,
+        timestampUs: String(event.timestampUs),
+        byteStart: String(event.byteStart),
+        byteEnd: String(event.byteEnd),
+        logSha256: document.log.sha256,
+      },
+    })),
+  ];
+  return api.createKnowledgeImageV5({ actor: FLIGHT_ACTOR, sequence: 1, objects });
+}
+
+export function hashFile(file) {
+  const resolved = path.resolve(process.cwd(), file);
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(resolved);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('error', reject);
+    stream.on('end', () => resolve(`sha256-${hash.digest('hex')}`));
+  });
+}
+
+function metadataText(document) {
+  return [
+    'format flight-events-1',
+    `log ${document.log.sha256}`,
+    `bytes ${document.log.byteLength}`,
+    `parser ${document.parser.id} ${document.parser.version}`,
+    `events ${document.events.length}`,
+    '',
+  ].join('\n');
+}
+
+function parseParser(value) {
+  if (!isPlain(value) || !sameKeys(value, ['id', 'version'])) {
+    return fail('FLIGHT_EVENTS_INVALID', 'parser must contain id and version.');
+  }
+  if (typeof value.id !== 'string' || !TOKEN.test(value.id)) {
+    return fail('FLIGHT_EVENTS_INVALID', 'parser.id must be a short token.');
+  }
+  if (typeof value.version !== 'string' || !TOKEN.test(value.version)) {
+    return fail('FLIGHT_EVENTS_INVALID', 'parser.version must be a short token.');
+  }
+  return { ok: true, parser: { id: value.id, version: value.version } };
+}
+
+function parseLog(value) {
+  if (!isPlain(value) || !sameKeys(value, ['sha256', 'byteLength', 'format'])) {
+    return fail('FLIGHT_EVENTS_INVALID', 'log must contain sha256, byteLength, and format.');
+  }
+  if (typeof value.sha256 !== 'string' || !DIGEST.test(value.sha256)) {
+    return fail('FLIGHT_EVENTS_INVALID', 'log.sha256 must be sha256- and 64 lowercase hex digits.');
+  }
+  if (!nonNegativeInteger(value.byteLength)) {
+    return fail('FLIGHT_EVENTS_INVALID', 'log.byteLength must be a non-negative integer.');
+  }
+  if (value.format !== 'ulog' && value.format !== 'dataflash' && value.format !== 'rosbag2') {
+    return fail('FLIGHT_EVENTS_INVALID', 'log.format must be ulog, dataflash, or rosbag2.');
+  }
+  return { ok: true, log: { sha256: value.sha256, byteLength: value.byteLength, format: value.format } };
+}
+
+function parseEvent(value, index, byteLength) {
+  const pathName = `events[${index}]`;
+  if (!isPlain(value) || !sameKeys(value, EVENT_KEYS)) {
+    return fail('FLIGHT_EVENTS_INVALID', `${pathName} has missing or unknown fields.`);
+  }
+  if (typeof value.id !== 'string' || !TOKEN.test(value.id)) {
+    return fail('FLIGHT_EVENTS_INVALID', `${pathName}.id must be a short token.`);
+  }
+  const fields = KIND_FIELDS[value.kind];
+  if (!fields) return fail('FLIGHT_EVENTS_INVALID', `${pathName}.kind is not a phase 1 event kind.`);
+  if (!nonNegativeInteger(value.timestampUs) || !nonNegativeInteger(value.byteStart) || !nonNegativeInteger(value.byteEnd)) {
+    return fail('FLIGHT_EVENTS_INVALID', `${pathName} timestamps and byte offsets must be non-negative integers.`);
+  }
+  if (value.byteEnd < value.byteStart || value.byteEnd > byteLength) {
+    return fail('FLIGHT_EVENTS_INVALID', `${pathName} byte range is outside the log.`);
+  }
+  const parsedFields = parseFields(value.fields, fields, pathName);
+  if (!parsedFields.ok) return parsedFields;
+  const event = {
+    id: value.id,
+    kind: value.kind,
+    timestampUs: value.timestampUs,
+    byteStart: value.byteStart,
+    byteEnd: value.byteEnd,
+    fields: parsedFields.fields,
+    text: '',
+  };
+  event.text = renderEventText(event);
+  if (value.text !== event.text) {
+    return fail('FLIGHT_EVENTS_INVALID', `${pathName}.text must be the canonical sentence for its kind and fields.`);
+  }
+  return { ok: true, event };
+}
+
+function parseFields(value, names, pathName) {
+  if (!isPlain(value) || !sameKeys(value, names)) {
+    return fail('FLIGHT_EVENTS_INVALID', `${pathName}.fields must contain exactly ${names.join(', ') || 'no keys'}.`);
+  }
+  const fields = {};
+  for (const name of names) {
+    const text = value[name];
+    const pattern = name === 'phrase' ? PHRASE : TOKEN;
+    if (typeof text !== 'string' || !pattern.test(text)) {
+      return fail('FLIGHT_EVENTS_INVALID', `${pathName}.fields.${name} is not a canonical token.`);
+    }
+    fields[name] = text;
+  }
+  return { ok: true, fields };
+}
+
+function compareEvents(left, right) {
+  if (left.timestampUs !== right.timestampUs) return left.timestampUs - right.timestampUs;
+  if (left.kind !== right.kind) return left.kind < right.kind ? -1 : 1;
+  if (left.byteStart !== right.byteStart) return left.byteStart - right.byteStart;
+  if (left.id !== right.id) return left.id < right.id ? -1 : 1;
+  return 0;
+}
+
+function fail(code, message) {
+  return { ok: false, code, message };
+}
+
+function nonNegativeInteger(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isPlain(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function sameKeys(value, keys) {
+  const actual = Object.keys(value);
+  if (actual.length !== keys.length) return false;
+  const allowed = new Set(keys);
+  return actual.every((key) => allowed.has(key));
+}
+
+async function inspectLog(file) {
+  const resolved = path.resolve(process.cwd(), file);
+  const stat = statSync(resolved);
+  if (!stat.isFile()) throw new Error(`FLIGHT_LOG_MISMATCH: ${file} is not a file.`);
+  const sha256 = await hashFile(file);
+  return { byteLength: stat.size, sha256 };
+}
+
+async function loadImageApi() {
+  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) return loaded;
+    } catch {
+      // Try the next candidate.
+    }
+  }
+  throw new Error('Could not load @knolo/core. Build packages/core first.');
+}
+
+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 };
+}
+
+function required(flags, name) {
+  if (!flags[name]) throw new Error(`Missing --${name}`);
+  return flags[name];
+}

package/bin/knolo.mjs

@@ -76,6 +76,9 @@ const SUBCOMMANDS = new Set([
   'compose',
   'attest',
   'verify-attestation',
+  'cortex',
+  'flight',
+  'skill',
 ]);
 const ICP_SUBCOMMANDS = new Set([
   'init',
@@ -173,6 +176,9 @@ Commands:
   kar                     KAR evidence-set retrieval over a Committed Evidence Graph
   compose                 Compose Knowledge Images, packs, and attestations offline
   attest                  Create or verify a composition attestation
+  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
   icp                     Scaffold and operate an ICP-native knowledge canister
 
 Global options:
@@ -211,6 +217,24 @@ function printCommandHelp(command) {
     kar: 'Usage: knolo kar <evaluate|verify|explain|inspect|graph|package|produce|domain|dossier|coverage|benchmark|demo|conformance> [options]\n\nKnolo Adversarial Retrieval. Semantics are frozen at kar-1-research-1.\n\n  knolo kar evaluate --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..."\n  knolo kar verify   --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..." --result result.json\n  knolo kar explain  --result result.json\n  knolo kar inspect  --image knowledge.knolo --graph knowledge.kar.json [--plan plan.json]\n  knolo kar graph build --image knowledge.knolo --source knowledge.ceg.yaml --out knowledge.kar.json\n  knolo kar package --image knowledge.knolo --graph knowledge.kar.json --out dist/my-knowledge-kar/\n  knolo kar produce rules --image knowledge.knolo --domain domains/contracts-v4 --out proposals.json\n  knolo kar domain validate domains/contracts-v4\n  knolo kar dossier build --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..." --out dossier/\n  knolo kar dossier verify dossier/\n  knolo kar coverage build --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..." --out coverage/\n  knolo kar coverage verify coverage/\n  knolo kar benchmark annotate --packet packet.json --decisions decisions.json --out labels.json --role human --reviewer-id <id>\n  knolo kar demo\n  knolo kar conformance\n\n--json prints the machine-readable result. verify exits non-zero when the certificate does not match. Abstention is a result and exits 0. graph and package author a Committed Evidence Graph without changing retrieval. produce proposes CEG Source and does not write committed bytes. dossier packages one evaluation and fails closed when committed fields change. coverage reports met requirements, gaps, and plans that did not decide. A gap is not a false claim. benchmark labels gold without showing producer output. demo and conformance run from a knolo-core checkout.',
     compose: 'Usage: knolo compose <create|verify|excerpt|query> [options]\n\nOffline composition of Knowledge Images, packs, KAR sidecars, Domain Packs, and bounded excerpts.\n\n  knolo compose create --members members.json --out composition/ [--host knowledge.knolo] [--availability material|digest] [--policy policy.json]\n  knolo compose verify composition/ [--require-material] [--member alias=path]\n  knolo compose excerpt --image knowledge.knolo --object <id> --out excerpt.json\n  knolo compose query --composition composition/ --eql "FROM chunk SEARCH \\"valve\\"" [--question "..."] [--json]\n\ncompositionRoot does not change a V5 state root or a KAR root. statement used means a query or evaluation ran. It does not mean SATISFIED, and it does not mean a claim is true or false. Hub attested: true is a listing flag and is not an attestation root. The CLI does not fetch Hub.',
     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>
+
+  knolo skill init <name> [--dir <parent>]
+  knolo skill check [<dir>] [--query <text>] [--json]
+  knolo skill pack [<dir>] [--out <dir>] [--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]
+
+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.`,
     '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':
@@ -1865,6 +1889,18 @@ async function main() {
         const { runComposeCli } = await import('./compose.mjs');
         return runComposeCli(command, commandArgs);
       }
+      if (command === 'cortex') {
+        const { runCortexCli } = await import('./cortex.mjs');
+        return runCortexCli(commandArgs);
+      }
+      if (command === 'flight') {
+        const { runFlightCli } = await import('./flight.mjs');
+        return runFlightCli(commandArgs);
+      }
+      if (command === 'skill') {
+        const { runSkillCli } = await import('./skill.mjs');
+        return runSkillCli(commandArgs);
+      }
       if (command === 'init') return await cmdInit();
       if (command === 'add') return await cmdAdd(commandArgs);
       if (command === 'search') return await runHubSearch(commandArgs);