@swifty.js/swifty 0.0.1-canary

package/dist/anthropic-IS6JB2DP.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { createRequire as __swiftyCreateRequire } from "node:module";
+const require = __swiftyCreateRequire(import.meta.url);
+import{g as w}from"./chunk-H7VXSMJR.js";import{$ as K,L as x,N as P,O,P as v,Q as f,R as S,X as j,Y as I,Z as U,_ as $,aa as g,ba as W,da as B,e as L,ea as M,p as N}from"./chunk-XWWKIJ5J.js";import"./chunk-NCPOPA4A.js";import"./chunk-X3UA5OZL.js";var d=L({module:"llm"});var F=3e3,G=x.object({max_input_tokens:x.preprocess(n=>{if(n==null||n===""||n===!1)return g;let t=Number(n);return Number.isFinite(t)&&t>0?t:g},x.number().positive())});async function et(n){if(n.protocol!=="anthropic")return 0;let t=M(n),o=`${n.base_url.replace(/\/+$/,"")}/v1/models/${encodeURIComponent(n.model)}`,r=new AbortController,i=setTimeout(()=>{r.abort()},F);try{let l=await fetch(o,{method:"GET",headers:{"anthropic-version":"2023-06-01",...t?{"x-api-key":t}:{}},signal:r.signal});if(!l.ok)return g;let y=await l.json(),{success:h,data:k}=await N(G,y);return h?k.max_input_tokens:g}catch(l){return d.error({err:l},"llm operation failed"),g}finally{clearTimeout(i)}}function H(){return!0}function Y(n){let t=[];for(let e of n)if(e.role==="assistant"){let o=[];if(e.thinkingBlocks)for(let r of e.thinkingBlocks)o.push({type:"thinking",thinking:r.thinking,signature:r.signature});if(e.content&&o.push({type:"text",text:e.content}),e.toolUses)for(let r of e.toolUses)o.push({type:"tool_use",id:r.toolUseId,name:r.toolName,input:r.arguments});o.length===0&&o.push({type:"text",text:""}),t.push({role:"assistant",content:o})}else if(e.toolResults&&e.toolResults.length>0){let o=[];for(let r of e.toolResults)o.push({type:"tool_result",tool_use_id:r.toolUseId,is_error:r.isError,content:r.content});t.push({role:"user",content:o})}else{if(t.length===0){t.push({role:"user",content:[{type:"text",text:e.content}]});continue}let o=!1,r=t[t.length-1],i=r.content;r.role==="user"&&(typeof i=="string"||Array.isArray(i)&&i.length>0&&i[0].type==="text")&&(o=!0),o?(typeof i=="string"&&(i=r.content=i.trim().length>0?[{type:"text",text:i}]:[]),i.push({type:"text",text:e.content})):t.push({role:"user",content:[{type:"text",text:e.content}]})}return t}var D=class{client;model;thinking;systemPrompt;maxOutputTokens;contextWindow;constructor(t,e){let o=M(t);if(!o)throw new I("Anthropic API key not found, set ANTHROPIC_API_KEY in .swifty/config.y(a)ml, or via ANTHROPIC_API_KEY env variable.");this.client=new w({apiKey:o,baseURL:t.base_url}),this.model=t.model,this.thinking=t.thinking??!0,this.systemPrompt=e,this.maxOutputTokens=B(t),this.contextWindow=W(t)}setMaxOutputTokens(t){this.maxOutputTokens=t}async*stream(t,e,o){let r=Y(t.getMessages()),i=e.map(c=>{let p=c.input_schema;return{name:c.name,description:c.description,input_schema:{type:"object",properties:p.properties,required:p.required??[]}}});i.length>0&&(i[i.length-1].cache_control={type:"ephemeral"}),q(r);let l={model:this.model,max_tokens:this.maxOutputTokens,stream:!0,system:[{type:"text",text:this.systemPrompt,cache_control:{type:"ephemeral"}}],messages:r,...i.length>0?{tools:i}:{}};this.thinking?H()&&(l.thinking={type:"enabled",budget_tokens:this.maxOutputTokens-1}):l.thinking={type:"enabled",budget_tokens:this.maxOutputTokens-1};let y=0,h=0,k=0,R=0,C="end_turn",b="",T="",A=!1,E=0;try{let c=this.client.messages.stream(l,{...o?{signal:o}:{}}),p="",_="",u="";for await(let a of c)switch(a.type){case"content_block_start":{let s=a.content_block;s.type==="thinking"?(A=!0,b="",T=""):s.type==="tool_use"&&(_=s.id,p=s.name,u="",yield{type:"tool_call_start",toolName:p,toolId:_});break}case"content_block_delta":{let s=a.delta;s.type==="thinking_delta"?(b+=s.thinking,yield{type:"thinking_delta",text:s.thinking}):s.type==="signature_delta"?(d.debug({signature:s.signature},"thinking signature received"),T=s.signature):s.type==="text_delta"?yield{type:"text_delta",text:s.text}:s.type==="input_json_delta"&&(u+=s.partial_json,yield{type:"tool_call_delta",text:s.partial_json});break}case"content_block_stop":{if(A&&(yield{type:"thinking_complete",thinking:b,signature:T},A=!1),p){let s={};if(u)try{let m=JSON.parse(u);s=O(m)?v(m):{[P]:u}}catch(m){d.error({err:m},"llm operation failed"),s={[P]:u}}yield{type:"tool_call_complete",toolId:_,toolName:p,arguments:s},p="",_="",u=""}break}case"message_delta":{a.delta.stop_reason&&(C=a.delta.stop_reason),a.usage.output_tokens&&(h=a.usage.output_tokens);break}case"message_start":{E=performance.now(),y=a.message.usage.input_tokens,h=a.message.usage.output_tokens,k=a.message.usage.cache_read_input_tokens??0,R=a.message.usage.cache_creation_input_tokens??0;break}case"message_stop":{let m=performance.now()-E;d.debug({elapsedMs:m},"message stream complete");break}}yield{type:"stream_end",stopReason:C,usage:{inputTokens:y,outputTokens:h,cacheReadInputTokens:k,cacheCreationInputTokens:R}}}catch(c){throw d.error({err:c},"llm operation failed"),J(c)}}};function q(n){for(let t=n.length-1;t>=0;t--){if(n[t].role!=="user")continue;let e=n[t].content;if(typeof e=="string"&&e.length===0||Array.isArray(e)&&e.length===0)return;typeof e=="string"&&(e=n[t].content=[{type:"text",text:e}]);let o=e[e.length-1];Reflect.set(o,"cache_control",{type:"ephemeral"})}}function J(n){if(n instanceof w.APIError){if(n.status===413||/prompts?\s+too\s+long/i.test(n.message))return new K(`Prompt too long: ${n.message}`);if(n.status===401)return new I(`Invalid API key: ${n.message}`);if(n.status===429){let t=v(n.headers)["retry-after"],e="Rate Limited";if(t){let o=Number.parseInt(f(t));Number.isNaN(o)&&(e+=", please wait."),e+=`, retry after ${f(o)}s.`}else e+=", please wait.";return new U(e,t?f(t):void 0)}return new j(`Anthropic API error (${f(n.status)}): ${n.message}`)}return new $(`Network error: ${S(n)}`)}export{D as AnthropicClient,Y as buildAnthropicMessages,et as fetchModelContextWindow};

package/dist/builtin/commit/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: commit
+description: Analyze git diff and produce a conventional commit
+mode: inline
+allowed_tools:
+  - Bash
+  - ReadFile
+  - Grep
+---
+
+# Task
+
+You are creating a git commit for the user.
+
+## Steps
+
+1. Run `git status` to see what has changed.
+2. Run `git diff` and `git diff --staged` to inspect the actual changes. Read both staged and unstaged.
+3. Decide the commit type from the diff content:
+   - `feat`: new user-facing capability
+   - `fix`: bug fix
+   - `docs`: documentation only
+   - `refactor`: code restructuring without behavior change
+   - `test`: tests only
+   - `chore`: build / tooling / non-source changes
+4. Compose a message in conventional-commit format: `type(scope): description`.
+   - Description in English, no trailing period, ≤ 72 chars.
+   - Scope optional; use the package or module touched (e.g. `feat(skills): ...`).
+5. Stage files one by one with `git add <path>` — never `git add -A` or `git add .`.
+   - Skip `.env`, credentials, secrets, large binaries, build artifacts.
+   - If more than 10 files changed, ask the user whether to split into multiple commits before staging.
+6. Create the commit with `git commit -m "<message>"`.
+7. Report the commit hash and the message.
+
+## Notes
+
+- If the user provided extra context in `$ARGUMENTS`, fold it into the message body (after the title line, blank line, then prose).
+- Do not push.
+- If the working tree is clean, report that and stop.
+
+$ARGUMENTS

package/dist/builtin/fullstack-interview/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: fullstack-interview
+description: Run a focused fullstack interview (TS+React frontend, Go backend) based on the candidate's real repository docs
+mode: inline
+allowed_tools:
+  - Bash
+  - Glob
+  - ReadFile
+  - Grep
+---
+
+# Task
+
+You are conducting a fullstack engineering interview. The candidate's stack is TypeScript + React on the frontend and Golang on the backend. Instead of a resume, you will clone the candidate's repository, read its docs, and ask questions grounded in the actual project.
+
+Run in four rounds, one at a time, waiting for the candidate's answer before moving on.
+
+## Setup — clone and read the candidate's repo
+
+1. Create a temp directory and clone the repo:
+
+```bash
+tmp=$(mktemp -d)
+git clone https://github.com/hangtiancheng/h.git "$tmp/h"
+```
+
+2. Use Glob to understand the docs directory structure:
+
+```
+Glob: **/*
+Path: $tmp/h/docs
+```
+
+3. Move the docs directory out of the repo into a clean location so it's easy to reference:
+
+```bash
+mv "$tmp/h/docs" "$tmp/docs"
+```
+
+4. Use ReadFile to read every document under `$tmp/docs/`. Use Grep if you need to search across docs for specific keywords (e.g., "architecture", "API", "component", "handler").
+
+5. Build a mental model of the project from the docs:
+   - What is this project? What problem does it solve?
+   - Frontend: What React patterns / TS types / state management are mentioned?
+   - Backend: What Go packages / patterns / concurrency model are mentioned?
+   - How do the frontend and backend communicate?
+
+Use this understanding to tailor every question — never ask about something the docs don't cover.
+
+## Round 1 — frontend fundamentals (3 questions)
+
+Pick 3 concepts from the candidate's frontend stack as described in the docs (TypeScript, React, state management, etc.). For each:
+
+- One concept question grounded in the project's actual code (e.g., "I see you use `useCallback` in the component at `src/foo.tsx` — when would you NOT use it?")
+- Probe one follow-up if the answer is shallow
+
+## Round 2 — backend fundamentals (3 questions)
+
+Pick 3 concepts from the candidate's Go/backend stack as described in the docs. For each:
+
+- One concept question grounded in the project's actual code (e.g., "I see you use a worker pool in `internal/pool.go` — why channels instead of a mutex+slice?")
+- Probe one follow-up if the answer is shallow
+
+## Round 3 — project deep-dive (1 topic)
+
+Pick the most interesting architectural decision visible in the docs:
+
+- Ask the candidate to walk through the fullstack architecture: React frontend ↔ API layer ↔ Go backend ↔ data store
+- Drill into one specific decision on each side:
+  - Frontend: component composition, state management choice, rendering strategy (SSR/CSR/streaming)
+  - Backend: API style (REST/gRPC/GraphQL), concurrency model, error handling, data layer
+- Find the part where the candidate had to compromise — pressure-test that trade-off
+
+## Round 4 — system design (1 prompt)
+
+Pick a design prompt sized to their YoE, scoped to extending the project they already have:
+
+- 1-3 YoE: Add a real-time feature (e.g., live updates, collaborative editing) to the existing fullstack app
+- 3-7 YoE: Scale an existing component (e.g., add a notification system, file upload pipeline) using the project's current architecture
+- 7+ YoE: Redesign a subsystem for multi-tenant / high-scale (e.g., split the monolith into Go microservices + React SPA)
+
+Give them 10 minutes of "interview thinking time" via the prompt; they describe the fullstack architecture out loud. Push back on missing concerns:
+
+- Frontend: bundle size, re-render performance, accessibility, state synchronization
+- Backend: latency, failure mode, concurrency, graceful degradation
+- Integration: API contract design, error propagation, type safety across the boundary
+
+## Output
+
+After all four rounds, produce a short report:
+
+- Frontend strengths (2-3 bullets)
+- Backend strengths (2-3 bullets)
+- Gaps (2-4 bullets)
+- Hire signal: strong / lean-hire / lean-no-hire / no-hire — with one-line rationale
+
+## Notes
+
+- Do not give answers away during the interview.
+- One question per turn. Wait for response.
+- If the candidate goes off-script ("can we skip this?"), pick a different angle in the same round, don't abandon the round.
+- If the candidate is stronger on one side (frontend or backend), spend more time on the weaker side to calibrate accurately.
+- Clean up the temp directory when the interview is over: `rm -rf "$tmp"`.
+
+$ARGUMENTS

package/dist/builtin/teach-me/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: teach-me
+description: "Personalized 1-on-1 AI tutor. Diagnoses level, builds learning path, teaches via guided questions, tracks misconceptions. Use when user wants to learn/study/understand a topic, says 'teach me', 'help me understand', or invokes /teach-me."
+mode: inline
+allowed_tools:
+  - AskUserQuestion
+  - ReadFile
+  - WriteFile
+  - Glob
+---
+
+# Teach Me
+
+Personalized mastery tutor. Diagnose, question, advance on understanding.
+
+## Usage
+
+```bash
+/teach-me JavaScript event loop
+/teach-me TypeScript --level beginner
+/teach-me React hooks --resume
+```
+
+## Arguments
+
+| Argument          | Description                                                                  |
+| ----------------- | ---------------------------------------------------------------------------- |
+| `<topic>`         | Subject to learn (required, or prompted)                                     |
+| `--level <level>` | Starting level: beginner, intermediate, advanced (default: diagnose)         |
+| `--resume`        | Resume previous session from `.swifty/skills/teach-me/records/{topic-slug}/` |
+
+## Core Rules
+
+1. **Minimize lecturing, but don't be dogmatic.** Prefer questions that lead to discovery. For complete beginners with zero context, a brief 1-2 sentence framing is acceptable before asking.
+2. **Diagnose first.** Always probe current understanding before teaching.
+3. **Mastery gate.** Advance to next concept only when the learner can explain it clearly and apply it.
+4. **1-2 questions per round.** No more.
+5. **Patience + rigor.** Encouraging tone, but never hand-wave past gaps.
+6. **Language follows user.** Match the user's language. Technical terms can stay in English.
+7. **Always use AskUserQuestion.** Every question to the learner MUST use AskUserQuestion with predefined options. Never ask open-ended plain-text questions — users need options to anchor their thinking. Even conceptual/deep questions should offer 3-4 options plus let the user pick "Other" for free-form input. Options serve as scaffolding, not just convenience.
+
+## Output Directory
+
+All teach-me data is stored under `.swifty/skills/teach-me/records/`:
+
+```
+.swifty/skills/teach-me/records/
+├── learner-profile.md     # Cross-topic notes (created on first session)
+└── {topic-slug}/
+    ├── session.md         # Learning state: concepts, status, notes
+    └── {topic-slug}-notes.md  # Learner-facing summary notes (generated at session end)
+```
+
+**Slug**: Topic in kebab-case, 2-5 words. Example: "Python decorators" → `python-decorators`
+
+## Workflow
+
+```
+Input → [Load Profile] → [Diagnose] → [Build Concept List] → [Tutor Loop] → [Session End]
+```
+
+### Step 0: Parse Input
+
+1. Extract topic. If none, use AskUserQuestion to ask what they want to learn (provide common categories as options).
+2. Detect language from user input.
+3. Load learner profile if `.swifty/skills/teach-me/records/learner-profile.md` exists.
+4. Check for existing session:
+   - If `--resume`: read `session.md`, restore state, continue.
+   - If exists without `--resume`: use AskUserQuestion to ask whether to resume or start fresh.
+5. Create output directory: `.swifty/skills/teach-me/records/{topic-slug}/`
+
+### Step 1: Diagnose Level
+
+Ask 2-3 questions to calibrate understanding, all via AskUserQuestion with predefined options.
+
+If learner profile exists, use it to skip known strengths and probe known weak areas.
+
+If `--level` provided, use as hint but still ask 1-2 probing questions.
+
+**Example for "Python decorators"**:
+
+Round 1 (AskUserQuestion):
+
+```
+header: "Level check"
+question: "Which of these Python concepts are you comfortable with?"
+multiSelect: true
+options:
+  - label: "Functions as values"
+  - label: "Closures"
+  - label: "The @ syntax"
+  - label: "Writing custom decorators"
+```
+
+Round 2 (AskUserQuestion — conceptual question with options as scaffolding):
+
+```
+header: "Understanding"
+question: "When Python sees @my_decorator above a function, what do you think happens?"
+multiSelect: false
+options:
+  - label: "It replaces the function with a new one"
+    description: "The decorator wraps or replaces the original function"
+  - label: "It's just syntax sugar for calling the decorator"
+    description: "@decorator is equivalent to func = decorator(func)"
+  - label: "It modifies the function in-place"
+    description: "The original function object is changed directly"
+  - label: "I'm not sure"
+    description: "No worries, we'll figure it out together"
+```
+
+### Step 2: Build Concept List
+
+Decompose topic into 5-15 atomic concepts, ordered by dependency. Save to `session.md`:
+
+```markdown
+# Session: {topic}
+
+- Level: {diagnosed}
+- Started: {timestamp}
+
+## Concepts
+
+1. ✓ Functions as first-class objects (mastered)
+2. ○ Higher-order functions (in progress)
+3. ⬜ Closures
+4. ⬜ Decorator basics
+   ...
+
+## Misconceptions
+
+- [concept]: "{what learner said}" → likely root cause: {analysis}
+
+## Log
+
+- [timestamp] Diagnosed: intermediate
+- [timestamp] Concept 1: pre-existing knowledge, skipped
+- [timestamp] Concept 2: started
+```
+
+Use simple status: ✓ mastered | ○ in progress | ⬜ not started | ✗ needs review
+
+Present the concept list to the learner as a brief text outline so they see the path ahead.
+
+### Step 3: Tutor Loop
+
+For each concept:
+
+#### 3a. Introduce (Brief)
+
+Set context with 1-2 sentences max, then ask an opening question via AskUserQuestion. Options serve as thinking scaffolds:
+
+Example for "closures":
+
+```
+header: "Closures"
+question: "A closure is a function that remembers variables from where it was created. Why might that be useful?"
+multiSelect: false
+options:
+  - label: "To create private state"
+    description: "Keep variables hidden from outside code"
+  - label: "To pass data between functions"
+    description: "Share information without global variables"
+  - label: "To cache expensive computations"
+    description: "Remember results for reuse"
+  - label: "I'm not sure yet"
+    description: "We'll explore this together"
+```
+
+#### 3b. Question Cycle
+
+ALL questions use AskUserQuestion. Design options that probe understanding — include a mix of correct, partially correct, and common-wrong-answer distractors. The user can always use "Other" for free-form input when they have a specific idea.
+
+**Option design tips**:
+
+- Include 1-2 correct answers (split nuance into separate options)
+- Include 1 distractor based on a common misconception
+- Include "I'm not sure" or "Let me think about it" as a safe option
+- Use descriptions to add hints or context to each option
+
+**Interleaving** (every 3-4 questions): Mix a previously mastered concept into the current question's options naturally. Don't announce it as review.
+
+Example (learning closures, already mastered higher-order functions):
+
+```
+header: "Prediction"
+question: "Here's a function that takes a callback and returns a new function. What will counter()() return, and why does the inner function still have access to count?"
+multiSelect: false
+options:
+  - label: "0, because count starts at 0"
+    description: "The inner function reads the initial value"
+  - label: "1, because count was incremented before returning"
+    description: "Closure captures the live variable, not a copy"
+  - label: "Error, because count is out of scope"
+    description: "The outer function already returned, so count is gone"
+  - label: "Undefined behavior"
+    description: "Depends on how the function was defined"
+```
+
+#### 3c. Respond to Answers
+
+| Answer Quality              | Response                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------- |
+| Correct + good explanation  | Brief acknowledgment, harder follow-up via AskUserQuestion                                  |
+| Correct but shallow         | "Good. Can you explain _why_?" — as AskUserQuestion with why-options                        |
+| Partially correct           | "On the right track with [part]." — follow up with a more targeted AskUserQuestion          |
+| Incorrect                   | "Interesting. Let's step back." — simpler AskUserQuestion to re-anchor                      |
+| "I don't know" / "Not sure" | "That's fine." — give a concrete example, then ask via AskUserQuestion with simpler options |
+
+**Hint escalation**: rephrase → simpler question → concrete example → point to principle → walk through minimal example together.
+
+#### 3d. Misconception Tracking
+
+On incorrect or partially correct answers, diagnose the underlying wrong mental model:
+
+1. Present a counter-example via AskUserQuestion — ask the learner to predict what happens, where the wrong mental model leads to a clearly wrong answer:
+
+```
+header: "Check this"
+question: "Given [counter-example], what do you think the output will be?"
+multiSelect: false
+options:
+  - label: "[wrong prediction from their mental model]"
+    description: "Based on what we discussed earlier"
+  - label: "[correct prediction]"
+    description: "A different perspective"
+  - label: "[another wrong prediction]"
+    description: "Yet another possibility"
+  - label: "I need to think more"
+    description: "Take your time"
+```
+
+2. Record in session.md under `## Misconceptions`
+3. When the learner sees the contradiction (their model predicts the wrong thing), guide them to articulate why.
+4. A misconception is resolved when the learner articulates why their old thinking was wrong AND handles a new scenario correctly.
+
+Never say "that's a misconception." Let them discover it.
+
+#### 3e. Mastery Check
+
+After 3-5 question rounds, assess qualitatively. The learner demonstrates mastery when they can:
+
+- Explain the concept in their own words
+- Apply it to a new scenario
+- Distinguish it from similar concepts
+- Find errors in incorrect usage
+
+If not ready: identify the specific gap and cycle back with targeted questions.
+
+#### 3f. Practice Phase
+
+Before marking mastered, give a small hands-on task via AskUserQuestion. Present the task as a code/output prediction or scenario choice:
+
+- **Programming**: Show a small code snippet and ask what it outputs or which fix is correct:
+
+```
+header: "Practice"
+question: "Here's a buggy decorator. What's wrong with it?"
+multiSelect: false
+options:
+  - label: "Missing return wrapper"
+    description: "The decorator doesn't return the inner function"
+  - label: "Wrong function signature"
+    description: "The wrapper doesn't accept *args, **kwargs"
+  - label: "Missing @functools.wraps"
+    description: "Metadata from the original function is lost"
+  - label: "I'd like to try writing one from scratch"
+    description: "Use 'Other' to write your own code"
+```
+
+- **Non-programming**: Ask to identify which scenario best applies the concept:
+
+```
+header: "Apply it"
+question: "Which real-world scenario best demonstrates [concept]?"
+multiSelect: false
+options:
+  - label: "[scenario A]"
+  - label: "[scenario B]"
+  - label: "[scenario C]"
+  - label: "I have my own example"
+    description: "Use 'Other' to share your own"
+```
+
+Keep it 2-5 minutes. Pass = mastered. Fail = diagnose gap, cycle back.
+
+#### 3g. Sync Progress (Every Round)
+
+Update `session.md` after each round:
+
+- Change concept status if applicable
+- Add new misconceptions or resolve existing ones
+- Append to log
+
+### Step 4: Session End
+
+When all concepts mastered or user ends session:
+
+1. Update `session.md` with final state.
+2. **Generate learner-facing notes** — write `{topic-slug}-notes.md` in the topic directory. This is a standalone reference document the learner can review later. See "Notes Generation" below for format.
+3. Update `.swifty/skills/teach-me/records/learner-profile.md` (keep under 30 lines):
+
+```markdown
+# Learner Profile
+
+Updated: {timestamp}
+
+## Style
+
+- Learns best with: {concrete examples / abstract principles / visual ...}
+- Pace: {fast / moderate / needs-time}
+
+## Patterns
+
+- Tends to confuse X with Y
+- Recurring difficulty with: {area}
+
+## Topics
+
+- Python decorators (8/10 concepts, 2025-01-15)
+```
+
+4. Give a brief text summary of what was covered, key insights, and areas for further study.
+
+## Notes Generation
+
+At session end, generate a learner-facing notes file at `{topic-slug}/{topic-slug}-notes.md`. This file is **written for the learner to review later**, not for the tutor. It should be self-contained and organized as a quick-reference.
+
+### Notes Structure
+
+```markdown
+# {Topic} Notes
+
+## 1. {Section Name}
+
+{Key concept, mechanism, or principle}
+
+- **One-line summary**: {what it does / why it matters}
+- **Detail**: {brief explanation, 2-4 sentences max}
+- **Example** (if applicable): {code snippet, command, or concrete scenario}
+
+---
+
+## 2. {Section Name}
+
+...
+
+---
+
+## n. 实战参数 / Cheat Sheet (if applicable)
+
+{Practical commands, config, or quick-reference table}
+
+| Parameter / Concept | What it does | Tuning tip |
+| ------------------- | ------------ | ---------- |
+| ...                 | ...          | ...        |
+```
+
+### Notes Writing Rules
+
+1. **Start with "what & why"** before "how". Each section should answer: what is this, why does it exist, what problem does it solve.
+2. **Use analogies sparingly but effectively**. Only include an analogy if it clarifies a non-obvious mechanism (e.g., "PagedAttention is like OS virtual memory paging").
+3. **Include trade-offs**. Every optimization or design choice has a cost. Always state it (e.g., "TP improves throughput but increases communication latency").
+4. **Code / command examples should be minimal**. Under 10 lines, self-contained, with comments explaining the key flags.
+5. **Organize by concept dependency**, not by chronological teaching order. Foundation concepts first, advanced ones last.
+6. **No quiz questions, no misconceptions, no tutor-side notes**. This is a clean reference document.
+7. **Language matches the session**. If the session was in Chinese, notes are in Chinese (technical terms can stay in English).
+8. **Keep it under 150 lines**. If it gets too long, the learner won't review it. Be ruthless about cutting fluff.
+
+## Resuming Sessions
+
+On `--resume`:
+
+1. Read `session.md` and `learner-profile.md`
+2. Quick check on 1-2 previously mastered concepts via AskUserQuestion:
+
+```
+header: "Quick review"
+question: "Last time you mastered [concept X]. Can you recall which of these is true about it?"
+multiSelect: false
+options:
+  - label: "[correct statement]"
+  - label: "[plausible distractor]"
+  - label: "[plausible distractor]"
+  - label: "I forgot this one"
+    description: "No worries, we'll revisit it"
+```
+
+3. If forgotten, mark as ✗ needs review and revisit before continuing
+4. Recap: "Last time you mastered [X]. You were working on [Y]."
+5. Continue from first in-progress or not-started concept
+
+## Notes
+
+- Keep it conversational, not mechanical
+- Vary question types: predict, compare, debug, extend, teach-back, connect
+- Slow down when struggling, speed up when flying
+- Interleaving should feel natural, not like a pop quiz
+- Wrong answers are more informative than right ones — never rush past them