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

package/README.md

@@ -23,6 +23,12 @@ npm install -g learn-anything-cli
 learn-anything init
 ```
 
+### Context7 Integration (Optional)
+
+When running `init` or `update`, you'll be prompted to enable **Context7** for documentation verification. When enabled, the AI will fetch official documentation and verify its explanations against authoritative sources — improving teaching accuracy.
+
+If you haven't set up Context7 yet, run `npx ctx7 setup` or visit the [Context7 docs](https://context7.com/docs/resources/all-clients) for your specific AI tool.
+
 After init, your AI assistant gains five learning commands:
 
 | Command                          | What it does                                                 |
@@ -37,7 +43,7 @@ After init, your AI assistant gains five learning commands:
 
 ### `/learn:topic <topic-name>` — Initialize a Topic
 
-The AI generates a hierarchical knowledge map (`.learn/topics/<topic>/knowledge-map.md`), creates a learning state tracker (`state.yaml`), and presents the landscape for you to choose your own path.
+The AI creates a learning state file (`state.json`) and generates a knowledge map (`knowledge-map.md`) via `render.mjs`, then presents the landscape for you to choose your own path.
 
 ### `/learn:explain <concept-name>` — Recursive Deep Dive
 
@@ -75,8 +81,8 @@ Your Project/
 ├── .learn/                    # Your learning data (knowledge maps, progress)
 │   └── topics/
 │       └── javascript/
-│           ├── knowledge-map.md
-│           ├── state.yaml
+│           ├── state.json          # Learning data (single source of truth)
+│           ├── knowledge-map.md    # Auto-generated by render.mjs from state.json
 │           └── sessions/
 └── ...
 ```

package/README.zh-CN.md

@@ -21,6 +21,12 @@ npm install -g learn-anything-cli
 learn-anything init
 ```
 
+### Context7 集成（可选）
+
+在执行 `init` 或 `update` 时，会提示是否启用 **Context7** 文档验证。启用后，AI 会获取官方文档并对照权威来源验证其教学内容——提高教学准确性。
+
+如果你还没有配置 Context7，运行 `npx ctx7 setup` 或访问 [Context7 文档](https://context7.com/docs/resources/all-clients) 查看你使用的 AI 工具的配置方式。
+
 初始化后，你的 AI 助手获得五个学习命令：
 
 | 命令                             | 功能                                   |
@@ -35,7 +41,7 @@ learn-anything init
 
 ### `/learn:topic <topic-name>` — 初始化主题
 
-AI 生成层次化知识图谱（`.learn/topics/<topic>/knowledge-map.md`），创建学习状态跟踪文件（`state.yaml`），展示知识全景让你自主选择学习路径。
+AI 创建学习状态文件（`state.json`），并通过 `render.mjs` 生成知识图谱（`knowledge-map.md`），展示知识全景让你自主选择学习路径。
 
 ### `/learn:explain <concept-name>` — 递归式深度学习
 
@@ -73,8 +79,8 @@ npx learn-anything-cli update
 ├── .learn/                    # 你的学习数据（知识图谱、进度）
 │   └── topics/
 │       └── javascript/
-│           ├── knowledge-map.md
-│           ├── state.yaml
+│           ├── state.json          # 学习数据（唯一数据源）
+│           ├── knowledge-map.md    # 由 render.mjs 从 state.json 自动生成
 │           └── sessions/
 └── ...
 ```

package/dist/cli/index.js

@@ -24,6 +24,8 @@ program
     .option('--tools <tools>', m.cli.toolsOptionDescription(availableToolIds.join(', ')))
     .option('--force', m.cli.forceOption)
     .option('--lang <locale>', m.cli.langOption)
+    .option('--context7', 'Enable Context7 documentation verification')
+    .option('--no-context7', 'Disable Context7 documentation verification')
     .action(async (targetPath = '.', options) => {
     const cliLocale = resolveLocale(options?.lang);
     const mc = cliLocale !== earlyLocale ? getMessages(cliLocale).cli : m.cli;
@@ -51,6 +53,7 @@ program
             tools: options?.tools,
             force: options?.force,
             locale: cliLocale,
+            context7: options?.context7,
         });
         await initCommand.execute(targetPath);
     }

package/dist/core/init.d.ts

@@ -4,14 +4,18 @@ type InitCommandOptions = {
     force?: boolean;
     locale?: SupportedLocale;
     update?: boolean;
+    context7?: boolean;
 };
 export declare class InitCommand {
     private readonly toolsArg?;
     private readonly force;
     private readonly locale;
     private readonly isUpdate;
+    private readonly context7Arg?;
+    private context7Enabled;
     constructor(options?: InitCommandOptions);
     execute(targetPath?: string): Promise<void>;
+    private promptContext7;
     private detectTools;
     private hasToolDir;
     private interactiveSelect;

package/dist/core/init.js

@@ -9,6 +9,7 @@ import { isInteractive } from '../utils/interactive.js';
 import { generateCommands, CommandAdapterRegistry } from './command-generation/index.js';
 import { getSkillTemplates, getCommandContents, generateSkillContent } from './shared/index.js';
 import { getMessages } from '../i18n/index.js';
+import { CONTEXT7_GUIDANCE } from './templates/context7-guidance.js';
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../../package.json');
 export class InitCommand {
@@ -16,11 +17,14 @@ export class InitCommand {
     force;
     locale;
     isUpdate;
+    context7Arg;
+    context7Enabled = false;
     constructor(options = {}) {
         this.toolsArg = options.tools;
         this.force = options.force ?? false;
         this.locale = options.locale ?? 'en';
         this.isUpdate = options.update ?? false;
+        this.context7Arg = options.context7;
     }
     async execute(targetPath = '.') {
         const resolvedPath = path.resolve(targetPath);
@@ -67,6 +71,12 @@ export class InitCommand {
                 .join(', '))));
             return;
         }
+        // Context7 setup
+        this.context7Enabled = await this.promptContext7();
+        if (this.context7Enabled) {
+            console.log(chalk.dim(m.init.context7Enabled));
+        }
+        console.log('');
         // Generate skill files for each tool
         for (const tool of selectedTools) {
             if (!tool.skillsDir)
@@ -87,6 +97,21 @@ export class InitCommand {
         console.log(cmd(chalk.cyan('/learn:review [topic-name]'), chalk.dim('    — Review progress, spaced repetition recommendations')));
         console.log(cmd(chalk.cyan('/learn:status [topic-name]'), chalk.dim('    — Visualize learning state as knowledge map heatmap')));
         console.log('');
+        if (this.context7Enabled) {
+            console.log(chalk.dim(m.init.context7SetupHint));
+            console.log('');
+        }
+    }
+    async promptContext7() {
+        const m = getMessages(this.locale);
+        if (this.context7Arg === true)
+            return true;
+        if (this.context7Arg === false)
+            return false;
+        if (!isInteractive())
+            return true;
+        const { confirm } = await import('@inquirer/prompts');
+        return confirm({ message: m.init.context7Prompt, default: true });
     }
     async detectTools(_resolvedPath) {
         return AI_TOOLS;
@@ -125,7 +150,9 @@ export class InitCommand {
         for (const entry of skillTemplates) {
             const skillDir = path.join(resolvedPath, tool.skillsDir, 'skills', entry.dirName);
             const skillFile = path.join(skillDir, 'SKILL.md');
-            const content = generateSkillContent(entry.template, VERSION);
+            const content = generateSkillContent(entry.template, VERSION, this.context7Enabled && isDocVerificationTemplate(entry.workflowId)
+                ? injectContext7Guidance
+                : undefined);
             await FileSystemUtils.writeFile(skillFile, content);
             const scriptsDir = path.join(skillDir, 'scripts');
             // topic / explain / practice → utils.mjs + render.mjs
@@ -135,6 +162,10 @@ export class InitCommand {
                 await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
                 await FileSystemUtils.writeFile(path.join(scriptsDir, 'render.mjs'), this.readCompiledScript('render.mjs'));
             }
+            // topic -> init-sessions.mjs
+            if (entry.dirName === 'learn-anything-topic') {
+                await FileSystemUtils.writeFile(path.join(scriptsDir, 'init-sessions.mjs'), this.readCompiledScript('init-sessions.mjs'));
+            }
             // status → utils.mjs + status.mjs
             if (entry.dirName === 'learn-anything-status') {
                 await FileSystemUtils.writeFile(path.join(scriptsDir, 'utils.mjs'), this.readCompiledScript('utils.mjs'));
@@ -160,4 +191,15 @@ export class InitCommand {
         }
     }
 }
+const DOC_VERIFICATION_WORKFLOWS = new Set(['topic', 'explain', 'practice']);
+function isDocVerificationTemplate(workflowId) {
+    return DOC_VERIFICATION_WORKFLOWS.has(workflowId);
+}
+function injectContext7Guidance(instructions) {
+    const marker = '\n## Command:';
+    const index = instructions.indexOf(marker);
+    if (index === -1)
+        return instructions + CONTEXT7_GUIDANCE;
+    return instructions.slice(0, index) + CONTEXT7_GUIDANCE + instructions.slice(index);
+}
 //# sourceMappingURL=init.js.map

package/dist/core/templates/context7-guidance.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Context7 documentation verification guidance.
+ * Injected into topic/explain/practice skill templates when Context7 is enabled.
+ *
+ * Instructs the AI to use Context7 MCP tools at runtime:
+ * - resolve-library-id: resolves library name to Context7 ID
+ * - query-docs: fetches docs by library ID + query
+ *
+ * NOT injected into review/status templates (those are about progress review
+ * and visualization, not teaching content).
+ */
+export declare const CONTEXT7_GUIDANCE = "\n## Documentation Verification (Context7)\n\nWhen teaching about a specific library or framework, verify your explanations against official documentation using Context7 MCP tools:\n\n1. **Resolve the library**: Call `resolve-library-id` with the library name (e.g., \"React\", \"TypeScript\")\n2. **Fetch relevant docs**: Call `query-docs` with the resolved library ID and the concept you are teaching as the query\n3. **Cross-reference**: Ensure your explanations, code examples, and API usage match the official documentation\n4. **Defer to docs**: If your explanation conflicts with official documentation, use the official documentation as the authoritative source\n\nIf Context7 MCP tools are not available in your environment, proceed with your built-in knowledge.\n";
+//# sourceMappingURL=context7-guidance.d.ts.map

package/dist/core/templates/context7-guidance.js

@@ -0,0 +1,24 @@
+/**
+ * Context7 documentation verification guidance.
+ * Injected into topic/explain/practice skill templates when Context7 is enabled.
+ *
+ * Instructs the AI to use Context7 MCP tools at runtime:
+ * - resolve-library-id: resolves library name to Context7 ID
+ * - query-docs: fetches docs by library ID + query
+ *
+ * NOT injected into review/status templates (those are about progress review
+ * and visualization, not teaching content).
+ */
+export const CONTEXT7_GUIDANCE = `
+## Documentation Verification (Context7)
+
+When teaching about a specific library or framework, verify your explanations against official documentation using Context7 MCP tools:
+
+1. **Resolve the library**: Call \`resolve-library-id\` with the library name (e.g., "React", "TypeScript")
+2. **Fetch relevant docs**: Call \`query-docs\` with the resolved library ID and the concept you are teaching as the query
+3. **Cross-reference**: Ensure your explanations, code examples, and API usage match the official documentation
+4. **Defer to docs**: If your explanation conflicts with official documentation, use the official documentation as the authoritative source
+
+If Context7 MCP tools are not available in your environment, proceed with your built-in knowledge.
+`;
+//# sourceMappingURL=context7-guidance.js.map

package/dist/core/templates/workflows/learn-explain.js

@@ -51,17 +51,21 @@ Structure your explanation:
 
 **A) Determine the filename:**
 
-Use the concept name exactly as it appears in state.json, in the same language. Convert to kebab-case and append the date:
+Use the concept name exactly as it appears in state.json, in the same language. Convert to kebab-case and append the date. Place the file in the subdirectory matching the domain's \`slug\` field from state.json:
 
-> \`./.learn/topics/<topic-name>/sessions/<concept-name-as-is>-YYYY-MM-DD.md\`
+> \`./.learn/topics/<topic-name>/sessions/<domain-slug>/<concept-name-as-is>-YYYY-MM-DD.md\`
+
+Where \`<domain-slug>\` is the \`slug\` field of the domain that contains this concept.
 
 Examples:
-- state.json has \`变量声明与数据类型\` → \`变量声明与数据类型-2026-05-24.md\`
-- state.json has \`Scope & Closures\` → \`Scope-Closures-2026-05-24.md\`
-- state.json has \`Event Loop\` → \`Event-Loop-2026-05-24.md\`
+- concept \`变量声明与数据类型\` in domain with slug \`语言基础\` → \`sessions/语言基础/变量声明与数据类型-2026-05-24.md\`
+- concept \`Scope & Closures\` in domain with slug \`函数与作用域\` → \`sessions/函数与作用域/Scope-Closures-2026-05-24.md\`
+- concept \`Event Loop\` in domain with slug \`async-programming\` → \`sessions/async-programming/Event-Loop-2026-05-24.md\`
 
 Match the language the user is learning in — don't force-translate.
 
+⚠️ If the domain subdirectory does not exist, create it first: \`mkdir -p ./.learn/topics/<topic-name>/sessions/<domain-slug>\`
+
 **B) Write the session file** containing: positioning, analogy, core mechanism, code example with walkthrough, misconceptions, Socratic check, and quick summary. The file should be self-contained — re-readable without the chat.
 
 Session file format:
@@ -153,7 +157,7 @@ Follow the workflow defined in the skill:
 1. Load context: match topic → read state.json (single source of truth, do NOT read knowledge-map.md)
 2. Assess user level (beginner/intermediate/advanced) and adjust teaching strategy
 3. Compose the full explanation: positioning → analogy → core mechanism → code example → common misconceptions → Socratic check
-4. CRITICAL — Write the session file FIRST (./.learn/topics/<topic>/sessions/<concept-name>-YYYY-MM-DD.md, matching the user's language), then echo the file content verbatim to the conversation. Also update state.json with Edit (last_explained, explain_count, status, confidence). Then run render.mjs to regenerate knowledge-map.md.
+4. CRITICAL — Write the session file FIRST (./.learn/topics/<topic>/sessions/<domain-slug>/<concept-name>-YYYY-MM-DD.md, where <domain-slug> comes from state.json, matching the user's language), then echo the file content verbatim to the conversation. Also update state.json with Edit (last_explained, explain_count, status, confidence). Then run render.mjs to regenerate knowledge-map.md.
 5. Identify sub-topics as recursive entry points (only AFTER saving the session and echoing to conversation)`;
 export function getLearnExplainSkillTemplate() {
     return {

package/dist/core/templates/workflows/learn-topic.js

@@ -77,7 +77,7 @@ Based on your expert understanding of "<topic-name>", generate a hierarchical kn
 - **Slug format**: lowercase kebab-case ("Scope & Closures" → "scope-closures").
 - All initial concepts: status "unexplored", confidence 0, counts 0, dates null.
 
-### Step 4: Run render.mjs to generate knowledge-map.md
+### Step 4: Run render.mjs and init-sessions.mjs
 
 \`\`\`bash
 SCRIPT=$(find . -path '*/learn-anything-topic/scripts/render.mjs' -print -quit 2>/dev/null)
@@ -86,6 +86,13 @@ node "$SCRIPT" ./.learn/topics/<topic-name>
 
 render.mjs validates state.json against the v1 schema and generates knowledge-map.md. If validation fails, fix state.json and re-run render.mjs. Do NOT manually write knowledge-map.md.
 
+\`\`\`bash
+SCRIPT=$(find . -path '*/learn-anything-topic/scripts/init-sessions.mjs' -print -quit 2>/dev/null)
+node "$SCRIPT" ./.learn/topics/<topic-name>
+\`\`\`
+
+init-sessions.mjs reads state.json and creates domain subdirectories under \`sessions/\` (based on each domain's \`slug\`). This organizes future learning session files by domain. Safe to re-run — existing directories are skipped.
+
 ### Step 5: Present the knowledge map
 
 Display the knowledge map as an ASCII tree:
@@ -124,6 +131,15 @@ Then guide the user:
 
 Read \`./.learn/topics/<topic-name>/state.json\` — state.json is the single source of truth, do NOT read knowledge-map.md or state.yaml.
 
+### Step 2.5: Run init-sessions.mjs to ensure domain directories exist
+
+\`\`\`bash
+SCRIPT=$(find . -path '*/learn-anything-topic/scripts/init-sessions.mjs' -print -quit 2>/dev/null)
+node "$SCRIPT" ./.learn/topics/<topic-name>
+\`\`\`
+
+This ensures domain subdirectories under \`sessions/\` are created (in case they were not created before or new domains were added). Safe to re-run.
+
 ### Step 3: Calculate and display progress
 
 From the domains/concepts structure, calculate: 🟢 mastered, 🔵 in progress, 🟠 needs practice, ⚪ unexplored.
@@ -158,8 +174,8 @@ const COMMAND_DESCRIPTION = 'Initialize or load a learning topic — view knowle
 const COMMAND_CONTENT = `Use the learn-anything-topic skill to handle the user's /learn <topic-name> request.
 Follow the workflow defined in the skill:
 1. Determine if the topic exists
-2. New topic: create directory structure → generate state.json (v1 with domains/concepts hierarchy) → run render.mjs to generate knowledge-map.md → present knowledge map and guide the user
-3. Existing topic: read state.json → calculate progress → give personalized recommendations`;
+2. New topic: create directory structure → generate state.json (v1 with domains/concepts hierarchy) → run render.mjs → run init-sessions.mjs → present knowledge map and guide the user
+3. Existing topic: read state.json → run init-sessions.mjs → calculate progress → give personalized recommendations`;
 export function getLearnTopicSkillTemplate() {
     return {
         name: SKILL_NAME,

package/dist/i18n/locales/en.js

@@ -24,6 +24,9 @@ export const en = {
         cmdLine: (cmd, desc) => `  ${cmd}${desc}`,
         interactiveSelectPrompt: 'Select AI tools to generate skills for (space to select, enter to confirm):',
         migrationComplete: (count) => `Migrated ${count} topic(s) from v0 to v1 format (backups created).`,
+        context7Prompt: 'Enable Context7 for documentation verification? (Provides on-demand access to official library docs)',
+        context7Enabled: '  📚 Context7 guidance enabled.',
+        context7SetupHint: '  💡 To set up Context7 MCP, run `npx ctx7 setup` or visit https://context7.com/docs/resources/all-clients',
     },
 };
 //# sourceMappingURL=en.js.map

package/dist/i18n/locales/zh-CN.js

@@ -24,6 +24,9 @@ export const zhCN = {
         cmdLine: (cmd, desc) => `  ${cmd}${desc}`,
         interactiveSelectPrompt: '选择要生成技能的 AI 工具（空格选择，回车确认）：',
         migrationComplete: (count) => `已迁移 ${count} 个主题从 v0 到 v1 格式（已创建备份）。`,
+        context7Prompt: '是否启用 Context7 进行文档验证？（提供按需访问官方库文档的能力）',
+        context7Enabled: '  📚 已启用 Context7 文档验证引导。',
+        context7SetupHint: '  💡 配置 Context7 MCP：运行 `npx ctx7 setup` 或访问 https://context7.com/docs/resources/all-clients',
     },
 };
 //# sourceMappingURL=zh-CN.js.map

package/dist/i18n/types.d.ts

@@ -24,6 +24,9 @@ export interface InitMessages {
     cmdLine: (cmd: string, desc: string) => string;
     interactiveSelectPrompt: string;
     migrationComplete: (count: number) => string;
+    context7Prompt: string;
+    context7Enabled: string;
+    context7SetupHint: string;
 }
 export interface LocaleMessages {
     cli: CLIMessages;

package/dist/scripts/init-sessions.d.mts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * init-sessions.mjs — standalone script
+ * Reads state.json (v1) and creates domain subdirectories under sessions/.
+ *
+ * Usage: node init-sessions.mjs <topic-dir>
+ *
+ * This file is compiled from src/scripts/init-sessions.mts via tsc and
+ * copied into each skill's scripts/ directory by init/update.
+ */
+import type { StateV1 } from './utils.mjs';
+export declare function initSessions(topicDir: string, state: StateV1): number;
+//# sourceMappingURL=init-sessions.d.mts.map

package/dist/scripts/init-sessions.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * init-sessions.mjs — standalone script
+ * Reads state.json (v1) and creates domain subdirectories under sessions/.
+ *
+ * Usage: node init-sessions.mjs <topic-dir>
+ *
+ * This file is compiled from src/scripts/init-sessions.mts via tsc and
+ * copied into each skill's scripts/ directory by init/update.
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateStateV1 } from './utils.mjs';
+/* ------------------------------------------------------------------ */
+/*  Init Sessions                                                     */
+/* ------------------------------------------------------------------ */
+export function initSessions(topicDir, state) {
+    const sessionsDir = join(topicDir, 'sessions');
+    // Ensure the top-level sessions/ directory exists
+    if (!existsSync(sessionsDir)) {
+        mkdirSync(sessionsDir, { recursive: true });
+    }
+    let created = 0;
+    for (const domain of state.domains) {
+        const domainDir = join(sessionsDir, domain.slug);
+        if (!existsSync(domainDir)) {
+            mkdirSync(domainDir, { recursive: true });
+            created++;
+        }
+    }
+    return created;
+}
+/* ------------------------------------------------------------------ */
+/*  CLI                                                               */
+/* ------------------------------------------------------------------ */
+function usage() {
+    const script = process.argv[1]?.split('/').pop() || 'init-sessions.mjs';
+    console.error(`Usage: node ${script} <topic-dir>`);
+    process.exit(1);
+}
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        usage();
+    }
+    const topicDir = resolve(args[0]);
+    const statePath = join(topicDir, 'state.json');
+    // 1. Read state.json
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf-8');
+    }
+    catch (error) {
+        console.error(`Error: state.json not found at ${statePath}`, error);
+        process.exit(1);
+    }
+    // 2. Parse JSON
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: Failed to parse state.json: ${msg}`);
+        process.exit(1);
+    }
+    // 3. Validate v1 format
+    const errors = validateStateV1(data);
+    if (errors.length > 0) {
+        console.error('Error: state.json validation failed:');
+        for (const e of errors) {
+            console.error(`  .${e.path}: ${e.message}`);
+        }
+        console.error('Fix the above issues in state.json and re-run init-sessions.mjs.');
+        process.exit(1);
+    }
+    const state = data;
+    // 4. Create domain subdirectories
+    const created = initSessions(topicDir, state);
+    // Summary to stdout
+    console.log(`Initialized ${state.domains.length} domain directories under sessions/ (${created} new) for "${state.topic}"`);
+}
+const isMain = process.argv[1] != null &&
+    fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isMain) {
+    main();
+}
+//# sourceMappingURL=init-sessions.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learn-anything-cli",
-  "version": "0.4.0-beta.1",
+  "version": "0.4.1",
   "description": "AI-powered recursive learning system with Socratic method and TDD practice",
   "keywords": [
     "learn-anything-cli",