zidane 7.2.4 → 8.0.4

package/docs/ARCHITECTURE.md

@@ -1,8 +1,90 @@
 # Zidane Architecture
 
-Internal execution model of the agent loop: how a run boots, how a turn streams, how a tool call is gated/executed/transformed, and the hook contracts that hold it together. Read this when you're modifying `src/agent.ts` / `src/loop.ts`, writing a hook that depends on firing order, or diagnosing a prompt-cache break. For the public API surface (createAgent, presets, hooks, sessions) see `docs/SKILL.md`.
+Two parts. **System architecture** (first): the layers from the SDK core up to the TUI/GUI, where code goes, and the limits lint enforces. Read it before adding a feature or moving code between folders. **Agent loop internals** (the rest): how a run boots, how a turn streams, how a tool call is gated/executed/transformed, and the hook contracts that hold it together. Read that part when you're modifying `src/agent.ts` / `src/loop.ts`, writing a hook that depends on firing order, or diagnosing a prompt-cache break. For the public API surface (createAgent, presets, hooks, sessions) see `docs/SKILL.md`.
 
-Contents: [Agent Lifecycle](#agent-lifecycle) · [Turn Loop](#turn-loop) · [Single Turn](#single-turn) · [Tool Execution](#tool-execution) · [Tool ergonomics defaults](#tool-ergonomics-defaults) · [Prompt caching](#prompt-caching) · [Tool aliasing](#tool-aliasing-wire-vs-canonical) · [Skills activation lifecycle](#skills-activation-lifecycle) · [Progressive tool disclosure](#progressive-tool-disclosure) · [Hook Firing Order](#hook-firing-order) · [Dependency Graph](#dependency-graph) · [Presets](#presets) · [Option Precedence](#option-precedence)
+System: [Layers](#layers) · [Feature folders](#feature-folders) · [Adding a feature](#adding-a-feature) · [Enforced limits](#enforced-limits) · [Testing contracts](#testing-contracts) · [Opt-in features](#opt-in-features)
+
+## Layers
+
+Dependencies point one way, down this list. Each layer may import the ones above it, never the ones below.
+
+| Layer | Where | Composition root | Details |
+|---|---|---|---|
+| SDK core | `src/*.ts`, `src/<folder>/` except `chat`, `ipc`, `tui`, `server` | `createAgent` (`src/agent.ts`) | this doc, below; `docs/SKILL.md` |
+| Chat engine | `src/chat/` (engine in `src/chat/host/`) | `createChatHost` (`src/chat/host/engine.ts`) | `docs/CHAT.md` |
+| Dispatcher + protocol | `src/ipc/protocol.ts`, `src/ipc/daemon/` | `src/ipc/daemon/dispatcher.ts`, one handler module per feature in `handlers/` (request params shape-checked first, `handlers/params.ts`) | `docs/IPC.md` |
+| Transports | unix socket (`src/ipc/daemon/server.ts` + `src/ipc/client.ts`), in-memory (`src/ipc/memory.ts`), WebSocket (`src/ipc/transports/ws-server.ts` + `ws-client.ts`, token carriers `ws-auth.ts`, per-connection rate limit `rate-limit.ts`); shared by the wire transports in `src/ipc/transports/`: the host side of a connection (`peer-rpc.ts`), its send budget (`send-budget.ts`: signals backlog bound, reply size), the client side (`client-core.ts`) | `startIpcDaemon` / `startInProcessHost` / `startWsServer` | `docs/IPC.md` |
+| Remote host (zidane-server) | `src/server/` (`server.ts`, device tokens `tokens.ts`, `config.ts`, origin / proxy policy and the `private` trusted-proxies keyword `security.ts`, the upgrade checks before the token `upgrade-guard.ts`, `audit.ts`, the `zidane server` CLI `cli.ts` (health probes, bootstrap token), standalone entry `main.ts`; the host both front-ends share comes from `createServerHostDispatcher` in `ws-server.ts`, which also serves `/healthz`); clients' side of several hosts in `src/chat/hosts/` (registry, host index, presence merge) and `src/ipc/hosts/` (probe, connection loop, saved servers; `zidane/ipc/remote`, entry `src/ipc/remote.ts`); packaging in `server/` (workspace package, Dockerfile, compose files incl. Coolify's), binary built by `scripts/build-server.ts` | `startZidaneServer` (one host behind the WebSocket transport with token auth, and a unix socket) | `docs/IPC.md` § Remote server; running it: `docs/SERVER.md` |
+| Machines | engine side `src/chat/host/machines/` (registry, remote `ExecutionContext`, offline wait, `local@`/`worktree@<machine>` providers; wire types in the leaf `src/chat/machine-protocol.ts`); the WS side `src/ipc/daemon/machine-gateway.ts`; the machine agent, its confined executor and `zidane machine share` in `src/ipc/machine/` | `createMachines` (engine), `startMachineAgent` | `docs/MACHINES.md` |
+| Clients | TUI (`src/tui/`, CLI in `tui/`), GUI (`gui/`, separate package), `zidane attach` (`src/ipc/attach.ts`) | `src/tui/app.tsx`; `gui/src/main/chat/ipc.ts` | `docs/TUI.md`, `docs/CHAT.md` § GUI checklist |
+
+The engine owns all session state and behavior; the dispatcher is a transport-free JSON-RPC method table around one `ChatHost`; transports only frame messages. A client sees the same protocol whether the host runs in a shared daemon (socket) or in its own process (in-memory), which is why TUI local mode and daemon mode share every code path above the transport.
+
+The GUI consumes the root package (`zidane`, `zidane/chat`, `zidane/chat/pure`, `zidane/ipc`, and on demand `zidane/ipc/remote`) like any external client; it never reaches into `src/`. `zidane/ipc/remote` (the WebSocket client and the saved-hosts registry) is its own entry, out of the `zidane/ipc` barrel, so an opt-in client loads none of it until it imports that entry.
+
+## Feature folders
+
+- **Colocate by feature within a layer; keep layers separate.** Everything the engine does for, say, todos lives in `src/chat/host/todos/`; the TUI's todos UI lives in `src/tui/todos/`. They are two folders, not one, because they sit in different layers.
+- **One entry per feature.** Other code imports a feature folder through its `index.ts` only. Files inside the folder import each other freely.
+- **Composition roots stay thin.** `engine.ts`, `dispatcher.ts`, `app.tsx` and the GUI's `ipc.ts` wire features together; they don't implement them. If a root grows logic, that logic is a feature folder waiting to be extracted.
+- Types shared between a root and its features live beside the root (e.g. `src/chat/host/types.ts`) so features never import the root.
+
+## Adding a feature
+
+A feature that spans the stack touches one place per layer:
+
+1. **Engine:** `src/chat/host/<feature>/index.ts`, wired into `createChatHost`.
+2. **Protocol:** request/response/signal types in `src/ipc/protocol.ts`.
+3. **Dispatcher:** `src/ipc/daemon/handlers/<feature>.ts`, registered in `dispatcher.ts`.
+4. **TUI:** `src/tui/<feature>/` (hooks, components), mounted from the app shell.
+5. **GUI:** `gui/src/main/chat/channels/<feature>.ts` (registers through the injected `IpcRegistrar`), plus renderer UI.
+
+Features that are pure SDK (a tool, a provider, a hook) stay in the core and need none of this.
+
+## Enforced limits
+
+Both run in `bun run lint` as errors (`eslint.config.ts`).
+
+- **Size** (`zidane/size-ratchet`): over all of `src/**/*.{ts,tsx}`, functions max 200 lines, modules max 1000, blank lines and comments not counted. Tests are exempt (a long spec is a catalogue). Fix a violation by extraction, not a disable.
+- **Boundaries** (`zidane/boundaries`, a local rule in the config):
+  - `src/chat` must not import `src/ipc`, `src/tui`, `src/server` or `gui/`; `src/ipc` must not import `src/tui`, `src/server` or `gui/`.
+  - `src/server` (zidane-server, a host process) may import `src/ipc` and `src/chat`, never `src/tui` or `gui/`; `src/tui` and the SDK core must not import it.
+  - The SDK core must not import `src/tui` or `src/ipc` (sole exception: `src/daemon-cli.ts`, the daemon binary's entry point).
+  - The SDK core may import from `src/chat` only the leaf modules in `CORE_CHAT_ALLOWLIST` (formatting, XDG paths, provider tables, the context-breakdown model, extension-facing registries) and never `src/chat/host`. That list records existing inversions; shrink it, don't grow it.
+  - `src/chat/host/<feature>/<file>` may only be imported from inside `<feature>/`; everyone else (tests included) goes through the index.
+
+## Testing contracts
+
+| Suite | Pins |
+|---|---|
+| `test/ipc-transport-conformance.test.ts` | Socket, in-memory and WebSocket `IpcClient`s behave identically against the same host (host identity, signal numbering and `sessions.resume` included). |
+| `test/ipc-ws-*.test.ts`, `test/server-*.test.ts` | WebSocket specifics (heartbeat, version skew against a server, reconnect + resume, slow consumers) and zidane-server: device tokens and auth, configuration, exposure rules and limits, the audit log, one host on both front-ends, shutdown, the CLI, `zidane attach --host`. |
+| `test/tui/app-modes.test.tsx` (+ `app-modes-harness.tsx`) | The real `<App>`, every scenario in local, daemon and remote (zidane-server over WebSocket) mode: same screen, same stored session. The remote server has its own store, so the window must get session data from its host. |
+| `test/tui-runtime-parity.test.ts` | Local vs daemon: normalized event streams, persisted turns, and what each mode sends to the model. |
+| `test/helpers/host-harness.ts` | A real `createChatHost` over an in-memory store and a mock provider; the base for `test/chat/host-*` specs. |
+
+A new engine feature gets a host-harness spec; a new protocol method is covered by conformance if both transports must agree on it.
+
+## Opt-in features
+
+An experimental feature is **one gate**: a boolean setting, off by default, plus a kill-switch env var that wins over it. `defineFeatureGate` (`src/chat/feature-gate.ts`, exported from `zidane/chat` and `zidane/chat/pure`) defines both together so every client reads the same pair:
+
+```ts
+export const daemonGate = defineFeatureGate({ setting: 'useDaemon', killSwitchEnv: 'ZIDANE_NO_DAEMON' })
+
+daemonGate.isEnabled(settings) // settings.useDaemon === true && !killed
+daemonGate.isKilled()          // process.env.ZIDANE_NO_DAEMON === '1'
+```
+
+The daemon runtime is the reference: the TUI checks it via `resolveHostTarget` (`src/tui/host-target.ts`, read through `isMultiProcess` in `src/tui/live-settings.ts`), the GUI main process via `daemonGate` directly, and `zidane --no-daemon` exports the env var. The kill switch exists so a bug in the gated path can never lock a user out, even when the settings UI is unreachable.
+
+Remote hosts have their gate too: `remoteHostsGate` (`remoteHosts` setting, kill switch `ZIDANE_NO_REMOTE`). Its settings row (Settings → Sessions in the TUI, General › Experimental in the GUI, "Remote hosts (experimental)") gates the saved servers (the Hosts settings, the per-host session groups, picking a host for a new session); an explicit `zidane --host` / `ZIDANE_HOST_URL` is its own opt-in, and the kill switch wins over it (see `docs/IPC.md` § TUI remote mode). Both clients load the saved-hosts code on demand behind the gate (the TUI's `src/tui/host/remote-hosts.ts`, the GUI main's `gui/src/main/chat/hosts/remote-hosts.ts`), each with a containment test that boots the app with the setting off and saved servers on disk and checks nothing loads or dials. Which settings a server owns when a window edits it is one classification for both: `isWindowOnlySetting` (`src/chat/host-scoped-settings.ts`).
+
+A settings row names its gate's kill switch with `killSwitchEnv` (`SETTINGS_TOGGLES`; every gate is in `FEATURE_GATES`). While the switch is engaged the row is inert and says `Turned off by <VAR>=1`: the TUI reads its environment, the GUI renderer asks its main process (`settings:killSwitches` → `engagedKillSwitches()`). `useDaemon` doesn't declare one yet, so its row stays live under `ZIDANE_NO_DAEMON`. Which switches a window keeps in its own `state.json` while a host owns the settings file: `WINDOW_LOCAL_SETTINGS` (`useDaemon`, `remoteHosts`).
+
+---
+
+Loop internals: [Agent Lifecycle](#agent-lifecycle) · [Turn Loop](#turn-loop) · [Single Turn](#single-turn) · [Tool Execution](#tool-execution) · [Tool ergonomics defaults](#tool-ergonomics-defaults) · [Prompt caching](#prompt-caching) · [Tool aliasing](#tool-aliasing-wire-vs-canonical) · [Skills activation lifecycle](#skills-activation-lifecycle) · [Progressive tool disclosure](#progressive-tool-disclosure) · [Hook Firing Order](#hook-firing-order) · [Dependency Graph](#dependency-graph) · [Presets](#presets) · [Option Precedence](#option-precedence)
 
 ## Agent Lifecycle
 
@@ -308,10 +390,11 @@ A prefix cache breaks at the first differing byte — the wire must be append-on
 
 | Knob | Cache-aware setting | Why |
 |---|---|---|
-| `elideStaleReads` | `'notice'` | Append-only: a `<system-reminder>` rides the mutating tool's own result, zero prefix rewrites. `'stub'` reclaims stale bytes at one full-prefix re-bill per read→edit transition. |
+| `elideStaleReads` | `false` or `'notice'` | Neither rewrites the prefix. `'notice'` is append-only: a `<system-reminder>` rides the mutating tool's own result, zero prefix rewrites. `'stub'` reclaims stale bytes at one full-prefix re-bill per read→edit transition. |
 | `thinkingDecay` | Step form `{ afterTurn, floor }` | Every distinct budget is one cache loss; step emits one change per run, geometric emits one per halving, a per-turn function disables caching for the rest of the run. |
 | `cacheTtl` | `'1h'` for interactive hosts, `'5m'` for headless back-to-back runs | The 5-minute default TTL is the dominant cache cost for a human-paced session. |
-| `compactStrategy` / `mediaKeepTurns` | Keep windows equal, chunk-aligned (`COMPACT_CHUNK_TURNS`) | A window then costs one invalidation, not two. |
+| `compactKeepTurns` | Chunk-aligned (`COMPACT_CHUNK_TURNS`) | The tail-compaction frontier then moves in discrete jumps, not per turn. |
+| `mediaBudget` over `mediaKeepTurns` | `{ maxItems: 80, maxBytes: 20 MiB }` + `maxImageEdge: 2000` | A positional window rewrites an earlier message per aged image and re-bills the conversation each time (replayed on a 470k-token GUI session: ~340 rewrites, 11 under the budget). The budget only ages media out near the provider's caps, in half-budget batches. |
 | `compactThresholdWindowFraction` | `0.25` for interactive hosts | Each tail-compaction frontier step rewrites an early message and re-bills the whole suffix (~50x the cost of keeping the bytes cached). Scaling the byte threshold with the model's window removes the steps on large-context models; ≤128k models keep the byte rule. Live A/B in `test-inference/cache-stability.inference.test.ts` § tail compaction vs context window. |
 | `thinking` level | Constant for the whole run | The thinking config is part of the cache key like the budget; toggling it mid-run forfeits the prefix. |
 | `system:transform` handlers | Byte-stable output only | Per-turn counters/timestamps belong in the transcript, not the system prompt. |
@@ -588,11 +671,14 @@ skills:activate                          ← during run, when a skill file is re
 Fires when a parent invokes the `spawn` tool. Children inherit the parent's preset (tools, system, aliases, mcpServers, skills, behavior) by default.
 
 ```
+spawn:queued          ← a top-level call found every slot taken (maxConcurrent); it waits, first come first served
 spawn:before          ← child agent created, before run
 spawn:complete        ← child finished successfully, includes AgentStats
 spawn:error           ← child run threw
 ```
 
+Past `maxConcurrent`, the top-level agent's spawn calls wait for a slot (aborting the run drops the waiters, and no child starts). A subagent's are refused, since waiting on slots its own ancestors hold could never end; a refused call (that cap, `maxDepth`, an unknown model, a bad `resume`) fails as a tool error. A child's `SessionRun` records the call that started it (`parentCallId`), and its `spawn-start` marker carries it (`spawn.callId`), so a client pairs every worker with its own call, live and on replay.
+
 The child's lifecycle also bubbles to the parent hook surface with `childId` + `depth`:
 
 ```
@@ -601,9 +687,18 @@ child:tool:gate / child:mcp:tool:gate          ← share the child's ctx — par
 child:tool:cancelled                           ← bubbled per-call cancel from a subagent's tool
 child:tool:transform                           ← share the child's ctx — parent mutations propagate
 child:tool:before / child:tool:after / child:tool:error
+child:validation:reject / child:repeat-guard:exceeded
 child:turn:after
 ```
 
+A spawn run BY a subagent (depth ≥ 2) fires `spawn:*` on that subagent's bus; it reaches the parent (and chains up to the root) as
+
+```
+child:spawn:before / child:spawn:complete / child:spawn:error
+```
+
+carrying the spawned agent's own record (`id`, `depth`, `task`, `callId`, …) plus `parentChildId` — the subagent that ran the `spawn` call. No `childId` (the spawned agent's `depth` is already the payload's `depth`), and no `tracingContext`: propagation into a nested child belongs to its spawner's own tracer. The root's `spawn:*` stays direct-children-only.
+
 `BUBBLED_MUTABLE_EVENTS` (`src/tools/spawn.ts`) lists `tool:gate`, `mcp:tool:gate`, `tool:transform` — the bubbled ctx is the same reference the child loop awaits on, so a parent listener can refuse/substitute/annotate a subagent's tool call without registering on the child.
 
 - **Subagent type registry** (`createSpawnTool({ subagents })`) adds a `subagent_type` enum to the schema; the matching `SubagentDef` overlays `system`, `model`, `tools` (allow-list), `readonly` (shorthand for `['read_file','grep','glob','list_files']`), and `description` for that one dispatch. Unknown types route to `'general-purpose'`.
@@ -684,10 +779,12 @@ Use `agent.hooks.hook(event, fn)` for dynamic post-creation registration (return
 
 - **`toolOutputBudget`** (off). Sums every result's `outputBytes` after `tool:transform`. On overshoot, appends a synthetic user message (`[Tool output budget exceeded: N bytes … cap: M]`) and fires `budget:exceeded` — the model self-compacts next turn instead of being cut.
 - **`compactStrategy: 'tail' | CompactFunction'`** — client-side, wire-only trim for non-Anthropic providers. `'tail'` stubs `tool_result` blocks older than `compactKeepTurns` past a byte threshold (`compactThreshold`, raised to `compactThresholdWindowFraction × contextWindow × 4 B` when the run knows its window — `autoCompact.contextWindow`, the active `ModelTarget`, or `provider.meta.contextWindow`); `session.turns` is untouched. Anthropic should prefer server-side `context-management-2025-06-27` (token-accurate). A custom function must preserve `tool_use ↔ tool_result` adjacency and the trailing user message.
-- **`mediaKeepTurns`** — wire-only media age-out. Inline `image`/`document` blocks older than N messages become an `attachment://<hash>` marker on the wire; `session.turns` keeps the bytes, `read_file path="attachment://<hash>"` re-inlines. Chunk-snapped for cache stability; requires `read_file` registered to be actionable.
+- **`mediaBudget`** — wire-only, budget-triggered media age-out (`applyMediaBudget`). Inline `image`/`document` blocks stay on the wire until their count passes `maxItems` (lowered to `provider.meta.capabilities.maxMediaPerRequest`, e.g. Bedrock's 20) or their base64 passes `maxBytes`; then the oldest become `attachment://<hash>` markers in steps of half the limit. Stateless and monotone within a run, so the prefix is rewritten once per step. Images still over 2000 px age out past the last 8 messages (the many-image rule). `session.turns` keeps the bytes; `read_file path="attachment://<hash>"` re-inlines.
+- **`mediaKeepTurns`** — positional media age-out: blocks older than N messages become markers, chunk-snapped. Takes precedence over `mediaBudget`; the two resolve as a pair from one layer (a run's `behavior` replaces the agent's media policy whole). Requires `read_file` registered.
+- **`maxImageEdge`** — shrinks inline PNGs whose longest edge exceeds N px, once, as they enter the session (`emitToolResult` for tool results, the seed prompt for pasted images), so the persisted turn and every later request carry the same bytes. Pure `node:zlib` codec in `src/media/png-downscale.ts`; other formats and unsupported PNGs (interlaced, 16-bit) pass through.
 - **`autoCompact`** (`boolean | AutoCompactConfig`, off). At each turn boundary, once effective input (`input + cacheRead + cacheCreation`) crosses `threshold` (default `0.85`) of the context window, summarizes older turns and continues. Window source: `autoCompact.contextWindow` → `provider.meta.contextWindow`, else inert. `minGrowthFraction` (default `0.1`) stops post-compact thrashing; `maxFailures` (default `2`) disables it after consecutive summary failures. Chat profiles enable at `{ threshold: 0.85 }`.
 - **`modelCatalog`** — override model metadata keyed `"<provider>:<modelId>"` or via `{ get, list }`. Resolution: run → agent `behavior.modelCatalog` → process-wide `setModelCatalog()` → bundled registry → local fallback tables, merged field-level. `list` returning `[]` empties a provider's picker; `get` returning `undefined` falls through. Unset by default.
-- **`dedupReads` + `requireReadBeforeEdit`** share a per-session map keyed by canonical absolute path. `dedupReads` gates the short-circuit "unchanged since last read" reply; `requireReadBeforeEdit` rejects `edit`/`multi_edit` when no entry exists (shell reads don't register). Hash drift is anchor-tolerant — a still-verbatim `old_string` proceeds with a disclosure note, a fuzzy-only match is refused with "re-read the file", and consecutive refusals escalate to name the likely external writer. A `tool:gate` hook pre-hydrates the map from `session.turns` on resume.
+- **`dedupReads` + `requireReadBeforeEdit`** share a per-session map keyed by canonical absolute path. `dedupReads` gates the short-circuit "unchanged since last read" reply; `requireReadBeforeEdit` rejects `edit`/`multi_edit` when no entry exists (shell reads register only with `trackShellReads`). Hash drift is anchor-tolerant — a still-verbatim `old_string` proceeds with a disclosure note, a fuzzy-only match is refused with "re-read the file", and consecutive refusals escalate to name the likely external writer. A `tool:gate` hook pre-hydrates the map from `session.turns` on resume.
 - **`dedupTools`** generalizes the pattern via a per-tool hasher keeping only the most recent hash. Hasher-only form replays the prior result on hit (fires `tool:transform`+`tool:after`). `{ hasher, mode: 'block-after', threshold, reason?, scope? }` replays the first `threshold − 1` calls then blocks via `tool:gate` (`threshold` default `4`, clamps at `2`); `scope: 'run'` keeps parent/subagent counters separate. Never list tools with side effects or non-deterministic output.
 - **`ToolContext.state`** (`src/tool-state.ts`) — durable key/value state that survives a durable-runtime replay where a journaled tool body doesn't re-execute. Reads are synchronous against a per-agent snapshot; writes stage as ops committed in call-index order. `AgentOptions.toolState` supplies the backing (unset ⇒ in-memory). A rejecting commit fires `tool-state:commit-failed` rather than failing the call; values cap at `maxValueBytes` (default 64 KiB JSON). See `docs/RESTATE.md#durable-tool-state`.
 - **`toolBudgets`** caps per-tool calls per run. At `runToolCounts[name] >= max`, `onExceed: 'block'` refuses (`Blocked: <message>`), `'steer'` enqueues a deduped synthetic user message. Fires `tool-budget:exceeded` (distinct from byte-level `budget:exceeded`). Counts include dedup substitutes.

package/docs/ARTIFACTS.md

@@ -5,8 +5,8 @@ An **artifact** is a durable, typed pointer to something a session produced outs
 - **Model / store:** `src/session/artifacts.ts`, `SessionStore` artifact methods in `src/session/index.ts`
 - **Producers:** the `metadata.artifacts` tool-result namespace, lifted by `src/loop.ts`
 - **Kinds:** `src/extensions/builtin-artifact-kinds.ts` + `ctx.registerArtifactKind`
-- **Surfaces:** TUI rail + `▢` title-bar chip · GUI rail + header chip · sessions-list badge · `#pr` completion
-- **IPC:** `sessions.artifacts`, `artifacts.list` / `delete` / `upsert`; signals `artifact:recorded`, `artifact:changed`
+- **Surfaces:** TUI rail + `▢` title-bar chip · GUI rail + header chip · session badges (GUI sidebar, TUI sessions list) · `#pr` completion
+- **IPC:** `sessions.artifacts`, `artifacts.list` / `delete` / `upsert`; signals `artifact:recorded`, `artifact:changed`; GUI-local `artifacts:badges`
 
 Contents: [Model](#model) · [Producers](#producers) · [Storage](#storage) · [Extension API](#extension-api) · [Surfaces](#surfaces) · [IPC](#ipc) · [Lazy refresh](#lazy-refresh) · [Disabling](#disabling) · [Known gaps](#known-gaps)
 
@@ -33,7 +33,7 @@ interface SessionArtifact {
 | Identity | `(sessionId, kind, uri)`. Re-emitting upserts: keeps `id` / `runId` / `turnId` / `createdAt`, refreshes `label` / `meta` / `projectRoot` / `updatedAt`. |
 | Cap | 200 per session. On overflow, `file` artifacts are evicted first, oldest first. |
 | Bounds | `kind` `[\w.:-]+` ≤ 64 chars · `uri` ≤ 2048 · `label` ≤ 512 (clipped) · `meta` ≤ 16 KB (dropped, artifact kept). |
-| `projectRoot` | Defaults to the session's root. `file` artifacts get the git root of the landed path when the execution runs on the host (`process` handle); docker/remote paths keep the session default. |
+| `projectRoot` | Defaults to the session's root. `file` artifacts get the project root of the landed path (`findProjectRoot` — a linked worktree's main checkout) when the execution runs on the host (`process` handle); docker/remote paths keep the session default. |
 | Subagents | Land on the shared parent session under the child's `runId`. |
 | Unknown kinds | Always render as `label` + `uri`. Rows are never dropped because a kind's extension is gone. |
 
@@ -76,6 +76,7 @@ ctx.registerArtifactKind({
   validateMeta?: (meta) => boolean,      // failing → meta dropped, artifact kept (own detections only)
   render?: (artifact) => { title, subtitle?, href?, status? },
   resolve?: async (artifact) => ({ label?, meta? }),   // lazy refresh, see below
+  badge?: (artifacts) => ExtensionSessionBadge | undefined, // the badge under a session's title
 })
 ctx.tui.registerArtifactRenderer({ kind, renderDetail: artifact => <Pane /> })   // TUI detail pane
 ctx.artifacts.list({ scope: 'session' | 'project' | 'all', kind?, since?, limit? })
@@ -88,6 +89,8 @@ ctx.registerHook('artifact:recorded', ({ artifact, runId, turnId }) => …)
 - `detect` rides `tool:transform` and `child:tool:transform` but can only append to `metadata.artifacts`; it never changes what the model sees. A throwing detector emits nothing.
 - `ctx.artifacts` is late-bound (like `ctx.sessions`): reads answer `[]`, `record` answers `undefined`, when detached or the store lacks artifact support. `record` never throws for unusable input either.
 - Row presentation goes through `renderArtifactRow(artifact, registry)`: registry kind → built-in kind → `label` + `uri` fallback. A throwing `render` falls back.
+- Session badges go through `sessionBadges(artifacts, registry)`: one per kind with a `badge`, given that session's artifacts of the kind newest first, ordered by `badge.order` (pull requests 0, commits 10, default 100). JSON-safe; a throwing or empty `badge` contributes none. Example: [EXTENSIONS.md → Session badges](./EXTENSIONS.md#session-badges).
+- The GUI main process renders rows, refreshes and badges with the extension registry of the project the artifact landed in (`projectRoot`; user-level when untagged), so extension kinds' `render` / `resolve` / `badge` run there too. Sidebar badges only use a registry already built (by a live runtime): until then a project's rows show the built-in kinds' badges only, and pick up extension kinds on the next re-read (`artifact:*`, `extensions:invalidated`).
 
 Authoring example: [EXTENSIONS.md → Session artifacts](./EXTENSIONS.md#session-artifacts).
 
@@ -98,7 +101,8 @@ Authoring example: [EXTENSIONS.md → Session artifacts](./EXTENSIONS.md#session
 | TUI rail (`ctrl+shift+a`) | Read-only column docked right of the chat screen, 34 cells: kind headers, bullet rows (PR state tints the bullet), path tails. Click a row to open its href. Hides itself under 110 columns; the toggle survives. Live via the same change ticks as the modal. |
 | TUI actions modal | Opened from the rail's `⋯ actions` footer: `↵` open href · `tab` session ↔ project · `c` copy locator · `d` remove. Grouped by kind, built-ins first; extension `renderDetail` mounts under the list in an error boundary. |
 | GUI rail (`⌃⇧A`, header chip, `⋯` menu) | 288 px column right of transcript + composer, under the header; session scope only (the project-wide view belongs to the project page). No controls of its own — the chip / shortcut open and close it. Hover → copy / remove, PR rows lazily refresh on first hover. Header chip shows the live count. Rows pre-rendered main-side (`artifacts:list` IPC). |
-| Sessions list | `N artifacts` badge from `artifactCount` (hidden at 0 or when the store doesn't report it). |
+| GUI sidebar row | Line 2 under the title: one badge per kind with a `badge` (commits, pull requests, extension kinds), each with a hover card listing its artifacts. A click selects the chat and opens the badge's `panel` (default Artifacts, scrolled to the kind; a card row also focuses its artifact via `uri`); ⌘-click opens a lone badge's `href`; right-click opens the badge's actions (copy, add to prompt, open, extension items: [EXTENSIONS.md → Badge actions](./EXTENSIONS.md#badge-actions)). A kind whose count grew pops and sweeps the row. Follows Settings › Chat › Sidebar run details and Artifacts. Read via `artifacts:badges`, re-read on `artifact:*` and `extensions:invalidated`. |
+| TUI sessions list | `N artifacts` stat from `artifactCount`, plus a badge line (icon in the badge's tone, text, `+N`). A click opens the chat with the rail on the badge's `panel` (Artifacts: the kind's group first); ctrl-click opens a lone badge's `href`; right-click (badges and rail rows) opens the badge actions modal. Only sessions with artifacts are asked, again when their count or activity changes. |
 | `#` completion | Shares the trigger with chats. `#pr` / `#br` / `#file` rank by kind alias; selecting inserts the locator as plain text (no reference grammar). |
 
 ### Opening artifacts

package/docs/CHAT.md

@@ -52,6 +52,7 @@ A non-Bun host (Electron, Tauri, Next.js) imports `zidane/chat` only — build-e
 - [Session export](#session-export)
 - [Session artifacts](#session-artifacts)
 - [Commands](#commands)
+- [Markdown commands and subagents](#markdown-commands-and-subagents)
 - [Title generation](#title-generation)
 - [Turn operations](#turn-operations)
 - [IPC contracts](#ipc-contracts)
@@ -149,13 +150,63 @@ Zero-config local models (Ollama, LM Studio, etc.) are discovered by probing wel
 ## Storage-slot layout
 
 ```ts
-resolveStorageDirs({ prefix: 'zidane', cwd, home }): StorageDirs
-// → { userDir, projectDir, mode: 'xdg' | 'legacy' }
+resolveStorageDirs({ prefix: '.zidane', storageDir?, home?, platform?, env? }): StorageDirs
+// → { configDir, dataDir, stateDir, cacheDir, mode: 'legacy-explicit' | 'legacy-existing' | 'xdg' | 'default' }
 ```
 
-- **`userDir`** — `$XDG_DATA_HOME/zidane` when set, else `~/.zidane` (legacy, still the common case).
-- **`projectDir`** — `<project root>/.zidane`, used for session exports and project-scoped skills/MCP config.
-- Every path in `ResolvedPaths` derives from these two roots; hosts overriding `ChatOptions.paths` should override both together to keep sessions and credentials colocated.
+Four slots: **config** (credentials, keybindings, `config.json`, `projects.json`), **data** (`sessions.db`), **state** (`state.json`), **cache** (session artifacts, task logs, update cache). First match wins (`src/chat/xdg.ts`):
+
+| Mode | When | Layout |
+|---|---|---|
+| `legacy-explicit` | `ChatOptions.storageDir` or `ZIDANE_STORAGE_DIR` set | All slots in `<storageDir>/<prefix>` |
+| `legacy-existing` | `~/<prefix>/` holds storage | All slots in `~/<prefix>` |
+| `xdg` | Linux, any `XDG_*_HOME`, or any `ZIDANE_{CONFIG,DATA,STATE,CACHE}_DIR` | `~/.config/zidane`, `~/.local/share/zidane`, `~/.local/state/zidane`, `~/.cache/zidane` (each overridable) |
+| `default` | Otherwise (macOS, Windows) | All slots in `~/<prefix>` |
+
+`ResolvedPaths.userDir` is an alias of `configDir`. Authored content stays home-anchored in every mode: `~/<prefix>/{extensions,skills,mcps.json,SYSTEM.md,AGENTS.md}` (with the project's `<checkout>/<prefix>/` counterparts). A `~/<prefix>/` holding only those entries (or `.DS_Store`) is not a legacy install, so scaffolding an extension or a skill never flips an XDG layout. Hosts writing storage must go through the resolved slots, never a literal `~/<prefix>`: one stray file there turns the next launch into `legacy-existing`. The desktop app resolves the same slots (`gui/src/main/paths.ts`).
+
+An install that was flipped to `legacy-existing` by an older build stays there; nothing is moved automatically. To get back to XDG, move `credentials.json`, `*-credentials.json`, `keybindings.json`, `config.json` and `projects.json` to the config dir, `sessions.db` to the data dir, `state.json` to the state dir, and drop the rest (cache) — leaving only authored entries in `~/<prefix>/`.
+
+### Checkout root vs project root
+
+`src/chat/project-root.ts` answers two questions that differ only inside a linked git worktree:
+
+| | Function | Meaning | Used for |
+|---|---|---|---|
+| Checkout root | `findGitRoot(cwd)` | The working tree `cwd` sits in (a worktree's own dir) | Discovery (`AGENTS.md`, `SYSTEM.md`, skills, MCPs, plugins, extensions), file completion, path display, the model's environment section |
+| Project root | `findProjectRoot(cwd)` / `projectRootOf(cwd)` | The project it belongs to — a linked worktree's **main checkout** | `SessionData.projectRoot`, session list scope + grouping, the safelist (`getSafelistForCwd`), artifact scope, the project-scoped DB |
+
+So every worktree of a repo is one project, while each reads its own branch's files. Submodules and worktrees of bare / `--separate-git-dir` repos stay their own project. The TUI exposes both as `ProjectLocation.{checkoutRoot, projectRoot}`, the GUI as `folder.locationOf(cwd)`. Sessions stamped with a worktree's checkout root by older builds are moved to the main checkout when the SQLite store opens.
+
+### Session environments
+
+Where a session's work happens is chosen at creation and stored as `metadata.environment` (`src/chat/environment.ts`). Absent means `{ kind: 'local', state: 'ready' }`, which is what every older session reads as — and what a create request without `environment` gets (workers, forks and programmatic creates stay local; the pickers turn the configured default into an explicit request). Each kind is an `EnvironmentProvider`, registered on `ChatHostEnvironment.environments` (default: `builtinEnvironmentProviders({ dataDir })` — `local` and `worktree`, `src/chat/environments/`):
+
+| Hook | Role |
+|---|---|
+| `configSchema` | Option fields (`boolean` / `string` / `number` / `choice` / `path` / `secret`) rendered by both settings UIs. `setting` binds a field to an existing `Settings` key (Local's OS sandbox → `sandbox`, `sandboxNetwork`, `sandboxAllowWrite`); `env` names an env-var fallback; `when` hides a field unless another has a value. |
+| `takesBranch` / `suggestBranch(config)` | The kind works on its own branch: pickers ask for one, pre-filled with the suggestion. |
+| `available({ cwd, config })` | Whether it can be offered (credentials, binaries, a git repo). Creation of an unavailable or unknown kind throws before anything is written. |
+| `prepare(input)` | Makes the environment exist. Present → the session starts `provisioning` and the host provisions in the background; its result can move `metadata.cwd` (e.g. to a worktree) and set `ref` / `execCwd`. Must be idempotent — `ChatHost.retryEnvironment` re-runs it after a failure or a restart. |
+| `execution(input)` | `{ key, create }` for the session's context. `resolveExecution` is the only caller; `execution-cache.ts` reuses the context while `key` holds. |
+| `teardown(env)` | Runs when the OWNING session is deleted, after its processes are gone. A fork shares its parent's environment (`owned: false`) and never tears it down. May keep it and say why. |
+
+States: `provisioning` → `ready` \| `failed` (with `error`), each persisted transition announced as `sessions:changed`. A prompt queued (`queue.add` / `chat.pushQueued`) while this host provisions is parked and delivered once the environment is ready; after a failure it stays queued until a retry succeeds. Every agent build (host `buildActiveRun`) passes `assertEnvironmentReady`, so a session never runs before its environment exists. `metadata.cwd` stays the host directory config and discovery read from; `environment.execCwd` is set only when commands run somewhere else (inside a sandbox). `zidane run --context …` remains a one-launch override in the TUI (the host runs that session on the launch context).
+
+Built-in kinds:
+
+| Kind | What it does |
+|---|---|
+| `local` | This machine, in the session's folder. Its options are the OS sandbox settings, so Settings → Environments and the Safety settings edit the same keys. Can't be disabled. |
+| `worktree` | A git worktree on its own branch — under `<dataDir>/worktrees/` by default, or next to the repo / in a git-excluded `.zidane/worktrees/` (the `location` option); `metadata.cwd` moves there, the session stays in the main checkout's project. Deleting the session removes the worktree unless it has uncommitted changes (kept, with the reason). |
+| `docker` | A container on this machine (`src/chat/environments/docker.ts`), running as the host `uid:gid` with `HOME=/tmp`. Workspace: *this checkout* (bind mount, edits your working tree) or *a new worktree* (provisioned like `worktree`, then mounted). Provisioning pulls the image; the setup command runs in every new container; after `idleMinutes` the container is removed (files stay on the host) and the next prompt starts a fresh one. Off until turned on. |
+| `e2b` / `daytona` | A cloud sandbox per session holding a **clone** of the repo on its own branch (`remote-sandbox.ts` + a vendor driver). Provisioning creates the sandbox, clones `origin` over https with the git token (secret → `GH_TOKEN`/`GITHUB_TOKEN` → `gh auth token`), checks out the branch from the base (the current branch if pushed, else the default branch), and runs the setup command; `execCwd` is the clone, `metadata.cwd` stays the host checkout (AGENTS.md, skills, MCPs load from it). Idle past `idleMinutes` → paused (e2b `pause`, Daytona `stop`) and marked `suspended`; the next prompt resumes it. e2b sandboxes are created with `onTimeout: 'pause'` and kept alive while used. Actions: **Push branch**, **Open pull request** (GitHub, via the REST API with the same token). Deleting the session deletes the sandbox. The token is stored in the sandbox's git credential store, so the agent can read it. Off until turned on. |
+
+Beyond `configSchema`, a provider can declare `offByDefault` (hidden until turned on — stored in `Settings.environments.enabled`), `verify` ("Test connection"), `note` (what creating one here will do, shown in pickers), `actions` (per-session commands: `ChatHost.listEnvironmentActions` / `runEnvironmentAction`, run on the session's own cached execution through `runSessionEnvironmentAction`), and `idleSuspendMinutes` (a once-a-minute host sweep releases idle executions past it and calls `suspend`).
+
+**Settings → Environments** (GUI tab, TUI Agent-tab "Environments" row) edit `Settings.environments` — `{ defaultKind?, disabled?, config?: { [kind]: { [key]: value } } }` in `state.json` — through `applyEnvironmentSettingsChange` (`src/chat/environment-settings.ts`), which validates every write against the kind's schema. `secret` fields go to `<dataDir>/environment-credentials.json` (0600) and never reach a client: descriptors (`describeEnvironments`) only say `configured` / `fromEnv`. A disabled kind is hidden from pickers and refused at creation.
+
+**Picking one.** The GUI composer shows an environment pill beside the folder toggle for a new chat (when more than Local is enabled), with a branch field for kinds that take one; rows show the kind / branch, a spinner while provisioning, and the failure with a Retry action. The TUI's `newSession` asks where the session runs, creates and provisions it before opening it (`src/tui/environment-session.ts`, inline locally, via `sessions.create` under the daemon), then moves the window into the prepared directory; `ctrl+r` on a failed row retries.
 
 ## Agents
 
@@ -171,11 +222,18 @@ const SHARED_BEHAVIOR: AgentBehavior = {
                                     // runs never trip tail compaction on
                                     // ordinary sessions; ≤128k stays on bytes
   compactKeepTurns: 8,             // floor, not a cap — see below
-  elideStaleReads: 'notice',       // append-only staleness note; never rewrites
-                                    // cached prefix bytes ('stub' re-bills the
-                                    // conversation per newly-stale read)
-  mediaKeepTurns: 8,                // matched to compactKeepTurns: one prompt-
-                                     // cache invalidation per window, not two
+  elideStaleReads: false,          // no reminder after the agent's own edits;
+                                    // 'stub' would re-bill the conversation
+                                    // per newly-stale read
+  mediaBudget: DEFAULT_MEDIA_BUDGET, // { maxItems: 80, maxBytes: 20 MiB }: media
+                                     // stays inline until near the provider's
+                                     // caps, then ages out in half-budget
+                                     // batches (no per-image cache reset)
+  maxImageEdge: DEFAULT_MAX_IMAGE_EDGE, // 2000: shrink PNGs once at entry; past
+                                     // it, >20-image requests are rejected
+  cacheTtl: '1h',                    // a human pause past 5 min no longer
+                                     // re-bills the conversation (API-key
+                                     // auth too; OAuth already defaulted to 1h)
   toolDisclosure: 'lazy',
   toolOutputBudget: 64 * 1024,
   toolOutputBudgetExcludeTools: DEFAULT_BUDGET_EXCLUDE_TOOLS,
@@ -188,7 +246,8 @@ const SHARED_BEHAVIOR: AgentBehavior = {
   autoCompact: { threshold: 0.85 },
 
   // loop prevention (ON in the chat profiles; OFF in the SDK core)
-  requireReadBeforeEdit: true,
+  requireReadBeforeEdit: false,    // old_string anchors already guard edits
+  shellToolNudges: true,           // fading pointer to read_file/grep/edit
   dedupTools: { mode: 'chain', excludeTools: [...] },
   repeatGuard: { mode: 'both', windowSize: 40 },
   thinkingDecay: { afterTurn: 10, floor: 1024 },
@@ -270,6 +329,7 @@ Both join `[...doctrine, userInstructions]` as the **static** half and `[envSect
 | `fileLogging` | `boolean` | `false` | The in-TUI Logs panel works regardless (in-memory). |
 | `showTodoIndicator`, `showUsageIndicator`, `showThrobber` | `boolean` | `true`, `true`, `false` | See **Todos**, **Subscription usage**. |
 | `artifacts` | `boolean` | `true` | Master switch for session artifacts (detection, `record_artifact`, every surface). See [ARTIFACTS.md § Disabling](./ARTIFACTS.md#disabling). |
+| `terminal`, `terminalAgent`, `terminalAgentTasks` | `boolean` | `true`, `true`, `true` | Terminals (the GUI drawer and tab; run by the daemon), the agent's `terminal_*` tools, and background `shell` tasks in terminals. Enforced by the host; a change rebuilds agents without aborting runs. See [TERMINAL.md § Settings](./TERMINAL.md#settings). |
 | `checkForUpdates` | `boolean` | `true` | |
 | `subscriptionUsage` | `boolean` | `true` | Gates *automatic* usage probes; see **Subscription usage**. |
 | `uiMode` | `'full'\|'minimal'` | `'full'` | |
@@ -758,11 +818,11 @@ The marker turn carries a `compact-summary` content block; the loop scans for it
 
 ```ts
 const text = renderSession(sessionData, { format: 'markdown' })   // or 'json' — render only
-const target = await writeSessionExport({ session: sessionData, format: 'markdown', cwd, prefix })
+const target = await writeSessionExport({ session: sessionData, format: 'markdown', cwd, prefix, dataDir })
 // → { filepath, dir, anchor: 'project' | 'home' }
 ```
 
-Anchor walks upward from `cwd` looking for `.git`; the first hit anchors to that repo (`project`), otherwise `~/.{prefix}/sessions/` (`home`). `resolveSessionExportTarget` computes the path without writing.
+Anchor walks upward from `cwd` looking for `.git`; the first hit anchors to that repo (`<repo>/.{prefix}/sessions/`, `project`), otherwise `<dataDir>/sessions/` (`home`; `dataDir` defaults to the resolved storage data dir, i.e. `~/.{prefix}` outside an XDG layout). `resolveSessionExportTarget` computes the path without writing.
 
 ## Session artifacts
 
@@ -776,11 +836,102 @@ Anchor walks upward from `cwd` looking for `.git`; the first hit anchors to that
 
 | Command | Requires | Does |
 |---|---|---|
-| `/help` | — | Lists `opts.getCommands()` (built-ins + extensions), read live so it stays accurate after `/reload`. |
+| `/help` | — | Lists `opts.getCommands()` (built-ins, extensions, and markdown file commands), read live so it stays accurate after `/reload`. |
 | `/reload` | `opts.reloadExtensions` | Re-discovers, re-runs `setup`, tears down the old extension instances. Omitted from the list on hosts without one. |
 
 `createCommandsCompletionProvider` (trigger `/`, shared with skills) suggests from the live merged command list. Authoring a new command — the full `Command` shape, `CommandInteraction`, `generateData`/`spawnAgents` — is documented in `docs/EXTENSIONS.md`; this module is the runtime that executes whatever a `Command` describes.
 
+## Markdown commands and subagents
+
+Drop a `.md` file in a commands or agents root and it becomes a slash command or a subagent, Claude Code style. `src/markdown-defs/` loads both; the loader never throws, and a bad file is dropped with a diagnostic.
+
+**Subagents, not agent profiles.** Files in `agents/` folders are *subagents*: entries of the `spawn` tool's `subagent_type`, run as child agents. They are not the agent profiles in the picker (`Build`, `Plan`, Codemode; see `src/chat/agents.ts`), which pick the session's own preset. The folder keeps Claude Code's name for compatibility. The builtin `Plan` subagent is likewise unrelated to the `plan` profile: it is a read-only child a model can spawn from any profile.
+
+| Root | Scope | Loaded |
+|---|---|---|
+| `.agents/commands`, `.agents/agents` | project | always |
+| `.zidane/commands`, `.zidane/agents` | project | always |
+| `~/.agents/commands`, `~/.agents/agents` | user | always |
+| `~/.zidane/commands`, `~/.zidane/agents` | user | always |
+| `.claude/commands`, `.claude/agents` (project and `~`) | foreign | only with `Settings.importForeignConfigs` |
+
+Roots are scanned in order: native project, native user, foreign project, foreign user. The first file for a name wins, so project beats user and native beats foreign. File-derived names are lowercased. Files in nested directories get colon names (`review/pr.md` is `/review:pr`); the scan stops at depth 3 and skips every entry starting with `.` (dot-dirs and dotfiles) plus `node_modules` (`build/` and `dist/` are valid namespaces). Names that collide with object keys (`__proto__`, `constructor`, `prototype`) are dropped with a `reserved ... name` diagnostic.
+
+**Where roots anchor.** Project roots anchor at the git root (the repo top, not the current subdirectory); outside git they use the cwd. `.zidane` follows the configured storage prefix (a custom prefix reads `.<prefix>/commands`). Headless always uses `.zidane`, and loads project agent roots only with `--project-agents` (user roots and builtins otherwise; see [HEADLESS.md](./HEADLESS.md)).
+
+**When files are re-read.** The chat/daemon host re-reads markdown files on every command list and dispatch. The TUI and GUI list commands through the session's host (`commands.list`); the TUI re-asks when the session, extensions, or the foreign toggle change, and the GUI on those toggles or after its 30-second cache. Before a session opens, the TUI scans the checkout root itself. Subagents load at each agent build, so an edited agent file applies from the next agent build, not mid-run.
+
+An agent's frontmatter `name:` keeps its case, and agent names match case-sensitively. To override builtin `Explore` (user folders only), set `name: Explore`; an `explore.md` without `name:` registers a separate `explore`. Commands match case-insensitively.
+
+An agent's `tools:` key controls its allowlist. A missing `tools` key inherits all parent tools. An explicitly empty `tools: []` drops the agent with a diagnostic, since spawn would treat an empty list as inherit-all. A `tools` value that is not a string or list (a YAML map, for example) drops the agent with `unreadable tools value; skipped`. Restriction keys fail closed: a value the loader cannot read drops the agent rather than widening its access. A blank key (`tools:`, `disallowedTools:`, or `readonly:` with nothing after it) drops the agent, and so does any of `tools`, `disallowedTools`, `readonly`, or `permissionMode` written twice.
+
+**Precedence across sources.** Commands: builtins (`/help`, `/reload`) > extension commands > file commands, first registration wins, case-insensitive. A file named like a builtin or an extension command is dropped (`mergeCommands` in `src/chat/commands.ts`). Skills also answer `/<name>`; as in Claude Code, a skill beats a file command of the same name, and the file command is dropped with a diagnostic. The check (`createSkillNameProbe`) looks for `<skills dir>/<name>/SKILL.md` in the session's skill paths plus extension skills, so a skill in a nested category folder or renamed by frontmatter is not detected. File commands carry no `group`: that field names a contributing extension, and a namespaced name (`git:commit`) already matches `/git`. Agents: builtin `Explore` / `Plan` < file agents < extension and profile agents. Under the TUI daemon, non-builtin commands (extension or file) run on the daemon.
+
+**Command format.**
+
+```md
+---
+description: Review a PR
+argument-hint: <pr-number>
+---
+Review PR $1 and focus on $ARGUMENTS.
+```
+
+- `description` falls back to the first body line; `argument-hint` is appended to it as `(args: ...)`.
+- `$ARGUMENTS` is the raw argument string; `$1`..`$9` are the whitespace-split arguments (a missing one becomes empty). Both expand in a single pass, so a `$` sequence the user types stays verbatim. A `$1`..`$9` followed by another digit stays literal (`$10` is not an argument), and `\$` produces a literal `$`.
+- With no placeholder in the body (escaped and multi-digit `$` sequences do not count), the arguments are appended after a blank line.
+- `model` and `allowed-tools` are ignored with a diagnostic. `!`cmd`` shell injection and `@file` inclusion are not supported. An empty body is dropped.
+
+**Agent format.**
+
+```md
+---
+name: reviewer
+description: Reviews diffs for bugs
+tools: Read, Grep, Bash(git:*)
+model: sonnet
+---
+You review diffs. Report bugs with file:line.
+```
+
+- `name` defaults to the file name. `description` is required: a file with no frontmatter or no non-empty `description` is dropped. The body is the system prompt.
+- `tools` takes a YAML list, `[a, b]`, `a, b`, or `a b`. Names map to zidane tools as below; `mcp__*` and native zidane names pass through. An unknown name is dropped. A pattern such as `Bash(git:*)` grants the full tool (here, unrestricted `shell`) with no argument restriction, so do not rely on patterns to sandbox an agent. An agent whose tools are all unmapped is dropped.
+- `readonly: true` (or the string `true`) makes the agent read-only; `false` leaves it unset. Any other value drops the agent. `permissionMode: plan` also sets `readonly`; other `permissionMode` values are ignored with a diagnostic.
+- `disallowedTools` takes the same shapes as `tools`. With `tools` set, the listed tools are subtracted from it. Without `tools`, the agent gets the native tool set minus the listed tools; MCP and extension tools are excluded (a diagnostic says so). An agent left with no tools is dropped. An unmappable name is noted, not fatal.
+- Only user-scope files can override builtin `Explore` or `Plan`. A project file with either name is dropped with a diagnostic, so a cloned repo cannot make them writable. A user override that sets no `tools` stays read-only unless it writes `readonly: false`; otherwise it would inherit every parent tool.
+
+| Claude Code | zidane |
+|---|---|
+| `Read` | `read_file` |
+| `Write` | `write_file` |
+| `Edit` | `edit` |
+| `MultiEdit` | `multi_edit` |
+| `Bash` | `shell` |
+| `Grep` | `grep` |
+| `Glob` | `glob` |
+| `LS` | `list_files` |
+| `WebFetch` | `fetch_url` |
+| `WebSearch` | `web_search` |
+| `Task`, `Agent` | `spawn` |
+
+- `model` accepts `inherit` (or nothing) for the parent model, a raw model id, or an alias:
+
+| Alias | Model |
+|---|---|
+| `haiku` | `claude-haiku-4-5-20251001` |
+| `sonnet` | `claude-sonnet-5` |
+| `opus` | `claude-opus-5-5` |
+| `fable` | `claude-fable-5-1` |
+
+  Aliases resolve only under an Anthropic parent (hosts do not pass a model catalog yet). Under any other provider the agent inherits the parent model and a diagnostic is logged.
+- `color`, `isolation`, `memory`, and `hooks` (and any `permissionMode` other than `plan`) are ignored with a diagnostic.
+
+**Trust.** Project files load without a prompt, like project skills and `AGENTS.md`: each is text the model reads, not code zidane runs. A command body is sent as a user turn through the normal approval gate. A subagent file sets a child's system prompt and narrows its tools; it cannot add one (spawn filters to a subset of the parent's tools), and it cannot replace builtin `Explore` or `Plan`. Project extensions differ because they execute code, hence their opt-in setting. Headless, which often runs unattended on a repo it did not write, loads project subagents only with `--project-agents`. SDK hosts can pass `includeProject: false` to `loadMarkdownCommands` / `loadMarkdownAgents`.
+
+**Agent Plugins.** Plugins in `.agents/plugins` contribute skills and MCP servers only: the Agent Plugins 1.0 spec defines no commands or subagents (see [PLUGINS.md](./PLUGINS.md)). Claude Code plugins (`.claude-plugin/plugin.json`) are a different format zidane does not load.
+
+**Diagnostics.** Dropped files, ignored keys, and unenforced patterns go to the debug log only (no UI surface). Run with `ZIDANE_DEBUG=1` to see them; headless writes them to stderr only when `ZIDANE_DEBUG` is set.
+
 ## Title generation
 
 ```ts

package/docs/EXECUTION_CONTEXT.md

@@ -29,6 +29,8 @@ context-specific flags.
 
 Contents: [Flags at a glance](#flags-at-a-glance) · [The `e2b` context](#the-e2b-context) · [The `daytona` context](#the-daytona-context) · [The `docker` context](#the-docker-context) · [The `process` context](#the-process-context-default) · [Programmatic use](#programmatic-use) · [See also](#see-also)
 
+> Chat sessions (TUI, GUI, daemon) pick these per session instead — Settings → Environments turns Docker, e2b and Daytona on, configures them and tests the connection. See [CHAT.md § Session environments](./CHAT.md#session-environments). The flags below are for one-off `zidane run` launches.
+
 ## Flags at a glance
 
 | Flag | `process` | `docker` | `e2b` | `daytona` | Meaning |
@@ -356,6 +358,12 @@ in time by the command timeout, but not in bytes.
 
 ---
 
+## Terminals
+
+`openTerminal(handle, { cols, rows, cwd?, env?, unsetEnv?, onData })` opens an interactive login shell in the context and returns a `TerminalProcess` (`write`, `resize`, `kill`, `detach`, `exited`). `process` and `docker` implement it under Bun (a local PTY; Docker through `docker exec -it`), `e2b` and `daytona` through their SDKs' PTY APIs, and those two also implement `reconnectTerminal(handle, id, …)` because their PTYs outlive the host. `execBackground` takes a `terminal` option that runs the task in a PTY (the `process` context honours it; `TaskHandle.terminal` says whether it did). See [TERMINAL.md](./TERMINAL.md).
+
+---
+
 ## Programmatic use
 
 The CLI flags map onto context factories you can call directly: