learn-anything-cli 0.4.0 → 0.4.2

package/README.md

@@ -43,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
 
@@ -81,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

@@ -41,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>` — 递归式深度学习
 
@@ -79,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/core/init.js

@@ -162,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'));

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-practice.js

@@ -1,5 +1,5 @@
 const SKILL_NAME = 'learn-anything-practice';
-const SKILL_DESCRIPTION = 'Master concepts through hands-on practice. Coding topics get real project files to edit in your IDE; conceptual topics get chat-based discussion. Dual-mode: Project Mode + Chat Mode.';
+const SKILL_DESCRIPTION = 'Master concepts through hands-on practice. Coding topics get real project files to edit in your IDE; conceptual topics get chat-based discussion. Dual-mode (Project Mode + Chat Mode).';
 const INSTRUCTIONS = `Always respond in the same language the user uses.
 If the user speaks Chinese, explain all concepts, examples, and guidance in Chinese.
 

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/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",
+  "version": "0.4.2",
   "description": "AI-powered recursive learning system with Socratic method and TDD practice",
   "keywords": [
     "learn-anything-cli",