feat: README/landing-page conversion overhaul (#225, #227, #228, #229, #232)

[dgenio]

Summary

Overhauls the first-touch experience: it reframes the README + docs landing page around ChainWeaver's actual moat (observe → compile → replace + governance) and ships the missing zero-install on-ramps. All five issues edit the same README hero region, so doing them in one PR avoids five colliding edits and lets the new tagline, demo, headline number, Colab badge, and stack diagram be tuned as one coherent landing page.

Changes

• positioning: lead with "observe → compile → replace" + governance, demote the "save LLM calls" hero #225 (positioning) — README.md and docs/index.md now lead with "observe → compile → replace" + governance; the old "Compile deterministic tool flows into LLM-free executable runs" hero and the top before/after mermaid (the strawman the issue calls out) are demoted, with "saving LLM calls" reframed as a consequence.
• benchmark: publish one headline cost/latency/correctness number with a reproducible harness (README hero) #227 (benchmark headline) — the hero surfaces a quantified, reproducible claim (0% vs 61–96% data corruption; ~$0.06 of LLM spend avoided per 10-step flow), linked to the committed report benchmarks/results/latest.md and reproducible with python benchmarks/report.py. (Numbers taken from the existing Publish benchmark report artifacts for latency, cost, and correctness claims #207 artifact; no noisy regen committed.)
• docs: add a 30-second demo GIF/asciinema to the top of the README #228 (demo asset) — docs/assets/quickstart.svg, an animated terminal SVG rendered from a real examples/simple_linear_flow.py run, is now the first visual in the README. scripts/gen_demo_cast.py is the headless, reproducible regenerator (captures real stdout → asciinema cast → termtosvg render); the cast is committed at docs/assets/quickstart.cast.
• dx: add an "Open in Colab" zero-install notebook (interim to the web playground #81) #229 (Colab notebook) — notebooks/quickstart.ipynb (defensive self-install → @tool → execute → export adapters) + an "Open in Colab" badge in the README. Exercised in CI via nbmake (new dev deps nbmake, ipykernel) on the ubuntu-latest / 3.12 lane so it can't silently rot.
• ecosystem: add the standardized "Part of the Weaver Stack" section + diagram + weaver-stack topic #232 (Weaver Stack) — standardized "Part of the Weaver Stack" section with the shared request-path diagram (contextweaver → ChainWeaver → agent-kernel → agentfence; adjacent vibeguard, lessonweaver, skdr-eval), an explicit standalone or together / no hard dependency note, and a weaver-stack package keyword.
• Rot guard tests/test_readme_assets.py; docs/agent-context/workflows.md CI section updated for the new nbmake step.

Testing

• Linting passes (ruff check chainweaver/ tests/ examples/) — All checks passed! (also clean on scripts/)
• Formatting check passes (ruff format --check chainweaver/ tests/ examples/) — clean
• Type checking passes (python -m mypy chainweaver/) — Success: no issues found in 131 source files (ran chainweaver/ tests/)
• All existing tests pass (python -m pytest tests/ -v) — 1196 passed, coverage 91.46% (gate 80%)
• New tests added for new functionality — tests/test_readme_assets.py (7 passed)
• Notebook executes (pytest --nbmake notebooks/) — 1 passed
• Docs build (mkdocs build --strict) — exit 0

Related Issues

Closes #225, closes #227, closes #228, closes #229, closes #232.

Checklist

• Code follows project conventions (see AGENTS.md and docs/agent-context/)
• Public API changes are documented — N/A, no public API symbols added (docs/assets/CI only)
• No secrets or credentials included

Maintainer follow-up (cannot be done from a PR)

• ecosystem: add the standardized "Part of the Weaver Stack" section + diagram + weaver-stack topic #232 also asks for the GitHub repo topic weaver-stack. Repo topics aren't settable via PR/MCP — please add it under Settings → Topics. The weaver-stack PyPI keyword is included here as the in-repo signal.
• docs: add a 30-second demo GIF/asciinema to the top of the README #228 / benchmark: publish one headline cost/latency/correctness number with a reproducible harness (README hero) #227 numbers and the demo cast should be refreshed on a release cadence (python scripts/gen_demo_cast.py && termtosvg render …, python benchmarks/report.py).

Notes / risks

• The demo SVG uses termtosvg's CSS-keyframe output, which animates inline on GitHub via <img>. If a reviewer prefers a GIF, the same .cast can be fed to agg.
• #225's "observe → compile → replace" copy is scoped to existing capabilities (ChainAnalyzer schema discovery, governance/attestation) — it does not claim the not-yet-built runtime auto-suggest-from-trace (Implement runtime chain observer with auto-flow suggestion #78/feat: chainweaver record — auto-suggest flows from a live agent tool trace (on-ramp for #78) #226).

---

Generated by Claude Code

[Copilot]

Pull request overview

Overhauls ChainWeaver's first-touch experience by repositioning the README/docs landing page around "observe → compile → replace" plus governance, and adds the missing zero-install on-ramps (animated demo SVG, Colab notebook, benchmark headline link, Weaver Stack section).

Changes:

• New README hero (tagline, Colab badge, animated quickstart.svg, governance bullets, quantified benchmark headline) and a standardized "Part of the Weaver Stack" section with shared diagram and "no hard dependency" note; docs/index.md mirrors the new positioning.
• New zero-install/regeneration assets: notebooks/quickstart.ipynb (defensive install → @tool → execute → export), scripts/gen_demo_cast.py (real-run cast generator), committed docs/assets/quickstart.{cast,svg}, and weaver-stack PyPI keyword.
• CI/test wiring: nbmake + ipykernel added to dev extras, new nbmake step on ubuntu/3.12, tests/test_readme_assets.py rot-guard, and docs/agent-context/workflows.md updated.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	New hero (tagline, Colab badge, demo SVG, moat/governance/benchmark blocks); standardized Weaver Stack section + diagram.
docs/index.md	Landing page mirrors new positioning and links the benchmark report.
docs/assets/quickstart.svg	Committed termtosvg-rendered animated demo of a real simple_linear_flow.py run.
docs/assets/quickstart.cast	Committed asciinema cast feeding the SVG.
scripts/gen_demo_cast.py	Headless, reproducible cast regenerator that captures real example stdout.
notebooks/quickstart.ipynb	Colab quickstart: defensive install, @tool defs, flow execution, export adapters.
tests/test_readme_assets.py	Structural rot guards for SVG, Colab badge, notebook, benchmark headline, Weaver Stack section.
pyproject.toml	Adds weaver-stack keyword and nbmake/ipykernel dev deps.
.github/workflows/ci.yml	Runs pytest --nbmake notebooks/ on ubuntu-latest / 3.12.
docs/agent-context/workflows.md	Documents the new nbmake CI step and adds docs.yml row.