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 information architecture

Jose Gabriel Ramirez Encinas1cabe9f48174
diff --git a/docs/README.md b/docs/README.md
index 046330182..d60084a68 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,19 +8,20 @@ deny-all-baseline networking — declared as Kubernetes CRDs.
> `CLERUM_*`). Same project — [code names](concepts/code-names.md).
Start at the root [`README.md`](../README.md) for the product pitch and license.
-Use this index for long-form docs. Pages describe what `deploy/base` and the
-minikube overlays ship; features that are off by default say so.
+Use this index for long-form docs. User and operator pages describe what
+`deploy/base` and the minikube overlays ship; features that are off by default
+say so. [Design records](#design-records) are point-in-time and not maintained.
---
## Get started
-| Doc | Description |
-| --------------------------------------------------------- | ---------------------------------------------- |
-| [Quickstart](get-started/quickstart.md) | Full platform on minikube with one command |
-| [Registry quickstart](get-started/registry-quickstart.md) | Connect, install, and publish as a self-hoster |
-| [Learning path](get-started/learning-path.md) | Choose a path by role and goal |
-| [FAQ](faq.md) | Common questions and troubleshooting |
+| Doc | Description |
+| --------------------------------------------------------- | -------------------------------------------------- |
+| [Quickstart](get-started/quickstart.md) | Full platform on minikube: set `.env`, one command |
+| [Registry quickstart](get-started/registry-quickstart.md) | Connect, install, and publish as a self-hoster |
+| [Learning path](get-started/learning-path.md) | Choose a path by role and goal |
+| [FAQ](faq.md) | Common questions and troubleshooting |
## Concepts
@@ -78,8 +79,8 @@ minikube overlays ship; features that are off by default say so.
| **Upgrade notes** | |
| [Workflow output PVC upgrade](deploy/workflow-output-pvc-upgrade.md) | Per-recipe output PVC ownership change |
| [Plugin Workload SDK upgrade](deploy/plugin-workload-sdk-upgrade.md) | promptBridge / clientNotifications rollout order and migration |
-| [GFS permission store](deploy/gfs-permission-store.md) | `gfs_controller` DB credential: provisioning, rotation, recovery |
| **Runbooks** | |
+| [GFS permission store](deploy/gfs-permission-store.md) | `gfs_controller` DB credential: provisioning, rotation, recovery |
| [Password work ownership recovery](how-to/password-work-ownership-recovery.md) | Recover the bcrypt work-bounding singleton |
| [MCP secret rollback permits](how-to/control-api-mcp-secret-rollback-permits.md) | Short-lived permits for the legacy MCP secret rollback path |
| [GFS large-file downloads](operations/gfs-large-file-host-downloads.md) | GFS admission limits vs visual model input |
diff --git a/docs/architecture/stateless-invariants.md b/docs/architecture/stateless-invariants.md
index 83af6039c..61023c787 100644
--- a/docs/architecture/stateless-invariants.md
+++ b/docs/architecture/stateless-invariants.md
@@ -8,8 +8,8 @@ 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).
+`spec.lifecycle.stateless` field and `status.lifecycle` states in the
+[Host CRD reference](../crds/host.md#spec-fields).
---
diff --git a/docs/deploy/llm-providers.md b/docs/deploy/llm-providers.md
index 977136d4b..4b663a683 100644
--- a/docs/deploy/llm-providers.md
+++ b/docs/deploy/llm-providers.md
@@ -59,7 +59,9 @@ returns key names only). To rotate a key, re-enter it.
- The driver builds GCP credentials **from the JSON in memory** — it never
writes a key file and does not use `GOOGLE_APPLICATION_CREDENTIALS`.
3. On the Host, open **Host → Environment** and set:
- - `VERTEX_PROJECT_ID` — the GCP project id (required).
+ - `VERTEX_PROJECT_ID` — the GCP project id. Set it explicitly: when it is
+ unset, the driver silently falls back to the service-account JSON's
+ `project_id`, and fails only if both are missing.
- `VERTEX_LOCATION` — the region, e.g. `us-central1` (optional; provider
default applies if unset).
4. Set the Host `spec.model.provider: vertex` and pick a Vertex model from the
@@ -106,7 +108,9 @@ the `clerum-model-secret-mapping` caveat.
> unset, mcp-host auto-detects the first provider whose keys are present.
> Because Bedrock's env vars are the standard `AWS_ACCESS_KEY_ID` /
> `AWS_SECRET_ACCESS_KEY`, a shell that already exports AWS credentials can
-> auto-select `bedrock`; set `CLERUM_MODEL_PROVIDER` explicitly to avoid that. See
+> auto-select `bedrock`; set `CLERUM_MODEL_PROVIDER` explicitly to avoid that.
+> Selection needs only the two keys, but Bedrock still needs `AWS_REGION` to
+> run; without it the provider fails to construct and mcp-host runs degraded. See
> [Local development](../llm-providers/README.md#46-local-development-no-kubernetes).
## 4. Extra credential slots (for provider fallback, R5)
diff --git a/docs/design/agent-models-credentials-ux.md b/docs/design/agent-models-credentials-ux.md
index 6e8f9c63d..1dbfcf426 100644
--- a/docs/design/agent-models-credentials-ux.md
+++ b/docs/design/agent-models-credentials-ux.md
@@ -236,4 +236,3 @@ Host or LLM Secret operation failed when the API can provide that detail.
- Shared-set impact and write-only limitations are visible before Save.
- The UI preserves drafts on failures and never places secret values in logs,
analytics, documentation, or error messages.
-
diff --git a/docs/design/self-hosted-registry-ux-redesign.md b/docs/design/self-hosted-registry-ux-redesign.md
index 9c669ad04..53e59e5c8 100644
--- a/docs/design/self-hosted-registry-ux-redesign.md
+++ b/docs/design/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 d11a67102..46686975f 100644
--- a/docs/get-started/quickstart.md
+++ b/docs/get-started/quickstart.md
@@ -100,9 +100,10 @@ It seeds for you:
- one account, using the `ADMIN_PASSWORD` you set in `.env`: username
**`admin`** for the Control UI and email **`[email protected]`** for the
Desktop App — the same account, and the sole Desktop App member. It is also
- the initial EvenDrive (GFS) operator. Re-running setup never recreates a
- revoked operator link or adds a second member; if the link is missing,
- setup stops with an actionable error.
+ the initial EvenDrive (GFS) operator. A default re-run of setup rebuilds
+ the control database, so it seeds a fresh link. With `REUSE_DB=true` it
+ keeps the database and never recreates a revoked operator link or adds a
+ second member; if the link is missing, setup stops with an actionable error.
Verify:
@@ -181,10 +182,15 @@ curl -s -X POST "$RPC/api/v1/rpc/hosts/$HOST/approvals/approve" \
## 5. Optional: chat from Telegram
-1. Create a bot with [@BotFather](https://t.me/BotFather); get your numeric
- user id (e.g. via `@userinfobot`).
-2. Set `CLERUM_TELEGRAM_BOT_TOKEN` and `CLERUM_TELEGRAM_USER_ID` in `.env`.
-3. Re-run `make minikube-setup ARGS="--skip-build"` and message your bot.
+1. Create a bot with [@BotFather](https://t.me/BotFather); copy the bot token
+ and its `@handle`.
+2. In the Control UI, open **External Channels** and create a channel: pick the
+ `chatllm` agent, choose Telegram, and paste the bot token and handle. The
+ token is stored as a write-only channel credential.
+3. Grant your Telegram account chat access, then message your bot.
+
+Setup does not read Telegram values from `.env`; channel credentials are set
+only through the Control UI (or the admin API).
Approval requests arrive on Telegram with inline **Approve / Deny** buttons.
Details: [Connect Telegram](../how-to/connect-telegram.md).
diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.md
index a470923a2..82f5eb315 100644
--- a/docs/llm-providers/README.md
+++ b/docs/llm-providers/README.md
@@ -217,9 +217,12 @@ deployment name. Step-by-step setup is in the operator guide:
### 4.6 Local development (no Kubernetes)
-Dev mode bypasses all of the above. Set `CLERUM_DEV_MODE=true` and export the
-provider's env var(s) — `OPENAI_API_KEY`, `GROQ_API_KEY`, `AWS_ACCESS_KEY_ID` +
-`AWS_SECRET_ACCESS_KEY`, etc. If `CLERUM_MODEL_PROVIDER` is unset, mcp-host
+Dev mode bypasses the Kubernetes setup above (Secrets, Host CRs). Set
+`CLERUM_DEV_MODE=true` and export the provider's env var(s) — `OPENAI_API_KEY`,
+`GROQ_API_KEY`, `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, etc. Bedrock
+also needs `AWS_REGION` to run: the two keys are enough for auto-selection, but
+without the region the provider fails to construct and mcp-host runs degraded.
+Azure likewise needs `AZURE_OPENAI_ENDPOINT`. If `CLERUM_MODEL_PROVIDER` is unset, mcp-host
**auto-detects** the first provider (in the canonical id order) whose required
slots are all present and uses that provider's default model;
`CLERUM_MODEL_NAME` applies only when `CLERUM_MODEL_PROVIDER` is also set.
@@ -375,17 +378,17 @@ failing over on those would just mask bugs.
## 8. Troubleshooting
-| Symptom | Cause |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Agent degraded, log `credential '<slot>' not found` | A required slot is missing. Bedrock needs **both** keys. |
-| Agent degraded, `failed to construct <provider>` | Missing non-secret env (`AWS_REGION`, `VERTEX_PROJECT_ID`, `AZURE_OPENAI_ENDPOINT`) or malformed Vertex JSON. |
-| `403 model_not_allowed` | Model isn't allowlisted/enabled for that provider. |
-| `404 No secret mapping found` (workflow step) | Provider has no entry in `clerum-model-secret-mapping` — see below. |
-| `500 ConfigMap not found` (workflow step) | `clerum-model-secret-mapping` missing from the `mcp-host` namespace. |
-| `502 mcp_host configure failed/unreachable` | WRC resolved the credential but couldn't configure mcp-host. |
-| Model dropdown empty in the wizard | No enabled allowlist rows for that provider. |
-| Context-window indicator looks wrong | `context_window_tokens` unset on the allowlist row → falls back to `CLERUM_CONTEXT_MAX_TOKENS`. |
-| Cost report shows a model as unpriced | No row in `llm_model_prices`; only 8 models are seeded. Add one under **Cost → LLM prices**. |
+| Symptom | Cause |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Agent degraded, log `Required LLM credential is missing` | A required slot is missing. Bedrock needs **both** keys. |
+| Agent degraded, log `Failed to construct LLM provider` | The log names neither provider nor cause. Check `AWS_REGION` (Bedrock), `AZURE_OPENAI_ENDPOINT` (Azure), or the Vertex JSON; Vertex uses the JSON's `project_id` when `VERTEX_PROJECT_ID` is unset and fails only if both are missing. |
+| `403 model_not_allowed` | Model isn't allowlisted/enabled for that provider. |
+| `404 No secret mapping found` (workflow step) | Provider has no entry in `clerum-model-secret-mapping` — see below. |
+| `500 ConfigMap not found` (workflow step) | `clerum-model-secret-mapping` missing from the `mcp-host` namespace. |
+| `502 mcp_host configure failed/unreachable` | WRC resolved the credential but couldn't configure mcp-host. |
+| Model dropdown empty in the wizard | No enabled allowlist rows for that provider. |
+| Context-window indicator looks wrong | `context_window_tokens` unset on the allowlist row → falls back to `CLERUM_CONTEXT_MAX_TOKENS`. |
+| Cost report shows a model as unpriced | No row in `llm_model_prices`; only 8 models are seeded. Add one under **Cost → LLM prices**. |
### Known sharp edge: workflow steps and the secret mapping
diff --git a/docs/llms.txt b/docs/llms.txt
index 78e8900dd..38a22f493 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -2,12 +2,12 @@
> Curated map of public docs. Prefer these paths over random monorepo files.
> Code/API still use the historical name "clerum" (clerum.io, CLERUM_*).
-> Docs describe what deploy/base and the minikube overlays ship; off-by-default features say so.
+> Docs describe what deploy/base and the minikube overlays ship; off-by-default features say so. design/ records are point-in-time, not maintained.
## Start here
- README: ../README.md — product pitch, security model, providers, license
-- Quickstart: get-started/quickstart.md — full platform on minikube, one command
+- Quickstart: get-started/quickstart.md — full platform on minikube: fill in .env, then one command
- Registry quickstart: get-started/registry-quickstart.md — self-hosted connect → install → publish round trip
- Learning path: get-started/learning-path.md
- FAQ: faq.md