hafez 1.2.0 → 1.4.0

package/dist/cli/help-agent.d.ts

@@ -1,6 +1 @@
-/**
- * Render the full prompt-gate output. Token budget: 1500-3000 tokens when
- * measured as char/3.5. The drift test in tests/cli-help-agent.test.ts
- * enforces the ceiling.
- */
 export declare function renderAgentHelp(): string;

package/dist/cli/help-agent.js

@@ -5,12 +5,13 @@
 // session and then produce valid batch JSON on first try.
 //
 // Hand-written sections: Preamble + Hard rules (prose, free-form).
-// Generated sections (wrapped in <!-- SECTION:name --> markers so the drift
-// test can parse them): op-catalog, critical-enums, batch-examples, digest.
+// Generated sections (wrapped in <!-- SECTION:name --> markers so tests can
+// parse them): op-catalog, critical-enums, batch-examples, digest.
 //
-// If the generated sections drift from the Zod schema, the drift test fails
-// loudly. Do NOT enumerate enum values inside the preamble or hard rules —
-// those come from schema-introspect.ts.
+// Generated sections derive from the Op Spec table (batch-ops.ts via
+// schema-introspect.ts), so they cannot drift from the Zod schemas. Do NOT
+// enumerate enum values inside the preamble or hard rules — those come from
+// schema-introspect.ts.
 import { listOps, getEnumValues, getOpExample, getOpSchema } from './schema-introspect.js';
 const PREAMBLE = `# Hafez — Agent Prompt Gate
 
@@ -143,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
@@ -155,6 +179,18 @@ const FOOTER = `## Lookup pointers
  * measured as char/3.5. The drift test in tests/cli-help-agent.test.ts
  * enforces the ceiling.
  */
+const EXIT_CODES_SECTION = `## Exit codes
+
+| code | meaning |
+|------|---------|
+| 0 | success |
+| 1 | not found / unknown error |
+| 2 | validation or usage error (bad flags, bad payload, core rejected the write) |
+| 3 | git push failed — the write IS committed locally |
+| 4 | write succeeded but the auto-sync after it failed |
+| 5 | slug already exists |
+| 6 | git commit failed — nothing was written to history |
+| 7 | vault locked by another hafez process — retry when it finishes |`;
 export function renderAgentHelp() {
     return [
         PREAMBLE,
@@ -166,6 +202,9 @@ export function renderAgentHelp() {
         '',
         renderDigestSection(),
         '',
+        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 {};

package/dist/cli/index.js

@@ -1,43 +1,67 @@
 // 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 { 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,
-    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 Error('Usage: hafez index rebuild');
+import { UsageError } 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('./help-agent.js')).renderAgentHelp() : USAGE) },
+    onboard: { phase: 'pre-vault', run: async () => (await import('./onboard.js')).renderOnboard() },
+    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) },
+    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) => {
+            if (args[0] === 'rebuild')
+                return (await import('./commands.js')).cmdIndexRebuild(os);
+            throw new UsageError('Usage: hafez index rebuild');
+        },
     },
-    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]
+/** 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
@@ -67,6 +91,7 @@ Commands:
   init --register <path>     Register an existing vault
   init                       Show current vault resolution
   onboard                    Agent-directed first run: seed the vault, pick integration level
+  upgrade                    Check whether hafez is outdated and print the update steps
   help --agent               Full API reference for agents
 
 Global flags:
@@ -76,13 +101,61 @@ Global flags:
 
 Vault discovery: --vault flag > ~/.config/hafez/vault
 `;
+/** Exit codes, documented in `hafez help --agent`. 0 = success; 4 is the
+ * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
+export 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 UsageError)
+        return 2;
+    if (err instanceof HafezError)
+        return EXIT_CODES[err.code] ?? 1;
+    return 1;
+}
+/** 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(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(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' +
@@ -92,147 +165,84 @@ 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;
-    }
-    // help runs before vault resolution — works without a registered vault
-    if (command === 'help') {
-        if (args[0] === '--agent') {
-            process.stdout.write(renderAgentHelp());
-            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++;
         }
-        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');
+        else if (a === '--json') {
+            json = true;
         }
-        catch (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(2);
-            }
-            failUnknown(err);
+        else {
+            rest.push(a);
         }
-        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') {
-        if (!args.includes('--okf')) {
-            process.stderr.write('Usage: hafez export --okf [--out <dir>]\n');
+    return { rest, vaultFlag, json };
+}
+export async function main(argv) {
+    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;
+        }
+        const name = command === '--version' || command === '-v' ? 'version' : command;
+        const spec = COMMANDS[name];
+        if (!spec) {
+            process.stderr.write(`Unknown command: ${command}\n${USAGE}`);
             process.exit(1);
         }
-        const outIdx = args.indexOf('--out');
-        let outDir = resolve(process.cwd(), 'okf-export');
-        if (outIdx !== -1) {
-            const outValue = args[outIdx + 1];
-            if (!outValue) {
-                process.stderr.write('Usage: hafez export --okf [--out <dir>]\n');
-                process.exit(1);
-            }
-            outDir = resolve(outValue);
+        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;
         }
-        const { exportOkf } = await import('../export-okf.js');
-        try {
-            const report = exportOkf(vaultPath, outDir);
-            if (json) {
-                process.stdout.write(JSON.stringify(report, null, 2) + '\n');
-            }
-            else {
-                const lines = [`Exported ${report.entities} entities, ${report.knowledge} knowledge, ${report.sessions} sessions to ${report.outDir}`];
-                for (const s of report.skipped)
-                    lines.push(`  skipped ${s.file}: ${s.reason}`);
-                if (report.unresolvedLinks > 0)
-                    lines.push(`  unresolved links: ${report.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) {
-            failUnknown(err);
+        if (typeof resolution === 'object' && 'error' in resolution) {
+            process.stderr.write(`Error: ${resolution.error}\n`);
+            process.exit(1);
         }
-        return;
-    }
-    // sync is handled specially — always runs, not gated by MUTATING_COMMANDS
-    if (command === 'sync') {
+        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 } });
-        try {
-            const result = await cmdSync(os, args);
-            process.stdout.write(result + '\n');
-        }
-        catch (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`);
-                    }
-                }
-                const exitCodes = { NOT_FOUND: 1, VALIDATION_FAILED: 2, GIT_PUSH_FAILED: 3 };
-                process.exit(exitCodes[err.code] ?? 1);
-            }
-            failUnknown(err);
-        }
-        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 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();
             }
@@ -246,16 +256,6 @@ export async function main(argv) {
         process.stdout.write(result + '\n');
     }
     catch (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`);
-                }
-            }
-            const exitCodes = { NOT_FOUND: 1, VALIDATION_FAILED: 2, GIT_PUSH_FAILED: 3 };
-            process.exit(exitCodes[err.code] ?? 1);
-        }
-        failUnknown(err);
+        report(err);
     }
 }

package/dist/cli/resolve-vault.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs
 import { join, resolve } from 'path';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
+import { kindDir } from '../vault.js';
 export function getConfigDir() {
     const xdg = process.env.XDG_CONFIG_HOME;
     return join(xdg || join(homedir(), '.config'), 'hafez');
@@ -28,7 +29,7 @@ export function saveVaultConfig(vaultPath) {
     writeFileSync(join(dir, 'vault'), resolve(vaultPath) + '\n');
 }
 function isVault(dirPath) {
-    return existsSync(dirPath) && statSync(dirPath).isDirectory() && existsSync(join(dirPath, 'entities'));
+    return existsSync(dirPath) && statSync(dirPath).isDirectory() && existsSync(join(dirPath, kindDir('entity')));
 }
 /**
  * Resolve vault path. Returns string or null.

package/dist/cli/schema-introspect.d.ts

@@ -1,4 +1,4 @@
-import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema } from './commands.js';
+import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema } from '../batch-ops.js';
 export interface FieldSchema {
     type: string;
     optional?: boolean;

package/dist/cli/schema-introspect.js

@@ -10,7 +10,7 @@
 // types actually used in BatchOperationSchema plus a few forward-looking ones
 // (`default`, `effects`, `union`) so the walker does not explode when the
 // schema is extended.
-import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema, } from './commands.js';
+import { BatchOperationSchema, SessionLogSchema, UpdateFieldsSchema, OP_SPECS, } from '../batch-ops.js';
 import { DigestInputSchema } from '../digest.js';
 import { ALIAS_KEYS } from '../contracts.js';
 // --- Walker ---
@@ -155,16 +155,8 @@ export const DIGEST_EXAMPLE = {
     session_date: '2026-01-15',
     agent: 'claude',
 };
-const OP_DESCRIPTIONS = {
-    'update': 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …).',
-    'create-entity': 'Create a new entity (capture / entity / project).',
-    'create-knowledge': 'Create a new knowledge note (insight / plan subtype).',
-    'create-session': 'Create a new session note linked to an entity.',
-    'capture': 'Quick capture — a raw inbox item with no structure required.',
-    'link': 'Add a parent or related link between two entities.',
-    'unlink': 'Remove a parent or related link between two entities.',
-    'promote': 'Promote a capture to entity/project/knowledge, or an entity to project.',
-};
+// Descriptions live in the Op Spec table (src/batch-ops.ts) — one row per op.
+const OP_DESCRIPTIONS = Object.fromEntries(OP_SPECS.map(s => [s.name, s.description]));
 export function listOps() {
     return enumerateBranches().map(({ op, kind }) => {
         const name = kind ? `${op}-${kind}` : op;
@@ -293,17 +285,9 @@ function shouldStrip(path, _key) {
     return Object.prototype.hasOwnProperty.call(ALIAS_KEYS, path);
 }
 function isDefaultIncluded(op, kind, fieldKey) {
-    if (op === 'create' && kind === 'entity' && fieldKey === 'type')
-        return true;
-    if (op === 'create' && kind === 'knowledge' && (fieldKey === 'subtype' || fieldKey === 'synthesis'))
-        return true;
-    if (op === 'create' && kind === 'session' && fieldKey === 'synthesis')
-        return true;
-    if (op === 'update' && fieldKey === 'status')
-        return true;
-    if (op === 'capture' && fieldKey === 'notes')
-        return true;
-    return false;
+    // Example-inclusion hints live in the Op Spec table, one row per op.
+    const spec = OP_SPECS.find(s => s.op === op && s.kind === kind);
+    return spec ? spec.exampleInclude.includes(fieldKey) : false;
 }
 function sampleValue(field) {
     switch (field.type) {