hafez 1.0.1 → 1.1.0

package/README.md

@@ -16,22 +16,23 @@ Claude Code (or any agent with shell access):
 ```text
 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 https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz
-   On npm 12+, append --allow-remote=root --allow-scripts=better-sqlite3
-   (npm 12 blocks URL-tarball installs and install scripts by default;
-   the SQLite bindings need their install script).
+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).
 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
@@ -43,8 +44,8 @@ The same thing by hand:
 
 ```bash
 # Install (Node.js 22+ and git required).
-# On npm 12+, append: --allow-remote=root --allow-scripts=better-sqlite3
-npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz
+# On npm 12+, append: --allow-scripts=better-sqlite3
+npm install -g hafez
 
 # One-time, if you've never used git on this machine:
 #   git config --global user.name "Your Name"
@@ -56,14 +57,18 @@ 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)
 ```
 
-On npm ≤11, `npm install -g github:shrvn-r/hafez` also works (npm 12 disables
-git installs by default). An npm registry package is planned; GitHub is the
-distribution channel for now.
+Prefer installing without the npm registry? The GitHub release tarball is the
+same artifact: `npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz`
+(npm 12+ additionally needs `--allow-remote=root`).
 
 ## Quick start
 
@@ -133,6 +138,7 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `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 |
 
@@ -168,10 +174,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).
 - **`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

@@ -10,10 +10,7 @@ export declare function cmdCreate(os: Hafez, args: string[], opts?: CommandOpts)
 export declare function cmdUpdate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdLink(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdUnlink(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
-/**
- * Top-level capture command — aliases to the same handler used by
- * `hafez create inbox`. Added to align the CLI verb with the batch op name.
- */
+/** Top-level capture command — aligns the CLI verb with the batch op name. */
 export declare function cmdCapture(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdPromote(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdValidate(os: Hafez, _args: string[], opts?: CommandOpts): Promise<string>;
@@ -107,27 +104,26 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     slug: z.ZodString;
     target: z.ZodString;
     relation: z.ZodEnum<{
-        related: "related";
         parent: "parent";
+        related: "related";
     }>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"unlink">;
     slug: z.ZodString;
     target: z.ZodString;
     relation: z.ZodEnum<{
-        related: "related";
         parent: "parent";
+        related: "related";
     }>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"promote">;
     slug: z.ZodString;
     target: z.ZodEnum<{
         entity: "entity";
-        knowledge: "knowledge";
         project: "project";
+        knowledge: "knowledge";
     }>;
 }, 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 cmdMigrateKnowledgeV2(args: string[], vaultPath: string): Promise<void>;

package/dist/cli/commands.js

@@ -5,7 +5,6 @@ import { ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VA
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { formatEntityHeader, formatKnowledgeHeader, formatQueryTable, formatKnowledgeTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
-import { migrateKnowledgeV2 } from '../migrate-knowledge-v2.js';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
 }
@@ -105,16 +104,7 @@ export async function cmdSearch(os, args, opts = {}) {
 export async function cmdCreate(os, args, opts = {}) {
     const kind = args[0];
     if (!kind)
-        throw new Error('Usage: hafez create <entity|knowledge|inbox> <name> [options]');
-    if (kind === 'inbox') {
-        const name = positionalArgs(args.slice(1)).join(' ');
-        if (!name)
-            throw new Error('Usage: hafez create inbox <name> [--notes "text"]');
-        const notes = getFlag(args, '--notes');
-        process.stderr.write('Warning: `hafez create inbox` is deprecated. Use `hafez capture <name>` instead.\n');
-        const slug = await os.capture(name, notes);
-        return opts.json ? jsonOut({ slug }) : slug;
-    }
+        throw new Error('Usage: hafez create <entity|knowledge> <name> [options]');
     const name = positionalArgs(args.slice(1)).join(' ');
     if (!name)
         throw new Error(`Usage: hafez create ${kind} <name> [options]`);
@@ -147,7 +137,7 @@ export async function cmdCreate(os, args, opts = {}) {
         });
         return opts.json ? jsonOut({ slug }) : slug;
     }
-    throw new Error(`Unknown kind: ${kind}. Use entity, knowledge, or inbox.`);
+    throw new Error(`Unknown kind: ${kind}. Use entity or knowledge.`);
 }
 export async function cmdUpdate(os, args, opts = {}) {
     const slug = args[0];
@@ -157,13 +147,11 @@ export async function cmdUpdate(os, args, opts = {}) {
     const status = getFlag(args, '--status');
     if (status)
         fields.status = status;
-    // Legacy --next-action: deprecation notice
-    const nextAction = getFlag(args, '--next-action');
-    if (nextAction !== undefined) {
-        process.stderr.write('Warning: --next-action is deprecated. Use --add-action instead.\n');
-        fields.add_action = nextAction === '' ? undefined : nextAction;
-        if (nextAction === '')
-            fields.clear_actions = true;
+    // Removed flag must fail loudly, not silently drop the value: older
+    // installed skills/scripts still pass it, and "Updated <slug>" with the
+    // action discarded is a false success.
+    if (args.includes('--next-action')) {
+        throw new Error('--next-action was removed in v1.0.2. Use --add-action (and --clear-actions) instead.');
     }
     const currentState = getFlag(args, '--current-state');
     if (currentState)
@@ -235,18 +223,10 @@ export async function cmdUpdate(os, args, opts = {}) {
     }
     return lines.join('\n');
 }
-/**
- * Parse link/unlink args, supporting both the legacy positional form
- * (`hafez link <slug> <target> <parent|related>`) and the new
- * `--relation <value>` named flag. Positional remains accepted as a
- * deprecated alias — emits a one-line warning to stderr.
- */
 function parseLinkArgs(args, verb) {
-    const relationFlag = getFlag(args, '--relation');
+    const relation = getFlag(args, '--relation');
     // After getFlag the relation value is still at its original positional slot
-    // (getFlag does NOT splice), so strip it manually to prevent it from being
-    // mistaken for a positional if someone passes both forms. Here we only
-    // consume the flag once above.
+    // (getFlag does NOT splice), so strip it manually before reading positionals.
     const positionals = args.filter((a, i) => {
         if (a === '--relation')
             return false;
@@ -254,18 +234,10 @@ function parseLinkArgs(args, verb) {
             return false;
         return !a.startsWith('--');
     });
-    const [slug, target, positionalRelation] = positionals;
-    if (!slug || !target) {
+    const [slug, target] = positionals;
+    if (!slug || !target || !relation) {
         throw new Error(`Usage: hafez ${verb} <slug> <target> --relation <parent|related>`);
     }
-    let relation = relationFlag;
-    if (!relation) {
-        if (!positionalRelation) {
-            throw new Error(`Usage: hafez ${verb} <slug> <target> --relation <parent|related>`);
-        }
-        relation = positionalRelation;
-        process.stderr.write(`Warning: positional relation is deprecated. Use: hafez ${verb} ${slug} ${target} --relation ${relation}\n`);
-    }
     if (!['parent', 'related'].includes(relation)) {
         throw new Error(`Invalid relation: ${relation}. Must be parent or related.`);
     }
@@ -281,10 +253,7 @@ export async function cmdUnlink(os, args, opts = {}) {
     await os.unlink(slug, target, relation);
     return opts.json ? jsonOut({ slug, target, relation }) : `Unlinked ${slug} — ${target} (${relation})`;
 }
-/**
- * Top-level capture command — aliases to the same handler used by
- * `hafez create inbox`. Added to align the CLI verb with the batch op name.
- */
+/** Top-level capture command — aligns the CLI verb with the batch op name. */
 export async function cmdCapture(os, args, opts = {}) {
     const name = positionalArgs(args).join(' ');
     if (!name)
@@ -584,28 +553,6 @@ export async function cmdDigest(os, _args, _opts = {}) {
     const ops = digest(result.data, existingSlugs);
     return JSON.stringify(ops, null, 2);
 }
-export async function cmdMigrateKnowledgeV2(args, vaultPath) {
-    const apply = args.includes('--apply');
-    const report = migrateKnowledgeV2(vaultPath, { apply });
-    console.log(`## Migration: knowledge-v2 ${apply ? '(APPLIED)' : '(dry run)'}`);
-    console.log(`- Sessions to move: ${report.sessionsToMove.length}`);
-    for (const f of report.sessionsToMove)
-        console.log(`  - ${f}`);
-    console.log(`- Empty notes to delete: ${report.emptyToDelete.length}`);
-    for (const f of report.emptyToDelete)
-        console.log(`  - ${f}`);
-    console.log(`- ## Insight → ## Synthesis: ${report.insightToRename.length}`);
-    for (const f of report.insightToRename)
-        console.log(`  - ${f}`);
-    console.log(`- ## Related to generate: ${report.relatedToGenerate.length}`);
-    for (const f of report.relatedToGenerate)
-        console.log(`  - ${f}`);
-    console.log(`- .gitignore needs update: ${report.gitignoreNeeded}`);
-    if (apply && report.gitCommitFailed)
-        console.log('⚠ Warning: git commit failed — changes are applied but not committed.');
-    if (!apply)
-        console.log('\nRun with --apply to execute migration.');
-}
 // --- Arg helpers ---
 function getFlag(args, flag) {
     const idx = args.indexOf(flag);

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

@@ -4,9 +4,10 @@ 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 { 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,
@@ -38,7 +39,7 @@ 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
+  create <kind> <name>       Create entity or knowledge note
   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
@@ -56,12 +57,8 @@ Commands:
   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
+  link <slug> <target> --relation <rel>    Add a link
+  unlink <slug> <target> --relation <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
@@ -69,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:
@@ -111,6 +109,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 {
@@ -184,64 +187,6 @@ export async function main(argv) {
         }
         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 } });

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`) 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,88 @@
+// 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\`) 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).
+
+## 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/db.js

@@ -88,7 +88,9 @@ function hashContent(content) {
 }
 function scanDir(dirPath) {
     try {
-        return readdirSync(dirPath).filter(f => f.endsWith('.md')).map(f => join(dirPath, f));
+        // 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 [];
@@ -401,46 +403,65 @@ export function createIndex(vaultPath, opts) {
     // The db files are a disposable local cache — keep them out of the user's
     // `git status` without dirtying their vault with a tracked .gitignore.
     ensureLocalExclude(vaultPath);
+    function removeDbFiles() {
+        // The -wal/-shm siblings must go too: a fresh db next to a stale WAL is
+        // itself corrupt.
+        for (const suffix of ['', '-wal', '-shm']) {
+            try {
+                unlinkSync(dbPath + suffix);
+            }
+            catch { /* may not exist */ }
+        }
+    }
+    function openDb() {
+        const fresh = new Database(dbPath);
+        try {
+            fresh.pragma('journal_mode = WAL');
+            fresh.pragma('busy_timeout = 5000');
+            fresh.pragma('foreign_keys = ON');
+            fresh.exec(SCHEMA);
+            return fresh;
+        }
+        catch (err) {
+            // Close before the caller unlinks — on filesystems without POSIX
+            // delete-while-open semantics, unlinking an open db fails silently and
+            // recovery would just reopen the same corrupt file.
+            try {
+                fresh.close();
+            }
+            catch { /* already unusable */ }
+            throw err;
+        }
+    }
     let db;
     try {
-        db = new Database(dbPath);
+        db = openDb();
     }
     catch {
-        // Corrupted DB — delete and recreate
-        try {
-            unlinkSync(dbPath);
-        }
-        catch { }
-        db = new Database(dbPath);
+        // Corrupted DB (garbage bytes, truncated WAL checkpoint). better-sqlite3
+        // doesn't touch the file until the first statement, so corruption surfaces
+        // at the pragma/exec inside openDb, not at the constructor — the whole
+        // open sequence must be inside this catch. The index is a disposable
+        // cache: delete and rebuild.
+        removeDbFiles();
+        db = openDb();
     }
-    db.pragma('journal_mode = WAL');
-    db.pragma('busy_timeout = 5000');
-    db.pragma('foreign_keys = ON');
-    db.exec(SCHEMA);
     // Schema migration: if next_action_count column missing, delete DB and recreate
     try {
         db.prepare('SELECT next_action_count FROM items LIMIT 0').run();
     }
     catch {
         db.close();
-        unlinkSync(dbPath);
-        db = new Database(dbPath);
-        db.pragma('journal_mode = WAL');
-        db.pragma('busy_timeout = 5000');
-        db.pragma('foreign_keys = ON');
-        db.exec(SCHEMA);
+        removeDbFiles();
+        db = openDb();
     }
     // Schema migration: if domain_entity column exists, delete DB and recreate
     try {
         db.prepare('SELECT domain_entity FROM items LIMIT 0').run();
         // Column exists — old schema, needs rebuild
         db.close();
-        unlinkSync(dbPath);
-        db = new Database(dbPath);
-        db.pragma('journal_mode = WAL');
-        db.pragma('busy_timeout = 5000');
-        db.pragma('foreign_keys = ON');
-        db.exec(SCHEMA);
+        removeDbFiles();
+        db = openDb();
     }
     catch {
         // Column doesn't exist — correct schema, continue
@@ -449,12 +470,8 @@ export function createIndex(vaultPath, opts) {
     const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
     if (!versionRow || versionRow.value !== SCHEMA_VERSION) {
         db.close();
-        unlinkSync(dbPath);
-        db = new Database(dbPath);
-        db.pragma('journal_mode = WAL');
-        db.pragma('busy_timeout = 5000');
-        db.pragma('foreign_keys = ON');
-        db.exec(SCHEMA);
+        removeDbFiles();
+        db = openDb();
         db.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
     }
     // Prepared statements
@@ -496,9 +513,8 @@ export function createIndex(vaultPath, opts) {
             process.stderr.write(`Warning: skipping ${kind}/${slug}.md: missing required field(s): ${missing}\n`);
             return;
         }
-        // Parse next actions from body (new), fall back to frontmatter (legacy pre-migration)
         const bodyActions = getNextActions(body);
-        const nextAction = bodyActions.length > 0 ? bodyActions[0] : (fm['next-action'] ?? null);
+        const nextAction = bodyActions.length > 0 ? bodyActions[0] : null;
         const nextActionCount = bodyActions.length;
         const brief = getBrief(body)?.slice(0, 300) ?? null;
         const logs = parseSessionLog(body);

package/dist/export-okf.js

@@ -1,7 +1,7 @@
 // src/export-okf.ts
 // Read-only export of the vault as an OKF v0.1 bundle (entities + knowledge + sessions).
 // Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
-// Pure sync function — no Hafez instance, index, git, or lock (mirrors migrate-*.ts).
+// Pure sync function — no Hafez instance, index, git, or lock.
 // Re-export overwrites a prior bundle in place but never deletes: files for vault
 // docs renamed or removed since the last export linger (unreferenced by the
 // regenerated indexes) until the bundle directory is deleted and re-exported.

package/dist/git.d.ts

@@ -8,5 +8,12 @@ export declare function gitSync(vaultPath: string): Promise<{
     pushed: boolean;
     remote: boolean;
 }>;
+/**
+ * Unstage files (best effort). Used by batch rollback: a commit that fails
+ * after `git add` leaves the new blobs staged in .git/index, and the next
+ * successful commit would publish the rolled-back content under the wrong
+ * message. Clearing the index entries restores worktree/HEAD/index agreement.
+ */
+export declare function gitUnstage(vaultPath: string, files: string[]): Promise<void>;
 export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
 export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;