docs: rebuild README, adopt agent-surface.dev, link GitHub from the docs site

[pbWise]

What

Three changes, all presentation and metadata — no library code.

1. README rebuilt to match the orpc-agent README's shape and quality.
Centered header with tagline and badges (CI, license, Node, npm, docs), a doc-nav line, a > [!NOTE] release/CI block, then: The idea → Why → Quick start → What happens on a call → What it gives you → Security model → Packages → Catching surface changes in review → Example → Non-goals → Development → Contributing → License.

Two mermaid diagrams replace the ASCII ladder: the one authority path (untrusted above the registry, application below, compiler gating both registry and bindings), and an invocation that hits confirmation through to server re-validation.

2. agent-surface.dev is now the official docs link.
Every doc link in the README points there, plus the homepage field in all seven package.json files and the Docs: line in the webmcp/testing READMEs. No reference to agent-surface-docs.vercel.app remains.

3. The docs site links back to GitHub.
socialLinks GitHub icon, "Edit this page on GitHub" edit link, footer source link + copyright, a "View on GitHub" hero action, and a short Project section on the home page pointing at the repo, CONTRIBUTING, and SECURITY.

Why

The README was a terse spec summary; orpc-agent's reads as a project front page. Same author, same npm scope conventions, so they should present alike. And the docs had no path back to the source.

Reviewer notes

• The CLI output in the README is real, not illustrative. I ran agent-surface inspect on examples/devices-app, then temporarily flipped devices.disable to server-mutation/optional to capture a genuine drift block, and reverted the file. That produces the mirror of orpc-agent's counter-intuitive-classification point: lowering a declared effect classifies as widening, because every gate keyed to the higher effect quietly stops applying.
• Both mermaid blocks were parse-checked against the mermaid parser this repo already depends on.
• All 12 agent-surface.dev links return 200. The apex 308s to www, so the links work as written.
• .changeset/docs-domain.md bumps all seven packages at patch, per the lockstep rule in .changeset/README.md — homepage is published metadata, so it needs a release to reach npm. changeset status confirms 0.20.1 across the board.
• Claims in the README are grounded in docs/ (plane rule, hide-vs-disable, confirmation digest binding, the explainSurface build-enforced boundary) and keep the honest non-claims: no same-realm isolation, no exactly-once, no forced cancellation.
• pnpm docs:build passes; the built HTML contains the social link, edit link, and footer. I could not screenshot the running site — port 5173 was held by another project's VitePress and the browser preview policy check never cleared, so verification is from built output rather than a rendered page.

Unrelated and left alone: .changeset/README.md:11 links ../docs/project/12-roadmap.md, which does not exist in this repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-surface-docs	Building	Preview	Aug 2, 2026 5:24pm