docs: 5-minute MCP tutorial + neighboring-projects boundaries table

[dgenio]

Summary

Implements the documentation/onboarding group identified during triage:
#46 (5-minute tutorial) + #71 (neighboring-projects boundaries). One PR
because both deliverables land in README.md/docs/ and serve the same
first-time-reader goal — splitting them would just churn the same files twice.

What changed

#46 — Tutorial

• New docs/tutorial.md walks a new reader from pip install through
  registration, principals, grants, all three LLM-safe response modes
  (summary/table/handle_only), handle expansion, a policy denial with
  a stable reason_code, and an audit via explain(). The MCP section
  points at docs/integrations.md rather than forking a second source of
  truth on MCP transports.
• New examples/tutorial.py is the runnable companion using only
  InMemoryDriver — offline, zero external dependencies. Demonstrates
  explicitly that email never reaches the LLM-safe Frame across any of
  the response modes (PII fields leaked into Frame: 0).
• Wired into the Makefile example target and the CI Examples step so the
  tutorial is exercised on Python 3.10/3.11/3.12 every push.
• README quickstart now points new readers at docs/tutorial.md.

#71 — Neighboring-projects boundaries

• README "How this relates to neighboring projects" section: neutral
  comparison table covering agent-kernel (this repo, embeddable
  runtime), AgentFence (external CLI/proxy gate), contextweaver
  (context compilation library), ChainWeaver (deterministic flow
  orchestrator), and weaver-spec (specification + conformance suite).
• Compact "minimal architecture" diagram showing the runtime path.
• "When not to use this" callout sending readers to the right neighbor
  project when agent-kernel is the wrong tool.

Misc

• CHANGELOG.md [Unreleased] entries for both additions.

Why

From triage on claude/triage-issues-Yzss7: of the 9 open issues not
already covered by an open PR, #46 and #71 were the most coherent pair —
both unblocked (MCP Driver shipped via #66 unblocked #46), both fully
closeable by the same PR, both share README.md, and the implementation
risk is the lowest of any plausible group. The marketplace cluster
(#52 + #49) had similar coherence but #49 was explicitly kept open as a
tracker, so that group's closure yield was lower.

How verified

• ruff format --check src/ tests/ examples/ — 49 files already formatted.
• ruff check src/ tests/ examples/ — All checks passed.
• python -m pytest -q — 450 passed in 0.96s.
• All four examples (basic_cli.py, billing_demo.py,
  http_driver_demo.py, tutorial.py) run cleanly end-to-end.
• The tutorial example asserts PII fields leaked into Frame: 0 against
  the table-mode preview — that line will fail loudly if the firewall
  ever regresses on allowed_fields enforcement.
• Pre-existing mypy notes (pydantic stub resolution,
  adapters/_base.py Any returns) verified to predate this branch via
  git stash — no src/ files were touched in this PR.

Tradeoffs / risks

• CI cycle grows by one short example (~50 lines of output, sub-second
  runtime).
• Sister-repo descriptions in the boundaries table were verified
  one-line-at-a-time against the existing README's tone and against the
  repo names; a reviewer with first-hand knowledge of each sister repo
  should sanity-check the wording.
• The tutorial's MCP section deliberately defers to
  docs/integrations.md rather than duplicating transport details, so
  there is exactly one canonical source for the MCP code patterns.

Scope notes (Mode B)

Two issues, one PR. Adjacent issues left untouched: #38 (OTel), #45
(namespaces), #47 (streaming firewall), #49/#51/#52 (marketplace), #68
(decompose policy_dsl.py + dry-run driver coverage), #74/#75/#76
(already covered by PR #79). One follow-up worth noting: #46 still
carries a stale blocked label (its blocker, MCP Driver, landed in
#66) — happy to drop the label in a follow-up if desired.

Closes

Closes #46
Closes #71

https://claude.ai/code/session_01E9jQWivDjJuYMXEFEq9Pq7

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds first-time-reader onboarding material: a runnable 5‑minute tutorial (offline + optional MCP section) and a README section clarifying boundaries vs neighboring Weaver ecosystem projects. It also wires the new tutorial example into make example and CI so it stays runnable.

Changes:

• Add docs/tutorial.md and a companion runnable examples/tutorial.py covering register → grant → invoke → expand → explain, with an MCP “swap the driver” section.
• Update README.md with a “neighboring projects” boundaries table + minimal architecture diagram + “when not to use this” guidance, plus a quick pointer to the tutorial.
• Run the new tutorial example in make example and the GitHub Actions CI workflow; document both additions in CHANGELOG.md.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Adds tutorial pointer and boundaries/architecture section for new readers.
Makefile	Includes examples/tutorial.py in the example target.
examples/tutorial.py	New runnable tutorial script using InMemoryDriver, executed by CI.
docs/tutorial.md	New 5‑minute walkthrough doc, with optional MCP driver swap guidance.
CHANGELOG.md	Adds Unreleased entries for the tutorial and boundaries section.
.github/workflows/ci.yml	Runs examples/tutorial.py as part of the Examples step.