fengming 0.3.10 → 0.3.12

package/docs/concepts/streaming.md

@@ -1,257 +0,0 @@
----
-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"
----
-
-FengMing 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, FengMing 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, FengMing 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, FengMing 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 `fengming 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 `fengming 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, FengMing 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.
-
-Long-running tools may emit typed progress before they return. For example,
-`web_fetch` arms a five-second timer when it starts: if the fetch is still
-pending, the preview can show `Fetching page content...`; if the fetch finishes
-or is canceled before then, no progress line is emitted. The later final tool
-result is still delivered normally to the model.
-
-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 FengMing'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, FengMing 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

@@ -1,328 +0,0 @@
----
-summary: "What the FengMing 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"
----
-
-FengMing builds a custom system prompt for every agent run. The prompt is **FengMing-owned** and does not use a runtime default prompt.
-
-The prompt is assembled by FengMing 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 FengMing-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.
-- **FengMing Control**: tells the model to prefer the `gateway` tool for
-  config/restart work and to avoid inventing CLI commands.
-- **FengMing 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 FengMing 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.
-
-FengMing 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
-
-FengMing 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**, **FengMing
-  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, FengMing 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
-
-FengMing 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,
-FengMing developer instructions, turn-scoped collaboration-mode instructions
-when FengMing 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 FengMing 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, FengMing 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. The compact FengMing skills list is also forwarded
-as turn-scoped collaboration 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` content from the configured agent
-workspace is not pasted into every native Codex turn; when memory tools are
-available for that workspace, Codex turns get a small workspace-memory note in
-turn-scoped collaboration developer instructions and should use `memory_search`
-or `memory_get` when durable memory is relevant. If tools are disabled, memory
-search is unavailable, or the active workspace differs from the agent memory
-workspace, `MEMORY.md` falls back to the normal bounded turn-context path. Active
-`BOOTSTRAP.md` content keeps the normal turn-context role for now.
-
-On non-Codex harnesses, bootstrap files continue to be composed into the
-FengMing 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 non-Codex `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
-non-Codex `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, FengMing 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.
-On native Codex, `MEMORY.md` is read on demand through memory tools when
-available, with bounded prompt fallback when tools cannot run. On other
-harnesses, the model only sees the shortened injected copy until it reads or
-searches memory directly. If `MEMORY.md` is repeatedly truncated there, 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, FengMing 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.
-
-Native Codex turns receive this list as turn-scoped collaboration developer
-instructions instead of per-turn user input, except lightweight cron turns that
-preserve the exact scheduled prompt. Other harnesses keep the normal prompt
-section.
-
-The location can point at a nested skill, such as
-`skills/personal/foo/SKILL.md`. Nesting is only organizational; the prompt still
-uses the flat skill name from `SKILL.md` frontmatter.
-
-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 FengMing docs directory (`docs/` in a Git checkout or the bundled npm
-package docs). If local docs are unavailable, it falls back to
-[https://docs.fengming.ai](https://docs.fengming.ai).
-
-The same section also includes the FengMing 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 FengMing behavior, commands, configuration, or architecture, and to
-run `fengming 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

@@ -1,47 +0,0 @@
----
-summary: "Where timezones show up in FengMing — 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"
----
-
-FengMing 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 Sun 2026-01-18 00:19:42 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, FengMing 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.