The README describes the product as it stood before #164. Somebody arriving today is told to do things that no longer exist, and told nothing about the two mechanisms that now decide what Braid feels like to use.
What it says that is no longer true
"run a skill such as /ddd:extract from the Actions tab" — the Actions tab left the sidebar. Extract runs from Build, per document or per group, and the pipeline across the top is read from the ontology's own build skills.
"Answer any Clarification the agent raised", alongside "open each Proposal" as two separate acts on two surfaces — they are one queue now. The Inbox holds both, a question and a change are two kinds of card in one list, and a run parked on several questions is one item because answering the last of them is what carries the run on.
"Studio (web UI), Desktop, CLI, and MCP clients all talk to one server over REST and SSE" — a run is read over AG-UI now. The CLI reads no runs at all: it has dev, init, serve, and workspace, and nothing that streams one.
The Features list predates the block protocol, the audience split, and evidence that resolves to its own host. None of those appear anywhere in the README.
What is missing and matters more
A run's output is typed, not prose. A skill renders by calling a tool, and each call is a route on Braid's own OpenAPI spec, so it is also a named MCP tool with a schema. The agent fills in fields. RenderBlock lives in schema, which is the one layer the server and Studio both see, so one zod object is the route body, the tool schema, and the renderer's type at once. A block carries no layout, which is what lets the same sequence be a scrolling answer on one surface and a record beside a proposal on another.
AG-UI is the wire format, and adopting it was the point. Studio consumes /agui with a stock HttpAgent, which is the only objective check that the endpoint is the protocol rather than something shaped like it. Any other client of AG-UI reaches Braid the same way. This deserves saying out loud, because "we speak a standard protocol" is a claim a reader can verify and "we have a nice UI" is not.
An answer is written for a reader. The ontology declares its audiences, and a block can name one. Most of an answer names nobody and everyone sees it; what differs is the part written for the reader who is here, and how much of a reference is shown.
A run is offered only the tools its kind of run may call. An ask run's gateway is handed a narrowed spec, so proposing is not something it is asked not to do, it is something it cannot see.
The deployment gap that cost a working afternoon
Nothing anywhere says that the server serves Studio from BRAID_STUDIO_ROOT, or that unset it answers 401 JSON at / and there is no UI at all. Nor that BRAID_HOME decides which directory the workspaces and registries live in, and that a server started without it silently reads an empty one and reports no workspaces.
Both are read in composeFsApp.ts and appear in no document. Two of us lost time to exactly this today. A deployment section naming every environment variable the server reads, and what each does when absent, is the single highest-value addition here.
Also worth revisiting
- The Quick Start points at
http://localhost:5173, which is the Vite dev server. A deployment serving the built bundle is on the API port, and the README never mentions that path exists.
- The architecture diagram still shows seven surfaces.
- The demo gif shows the old Clarification and Proposal surfaces.
Not this issue
Rewriting the Motivation or Design sections. The framing there still holds; it is the Usage, Architecture, and Features sections that describe a product that changed underneath them.
The README describes the product as it stood before #164. Somebody arriving today is told to do things that no longer exist, and told nothing about the two mechanisms that now decide what Braid feels like to use.
What it says that is no longer true
"run a skill such as
/ddd:extractfrom the Actions tab" — the Actions tab left the sidebar. Extract runs from Build, per document or per group, and the pipeline across the top is read from the ontology's own build skills."Answer any Clarification the agent raised", alongside "open each Proposal" as two separate acts on two surfaces — they are one queue now. The Inbox holds both, a question and a change are two kinds of card in one list, and a run parked on several questions is one item because answering the last of them is what carries the run on.
"Studio (web UI), Desktop, CLI, and MCP clients all talk to one server over REST and SSE" — a run is read over AG-UI now. The CLI reads no runs at all: it has
dev,init,serve, andworkspace, and nothing that streams one.The Features list predates the block protocol, the audience split, and evidence that resolves to its own host. None of those appear anywhere in the README.
What is missing and matters more
A run's output is typed, not prose. A skill renders by calling a tool, and each call is a route on Braid's own OpenAPI spec, so it is also a named MCP tool with a schema. The agent fills in fields.
RenderBlocklives inschema, which is the one layer the server and Studio both see, so one zod object is the route body, the tool schema, and the renderer's type at once. A block carries no layout, which is what lets the same sequence be a scrolling answer on one surface and a record beside a proposal on another.AG-UI is the wire format, and adopting it was the point. Studio consumes
/aguiwith a stockHttpAgent, which is the only objective check that the endpoint is the protocol rather than something shaped like it. Any other client of AG-UI reaches Braid the same way. This deserves saying out loud, because "we speak a standard protocol" is a claim a reader can verify and "we have a nice UI" is not.An answer is written for a reader. The ontology declares its audiences, and a block can name one. Most of an answer names nobody and everyone sees it; what differs is the part written for the reader who is here, and how much of a reference is shown.
A run is offered only the tools its kind of run may call. An
askrun's gateway is handed a narrowed spec, so proposing is not something it is asked not to do, it is something it cannot see.The deployment gap that cost a working afternoon
Nothing anywhere says that the server serves Studio from
BRAID_STUDIO_ROOT, or that unset it answers401JSON at/and there is no UI at all. Nor thatBRAID_HOMEdecides which directory the workspaces and registries live in, and that a server started without it silently reads an empty one and reports no workspaces.Both are read in
composeFsApp.tsand appear in no document. Two of us lost time to exactly this today. A deployment section naming every environment variable the server reads, and what each does when absent, is the single highest-value addition here.Also worth revisiting
http://localhost:5173, which is the Vite dev server. A deployment serving the built bundle is on the API port, and the README never mentions that path exists.Not this issue
Rewriting the Motivation or Design sections. The framing there still holds; it is the Usage, Architecture, and Features sections that describe a product that changed underneath them.