hafez 1.3.0 → 2.0.0

package/dist/surfaces/items.js

@@ -0,0 +1,523 @@
+// src/surfaces/items.ts
+//
+// The typed Item table of the Agent Contract (docs/agent-contract/README.md,
+// ADR 0001). One Item per row of the contract's owner table: each carries its
+// Owner, at most one declared fallback, its Invoke-only behaviour, an evidence
+// pointer, and its own text (placed by a static Surface) or a render function
+// for what the binary computes. Two Items carry neither: the session log on
+// update is behaviour, and `schema` output is the Op Spec's own rendering. Surfaces compose Items in
+// surfaces.ts; nothing instructional is written anywhere else.
+//
+// Edit an Item here, then re-render: `npx tsx scripts/render-surfaces.ts`.
+import { CONFIDENCE_LEVELS, ENTITY_STATUSES, PLAN_STATUSES, SESSION_LOG_TYPES, WRITE_LINE_FIELDS, getContract, statusesFor, footerForm, } from '../contracts.js';
+import { renderActionHandles } from '../document.js';
+import { slugify } from '../vault.js';
+import { ONBOARD_HARNESSES } from '../harness.js';
+const fence = (body) => '```\n' + body + '\n```';
+const oneOf = (values) => `<${values.join('|')}>`;
+/** A value as one shell word: bare when nothing in it is special, otherwise
+ * double-quoted with `\ " $ `` escaped. `always` quotes plain words too. */
+const shellArg = (value, always = false) => !always && /^[\w.,:@/=+-]+$/.test(value) ? value : `"${value.replace(/[\\"$`]/g, '\\$&')}"`;
+// The create line is spelled out here; the update lines are Write Lines.
+function renderNearMatch(input) {
+    if (input.form === 'relate') {
+        return `Optional, it resembles ${input.resembles.join(', ')}: ${updateLine(input.slug, { related: [...input.related, ...input.resembles] })}`;
+    }
+    if (input.form === 'batchWarning') {
+        return `Warning: op[${input.index}] create knowledge ${shellArg(input.name, true)} near-matches ${input.matches.join(', ')}; batch writes it anyway.`;
+    }
+    const { name, flags, evidence, matches } = input;
+    const one = matches.length === 1;
+    const matchLine = (m) => m.subtype === 'plan'
+        ? updateLine(m.slug, { status: oneOf(PLAN_STATUSES) })
+        : updateLine(m.slug, { add_evidence: evidence ?? '<evidence>' });
+    const createLine = [
+        `hafez create knowledge ${shellArg(name, true)}`,
+        ...flags.map(([flag, value]) => value === undefined ? `--${flag}` : `--${flag} ${shellArg(value)}`),
+        '--new',
+    ].join(' ');
+    return [
+        `${shellArg(name, true)} near-matches ${one ? 'an existing knowledge note' : `${matches.length} existing knowledge notes`}. Nothing was written.`,
+        '',
+        one ? 'Use it instead:' : 'Use one of them instead:',
+        ...matches.flatMap(m => [
+            '',
+            `${m.name} (${m.slug})${m.description ? `: ${m.description}` : ''}`,
+            fence(matchLine(m)),
+        ]),
+        '',
+        'A different note after all: create it anyway.',
+        fence(createLine),
+    ].join('\n');
+}
+// --- The Write Line and the read Footer ---
+/** Update fields whose value is free text: their flag quotes it. Every other
+ * value is a slug, Handle, enum or placeholder, written bare. */
+const TEXT_FIELDS = new Set(['brief', 'current_state', 'add_action', 'add_evidence', 'add_source', 'synthesis']);
+/** `hafez update <slug>` with one flag per field, in field order: the batch
+ * field with dashes; the log is type and summary in one value plus `--body`
+ * (its agent is detected, never shown); the action list repeats its flag;
+ * other lists are comma-joined. */
+function updateLine(slug, fields) {
+    const flag = (field, value) => `--${field.replace(/_/g, '-')} ${TEXT_FIELDS.has(field) ? shellArg(value, true) : value}`;
+    const flags = Object.entries(fields).flatMap(([field, value]) => {
+        if (field === 'session_log') {
+            const log = value;
+            return [`--log ${shellArg(`${log.type}: ${log.summary}`, true)}`, ...(log.body ? [`--body ${shellArg(log.body, true)}`] : [])];
+        }
+        if (field === 'add_actions')
+            return value.map(v => flag('add_action', v));
+        return [flag(field, Array.isArray(value) ? value.join(',') : String(value))];
+    });
+    return [`hafez update ${slug}`, ...flags].join(' ');
+}
+/** Each Footer field's placeholder. `undefined` leaves the field out. */
+const PLACEHOLDERS = {
+    session_log: ({ agent }) => ({ type: oneOf(SESSION_LOG_TYPES), summary: '<one line>', body: '<detail>', agent }),
+    complete_action: ({ handle }) => handle,
+    remove_action: () => '<handle>',
+    add_actions: () => ['<text>'],
+    brief: () => '<text>',
+    current_state: () => '<text>',
+    related: () => ['<slug>'],
+    parent: () => '<slug>',
+    add_evidence: () => '<what you saw>',
+    add_source: () => '<url or citation>',
+    synthesis: () => '<the whole insight, rewritten>',
+    confidence: () => oneOf(CONFIDENCE_LEVELS),
+    domain: () => ['<domain>'],
+    status: ({ target }) => oneOf(statusesFor(target)),
+};
+export function footerOp(input) {
+    const form = footerForm(input.target);
+    if (form === 'capture') {
+        return { op: 'promote', slug: input.slug, target: oneOf(getContract('capture').canPromoteTo) };
+    }
+    const fields = {};
+    for (const field of WRITE_LINE_FIELDS[form]) {
+        const value = PLACEHOLDERS[field](input);
+        if (value !== undefined)
+            fields[field] = value;
+    }
+    return { op: 'update', slug: input.slug, fields };
+}
+/** The Footer: a blank line, a rule line, plain prose and one fenced block. */
+function renderFooter(input) {
+    const op = footerOp(input);
+    const [prose, line] = op.op === 'promote'
+        ? ['A capture waits to be sorted. Once you can tell what it is, one command:', `hafez promote ${op.slug} ${op.target}`]
+        : ['Write back with one command. Keep the flags you need, drop the rest:', updateLine(op.slug, op.fields)];
+    return ['', '---', prose, '', fence(line)].join('\n');
+}
+/** A field that is set or, given empty, cleared: `<name> set` / `<name> cleared`. */
+const setOrCleared = (field, name = field.replace(/_/g, ' ')) => f => {
+    const value = f[field];
+    if (value === undefined)
+        return undefined;
+    return value === null || value === '' || (Array.isArray(value) && value.length === 0) ? `${name} cleared` : `${name} set`;
+};
+/** What each update field did, for the success line; `null` for a field that
+ * changes nothing of its own. Keyed by every update field, so a new field
+ * without a phrase fails the build. Key order is the line's order: the
+ * entity Footer's, then the rest. */
+const CHANGE_PHRASES = {
+    session_log: (_f, r) => r.logged ? 'log added' : undefined,
+    clear_actions: f => f.clear_actions ? 'actions cleared' : undefined,
+    complete_action: f => f.complete_action !== undefined ? '1 action ticked' : undefined,
+    remove_action: f => f.remove_action !== undefined ? '1 action removed' : undefined,
+    add_actions: f => {
+        const n = (f.add_action !== undefined ? 1 : 0) + (f.add_actions?.length ?? 0);
+        return n > 0 ? `${n} action${n === 1 ? '' : 's'} added` : undefined;
+    },
+    add_action: null, // counted with add_actions
+    brief: setOrCleared('brief'),
+    current_state: f => f.current_state !== undefined ? 'current state set' : undefined,
+    related: setOrCleared('related'),
+    parent: f => f.parent !== undefined ? `parent set to ${f.parent}` : undefined,
+    status: f => f.status !== undefined ? `status set to ${f.status}` : undefined,
+    description: setOrCleared('description'),
+    resource: setOrCleared('resource'),
+    domain: setOrCleared('domain'),
+    tags: setOrCleared('tags'),
+    confidence: f => f.confidence !== undefined ? `confidence set to ${f.confidence}` : undefined,
+    synthesis: f => f.synthesis !== undefined || f.insight !== undefined ? 'synthesis set' : undefined,
+    insight: null, // the alias of synthesis
+    add_evidence: f => f.add_evidence !== undefined ? 'evidence added' : undefined,
+    add_source: f => f.add_source !== undefined ? 'source added' : undefined,
+    agent: null, // names the log entry's agent
+};
+/** `Updated <slug>: <what changed>.` — one phrase per change, nothing else. */
+function renderUpdateSummary({ slug, fields, result }) {
+    const phrases = Object.values(CHANGE_PHRASES).flatMap(phrase => phrase?.(fields, result) ?? []);
+    return phrases.length > 0 ? `Updated ${slug}: ${phrases.join(', ')}.` : `Updated ${slug}.`;
+}
+/** The suffix a Stale open line carries on `read`: its age, or that it is
+ * undated. A fresh line carries none. */
+function renderStaleMarker({ stale, age_days }) {
+    if (!stale)
+        return '';
+    return age_days === null ? ' · stale, undated' : ` · stale ${age_days}d`;
+}
+/** The line after an update's success while Stale lines remain on the entity. */
+function renderStaleReminder({ handles }) {
+    const n = handles.length;
+    return `${n} stale action${n === 1 ? '' : 's'} ${n === 1 ? 'remains' : 'remain'}: ${handles.join(', ')}. Tick what landed, drop what is dead.`;
+}
+/** The error line stating nothing was written, any detail lines, then the
+ * Footer (which brings its own blank line) or, after a blank line, the miss. */
+function renderUpdateMisuse(input) {
+    const error = /[.!?]$/.test(input.error) ? input.error : `${input.error}.`;
+    return [
+        `Error: ${error} Nothing was written.`,
+        ...(input.details ?? []).map(d => `  - ${d}`),
+        'footer' in input ? ITEMS.writeLine.render(input.footer) : `\n${ITEMS.slugMissRecovery.render(input.miss)}`,
+    ].join('\n');
+}
+const CREATE_TYPES = ['project', 'entity'];
+const RELATIONS = ['parent', 'related'];
+const createEntityLine = (name) => `hafez create entity "${name}" --type ${oneOf(CREATE_TYPES)} --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"`;
+const CREATE_LINES = fence([
+    createEntityLine('<name>'),
+    `hafez create knowledge "<name>" --synthesis "<the insight>" --confidence ${oneOf(CONFIDENCE_LEVELS)} --related <slug>`,
+].join('\n'));
+/** Step 3 of the onboard script: the exact entries that let `hafez` run and
+ * write the vault without a prompt. Claude Code runs it from an allow entry;
+ * Codex from a command rule, with the vault a writable root of the sandbox. */
+function renderHarnessPermissions({ harness, vault }) {
+    const lead = 'A permission prompt on a hafez command means setup is unfinished.';
+    if (harness === 'claude-code') {
+        const { hooks, allowEntry } = ONBOARD_HARNESSES[harness];
+        return `${lead} Show the user this entry, then add it to ~/${hooks} under permissions.allow:\n\n${JSON.stringify(allowEntry)}`;
+    }
+    const { rules, rule, config } = ONBOARD_HARNESSES[harness];
+    return [
+        `${lead} Show the user these two entries, then add the first to ~/${rules}:`,
+        '',
+        rule,
+        '',
+        `and the second to ~/${config} under [sandbox_workspace_write], merged into any writable_roots already there:`,
+        '',
+        `writable_roots = [${JSON.stringify(vault)}]`,
+    ].join('\n');
+}
+const TEACHING_LINE_2 = {
+    'always-on': '2. Hafez is always on: the agent loads your work at the start of a session and writes to the vault as work lands.',
+    'invoke-only': '2. Hafez is invoke-only: nothing is loaded and nothing is written unless you ask. Say "read <name>" to load, "note this" to write.',
+};
+/** The four lines said to the user at hand-over, or line 2 alone. Line 1
+ * carries the save keystroke of the Harness `onboard` ran in; line 2 is the
+ * Mode. */
+function renderTeachingLines({ harness, mode, line2Only = false }) {
+    if (line2Only)
+        return TEACHING_LINE_2[mode];
+    return [
+        `1. Nothing saves itself. Run ${ONBOARD_HARNESSES[harness].keystroke} before you end a session.`,
+        TEACHING_LINE_2[mode],
+        '3. The agent writes without asking and tells you in one line. Every write is a git commit, so any of them can be undone.',
+        '4. If a hafez command ever asks for permission, setup is unfinished: run `hafez onboard` again.',
+    ].join('\n');
+}
+const BATCH_EXAMPLE_OP = '{"op":"create","kind":"entity","name":"Token Rotation","fields":{"type":"entity"}}';
+export const ITEMS = {
+    loadTriggers: {
+        label: 'Load triggers: read the best guess, create when there is no entity, load nothing when nothing is named',
+        owner: 'block',
+        invokeOnly: 'absent',
+        evidence: 'L1, M1',
+        text: 'At the start of a session, if the first message or the working folder names a piece of work, run `hafez read <slug>` on your best guess at the slug before anything else. A miss prints the closest slugs: read the one that fits. The work has no entity: create one with the line below. Nothing is named: load nothing.',
+    },
+    slugMissRecovery: {
+        label: 'Slug miss recovery',
+        owner: 'readMiss',
+        invokeOnly: 'same',
+        evidence: 'L1; Codex corpus, 6 of 13 reads missed, none recovered',
+        // The closest slugs read-ready, else the search line; then the create
+        // line, named by the miss's slug words so it creates the slug it missed.
+        render: ({ slug, closest }) => {
+            const name = slugify(slug).replace(/-/g, ' ');
+            const miss = `Error: no entity or knowledge note '${slug}'.`;
+            // No word to search for or name a note by: the miss line alone.
+            if (!name)
+                return miss;
+            return [
+                miss,
+                ...(closest.length > 0 ? closest.map(s => `hafez read ${s}`) : [`hafez search "${name}"`]),
+                ITEMS.createLines.render(name),
+            ].join('\n');
+        },
+    },
+    parentDescription: {
+        label: 'Parent description',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: 'L2',
+        /** The `parent:` line's value: the slug, with the parent's description
+         * in brackets when it has one. */
+        render: ({ slug, description }) => description ? `${slug} (${description})` : slug,
+    },
+    writeTriggers: {
+        label: 'Write triggers: work landed, insight, weighing, "note this"',
+        owner: 'block',
+        invokeOnly: 'absent',
+        evidence: 'M11, M2, never-ask decision #42',
+        text: place => [
+            '- Work landed (a commit, a merged PR, CI green): update the entity you read. The end of its `read` output shows the command.',
+            `- An insight emerged that is useful beyond this repo: create a knowledge note. ${place('knowledgeBoundary')}`,
+            '- The user says "note this" or "record that": write it.',
+            `- You are weighing whether something is worth writing: write it, as knowledge with \`--confidence ${CONFIDENCE_LEVELS[0]}\`.`,
+        ].join('\n'),
+    },
+    knowledgeBoundary: {
+        label: 'Knowledge boundary',
+        owner: 'block',
+        invokeOnly: 'absent',
+        evidence: 'M3',
+        text: "An insight about this repo's code alone goes in the repo's own docs instead.",
+    },
+    neverAsk: {
+        label: 'Never ask; the tell line',
+        owner: 'block',
+        fallback: 'hafezSkillBody',
+        invokeOnly: 'via the skill body',
+        evidence: 'audit §3',
+        text: (_place, at) => 'Never ask the user whether to write to the vault. Write, then say so in one line naming the slug and what you did.'
+            + (at === 'owner' ? ' Every write is a git commit and can be undone.' : ''),
+    },
+    readBeforeWrite: {
+        label: 'Read before write-back',
+        owner: 'block',
+        fallback: 'hafezSkillBody',
+        invokeOnly: 'via the skill body',
+        evidence: 'makes the footer sufficient',
+        text: 'Update only what you have read this session. Not read yet: read it first.',
+    },
+    oneCommand: {
+        label: 'One command per write',
+        owner: 'block',
+        invokeOnly: 'absent',
+        evidence: 'M8',
+        text: 'One command per write.',
+    },
+    openActions: {
+        label: 'Open actions are the agent\'s; stale lines are due',
+        owner: 'block',
+        fallback: 'hafezSkillBody',
+        invokeOnly: 'via the skill body and the write reminder',
+        evidence: 'M11',
+        text: 'Open actions on an entity you read are yours: tick what landed, drop what is dead. Lines `read` marks stale are due.',
+    },
+    neverEditByHand: {
+        label: 'Never edit vault files by hand',
+        owner: 'block',
+        invokeOnly: 'absent',
+        evidence: 'help decision #49',
+        text: 'Never edit vault files by hand.',
+    },
+    neverSaveUnprompted: {
+        label: 'Never save unprompted',
+        owner: 'block',
+        invokeOnly: 'not applicable',
+        evidence: 'D1, D8',
+        text: 'Never save the session unprompted. The user saves with the `hafez-save` skill.',
+    },
+    createLines: {
+        label: 'Create lines, their enums, plan, capture',
+        owner: 'block',
+        fallback: 'hafezSkillBody',
+        invokeOnly: 'via the skill body',
+        evidence: 'fields: kind/name 18, synthesis 16, subtype 15',
+        text: CREATE_LINES + '\n\nA plan is `--subtype plan` without `--synthesis`. Cannot tell entity from knowledge: `hafez capture "<name>"`.',
+        /** The entity create line for one name: what the `read` miss places. */
+        render: createEntityLine,
+    },
+    writeLine: {
+        label: 'Update field vocabulary, log type enum, the Write Line',
+        owner: 'readFooter',
+        fallback: 'updateMisuse',
+        invokeOnly: 'same',
+        evidence: 'fields: session_log 26, add_actions 27, complete_action 19, current_state 19, brief 14, related 14, remove_action 8',
+        render: renderFooter,
+    },
+    handles: {
+        label: 'Handles',
+        owner: 'read',
+        invokeOnly: 'same',
+        evidence: 'M11: 131 ticks, 28 matched a line the agent had read',
+        render: renderActionHandles,
+    },
+    staleMarker: {
+        label: 'Stale marker',
+        owner: 'read',
+        invokeOnly: 'same',
+        evidence: 'M11',
+        render: renderStaleMarker,
+    },
+    staleReminder: {
+        label: 'Stale reminder',
+        owner: 'updateSuccess',
+        invokeOnly: 'same',
+        evidence: 'M11',
+        render: renderStaleReminder,
+    },
+    updateSummary: {
+        label: 'What an update changed, in one line: the tell line',
+        owner: 'updateSuccess',
+        invokeOnly: 'same',
+        evidence: 'never-ask decision #42: one tell line per write',
+        render: renderUpdateSummary,
+    },
+    updateMisuse: {
+        label: 'The corrected shape after a misuse: nothing written, then the Footer',
+        owner: 'updateMisuse',
+        invokeOnly: 'same',
+        evidence: '19 of 84 writes errored after reading the reference',
+        render: renderUpdateMisuse,
+    },
+    sessionLogOnUpdate: {
+        label: 'Session log on update',
+        owner: 'mechanised',
+        invokeOnly: 'same',
+        evidence: 'M7',
+    },
+    nearMatch: {
+        label: 'Near-match on create knowledge',
+        owner: 'createKnowledge',
+        invokeOnly: 'same',
+        evidence: 'M4',
+        render: renderNearMatch,
+    },
+    saveTrigger: {
+        label: 'Save trigger',
+        owner: 'hafezSaveDescription',
+        invokeOnly: 'same',
+        evidence: 'D1; 111 digest calls, 7 errors when invoked',
+        text: 'Save this session to the Hafez vault. Use when the user invokes hafez-save or says "save", "save the session" or "wrap up". Never run it unprompted.',
+    },
+    saveMechanics: {
+        label: 'Save mechanics: shape, date, known slugs, no-pipe form',
+        owner: 'hafezSaveBody',
+        invokeOnly: 'same',
+        evidence: 'fields: digest keys 14 each; D2, D3, D4; harness research; #135',
+        text: [
+            '1. List the slugs you read, updated or created this session. Use only those; a slug you did not see in `hafez` output this session does not go in. No slugs: tell the user there is nothing to save and stop.',
+            '2. Run this once, with today\'s date:',
+            '',
+            fence([
+                "hafez digest --data '{",
+                '  "entities_touched": ["<slug>", "<slug>"],',
+                '  "decisions": ["<a decision made this session>"],',
+                '  "narrative": "<one to three sentences: what happened and how it connects>",',
+                '  "session_date": "<YYYY-MM-DD>"',
+                "}' | hafez batch",
+            ].join('\n')),
+            '',
+            'In the JSON, write each apostrophe as `’` (`isn’t`): a straight `\'` ends the quoted argument and the save fails.',
+            '',
+            'No pipe (PowerShell 5.1): put the JSON in `summary.json`, then `hafez digest --file summary.json > ops.json`, then `hafez batch --file ops.json`.',
+            '',
+            '3. Tell the user in one line: the session note\'s slug and the entities it logged to.',
+            '',
+            '`decisions` may be an empty array. Each slug in `entities_touched` gets a session log entry and the session note links them all. An unknown slug fails the save and names the slug: fix the list and run it again. A session already saved is skipped, so a second run does no harm.',
+        ].join('\n'),
+    },
+    unknownSlugAtSave: {
+        label: 'Unknown slug at save',
+        owner: 'digestError',
+        invokeOnly: 'same',
+        evidence: 'D2',
+        render: (slugs) => `Unknown slug${slugs.length === 1 ? '' : 's'} in entities_touched: ${slugs.map(s => `'${s}'`).join(', ')}. Nothing was saved: fix the list and run the save again.`,
+    },
+    find: {
+        label: 'Find: query, search, stats',
+        owner: 'hafezSkillBody',
+        invokeOnly: 'same',
+        evidence: 'help decision #49',
+        text: fence([
+            `hafez query --filter ${oneOf([...ENTITY_STATUSES, 'stale', 'capture'])}`,
+            'hafez search "<terms>" --kind <entity|knowledge>',
+            'hafez stats',
+        ].join('\n')),
+    },
+    rareOps: {
+        label: 'Rare ops: promote, link, unlink, status, delete, validate',
+        owner: 'hafezSkillBody',
+        invokeOnly: 'same',
+        evidence: 'help decision #49; owner decision #43',
+        text: fence([
+            `hafez promote <slug> ${oneOf(getContract('capture').canPromoteTo)}`,
+            `hafez link <slug> <target> --relation ${oneOf(RELATIONS)}`,
+            `hafez unlink <slug> <target> --relation ${oneOf(RELATIONS)}`,
+            `hafez update <slug> --status ${oneOf(ENTITY_STATUSES)}`,
+            'hafez delete <slug>',
+            'hafez validate',
+        ].join('\n'))
+            + `\n\nA plan's status is \`${PLAN_STATUSES.join('|')}\`. \`delete\` removes a knowledge or session note only; an entity is retired with \`--status done\`.`,
+    },
+    batchShape: {
+        label: 'Batch shape',
+        owner: 'hafezSkillBody',
+        fallback: 'batchMisuse',
+        invokeOnly: 'same',
+        evidence: 'M8; batch-examples needed by 73 write events; #145',
+        // The fallback is the `batch` misuse error's tail: the shape alone, one op.
+        text: (_place, at) => at === 'owner'
+            ? [
+                'Several writes that must land together go in one batch: a bare array, no wrapper. A slug is the name lowercased, apostrophes dropped, each other run of characters that are not letters or digits turned into one `-` and none left at either end, so a later op can name what an earlier one creates.',
+                '',
+                fence([
+                    "hafez batch --data '[",
+                    `  ${BATCH_EXAMPLE_OP},`,
+                    '  {"op":"link","slug":"token-rotation","target":"auth-refactor","relation":"parent"}',
+                    "]'",
+                ].join('\n')),
+                '',
+                'In the JSON, write each apostrophe as `’` (`isn’t`): a straight `\'` ends the quoted argument and the batch fails.',
+                '',
+                'No pipe (PowerShell 5.1): `hafez batch --file ops.json`.',
+            ].join('\n')
+            : `A batch is a bare JSON array of ops, no wrapper:\n\n${fence(`[\n  ${BATCH_EXAMPLE_OP}\n]`)}`,
+    },
+    upgradeReconfigure: {
+        label: 'Upgrade, reconfigure',
+        owner: 'hafezSkillBody',
+        invokeOnly: 'same',
+        evidence: 'help decision #49; onboard decision #58',
+        text: [
+            '- Upgrade: `hafez upgrade`. It checks and prints, it never installs. Show the user the printed steps and run them only after a yes.',
+            '- Set up or reconfigure: `hafez onboard`.',
+        ].join('\n'),
+    },
+    opShape: {
+        label: 'Machine-readable op shape',
+        owner: 'schema',
+        invokeOnly: 'same',
+        evidence: 'help decision #49',
+    },
+    folderMatch: {
+        label: 'The working folder is an entity: its read line, after the Block the hook re-delivers',
+        owner: 'onboard',
+        invokeOnly: 'not offered',
+        evidence: 'L1; onboard decision #58',
+        // Every match, in the order given (active first); the agent picks and reads.
+        render: (matches) => [
+            matches.length === 1
+                ? 'This folder is a Hafez entity. Read it first:'
+                : 'This folder matches several Hafez entities. Read the one that fits first:',
+            ...matches.map(m => `hafez read ${m.slug}${m.description ? ` (${m.description})` : ''}`),
+        ].join('\n'),
+    },
+    harnessPermissions: {
+        label: 'Binary on the harness allowlist; vault path writable',
+        owner: 'onboard',
+        invokeOnly: 'same',
+        evidence: 'never-ask decision #42; onboard decision #58',
+        render: renderHarnessPermissions,
+    },
+    teachingLines: {
+        label: 'The four teaching lines (to the user, not the agent)',
+        owner: 'onboard',
+        invokeOnly: 'same, line 2 differs',
+        evidence: 'onboard decision #58',
+        render: renderTeachingLines,
+    },
+};

package/dist/surfaces/surfaces.d.ts

@@ -0,0 +1,32 @@
+import { type FolderMatch, type Item, type ItemId, type SurfaceId } from './items.js';
+export interface Surface<Id extends string = ItemId> {
+    /** How the owner table names this Surface. */
+    label: string;
+    /** Static Surfaces only: the text, built by placing Items. */
+    compose?: (place: (id: Id) => string) => string;
+}
+export declare const SURFACES: Record<SurfaceId, Surface>;
+export declare const contentHash: (text: string) => string;
+/** An Item's text as a binary Surface places it at run time, in the form its
+ * role there (Owner or fallback) calls for. */
+export declare function placeIn(surfaceId: SurfaceId, id: ItemId): string;
+export declare function renderBlock(): string;
+/** `onboard --block`, what the SessionStart hook prints: the Block, then the
+ * read line for each entity matching the folder. */
+export declare function renderBlockHook(matches: FolderMatch[]): string;
+export declare const renderHafezSkill: () => string;
+/** `help --agent`: the `hafez` skill body, the one text, without the blank
+ * line that parts it from the skill file's frontmatter or the newline that
+ * ends the file (the CLI adds one to every output). */
+export declare const renderAgentHelp: () => string;
+export declare const renderHafezSaveSkill: () => string;
+export declare const OWNER_TABLE_BEGIN = "<!-- owner-table:begin (rendered from src/surfaces/items.ts; edit the Item, then run scripts/render-surfaces.ts) -->";
+export declare const OWNER_TABLE_END = "<!-- owner-table:end -->";
+export declare function renderOwnerTable(): string;
+/** Replace the marked owner-table region of `doc` with a fresh render. */
+export declare function spliceOwnerTable(doc: string): string;
+/** Every problem with the Item table: an Item with no Owner or no evidence
+ * pointer, an Item its Owner or static fallback never places, or one placed more than once in a
+ * Surface or in a Surface that is neither its Owner nor its declared fallback.
+ * Placement is checked for static Surfaces only; binary ones place at run time. */
+export declare function itemProblems(items: Record<string, Item>, surfaces: Record<string, Surface<string>>): string[];