hafez 1.2.0 → 1.4.0

package/dist/types.d.ts

@@ -1,11 +1,14 @@
-export type EntityType = 'capture' | 'entity' | 'project';
-export type EntityStatus = 'active' | 'paused' | 'done';
-export type ConfidenceLevel = 'observation' | 'pattern' | 'principle';
-export type SessionLogType = 'progress' | 'decision' | 'blocker' | 'research';
+import type { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, PLAN_STATUSES } from './contracts.js';
+export type EntityType = typeof ENTITY_TYPES[number];
+export type EntityStatus = typeof ENTITY_STATUSES[number];
+export type ConfidenceLevel = typeof CONFIDENCE_LEVELS[number];
+export type SessionLogType = typeof SESSION_LOG_TYPES[number];
 export type ReadDepth = 'frontmatter' | 'summary' | 'full';
-export type QueryFilter = 'active' | 'paused' | 'done' | 'all' | 'stale' | 'capture';
+export type QueryFilter = EntityStatus | 'all' | 'stale' | 'capture';
 export type LinkRelation = 'parent' | 'related';
-export type KnowledgeSubtype = 'insight' | 'plan';
+export type KnowledgeSubtype = typeof VALID_SUBTYPES[number];
+/** Plans are the one knowledge subtype with a lifecycle (see PLAN_STATUSES). */
+export type PlanStatus = typeof PLAN_STATUSES[number];
 export interface EntityQueryOpts {
     filter?: QueryFilter;
     type?: EntityType;
@@ -26,12 +29,23 @@ export interface KnowledgeQueryOpts {
     domain?: string;
     confidence?: ConfidenceLevel;
     subtype?: KnowledgeSubtype;
+    since?: string;
+    before?: string;
+    createdSince?: string;
+    createdBefore?: string;
     tags?: string[];
     sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
 }
+/** The unified (`kind: 'all'`) query takes the entity filter set plus the
+ * knowledge-only narrowing flags. Status filters apply to the entity side
+ * only — knowledge notes carry no status and are never excluded by one. */
+export interface UnifiedQueryOpts extends EntityQueryOpts {
+    kind?: 'entity' | 'knowledge' | 'all';
+    subtype?: KnowledgeSubtype;
+}
 export interface EntityFrontmatter {
     name: string;
     type: EntityType;
@@ -58,10 +72,33 @@ export interface KnowledgeFrontmatter {
     'reinforcement-count'?: number;
     tags?: string[];
     'session-date'?: string;
-    status?: 'active' | 'done';
+    status?: PlanStatus;
     'last-touched'?: string;
 }
+export interface SessionFrontmatter {
+    name: string;
+    created: string;
+    'session-date'?: string;
+    related?: string[];
+}
+/** What parseFilePath returns: the kind comes from Layout (the file's
+ * directory), so consumers switch on `kind` instead of sniffing keys. */
+export type ParsedVaultFile = {
+    kind: 'entity';
+    frontmatter: EntityFrontmatter;
+    body: string;
+} | {
+    kind: 'knowledge';
+    frontmatter: KnowledgeFrontmatter;
+    body: string;
+} | {
+    kind: 'session';
+    frontmatter: SessionFrontmatter;
+    body: string;
+};
 export interface ParsedFile<T = EntityFrontmatter | KnowledgeFrontmatter> {
+    /** Populated by read(): which side of the vault the slug resolved to. */
+    kind?: 'entity' | 'knowledge';
     frontmatter: T;
     body: string;
 }
@@ -95,6 +132,7 @@ export interface UpdateFields {
     tags?: string[];
     related?: string[];
     synthesis?: string;
+    insight?: string;
     add_evidence?: string;
     add_source?: string;
 }
@@ -116,7 +154,9 @@ export interface CreateEntityFields {
 }
 export interface CreateKnowledgeFields {
     subtype?: KnowledgeSubtype;
+    status?: PlanStatus;
     synthesis?: string;
+    insight?: string;
     description?: string;
     domain?: string[];
     related?: string[];
@@ -218,8 +258,16 @@ export interface ChangelogEntry {
 export interface BatchResult {
     op: string;
     slug: string;
-    status: 'ok' | 'error';
+    /** 'skipped' = the Op Spec green-lit the op but there was nothing to do
+     * (today: a duplicate session note) — no write, no error, batch continues.
+     * Dry-run reports the same disposition as a warning. */
+    status: 'ok' | 'error' | 'skipped';
     error?: string;
+    /** Why an op was skipped — same text the dry-run warning carries. */
+    warning?: string;
+    /** Error class when the failure — or the skip — maps to a specific HafezError
+     * code, so a single-op caller unwrapping this result keeps the right exit code. */
+    code?: 'SLUG_EXISTS';
     created?: boolean;
 }
 export type BatchOperation = {
@@ -267,6 +315,10 @@ export interface BatchOpValidation {
     created?: boolean;
     errors: string[];
     warning?: string;
+    /** Error class of the primary failure (NOT_FOUND / SLUG_EXISTS) when it
+     * maps to a specific HafezError code; single-op callers surface it as that
+     * code, batch-level failures stay VALIDATION_FAILED. */
+    primaryCode?: 'NOT_FOUND' | 'SLUG_EXISTS';
 }
 export interface BatchValidationReport {
     valid: boolean;
@@ -281,10 +333,34 @@ export declare class HafezError extends Error {
 export interface GitConfig {
     push?: boolean;
 }
+/**
+ * The persistence seam (see CONTEXT.md: Journal) — everything core needs
+ * from the history layer behind vault mutations. Git satisfies it in
+ * production (src/git.ts); tests may inject an in-memory adapter.
+ */
+export interface Journal {
+    /** Persist one logical change: stage written+deleted paths (vault-relative)
+     * and commit under message. Must clean up its own partial state (e.g.
+     * staged files) before rethrowing on a commit-stage failure; a push-stage
+     * failure surfaces as GIT_PUSH_FAILED with the commit kept. */
+    commit(written: string[], deleted: string[], message: string): Promise<void>;
+    /** Bidirectional sync with the remote, if any. */
+    sync(): Promise<{
+        pulled: boolean;
+        pushed: boolean;
+        remote: boolean;
+    }>;
+    /** History-derived changelog for entities/ and knowledge/ since a date. */
+    changelog(since: string): Promise<ChangelogEntry[]>;
+    /** Newest history timestamp per vault file (modified = any change, added = creation). */
+    fileTimes(mode: 'modified' | 'added'): Promise<Map<string, string>>;
+}
 export interface HafezConfig {
     vaultPath: string;
     readOnly?: boolean;
     git?: GitConfig;
+    /** Override the persistence layer. Defaults to the git adapter. */
+    persistence?: Journal;
     onWrite?: (slug: string, operation: string) => void;
 }
 export interface Hafez {
@@ -294,9 +370,7 @@ export interface Hafez {
         items: QueryResult[];
         total: number;
     }>;
-    queryUnified(opts?: EntityQueryOpts & {
-        kind?: 'entity' | 'knowledge' | 'all';
-    }): Promise<{
+    queryUnified(opts?: UnifiedQueryOpts): Promise<{
         items: UnifiedResult[];
         total: number;
     }>;
@@ -318,7 +392,7 @@ export interface Hafez {
         total: number;
     }>;
     related_to(slug: string, relation?: string): Promise<{
-        items: (QueryResult | KnowledgeQueryResult)[];
+        items: UnifiedResult[];
         total: number;
     }>;
     query_knowledge(opts?: KnowledgeQueryOpts): Promise<{

package/dist/vault.d.ts

@@ -1,11 +1,56 @@
+import type { ParsedVaultFile } from './types.js';
 export declare function slugify(name: string): string;
-export declare function resolveFilePath(vaultPath: string, slug: string, kind: 'entity' | 'knowledge'): string;
+export type VaultKind = 'entity' | 'knowledge' | 'session';
+/** Kinds that live in the SQLite read index (sessions are files-and-git only). */
+export declare const INDEXED_KINDS: ReadonlyArray<'entity' | 'knowledge'>;
+/** Vault directory for a kind, relative to the vault root. */
+export declare function kindDir(kind: VaultKind): string;
+/** A vault content file: anything a sync/merge must treat semantically. */
+export declare const VAULT_FILE_RE: RegExp;
+/** True for vault-relative paths whose kind lives in the read index. */
+export declare function isIndexedRelPath(relPath: string): boolean;
+/** History pathspecs covering the indexed dirs (changelog, file times). */
+export declare const INDEXED_DIR_PATHSPECS: ReadonlyArray<string>;
+/** Classify a vault-relative path into an indexed kind + slug; null outside
+ * the indexed dirs (sessions, non-vault files). Nested paths keep their
+ * historical shape: entities/archive/x-log.md → entity 'archive/x-log'. */
+export declare function classifyIndexedRelPath(relPath: string): {
+    kind: 'entity' | 'knowledge';
+    slug: string;
+} | null;
+/** All .md files directly in dir — non-recursive (archive/ subdirs are
+ * invisible by construction) and dotfile-free: dotfile slugs are rejected by
+ * resolveFilePath, so listing them would surface files no operation can reach. */
+export declare function scanVaultDir(dirPath: string): string[];
+/** Where an entity's overflow session-log entries are archived. */
+export declare function archiveLogPath(vaultPath: string, slug: string): string;
+export declare function resolveFilePath(vaultPath: string, slug: string, kind: VaultKind): string;
+/** The file a slug names, or null — entities are resolved before knowledge,
+ * the one resolution order every operation sees. */
+export declare function findVaultFile(vaultPath: string, slug: string): string | null;
+/** Does this slug name a vault file? An invalid slug definitionally doesn't
+ * exist — reference checks (create parent/related, link targets, validate)
+ * must report "does not exist", not crash. validate() in particular exists to
+ * REPORT malformed refs. */
+export declare function vaultFileExists(vaultPath: string, slug: string): boolean;
 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>;
-    body: string;
-};
+/** Fields that must always be arrays when present (may be scalar in
+ * hand-edited YAML). Parsing coerces them here; merge.ts unions them on
+ * conflict — one list, so a new list-valued field cannot be normalized on
+ * read and then overwritten wholesale on merge. */
+export declare const ARRAY_FIELDS: string[];
+/** Full-kind path classification (kindFromPath only distinguishes the
+ * indexed kinds — sessions default to knowledge there for compatibility).
+ * Session files live directly in sessions/, so only the immediate parent
+ * counts — matching anywhere in the path misclassifies every file of a
+ * vault that happens to live under a directory named "sessions". */
+export declare function vaultKindFromPath(filePath: string): VaultKind;
+/** Total kind classification for a vault-relative content file (anything
+ * matching VAULT_FILE_RE) — derived from KIND_DIRS, so adding a vault dir
+ * can't silently fall a new kind through to the wrong one. Throws on paths
+ * outside the vault dirs; callers gate on VAULT_FILE_RE first. */
+export declare function vaultKindFromRelPath(relPath: string): VaultKind;
+export declare function parseFilePath(path: string): ParsedVaultFile;
 export declare function parseContent(content: string): {
     frontmatter: Record<string, any>;
     body: string;

package/dist/vault.js

@@ -1,7 +1,7 @@
 // src/vault.ts
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { HafezError } from './types.js';
 // Prevent gray-matter from auto-coercing YAML date strings into JS Date objects
@@ -16,6 +16,48 @@ export function slugify(name) {
         .replace(/^-|-$/g, '')
         .replace(/-{2,}/g, '-');
 }
+const KIND_DIRS = { entity: 'entities', knowledge: 'knowledge', session: 'sessions' };
+/** Kinds that live in the SQLite read index (sessions are files-and-git only). */
+export const INDEXED_KINDS = ['entity', 'knowledge'];
+/** Vault directory for a kind, relative to the vault root. */
+export function kindDir(kind) {
+    return KIND_DIRS[kind];
+}
+/** A vault content file: anything a sync/merge must treat semantically. */
+export const VAULT_FILE_RE = new RegExp(`^(?:${Object.values(KIND_DIRS).join('|')})/.+\\.md$`);
+/** True for vault-relative paths whose kind lives in the read index. */
+export function isIndexedRelPath(relPath) {
+    return INDEXED_KINDS.some(k => relPath.startsWith(`${KIND_DIRS[k]}/`));
+}
+/** History pathspecs covering the indexed dirs (changelog, file times). */
+export const INDEXED_DIR_PATHSPECS = INDEXED_KINDS.map(k => `${KIND_DIRS[k]}/`);
+/** Classify a vault-relative path into an indexed kind + slug; null outside
+ * the indexed dirs (sessions, non-vault files). Nested paths keep their
+ * historical shape: entities/archive/x-log.md → entity 'archive/x-log'. */
+export function classifyIndexedRelPath(relPath) {
+    for (const kind of INDEXED_KINDS) {
+        const prefix = `${KIND_DIRS[kind]}/`;
+        if (relPath.startsWith(prefix)) {
+            return { kind, slug: relPath.replace(prefix, '').replace('.md', '') };
+        }
+    }
+    return null;
+}
+/** All .md files directly in dir — non-recursive (archive/ subdirs are
+ * invisible by construction) and dotfile-free: dotfile slugs are rejected by
+ * resolveFilePath, so listing them would surface files no operation can reach. */
+export function scanVaultDir(dirPath) {
+    try {
+        return readdirSync(dirPath).filter(f => f.endsWith('.md') && !f.startsWith('.')).map(f => join(dirPath, f));
+    }
+    catch {
+        return [];
+    }
+}
+/** Where an entity's overflow session-log entries are archived. */
+export function archiveLogPath(vaultPath, slug) {
+    return join(vaultPath, KIND_DIRS.entity, 'archive', `${slug}-log.md`);
+}
 // Slugs are path components: anything with separators (or a leading dot, or a
 // Windows drive colon) could escape the vault — "../../outside/secret" reads,
 // writes, and deletes files anywhere on disk. Block only those; spaces and
@@ -25,22 +67,52 @@ export function resolveFilePath(vaultPath, slug, kind) {
     if (!slug || slug.startsWith('.') || /[/\\:\0]/.test(slug)) {
         throw new HafezError('VALIDATION_FAILED', `Invalid slug: '${slug}'`);
     }
-    const dir = kind === 'entity' ? 'entities' : 'knowledge';
-    return join(vaultPath, dir, `${slug}.md`);
+    return join(vaultPath, KIND_DIRS[kind], `${slug}.md`);
+}
+/** The file a slug names, or null — entities are resolved before knowledge,
+ * the one resolution order every operation sees. */
+export function findVaultFile(vaultPath, slug) {
+    const entity = resolveFilePath(vaultPath, slug, 'entity');
+    if (existsSync(entity))
+        return entity;
+    const knowledge = resolveFilePath(vaultPath, slug, 'knowledge');
+    if (existsSync(knowledge))
+        return knowledge;
+    return null;
+}
+/** Does this slug name a vault file? An invalid slug definitionally doesn't
+ * exist — reference checks (create parent/related, link targets, validate)
+ * must report "does not exist", not crash. validate() in particular exists to
+ * REPORT malformed refs. */
+export function vaultFileExists(vaultPath, slug) {
+    try {
+        return findVaultFile(vaultPath, slug) !== null;
+    }
+    catch {
+        return false;
+    }
 }
 // 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.
+// The DEEPEST kind-dir occurrence wins: the in-vault dir is always deeper
+// than any ancestor, so a vault living under a directory named 'entities'
+// (e.g. ~/data/entities/myvault) can't shadow its knowledge/ files.
 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'));
+    const lastMatch = (dir) => {
+        let idx = -1;
+        for (const m of filePath.matchAll(new RegExp(`[/\\\\]${dir}[/\\\\]`, 'g')))
+            idx = m.index;
+        return idx;
+    };
+    return lastMatch(KIND_DIRS.entity) > lastMatch(KIND_DIRS.knowledge) ? 'entity' : 'knowledge';
 }
-// Fields that must always be arrays when present (may be scalar in hand-edited YAML)
-const ARRAY_FIELDS = ['related', 'tags', 'domain'];
+/** Fields that must always be arrays when present (may be scalar in
+ * hand-edited YAML). Parsing coerces them here; merge.ts unions them on
+ * conflict — one list, so a new list-valued field cannot be normalized on
+ * read and then overwritten wholesale on merge. */
+export const ARRAY_FIELDS = ['related', 'tags', 'domain'];
 function normalizeFrontmatter(fm) {
     for (const field of ARRAY_FIELDS) {
         if (field in fm && typeof fm[field] === 'string') {
@@ -49,10 +121,41 @@ function normalizeFrontmatter(fm) {
     }
     return fm;
 }
+/** Full-kind path classification (kindFromPath only distinguishes the
+ * indexed kinds — sessions default to knowledge there for compatibility).
+ * Session files live directly in sessions/, so only the immediate parent
+ * counts — matching anywhere in the path misclassifies every file of a
+ * vault that happens to live under a directory named "sessions". */
+export function vaultKindFromPath(filePath) {
+    if (new RegExp(`[/\\\\]${KIND_DIRS.session}[/\\\\][^/\\\\]+$`).test(filePath))
+        return 'session';
+    return kindFromPath(filePath);
+}
+/** Total kind classification for a vault-relative content file (anything
+ * matching VAULT_FILE_RE) — derived from KIND_DIRS, so adding a vault dir
+ * can't silently fall a new kind through to the wrong one. Throws on paths
+ * outside the vault dirs; callers gate on VAULT_FILE_RE first. */
+export function vaultKindFromRelPath(relPath) {
+    for (const [kind, dir] of Object.entries(KIND_DIRS)) {
+        if (relPath.startsWith(`${dir}/`))
+            return kind;
+    }
+    throw new HafezError('VALIDATION_FAILED', `Not a vault content path: ${relPath}`);
+}
 export function parseFilePath(path) {
     const content = readFileSync(path, 'utf-8');
     const { data, content: body } = matter(content, MATTER_OPTIONS);
-    return { frontmatter: normalizeFrontmatter(data), body: body.trim() };
+    const fm = normalizeFrontmatter(data);
+    const trimmed = body.trim();
+    const kind = vaultKindFromPath(path);
+    // Types over classes (C7): the frontmatter is normalized once here and
+    // asserted to the kind's shape — validation of required fields stays with
+    // schema.ts and the index builder, which tolerate malformed files.
+    if (kind === 'entity')
+        return { kind, frontmatter: fm, body: trimmed };
+    if (kind === 'session')
+        return { kind, frontmatter: fm, body: trimmed };
+    return { kind: 'knowledge', frontmatter: fm, body: trimmed };
 }
 export function parseContent(content) {
     const { data, content: body } = matter(content, MATTER_OPTIONS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc",
+    "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "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",

package/skill/SKILL.md

@@ -1,133 +1,71 @@
 ---
 name: hafez
 description: >
-  Hafez vault — personal knowledge base of captures, entities, projects,
-  and knowledge notes (with subtypes: insight, plan). Use when the user says /hafez, asks to query the vault
-  ("what am I working on?", "show active projects", "what's stale?"), wants to
-  read or create an entity, or references Hafez directly. Also use at session
-  start to load context for identifiable topics, and at session end to record
-  a digest. Even if the user just casually mentions a project by name,
-  use this skill to check if it's a Hafez entity.
+  Hafez vault — personal knowledge base of captures, entities, projects, and
+  knowledge notes (subtypes: insight, plan). Use when the user mentions Hafez
+  (or types /hafez), asks what's in the vault ("what am I working on?", "what's
+  stale?"), wants to create or update an entity or knowledge note, at session
+  start to load context for an identifiable topic, at session end to record a
+  digest, when a casually mentioned project name might be a vault entity, or
+  when the user wants to update the tool itself ("update hafez", "upgrade
+  hafez", "is hafez outdated").
 ---
 
 # Hafez — Vault Operations
 
-All operations use the `hafez` CLI. No file manipulation — the CLI handles reads, writes, validation, and git.
+All operations go through the `hafez` CLI — it owns reads, writes, validation, and git. Vault files are never edited directly.
 
 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
+## Situation → Command
 
-Run `hafez help --agent` for the complete, always-current API reference including all commands, flags, batch schema, and valid enum values.
-
-Quick reference for common operations:
+`hafez help --agent` is the complete, always-current API reference (all commands, flags, batch schema, enum values). This table covers the common situations; consult `help --agent` for anything beyond it.
 
 | Situation | Command |
 |-----------|---------|
-| Read an entity | `hafez read <slug>` |
-| Active projects | `hafez query --filter active` |
+| Read an entity (incl. a project the user mentions) | `hafez read <slug>` |
+| "What am I working on?" / active projects | `hafez query --filter active` |
 | Stale items | `hafez query --filter stale` |
-| Full-text search | `hafez search "<terms>"` |
-| Search knowledge only | `hafez search "<terms>" --kind knowledge` |
-| Create entity | `hafez create entity "<name>" --type project [--purpose "text"] [--description "text"] [--resource "uri"] [--brief "text"] [--add-action "task"]` |
-| Quick capture | `hafez capture "<name>"` |
+| Full-text search | `hafez search "<terms>"` (`--kind knowledge` to narrow) |
 | List inbox captures | `hafez query --filter capture` |
-| Update entity | `hafez update <slug> --brief "text" --add-action "task"` |
-| Complete action | `hafez update <slug> --complete-action "substring"` |
-| Session log | `hafez update <slug> --log "progress: summary" --agent claude` |
-| Link entities | `hafez link <slug> <target> --relation related` |
+| Children of a project | `hafez query --parent <slug>` |
+| Related entities/knowledge | `hafez query --related-to <slug>` |
+| New workstream | `hafez create entity "<name>" --type project [--brief "context"] [--add-action "task"]` (full flag list in `help --agent`; `--purpose` is project-only) |
+| New plan | `hafez create knowledge "<name>" --subtype plan [--status active\|done]` (plans have Goal/Steps/Dependencies — no `--synthesis`; `--status` is plan-only) |
+| Quick thought, no classification yet | `hafez capture "<name>"` |
 | Promote | `hafez promote <slug> <target>` (capture→entity/project/knowledge, entity→project) |
-| Add synthesis to knowledge | `hafez update <slug> --synthesis "text"` |
-| 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) |
+| Set handoff context / summary / URI | `hafez update <slug> --brief "text"` / `--description "summary"` / `--resource "https://..."` |
+| Add / complete a next action | `hafez update <slug> --add-action "task"` / `--complete-action "substring"` |
+| Significant milestone (deployed, merged, bug found) | `hafez update <slug> --log "progress: summary" --agent claude` |
+| Link entities | `hafez link <slug> <target> --relation related` (or `parent` when a thread belongs to a project) |
+| Revise a knowledge insight | `hafez update <slug> --synthesis "text"` (`--insight` is an alias) |
+| Back knowledge with evidence / a source | `hafez update <slug> --add-evidence "text"` / `--add-source "url"` |
 | Digest session → batch | `echo '{...}' \| hafez digest \| hafez batch` (no pipes? `--file` on both) |
 
-Note: `--insight` is an alias for `--synthesis`.
-
 ## Session Start — Context Loading
 
-When a topic is identifiable from the user's first message:
+Load context only when a specific entity slug or topic is identifiable from the user's first message:
 
 1. Run `hafez read <slug>` to load entity context
 2. If the entity has a `parent`, also read the parent at frontmatter depth: `hafez read <parent> --depth frontmatter`
 3. Search for related knowledge (`hafez search "<topic>" --kind knowledge`) and read any relevant note: `hafez read <knowledge-slug>`
 4. Present a brief context line: "Loaded context for {name} (status: {status}, next: {next_action})"
 
-Don't load context speculatively. Only when you can identify a specific entity slug or topic.
-
-## Mid-Session — Working With the Vault
-
-| Situation | Action |
-|-----------|--------|
-| User asks "what am I working on?" | `hafez query --filter active` |
-| User asks about stale items | `hafez query --filter stale` |
-| User mentions a project by name | `hafez read <slug>` |
-| New workstream emerges | `hafez create entity "<name>" --type project [--brief "context"] [--add-action "task"]` |
-| Quick thought, no classification | `hafez capture "<name>"` |
-| Promote capture to entity/project | `hafez promote <slug> entity` |
-| Insight worth preserving | Search first (`hafez search "<topic>"`), then create or update |
-| Entity relates to another | `hafez link <slug> <target> --relation related` |
-| Thread belongs to a project | `hafez link <slug> <parent> --relation parent` |
-| Knowledge needs new synthesis | `hafez update <slug> --synthesis "text"` |
-| Knowledge backed by new evidence | `hafez update <slug> --add-evidence "text"` |
-| Knowledge has a source to cite | `hafez update <slug> --add-source "url"` |
-| Need children of a project | `hafez query --parent <slug>` |
-| Need related entities/knowledge | `hafez query --related-to <slug>` |
-| Search for something | `hafez search "<terms>"` |
-| Set handoff context | `hafez update <slug> --brief "context"` |
-| Set one-line description | `hafez update <slug> --description "summary"` |
-| Set resource URI (entity) | `hafez update <slug> --resource "https://..."` |
-| Add a next action | `hafez update <slug> --add-action "task"` |
-| Complete a next action | `hafez update <slug> --complete-action "task"` |
-| Rebuild stale index | `hafez index rebuild` |
-| Pull latest from remote | `hafez sync` |
-
-### Ingest Reflex — Before Creating New Knowledge
-
-Before creating a new knowledge note, always check if one already exists:
-
-```bash
-hafez search "<topic>"
-hafez search "<topic>" --kind knowledge
-```
-
-If a related note exists, update it rather than creating a duplicate. Use `--synthesis` to revise the main insight text, `--add-evidence` to append supporting evidence, or `--add-source` to cite a new source.
-
-Only create a new note when no existing knowledge covers the topic.
-
-### Wiki Links in Knowledge Notes
-
-When writing or updating knowledge note prose (brief, synthesis, insight body), use `[[wiki links]]` to reference related entities and knowledge naturally. This makes the vault navigable as a wiki:
-
-- Reference related projects: `[[project-slug]]`
-- Reference other knowledge: `[[knowledge-slug]]`
-- Reference people or areas: `[[entity-slug]]`
-
-The CLI does not enforce link syntax — write them naturally in the prose content you pass to `--synthesis`, `--brief`, or `--insight`.
+## Search-First Ingest
 
-### Deliberate Ingest Pattern
+A new knowledge note is a last resort. When an insight emerges or a source (document, conversation, research) is being processed:
 
-When processing a source (document, conversation, research) to extract knowledge:
+1. Search for existing coverage: `hafez search "<topic>"`, narrowing with `--kind knowledge`.
+2. A note covers the topic → update it: `--synthesis` to revise the main insight, `--add-evidence` to append support, `--add-source` to cite.
+3. Nothing covers it → create it linked from birth (`hafez create knowledge "<name>" --related slug1,slug2`), then write the body via `--synthesis`.
 
-```bash
-# 1. Search for existing coverage
-hafez search "<topic>" --kind knowledge
-
-# 2a. If exists — update it
-hafez update <slug> --synthesis "Revised insight" --add-source "url"
-hafez update <slug> --add-evidence "New evidence from source"
-
-# 2b. If new — create it
-hafez create knowledge "<name>" --related slug1,slug2
+Write `[[wiki links]]` in any knowledge prose (`--brief`, `--synthesis`) to reference related projects, entities, and notes — the CLI does not enforce link syntax; write them naturally in the text. This is what keeps the vault navigable as a wiki.
 
-# 3. Then update the note body via --synthesis with wiki links to related notes
-hafez update <slug> --synthesis "Insight text referencing [[related-slug]]"
-```
+**Knowledge boundary:** before writing an insight down, ask where it belongs. Useful beyond the current session or repo → vault knowledge note. Specific to one repo's code or workflow → that repo's own docs (CLAUDE.md, README, comments), not the vault.
 
 ## Batch Operations
 
-**Rule: Use `hafez batch` when making 2+ mutating calls.** Individual commands auto-commit after each call (and push, when the vault has a remote). Running multiple individual commands back-to-back causes git push races on synced vaults. Batch does all operations in one commit + one push.
+**Rule: Use `hafez batch` when making 2+ mutating calls.** Individual commands auto-commit after each call (and push, when the vault has a remote). Running multiple individual commands back-to-back causes git push races on synced vaults. Batch does all operations in one commit + one push. For a single operation, individual commands are fine — they auto-sync.
 
 ```bash
 echo '[
@@ -147,8 +85,6 @@ On shells that can't pipe stdin to native executables (Windows PowerShell 5.1),
 
 **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
 
 At the end of a working session (or a natural breakpoint), record what happened:
@@ -173,24 +109,29 @@ Digest adds a session log entry to each touched entity and creates a session not
 
 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.
 
-**Mid-session updates and the digest coexist.** Point-in-time updates (`--status done`, `--complete-action`, brief changes) happen as they happen — don't defer them to session end. Digest adds the overall narrative on top. Do NOT hand-write session log entries (`--log`) right before digesting — digest builds the session summary itself. Use `--log` mid-session only for significant milestones (deployed, merged, discovered a bug).
+**Mid-session updates and the digest coexist.** Point-in-time updates (`--status done`, `--complete-action`, brief changes) happen as they happen — digest adds the overall narrative on top. Digest builds the session summary itself, so the session's closing log entry comes from digest; reserve hand-written `--log` for significant mid-session milestones (deployed, merged, discovered a bug).
 
-## Knowledge Maintenance
+Session end is also when knowledge gets written: review what was learned and run Search-First Ingest on anything worth keeping. Knowledge notes are the primary durable output of sessions — not a side effect.
 
-Knowledge notes are the primary durable output of sessions — not a side effect. Treat the vault as a living wiki.
+## Periodic Lint
 
-**Active maintenance pattern:**
-1. At session start: search for knowledge relevant to the topic
-2. During work: when insights emerge, search before creating — update existing notes first
-3. Use `[[wiki links]]` in knowledge prose to connect related concepts
-4. At session end: review what was learned and update or create knowledge notes
+Run at session end or on demand:
 
-**Periodic lint** (run at session end or on demand):
 ```bash
 hafez validate
-hafez query --kind knowledge --filter stale
+hafez query --kind knowledge --sort-by last_reinforced --sort-order asc --limit 20
 ```
-Surface orphaned notes (no related links) and stale knowledge for review or archival.
 
-**Knowledge boundary:** before writing an insight down, ask where it belongs. Useful beyond the current session or repo → vault knowledge note. Specific to one repo's code or workflow → that repo's own docs (CLAUDE.md, README, comments), not the vault.
+Surface orphaned notes (no related links) and the least-recently-reinforced knowledge for review or archival. (`--filter` is entity status — knowledge notes have none, so the query command rejects it under `--kind knowledge`.)
+
+## Updating Hafez Itself
+
+"update hafez" means the **tool**. `hafez update` is an entity update — a different thing entirely. Don't confuse them.
+
+1. Run `hafez upgrade`. It checks and prints; it never installs.
+2. Show the user the printed commands **verbatim** and wait for an explicit yes. They install code and overwrite the user's own agent instructions file — never run them unattended, and never run the tarball alternative alongside the npm install.
+3. Run the approved steps, then re-run `hafez upgrade` to verify.
+
+If `hafez upgrade` fails with the literal prefix `Unknown command:`, the installed hafez predates it. Install the current version, re-copy the bundled skill, then run `hafez upgrade` — the README's Updating section (github.com/shrvn-r/hafez) has the exact commands.
 
+`hafez upgrade` also prints the current integration snippet. Compare it against the Hafez block in the user's global instructions file and offer to reconcile differences — don't rewrite their file unasked.