docs: simplify the README for first-time users

[noeltock]

Problem

The README mixed first-use instructions with compiler, proof and compatibility contracts. It also left the AI boundary unclear and named an old Wesper collector version. Closes #111.

Solution

Lead with a complete HTML-to-block example, explain the CLI/library/optional-skill relationship, and move detailed contracts into linked reference pages. The README is 145 lines, down from 607. Builds on #112 and #113; this PR contains only the README and its two reference documents.

Behaviour or contract	Read first	Proof
A first conversion has supplied input and actual output	README quickstart	Fresh installed CLI produced the exact shown markup
AI is optional; the two outputs and assembly APIs are distinct	Workflow table and library section	Source review plus installed library example
Advanced contracts and existing links remain reachable	docs/reference.md	Relocation review, 24 retained README anchors
Development instructions match current CI routing	docs/development.md	Compared with scripts/ci-scope.mjs and existing scripts
Installed users can find the detailed guides	README documentation table	Repository URLs; package allowlist unchanged

Diff

+638 −549 · 3 files · no runtime or API changes

 README.md
- compiler and verification contracts before basic usage
- quickstart referring to an unexplained hero.html path
+ complete paragraph input, CLI command and Gutenberg output
+ workflow table, runnable library example and optional agent skill
+ limitations, benchmark distinction and links to detailed guides
+ compatibility anchors for the relocated sections
+ docs/reference.md
+   existing CLI/API, proof, configuration and styling contracts
+   corrected assembly/authoring explanations and Wesper 0.4.1 pin
+ docs/development.md
+   testing, current CI routing and historical benchmark details

The complete registered-block walkthrough remains in skills/block-runner/references/AUTHORING.md, as established in #91. That file, the installed skill prompts and the package allowlist are unchanged.

Testing & verification

Reviewed revision: 703d77209f26e1a176bc35a588b1d228f7158481 · Environment: macOS, Node 22.23.1; engine-strict fresh consumer installed from the candidate tarball.

• npx --no-install block-runner convert hello.html — passed with the README's supplied input and exact output.
• npx --no-install block-runner convert hello.html --out hello.blocks.html — passed; file matches the shown output.
• npx --no-install block-runner convert hello.html --json — passed: ok: true, one valid block, zero invalid blocks and no warnings.
• node hello.mjs — passed using the README's library example; same block markup and empty findings.
• npx --no-install block-runner skill --install — passed; both documented discovery directories were created in the isolated consumer.
• npm run check:private and npm run pack:check — passed. Separately reviewed all five documentation files for private references because docs/ is not packed.
• python3 /tmp/block-runner-docs-pass/check-links.py . README.md docs/reference.md docs/development.md docs/architecture.md docs/extending.md — passed, 76 candidate repository paths/anchors and zero failures. This local review utility is not a new repository dependency. Links to new main-branch documents become live when the stack merges.
• git diff codex/docs-architecture-110...HEAD --check — passed.
• npx vitest run dev/test/node-support.test.ts — passed, 4 tests. The install command retains the exact package engine range alongside the plain-language Node requirements.
• Source and relocation review found no lost advanced contracts; all 24 real headings from the previous README retain working fragments.

Not verified: human first-use/readability acceptance, fresh WordPress rendering or visual fidelity. The examples establish CLI/library/package behaviour, and the review establishes source consistency. GitHub CI passed on the reviewed revision: all three Node lanes, package-boundary, WordPress proof and the aggregate scope check. Run 34983974679. The additional packed custom-rule check and its duplicate class-token observation are recorded on #112.

Risk / rollout

Moving documentation can break navigation or separate a requirement from its explanation. Old README fragments now lead to the documentation table, with links to the corresponding detailed sections. The new guide links target the documentation added in #112 and #113.

Detection: check the retained anchors and linked contracts when editing these guides. Rollback: revert this PR's documentation commits. No website, dependency, generated template or release changes are included.

Authored by: GPT-6 via Codex.