# Braid

> Braid is a branchless code host: one converging history per repository,
> with signed intent layers instead of branches and pull requests. Agents are
> first-class collaborators here — the intended way for an LLM to read and
> write a Braid repository is the Braid MCP server, not scraping this app.

This file is also served at /agents.txt, /agents.md, and
/.well-known/llms.txt. The full agent documentation, inlined into one
document, is at /llms-full.txt.

## What you are looking at

This origin serves two things:

- The Braid web app (a JavaScript single-page app — every HTML path returns
  the same shell, so fetching pages here tells you almost nothing).
- The hosted Braid API, same-origin under `/v1`. Writes authenticate with
  passkeys and a session cookie — there are no API tokens or bearer keys to
  find — but the public commons is readable without any auth (see below).

## MCP server (the agent front door)

The Braid MCP server is `braid-mcp`, a zero-npm-dependency stdio server
(source: `mcp/braid-mcp.mjs` in the Braid tree). This origin publishes it as
one self-contained file — no checkout, no npm install, just Node 20+:

    curl -fO https://braid-forge.pages.dev/braid-mcp.mjs
    claude mcp add braid -- node braid-mcp.mjs

By default it talks to this deployment; `BRAID_URL` points it elsewhere.

Its ~48 `braid_*` tools deliberately parody the GitHub MCP server, so an
agent that knows how to work a GitHub repository already knows the shapes:
issues, releases, notifications, and file pushes work as expected, while
pull requests become intent layers (`braid_create_intent` →
`braid_set_intent_state` → per-operation review → `braid_converge_intent`)
and code search becomes `braid_scope_beam`, a token-true symbol lookup.
Clients that defer tool schemas can load just `braid_core` (reads) and
`braid_write` (mutations) — each is a dispatcher with an `action` enum.

## Signing in

Agents act as their person, never as themselves. The server reuses the Braid
CLI credential store (`~/.braid/credentials.json`) and is signed in exactly
when `braid whoami` is. Three ways in:

- `braid link` in a terminal (device-code link to a browser account), or
- the `braid_connect` tool → your person enters the code at /#/link →
  `braid_connect_complete`, or
- `braid_register` for a brand-new account with a software passkey.

Repository writes are signed with the machine's registered P-256 device key,
so provenance survives review: your edits land in your person's layers,
credited to them.

## Read-only HTTP surface (no auth, no MCP runtime needed)

An agent that can only make HTTPS requests can still read the public
commons directly — plain GET, JSON responses:

- `GET /v1/repos` — every public repository (`?query=` filters by
  name/description substring).
- `GET /v1/repos/{repoId}` — one repository (`repoId` looks like
  `repo:<uuid>`, from the list above).
- `GET /v1/repos/{repoId}/issues` — issues; other workflow surfaces
  (releases, milestones, labels) follow the same shape.
- `GET /v1/braid/repos/{repoId}/head` — the signed native head of the
  converging history.

Responses are keyed by surface name (`{"repositories": [...]}`,
`{"issues": [...]}`). Everything that writes, and everything private, needs
the MCP server and a linked account — raw HTTP has no way to sign.

## House rules

- Same write path, same review, same credit as any collaborator — an
  agent's edit converges exactly as far as the review panel accepts it.
- Governance is human-only by design: no tool exists for charter adoption or
  amendment, poll stances, roster admission, allocation decisions, or payout
  binding — and adding one is a policy violation, not a feature request.
- Presence is never logged; briefs and their responses deliberately are.

## Docs

- [Braid MCP server guide](/docs/mcp.md): the full tool suite, the
  GitHub-to-Braid mapping, the intent-layer workflow, and every server-side
  timeout and limit.
- [Bringing your agents to Braid](/docs/AGENTS.md): briefs (the human
  gesture), how an agent picks one up and answers it, and whose work the
  result is.
- [Everything above plus both docs in one file](/llms-full.txt)
- [The MCP server itself, ready to run](/braid-mcp.mjs): single-file build,
  Node 20+, stdio transport.