hafez 1.1.0 → 1.3.0

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
 
@@ -58,7 +59,17 @@ listed here, it does not exist — do not invent fields.
 - 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.
+  vault. Same validation as a real apply, zero filesystem mutation.
+
+## Slug contract (create-then-link in one batch)
+
+Slugs are deterministic: slug = slugify(name) — lowercase, non-alphanumeric
+runs collapse to single \`-\`, edges trimmed (\`"Auth Refactor!"\` →
+\`auth-refactor\`). A batch executes sequentially, so later ops may reference
+the slugs of earlier creates in the same batch (\`create\` then \`link\`/\`update\`
+works in one payload). Collisions hard-error — a wrong slug prediction can
+never silently hit an existing document. To verify predictions first:
+\`hafez batch --dry-run\` reports the derived slug for every create op.
 `;
 function renderOpCatalog() {
     const lines = ['<!-- SECTION:op-catalog -->'];
@@ -93,9 +104,10 @@ function renderCriticalEnums() {
 }
 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('Batch JSON shape — wrap one or more ops in an array:');
     lines.push('');
-    lines.push('  echo \'[...]\' | hafez batch');
+    lines.push('  echo \'[...]\' | hafez batch          # POSIX shells');
+    lines.push('  hafez batch --file payload.json     # any platform (PowerShell 5.1 cannot pipe stdin)');
     lines.push('');
     lines.push('Minimal example per op (canonical field names; aliased keys stripped):');
     lines.push('');
@@ -113,9 +125,11 @@ function renderBatchExamples() {
 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('NOT a batch op: it reads its own JSON and prints batch JSON.');
     lines.push('');
     lines.push("  echo '<digest-json>' | hafez digest | hafez batch");
+    lines.push('  # No stdin pipes (PowerShell 5.1): hafez digest --file summary.json > ops.json,');
+    lines.push('  # then hafez batch --file ops.json');
     lines.push('');
     lines.push('Input fields (`hafez schema digest` for the full schema):');
     const schema = getOpSchema('digest');
@@ -142,6 +156,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,
@@ -153,6 +179,8 @@ export function renderAgentHelp() {
         '',
         renderDigestSection(),
         '',
+        EXIT_CODES_SECTION,
+        '',
         FOOTER,
     ].join('\n');
 }

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import { dirname, join, resolve } 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';
@@ -11,6 +12,7 @@ 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,
@@ -25,7 +27,7 @@ const COMMANDS = {
     index: (os, args) => {
         if (args[0] === 'rebuild')
             return cmdIndexRebuild(os);
-        throw new Error('Usage: hafez index rebuild');
+        throw new UsageError('Usage: hafez index rebuild');
     },
     stats: cmdStats,
     changelog: cmdChangelog,
@@ -76,6 +78,49 @@ 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. */
+const EXIT_CODES = {
+    NOT_FOUND: 1,
+    VALIDATION_FAILED: 2,
+    GIT_PUSH_FAILED: 3,
+    SLUG_EXISTS: 5,
+    GIT_COMMIT_FAILED: 6,
+    VAULT_LOCKED: 7,
+};
+/** 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 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);
+    }
+    failUnknown(err);
+}
+// 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 ?? ''}`)) {
+        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' +
+            '  npm install -g hafez --allow-scripts=better-sqlite3\n');
+        process.exit(1);
+    }
+    process.stderr.write(`Error: ${e.message}\n`);
+    process.exit(1);
+}
 export async function main(argv) {
     const args = argv.slice(2);
     // Extract global flags
@@ -121,16 +166,7 @@ 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`);
-                }
-                process.exit(2);
-            }
-            process.stderr.write(`Error: ${err.message}\n`);
-            process.exit(1);
+            report(err);
         }
         return;
     }
@@ -152,61 +188,28 @@ export async function main(argv) {
     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);
+            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(report, null, 2) + '\n');
+                process.stdout.write(JSON.stringify(exportReport, 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)
+                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 (report.unresolvedLinks > 0)
-                    lines.push(`  unresolved links: ${report.unresolvedLinks}`);
+                if (exportReport.unresolvedLinks > 0)
+                    lines.push(`  unresolved links: ${exportReport.unresolvedLinks}`);
                 process.stdout.write(lines.join('\n') + '\n');
             }
         }
         catch (err) {
-            process.stderr.write(`Error: ${err.message}\n`);
-            process.exit(1);
-        }
-        return;
-    }
-    // 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);
+            report(err);
         }
         return;
     }
@@ -233,17 +236,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);
-        }
-        process.stderr.write(`Error: ${err.message}\n`);
-        process.exit(1);
+        report(err);
     }
 }

package/dist/cli/onboard.d.ts

@@ -1,2 +1,2 @@
-export declare const INTEGRATION_SNIPPET = "## Hafez \u2014 Session Memory\n\n- Session start: if the first message names a project or topic, load context\n  with `hafez read <slug>` (or `hafez search \"<topic>\"`). Don't load\n  speculatively.\n- Mid-session: new workstream -> create an entity. Durable insight -> create\n  or update a knowledge note (search first). User mentions a project by\n  name -> check if it's a Hafez entity. Use `hafez batch` for 2+ mutations.\n- Session end: record a digest (`hafez digest | hafez batch`) with the\n  entities touched, decisions made, and a short narrative.\n- Knowledge boundary: useful beyond this repo/session -> vault knowledge\n  note. Specific to one repo's code -> that repo's own docs, not the vault.";
+export declare const INTEGRATION_SNIPPET = "## Hafez \u2014 Session Memory\n\n- Session start: if the first message names a project or topic, load context\n  with `hafez read <slug>` (or `hafez search \"<topic>\"`). Don't load\n  speculatively.\n- Mid-session: new workstream -> create an entity. Durable insight -> create\n  or update a knowledge note (search first). User mentions a project by\n  name -> check if it's a Hafez entity. Use `hafez batch` for 2+ mutations.\n- Session end: record a digest (`hafez digest | hafez batch`; on shells\n  that can't pipe, e.g. PowerShell 5.1: `--file` on both) with the\n  entities touched, decisions made, and a short narrative.\n- Knowledge boundary: useful beyond this repo/session -> vault knowledge\n  note. Specific to one repo's code -> that repo's own docs, not the vault.";
 export declare function renderOnboard(): string;

package/dist/cli/onboard.js

@@ -16,7 +16,8 @@ export const INTEGRATION_SNIPPET = `## Hafez — Session Memory
 - Mid-session: new workstream -> create an entity. Durable insight -> create
   or update a knowledge note (search first). User mentions a project by
   name -> check if it's a Hafez entity. Use \`hafez batch\` for 2+ mutations.
-- Session end: record a digest (\`hafez digest | hafez batch\`) with the
+- Session end: record a digest (\`hafez digest | hafez batch\`; on shells
+  that can't pipe, e.g. PowerShell 5.1: \`--file\` on both) with the
   entities touched, decisions made, and a short narrative.
 - Knowledge boundary: useful beyond this repo/session -> vault knowledge
   note. Specific to one repo's code -> that repo's own docs, not the vault.`;
@@ -31,6 +32,11 @@ Prerequisites: \`hafez init\` resolves a vault, and you have read
 no other pieces are required. If your harness is Claude Code, also install
 the bundled skill — see the README Setup (github.com/shrvn-r/hafez).
 
+Re-running onboard is normal and intended: on a vault that is already set
+up and integrated, skip Step 2 and use Step 1 as a seeding interview for
+whatever is new since last time. Seed current, active work — seeding never
+means documenting the past; using the vault as you go stays primary.
+
 ## Step 1 — Seed the vault
 
 An empty vault gives the agent nothing to trigger on, so the memory loop

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) {

package/dist/cli.js

@@ -1,3 +1,21 @@
 #!/usr/bin/env node
-import { main } from './cli/index.js';
-main(process.argv);
+// Dynamic import so a failed native-module load can be caught: npm 11+
+// blocks install scripts by default, so `npm install -g hafez` "succeeds"
+// with the better-sqlite3 bindings unbuilt and every command dies at import
+// time. Catch that one failure and print the remedy instead of a stack trace.
+try {
+    const { main } = await import('./cli/index.js');
+    await main(process.argv);
+}
+catch (err) {
+    const msg = err instanceof Error ? `${err.message}\n${err.stack ?? ''}` : String(err);
+    if (/better[-_]sqlite3|Could not locate the bindings file|\bbindings\b/i.test(msg)) {
+        process.stderr.write('hafez: 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' +
+            '  npm install -g hafez --allow-scripts=better-sqlite3\n');
+        process.exit(1);
+    }
+    throw err;
+}
+export {};

package/dist/contracts.d.ts

@@ -24,3 +24,9 @@ export declare const ALIAS_KEYS: {
     readonly 'create.session.fields.insight': "synthesis";
 };
 export declare const SUBTYPE_SECTIONS: Record<KnowledgeSubtype, string[]>;
+/** Sections whose content only ever grows — sync merges union their lines
+ * instead of letting the newer side replace the older (see merge.ts). */
+export declare const APPEND_ONLY_SECTIONS: ReadonlySet<string>;
+/** Session-file sections. Sessions have no TypeContract (they are not typed
+ * entities), but their headings are still structural for Document splitting. */
+export declare const SESSION_SECTIONS: readonly ["Summary", "Entities Touched", "Decisions"];

package/dist/contracts.js

@@ -63,8 +63,8 @@ export function hasCapability(type, section) {
     return contract.defaultSections.includes(section) || contract.optionalSections.includes(section);
 }
 // --- Canonical enum tuples (single source of truth) ---
-// Every consumer (file validators, CLI input validator, help renderer) imports these.
-// The cli-schema-parity test enforces that no other file declares local copies.
+// Every consumer (file validators, the Op Spec table, help renderer) imports
+// these — no other file may declare local copies.
 export const ENTITY_TYPES = ['capture', 'entity', 'project'];
 export const ENTITY_STATUSES = ['active', 'paused', 'done'];
 export const SESSION_LOG_TYPES = ['progress', 'decision', 'blocker', 'research'];
@@ -85,3 +85,9 @@ export const SUBTYPE_SECTIONS = {
     insight: ['Synthesis', 'Evidence', 'Sources'],
     plan: ['Goal', 'Steps', 'Dependencies'],
 };
+/** Sections whose content only ever grows — sync merges union their lines
+ * instead of letting the newer side replace the older (see merge.ts). */
+export const APPEND_ONLY_SECTIONS = new Set(['Evidence', 'Sources']);
+/** Session-file sections. Sessions have no TypeContract (they are not typed
+ * entities), but their headings are still structural for Document splitting. */
+export const SESSION_SECTIONS = ['Summary', 'Entities Touched', 'Decisions'];

package/dist/db.js

@@ -1,11 +1,11 @@
 import Database from 'better-sqlite3';
 import { createHash } from 'crypto';
-import { readdirSync, readFileSync, statSync, existsSync, unlinkSync } from 'fs';
+import { readFileSync, statSync, existsSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
-import { parseFilePath } from './vault.js';
+import { parseFilePath, scanVaultDir, kindDir, INDEXED_KINDS } from './vault.js';
 import { ensureLocalExclude } from './knowledge-index.js';
-import { getNextActions, getBrief, WIKI_LINK_RE, findSection } from './sections.js';
-import { parseSessionLog } from './parser.js';
+import { getNextActions, getBrief, WIKI_LINK_RE, findSection } from './document.js';
+import { parseSessionLog } from './document.js';
 // Bump this when indexing logic changes to force a full rebuild.
 // v5: wiki link harvesting (mention relations), parent link indexing, relation filter on queries.
 // v6: description column on items.
@@ -86,16 +86,6 @@ const STOPWORDS = new Set([
 function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
 }
-function scanDir(dirPath) {
-    try {
-        // Skip dotfiles: their slugs are rejected by resolveFilePath, so indexing
-        // them would list entities that read/update can never reach.
-        return readdirSync(dirPath).filter(f => f.endsWith('.md') && !f.startsWith('.')).map(f => join(dirPath, f));
-    }
-    catch {
-        return [];
-    }
-}
 // --- Shared query functions (used by both write and readonly paths) ---
 function sanitizeFtsQuery(raw) {
     const cleaned = raw.replace(/[^\w\s]/g, ' ');
@@ -322,15 +312,19 @@ function getStatsFn(db) {
     WHERE kind = 'entity' AND status = 'active' AND next_action_count = 0
     ORDER BY last_touched DESC
   `).all();
+    // Full lists, not top-5: day-granularity timestamps tie massively (a
+    // new vault ties on everything), so the caller resolves ties (git commit
+    // time, then name) and caps. Name tiebreak here keeps the base order
+    // deterministic instead of leaking SQLite row order.
     const recently_touched = db.prepare(`
     SELECT slug, name, last_touched FROM items
     WHERE kind = 'entity'
-    ORDER BY last_touched DESC LIMIT 5
+    ORDER BY last_touched DESC, name COLLATE NOCASE ASC
   `).all();
     const recently_created = db.prepare(`
     SELECT slug, name, created FROM items
     WHERE kind = 'entity'
-    ORDER BY created DESC LIMIT 5
+    ORDER BY created DESC, name COLLATE NOCASE ASC
   `).all();
     const knowledgeCount = db.prepare("SELECT COUNT(*) as cnt FROM items WHERE kind = 'knowledge'").get().cnt;
     return {
@@ -579,8 +573,8 @@ export function createIndex(vaultPath, opts) {
         while ((wikiMatch = linkRe.exec(authoredBody)) !== null) {
             const targetSlug = wikiMatch[1];
             // Check if target file exists on disk (not in index — target may not be indexed yet)
-            const targetEntityPath = join(vaultPath, 'entities', `${targetSlug}.md`);
-            const targetKnowledgePath = join(vaultPath, 'knowledge', `${targetSlug}.md`);
+            const targetEntityPath = join(vaultPath, kindDir('entity'), `${targetSlug}.md`);
+            const targetKnowledgePath = join(vaultPath, kindDir('knowledge'), `${targetSlug}.md`);
             const targetExists = knownSlugs
                 ? knownSlugs.has(targetSlug)
                 : existsSync(targetEntityPath) || existsSync(targetKnowledgePath);
@@ -594,16 +588,16 @@ export function createIndex(vaultPath, opts) {
         db.exec('DELETE FROM links');
         // Collect all vault slugs for wiki link target validation
         const allVaultSlugs = new Set();
-        for (const file of scanDir(join(vaultPath, 'entities'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
             allVaultSlugs.add(basename(file, '.md'));
         }
-        for (const file of scanDir(join(vaultPath, 'knowledge'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
             allVaultSlugs.add(basename(file, '.md'));
         }
-        for (const file of scanDir(join(vaultPath, 'entities'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
             indexFile(file, 'entity', allVaultSlugs);
         }
-        for (const file of scanDir(join(vaultPath, 'knowledge'))) {
+        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
             indexFile(file, 'knowledge', allVaultSlugs);
         }
         db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('last_sync', ?)")
@@ -620,12 +614,9 @@ export function createIndex(vaultPath, opts) {
         }
         const lastSyncTime = parseInt(lastSync.value, 10);
         let changed = false;
-        const dirs = [
-            { dir: 'entities', kind: 'entity' },
-            { dir: 'knowledge', kind: 'knowledge' },
-        ];
+        const dirs = INDEXED_KINDS.map(kind => ({ dir: kindDir(kind), kind }));
         for (const { dir, kind } of dirs) {
-            for (const file of scanDir(join(vaultPath, dir))) {
+            for (const file of scanVaultDir(join(vaultPath, dir))) {
                 if (statSync(file).mtimeMs > lastSyncTime) {
                     indexFile(file, kind);
                     changed = true;
@@ -636,7 +627,7 @@ export function createIndex(vaultPath, opts) {
         const dbSlugs = db.prepare('SELECT slug FROM items').all().map(r => r.slug);
         const fileSlugs = new Set();
         for (const { dir } of dirs) {
-            for (const file of scanDir(join(vaultPath, dir))) {
+            for (const file of scanVaultDir(join(vaultPath, dir))) {
                 fileSlugs.add(basename(file, '.md'));
             }
         }
@@ -652,8 +643,7 @@ export function createIndex(vaultPath, opts) {
         }
     }
     function upsertFromFile(slug, kind) {
-        const dir = kind === 'entity' ? 'entities' : 'knowledge';
-        const filePath = join(vaultPath, dir, `${slug}.md`);
+        const filePath = join(vaultPath, kindDir(kind), `${slug}.md`);
         if (existsSync(filePath)) {
             // Force re-index by clearing cached hash
             deleteItemStmt.run(slug);

package/dist/digest.js

@@ -60,6 +60,8 @@ export function digest(input, existingSlugs, now = new Date()) {
     //    leak into the note body (the schema promises they are omitted).
     const noteBody = buildSessionNoteBody(input, knownTouched);
     const related = knownTouched;
+    // Typechecked against the Op Spec's session-create schema so digest output
+    // can never silently diverge from what batch validation accepts.
     const noteFields = {
         synthesis: noteBody,
         'session-date': input.session_date,