hafez 1.3.0 → 2.0.0

package/dist/cli/commands.js

@@ -1,10 +1,18 @@
 // src/cli/commands.ts
 import { readFileSync } from 'fs';
-import { parseArgs, splitList, str, UsageError } from './args.js';
+import { resolve } from 'path';
+import { helpIfAsked, parseArgs, splitList, str, MisuseError, RenderedError, UnknownFlagError, UsageError } from './args.js';
 import { HafezError } from '../types.js';
-import { BatchOperationSchema } from '../batch-ops.js';
+import { BatchOperationSchema, normalizeAliases, opErrorLine, batchInvalidHeader } from '../batch-ops.js';
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
+import { detectAgent } from '../harness.js';
+import { getActionItems } 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';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
@@ -17,30 +25,134 @@ export async function cmdRead(os, args, opts = {}) {
     if (!slug)
         throw new UsageError(READ_USAGE);
     const depth = (str(flags.depth) ?? 'summary');
-    const result = await os.read(slug, depth);
-    if (opts.json)
-        return jsonOut(result);
+    const result = await os.read(slug, depth).catch(err => {
+        if (!(err instanceof HafezError) || err.code !== 'NOT_FOUND')
+            throw err;
+        const closest = err.details ?? [];
+        throw opts.json
+            ? new RenderedError('NOT_FOUND', jsonOut({ slug, closest }), 'stdout')
+            : new RenderedError('NOT_FOUND', ITEMS.slugMissRecovery.render({ slug, closest }), 'stderr');
+    });
+    const footer = await footerFor(os, slug, result, depth);
+    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 });
+    }
     const fm = result.frontmatter;
-    if (result.kind === 'entity')
-        return formatEntityHeader(fm, result.body);
-    return formatKnowledgeHeader(fm, result.body);
+    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))
+        : formatKnowledgeHeader(fm, result.body);
+    // Trailing newlines only: the Footer brings its own blank line.
+    return `${text.replace(/\n+$/, '')}\n${ITEMS.writeLine.render(footer)}`;
+}
+/** 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. */
+async function parentLine(os, parent) {
+    if (!parent)
+        return undefined;
+    const description = await os.read(parent, 'frontmatter')
+        .then(file => file.frontmatter.description ?? null)
+        .catch(() => null);
+    return ITEMS.parentDescription.render({ slug: parent, description });
 }
-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]';
+/** The Handles of the Stale lines an entity holds after a write; none for a
+ * knowledge note. Best-effort: the write is committed, so a failed read here
+ * drops the reminder rather than failing the update. */
+async function staleAfterWrite(os, slug) {
+    try {
+        const file = await os.read(slug, 'full');
+        return file.kind === 'entity' ? staleHandles(file.body, file.frontmatter) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** 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. */
+async function footerFor(os, slug, result, depth) {
+    return { slug, agent: detectAgent(), ...(result.kind === 'entity'
+            ? {
+                target: { kind: 'entity', type: result.frontmatter.type },
+                handle: getActionItems(depth === 'full' ? result.body : (await os.read(slug, 'full')).body).find(a => a.handle)?.handle,
+            }
+            : { 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]
+
+  --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.`;
 const QUERY_FLAGS = {
     kind: 'string', filter: 'string', type: 'string', parent: 'string', 'related-to': 'string',
     domain: 'string', confidence: 'string', subtype: 'string', tag: 'string',
     since: 'string', before: 'string', 'created-since': 'string', 'created-before': 'string',
     'sort-by': 'string', 'sort-order': 'string', limit: 'string', offset: 'string',
 };
+/** Every flag the query parser accepts, for the branch-support matrix. */
+export const QUERY_FLAG_NAMES = Object.keys(QUERY_FLAGS);
+/** 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`
+ * never reached an entity query at all. */
+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'],
+    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'],
+};
+const FLAG_SCOPE_REASON = {
+    filter: 'it selects entity status (or the entity-only stale/capture views); knowledge notes carry no status',
+    type: 'entity types only',
+    parent: 'entity hierarchy only',
+    confidence: 'knowledge notes only',
+    subtype: 'knowledge notes only',
+};
+const QUERY_KINDS = ['entity', 'knowledge', '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 --kind ${branch}`;
+        const reason = FLAG_SCOPE_REASON[name] ? ` — ${FLAG_SCOPE_REASON[name]}` : '';
+        throw new UsageError(`--${name} is not supported ${where}${reason}\n${QUERY_USAGE}`);
+    }
+}
+/** Paging flags reach SQL as text — parse them strictly here so `--limit abc`
+ * is a usage error rather than a prepare-time SqliteError. */
+function intFlag(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw new UsageError(`--${name} must be a non-negative integer (got "${raw}")\n${QUERY_USAGE}`);
+    return Number(raw);
+}
 export async function cmdQuery(os, args, opts = {}) {
     const { flags } = parseArgs(args, QUERY_FLAGS, QUERY_USAGE);
-    const kind = str(flags.kind) ?? 'entity';
+    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}`);
+    }
+    rejectUnsupportedFlags(branch, flags);
     const filter = (str(flags.filter) ?? 'active');
     const type = str(flags.type);
     const parent = str(flags.parent);
-    const relatedTo = str(flags['related-to']);
     const domain = str(flags.domain);
     const confidence = str(flags.confidence);
+    const subtype = str(flags.subtype);
     const since = str(flags.since);
     const before = str(flags.before);
     const createdSince = str(flags['created-since']);
@@ -49,11 +161,10 @@ export async function cmdQuery(os, args, opts = {}) {
     const tags = tagRaw ? tagRaw.split(',').map(t => t.trim()).filter(Boolean) : undefined;
     const sortBy = str(flags['sort-by']);
     const sortOrder = str(flags['sort-order']);
-    const limitRaw = str(flags.limit);
-    const offsetRaw = str(flags.offset);
-    const limit = limitRaw != null ? parseInt(limitRaw, 10) : undefined;
-    const offset = offsetRaw != null ? parseInt(offsetRaw, 10) : undefined;
+    const limit = intFlag(str(flags.limit), 'limit');
+    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
     if (relatedTo) {
         const result = await os.related_to(relatedTo);
@@ -69,20 +180,19 @@ export async function cmdQuery(os, args, opts = {}) {
             sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge, total));
         return sections.length > 0 ? sections.join('\n\n') : 'No results.';
     }
-    const queryOpts = { filter, type, parent, domain, since, before, createdSince, createdBefore, tags, ...sortOpts };
-    // --kind knowledge: query knowledge only
-    // Note: time flags only apply to entity queries.
-    if (kind === 'knowledge') {
-        const subtype = str(flags.subtype);
-        const kOpts = { domain: domain ?? undefined, confidence, subtype, tags, ...sortOpts };
+    const queryOpts = { filter, type, parent, domain, ...timeOpts, tags, ...sortOpts };
+    // --kind knowledge: query knowledge only. The time window applies here too —
+    // knowledge rows carry created (and last-touched for the plan subtype).
+    if (branch === 'knowledge') {
+        const kOpts = { domain: domain ?? undefined, confidence, subtype, ...timeOpts, tags, ...sortOpts };
         const result = await os.query_knowledge(kOpts);
         if (opts.json)
             return jsonOut(result);
         return formatKnowledgeTable(result.items, result.total);
     }
     // --kind all: query both entities and knowledge via unified query
-    if (kind === 'all') {
-        const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence });
+    if (branch === 'all') {
+        const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence, subtype });
         if (opts.json)
             return jsonOut(result);
         const { items, total } = result;
@@ -116,13 +226,84 @@ export async function cmdSearch(os, args, opts = {}) {
         return jsonOut(results);
     return formatSearchResults(results);
 }
-const CREATE_USAGE = 'Usage: hafez create <entity|knowledge> <name> [options]';
-const CREATE_FLAGS = {
+/** Flags whose value is a comma list, on create and update alike. */
+const LIST_FLAGS = new Set(['domain', 'related', 'tags']);
+/** The Write Line grammar, one mapper for create and update: every provided
+ * flag → its field, the flag name with dashes as underscores. A comma-list
+ * flag is split; a `clearable` flag maps `""` to null (its clear signal); a
+ * repeatable flag given once is its own field (`--add-action` → `add_action`)
+ * and given more than once is the array form of that field (`add_actions`),
+ * so each repeat appends. Which fields a target accepts is the Op Spec's
+ * call, not the CLI's — the strict shape does all accepting and rejecting.
+ * Only provided flags are included: a present-but-undefined key would trip
+ * that same strict shape. */
+function flagFields(spec, flags, opts = {}) {
+    const fields = {};
+    for (const flag of Object.keys(spec)) {
+        const raw = flags[flag];
+        if (raw === undefined || opts.skip?.has(flag))
+            continue;
+        const field = flag.replace(/-/g, '_');
+        if (Array.isArray(raw)) {
+            if (raw.length === 1)
+                fields[field] = raw[0];
+            else
+                fields[`${field}s`] = raw;
+        }
+        else if (typeof raw === 'boolean')
+            fields[field] = raw;
+        else if (LIST_FLAGS.has(flag))
+            fields[field] = splitList(raw);
+        else
+            fields[field] = raw === '' && opts.clearable?.has(flag) ? null : raw;
+    }
+    return fields;
+}
+// --status is knowledge/plan only, and --purpose needs --type project: a field
+// whose section the chosen template lacks is rejected, never silently dropped.
+const CREATE_USAGE = 'Usage: hafez create <entity|knowledge> <name> [options]\n  entity:    --type <capture|entity|project> [--purpose text (project only)] [--brief text] [--add-action text (repeats)] …\n  knowledge: [--subtype <insight|plan>] [--status <active|done> (plan only)] [--synthesis text (insight only)] [--confidence <observation|pattern|principle>] [--new (write despite a near-match)] …';
+/** Exported so tests can assert the flag × kind matrix is exhaustive. */
+export const CREATE_FLAGS = {
     type: 'string', purpose: 'string', description: 'string', resource: 'string',
     domain: 'string', parent: 'string', related: 'string', tags: 'string',
-    brief: 'string', 'add-action': 'string',
-    subtype: 'string', synthesis: 'string', insight: 'string',
+    brief: 'string', 'add-action': 'repeat',
+    subtype: 'string', synthesis: 'string', insight: 'string', confidence: 'string',
+    // knowledge, plan subtype only — insights have no lifecycle
+    status: 'string',
+    // knowledge only: write despite a Near-match. Not a field of any shape.
+    new: 'boolean',
 };
+/** Every knowledge note, with its subtype, for the Near-match check. */
+async function knowledgeNotes(os) {
+    const plans = new Set((await os.query_knowledge({ subtype: 'plan' })).items.map(n => n.slug));
+    return (await os.query_knowledge()).items.map(n => ({
+        slug: n.slug, name: n.name, description: n.description, subtype: plans.has(n.slug) ? 'plan' : 'insight',
+    }));
+}
+/** The parsed flags as `[flag, value?]` pairs, in the order first given,
+ * for echoing a create line back. */
+function echoFlags(flags) {
+    return Object.entries(flags).flatMap(([flag, value]) => value === true ? [[flag]]
+        : Array.isArray(value) ? value.map(v => [flag, v])
+            : typeof value === 'string' ? [[flag, value]] : []);
+}
+/** `batch`'s Near-match warnings (#60): a save never fails on one, so they
+ * only warn. Each create is judged against the vault plus the batch's
+ * earlier creates. */
+async function nearMatchWarnings(os, operations) {
+    if (!operations.some(op => op.op === 'create' && op.kind === 'knowledge'))
+        return [];
+    const seen = await knowledgeNotes(os);
+    return operations.flatMap((op, index) => {
+        if (op.op !== 'create' || op.kind !== 'knowledge')
+            return [];
+        const { near } = resemblances(op.name, seen);
+        seen.push({ slug: slugify(op.name), name: op.name, subtype: op.fields?.subtype ?? 'insight' });
+        return near.length > 0
+            ? [ITEMS.nearMatch.render({ form: 'batchWarning', index, name: op.name, matches: near.map(n => n.slug) })]
+            : [];
+    });
+}
 export async function cmdCreate(os, args, opts = {}) {
     const { flags, positionals } = parseArgs(args, CREATE_FLAGS, CREATE_USAGE);
     const kind = positionals[0];
@@ -131,51 +312,103 @@ export async function cmdCreate(os, args, opts = {}) {
     const name = positionals.slice(1).join(' ');
     if (!name)
         throw new UsageError(`Usage: hafez create ${kind} <name> [options]`);
+    if (flags.new !== undefined && kind !== 'knowledge') {
+        throw new UsageError('--new is for create knowledge only: it writes a note despite a near-match');
+    }
+    // Kind-agnostic on purpose: the per-kind hand-filter this replaced
+    // discarded whatever its branch didn't name (--brief on knowledge,
+    // --subtype on entity) and still exited 0 with the value nowhere on disk.
+    const fields = flagFields(CREATE_FLAGS, flags, { skip: new Set(['new']) });
     if (kind === 'entity') {
-        const type = str(flags.type);
-        if (!type)
+        // The only per-kind rule the CLI still owns: --type is required, and a
+        // missing one deserves better than a shape error naming a JSON field.
+        if (fields.type === undefined)
             throw new UsageError('--type is required for entity creation');
-        const slug = await os.create('entity', name, {
-            type,
-            purpose: str(flags.purpose),
-            description: str(flags.description),
-            resource: str(flags.resource),
-            domain: splitList(flags.domain),
-            parent: str(flags.parent),
-            related: str(flags.related)?.split(','),
-            tags: str(flags.tags)?.split(','),
-            brief: str(flags.brief),
-            add_action: str(flags['add-action']),
-        });
+        const slug = await os.create('entity', name, fields);
         return opts.json ? jsonOut({ slug }) : slug;
     }
     if (kind === 'knowledge') {
-        const slug = await os.create('knowledge', name, {
-            subtype: str(flags.subtype),
-            synthesis: str(flags.synthesis) ?? str(flags.insight),
-            description: str(flags.description),
-            domain: str(flags.domain)?.split(','),
-            related: str(flags.related)?.split(','),
-            tags: str(flags.tags)?.split(','),
-        });
-        return opts.json ? jsonOut({ slug }) : slug;
+        // --insight passes through untouched: the Op Spec normalizes the alias
+        // (and drops it when --synthesis is also given). On entity it stays
+        // `insight` and the kind gate rejects it. --status flows through the
+        // same way; the subtype-aware gate accepts it on plans only.
+        const knowledgeFields = fields;
+        const { near, weak } = resemblances(name, await knowledgeNotes(os));
+        // Near-match (#60): refuse unless --new, handing back the update line.
+        // Only a create that would otherwise be written: an invalid one, or an
+        // exact slug collision, gets its own error rather than a --new line that
+        // would fail the same way.
+        if (near.length > 0 && flags.new === undefined
+            && (await os.validateBatch([{ op: 'create', kind: 'knowledge', name, fields: knowledgeFields }])).valid) {
+            throw new HafezError('SLUG_EXISTS', ITEMS.nearMatch.render({
+                form: 'refusal', name, flags: echoFlags(flags), matches: near,
+                evidence: str(flags.synthesis) ?? str(flags.insight),
+            }));
+        }
+        const slug = await os.create('knowledge', name, knowledgeFields);
+        if (opts.json)
+            return jsonOut({ slug });
+        const related = knowledgeFields.related ?? [];
+        const resembles = [...near, ...weak].map(n => n.slug).filter(r => !related.includes(r)).slice(0, 3);
+        if (resembles.length === 0)
+            return slug;
+        return `${slug}\n${ITEMS.nearMatch.render({ form: 'relate', slug, related, resembles })}`;
     }
     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] [--complete-action text] [--remove-action text] [--clear-actions] [--status s] [--log "type: summary"]';
-const UPDATE_FLAGS = {
+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]]';
+/** Exported so tests can assert the table covers the update schema. */
+export const UPDATE_FLAGS = {
     status: 'string', 'current-state': 'string', brief: 'string',
-    'add-action': 'string', 'complete-action': 'string', 'remove-action': 'string',
-    'clear-actions': 'boolean', log: 'string', agent: 'string',
+    'add-action': 'repeat', 'complete-action': 'string', 'remove-action': 'string',
+    'clear-actions': 'boolean', parent: 'string',
     description: 'string', resource: 'string', domain: 'string', confidence: 'string',
     tags: 'string', related: 'string', insight: 'string', synthesis: 'string',
-    'add-evidence': 'string', 'add-source': 'string',
+    'add-evidence': 'string', 'add-source': 'string', agent: 'string',
+    // Composed, not mapped: --log "type: summary" plus --body (and --agent, when
+    // given) build session_log.
+    log: 'string', body: 'string',
     // Removed flag, declared so it fails with guidance instead of a generic
     // unknown-flag error: older installed skills/scripts still pass it, and
     // "Updated <slug>" with the action discarded is a false success.
     'next-action': 'string',
 };
+/** Flags where an empty string is the clear signal — exactly the nullable
+ * fields of the update shape. Every other flag passes its value through
+ * untouched, so `--status ""` reaches the enum and is rejected by name
+ * instead of silently no-opping (which is how it read before: the guard
+ * each flag got was an accident of which one was typed). */
+const UPDATE_CLEARABLE_FLAGS = new Set(['brief', 'description', 'resource']);
+/** Flags the generic loop skips because they are not a field of the update
+ * shape — each is hand-handled in cmdUpdate. */
+export const UPDATE_SPECIAL_FLAGS = new Set(['log', 'body', 'next-action']);
+/** Update-shape fields with no flag of their own, and why. The exhaustiveness
+ * test consults this, so a gap here is a stated decision rather than the
+ * silent hole `add_actions` was. */
+export const UPDATE_FIELDS_WITHOUT_FLAGS = {
+    session_log: 'composed by --log "type: summary" (+ --body, --agent), never passed raw',
+};
 export async function cmdUpdate(os, args, opts = {}) {
+    // Every Write Line names the slug first, so a misuse that stops the parse
+    // part-way is still reported against it.
+    let slug = args[0]?.startsWith('--') ? undefined : args[0];
+    let fields;
+    let result;
+    try {
+        ({ slug, fields } = parseUpdate(args));
+        result = await os.update(slug, fields);
+    }
+    catch (err) {
+        throw await updateFailure(os, slug, err, opts);
+    }
+    if (opts.json)
+        return jsonOut({ slug, ...result });
+    const summary = ITEMS.updateSummary.render({ slug, fields, result });
+    const stale = await staleAfterWrite(os, slug);
+    return stale.length > 0 ? `${summary}\n${ITEMS.staleReminder.render({ handles: stale })}` : summary;
+}
+/** The update's argv as its slug and fields: the Write Line grammar. */
+function parseUpdate(args) {
     const { flags, positionals } = parseArgs(args, UPDATE_FLAGS, UPDATE_USAGE);
     const slug = positionals[0];
     if (!slug)
@@ -183,79 +416,66 @@ export async function cmdUpdate(os, args, opts = {}) {
     if (flags['next-action'] !== undefined) {
         throw new UsageError('--next-action was removed in v1.0.2. Use --add-action (and --clear-actions) instead.');
     }
-    const fields = {};
-    const status = str(flags.status);
-    if (status)
-        fields.status = status;
-    const currentState = str(flags['current-state']);
-    if (currentState)
-        fields.current_state = currentState;
-    // Brief
-    const brief = str(flags.brief);
-    if (brief !== undefined) {
-        fields.brief = brief === '' ? null : brief;
-    }
-    // Next Actions
-    const addAction = str(flags['add-action']);
-    if (addAction)
-        fields.add_action = addAction;
-    const completeAction = str(flags['complete-action']);
-    if (completeAction)
-        fields.complete_action = completeAction;
-    const removeAction = str(flags['remove-action']);
-    if (removeAction)
-        fields.remove_action = removeAction;
-    if (flags['clear-actions'])
-        fields.clear_actions = true;
+    // --insight is the declared alias; the Op Spec normalizes it (and drops it
+    // when --synthesis is also given).
+    const fields = flagFields(UPDATE_FLAGS, flags, { skip: UPDATE_SPECIAL_FLAGS, clearable: UPDATE_CLEARABLE_FLAGS });
+    // The one genuinely CLI-owned convenience: session_log is a nested object,
+    // so the flag pair composes it rather than naming a field. Without --log,
+    // the Spine adds the entry itself and --agent rides along as `agent`.
     const log = str(flags.log);
-    if (log) {
+    const body = str(flags.body);
+    if (body !== undefined && log === undefined) {
+        throw new UsageError('--body is the detail of a session log entry and needs --log "type: summary"');
+    }
+    if (log !== undefined) {
         const colonIdx = log.indexOf(':');
         if (colonIdx === -1)
             throw new UsageError('--log format: "type: summary". Types: progress, decision, blocker, research');
-        const type = log.slice(0, colonIdx).trim();
-        const summary = log.slice(colonIdx + 1).trim();
-        const agent = str(flags.agent) ?? 'claude';
-        fields.session_log = { type, summary, agent };
-    }
-    // Shared metadata (entity + knowledge)
-    const description = str(flags.description);
-    if (description !== undefined)
-        fields.description = description;
-    const resource = str(flags.resource);
-    if (resource !== undefined)
-        fields.resource = resource;
-    const domain = splitList(flags.domain);
-    if (domain)
-        fields.domain = domain;
-    const conf = str(flags.confidence);
-    if (conf)
-        fields.confidence = conf;
-    const tags = splitList(flags.tags);
-    if (tags)
-        fields.tags = tags;
-    const related = splitList(flags.related);
-    if (related)
-        fields.related = related;
-    const insight = str(flags.insight);
-    if (insight)
-        fields.synthesis = insight;
-    const synthesis = str(flags.synthesis);
-    if (synthesis)
-        fields.synthesis = synthesis;
-    const addEvidence = str(flags['add-evidence']);
-    if (addEvidence)
-        fields.add_evidence = addEvidence;
-    const addSource = str(flags['add-source']);
-    if (addSource)
-        fields.add_source = addSource;
-    const result = await os.update(slug, fields);
-    if (opts.json)
-        return jsonOut({ slug, ...result });
-    const lines = [`Updated ${slug}`];
-    if (result.matched_action) {
-        lines.push(`matched action: ${result.matched_action}`);
+        fields.session_log = {
+            type: log.slice(0, colonIdx).trim(),
+            summary: log.slice(colonIdx + 1).trim(),
+            ...(body !== undefined && { body }),
+            agent: fields.agent ?? detectAgent(),
+        };
+        delete fields.agent;
     }
-    return lines.join('\n');
+    // An update that names nothing to change would print a success line that
+    // names nothing either.
+    if (Object.keys(fields).length === 0)
+        throw new UsageError('update needs at least one flag');
+    return { slug, fields: fields };
+}
+/** What a failed update reports (Agent Contract: a misuse returns the
+ * corrected shape). A misuse — a usage error or a write the Op Spec rejected —
+ * says nothing was written, then gives the Footer `read` shows for the slug;
+ * a slug that names no file gets the `read` miss instead. Anything else, and
+ * any failure with no slug to report against, passes through unchanged. */
+async function updateFailure(os, slug, err, opts) {
+    const misuse = err instanceof UsageError
+        ? { error: err instanceof UnknownFlagError ? `update has no flag --${err.flag}` : err.reason }
+        : err instanceof HafezError && err.code === 'VALIDATION_FAILED' ? { error: err.message, details: err.details }
+            : undefined;
+    const missing = err instanceof HafezError && err.code === 'NOT_FOUND';
+    // Under --json only the miss has a machine form (read's); a misuse's
+    // Footer is prose, so the error passes through as it always has.
+    if (slug === undefined || (!misuse && !missing) || (opts.json && misuse))
+        return err;
+    let retry;
+    try {
+        retry = { footer: await footerFor(os, slug, await os.read(slug, 'full'), 'full') };
+    }
+    catch (readErr) {
+        if (!(readErr instanceof HafezError) || readErr.code !== 'NOT_FOUND')
+            return err;
+        retry = { miss: { slug, closest: readErr.details ?? [] } };
+    }
+    if (misuse)
+        return new RenderedError('VALIDATION_FAILED', ITEMS.updateMisuse.render({ ...misuse, ...retry }), 'stderr');
+    if (!('miss' in retry))
+        return err;
+    return opts.json
+        ? new RenderedError('NOT_FOUND', jsonOut(retry.miss), 'stdout')
+        : new RenderedError('NOT_FOUND', ITEMS.slugMissRecovery.render(retry.miss), 'stderr');
 }
 const LINK_FLAGS = { relation: 'string' };
 function parseLinkArgs(args, verb) {
@@ -305,7 +525,18 @@ export async function cmdPromote(os, args, opts = {}) {
         return jsonOut({ slug, target });
     return `Promoted ${slug} → ${target}`;
 }
-export async function cmdValidate(os, _args, opts = {}) {
+const DELETE_USAGE = 'Usage: hafez delete <slug>  (knowledge and session notes only — retire an entity with `hafez update <slug> --status done`)';
+export async function cmdDelete(os, args, opts = {}) {
+    const { positionals } = parseArgs(args, {}, DELETE_USAGE);
+    if (positionals.length !== 1)
+        throw new UsageError(DELETE_USAGE);
+    const [slug] = positionals;
+    // What may be deleted (not an entity, nothing linking to it) is core's rule.
+    const kind = await os.delete(slug);
+    return opts.json ? jsonOut({ slug, kind }) : `Deleted ${slug} (${kind})`;
+}
+export async function cmdValidate(os, args, opts = {}) {
+    helpIfAsked(args, 'Usage: hafez validate');
     const report = await os.validate();
     if (opts.json)
         return jsonOut(report);
@@ -315,7 +546,8 @@ export async function cmdIndexRebuild(os) {
     await os.rebuildIndex();
     return 'Index rebuilt.';
 }
-export async function cmdSync(os, _args) {
+export async function cmdSync(os, args) {
+    helpIfAsked(args, 'Usage: hafez sync  (pull remote changes, push local commits)');
     const result = await os.sync();
     if (!result.remote)
         return 'No remote configured — vault is local-only. Every write is already committed to git.';
@@ -327,7 +559,8 @@ export async function cmdSync(os, _args) {
         return 'Synced: pushed local commits.';
     return 'Already up to date.';
 }
-export async function cmdStats(os, _args, opts = {}) {
+export async function cmdStats(os, args, opts = {}) {
+    helpIfAsked(args, 'Usage: hafez stats');
     const stats = await os.stats();
     if (opts.json)
         return jsonOut(stats);
@@ -391,19 +624,12 @@ export function parseBatchInput(json) {
             continue;
         }
         const op = result.data;
-        // Alias: insight → synthesis for create knowledge/session and update ops.
-        // Runs only on successfully-parsed ops, preserving prior semantics.
-        if (op.fields) {
-            if (op.fields.insight && !op.fields.synthesis) {
-                op.fields.synthesis = op.fields.insight;
-                delete op.fields.insight;
-            }
-        }
-        operations.push(op);
+        // Alias normalization is the Op Spec's (normalizeAliases) — the CLI just
+        // hands back canonical ops so `batch --dry-run` output names real fields.
+        operations.push(normalizeAliases(op));
     }
     if (failureBlocks.length > 0) {
-        const header = `Batch failed validation: ${failureBlocks.length} invalid operation${failureBlocks.length === 1 ? '' : 's'} (0 of ${parsed.length} applied)`;
-        throw new HafezError('VALIDATION_FAILED', header, failureBlocks);
+        throw new HafezError('VALIDATION_FAILED', batchInvalidHeader(failureBlocks.length, parsed.length), failureBlocks);
     }
     return operations;
 }
@@ -424,6 +650,19 @@ function readPayloadFile(path) {
         return buf.toString('utf16le').replace(/^\uFEFF/, '');
     return buf.toString('utf-8').replace(/^\uFEFF/, '');
 }
+// The payload as one argument. Exists because Codex runs a command outside its
+// sandbox (where the vault's .git is writable) only when every stage of a pipe
+// matches an allow rule: `hafez digest --data '…' | hafez batch` does, an `echo`
+// stage does not.
+function readPayload(flags, usage) {
+    const data = str(flags.data);
+    const file = str(flags.file);
+    if (data !== undefined && file !== undefined)
+        throw new UsageError(`--data and --file are two ways to pass one payload; give one.\n${usage}`);
+    if (data !== undefined)
+        return data;
+    return file ? readPayloadFile(file) : readStdin();
+}
 function readStdin() {
     return new Promise((resolve, reject) => {
         let data = '';
@@ -433,17 +672,32 @@ function readStdin() {
         process.stdin.on('error', reject);
     });
 }
-const BATCH_USAGE = "Usage: hafez batch [--dry-run] [--file payload.json]  (or pipe JSON to stdin)";
-const BATCH_FLAGS = { 'dry-run': 'boolean', file: 'string' };
+const BATCH_USAGE = "Usage: hafez batch [--dry-run] [--data '<payload>' | --file payload.json]  (or pipe JSON to stdin)";
+const BATCH_FLAGS = { 'dry-run': 'boolean', data: 'string', file: 'string' };
 export async function cmdBatch(os, args, opts = {}) {
     const { flags } = parseArgs(args, BATCH_FLAGS, BATCH_USAGE);
     const dryRun = flags['dry-run'] === true;
-    const file = str(flags.file);
-    const input = file ? readPayloadFile(file) : await readStdin();
+    const input = await readPayload(flags, BATCH_USAGE);
+    // A payload that is not a well-formed batch is a misuse: the error carries
+    // the batch shape so the retry is right. Semantic failures (a missing slug)
+    // are not shape problems and say only what failed.
+    // No input is not one: in a pipe it means the stage before failed and said
+    // why, and a batch shape there would invite hand-writing the ops.
     if (!input.trim()) {
-        throw new HafezError('VALIDATION_FAILED', 'No input received. Pipe JSON array to stdin (echo \'[...]\' | hafez batch) or pass --file payload.json');
+        throw new HafezError('VALIDATION_FAILED', 'No input received. Pipe JSON array to stdin (echo \'[...]\' | hafez batch) or pass --data \'[...]\' or --file payload.json');
+    }
+    let operations;
+    try {
+        operations = parseBatchInput(input);
+    }
+    catch (err) {
+        throw err instanceof HafezError ? new MisuseError(err, placeIn('batchMisuse', 'batchShape')) : err;
     }
-    const operations = parseBatchInput(input);
+    const nearMatches = await nearMatchWarnings(os, operations);
+    // Under --json stdout is the report alone; the warnings go to stderr.
+    if (opts.json)
+        for (const w of nearMatches)
+            process.stderr.write(`${w}\n`);
     if (dryRun) {
         // Same validate phase as apply — dry-run can never green-light a payload
         // apply rejects. Reports derived slugs so agents can predict create slugs.
@@ -452,7 +706,9 @@ export async function cmdBatch(os, args, opts = {}) {
             return jsonOut(report);
         if (!report.valid) {
             const invalidCount = report.operations.filter(o => o.errors.length > 0).length;
-            const lines = report.operations.flatMap(o => o.errors.map(e => `op[${o.index}] (${o.op} ${o.slug}): ${e}`));
+            const lines = report.operations.flatMap(o => o.errors.map(e => opErrorLine(o.index, o.op, o.slug, e)));
+            // Dry-run's own header: it reports a hypothetical, so it says "would be
+            // applied" rather than the refusal wording batchInvalidHeader carries.
             throw new HafezError('VALIDATION_FAILED', `Batch invalid: ${invalidCount} of ${operations.length} operation${operations.length === 1 ? '' : 's'} failed validation (0 would be applied)`, lines);
         }
         const out = [`Batch valid: ${operations.length} operations would be applied`];
@@ -466,7 +722,7 @@ export async function cmdBatch(os, args, opts = {}) {
             if (o.warning)
                 out.push(`Warning: op[${o.index}] ${o.warning}`);
         }
-        return out.join('\n');
+        return [...out, ...nearMatches].join('\n');
     }
     const results = await os.batch(operations);
     if (opts.json)
@@ -475,16 +731,21 @@ export async function cmdBatch(os, args, opts = {}) {
     let output = `Batch complete: ${operations.length} operations`;
     if (created.length > 0)
         output += ` (created: ${created.join(', ')})`;
-    return output;
+    // Skipped ops carry the same warning line dry-run printed for them.
+    const lines = [output];
+    results.forEach((r, i) => {
+        if (r.status === 'skipped' && r.warning)
+            lines.push(`Warning: op[${i}] ${r.warning}`);
+    });
+    return [...lines, ...nearMatches].join('\n');
 }
-const DIGEST_USAGE = 'Usage: hafez digest [--file summary.json]  (or pipe JSON to stdin)';
-const DIGEST_FLAGS = { file: 'string' };
+const DIGEST_USAGE = "Usage: hafez digest [--data '<summary>' | --file summary.json]  (or pipe JSON to stdin)";
+const DIGEST_FLAGS = { data: 'string', file: 'string' };
 export async function cmdDigest(os, args, _opts = {}) {
     const { flags } = parseArgs(args, DIGEST_FLAGS, DIGEST_USAGE);
-    const file = str(flags.file);
-    const raw = file ? readPayloadFile(file) : await readStdin();
+    const raw = await readPayload(flags, DIGEST_USAGE);
     if (!raw.trim()) {
-        throw new UsageError('No input received. Pipe JSON object to stdin (echo \'{"entities_touched":...}\' | hafez digest) or pass --file summary.json');
+        throw new UsageError('No input received. Pipe JSON object to stdin (echo \'{"entities_touched":...}\' | hafez digest) or pass --data \'<summary>\' or --file summary.json');
     }
     // Parse JSON
     let parsed;
@@ -505,12 +766,34 @@ export async function cmdDigest(os, args, _opts = {}) {
     }
     // Resolve existing entity slugs — digest only generates update ops for entities
     const { items: entityItems } = await os.query({ filter: 'all', limit: 9999 });
-    const existingSlugs = new Set(entityItems.map(i => i.slug));
-    // Warn about unknown entity slugs
-    const unknownSlugs = result.data.entities_touched.filter(s => !existingSlugs.has(s));
-    for (const slug of unknownSlugs) {
-        process.stderr.write(`Warning: entity slug '${slug}' not found in vault — skipping session log update\n`);
+    const { items: knowledgeItems } = await os.query_knowledge({ limit: 9999 });
+    const ops = digest(result.data, new Set(entityItems.map(i => i.slug)), new Set(knowledgeItems.map(i => i.slug)));
+    // A session already saved: emit the session note alone, which batch skips
+    // as a duplicate, so a second save writes no second set of log entries.
+    const note = ops.find(o => o.op === 'create');
+    const [check] = (await os.validateBatch([note])).operations;
+    if (check.warning) {
+        process.stderr.write(`Session already saved as '${check.slug}' — skipped, nothing new to write\n`);
+        return JSON.stringify([note], null, 2);
     }
-    const ops = digest(result.data, existingSlugs);
     return JSON.stringify(ops, null, 2);
 }
+export async function cmdExport(_os, args, opts = {}) {
+    const EXPORT_USAGE = 'Usage: hafez export --okf [--out <dir>]';
+    const { flags } = parseArgs(args, { okf: 'boolean', out: 'string' }, EXPORT_USAGE);
+    if (flags.okf !== true)
+        throw new UsageError(EXPORT_USAGE);
+    const outDir = typeof flags.out === 'string' ? resolve(flags.out) : resolve(process.cwd(), 'okf-export');
+    if (!opts.vaultPath)
+        throw new HafezError('VALIDATION_FAILED', 'export requires a resolved vault path (CommandOpts.vaultPath)');
+    const { exportOkf } = await import('../export-okf.js');
+    const exportReport = exportOkf(opts.vaultPath, outDir);
+    if (opts.json)
+        return JSON.stringify(exportReport, null, 2);
+    const lines = [`Exported ${exportReport.entities} entities, ${exportReport.knowledge} knowledge, ${exportReport.sessions} sessions to ${exportReport.outDir}`];
+    for (const s of exportReport.skipped)
+        lines.push(`  skipped ${s.file}: ${s.reason}`);
+    if (exportReport.unresolvedLinks > 0)
+        lines.push(`  unresolved links: ${exportReport.unresolvedLinks}`);
+    return lines.join('\n');
+}