zidane 5.14.4 → 6.0.0

package/docs/EXTENSIONS.md

@@ -0,0 +1,1063 @@
+# 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.
+
+```ts
+// .zidane/extensions/hello/index.ts
+import { defineExtension } from 'zidane'
+
+export default defineExtension({
+  name: 'hello',
+  version: '0.1.0',
+  description: 'Logs every tool call',
+  setup(ctx) {
+    ctx.registerHook('tool:after', ({ name }) => ctx.logger.info('ran', { name }))
+  },
+})
+```
+
+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`.
+
+## 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.
+
+## Discovery
+
+Search order — 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.
+
+Optional manifest metadata can live in either `<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 `defineExtension` API
+
+```ts
+import type { ExtensionDefinition } from 'zidane'
+
+interface ExtensionDefinition {
+  name: string                                       // stable, kebab-case-ish
+  apiVersion?: 1                                     // omitted means v1
+  displayName?: string                               // optional UI label
+  permissions?: readonly ExtensionPermission[]       // descriptive, not a sandbox
+  capabilities?: readonly ExtensionCapability[]      // shown before setup runs
+  version?: string                                   // surfaced in Settings → Extensions
+  description?: string                               // ditto
+  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).
+
+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.
+
+### 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:
+
+```ts
+// .zidane/extensions/hello/index.ts — no runtime imports
+export default {
+  name: 'hello',
+  setup(ctx) {
+    ctx.registerHook('tool:after', e => ctx.logger.info('ran', e))
+  },
+}
+```
+
+For type-checking your `ctx` argument, use a **type-only** import (these get erased at runtime and don't need a resolver):
+
+```ts
+import type { ExtensionContext } from 'zidane'
+
+export default {
+  name: 'hello',
+  setup(ctx: ExtensionContext) {
+    ctx.registerHook('tool:after', e => ctx.logger.info('ran', e))
+  },
+}
+```
+
+## The `ctx` surface
+
+Three namespaces:
+
+| Namespace | Scope | When ignored |
+|---|---|---|
+| `ctx.*` (root) | Renderer-agnostic — folds into the agent and config | never |
+| `ctx.tui.*` | OpenTUI-specific (keybindings, modals, footer hints) | non-TUI host (GUI / SDK) |
+| `ctx.gui.*` | Reserved for the future GUI shell | every host today |
+
+### 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.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. |
+| `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, or `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); `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, `presentPlan` approval — the same prompt-slot UI as the tools, without tool calls or turns) — both optional, so guard for bare hosts | Output is display-only (persisted, never sent to the model); 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. |
+| `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. |
+
+`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.
+
+### TUI-specific
+
+```ts
+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
+  description: 'Open the joke panel',
+  onTrigger: dispatch => dispatch.openModal('jokes'),
+})
+
+ctx.tui.registerFooterHint({ key: '^J', label: 'jokes' })
+
+ctx.tui.registerModal({
+  id: 'jokes',
+  node: <JokesPanel />,
+})
+
+// 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
+})
+
+ctx.tui.registerRenderer('commit-graph', data =>   // auto-namespaced: '<ext>/commit-graph'
+  <CommitGraph {...(data as GraphData)} />)
+
+ctx.appendNote([{
+  text: '```\n* abc123 main\n```',                 // MANDATORY markdown fallback
+  custom: { renderer: 'commit-graph', data: { head: 'abc123' } }, // bare id auto-prefixed here
+}])
+// 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} />)
+```
+
+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.
+
+**Caching + viewport gating — the hooks** (from `zidane/tui`, importable in
+extensions thanks to host-module mapping):
+
+```tsx
+import { useRowVisible, useSessionState } from 'zidane/tui'
+
+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
+  }, [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).
+- 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.
+
+```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.
+
+// Late-bound host controls (null/false until the host attaches)
+ctx.runtime.model()                               // active model id
+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.
+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().
+```
+
+`/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.
+
+`onTrigger` receives an `ExtensionKeybindingDispatchContext` — `{ 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.
+
+Users can 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
+}
+```
+
+Extension bindings appear in `Settings → Keybindings` under a trailing **Extensions** section.
+
+### GUI-specific
+
+```ts
+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.
+
+## How it boots
+
+```mermaid
+flowchart TD
+  scan["discoverExtensions<br/>(.zidane/extensions/, .agents/extensions/, ~/.zidane/...)"]
+  inline["RunTuiOptions.extensions<br/>(host-provided)"]
+  state["loadState(state.json)<br/>→ Settings.enabledExtensions"]
+  build["buildExtensionRegistry<br/>(runs setup with disabled filter)"]
+  config["resolveConfig<br/>(folds into ResolvedConfig)"]
+  agent["buildAgent / createAgent<br/>(composePresets(extensionPreset, profile.preset))"]
+
+  scan --> build
+  inline --> build
+  state -->|disabled set| build
+  build --> config
+  config --> agent
+```
+
+Key invariants:
+
+1. **State first.** `runTui` reads `state.json` before discovery so a previously-disabled extension's `setup()` never runs — side effects (file handles, child processes) don't fire for toggled-off extensions.
+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:
+
+   ```ts
+   import {
+     buildExtensionRegistry, discoverExtensions, inlineLoadedExtension,
+     resolveConfig,
+   } from 'zidane'
+
+   const registry = await buildExtensionRegistry([
+     ...await discoverExtensions({ cwd, prefix }),
+     ...myInlineDefs.map(inlineLoadedExtension),
+   ])
+   const config = resolveConfig({ ...opts, extensionRegistry: registry })
+   ```
+
+## Enabling / disabling
+
+Each extension shows up in `Settings → Extensions` with a checkbox. Toggling writes to `Settings.enabledExtensions` (semantics mirror `enabledSkills` / `enabledMcps`):
+
+- `undefined` (fresh install) — **every** discovered extension runs.
+- `[]` — none run.
+- `[names]` — explicit allowlist.
+
+Disabled extensions:
+- Have `setup()` skipped at boot (no side effects).
+- Land on `registry.inactive` so the toggle UI still lists them.
+- 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 skip `setup()` entirely 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.
+
+## 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:
+
+```
+owner/repo                        # GitHub, single-extension repo
+github:owner/repo@v2              # pinned ref (branch or tag)
+owner/repo indexer                # pick one from a multi-extension repo (append the name)
+owner/repo#main:packages/ext      # search a subdirectory (monorepos); pasted tree URLs work too
+@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.
+
+**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):
+
+```
+Tahul/zidane:extensions/git-flow    # /commit — agent-written commit messages + one-tap push
+Tahul/zidane:extensions/headroom    # compress large tool outputs via a local Headroom proxy
+```
+
+Both are zero-dependency and 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).
+
+## Collisions + precedence
+
+When extension contributions overlap with host or built-in surfaces:
+
+| 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. |
+| 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. |
+
+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.
+
+## Hooks: parent vs subagent
+
+`registerHook(event, handler)` registers on the **parent** agent (the one TUI builds for the active session). Subagents — spawned via the `spawn` tool — get a fresh `createAgent()` call using the active profile's preset, **not** the extension preset.
+
+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))
+```
+
+## Authoring patterns
+
+### A custom tool
+
+```ts
+import { defineExtension } from 'zidane'
+import { z } from 'zod'
+
+export default defineExtension({
+  name: 'jq',
+  setup(ctx) {
+    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(),
+      }),
+      async execute({ json, filter }) {
+        // ... shell out, call a JS jq, whatever
+        return JSON.stringify(result, null, 2)
+      },
+    })
+  },
+})
+```
+
+### 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: { /* … */ },
+    })
+  },
+})
+```
+
+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.
+
+```ts
+import { defineExtension, definePreset } from 'zidane'
+import { glob, grep, readFile } from 'zidane/tools'
+
+export default defineExtension({
+  name: 'reviewer',
+  setup(ctx) {
+    ctx.registerAgent({
+      id: 'reviewer',
+      label: 'Reviewer',
+      description: 'Read-only code reviewer — explores + critiques, never writes.',
+      accent: 'model',
+      preset: definePreset({
+        name: 'reviewer',
+        system: 'You are a code reviewer. Be concise. Read files, point out issues, never edit.',
+        tools: { readFile, glob, grep },
+        behavior: { maxTurns: 30 },
+      }),
+    })
+  },
+})
+```
+
+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.
+
+### An MCP server
+
+```ts
+export default defineExtension({
+  name: 'linear-bundled',
+  setup(ctx) {
+    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())
+  },
+})
+```
+
+### 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 []
+      },
+    })
+  },
+})
+```
+
+`resolveReferences` and `onSubmit` are optional submit hooks. The TUI and GUI both call them before dispatching a prompt, using the shared `resolveCompletionSubmit` core helper:
+
+```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)
+  },
+})
+```
+
+### 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)
+      },
+    }))
+  },
+})
+```
+
+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.
+
+### Context panel sections + tool metadata
+
+```ts
+ctx.registerContextPanelSection({
+  id: 'build-info',
+  title: 'Build Info',
+  rows: [
+    { label: 'Branch', value: currentBranch },
+    { label: 'CI', value: ciUrl },
+  ],
+})
+
+ctx.registerToolResultMetadata({
+  namespace: 'acme.trace',
+  contextRows({ entries }) {
+    return entries.map(({ value }) => ({
+      label: 'Trace',
+      value: String(value),
+    }))
+  },
+})
+```
+
+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
+import { defineExtension } from 'zidane'
+import { Modal } from 'zidane/tui'
+
+function JokesPanel() {
+  return (
+    <Modal title="jokes">
+      <text>haha</text>
+    </Modal>
+  )
+}
+
+export default defineExtension({
+  name: 'jokes-ui',
+  setup(ctx) {
+    ctx.tui.registerModal({ id: 'jokes-panel', node: <JokesPanel /> })
+    ctx.tui.registerKeybinding({
+      id: 'jokes-ui.open',
+      default: 'ctrl+shift+j',
+      label: 'Jokes',
+      description: 'Open the jokes panel',
+      onTrigger: dispatch => dispatch.openModal('jokes-panel'),
+    })
+    ctx.tui.registerFooterHint({ key: '⌃⇧J', label: 'jokes' })
+  },
+})
+```
+
+`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>
+)
+```
+
+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.
+
+## Settings UI
+
+Open Settings (`ctrl+o`), navigate to the **Extensions** tab (alongside Skills + MCPs):
+
+```
+[ Agent ] [ UI ] [ Keybindings ] [ Authentication ] [ Skills ] [ MCP servers ] [ Extensions 2 / 3 ]
+
+  search extensions — name, version, description…
+
+  ✗ crash — Error during setup(): boom
+
+  ▶  [✓] 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.
+
+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:
+
+```ts
+ctx.registerConfigItem('limits', {
+  key: 'maxCostUsd',
+  type: 'number',
+  label: 'Max cost',
+  default: 1,
+  min: 0,
+  scope: 'project',
+  onChange: 'agent-rebuild',
+})
+```
+
+`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.
+
+## 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).
+- **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.
+
+## SDK surface
+
+For hosts (custom CLIs, GUI shells, scripts) that want to drive 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,
+} 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
+  // Install / update / remove pipeline (what the Settings panel calls):
+  installExtensionFromSpec,
+  updateInstalledExtension,
+  removeInstalledExtension,
+  readExtensionInstallProvenance,
+  ExtensionInstallError,
+} from 'zidane'
+
+import type {
+  ExtensionApiVersion, ExtensionCapability, ExtensionContext,
+  ExtensionDefinition, ExtensionManifest, ExtensionPermission,
+  ExtensionRegistry, ExtensionContributions, LoadedExtension,
+  ExtensionKeybinding, ExtensionFooterHint, ExtensionModal,
+  ExtensionRunTransform, ExtensionBehaviorTransform,
+  ExtensionProviderMiddleware, ExtensionToolCatalogTransform,
+  ExtensionMcpConfigTransform, ExtensionSkillPolicy,
+  ExtensionToolPolicy, ExtensionToolVerdict, ExtensionToolResultTransform,
+  ExtensionContextTransform, ExtensionPromptTransform,
+  ExtensionToolResultMetadataRegistration,
+  ExtensionPaths, ExtensionStorageSurface, ExtensionSessionStateSurface,
+  ExtensionSource, ExtensionTuiSurface, ExtensionGuiSurface,
+  TuiContributions, GuiContributions,
+} 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`.
+
+### 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`:
+
+```ts
+import { buildExtensionRegistry, createAgent, inlineLoadedExtension, runHeadless } from 'zidane'
+
+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):
+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.
+
+### 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.
+
+To keep a TUI modal's UI 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`).
+
+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.
+
+## 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:
+
+| | `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)`) |
+| 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.
+
+## File layout reference
+
+```
+<project>/
+├── .agents/extensions/                 # discovery root (cross-tool convention)
+│   └── my-ext/index.ts
+├── .zidane/extensions/                 # discovery root (zidane-specific)
+│   └── another-ext/
+│       ├── extension.json              # optional manifest metadata
+│       └── index.tsx
+~/.agents/extensions/                   # user-global, cross-tool
+~/.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.
+
+## 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`
+- [ ] Register what you need via `ctx.*` inside `setup`
+- [ ] Restart the TUI
+- [ ] Toggle on/off in `Settings → Extensions`
+- [ ] Rebind any contributed keybindings via `~/.zidane/keybindings.json` if you want different defaults