@agent-native/core 0.79.25 → 0.79.27

package/docs/content/template-plan.mdx

@@ -23,13 +23,70 @@ commit, branch, or git diff — into a high-altitude visual code review. Both op
 the same review surface, so you annotate, comment, and hand feedback back to the
 agent the same way.
 
-```an-diagram title="Two commands, one review surface" summary="Both commands publish through the hosted Plan MCP connector into the same annotate-and-comment surface."
-{
-  "html": "<div class=\"diagram-plan\"><div class=\"diagram-col\"><div class=\"diagram-node\"><span class=\"diagram-pill accent\">/visual-plan</span><small class=\"diagram-muted\">before code — architecture, UI, refactor</small></div><div class=\"diagram-node\"><span class=\"diagram-pill\">/visual-recap</span><small class=\"diagram-muted\">after code — PR, commit, branch, diff</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\">Plan MCP connector<br><small class=\"diagram-muted\">plan.agent-native.com</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Review surface<br><small class=\"diagram-muted\">diagrams · wireframes · annotated code · comments</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-node\">Coding agent<br><small class=\"diagram-muted\">feedback handed back</small></div></div>",
-  "css": ".diagram-plan{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-plan .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-plan .diagram-arrow{font-size:22px;line-height:1}.diagram-plan .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}"
+<Diagram id="doc-block-eoqv08" title="Two commands, one review surface" summary="Both commands publish through the hosted Plan MCP connector into the same annotate-and-comment surface.">
+
+```html
+<div class="diagram-plan">
+  <div class="diagram-col">
+    <div class="diagram-node">
+      <span class="diagram-pill accent">/visual-plan</span
+      ><small class="diagram-muted"
+        >before code — architecture, UI, refactor</small
+      >
+    </div>
+    <div class="diagram-node">
+      <span class="diagram-pill">/visual-recap</span
+      ><small class="diagram-muted"
+        >after code — PR, commit, branch, diff</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    Plan MCP connector<br /><small class="diagram-muted"
+      >plan.agent-native.com</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Review surface<br /><small class="diagram-muted"
+      >diagrams · wireframes · annotated code · comments</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
+  <div class="diagram-node">
+    Coding agent<br /><small class="diagram-muted">feedback handed back</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-plan {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-plan .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-plan .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-plan .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  text-align: center;
 }
 ```
 
+</Diagram>
+
 <WireframeBlock id="doc-block-h7x805">
   <Screen
     surface="desktop"

package/docs/content/template-slides.mdx

@@ -18,13 +18,58 @@ Generate full presentation decks from a prompt, edit slides visually, and presen
 
 When you open a deck, the slide canvas, outline, notes, and filmstrip stay in one editor surface while the agent can still create, revise, and navigate slides through actions.
 
-```an-diagram title="Prompt to deck" summary="Ask for a deck and the agent streams slides in one at a time through the same actions you could call from the CLI."
-{
-  "html": "<div class=\"diagram-flow\"><div class=\"diagram-node\">Prompt<br><small class=\"diagram-muted\">\"10-slide pitch deck\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Agent</span><small class=\"diagram-muted\">picks layouts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">create-deck</div><div class=\"diagram-pill\">add-slide &#215; n</div><small class=\"diagram-muted\">parallel, streaming</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>decks (SQL)</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">Editor renders live</div></div>",
-  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:6px;align-items:center}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+<Diagram id="doc-block-1u9bt95" title="Prompt to deck" summary="Ask for a deck and the agent streams slides in one at a time through the same actions you could call from the CLI.">
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-node">
+    Prompt<br /><small class="diagram-muted">"10-slide pitch deck"</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Agent</span
+    ><small class="diagram-muted">picks layouts</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-pill">create-deck</div>
+    <div class="diagram-pill">add-slide &#215; n</div>
+    <small class="diagram-muted">parallel, streaming</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>decks (SQL)</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
+  <div class="diagram-box">Editor renders live</div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: center;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 ## What you can do with it
 
 - **Generate decks from a prompt.** "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."

package/docs/content/template-videos.mdx

@@ -18,13 +18,60 @@ A programmatic video studio for the kind of motion graphics, product demos, and
 
 When you open the studio, you'll see a list of compositions on the home screen. Click into one and you get a player on top, a timeline at the bottom, and a properties panel on the right. The agent always knows which composition you have open.
 
-```an-diagram title="Animation as data" summary="A composition is a React component; every animation reads from a track so the agent and the timeline edit the same data."
-{
-  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">Timeline<br><small class=\"diagram-muted\">drag, resize, scrub</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">\"fade in at 2s\"</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">AnimationTrack</span><small class=\"diagram-muted\">startFrame / easing / animatedProps</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>React composition<br><small class=\"diagram-muted\">Remotion &lt;Player&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">MP4 / WebM</div></div>",
-  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+<Diagram id="doc-block-akc8td" title="Animation as data" summary={"A composition is a React component; every animation reads from a track so the agent and the timeline edit the same data."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-col">
+    <div class="diagram-node">
+      Timeline<br /><small class="diagram-muted">drag, resize, scrub</small>
+    </div>
+    <div class="diagram-node">
+      Agent<br /><small class="diagram-muted">"fade in at 2s"</small>
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">AnimationTrack</span
+    ><small class="diagram-muted">startFrame / easing / animatedProps</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    React composition<br /><small class="diagram-muted"
+      >Remotion &lt;Player&gt;</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">MP4 / WebM</div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 ## What you can do with it
 
 - **Generate animations from a prompt.** "Add a title card that fades in at 2 seconds and holds until 5." The agent edits the composition.

package/docs/content/tracking.mdx

@@ -19,13 +19,63 @@ track(
 );
 ```
 
-```an-diagram title="One track() call, every provider" summary="Server and client callers hit the same registry, which fans every event out to all active providers in parallel."
-{
-  "html": "<div class=\"trk\"><div class=\"diagram-col\"><div class=\"diagram-node\">Server code<br><small class=\"diagram-muted\">actions &middot; plugins &middot; routes</small></div><div class=\"diagram-node\">Browser code<br><small class=\"diagram-muted\">POST /_agent-native/track</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Provider registry</span><small class=\"diagram-muted\">fan-out, fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">PostHog</div><div class=\"diagram-box\">Mixpanel</div><div class=\"diagram-box\">Amplitude</div><div class=\"diagram-box\">Webhook</div></div></div>",
-  "css": ".trk{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.trk .diagram-col{display:flex;flex-direction:column;gap:8px}.trk .diagram-arrow{font-size:22px;line-height:1}.trk .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+<Diagram id="doc-block-w1opwu" title="One track() call, every provider" summary="Server and client callers hit the same registry, which fans every event out to all active providers in parallel.">
+
+```html
+<div class="trk">
+  <div class="diagram-col">
+    <div class="diagram-node">
+      Server code<br /><small class="diagram-muted"
+        >actions &middot; plugins &middot; routes</small
+      >
+    </div>
+    <div class="diagram-node">
+      Browser code<br /><small class="diagram-muted"
+        >POST /_agent-native/track</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Provider registry</span
+    ><small class="diagram-muted">fan-out, fire-and-forget</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-box">PostHog</div>
+    <div class="diagram-box">Mixpanel</div>
+    <div class="diagram-box">Amplitude</div>
+    <div class="diagram-box">Webhook</div>
+  </div>
+</div>
+```
+
+```css
+.trk {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.trk .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.trk .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.trk .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
 }
 ```
 
+</Diagram>
+
 ## Built-in providers {#built-in}
 
 Set an env var and the provider auto-registers at server startup. No code changes required.

package/docs/content/using-your-agent.mdx

@@ -9,13 +9,60 @@ The defining idea behind agent-native is that the agent and the UI are **equal p
 
 There's a simple through-line. The agent **sees** what you're looking at, you **direct** it toward what you want, you can **embed** it anywhere, you can go fully **UI-light** when that's the better fit, and you can **co-edit** the same documents at the same time. Each of those is a page in this section.
 
-```an-diagram title="The day-to-day loop" summary="Five ways of working with a docked agent — each is a page in this section."
-{
-  "html": "<div class=\"diagram-loop\"><div class=\"diagram-card\"><strong>Sees</strong><small class=\"diagram-muted\">your view &amp; selection</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Direct</strong><small class=\"diagram-muted\">@-mentions &amp; voice</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embed</strong><small class=\"diagram-muted\">drop into any app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>UI-light</strong><small class=\"diagram-muted\">chat is the product</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">Co-edit</span><small class=\"diagram-muted\">live, side by side</small></div></div>",
-  "css": ".diagram-loop{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-loop .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px;flex:1}.diagram-loop .diagram-arrow{align-self:center;font-size:22px;line-height:1}"
+<Diagram id="doc-block-z4xjdy" title="The day-to-day loop" summary={"Five ways of working with a docked agent — each is a page in this section."}>
+
+```html
+<div class="diagram-loop">
+  <div class="diagram-card">
+    <strong>Sees</strong
+    ><small class="diagram-muted">your view &amp; selection</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <strong>Direct</strong
+    ><small class="diagram-muted">@-mentions &amp; voice</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <strong>Embed</strong><small class="diagram-muted">drop into any app</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <strong>UI-light</strong
+    ><small class="diagram-muted">chat is the product</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card accent-card">
+    <span class="diagram-pill accent">Co-edit</span
+    ><small class="diagram-muted">live, side by side</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-loop {
+  display: flex;
+  align-items: stretch;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-loop .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 130px;
+  flex: 1;
+}
+.diagram-loop .diagram-arrow {
+  align-self: center;
+  font-size: 22px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 ## It sees what you're looking at {#it-sees}
 
 The agent isn't blind to your screen. Open an email and it knows which thread. Select a chart and it knows which chart. Highlight a paragraph and it can act on just that range. That shared awareness is what lets you say "reply to this" or "summarize the selection" without spelling out the context every time.

package/docs/content/voice-input.mdx

@@ -19,13 +19,52 @@ The composer's voice button records audio in the browser, then picks a provider:
 
 Provider choice is stored in application state under `voice-transcription-prefs` so the user can force `"auto"` (default — picks the best available provider), `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"`, or `"browser"` in the sidebar settings.
 
-```an-diagram title="Voice transcription provider fallback" summary="The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."
-{
-  "html": "<div class=\"diagram-voice\"><div class=\"diagram-node\">Mic button<br><small class=\"diagram-muted\">records webm/opus</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill accent\">1 &middot; Builder Gemini</div><small class=\"diagram-muted\">default when Builder connected</small><div class=\"diagram-pill\">2 &middot; BYOK cloud</div><small class=\"diagram-muted\">Gemini &middot; Groq &middot; OpenAI Whisper</small></div><div class=\"diagram-arrow diagram-warn\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box diagram-warn\" data-rough>3 &middot; Browser Web Speech<br><small class=\"diagram-muted\">fallback on 400 &middot; streams live</small></div></div>",
-  "css": ".diagram-voice{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-voice .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-voice .diagram-arrow{font-size:22px;line-height:1}"
+<Diagram id="doc-block-1q55wvc" title="Voice transcription provider fallback" summary={"The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."}>
+
+```html
+<div class="diagram-voice">
+  <div class="diagram-node">
+    Mic button<br /><small class="diagram-muted">records webm/opus</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card col">
+    <div class="diagram-pill accent">1 &middot; Builder Gemini</div>
+    <small class="diagram-muted">default when Builder connected</small>
+    <div class="diagram-pill">2 &middot; BYOK cloud</div>
+    <small class="diagram-muted"
+      >Gemini &middot; Groq &middot; OpenAI Whisper</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-warn" aria-hidden="true">&darr;</div>
+  <div class="diagram-box diagram-warn" data-rough>
+    3 &middot; Browser Web Speech<br /><small class="diagram-muted"
+      >fallback on 400 &middot; streams live</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-voice {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-voice .col {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px;
+}
+.diagram-voice .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
 }
 ```
 
+</Diagram>
+
 The route is **same-origin only** — cross-site POSTs are rejected so an attacker can't burn transcription credits from an external page.
 
 ## Enabling Providers {#enabling-providers}

package/docs/content/what-is-agent-native.mdx

@@ -50,13 +50,58 @@ Three things change when you reach rung 3:
 
 That's rung 3. That's agent-native.
 
-```an-diagram title="The Ladder Principle" summary="Most teams stop at rung 1 or 2. Agent-native is rung 3 — a real app and a real agent over one shared action surface."
-{
-  "html": "<div class=\"diagram-ladder\"><div class=\"diagram-card rung rung-3\"><span class=\"diagram-pill accent\">Rung 3 · agent-native</span><strong>Agent + UI as equal partners</strong><small class=\"diagram-muted\">One action surface. Every agent tool is also a button; every button runs the same logic the agent uses.</small></div><div class=\"diagram-card rung rung-2\"><span class=\"diagram-pill\">Rung 2</span><strong>A chat with tools</strong><small class=\"diagram-muted\">The agent can act — but it is still just a chat window. No dashboards, lists, or shortcuts.</small></div><div class=\"diagram-card rung rung-1\"><span class=\"diagram-pill warn\">Rung 1</span><strong>A single LLM call</strong><small class=\"diagram-muted\">Prompt in, string out. Impressive in a demo; breaks the moment reality gets messy.</small></div></div>",
-  "css": ".diagram-ladder{display:flex;flex-direction:column;gap:14px}.diagram-ladder .rung{display:flex;flex-direction:column;gap:6px;padding:16px 18px}.diagram-ladder .rung-2{margin-inline-end:48px}.diagram-ladder .rung-1{margin-inline-end:96px}"
+<Diagram id="doc-block-19ku4da" title="The Ladder Principle" summary={"Most teams stop at rung 1 or 2. Agent-native is rung 3 — a real app and a real agent over one shared action surface."}>
+
+```html
+<div class="diagram-ladder">
+  <div class="diagram-card rung rung-3">
+    <span class="diagram-pill accent">Rung 3 · agent-native</span
+    ><strong>Agent + UI as equal partners</strong
+    ><small class="diagram-muted"
+      >One action surface. Every agent tool is also a button; every button runs
+      the same logic the agent uses.</small
+    >
+  </div>
+  <div class="diagram-card rung rung-2">
+    <span class="diagram-pill">Rung 2</span><strong>A chat with tools</strong
+    ><small class="diagram-muted"
+      >The agent can act — but it is still just a chat window. No dashboards,
+      lists, or shortcuts.</small
+    >
+  </div>
+  <div class="diagram-card rung rung-1">
+    <span class="diagram-pill warn">Rung 1</span
+    ><strong>A single LLM call</strong
+    ><small class="diagram-muted"
+      >Prompt in, string out. Impressive in a demo; breaks the moment reality
+      gets messy.</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-ladder {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+.diagram-ladder .rung {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 16px 18px;
+}
+.diagram-ladder .rung-2 {
+  margin-inline-end: 48px;
+}
+.diagram-ladder .rung-1 {
+  margin-inline-end: 96px;
 }
 ```
 
+</Diagram>
+
 See [Key Concepts — Protocols](/docs/key-concepts#protocols) for how all of this hangs off the same action definition.
 
 ## Why every agent needs a UI {#why-every-agent-needs-a-ui}
@@ -97,13 +142,148 @@ a projection of that resulting state. The agent is not guessing from the DOM or
 mutating private component state directly; it interacts through the same typed
 action layer the UI uses.
 
-```an-diagram title="Shared state machine" summary="The user and agent both submit typed actions. Actions validate, authorize, apply the SQL-backed state update, then broadcast/render the new state."
-{
-  "html": "<div class=\"diagram-machine\"><div class=\"diagram-card surface user\" data-rough><span class=\"diagram-pill\">User surface</span><div class=\"diagram-node diagram-accent\">Open Design tab<br><small class=\"diagram-muted\">navigate.panel</small></div><div class=\"diagram-node\">Add text block<br><small class=\"diagram-muted\">plan.addBlock</small></div><div class=\"diagram-node\">Remove summary<br><small class=\"diagram-muted\">plan.removeBlock</small></div></div><div class=\"core\"><div class=\"lane-row\"><span class=\"diagram-pill\">intent -&gt; action</span><span class=\"diagram-pill\">action &lt;- intent</span></div><div class=\"diagram-panel action\" data-rough><span class=\"diagram-pill accent\">Typed action</span><strong>navigate</strong><small class=\"diagram-muted\">actor: user or agent &middot; input: panel = Design</small><div class=\"steps\"><span class=\"diagram-pill\">validate</span><span class=\"diagram-pill\">authorize</span><span class=\"diagram-pill\">apply update</span></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel state\" data-rough><span class=\"diagram-pill ok\">Shared state</span><strong>SQL + app state</strong><code>{ panel: \"Design\", lastActor: \"user\" }</code><small class=\"diagram-muted\">broadcast over live sync</small></div><div class=\"lane-row bottom\"><span class=\"diagram-pill ok\">state -&gt; UI</span><span class=\"diagram-pill ok\">context -&gt; agent</span></div></div><div class=\"diagram-card surface agent\" data-rough><span class=\"diagram-pill\">Agent surface</span><div class=\"diagram-node\">Add diagram block<br><small class=\"diagram-muted\">plan.addBlock</small></div><div class=\"diagram-node\">Remove stale block<br><small class=\"diagram-muted\">plan.removeBlock</small></div><div class=\"diagram-node diagram-accent\">Focus review view<br><small class=\"diagram-muted\">navigate.review</small></div></div></div>",
-  "css": ".diagram-machine{display:grid;grid-template-columns:minmax(150px,1fr) minmax(300px,1.45fr) minmax(150px,1fr);gap:12px;align-items:stretch}.diagram-machine .surface{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-machine .surface .diagram-pill{align-self:flex-start}.diagram-machine .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 12px}.diagram-machine .core{display:flex;flex-direction:column;justify-content:center;gap:8px;min-width:0}.diagram-machine .lane-row{display:flex;justify-content:space-between;gap:8px;flex-wrap:wrap}.diagram-machine .lane-row.bottom{justify-content:center}.diagram-machine .diagram-arrow{font-size:22px;line-height:1;text-align:center}.diagram-machine .diagram-panel{display:flex;flex-direction:column;gap:8px;min-width:0;padding:14px}.diagram-machine .steps{display:flex;gap:6px;flex-wrap:wrap}.diagram-machine code{align-self:flex-start;max-width:100%;white-space:normal}@media(max-width:760px){.diagram-machine{grid-template-columns:1fr}.diagram-machine .lane-row{justify-content:flex-start}.diagram-machine .lane-row.bottom{justify-content:flex-start}}"
+<Diagram id="doc-block-1n18itc" title="Shared state machine" summary={"The user and agent both submit typed actions. Actions validate, authorize, apply the SQL-backed state update, then broadcast/render the new state."}>
+
+```html
+<div class="diagram-machine">
+  <div class="diagram-card surface user" data-rough>
+    <span class="diagram-pill">User surface</span>
+    <div class="diagram-node diagram-accent">
+      Open Design tab<br /><small class="diagram-muted">navigate.panel</small>
+    </div>
+    <div class="diagram-node">
+      Add text block<br /><small class="diagram-muted">plan.addBlock</small>
+    </div>
+    <div class="diagram-node">
+      Remove summary<br /><small class="diagram-muted">plan.removeBlock</small>
+    </div>
+  </div>
+  <div class="core">
+    <div class="lane-row">
+      <span class="diagram-pill">intent -&gt; action</span
+      ><span class="diagram-pill">action &lt;- intent</span>
+    </div>
+    <div class="diagram-panel action" data-rough>
+      <span class="diagram-pill accent">Typed action</span
+      ><strong>navigate</strong
+      ><small class="diagram-muted"
+        >actor: user or agent &middot; input: panel = Design</small
+      >
+      <div class="steps">
+        <span class="diagram-pill">validate</span
+        ><span class="diagram-pill">authorize</span
+        ><span class="diagram-pill">apply update</span>
+      </div>
+    </div>
+    <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+    <div class="diagram-panel state" data-rough>
+      <span class="diagram-pill ok">Shared state</span
+      ><strong>SQL + app state</strong
+      ><code>{ panel: "Design", lastActor: "user" }</code
+      ><small class="diagram-muted">broadcast over live sync</small>
+    </div>
+    <div class="lane-row bottom">
+      <span class="diagram-pill ok">state -&gt; UI</span
+      ><span class="diagram-pill ok">context -&gt; agent</span>
+    </div>
+  </div>
+  <div class="diagram-card surface agent" data-rough>
+    <span class="diagram-pill">Agent surface</span>
+    <div class="diagram-node">
+      Add diagram block<br /><small class="diagram-muted">plan.addBlock</small>
+    </div>
+    <div class="diagram-node">
+      Remove stale block<br /><small class="diagram-muted"
+        >plan.removeBlock</small
+      >
+    </div>
+    <div class="diagram-node diagram-accent">
+      Focus review view<br /><small class="diagram-muted"
+        >navigate.review</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-machine {
+  display: grid;
+  grid-template-columns: minmax(150px, 1fr) minmax(300px, 1.45fr) minmax(
+      150px,
+      1fr
+    );
+  gap: 12px;
+  align-items: stretch;
+}
+.diagram-machine .surface {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 14px;
+}
+.diagram-machine .surface .diagram-pill {
+  align-self: flex-start;
+}
+.diagram-machine .diagram-node {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 10px 12px;
+}
+.diagram-machine .core {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 8px;
+  min-width: 0;
+}
+.diagram-machine .lane-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+.diagram-machine .lane-row.bottom {
+  justify-content: center;
+}
+.diagram-machine .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+  text-align: center;
+}
+.diagram-machine .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-width: 0;
+  padding: 14px;
+}
+.diagram-machine .steps {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+.diagram-machine code {
+  align-self: flex-start;
+  max-width: 100%;
+  white-space: normal;
+}
+@media (max-width: 760px) {
+  .diagram-machine {
+    grid-template-columns: 1fr;
+  }
+  .diagram-machine .lane-row {
+    justify-content: flex-start;
+  }
+  .diagram-machine .lane-row.bottom {
+    justify-content: flex-start;
+  }
 }
 ```
 
+</Diagram>
+
 When the agent creates a draft email, it appears in the UI. When you click "Send," the agent knows it was sent. There's no separate "agent world" and "UI world" — it's one system. See [Key Concepts](/docs/key-concepts) for the architecture that makes this work.
 
 ## Customization usually reserved for power tools {#workspace-customization}