hafez 1.4.0 → 2.0.0

package/dist/cli/format.js

@@ -1,4 +1,6 @@
-export function formatEntityHeader(fm, body) {
+/** `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) {
     const lines = [`# ${fm.name}`];
     if (fm.description)
         lines.push(`> ${fm.description}`);
@@ -11,9 +13,10 @@ export function formatEntityHeader(fm, body) {
         meta.push(`domain: ${fm.domain.join(', ')}`);
     if (meta.length)
         lines.push(meta.join(' | '));
+    // The parent line stands alone: with its description it is a sentence.
+    if (parent)
+        lines.push(`parent: ${parent}`);
     const meta2 = [];
-    if (fm.parent)
-        meta2.push(`parent: ${fm.parent}`);
     if (fm['last-touched'])
         meta2.push(`last-touched: ${fm['last-touched']}`);
     if (fm.created)
@@ -34,18 +37,33 @@ export function formatKnowledgeHeader(fm, body) {
     const lines = [`# ${fm.name}`];
     if (fm.description)
         lines.push(`> ${fm.description}`);
+    // A plan has a lifecycle and no reinforcement: its subtype, status and
+    // dates; an insight its confidence and reinforcement.
+    const plan = fm.subtype === 'plan';
     const meta = [];
-    if (fm.confidence)
+    if (plan)
+        meta.push('subtype: plan');
+    if (plan && fm.status)
+        meta.push(`status: ${fm.status}`);
+    if (!plan && fm.confidence)
         meta.push(`confidence: ${fm.confidence}`);
     if (fm.domain?.length)
         meta.push(`domain: ${Array.isArray(fm.domain) ? fm.domain.join(', ') : fm.domain}`);
     if (meta.length)
         lines.push(meta.join(' | '));
     const meta2 = [];
-    if (fm['reinforcement-count'] != null)
-        meta2.push(`reinforcement-count: ${fm['reinforcement-count']}`);
-    if (fm['last-reinforced'])
-        meta2.push(`last-reinforced: ${fm['last-reinforced']}`);
+    if (plan) {
+        if (fm.created)
+            meta2.push(`created: ${fm.created}`);
+        if (fm['last-touched'])
+            meta2.push(`last-touched: ${fm['last-touched']}`);
+    }
+    else {
+        if (fm['reinforcement-count'] != null)
+            meta2.push(`reinforcement-count: ${fm['reinforcement-count']}`);
+        if (fm['last-reinforced'])
+            meta2.push(`last-reinforced: ${fm['last-reinforced']}`);
+    }
     if (meta2.length)
         lines.push(meta2.join(' | '));
     if (fm.related?.length)
@@ -143,7 +161,7 @@ export function formatChangelog(entries) {
 }
 export function formatValidation(report) {
     const issues = report.broken_slugs.length + report.orphaned_knowledge.length +
-        report.oversized_related.length + report.missing_fields.length;
+        report.missing_fields.length;
     if (issues === 0) {
         return `Vault OK — ${report.total_entities} entities, ${report.total_knowledge} knowledge, 0 issues`;
     }
@@ -157,7 +175,6 @@ export function formatValidation(report) {
     };
     addSection('Broken Slugs', report.broken_slugs.map(i => `${i.slug}: ${i.issue}`));
     addSection('Orphaned Knowledge', report.orphaned_knowledge.map(s => `${s} (no related links, not referenced by any entity)`));
-    addSection('Oversized Related', report.oversized_related.map(i => `${i.slug}: ${i.issue}`));
     addSection('Missing Fields', report.missing_fields.map(i => `${i.slug}: ${i.issue}`));
     return sections.join('\n');
 }

package/dist/cli/index.d.ts

@@ -1,3 +1,5 @@
+import { HafezError, type HafezErrorCode } from '../types.js';
+import { UsageError } from './args.js';
 import type { CommandOpts } from './commands.js';
 type PreVaultRun = (args: string[], ctx: {
     json: boolean;
@@ -13,15 +15,24 @@ export type CommandSpec = {
     run: VaultRun;
 };
 export declare const COMMANDS: Record<string, CommandSpec>;
-/** Exported so a guard test can assert every registered command is documented
- * here — a registered-but-undocumented command is otherwise invisible. */
-export declare const USAGE = "Usage: hafez <command> [args]\n\nCommands:\n  read <slug>                Read entity or knowledge note\n  query [--filter ...] ...   Filter entities/knowledge\n    --kind all               Both kinds; --filter matches entity status only,\n                             so knowledge notes (which have none) always show\n  search <terms>             Full-text search\n  create <kind> <name>       Create entity or knowledge note\n  capture <name> [--notes]   Quick inbox capture\n  promote <slug> <target>    Promote capture\u2192entity/project/knowledge, entity\u2192project\n  update <slug> [--status]   Update an entity or knowledge note\n    --brief \"text\"           Set/replace Brief (use --brief \"\" to clear)\n    --description \"text\"     Set one-line description (use --description \"\" to clear)\n    --resource \"uri\"         Set canonical resource URI, entities only (use --resource \"\" to clear)\n    --add-action \"text\"      Add a next action\n    --complete-action \"text\"  Complete matching action\n    --remove-action \"text\"   Remove matching action\n    --clear-actions          Remove all next actions\n    --synthesis \"text\"       Set/replace Synthesis section (--insight is an alias)\n    --add-evidence \"text\"    Append to Evidence section\n    --add-source \"text\"      Append to Sources section\n  batch                      Apply multiple operations atomically (JSON on stdin)\n  digest                     Apply digest input (JSON stdin) \u2192 batch payload (JSON stdout)\n  export --okf [--out <dir>] Export vault as an OKF v0.1 bundle (read-only)\n  sync                       Pull remote changes and push local commits\n  link <slug> <target> --relation <rel>    Add a link\n  unlink <slug> <target> --relation <rel>  Remove a link\n  stats                      Vault summary: counts, stale items, recents\n  changelog --since <when>   Git-derived change history (e.g. --since 7.days.ago)\n  schema [op] [--examples]   Machine-readable JSON schema for batch operations\n  validate                   Check vault integrity\n  index rebuild              Rebuild the SQLite index\n  init --register <path>     Register an existing vault\n  init                       Show current vault resolution\n  onboard                    Agent-directed first run: seed the vault, pick integration level\n  upgrade                    Check whether hafez is outdated and print the update steps\n  help --agent               Full API reference for agents\n\nGlobal flags:\n  --vault <path>    Vault path (overrides config)\n  --json            JSON output (structured, machine-readable)\n  --version         Print the hafez version\n\nVault discovery: --vault flag > ~/.config/hafez/vault\n";
-/** Exit codes, documented in `hafez help --agent`. 0 = success; 4 is the
+/** The one exit-code table. The error → exit adapter maps HafezError codes
+ * through `errorCodes`; `hafez --help` prints every row. 4 is the
  * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
+export declare const EXIT_TABLE: ReadonlyArray<{
+    exit: number;
+    meaning: string;
+    errorCodes?: readonly HafezErrorCode[];
+}>;
 export declare const EXIT_CODES: Record<string, number>;
+/** Exported so a guard test can assert every registered command is documented
+ * here — a registered-but-undocumented command is otherwise invisible. */
+export declare const USAGE: string;
 /** The pure half of the error → exit adapter: which code an error maps to.
  * Exported so the exit-code contract is testable without spawning the CLI. */
 export declare function exitCodeFor(err: unknown): number;
+/** The text half of the error adapter: what it prints for a usage or vault
+ * error. A misuse ends with the shape to retry from. */
+export declare function errorText(err: UsageError | HafezError): string;
 /** Does this error mean the native module failed to load/build?
  *
  * Matched on the MESSAGE only, and only on the messages a load/ABI failure
@@ -38,5 +49,8 @@ export declare function extractGlobalFlags(args: string[]): {
     vaultFlag?: string;
     json: boolean;
 };
+/** Is this the SessionStart hook's form, `onboard --block`? Read from the raw
+ * args, the token after `--vault` skipped, so it holds when parsing them fails. */
+export declare function isBlockHook(args: string[]): boolean;
 export declare function main(argv: string[]): Promise<void>;
 export {};

package/dist/cli/index.js

@@ -10,7 +10,7 @@ import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { HafezError } from '../types.js';
-import { UsageError } from './args.js';
+import { HelpRequest, MisuseError, RenderedError, UsageError, helpIfAsked } from './args.js';
 /** Bind a vault command to its handler without importing the handler module
  * until the command actually runs. */
 function lazy(pick) {
@@ -18,8 +18,8 @@ function lazy(pick) {
 }
 export const COMMANDS = {
     // --- pre-vault ---
-    help: { phase: 'pre-vault', run: async (args) => (args[0] === '--agent' ? (await import('./help-agent.js')).renderAgentHelp() : USAGE) },
-    onboard: { phase: 'pre-vault', run: async () => (await import('./onboard.js')).renderOnboard() },
+    help: { phase: 'pre-vault', run: async (args) => (args[0] === '--agent' ? (await import('../surfaces/surfaces.js')).renderAgentHelp() : USAGE) },
+    onboard: { phase: 'pre-vault', run: async (args, ctx) => (await import('./onboard.js')).cmdOnboard(args, { vaultFlag: ctx.vaultFlag }) },
     schema: { phase: 'pre-vault', run: async (args) => (await import('./commands-schema.js')).cmdSchema(null, args) },
     version: { phase: 'pre-vault', run: () => versionLine() },
     init: { phase: 'pre-vault', run: async (args, ctx) => { (await import('./resolve-vault.js')).cmdInit(args, ctx.vaultFlag); return null; } },
@@ -38,14 +38,17 @@ export const COMMANDS = {
     link: { phase: 'vault', mutating: true, run: lazy(m => m.cmdLink) },
     unlink: { phase: 'vault', mutating: true, run: lazy(m => m.cmdUnlink) },
     promote: { phase: 'vault', mutating: true, run: lazy(m => m.cmdPromote) },
+    delete: { phase: 'vault', mutating: true, run: lazy(m => m.cmdDelete) },
     batch: { phase: 'vault', mutating: true, run: lazy(m => m.cmdBatch) },
     validate: { phase: 'vault', run: lazy(m => m.cmdValidate) },
     index: {
         phase: 'vault',
         run: async (os, args) => {
+            const usage = 'Usage: hafez index rebuild';
+            helpIfAsked(args, usage);
             if (args[0] === 'rebuild')
                 return (await import('./commands.js')).cmdIndexRebuild(os);
-            throw new UsageError('Usage: hafez index rebuild');
+            throw new UsageError(usage);
         },
     },
     stats: { phase: 'vault', run: lazy(m => m.cmdStats) },
@@ -53,6 +56,20 @@ export const COMMANDS = {
     digest: { phase: 'vault', run: lazy(m => m.cmdDigest) },
     export: { phase: 'vault', run: lazy(m => m.cmdExport) },
 };
+/** The one exit-code table. The error → exit adapter maps HafezError codes
+ * through `errorCodes`; `hafez --help` prints every row. 4 is the
+ * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
+export const EXIT_TABLE = [
+    { exit: 0, meaning: 'success' },
+    { exit: 1, meaning: 'not found (slug, command or vault) / unknown error', errorCodes: ['NOT_FOUND'] },
+    { exit: 2, meaning: 'validation or usage error (bad flags, bad payload, core rejected the write)', errorCodes: ['VALIDATION_FAILED'] },
+    { exit: 3, meaning: 'git push failed — the write IS committed locally', errorCodes: ['GIT_PUSH_FAILED'] },
+    { exit: 4, meaning: 'write succeeded but the auto-sync after it failed' },
+    { 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'] },
+];
+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
  * here — a registered-but-undocumented command is otherwise invisible. */
 export const USAGE = `Usage: hafez <command> [args]
@@ -66,19 +83,20 @@ Commands:
   create <kind> <name>       Create entity or knowledge note
   capture <name> [--notes]   Quick inbox capture
   promote <slug> <target>    Promote capture→entity/project/knowledge, entity→project
+  delete <slug>              Delete a knowledge or session note (an entity: update --status done)
   update <slug> [--status]   Update an entity or knowledge note
     --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 "text"  Complete matching action
-    --remove-action "text"   Remove matching 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
     --clear-actions          Remove all next actions
     --synthesis "text"       Set/replace Synthesis section (--insight is an alias)
     --add-evidence "text"    Append to Evidence section
     --add-source "text"      Append to Sources section
-  batch                      Apply multiple operations atomically (JSON on stdin)
-  digest                     Apply digest input (JSON stdin) → batch payload (JSON stdout)
+  batch                      Apply multiple operations atomically (JSON on stdin, --data or --file)
+  digest                     Apply digest input (JSON on stdin, --data or --file) → batch payload (JSON stdout)
   export --okf [--out <dir>] Export vault as an OKF v0.1 bundle (read-only)
   sync                       Pull remote changes and push local commits
   link <slug> <target> --relation <rel>    Add a link
@@ -90,9 +108,14 @@ Commands:
   index rebuild              Rebuild the SQLite index
   init --register <path>     Register an existing vault
   init                       Show current vault resolution
-  onboard                    Agent-directed first run: seed the vault, pick integration level
+  onboard                    Setup status, then the script your agent follows to set Hafez up
+    --install --mode <always-on|invoke-only> [--harness <h>] [--confirm]
+                             Write both skills and, always-on, the Block
+    --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)
   upgrade                    Check whether hafez is outdated and print the update steps
-  help --agent               Full API reference for agents
+  help --agent               The hafez skill body: the reference when the skill is not installed
 
 Global flags:
   --vault <path>    Vault path (overrides config)
@@ -100,39 +123,45 @@ Global flags:
   --version         Print the hafez version
 
 Vault discovery: --vault flag > ~/.config/hafez/vault
+
+Exit codes:
+${EXIT_TABLE.map(row => `  ${row.exit}  ${row.meaning}`).join('\n')}
 `;
-/** Exit codes, documented in `hafez help --agent`. 0 = success; 4 is the
- * mutate-succeeded-sync-failed warning path; anything unmapped = 1. */
-export const EXIT_CODES = {
-    NOT_FOUND: 1,
-    VALIDATION_FAILED: 2,
-    GIT_PUSH_FAILED: 3,
-    SLUG_EXISTS: 5,
-    GIT_COMMIT_FAILED: 6,
-    VAULT_LOCKED: 7,
-};
 /** The pure half of the error → exit adapter: which code an error maps to.
  * Exported so the exit-code contract is testable without spawning the CLI. */
 export function exitCodeFor(err) {
+    if (err instanceof HelpRequest)
+        return 0;
     if (err instanceof UsageError)
         return 2;
     if (err instanceof HafezError)
         return EXIT_CODES[err.code] ?? 1;
     return 1;
 }
+/** The text half of the error adapter: what it prints for a usage or vault
+ * error. A misuse ends with the shape to retry from. */
+export function errorText(err) {
+    const lines = [`Error: ${err.message}`];
+    if (err instanceof HafezError)
+        for (const detail of err.details ?? [])
+            lines.push(`  - ${detail}`);
+    if (err instanceof MisuseError)
+        lines.push('', err.shape);
+    return lines.join('\n') + '\n';
+}
 /** The one error → exit adapter. Usage errors (bad flags/args) are distinct
  * from vault errors and from unknown crashes. */
 function report(err) {
-    if (err instanceof UsageError) {
-        process.stderr.write(`Error: ${err.message}\n`);
+    if (err instanceof HelpRequest) {
+        process.stdout.write(err.usage + '\n');
         process.exit(exitCodeFor(err));
     }
-    if (err instanceof HafezError) {
-        process.stderr.write(`Error: ${err.message}\n`);
-        if (err.details?.length) {
-            for (const detail of err.details)
-                process.stderr.write(`  - ${detail}\n`);
-        }
+    if (err instanceof RenderedError) {
+        process[err.stream].write(err.output + '\n');
+        process.exit(exitCodeFor(err));
+    }
+    if (err instanceof UsageError || err instanceof HafezError) {
+        process.stderr.write(errorText(err));
         process.exit(exitCodeFor(err));
     }
     failUnknown(err);
@@ -202,7 +231,16 @@ export function extractGlobalFlags(args) {
     }
     return { rest, vaultFlag, json };
 }
+/** Is this the SessionStart hook's form, `onboard --block`? Read from the raw
+ * args, the token after `--vault` skipped, so it holds when parsing them fails. */
+export function isBlockHook(args) {
+    const command = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--vault');
+    return command === 'onboard' && args.includes('--block');
+}
 export async function main(argv) {
+    // The hook must never block a session: under `onboard --block` any failure
+    // at all, a bad flag included, prints nothing and exits 0 (#132).
+    const hook = isBlockHook(argv.slice(2));
     try {
         const { rest: args, vaultFlag, json } = extractGlobalFlags(argv.slice(2));
         const command = args.shift();
@@ -211,9 +249,11 @@ export async function main(argv) {
             return;
         }
         const name = command === '--version' || command === '-v' ? 'version' : command;
-        const spec = COMMANDS[name];
+        const spec = Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : undefined;
         if (!spec) {
-            process.stderr.write(`Unknown command: ${command}\n${USAGE}`);
+            // `list` is the command agents guess for listing the vault (#30).
+            const hint = command === 'list' ? '. To list the vault: hafez query --filter active' : '';
+            process.stderr.write(`Unknown command: ${command}${hint}\n${USAGE}`);
             process.exit(1);
         }
         if (spec.phase === 'pre-vault') {
@@ -256,6 +296,8 @@ export async function main(argv) {
         process.stdout.write(result + '\n');
     }
     catch (err) {
+        if (hook)
+            return;
         report(err);
     }
 }

package/dist/cli/install.d.ts

@@ -0,0 +1,53 @@
+import { type HarnessId } from '../harness.js';
+export declare const MODES: readonly ["always-on", "invoke-only"];
+export type Mode = (typeof MODES)[number];
+export declare const isMode: (value: string) => value is Mode;
+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;
+/** 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;
+export interface InstallState {
+    /** In the Harness's instructions file; null where it keeps no file.
+     * `broken`: markers `--install` and `--remove` refuse until fixed by hand. */
+    block: HashState | 'broken' | null;
+    /** Across both skill directories: the one state every file shares, else
+     * hand-edited when any file is, else stale. */
+    skills: HashState;
+    /** Some skill file carries a hash: `onboard --install` has run here. */
+    onboarded: boolean;
+}
+export declare function installState(home: string, harness: HarnessId): InstallState;
+export declare function install(opts: {
+    home: string;
+    harness: HarnessId;
+    mode: Mode;
+    confirm: boolean;
+}): string;
+export interface SkillCheck {
+    path: string;
+    state: HashState;
+}
+export interface BlockCheck {
+    harness: HarnessId;
+    path: string;
+    /** `broken`: markers `--install` would refuse until fixed by hand. */
+    state: Exclude<HashState, 'absent'> | 'broken';
+    /** The Block Hafez writes has changed since this one was written. */
+    renderChanged: boolean;
+}
+/** 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. */
+export declare function checkInstall(home: string): {
+    skills: SkillCheck[];
+    blocks: BlockCheck[];
+};
+/** Remove everything Hafez wrote: both skills from both directories, and the
+ * Block region from every instructions file a Harness reads. Nothing else. */
+export declare function remove({ home, confirm }: {
+    home: string;
+    confirm: boolean;
+}): string;