nodmix 2026.5.25

package/docs/concepts/agent-loop.md

@@ -0,0 +1,185 @@
+---
+summary: "Agent loop lifecycle, streams, and wait semantics"
+read_when:
+  - You need an exact walkthrough of the agent loop or lifecycle events
+  - You are changing session queueing, transcript writes, or session write lock behavior
+title: "Agent loop"
+---
+
+An agentic loop is the full "real" run of an agent: intake → context assembly → model inference →
+tool execution → streaming replies → persistence. It's the authoritative path that turns a message
+into actions and a final reply, while keeping session state consistent.
+
+In Nodmix, a loop is a single, serialized run per session that emits lifecycle and stream events
+as the model thinks, calls tools, and streams output. This doc explains how that authentic loop is
+wired end-to-end.
+
+## Entry points
+
+- Gateway RPC: `agent` and `agent.wait`.
+- CLI: `agent` command.
+
+## How it works (high-level)
+
+1. `agent` RPC validates params, resolves session (sessionKey/sessionId), persists session metadata, returns `{ runId, acceptedAt }` immediately.
+2. `agentCommand` runs the agent:
+   - resolves model + thinking/verbose/trace defaults
+   - loads skills snapshot
+   - calls `runEmbeddedPiAgent` (pi-agent-core runtime)
+   - emits **lifecycle end/error** if the embedded loop does not emit one
+3. `runEmbeddedPiAgent`:
+   - serializes runs via per-session + global queues
+   - resolves model + auth profile and builds the pi session
+   - subscribes to pi events and streams assistant/tool deltas
+   - enforces timeout -> aborts run if exceeded
+   - for Codex app-server turns, aborts an accepted turn that stops producing app-server progress before a terminal event
+   - returns payloads + usage metadata
+4. `subscribeEmbeddedPiSession` bridges pi-agent-core events to Nodmix `agent` stream:
+   - tool events => `stream: "tool"`
+   - assistant deltas => `stream: "assistant"`
+   - lifecycle events => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
+5. `agent.wait` uses `waitForAgentRun`:
+   - waits for **lifecycle end/error** for `runId`
+   - returns `{ status: ok|error|timeout, startedAt, endedAt, error? }`
+
+## Queueing + concurrency
+
+- Runs are serialized per session key (session lane) and optionally through a global lane.
+- This prevents tool/session races and keeps session history consistent.
+- Messaging channels can choose queue modes (steer/followup/collect/interrupt) that feed this lane system.
+  See [Command Queue](/concepts/queue).
+- Transcript writes are also protected by a session write lock on the session file. The lock is
+  process-aware and file-based, so it catches writers that bypass the in-process queue or come from
+  another process. Session transcript writers wait up to `session.writeLock.acquireTimeoutMs`
+  before reporting the session as busy; the default is `60000` ms.
+- Session write locks are non-reentrant by default. If a helper intentionally nests acquisition of
+  the same lock while preserving one logical writer, it must opt in explicitly with
+  `allowReentrant: true`.
+
+## Session + workspace preparation
+
+- Workspace is resolved and created; sandboxed runs may redirect to a sandbox workspace root.
+- Skills are loaded (or reused from a snapshot) and injected into env and prompt.
+- Bootstrap/context files are resolved and injected into the system prompt report.
+- A session write lock is acquired; `SessionManager` is opened and prepared before streaming. Any
+  later transcript rewrite, compaction, or truncation path must take the same lock before opening or
+  mutating the transcript file.
+
+## Prompt assembly + system prompt
+
+- System prompt is built from Nodmix's base prompt, skills prompt, bootstrap context, and per-run overrides.
+- Model-specific limits and compaction reserve tokens are enforced.
+- See [System prompt](/concepts/system-prompt) for what the model sees.
+
+## Hook points (where you can intercept)
+
+Nodmix has two hook systems:
+
+- **Internal hooks** (Gateway hooks): event-driven scripts for commands and lifecycle events.
+- **Plugin hooks**: extension points inside the agent/tool lifecycle and gateway pipeline.
+
+### Internal hooks (Gateway hooks)
+
+- **`agent:bootstrap`**: runs while building bootstrap files before the system prompt is finalized.
+  Use this to add/remove bootstrap context files.
+- **Command hooks**: `/new`, `/reset`, `/stop`, and other command events (see Hooks doc).
+
+See [Hooks](/automation/hooks) for setup and examples.
+
+### Plugin hooks (agent + gateway lifecycle)
+
+These run inside the agent loop or gateway pipeline:
+
+- **`before_model_resolve`**: runs pre-session (no `messages`) to deterministically override provider/model before model resolution.
+- **`before_prompt_build`**: runs after session load (with `messages`) to inject `prependContext`, `systemPrompt`, `prependSystemContext`, or `appendSystemContext` before prompt submission. Use `prependContext` for per-turn dynamic text and system-context fields for stable guidance that should sit in system prompt space.
+- **`before_agent_start`**: legacy compatibility hook that may run in either phase; prefer the explicit hooks above.
+- **`before_agent_reply`**: runs after inline actions and before the LLM call, letting a plugin claim the turn and return a synthetic reply or silence the turn entirely.
+- **`agent_end`**: inspect the final message list and run metadata after completion.
+- **`before_compaction` / `after_compaction`**: observe or annotate compaction cycles.
+- **`before_tool_call` / `after_tool_call`**: intercept tool params/results.
+- **`before_install`**: inspect built-in scan findings and optionally block skill or plugin installs.
+- **`tool_result_persist`**: synchronously transform tool results before they are written to an Nodmix-owned session transcript.
+- **`message_received` / `message_sending` / `message_sent`**: inbound + outbound message hooks.
+- **`session_start` / `session_end`**: session lifecycle boundaries.
+- **`gateway_start` / `gateway_stop`**: gateway lifecycle events.
+
+Hook decision rules for outbound/tool guards:
+
+- `before_tool_call`: `{ block: true }` is terminal and stops lower-priority handlers.
+- `before_tool_call`: `{ block: false }` is a no-op and does not clear a prior block.
+- `before_install`: `{ block: true }` is terminal and stops lower-priority handlers.
+- `before_install`: `{ block: false }` is a no-op and does not clear a prior block.
+- `message_sending`: `{ cancel: true }` is terminal and stops lower-priority handlers.
+- `message_sending`: `{ cancel: false }` is a no-op and does not clear a prior cancel.
+
+See [Plugin hooks](/plugins/hooks) for the hook API and registration details.
+
+Harnesses may adapt these hooks differently. The Codex app-server harness keeps
+Nodmix plugin hooks as the compatibility contract for documented mirrored
+surfaces, while Codex native hooks remain a separate lower-level Codex mechanism.
+
+## Streaming + partial replies
+
+- Assistant deltas are streamed from pi-agent-core and emitted as `assistant` events.
+- Block streaming can emit partial replies either on `text_end` or `message_end`.
+- Reasoning streaming can be emitted as a separate stream or as block replies.
+- See [Streaming](/concepts/streaming) for chunking and block reply behavior.
+
+## Tool execution + messaging tools
+
+- Tool start/update/end events are emitted on the `tool` stream.
+- Tool results are sanitized for size and image payloads before logging/emitting.
+- Messaging tool sends are tracked to suppress duplicate assistant confirmations.
+
+## Reply shaping + suppression
+
+- Final payloads are assembled from:
+  - assistant text (and optional reasoning)
+  - inline tool summaries (when verbose + allowed)
+  - assistant error text when the model errors
+- The exact silent token `NO_REPLY` / `no_reply` is filtered from outgoing
+  payloads.
+- Messaging tool duplicates are removed from the final payload list.
+- If no renderable payloads remain and a tool errored, a fallback tool error reply is emitted
+  (unless a messaging tool already sent a user-visible reply).
+
+## Compaction + retries
+
+- Auto-compaction emits `compaction` stream events and can trigger a retry.
+- On retry, in-memory buffers and tool summaries are reset to avoid duplicate output.
+- See [Compaction](/concepts/compaction) for the compaction pipeline.
+
+## Event streams (today)
+
+- `lifecycle`: emitted by `subscribeEmbeddedPiSession` (and as a fallback by `agentCommand`)
+- `assistant`: streamed deltas from pi-agent-core
+- `tool`: streamed tool events from pi-agent-core
+
+## Chat channel handling
+
+- Assistant deltas are buffered into chat `delta` messages.
+- A chat `final` is emitted on **lifecycle end/error**.
+
+## Timeouts
+
+- `agent.wait` default: 30s (just the wait). `timeoutMs` param overrides.
+- Agent runtime: `agents.defaults.timeoutSeconds` default 172800s (48 hours); enforced in `runEmbeddedPiAgent` abort timer.
+- Cron runtime: isolated agent-turn `timeoutSeconds` is owned by cron. The scheduler starts that timer when execution begins, aborts the underlying run at the configured deadline, then runs bounded cleanup before recording the timeout so a stale child session cannot keep the lane stuck.
+- Session liveness diagnostics: with diagnostics enabled, `diagnostics.stuckSessionWarnMs` classifies long `processing` sessions that have no observed reply, tool, status, block, or ACP progress. Active embedded runs, model calls, and tool calls report as `session.long_running`; active work with no recent progress reports as `session.stalled`; `session.stuck` is reserved for stale session bookkeeping with no active work. Stale session bookkeeping releases the affected session lane immediately; stalled embedded runs are abort-drained only after `diagnostics.stuckSessionAbortMs` (default: at least 5 minutes and 3x the warning threshold) so queued work can resume without cutting off merely slow runs. Recovery emits structured requested/completed outcomes, and diagnostic state is marked idle only if the same processing generation is still current. Repeated `session.stuck` diagnostics back off while the session remains unchanged.
+- Model idle timeout: Nodmix aborts a model request when no response chunks arrive before the idle window. `models.providers.<id>.timeoutSeconds` extends this idle watchdog for slow local/self-hosted providers, but it is still bounded by any lower `agents.defaults.timeoutSeconds` or run-specific timeout because those control the whole agent run. Otherwise Nodmix uses `agents.defaults.timeoutSeconds` when configured, capped at 120s by default. Cron-triggered runs with no explicit model or agent timeout disable the idle watchdog and rely on the cron outer timeout.
+- Provider HTTP request timeout: `models.providers.<id>.timeoutSeconds` applies to that provider's model HTTP fetches, including connect, headers, body, SDK request timeout, total guarded-fetch abort handling, and model stream idle watchdog. Use this for slow local/self-hosted providers such as Ollama before raising the whole agent runtime timeout, and keep the agent/runtime timeout at least as high when the model request needs to run longer.
+
+## Where things can end early
+
+- Agent timeout (abort)
+- AbortSignal (cancel)
+- Gateway disconnect or RPC timeout
+- `agent.wait` timeout (wait-only, does not stop agent)
+
+## Related
+
+- [Tools](/tools) — available agent tools
+- [Hooks](/automation/hooks) — event-driven scripts triggered by agent lifecycle events
+- [Compaction](/concepts/compaction) — how long conversations are summarized
+- [Exec Approvals](/tools/exec-approvals) — approval gates for shell commands
+- [Thinking](/tools/thinking) — thinking/reasoning level configuration

package/docs/concepts/agent-runtimes.md

@@ -0,0 +1,243 @@
+---
+summary: "How Nodmix separates model providers, models, channels, and agent runtimes"
+title: "Agent runtimes"
+read_when:
+  - You are choosing between PI, Codex, ACP, or another native agent runtime
+  - You are confused by provider/model/runtime labels in status or config
+  - You are documenting support parity for a native harness
+---
+
+An **agent runtime** is the component that owns one prepared model loop: it
+receives the prompt, drives model output, handles native tool calls, and returns
+the finished turn to Nodmix.
+
+Runtimes are easy to confuse with providers because both show up near model
+configuration. They are different layers:
+
+| Layer         | Examples                              | What it means                                                       |
+| ------------- | ------------------------------------- | ------------------------------------------------------------------- |
+| Provider      | `openai`, `anthropic`, `openai-codex` | How Nodmix authenticates, discovers models, and names model refs. |
+| Model         | `gpt-5.5`, `claude-opus-4-6`          | The model selected for the agent turn.                              |
+| Agent runtime | `pi`, `codex`, `claude-cli`           | The low level loop or backend that executes the prepared turn.      |
+| Channel       | Telegram, Discord, Slack, WhatsApp    | Where messages enter and leave Nodmix.                            |
+
+You will also see the word **harness** in code. A harness is the implementation
+that provides an agent runtime. For example, the bundled Codex harness
+implements the `codex` runtime. Public config uses `agentRuntime.id` on
+provider or model entries; whole-agent runtime keys are legacy and ignored.
+`nodmix doctor --fix` removes old whole-agent runtime pins and rewrites
+legacy runtime model refs to canonical provider/model refs plus model-scoped
+runtime policy where needed.
+
+There are two runtime families:
+
+- **Embedded harnesses** run inside Nodmix's prepared agent loop. Today this
+  is the built-in `pi` runtime plus registered plugin harnesses such as
+  `codex`.
+- **CLI backends** run a local CLI process while keeping the model ref
+  canonical. For example, `anthropic/claude-opus-4-7` with
+  a model-scoped `agentRuntime.id: "claude-cli"` means "select the Anthropic
+  model, execute through Claude CLI." `claude-cli` is not an embedded harness id
+  and must not be passed to AgentHarness selection.
+
+## Codex surfaces
+
+Most confusion comes from several different surfaces sharing the Codex name:
+
+| Surface                                          | Nodmix name/config                 | What it does                                                                                                   |
+| ------------------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| Native Codex app-server runtime                  | `openai/*` model refs                | Runs OpenAI embedded agent turns through Codex app-server. This is the usual ChatGPT/Codex subscription setup. |
+| Codex OAuth auth profiles                        | `openai-codex` auth provider         | Stores ChatGPT/Codex subscription auth that the Codex app-server harness consumes.                             |
+| Codex ACP adapter                                | `runtime: "acp"`, `agentId: "codex"` | Runs Codex through the external ACP/acpx control plane. Use only when ACP/acpx is explicitly asked.            |
+| Native Codex chat-control command set            | `/codex ...`                         | Binds, resumes, steers, stops, and inspects Codex app-server threads from chat.                                |
+| OpenAI Platform API route for non-agent surfaces | `openai/*` plus API-key auth         | Used for direct OpenAI APIs such as images, embeddings, speech, and realtime.                                  |
+
+Those surfaces are intentionally independent. Enabling the `codex` plugin makes
+the native app-server features available; `nodmix doctor --fix` owns legacy
+`openai-codex/*` route repair and stale session pin cleanup. Selecting
+`openai/*` for an agent model now means "run this through Codex" unless a
+non-agent OpenAI API surface is being used.
+
+The common ChatGPT/Codex subscription setup uses Codex OAuth for auth, but keeps
+the model ref as `openai/*` and selects the `codex` runtime:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: "openai/gpt-5.5",
+    },
+  },
+}
+```
+
+That means Nodmix selects an OpenAI model ref, then asks the Codex app-server
+runtime to run the embedded agent turn. It does not mean "use API billing," and
+it does not mean the channel, model provider catalog, or Nodmix session store
+becomes Codex.
+
+When the bundled `codex` plugin is enabled, natural-language Codex control
+should use the native `/codex` command surface (`/codex bind`, `/codex threads`,
+`/codex resume`, `/codex steer`, `/codex stop`) instead of ACP. Use ACP for
+Codex only when the user explicitly asks for ACP/acpx or is testing the ACP
+adapter path. Claude Code, Gemini CLI, OpenCode, Cursor, and similar external
+harnesses still use ACP.
+
+This is the agent-facing decision tree:
+
+1. If the user asks for **Codex bind/control/thread/resume/steer/stop**, use the
+   native `/codex` command surface when the bundled `codex` plugin is enabled.
+2. If the user asks for **Codex as the embedded runtime** or wants the normal
+   subscription-backed Codex agent experience, use `openai/<model>`.
+3. If the user explicitly chooses **PI for an OpenAI model**, keep the model ref
+   as `openai/<model>` and set provider/model runtime policy to
+   `agentRuntime.id: "pi"`. A selected `openai-codex` auth profile is routed
+   internally through PI's legacy Codex-auth transport.
+4. If legacy config still contains **`openai-codex/*` model refs**, repair it to
+   `openai/<model>` with `nodmix doctor --fix`; doctor keeps the Codex auth
+   route by adding provider/model-scoped `agentRuntime.id: "codex"` where the
+   old model ref implied it.
+   Legacy **`codex-cli/*` model refs** repair to the same `openai/<model>` Codex
+   app-server route; Nodmix no longer keeps a bundled Codex CLI backend.
+5. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use
+   ACP with `runtime: "acp"` and `agentId: "codex"`.
+6. If the request is for **Claude Code, Gemini CLI, OpenCode, Cursor, Droid, or
+   another external harness**, use ACP/acpx, not the native sub-agent runtime.
+
+| You mean...                             | Use...                                       |
+| --------------------------------------- | -------------------------------------------- |
+| Codex app-server chat/thread control    | `/codex ...` from the bundled `codex` plugin |
+| Codex app-server embedded agent runtime | `openai/*` agent model refs                  |
+| OpenAI Codex OAuth                      | `openai-codex` auth profiles                 |
+| Claude Code or other external harness   | ACP/acpx                                     |
+
+For the OpenAI-family prefix split, see [OpenAI](/providers/openai) and
+[Model providers](/concepts/model-providers). For the Codex runtime support
+contract, see [Codex harness runtime](/plugins/codex-harness-runtime#v1-support-contract).
+
+## Runtime ownership
+
+Different runtimes own different amounts of the loop.
+
+| Surface                     | Nodmix PI embedded                    | Codex app-server                                                            |
+| --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
+| Model loop owner            | Nodmix through the PI embedded runner | Codex app-server                                                            |
+| Canonical thread state      | Nodmix transcript                     | Codex thread, plus Nodmix transcript mirror                               |
+| Nodmix dynamic tools      | Native Nodmix tool loop               | Bridged through the Codex adapter                                           |
+| Native shell and file tools | PI/Nodmix path                        | Codex-native tools, bridged through native hooks where supported            |
+| Context engine              | Native Nodmix context assembly        | Nodmix projects assembled context into the Codex turn                     |
+| Compaction                  | Nodmix or selected context engine     | Codex-native compaction, with Nodmix notifications and mirror maintenance |
+| Channel delivery            | Nodmix                                | Nodmix                                                                    |
+
+This ownership split is the main design rule:
+
+- If Nodmix owns the surface, Nodmix can provide normal plugin hook behavior.
+- If the native runtime owns the surface, Nodmix needs runtime events or native hooks.
+- If the native runtime owns canonical thread state, Nodmix should mirror and project context, not rewrite unsupported internals.
+
+## Runtime selection
+
+Nodmix chooses an embedded runtime after provider and model resolution:
+
+1. Model-scoped runtime policy wins. This can live in a configured provider
+   model entry or in `agents.defaults.models["provider/model"].agentRuntime` /
+   `agents.list[].models["provider/model"].agentRuntime`. A provider wildcard
+   such as `agents.defaults.models["vllm/*"].agentRuntime` applies after exact
+   model policy, so dynamically discovered provider models can share one
+   runtime without overriding exact per-model exceptions.
+2. Provider-scoped runtime policy comes next at
+   `models.providers.<provider>.agentRuntime`.
+3. In `auto` mode, registered plugin runtimes can claim supported provider/model
+   pairs.
+4. If no runtime claims a turn in `auto` mode, Nodmix uses PI as the
+   compatibility runtime. Use an explicit runtime id when the run must be
+   strict.
+
+Whole-session and whole-agent runtime pins are ignored. That includes
+`NODMIX_AGENT_RUNTIME`, session `agentHarnessId`/`agentRuntimeOverride` state,
+`agents.defaults.agentRuntime`, and `agents.list[].agentRuntime`. Run
+`nodmix doctor --fix` to remove stale whole-agent runtime config and convert
+legacy runtime model refs where Nodmix can preserve the intent.
+
+Explicit provider/model plugin runtimes fail closed. For example,
+`agentRuntime.id: "codex"` on a provider or model means Codex or a clear
+selection/runtime error; it is never silently routed back to PI.
+
+CLI backend aliases are different from embedded harness ids. The preferred
+Claude CLI form is:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: "anthropic/claude-opus-4-7",
+      models: {
+        "anthropic/claude-opus-4-7": {
+          agentRuntime: { id: "claude-cli" },
+        },
+      },
+    },
+  },
+}
+```
+
+Legacy refs such as `claude-cli/claude-opus-4-7` remain supported for
+compatibility, but new config should keep the provider/model canonical and put
+the execution backend in provider/model runtime policy.
+
+Legacy `codex-cli/*` refs are different: doctor migrates them to `openai/*` so
+they run through the Codex app-server harness instead of preserving a Codex CLI
+backend.
+
+`auto` mode is intentionally conservative for most providers. OpenAI agent
+models are the exception: unset runtime and `auto` both resolve to the Codex
+harness. Explicit PI runtime config remains an opt-in compatibility route for
+`openai/*` agent turns; when paired with a selected `openai-codex` auth profile,
+Nodmix routes PI internally through the legacy Codex-auth transport while
+keeping the public model ref as `openai/*`. Stale OpenAI PI session pins are
+ignored by runtime selection and can be cleaned with `nodmix doctor --fix`.
+
+If `nodmix doctor` warns that the `codex` plugin is enabled while
+`openai-codex/*` remains in config, treat that as legacy route state. Run
+`nodmix doctor --fix` to rewrite it to `openai/*` with the Codex runtime.
+
+## Compatibility contract
+
+When a runtime is not PI, it should document what Nodmix surfaces it supports.
+Use this shape for runtime docs:
+
+| Question                               | Why it matters                                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Who owns the model loop?               | Determines where retries, tool continuation, and final answer decisions happen.                   |
+| Who owns canonical thread history?     | Determines whether Nodmix can edit history or only mirror it.                                   |
+| Do Nodmix dynamic tools work?        | Messaging, sessions, cron, and Nodmix-owned tools rely on this.                                 |
+| Do dynamic tool hooks work?            | Plugins expect `before_tool_call`, `after_tool_call`, and middleware around Nodmix-owned tools. |
+| Do native tool hooks work?             | Shell, patch, and runtime-owned tools need native hook support for policy and observation.        |
+| Does the context engine lifecycle run? | Memory and context plugins depend on assemble, ingest, after-turn, and compaction lifecycle.      |
+| What compaction data is exposed?       | Some plugins only need notifications, while others need kept/dropped metadata.                    |
+| What is intentionally unsupported?     | Users should not assume PI equivalence where the native runtime owns more state.                  |
+
+The Codex runtime support contract is documented in
+[Codex harness runtime](/plugins/codex-harness-runtime#v1-support-contract).
+
+## Status labels
+
+Status output may show both `Execution` and `Runtime` labels. Read them as
+diagnostics, not as provider names.
+
+- A model ref such as `openai/gpt-5.5` tells you the selected provider/model.
+- A runtime id such as `codex` tells you which loop is executing the turn.
+- A channel label such as Telegram or Discord tells you where the conversation is happening.
+
+If a run still shows an unexpected runtime, inspect the selected provider/model
+runtime policy first. Legacy session runtime pins no longer decide routing.
+
+## Related
+
+- [Codex harness](/plugins/codex-harness)
+- [Codex harness runtime](/plugins/codex-harness-runtime)
+- [OpenAI](/providers/openai)
+- [Agent harness plugins](/plugins/sdk-agent-harness)
+- [Agent loop](/concepts/agent-loop)
+- [Models](/concepts/models)
+- [Status](/cli/status)

package/docs/concepts/agent-workspace.md

@@ -0,0 +1,230 @@
+---
+summary: "Agent workspace: location, layout, and backup strategy"
+read_when:
+  - You need to explain the agent workspace or its file layout
+  - You want to back up or migrate an agent workspace
+title: "Agent workspace"
+sidebarTitle: "Agent workspace"
+---
+
+The workspace is the agent's home. It is the only working directory used for file tools and for workspace context. Keep it private and treat it as memory.
+
+This is separate from `~/.nodmix/`, which stores config, credentials, and sessions.
+
+<Warning>
+The workspace is the **default cwd**, not a hard sandbox. Tools resolve relative paths against the workspace, but absolute paths can still reach elsewhere on the host unless sandboxing is enabled. If you need isolation, use [`agents.defaults.sandbox`](/gateway/sandboxing) (and/or per-agent sandbox config).
+
+When sandboxing is enabled and `workspaceAccess` is not `"rw"`, tools operate inside a sandbox workspace under `~/.nodmix/sandboxes`, not your host workspace.
+</Warning>
+
+## Default location
+
+- Default: `~/.nodmix/workspace`
+- If `NODMIX_PROFILE` is set and not `"default"`, the default becomes `~/.nodmix/workspace-<profile>`.
+- Override in `~/.nodmix/nodmix.json`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      workspace: "~/.nodmix/workspace",
+    },
+  },
+}
+```
+
+`nodmix onboard`, `nodmix configure`, or `nodmix setup` will create the workspace and seed the bootstrap files if they are missing.
+
+<Note>
+Sandbox seed copies only accept regular in-workspace files; symlink/hardlink aliases that resolve outside the source workspace are ignored.
+</Note>
+
+If you already manage the workspace files yourself, you can disable bootstrap file creation:
+
+```json5
+{ agents: { defaults: { skipBootstrap: true } } }
+```
+
+## Extra workspace folders
+
+Older installs may have created `~/nodmix`. Keeping multiple workspace directories around can cause confusing auth or state drift, because only one workspace is active at a time.
+
+<Note>
+**Recommendation:** keep a single active workspace. If you no longer use the extra folders, archive or move them to Trash (for example `trash ~/nodmix`). If you intentionally keep multiple workspaces, make sure `agents.defaults.workspace` points to the active one.
+
+`nodmix doctor` warns when it detects extra workspace directories.
+</Note>
+
+## Workspace file map
+
+These are the standard files Nodmix expects inside the workspace:
+
+<AccordionGroup>
+  <Accordion title="AGENTS.md - operating instructions">
+    Operating instructions for the agent and how it should use memory. Loaded at the start of every session. Good place for rules, priorities, and "how to behave" details.
+  </Accordion>
+  <Accordion title="SOUL.md - persona and tone">
+    Persona, tone, and boundaries. Loaded every session. Guide: [SOUL.md personality guide](/concepts/soul).
+  </Accordion>
+  <Accordion title="USER.md - who the user is">
+    Who the user is and how to address them. Loaded every session.
+  </Accordion>
+  <Accordion title="IDENTITY.md - name, vibe, emoji">
+    The agent's name, vibe, and emoji. Created/updated during the bootstrap ritual.
+  </Accordion>
+  <Accordion title="TOOLS.md - local tool conventions">
+    Notes about your local tools and conventions. Does not control tool availability; it is only guidance.
+  </Accordion>
+  <Accordion title="HEARTBEAT.md - heartbeat checklist">
+    Optional tiny checklist for heartbeat runs. Keep it short to avoid token burn.
+  </Accordion>
+  <Accordion title="BOOT.md - startup checklist">
+    Optional startup checklist run automatically on gateway restart (when [internal hooks](/automation/hooks) are enabled). Keep it short; use the message tool for outbound sends.
+  </Accordion>
+  <Accordion title="BOOTSTRAP.md - first-run ritual">
+    One-time first-run ritual. Only created for a brand-new workspace. Delete it after the ritual is complete.
+  </Accordion>
+  <Accordion title="memory/YYYY-MM-DD.md - daily memory log">
+    Daily memory log (one file per day). Recommended to read today + yesterday on session start.
+  </Accordion>
+  <Accordion title="MEMORY.md - curated long-term memory (optional)">
+    Curated long-term memory: durable facts, preferences, decisions, and short summaries. Keep detailed logs in `memory/YYYY-MM-DD.md` so memory tools can retrieve them on demand without injecting them into every prompt. Only load `MEMORY.md` in the main, private session (not shared/group contexts). See [Memory](/concepts/memory) for the workflow and automatic memory flush.
+  </Accordion>
+  <Accordion title="skills/ - workspace skills (optional)">
+    Workspace-specific skills. Highest-precedence skill location for that workspace. Overrides project agent skills, personal agent skills, managed skills, bundled skills, and `skills.load.extraDirs` when names collide.
+  </Accordion>
+  <Accordion title="canvas/ - Canvas UI files (optional)">
+    Canvas UI files for node displays (for example `canvas/index.html`).
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+If any bootstrap file is missing, Nodmix injects a "missing file" marker into the session and continues. Large bootstrap files are truncated when injected; adjust limits with `agents.defaults.bootstrapMaxChars` (default: 12000) and `agents.defaults.bootstrapTotalMaxChars` (default: 60000). `nodmix setup` can recreate missing defaults without overwriting existing files.
+</Note>
+
+## What is NOT in the workspace
+
+These live under `~/.nodmix/` and should NOT be committed to the workspace repo:
+
+- `~/.nodmix/nodmix.json` (config)
+- `~/.nodmix/agents/<agentId>/agent/auth-profiles.json` (model auth profiles: OAuth + API keys)
+- `~/.nodmix/agents/<agentId>/agent/codex-home/` (per-agent Codex runtime account, config, skills, plugins, and native thread state)
+- `~/.nodmix/credentials/` (channel/provider state plus legacy OAuth import data)
+- `~/.nodmix/agents/<agentId>/sessions/` (session transcripts + metadata)
+- `~/.nodmix/skills/` (managed skills)
+
+If you need to migrate sessions or config, copy them separately and keep them out of version control.
+
+## Git backup (recommended, private)
+
+Treat the workspace as private memory. Put it in a **private** git repo so it is backed up and recoverable.
+
+Run these steps on the machine where the Gateway runs (that is where the workspace lives).
+
+<Steps>
+  <Step title="Initialize the repo">
+    If git is installed, brand-new workspaces are initialized automatically. If this workspace is not already a repo, run:
+
+    ```bash
+    cd ~/.nodmix/workspace
+    git init
+    git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
+    git commit -m "Add agent workspace"
+    ```
+
+  </Step>
+  <Step title="Add a private remote">
+    <Tabs>
+      <Tab title="GitHub web UI">
+        1. Create a new **private** repository on GitHub.
+        2. Do not initialize with a README (avoids merge conflicts).
+        3. Copy the HTTPS remote URL.
+        4. Add the remote and push:
+
+        ```bash
+        git branch -M main
+        git remote add origin <https-url>
+        git push -u origin main
+        ```
+      </Tab>
+      <Tab title="GitHub CLI (gh)">
+        ```bash
+        gh auth login
+        gh repo create nodmix-workspace --private --source . --remote origin --push
+        ```
+      </Tab>
+      <Tab title="GitLab web UI">
+        1. Create a new **private** repository on GitLab.
+        2. Do not initialize with a README (avoids merge conflicts).
+        3. Copy the HTTPS remote URL.
+        4. Add the remote and push:
+
+        ```bash
+        git branch -M main
+        git remote add origin <https-url>
+        git push -u origin main
+        ```
+      </Tab>
+    </Tabs>
+
+  </Step>
+  <Step title="Ongoing updates">
+    ```bash
+    git status
+    git add .
+    git commit -m "Update memory"
+    git push
+    ```
+  </Step>
+</Steps>
+
+## Do not commit secrets
+
+<Warning>
+Even in a private repo, avoid storing secrets in the workspace:
+
+- API keys, OAuth tokens, passwords, or private credentials.
+- Anything under `~/.nodmix/`.
+- Raw dumps of chats or sensitive attachments.
+
+If you must store sensitive references, use placeholders and keep the real secret elsewhere (password manager, environment variables, or `~/.nodmix/`).
+</Warning>
+
+Suggested `.gitignore` starter:
+
+```gitignore
+.DS_Store
+.env
+**/*.key
+**/*.pem
+**/secrets*
+```
+
+## Moving the workspace to a new machine
+
+<Steps>
+  <Step title="Clone the repo">
+    Clone the repo to the desired path (default `~/.nodmix/workspace`).
+  </Step>
+  <Step title="Update config">
+    Set `agents.defaults.workspace` to that path in `~/.nodmix/nodmix.json`.
+  </Step>
+  <Step title="Seed missing files">
+    Run `nodmix setup --workspace <path>` to seed any missing files.
+  </Step>
+  <Step title="Copy sessions (optional)">
+    If you need sessions, copy `~/.nodmix/agents/<agentId>/sessions/` from the old machine separately.
+  </Step>
+</Steps>
+
+## Advanced notes
+
+- Multi-agent routing can use different workspaces per agent. See [Channel routing](/channels/channel-routing) for routing configuration.
+- If `agents.defaults.sandbox` is enabled, non-main sessions can use per-session sandbox workspaces under `agents.defaults.sandbox.workspaceRoot`.
+
+## Related
+
+- [Heartbeat](/gateway/heartbeat) - HEARTBEAT.md workspace file
+- [Sandboxing](/gateway/sandboxing) - workspace access in sandboxed environments
+- [Session](/concepts/session) - session storage paths
+- [Standing orders](/automation/standing-orders) - persistent instructions in workspace files