docs: make public docs friendlier (#173)

docs: make public docs friendlier

Author: bglusman

README.md

@@ -2,35 +2,38 @@
 
 > **Keep your castle secure and moving.**
 
-Calciforge is a self-hosted security gateway for AI agents. It sits
-between your agents and the rest of the world, so every agent gets its
-own model routes, command permissions, destination-scoped secret
-substitution, and audit trail without holding your raw API keys.
+Calciforge is a self-hosted safety layer for AI agents. It sits between
+your agents and the outside world, then applies the rules you set:
+which model an agent may use, which commands it may run, where a secret
+may be sent, and what gets written to the audit trail. The agent can ask
+for `{{secret:NAME}}`; it does not need to hold the actual API key.
 
-The longer feature tour, configuration examples, and architecture notes
-live on the docs site: **[calciforge.org](https://calciforge.org/)**.
+The longer tour, setup examples, and architecture notes live on
+**[calciforge.org](https://calciforge.org/)**.
 
 ## What Works Today
 
-This is usable for a solo operator, but still in active hardening. New
-installations should be smoke-tested against their real channel
-credentials, fnox store, gateway providers, and synthetic routes before
-being treated as daily-driver infrastructure.
+This is usable for a solo operator, but still being hardened. Before you
+make it daily-driver infrastructure, test it with your real chat
+channels, fnox secret store, model providers, and routing choices. Castles
+move; config should still have brakes, labels, and fewer mysterious bathroom
+potions than Howl would tolerate.
 
 | Area | Status | Where to read more |
 |---|---:|---|
-| `{{secret:NAME}}` substitution in URL, headers, and body | Working | [Secret management](https://calciforge.org/#secret-management) |
+| Explicit `{{secret:NAME}}` substitution in URL, headers, and body | Working | [Secret management](https://calciforge.org/#secret-management) |
+| Opaque placeholder credentials for supervised agent env vars or managed credential files | Staged primitives | [Placeholder injection mode](https://calciforge.org/roadmap/placeholder-injection-mode.html) |
 | Per-secret destination allowlists | Working | [Outbound traffic gating](https://calciforge.org/#outbound-traffic-gating) |
-| Local paste UI for one-shot and bulk `.env` secret input | Working | [Secret management](https://calciforge.org/#secret-management) |
-| MCP and CLI tools for agent-facing secret-name discovery, with no value readback | Working | [Agent-facing tools](https://calciforge.org/#agent-facing-tools-mcp) |
-| Agent runtime contract for CLI-first guidance, optional MCP, artifacts, and future Calciforge APIs | Working draft | [Agent runtime contract](docs/agent-runtime-contract.md) |
+| Local paste form for one-shot and bulk `.env` secret input | Working | [Secret management](https://calciforge.org/#secret-management) |
+| Command-line and optional MCP tools for agent-facing secret-name discovery, with no value readback | Working | [Agent-facing tools](https://calciforge.org/#agent-facing-tools-mcp-and-cli) |
+| Agent runtime contract for command-line guidance, optional MCP, artifacts, and future Calciforge APIs | Working draft | [Agent runtime contract](docs/agent-runtime-contract.md) |
 | Telegram, Matrix, WhatsApp, Signal, and text/iMessage routing | Working | [Multi-channel chat](https://calciforge.org/#multi-channel-chat) |
 | OpenAI-compatible model gateway, provider routing, model aliases, alloys, cascades, dispatchers, and local model switching | Working | [Model gateway](docs/model-gateway.md) |
 | Helicone-backed gateway observability with dashboard-visible doctor checks | Working | [Model gateway](docs/model-gateway.md#external-gateway-engines) |
 | Codex CLI and OpenClaw Codex subscription/OAuth integration paths | Working | [Codex integration](docs/codex-openclaw-integration.md) |
 | `calciforge doctor` config/state/endpoint diagnostics | Working | [Quick Start](#quick-start) |
 | Default-on inbound prompt-injection scanning, with opt-in outbound exfiltration and response secret-leak heuristics via editable policy | Working | [Traffic gating](https://calciforge.org/#outbound-traffic-gating) |
-| Configurable scanner checks with editable Starlark policy, Rust-backed `regex_match`, and remote HTTP/LLM extension points | Working | [Security gateway](docs/security-gateway.md) |
+| Configurable scanner checks with editable Starlark policy, Rust-backed `regex_match`, and optional remote model review | Working | [Security gateway](docs/security-gateway.md) |
 | Contributor red-team fixtures for prompt-injection, encoding, Unicode, and tool-policy bypass cases | Working | [Security gateway](docs/security-gateway.md#testing) |
 | [`clash`](https://crates.io/crates/clash)-backed tool policy via the `clashd` sidecar | Working | [Policy sidecar](crates/clashd/README.md) |
 | mTLS `host-agent` for ZFS, systemd, PCT, git, and exec operations | Working | [Host-agent](crates/host-agent/README.md) |
@@ -52,7 +55,7 @@ After install, the default local pieces are:
 - `security-proxy` on `127.0.0.1:8888` — substitution, destination checks, scanning, credential injection
 - `clashd` on `127.0.0.1:9001` — small HTTP adapter around the `clash` policy engine
 - `secrets-client` — env → fnox → Vaultwarden secret resolver
-- `calciforge-secrets` — non-MCP secret-name discovery and `{{secret:NAME}}` reference helper
+- `calciforge-secrets` — command-line secret-name discovery and `{{secret:NAME}}` reference helper
 - `paste-server` — short-lived local/LAN forms for adding secrets without putting values in chat history
 
 The installer attempts to install and initialize `fnox` automatically.
@@ -97,9 +100,11 @@ routing, and observability. Route agent tool/web traffic through
 content needs scanning or `{{secret:NAME}}` substitution.
 
 First-class adapters are expected to document and test their Calciforge ingress
-and egress paths. Generic CLI, generic ACP, and recipe adapters are useful but
-best effort unless their recipe proves a network boundary; hardened deployments
-should disable unverified adapters rather than assuming proxy env is enough.
+and egress paths. Generic command-line, generic ACP, and recipe adapters are
+useful but best effort unless their recipe proves a network boundary. ACP means
+Agent Client Protocol, a way to run persistent agent sessions. Hardened
+deployments should disable unverified adapters rather than assuming proxy
+environment variables are enough.
 
 For externally managed agent daemons that Calciforge does not launch, proxying
 has to be configured on that daemon or its service manager and validated
@@ -110,13 +115,30 @@ export HTTP_PROXY=http://127.0.0.1:8888
 export NO_PROXY=localhost,127.0.0.1,::1
 ```
 
-Do not treat ambient `HTTPS_PROXY` as a security boundary unless it points at
-Calciforge's MITM listener and the agent runtime trusts the Calciforge CA. The
-installer enables the experimental hudsucker-backed listener and generates a
-persistent local CA by default; manual deployments can set
+Do not treat a generic `HTTPS_PROXY` setting as a security boundary unless it
+points at Calciforge's inspecting proxy and the agent runtime trusts the
+Calciforge CA. CA means certificate authority: a local certificate issuer your
+machine can trust so Calciforge may open an HTTPS tunnel, inspect the request,
+and then re-encrypt it. Without that trust step, HTTPS is mostly an opaque
+tube; Calciforge can see the destination host, not the page or request body
+inside. The installer enables the experimental hudsucker-backed listener and
+generates a persistent local CA by default; manual deployments can set
 `SECURITY_PROXY_CA_CERT=...` and `SECURITY_PROXY_CA_KEY=...`. Use a
-Calciforge-owned model gateway, fetch/tool path, audited recipe, or tested MITM
-proxy setup when HTTPS content needs scanning or secret substitution.
+Calciforge-owned model gateway, fetch/tool path, audited recipe, or tested
+inspecting-proxy setup when HTTPS content needs scanning or secret
+substitution.
+
+Secret handling is in a transition period. The working path today is explicit
+reference syntax: an agent emits `{{secret:NAME}}`, and Calciforge resolves it
+only at an approved destination. The next path is opaque placeholder
+credentials: Calciforge will generate fake-looking random values such as
+`cfg_OPENAI_API_KEY_<random>`, register them with the security proxy, then
+provide them to supervised agents through env vars or managed credential files.
+That matters for agents like OpenClaw lanes that expect plaintext credential
+files or ordinary `*_API_KEY` variables. Once that path is wired, they can
+receive stand-ins instead of real secrets, and the gateway will swap in the
+real value only during an allowed outbound request. That path is not the
+default yet.
 
 ## Tiny Config Sketch
 

docs/agent-runtime-contract.md

@@ -42,6 +42,10 @@ Secrets:
 - Put `{{secret:NAME}}` placeholders only into outbound requests that are
   routed through Calciforge. Do not try to resolve, print, log, or store secret
   values yourself.
+- If your runtime receives an env var or credential file whose value starts
+  with `cfg_`, treat it as an opaque Calciforge-managed credential stand-in.
+  Use it only in the provider request it was configured for. Do not print,
+  transform, rotate, or copy it elsewhere.
 
 Artifacts:
 - If Calciforge provides `CALCIFORGE_ARTIFACT_DIR`, write generated images,
@@ -71,6 +75,9 @@ Current surfaces:
   discovery and placeholder construction.
 - Optional `mcp-server` tools for the same secret-name workflow when MCP is
   explicitly configured.
+- Managed opaque placeholder credentials for supervised runtimes. Calciforge
+  or an installer-managed wrapper must generate and provide these values; the
+  agent should never invent a `cfg_*` value itself.
 - `CALCIFORGE_ARTIFACT_DIR` for recipes or adapters that produce files.
 - The OpenAI-compatible model gateway when a local agent should route model
   calls through Calciforge rather than directly to a provider.

docs/agents.md

@@ -5,12 +5,19 @@ title: Agents, Identities, and Routing
 
 # Agents, Identities, and Routing
 
+Status: Implemented
+
 This page covers the three configuration sections that together control who
 can talk to Calciforge and which AI backend handles their messages:
 
-- `[[agents]]` — AI backends Calciforge dispatches to
-- `[[identities]]` — users and their per-channel aliases
-- `[[routing]]` — maps identities to agents
+- `[[agents]]` — the AI backends Calciforge can call
+- `[[identities]]` — the people or service accounts Calciforge recognizes,
+  plus their per-channel aliases
+- `[[routing]]` — the rules that map identities to agents
+
+The short version: an incoming chat message becomes an identity, the identity
+chooses a route, and the route chooses an agent. It is a little like Howl's
+door dial, but with fewer colors and more audit logs.
 
 ## Architecture
 
@@ -35,15 +42,17 @@ Channel message arrives
 ## Agents (`[[agents]]`)
 
 Each `[[agents]]` entry defines one AI backend. The `kind` field selects the
-adapter. All other fields are adapter-specific.
+adapter, which is the small piece of Calciforge that knows how to talk to that
+backend. All other fields are adapter-specific.
 
 First-class adapters carry a stronger maintenance promise than generic
-wrappers: Calciforge should document how user ingress, callback auth, model
-egress, and tool/web egress are protected for that adapter, and regressions in
-those paths are Calciforge bugs where the upstream runtime gives us enough
-control to fix them. Generic CLI, generic ACP, and recipe adapters remain
-best-effort unless their recipe documents a tested boundary. In hardened
-profiles, prefer first-class adapters or explicitly verified recipes.
+wrappers: Calciforge should document how user messages arrive, how callbacks
+are authenticated, and how model/tool/web traffic is protected for that
+adapter. Regressions in those paths are Calciforge bugs when the upstream
+runtime gives us enough control to fix them. Generic command-line, generic ACP
+(Agent Client Protocol), and recipe adapters remain best-effort unless their
+recipe documents a tested boundary. In hardened profiles, prefer first-class
+adapters or explicitly verified recipes.
 
 ### Common fields
 
@@ -63,7 +72,8 @@ profiles, prefer first-class adapters or explicitly verified recipes.
 ### `kind = "openclaw-channel"`
 
 HTTP adapter for an OpenClaw gateway that has the Calciforge bridge plugin
-installed. The plugin package is still named `calciforge-channel` for
+installed. HTTP is the web protocol used for the request between the two
+services. The plugin package is still named `calciforge-channel` for
 compatibility, but Calciforge owns the user-facing channel. Calciforge POSTs
 each routed message to the plugin's
 `/calciforge/inbound` route, OpenClaw runs the selected agent lane with its own
@@ -79,8 +89,9 @@ Calciforge controls identity routing, channel access, callback authentication,
 and artifact delivery for this path. OpenClaw's outbound model/tool traffic is
 only covered by Calciforge's security layers when you configure the OpenClaw
 service to use a tested proxy/tool/policy integration; installing the channel
-plugin alone does not prove outbound egress enforcement. In managed MITM mode,
-prompt-injection response blocking is the default safety gate. Outbound
+plugin alone does not prove outbound egress enforcement. In managed
+inspecting-proxy mode, prompt-injection response blocking is the default safety
+gate. Outbound
 exfiltration heuristics and high-entropy response secret-leak detection are
 operator opt-ins because they can be noisy on provider/tool transcripts.
 
@@ -152,7 +163,7 @@ and the same reply token in `reply_auth_token_file`/`reply_auth_token`.
 ### `kind = "openai-compat"`
 
 Generic OpenAI-compatible HTTP endpoint (Ollama, LM Studio, Anthropic,
-Together, any endpoint that accepts `/v1/chat/completions`).
+Together, or any endpoint that accepts `/v1/chat/completions`).
 
 Required: `endpoint`. Recommended: `model`.
 
@@ -229,8 +240,9 @@ timeout_ms = 300000
 
 ### `kind = "cli"`
 
-Spawns a subprocess for each message. The command receives the message via
-the argument template: `{message}` in `args` is replaced at dispatch time.
+Spawns a command-line subprocess for each message. The command receives the
+message via the argument template: `{message}` in `args` is replaced at
+dispatch time.
 
 Required: `command`.
 

docs/channels/matrix.md

@@ -5,13 +5,18 @@ title: Matrix Channel Setup
 
 # Matrix Channel
 
-Calciforge connects to Matrix via the [Client-Server API v3](https://spec.matrix.org/v1.9/client-server-api/)
-using **HTTP long-polling** (`/sync`). No webhook endpoint or open firewall port required.
-
-> **No end-to-end encryption.** The Matrix channel receives plaintext `m.text`
-> events and can send plaintext replies plus native media events for agent
-> artifacts. E2EE is not supported due to compile-time dependency conflicts in
-> the current workspace. Do not use this channel in rooms where E2EE is required.
+Calciforge connects to Matrix through the [Client-Server API v3](https://spec.matrix.org/v1.9/client-server-api/)
+using **HTTP long-polling** (`/sync`). Long-polling means Calciforge keeps
+asking the homeserver for new events, so no webhook endpoint or open firewall
+port is required.
+
+> **No end-to-end encryption yet.** The Matrix channel currently uses the raw
+> Matrix Client-Server API, so it receives plaintext `m.text` events and sends
+> plaintext replies plus native media events for agent artifacts. Matrix itself
+> supports end-to-end encryption, and the Matrix Rust SDK has crypto support,
+> but Calciforge has not yet wired the required encrypted-room client state,
+> device trust, and persistent crypto store. Do not use this channel in rooms
+> where E2EE is required.
 
 ## Architecture
 
@@ -42,7 +47,9 @@ curl -s -X POST 'https://matrix.example.com/_matrix/client/v3/login' \
   }' | grep access_token
 ```
 
-   Copy the `access_token` value from the response.
+   Copy the `access_token` value from the response and store it like a
+   password. Access tokens are not decorative boilerplate; they are the key to
+   the bot account.
 
 3. **Find the room ID** for the room you want the bot to listen in:
    - In most clients: room settings → Advanced → Internal room ID
@@ -126,13 +133,20 @@ Some Matrix clients and bridges expose buttons or polls differently, and
 bridges such as Beeper may not support the downstream app's native controls.
 Use `ui_mode = "text"` in `[[channels]]` to force plain text for a channel;
 `ui_mode = "auto"` is reserved for channel-native affordances once the Matrix
-adapter can expose them without breaking bridged clients.
+adapter can expose them without breaking bridged clients. Plain text is not as
+flashy, but it behaves predictably across the moving castle of Matrix clients.
 
 You can still use a richer channel, such as Telegram, as the Calciforge control
 surface for agent/model selection while keeping Matrix as the main chat room.
 Selections are keyed by Calciforge identity and apply across that operator's
 channels.
 
+E2EE support is a high-priority follow-up, not a philosophical objection. The
+likely path is to move this adapter onto the Matrix Rust SDK crypto stack,
+persist the bot device's encrypted state, and add a real encrypted-room smoke
+test. Until that lands, treat Matrix as convenient self-hosted transport rather
+than the secure-room option it should become.
+
 <div class="channel-ui-grid">
   <figure>
     <img src="../assets/channel-ui-matrix-fallback.svg" alt="Matrix text fallback for agent and model selection">