better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/programmatic-integration.md

@@ -0,0 +1,212 @@
+---
+sidebar_position: 8
+title: "Programmatic Integration"
+description: "Three protocols for driving hermes-agent from external programs: ACP, the TUI gateway JSON-RPC, and the OpenAI-compatible HTTP API"
+---
+
+# Programmatic Integration
+
+Hermes ships three protocols for driving the agent from external programs — IDE plugins, custom UIs, CI pipelines, embedded sub-agents. Pick the one that matches your transport and consumer.
+
+| Protocol | Transport | Best for | Defined by |
+|----------|-----------|----------|------------|
+| **ACP** | JSON-RPC over stdio | IDE clients (VS Code, Zed, JetBrains) that already speak the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) | `acp_adapter/` |
+| **TUI gateway** | JSON-RPC over stdio (or WebSocket) | Custom hosts that want fine-grained control of sessions, slash commands, approvals, and streaming events | `tui_gateway/server.py` |
+| **API server** | HTTP + Server-Sent Events | OpenAI-compatible frontends (Open WebUI, LobeChat, LibreChat…) and language-agnostic web clients | `gateway/platforms/api_server.py` |
+
+All three drive the same `AIAgent` core. They differ only in wire format and which set of features they expose.
+
+---
+
+## ACP (Agent Client Protocol)
+
+`hermes acp` starts a stdio JSON-RPC server speaking ACP. Used in production by VS Code (Zed Industries' ACP extension), Zed, and any JetBrains IDE with an ACP plugin.
+
+Capabilities exposed: session creation, prompt submission, streaming agent message chunks, tool-call events, permission requests, session fork, cancel, and authentication. Tool output is rendered into ACP `Diff`/`ToolCall` content blocks the IDE understands.
+
+Full lifecycle, event bridge, and approval flow: [ACP Internals](./acp-internals).
+
+```bash
+hermes acp                  # serve ACP on stdio
+hermes acp --check          # verify ACP dependencies and adapter imports
+hermes acp --setup          # interactive provider/model setup for ACP terminal auth
+```
+
+---
+
+## TUI Gateway JSON-RPC
+
+`tui_gateway/server.py` is the protocol the Ink TUI (`hermes --tui`) and the embedded dashboard PTY bridge talk to. Any external host can speak the same protocol over stdio (or WebSocket via `tui_gateway/ws.py`).
+
+### Method catalog (selected)
+
+```
+prompt.submit           prompt.background       session.steer
+session.create          session.list            session.active_list
+session.activate        session.close           session.interrupt
+session.history         session.compress        session.branch
+session.title           session.usage           session.status
+clarify.lock            config.set / config.get commands.catalog
+command.resolve         command.dispatch        cli.exec
+reload.mcp              reload.env              process.stop
+delegation.status       subagent.interrupt      subagent.steer
+spawn_tree.save / list / load
+terminal.resize         clipboard.paste         image.attach
+```
+
+`session.active_list`, `session.activate`, and `session.close` are the process-local live-session controls used by the TUI session switcher. Use `session.list` / `/resume` for saved transcript discovery; use the active-session methods only for sessions that are currently open in the TUI gateway process.
+
+Within one authenticated gateway, resuming or activating a live session attaches another event subscriber rather than replacing the previous connection. Streaming and terminal events go to all attached clients; disconnecting one client does not end a session another client is viewing. Existing submit exclusivity and configured busy-input policy remain in force. Attached clients can steer the session's subagents; browser-controller results still require the connection that registered that controller. This does not enable independent gateway processes to write the same session, nor does it imply durable prompt admission across an owner restart.
+
+### Rewinding history on `prompt.submit`
+
+A rewind / edit / regenerate is a `prompt.submit` that drops part of the stored transcript before running the new turn. Because that write is a destructive rewrite of the session's durable rows, the gateway honors it only when the client states its intent:
+
+| Parameter | Meaning |
+|-----------|---------|
+| `truncate_before_user_ordinal` | Zero-based index of the user turn to cut at. Everything from that turn onward is dropped. Display-only timeline rows (`display_kind`) are not counted. Must be a real integer — a JSON boolean is refused with code `4004`. |
+| `truncate_before_row_id` | Integer SQLite row ID (`messages.id` / `row_id`) of the target user turn to cut at. Preferred durable address. When both ordinal and row ID are provided, gateway verifies they match (returning `4030` on mismatch). An unknown/stale row ID is refused with `4018` — it does **not** fall back to the ordinal. |
+| `confirm_truncate` | Required whenever an ordinal, message ID, or row ID is sent. Declares that this submit really is a rewind, not an ordinary send that happens to carry leftover parameters. Sending it without a target is refused with code `4004`. |
+| `confirm_empty_truncate` | Additionally required when the cut would leave the transcript empty (ordinal `0`). |
+
+A truncation parameter without `confirm_truncate` is refused with code `4004` or `4029` and nothing is written. Hosts that implement rewind must set the flag at the moment the user asks for it, and must never keep truncation parameters in state across ordinary submits. Prefer `truncate_before_row_id` (from resume `row_id` / `_row_id`) over ordinals; keep the ordinal as a back-compat / optimistic-row path only when no durable id is available yet.
+
+On a successful truncating submit against a durable session, the `prompt.submit` result additionally carries `survivor_user_row_ids` — the fresh post-rewrite row IDs of the surviving user turns, in visible-user-ordinal order. The rewrite re-inserts the kept prefix as new rows, so every row ID the host cached before the rewind is stale afterward; rebind cached IDs from this list (a `null` entry means that turn has no durable ID — drop the cached one) or the next rewind targeting an older surviving turn will be refused with `4018`.
+
+### Events streamed back
+
+`message.delta`, `message.complete`, `tool.start`, `tool.generating`, `tool.complete`, `gateway.ready`, `request.cancel`, plus session lifecycle and error events.
+
+### Server→client requests (questions the agent asks you)
+
+Approvals, clarify questions, sudo/secret prompts, vault unlock, MCP setup and the desktop read/act bridges are **JSON-RPC requests from the gateway to the client**, not events. The frame carries a string id, and the client answers with a normal JSON-RPC response bearing the same id:
+
+```
+← {"jsonrpc":"2.0","id":"srq-7","method":"approval","params":{"session_id":"…","request_id":"…","command":"rm -rf build","description":"…"}}
+→ {"jsonrpc":"2.0","id":"srq-7","result":{"choice":"once"}}
+```
+
+Methods: `approval` → `{choice}`; `clarify` → `{answer}` (single) or `{answers}` / `{}` cancel (batch, with `clarify.lock` to lock one answer early); `sudo`, `secret`, `vault.code`, `vault.unlock` → `{value}`; `connection` → `{settled_by, targets}` (the `manage_connections` card: one outcome per target); `terminal.read`, `window.read`, `preview.act`, `tour` → `{value}` (JSON text). Respond with a JSON-RPC error (`-32601`) for a method your host does not implement so the agent fails fast instead of waiting out the timeout.
+
+When the gateway withdraws a question (timeout, interrupt, answered from another surface) it emits `request.cancel` `{ id, method, reason }`; clear only the matching prompt. `session.resume` / `session.activate` results and `session.events.since` carry `open_requests` — the still-open frames — so a reconnecting client re-renders (and can still answer) them.
+
+### Pi-style RPC mapping
+
+Every command in the Pi-mono RPC spec ([issue #360](https://github.com/NousResearch/hermes-agent/issues/360)) has a TUI-gateway equivalent:
+
+| Pi command | Hermes equivalent |
+|------------|-------------------|
+| `prompt` | `prompt.submit` (or ACP `session/prompt`) |
+| `steer` | `session.steer` |
+| `follow_up` | `prompt.submit` queued after current turn |
+| `abort` | `session.interrupt` |
+| `set_model` | `command.dispatch` for `/model <provider:model>` (mid-session, persistent) |
+| `compact` | `session.compress` |
+| `get_state` | `session.status` |
+| `get_messages` | `session.history` |
+| `switch_session` | `session.resume` |
+| `fork` | `session.branch` |
+| `ui_request` / `ui_response` | server→client requests `clarify` / `sudo` / `secret` / `approval` answered by JSON-RPC response frames |
+
+---
+
+## OpenAI-Compatible API Server
+
+`gateway/platforms/api_server.py` exposes hermes over HTTP for any client that already speaks the OpenAI format. Useful when you want a web frontend, a curl-driven CI runner, or a non-Python consumer.
+
+Endpoints:
+
+```
+POST /v1/chat/completions        OpenAI Chat Completions (streaming via SSE)
+POST /v1/responses               OpenAI Responses API (stateful)
+POST /v1/runs                    Start a run, returns run_id (202)
+GET  /v1/runs/{id}               Run status
+GET  /v1/runs/{id}/events        SSE stream of lifecycle events
+POST /v1/runs/{id}/approval      Resolve a pending approval
+POST /v1/runs/{id}/steer         Inject mid-run guidance at the next tool boundary
+POST /v1/runs/{id}/stop          Interrupt the run
+GET  /v1/capabilities            Machine-readable feature flags
+POST /v1/browser-control/register Register a browser controller
+GET  /v1/browser-control/ws       Browser-controller WebSocket
+GET  /v1/models                  Lists hermes-agent
+GET  /api/model/options          Provider-aware picker inventory
+GET  /health, /health/detailed
+```
+
+Setup, headers (`X-Hermes-Session-Id`, `X-Hermes-Session-Key`), and frontend wiring: [API Server](../user-guide/features/api-server).
+
+Browser extensions can opt into the disabled-by-default controller protocol to
+drive the exact browser session that opened the Hermes conversation. The API
+and dashboard transports share one principal-bound broker and one explicit
+capability allowlist; see [Browser-extension control](../user-guide/features/api-server#browser-extension-control).
+
+### Model catalog surfaces
+
+The OpenAI-compatible API intentionally keeps `GET /v1/models` minimal: it is
+the compatibility endpoint frontends expect, not the full Hermes provider/model
+picker catalog.
+
+If an external control plane needs Hermes' curated provider rows, per-model
+pricing, or capability hints, use one of the authenticated picker surfaces:
+
+- API server REST: `GET /api/model/options` with the API-server bearer key
+- Dashboard backend REST: `GET /api/model/options` with `X-Hermes-Session-Token`
+- TUI gateway RPC: `model.options`
+
+Those surfaces share the same payload builder and the same custom-provider
+probe policy:
+
+- Normal open: probe only the current custom provider so offline saved
+  endpoints do not stall the picker.
+- Explicit refresh (`refresh=1` or `refresh: true`): bust the provider-model
+  cache and probe all saved custom providers so live catalogs repopulate fully.
+
+Use `/v1/models` for OpenAI-client compatibility. Use `/api/model/options` or
+`model.options` when you are building a Hermes-aware model picker.
+
+`POST /v1/runs/{id}/steer` is the HTTP equivalent of Hermes `/steer`: it does not create a new user turn or immediately rewrite the assistant output already in flight. Instead, the text is appended to the live run and becomes visible to the agent after the next tool boundary, so it can course-correct without discarding the current tool-calling loop.
+
+`/v1/runs/{id}/steer` is only accepted while the run status is `running`. Queued, approval-paused, stopping, cancelled, failed, and completed runs return `409 run_not_accepting_steer`, even if the server still retains internal agent references during cooperative shutdown.
+
+A `200` (and the `run.steered` event) means the text was **queued**, not that the agent consumed it. If a steer lands after the agent's final response — with no later tool boundary to deliver it at — the undelivered text is returned as `pending_steer` on the terminal event (`run.completed`, `run.failed`, or `run.cancelled`) and run status, so the client can replay it as the next user turn instead of losing it.
+
+#### Terminal run status
+
+The terminal status of a run is derived from how the agent's turn actually ended, and the terminal event name always matches it (`run.<status>`):
+
+| Turn outcome | Status | Terminal event | Flags on the event / status |
+|---|---|---|---|
+| Final answer produced | `completed` | `run.completed` | `completed: true` |
+| Interrupted (`/stop`, or an interrupt inside the agent) | `cancelled` | `run.cancelled` | `completed: false`, `interrupted: true` |
+| Provider/agent failure | `failed` | `run.failed` | `completed: false`, `error` |
+| Ended without finishing (iteration budget, truncated or partial reply) | `failed` | `run.failed` | `completed: false`, `partial` when applicable, `turn_exit_reason` (e.g. `max_iterations_reached(60/60)`), `output` with any fallback text |
+
+A run is never reported as `completed` with `completed: false` or `partial: true` in the same payload. The same rule applies to `/api/sessions/{id}/chat/stream`, whose `assistant.completed` payload carries the real `completed` / `partial` / `interrupted` flags and whose terminal event is `run.completed`, `run.failed`, or `run.cancelled`.
+
+---
+
+## Which one should I use?
+
+- **You're writing an IDE plugin and the IDE already speaks ACP** → ACP. Zero protocol work on the IDE side.
+- **You're writing a custom desktop / web / TUI host and want every Hermes feature** (slash commands, approvals, clarify, multi-agent, session branching) → TUI gateway JSON-RPC.
+- **You want any OpenAI-compatible frontend, a language-agnostic HTTP client, or curl-driven automation** → API server.
+- **You want a Python in-process embed without a subprocess** → import `run_agent.AIAgent` directly. See [Agent Loop](./agent-loop).
+
+---
+
+## Model hot-swapping
+
+Mid-session model switching works on every surface — it's the `/model` slash command under the hood.
+
+- **CLI / TUI:** `/model claude-sonnet-4` or `/model openrouter:anthropic/claude-sonnet-4.6`
+- **TUI gateway RPC:** `command.dispatch` with `{"command": "/model claude-sonnet-4"}`
+- **ACP:** the IDE sends the slash command as a prompt; the agent dispatches it
+- **API server:** include a `model` field in the request body
+
+Provider-aware resolution (the same model name picks the right format for whatever provider you're on) is built in. See `hermes_cli/model_switch.py`.
+
+---
+
+## A note on `--mode rpc`
+
+Hermes does not have a `--mode rpc` flag. The three protocols above already cover the use cases — ACP for IDE-protocol clients, the TUI gateway for stdio JSON-RPC hosts, and the API server for HTTP. If you find a real gap that none of them fill, open an issue with the concrete consumer you're building.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/prompt-assembly.md

@@ -0,0 +1,328 @@
+---
+sidebar_position: 5
+title: "Prompt Assembly"
+description: "How Hermes builds the system prompt, preserves cache stability, and injects ephemeral layers"
+---
+
+# Prompt Assembly
+
+Hermes deliberately separates:
+
+- **cached system prompt state**
+- **ephemeral API-call-time additions**
+
+This is one of the most important design choices in the project because it affects:
+
+- token usage
+- prompt caching effectiveness
+- session continuity
+- memory correctness
+
+Primary files:
+
+- `run_agent.py`
+- `agent/prompt_builder.py`
+- `tools/memory_tool.py`
+
+## Cached system prompt layers
+
+The cached system prompt is assembled as three ordered tiers (see `agent/system_prompt.py`):
+
+1. **stable** — identity (`SOUL.md` or fallback), tool/model guidance, coding operating brief
+2. **context** — caller-supplied `system_message`, project context files (`.hermes.md` / `AGENTS.md` / `CLAUDE.md` / `.cursorrules`), then the worktree-dependent git workspace snapshot, operator instructions and platform hints
+3. **volatile** — skills index, built-in memory snapshot (`MEMORY.md`), user profile snapshot (`USER.md`), external memory-provider block, timestamp/session/model/provider line, then runtime environment hints (host / home / **current working directory**)
+
+The final system prompt is then joined as: `stable` → `context` → `volatile`.
+
+This ordering matters for precedence discussions:
+- skills are part of the **stable** tier
+- memory/profile snapshots are part of the **volatile** tier
+- both are still in the cached system prompt (they are not injected as ad-hoc mid-turn overlays)
+
+Inside the context tier the shared project files come **before** anything naming the current worktree.
+Sessions of one project running in different git worktrees then share a prompt prefix covering the whole
+context block, instead of stopping at the first cwd-dependent line — that prefix is what a longest-prefix
+provider cache reuses. A session with no workspace snapshot keeps its trailing guidance in the stable
+tier; the runtime environment block always ends the volatile tier.
+
+Consequence for stored prompts: `_stored_prompt_matches_runtime()` (`agent/conversation_loop.py`) reads
+the first host-info paragraph after the rendered `# Hermes runtime environment` boundary, with a
+closing marker at the absolute end distinguishing this layout from legacy prose quoting the heading.
+The runtime boundary follows all project, operator, memory and plugin text, so examples in those
+blocks do not masquerade as the runtime cwd. Model/provider are read before the runtime boundary,
+excluding embedder descriptions. `Platform:` is deliberately not an identity field: a surface switch
+(desktop ↔ TUI) keeps the stored bytes and delivers the current surface's guidance as a one-shot note on
+the per-turn user-message channel (`agent/surface_switch.py`), so the cached prefix survives (#104414). Legacy prompts retain their original
+host-before-context anchor, so prompts persisted before the reorder still validate.
+
+When `skip_context_files` is set (e.g., subagent delegation), SOUL.md is not loaded and the hardcoded `DEFAULT_AGENT_IDENTITY` is used instead.
+
+### Concrete example: assembled system prompt
+
+Here is a simplified view of what the final system prompt looks like when all layers are present (comments show the source of each section):
+
+```
+# Layer 1: Agent Identity (from ~/.hermes/SOUL.md)
+You are Hermes, an AI assistant created by Nous Research.
+You are an expert software engineer and researcher.
+You value correctness, clarity, and efficiency.
+...
+
+# Layer 2: Tool-aware behavior guidance
+Task-learned procedures, pitfalls, and task-specific preferences belong
+in skills. Memory is the narrow exception for facts that apply to EVERY
+session regardless of task. Skill-writing instructions appear here only
+when skill_manage is available; its absence does not widen memory's scope.
+...
+When the user references something from a past conversation or you
+suspect relevant cross-session context exists, use session_search
+to recall it before asking them to repeat themselves.
+
+# Tool-use enforcement (for GPT/Codex models only)
+You MUST use your tools to take action — do not describe what you
+would do or plan to do without actually doing it.
+...
+
+# Layer 3: Honcho static block (when active)
+[Honcho personality/context data]
+
+# Layer 4: Optional system message (from config or API)
+[User-configured system message override]
+
+# Layer 5: Frozen MEMORY snapshot
+## Persistent Memory
+- User prefers Python 3.12, uses pyproject.toml
+- Default editor is nvim
+- Working on project "atlas" in ~/code/atlas
+- Timezone: US/Pacific
+
+# Layer 6: Frozen USER profile snapshot
+## User Profile
+- Name: Alice
+- GitHub: alice-dev
+
+# Layer 7: Skills index
+## Skills (mandatory)
+Before replying, scan the skills below. If one clearly matches
+your task, load it with skill_view(name) and follow its instructions.
+...
+<available_skills>
+  software-development:
+    - code-review: Structured code review workflow
+    - test-driven-development: TDD methodology
+  research:
+    - arxiv: Search and summarize arXiv papers
+</available_skills>
+
+# Layer 8: Context files (from project directory)
+# Project Context
+The following project context files have been loaded and should be followed:
+
+## AGENTS.md
+This is the atlas project. Use pytest for testing. The main
+entry point is src/atlas/main.py. Always run `make lint` before
+committing.
+
+# Layer 9: Timestamp + session
+Current time: 2026-03-30T14:30:00-07:00
+Session: abc123
+
+# Layer 10: Platform hint
+You are a CLI AI Agent. Try not to use markdown but simple text
+renderable inside a terminal.
+```
+
+## Customizing platform hints
+
+The platform hint (Layer 10 above) is the per-surface guidance Hermes
+injects for Telegram, WhatsApp, Slack, CLI, and other platforms — for
+example "you are on a terminal, avoid Markdown." The built-in defaults
+live in `PLATFORM_HINTS` (`agent/system_prompt.py`); plugin-provided
+platforms supply theirs through the platform registry.
+
+An administrator can append to or replace a single platform's hint from
+`config.yaml` via the top-level `platform_hints` key, without touching
+any other platform:
+
+```yaml
+platform_hints:
+  whatsapp:
+    append: >
+      When tabular output would be useful, invoke the table_formatting
+      skill instead of emitting a Markdown table.
+  slack:
+    replace: "You are on Slack. Keep responses tight and avoid wide tables."
+  telegram: "Prefer short messages; split long answers."   # shorthand = append
+```
+
+- `append` — keep the built-in hint and add the extra text after it.
+- `replace` — substitute the built-in hint entirely.
+- A bare string — shorthand for `append`.
+- `replace` wins over `append` when both are present.
+- A malformed entry is ignored defensively and falls back to the
+  unmodified default, so a bad config value can never break prompt
+  assembly or leak across platforms.
+
+The override is resolved when the system prompt is built (session start,
+and again on compaction since that rebuilds the prompt). It produces a
+byte-stable hint for a fixed config, so it lives in the **stable** tier
+alongside the built-in hint and does not break prompt caching — it is
+not a live mid-session mutation of a frozen prompt.
+
+## How SOUL.md appears in the prompt
+
+`SOUL.md` lives at `~/.hermes/SOUL.md` and serves as the agent's identity — the very first section of the system prompt. The loading logic in `prompt_builder.py` works as follows:
+
+```python
+# From agent/prompt_builder.py (simplified)
+def load_soul_md() -> Optional[str]:
+    soul_path = get_hermes_home() / "SOUL.md"
+    if not soul_path.exists():
+        return None
+    content = soul_path.read_text(encoding="utf-8").strip()
+    content = _scan_context_content(content, "SOUL.md")  # Security scan
+    content = _truncate_content(content, "SOUL.md")       # Cap scales with model context window (20k floor); config override wins
+    return content
+```
+
+When `load_soul_md()` returns content, it replaces the hardcoded `DEFAULT_AGENT_IDENTITY`. The `build_context_files_prompt()` function is then called with `skip_soul=True` to prevent SOUL.md from appearing twice (once as identity, once as a context file).
+
+If `SOUL.md` doesn't exist, the system falls back to:
+
+```
+You are Hermes Agent, built by Nous Research. Be direct: match the length
+of your reply to the weight of the ask — a one-line question gets a
+one-line answer, and finished work gets a short report of what changed,
+what's verified, and what's left, never a replay of the process. No
+filler ("Great question," "I'd be happy to"), no restating the request
+back, no re-summarizing what you already said, no narrating tool calls
+the user can see. Plain claims over adjectives; when unsure, say so
+plainly. Agree because it's right, not because the user said it. Depth
+is earned — give it when the user asks for detail, teaches, or the
+stakes demand it, not by default.
+```
+
+## How context files are injected
+
+`build_context_files_prompt()` uses a **priority system** — only one project context type is loaded (first match wins):
+
+```python
+# From agent/prompt_builder.py (simplified)
+def build_context_files_prompt(cwd=None, skip_soul=False):
+    cwd_path = Path(cwd).resolve()
+
+    # Priority: first match wins — only ONE project context loaded
+    project_context = (
+        _load_hermes_md(cwd_path)       # 1. .hermes.md / HERMES.md (walks to git root)
+        or _load_agents_md(cwd_path)    # 2. AGENTS.md (cwd only)
+        or _load_claude_md(cwd_path)    # 3. CLAUDE.md (cwd only)
+        or _load_cursorrules(cwd_path)  # 4. .cursorrules / .cursor/rules/*.mdc
+    )
+
+    sections = []
+    if project_context:
+        sections.append(project_context)
+
+    # SOUL.md from HERMES_HOME (independent of project context)
+    if not skip_soul:
+        soul_content = load_soul_md()
+        if soul_content:
+            sections.append(soul_content)
+
+    if not sections:
+        return ""
+
+    return (
+        "# Project Context\n\n"
+        "The following project context files have been loaded "
+        "and should be followed:\n\n"
+        + "\n".join(sections)
+    )
+```
+
+### Context file discovery details
+
+| Priority | Files | Search scope | Notes |
+|----------|-------|-------------|-------|
+| 1 | `.hermes.md`, `HERMES.md` | CWD up to git root | Hermes-native project config |
+| 2 | `AGENTS.md` | CWD only | Common agent instruction file |
+| 3 | `CLAUDE.md` | CWD only | Claude Code compatibility |
+| 4 | `.cursorrules`, `.cursor/rules/*.mdc` | CWD only | Cursor compatibility |
+
+All context files are:
+- **Security scanned** — checked for prompt injection patterns (invisible unicode, "ignore previous instructions", credential exfiltration attempts)
+- **Truncated** — capped at `context_file_max_chars` characters using a 70/20 head/tail split with a truncation marker. The cap scales with the model's context window (20,000-char floor, 500K ceiling); an explicit `context_file_max_chars` in `config.yaml` always wins.
+- **YAML frontmatter stripped** — `.hermes.md` frontmatter is removed (reserved for future config overrides)
+
+## API-call-time-only layers
+
+These are intentionally *not* persisted as part of the cached system prompt:
+
+- `ephemeral_system_prompt`
+- prefill messages
+- gateway-derived session context overlays
+- later-turn Honcho/external recall injected into the current-turn user message
+
+`pre_llm_call` plugin context also lands in this API-call-time path: it is appended to the current turn's **user message**, not written into the cached system prompt. When multiple plugins return context, Hermes concatenates those context blocks (see [Hooks → `pre_llm_call`](../user-guide/features/hooks.md#pre_llm_call)).
+
+This separation keeps the stable prefix stable for caching.
+
+## Memory snapshots
+
+Local memory and user profile data are captured in the system prompt's **volatile tier**. Mid-session writes update disk state but do not mutate the already-built cached system prompt until a rebuild path runs (new session, or explicit invalidation/rebuild flow such as compression-triggered rebuild).
+
+## Context files
+
+`agent/prompt_builder.py` scans and sanitizes project context files using a **priority system** — only one type is loaded (first match wins):
+
+1. `.hermes.md` / `HERMES.md` (walks to git root)
+2. `AGENTS.md` (CWD at startup; subdirectories discovered progressively during the session via `agent/subdirectory_hints.py`)
+3. `CLAUDE.md` (CWD only)
+4. `.cursorrules` / `.cursor/rules/*.mdc` (CWD only)
+
+`SOUL.md` is loaded separately via `load_soul_md()` for the identity slot. When it loads successfully, `build_context_files_prompt(skip_soul=True)` prevents it from appearing twice.
+
+Long files are truncated before injection.
+
+## Skills index
+
+The skills system contributes a compact skills index to the prompt when skills tooling is available.
+
+## Supported prompt customization surfaces
+
+Most users should treat `agent/prompt_builder.py` as implementation code, not a configuration surface. The supported customization path is to change the prompt inputs Hermes already loads, rather than editing Python templates in place.
+
+### Use these surfaces first
+
+- `~/.hermes/SOUL.md` — replace the built-in default identity block with your own agent persona and standing behavior.
+- `~/.hermes/MEMORY.md` and `~/.hermes/USER.md` — provide durable cross-session facts and user profile data that should be snapshotted into new sessions.
+- Project context files such as `.hermes.md`, `HERMES.md`, `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` — inject repo-specific working rules.
+- Skills — package reusable workflows and references without editing core prompt code.
+- Optional system prompt config / API overrides — add deployment-specific instruction text without forking Hermes.
+- Ephemeral overlays such as `HERMES_EPHEMERAL_SYSTEM_PROMPT` or prefill messages — add turn-scoped guidance that should not become part of the cached prompt prefix.
+
+### When to edit code instead
+
+Edit `agent/prompt_builder.py` only if you are intentionally maintaining a fork or contributing upstream behavior changes. That file assembles the prompt plumbing, cache boundaries, and injection order for every session. Direct edits there are global product changes, not per-user prompt customization.
+
+In other words:
+
+- if you want a different assistant identity, edit `SOUL.md`
+- if you want different repo rules, edit project context files
+- if you want reusable operating procedures, add or modify skills
+- if you want to change how Hermes assembles prompts for everyone, change Python and treat it as a code contribution
+
+## Why prompt assembly is split this way
+
+The architecture is intentionally optimized to:
+
+- preserve provider-side prompt caching
+- avoid mutating history unnecessarily
+- keep memory semantics understandable
+- let gateway/ACP/CLI add context without poisoning persistent prompt state
+
+## Related docs
+
+- [Context Compression & Prompt Caching](./context-compression-and-caching.md)
+- [Session Storage](./session-storage.md)
+- [Gateway Internals](./gateway-internals.md)