hafez 1.3.0 → 1.4.0

package/dist/cli/commands.js

@@ -1,8 +1,9 @@
 // src/cli/commands.ts
 import { readFileSync } from 'fs';
+import { resolve } from 'path';
 import { parseArgs, splitList, str, UsageError } from './args.js';
 import { HafezError } from '../types.js';
-import { BatchOperationSchema } from '../batch-ops.js';
+import { BatchOperationSchema, normalizeAliases, opErrorLine, batchInvalidHeader } from '../batch-ops.js';
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { formatEntityHeader, formatKnowledgeHeader, formatQueryTable, formatKnowledgeTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
@@ -25,22 +26,75 @@ export async function cmdRead(os, args, opts = {}) {
         return formatEntityHeader(fm, result.body);
     return formatKnowledgeHeader(fm, result.body);
 }
-const QUERY_USAGE = 'Usage: hafez query [--kind entity|knowledge|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]';
+const QUERY_USAGE = `Usage: hafez query [--kind entity|knowledge|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]
+
+  --filter active|paused|done matches entity status; knowledge notes carry no
+  status, so under --kind all they are always included alongside the matching
+  entities. --filter stale|capture are entity-only views and return no
+  knowledge. --filter/--type/--parent are rejected with --kind knowledge, and
+  --confidence/--subtype are rejected with --kind entity, rather than being
+  silently dropped. --related-to takes no other query flags.`;
 const QUERY_FLAGS = {
     kind: 'string', filter: 'string', type: 'string', parent: 'string', 'related-to': 'string',
     domain: 'string', confidence: 'string', subtype: 'string', tag: 'string',
     since: 'string', before: 'string', 'created-since': 'string', 'created-before': 'string',
     'sort-by': 'string', 'sort-order': 'string', limit: 'string', offset: 'string',
 };
+/** Every flag the query parser accepts, for the branch-support matrix. */
+export const QUERY_FLAG_NAMES = Object.keys(QUERY_FLAGS);
+/** Which flags each kind branch actually applies. A branch that cannot honour
+ * a flag rejects it (below) instead of dropping it: `--kind knowledge --filter
+ * stale` used to return every knowledge note with exit 0, and `--confidence`
+ * never reached an entity query at all. */
+export const QUERY_FLAG_SUPPORT = {
+    entity: ['kind', 'filter', 'type', 'parent', 'domain', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    knowledge: ['kind', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    all: ['kind', 'filter', 'type', 'parent', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    'related-to': ['related-to'],
+};
+const FLAG_SCOPE_REASON = {
+    filter: 'it selects entity status (or the entity-only stale/capture views); knowledge notes carry no status',
+    type: 'entity types only',
+    parent: 'entity hierarchy only',
+    confidence: 'knowledge notes only',
+    subtype: 'knowledge notes only',
+};
+const QUERY_KINDS = ['entity', 'knowledge', 'all'];
+function rejectUnsupportedFlags(branch, flags) {
+    const supported = new Set(QUERY_FLAG_SUPPORT[branch]);
+    for (const [name, value] of Object.entries(flags)) {
+        if (value === undefined || supported.has(name))
+            continue;
+        const where = branch === 'related-to'
+            ? 'with --related-to (it returns every entity and knowledge note linked to the slug)'
+            : `with --kind ${branch}`;
+        const reason = FLAG_SCOPE_REASON[name] ? ` — ${FLAG_SCOPE_REASON[name]}` : '';
+        throw new UsageError(`--${name} is not supported ${where}${reason}\n${QUERY_USAGE}`);
+    }
+}
+/** Paging flags reach SQL as text — parse them strictly here so `--limit abc`
+ * is a usage error rather than a prepare-time SqliteError. */
+function intFlag(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw new UsageError(`--${name} must be a non-negative integer (got "${raw}")\n${QUERY_USAGE}`);
+    return Number(raw);
+}
 export async function cmdQuery(os, args, opts = {}) {
     const { flags } = parseArgs(args, QUERY_FLAGS, QUERY_USAGE);
-    const kind = str(flags.kind) ?? 'entity';
+    const relatedTo = str(flags['related-to']);
+    const branch = relatedTo !== undefined ? 'related-to' : (str(flags.kind) ?? 'entity');
+    if (branch !== 'related-to' && !QUERY_KINDS.includes(branch)) {
+        throw new UsageError(`--kind must be one of ${QUERY_KINDS.join(', ')} (got "${branch}")\n${QUERY_USAGE}`);
+    }
+    rejectUnsupportedFlags(branch, flags);
     const filter = (str(flags.filter) ?? 'active');
     const type = str(flags.type);
     const parent = str(flags.parent);
-    const relatedTo = str(flags['related-to']);
     const domain = str(flags.domain);
     const confidence = str(flags.confidence);
+    const subtype = str(flags.subtype);
     const since = str(flags.since);
     const before = str(flags.before);
     const createdSince = str(flags['created-since']);
@@ -49,11 +103,10 @@ export async function cmdQuery(os, args, opts = {}) {
     const tags = tagRaw ? tagRaw.split(',').map(t => t.trim()).filter(Boolean) : undefined;
     const sortBy = str(flags['sort-by']);
     const sortOrder = str(flags['sort-order']);
-    const limitRaw = str(flags.limit);
-    const offsetRaw = str(flags.offset);
-    const limit = limitRaw != null ? parseInt(limitRaw, 10) : undefined;
-    const offset = offsetRaw != null ? parseInt(offsetRaw, 10) : undefined;
+    const limit = intFlag(str(flags.limit), 'limit');
+    const offset = intFlag(str(flags.offset), 'offset');
     const sortOpts = { sort_by: sortBy, sort_order: sortOrder, limit, offset };
+    const timeOpts = { since, before, createdSince, createdBefore };
     // --related-to: always returns both entities and knowledge
     if (relatedTo) {
         const result = await os.related_to(relatedTo);
@@ -69,20 +122,19 @@ export async function cmdQuery(os, args, opts = {}) {
             sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge, total));
         return sections.length > 0 ? sections.join('\n\n') : 'No results.';
     }
-    const queryOpts = { filter, type, parent, domain, since, before, createdSince, createdBefore, tags, ...sortOpts };
-    // --kind knowledge: query knowledge only
-    // Note: time flags only apply to entity queries.
-    if (kind === 'knowledge') {
-        const subtype = str(flags.subtype);
-        const kOpts = { domain: domain ?? undefined, confidence, subtype, tags, ...sortOpts };
+    const queryOpts = { filter, type, parent, domain, ...timeOpts, tags, ...sortOpts };
+    // --kind knowledge: query knowledge only. The time window applies here too —
+    // knowledge rows carry created (and last-touched for the plan subtype).
+    if (branch === 'knowledge') {
+        const kOpts = { domain: domain ?? undefined, confidence, subtype, ...timeOpts, tags, ...sortOpts };
         const result = await os.query_knowledge(kOpts);
         if (opts.json)
             return jsonOut(result);
         return formatKnowledgeTable(result.items, result.total);
     }
     // --kind all: query both entities and knowledge via unified query
-    if (kind === 'all') {
-        const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence });
+    if (branch === 'all') {
+        const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence, subtype });
         if (opts.json)
             return jsonOut(result);
         const { items, total } = result;
@@ -116,13 +168,38 @@ export async function cmdSearch(os, args, opts = {}) {
         return jsonOut(results);
     return formatSearchResults(results);
 }
-const CREATE_USAGE = 'Usage: hafez create <entity|knowledge> <name> [options]';
-const CREATE_FLAGS = {
+// --status is knowledge/plan only, and --purpose needs --type project: a field
+// whose section the chosen template lacks is rejected, never silently dropped.
+const CREATE_USAGE = 'Usage: hafez create <entity|knowledge> <name> [options]\n  entity:    --type capture|entity|project [--purpose text (project only)] [--brief text] [--add-action text] …\n  knowledge: [--subtype insight|plan] [--status active|done (plan only)] [--synthesis text (insight only)] …';
+/** Exported so tests can assert the flag × kind matrix is exhaustive. */
+export const CREATE_FLAGS = {
     type: 'string', purpose: 'string', description: 'string', resource: 'string',
     domain: 'string', parent: 'string', related: 'string', tags: 'string',
     brief: 'string', 'add-action': 'string',
     subtype: 'string', synthesis: 'string', insight: 'string',
+    // knowledge, plan subtype only — insights have no lifecycle
+    status: 'string',
 };
+/** Flags whose value is a comma list. Everything else is a plain string. */
+const CREATE_LIST_FLAGS = new Set(['domain', 'related', 'tags']);
+/** Every provided create flag → its field name (dashes become underscores),
+ * kind-agnostic on purpose. Which fields a kind accepts is the Op Spec's
+ * call, not the CLI's: the per-kind hand-filter this replaces discarded
+ * whatever its branch didn't name (--brief on knowledge, --subtype on
+ * entity) and still exited 0 with the value nowhere on disk. Only provided
+ * flags are included — a present-but-undefined key would trip the same
+ * strict shape that does the rejecting. */
+function createFields(flags) {
+    const fields = {};
+    for (const flag of Object.keys(CREATE_FLAGS)) {
+        if (flags[flag] === undefined)
+            continue;
+        fields[flag.replace(/-/g, '_')] = CREATE_LIST_FLAGS.has(flag)
+            ? splitList(flags[flag])
+            : str(flags[flag]);
+    }
+    return fields;
+}
 export async function cmdCreate(os, args, opts = {}) {
     const { flags, positionals } = parseArgs(args, CREATE_FLAGS, CREATE_USAGE);
     const kind = positionals[0];
@@ -131,50 +208,84 @@ export async function cmdCreate(os, args, opts = {}) {
     const name = positionals.slice(1).join(' ');
     if (!name)
         throw new UsageError(`Usage: hafez create ${kind} <name> [options]`);
+    const fields = createFields(flags);
     if (kind === 'entity') {
-        const type = str(flags.type);
-        if (!type)
+        // The only per-kind rule the CLI still owns: --type is required, and a
+        // missing one deserves better than a shape error naming a JSON field.
+        if (fields.type === undefined)
             throw new UsageError('--type is required for entity creation');
-        const slug = await os.create('entity', name, {
-            type,
-            purpose: str(flags.purpose),
-            description: str(flags.description),
-            resource: str(flags.resource),
-            domain: splitList(flags.domain),
-            parent: str(flags.parent),
-            related: str(flags.related)?.split(','),
-            tags: str(flags.tags)?.split(','),
-            brief: str(flags.brief),
-            add_action: str(flags['add-action']),
-        });
+        const slug = await os.create('entity', name, fields);
         return opts.json ? jsonOut({ slug }) : slug;
     }
     if (kind === 'knowledge') {
-        const slug = await os.create('knowledge', name, {
-            subtype: str(flags.subtype),
-            synthesis: str(flags.synthesis) ?? str(flags.insight),
-            description: str(flags.description),
-            domain: str(flags.domain)?.split(','),
-            related: str(flags.related)?.split(','),
-            tags: str(flags.tags)?.split(','),
-        });
+        // --insight passes through untouched: the Op Spec normalizes the alias
+        // (and drops it when --synthesis is also given). On entity it stays
+        // `insight` and the kind gate rejects it. --status flows through the
+        // same way; the subtype-aware gate accepts it on plans only.
+        const slug = await os.create('knowledge', name, fields);
         return opts.json ? jsonOut({ slug }) : slug;
     }
     throw new UsageError(`Unknown kind: ${kind}. Use entity or knowledge.`);
 }
 const UPDATE_USAGE = 'Usage: hafez update <slug> [--brief text] [--description text] [--resource uri] [--add-action text] [--complete-action text] [--remove-action text] [--clear-actions] [--status s] [--log "type: summary"]';
-const UPDATE_FLAGS = {
+/** Exported so tests can assert the table covers the update schema. */
+export const UPDATE_FLAGS = {
     status: 'string', 'current-state': 'string', brief: 'string',
     'add-action': 'string', 'complete-action': 'string', 'remove-action': 'string',
-    'clear-actions': 'boolean', log: 'string', agent: 'string',
+    'clear-actions': 'boolean',
     description: 'string', resource: 'string', domain: 'string', confidence: 'string',
     tags: 'string', related: 'string', insight: 'string', synthesis: 'string',
     'add-evidence': 'string', 'add-source': 'string',
+    // Composed, not mapped: --log "type: summary" plus --agent build session_log.
+    log: 'string', agent: 'string',
     // Removed flag, declared so it fails with guidance instead of a generic
     // unknown-flag error: older installed skills/scripts still pass it, and
     // "Updated <slug>" with the action discarded is a false success.
     'next-action': 'string',
 };
+/** Flags whose value is a comma list. Everything else is a plain string. */
+const UPDATE_LIST_FLAGS = new Set(['domain', 'tags', 'related']);
+/** Flags where an empty string is the clear signal — exactly the nullable
+ * fields of the update shape. Every other flag passes its value through
+ * untouched, so `--status ""` reaches the enum and is rejected by name
+ * instead of silently no-opping (which is how it read before: the guard
+ * each flag got was an accident of which one was typed). */
+const UPDATE_CLEARABLE_FLAGS = new Set(['brief', 'description', 'resource']);
+/** Flags the generic loop skips because they are not a field of the update
+ * shape — each is hand-handled in cmdUpdate. */
+export const UPDATE_SPECIAL_FLAGS = new Set(['log', 'agent', 'next-action']);
+/** Update-shape fields with no flag of their own, and why. The exhaustiveness
+ * test consults this, so a gap here is a stated decision rather than the
+ * silent hole `add_actions` was. */
+export const UPDATE_FIELDS_WITHOUT_FLAGS = {
+    session_log: 'composed by --log "type: summary" (+ --agent), never passed raw',
+    add_actions: 'array-valued: comma-splitting would mangle action text (actions carry commas), and the parser takes no repeated flags — batch payloads are the interface for multi-action writes',
+};
+/** Every provided update flag → its field name (dashes become underscores).
+ * Which fields the target accepts is the Op Spec's call, not the CLI's — the
+ * strict shape does all accepting and rejecting, exactly as on create. Only
+ * provided flags are included: a present-but-undefined key would trip that
+ * same strict shape. */
+function updateFields(flags) {
+    const fields = {};
+    for (const [flag, type] of Object.entries(UPDATE_FLAGS)) {
+        const raw = flags[flag];
+        if (raw === undefined || UPDATE_SPECIAL_FLAGS.has(flag))
+            continue;
+        const field = flag.replace(/-/g, '_');
+        if (type === 'boolean') {
+            fields[field] = true;
+            continue;
+        }
+        if (UPDATE_LIST_FLAGS.has(flag)) {
+            fields[field] = splitList(raw);
+            continue;
+        }
+        const value = str(raw);
+        fields[field] = value === '' && UPDATE_CLEARABLE_FLAGS.has(flag) ? null : value;
+    }
+    return fields;
+}
 export async function cmdUpdate(os, args, opts = {}) {
     const { flags, positionals } = parseArgs(args, UPDATE_FLAGS, UPDATE_USAGE);
     const slug = positionals[0];
@@ -183,71 +294,22 @@ export async function cmdUpdate(os, args, opts = {}) {
     if (flags['next-action'] !== undefined) {
         throw new UsageError('--next-action was removed in v1.0.2. Use --add-action (and --clear-actions) instead.');
     }
-    const fields = {};
-    const status = str(flags.status);
-    if (status)
-        fields.status = status;
-    const currentState = str(flags['current-state']);
-    if (currentState)
-        fields.current_state = currentState;
-    // Brief
-    const brief = str(flags.brief);
-    if (brief !== undefined) {
-        fields.brief = brief === '' ? null : brief;
-    }
-    // Next Actions
-    const addAction = str(flags['add-action']);
-    if (addAction)
-        fields.add_action = addAction;
-    const completeAction = str(flags['complete-action']);
-    if (completeAction)
-        fields.complete_action = completeAction;
-    const removeAction = str(flags['remove-action']);
-    if (removeAction)
-        fields.remove_action = removeAction;
-    if (flags['clear-actions'])
-        fields.clear_actions = true;
+    // --insight is the declared alias; the Op Spec normalizes it (and drops it
+    // when --synthesis is also given).
+    const fields = updateFields(flags);
+    // The one genuinely CLI-owned convenience: session_log is a nested object,
+    // so the flag pair composes it rather than naming a field.
     const log = str(flags.log);
-    if (log) {
+    if (log !== undefined) {
         const colonIdx = log.indexOf(':');
         if (colonIdx === -1)
             throw new UsageError('--log format: "type: summary". Types: progress, decision, blocker, research');
-        const type = log.slice(0, colonIdx).trim();
-        const summary = log.slice(colonIdx + 1).trim();
-        const agent = str(flags.agent) ?? 'claude';
-        fields.session_log = { type, summary, agent };
+        fields.session_log = {
+            type: log.slice(0, colonIdx).trim(),
+            summary: log.slice(colonIdx + 1).trim(),
+            agent: str(flags.agent) ?? 'claude',
+        };
     }
-    // Shared metadata (entity + knowledge)
-    const description = str(flags.description);
-    if (description !== undefined)
-        fields.description = description;
-    const resource = str(flags.resource);
-    if (resource !== undefined)
-        fields.resource = resource;
-    const domain = splitList(flags.domain);
-    if (domain)
-        fields.domain = domain;
-    const conf = str(flags.confidence);
-    if (conf)
-        fields.confidence = conf;
-    const tags = splitList(flags.tags);
-    if (tags)
-        fields.tags = tags;
-    const related = splitList(flags.related);
-    if (related)
-        fields.related = related;
-    const insight = str(flags.insight);
-    if (insight)
-        fields.synthesis = insight;
-    const synthesis = str(flags.synthesis);
-    if (synthesis)
-        fields.synthesis = synthesis;
-    const addEvidence = str(flags['add-evidence']);
-    if (addEvidence)
-        fields.add_evidence = addEvidence;
-    const addSource = str(flags['add-source']);
-    if (addSource)
-        fields.add_source = addSource;
     const result = await os.update(slug, fields);
     if (opts.json)
         return jsonOut({ slug, ...result });
@@ -391,19 +453,12 @@ export function parseBatchInput(json) {
             continue;
         }
         const op = result.data;
-        // Alias: insight → synthesis for create knowledge/session and update ops.
-        // Runs only on successfully-parsed ops, preserving prior semantics.
-        if (op.fields) {
-            if (op.fields.insight && !op.fields.synthesis) {
-                op.fields.synthesis = op.fields.insight;
-                delete op.fields.insight;
-            }
-        }
-        operations.push(op);
+        // Alias normalization is the Op Spec's (normalizeAliases) — the CLI just
+        // hands back canonical ops so `batch --dry-run` output names real fields.
+        operations.push(normalizeAliases(op));
     }
     if (failureBlocks.length > 0) {
-        const header = `Batch failed validation: ${failureBlocks.length} invalid operation${failureBlocks.length === 1 ? '' : 's'} (0 of ${parsed.length} applied)`;
-        throw new HafezError('VALIDATION_FAILED', header, failureBlocks);
+        throw new HafezError('VALIDATION_FAILED', batchInvalidHeader(failureBlocks.length, parsed.length), failureBlocks);
     }
     return operations;
 }
@@ -452,7 +507,9 @@ export async function cmdBatch(os, args, opts = {}) {
             return jsonOut(report);
         if (!report.valid) {
             const invalidCount = report.operations.filter(o => o.errors.length > 0).length;
-            const lines = report.operations.flatMap(o => o.errors.map(e => `op[${o.index}] (${o.op} ${o.slug}): ${e}`));
+            const lines = report.operations.flatMap(o => o.errors.map(e => opErrorLine(o.index, o.op, o.slug, e)));
+            // Dry-run's own header: it reports a hypothetical, so it says "would be
+            // applied" rather than the refusal wording batchInvalidHeader carries.
             throw new HafezError('VALIDATION_FAILED', `Batch invalid: ${invalidCount} of ${operations.length} operation${operations.length === 1 ? '' : 's'} failed validation (0 would be applied)`, lines);
         }
         const out = [`Batch valid: ${operations.length} operations would be applied`];
@@ -475,7 +532,13 @@ export async function cmdBatch(os, args, opts = {}) {
     let output = `Batch complete: ${operations.length} operations`;
     if (created.length > 0)
         output += ` (created: ${created.join(', ')})`;
-    return output;
+    // Skipped ops carry the same warning line dry-run printed for them.
+    const lines = [output];
+    results.forEach((r, i) => {
+        if (r.status === 'skipped' && r.warning)
+            lines.push(`Warning: op[${i}] ${r.warning}`);
+    });
+    return lines.join('\n');
 }
 const DIGEST_USAGE = 'Usage: hafez digest [--file summary.json]  (or pipe JSON to stdin)';
 const DIGEST_FLAGS = { file: 'string' };
@@ -514,3 +577,22 @@ export async function cmdDigest(os, args, _opts = {}) {
     const ops = digest(result.data, existingSlugs);
     return JSON.stringify(ops, null, 2);
 }
+export async function cmdExport(_os, args, opts = {}) {
+    const EXPORT_USAGE = 'Usage: hafez export --okf [--out <dir>]';
+    const { flags } = parseArgs(args, { okf: 'boolean', out: 'string' }, EXPORT_USAGE);
+    if (flags.okf !== true)
+        throw new UsageError(EXPORT_USAGE);
+    const outDir = typeof flags.out === 'string' ? resolve(flags.out) : resolve(process.cwd(), 'okf-export');
+    if (!opts.vaultPath)
+        throw new HafezError('VALIDATION_FAILED', 'export requires a resolved vault path (CommandOpts.vaultPath)');
+    const { exportOkf } = await import('../export-okf.js');
+    const exportReport = exportOkf(opts.vaultPath, outDir);
+    if (opts.json)
+        return JSON.stringify(exportReport, null, 2);
+    const lines = [`Exported ${exportReport.entities} entities, ${exportReport.knowledge} knowledge, ${exportReport.sessions} sessions to ${exportReport.outDir}`];
+    for (const s of exportReport.skipped)
+        lines.push(`  skipped ${s.file}: ${s.reason}`);
+    if (exportReport.unresolvedLinks > 0)
+        lines.push(`  unresolved links: ${exportReport.unresolvedLinks}`);
+    return lines.join('\n');
+}

package/dist/cli/help-agent.js

@@ -144,6 +144,29 @@ function renderDigestSection() {
     lines.push('<!-- /SECTION:digest -->');
     return lines.join('\n');
 }
+const UPGRADE_SECTION = `## Upgrading hafez itself
+
+\`hafez upgrade\` — checks whether the installed hafez is outdated and prints
+the steps. It NEVER installs: the steps install code and overwrite the user's
+agent instructions, so show them verbatim, get an explicit yes, and only then
+run them. Re-run to verify. Every check outcome exits 0 — being outdated is a
+report, not a gate — so read the output, not the exit code. A non-zero exit
+means the invocation was wrong (exit 2, \`upgrade\` takes no arguments), never
+that a check failed. Not to be confused with \`hafez update\`, which updates
+an entity.
+
+\`--json\` keys: current, latest (null when unverified), comparison
+(behind|equal|ahead|unknown), registryReachable, npmMajor, install
+(registry|dev-checkout), skill (present|absent), skillSource, skillTarget,
+alternativeInstall, steps. \`steps\` is the action list in execution order;
+\`kind: 'command'\` entries are executable, \`kind: 'action'\` entries are
+prose — do not shell out to them. \`alternativeInstall\` is mutually exclusive
+with the install command in \`steps\`; never run both.
+
+Checks the npm registry only (override with \`HAFEZ_REGISTRY_URL\`), so a
+just-cut GitHub Release can read as \`equal\` until it is published.
+
+`;
 const FOOTER = `## Lookup pointers
 
 - \`hafez schema\`                      — list all ops
@@ -181,6 +204,7 @@ export function renderAgentHelp() {
         '',
         EXIT_CODES_SECTION,
         '',
+        UPGRADE_SECTION,
         FOOTER,
     ].join('\n');
 }

package/dist/cli/index.d.ts

@@ -1 +1,42 @@
+import type { CommandOpts } from './commands.js';
+type PreVaultRun = (args: string[], ctx: {
+    json: boolean;
+    vaultFlag?: string;
+}) => Promise<string | null> | string | null;
+type VaultRun = (os: any, args: string[], opts: CommandOpts) => Promise<string>;
+export type CommandSpec = {
+    phase: 'pre-vault';
+    run: PreVaultRun;
+} | {
+    phase: 'vault';
+    mutating?: boolean;
+    run: VaultRun;
+};
+export declare const COMMANDS: Record<string, CommandSpec>;
+/** Exported so a guard test can assert every registered command is documented
+ * here — a registered-but-undocumented command is otherwise invisible. */
+export declare const USAGE = "Usage: hafez <command> [args]\n\nCommands:\n  read <slug>                Read entity or knowledge note\n  query [--filter ...] ...   Filter entities/knowledge\n    --kind all               Both kinds; --filter matches entity status only,\n                             so knowledge notes (which have none) always show\n  search <terms>             Full-text search\n  create <kind> <name>       Create entity or knowledge note\n  capture <name> [--notes]   Quick inbox capture\n  promote <slug> <target>    Promote capture\u2192entity/project/knowledge, entity\u2192project\n  update <slug> [--status]   Update an entity or knowledge note\n    --brief \"text\"           Set/replace Brief (use --brief \"\" to clear)\n    --description \"text\"     Set one-line description (use --description \"\" to clear)\n    --resource \"uri\"         Set canonical resource URI, entities only (use --resource \"\" to clear)\n    --add-action \"text\"      Add a next action\n    --complete-action \"text\"  Complete matching action\n    --remove-action \"text\"   Remove matching action\n    --clear-actions          Remove all next actions\n    --synthesis \"text\"       Set/replace Synthesis section (--insight is an alias)\n    --add-evidence \"text\"    Append to Evidence section\n    --add-source \"text\"      Append to Sources section\n  batch                      Apply multiple operations atomically (JSON on stdin)\n  digest                     Apply digest input (JSON stdin) \u2192 batch payload (JSON stdout)\n  export --okf [--out <dir>] Export vault as an OKF v0.1 bundle (read-only)\n  sync                       Pull remote changes and push local commits\n  link <slug> <target> --relation <rel>    Add a link\n  unlink <slug> <target> --relation <rel>  Remove a link\n  stats                      Vault summary: counts, stale items, recents\n  changelog --since <when>   Git-derived change history (e.g. --since 7.days.ago)\n  schema [op] [--examples]   Machine-readable JSON schema for batch operations\n  validate                   Check vault integrity\n  index rebuild              Rebuild the SQLite index\n  init --register <path>     Register an existing vault\n  init                       Show current vault resolution\n  onboard                    Agent-directed first run: seed the vault, pick integration level\n  upgrade                    Check whether hafez is outdated and print the update steps\n  help --agent               Full API reference for agents\n\nGlobal flags:\n  --vault <path>    Vault path (overrides config)\n  --json            JSON output (structured, machine-readable)\n  --version         Print the hafez version\n\nVault discovery: --vault flag > ~/.config/hafez/vault\n";
+/** Exit codes, documented in `hafez help --agent`. 0 = success; 4 is the
+ * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
+export declare const EXIT_CODES: Record<string, number>;
+/** The pure half of the error → exit adapter: which code an error maps to.
+ * Exported so the exit-code contract is testable without spawning the CLI. */
+export declare function exitCodeFor(err: unknown): number;
+/** Does this error mean the native module failed to load/build?
+ *
+ * Matched on the MESSAGE only, and only on the messages a load/ABI failure
+ * actually produces. The old test also scanned the stack for "better-sqlite3",
+ * which every SqliteError's stack contains — so a plain query error ("near
+ * 'abc': syntax error") printed reinstall advice instead of itself. */
+export declare function isBindingsFailure(err: unknown): boolean;
+/** Extract the global flags (--vault <path>, --json) from anywhere in argv.
+ * Exported for the in-process dispatch tests. A flag sitting where the vault
+ * path should be means the value is missing — never consume it (the same
+ * value-position rule parseArgs applies to declared command flags). */
+export declare function extractGlobalFlags(args: string[]): {
+    rest: string[];
+    vaultFlag?: string;
+    json: boolean;
+};
 export declare function main(argv: string[]): Promise<void>;
+export {};