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.exampleindex 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.mdindex 375be659b..c2b0cc273 100644--- a/README.md+++ b/README.md@@ -64,8 +64,8 @@ make install-all && npm --prefix control-ui installnpm 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. Evenfireadds 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, andapprovals 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 asconfiguration 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. Pickwhichever model gives the best cost/quality tradeoff for each job, and switchproviders without rebuilding, so your setup and data are never locked to asingle 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 ashort-lived, audience-scoped token; shared-file access is re-checked andaudited 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 singleenvironment variable; setup infers the matching provider).| Provider | `provider` value | Integration |diff --git a/docs/README.md b/docs/README.mdindex 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.mdindex 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 andthe `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 isunusable 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 workflowruntime read it — there is no hot call from mcp-host to control-api (theNetworkPolicy denies it by design). Changes therefore propagate **without aredeploy**: edit the allowlist, and the wizard, the host editor, and the runtimediff --git a/docs/design/README.md b/docs/design/README.mdnew file mode 100644index 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.mdsimilarity index 100%rename from docs/agent-models-credentials-ux.mdrename to docs/design/agent-models-credentials-ux.mddiff --git a/docs/features/ai-recipe-builder-app-architecture.md b/docs/design/ai-recipe-builder-app-architecture.mdsimilarity index 100%rename from docs/features/ai-recipe-builder-app-architecture.mdrename to docs/design/ai-recipe-builder-app-architecture.mddiff --git a/docs/features/control-ui-contract-test-hardening.md b/docs/design/control-ui-contract-test-hardening.mdsimilarity index 100%rename from docs/features/control-ui-contract-test-hardening.mdrename to docs/design/control-ui-contract-test-hardening.mddiff --git a/docs/desktop-ui-ux/control-ui-header-table-layout-inventory.md b/docs/design/control-ui-header-table-layout-inventory.mdsimilarity index 100%rename from docs/desktop-ui-ux/control-ui-header-table-layout-inventory.mdrename to docs/design/control-ui-header-table-layout-inventory.mddiff --git a/docs/features/desktop-embedded-notification-rail.md b/docs/design/desktop-embedded-notification-rail.mdsimilarity index 100%rename from docs/features/desktop-embedded-notification-rail.mdrename to docs/design/desktop-embedded-notification-rail.mddiff --git a/docs/features/self-hosted-registry-ux-redesign.md b/docs/design/self-hosted-registry-ux-redesign.mdsimilarity index 100%rename from docs/features/self-hosted-registry-ux-redesign.mdrename to docs/design/self-hosted-registry-ux-redesign.mddiff --git a/docs/desktop-ui-ux/README.md b/docs/desktop-ui-ux/README.mddeleted file mode 100644index 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 layoutsdiff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.mddeleted file mode 100644index 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 docsdiff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex 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 agentcan'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.mdindex 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 onemodel, 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 materializedto 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'sdecision.+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 fallbackdiff --git a/docs/llms.txt b/docs/llms.txtindex 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 providersdiff --git a/scripts/check-prereqs.sh b/scripts/check-prereqs.shindex cfef988c5..b876bc8a0 100755--- a/scripts/check-prereqs.sh+++ b/scripts/check-prereqs.sh@@ -340,6 +340,6 @@ if [ "$MISSING" -eq 0 ]; thenexit 0elseecho -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 1fidiff --git a/scripts/tests/test-minikube-t2-public-boundary.sh b/scripts/tests/test-minikube-t2-public-boundary.shindex 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",