hafez 1.3.0 → 2.0.0

package/dist/cli/format.d.ts

@@ -1,8 +1,12 @@
 import type { QueryResult, KnowledgeQueryResult, ValidationReport, SearchResult, VaultStats, ChangelogEntry } from '../types.js';
-export declare function formatEntityHeader(fm: Record<string, any>, body: string): string;
+/** `parent` is the rendered value of the `parent:` line (the slug with the
+ * parent's description); absent, the slug alone. */
+export declare function formatEntityHeader(fm: Record<string, any>, body: string, parent?: string | undefined): string;
 export declare function formatKnowledgeHeader(fm: Record<string, any>, body: string): string;
-export declare function formatQueryTable(results: QueryResult[], total?: number): string;
-export declare function formatKnowledgeTable(results: KnowledgeQueryResult[], total?: number): string;
+export type QueryTableRow = Pick<QueryResult, 'slug' | 'name' | 'type' | 'status' | 'next_action' | 'next_action_count'>;
+export declare function formatQueryTable(results: QueryTableRow[], total?: number): string;
+export type KnowledgeTableRow = Pick<KnowledgeQueryResult, 'slug' | 'name' | 'confidence' | 'domain' | 'reinforcement_count'>;
+export declare function formatKnowledgeTable(results: KnowledgeTableRow[], total?: number): string;
 export declare function formatSearchResults(results: SearchResult[]): string;
 export declare function formatStats(stats: VaultStats): string;
 export declare function formatChangelog(entries: ChangelogEntry[]): string;

package/dist/cli/format.js

@@ -1,4 +1,6 @@
-export function formatEntityHeader(fm, body) {
+/** `parent` is the rendered value of the `parent:` line (the slug with the
+ * parent's description); absent, the slug alone. */
+export function formatEntityHeader(fm, body, parent = fm.parent) {
     const lines = [`# ${fm.name}`];
     if (fm.description)
         lines.push(`> ${fm.description}`);
@@ -11,9 +13,10 @@ export function formatEntityHeader(fm, body) {
         meta.push(`domain: ${fm.domain.join(', ')}`);
     if (meta.length)
         lines.push(meta.join(' | '));
+    // The parent line stands alone: with its description it is a sentence.
+    if (parent)
+        lines.push(`parent: ${parent}`);
     const meta2 = [];
-    if (fm.parent)
-        meta2.push(`parent: ${fm.parent}`);
     if (fm['last-touched'])
         meta2.push(`last-touched: ${fm['last-touched']}`);
     if (fm.created)
@@ -34,18 +37,33 @@ export function formatKnowledgeHeader(fm, body) {
     const lines = [`# ${fm.name}`];
     if (fm.description)
         lines.push(`> ${fm.description}`);
+    // A plan has a lifecycle and no reinforcement: its subtype, status and
+    // dates; an insight its confidence and reinforcement.
+    const plan = fm.subtype === 'plan';
     const meta = [];
-    if (fm.confidence)
+    if (plan)
+        meta.push('subtype: plan');
+    if (plan && fm.status)
+        meta.push(`status: ${fm.status}`);
+    if (!plan && fm.confidence)
         meta.push(`confidence: ${fm.confidence}`);
     if (fm.domain?.length)
         meta.push(`domain: ${Array.isArray(fm.domain) ? fm.domain.join(', ') : fm.domain}`);
     if (meta.length)
         lines.push(meta.join(' | '));
     const meta2 = [];
-    if (fm['reinforcement-count'] != null)
-        meta2.push(`reinforcement-count: ${fm['reinforcement-count']}`);
-    if (fm['last-reinforced'])
-        meta2.push(`last-reinforced: ${fm['last-reinforced']}`);
+    if (plan) {
+        if (fm.created)
+            meta2.push(`created: ${fm.created}`);
+        if (fm['last-touched'])
+            meta2.push(`last-touched: ${fm['last-touched']}`);
+    }
+    else {
+        if (fm['reinforcement-count'] != null)
+            meta2.push(`reinforcement-count: ${fm['reinforcement-count']}`);
+        if (fm['last-reinforced'])
+            meta2.push(`last-reinforced: ${fm['last-reinforced']}`);
+    }
     if (meta2.length)
         lines.push(meta2.join(' | '));
     if (fm.related?.length)
@@ -143,7 +161,7 @@ export function formatChangelog(entries) {
 }
 export function formatValidation(report) {
     const issues = report.broken_slugs.length + report.orphaned_knowledge.length +
-        report.oversized_related.length + report.missing_fields.length;
+        report.missing_fields.length;
     if (issues === 0) {
         return `Vault OK — ${report.total_entities} entities, ${report.total_knowledge} knowledge, 0 issues`;
     }
@@ -157,7 +175,6 @@ export function formatValidation(report) {
     };
     addSection('Broken Slugs', report.broken_slugs.map(i => `${i.slug}: ${i.issue}`));
     addSection('Orphaned Knowledge', report.orphaned_knowledge.map(s => `${s} (no related links, not referenced by any entity)`));
-    addSection('Oversized Related', report.oversized_related.map(i => `${i.slug}: ${i.issue}`));
     addSection('Missing Fields', report.missing_fields.map(i => `${i.slug}: ${i.issue}`));
     return sections.join('\n');
 }

package/dist/cli/index.d.ts

@@ -1 +1,56 @@
+import { HafezError, type HafezErrorCode } from '../types.js';
+import { UsageError } from './args.js';
+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>;
+/** The one exit-code table. The error → exit adapter maps HafezError codes
+ * through `errorCodes`; `hafez --help` prints every row. 4 is the
+ * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
+export declare const EXIT_TABLE: ReadonlyArray<{
+    exit: number;
+    meaning: string;
+    errorCodes?: readonly HafezErrorCode[];
+}>;
+export declare const EXIT_CODES: Record<string, number>;
+/** 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: string;
+/** 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;
+/** The text half of the error adapter: what it prints for a usage or vault
+ * error. A misuse ends with the shape to retry from. */
+export declare function errorText(err: UsageError | HafezError): string;
+/** 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;
+};
+/** Is this the SessionStart hook's form, `onboard --block`? Read from the raw
+ * args, the token after `--vault` skipped, so it holds when parsing them fails. */
+export declare function isBlockHook(args: string[]): boolean;
 export declare function main(argv: string[]): Promise<void>;
+export {};

package/dist/cli/index.js

@@ -1,62 +1,102 @@
 // src/cli/index.ts
+//
+// Import discipline: this module is loaded for EVERY invocation, so it may
+// only import what every invocation needs — node builtins, the flag parser,
+// and the error type. Everything else (the core factory and its native SQLite
+// binding, zod-backed schema introspection, the markdown formatters, even
+// vault-path resolution) loads on demand from the command that needs it, so
+// `hafez --version` / `help` / `init` no longer pay for the whole program.
 import { readFileSync } from 'fs';
-import { dirname, join, resolve } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { createHafez } from '../index.js';
 import { HafezError } from '../types.js';
-import { parseArgs, UsageError } from './args.js';
-import { cmdRead, cmdQuery, cmdSearch, cmdCreate, cmdUpdate, cmdLink, cmdUnlink, cmdPromote, cmdValidate, cmdIndexRebuild, cmdBatch, cmdSync, cmdStats, cmdChangelog, cmdDigest, cmdCapture } from './commands.js';
-import { cmdSchema } from './commands-schema.js';
-import { renderAgentHelp } from './help-agent.js';
-import { renderOnboard } from './onboard.js';
-import { resolveVaultPath, noVaultMessage, cmdInit } from './resolve-vault.js';
-const COMMANDS = {
-    read: cmdRead,
-    sync: cmdSync,
-    query: cmdQuery,
-    search: cmdSearch,
-    create: cmdCreate,
-    capture: cmdCapture,
-    update: cmdUpdate,
-    link: cmdLink,
-    unlink: cmdUnlink,
-    promote: cmdPromote,
-    batch: cmdBatch,
-    schema: cmdSchema,
-    validate: cmdValidate,
-    index: (os, args) => {
-        if (args[0] === 'rebuild')
-            return cmdIndexRebuild(os);
-        throw new UsageError('Usage: hafez index rebuild');
+import { HelpRequest, MisuseError, RenderedError, UsageError, helpIfAsked } from './args.js';
+/** Bind a vault command to its handler without importing the handler module
+ * until the command actually runs. */
+function lazy(pick) {
+    return async (os, args, opts) => pick(await import('./commands.js'))(os, args, opts);
+}
+export const COMMANDS = {
+    // --- pre-vault ---
+    help: { phase: 'pre-vault', run: async (args) => (args[0] === '--agent' ? (await import('../surfaces/surfaces.js')).renderAgentHelp() : USAGE) },
+    onboard: { phase: 'pre-vault', run: async (args, ctx) => (await import('./onboard.js')).cmdOnboard(args, { vaultFlag: ctx.vaultFlag }) },
+    schema: { phase: 'pre-vault', run: async (args) => (await import('./commands-schema.js')).cmdSchema(null, args) },
+    version: { phase: 'pre-vault', run: () => versionLine() },
+    init: { phase: 'pre-vault', run: async (args, ctx) => { (await import('./resolve-vault.js')).cmdInit(args, ctx.vaultFlag); return null; } },
+    // Binds (args, ctx) explicitly: cmdUpgrade's third parameter is its
+    // dependency seam, and PreVaultRun's signature keeps dispatch from ever
+    // passing a third argument into it.
+    upgrade: { phase: 'pre-vault', run: async (args, ctx) => (await import('./upgrade.js')).cmdUpgrade(args, ctx) },
+    // --- vault ---
+    read: { phase: 'vault', run: lazy(m => m.cmdRead) },
+    sync: { phase: 'vault', run: lazy(m => m.cmdSync) },
+    query: { phase: 'vault', run: lazy(m => m.cmdQuery) },
+    search: { phase: 'vault', run: lazy(m => m.cmdSearch) },
+    create: { phase: 'vault', mutating: true, run: lazy(m => m.cmdCreate) },
+    capture: { phase: 'vault', mutating: true, run: lazy(m => m.cmdCapture) },
+    update: { phase: 'vault', mutating: true, run: lazy(m => m.cmdUpdate) },
+    link: { phase: 'vault', mutating: true, run: lazy(m => m.cmdLink) },
+    unlink: { phase: 'vault', mutating: true, run: lazy(m => m.cmdUnlink) },
+    promote: { phase: 'vault', mutating: true, run: lazy(m => m.cmdPromote) },
+    delete: { phase: 'vault', mutating: true, run: lazy(m => m.cmdDelete) },
+    batch: { phase: 'vault', mutating: true, run: lazy(m => m.cmdBatch) },
+    validate: { phase: 'vault', run: lazy(m => m.cmdValidate) },
+    index: {
+        phase: 'vault',
+        run: async (os, args) => {
+            const usage = 'Usage: hafez index rebuild';
+            helpIfAsked(args, usage);
+            if (args[0] === 'rebuild')
+                return (await import('./commands.js')).cmdIndexRebuild(os);
+            throw new UsageError(usage);
+        },
     },
-    stats: cmdStats,
-    changelog: cmdChangelog,
-    digest: cmdDigest,
+    stats: { phase: 'vault', run: lazy(m => m.cmdStats) },
+    changelog: { phase: 'vault', run: lazy(m => m.cmdChangelog) },
+    digest: { phase: 'vault', run: lazy(m => m.cmdDigest) },
+    export: { phase: 'vault', run: lazy(m => m.cmdExport) },
 };
-// Commands that modify vault files — auto-sync after these
-const MUTATING_COMMANDS = new Set(['update', 'create', 'capture', 'link', 'unlink', 'batch', 'promote']);
-const USAGE = `Usage: hafez <command> [args]
+/** The one exit-code table. The error → exit adapter maps HafezError codes
+ * through `errorCodes`; `hafez --help` prints every row. 4 is the
+ * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
+export const EXIT_TABLE = [
+    { exit: 0, meaning: 'success' },
+    { exit: 1, meaning: 'not found (slug, command or vault) / unknown error', errorCodes: ['NOT_FOUND'] },
+    { exit: 2, meaning: 'validation or usage error (bad flags, bad payload, core rejected the write)', errorCodes: ['VALIDATION_FAILED'] },
+    { exit: 3, meaning: 'git push failed — the write IS committed locally', errorCodes: ['GIT_PUSH_FAILED'] },
+    { exit: 4, meaning: 'write succeeded but the auto-sync after it failed' },
+    { exit: 5, meaning: 'slug already exists', errorCodes: ['SLUG_EXISTS'] },
+    { exit: 6, meaning: 'git commit failed — nothing was written to history', errorCodes: ['GIT_COMMIT_FAILED'] },
+    { exit: 7, meaning: 'vault locked by another hafez process — retry when it finishes', errorCodes: ['VAULT_LOCKED'] },
+];
+export const EXIT_CODES = Object.fromEntries(EXIT_TABLE.flatMap(row => (row.errorCodes ?? []).map(code => [code, row.exit])));
+/** Exported so a guard test can assert every registered command is documented
+ * here — a registered-but-undocumented command is otherwise invisible. */
+export const USAGE = `Usage: hafez <command> [args]
 
 Commands:
   read <slug>                Read entity or knowledge note
   query [--filter ...] ...   Filter entities/knowledge
+    --kind all               Both kinds; --filter matches entity status only,
+                             so knowledge notes (which have none) always show
   search <terms>             Full-text search
   create <kind> <name>       Create entity or knowledge note
   capture <name> [--notes]   Quick inbox capture
   promote <slug> <target>    Promote capture→entity/project/knowledge, entity→project
+  delete <slug>              Delete a knowledge or session note (an entity: update --status done)
   update <slug> [--status]   Update an entity or knowledge note
     --brief "text"           Set/replace Brief (use --brief "" to clear)
     --description "text"     Set one-line description (use --description "" to clear)
     --resource "uri"         Set canonical resource URI, entities only (use --resource "" to clear)
     --add-action "text"      Add a next action
-    --complete-action "text"  Complete matching action
-    --remove-action "text"   Remove matching action
+    --complete-action handle-or-text  Complete the action with that Handle (as read shows it), else the matching one
+    --remove-action handle-or-text    Remove the action with that Handle, else the matching one
     --clear-actions          Remove all next actions
     --synthesis "text"       Set/replace Synthesis section (--insight is an alias)
     --add-evidence "text"    Append to Evidence section
     --add-source "text"      Append to Sources section
-  batch                      Apply multiple operations atomically (JSON on stdin)
-  digest                     Apply digest input (JSON stdin) → batch payload (JSON stdout)
+  batch                      Apply multiple operations atomically (JSON on stdin, --data or --file)
+  digest                     Apply digest input (JSON on stdin, --data or --file) → batch payload (JSON stdout)
   export --okf [--out <dir>] Export vault as an OKF v0.1 bundle (read-only)
   sync                       Pull remote changes and push local commits
   link <slug> <target> --relation <rel>    Add a link
@@ -68,8 +108,14 @@ Commands:
   index rebuild              Rebuild the SQLite index
   init --register <path>     Register an existing vault
   init                       Show current vault resolution
-  onboard                    Agent-directed first run: seed the vault, pick integration level
-  help --agent               Full API reference for agents
+  onboard                    Setup status, then the script your agent follows to set Hafez up
+    --install --mode <always-on|invoke-only> [--harness <h>] [--confirm]
+                             Write both skills and, always-on, the Block
+    --remove [--confirm]     Remove the skills and the Block region
+    --block [--harness <h>]  Print the Block and the entities matching this folder
+                             (the SessionStart hook; prints nothing on any failure)
+  upgrade                    Check whether hafez is outdated and print the update steps
+  help --agent               The hafez skill body: the reference when the skill is not installed
 
 Global flags:
   --vault <path>    Vault path (overrides config)
@@ -77,41 +123,68 @@ Global flags:
   --version         Print the hafez version
 
 Vault discovery: --vault flag > ~/.config/hafez/vault
+
+Exit codes:
+${EXIT_TABLE.map(row => `  ${row.exit}  ${row.meaning}`).join('\n')}
 `;
-/** Exit codes, documented in `hafez help --agent`. 0 = success; 4 is the
- * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
-const EXIT_CODES = {
-    NOT_FOUND: 1,
-    VALIDATION_FAILED: 2,
-    GIT_PUSH_FAILED: 3,
-    SLUG_EXISTS: 5,
-    GIT_COMMIT_FAILED: 6,
-    VAULT_LOCKED: 7,
-};
+/** 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 function exitCodeFor(err) {
+    if (err instanceof HelpRequest)
+        return 0;
+    if (err instanceof UsageError)
+        return 2;
+    if (err instanceof HafezError)
+        return EXIT_CODES[err.code] ?? 1;
+    return 1;
+}
+/** The text half of the error adapter: what it prints for a usage or vault
+ * error. A misuse ends with the shape to retry from. */
+export function errorText(err) {
+    const lines = [`Error: ${err.message}`];
+    if (err instanceof HafezError)
+        for (const detail of err.details ?? [])
+            lines.push(`  - ${detail}`);
+    if (err instanceof MisuseError)
+        lines.push('', err.shape);
+    return lines.join('\n') + '\n';
+}
 /** The one error → exit adapter. Usage errors (bad flags/args) are distinct
  * from vault errors and from unknown crashes. */
 function report(err) {
-    if (err instanceof UsageError) {
-        process.stderr.write(`Error: ${err.message}\n`);
-        process.exit(2);
+    if (err instanceof HelpRequest) {
+        process.stdout.write(err.usage + '\n');
+        process.exit(exitCodeFor(err));
     }
-    if (err instanceof HafezError) {
-        process.stderr.write(`Error: ${err.message}\n`);
-        if (err.details?.length) {
-            for (const detail of err.details)
-                process.stderr.write(`  - ${detail}\n`);
-        }
-        process.exit(EXIT_CODES[err.code] ?? 1);
+    if (err instanceof RenderedError) {
+        process[err.stream].write(err.output + '\n');
+        process.exit(exitCodeFor(err));
+    }
+    if (err instanceof UsageError || err instanceof HafezError) {
+        process.stderr.write(errorText(err));
+        process.exit(exitCodeFor(err));
     }
     failUnknown(err);
 }
+/** 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 function isBindingsFailure(err) {
+    const message = err?.message;
+    if (typeof message !== 'string')
+        return false;
+    return /Could not locate the bindings file|better_sqlite3\.node|was compiled against a different Node\.js version|NODE_MODULE_VERSION|invalid ELF header/i.test(message);
+}
 // Terminal handler for non-Hafez errors. Special-cases unbuilt better-sqlite3
 // bindings: npm 11+ blocks install scripts by default, so `npm install -g
 // hafez` reports success with the native module unbuilt and the first indexed
 // command dies here — guide instead of stack-tracing.
 function failUnknown(err) {
     const e = err;
-    if (/better[-_]sqlite3|Could not locate the bindings file/i.test(`${e.message}\n${e.stack ?? ''}`)) {
+    if (isBindingsFailure(e)) {
         process.stderr.write('Error: the SQLite bindings (better-sqlite3) are not built.\n' +
             'npm 11+ blocks install scripts by default, so the install reports success\n' +
             'while skipping the native build. Fix with:\n\n' +
@@ -121,108 +194,95 @@ function failUnknown(err) {
     process.stderr.write(`Error: ${e.message}\n`);
     process.exit(1);
 }
-export async function main(argv) {
-    const args = argv.slice(2);
-    // Extract global flags
-    const vaultIdx = args.indexOf('--vault');
-    let flagValue;
-    if (vaultIdx !== -1) {
-        flagValue = args[vaultIdx + 1];
-        args.splice(vaultIdx, 2);
-    }
-    const jsonIdx = args.indexOf('--json');
-    const json = jsonIdx !== -1;
-    if (json)
-        args.splice(jsonIdx, 1);
-    const command = args.shift();
-    if (!command || command === '--help' || command === '-h') {
-        process.stdout.write(USAGE);
-        return;
-    }
-    if (command === '--version' || command === '-v' || command === 'version') {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf-8'));
-        process.stdout.write(`hafez ${pkg.version}\n`);
-        return;
+function versionLine() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf-8'));
+    return `hafez ${pkg.version}`;
+}
+/** 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 function extractGlobalFlags(args) {
+    const rest = [];
+    let vaultFlag;
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--vault') {
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith('--'))
+                throw new UsageError('--vault requires a path value');
+            // The old one-shot extraction left a second --vault in the command args
+            // where the declared-flag parser rejected it — keep failing loudly
+            // rather than silently letting the last one win (a mutating command
+            // would write to a different vault than the first flag named).
+            if (vaultFlag !== undefined)
+                throw new UsageError('--vault specified more than once');
+            vaultFlag = v;
+            i++;
+        }
+        else if (a === '--json') {
+            json = true;
+        }
+        else {
+            rest.push(a);
+        }
     }
-    // help runs before vault resolution — works without a registered vault
-    if (command === 'help') {
-        if (args[0] === '--agent') {
-            process.stdout.write(renderAgentHelp());
+    return { rest, vaultFlag, json };
+}
+/** Is this the SessionStart hook's form, `onboard --block`? Read from the raw
+ * args, the token after `--vault` skipped, so it holds when parsing them fails. */
+export function isBlockHook(args) {
+    const command = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--vault');
+    return command === 'onboard' && args.includes('--block');
+}
+export async function main(argv) {
+    // The hook must never block a session: under `onboard --block` any failure
+    // at all, a bad flag included, prints nothing and exits 0 (#132).
+    const hook = isBlockHook(argv.slice(2));
+    try {
+        const { rest: args, vaultFlag, json } = extractGlobalFlags(argv.slice(2));
+        const command = args.shift();
+        if (!command || command === '--help' || command === '-h') {
+            process.stdout.write(USAGE);
             return;
         }
-        process.stdout.write(USAGE);
-        return;
-    }
-    // onboard runs before vault resolution — static agent-directed text
-    if (command === 'onboard') {
-        process.stdout.write(renderOnboard());
-        return;
-    }
-    // schema runs before vault resolution — pure Zod introspection, no vault needed.
-    if (command === 'schema') {
-        try {
-            const result = await cmdSchema(null, args);
-            process.stdout.write(result + '\n');
+        const name = command === '--version' || command === '-v' ? 'version' : command;
+        const spec = Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : undefined;
+        if (!spec) {
+            // `list` is the command agents guess for listing the vault (#30).
+            const hint = command === 'list' ? '. To list the vault: hafez query --filter active' : '';
+            process.stderr.write(`Unknown command: ${command}${hint}\n${USAGE}`);
+            process.exit(1);
         }
-        catch (err) {
-            report(err);
+        if (spec.phase === 'pre-vault') {
+            const out = await spec.run(args, { json, vaultFlag });
+            if (out !== null)
+                process.stdout.write(out.endsWith('\n') ? out : out + '\n');
+            return;
         }
-        return;
-    }
-    // init runs before vault resolution
-    if (command === 'init') {
-        cmdInit(args, flagValue);
-        return;
-    }
-    // Resolve vault
-    const resolution = resolveVaultPath(flagValue);
-    if (resolution === null) {
-        process.stderr.write(noVaultMessage());
-        process.exit(1);
-    }
-    if (typeof resolution === 'object' && 'error' in resolution) {
-        process.stderr.write(`Error: ${resolution.error}\n`);
-        process.exit(1);
-    }
-    const vaultPath = resolution;
-    // export runs before Hafez instance creation — read-only, no auto-sync
-    if (command === 'export') {
-        try {
-            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');
-            const { exportOkf } = await import('../export-okf.js');
-            const exportReport = exportOkf(vaultPath, outDir);
-            if (json) {
-                process.stdout.write(JSON.stringify(exportReport, null, 2) + '\n');
-            }
-            else {
-                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}`);
-                process.stdout.write(lines.join('\n') + '\n');
-            }
+        // Resolve vault (loaded here, not at module top: the pre-vault commands
+        // above return without ever needing the vault machinery)
+        const { resolveVaultPath, noVaultMessage } = await import('./resolve-vault.js');
+        const resolution = resolveVaultPath(vaultFlag);
+        if (resolution === null) {
+            process.stderr.write(noVaultMessage());
+            process.exit(1);
         }
-        catch (err) {
-            report(err);
+        if (typeof resolution === 'object' && 'error' in resolution) {
+            process.stderr.write(`Error: ${resolution.error}\n`);
+            process.exit(1);
         }
-        return;
-    }
-    const handler = COMMANDS[command];
-    if (!handler) {
-        process.stderr.write(`Unknown command: ${command}\n${USAGE}`);
-        process.exit(1);
-    }
-    const os = createHafez({ vaultPath, git: { push: false } });
-    try {
-        const result = await handler(os, args, { json });
+        const vaultPath = resolution;
+        // First touch of the core — and so of the native SQLite binding. A
+        // failure to load it lands in the catch below and is recognised by
+        // isBindingsFailure, exactly as it was when this import was static.
+        const { createHafez } = await import('../index.js');
+        const os = createHafez({ vaultPath, git: { push: false } });
+        const result = await spec.run(os, args, { json, vaultPath });
         // Auto-sync after mutating commands
-        if (MUTATING_COMMANDS.has(command)) {
+        if (spec.mutating) {
             try {
                 await os.sync();
             }
@@ -236,6 +296,8 @@ export async function main(argv) {
         process.stdout.write(result + '\n');
     }
     catch (err) {
+        if (hook)
+            return;
         report(err);
     }
 }