hafez 1.0.2 → 1.2.0

package/README.md

@@ -1,12 +1,14 @@
 # Hafez
 
-**An agent-native personal knowledge vault.** *Hafez* (حافظ) is Persian for "the keeper — the one who memorizes," after the poet. It keeps a durable, structured memory for AI agents: plain markdown files you own, backed by SQLite full-text search and git.
+**A knowledge and project vault shared between you and your agents.** *Hafez* (حافظ) is Persian for "the keeper — the one who memorizes," after the poet. Plain markdown files you own, backed by SQLite full-text search and git.
 
 ## Why
 
-AI agents forget everything between sessions. Hafez gives them a place to remember — projects, insights, decisions, session history — as a knowledge graph they can read, query, and write through a CLI.
+Humans have short-term context. Agents have session context. Both can think big only about what's loaded right now — so both need a place that carries what happened and where things stand, ready whenever either wants to remember. Hafez is that place: projects with goals, actions, and progress; decisions; the insights that outlive them — a graph of markdown files both of you read.
 
-The files stay yours. Everything is markdown with YAML frontmatter in a git repo: readable in any editor, Obsidian-compatible, diffable, and synced like code. The SQLite index (`.hafez.db`) is a disposable read cache rebuilt from the files; git is the source of truth and the sync mechanism.
+Writing is the agent's job. As you work, the results organise themselves into the vault — at session end, at the critical points of a project — through a CLI that owns the plumbing: structure, validation, search, index, git. A malformed write fails; links must resolve. No agent decides how to treat your vault, so every agent treats it the same — and its context goes to your content, not your conventions.
+
+The files stay yours. Everything is markdown with YAML frontmatter in a git repo: readable — and editable — in any editor, Obsidian-compatible, diffable, and synced like code. The SQLite index (`.hafez.db`) is a disposable read cache rebuilt from the files; git is the source of truth and the sync mechanism. Nothing is trapped, either: `hafez export --okf` writes the vault as a standard [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle — Hafez's schema is stricter than OKF's, so the export loses nothing.
 
 ## Setup
 
@@ -17,31 +19,39 @@ Claude Code (or any agent with shell access):
 Set up Hafez, an agent-native knowledge vault (github.com/shrvn-r/hafez):
 
 1. Install the CLI (needs Node.js 22+ and git): npm install -g hafez
-   On npm 12+, append --allow-scripts=better-sqlite3 (npm 12 blocks install
-   scripts by default; the SQLite bindings need theirs).
+   On npm 11+, append --allow-scripts=better-sqlite3 (npm 11 blocks install
+   scripts by default; the SQLite bindings need theirs, and the install
+   reports success even when they were skipped).
 2. Check git identity is configured (git config user.name and user.email);
    if not, ask me for a name and email and set them with git config --global.
 3. Create my vault — a git repo with entities/ and knowledge/ directories and an
    initial commit. Suggest ~/vault but ask me where I want it first.
 4. Register it: hafez init --register <vault-path>
-5. Install the bundled agent skill: copy skill/SKILL.md from the installed
-   package ("$(npm root -g)/hafez/skill/SKILL.md") to ~/.claude/skills/hafez/SKILL.md
+5. If you are Claude Code, install the bundled skill: copy skill/SKILL.md
+   from the installed package ("$(npm root -g)/hafez/skill/SKILL.md") to
+   ~/.claude/skills/hafez/SKILL.md. Any other harness: skip this — step 7
+   covers integration.
 6. Read hafez help --agent, then verify end-to-end: create a test capture,
    hafez read it back, and show me hafez stats.
-7. Tell me what you set up, and give me three example asks I can use in future
-   sessions to see the vault working (e.g. "what am I working on?").
+7. Run hafez onboard and follow what it prints: interview me to seed the
+   vault with my current projects, then help me choose how deeply to
+   integrate Hafez into my agent setup.
 ```
 
 From then on, just mention your projects by name in any session — the skill
 teaches the agent when to read and write the vault, no commands required.
 
+Upgrading from an earlier name of this tool? Remove the old skill directory
+under `~/.claude/skills/` — two installed skills with near-identical
+triggers compete for the same invocations.
+
 ### Manual setup
 
 The same thing by hand:
 
 ```bash
 # Install (Node.js 22+ and git required).
-# On npm 12+, append: --allow-scripts=better-sqlite3
+# On npm 11+, append: --allow-scripts=better-sqlite3
 npm install -g hafez
 
 # One-time, if you've never used git on this machine:
@@ -54,9 +64,13 @@ cd ~/vault && git init && git commit --allow-empty -m "init vault"
 hafez init --register ~/vault           # remember this vault (one-time)
 hafez init                              # show current vault resolution
 
-# Claude Code skill (optional but recommended)
+# Claude Code only (optional): the bundled skill
 mkdir -p ~/.claude/skills/hafez
 cp "$(npm root -g)/hafez/skill/SKILL.md" ~/.claude/skills/hafez/SKILL.md
+
+# Then, in your agent — any harness: "run hafez onboard and follow it" —
+# guided first run (seed the vault with your current projects, choose an
+# integration level)
 ```
 
 Prefer installing without the npm registry? The GitHub release tarball is the
@@ -126,11 +140,12 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `hafez promote <slug> <entity\|project\|knowledge>` | Promote a capture upward |
 | `hafez update <slug> [flags]` | Status, brief, actions, session log, synthesis, evidence… |
 | `hafez link / unlink <slug> <target> --relation <parent\|related>` | Manage relationships |
-| `hafez batch [--dry-run]` | JSON ops on stdin → atomic multi-op, single git commit, rollback on failure |
+| `hafez batch [--dry-run] [--file payload.json]` | JSON ops (stdin or `--file`) → atomic multi-op, single git commit, rollback on failure; dry-run runs the same validation as apply and reports derived slugs |
 | `hafez stats` | Vault summary: counts, stale items, recents |
 | `hafez changelog --since 7.days.ago` | Git-derived change history |
 | `hafez sync` | Pull remote, push local commits (semantic merge on conflicts) |
 | `hafez validate` / `hafez index rebuild` | Integrity check / rebuild the read index |
+| `hafez onboard` | Agent-directed first run: seeding interview + integration setup |
 | `hafez schema [op] [--examples]` | Machine-readable JSON schema for every operation |
 | `hafez export --okf [--out <dir>]` | Read-only OKF v0.1 bundle export |
 
@@ -166,10 +181,16 @@ Writes are serialized through an internal mutex, so a single `Hafez` instance is
 
 ## Agent integration
 
-Hafez is built to be operated by agents:
+Hafez is built to be operated by agents — any agent. The CLI is the whole
+interface, so every harness that can run shell commands integrates the same
+way: through its instructions file — CLAUDE.md for Claude Code, AGENTS.md
+for everything on the [AGENTS.md standard](https://agents.md) (Codex, Cursor,
+Copilot, …). This repo follows the same convention: `AGENTS.md` is canonical
+and `CLAUDE.md` imports it.
 
-- **Claude Code skill** — the package bundles a skill (installed in [Setup](#setup)) covering the full session lifecycle: loading context at session start, vault ops mid-session, and a session-end digest.
+- **`hafez onboard`** — an agent-directed first-run guide: a seeding interview for the empty vault, then a choice of integration level (an always-active block for the harness's global instructions file, or invoke-only). Re-running it later is the intended way to seed newly started work — on a set-up vault it's just the interview.
 - **`hafez help --agent`** — a complete API reference designed to be loaded into an agent's context.
+- **Claude Code skill** — an optional adapter for one harness: the package bundles a skill (installed in [Setup](#setup)) covering the full session lifecycle: loading context at session start, vault ops mid-session, and a session-end digest.
 - **`hafez schema <op> --examples`** — JSON schemas with working examples for every batch operation, so agents can self-correct.
 - **`hafez batch`** — apply a whole session's worth of updates atomically from a single JSON payload. Validation errors report every bad op at once with did-you-mean hints.
 - **Markdown-native output** by default, `--json` everywhere for machine consumption.

package/dist/cli/commands.d.ts

@@ -126,4 +126,4 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
 }, z.core.$strict>], "op">;
 export declare function parseBatchInput(json: string): BatchOperation[];
 export declare function cmdBatch(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
-export declare function cmdDigest(os: Hafez, _args: string[], _opts?: CommandOpts): Promise<string>;
+export declare function cmdDigest(os: Hafez, args: string[], _opts?: CommandOpts): Promise<string>;

package/dist/cli/commands.js

@@ -1,5 +1,6 @@
 // src/cli/commands.ts
 import { z } from 'zod';
+import { readFileSync } from 'fs';
 import { HafezError } from '../types.js';
 import { ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, } from '../contracts.js';
 import { formatBatchError } from './batch-errors.js';
@@ -358,6 +359,7 @@ const CreateEntityFieldsSchema = z.object({
     tags: z.array(z.string()).optional(),
     brief: z.string().optional(),
     add_action: z.string().optional(),
+    add_actions: z.array(z.string()).optional(),
 }).strict();
 const CreateKnowledgeFieldsSchema = z.object({
     subtype: z.enum([...VALID_SUBTYPES]).optional(),
@@ -489,6 +491,23 @@ export function parseBatchInput(json) {
     }
     return operations;
 }
+// --file payload reader. Exists because Windows PowerShell 5.1 cannot pipe
+// stdin to native executables — the documented pipe idiom fails there, so a
+// file is the portable session-end path. PowerShell's own redirection writes
+// UTF-16LE (and other tools write BOM'd UTF-8), so decode both rather than
+// trading the pipe footgun for an encoding one.
+function readPayloadFile(path) {
+    let buf;
+    try {
+        buf = readFileSync(path);
+    }
+    catch {
+        throw new HafezError('VALIDATION_FAILED', `Cannot read --file: ${path}`);
+    }
+    if (buf[0] === 0xff && buf[1] === 0xfe)
+        return buf.toString('utf16le').replace(/^\uFEFF/, '');
+    return buf.toString('utf-8').replace(/^\uFEFF/, '');
+}
 function readStdin() {
     return new Promise((resolve, reject) => {
         let data = '';
@@ -500,15 +519,35 @@ function readStdin() {
 }
 export async function cmdBatch(os, args, opts = {}) {
     const dryRun = args.includes('--dry-run');
-    const input = await readStdin();
+    const file = getFlag(args, '--file');
+    const input = file ? readPayloadFile(file) : await readStdin();
     if (!input.trim()) {
-        throw new HafezError('VALIDATION_FAILED', 'No input received. Pipe JSON array to stdin: echo \'[...]\' | hafez batch');
+        throw new HafezError('VALIDATION_FAILED', 'No input received. Pipe JSON array to stdin (echo \'[...]\' | hafez batch) or pass --file payload.json');
     }
     const operations = parseBatchInput(input);
     if (dryRun) {
+        // Same validate phase as apply — dry-run can never green-light a payload
+        // apply rejects. Reports derived slugs so agents can predict create slugs.
+        const report = await os.validateBatch(operations);
         if (opts.json)
-            return jsonOut({ valid: true, operations: operations.length });
-        return `Batch valid: ${operations.length} operations would be applied`;
+            return jsonOut(report);
+        if (!report.valid) {
+            const invalidCount = report.operations.filter(o => o.errors.length > 0).length;
+            const lines = report.operations.flatMap(o => o.errors.map(e => `op[${o.index}] (${o.op} ${o.slug}): ${e}`));
+            throw new HafezError('VALIDATION_FAILED', `Batch invalid: ${invalidCount} of ${operations.length} operation${operations.length === 1 ? '' : 's'} failed validation (0 would be applied)`, lines);
+        }
+        const out = [`Batch valid: ${operations.length} operations would be applied`];
+        const creates = report.operations.filter(o => o.created);
+        if (creates.length > 0) {
+            out.push('Derived slugs:');
+            for (const c of creates)
+                out.push(`  op[${c.index}] ${c.op} → ${c.slug}`);
+        }
+        for (const o of report.operations) {
+            if (o.warning)
+                out.push(`Warning: op[${o.index}] ${o.warning}`);
+        }
+        return out.join('\n');
     }
     const results = await os.batch(operations);
     if (opts.json)
@@ -519,11 +558,11 @@ export async function cmdBatch(os, args, opts = {}) {
         output += ` (created: ${created.join(', ')})`;
     return output;
 }
-export async function cmdDigest(os, _args, _opts = {}) {
-    // Read stdin — reuses the existing readStdin() defined in this file
-    const raw = await readStdin();
+export async function cmdDigest(os, args, _opts = {}) {
+    const file = getFlag(args, '--file');
+    const raw = file ? readPayloadFile(file) : await readStdin();
     if (!raw.trim()) {
-        throw new Error('No input received. Pipe JSON object to stdin: echo \'{"entities_touched":...}\' | hafez digest');
+        throw new Error('No input received. Pipe JSON object to stdin (echo \'{"entities_touched":...}\' | hafez digest) or pass --file summary.json');
     }
     // Parse JSON
     let parsed;

package/dist/cli/format.js

@@ -104,6 +104,11 @@ export function formatSearchResults(results) {
 }
 export function formatStats(stats) {
     const lines = [];
+    const totalEntities = stats.counts.active + stats.counts.paused + stats.counts.done;
+    if (totalEntities === 0 && stats.knowledge_count === 0) {
+        lines.push('Vault is empty — run `hafez onboard` for the guided first run (seeding interview + agent integration).');
+        lines.push('');
+    }
     lines.push('## Status Counts');
     lines.push(`Active: ${stats.counts.active} | Paused: ${stats.counts.paused} | Done: ${stats.counts.done}`);
     lines.push('\n## Type Counts');

package/dist/cli/help-agent.js

@@ -58,7 +58,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 +103,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 +124,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');

package/dist/cli/index.js

@@ -7,6 +7,7 @@ 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,
@@ -65,6 +66,7 @@ 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
 
 Global flags:
@@ -74,6 +76,22 @@ Global flags:
 
 Vault discovery: --vault flag > ~/.config/hafez/vault
 `;
+// 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
@@ -107,6 +125,11 @@ export async function main(argv) {
         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 {
@@ -122,8 +145,7 @@ export async function main(argv) {
                 }
                 process.exit(2);
             }
-            process.stderr.write(`Error: ${err.message}\n`);
-            process.exit(1);
+            failUnknown(err);
         }
         return;
     }
@@ -175,8 +197,7 @@ export async function main(argv) {
             }
         }
         catch (err) {
-            process.stderr.write(`Error: ${err.message}\n`);
-            process.exit(1);
+            failUnknown(err);
         }
         return;
     }
@@ -198,8 +219,7 @@ export async function main(argv) {
                 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);
+            failUnknown(err);
         }
         return;
     }
@@ -236,7 +256,6 @@ export async function main(argv) {
             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);
+        failUnknown(err);
     }
 }

package/dist/cli/onboard.d.ts

@@ -0,0 +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`; 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

@@ -0,0 +1,94 @@
+// src/cli/onboard.ts
+//
+// `hafez onboard` — agent-directed first-run guide. Same pattern as
+// `hafez help --agent`: plain text printed for the agent operating on the
+// user's behalf. Covers the two things a fresh install leaves open — seeding
+// the empty vault and choosing how deeply the agent integrates.
+//
+// Static by design, and deliberately NOT part of the skill: the skill loads
+// into every session forever, this is read once. Living in the CLI also means
+// it works before the skill is installed.
+export const INTEGRATION_SNIPPET = `## Hafez — Session Memory
+
+- Session start: if the first message names a project or topic, load context
+  with \`hafez read <slug>\` (or \`hafez search "<topic>"\`). Don't load
+  speculatively.
+- 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\`; 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.`;
+export function renderOnboard() {
+    return `# Hafez — First Run
+
+You are an agent reading this on behalf of your user. Walk them through the
+steps below conversationally — do not dump this document on them.
+
+Prerequisites: \`hafez init\` resolves a vault, and you have read
+\`hafez help --agent\` (do that now if not). The CLI is the whole interface —
+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
+never starts. The goal here is a small set of high-quality entries — not a
+bulk import.
+
+1. Interview the user: "What are you actively working on right now?" Aim for
+   3-7 projects or areas. For each one, draw out:
+   - a one-line description (\`description\`)
+   - current state / handoff context, 2-4 sentences (\`brief\`)
+   - 1-2 concrete next actions (\`add_action\`)
+2. Offer to mine sources they already have — a repo's README, existing notes,
+   a TODO list. Read what they point you at, propose entries, and let them
+   approve before writing anything.
+3. Anything vague, aspirational, or someday-maybe becomes a capture, not a
+   project. Captures are the inbox; promotion comes later. When in doubt,
+   capture.
+4. Write everything in ONE \`hafez batch\` call (see
+   \`hafez schema create-entity --examples\`), then show the user
+   \`hafez stats\`.
+
+Quality bar: every project entry should let a future agent with zero context
+pick the work up from the brief alone. If a brief would not do that, ask one
+more question.
+
+## Step 2 — Choose the integration level
+
+Ask the user how they want Hafez wired into their sessions. Recommend the
+first option.
+
+RECOMMENDED — always active. Add the block below to the user's global agent
+instructions file — Claude Code: \`~/.claude/CLAUDE.md\`; any harness that
+follows the AGENTS.md standard (Codex, Cursor, Copilot, ...): its global
+AGENTS.md, e.g. \`~/.codex/AGENTS.md\` for Codex CLI. This makes memory
+automatic: context loads at session start, the vault is updated as work
+happens, and a digest records each session. Show them the block, get a yes,
+then append it verbatim:
+
+${INTEGRATION_SNIPPET}
+
+FALLBACK — invoke only. If the user prefers to stay in control, add nothing.
+Explain how invocation works: the agent touches the vault only when they
+mention Hafez or name a project ("what am I working on?", "read <slug>").
+Nothing is loaded or written unless asked. They can upgrade later
+by re-running \`hafez onboard\`.
+
+## Step 3 — Hand over
+
+Finish with three example asks tailored to what was just seeded, e.g.:
+
+- "What am I working on?"
+- "Read <their-project-slug> and pick up where we left off."
+- "Capture: <idea> — I'll triage it later."
+`;
+}

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/db.js

@@ -322,15 +322,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 {

package/dist/git.d.ts

@@ -16,4 +16,11 @@ export declare function gitSync(vaultPath: string): Promise<{
  */
 export declare function gitUnstage(vaultPath: string, files: string[]): Promise<void>;
 export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
+/**
+ * Latest git time per file (repo-relative, forward-slash paths). Used to
+ * break day-granularity frontmatter ties in stats recents. `modified` maps
+ * each file to its most recent commit; `added` to the commit that added it.
+ * Files with no history (not yet committed) are absent from the map.
+ */
+export declare function gitFileTimes(vaultPath: string, mode: 'modified' | 'added'): Promise<Map<string, string>>;
 export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;

package/dist/git.js

@@ -281,10 +281,15 @@ const FILE_STATUS_MAP = {
 };
 export async function gitChangelog(vaultPath, since) {
     const git = simpleGit(vaultPath);
+    // git approxidate fills a date-only --since with the *current* time of
+    // day, so `--since <today>` means "since right now" and silently returns
+    // nothing — the obvious "what happened today" query was the one that
+    // failed. Normalise bare dates to local midnight.
+    const normalizedSince = /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
     let output;
     try {
         output = await git.raw([
-            'log', `--since=${since}`, '--name-status',
+            'log', `--since=${normalizedSince}`, '--name-status',
             '--pretty=format:%H|%aI|%s', '--', 'entities/', 'knowledge/',
         ]);
     }
@@ -311,6 +316,10 @@ export async function gitChangelog(vaultPath, since) {
             const operation = FILE_STATUS_MAP[statusChar];
             if (!operation)
                 continue;
+            // Only vault documents — scaffold files (.gitkeep) live in the same
+            // dirs and would otherwise surface as changelog rows.
+            if (!filePath.endsWith('.md'))
+                continue;
             let kind;
             let slug;
             if (filePath.startsWith('entities/')) {
@@ -329,6 +338,37 @@ export async function gitChangelog(vaultPath, since) {
     }
     return entries;
 }
+/**
+ * Latest git time per file (repo-relative, forward-slash paths). Used to
+ * break day-granularity frontmatter ties in stats recents. `modified` maps
+ * each file to its most recent commit; `added` to the commit that added it.
+ * Files with no history (not yet committed) are absent from the map.
+ */
+export async function gitFileTimes(vaultPath, mode) {
+    const git = simpleGit(vaultPath);
+    let output;
+    try {
+        const args = ['log', '--pretty=format:%x00%aI', '--name-only', '--', 'entities/', 'knowledge/'];
+        if (mode === 'added')
+            args.splice(1, 0, '--diff-filter=A');
+        output = await git.raw(args);
+    }
+    catch {
+        return new Map(); // no git history
+    }
+    const times = new Map();
+    let current = '';
+    for (const line of output.split('\n')) {
+        if (line.startsWith('\0')) {
+            current = line.slice(1);
+            continue;
+        }
+        const file = line.trim();
+        if (file && !times.has(file))
+            times.set(file, current); // first hit = newest
+    }
+    return times;
+}
 export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
     const git = simpleGit(vaultPath);
     // If a previous run crashed mid-rebase/merge, the repo is stuck.

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import { parseFilePath, serializeFile, slugify, resolveFilePath } from './vault.js';
-import { gitCommitAndPush, gitSync, gitChangelog, gitUnstage } from './git.js';
+import { parseFilePath, serializeFile, slugify, resolveFilePath, kindFromPath } from './vault.js';
+import { gitCommitAndPush, gitSync, gitChangelog, gitUnstage, gitFileTimes } from './git.js';
 import { validateEntityFrontmatter, validateKnowledgeFrontmatter, validateSessionLogEntry } from './schema.js';
 import { bodyTemplate, knowledgeBodyTemplate } from './templates.js';
 import { formatSessionLogEntry, countSessionLogEntries, extractOldestSessionLogEntry } from './parser.js';
@@ -71,9 +71,6 @@ export function createHafez(config) {
         }
     }
     function today() { return new Date().toISOString().slice(0, 10); }
-    function kindFromPath(filePath) {
-        return filePath.includes('/entities/') ? 'entity' : 'knowledge';
-    }
     const ENTITY_ONLY_FIELDS = ['status', 'add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'brief', 'current_state', 'session_log', 'resource'];
     const KNOWLEDGE_ONLY_FIELDS = ['confidence', 'synthesis', 'add_evidence', 'add_source'];
     function validateKindFields(kind, fields) {
@@ -100,20 +97,22 @@ export function createHafez(config) {
             process.stderr.write(`Warning: failed to regenerate index.md: ${err.message}\n`);
         }
     }
-    // Shared by create() and batch() so optional fields can't silently diverge
-    // between the two paths (see CLAUDE.md Validation Gotchas).
-    function buildEntityFrontmatter(name, ef) {
+    // Shared by create(), batch(), and the batch validate phase so optional
+    // fields can't silently diverge between paths (see CLAUDE.md Validation
+    // Gotchas). `existsFn` is pluggable so validateBatchCore can supply a
+    // simulation-aware check (same-batch creates count as existing).
+    function buildEntityFrontmatter(name, ef, existsFn = exists) {
         const fm = { name, type: ef.type, status: 'active', created: today(), 'last-touched': today() };
         if (ef.domain?.length)
             fm.domain = ef.domain;
         if (ef.parent) {
-            if (!exists(ef.parent))
+            if (!existsFn(ef.parent))
                 throw new HafezError('VALIDATION_FAILED', `Parent '${ef.parent}' does not exist`);
             fm.parent = ef.parent;
         }
         if (ef.related?.length) {
             for (const r of ef.related) {
-                if (!exists(r))
+                if (!existsFn(r))
                     throw new HafezError('VALIDATION_FAILED', `Related slug '${r}' does not exist`);
             }
             fm.related = ef.related;
@@ -129,13 +128,25 @@ export function createHafez(config) {
             throw new HafezError('VALIDATION_FAILED', 'Invalid entity frontmatter', errors);
         return fm;
     }
-    function buildKnowledgeFrontmatter(name, kf) {
+    // Shared by create() and batch() like buildEntityFrontmatter — body-side
+    // optional fields (brief, actions) must behave identically in both paths.
+    function buildEntityBody(ef) {
+        let body = bodyTemplate(ef.type, { purpose: ef.purpose });
+        if (ef.brief)
+            body = setBrief(body, ef.brief);
+        if (ef.add_action)
+            body = addNextAction(body, ef.add_action);
+        for (const action of ef.add_actions ?? [])
+            body = addNextAction(body, action);
+        return body;
+    }
+    function buildKnowledgeFrontmatter(name, kf, existsFn = exists) {
         const fm = { name, confidence: 'observation', 'reinforcement-count': 0, created: today() };
         if (kf.domain?.length)
             fm.domain = kf.domain;
         if (kf.related?.length) {
             for (const r of kf.related) {
-                if (!exists(r))
+                if (!existsFn(r))
                     throw new HafezError('VALIDATION_FAILED', `Related slug '${r}' does not exist`);
             }
             fm.related = kf.related;
@@ -312,11 +323,7 @@ export function createHafez(config) {
             if (kind === 'entity') {
                 const ef = fields;
                 const fm = buildEntityFrontmatter(name, ef);
-                let body = bodyTemplate(ef.type, { purpose: ef.purpose });
-                if (ef.brief)
-                    body = setBrief(body, ef.brief);
-                if (ef.add_action)
-                    body = addNextAction(body, ef.add_action);
+                let body = buildEntityBody(ef);
                 const filePath = entityPath(slug);
                 mkdirSync(join(vaultPath, 'entities'), { recursive: true });
                 body = syncRelatedSection(body, fm);
@@ -456,10 +463,193 @@ export function createHafez(config) {
             onWrite?.(slug, 'unlink');
         });
     }
+    // "Recent" with day-granularity dates: primary sort is the frontmatter day,
+    // ties break on git commit time (the real recency signal), then name for
+    // files with no commit history yet. Without this the top-5 lists leak
+    // SQLite row order — a brand-new vault (everything same-day) showed
+    // alphabetical-and-missing-newest lists.
+    async function rankRecents(rows, dateKey, mode) {
+        const day = (r) => r[dateKey];
+        if (rows.length <= 1)
+            return rows;
+        // Everything sharing the 5th row's day (or newer) could land in the top 5
+        const cutoffDay = day(rows[Math.min(4, rows.length - 1)]);
+        const candidates = rows.filter(r => day(r) >= cutoffDay);
+        const hasTies = new Set(candidates.map(day)).size < candidates.length;
+        if (!hasTies)
+            return rows.slice(0, 5);
+        const times = await gitFileTimes(vaultPath, mode);
+        const gitTime = (r) => times.get(`entities/${r.slug}.md`) ?? '';
+        candidates.sort((a, b) => {
+            const dayCmp = day(b).localeCompare(day(a));
+            if (dayCmp !== 0)
+                return dayCmp;
+            const gitCmp = gitTime(b).localeCompare(gitTime(a)); // '' (uncommitted) sorts last
+            if (gitCmp !== 0)
+                return gitCmp;
+            return a.name.localeCompare(b.name);
+        });
+        return candidates.slice(0, 5);
+    }
+    // Shared validate phase — dry-run and apply both run this, so dry-run can
+    // never pass a payload apply rejects (parity by construction). Simulates
+    // creates so same-batch references validate: batch executes sequentially,
+    // so op N really does see op 1's creates on disk at apply time.
+    function validateBatchCore(operations) {
+        // slug → what it would be after earlier ops in this batch
+        const simulated = new Map();
+        const simulatedSessions = new Set();
+        const resolve = (slug) => {
+            const sim = simulated.get(slug);
+            if (sim)
+                return sim;
+            const fp = findFile(slug);
+            if (!fp)
+                return null;
+            const kind = kindFromPath(fp);
+            if (kind === 'knowledge')
+                return { kind, type: 'knowledge' };
+            try {
+                return { kind, type: parseFilePath(fp).frontmatter.type };
+            }
+            catch {
+                return { kind, type: 'entity' };
+            }
+        };
+        const existsAnywhere = (slug) => simulated.has(slug) || exists(slug);
+        const report = [];
+        for (const [index, op] of operations.entries()) {
+            const errors = [];
+            let warning;
+            let slug;
+            let created = false;
+            const pushErr = (err) => {
+                const e = err;
+                errors.push(e.details?.length ? `${e.message}: ${e.details.join('; ')}` : e.message);
+            };
+            if (op.op === 'update') {
+                slug = op.slug;
+                const target = resolve(op.slug);
+                if (!target)
+                    errors.push(`'${op.slug}' not found`);
+                else {
+                    try {
+                        validateKindFields(target.kind, op.fields);
+                    }
+                    catch (err) {
+                        pushErr(err);
+                    }
+                }
+                if (op.fields.session_log) {
+                    const logErrors = validateSessionLogEntry(op.fields.session_log);
+                    if (logErrors.length > 0)
+                        errors.push(`Invalid session log entry: ${logErrors.join('; ')}`);
+                }
+                if (op.fields.related) {
+                    for (const r of op.fields.related) {
+                        if (!existsAnywhere(r))
+                            errors.push(`Related slug '${r}' does not exist`);
+                    }
+                }
+            }
+            else if (op.op === 'create' && op.kind === 'session') {
+                slug = slugify(op.name);
+                if (exists(slug) || existsSync(join(vaultPath, 'sessions', `${slug}.md`)) || simulatedSessions.has(slug)) {
+                    warning = `session '${slug}' already exists — op will be skipped (batch continues)`;
+                }
+                else {
+                    simulatedSessions.add(slug);
+                    created = true;
+                }
+            }
+            else if (op.op === 'create') {
+                slug = slugify(op.name);
+                if (existsAnywhere(slug))
+                    errors.push(`Slug '${slug}' already exists`);
+                if (op.kind === 'entity') {
+                    try {
+                        buildEntityFrontmatter(op.name, op.fields, existsAnywhere);
+                    }
+                    catch (err) {
+                        pushErr(err);
+                    }
+                    simulated.set(slug, { kind: 'entity', type: op.fields.type });
+                }
+                else {
+                    try {
+                        buildKnowledgeFrontmatter(op.name, (op.fields || {}), existsAnywhere);
+                    }
+                    catch (err) {
+                        pushErr(err);
+                    }
+                    simulated.set(slug, { kind: 'knowledge', type: 'knowledge' });
+                }
+                created = errors.length === 0;
+            }
+            else if (op.op === 'capture') {
+                slug = slugify(op.name);
+                if (existsAnywhere(slug))
+                    errors.push(`Slug '${slug}' already exists`);
+                simulated.set(slug, { kind: 'entity', type: 'capture' });
+                created = errors.length === 0;
+            }
+            else if (op.op === 'link') {
+                slug = op.slug;
+                if (!resolve(op.slug))
+                    errors.push(`'${op.slug}' not found`);
+                if (!existsAnywhere(op.target))
+                    errors.push(`Target '${op.target}' does not exist`);
+            }
+            else if (op.op === 'unlink') {
+                slug = op.slug;
+                if (!resolve(op.slug))
+                    errors.push(`'${op.slug}' not found`);
+            }
+            else {
+                // promote
+                slug = op.slug;
+                const cur = resolve(op.slug);
+                if (!cur)
+                    errors.push(`'${op.slug}' not found`);
+                else {
+                    const currentType = cur.kind === 'knowledge' ? 'knowledge' : cur.type;
+                    try {
+                        const contract = getContract(currentType);
+                        if (!contract.canPromoteTo.includes(op.target)) {
+                            errors.push(`Cannot promote ${currentType} to ${op.target}. Valid targets: ${contract.canPromoteTo.join(', ') || 'none (terminal type)'}`);
+                        }
+                        else {
+                            simulated.set(op.slug, op.target === 'knowledge' ? { kind: 'knowledge', type: 'knowledge' } : { kind: 'entity', type: op.target });
+                        }
+                    }
+                    catch (err) {
+                        pushErr(err);
+                    }
+                }
+            }
+            const entry = { index, op: op.op, slug, errors };
+            if (created)
+                entry.created = true;
+            if (warning)
+                entry.warning = warning;
+            report.push(entry);
+        }
+        return { valid: report.every(o => o.errors.length === 0), operations: report };
+    }
+    function formatOpErrors(report) {
+        return report.operations.flatMap(o => o.errors.map(e => `op[${o.index}] (${o.op} ${o.slug}): ${e}`));
+    }
     async function batch(operations) {
         if (readOnly)
             throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
         return withLock(async () => {
+            // Validate the whole payload before touching anything — all errors
+            // surface at once, localised to their op.
+            const validation = validateBatchCore(operations);
+            if (!validation.valid) {
+                const invalidCount = validation.operations.filter(o => o.errors.length > 0).length;
+                throw new HafezError('VALIDATION_FAILED', `Batch failed validation: ${invalidCount} invalid operation${invalidCount === 1 ? '' : 's'} (0 of ${operations.length} applied)`, formatOpErrors(validation));
+            }
             // Capture originals for rollback
             const originals = new Map();
             function captureOriginal(filePath) {
@@ -470,8 +660,10 @@ export function createHafez(config) {
             const modifiedFiles = [];
             const affectedSlugs = [];
             const results = [];
+            let currentOp = -1;
             try {
                 for (const op of operations) {
+                    currentOp++;
                     if (op.op === 'update') {
                         const filePath = findFile(op.slug);
                         if (!filePath)
@@ -530,11 +722,7 @@ export function createHafez(config) {
                         if (op.kind === 'entity') {
                             const ef = op.fields;
                             const fm = buildEntityFrontmatter(op.name, ef);
-                            let entBody = bodyTemplate(ef.type, { purpose: ef.purpose });
-                            if (ef.brief)
-                                entBody = setBrief(entBody, ef.brief);
-                            if (ef.add_action)
-                                entBody = addNextAction(entBody, ef.add_action);
+                            let entBody = buildEntityBody(ef);
                             const filePath = entityPath(slug);
                             captureOriginal(filePath);
                             mkdirSync(join(vaultPath, 'entities'), { recursive: true });
@@ -643,6 +831,14 @@ export function createHafez(config) {
                         writeFileSync(path, content);
                     }
                 }
+                // Localise: which op failed, by index and slug/name. The validate
+                // phase above catches semantic errors pre-execution; this covers
+                // residual execution-time failures (races, disk errors).
+                if (err instanceof HafezError && currentOp >= 0) {
+                    const op = operations[currentOp];
+                    const label = 'slug' in op ? op.slug : slugify(op.name);
+                    throw new HafezError(err.code, `op[${currentOp}] (${op.op} ${label}): ${err.message}`, err.details);
+                }
                 throw err;
             }
             // Single git commit for all batch operations
@@ -918,6 +1114,7 @@ export function createHafez(config) {
         link,
         unlink,
         batch,
+        validateBatch: async (operations) => validateBatchCore(operations),
         sync: async () => {
             if (readOnly)
                 throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
@@ -959,7 +1156,10 @@ export function createHafez(config) {
             if (!idx)
                 return emptyStats;
             idx.syncIfStale();
-            return idx.getStats();
+            const s = idx.getStats();
+            s.recently_touched = await rankRecents(s.recently_touched, 'last_touched', 'modified');
+            s.recently_created = await rankRecents(s.recently_created, 'created', 'added');
+            return s;
         },
         changelog: (since) => gitChangelog(vaultPath, since),
     };

package/dist/types.d.ts

@@ -112,6 +112,7 @@ export interface CreateEntityFields {
     tags?: string[];
     brief?: string;
     add_action?: string;
+    add_actions?: string[];
 }
 export interface CreateKnowledgeFields {
     subtype?: KnowledgeSubtype;
@@ -259,6 +260,18 @@ export type BatchOperation = {
     slug: string;
     target: 'entity' | 'project' | 'knowledge';
 };
+export interface BatchOpValidation {
+    index: number;
+    op: string;
+    slug: string;
+    created?: boolean;
+    errors: string[];
+    warning?: string;
+}
+export interface BatchValidationReport {
+    valid: boolean;
+    operations: BatchOpValidation[];
+}
 export type HafezErrorCode = 'NOT_FOUND' | 'SLUG_EXISTS' | 'VALIDATION_FAILED' | 'GIT_PUSH_FAILED' | 'GIT_COMMIT_FAILED' | 'VAULT_LOCKED';
 export declare class HafezError extends Error {
     code: HafezErrorCode;
@@ -294,6 +307,7 @@ export interface Hafez {
     unlink(slug: string, target: string, relation: LinkRelation): Promise<void>;
     promote(slug: string, target: 'entity' | 'project' | 'knowledge'): Promise<string>;
     batch(operations: BatchOperation[]): Promise<BatchResult[]>;
+    validateBatch(operations: BatchOperation[]): Promise<BatchValidationReport>;
     sync(): Promise<{
         pulled: boolean;
         pushed: boolean;

package/dist/vault.d.ts

@@ -1,5 +1,6 @@
 export declare function slugify(name: string): string;
 export declare function resolveFilePath(vaultPath: string, slug: string, kind: 'entity' | 'knowledge'): string;
+export declare function kindFromPath(filePath: string): 'entity' | 'knowledge';
 export declare function slugExists(vaultPath: string, slug: string): boolean;
 export declare function parseFilePath(path: string): {
     frontmatter: Record<string, any>;

package/dist/vault.js

@@ -28,6 +28,13 @@ export function resolveFilePath(vaultPath, slug, kind) {
     const dir = kind === 'entity' ? 'entities' : 'knowledge';
     return join(vaultPath, dir, `${slug}.md`);
 }
+// Separator-agnostic: OS paths use '/' or '\' depending on platform, and a
+// POSIX-only check silently classifies every entity as knowledge on Windows
+// (all updates then fail on kind rules). Exported pure so win32 paths are
+// unit-testable from any platform.
+export function kindFromPath(filePath) {
+    return /[/\\]entities[/\\]/.test(filePath) ? 'entity' : 'knowledge';
+}
 export function slugExists(vaultPath, slug) {
     return existsSync(resolveFilePath(vaultPath, slug, 'entity'))
         || existsSync(resolveFilePath(vaultPath, slug, 'knowledge'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc",
-    "install:local": "mkdir -p ~/.local/bin && ln -sf \"$(pwd)/dist/cli.js\" ~/.local/bin/hafez && rm -f ~/.claude/skills/hafez/SKILL.md && mkdir -p ~/.claude/skills/hafez && cp \"$(pwd)/skill/SKILL.md\" ~/.claude/skills/hafez/SKILL.md",
+    "install:local": "chmod +x \"$(pwd)/dist/cli.js\" && mkdir -p ~/.local/bin && ln -sf \"$(pwd)/dist/cli.js\" ~/.local/bin/hafez && rm -f ~/.claude/skills/hafez/SKILL.md && mkdir -p ~/.claude/skills/hafez && cp \"$(pwd)/skill/SKILL.md\" ~/.claude/skills/hafez/SKILL.md",
     "pretest": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -34,15 +34,15 @@
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
-    "@types/proper-lockfile": "^4.1.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.4.0",
+    "@types/proper-lockfile": "^4.1.4",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "license": "MIT",
-  "description": "Agent-native personal knowledge vault: markdown + YAML frontmatter, SQLite FTS5 search, git-backed",
+  "description": "A knowledge and project vault shared between you and your agents — plain markdown + git, schema-enforced writes, FTS5 search, operated by agents through a CLI",
   "keywords": [
     "knowledge-base",
     "knowledge-vault",

package/skill/SKILL.md

@@ -14,7 +14,7 @@ description: >
 
 All operations use the `hafez` CLI. No file manipulation — the CLI handles reads, writes, validation, and git.
 
-If `hafez` is not installed, or `hafez init` reports no vault, stop and follow the setup in the project README (github.com/shrvn-r/hafez) before using this skill.
+If `hafez` is not installed, or `hafez init` reports no vault, stop and follow the setup in the project README (github.com/shrvn-r/hafez) before using this skill. If the vault exists but is empty, run `hafez onboard` and follow what it prints.
 
 ## CLI Reference
 
@@ -41,7 +41,7 @@ Quick reference for common operations:
 | Add evidence to knowledge | `hafez update <slug> --add-evidence "text"` |
 | Add source to knowledge | `hafez update <slug> --add-source "url"` |
 | Export OKF bundle | `hafez export --okf [--out <dir>]` (re-export overwrites, never deletes) |
-| Digest session → batch | `echo '{...}' \| hafez digest \| hafez batch` |
+| Digest session → batch | `echo '{...}' \| hafez digest \| hafez batch` (no pipes? `--file` on both) |
 
 Note: `--insight` is an alias for `--synthesis`.
 
@@ -143,6 +143,10 @@ echo '[
 
 Batch output includes created slugs: `Batch complete: 3 operations (created: new-thing, insight)`
 
+On shells that can't pipe stdin to native executables (Windows PowerShell 5.1), write the payload to a file and use `hafez batch --file payload.json` — same JSON, same behavior. (`cmd /c "hafez batch < payload.json"` also works.)
+
+**Slug contract.** Slugs derive deterministically from names: lowercase, non-alphanumeric runs become single `-` (`"Auth Refactor!"` → `auth-refactor`). Batch executes sequentially, so later ops can reference the slugs of earlier creates in the same payload — create-then-link works in one batch. Collisions hard-error, so a wrong prediction can't touch the wrong document; `hafez batch --dry-run` reports the derived slug for every create op if you want to verify first.
+
 For a single operation, individual commands are fine — they auto-sync.
 
 ## Session End — Digest
@@ -163,6 +167,8 @@ echo '{
 }' | hafez digest | hafez batch
 ```
 
+On shells that can't pipe (PowerShell 5.1), use files instead — digest stays inspectable in the middle: `hafez digest --file summary.json > ops.json`, then `hafez batch --file ops.json`.
+
 Digest adds a session log entry to each touched entity and creates a session note linking them all. Authoritative field docs: `hafez schema digest`.
 
 Digest itself is pure — it only prints batch JSON; `hafez batch` is what writes. If you are unsure the slugs exist, run `hafez digest` alone first: unknown slugs warn on stderr (they are omitted from the output). Fix `entities_touched`, regenerate, and pipe to batch **once** — re-running the full pipe after a successful batch creates a duplicate session note.