Fix doc updater: docs moved to code.claude.com

[karstenpet-ctrl]

Fixes #7.

update_docs.js has been dead since the docs moved off docs.claude.com. There are three separate failures — fixing only the hostname still produces a silently corrupted references/ directory, so all three are addressed here.

1. fetchUrl doesn't follow redirects

$ curl -sS -o /dev/null -w "%{http_code} -> %{redirect_url}\n" https://docs.claude.com/llms.txt
301 -> https://platform.claude.com/llms.txt

Any non-2xx was fatal, so the script died on the first request:

📥 Fetching llms.txt...
❌ Error: HTTP 301: Moved Permanently

Now follows up to 5 redirects, resolving Location relative to the current URL. Worth keeping independently of the host fix — it makes the next docs reshuffle degrade gracefully instead of hard-failing.

2. The source index moved, and the redirect target is the wrong index

docs.claude.com/llms.txt redirects to platform.claude.com/llms.txt, which is the API / developer platform index and contains zero Claude Code pages:

$ curl -sSL https://platform.claude.com/llms.txt | grep -cE 'claude-code/[^ )]+\.md'
0

The Claude Code index is at https://code.claude.com/llms.txt, with pages at code.claude.com/docs/en/*.md:

$ curl -sS -o /dev/null -w "%{http_code} -> %{redirect_url}\n" https://docs.claude.com/en/docs/claude-code/hooks.md
301 -> https://code.claude.com/docs/en/hooks.md

The path shape changed too — /en/docs/claude-code/<page>.md became /docs/en/<page>.md — so CLAUDE_CODE_PATTERN needed updating alongside LLMS_TXT_URL.

3. path.basename() silently clobbers colliding filenames

The one most worth catching. The new index has 172 pages, 48 of them nested (agent-sdk/, etc.), and 8 basenames collide:

hooks.md  mcp.md  overview.md  permissions.md
plugins.md  quickstart.md  sessions.md  skills.md

With path.basename(url), agent-sdk/hooks.md overwrites the Claude Code hooks.md — no error, no warning, just wrong content in a file the skill later cites as authoritative. Whichever URL sorts last wins. Nested paths now flatten on /, so agent-sdk/hooks.md → agent-sdk-hooks.md.

Verification

URL discovery from this branch:

📥 Fetching llms.txt...
discovered: 172
unique flattened filenames: 172
sample: agent-sdk-agent-loop.md, agent-sdk-claude-code-features.md, agent-sdk-cost-tracking.md

172 URLs → 172 unique filenames, no collisions.

Full run against a v0.3.1 install:

✅ Documentation update complete!
   172 files downloaded successfully

references/ went from 42 files / 572K to 175 files / 6.7M — 133 new pages (the whole agent-sdk/ section, whats-new-* weeklies, worktrees, workflows, advisor, accessibility, zero-data-retention, …), 39 existing pages refreshed with changed content, 3 byte-identical, and 0 orphaned. Confirmed the collision pairs land separately: hooks.md (238K, "Hooks reference") and agent-sdk-hooks.md (49.8K) are distinct files with different checksums.

Scope note

This PR changes only update_docs.js — it does not include the regenerated references/. That regeneration is a 133-new-file, ~6MB diff that would be unreviewable and conflict-prone, and it seems better folded into your release flow. Running node skills/working-with-claude-code/scripts/update_docs.js after merge produces it.

Tested on macOS 15 (arm64), Node 26.5.0.