hafez 1.0.2 → 1.1.0

package/README.md

@@ -24,12 +24,15 @@ Set up Hafez, an agent-native knowledge vault (github.com/shrvn-r/hafez):
 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
@@ -54,9 +57,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
@@ -131,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 |
 
@@ -166,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/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

@@ -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:
@@ -107,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 {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "1.0.2",
+  "version": "1.1.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",

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