hafez 2.1.0 → 2.3.0

package/README.md

@@ -1,5 +1,7 @@
 # Hafez
 
+[![CI](https://github.com/shrvn-r/hafez/actions/workflows/public.yml/badge.svg?branch=main)](https://github.com/shrvn-r/hafez/actions/workflows/public.yml)
+
 **A knowledge and project vault shared between you and your agents.** *Hafez* (حافظ) is Persian for "the keeper — the one who memorizes," after the poet. Plain markdown files you own, backed by SQLite full-text search and git.
 
 ## Why
@@ -77,6 +79,23 @@ plus `--allow-remote=root`, which npm 12+ requires for a remote URL:
 npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz --allow-scripts=better-sqlite3 --allow-remote=root
 ```
 
+### Cloud sessions
+
+A Claude Code cloud session (claude.ai/code, the mobile app) starts in a fresh
+container: no `hafez`, no vault, no Block. Keep the vault in a private GitHub
+repo and print the environment's setup script for it:
+
+```bash
+hafez onboard --cloud --vault-repo <owner>/<vault-repo>
+```
+
+Paste the script into the cloud environment's Setup script; the Trusted network
+policy is enough. It installs Hafez, registers the vault when it is attached to
+the session, and writes a Block with one rule more: a session started without
+the vault attached attaches it, clones it and registers it, with one approval
+from you. The script never clones the vault itself, because it runs without
+GitHub credentials. Writes push to the vault's `main` like anywhere else.
+
 ## Updating
 
 Tell your agent: **update hafez**. Or paste: "Run `hafez upgrade` and follow
@@ -148,6 +167,9 @@ hafez query --kind knowledge --domain security
 # Full-text search across the whole vault
 hafez search "token rotation"
 
+# See it in context: a live graph of the vault in your browser
+hafez graph auth-refactor
+
 # Record progress
 hafez update auth-refactor --log "progress: JWT flow implemented"
 hafez update auth-refactor --complete-action "migration plan"
@@ -161,7 +183,7 @@ Three kinds of documents, all markdown + YAML frontmatter:
 
 - **Entities** (`entities/*.md`) — the things you're working on. Types: `capture` (inbox item), `entity` (anything worth tracking), `project` (has outcomes). Statuses: `active | paused | done`. Bodies start from a per-type template (capture: `## Notes`; entity: `## Context`; project: `## Purpose` + `## Goals`) plus a `## Session Log` of dated agent entries; `## Brief` (freeform handoff context) and `## Next Actions` (checkbox list) appear when first written to.
 - **Knowledge** (`knowledge/*.md`) — durable insights that outlive any one project. Subtypes `insight | plan`; confidence levels `observation → pattern → principle` (promoted manually). Bodies hold `## Synthesis`, `## Evidence`, and `## Sources` — evidence accumulates over time via `--add-evidence`.
-- **Sessions** (`sessions/*.md`) — session summaries written via `batch`, kept as history, not indexed.
+- **Sessions** (`sessions/*.md`) — session summaries written at save time, never updated. Readable (`hafez read <slug>`), listed newest first (`hafez query --kind session`), and the look back from an entity (`hafez query --related-to <slug>`); search and query reach them only under `--kind session` or `--kind all`.
 
 Frontmatter at a glance:
 
@@ -175,15 +197,57 @@ Frontmatter at a glance:
 | `resource` (canonical URI) | optional | — |
 | `subtype`, `confidence` | — | optional |
 
-Links (`parent`, `related`) are validated — they must point at slugs that exist. `hafez validate` checks vault integrity.
+Links (`parent`, `related`) are validated — they must point at slugs that exist. A `related` link between two entities, or two knowledge notes, is kept on both files. `hafez validate` checks vault integrity.
+
+## Where your judgement matters
+
+The agent writes to your vault as work lands, without asking. Behind a few of those writes is a judgement no rule in the tool can make, and the Health pass's proposals wait for your yes. Each choice is below as the question, the test, and what happens once it is made, so you can make it, or check the one the agent made.
+
+### 1. Child or related?
+
+**Question:** one piece of work bears on another. Is it part of it, or beside it?
+
+**Test:** would it carry on if the other were finished or dropped? If not, it is a **Child**. If so, the two are **Related**.
+
+**Then:** a Child carries `parent`, the one mark of childhood, and the parent's `read` lists it. Related between two entities, or two knowledge notes, is one edge the tool keeps on both files. A pair is never both: a `related` naming a parent or a child is rejected, and so is a `--parent` naming a related entity. A parent whose own work is coordination only is a **Hub**.
+
+### 2. Split a Workstream or not?
+
+**Question:** an entity's `read` shows a `workstream:` line: its actions share an ALL-CAPS prefix that no Child or related entity carries in its name. Is it a real thread of work, or a habit of phrasing?
+
+**Test:** would you track it, brief it and finish it apart from the parent?
+
+**Then:** split, and the agent does it with ordinary writes: a Child is created under the parent, the open actions move to it, the log entries stay where they are, and one `decision` entry on the parent records the split. Don't, and nothing is written: the line is a fact, not a request, and it goes once those actions are done.
+
+### 3. Decision or lesson?
+
+**Question:** something was settled. Where does it live?
+
+**Test:** is it still true with this entity gone, no slug, path or "we chose" needed? If not, it is a **Decision**; if so, a lesson.
+
+**Then:** a decision is one `decision` entry on the log of the entity that owns the work (or an entry pointing at the repo's own record). A lesson is a knowledge note, related to where it came from. One fact, one place: a knowledge note that only repeats a decision is the Health pass's "restated decision".
+
+### 4. Retire or delete?
+
+**Question:** something in the vault is no longer wanted.
+
+**Test:** is it an entity? Then it is retired. A knowledge or session note can be deleted.
+
+**Then:** retiring sets `--status done`: the entity stays, readable and linked, and leaves the live views unless a Child of it is not yet done. Deleting removes the note in one commit, together with the back-edges it owns (the notes its own `related` names that name it back); any other entity or knowledge note naming it as `parent` or `related` refuses the delete until that link goes. Every write is a git commit, so either can be undone.
+
+### 5. What `hafez health` lists
+
+`hafez health` is the **Health pass**: it reads the vault and lists what placement would change, applying nothing. Run it, or ask the agent to check the vault; a sample of its output is [`health.md`](tests/fixtures/surfaces/health.md).
+
+Its six groups take three kinds of answer. **One-way edges** (a `related` kept on one end only) and **unlinked mentions** (a `[[slug]]` with no edge either way) are mechanical: each comes with the `link` line that adds the edge the vault already implies, so one yes can cover the group. **Workstreams** are question 2, one entity at a time. **Leakage** (a parent's, or a related entity's, log naming an entity since that entity was created: was that its work?), **restated decisions** (question 3) and **recurring names** (a name that keeps coming back in one entity's log and actions) are judged one by one: nothing is proposed for them.
 
 ## CLI overview
 
 | Command | What it does |
 |---|---|
-| `hafez read <slug> [--depth frontmatter\|summary\|full]` | Read an entity or knowledge note |
-| `hafez query [--filter active\|paused\|done\|stale\|capture\|all] [--type] [--kind entity\|knowledge\|all] [--domain] [--tag] [--parent] [--related-to] [--limit]` | Filter and list |
-| `hafez search <terms> [--kind ...]` | FTS5 full-text search |
+| `hafez read <slug> [--depth frontmatter\|summary\|full] [--archive]` | Read an entity, knowledge or session note; `--archive` an entity's archived log entries |
+| `hafez query [--filter active\|paused\|done\|stale\|capture\|all] [--type] [--kind entity\|knowledge\|session\|all] [--domain] [--tag] [--parent] [--related-to] [--limit]` | Filter and list |
+| `hafez search <terms> [--kind entity\|knowledge\|session\|all]` | FTS5 full-text search (default: entities and knowledge) |
 | `hafez create <entity\|knowledge> <name> [flags]` | Create a document |
 | `hafez capture <name> [--notes]` | Quick inbox capture |
 | `hafez promote <slug> <entity\|project\|knowledge>` | Promote a capture upward |
@@ -193,10 +257,13 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `hafez batch [--dry-run] [--data '<json>' \| --file payload.json]` | JSON ops (stdin, `--data` or `--file`) → atomic multi-op, single git commit, rollback on failure; dry-run runs the same validation as apply and reports derived slugs |
 | `hafez stats` | Vault summary: counts, stale items, recents |
 | `hafez changelog --since 7.days.ago` | Git-derived change history |
+| `hafez graph [slug] [--port N] [--no-open]` | Interactive, live graph of the vault in the browser (served on 127.0.0.1); a slug opens it focused on that note; `--json [--layers tag,domain,session]` prints `{nodes, edges}` |
 | `hafez sync` | Pull remote, push local commits (semantic merge on conflicts) |
 | `hafez validate` / `hafez index rebuild` | Integrity check / rebuild the read index |
+| `hafez health` | What placement would change: unsplit workstreams, recurring names, leakage, one-way `related` edges and unlinked `[[slug]]` mentions (each with its `hafez link` line), restated decisions; applies nothing |
 | `hafez onboard` | Setup status, then the script your agent follows: Mode, install, permissions, seeding |
 | `hafez onboard --install --mode <always-on\|invoke-only>` / `--remove` | Write (or remove) the two skills and, always-on, the marked Block in the harness's instructions file |
+| `hafez onboard --cloud --vault-repo <owner>/<repo>` | Print the setup script for Claude Code cloud sessions |
 | `hafez schema [op] [--examples]` | Machine-readable JSON schema for every operation |
 | `hafez export --okf [--out <dir>]` | Read-only OKF v0.1 bundle export |
 

package/dist/apply.d.ts

@@ -1,3 +1,4 @@
+import { type VaultKind } from './vault.js';
 import type { BatchOperation, BatchResult, CreateEntityFields, DeletableKind, CreateKnowledgeFields, KnowledgeSubtype, UpdateFields, UpdateResult } from './types.js';
 export interface AppliedOp {
     filesWritten: string[];
@@ -7,7 +8,7 @@ export interface AppliedOp {
     indexRemovals: string[];
     indexUpserts: Array<{
         slug: string;
-        kind: 'entity' | 'knowledge';
+        kind: VaultKind;
     }>;
     /** Set by the update arm: the line each Next Actions query matched. */
     updateResult?: UpdateResult;
@@ -25,6 +26,18 @@ export interface ApplyContext {
 export declare function validateKindFields(kind: 'entity' | 'knowledge', fields: UpdateFields, subtype?: KnowledgeSubtype): void;
 export declare function buildEntityFrontmatter(name: string, ef: CreateEntityFields, existsFn: (slug: string) => boolean): Record<string, any>;
 export declare function buildKnowledgeFrontmatter(name: string, kf: CreateKnowledgeFields, existsFn: (slug: string) => boolean): Record<string, any>;
+/** The mirror file an edge op touched: what the arm appends to its
+ * filesWritten and indexUpserts. */
+export interface EdgeTouch {
+    file: string;
+    upsert: {
+        slug: string;
+        kind: VaultKind;
+    };
+}
+/** Drop `a` from `b`'s related when the edge is same-kind. Exported for the
+ * delete arm (#243) as well. */
+export declare function dropBackEdge(ctx: ApplyContext, a: string, aKind: VaultKind, b: string): EdgeTouch | null;
 /** The single apply path for every mutation. Writes vault files but never
  * touches git or SQLite: the Spine commits [...filesWritten, ...filesDeleted]
  * under commitMessage (single ops) or one composed batch message, then runs

package/dist/apply.js

@@ -18,8 +18,8 @@
 // pure (no filesystem access); the frontmatter builders live here and are
 // exported so the batch validate phase can run them against a simulated vault.
 import { writeFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync } from 'fs';
-import { join, relative, dirname } from 'path';
-import { parseFilePath, serializeFile, slugify, resolveFilePath, kindFromPath, kindDir, archiveLogPath, findVaultFile, vaultFileExists } from './vault.js';
+import { join, dirname } from 'path';
+import { parseFilePath, serializeFile, slugify, resolveFilePath, vaultRel, kindFromPath, kindDir, archiveLogPath, findVaultFile, vaultFileExists } from './vault.js';
 import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
 import { bodyTemplate, knowledgeBodyTemplate, sessionBodyTemplate } from './templates.js';
 import { formatSessionLogEntry, stampAction, documentFor, documentForFile } from './document.js';
@@ -369,6 +369,42 @@ function withMechanisedLog(kind, fields) {
         },
     };
 }
+function mirrorEdge(ctx, a, aKind, b, mode) {
+    if (a === b)
+        return null;
+    const bPath = findVaultFile(ctx.vaultPath, b);
+    if (!bPath || kindFromPath(bPath) !== aKind)
+        return null;
+    const parsed = parseFilePath(bPath);
+    const fm = parsed.frontmatter;
+    const related = fm.related ?? [];
+    if (mode === 'write' ? related.includes(a) : !related.includes(a))
+        return null;
+    ctx.captureOriginal(bPath);
+    if (mode === 'write')
+        fm.related = [...related, a];
+    else {
+        fm.related = related.filter(r => r !== a);
+        if (fm.related.length === 0)
+            delete fm.related;
+    }
+    const body = documentForFile(parsed).syncRelatedSection(parsed.body, fm);
+    writeFileSync(bPath, serializeFile(fm, body));
+    return { file: vaultRel(ctx.vaultPath, bPath), upsert: { slug: b, kind: aKind } };
+}
+/** Write `a` into `b`'s related when the edge is same-kind. */
+function writeBackEdge(ctx, a, aKind, b) {
+    return mirrorEdge(ctx, a, aKind, b, 'write');
+}
+/** Write `a` into every same-kind target's related. */
+function backEdges(ctx, a, aKind, targets) {
+    return targets.flatMap(b => writeBackEdge(ctx, a, aKind, b) ?? []);
+}
+/** Drop `a` from `b`'s related when the edge is same-kind. Exported for the
+ * delete arm (#243) as well. */
+export function dropBackEdge(ctx, a, aKind, b) {
+    return mirrorEdge(ctx, a, aKind, b, 'drop');
+}
 // --- The arms ---
 function applyUpdate(op, ctx) {
     const { vaultPath } = ctx;
@@ -379,6 +415,9 @@ function applyUpdate(op, ctx) {
     const doc = documentForFile(parsedFile);
     let fm = parsedFile.frontmatter;
     let body = parsedFile.body;
+    // The related list before the fields replace it: the diff against the new
+    // one is what the edge writer and dropper mirror on the targets.
+    const relatedBefore = fm.related ?? [];
     const applied = applyUpdateFields(doc, fm, body, withMechanisedLog(kind, op.fields));
     fm = applied.fm;
     body = applied.body;
@@ -400,19 +439,30 @@ function applyUpdate(op, ctx) {
     }
     body = doc.syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
+    const touches = [];
+    if (op.fields.related !== undefined) {
+        const relatedAfter = fm.related ?? [];
+        touches.push(...backEdges(ctx, op.slug, kind, relatedAfter.filter(r => !relatedBefore.includes(r))));
+        for (const r of relatedBefore.filter(r => !relatedAfter.includes(r))) {
+            const t = dropBackEdge(ctx, op.slug, kind, r);
+            if (t)
+                touches.push(t);
+        }
+    }
     // Only the files THIS update wrote. Keying off the archive file merely
     // existing swept any external hand-edit sitting in entities/archive/
     // into an unrelated commit.
-    const files = [relative(vaultPath, filePath)];
+    const files = [vaultRel(vaultPath, filePath)];
     if (wroteArchive)
-        files.push(relative(vaultPath, archivePath));
+        files.push(vaultRel(vaultPath, archivePath));
+    files.push(...touches.map(t => t.file));
     return {
         filesWritten: files,
         filesDeleted: [],
         result: { op: 'update', slug: op.slug, status: 'ok' },
         commitMessage: `update: ${op.slug}`,
         indexRemovals: [],
-        indexUpserts: [{ slug: op.slug, kind }],
+        indexUpserts: [{ slug: op.slug, kind }, ...touches.map(t => t.upsert)],
         updateResult: applied.updateResult,
     };
 }
@@ -432,13 +482,14 @@ function applyCreateEntity(op, ctx) {
     mkdirSync(join(vaultPath, kindDir('entity')), { recursive: true });
     body = documentFor({ kind: 'entity' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
+    const touches = backEdges(ctx, slug, 'entity', fm.related ?? []);
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...touches.map(t => t.file)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
         indexRemovals: [],
-        indexUpserts: [{ slug, kind: 'entity' }],
+        indexUpserts: [{ slug, kind: 'entity' }, ...touches.map(t => t.upsert)],
     };
 }
 function applyCreateKnowledge(op, ctx) {
@@ -454,13 +505,14 @@ function applyCreateKnowledge(op, ctx) {
     mkdirSync(join(vaultPath, kindDir('knowledge')), { recursive: true });
     body = documentFor({ kind: 'knowledge' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
+    const touches = backEdges(ctx, slug, 'knowledge', fm.related ?? []);
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...touches.map(t => t.file)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
         indexRemovals: [],
-        indexUpserts: [{ slug, kind: 'knowledge' }],
+        indexUpserts: [{ slug, kind: 'knowledge' }, ...touches.map(t => t.upsert)],
     };
 }
 function applyCreateSession(op, ctx) {
@@ -480,25 +532,23 @@ function applyCreateSession(op, ctx) {
         appeared(slug);
     ctx.captureOriginal(filePath);
     const fm = { name: op.name, created: today() };
-    const kf = (op.fields ?? {});
+    const kf = op.fields ?? {};
     if (kf['session-date'])
         fm['session-date'] = kf['session-date'];
     if (kf.related?.length)
         fm.related = kf.related;
     // Session sections come from contracts.SESSION_SECTIONS — the same list
     // Document splits on, so the written body and the structural set agree.
-    let sessionBody = sessionBodyTemplate({ synthesis: kf.synthesis });
+    let sessionBody = sessionBodyTemplate({ synthesis: kf.synthesis, decisions: kf.decisions, entities_touched: kf.entities_touched });
     sessionBody = documentFor({ kind: 'session' }).syncRelatedSection(sessionBody, fm);
     writeFileSync(filePath, serializeFile(fm, sessionBody));
-    // Sessions are not indexed (db.ts only scans entities/ and knowledge/).
-    // They ARE included in git semantic merge (git.ts VAULT_FILE_RE).
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
         indexRemovals: [],
-        indexUpserts: [],
+        indexUpserts: [{ slug, kind: 'session' }],
     };
 }
 function applyCapture(op, ctx) {
@@ -518,7 +568,7 @@ function applyCapture(op, ctx) {
     mkdirSync(join(vaultPath, kindDir('entity')), { recursive: true });
     writeFileSync(filePath, serializeFile(fm, bodyTemplate('capture', { notes: op.notes })));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'capture', slug, status: 'ok', created: true },
         commitMessage: `capture: ${op.name}`,
@@ -533,6 +583,8 @@ function applyLink(op, ctx) {
     const parsedFile = parseFilePath(filePath);
     const fm = parsedFile.frontmatter;
     let body = parsedFile.body;
+    const kind = kindFromPath(filePath);
+    let touch = null;
     if (op.relation === 'parent') {
         fm.parent = op.target;
     }
@@ -541,16 +593,17 @@ function applyLink(op, ctx) {
         if (!related.includes(op.target))
             related.push(op.target);
         fm.related = related;
+        touch = writeBackEdge(ctx, op.slug, kind, op.target);
     }
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...(touch ? [touch.file] : [])],
         filesDeleted: [],
         result: { op: 'link', slug: op.slug, status: 'ok' },
         commitMessage: `link: ${op.slug} → ${op.target} (${op.relation})`,
         indexRemovals: [],
-        indexUpserts: [{ slug: op.slug, kind: kindFromPath(filePath) }],
+        indexUpserts: [{ slug: op.slug, kind }, ...(touch ? [touch.upsert] : [])],
     };
 }
 function applyUnlink(op, ctx) {
@@ -560,23 +613,30 @@ function applyUnlink(op, ctx) {
     const parsedFile = parseFilePath(filePath);
     const fm = parsedFile.frontmatter;
     let body = parsedFile.body;
+    const kind = kindFromPath(filePath);
+    let touch = null;
     if (op.relation === 'parent' && fm.parent === op.target) {
         delete fm.parent;
     }
-    else if (op.relation === 'related' && fm.related) {
-        fm.related = fm.related.filter((r) => r !== op.target);
-        if (fm.related.length === 0)
-            delete fm.related;
+    else if (op.relation === 'related') {
+        if (fm.related) {
+            fm.related = fm.related.filter((r) => r !== op.target);
+            if (fm.related.length === 0)
+                delete fm.related;
+        }
+        // The target's end goes too, even when this file never carried the edge
+        // (a legacy one-way edge).
+        touch = dropBackEdge(ctx, op.slug, kind, op.target);
     }
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...(touch ? [touch.file] : [])],
         filesDeleted: [],
         result: { op: 'unlink', slug: op.slug, status: 'ok' },
         commitMessage: `unlink: ${op.slug} ✕ ${op.target} (${op.relation})`,
         indexRemovals: [],
-        indexUpserts: [{ slug: op.slug, kind: kindFromPath(filePath) }],
+        indexUpserts: [{ slug: op.slug, kind }, ...(touch ? [touch.upsert] : [])],
     };
 }
 function applyPromote(op, ctx) {
@@ -631,10 +691,10 @@ function applyPromote(op, ctx) {
         catch (err) {
             throw new HafezError('VALIDATION_FAILED', `Failed to promote '${op.slug}' to knowledge: ${err instanceof Error ? err.message : String(err)}`);
         }
-        modifiedFiles.push(relative(vaultPath, newPath));
+        modifiedFiles.push(vaultRel(vaultPath, newPath));
         // The deletion must be staged too — `git add` of a removed path stages
         // the removal; omitting it leaves the vault permanently dirty.
-        deletedFiles.push(relative(vaultPath, filePath));
+        deletedFiles.push(vaultRel(vaultPath, filePath));
     }
     else {
         // Same-kind: capture→entity, capture→project, entity→project
@@ -661,7 +721,7 @@ function applyPromote(op, ctx) {
         }));
         newBody = doc.syncRelatedSection(newBody, fm);
         writeFileSync(filePath, serializeFile(fm, newBody));
-        modifiedFiles.push(relative(vaultPath, filePath));
+        modifiedFiles.push(vaultRel(vaultPath, filePath));
     }
     return {
         filesWritten: modifiedFiles,
@@ -683,15 +743,17 @@ function applyDelete(op, ctx) {
         vanished(op.slug);
     // The snapshot is the rollback: a commit-stage failure writes it back.
     ctx.captureOriginal(filePath);
+    // The other end of every same-kind edge the note owns goes with it (#243).
+    const own = kind === 'knowledge' ? parseFilePath(filePath).frontmatter.related ?? [] : [];
     unlinkSync(filePath);
+    const touches = own.flatMap(r => dropBackEdge(ctx, op.slug, 'knowledge', r) ?? []);
     return {
-        filesWritten: [],
-        filesDeleted: [relative(vaultPath, filePath)],
+        filesWritten: touches.map(t => t.file),
+        filesDeleted: [vaultRel(vaultPath, filePath)],
         result: { op: 'delete', slug: op.slug, status: 'ok' },
         commitMessage: `delete: ${op.slug} (${kind})`,
-        // Sessions are not indexed; a knowledge row goes with its file.
-        indexRemovals: kind === 'knowledge' ? [op.slug] : [],
-        indexUpserts: [],
+        indexRemovals: [op.slug],
+        indexUpserts: touches.map(t => t.upsert),
         deletedKind: kind,
     };
 }

package/dist/batch-ops.d.ts

@@ -34,12 +34,12 @@ export declare const UpdateFieldsSchema: z.ZodObject<{
     parent: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     confidence: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
     }>>;
-    tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
     add_evidence: z.ZodOptional<z.ZodString>;
@@ -52,10 +52,10 @@ export declare const CreateEntityFieldsSchema: z.ZodObject<{
     purpose: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     resource: z.ZodOptional<z.ZodString>;
-    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     parent: z.ZodOptional<z.ZodString>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     brief: z.ZodOptional<z.ZodString>;
     add_action: z.ZodOptional<z.ZodString>;
     add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -73,16 +73,18 @@ export declare const CreateKnowledgeFieldsSchema: z.ZodObject<{
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     'session-date': z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const CreateSessionFieldsSchema: z.ZodObject<{
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     'session-date': z.ZodOptional<z.ZodString>;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entities_touched: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
 }, z.core.$strict>;
 /** What `digest` may put in a session-create op — typechecked against the
  * schema so the two can never silently diverge again. */
@@ -119,12 +121,12 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         parent: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+        domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
         confidence: z.ZodOptional<z.ZodEnum<{
             [x: string]: string;
         }>>;
-        tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-        related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+        tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+        related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
         synthesis: z.ZodOptional<z.ZodString>;
         insight: z.ZodOptional<z.ZodString>;
         add_evidence: z.ZodOptional<z.ZodString>;
@@ -290,12 +292,12 @@ declare const OP_SPEC_ROWS: readonly [{
             parent: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             confidence: z.ZodOptional<z.ZodEnum<{
                 [x: string]: string;
             }>>;
-            tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
             add_evidence: z.ZodOptional<z.ZodString>;
@@ -326,10 +328,10 @@ declare const OP_SPEC_ROWS: readonly [{
             purpose: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
             resource: z.ZodOptional<z.ZodString>;
-            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             parent: z.ZodOptional<z.ZodString>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             brief: z.ZodOptional<z.ZodString>;
             add_action: z.ZodOptional<z.ZodString>;
             add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -367,9 +369,9 @@ declare const OP_SPEC_ROWS: readonly [{
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
-            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             'session-date': z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -395,11 +397,13 @@ declare const OP_SPEC_ROWS: readonly [{
         fields: z.ZodOptional<z.ZodObject<{
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             'session-date': z.ZodOptional<z.ZodString>;
+            decisions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            entities_touched: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
-    readonly description: "Create a new session note linked to an entity. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).";
+    readonly description: "Create a new session note linked to an entity. `synthesis` writes Summary, `decisions` one bullet each under Decisions, `entities_touched` one `[[slug]]` bullet each under Entities Touched. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).";
     readonly exampleInclude: readonly ["synthesis"];
     readonly check: (op: Extract<BatchOperation, {
         op: "create";
@@ -445,7 +449,7 @@ declare const OP_SPEC_ROWS: readonly [{
             related: "related";
         }>;
     }, z.core.$strict>;
-    readonly description: "Add a parent or related link between two entities.";
+    readonly description: "Add a parent or related link. A same-kind related link (entity↔entity, knowledge↔knowledge) is written on both files; a related naming the entity's parent or a child is rejected (parent subsumes related).";
     readonly exampleInclude: readonly [];
     readonly check: (op: Extract<BatchOperation, {
         op: "link";
@@ -466,7 +470,7 @@ declare const OP_SPEC_ROWS: readonly [{
             related: "related";
         }>;
     }, z.core.$strict>;
-    readonly description: "Remove a parent or related link between two entities.";
+    readonly description: "Remove a parent or related link. A same-kind related link is dropped from both files, a legacy one-way edge from whichever file carries it.";
     readonly exampleInclude: readonly [];
     readonly check: (op: Extract<BatchOperation, {
         op: "unlink";
@@ -503,7 +507,7 @@ declare const OP_SPEC_ROWS: readonly [{
         op: z.ZodLiteral<"delete">;
         slug: z.ZodString;
     }, z.core.$strict>;
-    readonly description: "Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. Rejected while another entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.";
+    readonly description: "Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. The back-edges the note owns (a knowledge note in its own related that names it back) are dropped with it, in the same commit. Rejected while any other entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.";
     readonly exampleInclude: readonly [];
     readonly addressesSessions: true;
     readonly check: (op: Extract<BatchOperation, {