docs: describe the product as the block protocol left it

[mroops0111]

Closes #172.

The README last changed substantially in #105. Four merges since then moved what it describes, and a reader arriving today is told to do things that no longer exist and told nothing about the mechanisms that now decide what Braid feels like to use.

• Give every run's output a typed block protocol, and reshape Studio's surfaces around it #164 gave a run's output a typed block protocol and put AG-UI on the wire
• feat: turn the graph into documents a reader can open, and keep them as blocks #179 wired the view axis end to end and added the Documents surface
• feat: name what a run hands to a person, and gate it as one resource #178 named a Handoff and hung the permission model off it
• Lend a conversation to another member, and retire the Actions surface #182 retired the Actions surface

Two commits. The first fixes what is false. The second fixes what the front door spends its space on.

What Was False

Two mechanisms get a section each, because they are what a reader can check. Typed Blocks says a skill renders by calling a tool, that each call is a route on Braid's own spec and therefore an MCP tool with a schema, and that a block carries no layout. AG-UI on the Wire says Studio consumes /agui with the protocol's own HttpAgent, which is the only objective test that the endpoint is the protocol rather than something shaped like it. Documents as Projections says the deterministic half of a document never passes through model output, and that staleness falls out of the split rather than being tracked.

The Loop described a product that changed underneath it. It routed a reader to an Actions tab that left the rail, and to a Proposal surface and a Clarification surface as two separate acts. It now routes through Build, one Inbox holding both kinds of card, and Documents.

Architecture no longer says a run travels over SSE, nor that the CLI reads one. The CLI has init, serve, dev, and workspace, and nothing that streams a run.

A skill's category decides what it is offered, which is the reader-facing half of the narrowed spec. ask, build, and generate each get a line, and the frontmatter example declares one.

@braidhq/source-loader-mcp and @braidhq/view-generator-doc were missing from the package table.

Package READMEs

These drifted the same way and were not in the issue's scope, but they are what somebody reads after the root one.

• studio: described seven surfaces, the Actions and Batch panels among them, and a run read over SSE. Now six surfaces, the block renderers, and a run read with a stock AG-UI client.
• server: the MCP Gateway section said a per-run gateway exposes the whole spec. forRuns ended that, and the gateway reads GET /openapi/runs/:category/openapi.json. Role gains the run wire and the render calls, and infrastructure/agui/ joins the tree.
• schema: the module families listed a clarify module that does not exist and omitted block, handoff, capability, coverage, reference, locale, embedding, and source-sync.
• core: ClarifyTicket has been Clarification for a while, and ViewService was missing from the services.
• sdk: defineViewGeneratorPlugin said a view kind renders a snapshot into an artifact, which predates subjects and format.
• ontology-ddd: scan was missing from the skills, and renderHint now orders a document as well as colouring a canvas.
• source-loader-mcp: the one package README that never followed the Role / Structure / Boundaries / Dependencies shape the other fifteen use. Restructured onto it with nothing removed.

What It Spends Its Space On

The root README is the project's front door, not its manual, and a correct document can still be the wrong one.

A worked example, which it never had. examples/conciergent has been in the repository the whole time: 120 nodes and 159 edges derived from one real codebase with no intent documents, the reviewed clarifications and proposals alongside, and a rendered graph. Every claim above it was abstract, so a reader could only believe it or not. One rule is quoted in full with the two source lines it was drawn from, because that is the shortest way to show what a model a PM can read actually looks like.

Five features, not seven. Past five a reader stops ranking and starts skimming, and the most distinctive item gets the weight of the most generic. Blocks and AG-UI were one story told twice, so they are one bullet. Git-versioned history becomes a clause of the gate it belongs to.

AG-UI moves to a badge. "We speak a standard protocol" is a credibility claim, and a badge is where a project makes one. It costs no space in a list whose job is to say why a reader should care, and the Design section still carries the detail.

The Deployment section goes. The issue asked for the full variable table in the root README, and that was the one recommendation not taken. packages/server/README.md has held that table since #117, and a second copy would drift against the first. It is also operator documentation: Quick Start's job is to get something running, and twelve lines about containers and a bare 401 belong after that, not inside it. One sentence points at compose.yaml and the server package.

Quick Start now says what is needed first. A reader could install, create a workspace, press run, and watch nothing happen, because a skill run is a claude subprocess and the README never mentioned it.

Motivation gains the objection a reader actually has now. The two failure modes it argued against were the 2024 ones. "Why not point an agent at the repository" is the current one, and the answer is the thesis: the graph is not an index that makes retrieval faster, it is where judgement is put so it outlives the conversation that produced it.

A Status section, because a public repository at 0.6.0 that never says where it stands reads as either abandoned or overclaiming.

Not in This PR

• The demo gif still shows the old Clarification and Proposal surfaces. It needs re-recording against a workspace whose contents can be shown publicly, and the hero alt text changes with it.
• The architecture diagram. architecture.pen is editable JSON and architecture.png is the rendered export, which needs the design app. Held for a separate pass rather than landing a half-updated pair.

Verified

eslint over every changed file, which is what lint-staged runs on .md. Every relative link resolves, examples/conciergent/graph.png is tracked so the image renders, and the packages/server/README.md#deployment anchor exists. No arrows or em-dashes in any file touched.

🤖 Generated with Claude Code