📚 docs(blocks): document that removing a block breaks published content

[kuuak]

Why

docs/blocks/create-block.md explains every step needed to register a block, but never says what registration is for once the block exists. Read as-is, a registration entry looks like scaffolding for new content — something safe to tidy away during an unrelated refactor.

It isn't. Registration is the link between already-published content and code:

• Drop a slug from blocksList in next/src/components/global/Blocks.tsx → the frontend renders nothing and logs The following block does not exist: <slug> (see Blocks.tsx:113).
• Drop the WordPress-side registration → Gutenberg no longer recognises the saved markup and shows the block as invalid content.

Because the slug is that link, a rename is a removal plus an addition — existing content still points at the old slug.

Now that registration is split across WordPress and Next, there are two independent ways to break live pages, and the guide flagged neither.

What changed

Documentation only — no behaviour change.

• docs/blocks/create-block.md — new "Removing or renaming a block" section, placed before the checklist.
• .claude/skills/wordpress-block-change/SKILL.md — a matching change rule, next to the existing "Do not introduce duplicate block registrations" rule. That rule covers adding duplicates but says nothing about removal, so coding agents using the skill had no reason not to drop one.

The quoted warning string is verbatim from Blocks.tsx; both relative links and the heading anchor were checked.

Context

This came out of a headless-WP project built on an older Superstack generation, where the equivalent rule lived in an ad-hoc .cursor/rules file as "NEVER delete wordpress blocks from the edit file". The constraint is a property of the stack rather than of any one project, so it belongs here.

Unrelated observation — stale paths in create-block.md

Not addressed in this PR (I'd be guessing at the intended structure), but noticed while adapting the doc. Checked against future @ 4a3943a:

Path referenced by the doc	Status
wordpress/theme/src/blocks/	missing (entire directory)
wordpress/theme/src/blocks/index.ts	missing
wordpress/theme/src/editor/editor.ts	missing — actual file is editor/index.ts
next/src/css/patterns/	missing
wordpress/theme/patterns/, next/src/components/filters.ts	OK

Steps 3–4 of Option B and Step 3 of Option A point at directories that don't exist. The doc also uses a ramoneurs/ namespace and a benefits-list-item block that aren't in the repo, and no block.json exists under next/src/components/custom/, so Step 1's example has no counterpart. Happy to open a separate issue if useful.

My section links only to Blocks.tsx, which does exist.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NMQ82izBcjxySfEM7W4nTP