feat(onboarding): add adaptive pedagogy and multi-LLM compatibility

- Add communication tone preference (pedagogical/direct/coaching/adaptive)
- Extend style preference to all goals at 15min threshold
- Add "reset" option for mid-journey preference changes
- Add "skip" shows what's being skipped
- Add fallback roadmap when reference.yaml fetch fails
- Add multi-LLM compatibility footnote (works on ChatGPT, Gemini, etc.)
- Update reference.yaml with tone question and question_flow

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitignore

@@ -24,3 +24,4 @@ npm-debug.log*
 # Personal notes & temp files
 to-ignore/
 .grepai/
+whitepapers/

CHANGELOG.md

@@ -8,6 +8,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- **Onboarding Prompt v2: Adaptive Pedagogy & Multi-LLM Support**
+  - **New "Communication Tone" question** in Phase 0 (after goal)
+    - 4 options: Pedagogical, Direct, Coaching, Adaptive
+    - Adapts HOW content is delivered (not just WHAT)
+  - **Style preference now universal** - offered to all goals when time >= 15min (was 30min, learn_everything only)
+  - **"Reset" option in depth control** - users can restart with different preferences anytime
+  - **"Skip" now shows what's skipped** - brief note about skipped content for future reference
+  - **Fallback handling** if reference.yaml fetch fails - embedded roadmap ensures onboarding works offline
+  - **Multi-LLM portability footnote** - documents that prompt works with ChatGPT, Gemini, etc.
+  - **Key Principle #6: Adaptable** - users can pivot goals/level mid-journey
+  - Files modified: `tools/onboarding-prompt.md`, `machine-readable/reference.yaml`
+  - Inspired by community feedback (Greg Lhotellier testing on ChatGPT)
+
 - **grepai MCP Server documentation** in `guide/ultimate-guide.md` (Section 8.3)
   - Privacy-first semantic code search using Ollama embeddings
   - Call graph analysis: trace callers, callees, and dependency graphs

machine-readable/reference.yaml

@@ -355,6 +355,14 @@ onboarding_questions:
         intermediate: "🟡 Intermediate (daily use)"
         power: "🔴 Power User (know basics, want advanced)"
 
+    tone:
+      ask: "How do you prefer me to communicate?"
+      options:
+        pedagogical: "🎓 Pedagogical - Detailed explanations, understand why"
+        direct: "⚡ Direct - Straight to the point"
+        coaching: "🧭 Coaching - Guide me with questions"
+        adaptive: "🔄 Adaptive - Mix based on complexity"
+
   optional:
     time:
       ask: "How much time do you have?"
@@ -373,12 +381,12 @@ onboarding_questions:
         examples: "💻 Examples (show me code)"
         reference: "🎯 Quick reference (just the facts)"
         handson: "🏋️ Hands-on (let me try)"
-      trigger: "Only ask if time >= 30min"
+      trigger: "Only ask if time >= 15min"
 
   # Logic for progressive questioning
   question_flow:
     fix_problem: "goal only → skip to troubleshooting"
-    get_started: "goal → level"
-    optimize: "goal → level → time"
-    build_agents: "goal → level → time"
-    learn_everything: "goal → level → time → style"
+    get_started: "goal → tone → level"
+    optimize: "goal → tone → level → time → style (if time >= 15min)"
+    build_agents: "goal → tone → level → time → style (if time >= 15min)"
+    learn_everything: "goal → tone → level → time → style"

tools/onboarding-prompt.md

@@ -12,13 +12,13 @@
 
 This prompt instructs Claude to become your personal onboarding coach by:
 
-1. **Profiling** you with 2 quick questions (goal + level)
+1. **Profiling** you with 3 quick questions (goal + tone + level)
 2. **Loading** the reference index for smart navigation
 3. **Routing** you to the right content based on your profile
-4. **Guiding** you progressively with depth control (yes/next/skip)
-5. **Adapting** to your preferred language
+4. **Guiding** you progressively with depth control (deeper/next/skip/reset)
+5. **Adapting** to your preferred language and communication style
 
-**Experience**: 2 questions → tailored content → interactive exploration.
+**Experience**: 3 questions → tailored content → interactive exploration.
 
 **Time**: 5-60 minutes depending on your goal and available time.
 
@@ -82,6 +82,12 @@ You are an expert Claude Code instructor. Your mission is to onboard me using th
    - 🐛 Fix a problem - Troubleshoot an issue
    - 📚 Learn everything - Complete guided tour
 
+3. **Communication style**: After goal, use AskUserQuestion:
+   - 🎓 Pedagogical - Detailed explanations, understand the "why"
+   - ⚡ Direct - Straight to the point, no fluff
+   - 🧭 Coaching - Guide me with questions, let me discover
+   - 🔄 Adaptive - Mix styles based on topic complexity
+
 ### Phase 1: Load Knowledge Index
 
 **Fetch the navigation index:**
@@ -98,6 +104,16 @@ https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/mai
 - `decide`: Decision tree for common situations
 - `commands`, `shortcuts`, `context`: Quick reference sections
 
+**Fallback if fetch fails:**
+If you cannot fetch the reference.yaml:
+1. Acknowledge: "I couldn't fetch the navigation index, but I can still help you."
+2. Use this embedded fallback roadmap:
+   - `get_started`: rules → commands → shortcuts
+   - `optimize`: context_management → plan_mode → cost_optimization
+   - `build_agents`: agents → skills → hooks
+   - `fix_problem`: troubleshooting checklist
+3. Continue with Phase 1.5 questions as normal.
+
 ### Phase 1.5: Refine Profile (progressive - based on goal)
 
 Based on the goal from Phase 0, ask ONLY the necessary additional questions:
@@ -105,10 +121,12 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions:
 | Goal | Additional Questions |
 |------|---------------------|
 | `fix_problem` | None → Skip directly to troubleshooting |
-| `get_started` | Level only (beginner/intermediate/power) |
-| `optimize` | Level + Time available |
-| `build_agents` | Level + Time available |
-| `learn_everything` | Level + Time + Learning style preference |
+| `get_started` | Level only |
+| `optimize` | Level + Time + Style (if time >= 15min) |
+| `build_agents` | Level + Time + Style (if time >= 15min) |
+| `learn_everything` | Level + Time + Style |
+
+**Note**: Communication tone was already asked in Phase 0 for all profiles.
 
 **Level question** - Use AskUserQuestion with options:
 - 🟢 Beginner - Never used / just installed
@@ -121,7 +139,7 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions:
 - 🎯 30-60 min
 - 📚 1+ hour
 
-**Style question** (only if time >= 30min) - Use AskUserQuestion with options:
+**Style question** (if time >= 15min) - Use AskUserQuestion with options:
 - 📖 Explanations (tell me why)
 - 💻 Examples (show me code)
 - 🎯 Quick reference (just the facts)
@@ -156,16 +174,25 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions:
 
 2. **Fetch and summarize**: Get the relevant section (typically 50-100 lines from the line number)
 
-3. **Present summary**: 2-3 key points adapted to user's style preference:
+3. **Present summary**: 2-3 key points adapted to BOTH style AND tone preferences:
+
+   **Style** (WHAT to emphasize):
    - `explain` → Focus on WHY and concepts
    - `examples` → Lead with code samples
    - `reference` → Bullet points, no prose
    - `handson` → Give them something to try immediately
 
+   **Tone** (HOW to deliver):
+   - `pedagogical` → Explain reasoning, use analogies, connect to broader concepts
+   - `direct` → State facts concisely, skip justifications, action-focused
+   - `coaching` → Ask questions first ("What do you think happens when...?"), guide discovery
+   - `adaptive` → Start direct, expand if user asks "why?", coach if user struggles
+
 4. **Depth control**: Use AskUserQuestion with options:
    - "Go deeper" → Provide detailed explanation with examples
    - "Next topic" → Brief summary, move to next topic
-   - "Skip" → Skip entirely
+   - "Skip" → Skip, but briefly mention what's being skipped (e.g., "Skipping Plan Mode. Note: it's for safe exploration before risky changes.")
+   - "Reset" → Restart onboarding with different preferences (go back to Phase 0)
 
 5. **Handle questions**: If user asks something specific, use `deep_dive` to find relevant section
 
@@ -208,15 +235,19 @@ Based on time spent and topics covered:
 
 ## Key Principles
 
-1. **Fast**: 2 questions max before delivering value
+1. **Fast**: 3 quick questions before delivering value
 2. **Targeted**: Content matches goal, not generic overview
 3. **Interactive**: User controls pace and depth
 4. **Practical**: Focus on actionable knowledge
 5. **Multilingual**: Full conversation in preferred language
+6. **Adaptable**: Users can reset and change preferences anytime
 
 ## Start Now
 
 Begin by asking about preferred language.
+
+---
+*Portability: This prompt works with other capable LLMs (ChatGPT, Gemini, etc.). For non-Claude Code environments, paste the reference.yaml content and answer questions manually instead of using AskUserQuestion.*
 ```
 
 ---