Decision records
This page: the architectural decisions behind the scaffolder and the app it generates: what was chosen, and what it was chosen against.
The two that explain the architecture
Worth reading even if you never change the template. Between them they answer "why is there a host layer at all" and "why is a dangerous operation shaped the way it is".
| ADR | Decision | Why it matters |
|---|---|---|
| 0010 | Consequence is gated by a server approval, not a frontend confirmation | Bind for context, gate for consequence: the rule that decides how every consequential operation is exposed, and the one mistake the template is built to make obvious |
| 0002 | An application-owned host protocol instead of @assistant-ui/react-ai-sdk | Why the Agent Host is code you can read. Everything in Host protocol follows from it |
All records
| ADR | Status | Decision | Why it matters |
|---|---|---|---|
| 0001 | accepted | Consume published @agent-surface/* and @orpc-agent/* | Generated apps depend on npm versions, not a workspace layout that cannot be scaffolded |
| 0002 | accepted | An application-owned host protocol | Avoids an ai@5 / ai@7 split-brain, and makes composition, dispatch and correlation code you can read |
| 0003 | accepted | Pin the AI SDK to the v5 line | @orpc-agent/ai-sdk peers on ai@^5; the host protocol isolates the browser from this choice |
| 0004 | accepted | A JSON file store, not SQLite | Zero native dependencies (the most common create-* install failure), and state survives restarts |
| 0005 | accepted · amended | Confirmation mode wait, executed between protocol steps | A human decision never holds a streaming response open |
| 0006 | accepted | A scripted LanguageModelV2 for the live path in CI | The whole production pipeline is tested with zero credentials |
| 0007 | accepted | Demo identity as a server-signed cookie | Roles are never read from a request body or tool input; one file is the seam for real auth |
| 0008 | superseded | A model key could be connected from the browser | The feature is gone. Kept for why a single shared process makes that dangerous |
| 0009 | accepted | The host answers server tool calls the runtime leaves open | Found with a live model, not by tests: a batched call otherwise strands the UI and malforms the model's history |
| 0010 | accepted | Consequence is gated by a server approval | A contextual binding reaches the server as a direct call, so binding a dangerous operation quietly weakens it |
| 0011 | accepted | The agent surface is compiled from source, not discovered at runtime | "What can the model do in this app" stops being a question only a running app can answer |
Adding one
Architectural decisions get an ADR in docs/adr/, numbered sequentially, with the same shape: Status · Context · Decision · Consequences. Add it to the table above and to the sidebar in docs/.vitepress/config.ts.
A decision that replaces an earlier one does not delete it: set the old record's status to superseded, and open it with what replaced it and what is still worth reading. ADR-0008 is the worked example. See Contributing.