[codad5]

Docs and tooling only: nothing under src/ changes behaviour (two classes gain an @since tag), so no release is needed.

What

composer docs generates an API reference into docs/api/ (ADR-0028). Foundation and Http are published first (26 files); the rest follow as their docblocks are reviewed.

• One page per public class, interface and enum, in one reading-order chain (layers in the order to learn them; the config names each layer's first classes), with a previous / up / next footer.
• Every page starts with YAML front matter (schema: "wptoolkit-api/1"): title, type, fqcn, namespace, layer, source, since, stability, order, summary, related.adr, and prev / next / up (paths relative to the page, so they are also working links). The field table is in the ADR.
• docs/api/index.json lists every page in order with the same facts; its paths join directly.
• Signatures, defaults and modifiers come from Reflection; the prose, parameter text, @throws and @since from the docblocks; ADRs the code cites become links. @internal classes and methods, magic methods and implicit interfaces (Stringable, UnitEnum) are left out.
• Output is deterministic (no dates, LF endings, fixed order); values that change every release (Application::VERSION) print as (set at release) so a version bump does not make the reference stale.

Why generated

A hand-written reference is the 0.x API.md again. The docblocks already carry the reasoning; this puts them where people and agents read, in an order, with facts a tool can read without parsing prose.

Checks

• composer docs:check (now part of composer verify) fails if a committed page differs from the source, is missing, or is stale.
• New CI job API reference: docs:check, then npm ci --ignore-scripts and a Node test that parses every page with gray-matter, checks required fields, unique consecutive order, that prev / next / up resolve from each page, that every relative link exists, that index.json agrees, and that following next from the index visits every page.
• 25 PHP tests against fixture classes: docblock parsing (types with spaces, wrapped text), what is documented and omitted, signatures, links, ADR paths, front matter, order, determinism, drift (changed, missing, stale, CRLF checkouts).
• Verified on Linux with PHP 8.1: the files generated on Windows with PHP 8.3 are byte-identical and docs:check passes. Static analysis caught that ReflectionClass::isReadOnly() does not exist on 8.1 before CI did.

Notes

• New dev dependency gray-matter 4.0.3 (recorded in tech-stack.md). npm audit flags it only through js-yaml, which @wordpress/env already brings; it only reads our own generated files.
• Thin docblocks show as thin pages (many parameter descriptions are empty). That is the to-do list for the next namespaces.
• Foundation exposes CoreServices, Coexistence, CopyOwner, LibraryTranslations and ToolkitCompatibility, which look like wiring. Whether they are API (or should be @internal) is a decision for the maintainer, not made here.

🤖 Generated with Claude Code