hafez 1.4.0 → 2.0.0

package/dist/surfaces/surfaces.js

@@ -0,0 +1,230 @@
+// src/surfaces/surfaces.ts
+//
+// Surfaces of the Agent Contract and how the static ones compose Items. A
+// static Surface is text the binary writes out (the Block, the two skill
+// files); a binary Surface is command output whose Items carry a render
+// function. Every Surface has the label the owner table names it by.
+//
+// Hashes (onboard decision #58): first 12 hex of SHA-256. The Block's begin
+// marker hashes the text between the marker lines; a skill file's `hash:`
+// frontmatter line hashes everything after the closing `---`.
+import { createHash } from 'crypto';
+import { ITEMS } from './items.js';
+export const SURFACES = {
+    block: {
+        label: 'Block',
+        compose: place => [
+            '## Hafez',
+            '',
+            'Hafez is this user\'s vault: what they are working on (entities) and what they have learned (knowledge). You reach it only through the `hafez` command.',
+            '',
+            `**Load.** ${place('loadTriggers')}`,
+            '',
+            '**Write as it happens.** Each of these is due the moment it occurs:',
+            '',
+            place('writeTriggers'),
+            '',
+            place('createLines'),
+            '',
+            '**Rules.**',
+            '',
+            `- ${place('neverAsk')}`,
+            `- ${place('readBeforeWrite')}`,
+            `- ${place('oneCommand')}`,
+            `- ${place('openActions')}`,
+            `- ${place('neverEditByHand')}`,
+            `- ${place('neverSaveUnprompted')}`,
+            '',
+        ].join('\n'),
+    },
+    hafezSkillDescription: {
+        label: '`hafez` skill description',
+        compose: () => 'Hafez vault: the less common operations and the tool itself. Use when the user asks what is in the vault ("what am I working on?", "what\'s stale?"), wants to promote, link, unlink, delete, change a status or validate, or wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez"). Also the reference to read when no Hafez block is in your instructions.',
+    },
+    hafezSkillBody: {
+        label: '`hafez` skill body',
+        compose: place => [
+            '',
+            '# Hafez',
+            '',
+            '- Update an entity or note: `hafez read <slug>`. The end of its output shows the write command.',
+            '- Create an entity or a knowledge note: the two `hafez create` lines below.',
+            '- Save the session: the `hafez-save` skill. No skill: `hafez schema digest`.',
+            '',
+            place('neverAsk'),
+            place('readBeforeWrite'),
+            place('openActions'),
+            '',
+            '## Create',
+            '',
+            place('createLines'),
+            '',
+            '## Find',
+            '',
+            place('find'),
+            '',
+            '## Less common operations',
+            '',
+            place('rareOps'),
+            '',
+            `${place('batchShape')} Machine-readable shape of any op: \`hafez schema <op>\`, with \`--examples\` for a sample.`,
+            '',
+            '## The tool itself',
+            '',
+            place('upgradeReconfigure'),
+            '',
+        ].join('\n'),
+    },
+    hafezSaveDescription: {
+        label: '`hafez-save` description',
+        compose: place => place('saveTrigger'),
+    },
+    hafezSaveBody: {
+        label: '`hafez-save` body',
+        compose: place => ['', '# Save the session', '', place('saveMechanics'), ''].join('\n'),
+    },
+    read: { label: 'Binary: `read`' },
+    readHeader: { label: 'Binary: `read` header' },
+    readFooter: { label: 'Binary: `read` Footer' },
+    readMiss: { label: 'Binary: `read` miss' },
+    updateSuccess: { label: 'Binary: `update` success output' },
+    updateMisuse: { label: 'Binary: `update` misuse error' },
+    createKnowledge: { label: 'Binary: `create knowledge` output' },
+    digestError: { label: 'Binary: `digest` error' },
+    batchMisuse: { label: 'Binary: `batch` misuse error' },
+    mechanised: { label: 'Binary, mechanised' },
+    schema: { label: '`schema`' },
+    onboard: { label: '`onboard`' },
+};
+export const contentHash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
+/** Compose a static Surface, placing each Item's text in the form its role
+ * (Owner or fallback) calls for. `onPlace` sees every placement, nested ones
+ * included. */
+function composeWith(items, surfaceId, surface, onPlace = () => { }) {
+    const place = (id) => {
+        onPlace(id);
+        const item = items[id];
+        if (!item)
+            throw new Error(`${surfaceId} places unknown Item ${id}`);
+        const text = item.text;
+        if (typeof text === 'function')
+            return text(place, item.owner === surfaceId ? 'owner' : 'fallback');
+        if (text === undefined)
+            throw new Error(`${surfaceId} places ${id}, which has no text`);
+        return text;
+    };
+    if (!surface.compose)
+        throw new Error(`${surfaceId} is not a static surface`);
+    return surface.compose(place);
+}
+const compose = (id) => composeWith(ITEMS, id, SURFACES[id]);
+/** An Item's text as a binary Surface places it at run time, in the form its
+ * role there (Owner or fallback) calls for. */
+export function placeIn(surfaceId, id) {
+    const item = ITEMS[id];
+    if (surfaceId !== item.owner && surfaceId !== item.fallback) {
+        throw new Error(`${surfaceId} places ${id}, which is neither its owner nor its fallback`);
+    }
+    return composeWith(ITEMS, surfaceId, { label: SURFACES[surfaceId].label, compose: place => place(id) });
+}
+/** YAML folded scalar lines: greedy wrap at 76 columns, two-space indent. */
+function fold(text) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(' ')) {
+        if (line && 2 + line.length + 1 + word.length > 76) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    lines.push(line);
+    return lines.map(l => `  ${l}`).join('\n');
+}
+function skillFile(name, description, body) {
+    const text = compose(body);
+    return `---\nname: ${name}\ndescription: >\n${fold(compose(description))}\nhash: ${contentHash(text)}\n---\n${text}`;
+}
+export function renderBlock() {
+    const inner = compose('block');
+    return `<!-- hafez:begin ${contentHash(inner)} -->\n${inner}<!-- hafez:end -->\n`;
+}
+/** `onboard --block`, what the SessionStart hook prints: the Block, then the
+ * read line for each entity matching the folder. */
+export function renderBlockHook(matches) {
+    return matches.length === 0 ? renderBlock() : `${renderBlock()}\n${ITEMS.folderMatch.render(matches)}\n`;
+}
+export const renderHafezSkill = () => skillFile('hafez', 'hafezSkillDescription', 'hafezSkillBody');
+/** `help --agent`: the `hafez` skill body, the one text, without the blank
+ * line that parts it from the skill file's frontmatter or the newline that
+ * ends the file (the CLI adds one to every output). */
+export const renderAgentHelp = () => compose('hafezSkillBody').replace(/^\n/, '').replace(/\n$/, '');
+export const renderHafezSaveSkill = () => skillFile('hafez-save', 'hafezSaveDescription', 'hafezSaveBody');
+// --- The owner table, rendered into a marked region of the contract README ---
+export const OWNER_TABLE_BEGIN = '<!-- owner-table:begin (rendered from src/surfaces/items.ts; edit the Item, then run scripts/render-surfaces.ts) -->';
+export const OWNER_TABLE_END = '<!-- owner-table:end -->';
+export function renderOwnerTable() {
+    const rows = Object.values(ITEMS).map((item) => {
+        const fallback = item.fallback ? SURFACES[item.fallback].label : '—';
+        return `| ${item.label} | ${SURFACES[item.owner].label} | ${fallback} | ${item.invokeOnly} |`;
+    });
+    return ['| Item | Owner | Fallback | Invoke-only |', '|---|---|---|---|', ...rows, ''].join('\n');
+}
+/** Replace the marked owner-table region of `doc` with a fresh render. */
+export function spliceOwnerTable(doc) {
+    const begin = doc.indexOf(OWNER_TABLE_BEGIN);
+    const end = doc.indexOf(OWNER_TABLE_END, begin);
+    if (begin < 0 || end < 0)
+        throw new Error('owner table markers missing or out of order');
+    if (doc.indexOf(OWNER_TABLE_BEGIN, begin + 1) >= 0 || doc.indexOf(OWNER_TABLE_END, end + 1) >= 0) {
+        throw new Error('owner table markers appear more than once');
+    }
+    return doc.slice(0, begin + OWNER_TABLE_BEGIN.length) + '\n' + renderOwnerTable() + doc.slice(end);
+}
+// --- Drift check 2: the typed Item table ---
+/** Every problem with the Item table: an Item with no Owner or no evidence
+ * pointer, an Item its Owner or static fallback never places, or one placed more than once in a
+ * Surface or in a Surface that is neither its Owner nor its declared fallback.
+ * Placement is checked for static Surfaces only; binary ones place at run time. */
+export function itemProblems(items, surfaces) {
+    const problems = [];
+    const placed = {};
+    for (const [sid, surface] of Object.entries(surfaces)) {
+        if (!surface.compose)
+            continue;
+        const counts = (placed[sid] = {});
+        try {
+            composeWith(items, sid, surface, id => { counts[id] = (counts[id] ?? 0) + 1; });
+        }
+        catch (err) {
+            problems.push(err.message);
+        }
+    }
+    for (const [id, item] of Object.entries(items)) {
+        if (!item.owner)
+            problems.push(`${id}: no owner`);
+        else if (!surfaces[item.owner])
+            problems.push(`${id}: unknown owner ${item.owner}`);
+        if (item.fallback && !surfaces[item.fallback])
+            problems.push(`${id}: unknown fallback ${item.fallback}`);
+        if (!item.evidence?.trim())
+            problems.push(`${id}: no evidence pointer`);
+        for (const [sid, counts] of Object.entries(placed)) {
+            const n = counts[id] ?? 0;
+            if (n > 0 && sid !== item.owner && sid !== item.fallback) {
+                problems.push(`${id}: placed in ${sid}, which is neither its owner nor its fallback`);
+            }
+            if (n > 1)
+                problems.push(`${id}: placed ${n} times in ${sid}`);
+        }
+        if (item.owner && surfaces[item.owner]?.compose && !placed[item.owner]?.[id]) {
+            problems.push(`${id}: not placed in its owner ${item.owner}`);
+        }
+        if (item.fallback && surfaces[item.fallback]?.compose && !placed[item.fallback]?.[id]) {
+            problems.push(`${id}: not placed in its fallback ${item.fallback}`);
+        }
+    }
+    return problems;
+}

package/dist/types.d.ts

@@ -9,18 +9,23 @@ export type LinkRelation = 'parent' | 'related';
 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];
+/** Sort fields, and the two an entity query cannot honour — reinforcement
+ * lives on knowledge notes only. Asking for one on the entity branch is a
+ * validation error, not a silent fall back to recency, so the entity opts
+ * type declares only what that branch can actually sort by. */
+export type SortField = 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+export type EntitySortField = Exclude<SortField, 'last_reinforced' | 'reinforcement_count'>;
 export interface EntityQueryOpts {
     filter?: QueryFilter;
     type?: EntityType;
     parent?: string;
     domain?: string;
-    confidence?: ConfidenceLevel;
     since?: string;
     before?: string;
     createdSince?: string;
     createdBefore?: string;
     tags?: string[];
-    sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+    sort_by?: EntitySortField;
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
@@ -34,18 +39,31 @@ export interface KnowledgeQueryOpts {
     createdSince?: string;
     createdBefore?: string;
     tags?: string[];
-    sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+    sort_by?: SortField;
     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';
+/** `kind: 'all'` (or unset): reaches both sides, so it takes opts from both
+ * and can honour every sort field. Status filters narrow the entity side only
+ * — knowledge notes carry no status and are never excluded by one. */
+export interface AllQueryOpts extends Omit<EntityQueryOpts, 'sort_by'> {
+    kind?: 'all';
+    confidence?: ConfidenceLevel;
     subtype?: KnowledgeSubtype;
+    sort_by?: SortField;
 }
+/** The unified query, discriminated on `kind`. Naming a single kind narrows
+ * this query to that kind's opts, because a narrowed branch maps no more than
+ * the dedicated one does: an out-of-scope condition would land on a column the
+ * selected kind leaves NULL and silently exclude every row. The read surface
+ * rejects those at runtime for callers without types; the union is what makes
+ * them a compile error first. */
+export type UnifiedQueryOpts = AllQueryOpts | (EntityQueryOpts & {
+    kind: 'entity';
+}) | (KnowledgeQueryOpts & {
+    kind: 'knowledge';
+});
 export interface EntityFrontmatter {
     name: string;
     type: EntityType;
@@ -96,12 +114,11 @@ export type ParsedVaultFile = {
     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;
-}
+/** What read() returns: the indexed arms of ParsedVaultFile (a session slug is
+ * never resolvable through read()), so consumers narrow on `kind`. */
+export type ParsedFile = Extract<ParsedVaultFile, {
+    kind: 'entity' | 'knowledge';
+}>;
 export interface SessionLogEntry {
     type: SessionLogType;
     summary: string;
@@ -119,12 +136,14 @@ export interface UpdateFields {
     status?: EntityStatus;
     current_state?: string;
     session_log?: SessionLogEntry;
+    agent?: string;
     brief?: string | null;
     add_action?: string;
     add_actions?: string[];
     complete_action?: string;
     remove_action?: string;
     clear_actions?: boolean;
+    parent?: string;
     description?: string | null;
     resource?: string | null;
     domain?: string[];
@@ -137,7 +156,9 @@ export interface UpdateFields {
     add_source?: string;
 }
 export interface UpdateResult {
-    matched_action?: string;
+    completed_action?: string;
+    removed_action?: string;
+    logged?: true;
 }
 export interface CreateEntityFields {
     type: EntityType;
@@ -155,6 +176,7 @@ export interface CreateEntityFields {
 export interface CreateKnowledgeFields {
     subtype?: KnowledgeSubtype;
     status?: PlanStatus;
+    confidence?: ConfidenceLevel;
     synthesis?: string;
     insight?: string;
     description?: string;
@@ -208,7 +230,6 @@ export interface ValidationIssue {
 export interface ValidationReport {
     broken_slugs: ValidationIssue[];
     orphaned_knowledge: string[];
-    oversized_related: ValidationIssue[];
     missing_fields: ValidationIssue[];
     total_entities: number;
     total_knowledge: number;
@@ -307,7 +328,13 @@ export type BatchOperation = {
     op: 'promote';
     slug: string;
     target: 'entity' | 'project' | 'knowledge';
+} | {
+    op: 'delete';
+    slug: string;
 };
+/** What `delete` may remove. An entity is never deleted: it is retired with
+ * `status: done`. */
+export type DeletableKind = 'knowledge' | 'session';
 export interface BatchOpValidation {
     index: number;
     op: string;
@@ -380,6 +407,8 @@ export interface Hafez {
     link(slug: string, target: string, relation: LinkRelation): Promise<void>;
     unlink(slug: string, target: string, relation: LinkRelation): Promise<void>;
     promote(slug: string, target: 'entity' | 'project' | 'knowledge'): Promise<string>;
+    /** Delete a knowledge or session note; resolves to the kind deleted. */
+    delete(slug: string): Promise<DeletableKind>;
     batch(operations: BatchOperation[]): Promise<BatchResult[]>;
     validateBatch(operations: BatchOperation[]): Promise<BatchValidationReport>;
     sync(): Promise<{

package/dist/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationReport } from './types.js';
+/** The vault integrity scan. Deliberately independent of the SQLite index:
+ * this is the one operation that does not trust the index, so it reads the
+ * files directly. Re-implementing it as an index query was considered and
+ * rejected — an integrity checker that reads the index is checking the
+ * index's model of the vault, not the vault. */
+export declare function validateVault(vaultPath: string): ValidationReport;

package/dist/validate.js

@@ -0,0 +1,109 @@
+import { join, basename } from 'path';
+import { parseFilePath, scanVaultDir, kindDir, vaultFileExists } from './vault.js';
+import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
+import { parentCycle } from './batch-ops.js';
+/** The vault integrity scan. Deliberately independent of the SQLite index:
+ * this is the one operation that does not trust the index, so it reads the
+ * files directly. Re-implementing it as an index query was considered and
+ * rejected — an integrity checker that reads the index is checking the
+ * index's model of the vault, not the vault. */
+export function validateVault(vaultPath) {
+    const exists = (slug) => vaultFileExists(vaultPath, slug);
+    const report = {
+        broken_slugs: [],
+        orphaned_knowledge: [],
+        missing_fields: [],
+        total_entities: 0,
+        total_knowledge: 0,
+    };
+    const knowledgeSlugs = new Set();
+    const referencedKnowledge = new Set();
+    const parents = new Map();
+    // Scan entities
+    const entDir = join(vaultPath, kindDir('entity'));
+    {
+        const files = scanVaultDir(entDir);
+        report.total_entities = files.length;
+        for (const filePath of files) {
+            const slug = basename(filePath, '.md');
+            let fm;
+            try {
+                fm = parseFilePath(filePath).frontmatter;
+            }
+            catch {
+                report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
+                continue;
+            }
+            const errors = validateEntityFrontmatter(fm);
+            for (const e of errors)
+                report.missing_fields.push({ slug, field: '', issue: e });
+            if (fm.parent) {
+                parents.set(slug, fm.parent);
+                if (!exists(fm.parent))
+                    report.broken_slugs.push({ slug, field: 'parent', issue: `parent '${fm.parent}' does not exist` });
+            }
+            if (fm.related && Array.isArray(fm.related)) {
+                for (const r of fm.related) {
+                    if (!exists(r))
+                        report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
+                    // Track referenced knowledge
+                    referencedKnowledge.add(r);
+                }
+            }
+        }
+    }
+    // Parent cycles: reported once each, under the first member found
+    const inCycle = new Set();
+    for (const [slug, parent] of parents) {
+        if (inCycle.has(slug))
+            continue;
+        const cycle = parentCycle(slug, parent, s => parents.get(s));
+        if (!cycle)
+            continue;
+        for (const s of cycle)
+            inCycle.add(s);
+        report.broken_slugs.push({ slug, field: 'parent', issue: `parent cycle: ${cycle.join(' → ')}` });
+    }
+    // Scan knowledge
+    const knDir = join(vaultPath, kindDir('knowledge'));
+    {
+        const files = scanVaultDir(knDir);
+        report.total_knowledge = files.length;
+        for (const filePath of files) {
+            const slug = basename(filePath, '.md');
+            knowledgeSlugs.add(slug);
+            let fm;
+            try {
+                fm = parseFilePath(filePath).frontmatter;
+            }
+            catch {
+                report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
+                continue;
+            }
+            const errors = validateKnowledgeFrontmatter(fm);
+            for (const e of errors)
+                report.missing_fields.push({ slug, field: '', issue: e });
+            if (fm.related && Array.isArray(fm.related)) {
+                for (const r of fm.related) {
+                    if (!exists(r))
+                        report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
+                }
+            }
+        }
+    }
+    // Find orphaned knowledge: no related, and not referenced by any entity
+    for (const slug of knowledgeSlugs) {
+        let fm;
+        try {
+            fm = parseFilePath(join(knDir, `${slug}.md`)).frontmatter;
+        }
+        catch {
+            continue; // already reported above
+        }
+        const hasRelated = fm.related && Array.isArray(fm.related) && fm.related.length > 0;
+        if (!hasRelated && !referencedKnowledge.has(slug)) {
+            report.orphaned_knowledge.push(slug);
+        }
+    }
+    return report;
+}

package/dist/vault.js

@@ -11,7 +11,7 @@ export function slugify(name) {
     // real slug instead of collapsing to ''.
     return name
         .toLowerCase()
-        .replace(/['']/g, '')
+        .replace(/['’]/g, '')
         .replace(/[^\p{L}\p{N}]+/gu, '-')
         .replace(/^-|-$/g, '')
         .replace(/-{2,}/g, '-');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,8 +18,9 @@
   ],
   "scripts": {
     "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",
+    "install:local": "chmod +x \"$(pwd)/dist/cli.js\" && mkdir -p ~/.local/bin && ln -sf \"$(pwd)/dist/cli.js\" ~/.local/bin/hafez && for d in ~/.claude/skills ~/.agents/skills; do for s in hafez hafez-save; do mkdir -p \"$d/$s\" && cp \"$(pwd)/skill/$s/SKILL.md\" \"$d/$s/SKILL.md\"; done; done",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "pretest": "npm run build && npm run typecheck",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepare": "npm run build"

package/skill/hafez/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: hafez
+description: >
+  Hafez vault: the less common operations and the tool itself. Use when the
+  user asks what is in the vault ("what am I working on?", "what's stale?"),
+  wants to promote, link, unlink, delete, change a status or validate, or
+  wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez").
+  Also the reference to read when no Hafez block is in your instructions.
+hash: 01a30ae1e209
+---
+
+# Hafez
+
+- Update an entity or note: `hafez read <slug>`. The end of its output shows the write command.
+- Create an entity or a knowledge note: the two `hafez create` lines below.
+- Save the session: the `hafez-save` skill. No skill: `hafez schema digest`.
+
+Never ask the user whether to write to the vault. Write, then say so in one line naming the slug and what you did.
+Update only what you have read this session. Not read yet: read it first.
+Open actions on an entity you read are yours: tick what landed, drop what is dead. Lines `read` marks stale are due.
+
+## Create
+
+```
+hafez create entity "<name>" --type <project|entity> --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"
+hafez create knowledge "<name>" --synthesis "<the insight>" --confidence <observation|pattern|principle> --related <slug>
+```
+
+A plan is `--subtype plan` without `--synthesis`. Cannot tell entity from knowledge: `hafez capture "<name>"`.
+
+## Find
+
+```
+hafez query --filter <active|paused|done|stale|capture>
+hafez search "<terms>" --kind <entity|knowledge>
+hafez stats
+```
+
+## Less common operations
+
+```
+hafez promote <slug> <entity|project|knowledge>
+hafez link <slug> <target> --relation <parent|related>
+hafez unlink <slug> <target> --relation <parent|related>
+hafez update <slug> --status <active|paused|done>
+hafez delete <slug>
+hafez validate
+```
+
+A plan's status is `active|done`. `delete` removes a knowledge or session note only; an entity is retired with `--status done`.
+
+Several writes that must land together go in one batch: a bare array, no wrapper. A slug is the name lowercased, apostrophes dropped, each other run of characters that are not letters or digits turned into one `-` and none left at either end, so a later op can name what an earlier one creates.
+
+```
+hafez batch --data '[
+  {"op":"create","kind":"entity","name":"Token Rotation","fields":{"type":"entity"}},
+  {"op":"link","slug":"token-rotation","target":"auth-refactor","relation":"parent"}
+]'
+```
+
+In the JSON, write each apostrophe as `’` (`isn’t`): a straight `'` ends the quoted argument and the batch fails.
+
+No pipe (PowerShell 5.1): `hafez batch --file ops.json`. Machine-readable shape of any op: `hafez schema <op>`, with `--examples` for a sample.
+
+## The tool itself
+
+- Upgrade: `hafez upgrade`. It checks and prints, it never installs. Show the user the printed steps and run them only after a yes.
+- Set up or reconfigure: `hafez onboard`.

package/skill/hafez-save/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: hafez-save
+description: >
+  Save this session to the Hafez vault. Use when the user invokes hafez-save
+  or says "save", "save the session" or "wrap up". Never run it unprompted.
+hash: 91351681e779
+---
+
+# Save the session
+
+1. List the slugs you read, updated or created this session. Use only those; a slug you did not see in `hafez` output this session does not go in. No slugs: tell the user there is nothing to save and stop.
+2. Run this once, with today's date:
+
+```
+hafez digest --data '{
+  "entities_touched": ["<slug>", "<slug>"],
+  "decisions": ["<a decision made this session>"],
+  "narrative": "<one to three sentences: what happened and how it connects>",
+  "session_date": "<YYYY-MM-DD>"
+}' | hafez batch
+```
+
+In the JSON, write each apostrophe as `’` (`isn’t`): a straight `'` ends the quoted argument and the save fails.
+
+No pipe (PowerShell 5.1): put the JSON in `summary.json`, then `hafez digest --file summary.json > ops.json`, then `hafez batch --file ops.json`.
+
+3. Tell the user in one line: the session note's slug and the entities it logged to.
+
+`decisions` may be an empty array. Each slug in `entities_touched` gets a session log entry and the session note links them all. An unknown slug fails the save and names the slug: fix the list and run it again. A session already saved is skipped, so a second run does no harm.

package/dist/cli/help-agent.d.ts

@@ -1 +0,0 @@
-export declare function renderAgentHelp(): string;