hafez 1.0.1

package/dist/cli/format.js

@@ -0,0 +1,158 @@
+export function formatEntityHeader(fm, body) {
+    const lines = [`# ${fm.name}`];
+    if (fm.description)
+        lines.push(`> ${fm.description}`);
+    const meta = [];
+    if (fm.status)
+        meta.push(`status: ${fm.status}`);
+    if (fm.type)
+        meta.push(`type: ${fm.type}`);
+    if (fm.domain?.length)
+        meta.push(`domain: ${fm.domain.join(', ')}`);
+    if (meta.length)
+        lines.push(meta.join(' | '));
+    const meta2 = [];
+    if (fm.parent)
+        meta2.push(`parent: ${fm.parent}`);
+    if (fm['last-touched'])
+        meta2.push(`last-touched: ${fm['last-touched']}`);
+    if (fm.created)
+        meta2.push(`created: ${fm.created}`);
+    if (meta2.length)
+        lines.push(meta2.join(' | '));
+    if (fm.related?.length)
+        lines.push(`related: ${fm.related.join(', ')}`);
+    if (fm.tags?.length)
+        lines.push(`tags: ${fm.tags.join(', ')}`);
+    if (fm.resource)
+        lines.push(`resource: ${fm.resource}`);
+    lines.push('');
+    lines.push(body);
+    return lines.join('\n');
+}
+export function formatKnowledgeHeader(fm, body) {
+    const lines = [`# ${fm.name}`];
+    if (fm.description)
+        lines.push(`> ${fm.description}`);
+    const meta = [];
+    if (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 (meta2.length)
+        lines.push(meta2.join(' | '));
+    if (fm.related?.length)
+        lines.push(`related: ${fm.related.join(', ')}`);
+    lines.push('');
+    lines.push(body);
+    return lines.join('\n');
+}
+export function formatQueryTable(results, total) {
+    if (results.length === 0)
+        return 'No results.';
+    const lines = ['| slug | name | type | status | next-action |', '|------|------|------|--------|-------------|'];
+    for (const r of results) {
+        let actionDisplay = r.next_action ?? '';
+        if (r.next_action && r.next_action_count > 1) {
+            actionDisplay = `${r.next_action} (+${r.next_action_count - 1} more)`;
+        }
+        lines.push(`| ${r.slug} | ${r.name} | ${r.type} | ${r.status} | ${actionDisplay} |`);
+    }
+    if (total != null && results.length < total) {
+        lines.push(`\nShowing ${results.length} of ${total}`);
+    }
+    return lines.join('\n');
+}
+export function formatKnowledgeTable(results, total) {
+    if (results.length === 0)
+        return 'No results.';
+    const lines = ['| slug | name | confidence | domains | reinforcements |', '|------|------|------------|---------|----------------|'];
+    for (const r of results) {
+        lines.push(`| ${r.slug} | ${r.name} | ${r.confidence} | ${r.domain.join(', ')} | ${r.reinforcement_count} |`);
+    }
+    if (total != null && results.length < total) {
+        lines.push(`\nShowing ${results.length} of ${total}`);
+    }
+    return lines.join('\n');
+}
+export function formatSearchResults(results) {
+    if (results.length === 0)
+        return 'No results.';
+    const entities = results.filter(r => r.kind === 'entity');
+    const knowledge = results.filter(r => r.kind === 'knowledge');
+    const sections = [];
+    if (entities.length > 0) {
+        const lines = ['## Entities', '', '| slug | name | type | match |', '|------|------|------|-------|'];
+        for (const r of entities)
+            lines.push(`| ${r.slug} | ${r.name} | ${r.type ?? ''} | ${r.snippet} |`);
+        sections.push(lines.join('\n'));
+    }
+    if (knowledge.length > 0) {
+        const lines = ['## Knowledge', '', '| slug | name | confidence | match |', '|------|------|------------|-------|'];
+        for (const r of knowledge)
+            lines.push(`| ${r.slug} | ${r.name} | ${r.confidence ?? ''} | ${r.snippet} |`);
+        sections.push(lines.join('\n'));
+    }
+    return sections.join('\n\n');
+}
+export function formatStats(stats) {
+    const lines = [];
+    lines.push('## Status Counts');
+    lines.push(`Active: ${stats.counts.active} | Paused: ${stats.counts.paused} | Done: ${stats.counts.done}`);
+    lines.push('\n## Type Counts');
+    lines.push(`Project: ${stats.by_type.project} | Entity: ${stats.by_type.entity} | Capture: ${stats.by_type.capture}`);
+    if (stats.stale.length > 0) {
+        lines.push('\n## Stale');
+        lines.push('| Slug | Type | Days |');
+        lines.push('|------|------|------|');
+        for (const s of stats.stale)
+            lines.push(`| ${s.slug} | ${s.type} | ${s.days_since_touched} |`);
+    }
+    if (stats.no_next_action.length > 0) {
+        lines.push('\n## Active Without Next Actions');
+        for (const s of stats.no_next_action)
+            lines.push(`- ${s.slug} (${s.type})`);
+    }
+    lines.push('\n## Recently Touched');
+    for (const s of stats.recently_touched)
+        lines.push(`- ${s.slug} (${s.last_touched})`);
+    lines.push('\n## Recently Created');
+    for (const s of stats.recently_created)
+        lines.push(`- ${s.slug} (${s.created})`);
+    return lines.join('\n');
+}
+export function formatChangelog(entries) {
+    if (entries.length === 0)
+        return 'No changes found.';
+    const header = '| Slug | Kind | Op | Date | Message |';
+    const sep = '|------|------|-----|------|---------|';
+    const rows = entries.map(e => `| ${e.slug} | ${e.kind} | ${e.operation} | ${e.timestamp.slice(0, 10)} | ${e.commit_message} |`);
+    return [header, sep, ...rows].join('\n');
+}
+export function formatValidation(report) {
+    const issues = report.broken_slugs.length + report.orphaned_knowledge.length +
+        report.oversized_related.length + report.missing_fields.length;
+    if (issues === 0) {
+        return `Vault OK — ${report.total_entities} entities, ${report.total_knowledge} knowledge, 0 issues`;
+    }
+    const sections = [`## Vault Validation — ${report.total_entities} entities, ${report.total_knowledge} knowledge`];
+    const addSection = (title, items) => {
+        if (items.length === 0)
+            return;
+        sections.push(`\n### ${title} (${items.length})`);
+        for (const item of items)
+            sections.push(`- ${item}`);
+    };
+    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/help-agent.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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

@@ -0,0 +1,158 @@
+// src/cli/help-agent.ts
+//
+// `hafez help --agent` — the prompt-gate. Plain text, no ANSI, no markdown
+// decoration. Designed for an LLM with zero Hafez context to read once per
+// 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.
+//
+// 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.
+import { listOps, getEnumValues, getOpExample, getOpSchema } from './schema-introspect.js';
+const PREAMBLE = `# Hafez — Agent Prompt Gate
+
+Hafez is your persistent knowledge graph for projects, entities, captures,
+knowledge notes, and session notes. The \`hafez\` CLI is the ONLY supported
+write path into the vault — never edit files under \`entities/\`, \`knowledge/\`,
+or \`sessions/\` by hand. Every mutation goes through the CLI so the git history,
+SQLite index, and link integrity stay in sync.
+
+Mental model:
+
+- An \`entity\` is tracked work with substance — a bug, a feature, a decision.
+  Entities have status, can have children, and carry a session log. The three
+  entity types are \`capture\` (raw inbox), \`entity\` (standalone tracked item),
+  and \`project\` (scoped effort with deliverables, can have child entities).
+- A \`knowledge\` note is an insight or a plan. Insights distil a pattern or
+  principle and mature through added evidence. Plans are structured steps
+  toward a goal. Knowledge is searchable, linkable, and timestamped.
+- A \`session\` note records what happened in a working session and references
+  the entities it touched. Session notes are created via \`create/session\`
+  and are not indexed in SQLite — they are for narrative, not query.
+- \`capture\` is the quick-inbox path: grab a link or thought, no structure.
+  A capture can later be promoted to entity, project, or knowledge.
+- Entities relate to each other through links: \`parent\` (hierarchy) or
+  \`related\` (soft reference). Use \`link\` / \`unlink\` ops to manage them.
+- Every meaningful update should include a session_log entry so the history
+  of the work is preserved. Sessions are how future-you reconstructs why a
+  decision was made.
+
+Single source of truth: the exact field names, enum values, and op signatures
+below are generated at runtime from the live Zod schema. If a field is not
+listed here, it does not exist — do not invent fields.
+
+## Hard rules (read before writing a batch)
+
+- ALWAYS batch 2+ mutations into one \`hafez batch\` call. Many single-op
+  calls fragment git history and clobber the vault index's atomicity guarantee.
+- NEVER invent field names. If a field is not in \`hafez schema <op>\`, it
+  does not exist. Unknown fields are rejected by the validator with a pointer
+  to the right schema.
+- NEVER write to vault files directly. Always go through the CLI.
+- STRONGLY PREFERRED: include a \`session_log\` on update ops that reflect
+  meaningful work. The validator does not enforce this — omitting it is a
+  code smell, not a hard error.
+- When in doubt, run \`hafez schema <op>\` before writing a batch. Cheap,
+  deterministic, no side effects.
+- Use \`hafez batch --dry-run\` to validate a payload without touching the
+  vault. Same errors, zero filesystem mutation.
+`;
+function renderOpCatalog() {
+    const lines = ['<!-- SECTION:op-catalog -->'];
+    lines.push('Ops (run `hafez schema <name>` for the full field list):');
+    for (const op of listOps()) {
+        const desc = op.description ? ` — ${op.description}` : '';
+        lines.push(`  ${op.name}${desc}`);
+        lines.push(`    → hafez schema ${op.name}`);
+    }
+    lines.push('<!-- /SECTION:op-catalog -->');
+    return lines.join('\n');
+}
+function renderCriticalEnums() {
+    const entries = [
+        ['update.fields.status', 'update.fields.status'],
+        ['update.fields.session_log.type', 'update.fields.session_log.type'],
+        ['update.fields.confidence', 'update.fields.confidence'],
+        ['create-entity.fields.type', 'create-entity.fields.type'],
+        ['create-knowledge.fields.subtype', 'create-knowledge.fields.subtype'],
+        ['link.relation', 'link.relation'],
+    ];
+    const lines = ['<!-- SECTION:critical-enums -->'];
+    lines.push('Critical enums (value lists — values are authoritative):');
+    for (const [label, path] of entries) {
+        const values = getEnumValues(path);
+        if (!values)
+            continue;
+        lines.push(`  ${label} = [${values.join(', ')}]`);
+    }
+    lines.push('<!-- /SECTION:critical-enums -->');
+    return lines.join('\n');
+}
+function renderBatchExamples() {
+    const lines = ['<!-- SECTION:batch-examples -->'];
+    lines.push('Batch JSON shape — wrap one or more ops in an array and pipe to stdin:');
+    lines.push('');
+    lines.push('  echo \'[...]\' | hafez batch');
+    lines.push('');
+    lines.push('Minimal example per op (canonical field names; aliased keys stripped):');
+    lines.push('');
+    for (const op of listOps()) {
+        const example = getOpExample(op.name);
+        if (!example)
+            continue;
+        lines.push(`# ${op.name}`);
+        lines.push(JSON.stringify(example, null, 2));
+        lines.push('');
+    }
+    lines.push('<!-- /SECTION:batch-examples -->');
+    return lines.join('\n');
+}
+function renderDigestSection() {
+    const lines = ['<!-- SECTION:digest -->'];
+    lines.push('Session digest — turn end-of-session context into a batch payload.');
+    lines.push('NOT a batch op: it reads its own JSON from stdin and prints batch JSON.');
+    lines.push('');
+    lines.push("  echo '<digest-json>' | hafez digest | hafez batch");
+    lines.push('');
+    lines.push('Input fields (`hafez schema digest` for the full schema):');
+    const schema = getOpSchema('digest');
+    for (const [name, field] of Object.entries(schema?.fields ?? {})) {
+        const req = field.optional ? 'optional' : 'required';
+        const desc = field.description ? ` — ${field.description}` : '';
+        lines.push(`  ${name} (${req})${desc}`);
+    }
+    lines.push('');
+    lines.push('Example input:');
+    lines.push(JSON.stringify(getOpExample('digest'), null, 2));
+    lines.push('<!-- /SECTION:digest -->');
+    return lines.join('\n');
+}
+const FOOTER = `## Lookup pointers
+
+- \`hafez schema\`                      — list all ops
+- \`hafez schema <op>\`                 — full JSON schema for one op
+- \`hafez schema <op> --examples\`      — working JSON examples per enum value
+- \`hafez batch --dry-run\`             — validate without touching the vault
+`;
+/**
+ * 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 function renderAgentHelp() {
+    return [
+        PREAMBLE,
+        renderOpCatalog(),
+        '',
+        renderCriticalEnums(),
+        '',
+        renderBatchExamples(),
+        '',
+        renderDigestSection(),
+        '',
+        FOOTER,
+    ].join('\n');
+}

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<void>;

package/dist/cli/index.js

@@ -0,0 +1,304 @@
+// src/cli/index.ts
+import { readFileSync } from 'fs';
+import { dirname, join, resolve } 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, cmdMigrateKnowledgeV2, cmdCapture } from './commands.js';
+import { cmdSchema } from './commands-schema.js';
+import { renderAgentHelp } from './help-agent.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');
+    },
+    stats: cmdStats,
+    changelog: cmdChangelog,
+    digest: cmdDigest,
+};
+// 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]
+
+Commands:
+  read <slug>                Read entity or knowledge note
+  query [--filter ...] ...   Filter entities/knowledge
+  search <terms>             Full-text search
+  create <kind> <name>       Create entity, knowledge, or inbox
+  capture <name> [--notes]   Quick inbox capture
+  promote <slug> <target>    Promote capture→entity/project/knowledge, entity→project
+  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
+    --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)
+  export --okf [--out <dir>] Export vault as an OKF v0.1 bundle (read-only)
+  sync                       Pull remote changes and push local commits
+  migrate next-actions       Migrate next-action frontmatter to body sections
+  migrate types              Migrate vault to v2 type system (dry-run by default)
+  migrate knowledge-v2       Migrate knowledge notes to v2 section structure (dry-run by default)
+    --apply                  Execute migration (writes files, does not commit)
+  link <slug> <target> <rel> Add a link
+  unlink <slug> <target> <rel> Remove a link
+  stats                      Vault summary: counts, stale items, recents
+  changelog --since <when>   Git-derived change history (e.g. --since 7.days.ago)
+  schema [op] [--examples]   Machine-readable JSON schema for batch operations
+  validate                   Check vault integrity
+  index rebuild              Rebuild the SQLite index
+  init --register <path>     Register an existing vault
+  init                       Show current vault resolution
+  help --agent               Full API reference for agents
+
+Global flags:
+  --vault <path>    Vault path (overrides config)
+  --json            JSON output (structured, machine-readable)
+  --version         Print the hafez version
+
+Vault discovery: --vault flag > ~/.config/hafez/vault
+`;
+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;
+        }
+        process.stdout.write(USAGE);
+        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');
+        }
+        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);
+            }
+            process.stderr.write(`Error: ${err.message}\n`);
+            process.exit(1);
+        }
+        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');
+            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);
+        }
+        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');
+            }
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err.message}\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    // migrate runs before Hafez instance creation
+    if (command === 'migrate') {
+        const subcommand = args[0];
+        if (subcommand === 'next-actions') {
+            const { migrateNextActions } = await import('../migrate-next-actions.js');
+            const apply = args.includes('--apply');
+            const report = migrateNextActions(vaultPath, apply);
+            const lines = [];
+            if (!apply)
+                lines.push('DRY RUN — use --apply to execute');
+            lines.push(`Candidates: ${report.candidates}`);
+            if (apply)
+                lines.push(`Migrated: ${report.migrated}`);
+            for (const d of report.details)
+                lines.push(`  ${d}`);
+            process.stdout.write(lines.join('\n') + '\n');
+            return;
+        }
+        if (subcommand === 'types') {
+            const { migrateTypes } = await import('../migrate-types.js');
+            const apply = args.includes('--apply');
+            const report = migrateTypes(vaultPath, apply);
+            const lines = [];
+            if (!apply) {
+                lines.push('DRY RUN — use --apply to execute');
+                lines.push('');
+            }
+            lines.push(`Type renames:         ${report.typeChanges}`);
+            lines.push(`Status renames:       ${report.statusChanges}`);
+            lines.push(`Subtypes added:       ${report.knowledgeSubtypeAdded}`);
+            lines.push(`Body restructures:    ${report.bodySectionsRestructured}`);
+            lines.push(`Malformed (skipped):  ${report.malformed.length}`);
+            if (report.malformed.length > 0) {
+                lines.push('');
+                lines.push('Malformed files (no type field):');
+                for (const f of report.malformed)
+                    lines.push(`  ⚠ ${f}`);
+            }
+            if (report.details.length > 0) {
+                lines.push('');
+                lines.push('Changes:');
+                for (const d of report.details)
+                    lines.push(`  ${d}`);
+            }
+            if (apply) {
+                lines.push('');
+                lines.push('Migration applied. Run `hafez index rebuild` to refresh the index.');
+            }
+            process.stdout.write(lines.join('\n') + '\n');
+            return;
+        }
+        if (subcommand === 'knowledge-v2') {
+            await cmdMigrateKnowledgeV2(args.slice(1), vaultPath);
+            return;
+        }
+        process.stderr.write('Usage: hafez migrate <next-actions|types|knowledge-v2> [--apply]\n');
+        process.exit(1);
+    }
+    // sync is handled specially — always runs, not gated by MUTATING_COMMANDS
+    if (command === 'sync') {
+        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);
+            }
+            process.stderr.write(`Error: ${err.message}\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 });
+        // Auto-sync after mutating commands
+        if (MUTATING_COMMANDS.has(command)) {
+            try {
+                await os.sync();
+            }
+            catch (syncErr) {
+                // Operation succeeded but sync failed — emit result with warning, exit 4
+                process.stdout.write(result + '\n');
+                process.stderr.write(`Warning: ${syncErr.message ?? syncErr.message}\n`);
+                process.exit(4);
+            }
+        }
+        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);
+        }
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(1);
+    }
+}

package/dist/cli/resolve-vault.d.ts

@@ -0,0 +1,13 @@
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export declare function readVaultConfig(): string | null;
+export declare function saveVaultConfig(vaultPath: string): void;
+/**
+ * Resolve vault path. Returns string or null.
+ * If config exists but points to a bad path, returns an error object instead.
+ */
+export declare function resolveVaultPath(flagValue?: string): string | null | {
+    error: string;
+};
+export declare function noVaultMessage(): string;
+export declare function cmdInit(args: string[], flagValue?: string): void;