docs: add ACP and internal systems implementation guides

- add ACP user and developer docs covering setup, lifecycle, callbacks,
  permissions, tool rendering, and runtime behavior
- add developer guides for agent loop, provider runtime resolution,
  prompt assembly, context caching/compression, gateway internals,
  session storage, tools runtime, trajectories, and cron internals
- refresh architecture, quickstart, installation, CLI reference, and
  environments docs to link the new implementation pages and ACP support

website/docs/developer-guide/provider-runtime.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 4
+title: "Provider Runtime Resolution"
+description: "How Hermes resolves providers, credentials, API modes, and auxiliary models at runtime"
+---
+
+# Provider Runtime Resolution
+
+Hermes has a shared provider runtime resolver used across:
+
+- CLI
+- gateway
+- cron jobs
+- ACP
+- auxiliary model calls
+
+Primary implementation:
+
+- `hermes_cli/runtime_provider.py`
+- `hermes_cli/auth.py`
+- `agent/auxiliary_client.py`
+
+## Resolution precedence
+
+At a high level, provider resolution uses:
+
+1. explicit CLI/runtime request
+2. environment variables
+3. `config.yaml` model/provider config
+4. provider-specific defaults or auto resolution
+
+## Providers
+
+Current provider families include:
+
+- OpenRouter
+- Nous Portal
+- OpenAI Codex
+- Anthropic (native)
+- Z.AI
+- Kimi / Moonshot
+- MiniMax
+- MiniMax China
+- custom OpenAI-compatible endpoints
+
+## Output of runtime resolution
+
+The runtime resolver returns data such as:
+
+- `provider`
+- `api_mode`
+- `base_url`
+- `api_key`
+- `source`
+- provider-specific metadata like expiry/refresh info
+
+## Why this matters
+
+This resolver is the main reason Hermes can share auth/runtime logic between:
+
+- `hermes chat`
+- gateway message handling
+- cron jobs running in fresh sessions
+- ACP editor sessions
+- auxiliary model tasks
+
+## OpenRouter vs custom OpenAI-compatible base URLs
+
+Hermes contains logic to avoid leaking the wrong API key to a custom endpoint when both `OPENROUTER_API_KEY` and `OPENAI_API_KEY` exist.
+
+That distinction is especially important for:
+
+- local model servers
+- non-OpenRouter OpenAI-compatible APIs
+- switching providers without re-running setup
+
+## Native Anthropic path
+
+Anthropic is not just "via OpenRouter" anymore.
+
+When provider resolution selects `anthropic`, Hermes uses:
+
+- `api_mode = anthropic_messages`
+- the native Anthropic Messages API
+- `agent/anthropic_adapter.py` for translation
+
+## OpenAI Codex path
+
+Codex uses a separate Responses API path:
+
+- `api_mode = codex_responses`
+- dedicated credential resolution and auth store support
+
+## Auxiliary model routing
+
+Auxiliary tasks such as:
+
+- vision
+- web extraction summarization
+- context compression summaries
+- session search summarization
+- skills hub operations
+- MCP helper operations
+- memory flushes
+
+can use their own provider/model routing rather than the main conversational model.
+
+## Fallback models
+
+Hermes also supports a configured fallback model/provider, allowing runtime failover in supported error paths.
+
+## Related docs
+
+- [Agent Loop Internals](./agent-loop.md)
+- [ACP Internals](./acp-internals.md)
+- [Context Compression & Prompt Caching](./context-compression-and-caching.md)