catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/teach/references/analogy-library.md

@@ -0,0 +1,153 @@
+# Analogy Library
+
+A curated collection of analogies mapping complex concepts to familiar mental models.
+Each analogy is tested for accuracy and memorability.
+
+---
+
+## Technology & Computing
+
+### Computer → Library
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Computer | Library | A place that stores and processes information |
+| CPU | Librarian | Responsible for finding, processing, and distributing information |
+| Memory (RAM) | Reading table | Temporarily holds books being read, fast but limited capacity |
+| Hard Drive | Bookshelves | Long-term storage for all books, large capacity but slower |
+| Operating System | Library management system | Coordinates all resources, keeps everything running smoothly |
+| Software | Books | Specific knowledge and instructions |
+| Internet | Interlibrary loan | Borrowing books from other libraries |
+
+### Programming → Cooking
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Code | Recipe | Step-by-step instructions |
+| Variable | Ingredient | Holds specific things |
+| Function | Cooking step | Process of turning ingredients into dishes |
+| Loop | Repetitive action | "Stir until mixed" |
+| Condition | Judgment | "If done, serve" |
+| Bug | Failed dish | Instructions went wrong, result is incorrect |
+| Debug | Finding the cause | Checking which step went wrong |
+
+### Data → Water System
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Data | Water | Flowing information |
+| Database | Reservoir | Stores large amounts of data |
+| API | Water pipe | Channel for data transmission |
+| Cache | Water tower | Temporary storage for quick access |
+| Stream | Water flow | Continuous data |
+| Batch | Bucket | Process a batch at once |
+
+---
+
+## Business & Management
+
+### Project Management → Navigation
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Project | Journey | From start to finish |
+| Deadline | Destination | Must arrive by |
+| Milestone | Road sign | Marks progress |
+| Risk | Roadblock | May hinder progress |
+| Resource | Fuel | What's needed to complete the journey |
+| Budget | Budget | Total available resources |
+
+### Team → Orchestra
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Team | Orchestra | Different roles collaborating to create |
+| Manager | Conductor | Coordinates everyone |
+| Specialist | Instrumentalist | Focuses on one area |
+| Communication | Sheet music | Shared language |
+| Deadline | Performance time | Must be ready by |
+| Feedback | Applause/criticism | Tells you how you did |
+
+---
+
+## Science & Nature
+
+### Evolution → Software Iteration
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Evolution | Version iteration | Gradual improvement |
+| Natural Selection | User feedback | Good stays, bad gets淘汰 |
+| Mutation | Bug | Unexpected change |
+| Adaptation | Feature optimization | Adjusting to environment |
+| Extinction | Deprecated feature | No longer used |
+
+### Ecosystem → Market
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Ecosystem | Market | Various parties interdependent |
+| Producer | Supplier | Provides products/services |
+| Consumer | User | Uses products/services |
+| Competition | Competition | Competing for resources |
+| Symbiosis | Cooperation | Mutual benefit |
+
+---
+
+## Learning & Education
+
+### Learning a Skill → Building a House
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Foundation | Basic knowledge | Must be solid before building |
+| Framework | Core concepts | The structure that holds everything |
+| Walls | Specific skills | Fill in the details |
+| Roof | Advanced mastery | Completes the picture |
+| Renovation | Continuous improvement | Always room to improve |
+
+### Understanding → Tree
+
+| Technical Concept | Analogy | Details |
+|---|---|---|
+| Roots | Fundamentals | Hidden but essential |
+| Trunk | Core principles | Everything connects to this |
+| Branches | Specific topics | Diversify from the core |
+| Leaves | Details | Change frequently, but support growth |
+| Fruit | Application | The practical result of understanding |
+
+---
+
+## Usage Notes
+
+- Pick **ONE** analogy per concept per session — don't mix metaphors
+- If a learner responds with confusion, switch to an alternative analogy
+- Analogies are **entry points**, not endpoints — always follow up with the real mechanism
+- Mark analogies as 🟡 (rough match) vs 🟢 (very close match) when the mapping isn't perfect
+- When an analogy breaks down, say so honestly: "This analogy doesn't hold up here, actually..."
+- **CRITICAL**: All analogies must be culturally appropriate and universally understandable
+
+---
+
+## Adding New Analogies
+
+When creating new analogies:
+
+1. **Test for accuracy**: Does the analogy actually map correctly?
+2. **Test for memorability**: Will learners remember it?
+3. **Test for universality**: Does it work across cultures?
+4. **Note limitations**: Where does the analogy break down?
+5. **Provide alternatives**: Have backup analogies ready
+
+---
+
+## Example Usage
+
+**Teaching about variables**:
+> "Think of a variable like a labeled box. You can put things in it, take things out, and change what's inside. The label (variable name) helps you find it later."
+
+**Teaching about functions**:
+> "A function is like a recipe. You give it ingredients (parameters), it follows steps (code), and gives you a dish (return value). You can use the same recipe many times."
+
+**Teaching about loops**:
+> "A loop is like washing dishes. You pick up a dish, wash it, dry it, put it away, then repeat for the next dish until you're done."

package/dist/extensions/builtin/teach/references/learning-paths.md

@@ -0,0 +1,214 @@
+# Learning Paths
+
+Structured curricula for learners at different levels.
+Each path is a recommended sequence of topics that build on each other.
+
+---
+
+## Path A: Foundations (L0 → L1)
+
+For learners with zero knowledge who want to understand the basics.
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| A1 | What is this field? | 5 min | — |
+| A2 | Core concepts | 10 min | A1 |
+| A3 | Basic terminology | 10 min | A2 |
+| A4 | Simple applications | 15 min | A3 |
+| A5 | Common patterns | 15 min | A4 |
+| A6 | Putting it together | 15 min | A1-A5 |
+
+**Total**: ~70 minutes across multiple sessions. Recommend 1-2 topics per day.
+
+### Example: Learning Cooking
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| A1 | What is cooking? | 5 min | — |
+| A2 | Essential tools | 10 min | A1 |
+| A3 | Basic techniques | 10 min | A2 |
+| A4 | Simple recipes | 15 min | A3 |
+| A5 | Flavor combinations | 15 min | A4 |
+| A6 | First complete meal | 15 min | A1-A5 |
+
+---
+
+## Path B: Practical Skills (L1 → L2)
+
+For learners who know basics and want to apply knowledge practically.
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| B1 | Real-world scenarios | 15 min | A* |
+| B2 | Problem-solving patterns | 15 min | B1 |
+| B3 | Tools and techniques | 15 min | B2 |
+| B4 | Best practices | 20 min | B3 |
+| B5 | Common mistakes | 10 min | B4 |
+| B6 | Hands-on practice | 20 min | B1-B5 |
+
+**Total**: ~95 minutes across multiple sessions.
+
+### Example: Cooking Intermediate
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| B1 | Meal planning | 15 min | A* |
+| B2 | Ingredient selection | 15 min | B1 |
+| B3 | Advanced techniques | 15 min | B2 |
+| B4 | Kitchen efficiency | 20 min | B3 |
+| B5 | Troubleshooting dishes | 10 min | B4 |
+| B6 | Cooking for others | 20 min | B1-B5 |
+
+---
+
+## Path C: Deep Understanding (L2 → L3)
+
+For advanced learners who want to understand system-level decisions.
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| C1 | Advanced concepts | 20 min | B* |
+| C2 | Architecture patterns | 15 min | C1 |
+| C3 | Performance considerations | 15 min | C2 |
+| C4 | Trade-offs and decisions | 15 min | C3 |
+| C5 | Industry trends | 20 min | C4 |
+| C6 | Expert techniques | 20 min | C1-C5 |
+
+**Total**: ~105 minutes across multiple sessions.
+
+### Example: Cooking Advanced
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| C1 | Cuisine theory | 20 min | B* |
+| C2 | Menu design | 15 min | C1 |
+| C3 | Nutrition science | 15 min | C2 |
+| C4 | Cost optimization | 15 min | C3 |
+| C5 | Food trends | 20 min | C4 |
+| C6 | Restaurant techniques | 20 min | C1-C5 |
+
+---
+
+## How to Use
+
+1. **Assess learner level** first (see teach-runtime.ts § Learner Level Detection)
+2. **Recommend a path**: "Based on your foundation, I recommend starting with Path A"
+3. **Go topic by topic**: Each topic is independent enough to pause/resume
+4. **After each topic**: Summarize key takeaways, suggest next topic
+5. **Adjust pace**: If a topic feels too easy → skip to next. Too hard → explain specific confusion
+6. **Track progress**: Use Session Memory to note completed topics and suggest next
+
+---
+
+## Quick Start Recommendations
+
+| Learner says | Recommend |
+|---|---|
+| "I know nothing about this" | Path A, start at A1 |
+| "I want to learn basic operations" | Path B, start at B1 |
+| "I want deep understanding" | Path C, start at C1 |
+| "I just want to learn one specific thing" | Direct teaching, no path |
+| "I want systematic learning" | Recommend Path A/B/C based on level |
+
+---
+
+## Custom Paths
+
+Learners can create custom paths:
+
+1. Ask learner what they want to achieve
+2. Break down into logical sequence
+3. Estimate duration for each topic
+4. Create custom path document
+5. Track progress in session memory
+
+---
+
+## Path Selection Guide
+
+### When to recommend Path A (Foundations)
+- Learner says "I know nothing"
+- Learner uses basic terminology incorrectly
+- Learner asks very basic questions
+- No prior experience mentioned
+
+### When to recommend Path B (Practical Skills)
+- Learner knows the basics
+- Learner wants to apply knowledge
+- Learner asks "how to" questions
+- Some experience mentioned
+
+### When to recommend Path C (Deep Understanding)
+- Learner already has practical experience
+- Learner asks "why" questions
+- Learner wants to understand trade-offs
+- Significant experience mentioned
+
+---
+
+## Progress Tracking
+
+Track progress across sessions:
+
+```markdown
+## Learning Progress
+
+### Current Path: Path B (Practical Skills)
+
+| # | Topic | Status | Date | Notes |
+|---|-------|--------|------|-------|
+| B1 | Real-world scenarios | ✅ Completed | 2026-06-10 | Good understanding |
+| B2 | Problem-solving patterns | 🔄 In Progress | 2026-06-10 | Need more examples |
+| B3 | Tools and techniques | ⏳ Not Started | — | — |
+| B4 | Best practices | ⏳ Not Started | — | — |
+| B5 | Common mistakes | ⏳ Not Started | — | — |
+| B6 | Hands-on practice | ⏳ Not Started | — | — |
+```
+
+---
+
+## Adapting Paths
+
+Paths are guidelines, not rigid rules. Adapt based on:
+
+1. **Learner's pace**: If they're fast, skip ahead. If slow, add more examples.
+2. **Learner's interests**: If they're more interested in one area, spend more time there.
+3. **Learner's goals**: If they have a specific goal, focus on relevant topics.
+4. **Learner's feedback**: If they say "I already know this", move on.
+
+---
+
+## Example: Learning Catui
+
+### Path A: Catui Basics (L0 → L1)
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| A1 | What is Catui? | 5 min | — |
+| A2 | Basic commands | 10 min | A1 |
+| A3 | Navigation and files | 10 min | A2 |
+| A4 | Simple conversations | 15 min | A3 |
+| A5 | Using tools | 15 min | A4 |
+| A6 | First real task | 15 min | A1-A5 |
+
+### Path B: Catui Intermediate (L1 → L2)
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| B1 | Session management | 15 min | A* |
+| B2 | Custom configurations | 15 min | B1 |
+| B3 | Advanced tools | 15 min | B2 |
+| B4 | Extensions | 20 min | B3 |
+| B5 | Troubleshooting | 10 min | B4 |
+| B6 | Real-world workflow | 20 min | B1-B5 |
+
+### Path C: Catui Advanced (L2 → L3)
+
+| # | Topic | Duration | Builds On |
+|---|-------|----------|-----------|
+| C1 | Architecture deep dive | 20 min | B* |
+| C2 | Custom extensions | 15 min | C1 |
+| C3 | Performance optimization | 15 min | C2 |
+| C4 | Integration patterns | 15 min | C3 |
+| C5 | Contributing to Catui | 20 min | C4 |
+| C6 | Expert techniques | 20 min | C1-C5 |

package/dist/extensions/builtin/teach/references/source-verification.md

@@ -0,0 +1,268 @@
+# Source Verification Rules
+
+Every factual claim in teaching must have a verifiable source.
+This ensures accuracy and builds learner trust.
+
+---
+
+## Source Hierarchy
+
+| Level | Source Type | Confidence | Example |
+|-------|------------|------------|---------|
+| 1 | Official documentation | ⭐⭐⭐⭐⭐ | Official guides, documentation |
+| 1 | Peer-reviewed papers | ⭐⭐⭐⭐⭐ | Academic papers, research reports |
+| 1 | Government/regulatory sources | ⭐⭐⭐⭐⭐ | Official statistics, regulatory documents |
+| 2 | Recognized industry experts | ⭐⭐⭐⭐ | Well-known experts, industry leaders |
+| 2 | Established educational institutions | ⭐⭐⭐⭐ | Universities, research institutions |
+| 2 | Well-known publications | ⭐⭐⭐⭐ | Authoritative media, professional journals |
+| 3 | Community sources (high-voted) | ⭐⭐⭐ | Stack Overflow, Reddit high-vote answers |
+| 3 | Open source projects | ⭐⭐⭐ | GitHub projects, official examples |
+| 4 | Blog posts, tutorials | ⭐⭐ | Personal blogs, tutorial websites |
+| 5 | User-generated content | ⭐ | Forum posts, comments |
+
+---
+
+## Citation Format
+
+Every factual claim must include:
+
+```markdown
+**Claim**: [Claim being made]
+**Source**: [Source Name](URL)
+**Confidence**: ⭐⭐⭐⭐⭐ (Reason for this confidence level)
+**Verification method**: [How this was verified - web search, official docs, user confirmation]
+```
+
+### Example
+
+```markdown
+**Claim**: Pasta should be cooked in salted water
+**Source**: [Barilla Official Guide](https://www.barilla.com/en-us/help/cooking-pasta)
+**Confidence**: ⭐⭐⭐⭐⭐ (Official authoritative source)
+**Verification method**: Official documentation confirmed
+```
+
+---
+
+## When Source is Unavailable
+
+If no reliable source can be found:
+
+1. **Use web search** to verify the claim
+2. **Ask the learner** to confirm if they have prior knowledge
+3. **Mark as unverified**:
+
+```markdown
+**Claim**: [Claim]
+**Source**: No reliable source available
+**Confidence**: ⭐ (Pending verification)
+**Verification method**: Requires user confirmation or further search
+```
+
+---
+
+## Source Verification Process
+
+Before stating a fact:
+
+1. **Check if you know the source** (official docs, established knowledge)
+2. **If uncertain**, use web search to verify
+3. **If still uncertain**, ask the learner:
+   - "I need to verify this claim. Have you seen this information elsewhere?"
+   - "Let me search for the latest information to confirm"
+4. **If no source found**, mark as unverified and suggest the learner verify independently
+
+---
+
+## Red Flags
+
+Never use these as primary sources:
+
+- ❌ Unverified social media posts
+- ❌ Anonymous forum answers without citations
+- ❌ Outdated information (>2 years for fast-moving topics)
+- ❌ Marketing materials disguised as education
+- ❌ Personal opinions presented as facts
+
+---
+
+## Special Cases
+
+### Historical Facts
+- Use official records, academic sources
+- Mark confidence based on source reliability
+
+### Technical Skills
+- Use official documentation, established tutorials
+- Prefer hands-on examples over theoretical explanations
+
+### Personal Preferences
+- No source needed for subjective topics
+- Clearly mark as "preference" not "fact"
+
+### Controversial Topics
+- Present multiple perspectives
+- Cite sources for each perspective
+- Let the learner form their own opinion
+
+---
+
+## Confidence Levels Explained
+
+### ⭐⭐⭐⭐⭐ (Very High Confidence)
+- Official documentation from the source
+- Peer-reviewed academic papers
+- Government/regulatory documents
+- Well-established facts
+
+**When to use**: When the source is authoritative and the information is well-documented.
+
+### ⭐⭐⭐⭐ (High Confidence)
+- Recognized industry experts
+- Established educational institutions
+- Well-known professional publications
+- Widely accepted best practices
+
+**When to use**: When the source is reputable but not the primary authority.
+
+### ⭐⭐⭐ (Medium Confidence)
+- Community sources with high votes/engagement
+- Open source projects with active maintenance
+- Multiple corroborating sources
+- Established conventions
+
+**When to use**: When information comes from community consensus.
+
+### ⭐⭐ (Low Confidence)
+- Personal blogs without citations
+- Tutorial websites without author credentials
+- Outdated information
+- Single-source claims
+
+**When to use**: When no better source exists, with appropriate caveats.
+
+### ⭐ (Very Low Confidence)
+- Unverified user-generated content
+- Anonymous sources
+- Conflicting information
+- Speculation
+
+**When to use**: Only when explicitly marked as unverified, with recommendation to verify.
+
+---
+
+## Source Quality Checklist
+
+Before citing a source, verify:
+
+- [ ] **Authority**: Is the source authoritative on this topic?
+- [ ] **Accuracy**: Is the information accurate and verifiable?
+- [ ] **Currency**: Is the information up-to-date?
+- [ ] **Coverage**: Does it cover the topic adequately?
+- [ ] **Objectivity**: Is it unbiased and objective?
+
+---
+
+## Handling Conflicting Sources
+
+When sources conflict:
+
+1. **Present both perspectives** with their sources
+2. **Note the conflict** explicitly
+3. **Recommend verification** by the learner
+4. **Explain why** one source might be more reliable
+
+Example:
+```markdown
+**Note**: There are different perspectives on this:
+
+**View A**: [Source A](url) suggests X
+**View B**: [Source B](url) suggests Y
+
+The conflict arises because [reason]. For your use case, [recommendation].
+```
+
+---
+
+## Source Verification Tools
+
+When available, use these tools to verify sources:
+
+1. **Web search**: Search for the claim to find corroborating sources
+2. **Official documentation**: Check the official docs for the topic
+3. **Expert opinions**: Look for recognized experts in the field
+4. **Community consensus**: Check Stack Overflow, Reddit, etc.
+5. **Academic sources**: For scientific claims, check peer-reviewed papers
+
+---
+
+## Example Source Citations
+
+### Technology Topic
+```markdown
+**Claim**: React uses a virtual DOM for performance
+**Source**: [React Official Documentation](https://reactjs.org/docs/faq-internals.html)
+**Confidence**: ⭐⭐⭐⭐⭐ (Official documentation)
+**Verification method**: Direct from React team
+```
+
+### Cooking Topic
+```markdown
+**Claim**: Salt raises the boiling point of water
+**Source**: [Serious Eats](https://www.seriouseats.com/2014/10/does-salt-make-water-boil-faster.html)
+**Confidence**: ⭐⭐⭐⭐ (Reputable food science source)
+**Verification method**: Food science explanation with citations
+```
+
+### Business Topic
+```markdown
+**Claim**: Agile methodology improves project success rates
+**Source**: [PMI Pulse of the Profession](https://www.pmi.org/learning/library)
+**Confidence**: ⭐⭐⭐⭐ (Professional organization research)
+**Verification method**: Industry research report
+```
+
+---
+
+## Teaching with Sources
+
+When teaching, integrate sources naturally:
+
+1. **State the fact**: "Pasta should be cooked al dente"
+2. **Provide the source**: "According to Barilla's official guide..."
+3. **Explain the confidence**: "This is a high-confidence source because..."
+4. **Encourage verification**: "You can verify this yourself by..."
+
+This builds trust and teaches critical thinking.
+
+---
+
+## Source Verification Workflow
+
+```mermaid
+graph TD
+    A[Start: Make a claim] --> B{Do you know the source?}
+    B -->|Yes| C[Verify source quality]
+    B -->|No| D[Search for source]
+    C --> E{Source reliable?}
+    D --> E
+    E -->|Yes| F[Cite source with confidence]
+    E -->|No| G[Search for better source]
+    G --> H{Found better source?}
+    H -->|Yes| F
+    H -->|No| I[Mark as unverified]
+    I --> J[Ask learner to verify]
+    F --> K[Continue teaching]
+    J --> K
+```
+
+---
+
+## Maintaining Source Quality
+
+Over time:
+
+1. **Update sources** when better ones become available
+2. **Remove outdated** sources
+3. **Add new sources** as you learn more
+4. **Track source quality** to improve future citations