docs: components/<Name>/README.md is the catalog source

.github/workflows/docs.yml

@@ -9,7 +9,6 @@ on:
       - 'bin/build-docs-bundle.sh'
       - 'bin/build-reference.py'
       - 'bin/_docs_components.py'
-      - 'bin/_docs_components/**'
       - 'bin/_load_catalog.py'
       - 'composer.json'
       - 'composer.lock'

.github/workflows/snippet-tests.yml

@@ -1,6 +1,6 @@
 name: Verify docs snippets
 
-# Runs every PHP snippet declared in bin/_docs_components/<slug>.md against
+# Runs every PHP snippet declared in components/<Name>/README.md against
 # the local toolkit and compares stdout to the expected-output block stored
 # next to the snippet in markdown. Anything that drifts fails CI; anything
 # that errors out also fails CI.
@@ -14,7 +14,6 @@ on:
     paths:
       - 'components/**'
       - 'bin/_docs_components.py'
-      - 'bin/_docs_components/**'
       - 'bin/_load_catalog.py'
       - 'bin/run-snippets.py'
       - 'composer.json'

.gitignore

@@ -57,3 +57,4 @@ docs/reference/zip.html
 
 # Bundled toolkit source for WordPress Playground — regenerated on every deploy.
 docs/assets/php-toolkit.zip
+docs-changes.md

bin/_docs_components.py

@@ -1,10 +1,12 @@
 # Component catalog for the runnable docs site.
 #
 # Per-component content (lede, sections, snippets, credit callouts,
-# see-also links, expected snippet outputs) is sourced from
-# bin/_docs_components/<slug>.md — see bin/_load_catalog.py for the format.
-# That keeps the docs source in plain markdown with code-fence snippets,
-# editable in any text editor and renderable as-is on github.com.
+# see-also links, expected snippet outputs) is sourced from each
+# components/<Name>/README.md — see bin/_load_catalog.py for the format.
+# The README *is* the catalog source: GitHub and Packagist render it as
+# a normal README (frontmatter is hidden by GitHub's renderer); the
+# build pipeline parses the frontmatter + snippet metadata blocks to
+# generate the docs site and run snippets in CI.
 #
 # This file still owns the small global metadata that doesn't belong in any
 # single component's markdown: the landing-page starter paths and the