# Stand In

> Stand In turns a messy brain-dump into a Context Capsule: a reviewed,
> approved handoff living at one shareable link. People read it as an
> editorial briefing and ask it questions; agents read and ask it over MCP.
> Answers come ONLY from context the creator approved, with the supporting
> items cited, and every question it cannot answer is recorded for the
> creator, so the Capsule gets smarter with use. The same host also serves
> legacy Gather links (structured intake interviews) and Give links
> (knowledge-base pages), and you can create and run all of it for your
> human entirely over MCP, no browser needed.

## Handed a Capsule link? Start here

If someone gave you (or your human) a Stand In link, bind it to this
conversation first so the next turn is not a one-shot fetch.

Preferred: add the per-capsule MCP server. The slug is the last path
segment of the link (strip a trailing `.md` if present):

    claude mcp add --transport http standin \
      https://THIS-HOST/api/stand-in/<slug>/mcp

That server is this chat's capsule. `read_briefing`, `ask_capsule`, and
`diff_since` take no link. Write `.standin` as `{"link":"<url>","slug":"<slug>"}`
in the working directory so the CLI is bound the same way
(`npx usestandin bind <link>`).

Still on the generic respond server (no bind yet)? Connect once:

    claude mcp add --transport http standin-respond \
      https://THIS-HOST/api/respond/mcp

Then:

- `bind_capsule` with the link: returns `slug`, `link`, `mcpUrl`, and
  `standinFile`. Add `mcpUrl` as an MCP server, or write `standinFile` to
  `.standin`. Later turns need no pasted URL.
- `read_briefing` with the link: the approved narrative as markdown. One
  call. No item ids.
- `ask_capsule` with the link and a question: a grounded answer citing the
  items it drew from. When the Capsule does not know, it says so and records
  the question for the creator. Never fill an unknown with your own guess;
  the honest refusal IS the product working.
- `diff_since` with the link and `since` (the `updatedAt` from a previous
  read): only items newer than that watermark.
- `read_capsule` with the link: an overview — from who, for what, item titles
  with ids and trust, and any files it shares. Item bodies are omitted on
  purpose. Prefer `read_briefing` unless you need ids. Pass specific ids to
  `read_capsule_items` when you need full bodies.
- `read_capsule_items` with the link and item ids from `read_capsule`: the
  full bodies of those live items only. Unknown ids are omitted.
- `download_capsule_file` with the link and a file id from `read_capsule`:
  the file's bytes, base64-encoded, exactly as the creator uploaded them.

That is the whole recipient loop: bind, briefing, ask what you need, pull
what changed. No account. The constraint (only approved context, honest
misses) is the product; do not wrap a general chatbot around it.

On a hosted Stand In page and no link was handed to you? The page tells you
itself. Look for an `x-standin-capsule` response header, a
`<meta name="standin:capsule">` tag, `<meta name="standin:mcp-bound">`, or a
JSON block at `#standin-capsule` in the head (`mcpBound` is the per-capsule
server). Any of them gives you the capsule link and MCP endpoint, so you can
read and ask it without being handed anything.

On ANY page (including sites we do not host), a Stand In embed is a recognizable
signal in the HTML: a script tag of the form
`<script src="<host>/embed.js" data-capsule="<slug>">`. If you see one, the host
is that script's origin and the capsule link is its `data-capsule`; add
`<host>/api/stand-in/<slug>/mcp`, or query `<host>/api/respond/mcp` with the
link. When the page is rendered (JavaScript runs), the same
`<meta name="standin:capsule">` and `#standin-capsule` descriptor appear in the
head too, injected by the embed.

Prefer a terminal and no MCP client? The same loop is one command:
`npx usestandin bind <link>`, then `npx usestandin read --md` and
`npx usestandin ask "your question"` with no link. `npx usestandin diff --since <ISO>`
pulls only what changed. For the full approved briefing in one shot without
bind: `npx usestandin read <link> --md` (that is `GET /<slug>.md`).

The same generic server carries the intake tools for Gather links you were handed:
`start_intake`, `answer_intake`, `finalize_intake`. The link itself is the
credential for all of these, exactly like the web page.

## Creating and managing for your human

The creator-side MCP server lives at `/api/mcp`, authorized with a
per-creator bearer token sent as `Authorization: Bearer <token>`. Your human
generates it once from their creator home ("Generate a new token"). Ask them
for it, or run `npx usestandin login` and approve in the browser (token saved
to `~/.config/standin/token`). You cannot mint or rotate it yourself by design,
so an agent can never lock its owner out.

    claude mcp add --transport http standin \
      https://THIS-HOST/api/mcp \
      --header "Authorization: Bearer <token-from-home>"

The server is stateless. Call `who_am_i` first after connecting, then
`tools/list`. `who_am_i` reports the credential kind (`bearer` or `oauth`),
your `actorClientId` (a stable id, never a display name), and open review
counts. Reads return a `rev`; writes accept optional `ifRev`. On
`revision_conflict`, re-read, merge, and retry with the new rev.

## The workflows worth knowing

Handoff (Capsule). The signature flow. A person dumps everything into one
canvas at /new (type, paste, talk); the product quietly crystallizes typed
context items out of their words, they approve what travels, preview the
exact recipient briefing, and publish one link. Recipients and their agents
read and ask it; unanswerable questions come back to the creator as ready-
to-answer cards.

Pass a project to another agent. Dump verbatim sources — a git tree, a
large markdown file, a folder of notes — with `create_stand_in`
(`organize: false` on a large dump so we do not crystallize the whole
tree into briefing cards). Skip `node_modules`, `.git`, and secrets. The
next agent on this token calls `search_context`, then `list_sources` /
`read_source` (overview, then a line slice or full). Crystallize
(`organize: true`, the default on a small dump) is for a *human*
briefing and Mirror; it is optional for agent-to-agent. Recipients still
only see what was approved and published. CLI: `npx usestandin create
--from .` then `npx usestandin search "auth" --capsule <id>`. Skill:
`/.well-known/agent-skills/standin/SKILL.md`.

Brief a teammate from mixed sources. One `create_stand_in` call can take
whatever you can pull: project notes, a PDF or spreadsheet (`files`),
labeled notes (`from` + `text` — Slack, Drive, email, a page, a repo, a
call, Granola; original words or a faithful extract, not an invented
essay), and a finished Gather (`intakeSlug` or `intakeSessionIds`). The
human reviews, publishes, and hands the live link to the teammate, whose
agent binds it.

Client onboarding (Gather). Create a link that interviews a new client
before a kickoff call and returns a clean structured record. Provide a JSON
Schema for the fields you want. The interview asks one question at a time,
merges answers into a record, recaps for confirmation, and finalizes behind
a separate retrieval secret. Fold that record into a capsule with
`create_stand_in` / `add_context` (`intakeSlug` or `intakeSessionIds`) so
the next agent stays inside it. Read the raw result with `get_record` when
legacy Gather tools are on.

Vacation cover (Give, legacy). Create a link that answers from a seeded
knowledge base. For new handoffs prefer a Capsule: it adds review, trust
states, provenance, and the learning loop.

## Creator tools (bearer token)

Capsule authoring (you file and read; your human decides):

- `create_stand_in`: dump notes, files (PDF, CSV, xlsx), URLs, and labeled sources into a capsule. `notes` is a string (a project dump) or an object (`from`, `text`) for anything you pulled. `intakeSlug` / `intakeSessionIds` folds in finalized Gather interviews this creator owns. `organize: false` files sources only; default true crystallizes a human briefing in the background. Skip YouTube, secrets, node_modules.
- `add_context`: append more verbatim notes. `organize: false` skips
  crystallization.
- `session_start` / `session_end`: load the last session note and open
  gaps (read-only); file a session summary as a source, never approved.
- `mint_add_link` / `list_add_links` / `revoke_add_link`: a copy-link so
  someone else can dump new sources. They cannot edit or publish. Mirror
  still holds what they add.
- `search_context`: search sources and items by meaning-bearing terms
  (a vague question is ranked, not only an exact phrase). Optional
  `capsuleId` and `nearPath` (a file in the working tree). Then
  `read_source`.
- `list_item_revisions` / `restore_item_revision`: every version of an
  item, who wrote it (human or agent, never an OAuth name). Restore
  proposes a copy; the human still approves.
- `export_library`: every capsule as markdown (published files match
  `GET /<slug>.md`).
- `mint_webhook` / `list_webhooks` / `revoke_webhook`: named https
  endpoints. POSTs are HMAC-signed (`webhook-id`, `webhook-timestamp`,
  `webhook-signature`). Secret shown once. Events: `capsule.published`,
  `gap.opened`.
- `list_sources` / `read_source`: list sources, then read one. Overview
  default; `view: lines` or `view: full`.
- `add_source_url`: fetch one public http(s) page.
- `add_file`: attach bytes; readable types become sources.
- `watch_source`: watch a URL or RSS feed; new material is proposed, never
  auto-approved. Not a Feed screen.
- `get_capsule_state` / `read_capsule_items` (creator) / `list_capsules`.
- `host_page`: HTML deliverable at `/d/<slug>` with the ask widget. Dropping an
  `.html` file on Capture also hosts it, marks it the primary artifact, and
  shares that URL.
- When your human has decided, `approve_capsule_items` and `publish_capsule`.
  Until then, recipients see nothing. Same-token agents can search and read
  sources immediately.
- Rehearsal & manage: `run_coverage_check`, `get_demand_insights`,
  `start_bake` / `get_bake_status`, `preview_capsule`, `preview_ask_capsule`,
  `compose_capture_reply`, `approve_agent_filings`, `reject_agent_filings`,
  `set_source_consolidation`. Per-tool reference: `/docs/mcp-reference`.

Legacy link tools:

- `provision_agent`: create a Gather/Give link. Key arguments:
  `displayName`, `purpose`, `dataUseStatement`; for Gather pass `schema`
  (a JSON Schema string); for Give pass `giveEnabled: true`, optional
  `bookingUrl`, `kbEntries`. Returns a `slug` and `url`.
- `list_agents`: every link you own, with mode, status, counts, open gaps.
- `list_sessions`, `get_record`: inspect Gather responses, pull a record.
- `list_knowledge`, `update_knowledge`: read and edit Give knowledge.
- `list_questions`: every question recipients asked a published capsule,
  answered or not, including what they pointed at on an embedding page.
- `list_gaps`, `answer_gap`, `dismiss_gap`: questions a link could not
  answer, and how to resolve them.
- `update_agent_settings`, `kill_agent`: change or disable a link.
- `add_participant`, `list_participants`, `close_intake`: multi-participant
  Gather.

## What to keep true

- Answers must stay grounded. A Capsule or Give link asserts only what its
  approved context contains. Do not instruct one to answer from outside it,
  and do not paper over its refusals.
- Every knowledge write is screened for sensitive content. If a write is
  flagged, stop and ask your human before setting `confirmSensitive`.
- The public link slug is for sharing. It is not a retrieval secret and not
  a bearer token. Keep the bearer token private to your human.