docs: explain workflows and terminology

[noeltock]

Problem

Developers had no public map connecting the CLI, library and agent skill to the conversion and registered-block workflows. Similar names also hid different contracts. Closes #110.

Solution

Add a source-linked architecture guide covering inputs, outputs, shared finalisation, generated-block delivery and the existing terminology. Builds on the custom-rule example in #112; the diff contains only the architecture guide.

Behaviour or contract	Read first	Proof
CLI assemble runs the full workflow; library assemble builds objects	Page-content conversion	Traced CLI dispatch, realize and assemble
Registered-block generation has separate compilation and write stages	Registered-block generation	Traced source analysis, compiler and destination callers
Diagnostic locations identify the correct input or generated output	Validation and error locations	Read both provenance implementations
Developers can locate the relevant module	Source map and glossary	36 candidate repository links checked

Diff

+95 −0 · 1 file · no runtime or API changes

+ docs/architecture.md
+   CLI/library/skill relationship and workflow table
+   convert + realize -> shared finalisation
+   separate registered-block analysis, generation and delivery map
+   source-location explanation, terminology and module links

Testing & verification

Reviewed revision: 3c4694a56e3fe269b243aea3e09b2f4f74d2b36c · Environment: macOS, source inspection against the 0.9.7 code.

• python3 /tmp/block-runner-docs-pass/check-links.py . docs/architecture.md docs/extending.md — passed, 36 candidate repository paths/anchors and zero failures. This was a local review utility, not a new repository dependency.
• npm run check:private — passed. The new guide was separately reviewed because docs/ is outside the packed-file scan.
• git diff --cached --check — passed before commit.
• Technical review followed one conversion path and the registered-block source path. The guide distinguishes analysis-derived compilation from supplied plans, and direct library writes from CLI confirmations.

Not verified: human onboarding acceptance. This is a documentation/source review, not new WordPress runtime or visual proof. GitHub CI passed on this revision: all three Node lanes, package-boundary, WordPress proof and the aggregate CI scope check. Run 34981865592.

Risk / rollout

Source links or diagrams can drift as implementation changes. The guide links entry points and identifies the different assembly and write boundaries without renaming them. The website, skill instructions and runtime remain unchanged.

Detection: follow the named callers when changing those workflows. Rollback: revert this guide commit. Merge after #112; the README entry link follows in the final documentation PR.

Authored by: GPT-6 via Codex.