Cut the comments back, rebuild docs/, and make both checkable

[pbking]

Three commits, each reviewable on its own.

1. Comments cut back to a summary line and its tags

Docblocks carried long explanations of why the code is the way it is — what core does and why that forced a choice, what was tried before, which decision a rule came from. That belongs in the docs; in the source it was 26% of every non-blank line and went stale silently.

	before	after
docblock lines	8,672	6,324
block /* */	924	101
line //	799	70
total	10,395	6,495

Left alone, because something reads them: the plugin header and every theme pattern's own header (Plugin Name:, Title:, Slug:, Synced: — reducing one deregisters the plugin, or the pattern, and this was the single most dangerous case), phpcs:ignore, /* translators: */, and eslint-disable.

Comments were located with PHP's own token_get_all() and with Babel, never by pattern-matching: // inside 'https://…' or a regex literal is everywhere here, and a regex pass would have eaten code. To prove the edit reached nothing else, every changed file had all comments stripped from both its old and new version and the remaining code compared. Four differ, each the repo's own formatters run afterwards — eslint's curly adding braces, prettier unwrapping two method chains whose parens only existed because comments split them, an empty catch { /* … */ } collapsing to catch {}, and two CSS comments inside an inline <style> that the PHP tokenizer sees as HTML.

2. The notes the code cannot carry, and a rebuilt docs/

Nine one-line comments went back, only where the code looks arbitrary or redundant and getting it wrong fails silently — the theme root without which WP_Theme_JSON_Resolver hands back a theme with every preset emptied; the $post global core/post-content reads instead of its context; the mirror rows read before anything deletes them; the array wp_handle_sideload() takes by reference; the variable-font weight whose space would be escaped in every URL; the theme.json cache that is stale after a write; late_route_registration; the annotations that select an ability's HTTP method; and why constrain() is passed a mime type rather than sniffing one. Each is guarded by a test, so the bug never ships; the comment buys back the diagnosis.

docs/ is rebuilt around what exists now:

• The 1.x deep dive — self-labelled HISTORICAL, describing the DB mirror and REST hijacking that 2.0 removed — is deleted.
• architecture-2.0.md is promoted to architecture.md and brought current. It had gone stale in two places: the browse grid draws its tiles on the server now, and the Site Editor's canvas is never used, not even for the user patterns it could host.
• abilities.md and cloud.md are new, and are where most of CLAUDE.md's bulk now lives.
• collections.md and dependencies.md lose their "Order of work" and "Acceptance" sections, which planned work that shipped. dependencies.md named an export_tree() that was never built; the walk is local_tree() + rewrite_references().

CLAUDE.md: 10,987 words → 942. readme.md drops the marketing copy and the use cases for what the plugin is, how to run it, and where to read.

3. Keeping it true, and checkable

Both repos already said "docs/ is living" and both had drifted anyway. So CLAUDE.md gains a Keeping the documentation true section — a change is not finished until the documents describing it are right, corrected in place and in the same commit — backed by npm run check:docs.

The check reads every backticked token in CLAUDE.md, readme.md and docs/ and verifies it: a path must exist, a directory must have something tracked under it, a symbol must appear in the source. That is exactly how these rot — a class renamed, a file moved, a method never built — and it is the part a person cannot do by reading. Mutation-tested: all three are caught.

What it cannot do is stated where people will read it: a sentence can be wrong with every identifier in it spelled correctly, so green means the names are real, not that the document is true.

Verification

	before	after
phpcs	2 errors	1 — the pre-existing i18n one
lint:js	41 errors	7 — the pre-existing no-unused-vars
lint:css	clean	clean
check:docs	—	0 unresolved
test:unit	—	104 passed
PHP suite	425/426	425/426

• I added the missing @param $tile on document_around(), since CLAUDE.md asks for pre-existing violations to be fixed in files you touch and a missing doc comment is squarely this PR's subject. The remaining phpcs error is MissingSingularPlaceholder; fixing it edits a translatable string, so I left it.
• The 7 lint:js errors are dead imports in PatternDetailsPanel.js, identical at the base.
• The one PHP failure is test_convert_theme_image_pattern_exports_assets, which fails identically at the base — the media pipeline this sandbox lacks, as CLAUDE.md documents.

Safe_Css is vendored byte-for-byte into patternbuilderwp.com apart from its namespace. Both copies got the identical transform and their bodies still match line for line — checked, not assumed. The shared tests/php/fixtures/safe-css-cases.json is untouched and still has the same md5 in both.

Companion PR: Twenty-Bellows/patternbuilderwp.com#57.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KtSTgGTH5hSBWVLPCJohhi