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.mdindex 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.mdindex 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 itsconsumer._ 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.mdindex 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 neverwrites 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; providerdefault 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.mdindex 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.mdindex 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.mdindex 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 theDesktop 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.mdindex 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 requiredslots 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 mappingdiff --git a/docs/llms.txt b/docs/llms.txtindex 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