feat: native plugin architecture with interactive courses and changelog reports (v1.1.0)

[costiash]

Summary

Transforms claude-code-docs from a script-based tool into a native Claude Code Plugin with a 4-skill architecture:

• claude-docs — 4-tier search skill (direct → scoped → content → fuzzy) with shell scripts, worked examples, and SDK language disambiguation
• claude-docs-validate — HTTP reachability checks with --quick mode
• claude-docs-course — Interactive HTML course generator with Obsidian & Amber design theme (Instrument Serif + Outfit typography, dark obsidian backgrounds, warm amber accents, grain textures, 18 interactive element patterns including Protocol Conversations)
• claude-docs-changelog — HTML changelog reports of recent doc changes via git history, with "Create Course" buttons that copy course commands to clipboard

Key changes

• /docs command rewritten as lean skill router (~54 lines) with routes: --course <topic>, --report [timeframe], -t, --stats, and default search
• Post-response course prompt added to search skill — every docs answer invites users to generate an interactive course
• Plugin version bumped to 1.1.0
• All project docs updated (README, CLAUDE.md, CHANGELOG, CONTRIBUTING)
• .gitignore updated to exclude reference projects and generated HTML

New files (8)

File	Purpose
plugin/skills/claude-docs-course/SKILL.md	4-phase docs-to-course pipeline
plugin/skills/claude-docs-course/references/design-system.md	Obsidian & Amber CSS tokens
plugin/skills/claude-docs-course/references/interactive-elements.md	18 interactive element patterns
plugin/skills/claude-docs-course/examples/course-from-docs.md	Worked example
plugin/skills/claude-docs-changelog/SKILL.md	Changelog report generator
plugin/skills/claude-docs-changelog/examples/changelog-report.md	Worked example
plugin/skills/claude-docs/scripts/content-search.sh	Full-text keyword search
plugin/skills/claude-docs/scripts/fuzzy-search.sh	Fuzzy filename matching

Test plan

• Search scripts work: DOCS_DIR=./docs ./plugin/skills/claude-docs/scripts/content-search.sh "hooks"
• Fuzzy search works: DOCS_DIR=./docs ./plugin/skills/claude-docs/scripts/fuzzy-search.sh "agent sdk"
• Course generation produces valid self-contained HTML (tested with "prompt caching" topic)
• Changelog report generates correct HTML with working "Create Course" buttons (clipboard copy + toast)
• Obsidian & Amber theme renders correctly (dark backgrounds, amber accents, grain texture, serif headings)
• Code review passed — version bump, color label fixes, stale value cleanup all addressed

🤖 Generated with Claude Code

[github-actions]

Coverage report

This PR does not seem to contain any modification to coverable code.

[claude]

hello test

[claude]

Claude Code Documentation Mirror - Enhanced Edition

⛔ CRITICAL: UPSTREAM ISOLATION ⛔

This repository is COMPLETELY INDEPENDENT. Do NOT:

• Push to, pull from, or sync with the upstream repo (ericbuess/claude-code-docs)
• Create PRs to the upstream repo
• Add upstream as a remote
• Reference upstream in any git operations

All git operations must target origin (costiash/claude-code-docs) ONLY.

This repository contains local copies of Claude documentation from multiple Anthropic sources:

• Platform docs: https://platform.claude.com (API, guides, Agent SDK, etc.)
• Claude Code docs: https://code.claude.com/docs (CLI-specific documentation)

The docs are periodically updated via GitHub Actions with safeguards to prevent mass deletion.

Architecture: Plugin-Based Documentation System

This repository delivers documentation via a Claude Code plugin. The plugin provides:

• /docs command — Routes queries to the appropriate skill
• claude-docs/ skill — Auto-discovery + search (content search, fuzzy matching, direct lookups)
• claude-docs-validate/ skill — Documentation health checks and freshness validation
• SessionStart hook — Auto-updates docs via git pull on each session start

Plugin Structure

plugin/
├── commands/docs.md              # /docs command (lean router)
├── skills/
│   ├── claude-docs/              # Search skill (auto-discovery)
│   │   ├── SKILL.md              # Search strategy and synthesis rules
│   │   ├── manifest-reference.md # Category-to-label mapping (single source of truth)
│   │   ├── examples/             # Worked examples for Claude
│   │   └── scripts/              # content-search.sh, fuzzy-search.sh
│   ├── claude-docs-validate/     # Validation skill
│   │   ├── SKILL.md              # Health check instructions
│   │   ├── examples/             # Worked examples
│   │   └── scripts/              # validate-paths.sh
│   └── claude-docs-course/       # Interactive course generator
│       ├── SKILL.md              # Course generation workflow (Obsidian & Amber theme)
│       ├── references/           # design-system.md, interactive-elements.md
│       └── examples/             # Worked examples
└── hooks/                        # SessionStart auto-sync

Search intelligence lives in the skills, not in CLAUDE.md. See plugin/skills/claude-docs/SKILL.md for search strategy details.

For /docs Command

The /docs command is handled by the plugin's lean router at plugin/commands/docs.md. It delegates to:

• claude-docs skill — For all documentation lookups, questions, and searches
• claude-docs-validate skill — For freshness checks (-t) and health validation
• claude-docs-course skill — For interactive course generation (--course <topic>)
• claude-docs-changelog skill — For HTML changelog reports (--report)
• Inline git log — For "what's new" queries

Search intelligence, synthesis rules, and URL generation live in plugin/skills/claude-docs/SKILL.md. Category mappings are in plugin/skills/claude-docs/manifest-reference.md (single source of truth).

CI/CD Scripts (Python, repo-only)

The scripts/ directory contains Python modules that run in GitHub Actions — they are not user-facing and are not installed with the plugin:

• scripts/fetcher/ — Fetches docs from Anthropic sitemaps (every 3 hours)
• scripts/lookup/ — Path validation for CI checks (daily)
• scripts/build_search_index.py — Generates .search_index.json consumed by the plugin's content search
• scripts/fetch_claude_docs.py — Thin wrapper for fetcher package
• scripts/lookup_paths.py — Thin wrapper for lookup package

These require Python 3.9+ and are only executed in GitHub Actions workflows.

Repository Structure

/
├── docs/                   # Documentation files (.md format)
│   ├── docs_manifest.json  # File tracking manifest
│   └── .search_index.json  # Full-text search index (CI-generated)
├── scripts/                # CI-only Python scripts
│   ├── fetch_claude_docs.py        # Thin wrapper for fetcher
│   ├── lookup_paths.py             # Thin wrapper for lookup
│   ├── build_search_index.py       # Index builder
│   ├── fetcher/                    # Documentation fetching package (8 modules)
│   └── lookup/                     # Search and validation package (7 modules)
├── plugin/                 # Claude Code Plugin (v1.1.0)
│   ├── .claude-plugin/plugin.json  # Plugin metadata
│   ├── commands/docs.md            # /docs slash command (lean router)
│   ├── skills/
│   │   ├── claude-docs/            # Search skill + examples + scripts
│   │   ├── claude-docs-validate/   # Validation skill + examples + scripts
│   │   ├── claude-docs-course/     # Interactive course generator + references
│   │   └── claude-docs-changelog/  # Changelog report generator + examples
│   └── hooks/                      # SessionStart hook (auto-update docs)
├── .claude-plugin/marketplace.json # Marketplace registration
├── paths_manifest.json     # Active paths manifest (auto-generated categories)
├── pyproject.toml          # Python project configuration
├── CHANGELOG.md            # Version history
├── tests/                  # Test suite (CI-only, covers Python scripts)
├── reports/                # Coverage and test reports
├── install.sh              # Migration wrapper (routes to plugin install)
├── uninstall.sh            # Points to plugin uninstall
├── index.html              # GitHub Pages landing page
└── CLAUDE.md               # This file (AI context)

Key Files

When working on this repository, read these files as needed (not auto-loaded to save context):

Plugin Files

• plugin/.claude-plugin/plugin.json - Plugin metadata (version, hooks)
• plugin/commands/docs.md - /docs command (lean router)
• plugin/skills/claude-docs/SKILL.md - Search skill (auto-discovery, search strategy, synthesis rules)
• plugin/skills/claude-docs/manifest-reference.md - Category-to-label mapping (single source of truth)
• plugin/skills/claude-docs/scripts/content-search.sh - Full-text keyword search
• plugin/skills/claude-docs/scripts/fuzzy-search.sh - Fuzzy filename matching
• plugin/skills/claude-docs/examples/ - Worked examples for search workflows
• plugin/skills/claude-docs-validate/SKILL.md - Validation skill instructions
• plugin/skills/claude-docs-course/SKILL.md - Interactive course generator (Obsidian & Amber theme)
• plugin/skills/claude-docs-course/references/design-system.md - Course visual design tokens
• plugin/skills/claude-docs-course/references/interactive-elements.md - HTML/CSS/JS patterns for course elements
• plugin/skills/claude-docs-changelog/SKILL.md - Changelog report generator (Obsidian & Amber theme)
• plugin/skills/claude-docs-validate/scripts/validate-paths.sh - HTTP reachability checks
• plugin/hooks/hooks.json + sync-docs.sh - SessionStart hook (auto-update docs)
• .claude-plugin/marketplace.json - Marketplace registration

CI/CD Scripts (Python)

• scripts/fetch_claude_docs.py - Documentation fetcher entry point
• scripts/lookup_paths.py - Search & validation entry point
• scripts/fetcher/ - Documentation fetching package (8 modules)
• scripts/lookup/ - Search & validation package (7 modules)
• scripts/build_search_index.py - Full-text search indexing
• paths_manifest.json - Active paths manifest (auto-generated categories)
• tests/ - Test suite (covers CI scripts)

Automation

• .github/workflows/ - Auto-update workflows (runs every 3 hours)

Documentation Deletion Safeguards

The automated sync system includes multiple safeguards to prevent catastrophic documentation loss. These were implemented after a critical bug where 80%+ of documentation was deleted due to broken sitemap URLs.

Safety Thresholds (in scripts/fetcher/config.py)

Constant	Value	Purpose
MIN_DISCOVERY_THRESHOLD	200	Minimum paths that must be discovered from sitemaps
MAX_DELETION_PERCENT	10	Maximum percentage of files that can be deleted in one sync
MIN_EXPECTED_FILES	250	Minimum files that must remain after sync

How Safeguards Work

1. Discovery Validation: Before fetching, validates that sitemap discovery found enough paths
2. Deletion Limiting: cleanup_old_files() refuses to delete more than 10% of existing files
3. File Count Validation: Refuses to proceed if result would have fewer than 250 files
4. Workflow Validation: GitHub Actions validates sync success before committing

Sitemap Sources

Documentation is discovered from two sitemaps:

• https://platform.claude.com/sitemap.xml - Platform documentation (API, guides, etc.)
• https://code.claude.com/docs/sitemap.xml - Claude Code CLI documentation

Filename Conventions

Files are named based on their source:

• Claude Code CLI docs: claude-code__<page>.md (e.g., claude-code__hooks.md) → https://code.claude.com/docs/en/<page>
• Platform docs: docs__en__<section>__<page>.md (e.g., docs__en__agent-sdk__python.md) → https://platform.claude.com/en/docs/<section>/<page>

Working on This Repository

Development Setup

# Install Python dependencies for CI scripts (uses uv)
uv sync --group dev

Testing

# Test plugin search scripts manually
DOCS_DIR=./docs ./plugin/skills/claude-docs/scripts/content-search.sh "hooks"
DOCS_DIR=./docs ./plugin/skills/claude-docs/scripts/fuzzy-search.sh "agent sdk"
DOCS_DIR=./docs ./plugin/skills/claude-docs-validate/scripts/validate-paths.sh --quick

# Test CI Python scripts
python3 scripts/lookup_paths.py --search "mcp"
pytest tests/ -v

# Run full CI test suite
pytest tests/ -q

Upstream Compatibility

This enhanced edition maintains compatibility with upstream (ericbuess/claude-code-docs):

• Same installation location (~/.claude-code-docs)
• Same /docs command interface
• Plugin features are additive, not breaking

[claude]

Changelog - Enhanced Edition

All notable changes to the enhanced edition of claude-code-docs will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[1.1.0] - 2026-03-28

Added

• claude-docs-course/ interactive course skill: Generates self-contained HTML courses on any Claude documentation topic
  • 4-phase pipeline: Topic Discovery → Curriculum Design → Build (module by module) → Review & Open
  • Obsidian & Amber design theme: Dark obsidian backgrounds, warm amber accents, Instrument Serif + Outfit typography, grain textures, glass-morphism effects
  • references/design-system.md — Complete CSS design tokens for the Obsidian & Amber theme
  • references/interactive-elements.md — 18 interactive element patterns including Protocol Conversations, code translations, quizzes, data flow animations, glossary tooltips
  • examples/course-from-docs.md — Worked example for hooks course generation
  • Courses saved to ~/.claude-code-docs/courses/<topic-slug>.html
• claude-docs-changelog/ report skill: Generates HTML changelog reports of recent documentation changes
  • Discovers changes via git history, categorizes by doc type, summarizes key updates
  • Each entry includes a "Create Course" button that copies /docs --course <topic> to clipboard
  • Obsidian & Amber themed to match courses
  • examples/changelog-report.md — Worked example
• Post-response course prompt: After every docs response, an emphasized prompt invites users to generate an interactive course on the topic
• /docs --course <topic> route: Direct course generation via the /docs command
• /docs --report route: Generate HTML changelog with configurable timeframe (default: 7 days)

Changed

• /docs command expanded: Now routes to 4 skills (search, validate, course, changelog) + inline git log
• README.md: Added "Interactive Courses" and "Changelog Reports" sections with usage examples
• CLAUDE.md: Updated plugin structure, routing table, and key files for new skills
• CONTRIBUTING.md: Updated for 4-skill architecture
• .gitignore: Added codebase-to-course-main/ and generated HTML exclusions

[1.0.0] - 2026-03-28

Breaking Changes

• Plugin is now the primary (and only recommended) install path — install.sh is now a migration wrapper that guides users to plugin install
• Legacy helper scripts no longer user-facing — claude-docs-helper.sh and the Python lookup module are now CI-only; plugin skills handle all user-facing search

Added

• claude-docs/ search skill: Enhanced search with 4-tier strategy (direct lookup, scoped search, content search, fuzzy matching)
  • scripts/content-search.sh — Full-text keyword search using .search_index.json or grep fallback
  • scripts/fuzzy-search.sh — Token-based fuzzy filename matching
  • examples/ — 3 worked examples (direct lookup, semantic search, cross-context disambiguation)
• claude-docs-validate/ health check skill: Documentation freshness and URL reachability checks
  • scripts/validate-paths.sh — Parallel HTTP HEAD checks with --quick mode
  • examples/ — Validation workflow example
• Zero Python dependency for users — All plugin features use shell scripts only; Python is CI-only

Changed

• /docs command rewritten as lean router (~40 lines) delegating to skills
• install.sh rewritten as migration wrapper (~100 lines) routing to plugin install
• uninstall.sh simplified to plugin uninstall instructions
• CLAUDE.md streamlined — removed ~350 lines of search strategy (now lives in skill SKILL.md)
• README.md updated — plugin-first, script install moved to "Legacy" section
• UNINSTALL.md simplified to plugin-only primary path
• CONTRIBUTING.md updated for plugin-first development workflow

Removed

• plugin/skills/claude-docs-workspace/ — Stale Phase 2 eval artifacts (was gitignored, not in repo)
• User-facing Python search (replaced by shell scripts in plugin skills)
• Legacy install.sh functionality (779 lines → 100 lines)

[0.6.0] - 2026-02-28

Added

• Native Claude Code Plugin: New plugin/ directory with full plugin structure
  • /docs slash command — AI-powered documentation search with intent classification
  • Auto-discovery Skill — Claude proactively searches docs for Claude-related questions without /docs prefix
  • SessionStart hook — automatically clones/updates documentation on each session start
  • Marketplace registration (.claude-plugin/marketplace.json)
• Plugin installation method: Two-command install via /plugin marketplace add + /plugin install — no Python, jq, or curl required
• Scoped search strategy: Skill instructions route queries to correct doc subcategories based on product context
• No-results fallback: Skill suggests synonyms and /docs -t when searches return empty
• Expanded category taxonomy: 11 documentation categories (up from 6) including agent_sdk, agents_and_tools, about_claude, get_started, test_and_evaluate
• Skill quality evaluation suite: 6 evals with grading, benchmarking, and HTML review viewer (dev artifacts, gitignored)

Changed

• README rewritten: More inviting, plugin-first installation, comparison table showing value proposition
• CLAUDE.md updated: Added plugin files to structure/key files, fixed category labels table, added all 11 categories
• Filename conventions documented: Corrected URL mapping rules (claude-code__ → code.claude.com, docs__en__ → platform.claude.com)

Fixed

• Broken domain references: All plugin instruction files now cite correct domains (platform.claude.com, code.claude.com) — never docs.anthropic.com or docs.claude.com
• CLAUDE.md example URLs: Fixed docs.claude.com → platform.claude.com in all code examples
• URL mapping in Skill and /docs command: Filename-to-URL conversion rules corrected for both CLI and platform docs

[0.5.1] - 2026-02-27

Fixed

• Search index path resolution: load_search_index() now resolves paths relative to __file__ instead of relying on cwd, fixing content search failures when invoked from outside the repo root (fixes Content search fails when helper script is called with absolute path #15)
• Manifest staging in CI: paths_manifest.json is now included in the git commit step — manifest updates were silently lost on every 3-hour sync
• Helper script cwd handling: All Python calls wrapped in (cd "$DOCS_PATH" && ...) subshells for reliable execution from any directory
• TARGET_DOCS in installer: Upgrade summary now correctly displays installed doc count instead of blank
• CI/CD python3 consistency: All workflow files use python3 -m pip (9 occurrences across 4 files)

Added

• Search index auto-generated during CI sync with continue-on-error and log-visible failure messages
• Behavioral test test_load_search_index_works_from_different_cwd for cwd independence
• test_no_deprecated_paths reuses url_to_safe_filename from fetcher package instead of duplicating logic
• test_internal_links_in_manifest logs pass statistics for CI visibility
• Test count: 303 (up from 294)

Changed

• README.md rewritten: 452 → ~120 lines — removed hardcoded counts, stale upgrade guide, redundant architecture section
• Replaced all hardcoded path/doc counts with dynamic values across CLAUDE.md, CONTRIBUTING.md, and helper script
• Plan documents moved to .gitignore (local development only)
• test_python_calls_use_subshell_cd uses regex assertion for specificity

Updated

• Paths manifest: Regenerated from live sitemaps (573 fetchable paths retained; 199 unfetchable paths excluded)
• Search index: Rebuilt with 574 indexed files
• test_search_index_file_count: Now compares against docs_manifest.json instead of hardcoded count
• Documentation content: Synced latest from Anthropic sitemaps

[0.5.0] - 2025-12-06

Breaking Changes

• Filename Convention Changed: All Claude Code CLI docs renamed to use domain-based prefix
  • Old: docs__en__<topic>.md (e.g., docs__en__hooks.md)
  • New: claude-code__<topic>.md (e.g., claude-code__hooks.md)
  • Platform docs use: docs__en__<path>.md
• Scripts Restructured: Monolithic scripts replaced with modular packages
  • Added: scripts/fetcher/ (8 modules for documentation fetching)
  • Added: scripts/lookup/ (7 modules for search and validation)
  • Removed: main.py, update_sitemap.py, extract_paths.py, clean_manifest.py

Added

• 2x Documentation Coverage: 571 files (up from ~270)
• 573 Tracked Paths: Comprehensive coverage across 6 categories
  • API Reference: 377 paths (65.8%)
  • Core Documentation: 82 paths (14.3%)
  • Prompt Library: 65 paths (11.3%)
  • Claude Code: 46 paths (8.0%)
  • Release Notes: 2 paths
  • Resources: 1 path
• Safety Thresholds: Prevent catastrophic deletion during automated sync
  • MIN_DISCOVERY_THRESHOLD: 200 paths minimum from sitemaps
  • MAX_DELETION_PERCENT: 10% maximum deletion per sync
  • MIN_EXPECTED_FILES: 250 minimum files required
• Modular Architecture: Better code organization and testability
  • fetcher/ package: config, manifest, paths, sitemap, content, safeguards, cli
  • lookup/ package: config, manifest, search, validation, formatting, cli
• Domain-Based Naming: Clear source identification in filenames
  • claude-code__*.md from code.claude.com
  • docs__en__*.md from platform.claude.com
• Version-Aware Upgrades: Installer detects existing version and shows upgrade info

Changed

• Manifest Structure: paths_manifest.json now tracks 573 paths in 6 categories
• Search Index: Updated to cover all 571 documentation files
• Python Packages: Thin wrappers (fetch_claude_docs.py, lookup_paths.py) for backward compatibility

Upgrade Notes

• Seamless Upgrade: Run install.sh again to upgrade from any v0.4.x version
• No Data Loss: All user configs remain in ~/.claude/
• Atomic Operation: Installation uses temp directory, moves atomically
• The installer will show before/after comparison during upgrade

[0.4.2] - 2025-11-25

Fixed

• Critical Auto-Update Bug: Fixed issue where /docs -t would destroy the installation directory
  • Root cause: Running install.sh from within ~/.claude-code-docs caused the script to delete its own working directory
  • Solution: Replaced full reinstall with lightweight script sync after git pull
• Template Fallback: Enhanced helper now gracefully degrades if template is missing instead of failing completely
• Security: Path Traversal Protection: Added realpath validation in fallback mode to ensure files stay within docs directory
  • Input sanitization removes special characters (already existed)
  • New: Resolved path validation ensures no escape from docs directory
• Silent Failure Logging: sync_helper_script() now logs failures to stderr for debugging
  • Previously errors were silently suppressed with || true
  • Now provides feedback when copy or move operations fail

Removed

• Useless Hook: Removed the PreToolUse hook that did nothing (just exit 0)
  • The hook fired on every Read tool use but provided no functionality
  • Updates now happen on-demand via /docs -t command

Added

• Post-Installation Verification: Installer now validates all critical components after installation
  • Checks helper script, template, docs directory, and command file
  • Reports issues instead of silently failing
• Lock File Mechanism: Added lock file to prevent concurrent update operations
  • Prevents race conditions when multiple /docs commands run simultaneously
  • Automatically cleans up stale locks (older than 60 seconds)
• Integration Tests: Added 9 new tests for critical bug fix scenarios (627 tests total)
  • Tests for sync_helper_script() atomic copy behavior
  • Tests verifying update doesn't delete working directory
  • Tests for template fallback functionality
  • Tests for lock file mechanism
  • Tests for path traversal protection

Changed

• Documentation Accuracy: Updated README and installer messages to clarify update behavior
  • Removed misleading "Auto-updates: Enabled" claims
  • Clarified that updates are on-demand via /docs -t
• Test Suite: Updated from 618 to 627 passing tests (78.7% coverage maintained)

[0.4.1] - 2025-11-24

Fixed

• Version Alignment: Updated all version strings from v0.3.4 to v0.4.1 to match git tag
• Path Count Accuracy: Corrected all documentation from outdated 268/270 to accurate 273 paths tracked
• File Count Clarity: Clarified distinction between paths tracked (273) vs files downloaded (~266-270)
• Category Breakdown: Updated all category counts to match current manifest:
  • Core Documentation: 80 paths (29.3%)
  • API Reference: 79 paths (28.9%)
  • Prompt Library: 65 paths (23.8%)
  • Claude Code: 45 paths (16.5%)
  • Release Notes: 2 paths
  • Resources: 1 path
  • Uncategorized: 1 path

Changed

• Architecture Documentation: Replaced outdated "Dual-Mode" concept with accurate "Single Installation with Graceful Degradation"
• Enhancement Documentation: Updated all enhancement docs (FEATURES.md, CAPABILITIES.md, README.md) with accurate numbers
• Install Messages: Updated installer output to show accurate, consistent information

[0.4.0] - 2025-11-24

Note: This tag was created but version strings in code were not updated (still showed v0.3.4). Fixed in v0.4.1.

[0.3.4] - 2025-11-06

Added

• Dual-Mode Architecture: Choose between standard (shell-only) or enhanced (Python-powered) modes during installation
• Extended Documentation Coverage: 449 documentation paths across 7 categories (vs 269 in standard mode)
• Full-Text Search: Search across all documentation content using --search flag
• Validation Tools: Verify documentation integrity with --validate command
• Category Organization: Documentation organized into core docs, API reference, Claude Code, prompt library, resources, release notes
• Enhanced Directory: Comprehensive feature documentation in enhancements/ directory
  • enhancements/README.md - Overview and navigation
  • enhancements/FEATURES.md - Technical feature specifications
  • enhancements/CAPABILITIES.md - Detailed capability documentation
  • enhancements/EXAMPLES.md - Practical usage examples
• Test Suite: 566 tests with 81.41% code coverage (target: 82%)
• Performance Benchmarks: Documented search, fetch, and validation performance characteristics

Changed

• README.md: Updated to version 0.3.4 with enhanced features section
• CLAUDE.md: Comprehensive instructions for dual-mode architecture
• Repository Structure: Reorganized for clearer separation between standard and enhanced modes

Improved

• Installation: Installer now prompts for mode selection (standard vs enhanced)
• Mode Detection: Helper script automatically detects Python availability and routes commands appropriately
• Documentation: All documentation verified against actual fetched content (449 paths confirmed)
• Graceful Degradation: Enhanced features fall back to standard mode when Python unavailable

Fixed

• File Count Accuracy: Corrected documentation references from outdated counts to actual values
• Manifest Alignment: docs_manifest.json now accurately reflects 269 documentation files
• Category Counts: All category counts verified against paths_manifest.json

Removed

• Temporary Tracking Files: Removed 20+ intermediate development tracking files
  • Phase reports (PHASE*.md)
  • Task summaries (TASK*.md)
  • Migration tracking (MIGRATION_*.md)
  • Analysis artifacts (analysis/execution/)
  • Development artifacts (docs-dev/)

[0.3.3] - Upstream Baseline

Inherited from Upstream

• Claude Code changelog integration
• Full macOS compatibility
• Linux support (Ubuntu, Debian, Fedora)
• Improved installer
• Documentation updates via GitHub Actions (repository-side)
• /docs slash command integration

---

Contributing

See CONTRIBUTING.md for guidelines on contributing to this enhanced edition.

For upstream contributions, see ericbuess/claude-code-docs.

[claude]

Changelog - Enhanced Edition

All notable changes to the enhanced edition of claude-code-docs will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[1.1.0] - 2026-03-28

Added

• claude-docs-course/ interactive course skill: Generates self-contained HTML courses on any Claude documentation topic
  • 4-phase pipeline: Topic Discovery → Curriculum Design → Build (module by module) → Review & Open
  • Obsidian & Amber design theme: Dark obsidian backgrounds, warm amber accents, Instrument Serif + Outfit typography, grain textures, glass-morphism effects
  • references/design-system.md — Complete CSS design tokens for the Obsidian & Amber theme
  • references/interactive-elements.md — 18 interactive element patterns including Protocol Conversations, code translations, quizzes, data flow animations, glossary tooltips
  • examples/course-from-docs.md — Worked example for hooks course generation
  • Courses saved to ~/.claude-code-docs/courses/<topic-slug>.html
• claude-docs-changelog/ report skill: Generates HTML changelog reports of recent documentation changes
  • Discovers changes via git history, categorizes by doc type, summarizes key updates
  • Each entry includes a "Create Course" button that copies /docs --course <topic> to clipboard
  • Obsidian & Amber themed to match courses
  • examples/changelog-report.md — Worked example
• Post-response course prompt: After every docs response, an emphasized prompt invites users to generate an interactive course on the topic
• /docs --course <topic> route: Direct course generation via the /docs command
• /docs --report route: Generate HTML changelog with configurable timeframe (default: 7 days)

Changed

• /docs command expanded: Now routes to 4 skills (search, validate, course, changelog) + inline git log
• README.md: Added "Interactive Courses" and "Changelog Reports" sections with usage examples
• CLAUDE.md: Updated plugin structure, routing table, and key files for new skills
• CONTRIBUTING.md: Updated for 4-skill architecture
• .gitignore: Added codebase-to-course-main/ and generated HTML exclusions

[1.0.0] - 2026-03-28

Breaking Changes

• Plugin is now the primary (and only recommended) install path — install.sh is now a migration wrapper that guides users to plugin install
• Legacy helper scripts no longer user-facing — claude-docs-helper.sh and the Python lookup module are now CI-only; plugin skills handle all user-facing search

Added

• claude-docs/ search skill: Enhanced search with 4-tier strategy (direct lookup, scoped search, content search, fuzzy matching)
  • scripts/content-search.sh — Full-text keyword search using .search_index.json or grep fallback
  • scripts/fuzzy-search.sh — Token-based fuzzy filename matching
  • examples/ — 3 worked examples (direct lookup, semantic search, cross-context disambiguation)
• claude-docs-validate/ health check skill: Documentation freshness and URL reachability checks
  • scripts/validate-paths.sh — Parallel HTTP HEAD checks with --quick mode
  • examples/ — Validation workflow example
• Zero Python dependency for users — All plugin features use shell scripts only; Python is CI-only

Changed

• /docs command rewritten as lean router (~40 lines) delegating to skills
• install.sh rewritten as migration wrapper (~100 lines) routing to plugin install
• uninstall.sh simplified to plugin uninstall instructions
• CLAUDE.md streamlined — removed ~350 lines of search strategy (now lives in skill SKILL.md)
• README.md updated — plugin-first, script install moved to "Legacy" section
• UNINSTALL.md simplified to plugin-only primary path
• CONTRIBUTING.md updated for plugin-first development workflow

Removed

• plugin/skills/claude-docs-workspace/ — Stale Phase 2 eval artifacts (was gitignored, not in repo)
• User-facing Python search (replaced by shell scripts in plugin skills)
• Legacy install.sh functionality (779 lines → 100 lines)

[0.6.0] - 2026-02-28

Added

• Native Claude Code Plugin: New plugin/ directory with full plugin structure
  • /docs slash command — AI-powered documentation search with intent classification
  • Auto-discovery Skill — Claude proactively searches docs for Claude-related questions without /docs prefix
  • SessionStart hook — automatically clones/updates documentation on each session start
  • Marketplace registration (.claude-plugin/marketplace.json)
• Plugin installation method: Two-command install via /plugin marketplace add + /plugin install — no Python, jq, or curl required
• Scoped search strategy: Skill instructions route queries to correct doc subcategories based on product context
• No-results fallback: Skill suggests synonyms and /docs -t when searches return empty
• Expanded category taxonomy: 11 documentation categories (up from 6) including agent_sdk, agents_and_tools, about_claude, get_started, test_and_evaluate
• Skill quality evaluation suite: 6 evals with grading, benchmarking, and HTML review viewer (dev artifacts, gitignored)

Changed

• README rewritten: More inviting, plugin-first installation, comparison table showing value proposition
• CLAUDE.md updated: Added plugin files to structure/key files, fixed category labels table, added all 11 categories
• Filename conventions documented: Corrected URL mapping rules (claude-code__ → code.claude.com, docs__en__ → platform.claude.com)

Fixed

• Broken domain references: All plugin instruction files now cite correct domains (platform.claude.com, code.claude.com) — never docs.anthropic.com or docs.claude.com
• CLAUDE.md example URLs: Fixed docs.claude.com → platform.claude.com in all code examples
• URL mapping in Skill and /docs command: Filename-to-URL conversion rules corrected for both CLI and platform docs

[0.5.1] - 2026-02-27

Fixed

• Search index path resolution: load_search_index() now resolves paths relative to __file__ instead of relying on cwd, fixing content search failures when invoked from outside the repo root (fixes Content search fails when helper script is called with absolute path #15)
• Manifest staging in CI: paths_manifest.json is now included in the git commit step — manifest updates were silently lost on every 3-hour sync
• Helper script cwd handling: All Python calls wrapped in (cd "$DOCS_PATH" && ...) subshells for reliable execution from any directory
• TARGET_DOCS in installer: Upgrade summary now correctly displays installed doc count instead of blank
• CI/CD python3 consistency: All workflow files use python3 -m pip (9 occurrences across 4 files)

Added

• Search index auto-generated during CI sync with continue-on-error and log-visible failure messages
• Behavioral test test_load_search_index_works_from_different_cwd for cwd independence
• test_no_deprecated_paths reuses url_to_safe_filename from fetcher package instead of duplicating logic
• test_internal_links_in_manifest logs pass statistics for CI visibility
• Test count: 303 (up from 294)

Changed

• README.md rewritten: 452 → ~120 lines — removed hardcoded counts, stale upgrade guide, redundant architecture section
• Replaced all hardcoded path/doc counts with dynamic values across CLAUDE.md, CONTRIBUTING.md, and helper script
• Plan documents moved to .gitignore (local development only)
• test_python_calls_use_subshell_cd uses regex assertion for specificity

Updated

• Paths manifest: Regenerated from live sitemaps (573 fetchable paths retained; 199 unfetchable paths excluded)
• Search index: Rebuilt with 574 indexed files
• test_search_index_file_count: Now compares against docs_manifest.json instead of hardcoded count
• Documentation content: Synced latest from Anthropic sitemaps

[0.5.0] - 2025-12-06

Breaking Changes

• Filename Convention Changed: All Claude Code CLI docs renamed to use domain-based prefix
  • Old: docs__en__<topic>.md (e.g., docs__en__hooks.md)
  • New: claude-code__<topic>.md (e.g., claude-code__hooks.md)
  • Platform docs use: docs__en__<path>.md
• Scripts Restructured: Monolithic scripts replaced with modular packages
  • Added: scripts/fetcher/ (8 modules for documentation fetching)
  • Added: scripts/lookup/ (7 modules for search and validation)
  • Removed: main.py, update_sitemap.py, extract_paths.py, clean_manifest.py

Added

• 2x Documentation Coverage: 571 files (up from ~270)
• 573 Tracked Paths: Comprehensive coverage across 6 categories
  • API Reference: 377 paths (65.8%)
  • Core Documentation: 82 paths (14.3%)
  • Prompt Library: 65 paths (11.3%)
  • Claude Code: 46 paths (8.0%)
  • Release Notes: 2 paths
  • Resources: 1 path
• Safety Thresholds: Prevent catastrophic deletion during automated sync
  • MIN_DISCOVERY_THRESHOLD: 200 paths minimum from sitemaps
  • MAX_DELETION_PERCENT: 10% maximum deletion per sync
  • MIN_EXPECTED_FILES: 250 minimum files required
• Modular Architecture: Better code organization and testability
  • fetcher/ package: config, manifest, paths, sitemap, content, safeguards, cli
  • lookup/ package: config, manifest, search, validation, formatting, cli
• Domain-Based Naming: Clear source identification in filenames
  • claude-code__*.md from code.claude.com
  • docs__en__*.md from platform.claude.com
• Version-Aware Upgrades: Installer detects existing version and shows upgrade info

Changed

• Manifest Structure: paths_manifest.json now tracks 573 paths in 6 categories
• Search Index: Updated to cover all 571 documentation files
• Python Packages: Thin wrappers (fetch_claude_docs.py, lookup_paths.py) for backward compatibility

Upgrade Notes

• Seamless Upgrade: Run install.sh again to upgrade from any v0.4.x version
• No Data Loss: All user configs remain in ~/.claude/
• Atomic Operation: Installation uses temp directory, moves atomically
• The installer will show before/after comparison during upgrade

[0.4.2] - 2025-11-25

Fixed

• Critical Auto-Update Bug: Fixed issue where /docs -t would destroy the installation directory
  • Root cause: Running install.sh from within ~/.claude-code-docs caused the script to delete its own working directory
  • Solution: Replaced full reinstall with lightweight script sync after git pull
• Template Fallback: Enhanced helper now gracefully degrades if template is missing instead of failing completely
• Security: Path Traversal Protection: Added realpath validation in fallback mode to ensure files stay within docs directory
  • Input sanitization removes special characters (already existed)
  • New: Resolved path validation ensures no escape from docs directory
• Silent Failure Logging: sync_helper_script() now logs failures to stderr for debugging
  • Previously errors were silently suppressed with || true
  • Now provides feedback when copy or move operations fail

Removed

• Useless Hook: Removed the PreToolUse hook that did nothing (just exit 0)
  • The hook fired on every Read tool use but provided no functionality
  • Updates now happen on-demand via /docs -t command

Added

• Post-Installation Verification: Installer now validates all critical components after installation
  • Checks helper script, template, docs directory, and command file
  • Reports issues instead of silently failing
• Lock File Mechanism: Added lock file to prevent concurrent update operations
  • Prevents race conditions when multiple /docs commands run simultaneously
  • Automatically cleans up stale locks (older than 60 seconds)
• Integration Tests: Added 9 new tests for critical bug fix scenarios (627 tests total)
  • Tests for sync_helper_script() atomic copy behavior
  • Tests verifying update doesn't delete working directory
  • Tests for template fallback functionality
  • Tests for lock file mechanism
  • Tests for path traversal protection

Changed

• Documentation Accuracy: Updated README and installer messages to clarify update behavior
  • Removed misleading "Auto-updates: Enabled" claims
  • Clarified that updates are on-demand via /docs -t
• Test Suite: Updated from 618 to 627 passing tests (78.7% coverage maintained)

[0.4.1] - 2025-11-24

Fixed

• Version Alignment: Updated all version strings from v0.3.4 to v0.4.1 to match git tag
• Path Count Accuracy: Corrected all documentation from outdated 268/270 to accurate 273 paths tracked
• File Count Clarity: Clarified distinction between paths tracked (273) vs files downloaded (~266-270)
• Category Breakdown: Updated all category counts to match current manifest:
  • Core Documentation: 80 paths (29.3%)
  • API Reference: 79 paths (28.9%)
  • Prompt Library: 65 paths (23.8%)
  • Claude Code: 45 paths (16.5%)
  • Release Notes: 2 paths
  • Resources: 1 path
  • Uncategorized: 1 path

Changed

• Architecture Documentation: Replaced outdated "Dual-Mode" concept with accurate "Single Installation with Graceful Degradation"
• Enhancement Documentation: Updated all enhancement docs (FEATURES.md, CAPABILITIES.md, README.md) with accurate numbers
• Install Messages: Updated installer output to show accurate, consistent information

[0.4.0] - 2025-11-24

Note: This tag was created but version strings in code were not updated (still showed v0.3.4). Fixed in v0.4.1.

[0.3.4] - 2025-11-06

Added

• Dual-Mode Architecture: Choose between standard (shell-only) or enhanced (Python-powered) modes during installation
• Extended Documentation Coverage: 449 documentation paths across 7 categories (vs 269 in standard mode)
• Full-Text Search: Search across all documentation content using --search flag
• Validation Tools: Verify documentation integrity with --validate command
• Category Organization: Documentation organized into core docs, API reference, Claude Code, prompt library, resources, release notes
• Enhanced Directory: Comprehensive feature documentation in enhancements/ directory
  • enhancements/README.md - Overview and navigation
  • enhancements/FEATURES.md - Technical feature specifications
  • enhancements/CAPABILITIES.md - Detailed capability documentation
  • enhancements/EXAMPLES.md - Practical usage examples
• Test Suite: 566 tests with 81.41% code coverage (target: 82%)
• Performance Benchmarks: Documented search, fetch, and validation performance characteristics

Changed

• README.md: Updated to version 0.3.4 with enhanced features section
• CLAUDE.md: Comprehensive instructions for dual-mode architecture
• Repository Structure: Reorganized for clearer separation between standard and enhanced modes

Improved

• Installation: Installer now prompts for mode selection (standard vs enhanced)
• Mode Detection: Helper script automatically detects Python availability and routes commands appropriately
• Documentation: All documentation verified against actual fetched content (449 paths confirmed)
• Graceful Degradation: Enhanced features fall back to standard mode when Python unavailable

Fixed

• File Count Accuracy: Corrected documentation references from outdated counts to actual values
• Manifest Alignment: docs_manifest.json now accurately reflects 269 documentation files
• Category Counts: All category counts verified against paths_manifest.json

Removed

• Temporary Tracking Files: Removed 20+ intermediate development tracking files
  • Phase reports (PHASE*.md)
  • Task summaries (TASK*.md)
  • Migration tracking (MIGRATION_*.md)
  • Analysis artifacts (analysis/execution/)
  • Development artifacts (docs-dev/)

[0.3.3] - Upstream Baseline

Inherited from Upstream

• Claude Code changelog integration
• Full macOS compatibility
• Linux support (Ubuntu, Debian, Fedora)
• Improved installer
• Documentation updates via GitHub Actions (repository-side)
• /docs slash command integration

---

Contributing

See CONTRIBUTING.md for guidelines on contributing to this enhanced edition.

For upstream contributions, see ericbuess/claude-code-docs.

[claude]

test cleanup - this comment will be deleted