Write up the proof of concept and expand the README

[chiplay]

Stack 3/3 — the write-up. Builds on #1 (package) and #2 (example). Internal review only for now; nothing goes to the Next.js or agent-browser repos until the team signs off.

What this changes

Adds docs/proposal.md and turns the stub README.md and AGENTS.md into the real front door. The proposal covers: where this sits relative to sitemap.ts, the layering, what was verified (with transcripts), where the humans stay in the loop, whether the corpus can enrich agent-browser directly, a friction log, and the PR sequence we would propose to Vercel.

Why

Three projects meet here and a reviewer needs one picture of how they stack:

flowchart TB
  subgraph repo["in the repo"]
    corpus["<b>.sightmap/</b><br/>what the app <i>is</i>"]
    tools["<b>.sightkick/</b><br/>what the app <i>can do</i>"]
  end
  seed["sightmap-next seed"] -.routes.-> corpus
  loop["sightmap CLI + agent<br/>coverage loop"] -.curate.-> corpus
  human["a person keeps the tools that matter,<br/>ranks the journeys"] -.gate.-> tools
  corpus & tools --> build["sightmap-next build"]
  build --> served["/.well-known/sightmap.json<br/>/.well-known/sightkick.json<br/>/sightkick-runtime.js"]
  build --> init["webmcp.init.js"]
  served --> comp["&lt;SightkickTools/&gt;"] --> mc["document.modelContext<br/>native WebMCP"]
  init -- "--init-script" --> mc
  mc --> ab["agent-browser"] & chat["ChatGPT browser · Chrome"]
  feat["features/*.feature"] -- "agent, once" --> plans["plans/*.plan.json"] -- "run-plan" --> ab

Loading

The sitemap.ts question. Right for the served half (/.well-known/sightmap.json is to agents what sitemap.xml is to crawlers), wrong for the corpus, which the spec makes a curated authority. Hence seed / curate / publish, and a metadata file convention in Next.js only as a later RFC.

Can the corpus enrich agent-browser directly? Its plugin protocol has four capabilities: credential.read, browser.provider, launch.mutate, command.run. None touch snapshot, so annotating the accessibility tree with component names needs an upstream change. What a plugin can do today: launch.mutate to auto-load webmcp.init.js when .sightmap/ is present, and command.run to surface sightmap snapshot / explain through agent-browser and its MCP debug profile. With Sightkick in the middle, most of the value arrives as tools and guidance anyway, which agent-browser already consumes.

Proposed sequence, after internal review: (1) agent-browser docs and a webmcp-gen addendum, no code; (2) vercel/next.js/examples/with-sightmap-webmcp, which is #2 trimmed; (3) an RFC discussion for an app/sightmap.yaml convention; (4) two small Sightkick follow-ups (sightkick build --format init-script, --via agent-browser).

Checklist

• Commits are signed off (git commit -s)
• npm test passes (docs only)

🤖 Generated with Claude Code

https://claude.ai/code/session_013FZAbWuynKT4NqXFMwtoBA

---

Generated by Claude Code