Skip to content

fix(claude-config): fetch-docs index_link resolves a slug to a nested page with the same basename #5496

Description

@kyle-sexton

Problem

plugins/claude-config/scripts/fetch-docs.sh resolves a bare doc slug to the first link in the docs index whose URL ends in /<slug>.md (index_link, line 212 on origin/main). A nested page with the same basename wins when the index lists it first.

The live index at https://code.claude.com/docs/llms.txt lists https://code.claude.com/docs/en/plugins/cli-reference.md (line 155) before https://code.claude.com/docs/en/cli-reference.md (line 267). Fetching slug cli-reference therefore records the plugins page as read. doc-citations.tsv cites cli-reference with the span --debug-file, which exists only on the top-level page, so check-doc-citations.sh reports a false "span missing" failure against a page it graded as read. --discover also marks the real page not-in-index, for the same reason.

hooks, permissions and skills have agent-sdk/<slug>.md siblings and resolve correctly today only because the index lists the top-level page first.

The old direct URL form (/docs/en/$slug.md) did not have this collision; it came in with #5440.

Evidence

  • git show origin/main:plugins/claude-config/scripts/fetch-docs.sh: index_link matches on the /<slug>.md suffix and prints the first hit.
  • curl -s https://code.claude.com/docs/llms.txt | grep -n cli-reference.md returns the plugins page at line 155 and the top-level page at line 267 (checked 2026-09-29).
  • Found by a post-merge review of feat(claude-config): shared upstream doc fetcher with per-run manifest #5440, which merged while both Claude review lanes failed on a 429 rate limit.

Acceptance criteria

  • index_link <slug> returns only the exact top-level page ($ORIGIN/docs/en/<slug>.md, or $ORIGIN/docs/<slug>.md), never a nested page that shares the basename.
  • A fetch-docs.test.sh case uses an index that lists plugins/<x>.md before <x>.md and asserts that the manifest URL is the top-level page.
  • --discover reports the top-level page as in the index for that fixture.
  • claude-config version bump and CHANGELOG entry.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.priority: highSignificant impact, or blocks an imminent release; staff this cycle.work-class: scopedA briefed fix or small feature; blast radius bounded by the brief, tests exist.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions