Skip to content

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

TypeScript

docs: address second-round review on correctness sweep

Jose Gabriel Ramirez Encinasc3272dd6bc5f
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 81872f958..8d424676f 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -520,9 +520,9 @@ a `Set<string>` so an unchanged hostRef triggers exactly one reconcile.
**RBAC:** HCC's `host-context-controller-channels-runtime` Role grants
`get/list/watch` on `communicationchannels.clerum.io` in the `channels`
-namespace. **Applied out-of-band** via `make gcp-dev-bootstrap-rbac` /
-`make gcp-prod-bootstrap-rbac` because the CD service account intentionally
-cannot grant RBAC (see `deploy/scripts/post-deploy-sync.sh`).
+namespace. **Applied out-of-band** with
+[`deploy/scripts/bootstrap-rbac.sh`](../../deploy/scripts/bootstrap-rbac.sh),
+because a deploy service account should not be able to grant RBAC.
---
@@ -1443,12 +1443,19 @@ Default: `your-registry.example.com/evenfire/`
### Full Production Deployment Sequence
+The service Makefiles only build and push images; they have no `deploy`
+target. The workloads ship as Kustomize manifests under `deploy/base`, applied
+through an overlay. [Production deployment](../deploy/production.md) gives the
+rollout order, and [minikube](../deploy/minikube.md) is the scripted reference
+(`make minikube-deploy-all`).
+
```bash
# 1. Install CRDs
helm install clerum-crds ./charts/clerum-crds
-# 2. Deploy host-context-controller (operator must run first)
-cd host-context-controller && make deploy
+# 2. Apply the platform manifests (deploy/base through your overlay):
+# host-context-controller first, then control-api, mcp-host,
+# channel-reader and the proxies
# 3. Deploy MCP server secrets and CRDs
cd mcp-servers && make deploy-all
@@ -1456,16 +1463,10 @@ cd mcp-servers && make deploy-all
# 4. Create Context CRD (defines which servers are accessible)
kubectl apply -f charts/clerum-crds/examples/context1.yaml
-# 5. Deploy mcp-host
-cd mcp-host && make deploy
-
-# 6. Create Host CRD with API keys secret
+# 5. Create Host CRD with API keys secret
kubectl apply -f charts/clerum-crds/examples/host-chatllm.yaml
-# 7. Deploy channel-reader
-cd channel-reader && make deploy
-
-# 8. Create CommunicationChannel CRD
+# 6. Create CommunicationChannel CRD
kubectl apply -f charts/clerum-crds/examples/channels.yaml
```
diff --git a/docs/architecture/stateless-invariants.md b/docs/architecture/stateless-invariants.md
index 83af6039c..ab7b9cb79 100644
--- a/docs/architecture/stateless-invariants.md
+++ b/docs/architecture/stateless-invariants.md
@@ -7,9 +7,9 @@ reusable anti-patterns**. Four of the five share one root cause: _a decision
made on evidence that had already aged between its producer and its
consumer._ Encode these as guardrails so the class does not reappear.
-This doc is the "how to not reintroduce the class" companion to the
-narrative in
-[`docs/architecture/overview.md` §12 (Stateless Agents / Host Lifecycle)](overview.md#12-stateless-agents-host-lifecycle).
+This doc is the "how to not reintroduce the class" companion to the Host
+stateless lifecycle fields (`spec.lifecycle.stateless`, `status.lifecycle`) in
+the [Host CRD reference](../crds/host.md#spec-fields).
---
diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.md
index 3ea4d4d5a..b54916cec 100644
--- a/docs/crds/llmhook.md
+++ b/docs/crds/llmhook.md
@@ -16,8 +16,9 @@ A Host opts in by listing hooks under `Host.spec.guardrails.hooks.<phase>[]`
(see [Host CRD](host.md)). A Host without a `guardrails` block runs no hooks.
- **Image targets:** host-context-controller deploys a Deployment, Service,
- and NetworkPolicy in `llm-hooks`. Hooks that share an image digest are
- co-located on one pod and routed by `spec.path`.
+ and NetworkPolicy in `llm-hooks`. Hooks with the same image ref, port,
+ `envSecret`, `egressBindings` and `addCapabilities` are co-located on one
+ pod and routed by `spec.path`; a difference in any of these gets its own pod.
- **Service and remote targets:** nothing is deployed.
- **Who writes what:** mcp-host only reads LlmHook CRs. Only the controller
writes `status`.
@@ -32,11 +33,11 @@ install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,
| 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.ref` | string | yes (image) | Container image. Must be digest-pinned at install; the image allowlist is checked only when `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST` is on (default off). |
| `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`. host-context-controller rejects private, metadata, link-local and reserved destinations at reconcile (condition `InvalidEgress`) and fails the hook pod closed; unlike McpServer, this is not checked at admission. |
+| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. host-context-controller rejects private, metadata, link-local and reserved destinations at reconcile (reason `InvalidEgress`) and fails the hook pod closed; unlike McpServer, this is not checked at admission. |
| `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. |
@@ -64,12 +65,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 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[]` | A single `Ready` condition with `observedGeneration`; its `reason` is one of `NoWorkload`, `Deploying`, `Ready`, `DuplicatePath`, `SecretNotFound`, `InvalidEgress`, `ReconcileError`. |
`kubectl get llmhooks -n llm-hooks` shows Path, Order, FailMode, Digest, and Ready.
diff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.md
index e80de7292..e4163c45f 100644
--- a/docs/crds/mcpserver.md
+++ b/docs/crds/mcpserver.md
@@ -72,7 +72,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 (control-api's `CONTROL_API_MCP_SERVERS_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. |
diff --git a/docs/features/self-hosted-registry-ux-redesign.md b/docs/features/self-hosted-registry-ux-redesign.md
index 9c669ad04..53e59e5c8 100644
--- a/docs/features/self-hosted-registry-ux-redesign.md
+++ b/docs/features/self-hosted-registry-ux-redesign.md
@@ -8,7 +8,7 @@
> function that changes, grouped by the spec's five phases.
>
> **Scope boundary:** control-ui only. Confirmed **zero new backend endpoints**
-> are required for phases 1–5 (see [Backend: no new endpoints](#backend-no-new-endpoints)).
+> are required for phases 1–5 (see [Backend: no new endpoints](#04-backend-no-new-endpoints)).
---
diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
index 89ed4da70..538b10bea 100644
--- a/docs/get-started/quickstart.md
+++ b/docs/get-started/quickstart.md
@@ -24,7 +24,8 @@ named `chatllm` you can message immediately.
Mistral, … see [the full list](../llm-providers/README.md)) put its key in
`.env` **and** set `CLERUM_MODEL_PROVIDER` and `CLERUM_MODEL_NAME`. The pair
must be enabled in the model allowlist, or setup stops with
- `HOST_MODEL_UNKNOWN`. Setup only writes the four keys above to the cluster,
+ `HOST_MODEL_UNKNOWN` (pair not in the allowlist) or `HOST_MODEL_DISABLED`
+ (pair listed but disabled). Setup only writes the four keys above to the cluster,
so after `make minikube-setup` run `make minikube-apply-secrets` and then
`kubectl rollout restart deployment/chatllm -n mcp-host --context clerum-test`.
Without any key, setup still boots, but the agent can't reply until you add
diff --git a/docs/get-started/registry-quickstart.md b/docs/get-started/registry-quickstart.md
index c37d3e074..7ab43549d 100644
--- a/docs/get-started/registry-quickstart.md
+++ b/docs/get-started/registry-quickstart.md
@@ -90,13 +90,16 @@ press **Install**.
| Field | Notes |
| --------------- | ------------------------------------------------------------------------------------------------- |
-| **Name** | Optional. Left blank, it is generated from the entry name and version. Must be a valid K8s name. |
+| **Server name** | Under **Configuration**. Optional. Left blank, it is generated from the entry name and version. |
| **Credentials** | Only if the entry declares them. Fill in **all** fields or **none** (empty installs it pending). |
| **Egress** | Review the external hosts the connector needs. Default-deny networking means unlisted hosts fail. |
-The install runs as a server-side saga: it verifies the bundle digest, creates
-the `McpServer` with its own private access scope, and rolls back if a step
-fails. Afterwards, grant it to agents from **Installed Connectors**.
+The install runs as a server-side saga: it creates the `McpServer` with its own
+private access scope and rolls back the Secrets and `McpServer` it created if a
+later step fails. For a `local` (bundle) entry it also compares the bundle to
+the registry's published digest and stops on a mismatch; when the registry
+returns no digest, or the lookup fails, the install continues without that
+check. Afterwards, grant it to agents from **Installed Connectors**.
Verify it landed:
diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.md
index 85dd9eac7..05047e61a 100644
--- a/docs/llm-providers/README.md
+++ b/docs/llm-providers/README.md
@@ -119,7 +119,7 @@ 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** tab,
`/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
diff --git a/docs/testing/desktop-headful-journeys.md b/docs/testing/desktop-headful-journeys.md
index 39e046e2b..348b68090 100644
--- a/docs/testing/desktop-headful-journeys.md
+++ b/docs/testing/desktop-headful-journeys.md
@@ -49,10 +49,26 @@ journey always runs.
cd desktop-app
# dev Evenfire must be closed (process-wide single-instance lock)
# keep control-api / external-rest-api / rpc-proxy port-forwarded to loopback
-# (for a local minikube: make -C .. minikube-pf-desktop)
+# (standard single minikube profile: make -C .. minikube-pf-desktop,
+# fixed ports 8090 / 8091 / 8094)
npm run qa:recorder:navigation # one journey
-npm run qa:recorder:all # all 13 specs / 22 tests
+npm run qa:recorder:all # all 14 specs / 23 tests
+```
+
+On a **branch-owned profile** the forwards use profile-owned ports instead of
+8091 / 8094. Hold them on the host and point the recorder at them:
+
+```bash
+MINIKUBE_PROFILE=<owned-profile> \
+ make -f scripts/minikube-profiles/branch.mk branch-profile-pf # from the repo root
+MINIKUBE_PROFILE=<owned-profile> \
+ make -f scripts/minikube-profiles/branch.mk branch-profile-info # prints the ports
+
+cd desktop-app
+EXTERNAL_REST_API_BASE_URL=http://127.0.0.1:<external-rest-api-port> \
+RPC_PROXY_BASE_URL=http://127.0.0.1:<rpc-proxy-port> \
+ npm run qa:recorder:navigation
```
`qa:recorder:all` includes `qa-recorder-model-selector.spec.ts`, which fails loudly
diff --git a/scripts/e2e/README-mongodb-mcp-dev.md b/scripts/e2e/README-mongodb-mcp-dev.md
index 89cd471e4..2784c56a1 100644
--- a/scripts/e2e/README-mongodb-mcp-dev.md
+++ b/scripts/e2e/README-mongodb-mcp-dev.md
@@ -49,7 +49,7 @@ bash scripts/e2e/fix-mongodb-probes-dev.sh # re-apply probe workarou
### Validate Desktop App against the stack
```bash
-# ensure port-forwards are running first (make gcp-dev-pf-desktop)
+# first keep control-api :8090, external-rest-api :8091 and rpc-proxy :8094 forwarded to loopback
bash scripts/e2e/playwright-dev.sh chat.test.ts -g "MongoDB"
# ── Visual debug modes ──