zidane 7.0.14 → 7.0.16

package/docs/EXTENSIONS.md

@@ -1,6 +1,6 @@
 # Zidane Extensions
 
-User-authored TypeScript / JavaScript modules that plug into a running zidane host without touching the upstream codebase. Drop `index.ts` into `.zidane/extensions/<name>/`, ship a small `setup(ctx)` function, and contribute tools, hooks, MCP servers, skills, themes, agent profiles, keybindings, runtime transforms, storage/session state, context-panel sections, and more.
+User-authored TypeScript / JavaScript modules that plug into a running zidane host without touching the upstream codebase. Drop `index.ts` into `.zidane/extensions/<name>/`, ship a `setup(ctx)` function, and contribute tools, hooks, MCP servers, skills, themes, agent profiles, keybindings, runtime transforms, storage/session state, context-panel sections, and more.
 
 ```ts
 // .zidane/extensions/hello/index.ts
@@ -16,39 +16,34 @@ export default defineExtension({
 })
 ```
 
-Restart the TUI — that's it. The extension shows up in `Settings → Extensions` for on/off toggling and its keybindings (if any) in `Settings → Keybindings`.
+Restart the TUI. The extension shows up in `Settings → Extensions` for on/off toggling and its keybindings (if any) in `Settings → Keybindings`.
 
-## Why
-
-The existing surfaces (`mcps.json`, `SKILL.md`, `keybindings.json`) cover static configuration. Extensions cover the parts you can only express as code: a custom tool, an observability hook, a streaming UI panel, a slash-command provider hitting an internal API. Anyone can vibe-code one and try it without forking zidane.
+Contents: [Discovery](#discovery) · [defineExtension API](#the-defineextension-api) · [The ctx surface](#the-ctx-surface) · [How it boots](#how-it-boots) · [Enabling / disabling](#enabling--disabling) · [Installing from GitHub / npm](#installing-from-github--npm) · [Collisions](#collisions--precedence) · [Hooks: parent vs subagent](#hooks-parent-vs-subagent) · [Authoring patterns](#authoring-patterns) · [Settings UI](#settings-ui) · [Limitations](#limitations--gotchas-v1) · [SDK surface](#sdk-surface) · [Preset vs extensions](#preset-vs-extensions) · [File layout](#file-layout-reference)
 
 ## Discovery
 
-Search order — first-found per `name` wins (same convention as skills + `mcps.json`):
+First-found per `name` wins (same convention as skills + `mcps.json`):
 
 1. `{project}/.agents/extensions/<name>/`
 2. `{project}/.zidane/extensions/<name>/`
 3. `~/.agents/extensions/<name>/`
 4. `~/.<prefix>/extensions/<name>/` (e.g. `~/.zidane/extensions/<name>/`)
 
-`{project}` is the git root walked up from `cwd` (or `cwd` itself when not in a repo). Each `<name>/` directory must contain one of (probed in order): `index.ts`, `index.tsx`, `index.mjs`, `index.js`.
-
-Bun loads `.ts` / `.tsx` natively — both under `bun run` and in `bun build --compile` binaries. No transpiler dependency.
+`{project}` is the git root walked up from `cwd` (or `cwd` itself outside a repo). Each `<name>/` directory must contain one of (probed in order): `index.ts`, `index.tsx`, `index.mjs`, `index.js`. Bun loads `.ts`/`.tsx` natively, in `bun run` and in `bun build --compile` binaries.
 
-Optional manifest metadata can live in either `<name>/extension.json` or the `zidane` field of `<name>/package.json`:
+Optional manifest metadata lives in `<name>/extension.json` or the `zidane` field of `<name>/package.json`:
 
 ```json
 {
   "apiVersion": 1,
   "name": "hello",
   "displayName": "Hello Tools",
-  "description": "Logs every tool call",
   "capabilities": ["hooks", "storage"],
   "permissions": ["storage:write"]
 }
 ```
 
-The loader rejects unsupported `apiVersion` values and rejects manifest/module name mismatches so the persisted extension identity stays stable.
+The loader rejects unsupported `apiVersion` values and manifest/module name mismatches, so the persisted extension identity stays stable.
 
 ## The `defineExtension` API
 
@@ -58,26 +53,25 @@ import type { ExtensionDefinition } from 'zidane'
 interface ExtensionDefinition {
   name: string                                       // stable, kebab-case-ish
   apiVersion?: 1                                     // omitted means v1
-  displayName?: string                               // optional UI label
+  displayName?: string
   permissions?: readonly ExtensionPermission[]       // descriptive, not a sandbox
   capabilities?: readonly ExtensionCapability[]      // shown before setup runs
-  version?: string                                   // surfaced in Settings → Extensions
-  description?: string                               // ditto
+  version?: string
+  description?: string
   setup: (ctx: ExtensionContext) => void | Promise<void>
   teardown?: () => void | Promise<void>              // reserved (no hot-reload yet)
 }
 ```
 
-`setup(ctx)` runs once per registry build — boot, `/reload`, or a cwd change. All registration goes through `ctx.*` — registration calls after `setup` resolves are dropped with a `logger.warn` for the author (runtime affordances like `ctx.tui.*` and `submitPrompt` stay live for the extension's whole lifetime). The framework awaits async `setup` before considering the extension "loaded", so a slow registration blocks only that extension (others run in parallel).
+`setup(ctx)` runs once per registry build — boot, `/reload`, or a cwd change. Registration calls after `setup` resolves are dropped with a `logger.warn` (runtime affordances like `ctx.tui.*` and `submitPrompt` stay live for the extension's whole lifetime). Async `setup` is awaited before the extension is "loaded"; extensions load in parallel, so one slow one only blocks itself.
 
-Throws inside `setup` are caught and surfaced on the extension's row in `Settings → Extensions` as an error message. The rest of boot continues — one bad extension can't brick the TUI.
+Throws inside `setup` are caught and surfaced on the extension's row in `Settings → Extensions`. The rest of boot continues.
 
 ### Zero-import alternative
 
-Compiled `zidane-tui` binaries don't expose their bundled `node_modules/zidane` to dynamic imports outside the bundle. For binaries, drop the `import` entirely — the loader accepts a plain object too:
+Compiled `zidane-tui` binaries don't expose their bundled `node_modules/zidane` to dynamic imports outside the bundle. For binaries, drop the `import` — the loader accepts a plain object:
 
 ```ts
-// .zidane/extensions/hello/index.ts — no runtime imports
 export default {
   name: 'hello',
   setup(ctx) {
@@ -86,16 +80,14 @@ export default {
 }
 ```
 
-For type-checking your `ctx` argument, use a **type-only** import (these get erased at runtime and don't need a resolver):
+For type-checking `ctx`, use a **type-only** import (erased at runtime, no resolver needed):
 
 ```ts
 import type { ExtensionContext } from 'zidane'
 
 export default {
   name: 'hello',
-  setup(ctx: ExtensionContext) {
-    ctx.registerHook('tool:after', e => ctx.logger.info('ran', e))
-  },
+  setup(ctx: ExtensionContext) { /* … */ },
 }
 ```
 
@@ -111,66 +103,44 @@ Three namespaces:
 
 ### Renderer-agnostic
 
-```ts
-ctx.name           // your extension name
-ctx.version        // optional
-ctx.dir            // absolute path to the extension folder (undefined for inline)
-ctx.scope          // 'project' | 'user' | 'inline' | 'builtin'
-ctx.logger         // Logger scoped to `extension:<name>`
-ctx.paths          // cwd/projectRoot/dataDir/cacheDir/configDir/stateDir
-ctx.storage.path(scope, ...segments)
-ctx.session.get(key) / set(key, value) / delete(key)
-ctx.config.get(key)
-
-ctx.registerTool(name, toolDef)
-ctx.registerHook(event, handler)
-ctx.registerMcpServer(serverConfig)
-ctx.registerSkill(skillConfig)
-ctx.registerCompletionProvider(provider)
-ctx.registerInlineAutocompleteProvider(provider)
-ctx.registerCommand(command)
-ctx.registerTheme(theme)
-ctx.registerAgent(profile)
-ctx.registerProvider(descriptor)
-ctx.registerSystemPromptFragment(text)
-ctx.registerContextBreakdownSection(contributor)
-ctx.registerContextPanelSection(section)
-ctx.registerToolResultMetadata(registration)
-ctx.registerRunTransform(transform)
-ctx.registerBehaviorTransform(transform)
-ctx.registerProviderMiddleware(middleware)
-ctx.registerToolCatalogTransform(transform)
-ctx.registerMcpConfigTransform(transform)
-ctx.registerSkillPolicy(policy)
-ctx.registerConfigCategory(category)
-ctx.registerConfigItem(categoryId?, item)
-```
-
 | API | Use it for | Notes |
 |---|---|---|
-| `registerTool(name, ToolDef)` | Custom agent tools | Profile tools win on name collision; built-in interaction tools (`ask_user`, `present_plan`) always win. |
-| `registerHook(event, handler)` | Observability / policy on `AgentHooks` | Fires on the **parent** agent only — for subagent activity subscribe to `child:tool:before` etc. |
-| `registerMcpServer(McpServerConfig)` | Programmatic MCP server (no `mcps.json` edit) | Discovered `mcps.json` wins on `name` collision. |
-| `registerSkill(SkillConfig)` | Programmatic `defineSkill()` injection | Force-included in the user's `enabledSkills` allowlist so an existing allowlist doesn't silently hide the extension's skill. |
-| `registerCompletionProvider(provider)` | New `/` `@` `!` triggers in the prompt | One-character trigger; collides with built-ins (`/` `@` `#`) → ignored. |
-| `registerInlineAutocompleteProvider({ id, suggest })` | Ghost-text autocomplete in the prompt (no trigger — runs on every keystroke pause) | `suggest(ctx)` returns a suffix string, a candidate list (user rotates with up/down, Tab accepts), or null. Gated by the user's `inlineAutocomplete` setting (default off). Built-in path provider runs first; first non-empty answer wins; dedupe by `id`, first registration wins; 150 ms per-provider deadline. |
-| `registerCommand(Command)` | A `/<name>` workflow — ordered handler steps (or a bare `run`) that `emit` local output (full markdown, or collapsed diff-colorable `detail` blocks), call `ctx.runAgent` for interactive sub-runs, `ctx.generateData` for silent schema-pinned JSON (no turns, no transcript; takes a zod v4 schema — result type inferred — or a plain JSON Schema object; optional `model` pins a catalog model), or `ctx.spawnAgents?` for parallel ISOLATED child agents (own context windows, full tool set, per-task `model` pinning — rendered like `spawn`-tool children); `ctx.appendContext?` persists a compact model-visible context note; `ctx.session?` exposes a read-only live view of the surrounding session (`id`/`turns`/`runs`/`metadata`) and `ctx.interaction?` offers user interaction (`confirm` yes/no, `askUser` forms — selects support `multi: true` — `presentPlan` approval) — the optional surfaces are host-dependent, so guard for bare hosts | `emit` output is display-only (persisted, never sent to the model); `appendContext` is the sanctioned model-visible escape hatch. Names dedupe first-registration-wins. Extensions extend `/` here rather than via a raw completion provider. |
-| `registerTheme(Theme)` | New `Settings → Theme` option | The picker's option list folds extension themes in at render time; built-in theme ids (`default`, `catppuccin-mocha`, …) shadow extension ids on collision. |
-| `registerAgent(AgentProfile)` | A complete agent (preset = tools + system + behavior + hooks + mcpServers + skills) added to the registry. Appears in the `shift+tab` cycle alongside Build / Plan. | Built-in profiles (`build`, `plan`) win on id collision; host-supplied profiles win over extensions too. |
-| `registerProvider(ProviderDescriptor)` | New LLM provider in the auth + model pickers | Host-supplied providers (incl. `BUILTIN_PROVIDERS`) win on `key` collision. A `models` list on the descriptor REPLACES the built-in registry, so the picker shows only your provider's models. For an OAuth provider, `await registerCustomOAuthProvider(flow)` in `setup` — zidane's own OAuth registry (`src/providers/oauth-registry.ts`; pi-ai removed its global one in 0.80.8) resolves the flow by id on EVERY token resolve, not just on refresh. A gateway speaking a built-in wire format reuses its factory: `anthropic({ baseURL, authMode: 'bearer', credentialSource: { providerId: '<key>' }, capabilities })` gets bearer auth, credentials under your own key (with the shared lazy refresh + cross-process lock), and no Claude Code persona. `extensions/bolt` is a complete example: device-flow login + Anthropic-compatible proxy. |
-| `registerSystemPromptFragment(text)` | Append a paragraph to every system prompt | Joined with `\n\n` separators, appended to `ctx.system` via a `system:transform` hook re-attached on every agent rebuild (works for every profile — Build / Plan / host-supplied). |
-| `registerContextBreakdownSection(fn)` | Existing low-level context panel contributor | May return a section or array of sections; async contributors are supported. |
-| `registerContextPanelSection(section)` | Richer context panel section with `id`, `title`, static rows, and/or async `load` | Normalized into the same context panel model. `registerContextBreakdownSection` remains supported. |
-| `registerToolResultMetadata(registration)` | Interpret namespaced metadata attached to tool results | Can project metadata entries into context-panel rows. |
-| `registerRunTransform(fn)` | Synchronously rewrite `agent.run()` options before precondition checks | Applied in extension order. Throws are logged under `ZIDANE_DEBUG` and ignored. |
-| `registerBehaviorTransform(fn)` | Synchronously rewrite resolved behavior (`maxTurns`, retry, budgets, etc.) | Run-level `behavior` options are re-applied after transforms so explicit caller choices win. |
-| `registerProviderMiddleware(fn)` | Wrap provider instances for tracing, fallback, metrics, or policy | Runs when a provider factory is called; returning `undefined` is treated as pass-through. |
-| `registerToolCatalogTransform(fn)` | Hide, rename, or replace tools before disclosure/execution | Runs for both pre-run context estimates and actual runs. |
-| `registerMcpConfigTransform(fn)` | Programmatically rewrite MCP server configs before connection | Discovered/user configs are merged first, then transforms run in extension order. |
-| `registerSkillPolicy(policy)` | Auto-activate a skill based on run context | `policy.when` may be async; failures are fail-open with debug logging. |
-| `registerConfigCategory` / `registerConfigItem` | Typed settings in Settings → Extensions | Items can declare `scope`, `requiresRestart`, and `onChange` metadata; `ctx.config.get` reads current values default-first. A `string` item can set `secret: true` — the row renders masked (last 4 kept) and the editor opens empty, so a token isn't shoulder-surfable. Presentation only: the value still lives in the settings bag, so it's for service tokens, not for anything belonging in the credential store. |
-
-`ctx.session` is extension-scoped, JSON-only, byte-bounded state attached to the active `Session`. It is available during agent runs and isolated by extension name. `ctx.storage.path()` returns a path under the host's data/cache/config/project root, clamped to `<scope>/extensions/<extension-name>/...` so `..` segments cannot escape the extension's storage directory.
+| `name` / `version` / `dir` / `scope` / `logger` / `paths` / `signal` | Identity, a `Logger` scoped `extension:<name>`, cwd/projectRoot/dataDir/cacheDir/configDir/stateDir, and an `AbortSignal` that flips when setup times out or the registry disposes | `dir` is `undefined` for inline extensions |
+| `storage.path(scope, ...segments)` | A path under the host's data/cache/config/project root | Clamped to `<scope>/extensions/<name>/...`; `..` segments can't escape it |
+| `session.get(key)` / `set(key, value)` / `delete(key)` | Extension-scoped, JSON-only, byte-bounded state on the active `Session` | Isolated per extension name; live during agent runs |
+| `config.get(key)` | Read this extension's own config values, default-first | Safe during `setup` (returns defaults) and in hooks/tools (live values) |
+| `disabled` | `true` when this build only declares config schema for a disabled extension | Gate side-effecting setup work on `!ctx.disabled` |
+| `registerTool(name, ToolDef)` | Custom agent tools | Profile tools win on name collision; built-in interaction tools (`ask_user`, `present_plan`) always win |
+| `registerHook(event, handler)` | Observability / policy on `AgentHooks` | Fires on the **parent** agent only — subscribe to `child:tool:before` etc. for subagents |
+| `registerMcpServer(McpServerConfig)` | Programmatic MCP server (no `mcps.json` edit) | Discovered `mcps.json` wins on `name` collision |
+| `registerSkill(SkillConfig)` | Programmatic `defineSkill()` injection | Force-included in the user's `enabledSkills` allowlist |
+| `loadAgentPlugin(dir \| options)` | Load an Agent Plugin (agent-plugins.org) — skills + MCP servers in one call | Must be awaited inside `setup`; malformed manifests come back as diagnostics on the result, never a thrown error |
+| `registerCompletionProvider(provider)` | New `/` `@` `!` triggers in the prompt | One-character trigger; collides with built-ins (`/` `@` `#`) → ignored |
+| `registerInlineAutocompleteProvider({ id, suggest })` | Ghost-text ahead of the cursor, no trigger | Gated by the user's `inlineAutocomplete` setting (off by default); first non-empty answer wins, 150 ms deadline |
+| `registerCommand(Command)` | A `/<name>` workflow | Names dedupe first-registration-wins; see [Authoring patterns](#a-custom-slash-command) |
+| `registerTheme(Theme)` | New `Settings → Theme` option | Built-in theme ids shadow extension ids on collision |
+| `registerAgent(AgentProfile)` | A complete agent profile in the `shift+tab` cycle | Built-in ids (`build`, `plan`) win on collision |
+| `registerSubagent(ExtensionSubagentDef)` | A named overlay the model selects via `spawn`'s `subagent_type` | Adds beat the host base on name collision |
+| `registerSubagentOverride(name, fn)` | Edit an existing subagent (host- or extension-provided) by name | Applied after adds, so overrides win over both; `fn` returning `undefined` deletes the entry |
+| `registerProvider(ProviderDescriptor)` | New LLM provider in the auth + model pickers | Host-supplied providers win on `key` collision; a `models` list REPLACES the built-in registry for that provider |
+| `registerSystemPromptFragment(text)` | Append a paragraph to every system prompt | Joined with `\n\n`, re-attached on every agent rebuild |
+| `registerContextBreakdownSection(fn)` | Existing low-level context panel contributor | May return one section or an array; async is supported |
+| `registerContextPanelSection(section)` | Richer context panel section (`id`, `title`, rows, optional async `load`) | Normalized into the same model as above |
+| `registerToolResultMetadata(registration)` | Interpret namespaced metadata attached to tool results | Can project entries into context-panel rows |
+| `registerArtifactKind({ kind, label, detect?, validateMeta?, render?, resolve? })` | Give meaning to a session artifact kind | Global namespace, first registration wins. See [ARTIFACTS.md](./ARTIFACTS.md) |
+| `artifacts.list(query)` / `artifacts.find(kind, uri)` | Read the artifact store | Late-bound like `sessions`: `[]` when detached. See [ARTIFACTS.md](./ARTIFACTS.md) |
+| `registerRunTransform(fn)` | Rewrite `agent.run()` options before precondition checks | Synchronous, applied in extension order; throws logged under `ZIDANE_DEBUG` and ignored |
+| `registerBehaviorTransform(fn)` | Rewrite resolved behavior (`maxTurns`, retry, budgets) | Run-level `behavior` options re-applied after, so explicit caller choices win |
+| `registerProviderMiddleware(fn)` | Wrap provider instances (tracing, fallback, metrics, policy) | Runs per provider-factory call; `undefined` return = pass-through |
+| `registerToolCatalogTransform(fn)` | Hide, rename, or replace tools before disclosure/execution | Runs for both context estimates and actual runs |
+| `registerMcpConfigTransform(fn)` | Rewrite MCP server configs before connection | Runs after discovered/user configs are merged |
+| `registerSkillPolicy(policy)` | Auto-activate a skill based on run context | `policy.when` may be async; failures are fail-open |
+| `registerToolPolicy({ tools?, decide })` | Gate tool calls pre-execution: allow / `{ block: reason }` / `{ patch: input }` | Patches are re-validated against the tool's schema; earlier verdicts (built-in guards, approval flow) win |
+| `registerToolResultTransform(fn)` | Chained middleware over finished tool results | Rides `tool:transform`; byte budgets still apply after |
+| `registerContextTransform(fn)` | Rewrite wire messages per provider call | Sugar over `registerProviderMiddleware` |
+| `registerPromptTransform(fn)` | Transform or consume a submitted prompt | Runs after `/` command interception, before skill-reference resolution |
+| `registerConfigCategory(category)` / `registerConfigItem(categoryId?, item)` | Typed settings in `Settings → Extensions` | See [Settings UI](#settings-ui) |
+| `bus?.emit(payload, opts)` / `bus?.onMessage(fn)` | Private cross-window message channel | Present only when the definition declares the `'ipc'` permission; payloads are JSON ≤ 64 KiB |
 
 ### TUI-specific
 
@@ -178,33 +148,34 @@ ctx.registerConfigItem(categoryId?, item)
 ctx.tui.registerKeybinding({
   id: 'my-ext.openPanel',           // globally unique, namespace by extension
   default: 'ctrl+shift+j',          // empty string = unbound by default
-  label: 'Jokes',                   // shown in Settings → Keybindings
+  label: 'Jokes',
   description: 'Open the joke panel',
   onTrigger: dispatch => dispatch.openModal('jokes'),
 })
 
 ctx.tui.registerFooterHint({ key: '^J', label: 'jokes' })
-
-ctx.tui.registerModal({
-  id: 'jokes',
-  node: <JokesPanel />,
+ctx.tui.registerModal({ id: 'jokes', node: <JokesPanel /> })
+
+// HUD — fire-and-forget, callable for the extension's whole lifetime.
+// No-ops on hosts without a UI.
+ctx.tui.notify('Indexed 42 files', { tone: 'info' })             // one-shot transcript line
+ctx.tui.setStatus('indexing… 42/117', { loader: true })          // dim line at the transcript tail
+ctx.tui.setStatus('✓ indexed', { timeout: 3000 })                // transient — auto-clears
+ctx.tui.setBanner(['review pending: 3 files'], { timeout: 10_000 }) // block above the prompt
+ctx.tui.setStatus(null)                                          // clear (also wiped on disposal)
+
+// Artifact detail pane in the /artifacts modal (row rendering is on the
+// renderer-agnostic registerArtifactKind({ render })):
+ctx.tui.registerArtifactRenderer({
+  kind: 'my-ext.deployment',
+  renderDetail: artifact => <DeploymentStatus url={artifact.uri} meta={artifact.meta} />,
 })
 
-// HUD — fire-and-forget, callable for the extension's whole lifetime
-// (setup, hooks, commands, timers). No-ops on hosts without a UI.
-ctx.tui.notify('Indexed 42 files', { tone: 'info' })            // one-shot transcript line
-ctx.tui.setStatus('indexing… 42/117', { loader: true })          // single dim line at the transcript tail, with working glyph
-ctx.tui.setStatus('✓ indexed', { timeout: 3000 })                // transient — auto-clears after 3s
-ctx.tui.setBanner(['review pending: 3 files'], { timeout: 10_000 }) // block above the prompt, next to the todo indicator
-ctx.tui.setStatus(null)                                          // clear (also wiped automatically on disposal)
-
 // Custom transcript rendering — view-layer only, fallback-mandatory:
 ctx.tui.registerToolRenderer({
   tools: ['shell'],                                // omit = offer for every tool
   render: ({ text }) =>
-    looksLikeTestOutput(text)
-      ? <TestSummaryTable output={text} />         // replaces the default ┃ block
-      : null,                                      // null = fall through to default
+    looksLikeTestOutput(text) ? <TestSummaryTable output={text} /> : null, // null = default view
 })
 
 ctx.tui.registerRenderer('commit-graph', data =>   // auto-namespaced: '<ext>/commit-graph'
@@ -217,54 +188,11 @@ ctx.appendNote([{
 // command emit() takes the same block shape (full '<ext>/<id>' required there)
 ```
 
-**The rendering invariant — data stays data.** Nothing a renderer paints is
-ever persisted: tool renderers are views over the tool turns you already
-have (zero schema change), and `custom` blocks persist `{ renderer-id,
-JSON-safe data, fallback markdown }` — the fallback IS the persisted output,
-so a pre-custom host (or an old zidane) renders these turns natively.
-Resolution happens at render time against the live filtered registry:
-disable the extension in Settings and rows fall back instantly; `/reload`
-re-skins old rows with new renderer code; a throwing renderer is
-error-bounded per row (fallback + dim notice — the transcript survives).
-V1 boundary: components are display-only (no focus/keyboard inside
-transcript rows) and TUI-scoped like modals — the fallback is the
-headless/GUI story. Tool renderers re-skin result rows, they don't
-resurrect them: `showToolResults: false` hides custom views too — output
-that must stay visible unconditionally belongs in a `custom` block.
-
-**Async data (fetch in a renderer):** `render` itself is synchronous by
-design — but the node it returns mounts as a real React subtree, so async
-work happens the standard React way, inside your component:
-
-```tsx
-function PrStatus({ pr }: { pr: number }) {
-  const [state, setState] = useState<'loading' | { title: string }>('loading')
-  useEffect(() => {
-    let cancelled = false
-    fetch(`https://api.github.com/repos/o/r/pulls/${pr}`)
-      .then(r => r.json())
-      .then((data) => {
-        if (!cancelled)
-          setState({ title: data.title })
-      })
-      .catch(() => {}) // keep the loading state; the row must never throw upward
-    return () => {
-      cancelled = true
-    }
-  }, [pr])
-  return <text>{state === 'loading' ? '⏳ loading…' : `#${pr} ${state.title}`}</text>
-}
-
-ctx.tui.registerRenderer('pr-status', data => <PrStatus pr={(data as { pr: number }).pr} />)
-```
+**Rendering invariant — data stays data.** Nothing a renderer paints is persisted: tool renderers are views over tool turns you already have; `custom` blocks persist `{ renderer-id, JSON-safe data, fallback markdown }` — the fallback IS the persisted output, so a pre-custom host renders natively. Disabling the extension falls rows back instantly; `/reload` re-skins them; a throwing renderer is error-bounded per row. Components are display-only (no focus/keyboard inside transcript rows); `showToolResults: false` hides custom views too.
 
-You get loading states, re-render on arrival, and cancellation for free —
-an async `render` signature would re-implement all of that (per-row promise
-caches, race handling) for no added capability, so it's deliberately not
-offered.
+**Async data:** `render` is synchronous, but the node it returns mounts as a real React subtree — `fetch`/`useEffect` inside your component like any React code.
 
-**Caching + viewport gating — the hooks** (from `zidane/tui`, importable in
-extensions thanks to host-module mapping):
+**Caching + viewport gating** (`useRowVisible`, `useSessionState` from `zidane/tui`):
 
 ```tsx
 import { useRowVisible, useSessionState } from 'zidane/tui'
@@ -273,112 +201,58 @@ function PrStatus({ pr }: { pr: number }) {
   const visible = useRowVisible()                       // false until scrolled in (latched)
   const [data, setData] = useSessionState<Pr | null>('pr', null)
   useEffect(() => {
-    if (!visible || data) return                        // off-screen OR cached → no fetch
-    fetchPr(pr).then(setData)                           // setData persists into the session
+    if (!visible || data) return
+    fetchPr(pr).then(setData)
   }, [visible, data, pr])
   return <text>{data ? data.title : visible ? '⏳' : '·'}</text>
 }
 ```
 
-- `useSessionState(id, initial)` — durable per-ROW state, keyed
-  `renderer:<localId>:<turnId>:<id>` in the session's extension-state bag
-  (your own namespace — inspect or clear it via `ctx.session`). Reload the
-  session and the row rehydrates instead of refetching. Values are
-  JSON-safe by type; live rows share the persisted turn's id, so keys agree
-  live and after reload.
-- `useRowVisible(margin?)` — `true` once the row has entered the viewport
-  (±margin rows of warm-up), LATCHED — mechanically, not just semantically:
-  once visible, the row UNSUBSCRIBES from the tracker, so scrolling it out
-  and back in causes zero re-renders and zero effect re-runs (test-pinned).
-  Re-run-on-revisit belongs to your own state keys. Reports `true`
-  immediately when no visibility tracker exists (headless-ish hosts) — work
-  is never gated behind a tracker that isn't there. One shared ~200ms poll
-  for the whole transcript, no per-row timers, and scrolling doesn't
-  re-render the transcript either (subscription store, not React state).
+- `useSessionState(id, initial)` — durable per-ROW state, keyed `renderer:<localId>:<turnId>:<id>` in the session's extension-state bag. Reload and the row rehydrates instead of refetching.
+- `useRowVisible(margin?)` — `true` once the row enters the viewport, LATCHED: once visible it unsubscribes from the tracker, so scrolling out and back causes zero re-renders. `true` immediately on hosts without a visibility tracker.
 - Both throw outside an extension-rendered row.
 
-**Module identity — ambient imports just work.** The TUI maps `react`,
-`react/jsx-runtime`, and the `@opentui/*` packages to its OWN live module
-instances before any extension loads (a Bun virtual-module plugin — see
-`extensions/host-modules.ts`), so `import { useState } from 'react'` in an
-extension always gets the reconciler's copy. Without this, bare imports
-resolve from the extension's directory — landing on nothing, or on a second
-react whose hooks throw "Invalid hook call". Don't bundle or depend on your
-own `react`/`@opentui/*`; import them bare and let the host supply them.
-
-The loader itself maps `zidane` and `zidane/providers` the same way (renderer-neutral,
-so headless / ACP hosts get it too) — `import { anthropic, registerCustomOAuthProvider }
-from 'zidane'` in an extension resolves to the host's LIVE modules, which matters for
-anything stateful: the provider factories, the credential store, and pi-ai's OAuth
-registry must be the host's copies, not a second instance loaded from your directory.
+**Module identity.** The TUI maps `react`, `react/jsx-runtime`, and `@opentui/*` to its own live module instances before any extension loads (a Bun virtual-module plugin, see `src/extensions/host-modules.ts`), so `import { useState } from 'react'` gets the reconciler's copy — don't bundle your own. The loader maps `zidane` / `zidane/providers` the same way (renderer-neutral, headless/ACP hosts included), which matters for stateful singletons: provider factories, the credential store, the OAuth registry.
 
 ```tsx
-
 // Prompt + interception surfaces
 ctx.submitPrompt('run the tests', { delivery: 'followUp' })   // as-if-typed; 'auto' | 'steer' | 'followUp'
-ctx.registerToolPolicy({                          // gate tool calls pre-execution
-  tools: ['shell'],
-  decide: call => String(call.input.command).includes('rm -rf')
-    ? { block: 'dangerous' }                      // or { patch: input } — re-validated against the tool schema
-    : 'allow',
-})
-ctx.registerToolResultTransform(({ tool, result }) =>          // chained result middleware
-  tool === 'shell' ? { result: redact(result) } : undefined)
-ctx.registerContextTransform(messages =>                       // rewrite wire messages per provider call
-  messages.filter(keep))
-ctx.registerPromptTransform(prompt =>                          // transform/consume submitted prompts
-  prompt.startsWith('!q ') ? `Be brief: ${prompt.slice(3)}` : undefined)
-// Not a parallel pipeline: `registerToolPolicy` registers into the SAME
-// `tool:gate` hook bucket as the agent's built-in guards, and
-// `registerToolResultTransform` rides `tool:transform` — one mechanism,
-// one composition order. These are ergonomic (typed verdicts, schema
-// re-validation) layers over hooks, not a second interception system.
+
+// Not a parallel pipeline: registerToolPolicy rides the SAME `tool:gate`
+// hook bucket as the agent's built-in guards, and registerToolResultTransform
+// rides `tool:transform` — one mechanism, one composition order.
 
 // Late-bound host controls (null/false/empty until the host attaches)
 ctx.runtime.model()                               // active model id
-ctx.runtime.models()                              // { provider: { key, name }, model: ModelInfo }[] across credentialed providers
+ctx.runtime.models()                              // { provider: { key, name }, model: ModelInfo }[]
 ctx.runtime.setThinking('high')
 await ctx.sessions.list()                         // { id, title?, updatedAt? }[]
 await ctx.sessions.switch(id)                     // or ctx.sessions.create()
 ctx.appendNote([{ text: '### Indexed\n42 files' }])            // durable display-only transcript note
 
 // Shell + files through the SESSION'S execution context — work happens
-// wherever the agent's tools run (host, docker, remote sandbox), with the
-// same transport output caps and containment. Hand-rolled child_process
-// always runs on the HOST and silently targets the wrong filesystem under
-// sandboxed contexts — ctx.workspace is the sandbox-correct way.
+// wherever the agent's tools run (host, docker, remote sandbox). Hand-rolled
+// child_process always runs on the HOST and silently targets the wrong
+// filesystem under sandboxed contexts.
 const { stdout, exitCode } = await ctx.workspace.exec('git status --porcelain')
 const pkg = await ctx.workspace.readFile('package.json')
 await ctx.workspace.writeFile('.cache/report.md', report)
 const size = await ctx.workspace.fileSize('big.log')   // probe before whole-reads
-// Detached (no live session) ⇒ these REJECT rather than silently no-op
-// (spawn failures reject with their real cause). The guard is
-// side-effect-free — it never spawns a container just to answer:
-if (await ctx.workspace.available()) { /* … */ }
-// Calling before the session's first run spawns the execution handle on
-// demand — same lifecycle seam (and `execution:ready` hook) as agent.run().
+if (await ctx.workspace.available()) { /* … */ }  // detached ⇒ calls above REJECT, not no-op
 ```
 
-`/reload` (built-in command) hot-reloads the registry: re-discover, re-import
-each extension's module graph fresh (on-disk edits apply live), re-run `setup`,
-swap — the outgoing instance's teardowns run and its HUD paint is wiped
-(generation-guarded, so the fresh instance's paint survives the swap ordering).
-Dispose also retires the instance's HUD writer: late status/banner writes from
-teardown closures or leaked timers are inert (`notify` stays live for farewell
-lines). Toggling an extension off in Settings hides its paint and mutes its
-notifications immediately; toggling back on restores them.
+`/reload` (built-in command) hot-reloads the registry: re-discover, re-import each extension's module graph fresh, re-run `setup`, swap — outgoing teardowns run and the outgoing HUD paint is wiped. Toggling an extension off in Settings hides its paint and mutes notifications immediately; toggling back on restores them.
 
-`onTrigger` receives an `ExtensionKeybindingDispatchContext` — `{ extensionName, openModal(id), closeModal() }`. Heavy work should hop to its own microtask; the dispatcher is synchronous.
+`onTrigger` receives `{ extensionName, openModal(id), closeModal() }`. Heavy work should hop to its own microtask; the dispatcher is synchronous.
 
-The dispatcher iterates **built-ins first, then extensions** — so an extension declaring `default: 'ctrl+o'` collides with `openSettings` and never fires. The loader emits a `logger.warn` on detect-time collisions (built-in + cross-extension). The framework also **reserves `escape` and `ctrl+c`** — extensions can't bind those chords (the registration is dropped with a warning), so the user always has a working "abort / back" key.
+The dispatcher iterates **built-ins first, then extensions** — an extension declaring `default: 'ctrl+o'` collides with `openSettings` and never fires (logged at detect time). The framework **reserves `escape` and `ctrl+c`** — extensions can't bind those chords (registration dropped with a warning).
 
-Users can rebind any extension keybinding from `~/.zidane/keybindings.json` by its `id`:
+Users rebind any extension keybinding from `~/.zidane/keybindings.json` by its `id`:
 
 ```jsonc
-// ~/.zidane/keybindings.json
 {
   "openSettings": "ctrl+o",
-  "my-ext.openPanel": "ctrl+shift+j"   // ← extension binding override
+  "my-ext.openPanel": "ctrl+shift+j"
 }
 ```
 
@@ -390,7 +264,7 @@ Extension bindings appear in `Settings → Keybindings` under a trailing **Exten
 ctx.gui.registerPanel({ id, label, render })
 ```
 
-`ctx.gui.registerPanel` calls land in the registry, but GUI panels are not rendered yet. GUI parity that is wired today includes extension discovery/settings, extension summaries, completion providers, and completion submit hooks (`resolveReferences` / `onSubmit`) through IPC.
+Calls land in the registry, but GUI panels aren't rendered yet. GUI parity wired today: extension discovery/settings, extension summaries, completion providers, and completion submit hooks (`resolveReferences` / `onSubmit`) through IPC.
 
 ## How it boots
 
@@ -412,9 +286,9 @@ flowchart TD
 
 Key invariants:
 
-1. **State first.** `runTui` reads `state.json` before discovery so the registry knows the enable allowlist as it builds. The allowlist gates **contributions, not execution**: a disabled-but-trusted extension is still imported and its `setup()` still runs — but only to declare its config schema (so its settings are browsable before you enable it). It runs with `ctx.disabled === true` and with the runtime bridges (`tui.*`, `submitPrompt`, `runtime`, `sessions`, `workspace`) withheld as inert no-ops, and it classifies as `inactive` so none of its behavioral contributions reach the active surface. Extensions that do side-effecting setup work (network probes, spawning processes, warming caches) must gate it on `!ctx.disabled`.
+1. **State first.** `runTui` reads `state.json` before discovery so the registry knows the enable allowlist as it builds. The allowlist gates **contributions, not execution**: a disabled-but-trusted extension is still imported and its `setup()` still runs — but only to declare its config schema. It runs with `ctx.disabled === true` and the runtime bridges (`tui.*`, `submitPrompt`, `runtime`, `sessions`, `workspace`) withheld as inert no-ops. Gate side-effecting setup work on `!ctx.disabled`.
 2. **Setup-then-merge.** Each extension's contributions are captured per-extension on `LoadedExtension.contributions`. The host can re-merge any subset via `mergeContributions(active, inactive)` to flip toggles without re-running `setup`.
-3. **Sync `resolveConfig`.** Setup can be async; `resolveConfig` can't. The host pre-builds the registry, then passes it via `ChatOptions.extensionRegistry`. `runTui` does this internally; SDK / GUI hosts do the same:
+3. **Sync `resolveConfig`.** Setup can be async; `resolveConfig` can't. The host pre-builds the registry, then passes it via `ChatOptions.extensionRegistry`:
 
    ```ts
    import {
@@ -431,24 +305,19 @@ Key invariants:
 
 ## Enabling / disabling
 
-Each extension shows up in `Settings → Extensions` with a checkbox. Toggling writes to `Settings.enabledExtensions` (semantics mirror `enabledSkills` / `enabledMcps`):
+Each extension shows up in `Settings → Extensions` with a checkbox. Toggling writes `Settings.enabledExtensions` (semantics mirror `enabledSkills` / `enabledMcps`):
 
-- `undefined` (fresh install) — **every** discovered extension runs.
+- `undefined` (fresh install) — every discovered extension runs.
 - `[]` — none run.
 - `[names]` — explicit allowlist.
 
-Disabled extensions:
-- Still run `setup()` at boot with `ctx.disabled === true` — schema-declaration only. Runtime bridges are withheld (`ctx.tui.*` / `ctx.submitPrompt` / `ctx.runtime` are inert), so an inactive extension can't paint status, inject prompts, or touch the session. Author-level side effects must be gated on `!ctx.disabled`.
-- Land on `registry.inactive` so the toggle UI still lists them, and expose their **config schema** (categories + items) so their settings render before you enable them.
-- Don't contribute tools / hooks / mcps / skills / themes / agents / providers / keybindings / footer hints / modals.
+Disabled extensions still run `setup()` at boot with `ctx.disabled === true` (schema-declaration only, runtime bridges inert), land on `registry.inactive`, and expose their config schema so settings render before you enable them. They don't contribute tools/hooks/mcps/skills/themes/agents/providers/keybindings/footer hints/modals.
 
-**Toggle = live filter; `/reload` = full re-apply.** Toggling live-filters tools / hooks / mcpServers / skills / completion providers / keybindings / footer hints (re-applied at the next session activation) and hides the extension's HUD paint + notifications immediately — but `setup()` isn't re-run and agent profiles + providers + themes stay visible in their pickers. Run `/reload` (or restart) to fully apply a toggle: the registry rebuilds against the current allowlist, so disabled extensions re-run `setup()` in schema-only mode (`ctx.disabled`, no behavioral contributions) and their picker entries disappear. Picking an extension-contributed profile after toggling its extension off — without reloading — activates a half-functional state: the profile's own preset works, but the extension's hooks / tools are suppressed.
+**Toggle = live filter; `/reload` = full re-apply.** Toggling live-filters tools/hooks/mcpServers/skills/completion providers/keybindings/footer hints and hides HUD paint immediately — but `setup()` isn't re-run and agent profiles/providers/themes stay visible in their pickers until `/reload` (or restart) rebuilds the registry against the current allowlist. Picking an extension-contributed profile after toggling its extension off — without reloading — activates a half-functional state: the profile's preset works, but the extension's hooks/tools are suppressed.
 
 ## Installing from GitHub / npm
 
-`Settings → Extensions → ctrl+g` fetches, validates, and installs an extension
-into the roots discovery already scans — then hot-reloads the registry, so
-it's live without a restart. Type a source into the inline input:
+`Settings → Extensions → ctrl+g` fetches, validates, and installs an extension into the roots discovery already scans, then hot-reloads the registry — live, no restart. Type a source into the inline input:
 
 ```
 owner/repo                        # GitHub, single-extension repo
@@ -458,41 +327,22 @@ owner/repo#main:packages/ext      # search a subdirectory (monorepos); pasted tr
 @scope/pkg@1.2.0                  # npm (exact versions or dist-tags; ranges are not resolved)
 ```
 
-…then pick the scope with ←/→: **global** (`~/.zidane/extensions/` — always
-trusted, the default) or **this project** (`<project>/.zidane/extensions/`,
-which still requires project-extension trust to load — the panel warns when
-the project isn't trusted). Progress streams into the panel's status line.
-Bare `a/b` is GitHub (npm slash-names are always `@scope/…`), anything else
-is npm.
+…then pick the scope with ←/→: **global** (`~/.zidane/extensions/`, always trusted) or **this project** (`<project>/.zidane/extensions/`, requires project-extension trust to load). Bare `a/b` is GitHub (npm slash-names are always `@scope/…`); anything else is npm.
 
 **Recognized package shapes** (same for both targets):
 
 - a root `index.{ts,tsx,mjs,js}` — single-extension repo/package
-- `extensions/<name>/index.*` directories — a collection; append the name to
-  the source input (the error notice lists the candidates when you don't)
-- for monorepos, `:path/to/dir` (GitHub only) re-roots the search — both
-  shapes above then apply to that directory; a pasted
-  `github.com/owner/repo/tree/<ref>/<path>` URL means the same thing
-
-**Pipeline guarantees** (`installExtensionFromSpec` in the SDK — the GUI calls
-the identical core):
-
-- The module is imported and validated (definition shape, apiVersion,
-  folder-safe name, manifest agreement) **in a staging dir before anything
-  touches your roots** — a failure installs nothing. This executes the
-  extension's top-level code once; your explicit install request is the consent.
-- The target folder is named from the *validated* `definition.name`, so
-  discovery's folder-name invariant holds by construction.
-- Dependencies install with the first of bun/npm/pnpm/yarn on PATH, **never
-  running lifecycle scripts** (bun's default; the others get `--ignore-scripts`).
-- An existing install of the same name is refused unless you confirm the
-  overwrite. A `.install.json` provenance file (raw spec, resolved
-  version/ref, exact commit SHA for git installs, scope, selected candidate,
-  timestamp) is written — it's what powers updates.
-
-**Bundled extensions** — this repo ships installable packages under
-`extensions/`, which double as real-world examples of the pipeline (note the
-subdir syntax — paste either source into the `ctrl+g` input):
+- `extensions/<name>/index.*` directories — a collection; append the name to the source input
+- for monorepos, `:path/to/dir` (GitHub only) re-roots the search
+
+**Pipeline guarantees** (`installExtensionFromSpec` — the GUI calls the identical core):
+
+- The module is imported and validated (definition shape, apiVersion, folder-safe name, manifest agreement) **in a staging dir before anything touches your roots** — a failure installs nothing. This runs the extension's top-level code once; your explicit install request is the consent.
+- The target folder is named from the *validated* `definition.name`.
+- Dependencies install with the first of bun/npm/pnpm/yarn on PATH, **never running lifecycle scripts**.
+- An existing install of the same name is refused unless you confirm the overwrite. A `.install.json` provenance file (raw spec, resolved version/ref, commit SHA, scope, timestamp) is written — it powers updates.
+
+**Bundled extensions** — this repo ships installable packages under `extensions/` as real-world examples (paste either source into the `ctrl+g` input):
 
 ```
 Tahul/zidane:extensions/git-flow    # /commit — agent-written commit messages + one-tap push
@@ -500,51 +350,31 @@ Tahul/zidane:extensions/headroom    # compress large tool outputs via a local He
 Tahul/zidane:extensions/pxpipe      # image tool outputs in-process + optional pxpipe proxy routing
 ```
 
-All mirror the packaging conventions to copy for
-your own extensions (`package.json` with `zidane-extension` keyword, entry
-`index.ts`, `zidane` as a peer).
-
-**Update / remove** live on the focused row of the same tab:
-
-- `ctrl+u` — update: first a cheap no-op probe — `git ls-remote` compares the
-  recorded commit SHA (npm: one registry GET re-resolves the version); an
-  unchanged remote reports "already up to date" without fetching or reloading
-  anything. (The probe compares the remote against the *recorded* install,
-  not your local files — to restore a hand-edited install, remove and
-  reinstall.) Otherwise it re-resolves the recorded spec (`owner/repo` follows
-  the branch, bare `pkg` follows `latest`; pinned refs/versions stay pinned)
-  and replaces the install **in place** (same root, even a
-  `.agents/extensions` one; an upstream rename removes the superseded
-  folder), reporting the commit delta (`abc1234 → def5678`). Hand-authored
-  extensions have no provenance — nothing to update from.
-- `ctrl+x` (twice — arm, then confirm; cursor moves disarm) — remove: deletes
-  the extension's directory and drops it from the enable allowlist. Works on
-  hand-authored extensions too; a containment guard refuses any directory
-  that isn't a direct child of a recognized extensions root.
-
-Install, update, and remove all finish with the `/reload` hot-swap, and all
-are thin wrappers over `installExtensionFromSpec` /
-`updateInstalledExtension` / `removeInstalledExtension` in the SDK (the GUI
-calls the same functions).
+All mirror the packaging conventions to copy for your own extensions (`package.json` with `zidane-extension` keyword, entry `index.ts`, `zidane` as a peer).
 
-## Collisions + precedence
+**Update / remove** on the focused row of the same tab:
+
+- `ctrl+u` — update: a cheap no-op probe (`git ls-remote` / one npm registry GET) compares the recorded install; unchanged reports "already up to date". Otherwise re-resolves the recorded spec (`owner/repo` follows the branch, bare `pkg` follows `latest`; pinned refs/versions stay pinned) and replaces the install in place, reporting the commit delta. Hand-authored extensions have no provenance to update from.
+- `ctrl+x` (twice — arm, then confirm) — remove: deletes the extension's directory and drops it from the enable allowlist. A containment guard refuses any directory that isn't a direct child of a recognized extensions root.
 
-When extension contributions overlap with host or built-in surfaces:
+Install, update, and remove all finish with the `/reload` hot-swap.
+
+## Collisions + precedence
 
 | Surface | Collision rule |
 |---|---|
 | Tools | Profile tools win, then later extensions (load order). Interaction tools (`ask_user`, `present_plan`) always win. |
-| Themes | Built-in theme ids win. Cross-extension collisions: last write wins. |
+| Themes | Built-in theme ids win. Cross-extension: last write wins. |
 | Agent profiles | Host-supplied profiles win on `id`. |
 | Providers | Host-supplied providers (incl. `BUILTIN_PROVIDERS`) win on `key`. |
 | MCP servers | Discovered `mcps.json` wins on `name`. |
 | Keybindings | Built-in actions match first; collisions logged at boot. |
 | Completion providers | First registered trigger wins per character. |
 | Skills | Concatenated catalog; per-name first registration wins. |
-| Runtime transforms / middleware | Applied in extension load order after registry merge; failures are logged only when `ZIDANE_DEBUG` is set. |
-| Storage/session keys | Namespaced by extension name; unsafe keys (`__proto__`, `prototype`, `constructor`) are rejected or ignored. |
+| Runtime transforms / middleware | Applied in extension load order after registry merge; failures logged only under `ZIDANE_DEBUG`. |
+| Storage/session keys | Namespaced by extension name; unsafe keys (`__proto__`, `prototype`, `constructor`) rejected or ignored. |
 
-The mental model: **extensions extend, they don't shadow.** The few cases where extensions *could* shadow (other extensions' tools, themes, keybinding ids) resolve by load order with a warning when relevant.
+The mental model: **extensions extend, they don't shadow.** The few cases where extensions *could* shadow (other extensions' tools, themes, keybinding ids) resolve by load order with a warning.
 
 ## Hooks: parent vs subagent
 
@@ -553,8 +383,8 @@ The mental model: **extensions extend, they don't shadow.** The few cases where
 To observe subagent activity, subscribe to the `child:*` mirror events (`child:tool:before`, `child:tool:after`, `child:stream:text`, …). They fire on the parent's hook bus with `{ childId, depth }` stamped on the context.
 
 ```ts
-ctx.registerHook('tool:after', (e) => log('parent tool', e))
-ctx.registerHook('child:tool:after', (e) => log('subagent tool', e, 'depth=', e.depth))
+ctx.registerHook('tool:after', e => log('parent tool', e))
+ctx.registerHook('child:tool:after', e => log('subagent tool', e, 'depth=', e.depth))
 ```
 
 ## Authoring patterns
@@ -571,10 +401,7 @@ export default defineExtension({
     ctx.registerTool('jq_query', {
       name: 'jq_query',
       description: 'Run a jq filter against the given JSON.',
-      schema: z.object({
-        json: z.string(),
-        filter: z.string(),
-      }),
+      schema: z.object({ json: z.string(), filter: z.string() }),
       async execute({ json, filter }) {
         // ... shell out, call a JS jq, whatever
         return JSON.stringify(result, null, 2)
@@ -587,28 +414,19 @@ export default defineExtension({
 ### A theme
 
 ```ts
-import { defineExtension } from 'zidane'
-
-export default defineExtension({
-  name: 'sunset',
-  setup(ctx) {
-    ctx.registerTheme({
-      id: 'sunset',
-      label: 'Sunset',
-      colors: { brand: '#ff6b35', accent: '#f7c59f', /* … */ },
-      select: { /* … */ },
-      surfaces: { /* … */ },
-      syntax: { /* … */ },
-    })
-  },
+ctx.registerTheme({
+  id: 'sunset',
+  label: 'Sunset',
+  colors: { brand: '#ff6b35', accent: '#f7c59f' /* … */ },
+  select: { /* … */ },
+  surfaces: { /* … */ },
+  syntax: { /* … */ },
 })
 ```
 
-After restart: `Settings → Theme → Sunset`.
-
 ### A complete agent profile
 
-`registerAgent` adds a profile to the same registry the built-in Build / Plan ride. The `shift+tab` keybinding (`cycleAgent`) cycles through every registered profile in registration order — extension profiles show up in the rotation automatically, no other UI wiring needed.
+`registerAgent` adds a profile to the same registry Build/Plan ride. `shift+tab` (`cycleAgent`) cycles every registered profile in registration order.
 
 ```ts
 import { defineExtension, definePreset } from 'zidane'
@@ -620,7 +438,7 @@ export default defineExtension({
     ctx.registerAgent({
       id: 'reviewer',
       label: 'Reviewer',
-      description: 'Read-only code reviewer — explores + critiques, never writes.',
+      description: 'Read-only code reviewer.',
       accent: 'model',
       preset: definePreset({
         name: 'reviewer',
@@ -633,149 +451,96 @@ export default defineExtension({
 })
 ```
 
-After restart: `shift+tab` cycles `build → plan → reviewer → build → ...`. The footer agent badge ("Build" / "Plan" / "Reviewer") flips in lockstep.
-
-Notes:
-
-- Profile ids must be unique across the merged registry. Built-in ids (`build`, `plan`) shadow extension ids on collision — you can't override the built-ins from an extension.
-- The `preset` field is a full `Preset` (same shape `composePresets` accepts): `tools`, `system`, `behavior`, `hooks`, `mcpServers`, `skills`. Anything you'd put in a host-side `agents` registry works here too.
-- The picker modal (`AgentPickerModal`) is exported from `zidane/tui` for embedders who want an explicit picker UI — not wired by default, since the cycle is enough for most setups.
+Profile ids must be unique; built-in ids (`build`, `plan`) shadow extension ids on collision. `preset` is a full `Preset` — `tools`, `system`, `behavior`, `hooks`, `mcpServers`, `skills`. The picker modal (`AgentPickerModal`) is exported from `zidane/tui` for embedders who want an explicit UI.
 
 ### An MCP server
 
 ```ts
-export default defineExtension({
-  name: 'linear-bundled',
-  setup(ctx) {
-    ctx.registerMcpServer({
-      name: 'linear',
-      transport: 'stdio',
-      command: 'npx',
-      args: ['-y', 'linear-mcp'],
-    })
-  },
+ctx.registerMcpServer({
+  name: 'linear',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', 'linear-mcp'],
 })
 ```
 
-Same effect as adding the entry to `mcps.json`, but the extension carries it alongside its docs / version / setup logic.
-
-### Observability + logging
-
-```ts
-export default defineExtension({
-  name: 'audit-log',
-  setup(ctx) {
-    const file = openAuditLog()
-    ctx.registerHook('tool:after', ({ name, callId }) => file.write(`${name}:${callId}\n`))
-    ctx.registerHook('child:tool:after', ({ name, callId, depth }) => file.write(`[d${depth}] ${name}:${callId}\n`))
-    ctx.registerHook('agent:done', ({ runId }) => file.flush())
-  },
-})
-```
+Same effect as an `mcps.json` entry, but carried alongside the extension's docs/version/setup logic.
 
 ### A custom slash command
 
 ```ts
-export default defineExtension({
-  name: 'jokes',
-  setup(ctx) {
-    ctx.registerCompletionProvider({
-      id: 'jokes',
-      trigger: '!',
-      label: 'Jokes',
-      async suggest(query) {
-        const items = await fetchJokes(query)
-        return items.map(j => ({
-          id: j.id,
-          label: j.title,
-          description: j.summary,
-          insertText: `!${j.title} `,
-          data: j,
-        }))
-      },
-      parseReferences(text) {
-        // walk text, find every "!title" occurrence, return spans
-        return []
-      },
-    })
+ctx.registerCommand({
+  name: 'deploy',
+  run: async (c) => {
+    const rows = await ctx.artifacts.list({ scope: 'project', kind: 'coolify.deployment' })
+    c.emit({ text: rows.map(r => `- [${r.label}](${r.uri})`).join('\n') || '_none_' })
   },
 })
 ```
 
-`resolveReferences` and `onSubmit` are optional submit hooks. The TUI and GUI both call them before dispatching a prompt, using the shared `resolveCompletionSubmit` core helper:
+`emit` output is display-only (persisted, never sent to the model). A command may also call `ctx.runAgent` for interactive sub-runs, `ctx.generateData` for silent schema-pinned JSON, `ctx.spawnAgents?` for parallel isolated child agents, and `ctx.appendContext?` to persist a model-visible note — the optional surfaces are host-dependent, so guard for bare hosts.
+
+### A completion provider
 
 ```ts
 ctx.registerCompletionProvider({
-  id: 'tickets',
-  trigger: '#',
-  label: 'Tickets',
-  async suggest(query, _ctx, signal) {
-    return searchTickets(query, { signal })
-  },
-  parseReferences(text) {
-    return findTicketRefs(text)
-  },
-  async resolveReferences(refs, _ctx, signal) {
-    return Promise.all(refs.map(ref => hydrateTicketRef(ref, { signal })))
-  },
-  async onSubmit({ references }) {
-    await rememberSubmittedTickets(references)
+  id: 'jokes',
+  trigger: '!',
+  label: 'Jokes',
+  async suggest(query) {
+    const items = await fetchJokes(query)
+    return items.map(j => ({ id: j.id, label: j.title, insertText: `!${j.title} `, data: j }))
   },
+  parseReferences(text) { return [] }, // walk text, find every "!title" occurrence
 })
 ```
 
+`resolveReferences` and `onSubmit` are optional submit hooks the TUI/GUI call before dispatching a prompt.
+
 ### Runtime transforms + session state
 
 ```ts
-export default defineExtension({
-  name: 'cost-guard',
-  setup(ctx) {
-    ctx.registerRunTransform((options) => ({
-      ...options,
-      behavior: {
-        ...options.behavior,
-        maxCostUsd: Math.min(options.behavior?.maxCostUsd ?? 5, 1),
-      },
-    }))
-
-    ctx.registerProviderMiddleware((provider) => ({
-      ...provider,
-      stream: async (options, callbacks) => {
-        await ctx.session.set('lastModel', options.model)
-        return provider.stream(options, callbacks)
-      },
-    }))
+ctx.registerRunTransform(options => ({
+  ...options,
+  behavior: { ...options.behavior, maxCostUsd: Math.min(options.behavior?.maxCostUsd ?? 5, 1) },
+}))
+
+ctx.registerProviderMiddleware(provider => ({
+  ...provider,
+  stream: async (options, callbacks) => {
+    await ctx.session.set('lastModel', options.model)
+    return provider.stream(options, callbacks)
   },
-})
+}))
 ```
 
-Transforms are synchronous and fail-open. Use them for cheap composition decisions: budget caps, tool catalog shaping, provider wrappers, MCP config rewrites, or skill activation policy. Put I/O in provider middleware, hooks, completion submit hooks, or tools.
+Transforms are synchronous and fail-open — use them for cheap composition decisions (budget caps, tool catalog shaping, provider wrappers). Put I/O in provider middleware, hooks, or tools.
+
+### Session artifacts
 
-### Context panel sections + tool metadata
+An extension gives meaning to an artifact `kind` — a durable, typed pointer to something a session produced (PR, branch, commit, file, deployment). Full model, storage, and surfaces: [ARTIFACTS.md](./ARTIFACTS.md).
 
 ```ts
-ctx.registerContextPanelSection({
-  id: 'build-info',
-  title: 'Build Info',
-  rows: [
-    { label: 'Branch', value: currentBranch },
-    { label: 'CI', value: ciUrl },
-  ],
-})
+export default defineExtension({
+  name: 'coolify',
+  setup(ctx) {
+    ctx.registerArtifactKind({
+      kind: 'coolify.deployment',          // namespace by extension; [\w.:-]+
+      label: 'Deployment',
+      detect: ({ tool, result, isError }) => {
+        if (isError || tool !== 'mcp_Coolify_deploy') return
+        const m = /deployment ([\w-]+)/.exec(String(result))
+        return m && { uri: `https://coolify.example/deployments/${m[1]}`, label: m[1], meta: { id: m[1], state: 'queued' } }
+      },
+      render: a => ({ title: a.label, href: a.uri, status: String((a.meta as { state?: string })?.state ?? '') }),
+      resolve: async a => ({ meta: { ...(a.meta as object), state: await fetchState(a) } }), // lazy, on view
+    })
 
-ctx.registerToolResultMetadata({
-  namespace: 'acme.trace',
-  contextRows({ entries }) {
-    return entries.map(({ value }) => ({
-      label: 'Trace',
-      value: String(value),
-    }))
+    ctx.tui.registerArtifactRenderer({ kind: 'coolify.deployment', renderDetail: a => <DeployLogs id={a.uri} /> })
   },
 })
 ```
 
-Tool-result metadata is namespaced. The registry does not validate `schema` yet; it records the declaration so hosts and future tooling can project or validate metadata consistently.
-
 ### A keybinding + modal
 
 ```tsx
@@ -783,11 +548,7 @@ import { defineExtension } from 'zidane'
 import { Modal } from 'zidane/tui'
 
 function JokesPanel() {
-  return (
-    <Modal title="jokes">
-      <text>haha</text>
-    </Modal>
-  )
+  return <Modal title="jokes"><text>haha</text></Modal>
 }
 
 export default defineExtension({
@@ -806,57 +567,21 @@ export default defineExtension({
 })
 ```
 
-`node` also accepts a **loader thunk** — `() => import('./panel')` — invoked only when the modal first opens. The imported module `export default`s the node and zidane unwraps `{ default }` for you. This keeps the panel's UI (and the `react/jsx-runtime` edge JSX injects) off the import graph of headless / embedded hosts that load the extension but never render a TUI modal. See [Headless-safe UI](#headless-safe-ui).
-
-```ts
-// index.ts — no UI imports, no JSX (keeps the entry renderer-neutral)
-import { defineExtension } from 'zidane'
-
-export default defineExtension({
-  name: 'jokes-ui',
-  setup(ctx) {
-    ctx.tui.registerModal({ id: 'jokes-panel', node: () => import('./panel') })
-    ctx.tui.registerKeybinding({
-      id: 'jokes-ui.open',
-      default: 'ctrl+shift+j',
-      label: 'Jokes',
-      description: 'Open the jokes panel',
-      onTrigger: dispatch => dispatch.openModal('jokes-panel'),
-    })
-  },
-})
-```
-
-```tsx
-// panel.tsx — UI + JSX live here, imported lazily on first open
-import { Modal } from 'zidane/tui'
-
-export default (
-  <Modal title="jokes">
-    <text>haha</text>
-  </Modal>
-)
-```
+`node` also accepts a **loader thunk** — `() => import('./panel')` — invoked only when the modal first opens, keeping the panel's UI (and the `react/jsx-runtime` import JSX injects) off the import graph of headless hosts. See [Headless-safe UI](#headless-safe-ui).
 
 Notes:
 
-- **Wrap your panel in `<Modal>` from `zidane/tui`.** It centers the panel, paints the bordered chrome, and installs the `esc` → close handler. The framework's `ModalRoot` also closes on `esc` as a baseline so a raw `<box>` still dismisses, but `<Modal>` is the canonical pattern.
-- **Fullscreen panels**: pass `fullscreen` (plus `horizontalMargin={0} verticalMargin={0}` for edge-to-edge) and the panel fills the terminal and tracks resizes live — the same layout the built-in Settings workbench uses. Sizing knobs (`maxWidth` / `minWidth` / `maxHeight`) are ignored under `fullscreen`; give overflowing content its own `<scrollbox>`.
-
-  ```tsx
-  <Modal title="dashboard" fullscreen horizontalMargin={0} verticalMargin={0}>
-    <scrollbox style={{ flexGrow: 1 }}>{/* … */}</scrollbox>
-  </Modal>
-  ```
-- Set `<Modal disableEscape>` if the panel needs to swallow `esc` itself (e.g. cancel a pending confirmation). The framework's baseline esc handler honors the opt-out automatically.
-- TUI components need `@opentui/react` resolvable at runtime. For the bundled binary, ship the modal as a small renderless registration and rely on `ctx.tui.registerFooterHint` + `onTrigger` to call a shell command instead.
+- **Wrap your panel in `<Modal>` from `zidane/tui`.** It centers the panel, paints the bordered chrome, and installs the `esc` → close handler.
+- **Fullscreen panels**: pass `fullscreen` (plus `horizontalMargin={0} verticalMargin={0}`) and the panel fills the terminal and tracks resizes — the layout the Settings workbench uses. Sizing knobs (`maxWidth`/`minWidth`/`maxHeight`) are ignored under `fullscreen`.
+- Set `<Modal disableEscape>` if the panel needs to swallow `esc` itself.
+- TUI components need `@opentui/react` resolvable at runtime; for a bundled binary, prefer a renderless registration + `ctx.tui.registerFooterHint`/`onTrigger` calling a shell command.
 
 ## Settings UI
 
 Open Settings (`ctrl+o`), navigate to the **Extensions** tab (alongside Skills + MCPs):
 
 ```
-[ Agent ] [ UI ] [ Keybindings ] [ Authentication ] [ Skills ] [ MCP servers ] [ Extensions 2 / 3 ]
+[ Agent ] [ UI ] [ Keybindings ] [ Authentication ] [ Skills ] [ MCP servers ] [ Extensions 1 / 2 ]
 
   search extensions — name, version, description…
 
@@ -864,25 +589,15 @@ Open Settings (`ctrl+o`), navigate to the **Extensions** tab (alongside Skills +
 
   ▶  [✓] hello  v0.1.0
        Logs every tool call · [project: ~/proj/.zidane/extensions/hello]
-     [✓] jq    v0.2.0
-       Run jq filters · [user: ~/.zidane/extensions/jq]
      [ ] notes
        Personal note-taking integration · [user: ~/.zidane/extensions/notes]
 
   ←→ tabs · ↑↓ navigate · ↵ toggle · esc close
 ```
 
-Failed extensions render at the top as a red preamble warning so authoring mistakes surface without hiding the working catalog. Disabled-no-error extensions stay in the toggle list (so the user can flip them back on). The `[source: path]` suffix shows where each extension lives on disk.
+Failed extensions render at the top as a red preamble warning. Disabled-no-error extensions stay in the toggle list. The `[source: path]` suffix shows where each extension lives on disk.
 
-Keybindings show up in `Settings → Keybindings` under an **Extensions** section:
-
-```
-Extensions
-  ctrl+shift+j   Jokes
-                 Open the jokes panel
-```
-
-Config items can declare lifecycle metadata:
+Config items declare lifecycle metadata:
 
 ```ts
 ctx.registerConfigItem('limits', {
@@ -896,27 +611,21 @@ ctx.registerConfigItem('limits', {
 })
 ```
 
-`scope` is currently host metadata; existing stores still persist values in the per-extension settings bag unless a host implements scoped writes. `onChange` is likewise advisory for hosts/UIs (`'live'`, `'agent-rebuild'`, or `'restart'`). `requiresRestart` remains accepted as a compatibility hint.
-
-Item types: `boolean` (toggle), `number` (input with `min`/`max`/`step`), `string` (input, optional `pattern`/`multiline`), `enum` (cycling choice over static `options`), `model` — an inline searchable picker over the host's credentialed model catalog (the ctrl+m interaction: type to filter, `↵` picks; with `multi: true`, `↵` toggles and `esc` applies) — and `action` (imperative row, below). `model` persists a plain id — or a comma-separated id list when `multi` — and degrades to the free string input on hosts without a catalog, so read it with a tolerant parser and validate ids against `ctx.runtime.models()` yourself.
+`scope` and `onChange` (`'live'` / `'agent-rebuild'` / `'restart'`) are advisory host metadata. Item types: `boolean`, `number` (`min`/`max`/`step`), `string` (`pattern`/`multiline`, or `secret: true` for a masked row + empty-on-open editor), `enum` (cycling over static `options`), `model` (searchable picker over the credentialed model catalog; `multi: true` toggles a comma-separated id list), and `action` (below).
 
 ### Config actions (`type: 'action'`)
 
-An `action` item renders as a **press ↵ to run** row instead of a value editor — use it for imperative setup steps that belong next to the settings they configure (start a service, log in, run a migration):
+Renders as a **press ↵ to run** row for imperative setup steps (start a service, log in, run a migration):
 
 ```ts
 ctx.registerConfigItem('headroom', {
   type: 'action',
   key: 'runContainer',
   label: 'Run container',
-  description: 'Start the Headroom proxy in Docker and set Base URL to it.',
   run: async () => {
     const baseUrl = await startMyService() // throw on failure — the message lands on the row
     return { message: `proxy running at ${baseUrl}`, config: { baseUrl } }
   },
-  // Optional passive probe — no ↵ needed: called when the settings panel
-  // surfaces the row (and re-called after any action settles), so the row
-  // shows live state. Return undefined to stay quiet (e.g. tool missing).
   status: async () => {
     const url = await findMyService()
     return url ? { state: 'ok', message: `running at ${url}` } : { state: 'off', message: 'not running' }
@@ -924,55 +633,40 @@ ctx.registerConfigItem('headroom', {
 })
 ```
 
-The contract:
-
-- **Success** — resolve with `{ message?, config? }` (or nothing). `message` becomes the row's feedback line; `config` names THIS extension's config keys to persist. Actions can't write settings directly — the host validates each returned entry against the registered item's schema (`sanitizeExtensionConfigActionPatch`) and drops anything unknown or invalid, so a buggy action degrades instead of corrupting settings.
-- **Failure** — throw / reject; the error message renders on the row in the error color.
-- **Runtime** — the host serializes actions (one in flight per settings panel) but imposes no timeout: bound your own work (`AbortSignal.timeout`, CLI timeouts) or the row shows `running…` until you settle.
-- **No value** — action keys hold nothing: `ctx.config.get('runContainer')` is `undefined`, and action items are omitted from the GUI wire schema (`toWireConfigSchema`) because `run` can't cross IPC — today actions are TUI-only.
-- **Status probe** — the optional `status` callback is passive decoration: it must be fast (the host caps each probe at ~3s and drops late results), must not mutate anything, and a throw is treated as "no status". `state` drives the row color: `ok` (accent), `off` (mute), `error` (error).
-
-The bundled `headroom` extension uses this for a **Run container** / **Stop container** pair managing a `zidane-headroom` container (`ghcr.io/chopratejas/headroom`) on the host: run reuses/starts/creates the container published on an ephemeral loopback port and returns `config: { baseUrl }` so the proxy URL is re-synced on every run; its `status` probe shows `running at …` / `container stopped` when you open Settings; stop leaves `baseUrl` untouched so a later run picks up where you left off. Run also forwards any provider credentials present in the host environment (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, AWS / Google) into the container via `docker run -e KEY` (value read from the host env, never placed in argv), and warns in the result message when none are found — a proxy without credentials boots and answers `/stats` but fails open on compression.
+- **Success** — resolve `{ message?, config? }`. `config` names this extension's own keys to persist; the host validates each entry against the registered item's schema and drops anything unknown.
+- **Failure** — throw; the message renders in the error color.
+- **Runtime** — the host serializes actions (one in flight per panel), no timeout — bound your own work.
+- **Status probe** — optional, passive, capped at ~3s; a throw means "no status". `state`: `ok` / `off` / `error`.
+- Action keys hold no value (`ctx.config.get('runContainer')` is `undefined`) and are omitted from the GUI wire schema — actions are TUI-only today.
 
 ## Limitations + gotchas (v1)
 
-- **Hot-reload via `/reload`.** Edit your extension, run `/reload` — discovery evicts the extension's module graph before importing, so the current on-disk code (deep imports included) re-evaluates; module-level state resets with it. `teardown` runs when the registry that ran `setup` is disposed (`/reload` swap, cwd change, process teardown) — it is **not** fired by an in-session enable/disable toggle, which live-filters until the next reload.
-- **No sandboxing.** Extensions run with the host's full Node access — same trust model as `SKILL.md` shell access. Don't load extensions from untrusted projects you wouldn't otherwise run.
-- **No cross-extension dependency declarations.** If extension A relies on extension B's tool, that's on the author to coordinate.
-- **No compaction lifecycle provider yet.** Extensions can transform run behavior and inspect context/tool metadata, but `compactConversation` is still host-driven (TUI/GUI) rather than an extension lifecycle surface.
-- **Eager modal `node`s load UI everywhere.** A modal registered with an eager `node: <Panel/>` builds its UI at `setup()`, so it joins the import graph of headless / embedded hosts too. Use the lazy `node: () => import('./panel')` form to keep TUI UI off non-TUI graphs — see [Headless-safe UI](#headless-safe-ui).
+- **Hot-reload via `/reload`.** Discovery evicts the extension's module graph before importing, so on-disk edits apply live; module-level state resets with it. `teardown` runs on registry disposal (`/reload`, cwd change, process teardown) — **not** on an in-session enable/disable toggle.
+- **No sandboxing.** Extensions run with the host's full Node access — same trust model as `SKILL.md` shell access.
+- **No cross-extension dependency declarations.** Coordination between extensions is on the authors.
+- **No compaction lifecycle provider yet.** `compactConversation` is still host-driven (TUI/GUI), not an extension surface.
+- **Eager modal `node`s load UI everywhere.** A modal registered with `node: <Panel/>` builds its UI at `setup()`, joining the import graph of headless hosts too. Use the lazy `node: () => import('./panel')` form — see [Headless-safe UI](#headless-safe-ui).
 - **Hooks don't bubble to subagents** — see [Hooks: parent vs subagent](#hooks-parent-vs-subagent).
-- **Compiled binary import resolution.** `zidane-tui` binaries can't dynamically resolve `import { defineExtension } from 'zidane'` against the bundle. Use the zero-import alternative or type-only imports — see above.
-- **Setup runs on the boot critical path.** Slow imports (heavy deps, network discovery) add latency to TUI startup. Imports run in parallel across extensions, but a single slow one still blocks `Promise.all`. Keep `setup` cheap.
+- **Compiled binary import resolution.** `zidane-tui` binaries can't dynamically resolve `import { defineExtension } from 'zidane'`. Use the zero-import alternative or type-only imports.
+- **Setup runs on the boot critical path.** Slow imports add latency to TUI startup; keep `setup` cheap.
 
 ## SDK surface
 
-For hosts (custom CLIs, GUI shells, scripts) that want to drive extensions without `runTui`:
+For hosts (custom CLIs, GUI shells, scripts) driving extensions without `runTui`:
 
 ```ts
 import {
-  defineExtension,         // identity helper
-  discoverExtensions,      // disk walk + import
-  inlineLoadedExtension,   // wrap a host-supplied def
-  buildExtensionRegistry,  // run setup, merge contributions
-  mergeContributions,      // re-merge a filtered subset (toggle)
-  isExtensionDefinition,   // structural type guard
-  defaultExtensionScanPaths,
-  scanExtensionDirectories,
-  EMPTY_EXTENSION_REGISTRY,
+  defineExtension, discoverExtensions, inlineLoadedExtension,
+  buildExtensionRegistry, mergeContributions, isExtensionDefinition,
+  defaultExtensionScanPaths, scanExtensionDirectories, EMPTY_EXTENSION_REGISTRY,
 } from 'zidane'
 
 import {
-  // Live-host wiring (the TUI uses these internally; GUI shells do the same):
-  createExtensionHud,               // ctx.tui.notify / setStatus / setBanner backing
-  createExtensionPromptBridge,      // ctx.submitPrompt backing
-  createExtensionHostRuntimeBridge, // ctx.runtime / ctx.sessions / appendNote backing
+  // Live-host wiring (TUI uses these internally; GUI shells do the same):
+  createExtensionHud, createExtensionPromptBridge, createExtensionHostRuntimeBridge,
   // Install / update / remove pipeline (what the Settings panel calls):
-  installExtensionFromSpec,
-  updateInstalledExtension,
-  removeInstalledExtension,
-  readExtensionInstallProvenance,
-  ExtensionInstallError,
+  installExtensionFromSpec, updateInstalledExtension, removeInstalledExtension,
+  readExtensionInstallProvenance, ExtensionInstallError,
 } from 'zidane'
 
 import type {
@@ -992,18 +686,11 @@ import type {
 } from 'zidane'
 ```
 
-Everything above is also importable from the `zidane/extensions` subpath
-(same barrel, narrower module graph for hosts that don't want the root).
-
-Same exports are available from `zidane/chat` for hosts that pull the chat layer (not the full SDK barrel).
-
-The TUI-specific bits (`ExtensionsSettingsModal`) live in `zidane/tui`.
+Also importable from `zidane/extensions` (same barrel, narrower module graph) and `zidane/chat` (for hosts that pull the chat layer, not the full SDK). The TUI-specific bits (`ExtensionsSettingsModal`) live in `zidane/tui`.
 
 ### Folding extensions into an agent
 
-`runTui` and the GUI wire the registry in for you. For an embedded harness, build
-the registry (async — it runs `setup()`), then hand the **result** to `createAgent`
-(sync) or `runHeadless`:
+`runTui` and the GUI wire the registry in for you. For an embedded harness, build the registry (async — it runs `setup()`), then hand the **result** to `createAgent` (sync) or `runHeadless`:
 
 ```ts
 import { buildExtensionRegistry, createAgent, inlineLoadedExtension, runHeadless } from 'zidane'
@@ -1013,72 +700,37 @@ const registry = await buildExtensionRegistry(defs.map(inlineLoadedExtension))
 // Long-lived agent:
 const agent = createAgent({ provider, execution, session, extensions: registry })
 
-// One-shot headless run (`preset` swaps the default `basic` bundle wholesale):
+// One-shot headless run:
 await runHeadless({ prompt, provider, preset: myPreset, extensions: registry })
 ```
 
-`createAgent({ extensions })` folds the registry's tools / hooks / MCP servers /
-skills / system fragments / subagents / runtime transforms / typed metadata into
-the agent, with your explicit options winning on collision. It is **not** just
-`composePresets(buildExtensionPreset(registry), preset)`: the fold also rebuilds
-the `spawn` tool's subagent menu (`withSubagents`), *appends* system fragments
-rather than replacing `system`, carries context-panel sections and tool-result
-metadata into `agent.getContextBreakdown()`, and leaves `ctx.config.get` reading
-live through the registry's `readSettings`. The renderer/picker surfaces a registry
-carries — `themes`, `agents`, `providers`, `completionProviders`, keybindings, footer
-hints — are **not** folded into a bare agent; they need a host (TUI/GUI) that consumes
-them.
+`createAgent({ extensions })` folds the registry's tools/hooks/MCP servers/skills/system fragments/subagents/runtime transforms/typed metadata into the agent, with explicit options winning on collision. It also rebuilds the `spawn` tool's subagent menu, *appends* system fragments rather than replacing `system`, and carries context-panel sections + tool-result metadata into `agent.getContextBreakdown()`. Renderer/picker surfaces (`themes`, `agents`, `providers`, `completionProviders`, keybindings, footer hints) are **not** folded into a bare agent — they need a host (TUI/GUI).
 
 ### Headless-safe UI
 
-Every **agent-level** contribution — tools, hooks, MCP servers, skills, system
-fragments, subagents, typed config — is headless-safe: it's plain data /
-callbacks, so registering it never drags a UI runtime onto a non-TUI host's
-import graph. TUI keybindings and footer hints are likewise just callbacks +
-data and are fine.
-
-The one exception is a modal's **eager** `node`. Because it's a `ReactNode`
-built during `setup()`, the JSX producing it is evaluated at registration time,
-so it lands on the import graph of *every* host that loads the extension —
-headless and embedded included.
+Every **agent-level** contribution (tools, hooks, MCP servers, skills, system fragments, subagents, typed config) is headless-safe: plain data/callbacks, no UI runtime on the import graph. TUI keybindings and footer hints are likewise callbacks + data.
 
-To keep a TUI modal's UI off non-TUI graphs:
+The exception is a modal's **eager** `node` — a `ReactNode` built during `setup()`, so its JSX is evaluated at registration time and lands on every host's import graph, headless included. To keep it off non-TUI graphs:
 
-- Register it with the **lazy** form: `node: () => import('./panel')`. The thunk
-  runs only when the modal first opens.
-- Keep the extension's **entry** module free of UI imports **and** JSX — a single
-  piece of JSX injects a static `react/jsx-runtime` import that defeats the split.
-- Put the component + its JSX in the lazily-imported `./panel` module and
-  `export default` the node (zidane unwraps the module's `default`).
+- Register with the lazy form: `node: () => import('./panel')`. The thunk runs only when the modal first opens.
+- Keep the extension's entry module free of UI imports **and** JSX (a single piece of JSX injects a static `react/jsx-runtime` import that defeats the split).
+- Put the component + JSX in the lazily-imported module and `export default` the node.
 
-This mirrors the guarantee zidane enforces on its own extension core: the
-`src/extensions/**` tree is renderer-neutral (no `react` / `@opentui` at
-runtime), checked by the `bundle-invariant` test. The lazy `node` form extends
-the same discipline to *your* extension's entry module.
+This mirrors zidane's own invariant: `src/extensions/**` is renderer-neutral (no `react`/`@opentui` at runtime), checked by the `bundle-invariant` test.
 
 ## Preset vs extensions
 
-Both layer contributions onto an agent, but they answer different questions — and an
-extension never shadows anything the host didn't already cede:
+Both layer contributions onto an agent, but answer different questions — an extension never shadows anything the host didn't already cede:
 
 | | `preset` (+ explicit `createAgent` options) | `extensions` (an `ExtensionRegistry`) |
 |---|---|---|
 | Role | The host's authoritative bundle — the agent "profile" | A contributed layer composed *under* the host |
-| Precedence | **Wins** on every collision | Loses to preset/explicit (mirrors the TUI's `composePresets(extensionPreset, profile.preset)`) |
+| Precedence | **Wins** on every collision | Loses to preset/explicit (mirrors `composePresets(extensionPreset, profile.preset)`) |
 | Unit | A static object you author | A *built* artifact: ran `setup()`, allowlist-gated, carries inactive/errored entries |
 | Lifecycle | Fixed at construction | Discovered, trusted, enabled/disabled per user |
 | Surface | tools, hooks, system, mcpServers, skills, behavior | all of the above **plus** subagents, typed config, themes, agent profiles, providers, completion providers, keybindings, footer hints, storage/session state, runtime transforms, context-panel sections, metadata |
 
-**Rule of thumb:**
-
-- **Host-owned and authoritative** (your core tools, your system prompt, your behavior
-  defaults) → `preset` / explicit options.
-- **Contributed, third-party, user-toggleable, or anything needing the extension-only
-  surfaces** (subagents, typed config, themes, providers, keybindings, storage/session state, runtime transforms) → `extensions`.
-
-If a tool or hook lives in both, the preset/explicit one wins (hooks from both still
-fire). The litmus test: *would a user expect to toggle it off in `Settings → Extensions`?*
-If yes, it's an extension.
+**Rule of thumb:** host-owned and authoritative (core tools, system prompt, behavior defaults) → `preset`/explicit options. Contributed, third-party, user-toggleable, or extension-only surfaces (subagents, typed config, themes, providers, keybindings, storage/session state, runtime transforms) → `extensions`. The litmus test: *would a user expect to toggle it off in `Settings → Extensions`?* If yes, it's an extension.
 
 ## File layout reference
 
@@ -1094,15 +746,13 @@ If yes, it's an extension.
 ~/.zidane/extensions/                   # user-global, zidane-specific
 ```
 
-Each `<name>/` is free to ship whatever it needs — additional files, `package.json` (including optional `package.json#zidane` manifest metadata), assets. The loader reads `extension.json` / `package.json#zidane` for metadata and only imports `index.{ts,tsx,mjs,js}` for executable code.
+Each `<name>/` is free to ship whatever it needs — additional files, `package.json` (including optional `package.json#zidane` manifest metadata), assets. The loader reads `extension.json`/`package.json#zidane` for metadata and only imports `index.{ts,tsx,mjs,js}` for executable code.
 
 ## Quick checklist
 
-Building your first extension:
-
 - [ ] Create `.zidane/extensions/<your-name>/index.ts`
 - [ ] `export default defineExtension({ name, setup })` (or the zero-import object form)
-- [ ] Optionally add `extension.json` with `apiVersion: 1`, `capabilities`, and `permissions`
+- [ ] Optionally add `extension.json` with `apiVersion: 1`, `capabilities`, `permissions`
 - [ ] Register what you need via `ctx.*` inside `setup`
 - [ ] Restart the TUI
 - [ ] Toggle on/off in `Settings → Extensions`