nodmix 2026.5.25

package/docs/concepts/streaming.md

@@ -0,0 +1,251 @@
+---
+summary: "Streaming + chunking behavior (block replies, channel preview streaming, mode mapping)"
+read_when:
+  - Explaining how streaming or chunking works on channels
+  - Changing block streaming or channel chunking behavior
+  - Debugging duplicate/early block replies or channel preview streaming
+title: "Streaming and chunking"
+---
+
+Nodmix has two separate streaming layers:
+
+- **Block streaming (channels):** emit completed **blocks** as the assistant writes. These are normal channel messages (not token deltas).
+- **Preview streaming (Telegram/Discord/Slack):** update a temporary **preview message** while generating.
+
+There is **no true token-delta streaming** to channel messages today. Preview streaming is message-based (send + edits/appends).
+
+## Block streaming (channel messages)
+
+Block streaming sends assistant output in coarse chunks as it becomes available.
+
+```
+Model output
+  └─ text_delta/events
+       ├─ (blockStreamingBreak=text_end)
+       │    └─ chunker emits blocks as buffer grows
+       └─ (blockStreamingBreak=message_end)
+            └─ chunker flushes at message_end
+                   └─ channel send (block replies)
+```
+
+Legend:
+
+- `text_delta/events`: model stream events (may be sparse for non-streaming models).
+- `chunker`: `EmbeddedBlockChunker` applying min/max bounds + break preference.
+- `channel send`: actual outbound messages (block replies).
+
+**Controls:**
+
+- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (default off).
+- Channel overrides: `*.blockStreaming` (and per-account variants) to force `"on"`/`"off"` per channel.
+- `agents.defaults.blockStreamingBreak`: `"text_end"` or `"message_end"`.
+- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
+- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (merge streamed blocks before send).
+- Channel hard cap: `*.textChunkLimit` (e.g., `channels.whatsapp.textChunkLimit`).
+- Channel chunk mode: `*.chunkMode` (`length` default, `newline` splits on blank lines (paragraph boundaries) before length chunking).
+- Discord soft cap: `channels.discord.maxLinesPerMessage` (default 17) splits tall replies to avoid UI clipping.
+
+**Boundary semantics:**
+
+- `text_end`: stream blocks as soon as chunker emits; flush on each `text_end`.
+- `message_end`: wait until assistant message finishes, then flush buffered output.
+
+`message_end` still uses the chunker if the buffered text exceeds `maxChars`, so it can emit multiple chunks at the end.
+
+### Media delivery with block streaming
+
+`MEDIA:` directives are normal delivery metadata. When block streaming sends a
+media block early, Nodmix remembers that delivery for the turn. If the final
+assistant payload repeats the same media URL, the final delivery strips the
+duplicate media instead of sending the attachment again.
+
+Exact duplicate final payloads are suppressed. If the final payload adds
+distinct text around media that was already streamed, Nodmix still sends the
+new text while keeping the media single-delivery. This prevents duplicate voice
+notes or files on channels such as Telegram when an agent emits `MEDIA:` during
+streaming and the provider also includes it in the completed reply.
+
+## Chunking algorithm (low/high bounds)
+
+Block chunking is implemented by `EmbeddedBlockChunker`:
+
+- **Low bound:** don't emit until buffer >= `minChars` (unless forced).
+- **High bound:** prefer splits before `maxChars`; if forced, split at `maxChars`.
+- **Break preference:** `paragraph` → `newline` → `sentence` → `whitespace` → hard break.
+- **Code fences:** never split inside fences; when forced at `maxChars`, close + reopen the fence to keep Markdown valid.
+
+`maxChars` is clamped to the channel `textChunkLimit`, so you can't exceed per-channel caps.
+
+## Coalescing (merge streamed blocks)
+
+When block streaming is enabled, Nodmix can **merge consecutive block chunks**
+before sending them out. This reduces "single-line spam" while still providing
+progressive output.
+
+- Coalescing waits for **idle gaps** (`idleMs`) before flushing.
+- Buffers are capped by `maxChars` and will flush if they exceed it.
+- `minChars` prevents tiny fragments from sending until enough text accumulates
+  (final flush always sends remaining text).
+- Joiner is derived from `blockStreamingChunk.breakPreference`
+  (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → space).
+- Channel overrides are available via `*.blockStreamingCoalesce` (including per-account configs).
+- Default coalesce `minChars` is bumped to 1500 for Signal/Slack/Discord unless overridden.
+
+## Human-like pacing between blocks
+
+When block streaming is enabled, you can add a **randomized pause** between
+block replies (after the first block). This makes multi-bubble responses feel
+more natural.
+
+- Config: `agents.defaults.humanDelay` (override per agent via `agents.list[].humanDelay`).
+- Modes: `off` (default), `natural` (800-2500ms), `custom` (`minMs`/`maxMs`).
+- Applies only to **block replies**, not final replies or tool summaries.
+
+## "Stream chunks or everything"
+
+This maps to:
+
+- **Stream chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emit as you go). Non-Telegram channels also need `*.blockStreaming: true`.
+- **Stream everything at end:** `blockStreamingBreak: "message_end"` (flush once, possibly multiple chunks if very long).
+- **No block streaming:** `blockStreamingDefault: "off"` (only final reply).
+
+**Channel note:** Block streaming is **off unless**
+`*.blockStreaming` is explicitly set to `true`. Channels can stream a live preview
+(`channels.<channel>.streaming`) without block replies.
+
+Config location reminder: the `blockStreaming*` defaults live under
+`agents.defaults`, not the root config.
+
+## Preview streaming modes
+
+Canonical key: `channels.<channel>.streaming`
+
+Modes:
+
+- `off`: disable preview streaming.
+- `partial`: single preview that is replaced with latest text.
+- `block`: preview updates in chunked/appended steps.
+- `progress`: progress/status preview during generation, final answer at completion.
+
+`streaming.mode: "block"` is a preview-streaming mode for edit-capable channels
+such as Discord and Telegram. It does not enable channel block delivery there.
+Use `streaming.block.enabled` or the legacy `blockStreaming` channel key when
+you want normal block replies. Microsoft Teams is the exception: it has no
+draft-preview block transport, so `streaming.mode: "block"` maps to Teams block
+delivery instead of native partial/progress streaming.
+
+### Channel mapping
+
+| Channel    | `off` | `partial` | `block` | `progress`              |
+| ---------- | ----- | --------- | ------- | ----------------------- |
+| Telegram   | ✅    | ✅        | ✅      | editable progress draft |
+| Discord    | ✅    | ✅        | ✅      | editable progress draft |
+| Slack      | ✅    | ✅        | ✅      | ✅                      |
+| Mattermost | ✅    | ✅        | ✅      | ✅                      |
+| MS Teams   | ✅    | ✅        | ✅      | native progress stream  |
+
+Slack-only:
+
+- `channels.slack.streaming.nativeTransport` toggles Slack native streaming API calls when `channels.slack.streaming.mode="partial"` (default: `true`).
+- Slack native streaming and Slack assistant thread status require a reply thread target. Top-level DMs do not show that thread-style preview, but they can still use Slack draft preview posts and edits.
+
+Legacy key migration:
+
+- Telegram: legacy `streamMode` and scalar/boolean `streaming` values are detected and migrated by doctor/config compatibility paths to `streaming.mode`.
+- Discord: `streamMode` + boolean `streaming` remain runtime aliases for the `streaming` enum; run `nodmix doctor --fix` to rewrite persisted config.
+- Slack: `streamMode` remains a runtime alias for `streaming.mode`; boolean `streaming` remains a runtime alias for `streaming.mode` plus `streaming.nativeTransport`; legacy `nativeStreaming` remains a runtime alias for `streaming.nativeTransport`. Run `nodmix doctor --fix` to rewrite persisted config.
+
+### Runtime behavior
+
+Telegram:
+
+- Uses `sendMessage` + `editMessageText` preview updates across DMs and group/topics.
+- Final text edits the active preview in place; long finals reuse that message for the first chunk and send only the remaining chunks.
+- `progress` mode keeps tool progress in an editable status draft, clears that draft at completion, and sends the final answer through normal delivery.
+- If the final edit fails before the completed text is confirmed, Nodmix uses normal final delivery and cleans up the stale preview.
+- Preview streaming is skipped when Telegram block streaming is explicitly enabled (to avoid double-streaming).
+- `/reasoning stream` can write reasoning to a transient preview that is deleted after final delivery.
+
+Discord:
+
+- Uses send + edit preview messages.
+- `block` mode uses draft chunking (`draftChunk`).
+- Preview streaming is skipped when Discord block streaming is explicitly enabled.
+- Final media, error, and explicit-reply payloads cancel pending previews without flushing a new draft, then use normal delivery.
+
+Slack:
+
+- `partial` can use Slack native streaming (`chat.startStream`/`append`/`stop`) when available.
+- `block` uses append-style draft previews.
+- `progress` uses status preview text, then final answer.
+- Top-level DMs without a reply thread use draft preview posts and edits instead of Slack native streaming.
+- Native and draft preview streaming suppress block replies for that turn, so a Slack reply is streamed by one delivery path only.
+- Final media/error payloads and progress finals do not create throwaway draft messages; only text/block finals that can edit the preview flush pending draft text.
+
+Mattermost:
+
+- Streams thinking, tool activity, and partial reply text into a single draft preview post that finalizes in place when the final answer is safe to send.
+- Falls back to sending a fresh final post if the preview post was deleted or is otherwise unavailable at finalize time.
+- Final media/error payloads cancel pending preview updates before normal delivery instead of flushing a temporary preview post.
+
+Matrix:
+
+- Draft previews finalize in place when the final text can reuse the preview event.
+- Media-only, error, and reply-target-mismatch finals cancel pending preview updates before normal delivery; an already-visible stale preview is redacted.
+
+### Tool-progress preview updates
+
+Preview streaming can also include **tool-progress** updates - short status lines like "searching the web", "reading file", or "calling tool" - that appear in the same preview message while tools are running, ahead of the final reply. In Codex app-server mode, Codex preamble/commentary messages use this same preview path, so short "I am checking..." progress notes can stream into the editable draft without becoming part of the final answer. This keeps multi-step tool turns visually alive rather than silent between the first thinking preview and the final answer.
+
+Supported surfaces:
+
+- **Discord**, **Slack**, **Telegram**, and **Matrix** stream tool-progress and Codex preamble updates into the live preview edit by default when preview streaming is active. Microsoft Teams uses its native progress stream in personal chats.
+- Telegram has shipped with tool-progress preview updates enabled since `v2026.4.22`; keeping them enabled preserves that released behavior.
+- **Mattermost** already folds tool activity into its single draft preview post (see above).
+- Tool-progress edits follow the active preview streaming mode; they are skipped when preview streaming is `off` or when block streaming has taken over the message. On Telegram, `streaming.mode: "off"` is final-only: generic progress chatter is also suppressed instead of being delivered as standalone status messages, while approval prompts, media payloads, and errors still route normally.
+- To keep preview streaming but hide tool-progress lines, set `streaming.preview.toolProgress` to `false` for that channel. To keep tool-progress lines visible while hiding command/exec text, set `streaming.preview.commandText` to `"status"` or `streaming.progress.commandText` to `"status"`; the default is `"raw"` to preserve released behavior. This policy is shared by draft/progress channels that use Nodmix's compact progress renderer, including Discord, Matrix, Microsoft Teams, Mattermost, Slack draft previews, and Telegram. To disable preview edits entirely, set `streaming.mode` to `off`.
+- Telegram selected quote replies are an exception: when `replyToMode` is not `"off"` and selected quote text is present, Nodmix skips the answer preview stream for that turn so tool-progress preview lines cannot render. Current-message replies without selected quote text still keep preview streaming. See [Telegram channel docs](/channels/telegram) for details.
+
+Keep progress lines visible but hide raw command/exec text:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "streaming": {
+        "mode": "partial",
+        "preview": {
+          "toolProgress": true,
+          "commandText": "status"
+        }
+      }
+    }
+  }
+}
+```
+
+Use the same shape under another compact progress channel key, for example `channels.discord`, `channels.matrix`, `channels.msteams`, `channels.mattermost`, or Slack draft previews. For progress-draft mode, put the same policy under `streaming.progress`:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "streaming": {
+        "mode": "progress",
+        "progress": {
+          "toolProgress": true,
+          "commandText": "status"
+        }
+      }
+    }
+  }
+}
+```
+
+## Related
+
+- [Message lifecycle refactor](/concepts/message-lifecycle-refactor) - target shared preview, edit, stream, and finalization design
+- [Progress drafts](/concepts/progress-drafts) - visible work-in-progress messages that update during long turns
+- [Messages](/concepts/messages) - message lifecycle and delivery
+- [Retry](/concepts/retry) - retry behavior on delivery failure
+- [Channels](/channels) - per-channel streaming support

package/docs/concepts/system-prompt.md

@@ -0,0 +1,310 @@
+---
+summary: "What the Nodmix system prompt contains and how it is assembled"
+read_when:
+  - Editing system prompt text, tools list, or time/heartbeat sections
+  - Changing workspace bootstrap or skills injection behavior
+title: "System prompt"
+---
+
+Nodmix builds a custom system prompt for every agent run. The prompt is **Nodmix-owned** and does not use the pi-coding-agent default prompt.
+
+The prompt is assembled by Nodmix and injected into each agent run.
+
+Prompt assembly has three layers:
+
+- `buildAgentSystemPrompt` renders the prompt from explicit inputs. It should
+  stay a pure renderer and should not read global config directly.
+- `resolveAgentSystemPromptConfig` resolves config-backed prompt knobs such as
+  owner display, TTS hints, model aliases, memory citation mode, and sub-agent
+  delegation mode for a specific agent.
+- Runtime adapters (embedded, CLI, command/export previews, compaction) gather
+  live facts such as tools, sandbox state, channel capabilities, context files,
+  and provider prompt contributions, then call the configured prompt facade.
+
+This keeps exported/debug prompt surfaces aligned with live runs without
+turning every runtime-specific detail into one monolithic builder.
+
+Provider plugins can contribute cache-aware prompt guidance without replacing
+the full Nodmix-owned prompt. The provider runtime can:
+
+- replace a small set of named core sections (`interaction_style`,
+  `tool_call_style`, `execution_bias`)
+- inject a **stable prefix** above the prompt cache boundary
+- inject a **dynamic suffix** below the prompt cache boundary
+
+Use provider-owned contributions for model-family-specific tuning. Keep legacy
+`before_prompt_build` prompt mutation for compatibility or truly global prompt
+changes, not normal provider behavior.
+
+The OpenAI GPT-5 family overlay keeps the core execution rule small and adds
+model-specific guidance for persona latching, concise output, tool discipline,
+parallel lookup, deliverable coverage, verification, missing context, and
+terminal-tool hygiene.
+
+## Structure
+
+The prompt is intentionally compact and uses fixed sections:
+
+- **Tooling**: structured-tool source-of-truth reminder plus runtime tool-use guidance.
+- **Execution Bias**: compact follow-through guidance: act in-turn on
+  actionable requests, continue until done or blocked, recover from weak tool
+  results, check mutable state live, and verify before finalizing.
+- **Safety**: short guardrail reminder to avoid power-seeking behavior or bypassing oversight.
+- **Skills** (when available): tells the model how to load skill instructions on demand.
+- **Nodmix Control**: tells the model to prefer the `gateway` tool for
+  config/restart work and to avoid inventing CLI commands.
+- **Nodmix Self-Update**: how to inspect config safely with
+  `config.schema.lookup`, patch config with `config.patch`, replace the full
+  config with `config.apply`, and run `update.run` only on explicit user
+  request. The agent-facing `gateway` tool also refuses to rewrite
+  `tools.exec.ask` / `tools.exec.security`, including legacy `tools.bash.*`
+  aliases that normalize to those protected exec paths.
+- **Workspace**: working directory (`agents.defaults.workspace`).
+- **Documentation**: local path to Nodmix docs/source and when to read them.
+- **Workspace Files (injected)**: indicates bootstrap files are included below.
+- **Sandbox** (when enabled): indicates sandboxed runtime, sandbox paths, and whether elevated exec is available.
+- **Current Date & Time**: time zone only (cache-stable; the live clock comes from `session_status`).
+- **Assistant Output Directives**: compact attachment, voice-note, and reply tag syntax.
+- **Heartbeats**: heartbeat prompt and ack behavior, when heartbeats are enabled for the default agent.
+- **Runtime**: host, OS, node, model, repo root (when detected), thinking level (one line).
+- **Reasoning**: current visibility level + /reasoning toggle hint.
+
+Nodmix keeps large stable content, including **Project Context**, above the
+internal prompt cache boundary. Volatile channel/session sections such as
+Control UI embed guidance, **Messaging**, **Voice**, **Group Chat Context**,
+**Reactions**, **Heartbeats**, and **Runtime** are appended below that boundary
+so local backends with prefix caches can reuse the stable workspace prefix
+across channel turns. Tool descriptions should likewise avoid embedding current
+channel names when the accepted schema already carries that runtime detail.
+
+The Tooling section also includes runtime guidance for long-running work:
+
+- use cron for future follow-up (`check back later`, reminders, recurring work)
+  instead of `exec` sleep loops, `yieldMs` delay tricks, or repeated `process`
+  polling
+- use `exec` / `process` only for commands that start now and continue running
+  in the background
+- when automatic completion wake is enabled, start the command once and rely on
+  the push-based wake path when it emits output or fails
+- use `process` for logs, status, input, or intervention when you need to
+  inspect a running command
+- if the task is larger, prefer `sessions_spawn`; sub-agent completion is
+  push-based and auto-announces back to the requester
+- do not poll `subagents list` / `sessions_list` in a loop just to wait for
+  completion
+
+`agents.defaults.subagents.delegationMode` can strengthen this guidance. The
+default `suggest` mode keeps the baseline nudge. `prefer` adds a dedicated
+**Sub-Agent Delegation** section telling the main agent to act as a responsive
+coordinator and push anything more involved than a direct reply through
+`sessions_spawn`. This is prompt-only; tool policy still controls whether
+`sessions_spawn` is available.
+
+When the experimental `update_plan` tool is enabled, Tooling also tells the
+model to use it only for non-trivial multi-step work, keep exactly one
+`in_progress` step, and avoid repeating the whole plan after each update.
+
+Safety guardrails in the system prompt are advisory. They guide model behavior but do not enforce policy. Use tool policy, exec approvals, sandboxing, and channel allowlists for hard enforcement; operators can disable these by design.
+
+On channels with native approval cards/buttons, the runtime prompt now tells the
+agent to rely on that native approval UI first. It should only include a manual
+`/approve` command when the tool result says chat approvals are unavailable or
+manual approval is the only path.
+
+## Prompt modes
+
+Nodmix can render smaller system prompts for sub-agents. The runtime sets a
+`promptMode` for each run (not a user-facing config):
+
+- `full` (default): includes all sections above.
+- `minimal`: used for sub-agents; omits **Memory Recall**, **Nodmix
+  Self-Update**, **Model Aliases**, **User Identity**, **Assistant Output Directives**,
+  **Messaging**, **Silent Replies**, and **Heartbeats**. Tooling, **Safety**,
+  **Skills** when supplied, Workspace, Sandbox, Current Date & Time (when
+  known), Runtime, and injected context stay available.
+- `none`: returns only the base identity line.
+
+When `promptMode=minimal`, extra injected prompts are labeled **Subagent
+Context** instead of **Group Chat Context**.
+
+For channel auto-reply runs, Nodmix omits the generic **Silent Replies**
+section when direct, group, or message-tool-only context owns the visible-reply
+contract. Only old automatic group/channel mode should show `NO_REPLY`; direct
+chats and message-tool-only replies do not receive silent-token guidance.
+
+## Prompt snapshots
+
+Nodmix keeps committed prompt snapshots for the Codex runtime happy path under
+`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. They render
+selected app-server thread/turn params plus a reconstructed model-bound prompt
+layer stack for Telegram direct, Discord group, and heartbeat turns. That stack
+includes a pinned Codex `gpt-5.5` model prompt fixture generated from Codex's
+model catalog/cache shape, the Codex happy-path permission developer text,
+Nodmix developer instructions, turn-scoped collaboration-mode instructions
+when Nodmix provides them, user turn input, and references to the dynamic tool
+specs.
+
+Refresh the pinned Codex model prompt fixture with
+`pnpm prompt:snapshots:sync-codex-model`. By default, the script looks for
+Codex's runtime cache at `$CODEX_HOME/models_cache.json`, then
+`~/.codex/models_cache.json`, and only then falls back to the maintainer Codex
+checkout convention at `~/code/codex/codex-rs/models-manager/models.json`. If
+none of those sources exist, the command exits without changing the committed
+fixture. Pass `--catalog <path>` to refresh from a specific `models_cache.json`
+or `models.json` file.
+
+These snapshots are still not a byte-for-byte raw OpenAI request capture. Codex
+can add runtime-owned workspace context such as `AGENTS.md`, environment
+context, memories, app/plugin instructions, and built-in Default
+collaboration-mode instructions inside the Codex runtime after Nodmix sends
+thread and turn params.
+
+Regenerate them with `pnpm prompt:snapshots:gen` and verify drift with
+`pnpm prompt:snapshots:check`. CI runs the drift check in the additional
+boundary shard so prompt changes and snapshot updates stay attached to the same
+PR.
+
+## Workspace bootstrap injection
+
+Bootstrap files are resolved from the active workspace, then routed to the
+prompt surface that matches their lifetime:
+
+- `AGENTS.md`
+- `SOUL.md`
+- `TOOLS.md`
+- `IDENTITY.md`
+- `USER.md`
+- `HEARTBEAT.md`
+- `BOOTSTRAP.md` (only on brand-new workspaces)
+- `MEMORY.md` when present
+
+On the native Codex harness, Nodmix avoids repeating stable workspace files
+in every user turn. Codex loads `AGENTS.md` through its own project-doc
+discovery. `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` are forwarded as
+Codex developer instructions. `HEARTBEAT.md` content is not injected; heartbeat
+turns get a collaboration-mode note pointing to the file when it exists and is
+non-empty. `MEMORY.md` and active `BOOTSTRAP.md` content keep the normal
+turn-context role for now.
+
+On non-Codex harnesses, bootstrap files continue to be composed into the
+Nodmix prompt according to their existing gates. `HEARTBEAT.md` is omitted on
+normal runs when heartbeats are disabled for the default agent or
+`agents.defaults.heartbeat.includeSystemPromptSection` is false. Keep injected
+files concise, especially `MEMORY.md`. `MEMORY.md` is intended to stay a curated
+long-term summary; detailed daily notes belong in `memory/*.md` where
+`memory_search` and `memory_get` can retrieve them on demand. Oversized
+`MEMORY.md` files increase prompt usage and can be partially injected because of
+the bootstrap file limits below.
+
+<Note>
+`memory/*.md` daily files are **not** part of the normal bootstrap Project Context. On ordinary turns they are accessed on demand via the `memory_search` and `memory_get` tools, so they do not count against the context window unless the model explicitly reads them. Bare `/new` and `/reset` turns are the exception: the runtime can prepend recent daily memory as a one-shot startup-context block for that first turn.
+</Note>
+
+Large files are truncated with a marker. The max per-file size is controlled by
+`agents.defaults.bootstrapMaxChars` (default: 12000). Total injected bootstrap
+content across files is capped by `agents.defaults.bootstrapTotalMaxChars`
+(default: 60000). Missing files inject a short missing-file marker. When truncation
+occurs, Nodmix can inject a concise system-prompt warning notice; control this with
+`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
+default: `always`). Detailed raw/injected counts stay in diagnostics such as
+`/context`, `/status`, doctor, and logs.
+
+For memory files, truncation is not data loss: the file remains intact on disk,
+but the model only sees the shortened injected copy until it reads or searches
+memory directly. If `MEMORY.md` is repeatedly truncated, distill it into a
+shorter durable summary and move detailed history into `memory/*.md`, or
+intentionally raise the bootstrap limits.
+
+Sub-agent sessions only inject `AGENTS.md` and `TOOLS.md` (other bootstrap files
+are filtered out to keep the sub-agent context small).
+
+Internal hooks can intercept this step via `agent:bootstrap` to mutate or replace
+the injected bootstrap files (for example swapping `SOUL.md` for an alternate persona).
+
+If you want to make the agent sound less generic, start with
+[SOUL.md Personality Guide](/concepts/soul).
+
+To inspect how much each injected file contributes (raw vs injected, truncation, plus tool schema overhead), use `/context list` or `/context detail`. See [Context](/concepts/context).
+
+## Time handling
+
+The system prompt includes a dedicated **Current Date & Time** section when the
+user timezone is known. To keep the prompt cache-stable, it now only includes
+the **time zone** (no dynamic clock or time format).
+
+Use `session_status` when the agent needs the current time; the status card
+includes a timestamp line. The same tool can optionally set a per-session model
+override (`model=default` clears it).
+
+Configure with:
+
+- `agents.defaults.userTimezone`
+- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
+
+See [Date & Time](/date-time) for full behavior details.
+
+## Skills
+
+When eligible skills exist, Nodmix injects a compact **available skills list**
+(`formatSkillsForPrompt`) that includes the **file path** for each skill. The
+prompt instructs the model to use `read` to load the SKILL.md at the listed
+location (workspace, managed, or bundled). If no skills are eligible, the
+Skills section is omitted.
+
+Eligibility includes skill metadata gates, runtime environment/config checks,
+and the effective agent skill allowlist when `agents.defaults.skills` or
+`agents.list[].skills` is configured.
+
+Plugin-bundled skills are eligible only when their owning plugin is enabled.
+This lets tool plugins expose deeper operating guides without embedding all of
+that guidance directly in every tool description.
+
+```
+<available_skills>
+  <skill>
+    <name>...</name>
+    <description>...</description>
+    <location>...</location>
+  </skill>
+</available_skills>
+```
+
+This keeps the base prompt small while still enabling targeted skill usage.
+
+The skills list budget is owned by the skills subsystem:
+
+- Global default: `skills.limits.maxSkillsPromptChars`
+- Per-agent override: `agents.list[].skillsLimits.maxSkillsPromptChars`
+
+Generic bounded runtime excerpts use a different surface:
+
+- `agents.defaults.contextLimits.*`
+- `agents.list[].contextLimits.*`
+
+That split keeps skills sizing separate from runtime read/injection sizing such
+as `memory_get`, live tool results, and post-compaction AGENTS.md refreshes.
+
+## Documentation
+
+The system prompt includes a **Documentation** section. When local docs are available, it
+points to the local Nodmix docs directory (`docs/` in a Git checkout or the bundled npm
+package docs). If local docs are unavailable, it falls back to
+[https://docs.nodmix.ai](https://docs.nodmix.ai).
+
+The same section also includes the Nodmix source location. Git checkouts expose the local
+source root so the agent can inspect code directly. Package installs include the GitHub
+source URL and tell the agent to review source there whenever the docs are incomplete or
+stale. The prompt also notes the public docs mirror, community Discord, and ClawHub
+([https://clawhub.ai](https://clawhub.ai)) for skills discovery. It tells the model to
+consult docs first for Nodmix behavior, commands, configuration, or architecture, and to
+run `nodmix status` itself when possible (asking the user only when it lacks access).
+For configuration specifically, it points agents to the `gateway` tool action
+`config.schema.lookup` for exact field-level docs and constraints, then to
+`docs/gateway/configuration.md` and `docs/gateway/configuration-reference.md`
+for broader guidance.
+
+## Related
+
+- [Agent runtime](/concepts/agent)
+- [Agent workspace](/concepts/agent-workspace)
+- [Context engine](/concepts/context-engine)

package/docs/concepts/timezone.md

@@ -0,0 +1,47 @@
+---
+summary: "Where timezones show up in Nodmix — envelopes, tool payloads, system prompt"
+read_when:
+  - You want a quick mental model for timezone handling
+  - You are deciding where to set or override a timezone
+title: "Timezones"
+---
+
+Nodmix standardizes timestamps so the model sees a **single reference time** instead of a mix of provider-local clocks. There are three surfaces where timezones show up, each with its own purpose:
+
+## Three timezone surfaces
+
+| Surface           | What it shows                                                                                           | Default                               | Configured via                                          |
+| ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------- |
+| Message envelopes | Wraps inbound channel messages: `[Signal +1555 2026-01-18 00:19 PST] hello`                             | Host-local                            | `agents.defaults.envelopeTimezone`                      |
+| Tool payloads     | Channel `readMessages`-style tools return raw provider time + normalized `timestampMs` / `timestampUtc` | UTC fields always present             | Not configurable — preserves provider-native timestamps |
+| System prompt     | A small `Current Date & Time` block with the **time zone only** (no clock value, for cache stability)   | Host timezone if `userTimezone` unset | `agents.defaults.userTimezone`                          |
+
+The system prompt deliberately omits the live clock to keep prompt caching stable across turns. When the agent needs the current time, it calls `session_status`.
+
+## Setting the user timezone
+
+```json5
+{
+  agents: {
+    defaults: {
+      userTimezone: "America/Chicago",
+    },
+  },
+}
+```
+
+If `userTimezone` is unset, Nodmix resolves the host timezone at runtime (no config write). `agents.defaults.timeFormat` (`auto` | `12` | `24`) controls 12h/24h rendering in envelopes and downstream surfaces, not in the system prompt section.
+
+## When to override
+
+- **Use UTC envelopes** (`envelopeTimezone: "utc"`) when you want stable timestamps across hosts in different regions, or when you want UTC-aligned logs to match diagnostics output.
+- **Use a fixed IANA zone** (e.g. `"Europe/Vienna"`) when the gateway host is in one zone but the user is in another and you want envelopes to read in the user's zone regardless of host migration.
+- **Set `envelopeTimestamp: "off"`** for low-token envelopes when timestamp context is not useful for the conversation.
+
+For the full behavior reference, examples per provider, and elapsed-time formatting, see [Date & Time](/date-time).
+
+## Related
+
+- [Date & Time](/date-time) — full envelope/tool/prompt behavior and examples.
+- [Heartbeat](/gateway/heartbeat) — active hours use timezone for scheduling.
+- [Cron Jobs](/automation/cron-jobs) — cron expressions use timezone for scheduling.