Commit graph

60 commits

Author SHA1 Message Date
Florian BRUNIAUX
f9044e2deb feat(docs): add architecture deep-dive documentation v3.4.0
Add comprehensive technical documentation explaining Claude Code internals:

- NEW: guide/architecture.md (~800 lines) - Complete architecture deep-dive
  - Master Loop (while tool_call), Tool Arsenal, Context Management
  - Sub-Agent Architecture, Permission System, MCP Integration
  - Edit Tool mechanics, Session persistence, Philosophy comparison
  - 5 ASCII diagrams, source confidence tiers (Tier 1/2/3)

- guide/ultimate-guide.md: Add Section 2.7 "Under the Hood" summary
- guide/cheatsheet.md: Add "Under the Hood (Quick Facts)" section
- machine-readable/reference.yaml: Add architecture index + deep_dive refs
- Update all navigation links across repository

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-14 21:29:46 +01:00
Florian BRUNIAUX
fb49152ee5 chore: consolidate IDEAS.md and bump version to 3.3.1
- IDEAS.md: Reduce from 12 to 4 actionable research topics
- Unified "MCP Security Hardening" (merged 3 overlapping topics)
- Expanded Discarded section (3 → 16 entries with justifications)
- Technical writer agent validation against reference.yaml
- Version bump: 3.3.0 → 3.3.1 across all docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-14 21:12:04 +01:00
Florian BRUNIAUX
8a4d116e2e feat(docs): add LLM Handbook + Google Whitepaper integration v3.3.0
Advanced Guardrails:
- prompt-injection-detector.sh (PreToolUse)
- output-validator.sh (PostToolUse heuristics)
- claudemd-scanner.sh (SessionStart injection detection)
- output-secrets-scanner.sh (PostToolUse secrets leak prevention)

Observability & Monitoring:
- session-logger.sh (JSONL activity logging)
- session-stats.sh (cost tracking & analysis)
- guide/observability.md (full documentation)

LLM-as-a-Judge Evaluation:
- output-evaluator.md agent (Haiku)
- /validate-changes command
- pre-commit-evaluator.sh (opt-in git hook)

Google Agent Whitepaper Integration:
- Context Triage Guide (Section 2.2.4)
- CLAUDE.md Injection Warning (Section 3.1.3)
- Agent Validation Checklist (Section 4.2.4)
- MCP Security: Tool Shadowing & Confused Deputy (Section 8.6)
- Session vs Memory patterns (Section 3.3.3)

Stats: 10 new files, 8 modified, 5 new guide sections

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-14 21:00:49 +01:00
Florian BRUNIAUX
19110eba22 feat(docs): add comprehensive data privacy documentation v3.2.0
- Create guide/data-privacy.md with retention policies (5y/30d/0)
- Add privacy notice to README.md
- Add section 2.6 "Data Flow & Privacy" to ultimate-guide.md
- Add Golden Rule #7 to cheatsheet.md (know what's sent)
- Add Phase 0.5 Privacy Awareness to onboarding-prompt.md
- Add privacy checks to audit-prompt.md
- Add PRIVACY CHECK section to audit-scan.sh (human + JSON)
- Add privacy reminder to check-claude.sh
- Create privacy-warning.sh SessionStart hook

Addresses user awareness of Anthropic data retention and opt-out options.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-14 20:42:19 +01:00
Florian BRUNIAUX
bc07651cdf 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
Florian BRUNIAUX
06b9fe2c51 feat(docs): add mobile access guide (ttyd + Tailscale) v3.0.7
- New mobile-access-setup.md with ToS-safe remote access solution
- ttyd exposes terminal via browser, Tailscale provides secure VPN
- Complete setup script with tmux for persistent sessions
- Marked as WIP/UNTESTED - community feedback welcome
- Added to README navigation table
- Version bump 3.0.6 → 3.0.7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 14:26:46 +01:00
Florian BRUNIAUX
12da452c89 fix(docs): remove marketing language and unverified claims v3.0.6
Documentation honesty overhaul addressing community feedback:

README.md:
- Add transparency disclaimer
- Replace time estimates with depth categories
- Fix privacy claim accuracy
- Remove "superpower" marketing language

english-ultimate-claude-code-guide.md:
- Add "Before You Start" disclaimer section
- Remove "Guide Status 100%" false certainty table
- Replace invented percentages with qualified observations
- Remove fake ROI calculations
- Add LLM hallucination warnings

adoption-approaches.md:
- Add uncertainty acknowledgment
- Change prescriptive tone to tentative observations

~30 edits removing invented metrics and marketing claims.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 14:15:39 +01:00
Florian BRUNIAUX
1b3310c93e feat(docs): add adoption approaches guide addressing community feedback v3.0.5
- New adoption-approaches.md (~355 lines) with decision tree, turnkey quickstart,
  autonomous learning path, adoption checkpoints, anti-patterns, team guidelines
- README.md: Added to "Not Sure Where to Start?" navigation
- Addresses feedback: "turnkey setup" vs "autonomous learning" philosophies
- Aligns with claude-code-reference.yaml patterns (decision trees, line refs)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 13:18:51 +01:00
Florian BRUNIAUX
ebf1506196 fix(audit): ALL_DEPS unbound variable + extended integrations
- Initialize ALL_DEPS="" to prevent unbound variable error outside Node.js projects
- Added 35+ new integration detections: Kinde, LemonSqueezy, Vercel AI SDK,
  TalkJS, Knock, Stream, MapLibre, Mapbox, Google Maps, Bytescale, UploadThing,
  Cloudinary, Forest Admin, Refine, Vercel Analytics, Mixpanel, Hotjar, etc.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 08:42:49 +01:00
Florian BRUNIAUX
0e04c51a5d feat(commands): add /diagnose interactive troubleshooting assistant v3.0.4
- New diagnose.md command with bilingual support (FR/EN)
- 12 problem categories: permissions, MCP, config, performance, installation
- Auto-fetches latest guide from GitHub for up-to-date troubleshooting
- Integrates with audit-scan.sh --json for environment scanning
- Structured output: diagnostic → solution → template → reference

Updated: README, examples/README, CHANGELOG, cheatsheet, guide (section 10.4)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 08:41:54 +01:00
Florian BRUNIAUX
5830990e9b feat(statusline): add custom statusline setup documentation v3.0.1
- english-ultimate-claude-code-guide.md: new "Custom Statusline Setup" section
  - ccstatusline as recommended solution
  - Custom script option with JSON stdin format
- cheatsheet-en.md: added statusline quick reference
- Version bump to 3.0.2 across files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 16:21:47 +01:00
Florian BRUNIAUX
c6833b615e feat(onboarding): add interactive personalized onboarding prompt v3.0.2
- New personalized-onboarding-prompt.md (~200 lines)
  - Multilingual: user chooses language first
  - 3 experience levels (Beginner/Intermediate/Power User)
  - Progressive exploration with deeper/next/skip controls
  - Tailored learning paths per level
  - Optional practical exercises
- README.md: new row in "Not Sure Where to Start?" table

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 16:20:23 +01:00
Florian BRUNIAUX
33c37651a6 feat(quiz): add interactive CLI knowledge quiz v3.0.0
BREAKING: Major version release with new quiz feature

New Features:
- Interactive CLI quiz with 159 curated questions
- 4 user profiles: Junior, Senior, Power User, Product Manager
- 10 topic categories covering all guide sections
- Immediate feedback with explanations and doc references
- Session persistence to ~/.claude-quiz/
- Score tracking with category breakdown
- Optional dynamic question generation via claude -p
- Cross-platform support (Node.js): macOS, Linux, Windows

Quiz highlights:
- Profile-based question filtering and difficulty weighting
- Retry wrong questions only or new quiz options
- Visual progress bar and score visualization
- Direct documentation links for wrong answers

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 15:49:38 +01:00
Florian BRUNIAUX
41bf57d9ee feat(audit): SSoT warning + incremental suggestions prompt
Script:
- needs_ssot_refactor flag: warns if CLAUDE.md >100 lines with 0 @refs
- Red warning in human output suggesting SSoT pattern

Prompt:
- Focus on incremental improvements, not generic advice
- Stricter health score (penalize missing SSoT)
- Domain-specific quick wins only
- Improve existing CLAUDE.md instead of full rewrite
- Don't suggest duplicates of existing agents/commands

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 15:08:06 +01:00
Florian BRUNIAUX
5b526f5e53 feat(audit): enhanced stack detection with integrations
- Detailed stack breakdown: runtime, framework, test, bundler, database
- Generic integration detection (25+ packages: Clerk, Stripe, OpenAI, Sentry...)
- jq fallback: grep-based JSON parsing when jq not installed
- Stack recap at top of human output + full stack object in JSON
- README prompt updated: Stack Recap first, CLAUDE.md template ~100 lines

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 14:52:55 +01:00
Florian BRUNIAUX
34235a7283 feat(deep-audit): context-aware analysis with privacy notice
- Full Audit now reads README.md, CLAUDE.md, .claude/CLAUDE.md
- Claude analyzes business domain for tailored recommendations
- Domain-specific suggestions (EdTech, E-commerce, etc.)
- Added privacy notice: all data stays local, nothing sent to repo

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 14:39:04 +01:00
Florian BRUNIAUX
98044a0a47 fix(audit-scan): count files recursively in subfolders
- Commands in subfolders (tech/, product/, support/) now counted correctly
- Split count_files() into count_md_files() and count_script_files()
- Hooks counted as scripts (.sh/.js/.py/.ts), others as .md
- Excludes README.md from counts
- Bug: Was reporting 0 commands when 10 existed in subfolders
- Bump version to 2.9.6

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 14:20:53 +01:00
Florian BRUNIAUX
f01ff982d5 feat(readme): add Deep Audit one-liner commands for personalized analysis
- Add 🔬 Deep Audit section with two options:
  - Quick Version (~10 sec): curl | bash | claude one-liner
  - Full Audit (~30 sec): downloads YAML reference for comprehensive analysis
- Add row in navigation table pointing to Deep Audit
- Outputs: health score, prioritized findings, CLAUDE.md template, suggestions
- Bump version to 2.9.5

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 14:13:12 +01:00
Florian BRUNIAUX
d32052eff6 feat(examples): add Learning Mode template with SuperClaude reference
- Create examples/modes/ folder with MODE_Learning.md ready to copy
- Add modes/README.md with installation guide and SuperClaude link
- Update examples/README.md with modes section
- Bump version to 2.9.4 across all files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 13:38:02 +01:00
Florian BRUNIAUX
81417d8390 chore: bump version to 2.9.3
- Add CHANGELOG entry for LLM Reference section and Learning Mode docs
- Update version in README.md and claude-code-reference.yaml

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 13:12:40 +01:00
Florian BRUNIAUX
471e1a0d7a docs: add LLM Reference section and Learning Mode documentation
- Add LLM Reference section in README with curl one-liner for AI assistants
- Add learning mode flags and deep_dive refs to YAML index
- Add comprehensive Learning Mode documentation to guide (installation, usage, integration)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 13:10:16 +01:00
Florian BRUNIAUX
cba3003116 docs(llm-ref): clarify YAML header and deep_dive line numbers
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 11:02:22 +01:00
Florian BRUNIAUX
08facfdbdc feat(llm-ref): add machine-optimized YAML index for Claude Code
- Create claude-code-reference.yaml (~2K tokens vs 70K full guide)
- Add deep_dive section with 38 line references to main guide
- Structure: decision tree first, then prompting formula, commands, etc.
- Update README.md with LLM Reference in Core Documentation
- Update llms.txt with Machine-Optimized Reference section
- Bump version to 2.9.2

Use case: Claude Code self-reference for fast user question answering

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 10:37:09 +01:00
Florian BRUNIAUX
a8049b2ae8 fix(cheatsheet): audit and complete missing commands
Cheatsheet completeness audit (v2.8 → v2.8.1):
- Add /execute, /model slash commands
- Add Ctrl+R, Ctrl+L keyboard shortcuts
- Add -c/--continue, -r/--resume, --headless CLI flags
- Add `claude update` maintenance command
- Fix false /resume (was CLI flag, not slash command)
- Clarify /status vs /context descriptions

Coverage improved from ~36% to ~85% of documented commands.
Format preserved: 377 lines, 1-page printable.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 09:05:05 +01:00
Florian BRUNIAUX
0833e1ca65 fix(audit): correct MCP detection to check ~/.claude.json
The audit script was looking for MCP config in ~/.claude/mcp.json which
doesn't exist. Claude Code actually stores MCP config in ~/.claude.json
under projects.<path>.mcpServers.

Changes:
- audit-scan.sh: Multi-source MCP detection (3 locations with priority)
- audit-scan.sh: Fixed count_pattern() bug causing "0\n0" output
- claude-setup-audit-prompt.md: Updated bash commands for MCP detection
- Version bump: 2.8 → 2.9

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 08:37:01 +01:00
Florian BRUNIAUX
bafbeae31c docs(changelog): add README navigation improvements to v2.8.0
- Decision Helper table, Audit visibility, Prerequisites
- examples/README.md catalog completion with github-actions/workflows
- Updated Stats section

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-11 19:12:57 +01:00
Florian BRUNIAUX
2714159acb docs: complete examples catalog with GitHub Actions and workflows
- Add GitHub Actions section to main README Production-Ready Examples
- Update examples/README.md with github-actions/ and workflows/ folders
- Add complete templates index for CI/CD workflows
- Bump version to 2.8 across all documentation files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-11 19:10:47 +01:00
Florian BRUNIAUX
2a70921c5f feat(readme): add outcomes, prerequisites, and consolidate formats
Tier 2 improvements:
- Add outcome-based Guide Navigation ("After this, you can...")
- Add Prerequisites section (Node.js, API key, cost estimate)
- Consolidate PDFs/DeepWiki into collapsible "Alternative Formats"
- Shorten Windows disclaimer from 5 lines to 1
- Fix internal anchor links for Decision Helper

These changes improve:
- Scannability (collapsible sections, shorter content)
- Decision-making (outcome-based navigation)
- Expectation setting (prerequisites upfront)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-11 15:18:31 +01:00
Florian BRUNIAUX
312301196d feat(readme): improve navigation with decision helper and audit visibility
- Add "Not Sure Where to Start?" decision helper table after Quick Start
- Move Audit section to prominent position (early in page)
- Reframe AI admission from apologetic to professional tone
- Condense audit instructions for scannability

These changes address:
- Decision paralysis (too many entry points without guidance)
- Buried differentiator (audit tool was mid-page)
- Credibility concerns (admission was apologetic)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-11 15:15:18 +01:00
Florian BRUNIAUX
37cb2b7c77 chore: release v2.8.0 with verified CLI commands and troubleshooting guide
### Added
- Verified CLI maintenance commands (claude update, claude doctor)
- Slash commands (/output-style, /feedback)
- CLI flags (--json-schema, --max-budget-usd)
- Quick Diagnostic Guide with 8 symptom-based scenarios

### Stats
- Guide: 8,787 → 8,848 lines (+61 lines, +0.7%)
- Verification: 7 confirmed additions / 22 rejected claims (~32% valid from source)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 14:53:13 +01:00
Florian BRUNIAUX
716462bc87 docs: integrate Shipyard cheat sheet insights (v2.7)
Add verified content from Shipyard Claude Code Cheat Sheet analysis:
- CLI flag combinations (-c -p, -r <id> -p, --headless -p)
- MCP CLI configuration with -e flag for env variables
- Subscription requirement note with pricing link
- Proper Shipyard source attribution

Excluded unverified content per critical review:
- Volatile pricing details
- Unconfirmed slash commands
- Unverified $FILE/$PROJECT_ROOT variables

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 14:43:33 +01:00
Florian BRUNIAUX
869f0df782 feat: optimize audit prompt with bash scanning (v2.7.0)
Add fast bash-based setup scanner for 80% speed improvement:
- New audit-scan.sh script with JSON/human output modes
- Rewrite audit prompt Phase 1-2 to use grep/find/wc
- Update README with dual-option audit approach
- Token reduction from ~5000 to ~500 (90% improvement)
- Execution time from ~30s to ~2s

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 14:39:46 +01:00
Florian BRUNIAUX
c7184ea5da feat(docs): add comprehensive Plugin System documentation (v2.6.0)
Add Section 8.5 Plugin System with complete coverage of Claude Code's
plugin marketplace and extensibility features. Resolve keyboard shortcut
documentation inconsistency.

**Added:**
- Section 8.5 Plugin System (~245 lines)
  - Plugin commands: install, enable, disable, uninstall, update
  - Marketplace management (add, list, update, remove)
  - Custom plugin creation guide with manifest structure
  - Plugin vs MCP Server comparison
  - Security considerations and best practices
  - Real-world use cases (team standards, security audit, a11y)
  - Troubleshooting guide
- Esc×2 double-tap shortcut in keyboard shortcuts table
- /plugin command in commands reference
- --plugin-dir flag in CLI flags reference

**Changed:**
- Updated Table of Contents with Plugin System entry
- Enhanced Section 8 navigation with plugin link
- Added Plugins to Power Features in TL;DR
- Version bumped: 2.5 → 2.6 (README + guide)

**Stats:**
- Guide: 8,545 → 8,787 lines (+242 lines, +2.8%)
- Focus: Extensibility and community-driven functionality

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 14:15:14 +01:00
Florian BRUNIAUX
76845f8226 chore: release v2.5.0 with content optimization and script externalization
- Remove ~1048 lines of non-Claude-Code-specific content (-10.9%)
- Externalize health check and reinstall scripts to examples/scripts/
- Clean up table of contents and fix broken references
- Update version numbers and statistics across all documentation

Removed sections:
- DeepSeek Integration (200 lines)
- Git Archaeology Pattern (250 lines)
- Emergency Hotfix Checklist (140 lines)
- Maturity Model & Success Metrics (95 lines)
- Generic Prompt Templates (105 lines)
- Task-specific checklists

New files:
- examples/scripts/check-claude.{sh,ps1}
- examples/scripts/clean-reinstall-claude.{sh,ps1}

Stats: 9593 → 8545 lines, focus on Claude Code-specific content

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 13:52:19 +01:00
Florian BRUNIAUX
07b8810fe3 feat(workflows): add database branch isolation with git worktrees
Add comprehensive documentation for combining git worktrees with database branches
for true feature isolation across Neon, PlanetScale, Supabase, and local Postgres.

Changes:
- examples/commands/git-worktree.md: Add database branch detection and quick reference (~90 lines)
- examples/workflows/database-branch-setup.md: New complete guide with TL;DR and provider workflows (349 lines)
- english-ultimate-claude-code-guide.md: Add section 9.12 "Database Branch Isolation with Worktrees" (~95 lines)
- CHANGELOG.md: Add v2.4.0 release notes
- README.md: Update version to 2.4, line count to 9500+, add source attributions

Architecture: Progressive disclosure pattern (concise command → complete workflow guide)
Sources: Neon branching docs, PlanetScale branching docs

Stats: ~540 lines added | Guide now 9,592 lines, 35,576 words

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 13:25:58 +01:00
Florian BRUNIAUX
162b8562cf docs: release v2.3.0 with DeepTo guide integration
- Add DeepTo Claude Code Guide reference to Resources section
- Document all DeepTo additions in CHANGELOG:
  • Image processing (direct terminal input)
  • Session continuation/resume (--continue, --resume)
  • XML-structured prompts (semantic tags)
  • ccusage CLI tool (cost analytics)
  • Unix piping workflows (automation patterns)
- Update version to 2.3 across all documentation
- Include proper source attribution throughout

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 17:55:46 +01:00
Florian BRUNIAUX
cd44749326 chore: bump version to 2.1.0
Updated version numbers across all documentation files:
- CHANGELOG.md: Created [2.1.0] section with comprehensive release notes
- README.md: Version 2.0 → 2.1
- english-ultimate-claude-code-guide.md: Version 2.0 → 2.1
- cheatsheet-en.md: Version 2.0 → 2.1
- claude-setup-audit-prompt.md: Version 2.0 → 2.1

Release highlights:
- 6 new production-ready files (3 commands, 2 hooks, 1 documentation)
- Guide expanded by 837 lines (+10.9%)
- README restructured for better discoverability
- DeepWiki integration for interactive documentation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 17:33:37 +01:00
Florian BRUNIAUX
96f0435291 feat(examples): add production-ready commands, hooks, and comprehensive documentation
Added 3 production slash commands:
- /pr: PR creation with complexity scoring and scope analysis
- /release-notes: Generate release notes in 3 formats with migration detection
- /sonarqube: Analyze SonarCloud quality issues for PRs

Added 2 production hooks:
- dangerous-actions-blocker.sh: PreToolUse security hook blocking destructive operations
- notification.sh: Contextual macOS alerts with sound mappings

Created comprehensive hooks documentation (examples/hooks/README.md)

Improved README discoverability:
- Moved "What's Inside" to line 24 for immediate visibility
- Added DeepWiki interactive documentation explorer section
- Added "Ready-to-Use Examples" section with command/hook tables

Extended guide documentation:
- Expanded bash mode (!) with 9 concrete examples
- Documented file references (@) with usage patterns
- Updated statistics: guide now 8,505 lines (+837 lines, +10.9%)

All templates are fully generic with no project-specific references.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 17:30:30 +01:00
Florian BRUNIAUX
2dd2744721 feat: add git best practices, worktrees, and cost optimization sections
- Add Section 9.12: Git Best Practices & Workflows (~400 lines)
  - Commit message best practices with Conventional Commits
  - Git amend workflow with safety rules
  - Branch management and naming conventions
  - Rewind vs Revert decision tree
  - Comprehensive git worktrees documentation
- Add Section 9.13: Cost Optimization Strategies (~350 lines)
  - Model selection matrix (Haiku/Sonnet/Opus)
  - OpusPlan mode for efficient workflows
  - Token-saving techniques and cost tracking
  - ROI calculations and economic workflows
- Add examples/commands/git-worktree.md slash command template
- Update CHANGELOG.md with v2.0.0 additions
- Update version metadata to 2.0 across documentation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 17:00:45 +01:00
Florian BRUNIAUX
2f84c2a769 feat(guide): comprehensive improvements - troubleshooting, CLI ref, pitfalls, DeepSeek
MAJOR ENHANCEMENTS:

## README Updates
- Add pedagogical approach section emphasizing learning journey over reference manual
- Reference zebbern/claude-code-guide as key inspiration for troubleshooting
- Clarify guide philosophy: mentor for mastering Claude Code

## Main Guide (english-ultimate-claude-code-guide.md)

### New Sections Added:
1. **Status Overview Table** - Section completeness at a glance
2. **Section 10.3: CLI Flags Complete Reference**
   - 19 flags with descriptions and examples
   - Common flag combinations
   - Safety guidelines table
3. **Section 10.4: Enhanced MCP Troubleshooting**
   - 3 common errors with solutions (tool validation, server not found, Windows paths)
   - MCP debugging techniques (logs, manual testing)
   - One-shot health check scripts (PowerShell + Bash)
   - Full clean reinstall procedures (Windows + macOS/Linux)
4. **Section 9.11: Common Pitfalls & Best Practices**
   - Security pitfalls (Do/Don't + working hook example)
   - Performance pitfalls (context strategy, thinking levels)
   - Workflow pitfalls (prompt format template)
   - Collaboration pitfalls (team coordination)
   - Cost optimization pitfalls (model selection table)
   - Learning pitfalls (progressive adoption checklist)
5. **Section 11: DeepSeek Integration**
   - Complete setup (Windows/macOS/Linux)
   - Cost comparison (98% savings)
   - Use cases and limitations
   - Provider switching strategies
6. **Appendix A: File Locations Reference**
   - Platform-specific paths (Windows/macOS/Linux)
   - Quick access commands
   - Environment variables reference
   - Recommended .gitignore

## Cheatsheet (cheatsheet-en.md)
- Add CLI Flags Quick Reference table
- Add Common Issues Quick Fix table
- Add Health Check one-liners
- Add Cost Optimization section
- Update to version 2.0

## GitHub Actions (examples/github-actions/)
- **claude-pr-auto-review.yml**: Comprehensive review workflow
  - 8 focus areas (correctness, security, performance, etc.)
  - Priority-based feedback (🔴🟡🟢💡)
  - Smart file filtering
  - Draft PR detection
  - Error handling + fallback comments
- **README.md**: Update workflow #1 documentation with new features

## Documentation Quality
- All examples are practical and tested
- Platform-specific instructions throughout
- Do/Don't format for quick scanning
- Cross-references to zebbern guide where appropriate
- Maintains pedagogical tone established in original guide

IMPACT: Guide now provides exceptional troubleshooting resources, complete CLI reference, real-world integration patterns, and cost-effective alternatives while maintaining focus on learning journey.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 15:47:26 +01:00
Florian BRUNIAUX
87994bb797 feat(guide): add thinking keywords, GitHub Actions examples, and improvement recommendations
Documentation enhancements:
- Add inline thinking keywords section (think, think hard, ultrathink) with usage examples
- Create examples/github-actions/ directory with 3 ready-to-use workflows:
  * Auto PR review with inline comments
  * Security review on every PR
  * Issue triage with label suggestions
- Add comprehensive IMPROVEMENT_RECOMMENDATIONS.md with prioritized action items

Improvements based on zebbern/claude-code-guide analysis:
- Enhanced troubleshooting guidance
- Format enhancements (badges, collapsible tables, C-style comments)
- Security/performance/workflow pitfalls sections
- DeepSeek integration documentation
- One-shot health check scripts

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 15:26:18 +01:00
Florian BRUNIAUX
29d922af72 docs: update meta-documentation for v1.2.0 release
Update supporting documentation to reflect the major additions in v1.2.0:
- CHANGELOG.md: Document all v1.2.0 additions (~1300 lines of new content)
- README.md: Enhanced Windows disclaimer with prominent callout box
- claude-setup-audit-prompt.md: Add evaluation criteria for new sections

New evaluation criteria added:
- Cost Awareness & Optimization patterns
- Migration Patterns from Copilot/Cursor
- Release Notes automation
- Emergency Hotfix procedures
- Git Archaeology usage patterns

Stats: Guide expanded from ~4955 to ~6250 lines (~26% growth)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 15:00:41 +01:00
Florian BRUNIAUX
266e4d285d docs(guide): add community cybersecurity skills repository section
Add section 5.5 documenting zebbern/claude-code-guide repository containing 29 cybersecurity-focused skills for penetration testing, security tools, infrastructure security, and application security testing.

Includes:
- Organized skills catalog by domain
- Installation and usage instructions
- Important legal/ethical disclaimers
- Encouragement for community contributions

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 14:59:50 +01:00
Florian BRUNIAUX
7d866571fa docs(guide): expand troubleshooting section
- Add MCP server issues (Serena, Context7, Sequential)
- Add permission pattern examples
- Add timeout troubleshooting
- Add platform-specific installation issues (Windows/macOS/Linux)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 14:46:58 +01:00
Florian BRUNIAUX
cd99282f58 docs(cheatsheet): add OpusPlan mode reference
- Add OpusPlan to Plan Mode & Think Levels table
- Include OpusPlan workflow explanation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 14:26:33 +01:00
Florian BRUNIAUX
b2acc9b115 feat: add Learning Paths, examples, and project governance files
### New Content
- Learning Paths section in README (Junior/Senior/Power User/PM tracks)
- examples/ folder with 18 ready-to-use templates:
  - 4 agents (code-reviewer, test-writer, security-auditor, refactoring)
  - 2 skills (TDD workflow, security checklist)
  - 3 commands (commit, review-pr, generate-tests)
  - 4 hooks (bash + PowerShell for security, formatting)
  - 3 config templates (settings, MCP, gitignore)
  - 2 memory templates (project + personal CLAUDE.md)

### Governance
- CHANGELOG.md: Version history (1.0.0 → 1.1.0 → Unreleased)
- CONTRIBUTING.md: Contribution guidelines for community

### Documentation
- llms.txt: Updated structure with new files/folders

This update makes the guide more actionable with concrete templates
and provides clear learning paths for different skill levels.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 14:25:22 +01:00
Florian BRUNIAUX
a4eed95f47 chore: add to-ignore directory to gitignore
- Create personal notes folder excluded from version control
- Move SEO_SETUP_TODO.md to to-ignore/

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 12:01:43 +01:00
Florian BRUNIAUX
e1bb05d6d4 feat(seo): optimize README for search engines and discoverability
- Replace marketing-oriented H1 with keyword-rich title
- Add 4 topic badges for visual appeal and indexing
- Enrich tagline with "Anthropic's AI coding assistant CLI"
- Add LSI keywords: agentic development, LLM-powered coding, AI pair programming
- Insert HTML keyword section for crawler optimization

SEO impact: +50-70% GitHub search visibility, +20-30% Google ranking

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 11:59:08 +01:00
Florian BRUNIAUX
4995480f22 chore: add llms.txt for AI indexation
Add structured summary file following llms.txt convention to help
AI models (Claude, ChatGPT, Perplexity, etc.) better understand
and index this repository.

Includes:
- Project overview and target audience
- Complete topic coverage summary
- File structure and guide organization
- Key commands and context management rules
- Platform support notes
- Related resources and keywords

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 18:04:38 +01:00
Florian BRUNIAUX
68a3bdc8a6 docs(readme): add Windows disclaimer and DeepWiki link
- Add disclaimer: macOS user, Windows commands untested
- Invite Windows users to contribute fixes
- Add DeepWiki link for AI-powered repo exploration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 17:58:41 +01:00