Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs: add guides for guardrails, OAuth connectors, LLM subscriptions, and the Desktop App

Jose Gabriel Ramirez Encinasff49e6aef8a7
diff --git a/docs/README.md b/docs/README.md
index 046330182..ccf1fbcb2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -46,27 +46,31 @@ minikube overlays ship; features that are off by default say so.
## How-to guides
-| Doc | Description |
-| ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| [Connect Telegram](how-to/connect-telegram.md) | Minikube env or CRD channel path |
-| [Connect Slack](how-to/connect-slack.md) | Slack app scopes, request URL, conversation verification |
-| [Connect Microsoft Teams](how-to/connect-teams.md) | Teams CLI bot registration, endpoint, conversation verify |
-| [Configure approvals](how-to/configure-approvals.md) | Human-in-the-loop tool gates |
-| [Add an MCP server](how-to/add-mcp-server.md) | Dev-mode JSON, CRD, or Control UI path |
-| [Desktop setup & updates](how-to/desktop-setup-and-updates.md) | Environments, invitation setup, updates |
-| [Member invitations on self-hosted](how-to/member-invitations-self-hosted.md) | Hosted mode zero-config emails vs running your own service |
-| [Track usage & set budgets](how-to/token-budgets-and-usage.md) | Enable budgets, scope, block vs warn |
-| [Connect to the registry](how-to/connect-to-registry.md) | Self-hosted registry connect flow |
-| [Publish a plugin](how-to/publish-plugin-to-registry.md) | Publish under your org with an `efrk_` key |
-| [Shared & global files](how-to/shared-and-global-files.md) | Team workspaces (SFS) and the brokered drive (EvenDrive / GFS) |
+| Doc | Description |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| [Connect Telegram](how-to/connect-telegram.md) | Minikube env or CRD channel path |
+| [Connect Slack](how-to/connect-slack.md) | Slack app scopes, request URL, conversation verification |
+| [Connect Microsoft Teams](how-to/connect-teams.md) | Teams CLI bot registration, endpoint, conversation verify |
+| [Use the Desktop App](how-to/use-the-desktop-app.md) | Daily use: chat, attachments, approvals, EvenDrive, shortcuts, deep links |
+| [Configure guardrails](how-to/configure-guardrails.md) | Tool-call rules, installed guardrail hooks, built-ins |
+| [Connect an OAuth connector](how-to/connect-oauth-connector.md) | Remote and OAuth MCP servers, user authorization, connector credentials |
+| [Configure approvals](how-to/configure-approvals.md) | Human-in-the-loop tool gates |
+| [Add an MCP server](how-to/add-mcp-server.md) | Dev-mode JSON, CRD, or Control UI path |
+| [Desktop setup & updates](how-to/desktop-setup-and-updates.md) | Environments, invitation setup, updates |
+| [Member invitations on self-hosted](how-to/member-invitations-self-hosted.md) | Hosted mode zero-config emails vs running your own service |
+| [Track usage & set budgets](how-to/token-budgets-and-usage.md) | Enable budgets, scope, block vs warn |
+| [Connect to the registry](how-to/connect-to-registry.md) | Self-hosted registry connect flow |
+| [Publish a plugin](how-to/publish-plugin-to-registry.md) | Publish under your org with an `efrk_` key |
+| [Shared & global files](how-to/shared-and-global-files.md) | Team workspaces (SFS) and the brokered drive (EvenDrive / GFS) |
## LLM providers
-| Doc | Description |
-| --------------------------------------------------------- | ---------------------------------------------------------------------- |
-| [LLM providers overview](llm-providers/README.md) | The 24 providers, mental model, support matrix, request flow, fallback |
-| [Configure LLM providers](deploy/llm-providers.md) | Operator guide: credentials, Vertex/Bedrock/Azure, allowlist, selector |
-| [Add an LLM provider](llm-providers/adding-a-provider.md) | Data-only vs driver-based integration paths |
+| Doc | Description |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| [LLM providers overview](llm-providers/README.md) | The 24 providers, mental model, support matrix, request flow, fallback |
+| [Configure LLM providers](deploy/llm-providers.md) | Operator guide: credentials, Vertex/Bedrock/Azure, allowlist, selector |
+| [Use a ChatGPT or Grok subscription](how-to/connect-llm-subscription.md) | Sign in with a subscription instead of an API key (off by default) |
+| [Add an LLM provider](llm-providers/adding-a-provider.md) | Data-only vs driver-based integration paths |
## Deploy & operate
diff --git a/docs/crds/host.md b/docs/crds/host.md
index 23877a459..7043e7822 100644
--- a/docs/crds/host.md
+++ b/docs/crds/host.md
@@ -56,13 +56,13 @@ represents a single LLM agent instance (an "agent" in Control UI and the Desktop
| Field | Description |
|-------|-------------|
-| `guardrails.rules[]` | Ordered tool-lane rules evaluated top-down: `{id, action: allow\|ask\|deny, reasonCode, match: {tool, arguments[]}}`. |
-| `guardrails.hooks.<phase>[]` | Installed [LlmHook](llmhook.md) references `{id, digest}` per phase: `preToolUse`, `postToolUse`, `preCall`, `moderate`, `postCallSuccess`, `onError`. |
+| `guardrails.rules[]` | Tool-lane rules `{id, action: allow\|ask\|deny, reasonCode, match: {tool, arguments[]}}`. Every matching rule contributes and the strictest decision wins; array order is not precedence. Once any rule exists, a call that matches none resolves to `ask`. |
+| `guardrails.hooks.<phase>[]` | Installed [LlmHook](llmhook.md) references `{id, digest}` per phase: `preToolUse`, `postToolUse`, `preCall`, `moderate`, `postCallSuccess`, `onError`. A referenced hook runs at every point in its own `lifecyclePoints`. |
| `guardrails.builtins[]` | First-party hooks compiled into mcp-host (e.g. `prompt-shaping`, `token-trim`). |
-| `guardrails.minInstalledHookTrustLevel` | `low` \| `mid` \| `high`: minimum platform-assigned trust level an installed hook needs to run on this Host. |
-| `guardrails.capabilityCeiling[]` | Upper bound on hook capabilities: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. |
-| `guardrails.approvalPolicies[]` | Approval policies available to `ask` decisions: `cli_only`, `channel_users`, `designated_approvers`. |
-| `guardrails.limits` | `maxRules` (100), `maxHooksPerPhase` (8), `maxHookTimeoutMs` (5000), `maxHookOutputBytes` (65536). |
+| `guardrails.minInstalledHookTrustLevel` | `low` \| `mid` \| `high`: minimum trust level for hooks installed onto this Host. Checked by control-api when a hook is installed or upgraded, not at runtime. |
+| `guardrails.capabilityCeiling[]` | Upper bound on the capabilities an install may grant: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Checked at install/upgrade, not at runtime, so a hand-edited LlmHook is not re-validated against it. |
+| `guardrails.approvalPolicies[]` | Accepted by the schema (`cli_only`, `channel_users`, `designated_approvers`) but not read by mcp-host today; `ask` decisions use `spec.approval`. |
+| `guardrails.limits` | `maxRules` (100) and `maxHookTimeoutMs` (5000, the deadline for every hook call) are enforced. `maxHookOutputBytes` (65536 when a `limits` object is present; otherwise mcp-host allows 1 MiB, and 5 MiB for `preCall` rewrites) applies to LLM-lane hooks. `maxHooksPerPhase` is accepted but not enforced. |
Apply the CRD before any component writes `spec.guardrails`: the API server
silently prunes fields an older CRD does not know.
diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.md
index 1450066f5..0ea3e60a6 100644
--- a/docs/crds/llmhook.md
+++ b/docs/crds/llmhook.md
@@ -25,31 +25,34 @@ A Host opts in by listing hooks under `Host.spec.guardrails.hooks.<phase>[]`
Control UI installs hooks from the registry (**Installed Guardrails**). The
install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,
`mid` or `high`) that hook authors cannot set. The Host's
-`guardrails.minInstalledHookTrustLevel` is checked against that annotation.
+`guardrails.minInstalledHookTrustLevel` is checked against that annotation
+(and granted capabilities against `guardrails.capabilityCeiling`) by
+control-api when a hook is installed or upgraded; mcp-host does not re-check
+either at runtime.
## Spec Fields
-| Field | Type | Required | Description |
-| -------------------------------------------- | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `spec.target` | object | yes | Exactly one of `image`, `service`, `remote`. |
-| `spec.target.image.ref` | string | yes (image) | Container image. Validated against the image allowlist and digest-pinned at install. |
-| `spec.target.image.port` | int | yes (image) | Port the hook HTTP server listens on (1–65535). |
-| `spec.target.image.imagePullSecrets` | string[] | no | Pull secret names in `llm-hooks`. |
-| `spec.target.image.envSecret` | string | no | The hook's own credential Secret in `llm-hooks`. It can never reference a Host or LLM-key Secret. |
-| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. Looser than McpServer egress: no private-range hardening yet. |
-| `spec.target.image.security.addCapabilities` | string[] | no | Subset of `CHOWN`, `FOWNER`, `DAC_OVERRIDE`, `NET_BIND_SERVICE`. |
-| `spec.target.service` | object | yes (service) | Existing in-cluster Service: `name`, `namespace`, `port`. |
-| `spec.target.remote.baseUrl` | string | yes (remote) | External endpoint mcp-host dials directly. Must be `https://`; SSRF-validated at dial time. |
-| `spec.target.remote.authHeadersSecret` | string | no | Secret supplying auth headers for the remote endpoint. |
-| `spec.path` | string | no (default `/`) | Calls go to `{endpoint}{path}/v1/{point}`. Co-located image hooks must use distinct paths. |
-| `spec.lifecyclePoints` | string[] | yes (1–6) | LLM lane: `preCall`, `moderate`, `postCallSuccess`, `onError`. Tool lane: `preToolUse`, `postToolUse`. |
-| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |
-| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |
-| `spec.failMode` | `open` \| `closed` | no (default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. |
-| `spec.timeoutMs` | int | no (default 5000) | Per-call timeout. |
-| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |
-| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Must fall within the Host's `guardrails.capabilityCeiling`, and is re-checked on every hook response. |
-| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |
+| Field | Type | Required | Description |
+| -------------------------------------------- | ----------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spec.target` | object | yes | Exactly one of `image`, `service`, `remote`. |
+| `spec.target.image.ref` | string | yes (image) | Container image. Validated against the image allowlist and digest-pinned at install. |
+| `spec.target.image.port` | int | yes (image) | Port the hook HTTP server listens on (1–65535). |
+| `spec.target.image.imagePullSecrets` | string[] | no | Pull secret names in `llm-hooks`. |
+| `spec.target.image.envSecret` | string | no | The hook's own credential Secret in `llm-hooks`. It can never reference a Host or LLM-key Secret. |
+| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. Looser than McpServer egress: no private-range hardening yet. |
+| `spec.target.image.security.addCapabilities` | string[] | no | Subset of `CHOWN`, `FOWNER`, `DAC_OVERRIDE`, `NET_BIND_SERVICE`. |
+| `spec.target.service` | object | yes (service) | Existing in-cluster Service: `name`, `namespace`, `port`. |
+| `spec.target.remote.baseUrl` | string | yes (remote) | External endpoint mcp-host dials directly. Must be `https://`; SSRF-validated at dial time. |
+| `spec.target.remote.authHeadersSecret` | string | no | Secret supplying auth headers for the remote endpoint. |
+| `spec.path` | string | no (default `/`) | Calls go to `{endpoint}{path}/v1/{point}`. Co-located image hooks must use distinct paths. |
+| `spec.lifecyclePoints` | string[] | yes (1–6) | LLM lane: `preCall`, `moderate`, `postCallSuccess`, `onError`. Tool lane: `preToolUse`, `postToolUse`. |
+| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |
+| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |
+| `spec.failMode` | `open` \| `closed` | no (CRD default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. The Control UI install form defaults to `open` unless `may_deny` is granted. |
+| `spec.timeoutMs` | int | no (default 5000) | Accepted but not used today; the deadline is the Host's `guardrails.limits.maxHookTimeoutMs` (default 5000). |
+| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |
+| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Checked against the Host's `guardrails.capabilityCeiling` at install time; mcp-host ignores response actions the hook was not granted. |
+| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |
### Admission rules
@@ -63,12 +66,12 @@ install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,
## Status Fields
-| Field | Description |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status.observedDigest` | Image digest actually running. mcp-host binds `Host.spec.guardrails.hooks[].digest` against this, and fails closed (or skips with an alert) on mismatch. |
-| `status.readyReplicas` | Ready replicas (image targets only). |
-| `status.lastReconciled` | Timestamp of the last successful reconcile. |
-| `status.conditions[]` | Standard conditions (`Deployed`, `Ready`) with `observedGeneration`. |
+| Field | Description |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status.observedDigest` | Image digest actually running. mcp-host compares it with `Host.spec.guardrails.hooks[].digest`. On a mismatch the hook is quarantined: calls are treated as unavailable, so a `may_deny` hook denies and an advisory hook contributes nothing (LLM-lane points). |
+| `status.readyReplicas` | Ready replicas (image targets only). |
+| `status.lastReconciled` | Timestamp of the last successful reconcile. |
+| `status.conditions[]` | Standard conditions (`Deployed`, `Ready`) with `observedGeneration`. |
`kubectl get llmhooks -n llm-hooks` shows Path, Order, FailMode, Digest, and Ready.
@@ -109,5 +112,6 @@ A zero-dependency reference implementation of the `/v1` protocol lives in
## Related
+- [Configure guardrails](../how-to/configure-guardrails.md): the how-to guide
- [Host CRD](host.md): `spec.guardrails`
- [CRD Index](README.md)
diff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.md
index 73b38b4f2..349b754df 100644
--- a/docs/crds/mcpserver.md
+++ b/docs/crds/mcpserver.md
@@ -71,7 +71,7 @@ after creation:
|-------|-----------|-------------|
| `oauth.id` | all | Stable client identifier; also the callback path segment. Immutable. |
| `oauth.provider` | built-in | `salesforce`, `slack`, `notion`, `microsoft-graph`, `google`, `monday`, `clickup`, `vercel`. Immutable. |
-| `oauth.clientIdRef` / `oauth.clientSecretRef` | all | `{name, key}` of Secrets in the `mcp-servers` namespace holding the client id / secret. |
+| `oauth.clientIdRef` / `oauth.clientSecretRef` | all | `{name, key}` of Secrets in the `mcp-server` namespace holding the client id / secret. |
| `oauth.scopes[]` | all | Scopes to request. Include the provider's offline/refresh scope when `backgroundAccess` is true. |
| `oauth.backgroundAccess` | all | Allow use by a workload with no live human session. |
| `oauth.grantScope` | all | `user` (default): every user authorizes their own grant. `context`: one shared identity per Context, which one member bootstraps and others inherit. Immutable. |
@@ -91,7 +91,9 @@ after creation:
With dynamic registration, the install id is appended and registered
automatically.
-The Control UI wizard shows the exact URI.
+The remote-connector wizard in Control UI shows the exact URI. See
+[Connect an OAuth connector](../how-to/connect-oauth-connector.md) for the
+full walkthrough.
### Server Configuration
diff --git a/docs/how-to/add-mcp-server.md b/docs/how-to/add-mcp-server.md
index 501884093..c331a868b 100644
--- a/docs/how-to/add-mcp-server.md
+++ b/docs/how-to/add-mcp-server.md
@@ -116,5 +116,6 @@ See [stdio-bridge README](../../stdio-bridge/README.md) and
## Related
+- [Connect an OAuth connector](connect-oauth-connector.md): remote MCP servers, OAuth sign-in, and updating connector credentials
- [CRD index](../crds/README.md)
- [Architecture overview](../architecture/overview.md)
diff --git a/docs/how-to/configure-approvals.md b/docs/how-to/configure-approvals.md
index b73c0482d..f0bf37619 100644
--- a/docs/how-to/configure-approvals.md
+++ b/docs/how-to/configure-approvals.md
@@ -118,6 +118,7 @@ Cluster E2E coverage: [E2E guide](../testing/e2e-guide.md).
## Related
+- [Configure guardrails](configure-guardrails.md): rules whose `ask` decision uses this approval flow
- Root [Security model](../../README.md#security-model)
- [Host CRD](../crds/host.md)
- [Connect Telegram](connect-telegram.md)
diff --git a/docs/how-to/configure-guardrails.md b/docs/how-to/configure-guardrails.md
new file mode 100644
index 000000000..149f757e6
--- /dev/null
+++ b/docs/how-to/configure-guardrails.md
@@ -0,0 +1,344 @@
+# How to: add guardrails to an agent
+
+Guardrails are an **opt-in** policy block on a Host (`spec.guardrails`). A
+Host without one behaves exactly as before. No guardrails block and no
+`LlmHook` ship in `deploy/base` or the minikube overlays. The base only
+creates the `llm-hooks` namespace, its RBAC, and a default-deny
+NetworkPolicy, so there is no flag to flip: you turn guardrails on by
+writing the block.
+
+Guardrails are a policy layer inside mcp-host. They are **not a sandbox**.
+Argument predicates are lexical, so path and URL checks are not TOCTOU-safe.
+A guardrail `allow` never bypasses the approval gate, the input validators,
+or workload isolation.
+
+## Mental model
+
+There are two lanes, and both use the same `allow` / `ask` / `deny`
+decisions:
+
+| Lane | What runs | Where it acts |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| **Tool lane** | `rules[]`, installed hooks at `preToolUse` / `postToolUse`, a doom-loop check | Before a tool call (decide), after it (redact the result) |
+| **LLM lane** | Built-ins (`prompt-shaping`, `token-trim`), then installed hooks at `preCall`, `moderate`, `postCallSuccess`, `onError` | Around the main model call |
+
+How a tool call is decided:
+
+1. Every rule that matches the call contributes its action, and so does
+ every `preToolUse` hook that returns a decision.
+2. **The strictest contribution wins:** `deny` > `ask` > `allow`. The order
+ of the rules does **not** matter. A broad `allow` cannot override a
+ narrower `deny`.
+3. If the Host has at least one rule and **nothing matched**, the result is
+ `ask` (reason `unmatched_ask`). If the Host has no rules, the result is
+ `no_decision` and the call follows the normal path.
+4. The result is applied:
+ - `deny` returns `Blocked by guardrail policy (<reason>)` to the model.
+ - `ask` suspends the call for approval.
+ - `allow` and `no_decision` go on to the normal [approval gate](configure-approvals.md).
+
+Because of step 3, adding a single `deny` rule turns **every other** tool
+call into an `ask`. Pair specific rules with a catch-all `allow` per
+provenance (see the example below).
+
+### How `ask` interacts with approvals
+
+- In an **interactive** run, a guardrail `ask` creates a pending approval
+ scoped to that exact invocation. Its description reads
+ `Guardrail requires approval (<reason>)`. You approve it on the usual
+ surfaces. Once it is approved, the call runs without a second prompt from
+ `spec.approval`.
+- Tasks started by a person's message (Desktop App chat or a messaging
+ channel; task source `channel`) are interactive. `cron` and `internal`
+ tasks are **unattended**. In an unattended run an `ask` becomes
+ a deny ("approval required but no approver is available"), so the task
+ does not hang.
+- `allow` does not skip approvals. MCP tools and the five risky native tools
+ still require approval under `spec.approval`.
+
+## Option A — mcp-host dev mode
+
+Set `CLERUM_GUARDRAILS_CONFIG` to the JSON form of the `spec.guardrails`
+block. mcp-host uses it only when no Host CR supplies one. For dev and E2E,
+you can also list hooks inline as `hookDescriptors` to point at a local hook
+server without the reconciler.
+
+## Option B — Host CRD
+
+Apply the current `charts/clerum-crds` first. The API server **silently
+prunes** fields that an older CRD does not know, so a `guardrails` block
+written against a stale CRD simply disappears.
+
+```yaml
+apiVersion: clerum.io/v1alpha1
+kind: Host
+metadata:
+ name: chatllm
+ namespace: mcp-host
+spec:
+ # ...existing fields...
+ guardrails:
+ rules:
+ # Catch-alls so unmatched calls don't fall to `ask`.
+ - id: allow-native
+ action: allow
+ match: { tool: { provenance: native } }
+ - id: allow-mcp
+ action: allow
+ match: { tool: { provenance: mcp } }
+ # Strictest wins: this deny beats allow-native.
+ - id: no-metadata-endpoint
+ action: deny
+ reasonCode: metadata_blocked
+ match:
+ tool: { provenance: native, name: http_request }
+ arguments:
+ - { type: url, pointer: /url, op: host_in, value: ['169.254.169.254'] }
+ - id: ask-github-writes
+ action: ask
+ match: { tool: { provenance: mcp, server: github, name: '*create*' } }
+ builtins:
+ - type: token-trim
+ order: 10
+ config: { maxInputTokens: 60000 }
+ capabilityCeiling: [may_deny, may_substitute_result]
+ hooks:
+ postCallSuccess:
+ - id: pii-redactor
+ digest: sha256:<digest>
+```
+
+**Rule fields.** Each rule needs:
+
+- `id`: unique within the Host.
+- `action`: `allow`, `ask` or `deny`.
+- `match.tool.provenance`: `native` or `mcp`. Provenance comes from the tool
+ registry, never from the tool's name.
+
+`server` and `name` are optional. They support only `*` and `?` wildcards,
+anchored to the whole value. If you omit them, the rule matches every tool of
+that provenance. A rule's `arguments[]` predicates must **all** match. Each
+predicate has a `type`, a JSON Pointer into the arguments, an `op` and a
+`value`:
+
+| `type` | `op` values | Notes |
+| --------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `path` | `equals`, `under`, `outside` | Lexical normalisation; no symlink resolution |
+| `url` | `scheme_in`, `host_in`, `port_in`, `path_under` | URLs with credentials never match |
+| `command` | `executable_is`, `argv_prefix` | Argument must be `[exe, ...args]` or `{executable, args}`; a shell **string never matches** |
+| `json` | `exists`, `equals`, `one_of`, `contains` | Canonical key order |
+
+The CRD does not validate rule shape. mcp-host compiles the rules when a task
+starts, and a malformed set (missing provenance, duplicate id, unknown op,
+bad pointer) makes the task fail rather than run with part of the rules.
+
+**Built-ins** run in-process on the main model lane only, sorted by `order`
+(default 100). For each item, mcp-host reads only `type`, `order` and
+`config`.
+
+- `prompt-shaping` forces `temperature`, `maxTokens` and `toolChoice`.
+- `token-trim` reuses the pre-prune passes. It accepts `maxInputTokens`,
+ `protectedTailTurns`, `summaryThresholdTokens`, `maxArgsBytes` and per-pass
+ toggles. When `maxInputTokens` is set and the request is already under it,
+ the request is left unchanged.
+
+**Hooks** reference installed [LlmHook](../crds/llmhook.md) CRs as `{id,
+digest}`. The full field list is in [Host CRD → Guardrails](../crds/host.md#guardrails).
+
+mcp-host picks up Host and LlmHook changes live; you do not need to restart
+the pod.
+
+## Option C — the Control UI
+
+### Install a hook from the Marketplace
+
+1. In the sidebar, open **Installed Guardrails** (`/guardrails`). The page
+ lists every `LlmHook` with its lifecycle, order, fail mode and status.
+2. Click **Install Guardrail**. This opens the org Marketplace entries,
+ filtered to guardrail hooks (`/marketplace/org/entries?type=llm-hook`).
+ Pick an entry and choose **Install**.
+3. In the install form (**Configure** → **Install**):
+ - **Agent**: the Host to bind to. It defaults to the first agent in the
+ list, so check it.
+ - **Credentials**: shown only if the hook declares a credential schema.
+ - **Advanced details**: the capabilities to grant, **Order** (default
+ 100), and **Fail mode**. Ticking **May deny** forces fail closed.
+4. **Install** calls `POST /admin/registry/install-hook`. That call:
+ - checks the entry: it must be org-scoped, and its admission rules are
+ validated;
+ - checks the agent: the hook's trust level must meet the agent's floor,
+ and the capabilities you selected must fall within the agent's ceiling;
+ - requires a digest-pinned image, and checks the image allowlist when
+ enforcement is on;
+ - creates the `LlmHook` in `llm-hooks`, stamped with a platform-assigned
+ `clerum.io/trust-level` annotation;
+ - adds a reference to the agent under **every** lifecycle point the hook
+ declares. For image hooks, the reference includes the image digest.
+
+ If the agent update fails, the install rolls back.
+
+**Before you install, set `capabilityCeiling` on the Host.** A missing
+ceiling counts as the empty set, so no capability can be granted. The UI has
+no editor for the ceiling.
+
+**Trust levels** (`low` < `mid` < `high`) come from the registry. They are
+taken at face value only for curated orgs: your cluster's own org,
+`@clerum`/`@evenfire`, and any org listed in `CONTROL_API_CURATED_HOOK_ORGS`.
+Every other org is capped at `CONTROL_API_DEFAULT_HOOK_TRUST_CAP` (default
+`mid`).
+
+### See and remove hooks on an agent
+
+Open **Agents** → the agent → **Advanced** → **Hooks**. The table lists each
+`{hook, phase}` reference. Row actions are **View details** and
+**Remove from \<phase\>**. Removing a reference leaves the hook installed. To
+remove it from the cluster, uninstall it on **Installed Guardrails**. That
+strips the reference from every Host first, then deletes the CR. **Add
+hook** goes to the same Marketplace list.
+
+The UI edits hook references only. It has no editor for rules, built-ins,
+trust floor, ceiling or limits, and it cannot attach an already-installed
+hook to a second agent. Use the CRD (Option B) for those. The UI preserves
+the fields it does not edit when it saves.
+
+## Hook behaviour you should know
+
+- **Capabilities are enforced on the response.** If a hook returns a deny
+ without `may_deny`, the deny is downgraded to no decision. A rewrite
+ without `may_rewrite` is dropped, and so is a substitute without
+ `may_substitute_result`. `may_add_context` is **not** enforced today.
+ Installed hooks can never change the system prompt.
+- **`failMode` only bites with the matching capability.** If a hook is
+ unavailable (timeout, 5xx, a malformed or oversized reply, or an SSRF
+ refusal):
+ - a `failMode: closed` hook with `may_deny` contributes a deny
+ (`hook_unavailable`);
+ - a closed `postToolUse` redactor with `may_rewrite` withholds the tool
+ result;
+ - a closed `postCallSuccess` hook with `may_substitute_result` withholds
+ the model output;
+ - in every other case the hook contributes nothing.
+
+ The CRD defaults to `closed`, but the install route and form default to
+ `open` unless **May deny** is selected.
+
+- **Timeouts.** The per-call deadline is the Host's
+ `limits.maxHookTimeoutMs`, default 5000 ms, on both lanes. mcp-host does
+ not read `LlmHook.spec.timeoutMs`.
+- **Circuit breaker.** `onUnavailable.mode: breaker` (threshold 5, cooldown
+ 30000 ms by default) short-circuits a down hook without dialing it. It
+ applies only to LLM-lane hooks **without** `may_deny`. A deny-capable hook
+ is always dialed.
+- **Digest binding.** For image hooks, mcp-host compares the Host's `digest`
+ with `LlmHook.status.observedDigest`. On a mismatch it quarantines the
+ hook: every call reports unavailable, so the fail-mode rules above apply.
+ The same happens to a co-located hook that lost a `DuplicatePath`
+ collision. Upgrade with `POST /admin/registry/upgrade-hook`, which bumps
+ the CR and every Host's digest together.
+- **The Host phase key does not filter.** mcp-host collects hook ids from
+ all phases. The `LlmHook`'s own `lifecyclePoints` decide where it runs.
+
+## Try the reference hook
+
+[`hooks/reference-guardrail-hook/`](../../hooks/reference-guardrail-hook/) is
+a zero-dependency Node server. It implements the **LLM-lane** points only:
+
+- `pre_call` rejects jailbreak phrases;
+- `moderate` returns 422 on disallowed content;
+- `post_call` redacts card, SSN and email patterns;
+- `on_error` returns a text fallback.
+
+It has no tool-lane endpoints. To try it:
+
+```bash
+docker build -t reference-guardrail-hook:dev hooks/reference-guardrail-hook
+minikube -p <profile> image load reference-guardrail-hook:dev
+kubectl apply -f hooks/reference-guardrail-hook/deploy.yaml
+```
+
+Then point an `LlmHook` at the Service and reference it from a Host. Use
+`kubectl`, because control-api only allows hooks to be created through
+`install-hook`:
+
+```yaml
+apiVersion: clerum.io/v1alpha1
+kind: LlmHook
+metadata: { name: reference-hook, namespace: llm-hooks }
+spec:
+ target:
+ service: { name: reference-guardrail-hook, namespace: llm-hooks, port: 8080 }
+ lifecyclePoints: [preCall, moderate, postCallSuccess]
+ capabilities: [may_deny, may_substitute_result]
+ failMode: closed
+---
+# On the Host (service targets have no digest to pin):
+spec:
+ guardrails:
+ capabilityCeiling: [may_deny, may_substitute_result]
+ hooks:
+ preCall: [{ id: reference-hook }]
+```
+
+host-context-controller marks a service-target hook `Ready=True` with reason
+`NoWorkload`. It also creates `llmhook-svc-reference-hook`, which admits
+ingress from the referencing Hosts only. A hand-applied CR skips the
+install-time trust-floor and ceiling checks (see Limits).
+
+## Verify
+
+1. Run `kubectl get llmhooks -n llm-hooks` and check that the hook is Ready
+ and that its digest matches the Host reference.
+2. Send a prompt the hook should block. You should get a canned refusal
+ (for example _"I can't comply with that request."_), not the model's
+ answer.
+3. For rules, trigger a matching tool call and look for the `Blocked by
+guardrail policy` result or a pending approval. The
+ `clerum_mcp_host_guardrail_decisions_total` metric counts decisions by
+ lane, source, outcome and reason.
+
+## Limits
+
+- **Install-time checks only.** `minInstalledHookTrustLevel` and
+ `capabilityCeiling` are checked by control-api at install and upgrade.
+ mcp-host does not re-check them at runtime, so a reference added by
+ editing the Host bypasses both.
+- **No runtime reader.** `approvalPolicies` and `limits.maxHooksPerPhase`
+ are accepted by the CRD, but nothing reads them today. Approver routing
+ stays in `spec.approval`.
+- **Response size caps.** `limits.maxHookOutputBytes` caps LLM-lane hook
+ responses. The CRD default (65536) applies only when a `limits` object is
+ present; otherwise mcp-host uses 1 MiB, and `preCall` rewrites get 5 MiB.
+ Tool-lane hooks are not capped by this field.
+- **LLM-lane only.** Quarantine on digest mismatch and the circuit breaker
+ are implemented for LLM-lane hooks only. Tool-lane hooks are dialed
+ without them.
+- **Doom-loop guard.** It is active whenever tool-lane rules or hooks exist:
+ three consecutive identical calls are denied (`repeated_identical_call`).
+ It is a runaway guard, not a security control, because alternating calls
+ evade it.
+- **Scope.** The aux/compaction model lane runs no guardrails.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spec.guardrails` vanishes after apply | The CRD is older than the field and pruned it. Apply `charts/clerum-crds` first, then re-apply the Host. |
+| Every tool call now asks for approval | Rules exist and nothing matched (`unmatched_ask`). Add catch-all `allow` rules per provenance. |
+| Cron or workflow tasks fail with "approval required but no approver is available" | A guardrail `ask` in an unattended run. Add a rule that resolves the call to `allow` or `deny`. |
+| Tasks fail right after you edit rules | The rule set is malformed and rejected as a whole. Check mcp-host logs for the rule id. |
+| Refusal "a required safety check is unavailable" | A `may_deny` hook with `failMode: closed` is unreachable, timing out, or quarantined. Check the hook's pod and the Host `digest` against `status.observedDigest`. |
+| mcp-host logs `digest mismatch ... quarantining` | The hook image changed without the Host pin. Use upgrade-hook, or update the `digest` to `status.observedDigest`. |
+| Install: `capability_exceeds_ceiling`, or no capability can be ticked | The Host has no `capabilityCeiling`, or the ceiling is too narrow. Set it on the Host. |
+| Install: `hook_below_trust_floor` | The hook's resolved trust is below `minInstalledHookTrustLevel`. |
+| Install: `content_egress_requires_high_trust` | The hook sees content and has egress or a remote target, so it needs `high` trust, which non-curated orgs never reach. Add the org to `CONTROL_API_CURATED_HOOK_ORGS` or use a hook without egress. |
+| Install: `content_access_conflict` | The entry declares `contentAccess: metadata` on a content-bearing point. The publisher must fix `hook_meta` and republish. |
+| Install: `hook_requires_org_scope` / `image_ref_not_digest_pinned` | Only org-owned entries with `@sha256:` image refs can be installed. |
+| Hook installed, but it never runs | Check that a Host references the hook's id, and that the CR is not `Ready=False/DuplicatePath`. A hook that returns a deny without `may_deny` is ignored. |
+
+## Related
+
+- [LlmHook CRD](../crds/llmhook.md)
+- [Host CRD → Guardrails](../crds/host.md#guardrails)
+- [Configure approvals](configure-approvals.md)
+- [Control UI](../surfaces/control-ui.md)
+- [Claims guardrails](../meta/claims-guardrails.md)
diff --git a/docs/how-to/connect-llm-subscription.md b/docs/how-to/connect-llm-subscription.md
new file mode 100644
index 000000000..be9ce631a
--- /dev/null
+++ b/docs/how-to/connect-llm-subscription.md
@@ -0,0 +1,293 @@
+# How to: use a ChatGPT (Codex) or Grok subscription instead of an API key
+
+evenfire has two LLM providers that sign in with a subscription account rather
+than an API key:
+
+| Provider id | Control UI label | Sign-in |
+| -------------------- | ----------------------- | ----------------------- |
+| `codex-subscription` | "ChatGPT Subscription" | ChatGPT account (Codex) |
+| `grok-subscription` | "xAI Grok Subscription" | xAI account (SuperGrok) |
+
+An admin signs in once from Control UI. Agents (Hosts) and workflow recipes
+then pick that sign-in, and the account's subscription entitlement pays for the
+calls instead of metered API billing. Both providers are **off in
+`deploy/base`** and switched on in the minikube overlay.
+
+This page covers the operator workflow. For the wire format, limits and error
+taxonomy, see the [Codex transport contract](../architecture/codex-subscription-transport-contract.md)
+and the [Grok transport contract](../architecture/grok-subscription-transport-contract.md).
+
+## How it works
+
+1. **control-api holds the credential.** The OAuth tokens are stored
+ encrypted in control-api's database. There is no Kubernetes Secret and no
+ `secretRef` slot for these providers.
+2. **A Host or recipe names a connection.** Each sign-in is a named
+ _connection_ (also called a _grant_). A Host picks one with
+ `spec.model.connectionRef`.
+3. **Traffic goes through a broker in `control-plane`.** For every model call,
+ `mcp-host` asks control-api to authorize the attempt and gets a single-use
+ ticket. It then streams to `codex-llm-proxy` or `grok-llm-proxy`, which
+ redeems the ticket, holds the access token only for that operation, and
+ calls the vendor's subscription endpoint. The model stream never passes
+ through control-api.
+4. **Models come from the account.** Each connection has its own model
+ catalog, read from the vendor at sign-in. There is no built-in default
+ model, and nothing falls back to an API key.
+
+## Enable on your cluster
+
+Every switch below defaults to off. Set them in this order: proxies and
+control-api first, then the Host and recipe switches.
+
+| Key | Where it lives | Codex | Grok |
+| ---------------------------------------- | ---------------------------------------------------------------- | -------- | ------------------------- |
+| `CONTROL_API_CODEX_SUBSCRIPTION_ENABLED` | ConfigMap `control-api-config` (ns `control-plane`) | `"true"` | — |
+| `CONTROL_API_GROK_SUBSCRIPTION_ENABLED` | ConfigMap `control-api-config` (ns `control-plane`) | — | `"true"` |
+| `CODEX_LLM_PROXY_EXECUTION_ENABLED` | ConfigMap `codex-llm-proxy-config` (ns `control-plane`) | `"true"` | — |
+| `GROK_LLM_PROXY_EXECUTION_ENABLED` | ConfigMap `grok-llm-proxy-config` (ns `control-plane`) | — | `"true"` |
+| `MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` | ConfigMap `mcp-host-config` (ns `mcp-host`) | `"true"` | — |
+| `WRC_GROK_SUBSCRIPTION_ENABLED` | `env` on the `workflow-recipes` Deployment (not a ConfigMap key) | — | `"true"` for Grok recipes |
+| `MCP_HOST_GROK_SUBSCRIPTION_ENABLED` | **Do not set.** HCC injects it per Host | — | automatic |
+
+Notes:
+
+- The flags accept only the exact string `true`. Any other value keeps the
+ feature off.
+- `deploy/base` does not ship an `mcp-host-config` ConfigMap. The Host
+ controller (HCC) loads it into every Host's `mcp-host` container with
+ `envFrom`, so your overlay must provide it. The minikube overlay does
+ (`deploy/overlays/minikube/configmaps/mcp-host-config.yaml`).
+- `MCP_HOST_GROK_SUBSCRIPTION_ENABLED` is added by HCC only to Hosts that are
+ actually configured for Grok, once control-api has Grok on. Do not put it in
+ `mcp-host-config`.
+- Each proxy needs its inter-service token in `codex-llm-proxy-secrets` or
+ `grok-llm-proxy-secrets`. `deploy/scripts/apply-inter-service-tokens.sh`
+ creates both.
+- Optional: `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED` in `control-api-config`
+ turns on periodic catalog refresh (see [Models and catalog sync](#models-and-catalog-sync)).
+- The minikube overlay sets everything in the table under
+ `deploy/overlays/minikube/` (`configmaps/*` and
+ `patches/workflow-recipes-grok.yaml`).
+
+Restart the affected Deployments after you change a ConfigMap. For upgrade
+order on a live cluster, see the Grok contract's
+[Rollout order](../architecture/grok-subscription-transport-contract.md#rollout-order).
+
+To check what control-api thinks is on, call
+`GET /api/v1/admin/llm/providers/capabilities`. It returns
+`{ "providers": { "codex-subscription": { "enabled": … }, "grok-subscription": { "enabled": … } } }`.
+
+## Connect a subscription
+
+1. In Control UI, open **Secrets → LLM Subscriptions**
+ (`/secrets/llm/subscriptions`).
+2. Create a subscription. Pick the **Provider** (ChatGPT or Grok; only
+ enabled providers are offered) and give it a **Name** of up to 64
+ characters. Agents see this name when they pick a subscription.
+3. Click **Sign in with ChatGPT** or **Sign in with Grok**. Control UI opens
+ the vendor's verification page in a new tab and shows a one-time code.
+ Sign in there with the subscription account and enter the code.
+4. When the sign-in completes, control-api reads the account's model catalog.
+ You see "Connected — catalog synced".
+5. Under **Enabled models**, turn models on or off. Under **Primary model**,
+ choose the default model. It must be one of the enabled models.
+
+For Grok, the sign-in panel shows a notice about how evenfire authenticates to
+xAI. Read it before you connect.
+
+### Device code vs browser sign-in
+
+Control UI always uses the **device-code** flow for both providers. It works
+with the public CLI client ids that control-api ships as defaults.
+
+control-api also has a **browser OAuth** flow for Codex only
+(`POST /api/v1/admin/llm/providers/codex-subscription/connections/:key/browser/start`).
+Control UI does not call it. It is refused with `browser_oauth_unregistered`
+unless `CONTROL_API_CODEX_OAUTH_CLIENT_ID` is set to an OpenAI client that you
+registered for this callback URL:
+
+```text
+<control-ui origin>/control-api/api/v1/auth/codex-subscription/callback
+```
+
+The origin comes from `CONTROL_API_CONTROL_UI_BASE_URL`. Grok has no browser
+flow.
+
+### Multiple named connections
+
+You can create as many connections as you need, for example one per team
+account. Each one has its own tokens, catalog and enabled models.
+
+- Keys are generated as `codex-<hex>` or `grok-<hex>`. Through the API you
+ can supply your own key instead: lowercase letters, digits and `-`, up to
+ 63 characters.
+- One vendor account can back only one live connection per provider. A second
+ sign-in with the same account fails with `fingerprint_in_use`.
+- `unassigned` is reserved for both providers.
+
+### The `deployment-default` connection
+
+`deployment-default` is a reserved Codex key from the original single-grant
+design. The un-keyed Codex admin routes (for example
+`GET …/codex-subscription/connection`) act on it. If it exists, a Host uses it
+only when its `connectionRef` names it explicitly. An empty `connectionRef` is
+never treated as `deployment-default`.
+
+Grok does not accept `deployment-default` at all. Every Grok connection uses
+a named key.
+
+## Assign a subscription to an agent
+
+### In Control UI
+
+1. Open the agent, then the **Models & creds** tab (`/agents/<name>/model`).
+2. Edit the model configuration and choose provider **ChatGPT Subscription**
+ or **xAI Grok Subscription**. The new-agent wizard offers the same options.
+3. In **Credential**, choose one of the subscriptions created under Secrets.
+ Agents only choose a subscription. Creating one happens under Secrets.
+4. Pick a model from that connection's enabled models and save.
+
+Saving without a subscription fails with "Choose a ChatGPT subscription
+before saving." (or the Grok version).
+
+### In the Host CRD
+
+```yaml
+apiVersion: clerum.io/v1alpha1
+kind: Host
+metadata:
+ name: chatllm
+ namespace: mcp-host
+spec:
+ host: chatLLM
+ contextRef: context1
+ model:
+ provider: codex-subscription # or grok-subscription
+ name: <a model enabled on this connection>
+ connectionRef: codex-0123456789abcdef
+```
+
+The CRD enforces these rules:
+
+- `spec.secretRef` may be omitted only when the primary and every
+ `llmPolicy.fallbacks[]` entry use the same subscription provider. With an
+ API-key fallback you still need `secretRef`.
+- `credentialSlot` is not allowed on a subscription fallback.
+- A Host may use at most one subscription provider across `model`,
+ `llmPolicy.fallbacks` and `allowedModels`. You cannot mix Codex and Grok.
+
+See [Host CRD](../crds/host.md) for the full schema.
+
+### What "unassigned" means
+
+A subscription Host with no `connectionRef` is **unassigned**. It is never
+given the execute permission, so it makes no model calls. It does not fall
+back to `deployment-default` or to an API key. Model calls fail with
+`unassigned_connection` ("Host has no coding-plan subscription assigned").
+
+### Admin API
+
+The admin API can also list Hosts and assign them without the agent page.
+Every route is under `/api/v1/admin/llm/providers/<provider-id>/`:
+
+| Route | Purpose |
+| --------------------------------------------- | --------------------------------------------------------------- |
+| `GET connections` | Connections with their assigned Hosts, plus `assignableHosts` |
+| `GET assignable-hosts` | Every Host with its provider, model and current `connectionRef` |
+| `POST connections/:key/hosts/:hostRef/bind` | Point a Host at this connection and seed a model |
+| `POST connections/:key/hosts/:hostRef/unbind` | Set the Host back to `unassigned` |
+
+## Models and catalog sync
+
+A connection's catalog is read at sign-in and **is not refreshed on its own**.
+A model the vendor publishes later does not appear until you sync:
+
+- In Control UI, open the subscription and click **Sync catalog**.
+- Or call `POST /api/v1/admin/llm/providers/<provider-id>/connections/:key/catalog/sync`.
+- `GET …/connections/:key/models` lists the catalog, and
+ `PATCH …/connections/:key/models/:model` with `{ "enabled": true|false }`
+ turns one model on or off.
+
+For periodic sync, set `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED: "true"` in
+`control-api-config`. The interval is `SUBSCRIPTION_CATALOG_SYNC_INTERVAL_MS`:
+6 hours by default, and control-api refuses to start below 15 minutes. It is
+off by default on purpose. Each tick calls the vendor once per connection,
+and a Grok token refresh during a tick rotates the refresh token.
+
+## Use a subscription in a workflow recipe
+
+Both providers are valid for `spec.agent.provider` and step agents in a
+`WorkflowRecipe`, with these rules:
+
+- A recipe may use at most one subscription provider.
+- `spec.agent.secretRef` is not allowed for a subscription provider.
+- The recipe picks a connection with an annotation, not a spec field. In the
+ recipe editor's confirm step, choose a **ChatGPT grant** or **Grok grant**.
+ Codex recipes store it in `clerum.io/codex-connection-ref` and
+ `clerum.io/subscription-connection-ref`. Grok recipes store it in
+ `clerum.io/subscription-connection-ref` only.
+- Grok recipes also need `WRC_GROK_SUBSCRIPTION_ENABLED=true` on
+ `workflow-recipes`. That switch controls the recipe's Grok permission,
+ egress policy and pod environment.
+
+## Refresh, reconnect and revoke
+
+- **Access-token refresh is automatic.** control-api refreshes the access
+ token when it authorizes a call. `POST …/connections/:key/refresh` forces
+ a refresh.
+- **Reconnect.** If the vendor rejects the saved refresh token, the
+ connection moves to `reauth_required` and Control UI shows
+ **Reconnect ChatGPT** / **Reconnect Grok**. This runs the same device-code
+ sign-in.
+- **Delete (revoke).** **Delete** in the subscription list revokes the
+ connection. control-api marks it revoked, cancels pending sign-ins, and asks
+ the vendor to revoke the refresh token. Agents assigned to it keep the reference but can no longer
+ authorize. Reassign them to another subscription.
+- **Grok revoke is permanent per key.** A revoked Grok key cannot be
+ reconnected. Create a new subscription instead. Access tokens issued
+ before the revoke stay valid until they expire.
+
+## Limits to know
+
+- **Output ceiling on Codex SDK grants.** A Plugin Workload SDK grant's
+ per-grant output ceiling (`maxOutputTokens`) becomes `max_tokens` on API-key
+ providers. The ChatGPT subscription endpoint cannot take that field, so for
+ `codex-subscription` only the transport contract's fixed limit applies.
+- **Image input.** Both providers accept PNG and JPEG image parts. The Grok
+ image limits are based on xAI's public API documentation. They have not been
+ measured against the Grok subscription endpoint. See
+ [Visual requests](../architecture/grok-subscription-transport-contract.md#visual-requests-issue-784).
+- **One subscription provider per Host or recipe** (see above).
+- **Requests are capped.** Message, tool and body-size caps are listed under
+ _Limits_ in each transport contract.
+
+## Troubleshooting
+
+| Symptom / error | Cause | Fix |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| No **LLM Subscriptions** content, or API `404 {"error":"disabled"}` | `CONTROL_API_*_SUBSCRIPTION_ENABLED` is not `true` | Set the flag in `control-api-config` and restart control-api |
+| Calls fail although sign-in worked; proxy answers `404 disabled` | `*_LLM_PROXY_EXECUTION_ENABLED` is off | Set it in the proxy's ConfigMap and restart the proxy |
+| Codex Host cannot build its provider | `MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` missing from `mcp-host-config` | Add it, then let HCC roll the Host |
+| Grok recipe is refused or cannot reach the proxy | `WRC_GROK_SUBSCRIPTION_ENABLED` is off | Set it on the `workflow-recipes` Deployment |
+| `browser_oauth_unregistered` | Browser OAuth with the default public client | Use device code, or register an OpenAI client and set `CONTROL_API_CODEX_OAUTH_CLIENT_ID` |
+| "… sign-in expired / denied / timed out" | Device code was not confirmed in time | Click **Sign in** again |
+| `fingerprint_in_use` | That account already backs a live connection | Use the existing connection |
+| `connection_key_taken` | Key already exists (for Grok, possibly a revoked key) | Choose another key |
+| `reauth_required` / "Reconnect" shown | Vendor rejected the refresh token | Click **Reconnect**, then **Sync catalog** |
+| New vendor model missing | Catalog is only read at sign-in | **Sync catalog**, or enable the cron |
+| `default_model_not_offered` | Default model is not an enabled model on that connection | Enable the model first |
+| `unassigned_connection` | Host has no `connectionRef` | Assign a subscription on **Models & creds** |
+| `spec.secretRef is required unless every LLM target is the same oauth-broker provider` | Mixed subscription + API-key chain without a Secret | Add `secretRef` for the API-key targets |
+| `a Host may declare at most one oauth-broker provider` | Codex and Grok on one Host | Use one subscription provider per Host |
+| `hosts_unavailable` (503) | control-api cannot read Host objects | Check control-api's Kubernetes access |
+
+## Related
+
+- [LLM providers](../llm-providers/README.md) (Group D: subscription sign-in)
+- [Codex subscription transport contract](../architecture/codex-subscription-transport-contract.md)
+- [Grok subscription transport contract](../architecture/grok-subscription-transport-contract.md)
+- [Grok subscription validation](../testing/grok-subscription-validation.md)
+- [Host CRD](../crds/host.md)
+- [Control UI](../surfaces/control-ui.md)
+- [Track usage and set token budgets](token-budgets-and-usage.md)
diff --git a/docs/how-to/connect-oauth-connector.md b/docs/how-to/connect-oauth-connector.md
new file mode 100644
index 000000000..c9e3e7c72
--- /dev/null
+++ b/docs/how-to/connect-oauth-connector.md
@@ -0,0 +1,263 @@
+# How to: connect an OAuth connector and manage connector credentials
+
+Some connectors (MCP servers) authenticate with OAuth instead of a static API
+key. For these, an operator installs the connector once, and each user (or one
+member of a Context) authorizes it in the browser. control-api keeps the
+tokens. This page covers that flow, then the second half of the topic:
+setting and rotating credentials for connectors that use a static Secret.
+
+Field-by-field reference: [McpServer CRD, OAuth (`spec.oauth`)](../crds/mcpserver.md#oauth-specoauth).
+
+## Mental model
+
+1. An operator installs an `McpServer` with `spec.auth.type: oauth` and a
+ `spec.oauth` block. No token is stored on the resource.
+2. A user authorizes it in the Desktop app. The provider redirects back to
+ control-api's OAuth callback, and control-api stores the grant encrypted
+ (AES-256-GCM, access and refresh tokens).
+3. When an agent calls a tool on that server, mcp-host asks control-api's
+ broker for a token for that connection and sends it as an
+ `Authorization: Bearer` header on the request.
+4. If no grant exists, the task pauses and the chat shows a **Connect** prompt
+ instead of Approve/Deny.
+
+Tokens are never mounted into the connector pod. host-context-controller only
+hashes and mounts the static `spec.envSecret`. For remote servers, the egress
+proxy it generates passes the per-request `Authorization` header through. It
+also rejects an OAuth server that pins a static `Authorization` header.
+
+## Prerequisites
+
+| Setting (control-api) | Default | What happens if it is wrong |
+| ------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MCP_OAUTH_BROKER_ENABLED` | **Off** in `deploy/base`, `true` in the minikube overlay | The token broker answers `404`, mcp-host reads that as "no grant", and the agent asks for consent forever, even after the user authorizes. Accepts only `true` or `false`. |
+| `CONTROL_API_OAUTH_CALLBACK_BASE_URL` | Unset in base, `http://127.0.0.1:8090` in minikube | Must be the bare, browser-reachable origin that routes `/api/v1/oauth-callback/` to control-api. When unset, control-api builds the redirect URI from the request Host, which is usually an internal hostname. Built-in, generic, and CIMD installs are rejected while it is unset. |
+| `CONTROL_API_OAUTH_STATE_HMAC_SECRET`, `CONTROL_API_OAUTH_ENCRYPTION_KEY` | Dev defaults; read from the control-api Secret in base | Generate real values (`deploy/scripts/gen-jwt-keys.sh` does this). The encryption key protects stored grants. |
+| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | **Off**, including in minikube | Remote-server tokens are only refreshed when someone uses them. See [Refresh and background use](#refresh-and-background-use). |
+
+The Control UI **Marketplace** OAuth install form (built-in and generic
+providers) shows the redirect URI using
+`NEXT_PUBLIC_CONTROL_API_OAUTH_CALLBACK_BASE_URL`. Next.js compiles this value
+into the Control UI bundle at build time. The shipped Dockerfile and the
+minikube image build do not set it. Without it, the form shows "not configured"
+and keeps **Install** disabled. The remote-server wizard is not affected,
+because control-api computes its redirect URI. If your build does not set the
+variable, install built-in and generic connectors with YAML (below).
+
+The desktop app opens the provider's authorize URL only if it uses `https:`.
+
+## Three ways to configure OAuth
+
+| Style | `spec.oauth.source` | How you install it | Redirect URI to register |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Built-in provider adapter | absent; `provider` is one of `salesforce`, `slack`, `notion`, `microsoft-graph`, `google`, `monday`, `clickup`, `vercel` | YAML, or the Marketplace OAuth form | `<CALLBACK_BASE>/api/v1/oauth-callback/<oauth.id>` |
+| Remote MCP server (discovery) | `remote` | Control UI **Add remote server** wizard | `/api/v1/oauth-callback/remote` if the authorization server supports RFC 9207 `iss`; otherwise `/api/v1/oauth-callback/remote/<serverName>` |
+| Generic, operator-configured client | `generic` | YAML, or the Marketplace OAuth form (adds an **Endpoints** step) | `<CALLBACK_BASE>/api/v1/oauth-callback/<oauth.id>` |
+
+Endpoints for `remote` and `generic` must use `https` and a public host. Hosts
+that resolve to private, metadata, link-local, or reserved addresses are
+rejected.
+
+`source`, `provider`, `oauth.id`, and `grantScope` cannot be changed after
+creation. To change one, delete the connector and install it again.
+Reinstalling invalidates existing grants: grants are bound to the McpServer's
+UID, so users must authorize again.
+
+### Who holds the grant: `grantScope`
+
+- **`user`** (default; shown as **Per user**): each user authorizes their own
+ account. One grant per user covers every agent of theirs that uses this
+ connector.
+- **`context`** (shown as **Per context** / **Shared (context)**): one shared
+ grant per Context. Any member authorizes it, and every agent in that Context
+ then acts with that identity. Desktop asks the user to confirm before
+ connecting or disconnecting a shared grant.
+
+Users can only authorize or disconnect servers whose `spec.contextRef` is a
+Context they belong to. Otherwise the request fails with
+`context_membership_denied`.
+
+## Operator: add a remote MCP server (Control UI)
+
+1. Open **Connectors** (`/connectors`) and click **Add remote server**
+ (`/connectors/remote/new`).
+2. **Identify**: enter the **Remote server URL** (for example
+ `https://mcp.example.com/mcp`), a **Server name** (a Kubernetes name), and
+ the **Context** to attach the server to. Click **Detect**.
+ control-api runs RFC 9728/8414 discovery and probes the MCP endpoint. If the
+ endpoint is unreachable, the wizard stays on this step and may suggest the
+ correct URL.
+3. **Configure**: review the detected issuer, endpoints, scopes, and
+ **Registration mode**. The mode is picked in this order:
+ - **Client ID Metadata Document (public client)**: no credentials. Offered
+ only when the server supports RFC 9207 `iss`. The client ID is a URL on
+ your callback origin
+ (`<CALLBACK_BASE>/api/v1/.well-known/evenfire-mcp-client`), so the
+ authorization server must be able to fetch it.
+ - **Dynamic Client Registration**: control-api registers a client and stores
+ its credentials encrypted. You do not supply any.
+ - **Pre-registered client required**: register an OAuth app at the provider
+ with the **Redirect URI** the wizard shows, then paste its **Client ID**
+ and **Client secret**.
+
+ Choose the **Grant scope**: **Per user** (recommended) or **Per context**.
+
+4. **Confirm**: review the summary and click **Install remote server**. If the
+ mode is pre-registered, the wizard shows the final redirect URI again.
+ Register exactly that URI. If the authorization server changed since
+ detection, the wizard warns that the URI is different.
+
+The install creates the client Secret (pre-registered only), the McpServer, and
+the Context attachment, and rolls back if a step fails. The resulting
+McpServer runs the platform egress proxy image (`clerum/nginx-egress-proxy`)
+with an exact-host egress binding to port 443 of the remote host. API
+equivalents: `POST /api/v1/admin/mcp-servers/remote/discover` (dry run) and
+`POST /api/v1/admin/mcp-servers/remote`.
+
+## Operator: built-in or generic provider (YAML)
+
+Create an OAuth app at the provider, register the redirect URI, and store the
+client credentials in a Secret in the MCP server namespace:
+
+```yaml
+apiVersion: clerum.io/v1alpha1
+kind: McpServer
+metadata:
+ name: notion
+ namespace: mcp-server
+spec:
+ contextRef: context1
+ # image, transport, egress: see the CRD reference
+ auth:
+ type: oauth # forbids auth.secretRef / auth.secretKey
+ oauth:
+ id: notion-mcp # callback path segment, immutable
+ provider: notion
+ clientIdRef: { name: notion-oauth-client, key: client_id }
+ clientSecretRef: { name: notion-oauth-client, key: client_secret }
+ scopes: [...] # provider-specific
+ grantScope: user
+```
+
+Redirect URI for this example:
+`<CONTROL_API_OAUTH_CALLBACK_BASE_URL>/api/v1/oauth-callback/notion-mcp`.
+For `generic`, set `source: generic` and add the endpoint and wire fields
+listed in the [CRD reference](../crds/mcpserver.md#oauth-specoauth).
+
+If the client Secret or one of its keys is missing, authorization fails with
+`503 integration_not_configured`, and the error message names the missing
+Secret.
+
+## End user: authorize, use, disconnect
+
+**Ahead of time:** in the Desktop app, open **Connectors**. There is one row
+per connector and agent, and each row shows **Authorized**, **Requires setup**,
+or **No OAuth**. Click **Authorize** to open the provider's consent page in your
+system browser. A connector you already authorized shows **Disconnect**.
+Connectors with static credentials (**No OAuth**) have no button.
+
+**In chat:** if an agent calls a tool on an OAuth connector you have not
+authorized, the task pauses and the progress card shows
+**Connect \<server\> to continue**. Clicking **Connect \<server\>** opens the
+same browser consent. When the browser hands control back to the app
+(`clerum://oauth-completed`), the paused task continues. The pause survives an
+mcp-host restart.
+
+## Refresh and background use
+
+- **Refresh on use:** when a stored access token is within 60 seconds of
+ expiry, control-api refreshes it before returning it. If there is no refresh
+ token, or a remote or generic server was installed with
+ `supportsRefresh: false`, the user is asked to connect again.
+- **Proactive refresh** of remote-server grants runs only when
+ `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED=true`. It is off by default.
+- **`backgroundAccess`** is a field on the spec (see the CRD reference). The
+ broker path agents use today requests tokens as a live session, so do not
+ count on unattended access without testing it in your environment. If you
+ need refresh, request the provider's offline or refresh scope.
+
+## Disconnect and revoke
+
+- **User:** **Disconnect** on the Desktop Connectors page. Desktop asks for
+ confirmation, then calls `DELETE /api/v1/mcp-oauth/<server>/grant` through
+ rpc-proxy, which deletes the stored grant. For a **Per context** connector,
+ this removes access for everyone in the Context.
+- **Admin (API only, no Control UI screen):**
+ `GET /api/v1/admin/mcp-servers/<name>/oauth/user-grants` lists users with a
+ grant. `DELETE /api/v1/admin/mcp-servers/<name>/oauth/user-grants/<userId>`
+ with body `{ "oauthClientId": "..." }` force-revokes one user's grant.
+- **Limits:** revocation deletes evenfire's copy of the grant. It does not call
+ the provider's revocation endpoint, so revoke the app at the provider too if
+ you need that. Sessions that are already running may keep a cached token
+ for a while. Desktop warns that "active sessions end on the next revocation
+ sweep."
+
+## Part 2: credentials for static-credential connectors
+
+Connectors that use API keys read them from the Secret named in
+`spec.envSecret` (in the MCP server namespace). OAuth connectors do not use
+this flow. Their **Credentials** tab shows the client configuration read-only,
+and rotating an OAuth client secret is not available in Control UI.
+
+### Install now, add credentials later
+
+When you install a connector from the **Marketplace**, leave every credential
+field empty to install it without credentials. A partly filled form is
+rejected. host-context-controller then sets the condition
+`SecretResolved=False` (reason `SecretNotFound`) and does not deploy the
+connector. **Connectors** shows the badge **Missing Secret**.
+
+```bash
+kubectl get mcpserver <name> -n mcp-server \
+ -o jsonpath='{.status.conditions[?(@.type=="SecretResolved")]}'
+```
+
+### Set or rotate credentials
+
+Open the connector, click **Edit connector**, and select the **Credentials**
+tab (`/connectors/<name>/edit`). The tab lists each Secret key and its
+environment variable. Stored values are never shown.
+
+- **Secret missing** (`SecretNotFound`): the section is **Set credentials**.
+ Fill every key, click **Set credentials**, then confirm with **Set & start**.
+ This creates the Secret, and the connector starts.
+- **Secret exists** (including `SecretMissingKey`): the section is
+ **Update credentials**. Fill only the keys you want to change; blank fields
+ keep their current value. Click **Rotate credentials**, then confirm with
+ **Rotate & restart**.
+
+Rotation calls `PUT /api/v1/admin/mcp-secrets/<name>` with `{ "data": { ... } }`.
+This is a server-side merge patch: the keys you send are added or replaced, and
+every other key stays. Empty values are rejected, and the response never echoes
+values. It also returns `affectedConnectors`: every McpServer whose
+`spec.envSecret` uses this Secret. Secrets owned by a WorkflowRecipe are
+refused (`409`).
+
+control-api does not restart anything itself. host-context-controller watches
+Secrets, recomputes a SHA-256 of the Secret data, and writes it to the pod
+template annotation `clerum.io/credentials-revision`. Every affected Deployment
+then rolls out. The Control UI waits up to 180 seconds for this connector's
+Deployment to become ready again. Other connectors that share the Secret roll
+out too, but the screen only tracks the current one.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Agent keeps asking to **Connect** after the user authorized | `MCP_OAUTH_BROKER_ENABLED` is not `true` | Set it on control-api and restart |
+| Provider says `redirect_uri` mismatch | Callback base is unset or wrong, or the registered URI differs from the one shown | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` to the public origin. Register the exact URI the wizard shows. |
+| Remote install returns `callback_base_url_unconfigured` | CIMD, or a server without RFC 9207, needs the public callback origin | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` |
+| **Detect** stops with an unreachable transport (`transport_unreachable` on install) | The URL is not the MCP endpoint | Use the URL the wizard suggests, or the server's documented MCP path |
+| Marketplace OAuth form says the callback URL is not configured | `NEXT_PUBLIC_CONTROL_API_OAUTH_CALLBACK_BASE_URL` was not set when Control UI was built | Rebuild Control UI with it, or install with YAML |
+| `503 integration_not_configured` | The client ID or secret Secret, or one of its keys, is missing | Create the Secret the hint names |
+| `403 context_membership_denied` | The user is not a member of the server's Context | Add the user to the Context |
+| Users must authorize again after a reinstall | Grants are bound to the old McpServer UID | Expected |
+| Connector shows **Missing Secret** | `SecretResolved=False` | Use **Set credentials** on the **Credentials** tab |
+| Rotation restarted other connectors | They share the same `envSecret` | Expected. Check `affectedConnectors`. |
+
+## Related
+
+- [McpServer CRD: OAuth and status conditions](../crds/mcpserver.md#oauth-specoauth)
+- [Add an MCP server](add-mcp-server.md)
+- [Configure approvals](configure-approvals.md)
+- [Control UI](../surfaces/control-ui.md) and [Desktop app](../surfaces/desktop-app.md)
diff --git a/docs/how-to/desktop-setup-and-updates.md b/docs/how-to/desktop-setup-and-updates.md
index 213b2c4ad..694aa8d92 100644
--- a/docs/how-to/desktop-setup-and-updates.md
+++ b/docs/how-to/desktop-setup-and-updates.md
@@ -90,8 +90,8 @@ After you authenticate, the app checks the **currently selected tenant** for its
update policy, so different tenants can be on different versions at the same
time. It asks that tenant's External REST API for its release info, including a
`minimumDesktopVersion`. If the installed version is **below** that minimum, the
-app shows an **update-required** screen and opens the release page for the new
-build (tag `desktop-app-<version>`) in your browser. (A packaged distribution is
+app shows a **Desktop update required** dialog; **Download update** opens the
+release page for the new build (tag `desktop-app-<version>`) in your browser. (A packaged distribution is
where this matters most — a source checkout can just pull the latest.)
This is update **detection**, not silent auto-install: the app tells the user an
diff --git a/docs/how-to/use-the-desktop-app.md b/docs/how-to/use-the-desktop-app.md
new file mode 100644
index 000000000..beffe3184
--- /dev/null
+++ b/docs/how-to/use-the-desktop-app.md
@@ -0,0 +1,305 @@
+# How to: use the Desktop App day to day
+
+The Desktop App is where members chat with their agents, approve the actions
+that need a human, open the apps that plugins ship, and work with files in
+EvenDrive. This guide walks through the screens as they appear in the app. It
+is written for members, and for the admins who help them.
+
+For what the app is and how it connects to the platform, see
+[Desktop App](../surfaces/desktop-app.md). For adding environments, the
+invitation setup, and update checks, see
+[Desktop setup & updates](desktop-setup-and-updates.md).
+
+> **Shortcut convention.** **Mod** means **Cmd (⌘)** on macOS and **Ctrl** on
+> Windows and Linux. For example, Mod+K is ⌘K on a Mac and Ctrl+K elsewhere.
+
+## First run
+
+The first time you open the app, it has no server to connect to yet, so it
+shows a short setup wizard instead of the sign-in screen. The first question
+is **Do you already have an Evenfire server?**, and it has three answers:
+
+| Answer | What happens next |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **My team already uses Evenfire** | **Connect to your team**: enter the email address your team invited and choose **Continue setup**. The app opens your browser so you can finish setup there. |
+| **I have a server address** | **Connect to a server**: enter an **Environment name** and the **External REST API** address, then choose **Save environment**. If the app finds an Evenfire server running on this computer, it also offers a one-click **Localhost** option. |
+| **No, I'm just getting started** | **How do you want to run Evenfire?**, with three choices: **Evenfire hosts it for me**, **I'll run it myself**, or **I have no idea**. The last one opens **Which one is right for you?**, which compares the two options. |
+
+The hosted and self-hosted choices each explain the option and offer a
+button that opens more in your browser: **See hosted Evenfire** or
+**Open the deployment guide**. A second button,
+**I have a server — enter its address**, takes you to **Connect to a server**. Use **Back** at the bottom of the card to change an
+earlier answer.
+
+After setup you sign in with your **Email** and **Password**. If you forgot
+your password, **Forgot password** opens the reset page in your browser.
+Environments are added and switched from the **Environment** selector at the
+bottom of the sign-in screen. See
+[Desktop setup & updates](desktop-setup-and-updates.md) for details.
+
+## Find your way around
+
+### Sidebar
+
+| Entry | What it does |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Chat** | Opens your chats. The **New chat** button next to it starts a chat. Expand it to see your most recent sessions. Each session has a **⋯** menu with **Rename** and **Delete** (deleted messages can't be recovered). |
+| **Apps** | Opens the app picker. Expand it to launch an app directly. |
+| **EvenDrive** | Opens your files. Expand it to see a file tree that you can browse right in the sidebar. |
+| **Settings** (bottom) | Opens a menu that shows your name and email, plus **Agents**, **Connectors**, **Plugins**, **Settings**, and **Logout**. |
+
+You can collapse the sidebar to icons with **Collapse sidebar** and bring it
+back with **Expand sidebar**.
+
+### Tabs and Home
+
+Chats, apps, EvenDrive folders, and file previews open as **tabs** in one
+strip across the top of the window. Tabs stay open as you move around the
+app. You can drag a tab to reorder it, and close it with its **×**. Closing a
+chat tab doesn't delete the conversation; you can reopen it from the sidebar.
+When no tabs are open, Home shows **Nothing open** with a **New chat** button.
+
+### Title bar
+
+The window has its own title bar on every platform:
+
+- **Search** (Mod+F) searches your **Agents**, **Connectors**, **Plugins**,
+ and **Apps**.
+- The bell, **Notifications and approvals**, opens your inbox. When something
+ is waiting on you, it shows a **Pending approvals** section at the top.
+- **Open chat drawer** appears while you're on a tab that isn't a chat, such
+ as an app or a folder. It opens a chat panel on the right so you can talk to
+ an agent alongside your work.
+- The window buttons (**Minimize**, **Maximize**/**Restore**, **Close**)
+ follow your platform's order. Double-click an empty part of the title bar
+ to maximize or restore the window.
+
+### Chat drawer
+
+The chat drawer is a resizable panel on the right. At the top is the
+**Open chats** switcher, which lets you jump between open chats. While an app
+is open, Mod+E opens the drawer and puts you in the switcher. The
+drawer also has buttons for **New chat**, **Open chat in full screen**, and
+**Collapse chat drawer**. If the window gets too narrow, the drawer hides
+itself and comes back when there's room again.
+
+## Chat with an agent
+
+1. Start a chat with **New chat** (or Mod+T). The page asks
+ **Start a new conversation with:** followed by an agent picker. Choose the
+ agent you want.
+2. Type in the composer. **Enter** sends the message. **Shift+Enter** adds a
+ new line. While a chat is showing, in a tab or in the drawer, Mod+Shift+L
+ moves the cursor to the composer.
+3. While the agent works, a live status line shows what it's doing, such as
+ `Using <tool>`, `Thinking …`, or `Finished <tool>`. When the answer
+ arrives, **More details · N tools** expands the steps behind it, and the
+ square **Stop agent** button cancels a run that's still going.
+
+### Add context and attach files
+
+The **+** button (**Add context**) in the composer opens a menu with:
+
+- **Plugins** and **Connectors**: attach a reference to a specific plugin or
+ connector so the agent knows to use it.
+- **Upload Files**: pick files from your computer. You can also drag files
+ onto the composer (**Drop files here**) or paste them in.
+
+The composer checks each message before sending it and explains anything
+that won't fit:
+
+| Limit | Value |
+| --------------------------------------------------- | ------------------------------------------- |
+| Attachments per message (images and files together) | 20 |
+| Size of each file | 11 MiB |
+| Size of all files in one message, once encoded | 16 MiB |
+| Image formats | JPEG and PNG |
+| Size of each image (most models) | 3 MB, with up to 8 MB of images per message |
+
+Some models accept larger images. For Codex and Grok subscription models, the
+limit is 16 MiB per image and 16 MiB in total, and Codex images can be at
+most 2048 px on their longest side. If the model you've chosen doesn't accept
+images, the composer tells you.
+
+### Choose a model for this chat
+
+The model chip in the composer shows which model the chat uses. Click it to
+pick another model your admin allows. The change **applies to your next
+message**, not to one that's already running. If the list can't load, the
+chip reads **Models unavailable**; click it to try again.
+
+### Approve, deny, or connect
+
+Some tool calls need your approval before they run, depending on how your
+admin set up approvals (see [Configure approvals](configure-approvals.md)).
+When that happens, the run pauses in the chat and shows
+**`<tool>` requires approval**, with a preview of the tool's input and
+**Approve** and **Deny** buttons. Approvals from plugin workflows also show up
+under **Pending approvals** in the notifications inbox.
+
+If a connector needs you to sign in first, the chat shows
+**Connect `<server>` to continue** and a **Connect `<server>`** button
+instead. The button opens the provider's sign-in page.
+
+### Generated files
+
+When an agent produces files, they appear under the answer in a
+**Generated files** list. You can **Download** each file, or use
+**Download all**. HTML and Markdown files also have a **Preview** button.
+
+## EvenDrive
+
+**EvenDrive** in the sidebar opens the **Files** page. It starts at
+**Shared with me**, which lists everything that has been shared with you;
+click a folder to go into it. The breadcrumb at the top shows where you are.
+
+- **Add files.** In a folder you can edit, use **New folder** and
+ **Upload file**, or drag files onto the page. The server sets the size
+ limit for uploads, and the app tells you if a file is too large.
+- **Organize.** Each item's menu has **Rename**, **Move to…**, **Download**,
+ and **Delete**, depending on your access. When you open a file you can edit,
+ its menu also has **Replace file**. You can also drag an item onto a folder
+ to move it. Deleting a file or folder deletes it for everyone who has
+ access.
+- **Share.** Choose **Share** to open the sharing dialog. Under
+ **Add people, teams, agents, or workflows**, you can give someone **Read** or
+ **Editor** access. The **People with access** list shows who already has
+ access, including people who get it from a parent folder. A folder's
+ permissions apply to everything inside it, so changing or removing someone's
+ inherited access on one item asks you to confirm the change on the parent
+ folder (**Update role on parent folder?** or **Remove from parent folder?**).
+ To give one file less access than its folder, put it in a separate folder
+ with more limited access.
+- **Preview.** Images, Markdown, and videos open in a preview tab.
+- **Links.** **Copy link** copies a link to an item. On **Shared with me**,
+ **Open EvenDrive link** lets you paste a link to go straight to that item.
+
+For how EvenDrive storage works behind the scenes (the GlobalFileSystem), see
+[Shared and global files](shared-and-global-files.md).
+
+## Agents
+
+**Settings → Agents** lists the agents you can use (_Create, manage, and
+monitor your AI agents from one place_). Open an agent to see its
+**Connectors**, **Members**, and **Activity** sections. In a new chat, each
+agent in the agent picker has a **⋯** menu that jumps to the same sections.
+
+## Connectors
+
+**Settings → Connectors** lists each connector for each agent you can use,
+with a status of **Authorized**, **Requires setup**, or **No OAuth**. Choose
+**Authorize** to sign in to a connector's provider, or **Disconnect** to
+remove your access. Hover over the status to see whether access applies only
+to you or is shared with your whole Context. Click a row to open that
+agent's own Connectors tab. For the full sign-in flow, see
+[Connect an OAuth connector](connect-oauth-connector.md).
+
+## Apps and Plugins
+
+**Apps** lists the apps that your plugins provide, with the heading
+**Discover and launch tools to help you work smarter**. Click an app to open
+it in a tab inside the app window. While an app is open, the title bar has
+**Refresh app content** and **Copy current app link**. The first time a
+plugin asks to read your information, you'll see
+**`<plugin>` wants access to your information**, with **Allow** and **Deny**.
+You can review or remove that access later under
+**Settings → Plugin permissions**, using **Revoke** or **Revoke all**.
+
+**Settings → Plugins** lists the plugins deployed for you, along with their
+**Status** and **Recent Runs**. You can download files produced by recent
+runs from here. **Trigger** starts a plugin, asking for any inputs it needs,
+if the plugin supports being started by hand. **Refresh** reloads the
+run list.
+
+## Keyboard shortcuts and the command palette
+
+| Shortcut | Action |
+| ------------------------- | --------------------------------------------------------------------- |
+| Mod+T | New chat tab |
+| Mod+E | Open chats switcher (while an app is open) |
+| Mod+W | Close current tab (the conversation is kept) |
+| Mod+1 … Mod+8 | Select tab 1–8 |
+| Mod+9 | Select last tab |
+| Ctrl+Tab / Ctrl+Shift+Tab | Next / previous tab (this is Ctrl on every platform, including macOS) |
+| Mod+F | Focus global search |
+| Mod+Shift+F | Search current content (find text in the open chat or app) |
+| Mod+Shift+L | Focus message composer (while a chat is showing) |
+| Mod+K | Open command palette |
+| Mod+, | Open Settings |
+
+These shortcuts also work while an app has focus. You can't change them:
+**Settings → Shortcuts** lists them for reference only.
+
+**Mod+K** opens the command palette (**Type a command**). Besides everything
+in the table above, it can run commands that have no shortcut:
+**Keyboard shortcuts**, **Log out**, **Go to Chat / Apps / Agents / Plugins /
+Connectors / EvenDrive**, **Open notifications and approvals**,
+**Toggle sidebar**, **Refresh current app**, and **Back to Apps**. The palette
+only lists the commands that make sense at that moment.
+
+## Links that open the app
+
+The app handles `evenfire://` links:
+
+| Link | What it does |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `evenfire://desktop-environment?externalRestApiBaseUrl=…` | Adds or updates an environment. The app first asks **Add desktop environment?** and shows the addresses, so you can check that you trust them. Profile UI's **Open desktop app and setup** button opens this kind of link. |
+| `evenfire://desktop-setup?…` | Finishes invitation setup after you complete it in the browser. |
+| `evenfire://logout` | Signs the app out. |
+| `evenfire://app/<namespace>/<name>?path=…&team=…` | Opens an app, optionally on a specific page and team. The app first asks **Open app link?**; choose **Open** or **Dismiss**. |
+
+**Copy current app link** copies a regular web link of the form
+`https://<profile-ui>/open/apps/<namespace>/<name>`, which you can paste
+anywhere. Opening it in a browser hands it to the Desktop App as an
+`evenfire://app/…` link, so the person you share it with lands in the same
+app (as long as they have access to it).
+
+## Settings
+
+Open Settings with **Settings → Settings** or Mod+,. It has these tabs:
+
+- **Account**: your name and email. **Edit** and **Update password** open
+ your profile in Profile UI.
+- **Appearance**: **Dark** or **Light** theme.
+- **Notifications**:
+ - **In App Notifications** and **Desktop notifications** each let you
+ choose **Always show notifications**, **Show while I'm elsewhere in
+ Evenfire**, or **Show only when I'm away from Evenfire**.
+ - **Channel fallback** chooses whether Telegram or Slack should get plugin
+ notifications when the desktop app doesn't acknowledge them in time.
+ - **Notification sound** sets the alert volume.
+- **Plugin permissions**: see [Apps and Plugins](#apps-and-plugins).
+- **Social channels**: appears only if your account has social channels
+ available. It links to Profile UI to set them up.
+- **Shortcuts**: the keyboard shortcut reference.
+- **Information**: the app version, the External REST API and RPC proxy
+ addresses with their versions and health, and whether an update is
+ required. This is the first place to look when something seems off.
+
+Environments aren't managed in Settings. Add and switch them from the
+**Environment** selector on the sign-in screen.
+
+## Troubleshooting
+
+| You see | What it means / what to do |
+| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| On sign-in: **Couldn't reach `<environment>`. A local Evenfire looks like it's running — switch to `<other>` and retry?** | The selected environment isn't responding, but one on this computer is. Choose **Switch to `<other>` & retry**, or pick the right environment from the **Environment** selector. |
+| **Services Unavailable**, with `external-rest-api` or `rpc-proxy` marked unavailable | The app can't reach the server. Choose **Retry Health Check**. If it keeps failing, ask your admin whether the server is up. |
+| **Desktop update required** | Your server needs a newer version of the app. **Download update** opens the release page. **More info** shows the version you have and the latest one. |
+| **Desktop notifications are blocked by system permission.** (in **Settings → Notifications**) | Allow notifications for Evenfire in your operating system's settings. |
+| The composer says **Agent degraded — fix the LLM Secret to resume.** | The agent's model credentials aren't working. An admin needs to fix the agent's LLM Secret. |
+| **Connect `<server>` to continue** in a chat | Choose **Connect `<server>`**, or use **Authorize** on the Connectors page. |
+| **Models unavailable** on the model chip | The model list couldn't load. Click the chip to try again. |
+| **File access is not authorized** in EvenDrive | Choose **Retry file access**. If it still fails, sign in again or ask an admin. |
+| **Session refresh failed: …** in an open app | Close the app and open it again. |
+| **A message can carry at most 20 attachments.** (or a size message) | Remove some attachments, or split them across several messages. See [the limits above](#add-context-and-attach-files). |
+| Something else looks wrong | Check **Settings → Information** for health status and versions, and share it with your admin. |
+
+## Related
+
+- [Desktop App](../surfaces/desktop-app.md): what the app is, how it's wired, how to package it
+- [Desktop setup & updates](desktop-setup-and-updates.md): environments, invitations, update checks
+- [Configure approvals](configure-approvals.md): which tool calls ask for approval
+- [Connect an OAuth connector](connect-oauth-connector.md): the connector sign-in flow
+- [Shared and global files](shared-and-global-files.md): the storage behind EvenDrive
+- [Profile UI](../surfaces/profile-ui.md): account, password, and desktop setup in the browser
diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.md
index 35b21c09a..219eb7b63 100644
--- a/docs/llm-providers/README.md
+++ b/docs/llm-providers/README.md
@@ -119,14 +119,16 @@ authenticates with an `api-key` header instead of `Authorization: Bearer`, and
| Grok subscription | `grok-subscription` | OAuth sign-in held by control-api, no Secret slot | `CONTROL_API_GROK_SUBSCRIPTION_ENABLED`, `GROK_LLM_PROXY_EXECUTION_ENABLED`, `WRC_GROK_SUBSCRIPTION_ENABLED` (recipes); mcp-host's flag is injected per Host |
These providers use a subscription account instead of an API key. An admin
-signs in from Control UI (**Secrets → LLM → Subscriptions**,
+signs in from Control UI (**Secrets → LLM Subscriptions**,
`/secrets/llm/subscriptions`); control-api
keeps the OAuth tokens, and model traffic goes through the in-cluster
`codex-llm-proxy` / `grok-llm-proxy`. A Host selects a sign-in with
`spec.model.connectionRef` and needs no `secretRef` when every target is
the same subscription provider. A Host may use at most one subscription
provider. They are **off in `deploy/base`** and switched on in the minikube
-overlay. Wire-level details:
+overlay. Setup guide:
+[Use a ChatGPT or Grok subscription](../how-to/connect-llm-subscription.md).
+Wire-level details:
[Codex transport contract](../architecture/codex-subscription-transport-contract.md),
[Grok transport contract](../architecture/grok-subscription-transport-contract.md).
diff --git a/docs/llms.txt b/docs/llms.txt
index 78e8900dd..48ad80066 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -36,6 +36,9 @@
- Connect Telegram: how-to/connect-telegram.md
- Connect Slack (app scopes, request URL, verify flow, approval buttons): how-to/connect-slack.md
- Connect Microsoft Teams (Teams CLI registration, derived endpoint, single-tenant requirement, verify flow): how-to/connect-teams.md
+- Use the Desktop App (chat, attachments, EvenDrive, shortcuts, deep links): how-to/use-the-desktop-app.md
+- Configure guardrails (rules, installed hooks, built-ins): how-to/configure-guardrails.md
+- Connect an OAuth connector (remote MCP servers, user authorization, connector credentials): how-to/connect-oauth-connector.md
- Configure approvals: how-to/configure-approvals.md
- Add MCP server: how-to/add-mcp-server.md
- Desktop setup & updates (environments, invitation, updates): how-to/desktop-setup-and-updates.md
@@ -49,6 +52,7 @@
- LLM providers overview (the 24 providers, including the Codex and Grok subscription sign-ins, mental model, support matrix): llm-providers/README.md
- Configure LLM providers — operator guide (credentials, Vertex/Bedrock/Azure, allowlist, session selector): deploy/llm-providers.md
+- Use a ChatGPT (Codex) or Grok subscription instead of an API key: how-to/connect-llm-subscription.md
- Add an LLM provider (data-only vs driver-based integration): llm-providers/adding-a-provider.md
## Deploy & operate
diff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.md
index e159e90a5..5d248a773 100644
--- a/docs/surfaces/desktop-app.md
+++ b/docs/surfaces/desktop-app.md
@@ -15,10 +15,9 @@ platform, and the [Control UI](control-ui.md) for the admin side of that split.
## The daily loop
-1. **Log in.** Password login posts to `POST /api/v1/auth/password-login`;
- Google login posts an already-issued `idToken` to
- `POST /api/v1/auth/google` — the token has to already exist, since the
- app does not drive a full OAuth browser redirect yet. Once a session is
+1. **Log in.** The sign-in screen offers email and password, posted to
+ `POST /api/v1/auth/password-login`. (The main process also exposes a
+ Google `idToken` login IPC, but no screen uses it today.) Once a session is
established, it is restored from the OS keychain via `keytar`, with a
local file fallback when no keychain is available.
2. **Pick a team.** Team listing and switching read the access catalog:
@@ -100,7 +99,8 @@ The app's top-level routes (`DESKTOP_ROUTES` in
**Apps** (`sandbox-ui`), **Agents** (`agents`), **Connectors**
(`mcp-servers`), **Plugins** (`workflows`), **EvenDrive** (`files`), a file
`preview` view, and **Settings**. Inside an agent, the workspace has
-Connectors, Members, Shared files and Activity sub-routes. Outside that
+Connectors, Members and Activity sub-routes (plus **Agent Files** when the
+app is built with `VITE_SHOW_AGENT_FILES_UI`). Outside that
authenticated shell sit the first-run onboarding flow, the auth page (login),
and `UnavailablePage`, shown instead of login when a required backend
dependency is unreachable.
@@ -117,7 +117,7 @@ Two screens worth calling out specifically:
fourth top-level product.
Below, the LeadForge recipe's own dashboard runs inside the Desktop App's
- frame — the app's rail and its "Back to apps" bar are still in charge, and
+ frame — the Desktop App's own navigation stays in charge, and
everything the plugin's UI loads comes through `rpc-proxy`. The plugin gets
a real interface; it does not get a second client to install.
@@ -240,8 +240,8 @@ above for why leaving it unset is silently wrong rather than loudly broken.
## Limits
-- The Google login path expects an already-issued `idToken`; there is no
- full OAuth browser redirect yet.
+- There is no Google or SSO sign-in screen; members sign in with email and
+ password.
- The activity stream never carries internal reasoning / chain-of-thought
content, and it is read-only — message submission always goes through the
`/messages` endpoint, never the stream.
@@ -255,6 +255,7 @@ above for why leaving it unset is silently wrong rather than loudly broken.
## Next
+- [Use the Desktop App](../how-to/use-the-desktop-app.md) — the end-user guide: chat, attachments, EvenDrive, shortcuts, deep links
- [UI Surfaces](README.md) — the persona matrix across all three consoles
- [Control UI](control-ui.md) — the admin console
- [Profile UI](profile-ui.md) — the invited member's front door