## Summary

The toolkit now documents itself using only its own runtime *and* its
own structured-data parsers. No Python in CI; no hand-rolled regex over
markdown or HTML.

## What changed

| Was | Now |
| --- | --- |
| `bin/_docs_components.py` (200 lines, dead-code dicts) | *deleted* |
| `bin/_load_catalog.py` (370 lines: hand-rolled YAML-subset parser,
regex section splitter, regex snippet extractor) | replaced with proper
parsers |
| `bin/build-reference.py` (220 lines) | `bin/build-reference.php` |
| `bin/run-snippets.py` (230 lines) | `bin/run-snippets.php` |
| `bin/serve-docs.py` (50 lines) | `bin/serve-docs.php` (uses `php -S`
with router) |

## Parsers

| Surface | Parser |
| --- | --- |
| README YAML frontmatter (`slug`, `title`, `install`, `credit_*`,
`see_also`) | **`Webuni\FrontMatter\FrontMatter::parse()`** — already
vendored under `components/Markdown/vendor-patched/` for the Markdown
component. Single-line, multi-line `key: |`, and YAML lists all behave
correctly. The same parser GitHub uses for the README's frontmatter
table. |
| Markdown body → AST | **`League\CommonMark\Parser\MarkdownParser`** +
walking the document. Section boundaries = `Heading` nodes at level 2.
Snippets = `HtmlBlock` (`<!-- snippet: -->`) → `FencedCode` (info=`php`)
tuples. Expected-output = `HtmlBlock` (`<!-- expected-output -->`) →
`FencedCode` pair. Body content rendered via
`HtmlRenderer::renderNodes()` so raw HTML round-trips verbatim. |
| Pitfall callouts (HtmlBlocks of the form `<p>Footgun: …</p>`) |
**`WP_HTML_Tag_Processor`** — walks tokens, confirms a `<p>` opener,
finds the first inner `#text` node, classifies, strips the `Footgun:` /
`Gotcha:` prefix via `set_modifiable_text()`, then slices off the outer
`<p>...</p>` by length (no regex). |
| Lede paragraph → inline HTML (no outer `<p>`) | Render the lede
`Paragraph` node's **inline children directly** via
`HtmlRenderer::renderNodes()` instead of slicing afterward. |
| Snippet metadata comment (`<!-- snippet: filename: x.php\nrunnable:
true\n-->`) | String slicing of literal `<!--` / `-->` delimiters — no
regex. |
| `--update` writing captured stdout back into a README | **CommonMark
AST** locates the snippet's exact line range; line-by-line splice. No
regex over the README. |

## Behavioural parity

- **87/87 snippets** match their captured stdout. The PHP normalizer
mirrors the Python regex set 1:1, so existing expected-output blocks
stay valid.
- **`docs/reference/*.html`** render correctly: 9 `<php-snippet>` + 9
fallback + 9 expected-output triples on `html.html`, 4 pitfall callouts
(the bold-lead pattern is preserved), see-also list intact.
- **`--update`** verified end-to-end:
- When an expected-output block has drifted, the rewritten content is
byte-for-byte the original.
- When no expected-output exists for a snippet, `--update` inserts a
fresh block in the right place; resulting README is byte-identical to
one with the block authored manually.

## Frontmatter format change: `see_also` is a proper YAML list

```yaml
# Before (repeated keys — not standard YAML)
see_also: a | A | reason
see_also: b | B | reason

# After
see_also:
  - a | A | reason
  - b | B | reason
```

`Webuni\FrontMatter\FrontMatter` correctly types it as a sequence; any
frontmatter-aware tool reading the README sees the same shape. All 18
component READMEs migrated.

## Workflows simplified

- `snippet-tests.yml` drops the `actions/setup-python` step.
- `docs.yml` swaps `python3 bin/build-reference.py` for `php
bin/build-reference.php`.

## Remaining `preg_*` calls (all on plain text, not HTML)

- `slugify()` — heading text → URL-safe slug.
- `normalize()` — scrubs noise from snippet stdout (tempfile paths, git
hashes, timestamps).
- One pattern in run-snippets that matches the `require
'...autoload.php';` line in the snippet's PHP **source** to inject the
local-prelude polyfill.

These operate on plain strings, not HTML, so they're not what the "no
regex over HTML" rule was about.

## Test plan
- [ ] `Verify docs snippets` workflow passes (87/87).
- [ ] `Deploy docs to GitHub Pages` runs cleanly on push to trunk.
- [ ] Local preview: `bash bin/build-docs-bundle.sh && php
bin/serve-docs.php` — http://localhost:8787 renders all reference pages
with snippets.
- [ ] `php bin/run-snippets.php --update` (no-op, no drift) leaves all
READMEs untouched.