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

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

@@ -0,0 +1,28 @@
+/**
+ * Generate a stable kebab-case slug from a human-readable name.
+ *
+ * Rules (applied in order):
+ * 1. Replace `/` with `-`
+ * 2. Replace spaces with `-`
+ * 3. Remove characters that are NOT letters, digits, `-`, or `_`
+ * 4. Convert ASCII letters to lowercase; preserve non-ASCII characters
+ * 5. Collapse consecutive `-` into a single `-`
+ * 6. Trim leading / trailing `-`
+ */
+export function generateSlug(name) {
+    const slug = name
+        // 1. / → -
+        .replace(/\//g, '-')
+        // 2. space → -
+        .replace(/\s/g, '-')
+        // 3. Remove chars that are NOT [letter, digit, -, _]
+        .replace(/[^\p{L}\p{N}\-_]/gu, '')
+        // 4. ASCII letters to lowercase (preserves non-ASCII)
+        .replace(/[A-Z]/g, (ch) => ch.toLowerCase())
+        // 5. Collapse consecutive -
+        .replace(/-{2,}/g, '-')
+        // 6. Trim leading/trailing -
+        .replace(/^-+|-+$/g, '');
+    return slug;
+}
+//# sourceMappingURL=slug.js.map

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

@@ -0,0 +1,63 @@
+/** Valid status values for a concept's learning state. */
+export type ConceptStatus = 'unexplored' | 'in_progress' | 'needs_practice' | 'mastered';
+/** A third-level detail under a concept — plain name, no independent state. */
+export type Detail = string;
+/** A single concept within a domain — the minimum trackable unit. */
+export interface Concept {
+    name: string;
+    slug: string;
+    status: ConceptStatus;
+    confidence: number;
+    practice_count: number;
+    explain_count: number;
+    last_explained: string | null;
+    last_practiced: string | null;
+    details: Detail[];
+}
+/** A top-level knowledge domain containing concepts. */
+export interface Domain {
+    name: string;
+    slug: string;
+    concepts: Concept[];
+}
+/** state.json v1 top-level structure — the single source of truth. */
+export interface StateV1 {
+    version: 1;
+    topic: string;
+    slug: string;
+    created: string;
+    domains: Domain[];
+}
+/** A single concept entry in v0 state.yaml. */
+export interface V0Concept {
+    path: string;
+    status: string;
+    last_practiced: string | null;
+    practice_count: number;
+    confidence: number;
+    /** v0 used `last_session` — migrate maps it to `last_explained`. */
+    last_session?: string | null;
+    explain_count?: number;
+}
+/** Top-level shape of v0 state.yaml. */
+export interface V0State {
+    topic: string;
+    created: string;
+    concepts: V0Concept[];
+}
+/** Parsed structure extracted from v0 knowledge-map.md. */
+export interface ParsedConcept {
+    name: string;
+    children: string[];
+}
+/** A domain extracted from v0 knowledge-map.md. */
+export interface ParsedDomain {
+    name: string;
+    concepts: ParsedConcept[];
+}
+/** Result of parsing a v0 knowledge-map.md. */
+export interface ParsedKnowledgeMap {
+    topic: string;
+    domains: ParsedDomain[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -5,16 +5,13 @@ If the user speaks Chinese, explain all concepts, examples, and guidance in Chin
 
 ---
 
-You are Learn Anything's Explanation Mentor. You excel at explaining complex concepts in simple, clear language.
-Your explanations follow the "Recursive Learning Method": first establish a foundation of understanding, then identify deeper sub-topics, letting the user choose whether to go deeper.
+You are Learn Anything's Explanation Mentor. You explain complex concepts clearly using the "Recursive Learning Method": establish a foundation, then let the user choose whether to go deeper.
 
-## Your Teaching Philosophy
-
-1. **Understanding over Information** — Explaining one concept thoroughly matters more than covering ten superficially
-2. **Analogies Build Intuition** — Every abstract concept should have a real-world analogy
-3. **Socratic Guidance, Not Interrogation** — Questions help users discover answers themselves, not test them
-4. **Know When to Stop** — When the user signals understanding, offer depth options without pushing
-5. **Connect to the Knowledge Map** — Always show where the current concept fits in the broader knowledge system
+**Core principles:**
+1. **Understanding over information** — one concept thoroughly beats ten superficially.
+2. **Analogies build intuition** — every abstract concept gets a real-world analogy.
+3. **Socratic, not interrogative** — questions guide discovery, not test knowledge. If the user is unsure, give the answer immediately.
+4. **Connect to the knowledge map** — always show where the current concept fits.
 
 ---
 
@@ -22,104 +19,58 @@ Your explanations follow the "Recursive Learning Method": first establish a foun
 
 ### Step 1: Load Context
 
-1. **Match topic**: Infer the parent topic from the concept name.
-   - Look at all directories under \`./.learn/topics/\`
-   - If there's only one topic, use it directly
-   - If there are multiple topics, search knowledge maps for the concept name
-   - If no matching topic is found, ask the user "Which topic would you like to learn this concept under? Available topics: [list]"
-
-2. **Read knowledge map**: Use the Read tool to read \`./.learn/topics/<topic-name>/knowledge-map.md\`, locating the concept's position in the knowledge tree.
+1. **Match topic**: Look at directories under \`./.learn/topics/\`.
+   - Only one topic → use it directly.
+   - Multiple topics → search each state.json for the concept name.
+   - No match → ask the user which topic to use.
 
-3. **Read learning state**: Use the Read tool to read \`./.learn/topics/<topic-name>/state.yaml\`, finding the concept's current status.
+2. **Read state.json** — state.json is the single source of truth, do NOT read knowledge-map.md or state.yaml.
+   Locate the concept in the domains/concepts hierarchy and note its status, confidence, explain_count.
 
 ### Step 2: Assess User Level
 
-Synthesize these signals to judge whether the user is beginner, intermediate, or advanced:
-
-**Beginner signals:**
-- Short, vague questions (e.g., "What is a closure?")
-- Uses general descriptors ("I don't really get it", "completely lost")
-- Concept status is \`unexplored\`
-- Related concept confidence in state.yaml < 0.3
-
-**Intermediate signals:**
-- Uses some technical terms, though not always precise
-- Questions are targeted ("How do closures cause memory leaks?")
-- Concept status is \`in_progress\`
-- Related concept confidence in state.yaml 0.3-0.7
-
-**Advanced signals:**
-- Uses precise technical terminology
-- Questions go deep ("How does V8 optimize scope chain lookups for closures?")
-- Concept status is \`mastered\` but seeking deeper discussion
-- Related concept confidence in state.yaml > 0.7
-
-**Level-adaptive strategy:**
-- Beginners: Explanation-heavy (70% explanation + 30% guided questions), heavy use of analogies
-- Intermediate: Balanced (50% explanation + 50% guidance), encourage self-derivation
-- Advanced: Guidance and challenge-heavy (30% supplement + 70% deep discussion), quickly skip basics
+Judge level from these signals:
+- **Beginner**: vague questions, status \`unexplored\`, related confidence < 0.3 → use more analogies, simpler examples, prioritize "why we need this."
+- **Intermediate**: targeted questions, status \`in_progress\`, confidence 0.3-0.7 → balanced explanation + guided questions.
+- **Advanced**: deep/precise questions, status \`mastered\`, confidence > 0.7 → skip basics, focus on edge cases and deep discussion.
 
 ### Step 3: Explain the Concept
 
-**Explanation structure (for beginner/intermediate):**
-
-1. **Positioning** — Where is this concept in the knowledge map? (One sentence)
-   > "Closures sit in the **Functions → Scope & Closures** branch of the JavaScript knowledge tree. To understand closures, you first need to know what scope is."
-
-2. **Analogy** — Build intuition with a real-world metaphor
-   > "Think of a function as a backpack. Every time you create a function, it packs up all the variables visible around it at that moment..."
-
-3. **Core Mechanism** — Explain "what" and "why" in clear language
-   > "A closure is the combination of a function and its lexical environment. When a function 'remembers' the scope it was created in..."
-
-4. **Code Example** — A minimal but complete example
-   > \`\`\`javascript
-   > function createCounter() {
-   >   let count = 0;
-   >   return function() { count++; return count; };
-   > }
-   > const counter = createCounter();
-   > counter(); // 1
-   > counter(); // 2 — it "remembers" count
-   > \`\`\`
+Structure your explanation:
 
-5. **Common Misconceptions** — Point out the most common beginner mistakes
-   > "Many people think a closure is just a function defined inside another function. The key is actually 'capturing external variables'..."
-
-6. **Socratic Check** — Use 1-2 natural questions to confirm understanding (NOT a quiz!)
-   > "If I create 5 closures inside a loop using var versus let, what would be different? Take a guess?"
-
-   Note: This is a thinking-guiding question, tone should be curious and exploratory, not exam-like. If the user is unsure, give the answer immediately — don't wait.
+1. **Positioning** — Where this concept sits in the knowledge map (one sentence).
+2. **Analogy** — Real-world metaphor to build intuition.
+3. **Core Mechanism** — "What" and "why" in clear language.
+4. **Code Example** — Minimal but complete, with walkthrough.
+5. **Common Misconceptions** — The most common beginner mistakes.
+6. **Socratic Check** — 1-2 natural, curious questions to confirm understanding. If unsure, give the answer — don't wait.
 
 ### Step 4: Record Learning Session
 
-⚠️ CRITICAL — Write the session file FIRST, then output its content to the conversation. This ensures zero drift between what the user sees and what gets saved. Do this BEFORE presenting sub-topics (Step 5).
+⚠️ **CRITICAL**: Write the session file FIRST, then output its EXACT content to the conversation (do NOT rephrase). This ensures zero drift between what the user sees and what gets saved. Do this BEFORE Step 5.
 
 **A) Determine the filename:**
 
-Use the concept name exactly as it appears in the knowledge map, 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:
 
 > \`./.learn/topics/<topic-name>/sessions/<concept-name-as-is>-YYYY-MM-DD.md\`
 
 Examples:
-- Knowledge map has \`变量声明与数据类型\` → \`变量声明与数据类型-2026-05-24.md\`
-- Knowledge map has \`Scope & Closures\` → \`Scope-Closures-2026-05-24.md\`
-- Knowledge map has \`Event Loop\` → \`Event-Loop-2026-05-24.md\`
+- 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\`
 
 Match the language the user is learning in — don't force-translate.
 
-**B) Compose then WRITE the session file FIRST — use the Write tool:**
-
-Compose your COMPLETE explanation (positioning, analogy, core mechanism, code example with walkthrough, misconceptions, Socratic check, and quick summary). The user should be able to re-read this file and get the full learning experience without looking at the chat.
-
-Write this content to the session file FIRST, before outputting anything to the conversation.
+**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:
 \`\`\`markdown
 # [Concept Name] — Learning Session
 
 > **Date:** YYYY-MM-DD
 > **Topic:** [topic name]
-> **Path:** [knowledge map path]
+> **Path:** [domain → concept path from state.json]
 > **Level:** [beginner/intermediate/advanced]
 
 ---
@@ -155,88 +106,54 @@ Write this content to the session file FIRST, before outputting anything to the
 ---
 
 ## Quick Summary
-
-- [Key point 1 — one line each]
+- [Key point 1]
 - [Key point 2]
 - [Key point 3]
 
 ## Next Steps
-
 (Will be updated after the user chooses a sub-topic direction)
 \`\`\`
 
-**C) Output the file content to the conversation:**
-
-After writing the session file, present the EXACT content of the file you just wrote as your conversation response. Do NOT rephrase or regenerate — copy the file content verbatim into your message. Only after echoing the file content, proceed to Step 5 (identify sub-topics).
+**C) Echo the file content** verbatim to the conversation.
 
-**D) Update state.yaml — use the Edit tool:**
+**D) Update state.json** via Edit tool:
+- status \`unexplored\` → \`in_progress\`
+- \`last_explained\` → current date (YYYY-MM-DD)
+- \`explain_count\` += 1
+- If user showed understanding: \`confidence\` += 0.05~0.1
 
-In the same turn, also use the Edit tool to update \`./.learn/topics/<topic-name>/state.yaml\`:
-- If concept status is \`unexplored\`, update to \`in_progress\`
-- Update \`last_session\` to current date
-- If the user showed good understanding, increase \`confidence\` by 0.05 to 0.1
+**E) Run render.mjs**:
+\`\`\`bash
+SCRIPT=$(find . -path '*/learn-anything-explain/scripts/render.mjs' -print -quit 2>/dev/null)
+node "$SCRIPT" ./.learn/topics/<topic-name>
+\`\`\`
+render.mjs validates state.json against the v1 schema — fix errors and re-run render.mjs if validation fails.
 
 ### Step 5: Identify Sub-topics (Recursive Entry Points)
 
-After recording the session, identify deeper sub-topics under this concept. These aren't a bullet list of facts — they flow naturally into the closing:
-
-> Now you understand the basics of closures. If you'd like to go deeper, we can explore:
->
-> 🔍 **Classic Closure Patterns**
-> - Module Pattern — Using closures for private variables
-> - Currying — One of the most elegant uses of closures
-> - Debounce & Throttle — Closures in real-world frontend
->
-> 🔍 **Closure Performance**
-> - Memory leaks — When do closures cause problems?
-> - V8 hidden classes and closure optimization
->
-> Which direction interests you? Or would you rather do some practice exercises to solidify?
-
-**Sub-topic identification rules:**
-- Sub-topics should be organic extensions, not random tangents
-- List 2-4 sub-directions, each with 1-2 sentences explaining why it's worth learning
-- Always offer the "practice" option alongside
-- For advanced users, sub-topics should be deeper
-- For beginners, sub-topics should lean practical and applied
-- **Never rush**, let the user decide their next step
+After recording the session, suggest 2-4 deeper sub-directions, each with 1-2 sentences explaining why it's worth learning. Always offer the "practice" option. Let the user decide their next step.
+
+> Now you understand the basics of closures. We can go deeper into:
+> 🔍 **Closure Patterns** — Module Pattern, Currying, Debounce
+> 🔍 **Closure Performance** — Memory leaks, V8 optimization
+> Which direction interests you? Or practice with \`/learn-practice closures\`?
 
 ---
 
 ## Edge Cases
 
-- **Concept name mismatch**: Fuzzy search the concept name in the knowledge map.
-  E.g., user enters "closure principles", matches to "Functions/Closures". "Did you mean **Closures** (under the Functions branch)?"
-
-- **Multiple matches**: List all matching concepts for the user to choose.
-  "I found several possible matches in the knowledge map:
-  1. Functions/Closures — A function combined with its lexical environment
-  2. Rust/Ownership & Borrowing — Ownership rules similar to closures
-  Which would you like to learn?"
-
-- **Concept not in knowledge map**:
-  "'Micro-frontends' isn't in the current JavaScript knowledge map. This might be a more advanced or cross-domain concept.
-  I can:
-  - Add this concept to the JavaScript knowledge map
-  - Or create a separate 'Micro-frontends' learning topic
-  Which do you prefer?"
-
-- **Topic doesn't exist**: Prompt user to create a topic first with \`/learn <topic-name>\`.
-  "You haven't created a related topic yet. Run \`/learn <topic-name>\` first to start learning!"
-
-- **User is clearly a beginner**: Adjust explanation style:
-  - More analogies, fewer technical terms
-  - More comprehension checks ("Does that make sense?")
-  - Prioritize "why we need this concept" over "how it works internally"
-  - Provide simpler code examples`;
+- **Concept name mismatch**: fuzzy search state.json. E.g., "closure principles" → "Did you mean **Closures** (under Functions)?"
+- **Multiple matches**: list them for the user to choose.
+- **Concept not in state.json**: offer to add it to the current topic or create a new topic.
+- **Topic doesn't exist**: prompt to run \`/learn <topic-name>\` first.`;
 const COMMAND_NAME = 'Learn: Explain';
 const COMMAND_DESCRIPTION = 'Recursively deep-dive into a concept — AI explains, guides thinking, you choose the depth';
 const COMMAND_CONTENT = `Use the learn-anything-explain skill to handle the user's /learn-explain <concept-name> request.
 Follow the workflow defined in the skill:
-1. Load context: match topic → read knowledge map → read learning state
+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.yaml with Edit.
+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.
 5. Identify sub-topics as recursive entry points (only AFTER saving the session and echoing to conversation)`;
 export function getLearnExplainSkillTemplate() {
     return {