learn-anything-cli 0.2.1 → 0.4.0-beta.1

package/README.md

@@ -1,5 +1,7 @@
 # Learn Anything
 
+[English](./README.md) | [中文](./README.zh-CN.md)
+
 AI-powered recursive learning system — turns your AI coding assistant into an interactive tutor using the Socratic method and TDD-style exercises.
 
 Generate skill and command files for **30+ AI tools** (Claude Code, Cursor, Gemini CLI, Codex, Copilot, Windsurf, etc.), then use slash commands to systematically master any technical topic.

package/dist/cli/index.js

@@ -43,7 +43,7 @@ program
                 throw error;
             }
             else {
-                throw new Error(mc.cannotAccess(targetPath, error.message));
+                throw new Error(mc.cannotAccess(targetPath, error.message), { cause: error });
             }
         }
         const { InitCommand } = await import('../core/init.js');

package/dist/core/command-generation/registry.js

@@ -1,4 +1,4 @@
-import { claudeAdapter, cursorAdapter, codexAdapter, geminiAdapter, } from './adapters/index.js';
+import { claudeAdapter, cursorAdapter, codexAdapter, geminiAdapter } from './adapters/index.js';
 export class CommandAdapterRegistry {
     static adapters = new Map();
     static {

package/dist/core/config.js

@@ -1,33 +1,161 @@
 export const LEARN_DIR = '.learn';
 export const AI_TOOLS = [
-    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq' },
-    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent' },
-    { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
-    { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
-    { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },
+    {
+        name: 'Amazon Q Developer',
+        value: 'amazon-q',
+        available: true,
+        successLabel: 'Amazon Q Developer',
+        skillsDir: '.amazonq',
+    },
+    {
+        name: 'Antigravity',
+        value: 'antigravity',
+        available: true,
+        successLabel: 'Antigravity',
+        skillsDir: '.agent',
+    },
+    {
+        name: 'Auggie (Augment CLI)',
+        value: 'auggie',
+        available: true,
+        successLabel: 'Auggie',
+        skillsDir: '.augment',
+    },
+    {
+        name: 'Bob Shell',
+        value: 'bob',
+        available: true,
+        successLabel: 'Bob Shell',
+        skillsDir: '.bob',
+    },
+    {
+        name: 'Claude Code',
+        value: 'claude',
+        available: true,
+        successLabel: 'Claude Code',
+        skillsDir: '.claude',
+    },
     { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline' },
     { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.codex' },
-    { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
-    { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
-    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue' },
-    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec' },
+    {
+        name: 'ForgeCode',
+        value: 'forgecode',
+        available: true,
+        successLabel: 'ForgeCode',
+        skillsDir: '.forge',
+    },
+    {
+        name: 'CodeBuddy Code (CLI)',
+        value: 'codebuddy',
+        available: true,
+        successLabel: 'CodeBuddy Code',
+        skillsDir: '.codebuddy',
+    },
+    {
+        name: 'Continue',
+        value: 'continue',
+        available: true,
+        successLabel: 'Continue (VS Code / JetBrains / Cli)',
+        skillsDir: '.continue',
+    },
+    {
+        name: 'CoStrict',
+        value: 'costrict',
+        available: true,
+        successLabel: 'CoStrict',
+        skillsDir: '.cospec',
+    },
     { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
-    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor' },
-    { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
-    { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
-    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'] },
+    {
+        name: 'Cursor',
+        value: 'cursor',
+        available: true,
+        successLabel: 'Cursor',
+        skillsDir: '.cursor',
+    },
+    {
+        name: 'Factory Droid',
+        value: 'factory',
+        available: true,
+        successLabel: 'Factory Droid',
+        skillsDir: '.factory',
+    },
+    {
+        name: 'Gemini CLI',
+        value: 'gemini',
+        available: true,
+        successLabel: 'Gemini CLI',
+        skillsDir: '.gemini',
+    },
+    {
+        name: 'GitHub Copilot',
+        value: 'github-copilot',
+        available: true,
+        successLabel: 'GitHub Copilot',
+        skillsDir: '.github',
+        detectionPaths: [
+            '.github/copilot-instructions.md',
+            '.github/instructions',
+            '.github/workflows/copilot-setup-steps.yml',
+            '.github/prompts',
+            '.github/agents',
+            '.github/skills',
+            '.github/.mcp.json',
+        ],
+    },
     { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
     { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie' },
-    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode' },
+    {
+        name: 'Kilo Code',
+        value: 'kilocode',
+        available: true,
+        successLabel: 'Kilo Code',
+        skillsDir: '.kilocode',
+    },
     { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro' },
-    { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode' },
+    {
+        name: 'OpenCode',
+        value: 'opencode',
+        available: true,
+        successLabel: 'OpenCode',
+        skillsDir: '.opencode',
+    },
     { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
     { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder' },
-    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma' },
-    { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
-    { name: 'RooCode', value: 'roocode', available: true, successLabel: 'RooCode', skillsDir: '.roo' },
+    {
+        name: 'Lingma',
+        value: 'lingma',
+        available: true,
+        successLabel: 'Lingma',
+        skillsDir: '.lingma',
+    },
+    {
+        name: 'Qwen Code',
+        value: 'qwen',
+        available: true,
+        successLabel: 'Qwen Code',
+        skillsDir: '.qwen',
+    },
+    {
+        name: 'RooCode',
+        value: 'roocode',
+        available: true,
+        successLabel: 'RooCode',
+        skillsDir: '.roo',
+    },
     { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae' },
-    { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf', skillsDir: '.windsurf' },
-    { name: 'AGENTS.md (works with Amp, VS Code, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' },
+    {
+        name: 'Windsurf',
+        value: 'windsurf',
+        available: true,
+        successLabel: 'Windsurf',
+        skillsDir: '.windsurf',
+    },
+    {
+        name: 'AGENTS.md (works with Amp, VS Code, …)',
+        value: 'agents',
+        available: false,
+        successLabel: 'your AGENTS.md-compatible assistant',
+    },
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/init.d.ts

@@ -16,6 +16,8 @@ export declare class InitCommand {
     private hasToolDir;
     private interactiveSelect;
     private generateSkillsForTool;
+    /** Read a compiled script from dist/scripts/ (bundled alongside this module). */
+    private readCompiledScript;
     private generateCommandsForTool;
 }
 export {};

package/dist/core/init.js

@@ -2,11 +2,12 @@ import path from 'path';
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { AI_TOOLS, LEARN_DIR } from './config.js';
 import { isInteractive } from '../utils/interactive.js';
-import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
-import { getSkillTemplates, getCommandContents, generateSkillContent, } from './shared/index.js';
+import { generateCommands, CommandAdapterRegistry } from './command-generation/index.js';
+import { getSkillTemplates, getCommandContents, generateSkillContent } from './shared/index.js';
 import { getMessages } from '../i18n/index.js';
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../../package.json');
@@ -28,7 +29,14 @@ export class InitCommand {
         await FileSystemUtils.ensureDir(resolvedPath);
         // Create .learn/ directory in the target project
         const learnDir = path.join(resolvedPath, LEARN_DIR);
-        await FileSystemUtils.ensureDir(path.join(learnDir, 'topics'));
+        const topicsDir = path.join(learnDir, 'topics');
+        await FileSystemUtils.ensureDir(topicsDir);
+        // Run v0→v1 migration for any existing learning data
+        const { migrateAll } = await import('./learn-protocol/index.js');
+        const report = await migrateAll(topicsDir);
+        if (report.migratedCount > 0) {
+            console.log(chalk.green(m.init.migrationComplete(report.migratedCount)));
+        }
         console.log(chalk.bold(m.init.header));
         // Detect available tools
         const availableTools = await this.detectTools(resolvedPath);
@@ -53,7 +61,10 @@ export class InitCommand {
         }
         if (selectedTools.length === 0) {
             console.log(chalk.yellow(m.init.noToolsSelected));
-            console.log(chalk.dim(m.init.availableTools(availableTools.filter((t) => t.available).map((t) => t.value).join(', '))));
+            console.log(chalk.dim(m.init.availableTools(availableTools
+                .filter((t) => t.available)
+                .map((t) => t.value)
+                .join(', '))));
             return;
         }
         // Generate skill files for each tool
@@ -77,7 +88,7 @@ export class InitCommand {
         console.log(cmd(chalk.cyan('/learn:status [topic-name]'), chalk.dim('    — Visualize learning state as knowledge map heatmap')));
         console.log('');
     }
-    async detectTools(resolvedPath) {
+    async detectTools(_resolvedPath) {
         return AI_TOOLS;
     }
     hasToolDir(resolvedPath, tool) {
@@ -93,7 +104,7 @@ export class InitCommand {
     }
     async interactiveSelect(tools) {
         const availableTools = tools.filter((t) => t.available && t.skillsDir);
-        const { search, checkbox } = await import('@inquirer/prompts');
+        const { checkbox } = await import('@inquirer/prompts');
         // Auto-detect existing tool dirs and pre-select them
         const detected = availableTools.filter((t) => this.hasToolDir(process.cwd(), t));
         const detectedValues = new Set(detected.map((t) => t.value));
@@ -116,8 +127,27 @@ export class InitCommand {
             const skillFile = path.join(skillDir, 'SKILL.md');
             const content = generateSkillContent(entry.template, VERSION);
             await FileSystemUtils.writeFile(skillFile, content);
+            const scriptsDir = path.join(skillDir, 'scripts');
+            // topic / explain / practice → utils.mjs + render.mjs
+            if (entry.dirName === 'learn-anything-topic' ||
+                entry.dirName === 'learn-anything-explain' ||
+                entry.dirName === 'learn-anything-practice') {
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'render.mjs'), this.readCompiledScript('render.mjs'));
+            }
+            // status → utils.mjs + status.mjs
+            if (entry.dirName === 'learn-anything-status') {
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'status.mjs'), this.readCompiledScript('status.mjs'));
+            }
+            // review → no scripts needed
         }
     }
+    /** Read a compiled script from dist/scripts/ (bundled alongside this module). */
+    readCompiledScript(filename) {
+        const scriptPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'scripts', filename);
+        return fs.readFileSync(scriptPath, 'utf-8');
+    }
     async generateCommandsForTool(resolvedPath, tool) {
         const adapter = CommandAdapterRegistry.get(tool.value);
         if (!adapter)

package/dist/core/learn-protocol/index.d.ts

@@ -0,0 +1,8 @@
+export type { ConceptStatus, Concept, Domain, StateV1, Detail, V0Concept, V0State, ParsedConcept, ParsedDomain, ParsedKnowledgeMap, } from './types.js';
+export { stateV1Schema, validateStateV1 } from './schema.js';
+export type { StateV1Schema, ValidationResult } from './schema.js';
+export { generateSlug } from './slug.js';
+export { parseKnowledgeMap } from './parser.js';
+export { isV0State, migrateV0ToV1, migrateAll } from './migrate.js';
+export type { MigrationResult, MigrationReport } from './migrate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/learn-protocol/index.js

@@ -0,0 +1,5 @@
+export { stateV1Schema, validateStateV1 } from './schema.js';
+export { generateSlug } from './slug.js';
+export { parseKnowledgeMap } from './parser.js';
+export { isV0State, migrateV0ToV1, migrateAll } from './migrate.js';
+//# sourceMappingURL=index.js.map

package/dist/core/learn-protocol/migrate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * v0 -> v1 migration logic.
+ *
+ * Detects v0 state.yaml format and merges it with knowledge-map.md
+ * to produce a state.json v1 file. Migration is idempotent and
+ * creates .bak backups before writing.
+ *
+ * Migration chain:
+ *   state.yaml (v0) + knowledge-map.md (v0)
+ *     -> migrateV0ToV1()
+ *       -> state.json (v1) + state.yaml.v0.bak + knowledge-map.md.v0.bak
+ */
+import type { V0State } from './types.js';
+/**
+ * Check if a parsed YAML object matches the v0 state format.
+ *
+ * v0 is identified by having `topic` and `concepts` fields but
+ * NO `version` field. Returns `true` when the data matches v0.
+ */
+export declare function isV0State(data: unknown): data is V0State;
+export interface MigrationResult {
+    migrated: boolean;
+    topic: string;
+    reason?: 'already_migrated' | 'already_v1' | 'not_v0' | 'no_state_yaml' | 'error';
+    error?: string;
+}
+export interface MigrationReport {
+    migratedCount: number;
+    skippedCount: number;
+    results: MigrationResult[];
+}
+/**
+ * Migrate a single topic directory from v0 to v1.
+ *
+ * Reads `state.yaml` and `knowledge-map.md`, merges them into `state.json`,
+ * and creates `.bak` backup files. Idempotent — skips if already migrated.
+ *
+ * @param topicDir — Absolute path to the topic directory (e.g. `.learn/topics/javascript`)
+ * @returns A MigrationResult describing what happened
+ */
+export declare function migrateV0ToV1(topicDir: string): Promise<MigrationResult>;
+/**
+ * Migrate ALL topics under a base directory from v0 to v1.
+ *
+ * Scans `.learn/topics/` for topic subdirectories and runs
+ * migrateV0ToV1 on each one. Returns a summary report.
+ *
+ * @param baseDir — Path to the topics directory (e.g. `.learn/topics`)
+ * @returns MigrationReport with counts and per-topic results
+ */
+export declare function migrateAll(baseDir: string): Promise<MigrationReport>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/core/learn-protocol/migrate.js

@@ -0,0 +1,259 @@
+/**
+ * v0 -> v1 migration logic.
+ *
+ * Detects v0 state.yaml format and merges it with knowledge-map.md
+ * to produce a state.json v1 file. Migration is idempotent and
+ * creates .bak backups before writing.
+ *
+ * Migration chain:
+ *   state.yaml (v0) + knowledge-map.md (v0)
+ *     -> migrateV0ToV1()
+ *       -> state.json (v1) + state.yaml.v0.bak + knowledge-map.md.v0.bak
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { parseKnowledgeMap } from './parser.js';
+import { generateSlug } from './slug.js';
+import { stateV1Schema } from './schema.js';
+import { render } from '../../scripts/render.mjs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+// ---- Public API ---------------------------------------------------------
+/**
+ * Check if a parsed YAML object matches the v0 state format.
+ *
+ * v0 is identified by having `topic` and `concepts` fields but
+ * NO `version` field. Returns `true` when the data matches v0.
+ */
+export function isV0State(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    // v0: has topic (string) and concepts (array), no version field
+    if (typeof obj.topic !== 'string' || !obj.topic)
+        return false;
+    if (!Array.isArray(obj.concepts))
+        return false;
+    if (obj.version !== undefined)
+        return false;
+    return true;
+}
+/**
+ * Migrate a single topic directory from v0 to v1.
+ *
+ * Reads `state.yaml` and `knowledge-map.md`, merges them into `state.json`,
+ * and creates `.bak` backup files. Idempotent — skips if already migrated.
+ *
+ * @param topicDir — Absolute path to the topic directory (e.g. `.learn/topics/javascript`)
+ * @returns A MigrationResult describing what happened
+ */
+export async function migrateV0ToV1(topicDir) {
+    const stateYamlPath = path.join(topicDir, 'state.yaml');
+    const knowledgeMapPath = path.join(topicDir, 'knowledge-map.md');
+    const stateJsonPath = path.join(topicDir, 'state.json');
+    const stateYamlBackup = path.join(topicDir, 'state.yaml.v0.bak');
+    const knowledgeMapBackup = path.join(topicDir, 'knowledge-map.md.v0.bak');
+    // 1. Skip if state.json already exists (already migrated)
+    if (await FileSystemUtils.fileExists(stateJsonPath)) {
+        try {
+            const existing = JSON.parse(await fs.readFile(stateJsonPath, 'utf-8'));
+            return {
+                migrated: false,
+                topic: existing.topic || path.basename(topicDir),
+                reason: 'already_migrated',
+            };
+        }
+        catch {
+            return {
+                migrated: false,
+                topic: path.basename(topicDir),
+                reason: 'already_migrated',
+            };
+        }
+    }
+    // 2. Check state.yaml exists
+    if (!(await FileSystemUtils.fileExists(stateYamlPath))) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'no_state_yaml',
+        };
+    }
+    // 3. Read and parse state.yaml
+    let v0Data;
+    try {
+        const yamlContent = await fs.readFile(stateYamlPath, 'utf-8');
+        v0Data = parseYaml(yamlContent);
+    }
+    catch (err) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'error',
+            error: `Failed to parse state.yaml: ${err.message}`,
+        };
+    }
+    // 4. Check v0 format (has topic + concepts, no version field)
+    if (!isV0State(v0Data)) {
+        return {
+            migrated: false,
+            topic: path.basename(topicDir),
+            reason: 'not_v0',
+        };
+    }
+    const v0State = v0Data;
+    // 7. Read and parse knowledge-map.md
+    let parsedMap;
+    if (await FileSystemUtils.fileExists(knowledgeMapPath)) {
+        try {
+            const kmContent = await fs.readFile(knowledgeMapPath, 'utf-8');
+            parsedMap = parseKnowledgeMap(kmContent);
+        }
+        catch (err) {
+            return {
+                migrated: false,
+                topic: v0State.topic,
+                reason: 'error',
+                error: `Failed to parse knowledge-map.md: ${err.message}`,
+            };
+        }
+    }
+    else {
+        // Without knowledge-map.md we can't build the hierarchy; skip
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: 'knowledge-map.md not found',
+        };
+    }
+    // 8. Merge: build a lookup from v0 path -> V0Concept
+    const conceptLookup = new Map();
+    for (const c of v0State.concepts) {
+        conceptLookup.set(c.path, c);
+    }
+    // 9. Build StateV1 from parsed hierarchy + v0 state data
+    const domains = parsedMap.domains.map((pd) => ({
+        name: pd.name,
+        slug: generateSlug(pd.name),
+        concepts: pd.concepts.map((pc) => {
+            const v0Path = `${pd.name}/${pc.name}`;
+            const v0Concept = conceptLookup.get(v0Path);
+            return {
+                name: pc.name,
+                slug: generateSlug(pc.name),
+                status: mapStatus(v0Concept?.status),
+                confidence: v0Concept?.confidence ?? 0,
+                practice_count: v0Concept?.practice_count ?? 0,
+                explain_count: v0Concept?.explain_count ?? 0,
+                last_explained: v0Concept?.last_session ?? null,
+                last_practiced: v0Concept?.last_practiced ?? null,
+                details: pc.children,
+            };
+        }),
+    }));
+    const stateV1 = {
+        version: 1,
+        topic: v0State.topic,
+        slug: generateSlug(v0State.topic),
+        created: v0State.created,
+        domains,
+    };
+    // 10. Validate the generated state against the schema
+    const validation = stateV1Schema.safeParse(stateV1);
+    if (!validation.success) {
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: `Generated state.json failed validation: ${validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`,
+        };
+    }
+    // 11. Write state.json
+    try {
+        await FileSystemUtils.writeFile(stateJsonPath, JSON.stringify(stateV1, null, 2) + '\n');
+    }
+    catch (err) {
+        return {
+            migrated: false,
+            topic: v0State.topic,
+            reason: 'error',
+            error: `Failed to write state.json: ${err.message}`,
+        };
+    }
+    // 12. Create backup files, then remove originals
+    //     After migration, state.json is the single source of truth,
+    //     so the v0 files should not remain alongside it.
+    try {
+        await fs.copyFile(stateYamlPath, stateYamlBackup);
+        await fs.copyFile(knowledgeMapPath, knowledgeMapBackup);
+        await fs.rm(stateYamlPath, { force: true });
+        await fs.rm(knowledgeMapPath, { force: true });
+    }
+    catch (err) {
+        // Backup/cleanup failure is non-fatal — state.json was already written
+        console.error(`Warning: Failed to create backup files or clean up originals in ${topicDir}: ${err.message}`);
+    }
+    // 13. Regenerate knowledge-map.md from state.json (v1 format)
+    try {
+        const rendered = render(stateV1);
+        await FileSystemUtils.writeFile(knowledgeMapPath, rendered);
+    }
+    catch (err) {
+        // Render failure is non-fatal — migration itself succeeded
+        console.error(`Warning: Failed to regenerate knowledge-map.md in ${topicDir}: ${err.message}`);
+    }
+    return {
+        migrated: true,
+        topic: v0State.topic,
+    };
+}
+/**
+ * Migrate ALL topics under a base directory from v0 to v1.
+ *
+ * Scans `.learn/topics/` for topic subdirectories and runs
+ * migrateV0ToV1 on each one. Returns a summary report.
+ *
+ * @param baseDir — Path to the topics directory (e.g. `.learn/topics`)
+ * @returns MigrationReport with counts and per-topic results
+ */
+export async function migrateAll(baseDir) {
+    const results = [];
+    let entryNames;
+    try {
+        entryNames = await fs.readdir(baseDir);
+    }
+    catch {
+        // Directory doesn't exist — nothing to migrate
+        return { migratedCount: 0, skippedCount: 0, results: [] };
+    }
+    // Check each entry to see if it's a directory
+    const topicDirs = [];
+    for (const name of entryNames) {
+        const fullPath = path.join(baseDir, name);
+        try {
+            const stat = await fs.stat(fullPath);
+            if (stat.isDirectory())
+                topicDirs.push(fullPath);
+        }
+        catch {
+            // Skip entries we can't stat
+        }
+    }
+    for (const dir of topicDirs) {
+        const result = await migrateV0ToV1(dir);
+        results.push(result);
+    }
+    const migratedCount = results.filter((r) => r.migrated).length;
+    const skippedCount = results.filter((r) => !r.migrated).length;
+    return { migratedCount, skippedCount, results };
+}
+// ---- Helpers -----------------------------------------------------------
+/** Map v0 status string to v1 ConceptStatus; default to 'unexplored'. */
+function mapStatus(status) {
+    if (status === 'in_progress' || status === 'needs_practice' || status === 'mastered') {
+        return status;
+    }
+    return 'unexplored';
+}
+//# sourceMappingURL=migrate.js.map

package/dist/core/learn-protocol/parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Markdown parser for v0 knowledge-map.md.
+ *
+ * Uses unified + remark-parse to extract the hierarchical structure
+ * (domains -> concepts -> details) from the v0 knowledge-map format.
+ *
+ * This is used ONLY during migration (init/update), not at AI runtime.
+ *
+ * v0 knowledge-map.md format:
+ *
+ * ```md
+ * # Topic Name
+ * ## Domain 1
+ * - Concept A
+ *   - Detail A1
+ *   - Detail A2
+ * - Concept B
+ * ## Domain 2
+ * - Concept C
+ * ```
+ */
+import type { ParsedKnowledgeMap } from './types.js';
+/**
+ * Parse a v0 knowledge-map.md file content into a structured representation.
+ *
+ * The parser walks the mdast tree:
+ * - `# Title` (h1) -> topic name
+ * - `## DomainName` (h2) -> start a new domain
+ * - `- Concept` (top-level list item) -> add concept to current domain
+ * - `  - Detail` (nested list item) -> add detail to preceding concept
+ */
+export declare function parseKnowledgeMap(markdown: string): ParsedKnowledgeMap;
+//# sourceMappingURL=parser.d.ts.map