refactor: restructure repo into thematic directories v3.1.0

Major repository reorganization for improved navigation: New directory structure: - guide/ - Core documentation (ultimate-guide, cheatsheet, adoption) - tools/ - Interactive utilities (audit, onboarding, mobile-access) - machine-readable/ - LLM/AI consumption (reference.yaml, llms.txt) - exports/ - Generated outputs (PDFs) Changes: - Move 10 files to thematic directories with cleaner names - Create README.md index for each new directory - Update 150+ internal links across all documentation - Add "Repository Structure" section to main README - Remove redundant npm install command from README header - Remove unverified cost estimate from prerequisites - Fix broken anchor link (#-quick-start-15-minutes) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 15:30:02 +01:00 · 2026-01-13 15:30:02 +01:00 · bc07651cdf
commit bc07651cdf
parent 06b9fe2c51
35 changed files with 450 additions and 282 deletions
--- a/tools/README.md
+++ b/tools/README.md
@ -0,0 +1,23 @@
+# Interactive Tools
+
+Prompts and utilities for Claude Code setup and optimization.
+
+## Contents
+
+| File | Description | Usage |
+|------|-------------|-------|
+| [audit-prompt.md](./audit-prompt.md) | Comprehensive setup audit with personalized recommendations | `cat audit-prompt.md \| claude` |
+| [onboarding-prompt.md](./onboarding-prompt.md) | Personalized guided tour based on your profile | `cat onboarding-prompt.md \| claude` |
+| [mobile-access.md](./mobile-access.md) | Setup guide for mobile access via ttyd + Tailscale | Step-by-step |
+
+## Quick Audit
+
+For a fast automated scan, use the script instead:
+
+```bash
+curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh | bash
+```
+
+---
+
+*Back to [main README](../README.md)*
--- a/tools/audit-prompt.md
+++ b/tools/audit-prompt.md
@ -0,0 +1,556 @@
+# Audit Your Claude Code Setup
+
+> A self-contained prompt to analyze your Claude Code configuration against best practices.
+
+**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
+
+**Reference**: [The Ultimate Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md)
+
+---
+
+## 1. What This Does
+
+This prompt instructs Claude to perform a comprehensive audit of your Claude Code setup by:
+
+1. **Scanning** your global and project configuration files using efficient bash commands
+2. **Evaluating** each element against best practices from the guide
+3. **Generating** a prioritized report with actionable recommendations
+4. **Providing** ready-to-use templates tailored to your tech stack
+
+**Performance**: Uses bash/grep for ~80% faster scanning and 90% fewer tokens compared to reading files.
+
+**Important**: Claude will NOT make any changes without your explicit approval.
+
+---
+
+## 2. Who This Is For
+
+| Level | What You'll Get |
+|-------|-----------------|
+| **Beginner** | Discover what you're missing and get starter templates |
+| **Intermediate** | Identify optimization opportunities and advanced patterns |
+| **Power User** | Validate your setup and find edge cases to polish |
+
+**Prerequisites**:
+- Claude Code installed and working
+- A project directory to analyze (or just global config)
+- Bash shell (native on macOS/Linux, WSL on Windows)
+
+**Time**: ~2-3 minutes (optimized with bash scanning)
+
+---
+
+## 3. How to Use It
+
+### Step 1: Copy the Prompt
+
+Copy everything inside the code block in [Section 4](#4-the-prompt) below.
+
+### Step 2: Run Claude Code
+
+```bash
+cd your-project-directory
+claude --ultrathink
+```
+
+> **Note**: `--ultrathink` enables maximum analysis depth (~32K tokens). You can also use `--think` for lighter analysis.
+
+### Step 3: Paste and Execute
+
+Paste the prompt and press Enter. Claude will begin the audit.
+
+### Step 4: Review Results
+
+Claude will present findings and ask for validation before making any changes.
+
+### Platform Note
+
+| Platform | Global Config Path |
+|----------|-------------------|
+| **macOS/Linux** | `~/.claude/` |
+| **Windows** | `%USERPROFILE%\.claude\` |
+
+---
+
+## 4. The Prompt
+
+```markdown
+# Audit My Claude Code Setup
+
+## Context
+
+Perform a comprehensive audit of my Claude Code configuration against best practices from "The Ultimate Claude Code Guide":
+https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md
+
+## Instructions
+
+### Phase 1: Discovery (Bash Scan)
+
+**IMPORTANT**: Use efficient bash commands. Do NOT read files unnecessarily.
+
+#### 1.1 Quick Configuration Scan
+
+**Run this bash command to get all config status at once:**
+
+```bash
+bash -c '
+echo "=== GLOBAL CONFIG ==="
+for f in ~/.claude/CLAUDE.md ~/.claude/settings.json; do
+  [ -f "$f" ] && echo "✅ $(basename $f)" || echo "❌ $(basename $f)"
+done
+# Note: MCP config is now in ~/.claude.json, not ~/.claude/mcp.json
+[ -f ~/.claude.json ] && echo "✅ ~/.claude.json (contains MCP config)" || echo "❌ ~/.claude.json"
+
+echo -e "\n=== PROJECT CONFIG ==="
+for f in ./CLAUDE.md ./.claude/CLAUDE.md ./.claude/settings.json ./.claude/settings.local.json; do
+  [ -f "$f" ] && echo "✅ $f" || echo "❌ $f"
+done
+
+echo -e "\n=== EXTENSIONS ==="
+for d in agents commands skills hooks rules; do
+  if [ -d "./.claude/$d" ]; then
+    count=$(find "./.claude/$d" -maxdepth 1 -type f | wc -l | tr -d " ")
+    echo "✅ $d: $count files"
+  else
+    echo "❌ $d/"
+  fi
+done
+
+echo -e "\n=== TECH STACK ==="
+[ -f package.json ] && echo "nodejs: $(grep -oP "\"name\":\s*\"\K[^\"]*" package.json 2>/dev/null || echo "detected")"
+[ -f pyproject.toml ] && echo "python: $(grep "^name" pyproject.toml | head -1)"
+[ -f requirements.txt ] && echo "python: requirements.txt"
+[ -f go.mod ] && echo "go: $(head -1 go.mod)"
+[ -f Cargo.toml ] && echo "rust: $(grep "^name" Cargo.toml | head -1)"
+[ -f composer.json ] && echo "php: detected"
+[ -f Gemfile ] && echo "ruby: detected"
+'
+```
+
+**Store the output** for evaluation phase.
+
+#### 1.2 Quality Pattern Checks
+
+**Run these targeted grep commands:**
+
+```bash
+bash -c '
+# Security hooks
+echo "=== SECURITY HOOKS ==="
+if [ -d "./.claude/hooks" ]; then
+  grep -l "PreToolUse" ./.claude/hooks/* 2>/dev/null || echo "❌ None found"
+else
+  echo "❌ No hooks directory"
+fi
+
+# MCP servers (check all locations)
+echo -e "\n=== MCP SERVERS ==="
+CURRENT_DIR=$(pwd)
+
+# Check 1: Project-specific MCP in ~/.claude.json (most common)
+if [ -f ~/.claude.json ] && command -v jq &> /dev/null; then
+  MCP=$(jq -r --arg path "$CURRENT_DIR" ".projects[\$path].mcpServers // {} | keys[]" ~/.claude.json 2>/dev/null)
+  if [ -n "$MCP" ]; then
+    echo "Source: ~/.claude.json (project)"
+    echo "$MCP"
+  fi
+fi
+
+# Check 2: Project-level .claude/mcp.json
+if [ -z "$MCP" ] && [ -f ./.claude/mcp.json ]; then
+  echo "Source: .claude/mcp.json"
+  if command -v jq &> /dev/null; then
+    jq -r ".mcpServers // {} | keys[]" ./.claude/mcp.json 2>/dev/null
+  else
+    grep -oE "\"[a-zA-Z0-9_-]+\"[[:space:]]*:" ./.claude/mcp.json | sed "s/\"//g;s/://g"
+  fi
+fi
+
+# Check 3: Legacy global ~/.claude/mcp.json
+if [ -z "$MCP" ] && [ -f ~/.claude/mcp.json ]; then
+  echo "Source: ~/.claude/mcp.json (global)"
+  if command -v jq &> /dev/null; then
+    jq -r ".mcpServers // {} | keys[]" ~/.claude/mcp.json 2>/dev/null
+  else
+    grep -oE "\"[a-zA-Z0-9_-]+\"[[:space:]]*:" ~/.claude/mcp.json | sed "s/\"//g;s/://g"
+  fi
+fi
+
+[ -z "$MCP" ] && echo "❌ No MCP servers configured for this project"
+
+# CLAUDE.md quality
+echo -e "\n=== MEMORY FILE QUALITY ==="
+if [ -f ./CLAUDE.md ]; then
+  lines=$(wc -l < ./CLAUDE.md | tr -d " ")
+  refs=$(grep -c "@" ./CLAUDE.md 2>/dev/null || echo 0)
+  examples=$(grep -ci "example" ./CLAUDE.md 2>/dev/null || echo 0)
+  echo "Lines: $lines"
+  echo "@references: $refs"
+  echo "Examples: $examples"
+  [ $lines -gt 200 ] && echo "⚠️  Consider shortening (>200 lines)"
+else
+  echo "❌ No CLAUDE.md"
+fi
+
+# Single Source of Truth pattern
+echo -e "\n=== SSOT PATTERN ==="
+if [ -f ./CLAUDE.md ]; then
+  grep -E "^@|/docs/|/conventions/" ./CLAUDE.md 2>/dev/null | head -5 || echo "❌ No @references found"
+else
+  echo "❌ No CLAUDE.md"
+fi
+
+# Documentation folders
+echo -e "\n=== DOCUMENTATION ==="
+for d in docs/ docs/conventions/ documentation/; do
+  [ -d "$d" ] && echo "✅ $d exists"
+done
+'
+```
+
+**Store the output** for evaluation phase.
+
+#### 1.3 Optional: Full Script
+
+For a comprehensive JSON report, use the audit script from the repository:
+
+```bash
+# Download and run the official audit script
+curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh | bash
+
+# Or if you have the repo locally:
+# ./examples/scripts/audit-scan.sh --json
+```
+
+### Phase 2: Evaluate & Report
+
+**IMPORTANT**: Use the bash scan outputs from Phase 1 as your primary data source. Only read files when you need specific content examples or template generation.
+
+#### 2.1 Evaluation Checklist
+
+For each category, evaluate against these criteria based on Phase 1 scan results:
+
+**Memory Files (Guide Section 3.1)**
+- [ ] Global CLAUDE.md exists with personal preferences
+- [ ] Project CLAUDE.md exists with team conventions
+- [ ] Memory files are concise (not essays)
+- [ ] Includes concrete examples
+- [ ] References external docs instead of duplicating
+
+**Single Source of Truth (Guide Section 3.1)**
+- [ ] Conventions documented in `/docs/conventions/` or similar
+- [ ] CLAUDE.md references these docs with `@path`
+- [ ] Same conventions used across tools (CodeRabbit, SonarQube, etc.)
+
+**Folder Structure (Guide Section 3.2)**
+- [ ] `.claude/` folder properly organized
+- [ ] Appropriate gitignore (settings.local.json, local CLAUDE.md)
+
+**Context Management (Guide Section 2.2)**
+- [ ] Awareness of context zones (green/yellow/red)
+- [ ] Sanity markers strategy documented
+- [ ] Context poisoning prevention considered
+
+**Plan Mode Usage (Guide Section 2.3)**
+- [ ] Plan mode mentioned for complex/risky tasks
+- [ ] Auto Plan Mode configured if needed
+
+**Agents (Guide Section 4)**
+- [ ] Custom agents for repetitive specialized tasks
+- [ ] Agents have clear descriptions (Tool SEO principle)
+- [ ] Appropriate model selection per agent (haiku/sonnet/opus)
+
+**Skills (Guide Section 5)**
+- [ ] Reusable knowledge modules for complex domains
+- [ ] Properly structured with frontmatter
+
+**Commands (Guide Section 6)**
+- [ ] Custom commands for frequent workflows
+- [ ] Use $ARGUMENTS for flexibility
+
+**Hooks (Guide Section 7)**
+- [ ] Security hooks (PreToolUse) for sensitive operations
+- [ ] Auto-formatting hooks (PostToolUse) if needed
+- [ ] Context enrichment (UserPromptSubmit) if useful
+
+**MCP Servers (Guide Section 8)**
+- [ ] Serena configured if large codebase (indexation + memory)
+- [ ] Context7 configured if using external libraries
+- [ ] Other relevant MCPs for the project needs
+
+**Think Levels & Trinity (Guide Section 9.1)**
+- [ ] Understanding of --think / --think-hard / --ultrathink
+- [ ] Trinity pattern documented for complex workflows
+
+**CI/CD Integration (Guide Section 9.3)**
+- [ ] Verify Gate pattern implemented (build → lint → test → typecheck)
+- [ ] Autonomous retry loop considered
+
+**Continuous Improvement (Guide Section 9.10)**
+- [ ] Meta-rules for fixing system, not just code
+- [ ] Learning from repeated issues
+
+**Cost Awareness (Guide Section 2.2)**
+- [ ] Understanding of pricing model (Sonnet/Opus/Haiku costs)
+- [ ] Using /compact proactively to manage costs
+- [ ] Being specific in queries to reduce token usage
+- [ ] Tracking costs via Anthropic Console
+
+**Migration Patterns (Guide Section 1.6)**
+- [ ] Understanding differences vs Copilot/Cursor
+- [ ] Hybrid workflow defined (when to use which tool)
+- [ ] Successfully transitioned from previous AI tools
+
+**Release Notes Automation (Guide Section 9.3)**
+- [ ] Using Claude for changelog generation
+- [ ] Automated release notes in CI/CD
+- [ ] User-facing vs technical release notes
+
+**Emergency Procedures (Guide Appendix A.10)**
+- [ ] Hotfix checklist available for production issues
+- [ ] Plan Mode usage during critical fixes
+- [ ] Post-mortem process documented
+
+**Git Archaeology (Guide Appendix A.11)**
+- [ ] Using git blame/log for code understanding
+- [ ] Finding domain experts via git history
+- [ ] Understanding code evolution patterns
+
+#### 2.2 Calculate Health Score
+
+**Formula**: `Score = (earned_points / max_points) × 100`
+
+| Priority | Points per ✅ | Weight Rationale |
+|----------|--------------|------------------|
+| 🔴 High | 3 points | Fundamentals, security, major productivity |
+| 🟡 Medium | 2 points | Best practices, recommended patterns |
+| 🟢 Low | 1 point | Polish, optimization, nice-to-have |
+
+**Priority Assignment Rules**:
+- 🔴 **High**: Missing CLAUDE.md (any), no security hooks, no permissions config, no context management awareness
+- 🟡 **Medium**: No custom agents for repeated tasks, incomplete MCP setup, missing Single Source of Truth, no CI integration
+- 🟢 **Low**: Tool SEO optimization, optional skills, advanced patterns like Trinity
+
+#### 2.3 Generate Report
+
+**Executive Summary** (5-10 lines):
+- Health Score: X/100 (with color indicator)
+- Top 3 Quick Wins (< 5 min each)
+- Top 3 Important Gaps
+- Detected tech stack
+
+**Quick Wins Section**:
+List 3-5 high-impact actions that take less than 5 minutes:
+```
+⚡ Quick Win 1: [action] → [impact]
+⚡ Quick Win 2: [action] → [impact]
+⚡ Quick Win 3: [action] → [impact]
+```
+
+**Findings Table** (4 columns):
+
+| Priority | Element | Status | Action |
+|----------|---------|--------|--------|
+| 🔴 | ... | ❌/⚠️/✅ | ... |
+
+**Detailed Findings** (expandable per item):
+For each ❌ or ⚠️ item, provide:
+```
+### [Element Name]
+**Current State**: [what exists or doesn't]
+**Why It Matters**: [impact on workflow]
+**Guide Reference**: [Section X.X](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#section-anchor)
+```
+
+**Efficient Guide Reference Lookup**:
+Instead of reading the entire guide, use these line ranges for targeted extraction:
+
+```bash
+# Memory Files best practices
+sed -n '2184,2314p' guide/ultimate-guide.md
+
+# Hooks section
+sed -n '3962,4528p' guide/ultimate-guide.md
+
+# MCP Servers section
+sed -n '4529,5076p' guide/ultimate-guide.md
+
+# Context Management
+sed -n '910,1423p' guide/ultimate-guide.md
+
+# Plan Mode
+sed -n '1424,1601p' guide/ultimate-guide.md
+```
+
+**Suggested Templates**:
+For each High/Medium priority gap, provide a STACK-SPECIFIC template:
+```
+### Template: [Element Name]
+
+**File**: `path/to/file`
+**Stack**: [detected stack]
+
+**Suggested content**:
+\`\`\`
+[template content customized for the detected tech stack]
+\`\`\`
+```
+
+### Phase 3: Await Validation
+
+**CRITICAL**: Do NOT create or modify any files without explicit approval.
+
+After presenting the report, ask:
+
+"Which of these suggestions would you like me to implement?
+
+Options:
+- `all` - Implement all templates
+- `high` - Only 🔴 High priority items
+- `1, 3, 5` - Specific items by number
+- `none` - Just keep the report for reference
+
+Please specify your choice:"
+
+Wait for explicit user response before taking any action.
+
+## Output Format
+
+Structure your response exactly as:
+
+1. **Executive Summary** (health score, quick wins, gaps, stack)
+2. **Quick Wins** (3-5 immediate actions)
+3. **Findings Table** (4-column overview)
+4. **Detailed Findings** (expanded per item)
+5. **Suggested Templates** (stack-specific, ready to use)
+6. **Validation Request** (ask before implementing)
+```
+
+---
+
+## 5. What to Expect
+
+Here's an example of what the audit report looks like:
+
+### Example Executive Summary
+
+```
+## Executive Summary
+
+**Health Score**: 45/100 🟡
+
+**Detected Stack**: TypeScript + Next.js + Prisma
+
+**Quick Wins** (< 5 min each):
+⚡ Create project CLAUDE.md → Immediate context for Claude
+⚡ Add .claude/ to .gitignore patterns → Prevent accidental commits
+⚡ Enable Context7 MCP → Better library documentation
+
+**Top 3 Gaps**:
+1. 🔴 No project CLAUDE.md - Claude lacks project context
+2. 🔴 No security hooks - Sensitive operations unprotected
+3. 🟡 No custom agents - Repetitive tasks done manually
+```
+
+### Example Findings Table
+
+| Priority | Element | Status | Action |
+|----------|---------|--------|--------|
+| 🔴 High | Project CLAUDE.md | ❌ Missing | Create with stack conventions |
+| 🔴 High | Security hooks | ❌ Missing | Add PreToolUse for secrets |
+| 🟡 Medium | Custom agents | ❌ Missing | Create for code review, testing |
+| 🟡 Medium | MCP Serena | ⚠️ Partial | Add memory configuration |
+| 🟢 Low | Tool SEO | ⚠️ Partial | Improve agent descriptions |
+
+---
+
+## 6. Understanding Results
+
+### Glossary
+
+| Term | Definition |
+|------|------------|
+| **Memory Files** | CLAUDE.md files that provide persistent context to Claude across sessions |
+| **Single Source of Truth** | Pattern where conventions are documented once and referenced everywhere |
+| **Tool SEO** | Writing agent/command descriptions so Claude selects the right tool automatically |
+| **MCP Servers** | Model Context Protocol - external tools that extend Claude's capabilities. Config stored in `~/.claude.json` per project, or `.claude/mcp.json` at project level |
+| **Serena** | MCP server for codebase indexation and session memory persistence |
+| **Context7** | MCP server for official library documentation lookup |
+| **Hooks** | Scripts that run automatically on Claude events (PreToolUse, PostToolUse, etc.) |
+| **PreToolUse** | Hook that runs BEFORE Claude executes a tool - great for security checks |
+| **PostToolUse** | Hook that runs AFTER Claude executes a tool - great for formatting |
+| **Plan Mode** | Read-only exploration mode for safe analysis before making changes |
+| **Think Levels** | `--think`, `--think-hard`, `--ultrathink` - different analysis depths |
+| **Trinity Pattern** | Combining Plan Mode + Think Levels + MCP for complex tasks |
+| **Verify Gate** | CI/CD pattern: build → lint → test → typecheck before merge |
+| **Context Zones** | Green (0-50%), Yellow (50-70%), Red (70%+) - context usage thresholds |
+
+### Priority Levels Explained
+
+| Level | Meaning | Examples |
+|-------|---------|----------|
+| 🔴 **High** | Missing fundamentals, security risks, major productivity loss | No CLAUDE.md, no security hooks |
+| 🟡 **Medium** | Recommended best practices, significant improvements | No agents, incomplete MCP |
+| 🟢 **Low** | Nice-to-have optimizations, polish | Tool SEO, advanced patterns |
+
+### Status Icons
+
+| Icon | Meaning |
+|------|---------|
+| ✅ | Good - meets best practices |
+| ⚠️ | Partial - exists but needs improvement |
+| ❌ | Missing - doesn't exist or broken |
+
+---
+
+## 7. Common Issues
+
+### "Claude didn't find my files"
+
+**Cause**: Wrong working directory or platform path differences.
+
+**Fix**:
+- Ensure you run `claude` from your project root
+- On Windows, paths use `%USERPROFILE%\.claude\` not `~/.claude/`
+
+### "Health score seems wrong"
+
+**Cause**: The weighted formula may not match your priorities.
+
+**Fix**: Focus on the specific findings rather than the score. The score is indicative, not absolute.
+
+### "Templates don't match my stack"
+
+**Cause**: Stack detection failed or project uses uncommon setup.
+
+**Fix**: Tell Claude your stack explicitly: "My project uses [X]. Regenerate templates for this stack."
+
+### "Too many recommendations"
+
+**Cause**: First-time audit on a project without Claude Code configuration.
+
+**Fix**:
+1. Start with Quick Wins only
+2. Implement High priority items first
+3. Add Medium/Low items incrementally
+
+### "Claude made changes without asking"
+
+**Cause**: This shouldn't happen if using the prompt correctly.
+
+**Fix**:
+- Ensure you copied the entire prompt including Phase 3
+- Use Plan Mode (`Shift+Tab` twice) for extra safety
+- Report this as a bug if it persists
+
+---
+
+## 8. Related Resources
+
+- [The Ultimate Claude Code Guide](../guide/ultimate-guide.md) - Full reference
+- [Cheatsheet](../guide/cheatsheet.md) - Quick daily reference
+- [Claude Code Official Docs](https://docs.anthropic.com/en/docs/claude-code) - Anthropic documentation
+
+---
+
+*Last updated: January 2026 | Version 2.9 - Fixed MCP detection (now checks ~/.claude.json)*
--- a/tools/mobile-access.md
+++ b/tools/mobile-access.md
@ -0,0 +1,299 @@
+# Claude Code Mobile Access
+
+> **⚠️ STATUS: WIP / UNTESTED**
+>
+> This guide is a work in progress. The setup has not been fully tested across different environments.
+> Use at your own risk. Contributions and feedback welcome.
+
+---
+
+## The Problem
+
+Claude Code CLI is a **local interactive process**, not a service with a session API. Each instance is autonomous. Even `claude --remote` only offloads execution—it doesn't create a relay system.
+
+**What's missing**: A native `claude --serve` mode that exposes a WebSocket API, allows multiple clients, and maintains the same conversation context.
+
+**The workaround**: Expose your terminal via web browser using `ttyd`, accessible from anywhere via `Tailscale` VPN.
+
+---
+
+## Solution: ttyd + Tailscale
+
+```
+YOUR COMPUTER                     YOUR PHONE
+┌─────────────────┐               ┌─────────────────┐
+│  Claude Code    │◄──────────────│  Browser        │
+│  (runs here)    │   Tailscale   │  (same session) │
+│                 │   (VPN)       │                 │
+└─────────────────┘               └─────────────────┘
+```
+
+- **ttyd**: Exposes your terminal in a web browser
+- **Tailscale**: Free VPN that gives your computer a fixed IP, accessible from anywhere (4G, public WiFi, etc.)
+- **tmux**: Keeps session alive even if you close the browser
+
+**Use case**: Follow and continue Claude Code sessions from your phone (commuting, away from desk, etc.)
+
+---
+
+## Why This Approach?
+
+### ToS Considerations
+
+Some third-party wrappers (like OpenCode) have been blocked by Anthropic for ToS violations. This approach is **ToS-safe** because:
+
+- You're using the **official Claude Code CLI**
+- ttyd just exposes your terminal via browser (no wrapper)
+- Tailscale is just a VPN for secure access
+- No third-party client interacting with Claude's API
+
+---
+
+## Prerequisites
+
+- macOS or Linux
+- Claude Code CLI installed and authenticated
+- Tailscale account (free tier works)
+
+---
+
+## Installation
+
+### Quick Setup Script
+
+```bash
+#!/bin/bash
+# claude-mobile-setup.sh
+
+set -e
+
+echo "=== Setup Claude Code Mobile ==="
+
+# 1. Install ttyd + tmux
+echo "[1/2] Installing ttyd..."
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install ttyd tmux
+else
+    sudo apt install -y tmux
+    sudo snap install ttyd --classic
+fi
+
+# 2. Install Tailscale
+echo "[2/2] Installing Tailscale..."
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install tailscale
+else
+    curl -fsSL https://tailscale.com/install.sh | sh
+fi
+
+# 3. Create launcher script
+mkdir -p ~/.local/bin
+cat > ~/.local/bin/claude-mobile << 'EOF'
+#!/bin/bash
+PORT=7681
+PASS="${CLAUDE_MOBILE_PASS:-claude123}"
+
+TS_IP=$(tailscale ip -4 2>/dev/null || echo "not connected")
+
+echo "══════════════════════════════════"
+echo "  CLAUDE CODE MOBILE"
+echo "══════════════════════════════════"
+echo "  URL:  http://$TS_IP:$PORT"
+echo "  User: claude"
+echo "  Pass: $PASS"
+echo "══════════════════════════════════"
+echo ""
+echo "Open this URL on your phone."
+echo "Press Ctrl+C to stop."
+echo ""
+
+# Kill existing session if any
+tmux kill-session -t cc 2>/dev/null || true
+
+# Start Claude in tmux, expose via ttyd
+tmux new-session -d -s cc 'claude'
+exec ttyd -W -p $PORT -c "claude:$PASS" tmux attach -t cc
+EOF
+
+chmod +x ~/.local/bin/claude-mobile
+
+# Add to PATH
+if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
+    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+fi
+
+echo ""
+echo "=== Installation Complete ==="
+echo ""
+echo "Next steps:"
+echo "  1. Run: tailscale up"
+echo "  2. Run: source ~/.zshrc"
+echo "  3. Run: claude-mobile"
+echo ""
+```
+
+### Manual Installation
+
+```bash
+# macOS
+brew install ttyd tmux tailscale
+
+# Linux (Debian/Ubuntu)
+sudo apt install -y tmux
+sudo snap install ttyd --classic
+curl -fsSL https://tailscale.com/install.sh | sh
+```
+
+---
+
+## Usage
+
+### First Time Setup
+
+```bash
+# 1. Connect to Tailscale (one-time)
+tailscale up
+# Follow the link to authenticate with Google/GitHub/etc.
+
+# 2. Install Tailscale on your phone
+# iOS: App Store → Tailscale
+# Android: Play Store → Tailscale
+# Login with same account
+
+# 3. Start Claude Code Mobile
+claude-mobile
+```
+
+### Output
+
+```
+══════════════════════════════════
+  CLAUDE CODE MOBILE
+══════════════════════════════════
+  URL:  http://100.78.42.15:7681
+  User: claude
+  Pass: claude123
+══════════════════════════════════
+```
+
+### On Your Phone
+
+1. Open Safari/Chrome
+2. Go to `http://100.78.42.15:7681` (use your actual Tailscale IP)
+3. Login with `claude` / `claude123`
+4. You now have Claude Code in your browser
+
+---
+
+## Configuration
+
+### Change Password
+
+```bash
+export CLAUDE_MOBILE_PASS="your-secure-password"
+claude-mobile
+```
+
+Or add to your shell config:
+
+```bash
+echo 'export CLAUDE_MOBILE_PASS="your-secure-password"' >> ~/.zshrc
+```
+
+### Change Port
+
+Edit `~/.local/bin/claude-mobile` and change `PORT=7681` to your preferred port.
+
+---
+
+## Security
+
+| Layer | Protection |
+|-------|------------|
+| **Network** | Tailscale uses WireGuard encryption |
+| **Authentication** | Basic auth (username:password) via ttyd |
+| **Access** | Only accessible from your Tailscale network |
+
+**Recommendations**:
+- Use a strong password (not the default `claude123`)
+- Don't expose ttyd directly to the internet without Tailscale
+- Keep Tailscale client updated on all devices
+
+---
+
+## Troubleshooting
+
+### "not connected" instead of IP
+
+```bash
+# Check Tailscale status
+tailscale status
+
+# If disconnected, reconnect
+tailscale up
+```
+
+### Can't access from phone
+
+1. Ensure Tailscale app is installed on phone and connected to same account
+2. Check firewall isn't blocking port 7681
+3. Try accessing locally first: `http://localhost:7681`
+
+### Session not persisting
+
+The tmux session should persist. To manually reattach:
+
+```bash
+tmux attach -t cc
+```
+
+### ttyd command not found
+
+```bash
+# macOS
+brew reinstall ttyd
+
+# Linux
+sudo snap install ttyd --classic
+```
+
+---
+
+## Alternatives Considered
+
+| Solution | Pros | Cons | ToS Risk |
+|----------|------|------|----------|
+| **ttyd + Tailscale** ✅ | Simple, no wrapper, ToS-safe | Terminal UX on mobile | ✅ Safe |
+| Happy Coder (7.1K ⭐) | Native apps, polished | Wraps CLI | ⚠️ Unknown |
+| Claude Code Web (5.5K ⭐) | Rich UI | Wraps CLI | ⚠️ Unknown |
+| tmux + SSH | Zero deps | Needs SSH client on phone | ✅ Safe |
+
+We chose ttyd + Tailscale because:
+- It's just your terminal exposed via browser
+- No third-party wrapper around Claude Code
+- Zero ToS risk—you're using the official CLI
+
+---
+
+## Related Resources
+
+- [ttyd GitHub](https://github.com/tsl0922/ttyd) - Terminal web server
+- [Tailscale](https://tailscale.com/) - Zero-config VPN
+- [ttyd + Claude Code Guide](https://aiengineerguide.com/blog/agentic-cli-browser-ttyd/) - Community tutorial
+- [VPS Setup Guide](https://joshualent.com/snippets/claude-phone/) - Alternative: run on VPS
+
+---
+
+## Contributing
+
+This doc is **WIP/UNTESTED**. If you test this setup, please share:
+- Your OS/environment
+- Any issues encountered
+- Suggested improvements
+
+Open an issue or PR on this repo.
+
+---
+
+*Last updated: January 2026 | Status: WIP/UNTESTED*
--- a/tools/onboarding-prompt.md
+++ b/tools/onboarding-prompt.md
@ -0,0 +1,222 @@
+# Personalized Claude Code Onboarding
+
+> An interactive prompt for Claude to guide you through the Ultimate Claude Code Guide at your own pace.
+
+**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
+
+**Reference**: [The Ultimate Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md)
+
+---
+
+## 1. What This Does
+
+This prompt instructs Claude to become your personal onboarding coach by:
+
+1. **Assessing** your current Claude Code knowledge level through interactive questions
+2. **Reading** the comprehensive guide documentation
+3. **Presenting** a structured learning path tailored to your level
+4. **Guiding** you progressively with the option to dive deeper on any topic
+5. **Adapting** to your preferred language (English, French, or any other)
+
+**Experience**: Interactive Q&A format - you control the pace and depth.
+
+**Important**: Claude will ask questions to understand your needs before presenting information.
+
+---
+
+## 2. Who This Is For
+
+| Level | What You'll Experience |
+|-------|------------------------|
+| **Beginner** | Full guided tour from installation to first workflows |
+| **Intermediate** | Focus on Plan Mode, context management, cost optimization |
+| **Power User** | Deep dive into Agents, Skills, Hooks, MCPs, and advanced patterns |
+
+**Prerequisites**:
+- Claude Code installed (or wanting to learn about it)
+- ~15-30 minutes for the initial assessment and overview
+- Curiosity about maximizing your Claude Code productivity
+
+**Time**: Self-paced (typically 15-60 minutes depending on depth)
+
+---
+
+## 3. How to Use It
+
+### Step 1: Copy the Prompt
+
+Copy everything inside the code block in [Section 4](#4-the-prompt) below.
+
+### Step 2: Run Claude Code
+
+```bash
+claude
+```
+
+### Step 3: Paste and Interact
+
+Paste the prompt and press Enter. Claude will begin by asking about your preferred language and experience level.
+
+### Step 4: Explore at Your Pace
+
+Answer Claude's questions and request deeper dives on topics that interest you.
+
+---
+
+## 4. The Prompt
+
+```markdown
+# Personalized Claude Code Onboarding
+
+## Your Role
+
+You are an expert Claude Code instructor. Your mission is to onboard me to Claude Code using "The Ultimate Claude Code Guide" as your reference material.
+
+## Instructions
+
+### Phase 0: Language & Level Assessment
+
+**First, ask me these questions ONE AT A TIME:**
+
+1. **Language**: "What language would you prefer for this onboarding? (e.g., English, French, Spanish, German...)"
+
+2. **Experience Level**: After I answer, ask:
+   "What's your current experience with Claude Code?
+   - 🟢 **Beginner**: Never used it or just installed it
+   - 🟡 **Intermediate**: Use it daily but want to optimize
+   - 🔴 **Power User**: Know the basics, want advanced features"
+
+3. **Focus Areas** (optional): Based on my level, you may ask what specific topics interest me most.
+
+### Phase 1: Read the Guide
+
+**After understanding my preferences, read the guide:**
+
+Fetch and read the complete guide from:
+https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/guide/ultimate-guide.md
+
+**Alternative**: If the URL is not accessible, use WebSearch to find the guide content or ask me to provide it.
+
+### Phase 2: Present Structured Overview
+
+**Create a learning roadmap based on my level:**
+
+For **Beginners** (🟢), focus on:
+- Installation & first run
+- The 5 essential commands
+- Permission modes (suggest, auto-edit, full-auto)
+- Basic context management
+- Cost awareness
+
+For **Intermediate** (🟡), focus on:
+- Plan Mode and when to use it
+- Context window optimization
+- OpusPlan pattern (Opus plans, Sonnet executes)
+- Session management
+- CLAUDE.md best practices
+
+For **Power Users** (🔴), focus on:
+- Commands vs Skills vs Agents distinction
+- Custom agents creation
+- Hooks system
+- MCP servers configuration
+- Ultrathink + Sequential Thinking
+- Advanced patterns (XML prompting, split roles)
+
+### Phase 3: Interactive Exploration
+
+**After presenting the overview:**
+
+1. Present a table of contents for my level
+2. Ask: "Which topic would you like to explore first? Or type 'all' for a complete walkthrough."
+3. For each topic:
+   - Give a concise summary (2-3 key points)
+   - Ask: "Want to go deeper on this? (yes/next/skip)"
+   - If "yes": provide detailed explanation with examples
+   - If "next": move to next topic with brief summary
+   - If "skip": skip entirely
+
+### Phase 4: Practical Exercises (Optional)
+
+**If I want hands-on practice, suggest:**
+
+- For Beginners: "Try running `claude` and ask it to explain a file in your project"
+- For Intermediate: "Use Plan Mode (Shift+Tab x2) on your next feature"
+- For Power Users: "Create a custom agent for your most common task"
+
+## Output Format
+
+- Use tables for structured information
+- Use code blocks for commands and examples
+- Keep explanations concise unless I ask for details
+- Always end sections with a question to keep it interactive
+- Adapt your vocabulary and examples to my stated language
+
+## Key Principles
+
+1. **Interactive**: Always ask before dumping information
+2. **Progressive**: Build complexity gradually
+3. **Practical**: Focus on actionable knowledge
+4. **Respectful of time**: Let me control the pace
+5. **Multilingual**: Respond in my preferred language throughout
+
+## Start Now
+
+Begin by asking me about my preferred language.
+```
+
+---
+
+## 5. Example Interaction
+
+Here's how a typical onboarding session might go:
+
+**Claude**: What language would you prefer for this onboarding?
+
+**You**: French
+
+**Claude**: Parfait ! Quel est ton niveau actuel avec Claude Code ?
+- 🟢 Débutant
+- 🟡 Intermédiaire
+- 🔴 Power User
+
+**You**: Intermédiaire
+
+**Claude**: *[Presents tailored overview in French with focus on Plan Mode, context optimization, etc.]*
+
+Quel sujet veux-tu explorer en premier ?
+
+**You**: Plan Mode
+
+**Claude**: *[Explains Plan Mode with examples]*
+
+Tu veux approfondir ou passer au sujet suivant ?
+
+---
+
+## 6. Tips for Best Results
+
+| Tip | Why It Helps |
+|-----|--------------|
+| **Be honest about your level** | Gets you the right content, not too basic or advanced |
+| **Say "deeper" when curious** | Claude will provide more examples and edge cases |
+| **Say "skip" freely** | No need to cover what you already know |
+| **Ask for examples** | Practical examples solidify understanding |
+| **Request your language** | Works in any language Claude supports |
+
+---
+
+## 7. Related Resources
+
+- [The Ultimate Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md) - Full reference
+- [Claude Code Setup Audit](./audit-prompt.md) - Analyze your configuration
+- [Quick Reference Cheatsheet](../guide/cheatsheet.md) - Commands at a glance
+
+---
+
+## 8. Feedback
+
+Found this helpful? Have suggestions?
+- Star the repo: [claude-code-ultimate-guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)
+- Open an issue for improvements
+- Share with others learning Claude Code