hafez 2.0.0 → 2.2.0

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);
@@ -356,11 +407,11 @@ export async function cmdCreate(os, args, opts = {}) {
     }
     throw new UsageError(`Unknown kind: ${kind}. Use entity or knowledge.`);
 }
-const UPDATE_USAGE = 'Usage: hafez update <slug> [--brief text] [--description text] [--resource uri] [--add-action text (repeats)] [--complete-action handle-or-text] [--remove-action handle-or-text] [--clear-actions] [--status <active|paused|done>] [--parent slug] [--log "<progress|decision|blocker|research>: summary" [--body text]]';
+const UPDATE_USAGE = 'Usage: hafez update <slug> [--brief text] [--description text] [--resource uri] [--add-action text (repeats)] [--complete-action handle-or-text (repeats)] [--remove-action handle-or-text (repeats)] [--clear-actions] [--status <active|paused|done>] [--parent slug] [--log "<progress|decision|blocker|research>: summary" [--body text]]';
 /** Exported so tests can assert the table covers the update schema. */
 export const UPDATE_FLAGS = {
     status: 'string', 'current-state': 'string', brief: 'string',
-    'add-action': 'repeat', 'complete-action': 'string', 'remove-action': 'string',
+    'add-action': 'repeat', 'complete-action': 'repeat', 'remove-action': 'repeat',
     'clear-actions': 'boolean', parent: 'string',
     description: 'string', resource: 'string', domain: 'string', confidence: 'string',
     tags: 'string', related: 'string', insight: 'string', synthesis: 'string',
@@ -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;

package/dist/cli/format.js

@@ -1,6 +1,7 @@
 /** `parent` is the rendered value of the `parent:` line (the slug with the
- * parent's description); absent, the slug alone. */
-export function formatEntityHeader(fm, body, parent = fm.parent) {
+ * parent's description); absent, the slug alone. `pointers` are the lines
+ * naming what hangs off the entity elsewhere (its sessions, its archive). */
+export function formatEntityHeader(fm, body, parent = fm.parent, pointers = []) {
     const lines = [`# ${fm.name}`];
     if (fm.description)
         lines.push(`> ${fm.description}`);
@@ -29,6 +30,23 @@ export function formatEntityHeader(fm, body, parent = fm.parent) {
         lines.push(`tags: ${fm.tags.join(', ')}`);
     if (fm.resource)
         lines.push(`resource: ${fm.resource}`);
+    lines.push(...pointers);
+    lines.push('');
+    lines.push(body);
+    return lines.join('\n');
+}
+/** A session note: its day, then the entities it touched. */
+export function formatSessionHeader(fm, body) {
+    const lines = [`# ${fm.name}`];
+    const meta = [];
+    if (fm['session-date'])
+        meta.push(`session-date: ${fm['session-date']}`);
+    if (fm.created)
+        meta.push(`created: ${fm.created}`);
+    if (meta.length)
+        lines.push(meta.join(' | '));
+    if (fm.related?.length)
+        lines.push(`related: ${fm.related.join(', ')}`);
     lines.push('');
     lines.push(body);
     return lines.join('\n');
@@ -100,11 +118,24 @@ export function formatKnowledgeTable(results, total) {
     }
     return lines.join('\n');
 }
+export function formatSessionTable(results, total) {
+    if (results.length === 0)
+        return 'No results.';
+    const lines = ['| slug | name | session-date | related |', '|------|------|--------------|---------|'];
+    for (const r of results) {
+        lines.push(`| ${r.slug} | ${r.name} | ${r.session_date} | ${r.related.join(', ')} |`);
+    }
+    if (total != null && results.length < total) {
+        lines.push(`\nShowing ${results.length} of ${total}`);
+    }
+    return lines.join('\n');
+}
 export function formatSearchResults(results) {
     if (results.length === 0)
         return 'No results.';
     const entities = results.filter(r => r.kind === 'entity');
     const knowledge = results.filter(r => r.kind === 'knowledge');
+    const sessions = results.filter(r => r.kind === 'session');
     const sections = [];
     if (entities.length > 0) {
         const lines = ['## Entities', '', '| slug | name | type | match |', '|------|------|------|-------|'];
@@ -118,6 +149,12 @@ export function formatSearchResults(results) {
             lines.push(`| ${r.slug} | ${r.name} | ${r.confidence ?? ''} | ${r.snippet} |`);
         sections.push(lines.join('\n'));
     }
+    if (sessions.length > 0) {
+        const lines = ['## Sessions', '', '| slug | name | match |', '|------|------|-------|'];
+        for (const r of sessions)
+            lines.push(`| ${r.slug} | ${r.name} | ${r.snippet} |`);
+        sections.push(lines.join('\n'));
+    }
     return sections.join('\n\n');
 }
 export function formatStats(stats) {
@@ -162,10 +199,11 @@ export function formatChangelog(entries) {
 export function formatValidation(report) {
     const issues = report.broken_slugs.length + report.orphaned_knowledge.length +
         report.missing_fields.length;
+    const counts = `${report.total_entities} entities, ${report.total_knowledge} knowledge, ${report.total_sessions} sessions`;
     if (issues === 0) {
-        return `Vault OK — ${report.total_entities} entities, ${report.total_knowledge} knowledge, 0 issues`;
+        return `Vault OK — ${counts}, 0 issues`;
     }
-    const sections = [`## Vault Validation — ${report.total_entities} entities, ${report.total_knowledge} knowledge`];
+    const sections = [`## Vault Validation — ${counts}`];
     const addSection = (title, items) => {
         if (items.length === 0)
             return;

package/dist/cli/index.js

@@ -68,6 +68,7 @@ export const EXIT_TABLE = [
     { exit: 5, meaning: 'slug already exists', errorCodes: ['SLUG_EXISTS'] },
     { exit: 6, meaning: 'git commit failed — nothing was written to history', errorCodes: ['GIT_COMMIT_FAILED'] },
     { exit: 7, meaning: 'vault locked by another hafez process — retry when it finishes', errorCodes: ['VAULT_LOCKED'] },
+    { exit: 8, meaning: "git read failed (changelog, stats) — the vault's git is unusable", errorCodes: ['GIT_READ_FAILED'] },
 ];
 export const EXIT_CODES = Object.fromEntries(EXIT_TABLE.flatMap(row => (row.errorCodes ?? []).map(code => [code, row.exit])));
 /** Exported so a guard test can assert every registered command is documented
@@ -75,11 +76,14 @@ export const EXIT_CODES = Object.fromEntries(EXIT_TABLE.flatMap(row => (row.erro
 export const USAGE = `Usage: hafez <command> [args]
 
 Commands:
-  read <slug>                Read entity or knowledge note
+  read <slug>                Read an entity, knowledge note or session note
+    --archive                An entity's archived log entries
   query [--filter ...] ...   Filter entities/knowledge
-    --kind all               Both kinds; --filter matches entity status only,
-                             so knowledge notes (which have none) always show
-  search <terms>             Full-text search
+    --kind all               Every kind, sessions included; --filter matches
+                             entity status only, so the rest always show
+    --kind session           Session notes alone, newest first
+  search <terms>             Full-text search of entities and knowledge
+    --kind session|all       Session notes alone, or every kind
   create <kind> <name>       Create entity or knowledge note
   capture <name> [--notes]   Quick inbox capture
   promote <slug> <target>    Promote capture→entity/project/knowledge, entity→project
@@ -88,9 +92,9 @@ Commands:
     --brief "text"           Set/replace Brief (use --brief "" to clear)
     --description "text"     Set one-line description (use --description "" to clear)
     --resource "uri"         Set canonical resource URI, entities only (use --resource "" to clear)
-    --add-action "text"      Add a next action
-    --complete-action handle-or-text  Complete the action with that Handle (as read shows it), else the matching one
-    --remove-action handle-or-text    Remove the action with that Handle, else the matching one
+    --add-action "text"      Add a next action (repeats)
+    --complete-action handle-or-text  Complete the action with that Handle (as read shows it), else the matching one (repeats)
+    --remove-action handle-or-text    Remove the action with that Handle, else the matching one (repeats)
     --clear-actions          Remove all next actions
     --synthesis "text"       Set/replace Synthesis section (--insight is an alias)
     --add-evidence "text"    Append to Evidence section
@@ -109,11 +113,14 @@ Commands:
   init --register <path>     Register an existing vault
   init                       Show current vault resolution
   onboard                    Setup status, then the script your agent follows to set Hafez up
-    --install --mode <always-on|invoke-only> [--harness <h>] [--confirm]
+    --install --mode <always-on|invoke-only> [--harness <h>] [--vault-repo <o/r>] [--confirm]
                              Write both skills and, always-on, the Block
+                             (--vault-repo: the cloud Block, which attaches that repo)
     --remove [--confirm]     Remove the skills and the Block region
     --block [--harness <h>]  Print the Block and the entities matching this folder
                              (the SessionStart hook; prints nothing on any failure)
+    --cloud --vault-repo <o/r>
+                             Print the setup script for Claude Code cloud sessions
   upgrade                    Check whether hafez is outdated and print the update steps
   help --agent               The hafez skill body: the reference when the skill is not installed
 
@@ -280,20 +287,25 @@ export async function main(argv) {
         // isBindingsFailure, exactly as it was when this import was static.
         const { createHafez } = await import('../index.js');
         const os = createHafez({ vaultPath, git: { push: false } });
-        const result = await spec.run(os, args, { json, vaultPath });
-        // Auto-sync after mutating commands
-        if (spec.mutating) {
-            try {
-                await os.sync();
-            }
-            catch (syncErr) {
-                // Operation succeeded but sync failed — emit result with warning, exit 4
-                process.stdout.write(result + '\n');
-                process.stderr.write(`Warning: ${syncErr.message ?? syncErr.message}\n`);
-                process.exit(4);
+        try {
+            const result = await spec.run(os, args, { json, vaultPath });
+            // Auto-sync after mutating commands
+            if (spec.mutating) {
+                try {
+                    await os.sync();
+                }
+                catch (syncErr) {
+                    // Operation succeeded but sync failed — emit result with warning, exit 4
+                    process.stdout.write(result + '\n');
+                    process.stderr.write(`Warning: ${syncErr.message ?? syncErr.message}\n`);
+                    process.exit(4);
+                }
             }
+            process.stdout.write(result + '\n');
+        }
+        finally {
+            os.close();
         }
-        process.stdout.write(result + '\n');
     }
     catch (err) {
         if (hook)

package/dist/cli/install.d.ts

@@ -6,6 +6,12 @@ export declare const SKILL_DIRS: string[];
 export type HashState = 'absent' | 'current' | 'stale' | 'hand-edited';
 /** What to do about broken markers: a hand edit, then `rerun`. */
 export declare const fixBrokenMarkers: (path: string, rerun: string) => string;
+/** The flag that keeps an install a cloud one, for every printed install line. */
+export declare const vaultRepoFlag: (vaultRepo: string | undefined) => string;
+/** What to do about a 1.x section: Hafez cannot tell where it ends. */
+export declare const removeLegacy: (path: string, line: number) => string;
+/** The status line for a 1.x section. */
+export declare const legacyLine: (path: string, line: number) => string;
 /** Codex reads an `AGENTS.override.md` in place of `AGENTS.md` when one
  * exists: the first candidate present, else the last. */
 export declare const instructionsFile: (home: string, candidates: readonly string[]) => string;
@@ -18,13 +24,20 @@ export interface InstallState {
     skills: HashState;
     /** Some skill file carries a hash: `onboard --install` has run here. */
     onboarded: boolean;
+    /** The line of a 1.x section in the instructions file, else null. */
+    legacy: number | null;
+    /** The Block is a cloud Block, for this vault repo. */
+    vaultRepo?: string;
 }
 export declare function installState(home: string, harness: HarnessId): InstallState;
+/** `vaultRepo`: the install is for a cloud container, whose Block carries
+ * the rule that attaches that repo as the vault (#160). */
 export declare function install(opts: {
     home: string;
     harness: HarnessId;
     mode: Mode;
     confirm: boolean;
+    vaultRepo?: string;
 }): string;
 export interface SkillCheck {
     path: string;
@@ -37,13 +50,21 @@ export interface BlockCheck {
     state: Exclude<HashState, 'absent'> | 'broken';
     /** The Block Hafez writes has changed since this one was written. */
     renderChanged: boolean;
+    /** A cloud Block: the vault repo it was written for. */
+    vaultRepo?: string;
+}
+export interface LegacyCheck {
+    harness: HarnessId;
+    path: string;
+    line: number;
 }
 /** Both skills in both directories, and the Block in the instructions file
  * each Harness reads — the one `--install` would write. Only Blocks that are
- * there are listed: none means invoke-only. */
+ * there are listed: none, and no 1.x section, means invoke-only. */
 export declare function checkInstall(home: string): {
     skills: SkillCheck[];
     blocks: BlockCheck[];
+    legacy: LegacyCheck[];
 };
 /** Remove everything Hafez wrote: both skills from both directories, and the
  * Block region from every instructions file a Harness reads. Nothing else. */