hafez 2.1.0 → 2.2.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
@@ -161,7 +180,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:
 
@@ -181,9 +200,9 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 
 | 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 |
@@ -197,6 +216,7 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `hafez validate` / `hafez index rebuild` | Integrity check / rebuild the read index |
 | `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;

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';
@@ -403,9 +403,9 @@ function applyUpdate(op, ctx) {
     // 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));
     return {
         filesWritten: files,
         filesDeleted: [],
@@ -433,7 +433,7 @@ function applyCreateEntity(op, ctx) {
     body = documentFor({ kind: 'entity' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
@@ -455,7 +455,7 @@ function applyCreateKnowledge(op, ctx) {
     body = documentFor({ kind: 'knowledge' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
@@ -490,15 +490,13 @@ function applyCreateSession(op, ctx) {
     let sessionBody = sessionBodyTemplate({ synthesis: kf.synthesis });
     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 +516,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}`,
@@ -545,7 +543,7 @@ function applyLink(op, ctx) {
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'link', slug: op.slug, status: 'ok' },
         commitMessage: `link: ${op.slug} → ${op.target} (${op.relation})`,
@@ -571,7 +569,7 @@ function applyUnlink(op, ctx) {
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'unlink', slug: op.slug, status: 'ok' },
         commitMessage: `unlink: ${op.slug} ✕ ${op.target} (${op.relation})`,
@@ -631,10 +629,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 +659,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,
@@ -686,11 +684,10 @@ function applyDelete(op, ctx) {
     unlinkSync(filePath);
     return {
         filesWritten: [],
-        filesDeleted: [relative(vaultPath, filePath)],
+        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] : [],
+        indexRemovals: [op.slug],
         indexUpserts: [],
         deletedKind: kind,
     };

package/dist/batch-ops.js

@@ -264,7 +264,9 @@ export function duplicateSessionWarning(slug) {
  * batch). The builder runs before the claim — it must see the pre-claim
  * world so a self-referencing parent still fails. */
 function claimNew(ctx, errors, slug, info, build) {
-    const taken = ctx.existsAnywhere(slug);
+    // A session note holds its slug too: every kind shares one index row per
+    // slug, so a create must not take one a session already has.
+    const taken = ctx.existsAnywhere(slug) || ctx.sessionExists(slug);
     if (taken)
         errors.push(`Slug '${slug}' already exists`);
     if (build) {

package/dist/cli/block-hook.js

@@ -26,11 +26,16 @@ export async function blockHook(ctx) {
         // leave an index file in it.
         if (typeof vaultPath !== 'string' || !isVault(vaultPath))
             return null;
-        const cwd = realpathSync(ctx.cwd ?? process.cwd());
+        const dir = ctx.cwd ?? process.cwd();
+        // A deleted working directory: no folder to match.
+        if (!existsSync(dir))
+            return null;
+        const cwd = canonical(dir);
         const folders = foldersOf(cwd);
         const remotes = remoteUrls(cwd);
         const { createHafez } = await import('../index.js');
-        const { items } = await createHafez({ vaultPath, git: { push: false } }).query({ filter: 'all' });
+        const os = createHafez({ vaultPath, git: { push: false } });
+        const { items } = await os.query({ filter: 'all' }).finally(() => os.close());
         const matches = items
             .filter(e => folders.some(f => basename(f) === e.slug) || (e.resource !== null && resourceMatches(e.resource, folders, remotes)))
             // Active first: the status tuple is ordered active, paused, done.
@@ -59,13 +64,25 @@ function foldersOf(cwd) {
     const [top, common] = out?.split('\n') ?? [];
     // Before git 2.31 `--path-format` is echoed back, not obeyed: no git root.
     if (top && common && isAbsolute(top) && isAbsolute(common)) {
-        folders.push(top);
+        const root = canonical(top);
+        folders.push(root);
         // A linked worktree shares the main checkout's `.git` as its common dir.
-        if (basename(common) === '.git' && dirname(common) !== top)
-            folders.push(dirname(common));
+        // The shape is read off git's own path: a symlinked `.git` resolves to a
+        // directory with some other name.
+        const main = canonical(dirname(common));
+        if (basename(common) === '.git' && main !== root)
+            folders.push(main);
     }
     return [...new Set(folders)];
 }
+/** One spelling per folder, so paths from git, the working directory and a
+ * `resource` compare equal: git prints `C:/…` on Windows, realpath `C:\…`.
+ * The native realpath, since only it returns the filesystem's own letter case
+ * (`c:\users\…` is `C:\Users\…`) and long names for 8.3 ones. */
+function canonical(path) {
+    const abs = resolve(path);
+    return existsSync(abs) ? realpathSync.native(abs) : abs;
+}
 /** Every remote's URL, normalised. */
 function remoteUrls(cwd) {
     const out = git(cwd, 'config', '--get-regexp', '^remote\\..*\\.url$');
@@ -82,9 +99,7 @@ function normaliseUrl(url) {
         .replace(/\.git$/, '');
 }
 function resourceMatches(resource, folders, remotes) {
-    if (isAbsolute(resource)) {
-        const path = resolve(resource);
-        return folders.includes(existsSync(path) ? realpathSync(path) : path);
-    }
+    if (isAbsolute(resource))
+        return folders.includes(canonical(resource));
     return remotes.includes(normaliseUrl(resource));
 }

package/dist/cli/commands.d.ts

@@ -9,7 +9,7 @@ export interface CommandOpts {
 export declare function cmdRead(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 /** Every flag the query parser accepts, for the branch-support matrix. */
 export declare const QUERY_FLAG_NAMES: string[];
-export type QueryBranch = 'entity' | 'knowledge' | 'all' | 'related-to';
+export type QueryBranch = 'entity' | 'knowledge' | 'session' | 'all' | 'related-to';
 /** Which flags each kind branch actually applies. A branch that cannot honour
  * a flag rejects it (below) instead of dropping it: `--kind knowledge --filter
  * stale` used to return every knowledge note with exit 0, and `--confidence`

package/dist/cli/commands.js

@@ -7,18 +7,18 @@ import { BatchOperationSchema, normalizeAliases, opErrorLine, batchInvalidHeader
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { detectAgent } from '../harness.js';
-import { getActionItems } from '../document.js';
+import { getActionItems, parseSessionLogHeading } from '../document.js';
 import { resemblances } from '../near-match.js';
 import { actionAge, agedActions, staleHandles, stalenessDaysOf } from '../stale.js';
 import { slugify } from '../vault.js';
 import { ITEMS, footerOp } from '../surfaces/items.js';
 import { placeIn } from '../surfaces/surfaces.js';
-import { formatEntityHeader, formatKnowledgeHeader, formatQueryTable, formatKnowledgeTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
+import { formatEntityHeader, formatKnowledgeHeader, formatSessionHeader, formatQueryTable, formatKnowledgeTable, formatSessionTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
 }
-const READ_USAGE = 'Usage: hafez read <slug> [--depth frontmatter|summary|full]';
-const READ_FLAGS = { depth: 'string' };
+const READ_USAGE = 'Usage: hafez read <slug> [--depth frontmatter|summary|full] [--archive]';
+const READ_FLAGS = { depth: 'string', archive: 'boolean' };
 export async function cmdRead(os, args, opts = {}) {
     const { flags, positionals } = parseArgs(args, READ_FLAGS, READ_USAGE);
     const slug = positionals[0];
@@ -33,23 +33,52 @@ export async function cmdRead(os, args, opts = {}) {
             ? new RenderedError('NOT_FOUND', jsonOut({ slug, closest }), 'stdout')
             : new RenderedError('NOT_FOUND', ITEMS.slugMissRecovery.render({ slug, closest }), 'stderr');
     });
+    if (flags.archive) {
+        // The archive is an entity's: reached from it on purpose (#34).
+        if (result.kind !== 'entity')
+            throw new UsageError(`--archive reads an entity's archived log entries; '${slug}' is a ${result.kind === 'session' ? 'session note' : 'knowledge note'}\n${READ_USAGE}`);
+        const archive = await os.archive(slug);
+        if (opts.json)
+            return jsonOut({ slug, archive });
+        return archive ?? `no archive for ${slug}`;
+    }
+    // A session note is read, never written: no Footer (#35).
+    if (result.kind === 'session') {
+        if (opts.json)
+            return jsonOut(result);
+        return formatSessionHeader(result.frontmatter, result.body);
+    }
     const footer = await footerFor(os, slug, result, depth);
+    const pointers = result.kind === 'entity' ? await pointersFor(os, slug) : null;
     if (opts.json) {
         const writes = footerOp(footer);
         // A frontmatter-depth read carries no body, so it has no actions to list.
         if (result.kind !== 'entity' || depth === 'frontmatter')
-            return jsonOut({ ...result, writes });
-        return jsonOut({ ...result, actions: agedActions(result.body, result.frontmatter), writes });
+            return jsonOut({ ...result, ...pointers, writes });
+        return jsonOut({ ...result, actions: agedActions(result.body, result.frontmatter), ...pointers, writes });
     }
     const fm = result.frontmatter;
     const days = stalenessDaysOf(fm);
     const staleMark = (added) => ITEMS.staleMarker.render(actionAge(added, days));
     const text = result.kind === 'entity'
-        ? formatEntityHeader(fm, ITEMS.handles.render(result.body, staleMark), await parentLine(os, fm.parent))
+        ? formatEntityHeader(fm, ITEMS.handles.render(result.body, staleMark), await parentLine(os, fm.parent), [
+            ITEMS.sessionsLine.render({ slug, ...pointers.sessions }),
+            ITEMS.archivePointer.render({ slug, entries: pointers.archive_entries }),
+        ].filter(Boolean))
         : formatKnowledgeHeader(fm, result.body);
     // Trailing newlines only: the Footer brings its own blank line.
     return `${text.replace(/\n+$/, '')}\n${ITEMS.writeLine.render(footer)}`;
 }
+/** What hangs off an entity elsewhere: the sessions that touched it (the
+ * look back, #35) and its archived log entries (#34). Counted at read time,
+ * nothing written. */
+async function pointersFor(os, slug) {
+    const sessions = (await os.related_to(slug)).items.filter((i) => i.kind === 'session');
+    const latest = sessions.reduce((max, s) => (max === null || s.session_date > max ? s.session_date : max), null);
+    const archive = await os.archive(slug);
+    const entries = archive ? archive.split('\n').filter(line => parseSessionLogHeading(line)).length : 0;
+    return { sessions: { count: sessions.length, latest }, archive_entries: entries };
+}
 /** The `parent:` line's value: the slug with the parent's description. The
  * one thing `read` takes from another file; a parent that cannot be read
  * (a broken slug) is named by its slug alone. */
@@ -75,7 +104,7 @@ async function staleAfterWrite(os, slug) {
 }
 /** The Footer for a file `read` returned at `depth`. The Footer is the same
  * at every depth, so its Handle comes from the whole file, not from the body
- * this depth shows. */
+ * this depth shows. A session note has none: it is never written to. */
 async function footerFor(os, slug, result, depth) {
     return { slug, agent: detectAgent(), ...(result.kind === 'entity'
             ? {
@@ -84,14 +113,16 @@ async function footerFor(os, slug, result, depth) {
             }
             : { target: { kind: 'knowledge', subtype: result.frontmatter.subtype } }) };
 }
-const QUERY_USAGE = `Usage: hafez query [--kind entity|knowledge|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]
+const QUERY_USAGE = `Usage: hafez query [--kind entity|knowledge|session|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]
 
-  --filter active|paused|done matches entity status; knowledge notes carry no
-  status, so under --kind all they are always included alongside the matching
-  entities. --filter stale|capture are entity-only views and return no
-  knowledge. --filter/--type/--parent are rejected with --kind knowledge, and
-  --confidence/--subtype are rejected with --kind entity, rather than being
-  silently dropped. --related-to takes no other query flags.`;
+  --filter active|paused|done matches entity status; knowledge and session
+  notes carry no status, so under --kind all they are always included
+  alongside the matching entities. --filter stale|capture are entity-only
+  views and return no knowledge. --filter/--type/--parent are rejected with
+  --kind knowledge, and --confidence/--subtype are rejected with --kind
+  entity, rather than being silently dropped. --kind session lists session
+  notes newest first and takes the time window, sort and paging flags only.
+  --related-to takes --kind to narrow to one kind and no other query flag.`;
 const QUERY_FLAGS = {
     kind: 'string', filter: 'string', type: 'string', parent: 'string', 'related-to': 'string',
     domain: 'string', confidence: 'string', subtype: 'string', tag: 'string',
@@ -107,8 +138,9 @@ export const QUERY_FLAG_NAMES = Object.keys(QUERY_FLAGS);
 export const QUERY_FLAG_SUPPORT = {
     entity: ['kind', 'filter', 'type', 'parent', 'domain', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
     knowledge: ['kind', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    session: ['kind', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
     all: ['kind', 'filter', 'type', 'parent', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
-    'related-to': ['related-to'],
+    'related-to': ['related-to', 'kind'],
 };
 const FLAG_SCOPE_REASON = {
     filter: 'it selects entity status (or the entity-only stale/capture views); knowledge notes carry no status',
@@ -117,16 +149,17 @@ const FLAG_SCOPE_REASON = {
     confidence: 'knowledge notes only',
     subtype: 'knowledge notes only',
 };
-const QUERY_KINDS = ['entity', 'knowledge', 'all'];
+const QUERY_KINDS = ['entity', 'knowledge', 'session', 'all'];
 function rejectUnsupportedFlags(branch, flags) {
     const supported = new Set(QUERY_FLAG_SUPPORT[branch]);
     for (const [name, value] of Object.entries(flags)) {
         if (value === undefined || supported.has(name))
             continue;
         const where = branch === 'related-to'
-            ? 'with --related-to (it returns every entity and knowledge note linked to the slug)'
+            ? 'with --related-to (it returns every entity, knowledge note and session note linked to the slug)'
             : `with --kind ${branch}`;
-        const reason = FLAG_SCOPE_REASON[name] ? ` — ${FLAG_SCOPE_REASON[name]}` : '';
+        const scope = branch === 'session' && (name === 'domain' || name === 'tag') ? 'a session note carries none' : FLAG_SCOPE_REASON[name];
+        const reason = scope ? ` — ${scope}` : '';
         throw new UsageError(`--${name} is not supported ${where}${reason}\n${QUERY_USAGE}`);
     }
 }
@@ -142,9 +175,10 @@ function intFlag(raw, name) {
 export async function cmdQuery(os, args, opts = {}) {
     const { flags } = parseArgs(args, QUERY_FLAGS, QUERY_USAGE);
     const relatedTo = str(flags['related-to']);
-    const branch = relatedTo !== undefined ? 'related-to' : (str(flags.kind) ?? 'entity');
-    if (branch !== 'related-to' && !QUERY_KINDS.includes(branch)) {
-        throw new UsageError(`--kind must be one of ${QUERY_KINDS.join(', ')} (got "${branch}")\n${QUERY_USAGE}`);
+    const kindFlag = str(flags.kind);
+    const branch = relatedTo !== undefined ? 'related-to' : (kindFlag ?? 'entity');
+    if (kindFlag !== undefined && !QUERY_KINDS.includes(kindFlag)) {
+        throw new UsageError(`--kind must be one of ${QUERY_KINDS.join(', ')} (got "${kindFlag}")\n${QUERY_USAGE}`);
     }
     rejectUnsupportedFlags(branch, flags);
     const filter = (str(flags.filter) ?? 'active');
@@ -165,20 +199,16 @@ export async function cmdQuery(os, args, opts = {}) {
     const offset = intFlag(str(flags.offset), 'offset');
     const sortOpts = { sort_by: sortBy, sort_order: sortOrder, limit, offset };
     const timeOpts = { since, before, createdSince, createdBefore };
-    // --related-to: always returns both entities and knowledge
+    // --related-to: every kind linked to the slug, the sessions that touched
+    // an entity included; --kind narrows to one (the entity header's
+    // `--kind session --related-to` line)
     if (relatedTo) {
-        const result = await os.related_to(relatedTo);
+        const linked = await os.related_to(relatedTo);
+        const items = kindFlag && kindFlag !== 'all' ? linked.items.filter(i => i.kind === kindFlag) : linked.items;
+        const result = { items, total: items.length };
         if (opts.json)
             return jsonOut(result);
-        const { items: results, total } = result;
-        const entities = results.filter(r => r.kind === 'entity');
-        const knowledge = results.filter(r => r.kind === 'knowledge');
-        const sections = [];
-        if (entities.length > 0)
-            sections.push('## Entities\n\n' + formatQueryTable(entities, total));
-        if (knowledge.length > 0)
-            sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge, total));
-        return sections.length > 0 ? sections.join('\n\n') : 'No results.';
+        return formatUnifiedSections(result.items, result.total);
     }
     const queryOpts = { filter, type, parent, domain, ...timeOpts, tags, ...sortOpts };
     // --kind knowledge: query knowledge only. The time window applies here too —
@@ -190,22 +220,19 @@ export async function cmdQuery(os, args, opts = {}) {
             return jsonOut(result);
         return formatKnowledgeTable(result.items, result.total);
     }
-    // --kind all: query both entities and knowledge via unified query
+    // --kind session: the session notes alone, newest first
+    if (branch === 'session') {
+        const result = await os.query_sessions({ ...timeOpts, ...sortOpts });
+        if (opts.json)
+            return jsonOut(result);
+        return formatSessionTable(result.items, result.total);
+    }
+    // --kind all: every kind via the unified query, sessions included
     if (branch === 'all') {
         const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence, subtype });
         if (opts.json)
             return jsonOut(result);
-        const { items, total } = result;
-        const entities = items.filter(i => i.kind === 'entity');
-        const knowledge = items.filter(i => i.kind === 'knowledge');
-        const sections = [];
-        if (entities.length > 0)
-            sections.push('## Entities\n\n' + formatQueryTable(entities));
-        if (knowledge.length > 0)
-            sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge));
-        if (items.length < total)
-            sections.push(`\nShowing ${items.length} of ${total}`);
-        return sections.length > 0 ? sections.join('\n\n') : 'No results.';
+        return formatUnifiedSections(result.items, result.total);
     }
     // --kind entity (default): query entities
     const result = await os.query(queryOpts);
@@ -213,14 +240,38 @@ export async function cmdQuery(os, args, opts = {}) {
         return jsonOut(result);
     return formatQueryTable(result.items, result.total);
 }
-const SEARCH_USAGE = 'Usage: hafez search <terms> [--kind entity|knowledge|all]';
+/** One section per kind present, in the order entities, knowledge,
+ * sessions; a page line when the page is short of the total. */
+function formatUnifiedSections(items, total) {
+    const entities = items.filter((i) => i.kind === 'entity');
+    const knowledge = items.filter((i) => i.kind === 'knowledge');
+    const sessions = items.filter((i) => i.kind === 'session');
+    const sections = [];
+    if (entities.length > 0)
+        sections.push('## Entities\n\n' + formatQueryTable(entities));
+    if (knowledge.length > 0)
+        sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge));
+    if (sessions.length > 0)
+        sections.push('## Sessions\n\n' + formatSessionTable(sessions));
+    if (items.length < total)
+        sections.push(`\nShowing ${items.length} of ${total}`);
+    return sections.length > 0 ? sections.join('\n\n') : 'No results.';
+}
+const SEARCH_USAGE = `Usage: hafez search <terms> [--kind entity|knowledge|session|all]
+
+  Without --kind, entities and knowledge notes are searched. --kind all adds
+  the session notes; --kind session searches them alone.`;
 const SEARCH_FLAGS = { kind: 'string' };
+const SEARCH_KINDS = ['entity', 'knowledge', 'session', 'all'];
 export async function cmdSearch(os, args, opts = {}) {
     const { flags, positionals } = parseArgs(args, SEARCH_FLAGS, SEARCH_USAGE);
     const terms = positionals.join(' ');
     if (!terms)
         throw new UsageError(SEARCH_USAGE);
-    const kind = (str(flags.kind) ?? 'all');
+    const kind = str(flags.kind);
+    if (kind !== undefined && !SEARCH_KINDS.includes(kind)) {
+        throw new UsageError(`--kind must be one of ${SEARCH_KINDS.join(', ')} (got "${kind}")\n${SEARCH_USAGE}`);
+    }
     const results = await os.search(terms, kind);
     if (opts.json)
         return jsonOut(results);
@@ -462,7 +513,14 @@ async function updateFailure(os, slug, err, opts) {
         return err;
     let retry;
     try {
-        retry = { footer: await footerFor(os, slug, await os.read(slug, 'full'), 'full') };
+        const file = await os.read(slug, 'full');
+        // The Op Spec resolves no session note, so the update missed; the slug
+        // names one all the same. Say what it is instead of offering a Footer
+        // it will never have.
+        if (file.kind === 'session') {
+            return new RenderedError('VALIDATION_FAILED', `'${slug}' is a session note: written once and read, never updated. What matters from it belongs on the entity it touched.`, 'stderr');
+        }
+        retry = { footer: await footerFor(os, slug, file, 'full') };
     }
     catch (readErr) {
         if (!(readErr instanceof HafezError) || readErr.code !== 'NOT_FOUND')

package/dist/cli/format.d.ts

@@ -1,12 +1,17 @@
-import type { QueryResult, KnowledgeQueryResult, ValidationReport, SearchResult, VaultStats, ChangelogEntry } from '../types.js';
+import type { QueryResult, KnowledgeQueryResult, SessionQueryResult, ValidationReport, SearchResult, VaultStats, ChangelogEntry } from '../types.js';
 /** `parent` is the rendered value of the `parent:` line (the slug with the
- * parent's description); absent, the slug alone. */
-export declare function formatEntityHeader(fm: Record<string, any>, body: string, parent?: string | undefined): string;
+ * parent's description); absent, the slug alone. `pointers` are the lines
+ * naming what hangs off the entity elsewhere (its sessions, its archive). */
+export declare function formatEntityHeader(fm: Record<string, any>, body: string, parent?: string | undefined, pointers?: string[]): string;
+/** A session note: its day, then the entities it touched. */
+export declare function formatSessionHeader(fm: Record<string, any>, body: string): string;
 export declare function formatKnowledgeHeader(fm: Record<string, any>, body: string): string;
 export type QueryTableRow = Pick<QueryResult, 'slug' | 'name' | 'type' | 'status' | 'next_action' | 'next_action_count'>;
 export declare function formatQueryTable(results: QueryTableRow[], total?: number): string;
 export type KnowledgeTableRow = Pick<KnowledgeQueryResult, 'slug' | 'name' | 'confidence' | 'domain' | 'reinforcement_count'>;
 export declare function formatKnowledgeTable(results: KnowledgeTableRow[], total?: number): string;
+export type SessionTableRow = Pick<SessionQueryResult, 'slug' | 'name' | 'session_date' | 'related'>;
+export declare function formatSessionTable(results: SessionTableRow[], total?: number): string;
 export declare function formatSearchResults(results: SearchResult[]): string;
 export declare function formatStats(stats: VaultStats): string;
 export declare function formatChangelog(entries: ChangelogEntry[]): string;