docs: index the Agent Plugins spec and the moved Claude Code pages

[kyle-sexton]

Summary

docs/OFFICIAL-DOCS.md is this repository's maintained navigation index of live
upstream pointers. A full live audit of the index on 2026-08-16 found two real
defects. This PR fixes both. One file, +7/-3.

Defect 1 — the Agent Plugins specification is missing. "Normative ecosystem
contracts" indexed the Agent Skills specification and the Model Context
Protocol specification, but not the Agent Plugins specification. Those are
different documents with different scopes: Agent Plugins is the packaging
contract that compatible clients load, and Agent Skills and MCP are two of the
component contracts it packages. Reading the Agent Skills spec therefore does
not discharge a preflight for a claim that rests on Agent Plugins packaging —
which is precisely the failure a missing pointer invites, and the same
conflation that produced a P1 review thread on #19. The fix adds the pointer and
one clause of disambiguation to the section's existing lead-in.

Defect 2 — both Claude Code pointers moved host. They return HTTP 301 to
a new host and a flattened path. AGENTS.md names this case directly: "If a
source host moves a page, update this index in the same change that relies on
the new location."

Old URL	Code	New URL
docs.claude.com/en/docs/claude-code/overview	301	code.claude.com/docs/en/overview
docs.claude.com/en/docs/claude-code/plugins	301	code.claude.com/docs/en/plugins

Both new targets are confirmed against the publisher's own page list rather than
against the redirect alone: code.claude.com/docs/llms.txt lists both, and a
search of that same index for docs.claude.com returns zero hits. The old
host is retired from the publisher's index, so this is a completed move, not a
transitional alias. Both existing labels remain accurate at the new URLs, so no
label text changes.

Scope note, stated rather than hidden

The audit behind this change recommended splitting these into two pull
requests — two defects, two sections, two independent bodies of evidence — while
recording that combining them is defensible and cheap, since the Claude Code fix
is a two-line, evidence-complete change with zero interaction with the other. They
are combined here deliberately: both are evidence-complete, and AGENTS.md's
"update this index when a pointer moves" clause is unconditional, so leaving a
known-moved pointer in place once observed is the worse option. The contrary
recommendation is recorded here so a reviewer can disagree with the call knowing
it was made rather than overlooked.

Deliberately NOT changed

Two of the four redirects the audit found are not defects, recorded so they
are not "fixed" later by someone who re-runs the same scan:

Pointer	Code	Why it stays
MCP /specification/latest	307 Temporary	A temporary redirect on a path whose final segment is literally latest is the publisher operating a rotating alias. Rewriting it to the dated target would pin this index to a snapshot and defeat the alias — the opposite of what this file is for.
alistair.cockburn.us/hexagonal-architecture/	301, same host, same path, trailing slash dropped	Pure URL canonicalization. No move, no content change. Churn with no reader benefit.

Also not added, because the defect does not require them: the spec's version and
status strings (this file states in its own opening that it "is not a cached
specification", and embedding 1.0.0 / Working Draft would go stale as the draft
advances), agent-plugins.org sub-pages, or a /compatible-clients pointer.

Mandatory documentation preflight

Verification date: 2026-08-16. Repository reads taken from origin/main:
README.md, docs/OFFICIAL-DOCS.md, all of docs/PLUGIN-PHILOSOPHY.md, and
AGENTS.md.

Every one of the 29 URLs in the index was fetched live, not sampled. Results:
25 OK, 4 redirected, 0 dead, 0 content-drifted. Status codes were probed
deterministically and each pointer's served content was checked against the label
the index gives it, because a 200 serving unrelated content is a defect no
status code reveals.

Live pointers consulted for the two changes specifically, all retrieved
2026-08-16:

• https://agent-plugins.org/specification — 200, no redirect. Confirmed present
  in https://agent-plugins.org/sitemap.xml, which emits 13 entries and lists no
  versioned specification path, so there is no competing canonical candidate.
• https://agent-plugins.org/ — 200. Establishes the container-vs-component
  relationship this PR's lead-in sentence describes.
• https://code.claude.com/docs/en/overview — 200 (from a 301).
• https://code.claude.com/docs/en/plugins — 200 (from a 301).
• https://code.claude.com/docs/llms.txt — 200. The publisher's own page list,
  used to confirm both new paths and the absence of the old host.
• https://cursor.com/docs/plugins — 200. Independent client-side corroboration
  that Agent Plugins is a distinct standard.

Every URL is linked, not reproduced; no upstream prose or examples are copied
into this repository.

A method note this repository should hold us to. One URL in an earlier pass of
this work was produced by a page summarizer rather than by the publisher, was
then fetched, and its 404 was reported as an upstream defect. It was not: the path
existed nowhere upstream. Every URL in this PR is either extracted by script from
the file being edited or confirmed against a publisher-emitted page list
(sitemap.xml / llms.txt). No pointer here rests on a summarizer's output.

Commands and behavioral evidence

Run locally on this branch before pushing:

$ npm test
ℹ tests 35
ℹ pass 35
ℹ fail 0

$ npm run validate
PASS: marketplace <checkout>; 0 error(s), 0 warning(s).

The directly relevant gate is tests/documentation-contract.test.mjs's "the
upstream index retains every required live OpenAI pointer", which passes — this
change adds a pointer and re-targets two, and removes none. "repository-owned
Markdown pointers resolve" also passes.

Staging used an explicit path (git add docs/OFFICIAL-DOCS.md). The commit is
signature-verified.

AGENTS.md PR contract — rows that do not apply

Named rather than silently omitted. User goal and vertical slice: keep the
upstream source map accurate, so a preflight performed against it is actually
sufficient; the slice is the index file alone. Live upstream URLs consulted and
the date checked: above. Context inputs and precedence: AGENTS.md's
preflight and PR contract, and this file's own stated purpose; no precedence
conflict arose. Native surfaces selected, ports and adapters introduced,
defaults, configuration, and fallbacks, and migration dispositions and
intentional differences are all not applicable — no plugin, skill, manifest,
script, or marketplace entry changes here, and no CLI surface is touched, so the
codex ... --help inspection required for CLI-affecting changes is not triggered.

Related

No linked issue. This corrects a documentation index defect found while
completing the live preflight requested by review on #19; it is recorded in this
repository's planning artifacts rather than as a GitHub issue.

This PR is independent of #19 and does not depend on it. It is offered for
maintainer review on its own merits.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.