hafez 1.0.1

package/dist/knowledge-index.d.ts

@@ -0,0 +1,3 @@
+/** Ensure every generated local-only artifact is covered by .git/info/exclude. */
+export declare function ensureLocalExclude(vaultPath: string): void;
+export declare function generateVaultIndex(vaultPath: string): void;

package/dist/knowledge-index.js

@@ -0,0 +1,135 @@
+// src/knowledge-index.ts
+// Generates the vault-root index.md covering entities (grouped by status) and
+// knowledge (grouped by domain) — local-only, auto-regenerated on every entity/knowledge write.
+import { readdirSync, readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
+import { join, basename } from 'path';
+import { parseFilePath } from './vault.js';
+import { deriveSummary } from './sections.js';
+import { ENTITY_STATUSES } from './contracts.js';
+function truncate(s) {
+    return s.length > 100 ? s.slice(0, 97) + '...' : s;
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function formatEntry(item) {
+    const desc = item.summary ? ` — ${item.summary}` : '';
+    return `- [[${item.slug}]]${desc} (${item.suffix})`;
+}
+/** Parse every .md directly in dir (non-recursive — auto-excludes archive/), skipping malformed files. */
+function scanParsed(dir) {
+    const docs = [];
+    for (const file of readdirSync(dir).filter(f => f.endsWith('.md'))) {
+        try {
+            const { frontmatter: fm, body } = parseFilePath(join(dir, file));
+            if (!fm.name)
+                continue;
+            docs.push({ slug: basename(file, '.md'), fm, body });
+        }
+        catch {
+            continue;
+        }
+    }
+    return docs;
+}
+/** Local-only artifacts the CLI generates inside the vault. They must never
+ * show up in the user's `git status`, but forcing a tracked .gitignore entry
+ * would dirty their vault — so they go into .git/info/exclude instead. */
+const LOCAL_EXCLUDES = ['/index.md', '/.hafez.db', '/.hafez.db-shm', '/.hafez.db-wal'];
+/** Ensure every generated local-only artifact is covered by .git/info/exclude. */
+export function ensureLocalExclude(vaultPath) {
+    try {
+        const gitDir = join(vaultPath, '.git');
+        if (!existsSync(gitDir) || !statSync(gitDir).isDirectory())
+            return;
+        const excludePath = join(gitDir, 'info', 'exclude');
+        const existing = existsSync(excludePath) ? readFileSync(excludePath, 'utf-8') : '';
+        const lines = new Set(existing.split('\n').map(l => l.trim()));
+        const missing = LOCAL_EXCLUDES.filter(p => !lines.has(p));
+        if (missing.length === 0)
+            return;
+        mkdirSync(join(gitDir, 'info'), { recursive: true });
+        const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+        writeFileSync(excludePath, existing + sep + missing.join('\n') + '\n');
+    }
+    catch { /* best effort — never fail a vault write over ignore hygiene */ }
+}
+export function generateVaultIndex(vaultPath) {
+    const entitiesDir = join(vaultPath, 'entities');
+    const knowledgeDir = join(vaultPath, 'knowledge');
+    const hasEntities = existsSync(entitiesDir);
+    const hasKnowledge = existsSync(knowledgeDir);
+    if (!hasEntities && !hasKnowledge)
+        return;
+    const lines = ['# Vault Index', '', '> Auto-generated by hafez. Do not edit manually.', ''];
+    if (hasEntities) {
+        const byStatus = new Map();
+        for (const { slug, fm, body } of scanParsed(entitiesDir)) {
+            const status = fm.status ?? 'active';
+            const list = byStatus.get(status) ?? [];
+            list.push({ slug, name: fm.name, summary: truncate(deriveSummary('entity', fm, body)), suffix: fm.type ?? 'entity' });
+            byStatus.set(status, list);
+        }
+        if (byStatus.size > 0) {
+            // Known statuses in canonical order, then any non-standard values (hand-edited
+            // files reach here unvalidated) so no live entity silently vanishes.
+            const known = ENTITY_STATUSES;
+            const extra = [...byStatus.keys()].filter(s => !known.includes(s)).sort();
+            lines.push('## Entities', '');
+            for (const status of [...known, ...extra]) {
+                const items = byStatus.get(status);
+                if (!items)
+                    continue;
+                lines.push(`### ${capitalize(status)}`);
+                for (const item of items.sort((a, b) => a.name.localeCompare(b.name))) {
+                    lines.push(formatEntry(item));
+                }
+                lines.push('');
+            }
+        }
+    }
+    if (hasKnowledge) {
+        const entries = [];
+        for (const { slug, fm, body } of scanParsed(knowledgeDir)) {
+            entries.push({
+                slug,
+                name: fm.name,
+                domains: Array.isArray(fm.domain) ? fm.domain : fm.domain ? [fm.domain] : [],
+                summary: truncate(deriveSummary('knowledge', fm, body)),
+                suffix: fm.confidence ?? 'observation',
+            });
+        }
+        const groups = new Map();
+        for (const entry of entries) {
+            if (entry.domains.length === 0) {
+                const list = groups.get('Uncategorized') ?? [];
+                list.push(entry);
+                groups.set('Uncategorized', list);
+            }
+            else {
+                for (const domain of entry.domains) {
+                    const key = capitalize(domain);
+                    const list = groups.get(key) ?? [];
+                    list.push(entry);
+                    groups.set(key, list);
+                }
+            }
+        }
+        const sortedKeys = [...groups.keys()].filter(k => k !== 'Uncategorized').sort();
+        if (groups.has('Uncategorized'))
+            sortedKeys.push('Uncategorized');
+        if (sortedKeys.length > 0) {
+            lines.push('## Knowledge', '');
+            for (const key of sortedKeys) {
+                lines.push(`### ${key}`);
+                const items = groups.get(key).sort((a, b) => a.name.localeCompare(b.name));
+                for (const item of items) {
+                    lines.push(formatEntry(item));
+                }
+                lines.push('');
+            }
+        }
+    }
+    ensureLocalExclude(vaultPath);
+    writeFileSync(join(vaultPath, 'index.md'), lines.join('\n'));
+}

package/dist/merge.d.ts

@@ -0,0 +1 @@
+export declare function mergeVaultContent(remote: string, local: string): string;

package/dist/merge.js

@@ -0,0 +1,176 @@
+// src/merge.ts
+import { parseContent, serializeFile } from './vault.js';
+import { parseSessionLogHeading } from './parser.js';
+// Fields that are ISO date strings — latest date wins
+const DATE_FIELDS = ['last-touched', 'last-reinforced', 'created'];
+// Fields that are numeric counters — max wins
+const COUNT_FIELDS = ['reinforcement-count', 'staleness-days'];
+// Fields that are always arrays — union with dedup
+const ARRAY_FIELDS_UNCAPPED = ['tags', 'domain', 'related'];
+export function mergeVaultContent(remote, local) {
+    const r = parseContent(remote);
+    const l = parseContent(local);
+    const fm = mergeFrontmatter(r.frontmatter, l.frontmatter);
+    const body = mergeBody(r.body, l.body);
+    return serializeFile(fm, body);
+}
+function mergeFrontmatter(remote, local) {
+    // Start with remote as base, overlay local (local wins for scalars)
+    const merged = { ...remote, ...local };
+    // Date fields: latest wins
+    for (const key of DATE_FIELDS) {
+        const r = remote[key], l = local[key];
+        if (r && l)
+            merged[key] = r > l ? r : l;
+        else if (r)
+            merged[key] = r;
+    }
+    // Count fields: max wins
+    for (const key of COUNT_FIELDS) {
+        const r = remote[key], l = local[key];
+        if (r != null && l != null)
+            merged[key] = Math.max(r, l);
+        else if (r != null)
+            merged[key] = r;
+    }
+    // Array fields: union
+    for (const key of ARRAY_FIELDS_UNCAPPED) {
+        merged[key] = unionArrays(remote[key], local[key]);
+        if (merged[key].length === 0)
+            delete merged[key];
+    }
+    return merged;
+}
+function unionArrays(a, b) {
+    // Local (b) items first so they survive cap truncation
+    const arrA = Array.isArray(a) ? a : a ? [a] : [];
+    const arrB = Array.isArray(b) ? b : b ? [b] : [];
+    return [...new Set([...arrB, ...arrA])];
+}
+function splitSections(body) {
+    const parts = body.split(/\n(?=## )/g);
+    const sections = [];
+    let preamble = '';
+    for (const part of parts) {
+        if (part.startsWith('## ')) {
+            const nlIdx = part.indexOf('\n');
+            const heading = nlIdx === -1 ? part : part.slice(0, nlIdx);
+            const content = nlIdx === -1 ? '' : part.slice(nlIdx + 1);
+            sections.push({ heading: heading.trim(), content: content.trim() });
+        }
+        else {
+            preamble = part.trim();
+        }
+    }
+    return { preamble, sections };
+}
+function mergeBody(remoteBody, localBody) {
+    if (remoteBody === localBody)
+        return localBody;
+    const remote = splitSections(remoteBody);
+    const local = splitSections(localBody);
+    // Build merged sections starting from local
+    const localHeadings = new Set(local.sections.map(s => s.heading));
+    const mergedSections = [];
+    for (const ls of local.sections) {
+        const rs = remote.sections.find(s => s.heading === ls.heading);
+        if (ls.heading === '## Session Log' && rs) {
+            mergedSections.push({ heading: ls.heading, content: mergeSessionLogs(rs.content, ls.content) });
+        }
+        else if (ls.heading === '## Next Actions' && rs) {
+            mergedSections.push({ heading: ls.heading, content: mergeNextActions(rs.content, ls.content) });
+        }
+        else {
+            // Brief, Current State, anything else: local wins
+            mergedSections.push(ls);
+        }
+    }
+    // Append remote-only sections (not in local)
+    for (const rs of remote.sections) {
+        if (!localHeadings.has(rs.heading)) {
+            mergedSections.push(rs);
+        }
+    }
+    // Reassemble
+    const preamble = local.preamble || remote.preamble;
+    const parts = [preamble, ...mergedSections.map(s => `${s.heading}\n\n${s.content}`)].filter(Boolean);
+    return parts.join('\n\n');
+}
+function mergeSessionLogs(remoteContent, localContent) {
+    const remoteEntries = parseLogEntries(remoteContent);
+    const localEntries = parseLogEntries(localContent);
+    // Index local entries by identity key for dedup
+    const localKeys = new Set(localEntries.map(e => e.key));
+    const merged = [...localEntries];
+    // Add remote entries not present in local
+    for (const re of remoteEntries) {
+        if (!localKeys.has(re.key)) {
+            merged.push(re);
+        }
+    }
+    // Sort newest-first, with stable tiebreaker on identity key
+    merged.sort((a, b) => b.date.localeCompare(a.date) || a.key.localeCompare(b.key));
+    return merged.map(e => e.raw).join('\n\n');
+}
+function parseLogEntries(content) {
+    const entries = [];
+    const blocks = content.split(/\n(?=### \d{4}-\d{2}-\d{2})/);
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed)
+            continue;
+        const firstLine = trimmed.split('\n')[0];
+        const parsed = parseSessionLogHeading(firstLine);
+        if (parsed) {
+            entries.push({
+                key: `${parsed.date}|${parsed.agent}|${parsed.type}`,
+                date: parsed.date,
+                raw: trimmed,
+            });
+        }
+    }
+    return entries;
+}
+function mergeNextActions(remoteContent, localContent) {
+    const remoteItems = parseActionItems(remoteContent);
+    const localItems = parseActionItems(localContent);
+    // Build merged set: start with local items
+    const seen = new Set();
+    const merged = [];
+    // Add all local items
+    for (const item of localItems) {
+        seen.add(item.text);
+        merged.push(item);
+    }
+    // Add remote items not in local
+    for (const item of remoteItems) {
+        if (!seen.has(item.text)) {
+            seen.add(item.text);
+            merged.push(item);
+        }
+        else {
+            // If remote has it checked but local has it unchecked, upgrade to checked
+            const existing = merged.find(m => m.text === item.text);
+            if (existing && item.checked && !existing.checked) {
+                existing.checked = true;
+            }
+        }
+    }
+    return merged.map(i => `- [${i.checked ? 'x' : ' '}] ${i.text}`).join('\n');
+}
+function parseActionItems(content) {
+    const items = [];
+    for (const line of content.split('\n')) {
+        const unchecked = line.match(/^- \[ \] (.+)$/);
+        if (unchecked) {
+            items.push({ checked: false, text: unchecked[1] });
+            continue;
+        }
+        const checked = line.match(/^- \[x\] (.+)$/);
+        if (checked) {
+            items.push({ checked: true, text: checked[1] });
+            continue;
+        }
+    }
+    return items;
+}

package/dist/migrate-knowledge-v2.d.ts

@@ -0,0 +1,11 @@
+export interface MigrationReport {
+    sessionsToMove: string[];
+    emptyToDelete: string[];
+    insightToRename: string[];
+    relatedToGenerate: string[];
+    gitignoreNeeded: boolean;
+    gitCommitFailed: boolean;
+}
+export declare function migrateKnowledgeV2(vaultPath: string, opts: {
+    apply: boolean;
+}): MigrationReport;

package/dist/migrate-knowledge-v2.js

@@ -0,0 +1,158 @@
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync, appendFileSync } from 'fs';
+import { join } from 'path';
+import { parseFilePath, serializeFile } from './vault.js';
+import { syncRelatedSection, findSection } from './sections.js';
+import { generateVaultIndex } from './knowledge-index.js';
+import { spawnSync } from 'child_process';
+export function migrateKnowledgeV2(vaultPath, opts) {
+    const report = {
+        sessionsToMove: [],
+        emptyToDelete: [],
+        insightToRename: [],
+        relatedToGenerate: [],
+        gitignoreNeeded: false,
+        gitCommitFailed: false,
+    };
+    const knowledgeDir = join(vaultPath, 'knowledge');
+    const sessionsDir = join(vaultPath, 'sessions');
+    const entitiesDir = join(vaultPath, 'entities');
+    // Step 1: Find session knowledge notes (by frontmatter subtype, not filename)
+    if (existsSync(knowledgeDir)) {
+        for (const file of readdirSync(knowledgeDir).filter(f => f.endsWith('.md'))) {
+            try {
+                const { frontmatter } = parseFilePath(join(knowledgeDir, file));
+                if (frontmatter.subtype === 'session') {
+                    report.sessionsToMove.push(file);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    // Step 2: Find empty-body knowledge notes
+    if (existsSync(knowledgeDir)) {
+        for (const file of readdirSync(knowledgeDir).filter(f => f.endsWith('.md'))) {
+            if (report.sessionsToMove.includes(file))
+                continue; // already moving
+            try {
+                const { body } = parseFilePath(join(knowledgeDir, file));
+                // "Empty" = body only has section headings (## ...) and whitespace
+                const stripped = body.replace(/^## .+$/gm, '').trim();
+                if (!stripped)
+                    report.emptyToDelete.push(file);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    // Step 3: Find knowledge notes with ## Insight heading
+    if (existsSync(knowledgeDir)) {
+        for (const file of readdirSync(knowledgeDir).filter(f => f.endsWith('.md'))) {
+            if (report.sessionsToMove.includes(file) || report.emptyToDelete.includes(file))
+                continue;
+            try {
+                const { body } = parseFilePath(join(knowledgeDir, file));
+                if (findSection(body, 'Insight'))
+                    report.insightToRename.push(file);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    // Step 4: Find files needing ## Related section generation
+    for (const [dir, kind] of [[entitiesDir, 'entity'], [knowledgeDir, 'knowledge']]) {
+        if (!existsSync(dir))
+            continue;
+        for (const file of readdirSync(dir).filter(f => f.endsWith('.md'))) {
+            if (kind === 'knowledge' && (report.sessionsToMove.includes(file) || report.emptyToDelete.includes(file)))
+                continue;
+            try {
+                const { frontmatter: fm, body } = parseFilePath(join(dir, file));
+                const hasLinks = (fm.related?.length > 0) || fm.parent;
+                if (hasLinks) {
+                    const synced = syncRelatedSection(body, fm);
+                    if (synced !== body)
+                        report.relatedToGenerate.push(`${kind === 'entity' ? 'entities' : 'knowledge'}/${file}`);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    // Step 5: Check .gitignore
+    const gitignorePath = join(vaultPath, '.gitignore');
+    if (existsSync(gitignorePath)) {
+        const content = readFileSync(gitignorePath, 'utf-8');
+        if (!content.includes('/index.md'))
+            report.gitignoreNeeded = true;
+    }
+    else {
+        report.gitignoreNeeded = true;
+    }
+    if (!opts.apply)
+        return report;
+    // --- Apply ---
+    // Step 1: Move sessions
+    if (report.sessionsToMove.length > 0) {
+        mkdirSync(sessionsDir, { recursive: true });
+        for (const file of report.sessionsToMove) {
+            renameSync(join(knowledgeDir, file), join(sessionsDir, file));
+        }
+    }
+    // Step 2: Delete empty notes
+    for (const file of report.emptyToDelete) {
+        unlinkSync(join(knowledgeDir, file));
+    }
+    // Step 3: Rename ## Insight to ## Synthesis, add ## Sources if missing
+    for (const file of report.insightToRename) {
+        const filePath = join(knowledgeDir, file);
+        const content = readFileSync(filePath, 'utf-8');
+        let updated = content.replace(/^## Insight$/gm, '## Synthesis');
+        // Add ## Sources section if missing (new notes get it by default)
+        if (!findSection(updated, 'Sources')) {
+            updated = updated.trimEnd() + '\n\n## Sources\n';
+        }
+        writeFileSync(filePath, updated);
+    }
+    // Step 4: Generate ## Related sections
+    for (const relPath of report.relatedToGenerate) {
+        const filePath = join(vaultPath, relPath);
+        const { frontmatter: fm, body } = parseFilePath(filePath);
+        const newBody = syncRelatedSection(body, fm);
+        writeFileSync(filePath, serializeFile(fm, newBody));
+    }
+    // Step 5: Update .gitignore
+    if (report.gitignoreNeeded) {
+        appendFileSync(gitignorePath, '\n/index.md\n');
+    }
+    // Git commit only the files this migration touched
+    const filesToStage = [];
+    for (const f of report.sessionsToMove) {
+        filesToStage.push(`knowledge/${f}`); // deleted from knowledge/
+        filesToStage.push(`sessions/${f}`); // added to sessions/
+    }
+    for (const f of report.emptyToDelete)
+        filesToStage.push(`knowledge/${f}`);
+    for (const f of report.insightToRename)
+        filesToStage.push(`knowledge/${f}`);
+    for (const relPath of report.relatedToGenerate)
+        filesToStage.push(relPath);
+    if (report.gitignoreNeeded)
+        filesToStage.push('.gitignore');
+    if (filesToStage.length > 0) {
+        spawnSync('git', ['add', '--', ...filesToStage], { cwd: vaultPath, stdio: 'pipe' });
+    }
+    const commitResult = spawnSync('git', ['commit', '-m', 'migrate: knowledge-v2 (wiki links, synthesis, session move, cleanup)'], { cwd: vaultPath, stdio: 'pipe' });
+    if (commitResult.status !== 0) {
+        const stderr = commitResult.stderr?.toString() ?? 'unknown error';
+        process.stderr.write(`Warning: git commit failed: ${stderr}\n`);
+        report.gitCommitFailed = true;
+    }
+    // Post-commit: generate index.md (not committed — gitignored)
+    generateVaultIndex(vaultPath);
+    return report;
+}

package/dist/migrate-next-actions.d.ts

@@ -0,0 +1,6 @@
+export interface MigrationReport {
+    candidates: number;
+    migrated: number;
+    details: string[];
+}
+export declare function migrateNextActions(vaultPath: string, apply: boolean): MigrationReport;

package/dist/migrate-next-actions.js

@@ -0,0 +1,32 @@
+// src/migrate-next-actions.ts
+import { readdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { parseFilePath, serializeFile } from './vault.js';
+import { addNextAction } from './sections.js';
+export function migrateNextActions(vaultPath, apply) {
+    const entDir = join(vaultPath, 'entities');
+    const files = readdirSync(entDir).filter(f => f.endsWith('.md'));
+    const report = { candidates: 0, migrated: 0, details: [] };
+    for (const file of files) {
+        const filePath = join(entDir, file);
+        const { frontmatter: fm, body } = parseFilePath(filePath);
+        const nextAction = fm['next-action'];
+        // Skip if no next-action or it's null/empty
+        if (!nextAction || typeof nextAction !== 'string' || nextAction.trim() === '')
+            continue;
+        // Skip if already has a Next Actions section (idempotent)
+        if (body.includes('## Next Actions')) {
+            report.details.push(`${file}: skipped (already has ## Next Actions)`);
+            continue;
+        }
+        report.candidates++;
+        report.details.push(`${file}: next-action = "${nextAction}"`);
+        if (apply) {
+            const newBody = addNextAction(body, nextAction);
+            delete fm['next-action'];
+            writeFileSync(filePath, serializeFile(fm, newBody));
+            report.migrated++;
+        }
+    }
+    return report;
+}

package/dist/migrate-types.d.ts

@@ -0,0 +1,11 @@
+export interface MigrationReport {
+    typeChanges: number;
+    statusChanges: number;
+    knowledgeSubtypeAdded: number;
+    bodySectionsRestructured: number;
+    malformed: string[];
+    skipped: string[];
+    details: string[];
+    applied: boolean;
+}
+export declare function migrateTypes(vaultPath: string, apply: boolean): MigrationReport;

package/dist/migrate-types.js

@@ -0,0 +1,142 @@
+// src/migrate-types.ts
+import { readdirSync, writeFileSync, existsSync } from 'fs';
+import { join, relative } from 'path';
+import { parseFilePath, serializeFile } from './vault.js';
+// --- Type and status mapping tables ---
+const TYPE_MAP = {
+    thread: 'entity',
+    idea: 'entity',
+    area: 'project',
+    inbox: 'capture',
+};
+const STATUS_MAP = {
+    simmering: 'paused',
+    dormant: 'paused',
+};
+function newReport(applied) {
+    return { typeChanges: 0, statusChanges: 0, knowledgeSubtypeAdded: 0, bodySectionsRestructured: 0, malformed: [], skipped: [], details: [], applied };
+}
+/** Migrate a single entity file's frontmatter. Returns null if no change needed. */
+function migrateEntityFrontmatter(fm, filename, report) {
+    const rawType = fm.type;
+    // Malformed: missing type field
+    if (rawType === undefined || rawType === null) {
+        report.malformed.push(filename);
+        report.details.push(`${filename}: SKIPPED — missing type field`);
+        return null;
+    }
+    // Already-valid type and status — skip
+    const mappedType = TYPE_MAP[rawType] ?? rawType;
+    const mappedStatus = STATUS_MAP[fm.status] ?? fm.status;
+    const typeChanged = mappedType !== rawType;
+    const statusChanged = mappedStatus !== fm.status;
+    if (!typeChanged && !statusChanged) {
+        report.skipped.push(filename);
+        return null;
+    }
+    const newFm = { ...fm };
+    if (typeChanged) {
+        newFm.type = mappedType;
+        report.typeChanges++;
+        report.details.push(`${filename}: type ${rawType} → ${mappedType}`);
+    }
+    if (statusChanged) {
+        newFm.status = mappedStatus;
+        report.statusChanges++;
+        report.details.push(`${filename}: status ${fm.status} → ${mappedStatus}`);
+    }
+    return newFm;
+}
+/**
+ * Restructure body sections for old template types.
+ * - idea entities: ## Hypothesis → ## Context
+ * Returns the new body and whether any restructuring occurred.
+ * Checks unconditionally for ## Hypothesis — only idea entities use that heading,
+ * and this makes the rename idempotent regardless of whether the type rename already ran.
+ */
+function migrateEntityBody(body) {
+    let newBody = body;
+    let changed = false;
+    // idea template used ## Hypothesis where entity template expects ## Context.
+    // Check unconditionally so a partial migration (type renamed, body not yet renamed) is safe to rerun.
+    const re = /^## Hypothesis$/m;
+    if (re.test(newBody)) {
+        newBody = newBody.replace(re, '## Context');
+        changed = true;
+    }
+    return { body: newBody, changed };
+}
+/** Scan entity dir (and entities/archive if present) and return all .md files with their paths. */
+function collectEntityFiles(vaultPath) {
+    const entDir = join(vaultPath, 'entities');
+    const files = readdirSync(entDir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => join(entDir, f));
+    const archiveDir = join(entDir, 'archive');
+    if (existsSync(archiveDir)) {
+        readdirSync(archiveDir)
+            .filter(f => f.endsWith('.md'))
+            .forEach(f => files.push(join(archiveDir, f)));
+    }
+    return files;
+}
+export function migrateTypes(vaultPath, apply) {
+    const report = newReport(apply);
+    // --- 1. Entity files ---
+    const entityFiles = collectEntityFiles(vaultPath);
+    const entityWrites = [];
+    for (const filePath of entityFiles) {
+        const filename = relative(vaultPath, filePath);
+        const { frontmatter: fm, body } = parseFilePath(filePath);
+        const newFm = migrateEntityFrontmatter(fm, filename, report);
+        // Skip malformed files entirely — no body migration either
+        if (report.malformed.includes(filename))
+            continue;
+        // Check body restructuring (unconditional — idempotent regardless of type rename order)
+        const { body: newBody, changed: bodyChanged } = migrateEntityBody(body);
+        if (bodyChanged) {
+            report.bodySectionsRestructured++;
+            report.details.push(`${filename}: ## Hypothesis → ## Context`);
+        }
+        if (newFm === null && !bodyChanged)
+            continue; // nothing to do
+        // Use newFm if frontmatter changed, else original fm (for body-only changes)
+        const finalFm = newFm ?? fm;
+        entityWrites.push({ filePath, content: serializeFile(finalFm, newBody) });
+    }
+    // --- 2. Knowledge files: add subtype: insight ---
+    const knowledgeDir = join(vaultPath, 'knowledge');
+    const knowledgeFiles = existsSync(knowledgeDir)
+        ? readdirSync(knowledgeDir).filter(f => f.endsWith('.md')).map(f => join(knowledgeDir, f))
+        : [];
+    const knowledgeWrites = [];
+    const REVIEW_KEYWORDS = /reference|guide|template|framework|checklist|how-to|integration/i;
+    for (const filePath of knowledgeFiles) {
+        const filename = relative(vaultPath, filePath);
+        const { frontmatter: fm, body } = parseFilePath(filePath);
+        if (fm.subtype !== undefined) {
+            report.skipped.push(filename);
+            continue;
+        }
+        const newFm = { ...fm, subtype: 'insight' };
+        report.knowledgeSubtypeAdded++;
+        const needsReview = REVIEW_KEYWORDS.test(filename);
+        report.details.push(`${filename}: added subtype: insight${needsReview ? ' ⚠ review — may not be an insight' : ''}`);
+        knowledgeWrites.push({ filePath, content: serializeFile(newFm, body) });
+    }
+    if (!apply)
+        return report;
+    // --- Write all changed files. Crash during write-back → git checkout HEAD -- entities/ knowledge/ ---
+    const allWrites = [...entityWrites, ...knowledgeWrites];
+    try {
+        for (const { filePath, content } of allWrites) {
+            writeFileSync(filePath, content);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`\nMigration failed during write: ${err}\n`);
+        process.stderr.write(`Recovery: git -C ${vaultPath} checkout HEAD -- entities/ knowledge/\n`);
+        throw err;
+    }
+    return report;
+}