# 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, connect to the public
respond server, no auth needed, at `/api/respond/mcp` on this same host:

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

Then:

- `read_capsule` with the link: the whole approved briefing, from who, for
  what, every context item with its trust state (approved directly, source
  backed, inferred, conflicted, stale), and any files it shares.
- `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.
- `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: read once, ask what you need, pull any data
files. No account, no setup beyond adding the server above.

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, or a JSON block at `#standin-capsule` in
the head. Any of them gives you the capsule link and the respond 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`; query it at
`<host>/api/respond/mcp`. 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 standin read <link>` and `npx standin ask <link> "your question"`.

The same 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. 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 `tools/list` to see everything.

## 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.

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. Read the result later with `get_record`.

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`: the one-call path, and the one to prefer. Give it a
  `title` and `purpose`, plus optional `authorName`, `audience`, `until`
  (YYYY-MM-DD), `notes` (an array of verbatim context strings), and `files`
  (each `{ filename, contentBase64, contentType?, shareWithRecipients? }`).
  It creates the capsule, files every note and file as agent-authored, and
  crystallizes them into proposed items in a single pass. Returns the
  `reviewUrl` where your human approves what travels and publishes. When you
  already have the material, this is the whole authoring step in one call.
- `create_capsule`: start an empty handoff, then build it incrementally with
  the two tools below. Use when you are gathering context over several turns
  rather than all at once.
- `add_context`: file verbatim notes as preserved sources and crystallize
  them into proposed items in one pass. Only file what your human actually
  said, wrote, or decided; never your own guesses.
- `add_file`: attach one file (`filename`, `contentBase64`, optional
  `contentType`, `shareWithRecipients`). Readable files (text formats, PDFs)
  are read into the capsule and crystallized; others are housed and travel
  only if shared.
- Everything above files as agent-authored and waits for the human at the
  reviewUrl: there is deliberately no approve or publish tool.
- `get_capsule_state`: what awaits review, what is approved, open recipient
  questions, the live link when published.
- `list_capsules`: every capsule with status and counts.

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.