docs, test: harden newcomer onboarding (#194, #202, #203, #208, #209, #212)

[dgenio]

Summary

Six tightly-coupled documentation and metadata fixes that share the README, pyproject.toml, and docs/ surface — bundled so the new smoke tests (#203) can guard the doc fixes (#194, #202, #209, #212) from regressing the moment they land, and so the new runtime-responsibilities page (#208) is anchored into both the README and the mkdocs nav.

Pure docs + tests + package metadata. No runtime code changes. The single touched non-test source file is chainweaver/__init__.py, where __version__ is bumped from "0.9.0" → "0.10.0" to match the release commit in pyproject.toml — the kind of drift the new metadata-consistency test catches.

Changes

File	Issue	Change
pyproject.toml	#209	[project.urls] adds Documentation, Source, Changelog, Issues so PyPI sidebar / pip show link users to the right place; keywords expanded.
chainweaver/__init__.py	#209	__version__ bumped to "0.10.0" to match pyproject.toml (now caught by tests/test_metadata_consistency.py).
README.md	#194, #202, #208, #209, #212	New top-of-file "See it in 30 seconds" before/after narrative (#202); expanded Installation extras table (#209); "Where ChainWeaver fits in the Weaver Stack" subsection (#212); link to the new runtime-responsibilities page from the MCP Integration section (#208); paragraph + entry-script snippet explaining set_default_registry next to the inspect/viz CLI examples (#194). Two existing Python blocks marked with <!-- smoke-test: run --> so they get exercised by the new smoke test.
docs/runtime-responsibilities.md (new)	#208	5 sections (when to invoke, trace persistence/redaction, side-effect tools, flows as named operations, MCP parity) + concrete handle_request example.
mkdocs.yml	#208	Wires the new page into nav under "Is this for me?".
tests/test_readme_smoke.py (new)	#203	Extracts opt-in <!-- smoke-test: run --> Python blocks and runs each in a fresh subprocess (with the repo on PYTHONPATH); asserts chainweaver --help lists every registered command; asserts chainweaver validate examples/double_add_format.flow.yaml exits clean from a fresh checkout; asserts all bundled examples the README points to exist; asserts the chainweaver[yaml] install note appears near the first .flow.yaml mention.
tests/test_metadata_consistency.py (new)	#203, #209	Asserts pyproject.toml version ↔ chainweaver.__version__ ↔ latest released ## [x.y.z] heading in CHANGELOG.md agree, and that [project.urls] exposes the required user-navigation URLs. Uses stdlib tomllib on 3.11+ with a regex fallback for 3.10.
tests/test_runtime_responsibilities_doc.py (new)	#208	Anti-drift: the page exists, has the 5 required H2 sections, includes a concrete handle_request example, the README links to it, and mkdocs.yml includes it in nav.

Why

All six issues describe distinct first-30-seconds-of-the-repo failure modes that the maintainer-triage process kept reopening (#190 / #192 / #193 / #195 / #196 / #197 closed earlier today were the concrete instances; #194 and the rest in this PR are the next batch plus the systemic guard). Shipping the README polish (#194 / #202 / #209 / #212) alongside the smoke tests (#203) means the class of drift becomes a CI failure mode from day one rather than something that has to be re-discovered by the next contributor.

The runtime-responsibilities page (#208) is the only sizable new doc; it lands here because the README's MCP-integration section now links to it, so the two issues' acceptance criteria are jointly satisfied without orphaning either page.

Testing

• Linting passes (ruff check chainweaver/ tests/ examples/) — All checks passed
• Formatting check passes (ruff format --check chainweaver/ tests/ examples/) — 152 files OK
• Type checking passes (python -m mypy chainweaver/) — 125 files, 0 issues
• All existing tests pass (python -m pytest tests/ -v) — 1107 passed
• New tests added for new functionality — 23 new tests in 3 new test modules

Reproducible verification:

$ python -m ruff check chainweaver/ tests/ examples/
All checks passed!

$ python -m ruff format --check chainweaver/ tests/ examples/
152 files already formatted

$ python -m mypy chainweaver/ tests/
Success: no issues found in 125 source files

$ python -m pytest tests/ -q --no-cov
........................................................................ [97%]
........................................................................ [100%]
1107 passed in 10.08s

Targeted run of the new suites:

$ python -m pytest tests/test_readme_smoke.py tests/test_metadata_consistency.py tests/test_runtime_responsibilities_doc.py --no-cov -v
...
23 passed in 1.30s

Related Issues

Closes #194 — README inspect example assumes a programmatically-registered registry.
Closes #202 — Rewrite README landing path around a concrete before/after use case.
Closes #203 — Add README and docs snippet smoke tests to prevent onboarding drift.
Closes #208 — Add runtime responsibilities page.
Closes #209 — Improve package metadata and install docs.
Closes #212 — docs: link ChainWeaver into the Weaver Stack ecosystem map.

Follows directly from the triage in #214's predecessor sweep (six already-fixed issues closed today: #190, #192, #193, #195, #196, #197).

Checklist

• Code follows project conventions (see AGENTS.md and docs/agent-context/) — anti-drift tests mirror tests/test_cli_docs.py's pattern; smoke-test subprocess plumbing mirrors tests/test_cookbook_examples.py's pattern; commit message follows the repo's docs, test: … conventional style.
• Public API changes are documented — none; this PR is docs + tests + package metadata only. __version__ bump is metadata, not API.
• No secrets or credentials included.

Scope notes (Mode B)

User explicitly authorized Mode B + "one PR for all" + "I don't care about retro compatibility" + "new dependencies if worthy". I did not add any new runtime dependency (the test deps pytest / pyyaml are already in [dev]). Mode B latitude used only for: (a) bundling all six issues in one PR per the user's explicit request; (b) fixing the __init__.py ↔ pyproject.toml version drift discovered while writing the metadata consistency test, which is in #209's explicit scope ("Ensure package version metadata remains consistent with chainweaver.__version__"); (c) wiring the new docs page into both the README and the mkdocs nav rather than leaving it floating.

Tradeoffs / risks

• Smoke-test opt-in marker (Add README and docs snippet smoke tests to prevent onboarding drift #203). I chose opt-in (<!-- smoke-test: run -->) over opt-out (allowlist file) because the README has many illustrative Python blocks (16 today) and the asymmetry is asymmetric: missing one illustrative block from the allowlist breaks CI for innocent reasons, while missing one runnable block from the marker just fails to catch a future regression in that block. Marking two blocks today (Quick Start and @tool decorator); follow-ups can mark more.
• Subprocess PYTHONPATH plumbing. The smoke test forces PYTHONPATH=<repo_root> into the subprocess so README blocks work from a fresh checkout and from an editable install. This matches what a newcomer running python -c "$(cat block.py)" from the repo root would experience.
• tomllib vs tomli for 3.10. Repo supports Python >=3.10 but tomllib lands in stdlib at 3.11. Rather than add tomli to [dev] for the single 3.10 leg, I added a small regex fallback in _pyproject_table() that handles the keys the test reads. If 3.10 ever drops from the matrix, the fallback becomes dead code and is one delete away.
• agent-context/ doc-drift. The README and the new page do not duplicate docs/agent-context/ content; that boundary stays intact (agent-context/ remains not_in_nav per the existing mkdocs convention).
• Weaver Stack URL (docs: link ChainWeaver into the Weaver Stack ecosystem map #212). The sibling-projects table cross-references issue numbers (Declare weaver-spec v0.1.0 compatibility + run conformance in CI #91 / Consume RoutingDecision from contextweaver for dynamic step resolution #106 / Add optional agent-kernel execution backend (FlowExecutor via Kernel) #89 / Interop: turn repeated workflow failures into reviewed lessons #210), not external URLs, because the sibling repos' canonical URLs are still being shaped. When weaver-spec publishes the ecosystem map, the placeholder link in the same subsection can be promoted to a real URL in a one-line follow-up.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'ChainWeaver microbenchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.25.

Benchmark suite	Current: 19378b5	Previous: 530174a	Ratio
compiled_total_ms_n2_llm100_tool0	0.18995399994992113 ms	0.14817599998195874 ms	1.28
compiled_overhead_ms_n2_llm100_tool0	0.12493199994878523 ms	0.08674199997926735 ms	1.44
compiled_overhead_ms_n5_llm500_tool50	0.36212600002727413 ms	0.21608299999797964 ms	1.68

This comment was automatically generated by workflow using github-action-benchmark.

CC: @dgenio

[Copilot]

Pull request overview

This PR hardens newcomer onboarding by updating top-level docs and package metadata and adding anti-drift tests that exercise README snippets, verify metadata consistency, and ensure the new runtime-responsibilities doc stays wired into the docs site/navigation.

Changes:

• Add smoke/anti-drift tests for README runnable snippets, CLI help/validate, metadata/version consistency, and the runtime-responsibilities doc presence/structure.
• Expand README onboarding content (30-second narrative, installation extras table, Weaver Stack positioning) and add the new docs/runtime-responsibilities.md page wired into mkdocs.yml.
• Update pyproject.toml keywords/URLs and bump chainweaver.__version__ to match the package version.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/test_runtime_responsibilities_doc.py	Adds anti-drift assertions for the new runtime-responsibilities doc page and its references.
tests/test_readme_smoke.py	Adds opt-in README fenced-python execution + CLI and bundled-example smoke checks.
tests/test_metadata_consistency.py	Adds version/URL consistency checks across pyproject.toml, runtime __version__, and CHANGELOG.md.
README.md	Updates onboarding narrative, installation extras guidance, Weaver Stack context, and links to runtime responsibilities; adds smoke-test markers.
pyproject.toml	Expands keywords and adds [project.urls] entries for user navigation.
mkdocs.yml	Adds the runtime responsibilities page to the published nav.
docs/runtime-responsibilities.md	Introduces a host-responsibilities guide for embedding ChainWeaver (invocation, traces, side effects, MCP parity).
chainweaver/__init__.py	Bumps __version__ to 0.10.0.