hafez 1.4.0 → 2.0.0

package/dist/digest.js

@@ -1,9 +1,13 @@
 // src/digest.ts
+import { createHash } from 'crypto';
 import { z } from 'zod';
+import { HafezError } from './types.js';
+import { detectAgent } from './harness.js';
+import { ITEMS } from './surfaces/items.js';
 // --- Schema ---
 export const DigestInputSchema = z.object({
     entities_touched: z.array(z.string())
-        .describe('Slugs of entities worked on. Each gets a session log entry; the session note links them all. Unknown slugs warn on stderr and are omitted.'),
+        .describe('Slugs of entities worked on. Each gets a session log entry; the session note links them all. An unknown slug fails the digest and is named.'),
     decisions: z.array(z.string())
         .describe('Key decisions made this session (may be empty). Recorded in the session note.')
         .default([]),
@@ -12,8 +16,8 @@ export const DigestInputSchema = z.object({
     session_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD')
         .describe('Session date, YYYY-MM-DD.'),
     agent: z.string()
-        .describe('Agent identifier recorded in session logs.')
-        .default('claude'),
+        .describe('Agent identifier recorded in session logs. Detected from the Harness when absent.')
+        .optional(),
 });
 /**
  * Validate and parse raw digest input from stdin.
@@ -39,27 +43,32 @@ export function parseDigestInput(raw) {
 /**
  * Convert session context into a hafez batch payload.
  * Pure function — no file I/O, no vault access.
- * Unknown slugs in entities_touched are silently omitted (caller should warn).
+ * An unknown slug in entities_touched is a NOT_FOUND naming it (and only the
+ * unknown ones), never a session log that points nowhere. A knowledge slug is
+ * known: the note links it, but a session log is entity-only.
  */
-export function digest(input, existingSlugs, now = new Date()) {
+export function digest(input, entitySlugs, knowledgeSlugs = new Set()) {
+    const touched = [...new Set(input.entities_touched)];
+    const unknown = touched.filter(s => !entitySlugs.has(s) && !knowledgeSlugs.has(s));
+    if (unknown.length > 0)
+        throw new HafezError('NOT_FOUND', ITEMS.unknownSlugAtSave.render(unknown));
     const ops = [];
-    // 1. Session log updates for each known slug
-    const knownTouched = input.entities_touched.filter(s => existingSlugs.has(s));
-    for (const slug of knownTouched) {
+    const agent = input.agent || detectAgent();
+    // 1. Session log updates for each touched entity
+    for (const slug of touched.filter(s => entitySlugs.has(s))) {
         const sessionLogSummary = buildSessionLogSummary(input);
         const fields = {
             session_log: {
                 type: 'progress',
                 summary: sessionLogSummary,
-                agent: input.agent,
+                agent,
             },
         };
         ops.push({ op: 'update', slug, fields });
     }
-    // 2. Session note — built from known slugs only, so unknown slugs never
-    //    leak into the note body (the schema promises they are omitted).
-    const noteBody = buildSessionNoteBody(input, knownTouched);
-    const related = knownTouched;
+    // 2. Session note
+    const noteBody = buildSessionNoteBody(input, touched);
+    const related = touched;
     // Typechecked against the Op Spec's session-create schema so digest output
     // can never silently diverge from what batch validation accepts.
     const noteFields = {
@@ -67,7 +76,9 @@ export function digest(input, existingSlugs, now = new Date()) {
         'session-date': input.session_date,
         ...(related.length > 0 ? { related } : {}),
     };
-    const noteName = `Session ${input.session_date} ${now.toISOString().slice(11, 19)}`;
+    // Named by the session date and its note, so a second save of the same
+    // session derives the same slug and batch skips it as a duplicate.
+    const noteName = `Session ${input.session_date} ${createHash('sha256').update(noteBody).digest('hex').slice(0, 8)}`;
     ops.push({ op: 'create', kind: 'session', name: noteName, fields: noteFields });
     return ops;
 }
@@ -79,7 +90,7 @@ function buildSessionLogSummary(input) {
     }
     return parts.join(' | ');
 }
-function buildSessionNoteBody(input, knownTouched) {
+function buildSessionNoteBody(input, touched) {
     const lines = [input.narrative.trim()];
     if (input.decisions.length > 0) {
         lines.push('');
@@ -88,9 +99,9 @@ function buildSessionNoteBody(input, knownTouched) {
             lines.push(`- ${d}`);
         }
     }
-    if (knownTouched.length > 0) {
+    if (touched.length > 0) {
         lines.push('');
-        lines.push(`**Entities touched:** ${knownTouched.join(', ')}`);
+        lines.push(`**Entities touched:** ${touched.join(', ')}`);
     }
     return lines.join('\n');
 }

package/dist/document.d.ts

@@ -1,4 +1,29 @@
-import type { SessionLogEntry, SessionLogType } from './types.js';
+import { type SessionLogEntry, type SessionLogType } from './types.js';
+/** The action text without its trailing added-date stamp, if any. */
+export declare function stripActionStamp(text: string): string;
+/** The day an action's stamp names; null when the line is undated. */
+export declare function actionAdded(text: string): string | null;
+/** Stamp an action with its added date; text that already ends in a stamp is
+ * returned as is, so a carried-over line is never double-stamped. */
+export declare function stampAction(text: string, day: string): string;
+/** One checkbox line of Next Actions as a reader sees it: unstamped text, and
+ * a Handle and added day (null when undated) when the line is open. */
+export type ActionItem = {
+    handle: string;
+    text: string;
+    added: string | null;
+} | {
+    handle?: undefined;
+    text: string;
+};
+/** The open action a query named: its line's position within the Next
+ * Actions section, and its unstamped text. Editing by position rather than
+ * re-matching the text keeps a Handle-named line unambiguous when its text
+ * is a substring of another line's, or a duplicate of one. */
+export interface ActionMatch {
+    line: number;
+    text: string;
+}
 export declare function parseSessionLogHeading(line: string): {
     date: string;
     agent: string;
@@ -84,16 +109,27 @@ export interface Doc {
     setBrief(body: string, content: string): string;
     removeBrief(body: string): string;
     getNextActions(body: string): string[];
+    getActionItems(body: string): ActionItem[];
+    renderActionHandles(body: string, mark?: (added: string | null) => string): string;
     addNextAction(body: string, action: string): string;
-    completeNextAction(body: string, query: string): {
+    matchNextAction(body: string, query: string): ActionMatch;
+    completeNextAction(body: string, action: string | ActionMatch): {
         matched: string;
         body: string;
     };
-    removeNextAction(body: string, query: string): {
+    removeNextAction(body: string, action: string | ActionMatch): {
         matched: string;
+        line: string;
+        body: string;
+    };
+    actionLines(body: string): string[];
+    extractOldestTickedActions(body: string, keep: number): {
+        lines: string[];
         body: string;
     };
+    pruneNextActions(body: string): string;
     clearNextActions(body: string): string;
+    stripNextActionStamps(body: string): string;
     syncRelatedSection(body: string, frontmatter: {
         parent?: string;
         related?: string[];
@@ -101,6 +137,8 @@ export interface Doc {
 }
 export declare function getBrief(body: string): string | null;
 export declare function getNextActions(body: string): string[];
+export declare function getActionItems(body: string): ActionItem[];
+export declare function renderActionHandles(body: string, mark?: (added: string | null) => string): string;
 export declare function parseSessionLog(body: string): Array<{
     date: string;
     agent: string;

package/dist/document.js

@@ -9,9 +9,65 @@
 // and returns the Document operations bound to it. There is deliberately no
 // global fallback set — a session-only heading like '## Decisions' quoted
 // inside an entity's Brief must NOT terminate that section.
+import { createHash } from 'crypto';
+import { HafezError } from './types.js';
 import { ALL_CONTRACTS, SUBTYPE_SECTIONS, SESSION_SECTIONS, getContract } from './contracts.js';
 import { localDay } from './dates.js';
-const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
+// One checkbox line of Next Actions, tested line by line. `m` so a CRLF
+// line's trailing \r is not taken as action text.
+const OPEN_ACTION_RE = /^- \[ \] (.+)$/m;
+const ACTION_RE = /^- \[([ xX])\] (.+)$/m;
+// --- Next-action added-date stamp ---
+// Adding an action stamps its line `(added YYYY-MM-DD)` with the local day
+// (Apply does the stamping — every add path goes through it). The stamp is
+// file format only: every reader of action text — the index, query, matching,
+// export, merge identity — works on the unstamped text.
+const ACTION_STAMP_RE = /\s*\(added (\d{4}-\d{2}-\d{2})\)\s*$/;
+/** The action text without its trailing added-date stamp, if any. */
+export function stripActionStamp(text) {
+    return text.replace(ACTION_STAMP_RE, '');
+}
+/** The day an action's stamp names; null when the line is undated. */
+export function actionAdded(text) {
+    return ACTION_STAMP_RE.exec(text)?.[1] ?? null;
+}
+/** Stamp an action with its added date; text that already ends in a stamp is
+ * returned as is, so a carried-over line is never double-stamped. */
+export function stampAction(text, day) {
+    return ACTION_STAMP_RE.test(text) ? text : `${text.trimEnd()} (added ${day})`;
+}
+// --- Next-action Handles ---
+// `read` renders a Handle in front of each open action so an agent can tick
+// or drop a line without quoting its text. Derived at read time, never stored.
+const HANDLE_MIN_LENGTH = 4;
+/** A query that may name a line by Handle: lowercase hex, at least the minimum. */
+const HANDLE_QUERY_RE = new RegExp(`^[0-9a-f]{${HANDLE_MIN_LENGTH},}$`);
+/** The full hashes Handles are cut from, one per open action line, in order:
+ * bare hex of the SHA-256 of the normalised, unstamped text. A repeated text
+ * hashes with its occurrence number, so identical lines get distinct hashes. */
+function actionHashes(lines) {
+    const seen = new Map();
+    return lines.map(line => {
+        const text = normalizeForMatch(stripActionStamp(line));
+        const n = seen.get(text) ?? 0;
+        seen.set(text, n + 1);
+        return createHash('sha256').update(n === 0 ? text : `${text}\0${n}`).digest('hex');
+    });
+}
+/** The Handles of a list of open action lines, in order: each line's hash cut
+ * to the shortest prefix (at least four) that no other line's hash shares. */
+function actionHandles(lines) {
+    const hashes = actionHashes(lines);
+    return hashes.map((hash, i) => {
+        let length = HANDLE_MIN_LENGTH;
+        hashes.forEach((other, j) => {
+            // Capped at the full hash: two identical hashes share every prefix.
+            while (j !== i && length < hash.length && other.startsWith(hash.slice(0, length)))
+                length++;
+        });
+        return hash.slice(0, length);
+    });
+}
 // --- Set-independent helpers ---
 const HEADING_RE = /^### (\d{4}-\d{2}-\d{2}) (?:—|--) (.+?)(?:\s+\[(\w+)\])?$/;
 export function parseSessionLogHeading(line) {
@@ -351,31 +407,71 @@ function makeDoc(structuralSections) {
         // After-target not found — fall back to insertBefore logic
         return insertSectionBefore(body, heading, content, beforeFallbacks);
     }
+    /** The Next Actions section's raw lines (from the heading's line end to the
+     * section end) — the line positions an ActionMatch counts in. */
+    function actionSectionLines(body) {
+        const section = findSection(body, 'Next Actions');
+        return section ? body.slice(section.headingEnd, section.end).split('\n') : [];
+    }
+    /** A section line as it leaves the file (archive): without a CRLF line's \r. */
+    function withoutCR(line) {
+        return line.replace(/\r$/, '');
+    }
+    /** Where the action at `lines[i]` ends: past every line it carries (sub-
+     * bullets, notes — anything up to the next checkbox line), trailing blank
+     * lines left out. The item rule merge.ts parses by; whatever moves the
+     * action moves these with it. */
+    function actionEnd(lines, i) {
+        let end = i + 1;
+        for (let j = i + 1; j < lines.length && !ACTION_RE.test(lines[j]); j++) {
+            if (lines[j].trim())
+                end = j + 1;
+        }
+        return end;
+    }
+    /** The action at `lines[i]` and the lines it carries, as they leave the file. */
+    function actionBlock(lines, i) {
+        return lines.slice(i, actionEnd(lines, i)).map(withoutCR).join('\n');
+    }
+    /** Every open line of Next Actions: its position and raw text, stamp included. */
+    function openActions(body) {
+        return actionSectionLines(body).flatMap((l, line) => {
+            const m = OPEN_ACTION_RE.exec(l);
+            return m ? [{ line, raw: m[1] }] : [];
+        });
+    }
     /**
-     * Match an action by case-insensitive substring against unchecked items.
-     * Throws on 0 or >1 matches.
+     * Find the open action a query names. Four or more lowercase hex that
+     * prefix exactly one open line's hash name that line, so a Handle from an
+     * earlier read still works after a sibling changed its rendered length;
+     * prefixing two or more is ambiguous. Anything else is text: a
+     * case-insensitive substring of the unstamped text, the query's own stamp
+     * (copied from a read) ignored. Throws on 0 or >1 matches; error text
+     * lists the unstamped actions.
      */
     function matchAction(body, query) {
-        const section = findSection(body, 'Next Actions');
-        if (!section)
-            throw new Error(`No matching action for "${query}"`);
-        const normalizedQuery = normalizeForMatch(query).toLowerCase();
-        const matches = [];
-        const allActions = [];
-        let m;
-        const re = new RegExp(UNCHECKED_RE.source, 'gm');
-        while ((m = re.exec(section.content)) !== null) {
-            allActions.push(m[1]);
-            if (normalizeForMatch(m[1]).toLowerCase().includes(normalizedQuery)) {
-                matches.push(m[1]);
-            }
+        if (!findSection(body, 'Next Actions'))
+            throw new HafezError('VALIDATION_FAILED', `No matching action for "${query}"`);
+        const open = openActions(body);
+        const toMatch = (a) => ({ line: a.line, text: stripActionStamp(a.raw) });
+        const ambiguous = (matches) => new HafezError('VALIDATION_FAILED', `Ambiguous match for "${query}": ${matches.map(a => stripActionStamp(a.raw)).join(', ')}`);
+        if (HANDLE_QUERY_RE.test(query)) {
+            const hashes = actionHashes(open.map(a => a.raw));
+            const byHandle = open.filter((_, i) => hashes[i].startsWith(query));
+            if (byHandle.length === 1)
+                return toMatch(byHandle[0]);
+            if (byHandle.length > 1)
+                throw ambiguous(byHandle);
         }
+        // A query that is only a stamp keeps it, so it cannot strip to '' and match every line.
+        const normalizedQuery = normalizeForMatch(stripActionStamp(query) || query).toLowerCase();
+        const matches = open.filter(a => normalizeForMatch(stripActionStamp(a.raw)).toLowerCase().includes(normalizedQuery));
         if (matches.length === 0) {
-            throw new Error(`No matching action for "${query}". Actions: ${JSON.stringify(allActions)}`);
+            throw new HafezError('VALIDATION_FAILED', `No matching action for "${query}". Actions: ${JSON.stringify(open.map(a => stripActionStamp(a.raw)))}`);
         }
         if (matches.length > 1)
-            throw new Error(`Ambiguous match for "${query}": ${matches.join(', ')}`);
-        return matches[0];
+            throw ambiguous(matches);
+        return toMatch(matches[0]);
     }
     // --- Brief functions ---
     function getBrief(body) {
@@ -399,16 +495,29 @@ function makeDoc(structuralSections) {
     }
     // --- Next Actions functions ---
     function getNextActions(body) {
-        const section = findSection(body, 'Next Actions');
-        if (!section)
-            return [];
-        const actions = [];
-        let m;
-        const re = new RegExp(UNCHECKED_RE.source, 'gm');
-        while ((m = re.exec(section.content)) !== null) {
-            actions.push(m[1]);
-        }
-        return actions;
+        return openActions(body).map(a => stripActionStamp(a.raw));
+    }
+    /** Every checkbox line of Next Actions in file order, open lines with their Handle. */
+    function getActionItems(body) {
+        const handles = actionHandles(openActions(body).map(a => a.raw));
+        let open = 0;
+        return actionSectionLines(body).flatMap(l => {
+            const m = ACTION_RE.exec(l);
+            if (!m)
+                return [];
+            const text = stripActionStamp(m[2]);
+            return [m[1] === ' ' ? { handle: handles[open++], text, added: actionAdded(m[2]) } : { text }];
+        });
+    }
+    /** The body with each open Next Actions line rendered `- [ ] <handle>  <text>`
+     * plus whatever `mark` gives for its added day — what `read` shows. Ticked
+     * lines and everything outside the section are left as they are. */
+    function renderActionHandles(body, mark = () => '') {
+        const open = openActions(body);
+        if (open.length === 0)
+            return body;
+        const handles = actionHandles(open.map(a => a.raw));
+        return editActionLines(body, lines => open.forEach((a, i) => { lines[a.line] = `- [ ] ${handles[i]}  ${a.raw}${mark(actionAdded(a.raw))}`; }));
     }
     function addNextAction(body, action) {
         const section = findSection(body, 'Next Actions');
@@ -416,7 +525,7 @@ function makeDoc(structuralSections) {
             // Add the new item at the end of unchecked items (before any checked items)
             const lines = section.content.split('\n');
             const lastUncheckedIdx = lines.reduce((last, line, i) => line.startsWith('- [ ] ') ? i : last, -1);
-            const insertIdx = lastUncheckedIdx === -1 ? 0 : lastUncheckedIdx + 1;
+            const insertIdx = lastUncheckedIdx === -1 ? 0 : actionEnd(lines, lastUncheckedIdx);
             lines.splice(insertIdx, 0, `- [ ] ${action}`);
             const newContent = lines.join('\n');
             const before = body.slice(0, section.start).replace(/\n+$/, '');
@@ -429,45 +538,79 @@ function makeDoc(structuralSections) {
         return insertSectionAfter(body, 'Next Actions', `- [ ] ${action}`, 'Brief', ['Session Log']);
     }
     /**
-     * Edit the matched action's line inside the Next Actions section only.
-     * Matching was always section-scoped; editing must be too — an identical
-     * checkbox line quoted elsewhere in the body (a Brief restating a blocker)
-     * is authored content, not an action. Works on the section's raw slice and
-     * on whole lines, so action text is never interpreted as a replacement
-     * pattern ($&, $', $1 survive byte-identical).
+     * Edit the Next Actions section's raw lines, and nothing outside it. An
+     * identical checkbox line quoted elsewhere in the body (a Brief restating
+     * a blocker) is authored content, not an action. Works on whole lines, so
+     * action text is never interpreted as a replacement pattern ($&, $', $1
+     * survive byte-identical).
      */
-    function editActionLine(body, matched, edit) {
+    function editActionLines(body, edit) {
         const section = findSection(body, 'Next Actions');
         if (!section)
             return body;
         const lines = body.slice(section.headingEnd, section.end).split('\n');
-        const idx = lines.indexOf(`- [ ] ${matched}`);
-        if (idx === -1)
-            return body;
-        edit(lines, idx);
+        edit(lines);
         return body.slice(0, section.headingEnd) + lines.join('\n') + body.slice(section.end);
     }
-    function completeNextAction(body, query) {
-        const matched = matchAction(body, query);
-        // Replace the unchecked item with checked
-        const updatedBody = editActionLine(body, matched, (lines, i) => { lines[i] = `- [x] ${matched}`; });
-        // Check if any unchecked items remain
-        const remaining = getNextActions(updatedBody);
-        if (remaining.length === 0) {
-            return { matched, body: clearNextActions(updatedBody) };
-        }
-        return { matched, body: updatedBody };
-    }
-    function removeNextAction(body, query) {
-        const matched = matchAction(body, query);
-        // Remove the line
-        const updatedBody = editActionLine(body, matched, (lines, i) => { lines.splice(i, 1); });
-        // Check if any unchecked items remain
-        const remaining = getNextActions(updatedBody);
-        if (remaining.length === 0) {
-            return { matched, body: clearNextActions(updatedBody) };
-        }
-        return { matched, body: updatedBody };
+    // complete / remove edit one line and nothing else. They do not collapse
+    // an emptied section — that is pruneNextActions, run once by the caller
+    // after every edit of the op, so a tick that empties the open list and an
+    // add in the same op never remove-then-recreate the section (which lost
+    // the checked lines and re-homed the section below Current State).
+    // Each takes a query, or a match resolved earlier against this same body.
+    // `matched` is reported unstamped; the line edited keeps its stamp.
+    function completeNextAction(body, action) {
+        const match = typeof action === 'string' ? matchAction(body, action) : action;
+        return { matched: match.text, body: editActionLines(body, lines => { lines[match.line] = lines[match.line].replace('- [ ] ', '- [x] '); }) };
+    }
+    // `line` is the removed line as the file held it, stamp included, with the
+    // lines it carries — what the archive log keeps.
+    function removeNextAction(body, action) {
+        const match = typeof action === 'string' ? matchAction(body, action) : action;
+        const section = actionSectionLines(body);
+        const end = actionEnd(section, match.line);
+        return { matched: match.text, line: actionBlock(section, match.line), body: editActionLines(body, lines => { lines.splice(match.line, end - match.line); }) };
+    }
+    /** Every checkbox line of Next Actions, open and ticked, as the file holds
+     * them — each with the lines it carries. */
+    function actionLines(body) {
+        const section = actionSectionLines(body);
+        return section.flatMap((l, i) => ACTION_RE.test(l) ? [actionBlock(section, i)] : []);
+    }
+    /** Take the oldest ticked lines out of Next Actions until at most `keep`
+     * remain. Lines are added in order and ticked in place, so file order is
+     * age order. `lines` are the taken lines as the file held them, oldest
+     * first, each with the lines it carries. */
+    function extractOldestTickedActions(body, keep) {
+        const section = actionSectionLines(body);
+        const ticked = section.flatMap((l, i) => ACTION_RE.exec(l)?.[1].trim() ? [i] : []);
+        const oldest = ticked.slice(0, Math.max(0, ticked.length - keep));
+        if (oldest.length === 0)
+            return { lines: [], body };
+        const taken = new Set(oldest.flatMap(i => Array.from({ length: actionEnd(section, i) - i }, (_, k) => i + k)));
+        return {
+            lines: oldest.map(i => actionBlock(section, i)),
+            body: editActionLines(body, lines => { lines.splice(0, lines.length, ...lines.filter((_, i) => !taken.has(i))); }),
+        };
+    }
+    /** The body with the stamp stripped from every checkbox line (open and
+     * ticked) of Next Actions — for surfaces that carry action text but not the
+     * vault's file format (export). Nothing outside the section is touched. */
+    function stripNextActionStamps(body) {
+        const section = findSection(body, 'Next Actions');
+        if (!section)
+            return body;
+        const content = body.slice(section.headingEnd, section.end)
+            .split('\n')
+            .map(line => /^- \[[ xX]\] /.test(line) ? stripActionStamp(line) : line)
+            .join('\n');
+        return body.slice(0, section.headingEnd) + content + body.slice(section.end);
+    }
+    /** Remove the section once no open item remains (appear-on-write, removed when emptied). */
+    function pruneNextActions(body) {
+        if (!findSection(body, 'Next Actions'))
+            return body;
+        return getNextActions(body).length === 0 ? clearNextActions(body) : body;
     }
     function clearNextActions(body) {
         return removeSection(body, 'Next Actions');
@@ -531,10 +674,17 @@ function makeDoc(structuralSections) {
         setBrief,
         removeBrief,
         getNextActions,
+        getActionItems,
+        renderActionHandles,
         addNextAction,
+        matchNextAction: matchAction,
         completeNextAction,
         removeNextAction,
+        actionLines,
+        extractOldestTickedActions,
+        pruneNextActions,
         clearNextActions,
+        stripNextActionStamps,
         syncRelatedSection,
     };
 }
@@ -549,6 +699,12 @@ export function getBrief(body) {
 export function getNextActions(body) {
     return ENTITY_UNION_DOC.getNextActions(body);
 }
+export function getActionItems(body) {
+    return ENTITY_UNION_DOC.getActionItems(body);
+}
+export function renderActionHandles(body, mark) {
+    return ENTITY_UNION_DOC.renderActionHandles(body, mark);
+}
 export function parseSessionLog(body) {
     return ENTITY_UNION_DOC.parseSessionLog(body);
 }

package/dist/export-okf.d.ts

@@ -9,4 +9,17 @@ export interface OkfExportReport {
     }>;
     unresolvedLinks: number;
 }
+/** Frontmatter of an exported OKF document. Not vault frontmatter: `name` maps
+ * to `title`, `type` is normalized per kind, `timestamp` (and `description`,
+ * when the source has none) is derived, `resource` survives only on entities,
+ * and the remaining keys are carried through verbatim. */
+export interface OkfFrontmatter {
+    type: string;
+    title: string;
+    description?: string;
+    resource?: string;
+    tags?: string[];
+    timestamp?: string;
+    [key: string]: unknown;
+}
 export declare function exportOkf(vaultPath: string, outDir: string): OkfExportReport;

package/dist/export-okf.js

@@ -9,9 +9,10 @@ import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, resolve, sep, basename } from 'path';
 import { parseFilePath, serializeFile, scanVaultDir, kindDir } from './vault.js';
 import { DEFAULT_KNOWLEDGE_SUBTYPE } from './contracts.js';
-import { deriveSummary, WIKI_LINK_RE } from './document.js';
+import { deriveSummary, documentFor, WIKI_LINK_RE } from './document.js';
 const SOURCE_KINDS = ['entity', 'knowledge', 'session'];
 const KIND_DIRS = SOURCE_KINDS.map(kind => ({ dir: kindDir(kind), kind }));
+const ENTITY_DOC = documentFor({ kind: 'entity' });
 // The shared wiki-link syntax (document.ts) — group 1 slug, group 2 display.
 const OKF_LINK_RE = new RegExp(WIKI_LINK_RE.source, 'g');
 /** `index.md` is reserved in every bundle directory for the generated index, so
@@ -41,14 +42,14 @@ function assignBundleNames(docs) {
 }
 function mapFrontmatter(doc) {
     const { fm, kind, body } = doc;
-    const mapped = {};
+    let type;
     if (kind === 'entity')
-        mapped.type = fm.type ?? 'entity';
+        type = fm.type ?? 'entity';
     else if (kind === 'knowledge')
-        mapped.type = `knowledge/${fm.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE}`;
+        type = `knowledge/${fm.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE}`;
     else
-        mapped.type = 'session';
-    mapped.title = fm.name;
+        type = 'session';
+    const mapped = { type, title: fm.name };
     const description = deriveSummary(kind, fm, body);
     if (description)
         mapped.description = description;
@@ -151,7 +152,10 @@ export function exportOkf(vaultPath, outDir) {
         const mapped = mapFrontmatter(doc);
         const outSubdir = join(resolvedOut, doc.dir);
         mkdirSync(outSubdir, { recursive: true });
-        writeFileSync(join(outSubdir, `${doc.file}.md`), serializeFile(mapped, transformBody(doc.body)));
+        // The added-date stamp is vault file format, not action text: exported
+        // Next Actions carry the unstamped text.
+        const body = doc.kind === 'entity' ? ENTITY_DOC.stripNextActionStamps(doc.body) : doc.body;
+        writeFileSync(join(outSubdir, `${doc.file}.md`), serializeFile(mapped, transformBody(body)));
         if (doc.kind === 'entity')
             report.entities++;
         else if (doc.kind === 'knowledge')

package/dist/harness.d.ts

@@ -0,0 +1,58 @@
+/** Recorded when no Harness is detectable. */
+export declare const NEUTRAL_AGENT = "agent";
+export declare function detectAgent(env?: Record<string, string | undefined>): string;
+/** Every Harness `onboard` can configure, and where its always-loaded
+ * user-level instructions file lives, relative to the home directory (harness
+ * research, docs/research/2026-09-29-harness-instruction-surfaces.md): the
+ * first candidate that exists, else the last. Cursor keeps its User Rules in a
+ * Settings UI, not a file: `null`, and the Block is printed for manual paste.
+ * `dir` is the config directory whose presence says the Harness is installed. */
+export declare const HARNESSES: {
+    readonly 'claude-code': {
+        readonly label: "Claude Code";
+        readonly dir: ".claude";
+        readonly instructions: readonly [".claude/CLAUDE.md"];
+    };
+    readonly codex: {
+        readonly label: "Codex";
+        readonly dir: ".codex";
+        readonly instructions: readonly [".codex/AGENTS.override.md", ".codex/AGENTS.md"];
+    };
+    readonly cursor: {
+        readonly label: "Cursor";
+        readonly dir: ".cursor";
+        readonly instructions: null;
+    };
+    readonly gemini: {
+        readonly label: "Gemini CLI";
+        readonly dir: ".gemini";
+        readonly instructions: readonly [".gemini/GEMINI.md"];
+    };
+    readonly copilot: {
+        readonly label: "Copilot CLI";
+        readonly dir: ".copilot";
+        readonly instructions: readonly [".copilot/copilot-instructions.md"];
+    };
+};
+export type HarnessId = keyof typeof HARNESSES;
+/** The Harnesses bare `onboard` sets up from inside — the ones detected from
+ * the environment — and, relative to the home directory, where each keeps
+ * what the agent applies: the SessionStart hook and the permission entries.
+ * `keystroke` invokes the `hafez-save` skill there. */
+export declare const ONBOARD_HARNESSES: {
+    readonly 'claude-code': {
+        readonly keystroke: "/hafez-save";
+        readonly hooks: ".claude/settings.json";
+        readonly allowEntry: "Bash(hafez:*)";
+    };
+    readonly codex: {
+        readonly keystroke: "$hafez-save";
+        readonly hooks: ".codex/hooks.json";
+        readonly rules: ".codex/rules/default.rules";
+        readonly rule: "prefix_rule(pattern = [\"hafez\"], decision = \"allow\")";
+        readonly config: ".codex/config.toml";
+    };
+};
+export type OnboardHarness = keyof typeof ONBOARD_HARNESSES;
+export declare const isOnboardHarness: (value: string) => value is OnboardHarness;
+export declare const isHarness: (value: string) => value is HarnessId;