hafez 1.1.0 → 1.3.0

package/README.md

@@ -1,12 +1,14 @@
 # Hafez
 
-**An agent-native personal knowledge vault.** *Hafez* (حافظ) is Persian for "the keeper — the one who memorizes," after the poet. It keeps a durable, structured memory for AI agents: plain markdown files you own, backed by SQLite full-text search and git.
+**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
 
-AI agents forget everything between sessions. Hafez gives them a place to remember — projects, insights, decisions, session history — as a knowledge graph they can read, query, and write through a CLI.
+Humans have short-term context. Agents have session context. Both can think big only about what's loaded right now — so both need a place that carries what happened and where things stand, ready whenever either wants to remember. Hafez is that place: projects with goals, actions, and progress; decisions; the insights that outlive them — a graph of markdown files both of you read.
 
-The files stay yours. Everything is markdown with YAML frontmatter in a git repo: readable in any editor, Obsidian-compatible, diffable, and synced like code. The SQLite index (`.hafez.db`) is a disposable read cache rebuilt from the files; git is the source of truth and the sync mechanism.
+Writing is the agent's job. As you work, the results organise themselves into the vault — at session end, at the critical points of a project — through a CLI that owns the plumbing: structure, validation, search, index, git. A malformed write fails; links must resolve. No agent decides how to treat your vault, so every agent treats it the same — and its context goes to your content, not your conventions.
+
+The files stay yours. Everything is markdown with YAML frontmatter in a git repo: readable — and editable — in any editor, Obsidian-compatible, diffable, and synced like code. The SQLite index (`.hafez.db`) is a disposable read cache rebuilt from the files; git is the source of truth and the sync mechanism. Nothing is trapped, either: `hafez export --okf` writes the vault as a standard [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle — Hafez's schema is stricter than OKF's, so the export loses nothing.
 
 ## Setup
 
@@ -17,8 +19,9 @@ Claude Code (or any agent with shell access):
 Set up Hafez, an agent-native knowledge vault (github.com/shrvn-r/hafez):
 
 1. Install the CLI (needs Node.js 22+ and git): npm install -g hafez
-   On npm 12+, append --allow-scripts=better-sqlite3 (npm 12 blocks install
-   scripts by default; the SQLite bindings need theirs).
+   On npm 11+, append --allow-scripts=better-sqlite3 (npm 11 blocks install
+   scripts by default; the SQLite bindings need theirs, and the install
+   reports success even when they were skipped).
 2. Check git identity is configured (git config user.name and user.email);
    if not, ask me for a name and email and set them with git config --global.
 3. Create my vault — a git repo with entities/ and knowledge/ directories and an
@@ -38,13 +41,17 @@ Set up Hafez, an agent-native knowledge vault (github.com/shrvn-r/hafez):
 From then on, just mention your projects by name in any session — the skill
 teaches the agent when to read and write the vault, no commands required.
 
+Upgrading from an earlier name of this tool? Remove the old skill directory
+under `~/.claude/skills/` — two installed skills with near-identical
+triggers compete for the same invocations.
+
 ### Manual setup
 
 The same thing by hand:
 
 ```bash
 # Install (Node.js 22+ and git required).
-# On npm 12+, append: --allow-scripts=better-sqlite3
+# On npm 11+, append: --allow-scripts=better-sqlite3
 npm install -g hafez
 
 # One-time, if you've never used git on this machine:
@@ -133,7 +140,7 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `hafez promote <slug> <entity\|project\|knowledge>` | Promote a capture upward |
 | `hafez update <slug> [flags]` | Status, brief, actions, session log, synthesis, evidence… |
 | `hafez link / unlink <slug> <target> --relation <parent\|related>` | Manage relationships |
-| `hafez batch [--dry-run]` | JSON ops on stdin → atomic multi-op, single git commit, rollback on failure |
+| `hafez batch [--dry-run] [--file payload.json]` | JSON ops (stdin or `--file`) → atomic multi-op, single git commit, rollback on failure; dry-run runs the same validation as apply and reports derived slugs |
 | `hafez stats` | Vault summary: counts, stale items, recents |
 | `hafez changelog --since 7.days.ago` | Git-derived change history |
 | `hafez sync` | Pull remote, push local commits (semantic merge on conflicts) |
@@ -181,7 +188,7 @@ for everything on the [AGENTS.md standard](https://agents.md) (Codex, Cursor,
 Copilot, …). This repo follows the same convention: `AGENTS.md` is canonical
 and `CLAUDE.md` imports it.
 
-- **`hafez onboard`** — an agent-directed first-run guide: a seeding interview for the empty vault, then a choice of integration level (an always-active block for the harness's global instructions file, or invoke-only).
+- **`hafez onboard`** — an agent-directed first-run guide: a seeding interview for the empty vault, then a choice of integration level (an always-active block for the harness's global instructions file, or invoke-only). Re-running it later is the intended way to seed newly started work — on a set-up vault it's just the interview.
 - **`hafez help --agent`** — a complete API reference designed to be loaded into an agent's context.
 - **Claude Code skill** — an optional adapter for one harness: the package bundles a skill (installed in [Setup](#setup)) covering the full session lifecycle: loading context at session start, vault ops mid-session, and a session-end digest.
 - **`hafez schema <op> --examples`** — JSON schemas with working examples for every batch operation, so agents can self-correct.

package/dist/batch-ops.d.ts

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+import type { BatchOperation, CreateEntityFields, CreateKnowledgeFields, SessionLogEntry, UpdateFields } from './types.js';
+export declare const SessionLogSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    summary: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    agent: z.ZodString;
+}, z.core.$strict>;
+export declare const UpdateFieldsSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    current_state: z.ZodOptional<z.ZodString>;
+    session_log: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        summary: z.ZodString;
+        body: z.ZodOptional<z.ZodString>;
+        agent: z.ZodString;
+    }, z.core.$strict>>;
+    brief: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    add_action: z.ZodOptional<z.ZodString>;
+    add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    complete_action: z.ZodOptional<z.ZodString>;
+    remove_action: z.ZodOptional<z.ZodString>;
+    clear_actions: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    synthesis: z.ZodOptional<z.ZodString>;
+    insight: z.ZodOptional<z.ZodString>;
+    add_evidence: z.ZodOptional<z.ZodString>;
+    add_source: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const CreateEntityFieldsSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    purpose: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    parent: z.ZodOptional<z.ZodString>;
+    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    brief: z.ZodOptional<z.ZodString>;
+    add_action: z.ZodOptional<z.ZodString>;
+    add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const CreateKnowledgeFieldsSchema: z.ZodObject<{
+    subtype: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    synthesis: z.ZodOptional<z.ZodString>;
+    insight: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    'session-date': z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const CreateSessionFieldsSchema: z.ZodObject<{
+    synthesis: z.ZodOptional<z.ZodString>;
+    insight: z.ZodOptional<z.ZodString>;
+    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    'session-date': z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** What `digest` may put in a session-create op — typechecked against the
+ * schema so the two can never silently diverge again. */
+export type CreateSessionFieldsInput = z.infer<typeof CreateSessionFieldsSchema>;
+export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"update">;
+    slug: z.ZodString;
+    fields: z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        current_state: z.ZodOptional<z.ZodString>;
+        session_log: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<{
+                [x: string]: string;
+            }>;
+            summary: z.ZodString;
+            body: z.ZodOptional<z.ZodString>;
+            agent: z.ZodString;
+        }, z.core.$strict>>;
+        brief: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        add_action: z.ZodOptional<z.ZodString>;
+        add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        complete_action: z.ZodOptional<z.ZodString>;
+        remove_action: z.ZodOptional<z.ZodString>;
+        clear_actions: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        confidence: z.ZodOptional<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        synthesis: z.ZodOptional<z.ZodString>;
+        insight: z.ZodOptional<z.ZodString>;
+        add_evidence: z.ZodOptional<z.ZodString>;
+        add_source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"create">;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"capture">;
+    name: z.ZodString;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"link">;
+    slug: z.ZodString;
+    target: z.ZodString;
+    relation: z.ZodEnum<{
+        parent: "parent";
+        related: "related";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"unlink">;
+    slug: z.ZodString;
+    target: z.ZodString;
+    relation: z.ZodEnum<{
+        parent: "parent";
+        related: "related";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"promote">;
+    slug: z.ZodString;
+    target: z.ZodEnum<{
+        entity: "entity";
+        project: "project";
+        knowledge: "knowledge";
+    }>;
+}, z.core.$strict>], "op">;
+/** Vault context handed to each spec's semantic check by validateBatchCore.
+ * Simulation-aware: creates earlier in the batch count as existing. */
+export interface OpCheckContext {
+    resolve(slug: string): {
+        kind: 'entity' | 'knowledge';
+        type: string;
+    } | null;
+    existsAnywhere(slug: string): boolean;
+    sessionExists(slug: string): boolean;
+    simulate(slug: string, info: {
+        kind: 'entity' | 'knowledge';
+        type: string;
+    }): void;
+    simulateSession(slug: string): void;
+    validateKindFields(kind: 'entity' | 'knowledge', fields: UpdateFields): void;
+    validateSessionLogEntry(entry: SessionLogEntry): string[];
+    buildEntityFrontmatter(name: string, fields: CreateEntityFields): void;
+    buildKnowledgeFrontmatter(name: string, fields: CreateKnowledgeFields): void;
+}
+export interface OpCheckResult {
+    slug: string;
+    errors: string[];
+    created?: boolean;
+    warning?: string;
+}
+export interface OpSpec {
+    /** Stable identifier used by `schema <name>` and the op catalog. */
+    name: string;
+    op: BatchOperation['op'];
+    kind?: 'entity' | 'knowledge' | 'session';
+    schema: z.ZodType;
+    description: string;
+    /** Optional fields force-included in the generated example payload. */
+    exampleInclude: string[];
+    check(op: any, ctx: OpCheckContext): OpCheckResult;
+}
+export declare const OP_SPECS: OpSpec[];
+/** Find the spec for a (shape-valid) operation. */
+export declare function specFor(op: BatchOperation): OpSpec;
+/** Op names for error text ("expected one of […]") — derived, never hardcoded. */
+export declare function validOpNames(): string[];
+/** Create kinds for error text — derived from the table. */
+export declare function validCreateKinds(): string[];

package/dist/batch-ops.js

@@ -0,0 +1,322 @@
+// src/batch-ops.ts
+// The Op Spec (see CONTEXT.md): one table defining every batch operation —
+// shape (Zod), semantic check, description, and example hints — from which
+// validation, error text, and schema introspection all derive. Adding an op
+// means adding one entry here.
+import { z } from 'zod';
+import { ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, getContract, } from './contracts.js';
+import { slugify } from './vault.js';
+import { HafezError } from './types.js';
+// --- Shapes ---
+// All enums are built from contracts.ts tuples so help-renderer, file validators,
+// and CLI-input validator share a single source of truth.
+// Every z.object(...) is .strict() — unknown keys become `unrecognized_keys` issues
+// (not silently dropped), which is load-bearing for the error-formatter's did-you-mean
+// hints and for catching typos like `{"kind": "parent"}` on a link op.
+export const SessionLogSchema = z.object({
+    type: z.enum([...SESSION_LOG_TYPES]),
+    summary: z.string(),
+    body: z.string().optional(),
+    agent: z.string(),
+}).strict();
+export const UpdateFieldsSchema = z.object({
+    status: z.enum([...ENTITY_STATUSES]).optional(),
+    current_state: z.string().optional(),
+    session_log: SessionLogSchema.optional(),
+    brief: z.string().nullable().optional(),
+    add_action: z.string().optional(),
+    add_actions: z.array(z.string()).optional(),
+    complete_action: z.string().optional(),
+    remove_action: z.string().optional(),
+    clear_actions: z.boolean().optional(),
+    // Knowledge metadata
+    description: z.string().nullable().optional(),
+    resource: z.string().nullable().optional(),
+    domain: z.array(z.string()).optional(),
+    confidence: z.enum([...CONFIDENCE_LEVELS]).optional(),
+    tags: z.array(z.string()).optional(),
+    related: z.array(z.string()).optional(),
+    synthesis: z.string().optional(),
+    insight: z.string().optional(), // alias for synthesis (normalized in parseBatchInput)
+    add_evidence: z.string().optional(),
+    add_source: z.string().optional(),
+}).strict();
+export const CreateEntityFieldsSchema = z.object({
+    type: z.enum([...ENTITY_TYPES]),
+    purpose: z.string().optional(),
+    description: z.string().optional(),
+    resource: z.string().optional(),
+    domain: z.array(z.string()).optional(),
+    parent: z.string().optional(),
+    related: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+    brief: z.string().optional(),
+    add_action: z.string().optional(),
+    add_actions: z.array(z.string()).optional(),
+}).strict();
+export const CreateKnowledgeFieldsSchema = z.object({
+    subtype: z.enum([...VALID_SUBTYPES]).optional(),
+    synthesis: z.string().optional(),
+    insight: z.string().optional(),
+    description: z.string().optional(),
+    domain: z.array(z.string()).optional(),
+    related: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+    'session-date': z.string().optional(),
+}).strict();
+export const CreateSessionFieldsSchema = z.object({
+    synthesis: z.string().optional(),
+    insight: z.string().optional(),
+    related: z.array(z.string()).optional(),
+    'session-date': z.string().optional(),
+}).strict();
+const CreateEntityBranch = z.object({
+    op: z.literal('create'),
+    kind: z.literal('entity'),
+    name: z.string(),
+    fields: CreateEntityFieldsSchema,
+}).strict();
+const CreateKnowledgeBranch = z.object({
+    op: z.literal('create'),
+    kind: z.literal('knowledge'),
+    name: z.string(),
+    fields: CreateKnowledgeFieldsSchema.optional(),
+}).strict();
+const CreateSessionBranch = z.object({
+    op: z.literal('create'),
+    kind: z.literal('session'),
+    name: z.string(),
+    fields: CreateSessionFieldsSchema.optional(),
+}).strict();
+const UpdateBranch = z.object({
+    op: z.literal('update'),
+    slug: z.string(),
+    fields: UpdateFieldsSchema,
+}).strict();
+const CaptureBranch = z.object({
+    op: z.literal('capture'),
+    name: z.string(),
+    notes: z.string().optional(),
+}).strict();
+const LinkBranch = z.object({
+    op: z.literal('link'),
+    slug: z.string(),
+    target: z.string(),
+    relation: z.enum(['parent', 'related']),
+}).strict();
+const UnlinkBranch = z.object({
+    op: z.literal('unlink'),
+    slug: z.string(),
+    target: z.string(),
+    relation: z.enum(['parent', 'related']),
+}).strict();
+const PromoteBranch = z.object({
+    op: z.literal('promote'),
+    slug: z.string(),
+    target: z.enum(['entity', 'project', 'knowledge']),
+}).strict();
+// Nested discriminated union: outer on `op`, inner on `kind` for create branch.
+// A flat `discriminatedUnion('op', [...])` cannot work because three branches share
+// op=create — Zod requires unique discriminator values per branch and throws at
+// schema construction time if violated.
+const CreateBranch = z.discriminatedUnion('kind', [
+    CreateEntityBranch,
+    CreateKnowledgeBranch,
+    CreateSessionBranch,
+]);
+export const BatchOperationSchema = z.discriminatedUnion('op', [
+    UpdateBranch,
+    // create is a nested discriminatedUnion on `kind` — see CreateBranch above.
+    // discriminatedUnion accepts a ZodDiscriminatedUnion as a branch via option-flattening.
+    CreateBranch,
+    CaptureBranch,
+    LinkBranch,
+    UnlinkBranch,
+    PromoteBranch,
+]);
+function pushErr(errors, err) {
+    const e = err;
+    errors.push(e.details?.length ? `${e.message}: ${e.details.join('; ')}` : e.message);
+}
+export const OP_SPECS = [
+    {
+        name: 'update',
+        op: 'update',
+        schema: UpdateBranch,
+        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …).',
+        exampleInclude: ['status'],
+        check(op, ctx) {
+            const errors = [];
+            const target = ctx.resolve(op.slug);
+            if (!target)
+                errors.push(`'${op.slug}' not found`);
+            else {
+                try {
+                    ctx.validateKindFields(target.kind, op.fields);
+                }
+                catch (err) {
+                    pushErr(errors, err);
+                }
+            }
+            if (op.fields.session_log) {
+                const logErrors = ctx.validateSessionLogEntry(op.fields.session_log);
+                if (logErrors.length > 0)
+                    errors.push(`Invalid session log entry: ${logErrors.join('; ')}`);
+            }
+            if (op.fields.related) {
+                for (const r of op.fields.related) {
+                    if (!ctx.existsAnywhere(r))
+                        errors.push(`Related slug '${r}' does not exist`);
+                }
+            }
+            return { slug: op.slug, errors };
+        },
+    },
+    {
+        name: 'create-entity',
+        op: 'create',
+        kind: 'entity',
+        schema: CreateEntityBranch,
+        description: 'Create a new entity (capture / entity / project).',
+        exampleInclude: ['type'],
+        check(op, ctx) {
+            const errors = [];
+            const slug = slugify(op.name);
+            if (ctx.existsAnywhere(slug))
+                errors.push(`Slug '${slug}' already exists`);
+            try {
+                ctx.buildEntityFrontmatter(op.name, op.fields);
+            }
+            catch (err) {
+                pushErr(errors, err);
+            }
+            ctx.simulate(slug, { kind: 'entity', type: op.fields.type });
+            return { slug, errors, created: errors.length === 0 };
+        },
+    },
+    {
+        name: 'create-knowledge',
+        op: 'create',
+        kind: 'knowledge',
+        schema: CreateKnowledgeBranch,
+        description: 'Create a new knowledge note (insight / plan subtype).',
+        exampleInclude: ['subtype', 'synthesis'],
+        check(op, ctx) {
+            const errors = [];
+            const slug = slugify(op.name);
+            if (ctx.existsAnywhere(slug))
+                errors.push(`Slug '${slug}' already exists`);
+            try {
+                ctx.buildKnowledgeFrontmatter(op.name, (op.fields || {}));
+            }
+            catch (err) {
+                pushErr(errors, err);
+            }
+            ctx.simulate(slug, { kind: 'knowledge', type: 'knowledge' });
+            return { slug, errors, created: errors.length === 0 };
+        },
+    },
+    {
+        name: 'create-session',
+        op: 'create',
+        kind: 'session',
+        schema: CreateSessionBranch,
+        description: 'Create a new session note linked to an entity.',
+        exampleInclude: ['synthesis'],
+        check(op, ctx) {
+            const slug = slugify(op.name);
+            if (ctx.existsAnywhere(slug) || ctx.sessionExists(slug)) {
+                return { slug, errors: [], warning: `session '${slug}' already exists — op will be skipped (batch continues)` };
+            }
+            ctx.simulateSession(slug);
+            return { slug, errors: [], created: true };
+        },
+    },
+    {
+        name: 'capture',
+        op: 'capture',
+        schema: CaptureBranch,
+        description: 'Quick capture — a raw inbox item with no structure required.',
+        exampleInclude: ['notes'],
+        check(op, ctx) {
+            const errors = [];
+            const slug = slugify(op.name);
+            if (ctx.existsAnywhere(slug))
+                errors.push(`Slug '${slug}' already exists`);
+            ctx.simulate(slug, { kind: 'entity', type: 'capture' });
+            return { slug, errors, created: errors.length === 0 };
+        },
+    },
+    {
+        name: 'link',
+        op: 'link',
+        schema: LinkBranch,
+        description: 'Add a parent or related link between two entities.',
+        exampleInclude: [],
+        check(op, ctx) {
+            const errors = [];
+            if (!ctx.resolve(op.slug))
+                errors.push(`'${op.slug}' not found`);
+            if (!ctx.existsAnywhere(op.target))
+                errors.push(`Target '${op.target}' does not exist`);
+            return { slug: op.slug, errors };
+        },
+    },
+    {
+        name: 'unlink',
+        op: 'unlink',
+        schema: UnlinkBranch,
+        description: 'Remove a parent or related link between two entities.',
+        exampleInclude: [],
+        check(op, ctx) {
+            const errors = [];
+            if (!ctx.resolve(op.slug))
+                errors.push(`'${op.slug}' not found`);
+            return { slug: op.slug, errors };
+        },
+    },
+    {
+        name: 'promote',
+        op: 'promote',
+        schema: PromoteBranch,
+        description: 'Promote a capture to entity/project/knowledge, or an entity to project.',
+        exampleInclude: [],
+        check(op, ctx) {
+            const errors = [];
+            const cur = ctx.resolve(op.slug);
+            if (!cur)
+                errors.push(`'${op.slug}' not found`);
+            else {
+                const currentType = cur.kind === 'knowledge' ? 'knowledge' : cur.type;
+                try {
+                    const contract = getContract(currentType);
+                    if (!contract.canPromoteTo.includes(op.target)) {
+                        errors.push(`Cannot promote ${currentType} to ${op.target}. Valid targets: ${contract.canPromoteTo.join(', ') || 'none (terminal type)'}`);
+                    }
+                    else {
+                        ctx.simulate(op.slug, op.target === 'knowledge' ? { kind: 'knowledge', type: 'knowledge' } : { kind: 'entity', type: op.target });
+                    }
+                }
+                catch (err) {
+                    pushErr(errors, err);
+                }
+            }
+            return { slug: op.slug, errors };
+        },
+    },
+];
+/** Find the spec for a (shape-valid) operation. */
+export function specFor(op) {
+    const spec = OP_SPECS.find(s => s.op === op.op && (s.kind === undefined || s.kind === op.kind));
+    if (!spec)
+        throw new HafezError('VALIDATION_FAILED', `Unknown batch op: ${op.op}`);
+    return spec;
+}
+/** Op names for error text ("expected one of […]") — derived, never hardcoded. */
+export function validOpNames() {
+    return [...new Set(OP_SPECS.map(s => s.op))];
+}
+/** Create kinds for error text — derived from the table. */
+export function validCreateKinds() {
+    return OP_SPECS.filter(s => s.op === 'create' && s.kind).map(s => s.kind);
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,15 @@
+/** Bad invocation (unknown flag, missing value, missing positional).
+ * Distinct from crashes: the error adapter maps it to exit 2. */
+export declare class UsageError extends Error {
+}
+export type FlagType = 'string' | 'boolean';
+/** Flag names WITHOUT the leading dashes, e.g. { 'add-action': 'string' }. */
+export type FlagSpec = Record<string, FlagType>;
+export interface ParsedArgs {
+    flags: Record<string, string | boolean | undefined>;
+    positionals: string[];
+}
+export declare function parseArgs(args: string[], spec: FlagSpec, usage: string): ParsedArgs;
+/** Comma-separated list flag → trimmed array (undefined stays undefined). */
+export declare function splitList(value: string | boolean | undefined): string[] | undefined;
+export declare function str(value: string | boolean | undefined): string | undefined;

package/dist/cli/args.js

@@ -0,0 +1,49 @@
+// src/cli/args.ts
+// The one flag parser behind every CLI command. Each command declares its
+// flags; parseArgs enforces the declaration — unknown flags and missing
+// values are UsageErrors instead of silently ignored tokens (the getFlag era
+// needed a documented workaround because values stayed in the positional
+// stream).
+/** Bad invocation (unknown flag, missing value, missing positional).
+ * Distinct from crashes: the error adapter maps it to exit 2. */
+export class UsageError extends Error {
+}
+export function parseArgs(args, spec, usage) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (token.startsWith('--')) {
+            const name = token.slice(2);
+            const type = spec[name];
+            if (!type)
+                throw new UsageError(`Unknown flag --${name}\n${usage}`);
+            if (type === 'boolean') {
+                flags[name] = true;
+                continue;
+            }
+            const value = args[i + 1];
+            // A declared flag in value position means the value was omitted
+            // (`--brief --clear-actions`) — consuming it would both corrupt the
+            // string and silently drop the swallowed flag.
+            if (value === undefined || (value.startsWith('--') && value.slice(2) in spec)) {
+                throw new UsageError(`--${name} requires a value\n${usage}`);
+            }
+            flags[name] = value;
+            i++;
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { flags, positionals };
+}
+/** Comma-separated list flag → trimmed array (undefined stays undefined). */
+export function splitList(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return value.split(',').map(s => s.trim());
+}
+export function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}

package/dist/cli/batch-errors.js

@@ -9,6 +9,7 @@
 // without those, the `unrecognized_keys` and `invalid_union_discriminator`
 // paths are unreachable.
 import { getOpSchema, listOps } from './schema-introspect.js';
+import { validOpNames, validCreateKinds } from '../batch-ops.js';
 // --- did-you-mean (cheap Levenshtein) ---
 export function levenshtein(a, b) {
     if (a === b)
@@ -91,7 +92,8 @@ export function opNameOf(raw) {
         return null;
     if (op === 'create') {
         const kind = raw.kind;
-        if (typeof kind === 'string')
+        const names = new Set(listOps().map(o => o.name));
+        if (typeof kind === 'string' && names.has(`create-${kind}`))
             return `create-${kind}`;
         return 'create';
     }
@@ -126,7 +128,8 @@ function toStr(v) {
         return String(v);
     }
 }
-const VALID_OPS = ['update', 'create', 'capture', 'link', 'unlink', 'promote'];
+// Derived from the Op Spec table — never hardcoded here.
+const VALID_OPS = validOpNames();
 /**
  * Format a single Zod issue into a readable block. Caller supplies the op
  * index and the raw op JSON so the block can reference the right `hafez
@@ -160,7 +163,7 @@ export function formatIssue(issue, opIndex, raw) {
             return [
                 header,
                 `  field: kind`,
-                `  issue: unknown kind ${got} (expected one of [entity, knowledge, session])`,
+                `  issue: unknown kind ${got} (expected one of [${validCreateKinds().join(', ')}])`,
                 `  ${tip}`,
             ].join('\n');
         }