Skip to content

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

TypeScript

docs: reorganize the docs tree so every page is reachable

Jose Gabriel Ramirez Encinas829db12cd464
diff --git a/.env.example b/.env.example
index 6d9a413a9..e62eb15c7 100644
--- a/.env.example
+++ b/.env.example
@@ -9,7 +9,7 @@
# `make minikube-setup`. Setup creates the K8s secrets for you; the remaining
# MCP/channel credentials are optional and only needed for those integrations.
#
-# See docs/get-started/minikube.md for the full walkthrough.
+# See docs/get-started/quickstart.md for the full walkthrough.
# =============================================================================
# -----------------------------------------------------------------------------
diff --git a/README.md b/README.md
index 375be659b..c2b0cc273 100644
--- a/README.md
+++ b/README.md
@@ -64,8 +64,8 @@ make install-all && npm --prefix control-ui install
npm run ui # Control UI + Profile UI + Desktop App
```
-The full walkthrough (prerequisites, login, and the pure-API path) is in
-[Get started on minikube](docs/get-started/minikube.md).
+The full walkthrough (prerequisites, login, and the pure-API path) is in the
+[Quickstart](docs/get-started/quickstart.md).
Evenfire is meant to be run on a remote cluster — see [Deploying to a remote cluster](#deploying-to-a-remote-cluster).
@@ -119,8 +119,7 @@ to its deep dive.
- **vs a hosted assistant**: you own the data and the infrastructure. Evenfire
adds no vendor to the request path: with your own model keys, prompts and files
- go straight to the model provider you choose. Point an agent at a self-hosted
- or local model and nothing leaves your environment at all.
+ go straight to the model provider you choose.
- **vs an in-process agent framework**: real isolation and governance:
per-agent pods, default-deny networking, multi-tenant teams and roles, and
approvals enforced by the platform rather than by the calling application.
@@ -128,7 +127,7 @@ to its deep dive.
connector registry, shared files, and cost accounting, all declared as
configuration instead of assembled by hand.
- **vs betting on one provider**: the same agents, tools, and configuration run
- across a growing roster of providers, from frontier labs to local LLMs. Pick
+ across a growing roster of providers. Pick
whichever model gives the best cost/quality tradeoff for each job, and switch
providers without rebuilding, so your setup and data are never locked to a
single vendor.
@@ -145,10 +144,14 @@ four layers constrain what it can do:
channel, and callbacks are signature-verified.
- **Least privilege.** Each agent reaches only the connectors its `Context`
grants, through short-lived, scope-narrowed tokens that can't widen
- themselves; container images must match a pinned digest and an allowlist.
-- **Deny-all networking.** Runtime namespaces start with no connectivity;
- access is opened per (agent, connector), and outbound traffic is pinned to
- the specific hosts a connector declares, never the open internet.
+ themselves. Connector images are checked against an allowlist (audit mode by
+ default), and custom workflow coordinator images must be digest-pinned.
+- **Deny-all networking.** Runtime namespaces start with no connectivity, and
+ access is opened per (agent, connector). A connector's egress is limited to
+ the hosts and ports it declares, unless an operator approves explicit
+ `public-web` egress. Agent pods may reach the public internet on ports
+ 80/443 (for the LLM API and the approval-gated `http_request` tool);
+ private, metadata and cluster-internal ranges stay blocked.
- **Authenticated internals.** Every service-to-service call carries a
short-lived, audience-scoped token; shared-file access is re-checked and
audited on each request, and inbound webhooks are signature-verified.
@@ -159,8 +162,7 @@ Report vulnerabilities privately: **[SECURITY.md](SECURITY.md)**.
## Supported LLM providers
-A broad, growing set of providers behind one interface, from frontier labs to
-local models. Keys live in a Kubernetes Secret you create (dev mode: a single
+A broad, growing set of hosted model providers behind one interface. Keys live in a Kubernetes Secret you create (dev mode: a single
environment variable; setup infers the matching provider).
| Provider | `provider` value | Integration |
diff --git a/docs/README.md b/docs/README.md
index 3cfb99ce6..046330182 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,13 +2,14 @@
**evenfire** is a self-hostable platform for LLM agents that take real actions:
multi-channel messaging, MCP tools, human-in-the-loop approvals, and
-default-deny networking — declared as Kubernetes CRDs.
+deny-all-baseline networking — declared as Kubernetes CRDs.
> Code and API group still use the historical name **clerum** (`clerum.io`,
> `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.
+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.
---
@@ -16,7 +17,7 @@ Use this index for long-form docs.
| Doc | Description |
| --------------------------------------------------------- | ---------------------------------------------- |
-| [Quickstart](get-started/quickstart.md) | Full platform on minikube in minutes |
+| [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 |
@@ -27,43 +28,61 @@ Use this index for long-form docs.
| ------------------------------------------------------------------ | -------------------------------------------------------------------- |
| [Why evenfire](concepts/why-evenfire.md) | Problem, audience, design intent |
| [When to use evenfire](concepts/when-to-use-evenfire.md) | Fit vs personal assistants / in-process frameworks (categories only) |
+| [A tool call, end to end](concepts/tool-call-end-to-end.md) | From a user request through approval to the artifact |
| [Open core: self-host vs hosted](concepts/open-core-and-hosted.md) | What's in this repo vs the managed evenfire hosted service |
| [Code names](concepts/code-names.md) | evenfire vs clerum |
| [Architecture overview](architecture/overview.md) | Services, CRDs, message lifecycle, NetworkPolicy model |
| [Platform topology](architecture/platform-topology.md) | Namespaces, controller split, deny-all baseline |
| [Non-MCP services](architecture/non-mcp-services.md) | Namespace splitting and L0–L3 policy layers |
-| [Diagrams](architecture/diagrams/) | Excalidraw sources |
## Surfaces (the UIs)
| Doc | Description |
| -------------------------------------- | -------------------------------------------------------------------------- |
| [Surfaces index](surfaces/README.md) | Which UI is for whom, and what each may reach |
-| [Control UI](surfaces/control-ui.md) | Admin console: usage, budgets, approvals, egress, registry |
+| [Control UI](surfaces/control-ui.md) | Admin console: usage, budgets, approvals, egress, marketplace, guardrails |
| [Desktop App](surfaces/desktop-app.md) | End-user client: chat, live activity, approvals, artifacts; how to ship it |
| [Profile UI](surfaces/profile-ui.md) | Member front door: invitation, password, desktop handoff |
## 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 or CRD allowlist path |
-| [LLM providers overview](llm-providers/README.md) | Which providers are supported and how they fit together |
-| [Configure LLM providers](deploy/llm-providers.md) | Credentials, model allowlist, per-session selector |
-| [Add an LLM provider](llm-providers/adding-a-provider.md) | Data-only vs driver-based integration paths |
-| [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 (GFS) |
-| [Minikube full stack](deploy/minikube.md) | Local Kubernetes platform |
-| [Production notes](deploy/production.md) | Checklist and in-repo deploy assets |
-| [WorkflowRecipes operations](deploy/workflow-recipes-guide.md) | Recipe ops, RBAC, debugging |
+| 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) |
+
+## 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 |
+
+## Deploy & operate
+
+| Doc | Description |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| [Minikube full stack](deploy/minikube.md) | In-depth reference for the local platform |
+| [Production notes](deploy/production.md) | Checklist and in-repo deploy assets |
+| [WorkflowRecipes operations](deploy/workflow-recipes-guide.md) | Recipe ops, RBAC, debugging |
+| **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** | |
+| [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 |
## Reference
@@ -74,24 +93,59 @@ Use this index for long-form docs.
| [llms.txt](llms.txt) | Machine-readable doc map for coding agents |
| Service READMEs | One-line map per component in the root [README components list](../README.md#docs-and-components) |
-## Testing
-
-| Doc | Description |
-| --------------------------------------------------------------------------- | -------------------------------------- |
-| [E2E guide](testing/e2e-guide.md) | Cluster E2E suites, approvals, desktop |
-| [Custom coordinator E2E gates](testing/custom-coordinator-e2e-gates.md) | Gates for custom coordinator images |
-| [Desktop observation smoke test](testing/desktop-observation-smoke-test.md) | Desktop surface smoke check |
+## Architecture deep dives
+
+Design-level explanations of specific subsystems. Read the overview first.
+
+| Doc | Description |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| [Diagrams](architecture/diagrams/) | Excalidraw sources |
+| [Stateless agent invariants](architecture/stateless-invariants.md) | Guardrails for the suspend/wake agent lifecycle |
+| [HCC readiness flows](architecture/hcc-readiness-flows.md) | Probe vs data-path readiness in host-context-controller |
+| [Live entity-change semantics](architecture/live-entity-change-consumer-semantics.md) | Latest-state convergence contract for live UI updates |
+| [Governed tracing](architecture/governed-tracing.md) | Control-plane evidence of what agents, admins, controllers did |
+| [Administrative rate limits](architecture/administrative-rate-limits.md) | Control API quotas and how the UIs handle throttling |
+| [GFS desktop operator parity](architecture/gfs-desktop-operator-parity.md) | Initial Desktop identity as EvenDrive operator on self-hosted |
+| [Registry pull secrets: self-provisioning](architecture/registry-pull-secret-self-provisioning.md) | How a self-hosted install provisions its registry image-pull Secret |
+| [Registry pull secrets: recipe workloads](architecture/registry-pull-secret-recipe-workloads.md) | Extending that pull Secret to WorkflowRecipe workloads |
+| [Codex subscription transport contract](architecture/codex-subscription-transport-contract.md) | Wire contract for the `codex-subscription` provider |
+| [Grok subscription transport contract](architecture/grok-subscription-transport-contract.md) | Wire contract and flags for `grok-subscription` |
+| [WorkflowRecipe naming](architecture/workflow-recipe-naming.md) | Generated resource-name rules |
+
+## Testing & contributor runbooks
+
+Contributor-facing. Most assume a local development cluster and the lanes in
+[`CONTRIBUTING.md`](../CONTRIBUTING.md).
+
+| Doc | Description |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
+| [E2E guide](testing/e2e-guide.md) | Cluster E2E suites, approvals, desktop |
+| [Minikube T0/T1/T2 runbook](testing/minikube-t2-runbook.md) | The validation-lane contract |
+| [Custom coordinator E2E gates](testing/custom-coordinator-e2e-gates.md) | Gates for custom coordinator images |
+| [Desktop observation smoke test](testing/desktop-observation-smoke-test.md) | Desktop surface smoke check |
+| [Control UI headful journeys](testing/control-ui-headful-journeys.md) | Optional Playwright QA recorder for Control UI |
+| [Desktop headful journeys](testing/desktop-headful-journeys.md) | Optional Playwright QA recorder for the Desktop App |
+| [Codex subscription validation](testing/codex-subscription-validation.md) | Evidence lanes for `codex-subscription` |
+| [Grok subscription validation](testing/grok-subscription-validation.md) | Evidence lanes for `grok-subscription` image input |
+| [Workflow NetworkPolicy regressions](testing/workflow-network-policy-regressions.md) | Ownership rules learned from workflow policy bugs |
+| [Stateless idle calibration](testing/stateless-idle-calibration.md) | Measuring the stateless time-to-idle |
+| [Local measurements](testing/local-measurements.md) | Running benchmarks through the intake gate |
+| [CodeQL rate-limiting dispositions](how-to/codeql-js-missing-rate-limiting.md) | Audited dispositions for `js/missing-rate-limiting` |
## For coding agents
-| Doc | Description |
-| --------------------------------------------------------------- | ----------------------------------------------- |
-| [WorkflowRecipe guide](agents/CLERUM_WORKFLOW_RECIPE_GUIDE.md) | Authoring recipes, for agents |
-| [Shared frontend rules](agents/frontend-style-rules.md) | Cross-app rules for the three frontend surfaces |
-| [Control UI rules](agents/control-ui-rules.md) | Control UI application-specific guidance |
-| [Profile UI rules](agents/profile-ui-rules.md) | Profile UI application-specific guidance |
-| [Desktop renderer rules](agents/desktop-ui-rules.md) | Desktop renderer application guidance |
-| [WorkflowRecipe naming](architecture/workflow-recipe-naming.md) | Generated resource-name rules |
+| Doc | Description |
+| -------------------------------------------------------------- | ----------------------------------------------- |
+| [WorkflowRecipe guide](agents/CLERUM_WORKFLOW_RECIPE_GUIDE.md) | Authoring recipes, for agents |
+| [Shared frontend rules](agents/frontend-style-rules.md) | Cross-app rules for the three frontend surfaces |
+| [Control UI rules](agents/control-ui-rules.md) | Control UI application-specific guidance |
+| [Profile UI rules](agents/profile-ui-rules.md) | Profile UI application-specific guidance |
+| [Desktop renderer rules](agents/desktop-ui-rules.md) | Desktop renderer application guidance |
+
+## Design records
+
+Point-in-time design notes and inventories, kept for context and not maintained
+as user docs: [design/](design/README.md).
## Community & trust
@@ -115,6 +169,7 @@ Use this index for long-form docs.
| Pick or configure an LLM provider | [LLM providers overview](llm-providers/README.md) |
| Run the full stack locally | [Minikube](deploy/minikube.md) |
| Ship to a real cluster | [Production notes](deploy/production.md) |
+| Upgrade an existing install | [Deploy & operate › Upgrade notes](#deploy--operate) |
| Debug E2E | [E2E guide](testing/e2e-guide.md) |
| Feed docs to an LLM | [llms.txt](llms.txt) |
| Use the admin console | [Control UI](surfaces/control-ui.md) |
diff --git a/docs/deploy/llm-providers.md b/docs/deploy/llm-providers.md
index 36a82f152..1db11052c 100644
--- a/docs/deploy/llm-providers.md
+++ b/docs/deploy/llm-providers.md
@@ -80,6 +80,16 @@ returns key names only). To rotate a key, re-enter it.
allowlist. Bedrock model ids are runtime-qualified, e.g.
`anthropic.claude-sonnet-4-6-v1:0`.
+## 3a. Configuring Azure OpenAI
+
+1. In Control UI, open **Secrets → LLM**, expand the **Azure OpenAI** group,
+ and enter `azure-openai-api-key`.
+2. On the Host, open **Host → Environment** and set `AZURE_OPENAI_ENDPOINT`
+ (required; the driver fails closed without it) and optionally
+ `AZURE_OPENAI_API_VERSION`.
+3. Set the Host `spec.model.provider: azure`. The model name is your **Azure
+ deployment name**, not a catalog id, so allowlist the deployment name.
+
### Bedrock and Azure in workflows
`bedrock` and `azure` are **not admissible in WorkflowRecipe steps**: they are
@@ -91,14 +101,12 @@ the other 22 providers are admissible in recipes — see the
[providers overview](../llm-providers/README.md) for the per-surface matrix and
the `clerum-model-secret-mapping` caveat.
-> **Dev-mode note.** When mcp-host runs in dev mode with no explicit
-> `spec.model`, it auto-detects the provider from whichever credential env vars
-> are present, in canonical id order (`openai` → `claude` → `zai` → `bailian` →
-> `vertex` → `bedrock` → the rest). Because Bedrock's slots are the standard AWS variables
-> (`aws-access-key-id` / `aws-secret-access-key`), a shell that already exports
-> generic AWS credentials — with `AWS_REGION` also set — can auto-select
-> `bedrock` when no higher-priority provider key is exported. Set `spec.model`
-> explicitly (or unset the AWS vars) if that is not what you want in dev.
+> **Dev-mode note.** Single-service dev mode (`CLERUM_DEV_MODE=true`, no
+> Kubernetes) reads credentials from env vars and the provider from
+> `CLERUM_MODEL_PROVIDER`. Bedrock's env vars are the standard
+> `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`, so a shell that already exports
+> AWS credentials can auto-select `bedrock`. See
+> [Local development](../llm-providers/README.md#46-local-development-no-kubernetes).
## 4. Extra credential slots (for provider fallback, R5)
@@ -123,11 +131,20 @@ Fail-closed semantics: a model is usable only if a row exists for
`(provider, model)` with `enabled = true`. A provider with no enabled rows is
unusable and is flagged in the wizard.
+**Discovery review.** `/llm-models` (Catalog) and `/llm-models/discovery`
+(Discovery Review) are two tabs of the same screen. A models.dev catalog sync
+adds new rows as **disabled** for you to review; it never enables anything on
+its own. Models that disappear from the latest live catalog stay in Catalog
+with a **Stale** marker and a per-provider stale count.
+
+Per-model image-input capability (`image_input`) is covered in the
+[providers overview](../llm-providers/README.md#image-input-capability-image_input).
+
### Propagation to runtime (ConfigMap)
control-api materializes the allowlist into the **`clerum-llm-allowed-models`**
ConfigMap in the `mcp-host` namespace (`<provider>` → JSON array of
-`{ model, displayName?, contextWindowTokens? }`). mcp-host and the workflow
+`{ model, displayName?, contextWindowTokens?, vendor?, imageInput? }`). mcp-host and the workflow
runtime read it — there is no hot call from mcp-host to control-api (the
NetworkPolicy denies it by design). Changes therefore propagate **without a
redeploy**: edit the allowlist, and the wizard, the host editor, and the runtime
diff --git a/docs/design/README.md b/docs/design/README.md
new file mode 100644
index 000000000..575b6f629
--- /dev/null
+++ b/docs/design/README.md
@@ -0,0 +1,16 @@
+# Design records
+
+Point-in-time design notes, mini-specs, and inventories written while a feature
+was being built. They explain _why_ something is shaped the way it is, but they
+are **not user documentation** and are not kept up to date: the code is the
+source of truth. For how to use or operate evenfire, start at the
+[docs index](../README.md).
+
+| Record | What it is | Status note |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| [AI Recipe Builder app architecture](ai-recipe-builder-app-architecture.md) | Architecture of the sandbox app that drafts WorkflowRecipes through an LLM conversation | — |
+| [Agent models and LLM Secrets UX](agent-models-credentials-ux.md) | UX decision record for agent creation and the agent **Models & creds** tab | Marked "Proposed" in the record |
+| [Control UI contract test hardening](control-ui-contract-test-hardening.md) | Test-methodology mini-spec for Control UI fixtures (PR #298) | Pre-implementation record |
+| [Control UI header and table layout inventory](control-ui-header-table-layout-inventory.md) | As-built inventory of Control UI headers, tabs, and tables used for standardization work | Snapshot dated in the record (2026-08-19) |
+| [Desktop embedded notification rail](desktop-embedded-notification-rail.md) | Layout decision for the notification drawer next to an embedded app | — |
+| [Self-hosted registry UX redesign](self-hosted-registry-ux-redesign.md) | Implementation map for the Marketplace / Publisher redesign | The Publisher fold into **Marketplace › your org** has shipped; the record still says "planned" |
diff --git a/docs/agent-models-credentials-ux.md b/docs/design/agent-models-credentials-ux.md
similarity index 100%
rename from docs/agent-models-credentials-ux.md
rename to docs/design/agent-models-credentials-ux.md
diff --git a/docs/features/ai-recipe-builder-app-architecture.md b/docs/design/ai-recipe-builder-app-architecture.md
similarity index 100%
rename from docs/features/ai-recipe-builder-app-architecture.md
rename to docs/design/ai-recipe-builder-app-architecture.md
diff --git a/docs/features/control-ui-contract-test-hardening.md b/docs/design/control-ui-contract-test-hardening.md
similarity index 100%
rename from docs/features/control-ui-contract-test-hardening.md
rename to docs/design/control-ui-contract-test-hardening.md
diff --git a/docs/desktop-ui-ux/control-ui-header-table-layout-inventory.md b/docs/design/control-ui-header-table-layout-inventory.md
similarity index 100%
rename from docs/desktop-ui-ux/control-ui-header-table-layout-inventory.md
rename to docs/design/control-ui-header-table-layout-inventory.md
diff --git a/docs/features/desktop-embedded-notification-rail.md b/docs/design/desktop-embedded-notification-rail.md
similarity index 100%
rename from docs/features/desktop-embedded-notification-rail.md
rename to docs/design/desktop-embedded-notification-rail.md
diff --git a/docs/features/self-hosted-registry-ux-redesign.md b/docs/design/self-hosted-registry-ux-redesign.md
similarity index 100%
rename from docs/features/self-hosted-registry-ux-redesign.md
rename to docs/design/self-hosted-registry-ux-redesign.md
diff --git a/docs/desktop-ui-ux/README.md b/docs/desktop-ui-ux/README.md
deleted file mode 100644
index 5ba1604f4..000000000
--- a/docs/desktop-ui-ux/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Desktop UI UX Docs
-
-This folder is the source of truth for desktop UX decisions, with a focus on end-user clarity and low-friction workflows.
-
-## Product Positioning
-
-- `control-ui` is for admins configuring hosts, agents, teams, users, and permissions.
-- `desktop-app` is for non-technical end users (PM, BD, operators) who need a simplified experience.
-- Desktop UX should hide setup complexity and expose only what users need to do their work.
-
-## Current Documents
-
-- [`control-ui-header-table-layout-inventory.md`](control-ui-header-table-layout-inventory.md):
- point-in-time inventory of Control UI page headers and table layouts
diff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.md
deleted file mode 100644
index dcd6bd181..000000000
--- a/docs/get-started/minikube.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Get started on minikube
-
-`make minikube-setup` stands up the whole platform on a local cluster — every
-service, deny-all NetworkPolicies, the JWT chain, and a seeded agent named
-`chatllm`. It starts with an empty connector context — mcp-host's native tools
-(shell, file read/write, HTTP, memory) need no MCP server; install connectors
-from the registry when you want more. Setup infers the provider from the first of
-`OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY`, `BAILIAN_API_KEY` set in
-`.env`; for any other provider also set `CLERUM_MODEL_PROVIDER` and
-`CLERUM_MODEL_NAME`.
-
-## Prerequisites
-
-Docker Desktop with **≥10 GB RAM / 6 CPUs** · `minikube` v1.30+ · `kubectl` ·
-`python3` · Node.js 24+ · `git` · `make` · `ruby` (renders the control-api DB
-migration overlay; ships with macOS, `apt-get install ruby` on Debian/Ubuntu).
-
-Run `make prereqs` (alias `make doctor`) to check every one of these at once —
-it prints the exact install command per platform for anything missing, and
-flags a `.env` without `ADMIN_PASSWORD` or an LLM key. `make minikube-setup`
-runs it automatically first (bypass with `SKIP_PREREQS=true`).
-
-## Bring the platform up
-
-```bash
-git clone https://github.com/evenfire-ai/evenfire.git && cd evenfire
-cp .env.example .env
-# edit .env: set ADMIN_PASSWORD (required — no default ships) and ONE LLM key
-# (OpenAI/Claude/Z.AI/Bailian are auto-detected; other providers also need
-# CLERUM_MODEL_PROVIDER + CLERUM_MODEL_NAME)
-MINIKUBE_IMAGE_TAG=latest make minikube-setup # first run ~15 min (pulling images dominates); re-run safe
-make minikube-status # wait for every deployment READY
-```
-
-The default `minimal` seed is setup-first. Before it logs in as the technical
-bootstrap admin, it consumes `/api/v1/admin/auth/setup`, which atomically
-creates the `[email protected]` Desktop identity and its `initial_setup`
-GFS operator link when `CONTROL_API_DESKTOP_GFS_OPERATOR_LINKING_ENABLED=true`.
-The seed then verifies that link through the Control API. A rerun may fall back
-to login only when the same active link is present; it fails closed instead of
-creating an unlinked ordinary Desktop member or recreating a revoked link.
-
-**You do not build images.** `make minikube-setup` pulls all 23 service images
-from `ghcr.io/evenfire-ai`, published for `linux/amd64` and `linux/arm64`, so an
-Apple Silicon Mac pulls a native image rather than compiling anything. MCP
-servers stay out of the cluster and are installed on demand from the evenfire
-registry.
-
-`MINIKUBE_IMAGE_TAG=latest` is required today: the manifests pin the next
-release tag, and its images only exist once that release is promoted. Without
-the override the pull fails with a message naming this variable. Drop it after
-the release is cut. If minikube itself fails to start, add
-`MINIKUBE_MEMORY=9216` — the 10240 MB default exceeds a stock Docker Desktop
-ceiling.
-
-To build every image from source instead, use `make minikube-setup-local`
-(equivalently `IMAGE_SOURCE=local`), which needs no tag override.
-
-## Say hello (desktop app)
-
-The UIs run from your workstation, so install their dependencies once, then run
-them against the cluster:
-
-```bash
-make install-all && npm --prefix control-ui install
-npm run ui # Control UI + Profile UI + Desktop App
-```
-
-Log in as `[email protected]` using the `ADMIN_PASSWORD` you set in `.env`;
-the same account is the initial GFS operator on a fresh self-hosted install.
-Message the `chatllm` agent, and ask it to run a command or generate a PDF —
-then approve the tool call from the chat. The same password logs into the
-Control UI as `admin`. The Desktop App is the client you just used; Control UI
-is the admin console for the same fleet — both are toured in
-[docs/surfaces/](../surfaces/README.md).
-
-## Prefer the API path?
-
-The full curl walkthrough exercises the real session → scoped-RPC → rpc-proxy
-JWT chain, with troubleshooting notes:
-[quickstart.md](quickstart.md) ·
-[deploy/minikube.md](../deploy/minikube.md) · production:
-[deploy/production.md](../deploy/production.md).
-
-## See also
-
-- [See it work: a tool call, end to end](../concepts/tool-call-end-to-end.md)
-- [Learning path](learning-path.md) — role-based route through the docs
diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
index 4cd0e11cf..9a99b1e32 100644
--- a/docs/get-started/quickstart.md
+++ b/docs/get-started/quickstart.md
@@ -27,6 +27,11 @@ named `chatllm` you can message immediately.
`HOST_MODEL_UNKNOWN`. Without any key, setup still boots, but the agent
can't reply until you add one.
+Run `make prereqs` (alias `make doctor`) to check all of these at once. It
+prints the install command for anything missing and flags a `.env` without
+`ADMIN_PASSWORD` or an LLM key. `make minikube-setup` runs it first (skip with
+`SKIP_PREREQS=true`).
+
## 1. Configure
```bash
@@ -91,7 +96,10 @@ It seeds for you:
install connectors from the registry) + a CommunicationChannel
- 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
+ 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.
Verify:
diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.md
index 85dd9eac7..35b21c09a 100644
--- a/docs/llm-providers/README.md
+++ b/docs/llm-providers/README.md
@@ -205,27 +205,15 @@ surfacing as an opaque `401` on the first message.
Paste the key into its field under **Secrets → LLM**, allowlist at least one
model, set the Host's provider and model. That's all — no env vars, no code.
-### 4.3 Amazon Bedrock
+### 4.3–4.5 Bedrock, Vertex AI, Azure OpenAI
-Enter **both** `aws-access-key-id` and `aws-secret-access-key` **in a single
-save** — a half-written pair is rejected client-side and by control-api, so a
-Host is never left half-configured. Then set `AWS_REGION` under
-**Host → Environment**. Bedrock model ids are runtime-qualified, e.g.
-`anthropic.claude-sonnet-4-6-v1:0`.
-
-### 4.4 Google Vertex AI
-
-Paste the **entire service-account JSON** into `vertex-service-account-json`.
-Its shape is validated (must parse, must contain `client_email` and
-`private_key`). Set `VERTEX_PROJECT_ID` (and optionally `VERTEX_LOCATION`) under
-**Host → Environment**. The driver builds credentials from the JSON **in memory**
-— it never writes a key file and never uses `GOOGLE_APPLICATION_CREDENTIALS`.
-
-### 4.5 Azure OpenAI
-
-Enter the key, then set `AZURE_OPENAI_ENDPOINT` under **Host → Environment**
-(this is required — construction fails closed without it). Remember the model
-field is your **deployment name**.
+These need more than one value: Bedrock takes a key pair saved together plus
+`AWS_REGION`; Vertex takes a service-account JSON plus `VERTEX_PROJECT_ID`;
+Azure takes a key plus `AZURE_OPENAI_ENDPOINT`, and its model name is your
+deployment name. Step-by-step setup is in the operator guide:
+[Vertex AI](../deploy/llm-providers.md#2-configuring-google-vertex-ai) ·
+[Bedrock](../deploy/llm-providers.md#3-configuring-amazon-bedrock) ·
+[Azure OpenAI](../deploy/llm-providers.md#3a-configuring-azure-openai).
### 4.6 Local development (no Kubernetes)
@@ -274,20 +262,11 @@ lives in the control-api Postgres table `llm_allowed_models`, is managed at
`/llm-models`, is fully audited (`llm_allowed_models_audit`), and is materialized
to the `clerum-llm-allowed-models` ConfigMap for the runtime.
-- **Fail-closed**: a row must exist and be `enabled`. A provider with no enabled
- rows is unusable and flagged in the wizard.
-- **Discovery review**: `/llm-models` and `/llm-models/discovery` are the
- route-backed Catalog and Discovery Review tabs of one operator surface. A
- models.dev sync still lands rows as **disabled** for the operator to curate —
- it never auto-enables anything. Models missing from the latest live catalog
- remain in Catalog with a **Stale** row indicator and provider-level stale count.
-- **Deployed resources are never interrupted.** If a model falls out of the
- allowlist, running Hosts keep working (a `WARN` plus a metric, marked "out of
- allowlist" in the UI). Hard enforcement applies only to _new_ selections: host
- create/edit, the runtime set-model call, and workflow `configure`.
-- **If the ConfigMap is missing** (rollout in progress, migration not yet run),
- the runtime degrades explicitly: only the model already configured on the
- Host/step is permitted. Neither open nor bricked.
+In short: it is **fail-closed** (a model needs an enabled row), catalog sync
+only proposes disabled rows, models already deployed are never interrupted,
+and a missing ConfigMap degrades to "only the configured model". Operator
+details (propagation, metrics, degraded mode, discovery review) are in the
+[operator guide](../deploy/llm-providers.md#5-the-model-allowlist).
### Image input capability (`image_input`)
@@ -372,6 +351,9 @@ the allowlist:
- You can change the _model_, not the _provider_ — the provider is the operator's
decision.
+Operator-side details (scopes, context-window indicator, usage attribution):
+[operator guide §6](../deploy/llm-providers.md#6-the-per-session-model-selector-desktop-app).
+
---
## 7. Provider fallback
diff --git a/docs/llms.txt b/docs/llms.txt
index f65171cd7..78e8900dd 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -2,10 +2,11 @@
> 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.
## Start here
-- README: ../README.md — product pitch, security model, CRDs, license
+- README: ../README.md — product pitch, security model, providers, license
- Quickstart: get-started/quickstart.md — full platform on minikube, one command
- Registry quickstart: get-started/registry-quickstart.md — self-hosted connect → install → publish round trip
- Learning path: get-started/learning-path.md
@@ -15,11 +16,13 @@
- Why evenfire: concepts/why-evenfire.md
- When to use evenfire (categories): concepts/when-to-use-evenfire.md
+- A tool call, end to end: concepts/tool-call-end-to-end.md
- Open core (self-host vs evenfire hosted): concepts/open-core-and-hosted.md
- Claims guardrails: meta/claims-guardrails.md
- Code names (evenfire vs clerum): concepts/code-names.md
- Architecture overview: architecture/overview.md
- Platform topology / NetworkPolicies: architecture/platform-topology.md
+- Non-MCP services (namespace split, L0–L3 policy layers): architecture/non-mcp-services.md
## Surfaces (the UIs)
@@ -35,18 +38,30 @@
- Connect Microsoft Teams (Teams CLI registration, derived endpoint, single-tenant requirement, verify flow): how-to/connect-teams.md
- Configure approvals: how-to/configure-approvals.md
- Add MCP server: how-to/add-mcp-server.md
-- 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 (credentials, model allowlist, session selector): deploy/llm-providers.md
-- Add an LLM provider (data-only vs driver-based integration): llm-providers/adding-a-provider.md
- Desktop setup & updates (environments, invitation, updates): how-to/desktop-setup-and-updates.md
- Member invitations on self-hosted (hosted mode vs your own service): how-to/member-invitations-self-hosted.md
- Track usage & set token budgets: how-to/token-budgets-and-usage.md
- Connect a self-hosted deployment to the registry: how-to/connect-to-registry.md
- Publish a plugin to the registry (efrk_ org key): how-to/publish-plugin-to-registry.md
-- Shared & global files (SFS team workspace + brokered GFS drive): how-to/shared-and-global-files.md
-- Minikube full stack: deploy/minikube.md
+- Shared & global files (SFS team workspace + EvenDrive/GFS brokered drive): how-to/shared-and-global-files.md
+
+## LLM providers
+
+- 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
+- Add an LLM provider (data-only vs driver-based integration): llm-providers/adding-a-provider.md
+
+## Deploy & operate
+
+- Minikube full stack (in-depth reference): deploy/minikube.md
- Production checklist: deploy/production.md
- WorkflowRecipes ops: deploy/workflow-recipes-guide.md
+- Upgrade: workflow output PVC ownership: deploy/workflow-output-pvc-upgrade.md
+- Upgrade: Plugin Workload SDK (promptBridge / clientNotifications): deploy/plugin-workload-sdk-upgrade.md
+- GFS permission store credential (provision, rotate, recover): deploy/gfs-permission-store.md
+- Runbook: password work ownership recovery: how-to/password-work-ownership-recovery.md
+- Runbook: MCP secret rollback permits: how-to/control-api-mcp-secret-rollback-permits.md
+- Runbook: GFS large-file downloads and model input limits: operations/gfs-large-file-host-downloads.md
## Reference
@@ -60,14 +75,52 @@
- WorkflowRecipePolicy: crds/workflowrecipepolicy.md
- SharedFileSystem: crds/sharedfilesystem.md
- GlobalFileSystem: crds/globalfilesystem.md
+- Workflow SDK: ../packages/workflow-sdk/README.md
+
+## Architecture deep dives
+
+- Stateless agent invariants: architecture/stateless-invariants.md
+- HCC readiness flows: architecture/hcc-readiness-flows.md
+- Live entity-change consumer semantics: architecture/live-entity-change-consumer-semantics.md
+- Governed tracing: architecture/governed-tracing.md
+- Administrative rate limits: architecture/administrative-rate-limits.md
+- GFS desktop operator parity: architecture/gfs-desktop-operator-parity.md
+- Registry pull secret self-provisioning: architecture/registry-pull-secret-self-provisioning.md
+- Registry pull secret for recipe workloads: architecture/registry-pull-secret-recipe-workloads.md
+- Codex subscription transport contract: architecture/codex-subscription-transport-contract.md
+- Grok subscription transport contract: architecture/grok-subscription-transport-contract.md
+- WorkflowRecipe naming: architecture/workflow-recipe-naming.md
## Testing & contributing
-- E2E guide: testing/e2e-guide.md
- Contributing: ../CONTRIBUTING.md
+- E2E guide: testing/e2e-guide.md
+- Minikube T0/T1/T2 runbook: testing/minikube-t2-runbook.md
+- Custom coordinator E2E gates: testing/custom-coordinator-e2e-gates.md
+- Desktop observation smoke test: testing/desktop-observation-smoke-test.md
+- Control UI headful journeys: testing/control-ui-headful-journeys.md
+- Desktop headful journeys: testing/desktop-headful-journeys.md
+- Codex subscription validation: testing/codex-subscription-validation.md
+- Grok subscription validation: testing/grok-subscription-validation.md
+- Workflow NetworkPolicy regressions: testing/workflow-network-policy-regressions.md
+- Stateless idle calibration: testing/stateless-idle-calibration.md
+- Local measurements: testing/local-measurements.md
+- CodeQL rate-limiting dispositions: how-to/codeql-js-missing-rate-limiting.md
- Security: ../SECURITY.md
- License: ../LICENSE
+## For coding agents
+
+- WorkflowRecipe authoring guide: agents/CLERUM_WORKFLOW_RECIPE_GUIDE.md
+- Shared frontend rules: agents/frontend-style-rules.md
+- Control UI rules: agents/control-ui-rules.md
+- Profile UI rules: agents/profile-ui-rules.md
+- Desktop renderer rules: agents/desktop-ui-rules.md
+
+## Design records (point-in-time, not maintained)
+
+- Index: design/README.md
+
## Service READMEs (implementation detail)
- ../mcp-host/README.md — agent runtime env vars and providers
diff --git a/scripts/check-prereqs.sh b/scripts/check-prereqs.sh
index cfef988c5..b876bc8a0 100755
--- a/scripts/check-prereqs.sh
+++ b/scripts/check-prereqs.sh
@@ -340,6 +340,6 @@ if [ "$MISSING" -eq 0 ]; then
exit 0
else
echo -e "${RED}${BOLD}${MISSING} required prerequisite(s) missing.${NC} Install the item(s) above, then re-run ${BOLD}make prereqs${NC}."
- echo "Full walkthrough: docs/get-started/minikube.md"
+ echo "Full walkthrough: docs/get-started/quickstart.md"
exit 1
fi
diff --git a/scripts/tests/test-minikube-t2-public-boundary.sh b/scripts/tests/test-minikube-t2-public-boundary.sh
index 2ebc66005..23d12dbcc 100755
--- a/scripts/tests/test-minikube-t2-public-boundary.sh
+++ b/scripts/tests/test-minikube-t2-public-boundary.sh
@@ -78,7 +78,7 @@ safe_source_paths = {
"control-ui/components/llmcredentialfields/index.tsx",
"control-ui/components/llmcredentialfields/types.ts",
"control-ui/components/__tests__/llmcredentialfields.test.tsx",
- "docs/agent-models-credentials-ux.md",
+ "docs/design/agent-models-credentials-ux.md",
"deploy/scripts/lib/gfs-credential-rollout.sh",
"deploy/scripts/lib/gfs-credential-secret.sh",
"deploy/scripts/reconcile-gfs-deploy-credentials.sh",