@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/agent/lessons-tracker.js

@@ -18,6 +18,160 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { logger } from '../utils/logger.js';
+import { getLessonProvenanceIndex } from './lesson-provenance.js';
+export function renderLessonConceptGraphMermaid(graph, maxLinks = 80) {
+    const lines = ['graph TD'];
+    const lessonNodeById = new Map();
+    const conceptNodeById = new Map();
+    graph.lessons.forEach((lesson, index) => {
+        const nodeId = `L${index}`;
+        lessonNodeById.set(lesson.id, nodeId);
+        lines.push(`  ${nodeId}["${escapeMermaidLabel(`${lesson.category}: ${truncateLabel(lesson.content, 64)}`)}"]`);
+    });
+    graph.concepts.forEach((concept, index) => {
+        const nodeId = `C${index}`;
+        conceptNodeById.set(concept.id, nodeId);
+        lines.push(`  ${nodeId}(("${escapeMermaidLabel(concept.label)}"))`);
+    });
+    let emittedLinks = 0;
+    for (const [lessonId, concepts] of Object.entries(graph.lessonConcepts)) {
+        const lessonNode = lessonNodeById.get(lessonId);
+        if (!lessonNode)
+            continue;
+        for (const concept of concepts) {
+            const conceptNode = conceptNodeById.get(concept.slug);
+            if (!conceptNode)
+                continue;
+            lines.push(`  ${lessonNode} --> ${conceptNode}`);
+            emittedLinks++;
+            if (emittedLinks >= maxLinks)
+                return lines.join('\n');
+        }
+    }
+    return lines.join('\n');
+}
+export function renderLessonConceptGraph(graph, format = 'summary') {
+    if (format === 'json') {
+        return JSON.stringify(graph, null, 2);
+    }
+    if (format === 'markdown') {
+        return renderLessonConceptGraphMarkdown(graph);
+    }
+    if (format === 'mermaid') {
+        return renderLessonConceptGraphMermaid(graph);
+    }
+    return renderLessonConceptGraphSummary(graph);
+}
+export function renderLessonConceptGraphMarkdown(graph) {
+    if (graph.lessons.length === 0) {
+        return '# Lessons Graph\n\nNo lessons available for graphing.';
+    }
+    const lessonsById = new Map(graph.lessons.map(lesson => [lesson.id, lesson]));
+    const lines = [
+        '# Lessons Graph',
+        '',
+        `Generated: ${new Date(graph.generatedAt).toISOString()}`,
+        `Lessons: ${graph.lessons.length}`,
+        `Concepts: ${graph.concepts.length}`,
+        `Relations: ${graph.relatedLessons.length}`,
+        ...renderLessonGraphFilterLines(graph.filters),
+        '',
+        '## Concepts',
+    ];
+    for (const concept of graph.concepts) {
+        lines.push('', `### [[${concept.id}|${concept.label}]]`);
+        lines.push(`- Sources: ${concept.sources.join(', ')}`);
+        lines.push(`- Weight: ${concept.weight}`);
+        lines.push('- Backlinks:');
+        for (const lessonId of graph.backlinks[concept.id] ?? concept.lessonIds) {
+            const lesson = lessonsById.get(lessonId);
+            const label = lesson ? `${lesson.category}: ${lesson.content}` : lessonId;
+            lines.push(`  - [${lessonId}] ${label}`);
+        }
+    }
+    lines.push('', '## Related Lessons');
+    if (graph.relatedLessons.length === 0) {
+        lines.push('- No lesson-to-lesson relations yet.');
+    }
+    else {
+        for (const edge of graph.relatedLessons) {
+            const shared = edge.sharedConcepts.map(slug => `[[${slug}]]`).join(', ');
+            lines.push(`- [${edge.from}] <-> [${edge.to}] via ${shared}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function renderLessonConceptVaultFiles(graph) {
+    const files = [];
+    const lessonsById = new Map(graph.lessons.map(lesson => [lesson.id, lesson]));
+    files.push({
+        path: 'index.md',
+        content: renderLessonVaultIndex(graph),
+    });
+    files.push({
+        path: '_concepts.md',
+        content: renderLessonVaultConceptIndex(graph),
+    });
+    files.push({
+        path: '_lessons.md',
+        content: renderLessonVaultLessonIndex(graph),
+    });
+    for (const concept of graph.concepts) {
+        files.push({
+            path: `concepts/${safeVaultSegment(concept.id)}.md`,
+            content: renderLessonVaultConcept(graph, concept, lessonsById),
+        });
+    }
+    for (const lesson of graph.lessons) {
+        files.push({
+            path: `lessons/${safeVaultSegment(lesson.id)}.md`,
+            content: renderLessonVaultLesson(graph, lesson),
+        });
+    }
+    files.push({ path: 'graph.json', content: renderLessonConceptGraph(graph, 'json') });
+    files.push({ path: 'graph.mmd', content: renderLessonConceptGraph(graph, 'mermaid') });
+    files.push({
+        path: 'manifest.json',
+        content: renderLessonVaultManifest(graph, [...files.map(file => file.path), 'manifest.json']),
+    });
+    return files;
+}
+export function renderLessonConceptGraphSummary(graph, maxConcepts = 12, maxRelations = 10) {
+    if (graph.lessons.length === 0) {
+        return 'No lessons available for graphing.';
+    }
+    const conceptLines = graph.concepts.slice(0, maxConcepts).map(concept => {
+        const sources = concept.sources.join(',');
+        return `- ${concept.label} (${concept.lessonIds.length} lesson(s); ${sources})`;
+    });
+    const relatedLines = graph.relatedLessons.slice(0, maxRelations).map(edge => {
+        const left = graph.lessons.find(lesson => lesson.id === edge.from);
+        const right = graph.lessons.find(lesson => lesson.id === edge.to);
+        return [
+            `- [${edge.from}] ${left?.content ?? edge.from}`,
+            `  <-> [${edge.to}] ${right?.content ?? edge.to}`,
+            `  shared: ${edge.sharedConcepts.join(', ')}`,
+        ].join('\n');
+    });
+    const backlinkLines = graph.concepts.slice(0, maxConcepts).map(concept => {
+        const ids = (graph.backlinks[concept.id] ?? concept.lessonIds).map(id => `[${id}]`).join(', ');
+        return `- ${concept.label}: ${ids}`;
+    });
+    return [
+        `Lesson graph: ${graph.lessons.length} lesson(s), ${graph.concepts.length} concept(s), ${graph.relatedLessons.length} relation(s).`,
+        ...renderLessonGraphFilterLines(graph.filters),
+        '',
+        '## Concepts',
+        conceptLines.length > 0 ? conceptLines.join('\n') : '- No concepts extracted.',
+        '',
+        '## Backlinks',
+        backlinkLines.length > 0 ? backlinkLines.join('\n') : '- No concept backlinks yet.',
+        '',
+        '## Related Lessons',
+        relatedLines.length > 0 ? relatedLines.join('\n') : '- No lesson-to-lesson relations yet.',
+    ].join('\n');
+}
 // ============================================================================
 // Singleton registry (one tracker per working directory)
 // ============================================================================
@@ -26,6 +180,11 @@ export function getLessonsTracker(workDir = process.cwd()) {
     const key = path.resolve(workDir);
     if (!registry.has(key)) {
         registry.set(key, new LessonsTracker(key));
+        if (registry.size > 20) {
+            const firstKey = registry.keys().next().value;
+            if (firstKey)
+                registry.delete(firstKey);
+        }
     }
     return registry.get(key);
 }
@@ -38,12 +197,48 @@ export class LessonsTracker {
     globalPath;
     items = [];
     loaded = false;
+    _cachedBlock = null;
+    _cacheTime = 0;
+    /**
+     * Serialized write chain (F33).
+     *
+     * Previously `add()` did load → mutate `this.items` → `save()` without
+     * any lock. Two concurrent calls — realistic when a multi-agent spawn
+     * runs in parallel — both pushed their own lesson into the in-memory
+     * array and then each `save()` wrote a snapshot to disk, so the second
+     * writer's snapshot silently clobbered the first writer's lesson.
+     *
+     * The queue serializes every disk write through a chained promise so
+     * only one `fs.writeFileSync` runs at a time, and each write re-reads
+     * the canonical disk state just before writing — matching the F17
+     * SessionStore lock pattern but lighter-weight since lessons are
+     * append-only.
+     */
+    _writeChain = Promise.resolve();
     constructor(workDir) {
         this.workDir = workDir;
         const projectDir = path.join(workDir, '.codebuddy');
         this.projectPath = path.join(projectDir, 'lessons.md');
         this.globalPath = path.join(os.homedir(), '.codebuddy', 'lessons.md');
     }
+    /**
+     * Enqueue a write through the serialized chain. Errors are logged but
+     * don't break the chain so later writes can still proceed.
+     */
+    enqueueWrite(fn) {
+        this._writeChain = this._writeChain
+            .then(() => {
+            try {
+                fn();
+            }
+            catch (err) {
+                logger.warn('[lessons] write failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        });
+        return this._writeChain;
+    }
     // --------------------------------------------------------------------------
     // Public API
     // --------------------------------------------------------------------------
@@ -53,28 +248,36 @@ export class LessonsTracker {
         this.loaded = true;
         const globalItems = this.loadFile(this.globalPath);
         const projectItems = this.loadFile(this.projectPath);
-        // Merge: project overrides global for duplicate ids
+        // Merge: project overrides global for duplicate ids (warn on content mismatch)
         const byId = new Map();
         for (const item of [...globalItems, ...projectItems]) {
+            const existing = byId.get(item.id);
+            if (existing && existing.content !== item.content) {
+                logger.warn(`[lessons] duplicate ID "${item.id}" — project overrides global`);
+            }
             byId.set(item.id, item);
         }
         this.items = Array.from(byId.values());
     }
+    /**
+     * Save to project path only (global is managed manually or via
+     * `lessons_add --global`). Routed through the serialized write queue
+     * so concurrent add/remove calls cannot clobber each other (F33).
+     *
+     * The fire-and-forget nature is preserved — callers that want to
+     * observe write completion can `await tracker.save()` explicitly.
+     */
     save() {
         this.load();
-        // Save to project path only (global is managed manually or by `lessons_add --global`)
-        try {
+        return this.enqueueWrite(() => {
             const dir = path.dirname(this.projectPath);
             if (!fs.existsSync(dir)) {
                 fs.mkdirSync(dir, { recursive: true });
             }
             fs.writeFileSync(this.projectPath, this.serialise(), 'utf-8');
-        }
-        catch {
-            // non-fatal
-        }
+        });
     }
-    add(category, content, source = 'manual', context) {
+    add(category, content, source = 'manual', context, provenance) {
         this.load();
         const item = {
             id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),
@@ -85,7 +288,17 @@ export class LessonsTracker {
             source,
         };
         this.items.push(item);
+        this._cachedBlock = null;
         this.save();
+        // Record "created by" provenance in the side-car index when known.
+        if (provenance && (provenance.runId || provenance.outcomeId || provenance.sagaId)) {
+            try {
+                getLessonProvenanceIndex(this.workDir).recordCreated(item.id, provenance);
+            }
+            catch {
+                // Provenance is best-effort; never fail a lesson write on it.
+            }
+        }
         return item;
     }
     remove(id) {
@@ -94,6 +307,7 @@ export class LessonsTracker {
         if (idx === -1)
             return false;
         this.items.splice(idx, 1);
+        this._cachedBlock = null;
         this.save();
         return true;
     }
@@ -103,6 +317,7 @@ export class LessonsTracker {
         this.items = category
             ? this.items.filter(i => i.category !== category)
             : [];
+        this._cachedBlock = null;
         this.save();
         return before - this.items.length;
     }
@@ -120,14 +335,144 @@ export class LessonsTracker {
                 (item.context?.toLowerCase().includes(q) ?? false));
         });
     }
+    buildConceptGraph(options = {}) {
+        this.load();
+        const { query, category } = options;
+        const limit = normalizeGraphLimit(options.limit);
+        const includeKeywords = options.includeKeywords !== false;
+        const normalizedQuery = query?.toLowerCase().trim();
+        const normalizedConcept = normalizeGraphConceptFilter(options.concept);
+        const lessons = this.items
+            .filter(item => !category || item.category === category)
+            .filter(item => {
+            if (!normalizedQuery)
+                return true;
+            return (item.content.toLowerCase().includes(normalizedQuery) ||
+                (item.context?.toLowerCase().includes(normalizedQuery) ?? false));
+        })
+            .filter(item => {
+            if (!normalizedConcept)
+                return true;
+            return extractLessonConcepts(item, { includeKeywords }).some(concept => (concept.slug === normalizedConcept ||
+                slugifyConcept(concept.label) === normalizedConcept));
+        })
+            .slice(0, limit);
+        const conceptMap = new Map();
+        const lessonConcepts = {};
+        for (const lesson of lessons) {
+            const concepts = extractLessonConcepts(lesson, { includeKeywords });
+            lessonConcepts[lesson.id] = concepts;
+            for (const concept of concepts) {
+                const existing = conceptMap.get(concept.slug);
+                if (existing) {
+                    if (!existing.lessonIds.includes(lesson.id)) {
+                        existing.lessonIds.push(lesson.id);
+                    }
+                    for (const source of concept.sources) {
+                        if (!existing.sources.includes(source)) {
+                            existing.sources.push(source);
+                        }
+                    }
+                    existing.weight = existing.lessonIds.length;
+                }
+                else {
+                    conceptMap.set(concept.slug, {
+                        id: concept.slug,
+                        label: concept.label,
+                        lessonIds: [lesson.id],
+                        sources: [...concept.sources],
+                        weight: 1,
+                    });
+                }
+            }
+        }
+        const concepts = Array.from(conceptMap.values())
+            .sort((a, b) => b.weight - a.weight || a.label.localeCompare(b.label));
+        const backlinks = buildConceptBacklinks(concepts);
+        const relatedLessons = buildRelatedLessonEdges(lessons, lessonConcepts);
+        return {
+            schemaVersion: 1,
+            generatedAt: Date.now(),
+            filters: buildLessonGraphFilters({ query, concept: options.concept, category, includeKeywords, limit }),
+            lessons,
+            concepts,
+            lessonConcepts,
+            backlinks,
+            relatedLessons,
+        };
+    }
+    getConceptDetails(conceptName) {
+        const graph = this.buildConceptGraph({ includeKeywords: true, limit: 1000 });
+        const slug = conceptName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+        const conceptNode = graph.concepts.find(c => c.id === slug || c.label.toLowerCase() === conceptName.toLowerCase());
+        if (!conceptNode)
+            return null;
+        const provIndex = getLessonProvenanceIndex(this.workDir);
+        const lessons = graph.lessons
+            .filter(l => conceptNode.lessonIds.includes(l.id))
+            .map(l => {
+            const prov = provIndex.getProvenance(l.id);
+            return {
+                id: l.id,
+                category: l.category,
+                content: l.content,
+                context: l.context,
+                createdBy: prov?.createdBy,
+                usedBy: prov?.usedBy,
+            };
+        });
+        const backlinkIds = new Set();
+        for (const rel of graph.relatedLessons) {
+            if (conceptNode.lessonIds.includes(rel.from) || conceptNode.lessonIds.includes(rel.to)) {
+                for (const c of rel.sharedConcepts) {
+                    if (c !== conceptNode.id) {
+                        backlinkIds.add(c);
+                    }
+                }
+            }
+        }
+        const backlinks = Array.from(backlinkIds)
+            .map(id => graph.concepts.find(c => c.id === id)?.label)
+            .filter(Boolean);
+        return {
+            concept: {
+                id: conceptNode.id,
+                label: conceptNode.label,
+                weight: conceptNode.weight,
+            },
+            lessons,
+            backlinks,
+        };
+    }
     /**
      * Build the per-turn context block injected BEFORE the todo suffix.
      * Returns null when there are no lessons (avoids noisy injections).
      */
     buildContextBlock() {
+        if (this._cachedBlock !== null && Date.now() - this._cacheTime < 5000) {
+            return this._cachedBlock;
+        }
         this.load();
         if (this.items.length === 0)
             return null;
+        // Record usage off the hot path
+        const workDir = this.workDir;
+        const lessonIds = this.items.map(item => item.id);
+        Promise.resolve().then(async () => {
+            try {
+                const { RunStore } = await import('../observability/run-store.js');
+                const activeRunId = RunStore.getInstance().getCurrentRunId();
+                if (activeRunId) {
+                    const index = getLessonProvenanceIndex(workDir);
+                    for (const id of lessonIds) {
+                        index.recordUsage(id, activeRunId);
+                    }
+                }
+            }
+            catch (err) {
+                logger.debug('[lessons] failed to record usage in background', { error: String(err) });
+            }
+        });
         const lines = [
             '<lessons_context>',
             '## Active Lessons (apply to this turn)',
@@ -150,7 +495,10 @@ export class LessonsTracker {
             }
         }
         lines.push('</lessons_context>');
-        return lines.join('\n');
+        const result = lines.join('\n');
+        this._cachedBlock = result;
+        this._cacheTime = Date.now();
+        return result;
     }
     // --------------------------------------------------------------------------
     // Analytics
@@ -201,6 +549,7 @@ export class LessonsTracker {
         this.items = this.items.filter(item => !(item.category === 'INSIGHT' && item.createdAt > 0 && item.createdAt < threshold));
         const removed = before - this.items.length;
         if (removed > 0) {
+            this._cachedBlock = null;
             this.save();
         }
         return removed;
@@ -259,22 +608,28 @@ export class LessonsTracker {
             // Item: - [id] content <!-- date source:context -->
             const itemMatch = rawLine.match(/^- \[([^\]]+)\] (.+?) <!-- ([^\s]+) ([^\s:]+)(?::([^-]+))? -->/);
             if (itemMatch) {
+                const [, id, rawContent, dateStr, sourceStr, ctx] = itemMatch;
+                if (id === undefined || rawContent === undefined || dateStr === undefined || sourceStr === undefined)
+                    continue;
                 items.push({
-                    id: itemMatch[1],
-                    content: itemMatch[2].trim(),
+                    id,
+                    content: rawContent.trim(),
                     category: currentCategory,
-                    createdAt: new Date(itemMatch[3]).getTime() || 0,
-                    source: itemMatch[4] ?? 'manual',
-                    context: itemMatch[5]?.trim() || undefined,
+                    createdAt: new Date(dateStr).getTime() || 0,
+                    source: sourceStr ?? 'manual',
+                    context: ctx?.trim() || undefined,
                 });
                 continue;
             }
             // Plain item fallback: - content
             const plainMatch = rawLine.match(/^- (.+)/);
             if (plainMatch) {
+                const plainContent = plainMatch[1];
+                if (plainContent === undefined)
+                    continue;
                 items.push({
                     id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),
-                    content: plainMatch[1].trim(),
+                    content: plainContent.trim(),
                     category: currentCategory,
                     createdAt: 0,
                     source: 'manual',
@@ -284,4 +639,426 @@ export class LessonsTracker {
         return items;
     }
 }
+const CONCEPT_STOP_WORDS = new Set([
+    'about', 'after', 'again', 'ainsi', 'always', 'avant', 'avoir', 'because',
+    'before', 'cette', 'comme', 'dans', 'faire', 'from', 'leurs', 'mettre',
+    'pour', 'quand', 'should', 'then', 'this', 'tool', 'tools', 'tout',
+    'toute', 'use', 'using', 'with',
+]);
+function extractLessonConcepts(lesson, options = {}) {
+    const concepts = new Map();
+    const add = (rawLabel, source, rawSlug = rawLabel) => {
+        const label = normalizeConceptLabel(rawLabel);
+        const slug = slugifyConcept(normalizeConceptLabel(rawSlug));
+        if (!slug || CONCEPT_STOP_WORDS.has(slug))
+            return;
+        const existing = concepts.get(slug);
+        if (existing) {
+            if (!existing.sources.includes(source))
+                existing.sources.push(source);
+            return;
+        }
+        concepts.set(slug, { slug, label, sources: [source] });
+    };
+    if (lesson.context)
+        add(lesson.context, 'context');
+    for (const match of lesson.content.matchAll(/\[\[([^\]]+)\]\]/g)) {
+        const inner = match[1];
+        if (inner === undefined)
+            continue;
+        const { label, target } = parseWikiLink(inner);
+        add(label, 'wiki_link', target);
+    }
+    for (const match of lesson.content.matchAll(/(?<!!)\[([^\]]+)\]\(([^)]+)\)/g)) {
+        const linkLabel = match[1];
+        const linkTarget = match[2];
+        if (linkLabel === undefined || linkTarget === undefined)
+            continue;
+        const target = normalizeMarkdownLinkTarget(linkTarget);
+        if (target)
+            add(linkLabel, 'markdown_link', target);
+    }
+    for (const match of lesson.content.matchAll(/(?:^|\s)#([A-Za-z0-9][A-Za-z0-9_-]{1,64})/g)) {
+        const tag = match[1];
+        if (tag === undefined)
+            continue;
+        add(tag, 'tag');
+    }
+    for (const match of lesson.content.matchAll(/\b(?:tags?|related)\s*:\s*([^.;\n]+)/gi)) {
+        const tagList = match[1];
+        if (tagList === undefined)
+            continue;
+        for (const part of tagList.split(/[,|]/)) {
+            add(part, match[0].toLowerCase().startsWith('related') ? 'related' : 'tag');
+        }
+    }
+    if (options.includeKeywords !== false) {
+        const cleanedContent = lesson.content
+            .replace(/\[\[[^\]]+\]\]/g, ' ')
+            .replace(/(?<!!)\[[^\]]+\]\([^)]+\)/g, ' ')
+            .replace(/<!--.*?-->/g, ' ')
+            .replace(/\b(?:tags?|related)\s*:\s*([^.;\n]+)/gi, ' ');
+        for (const rawWord of cleanedContent.split(/[^A-Za-z0-9À-ÖØ-öø-ÿ_-]+/u)) {
+            const label = normalizeConceptLabel(rawWord);
+            const slug = slugifyConcept(label);
+            if (slug.length >= 5 && !CONCEPT_STOP_WORDS.has(slug)) {
+                add(label, 'keyword');
+            }
+            if (concepts.size >= 12)
+                break;
+        }
+    }
+    return Array.from(concepts.values()).sort((a, b) => a.label.localeCompare(b.label));
+}
+function buildRelatedLessonEdges(lessons, lessonConcepts) {
+    const edges = [];
+    for (let i = 0; i < lessons.length; i++) {
+        for (let j = i + 1; j < lessons.length; j++) {
+            const left = lessons[i];
+            const right = lessons[j];
+            if (left === undefined || right === undefined)
+                continue;
+            const leftConcepts = new Set((lessonConcepts[left.id] ?? []).map(concept => concept.slug));
+            const sharedConcepts = (lessonConcepts[right.id] ?? [])
+                .map(concept => concept.slug)
+                .filter(slug => leftConcepts.has(slug));
+            if (sharedConcepts.length === 0)
+                continue;
+            edges.push({
+                from: left.id,
+                to: right.id,
+                sharedConcepts,
+                weight: sharedConcepts.length,
+            });
+        }
+    }
+    return edges.sort((a, b) => b.weight - a.weight || a.from.localeCompare(b.from));
+}
+function buildConceptBacklinks(concepts) {
+    const backlinks = {};
+    for (const concept of concepts) {
+        backlinks[concept.id] = [...concept.lessonIds];
+    }
+    return backlinks;
+}
+function renderLessonVaultIndex(graph) {
+    const lines = [
+        ...renderYamlFrontmatter([
+            ['type', 'lessons-vault-index'],
+            ['schemaVersion', graph.schemaVersion],
+            ['generatedAt', new Date(graph.generatedAt).toISOString()],
+            ['lessons', graph.lessons.length],
+            ['concepts', graph.concepts.length],
+            ['relations', graph.relatedLessons.length],
+        ]),
+        '# Lessons Vault',
+        '',
+        `Generated: ${new Date(graph.generatedAt).toISOString()}`,
+        `Schema version: ${graph.schemaVersion}`,
+        `Lessons: ${graph.lessons.length}`,
+        `Concepts: ${graph.concepts.length}`,
+        `Relations: ${graph.relatedLessons.length}`,
+        ...renderLessonGraphFilterLines(graph.filters),
+        '',
+        '## Indexes',
+        `- ${vaultWikiLink('_concepts', 'Concept index')}`,
+        `- ${vaultWikiLink('_lessons', 'Lesson index')}`,
+        '',
+        '## Concepts',
+    ];
+    if (graph.concepts.length === 0) {
+        lines.push('- No concepts extracted.');
+    }
+    else {
+        for (const concept of graph.concepts) {
+            lines.push(`- ${vaultWikiLink(`concepts/${concept.id}`, concept.label)} (${concept.lessonIds.length} lesson(s); ${concept.sources.join(', ')})`);
+        }
+    }
+    lines.push('', '## Lessons');
+    if (graph.lessons.length === 0) {
+        lines.push('- No lessons available.');
+    }
+    else {
+        for (const lesson of graph.lessons) {
+            lines.push(`- ${vaultWikiLink(`lessons/${lesson.id}`, `${lesson.category}: ${truncateLabel(lesson.content, 80)}`)}`);
+        }
+    }
+    lines.push('', '## Artifacts');
+    lines.push('- `graph.json`');
+    lines.push('- `graph.mmd`');
+    lines.push('- `manifest.json`');
+    return lines.join('\n');
+}
+function renderLessonVaultManifest(graph, files) {
+    const manifest = {
+        vaultSchemaVersion: 1,
+        graphSchemaVersion: graph.schemaVersion,
+        generatedAt: new Date(graph.generatedAt).toISOString(),
+        entrypoints: {
+            index: 'index.md',
+            conceptsIndex: '_concepts.md',
+            lessonsIndex: '_lessons.md',
+            graphJson: 'graph.json',
+            graphMermaid: 'graph.mmd',
+            manifest: 'manifest.json',
+        },
+        counts: {
+            lessons: graph.lessons.length,
+            concepts: graph.concepts.length,
+            relations: graph.relatedLessons.length,
+            files: files.length,
+        },
+        filters: graph.filters,
+        concepts: graph.concepts.map(concept => ({
+            id: concept.id,
+            label: concept.label,
+            path: `concepts/${safeVaultSegment(concept.id)}.md`,
+            sources: concept.sources,
+            lessonIds: graph.backlinks[concept.id] ?? concept.lessonIds,
+        })),
+        lessons: graph.lessons.map(lesson => ({
+            id: lesson.id,
+            category: lesson.category,
+            path: `lessons/${safeVaultSegment(lesson.id)}.md`,
+            conceptIds: (graph.lessonConcepts[lesson.id] ?? []).map(concept => concept.slug),
+        })),
+        files,
+    };
+    return JSON.stringify(manifest, null, 2);
+}
+function renderLessonVaultConceptIndex(graph) {
+    const lines = [
+        ...renderYamlFrontmatter([
+            ['type', 'lessons-vault-concepts-index'],
+            ['schemaVersion', graph.schemaVersion],
+            ['generatedAt', new Date(graph.generatedAt).toISOString()],
+            ['concepts', graph.concepts.map(concept => concept.id)],
+        ]),
+        '# Concept Index',
+        '',
+    ];
+    if (graph.concepts.length === 0) {
+        lines.push('- No concepts extracted.');
+    }
+    else {
+        for (const concept of graph.concepts) {
+            const sources = concept.sources.join(', ');
+            const link = vaultWikiLink(`concepts/${concept.id}`, concept.label);
+            lines.push(`- ${link} (${concept.lessonIds.length} lesson(s); ${sources})`);
+        }
+    }
+    return lines.join('\n');
+}
+function renderLessonVaultLessonIndex(graph) {
+    const lines = [
+        ...renderYamlFrontmatter([
+            ['type', 'lessons-vault-lessons-index'],
+            ['schemaVersion', graph.schemaVersion],
+            ['generatedAt', new Date(graph.generatedAt).toISOString()],
+            ['lessonIds', graph.lessons.map(lesson => lesson.id)],
+        ]),
+        '# Lesson Index',
+        '',
+    ];
+    if (graph.lessons.length === 0) {
+        lines.push('- No lessons available.');
+    }
+    else {
+        for (const lesson of graph.lessons) {
+            const concepts = (graph.lessonConcepts[lesson.id] ?? [])
+                .map(concept => vaultWikiLink(`concepts/${concept.slug}`, concept.label))
+                .join(', ');
+            const label = `${lesson.category}: ${truncateLabel(lesson.content, 96)}`;
+            const suffix = concepts ? ` concepts: ${concepts}` : '';
+            lines.push(`- ${vaultWikiLink(`lessons/${lesson.id}`, label)}${suffix}`);
+        }
+    }
+    return lines.join('\n');
+}
+function renderLessonVaultConcept(graph, concept, lessonsById) {
+    const lines = [
+        ...renderYamlFrontmatter([
+            ['type', 'lesson-concept'],
+            ['id', concept.id],
+            ['label', concept.label],
+            ['sources', concept.sources],
+            ['lessonIds', graph.backlinks[concept.id] ?? concept.lessonIds],
+            ['weight', concept.weight],
+        ]),
+        `# ${concept.label}`,
+        '',
+        `Concept id: \`${concept.id}\``,
+        `Sources: ${concept.sources.join(', ')}`,
+        `Weight: ${concept.weight}`,
+        '',
+        '## Backlinks',
+    ];
+    for (const lessonId of graph.backlinks[concept.id] ?? concept.lessonIds) {
+        const lesson = lessonsById.get(lessonId);
+        const label = lesson ? `${lesson.category}: ${truncateLabel(lesson.content, 96)}` : lessonId;
+        lines.push(`- ${vaultWikiLink(`lessons/${lessonId}`, label)}`);
+    }
+    const related = graph.relatedLessons.filter(edge => edge.sharedConcepts.includes(concept.id));
+    lines.push('', '## Related Lessons');
+    if (related.length === 0) {
+        lines.push('- No lesson-to-lesson relations through this concept yet.');
+    }
+    else {
+        for (const edge of related) {
+            lines.push(`- ${vaultWikiLink(`lessons/${edge.from}`, edge.from)} <-> ${vaultWikiLink(`lessons/${edge.to}`, edge.to)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function renderLessonVaultLesson(graph, lesson) {
+    const concepts = graph.lessonConcepts[lesson.id] ?? [];
+    const lines = [
+        ...renderYamlFrontmatter([
+            ['type', 'lesson'],
+            ['id', lesson.id],
+            ['category', lesson.category],
+            ['source', lesson.source],
+            ['createdAt', lesson.createdAt ? new Date(lesson.createdAt).toISOString() : undefined],
+            ['context', lesson.context],
+            ['concepts', concepts.map(concept => concept.slug)],
+        ]),
+        `# ${lesson.category}: ${lesson.id}`,
+        '',
+        `Category: ${lesson.category}`,
+        `Source: ${lesson.source}`,
+        `Created: ${lesson.createdAt ? new Date(lesson.createdAt).toISOString() : 'unknown'}`,
+        ...(lesson.context ? [`Context: ${lesson.context}`] : []),
+        '',
+        '## Content',
+        lesson.content,
+        '',
+        '## Concepts',
+    ];
+    if (concepts.length === 0) {
+        lines.push('- No concepts extracted.');
+    }
+    else {
+        for (const concept of concepts) {
+            lines.push(`- ${vaultWikiLink(`concepts/${concept.slug}`, concept.label)} (${concept.sources.join(', ')})`);
+        }
+    }
+    const related = graph.relatedLessons.filter(edge => edge.from === lesson.id || edge.to === lesson.id);
+    lines.push('', '## Related Lessons');
+    if (related.length === 0) {
+        lines.push('- No related lessons yet.');
+    }
+    else {
+        for (const edge of related) {
+            const otherId = edge.from === lesson.id ? edge.to : edge.from;
+            const shared = edge.sharedConcepts.map(slug => vaultWikiLink(`concepts/${slug}`, slug)).join(', ');
+            lines.push(`- ${vaultWikiLink(`lessons/${otherId}`, otherId)} via ${shared}`);
+        }
+    }
+    return lines.join('\n');
+}
+function vaultWikiLink(target, label) {
+    const safeLabel = label.replace(/[[\]|]/g, '').replace(/\s+/g, ' ').trim();
+    return `[[${target}|${safeLabel || target}]]`;
+}
+function renderYamlFrontmatter(entries) {
+    const lines = ['---'];
+    for (const [key, value] of entries) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                lines.push(`${key}: []`);
+            }
+            else {
+                lines.push(`${key}:`);
+                for (const item of value) {
+                    lines.push(`  - ${yamlScalar(item)}`);
+                }
+            }
+        }
+        else {
+            lines.push(`${key}: ${yamlScalar(value)}`);
+        }
+    }
+    lines.push('---', '');
+    return lines;
+}
+function yamlScalar(value) {
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function safeVaultSegment(value) {
+    return slugifyConcept(value) || 'unknown';
+}
+function buildLessonGraphFilters(filters) {
+    return {
+        ...(filters.query ? { query: filters.query } : {}),
+        ...(filters.concept ? { concept: filters.concept } : {}),
+        ...(filters.category ? { category: filters.category } : {}),
+        includeKeywords: filters.includeKeywords,
+        limit: filters.limit,
+    };
+}
+function renderLessonGraphFilterLines(filters) {
+    if (!filters)
+        return [];
+    return [
+        `Filters: query=${filters.query ?? 'any'}; concept=${filters.concept ?? 'any'}; category=${filters.category ?? 'any'}; includeKeywords=${filters.includeKeywords}; limit=${filters.limit}`,
+    ];
+}
+function normalizeGraphLimit(value) {
+    if (value === undefined)
+        return 50;
+    if (!Number.isFinite(value))
+        return 50;
+    return Math.min(Math.max(Math.floor(value), 1), 200);
+}
+function normalizeGraphConceptFilter(value) {
+    if (!value)
+        return null;
+    const target = normalizeMarkdownLinkTarget(value) ?? value;
+    const slug = slugifyConcept(normalizeConceptLabel(target));
+    return slug || null;
+}
+function parseWikiLink(value) {
+    const [target = '', alias] = value.split('|', 2).map(part => part.trim());
+    return {
+        label: alias || target,
+        target: normalizeMarkdownLinkTarget(target) ?? target,
+    };
+}
+function normalizeMarkdownLinkTarget(value) {
+    const trimmed = value.trim();
+    if (!trimmed || /^[a-z][a-z0-9+.-]*:/i.test(trimmed))
+        return null;
+    const [withoutQuery = ''] = trimmed.startsWith('#') ? [trimmed.slice(1)] : trimmed.split(/[?#]/, 1);
+    const normalized = withoutQuery.replace(/\\/g, '/').replace(/\/+$/g, '');
+    const basename = normalized.split('/').pop() ?? normalized;
+    const withoutExtension = basename.replace(/\.md$/i, '');
+    return withoutExtension || null;
+}
+function normalizeConceptLabel(value) {
+    return value
+        .replace(/^#+/, '')
+        .replace(/[[\]`*_]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function escapeMermaidLabel(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function truncateLabel(value, maxLength) {
+    return value.length > maxLength ? `${value.slice(0, maxLength - 3)}...` : value;
+}
+function slugifyConcept(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
 //# sourceMappingURL=lessons-tracker.js.map