feat: turn the graph into documents a reader can open, and keep them as blocks

[mroops0111]

Closes #174. Closes #130. Supersedes #147.

The view-generator axis was fully declared and never called. ViewGeneratorPlugin had viewKind, configSchema, render and skills, the registry had three ways to reach one, and nothing shipped a generator, nothing called render, and ViewArtifact.format had no reader. Meanwhile braid:generate-doc wrote CommonMark into a path that resolves on the server host, so against a remote workspace a user could run the skill and never read what it wrote.

This wires the axis end to end, and settles what a document is made of.

What changed

A document is a stored sequence of render calls. The first cut wrote HTML fragments, and that was rejected on token economics. An HTML form has to spell out everything a reader sees, including the half the projection already knows: every heading, every node name, every status, every id in the footer. A block form emits calls against a fixed schema and the surface draws the rest. Measured on the same subject, the block form's output is about 61% smaller, and the deterministic half never passes through model output at all. Both are not written, because paying twice for the same information is the thing this was trying to avoid.

The writing is split in two. @braidhq/view-generator-doc projects a subject into material JSON, which is a function of the graph, so the same graph and subject give the same bytes. Two skills, reference and tutorial, read that material and write the page. Neither is handed a template, because a generator that dictates the shape of an explanation gets a document that obeys the shape and teaches nobody. What the plugin decides is what is in scope and in what order; what the sentences say is the skill's alone.

Order comes from the ontology, not from a type name. The projection walks renderHint: containers open a document, expandedUnder chains give the nesting, section types become flat groups. Nothing in the package names a DDD type, so a second ontology gets documents without this code changing. Nodes attached further up their own chain are recovered in a second pass, which is what stops a rule hanging off an aggregate from silently disappearing.

Staleness falls out of the split. Project the subject again and compare against the material the document was actually written from. Because render is a function, an edit that changes nothing a reader would read leaves every form of it current, and one that does is marked on the shelf. It compares the whole projected material rather than the container node, so a change three levels down still counts.

Three render calls for what a document needs and an answer does not. showSection is a heading with a level and the nodes it covers. showCheck is a question at recall, apply or judge, with optional choices and which one is right, refused at the schema if it offers choices and names no answer. showCustom carries a kind its own plugin declares a schema for: Braid validates it and refuses an unclaimed kind, but never draws it. A plugin wanting its own shape drawn renders it in its own surface, against its own design system.

Every render route is now scoped to the runs that may call it. forRuns() existed and had been applied to none of them, so an ask run was offered show_matrix and a generate run was offered everything. A render call costs a place in the tool list and the tokens to describe it whether or not it is ever made. The three new calls reach generate runs alone.

Which nodes a kind can be written about is declared. A generator says subjects: [{ by: 'container' }], which reads the ontology's hint, or { by: 'type' }, which names a type it ships with. Omitted takes any node, which is the honest answer for a kind with no opinion rather than a silent narrowing. The doc generator takes containers; a future generator over a metric or a single aggregate declares its own rule and needs no change here.

Format is declared rather than guessed. A form says what it writes, and the surface reads that declaration instead of the file extension. That is what lets a form written later produce something else, and what makes a stale file in a format its form no longer writes disappear from the list rather than sit beside the current one under the same name.

A Documents surface in Studio. Shelved by what each document is about rather than listed as paths, since a reader thinks in subjects and not in filenames. Each subject shows the forms it has and says when the graph has moved on. Writing one picks the form first and the subject second, because the form is what decides which subjects are available. Documents are drawn by the same block renderers the Ask surface uses, so an answer and a document are one set of components.

A resolved reference shows its node's name. It used to print the id inline. A reader meeting ctx.remoteSigningTask mid-sentence has been handed the machinery rather than the thing, so the name is set in the surrounding type and the id stays a hover away. This lands on Ask and the Inbox too.

Breaking

• braid:generate-doc is gone. It becomes the reference form of the doc view kind. Nothing read its output, so no reader is broken by the move.
• GET /workspaces/:id/views, GET /workspaces/:id/views/:kind/:form/:subject and POST /workspaces/:id/views are new, along with GET /view-kinds.
• defineViewGeneratorPlugin takes subjects and format on each form.

Verified

pnpm lint clean, pnpm typecheck 16/16, and the package suites: schema 322, core 512, studio 281, sdk 29, view-generator-doc 16, server 606. Server drops a worker on a different file under turbo contention and passes 606/606 in isolation, which predates this branch. storage-kuzu fails on the native crash of #58, and no file in that package is touched here.

End to end in the browser against a real workspace: both forms written on the same container off one projection; a document read back after the run, drawn from its stored blocks; the graph edited and the shelf marking the subject stale, then current again after a rewrite; a path carrying a separator refused before a handler sees it.

Not doing

• No exam or presentation form. The mechanism does not need them to be right, and a plugin adds a form without the framework learning its name.
• No reader-assembled node set as a subject. A subject comes from a declared rule. generate-doc can only be scoped to a container node, so a curated set of nodes cannot be rendered #131 keeps the curated case.
• No output validator. The checker loop is design: workspace-configurable writing style for generated content, enforced by a validator #101, which wants it for node.description as well.
• No editing. A view that writes back is feat: bidirectional / editable View — user edits on a rendered view emit Proposals (writeback view) #65.
• No finish hook on the run. A form's last act is the last block it emits, and the service takes the sequence off the run's log. A hook letting a form say "this is the document" would be a second way to say the same thing.
• No AG-UI braid.artifact announcement. The blocks themselves already reach a client as braid.block. What is missing is the event saying a document now exists at this address, and the service assembles it after the run ends, so the skill is not what knows the address and emitting into a completed run is a shape the runner does not have. Recorded on A generated document has one form, one format, and no reader, because the axis built to carry it is never called #174 rather than rushed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PL1PNnaEeFuZA9fdDJCpMP