Skip to content

CHANGELOG.md

Latest commit

 

History

History
402 lines (343 loc) · 24.4 KB

CHANGELOG.md

File metadata and controls

402 lines (343 loc) · 24.4 KB
Raw

Changelog

All notable changes to claude-code-docs will be documented in this file.

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

[2.0.2] - 2026-08-04

Background-sync lock rework from issue #28 (PR #32), the search-index stale-ratio ceiling from issue #29 (PR #34), and the low-severity backlog from issue #30 (PR #34). Bot reviewers converged on approve with no substantive findings; adversarially verified by execution.

Added

  • Stale-ratio ceiling on the search index (#29). Carry-forward keeps search usable through doc-site outages, but it also satisfied the content-share guard — so a standalone index build over a mostly-missing scratch dir could publish a largely-stale index silently. The build now refuses when more than half the records were carried forward from the committed index (DOCS_INDEX_MAX_CARRY_SHARE, default 0.5; 1 disables). Carry-forward itself is unchanged.
  • Shell/Python host-allowlist parity test (#30): ALLOWED_HOSTS (fetch-docs.sh) and ALLOWED_DOMAINS (fetcher config) are now locked together by a unit test, so the two spellings of the fetch-domain contract cannot drift silently.

Changed

  • Sync uses a true worker pool (#30): xargs -0 -n1 -P keeps all parallel slots busy instead of the old batch loop, where every batch waited on its slowest fetch. The lock heartbeat moved from the batch boundary to per-page.
  • fuzzy-search.sh rewritten as a single awk pass (#30): ~17s per query (≈7,000 grep forks over 725 pages) down to ~0.03s, identical rankings (one provably-unreachable scoring branch dropped rather than ported). This unblocked wiring the test-skills.sh search-quality harness (64 checks, ~10 min before, ~12s now) into CI as part of the macOS shell job.
  • prune now clears orphaned .tmp.* files (#30) older than an hour — a killed fetch's leftovers were previously invisible to the *.md glob.
  • install.sh keeps a still-shallow clone shallow (#30): updates fetch with --depth 1 unless manifest-diff.sh already deepened the clone, instead of unconditionally downloading every intermediate metadata commit.
  • Quick-validate sampling re-seeded per run (#30): the awk shuffle mixes the PID into the seed, so two runs in the same second no longer sample identical pages.
  • CI dedupe (#30): coverage.yml (a strict subset of test.yml, which already enforces the 50% floor) removed; ~180 lines of dead mirror-era sitemap discovery functions deleted; pyproject.toml version aligned with the plugin (2.0.1) and the requests pin/floor cross-referenced between pyproject.toml and scripts/requirements.txt.
  • Legacy-hook cleanup hardened (#30): the settings.json jq filter in install.sh/uninstall.sh tostring-coerces a non-string .command instead of erroring the whole filter (the two copies are deliberately duplicated — both scripts run standalone — and now say so).

Fixed

  • Sync is now single-flight for every caller. The lock moved from the SessionStart hook into fetch-docs.sh sync itself, so direct CLI syncs and --background children are covered, not just the hook path. The lock is PID-owned (cache/.sync.lock/pid) with a per-batch mtime heartbeat.
  • A slow first sync can no longer lose its lock. The blind 30-minute mtime reaper is gone; a held lock is reaped only on evidence — dead owner PID, a pidless lock older than a minute, or a 30-minute-idle mtime despite a "live" PID (recycled-PID backstop). Reaping goes through an atomic rename so two contenders cannot double-reap.
  • EXIT-trap cascade closed. Lock release is owner-checked, so a sync whose lock was reaped and re-acquired by a successor can no longer remove the successor's lock on exit. A plain file left at the lock path is reaped instead of silently disabling every future sync.
  • Crash-cleanup rescue hardened. A racing sync child's recreated cache scaffolding (.meta/, .sync.lock/) no longer defeats the rescue of a populated parked cache during self-heal; a disk-full lock backout reports a distinct error instead of "another sync is already running"; lock cleanup works on BSD userland (rm -rf cannot remove unreadable directories there).

[2.0.1] - 2026-08-02

Deployment-hardening release: no new features, all fixes from an exhaustive 5-domain code review of v2.0.0 plus an adversarial re-review of the fixes.

Fixed

  • macOS sync now works. The page-fetch job pool no longer relies on xargs -I (BSD's 255-byte replacement limit made one page permanently unsyncable), the validator no longer uses mapfile/shuf (dead on stock macOS bash 3.2), and a new shell-macos CI job runs the shell suite under BSD userland on every PR.
  • Session-hook wedge fixed. The SessionStart hook timeout (15s) was below its own 30s clone budget and could wedge installs forever; now 45s. The self-heal path re-clones a corrupt install, verifies git resolves to the docs directory itself (a lost .git under a git-managed $HOME previously risked hard-resetting the user's repo), preserves untracked cache/ and courses/ across the swap, and never nests a fresh clone inside a half-deleted one.
  • No more no-op updates every 3 hours. The metadata workflow compares manifest/index against HEAD ignoring only the generated_at line, so a commit (and every user's session-hook update) happens only when content actually changed (~2,900 churn commits/year eliminated).
  • Search results no longer degrade during doc-site outages. The search index carries forward the previous entry for pages whose fetch failed, guarded by a content-share floor; safeguard counts now use real per-run fetch successes (changelog excluded, single owner) and run before anything is written.
  • Security hardening. Real DTD/ENTITY rejection over the full sitemap content (the previous 2 KB prefix check was bypassable with comment padding; before that, defusedxml kwargs passed to stdlib ElementTree were silently dead); manifest-filename traversal guard; ALLOWED_DOMAINS actually enforced; redirects uniformly treated as fetch failures across client, fetcher, and the daily reachability monitor.
  • Discovery is fail-closed with retries. A dead discovery source (sitemap or llms.txt) aborts the run instead of silently dropping its pages; transient errors are retried with backoff first so a single CDN blip doesn't kill a run.
  • CI honesty. Removed || true around tests, the hardcoded fake coverage number, and deprecated upload actions; coverage gate now reflects reality; workflow actions SHA-pinned; PR workflows gated for forks; manifest-diff.sh --since no longer hangs; installer jq crash on partial hook entries fixed.

Removed

  • Dead v1 legacy layer (scripts/claude-docs-helper.sh + template and the tests pinning them) and the model-facing examples that still taught the v1 mirror workflow with fabricated URLs — regenerated from the live manifest.

[2.0.0] - 2026-07-31

Breaking Changes — v1 mirror → v2 manifest + client fetch

  • No documentation prose is committed anymore. The repo now ships only metadata (paths_manifest.json + search_index.json); the actual .md pages are fetched at runtime from Anthropic's servers into a local cache at ~/.claude-code-docs/cache/. See ARCHITECTURE.md.
  • One-time automatic re-sync on upgrade. The SessionStart hook now runs git reset --hard origin/main (was git pull --ff-only). This absorbs the metadata-only cutover (and the later history rewrite), deletes the stale tracked docs/*.md left over from old mirror-era clones, and preserves your untracked cache/ and courses/. Nothing to do — it happens automatically on your next session.

Changed

  • /docs is now a Skill, not a flat command. plugin/commands/docs.md → plugin/skills/docs/SKILL.md (disable-model-invocation, so it fires only on an explicit /docs; auto-discovery stays the claude-docs skill's job). Invocation is unchanged — bare /docs … still works, plus the namespaced /claude-docs:docs.

Migration notes (only if you used the older script install)

  • Remove the stale personal command so it can't shadow or conflict with the plugin's /docs: rm -f ~/.claude/commands/docs.md (or run ~/.claude-code-docs/uninstall.sh, which also clears legacy hooks from ~/.claude/settings.json).
  • Then install the plugin: /plugin marketplace add costiash/claude-code-docs then /plugin install claude-docs@claude-code-docs.

[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 #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 project.

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