Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: correct stale counts, routes, and setup steps across public docs
Jose Gabriel Ramirez Encinasea0508bae365
diff --git a/.env.example b/.env.exampleindex 81ef3c5f2..6d9a413a9 100644--- a/.env.example+++ b/.env.example@@ -31,6 +31,16 @@ ZAI_API_KEY=# Coding Plan API key: https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=globalset#/efm/coding_planBAILIAN_API_KEY=+# Setup auto-selects the agent's provider from the first of the four keys above.+# Every other supported provider is read too (and written to the LLM Secret),+# but needs CLERUM_MODEL_PROVIDER + CLERUM_MODEL_NAME below to be selected:+# OPENROUTER_API_KEY GEMINI_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY+# TOGETHER_API_KEY FIREWORKS_API_KEY MISTRAL_API_KEY XAI_API_KEY+# CEREBRAS_API_KEY DEEPINFRA_API_KEY PERPLEXITY_API_KEY MOONSHOT_API_KEY+# NEBIUS_API_KEY NOVITA_API_KEY MINIMAX_API_KEY AZURE_OPENAI_API_KEY+# VERTEX_SERVICE_ACCOUNT_JSON AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY+# See docs/llm-providers/README.md for per-provider settings.+# -----------------------------------------------------------------------------# Platform admin password (REQUIRED for `make minikube-setup`)# -----------------------------------------------------------------------------@@ -104,11 +114,14 @@ CLERUM_EMAIL_SMTP_PORT=587# These go into mcp-host ConfigMap, not secrets# ------------------------------------------------------------------------------# LLM provider: "openai", "claude", "zai", or "bailian" (default: openai)+# LLM provider id (any id from docs/llm-providers/README.md). When unset, setup+# uses the first key present: openai, claude, zai, bailian (no key: openai).# CLERUM_MODEL_PROVIDER=openai-# Specific model name (default varies by provider: gpt-4o, claude-3-5-sonnet, glm-5, qwen3-coder-plus)-# CLERUM_MODEL_NAME=gpt-4o+# Model name. Only valid together with CLERUM_MODEL_PROVIDER, and the pair must+# be enabled in the model allowlist. Defaults: openai gpt-5.4-mini,+# claude claude-sonnet-4-6, zai glm-5.1, bailian qwen3-coder-plus.+# CLERUM_MODEL_NAME=gpt-5.4-mini# Feature flag for new agent loop (default: false)# CLERUM_USE_NEW_AGENT_LOOP=falsediff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex f2956da37..123ffc8ed 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -52,7 +52,7 @@ NetworkPolicy owned by whichever component is responsible for that selector.| Service | Role || --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |-| [channel-reader](channel-reader/) | Polls Telegram / Email / Slack, forwards messages to `mcp-host` |+| [channel-reader](channel-reader/) | Receives Telegram / Email / Slack / Teams messages, forwards them to `mcp-host` || [workflow-approval-request-reader](workflow-approval-request-reader/) | Inbound half of channel approvals — receives provider callbacks and submits decisions |### Agent runtime — `mcp-host`, `mcp-server` (both deny-all)@@ -102,14 +102,14 @@ platform's three human surfaces: [docs/surfaces/README.md](docs/surfaces/README.## CRDs-`Host`, `Context`, `McpServer`, `CommunicationChannel`, `WorkflowRecipe`,+`Host`, `Context`, `McpServer`, `LlmHook`, `CommunicationChannel`, `WorkflowRecipe`,`WorkflowRecipePolicy`, `SharedFileSystem`, `GlobalFileSystem` — one referencepage each under [docs/crds/](docs/crds/), shipped in[charts/clerum-crds](charts/clerum-crds/).```mermaidflowchart TB- user[Telegram / Email / Slack] --> cr[channel-reader]+ user[Telegram / Email / Slack / Teams] --> cr[channel-reader]desktop[Desktop App] --> rpc[rpc-proxy]cui[control-ui] --> capipui[profile-ui] --> era[external-rest-api]@@ -139,8 +139,10 @@ flowchart TB## Swapping LLM providers-Set `CLERUM_MODEL_PROVIDER` to `openai | claude | zai | bailian` and supply the-matching API key. One interface, no code change. `CLERUM_MODEL_NAME` picks a+Set `CLERUM_MODEL_PROVIDER` to any of the 24 provider ids in+[`packages/llm-providers`](packages/llm-providers/index.cjs) and supply the+matching credential. One interface, no code change. Minikube setup auto-detects+only `openai`, `claude`, `zai` and `bailian` from their keys. `CLERUM_MODEL_NAME` picks amodel only together with `CLERUM_MODEL_PROVIDER`; minikube setup refuses italone and defaults to `openai/gpt-5.4-mini` when no key is set. See[mcp-host/README.md](mcp-host/README.md) anddiff --git a/README.md b/README.mdindex 33104dbd4..375be659b 100644--- a/README.md+++ b/README.md@@ -78,7 +78,7 @@ Evenfire is a complete platform for running LLM agents that takeAgents in Evenfire can:-- **Converse** across the native desktop app, Telegram, Microsoft Teams and Slack+- **Converse** across the native desktop app, Telegram, Microsoft Teams, Slack and email- **Call tools** over the [Model Context Protocol](https://modelcontextprotocol.io) (MCP)- **Share** teams, files, and cost budgets- **Compose** multi-step workflows@@ -103,7 +103,7 @@ to its deep dive.| Capability | What you get | Deep dive || ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |-| **Agents** | Real actions across Telegram / Email / Slack / desktop (`shell_exec`, HTTP, a real browser, files), plus memory and approval gates | [mcp-host](mcp-host/README.md) |+| **Agents** | Real actions across Telegram / Email / Slack / Teams / desktop (`shell_exec`, HTTP, a real browser, files), plus memory and approval gates | [mcp-host](mcp-host/README.md) || **Console & client** | An admin **Control UI** console and an Electron **Desktop App**, plus a small Profile UI for invites | [surfaces](docs/surfaces/README.md) || **Connectors (MCP)** | Governed MCP servers with per-`Context` allowlists; stdio tools via the bridge; remote SaaS behind a pinned egress proxy | [mcp-servers](mcp-servers/README.md) || **Workflows** | Declarative multi-workload `WorkflowRecipe`s with a lifecycle: risk-based approval, shadow testing, rollback | [workflowrecipe](docs/crds/workflowrecipe.md) |@@ -111,7 +111,7 @@ to its deep dive.| **Teams & access** | Profiles, teams, roles (admin / inviter / member), invitations, and session → scoped-RPC token brokerage | [external-rest-api](external-rest-api/README.md) || **Files** | Read-only team workspaces agents can draw on, plus a brokered, audited shared drive where every read and write is checked and logged | [gfs-controller](gfs-controller/README.md) || **Cost & governance** | Token budgets per scope (block/warn), usage and LLM-price accounting, and a connector-image allowlist | [token budgets](docs/how-to/token-budgets-and-usage.md) |-| **Config as code** | The whole fleet as eight `clerum.io` ([why that name?](docs/concepts/code-names.md)) CRDs: version-controlled, reviewable, GitOps-friendly | [crds](docs/crds/README.md) |+| **Config as code** | The whole fleet as nine `clerum.io` ([why that name?](docs/concepts/code-names.md)) CRDs: version-controlled, reviewable, GitOps-friendly | [crds](docs/crds/README.md) |---@@ -163,33 +163,37 @@ A broad, growing set of providers behind one interface, from frontier labs tolocal models. Keys live in a Kubernetes Secret you create (dev mode: a singleenvironment variable; setup infers the matching provider).-| Provider | `provider` value | Integration |-| ---------------- | ---------------- | ----------------- |-| OpenAI | `openai` | Native SDK |-| Anthropic | `claude` | Native SDK |-| Z.AI | `zai` | OpenAI-compatible |-| Bailian | `bailian` | OpenAI-compatible |-| Google Vertex AI | `vertex` | Native SDK |-| Amazon Bedrock | `bedrock` | Native SDK |-| OpenRouter | `openrouter` | OpenAI-compatible |-| Google Gemini | `gemini` | OpenAI-compatible |-| DeepSeek | `deepseek` | OpenAI-compatible |-| Groq | `groq` | OpenAI-compatible |-| Together AI | `together` | OpenAI-compatible |-| Fireworks AI | `fireworks` | OpenAI-compatible |-| Mistral AI | `mistral` | OpenAI-compatible |-| xAI (Grok) | `xai` | OpenAI-compatible |-| Cerebras | `cerebras` | OpenAI-compatible |-| DeepInfra | `deepinfra` | OpenAI-compatible |-| Perplexity | `perplexity` | OpenAI-compatible |-| Moonshot (Kimi) | `moonshot` | OpenAI-compatible |-| Nebius | `nebius` | OpenAI-compatible |-| Novita AI | `novita` | OpenAI-compatible |-| MiniMax | `minimax` | OpenAI-compatible |-| Azure OpenAI | `azure` | Light driver |+| Provider | `provider` value | Integration |+| ---------------------------- | -------------------- | ------------------------------------- |+| OpenAI | `openai` | Native SDK |+| Anthropic | `claude` | Native SDK |+| Z.AI | `zai` | OpenAI-compatible |+| Bailian | `bailian` | OpenAI-compatible |+| Google Vertex AI | `vertex` | Native SDK |+| Amazon Bedrock | `bedrock` | Native SDK |+| OpenRouter | `openrouter` | OpenAI-compatible |+| Google Gemini | `gemini` | OpenAI-compatible |+| DeepSeek | `deepseek` | OpenAI-compatible |+| Groq | `groq` | OpenAI-compatible |+| Together AI | `together` | OpenAI-compatible |+| Fireworks AI | `fireworks` | OpenAI-compatible |+| Mistral AI | `mistral` | OpenAI-compatible |+| xAI (Grok) | `xai` | OpenAI-compatible |+| Cerebras | `cerebras` | OpenAI-compatible |+| DeepInfra | `deepinfra` | OpenAI-compatible |+| Perplexity | `perplexity` | OpenAI-compatible |+| Moonshot (Kimi) | `moonshot` | OpenAI-compatible |+| Nebius | `nebius` | OpenAI-compatible |+| Novita AI | `novita` | OpenAI-compatible |+| MiniMax | `minimax` | OpenAI-compatible |+| Azure OpenAI | `azure` | Light driver |+| ChatGPT (Codex) subscription | `codex-subscription` | Subscription sign-in (off by default) |+| Grok subscription | `grok-subscription` | Subscription sign-in (off by default) |Most providers are OpenAI-compatible and plug in as config with no custom code;only a few (`claude`, `vertex`, `bedrock`, `azure`) need a dedicated integration.+The two subscription providers use an admin's sign-in instead of an API key and+are switched off in `deploy/base` (on in the minikube overlay).Overview: [docs/llm-providers/README.md](docs/llm-providers/README.md) ·Configure: [docs/deploy/llm-providers.md](docs/deploy/llm-providers.md) ·Add one: [docs/llm-providers/adding-a-provider.md](docs/llm-providers/adding-a-provider.md) ·@@ -214,9 +218,7 @@ signing/JWT keys, secrets, and the security non-negotiables.## Development and testingEach service is an independent npm package. Run `npm test` in a package, or-`make test-unit-all` after installing deps; `make test-counts` prints the live-unit-test file and case totals: "is it real, is it tested" without a hardcoded-number to drift. E2E suites run against minikube with Calico NetworkPolicies and+`make test-unit-all` after installing deps. E2E suites run against minikube with Calico NetworkPolicies andthe approval flow: [docs/testing/e2e-guide.md](docs/testing/e2e-guide.md).Contributor loop: [CONTRIBUTING.md](CONTRIBUTING.md).@@ -234,7 +236,7 @@ Contributor loop: [CONTRIBUTING.md](CONTRIBUTING.md).| [docs/concepts/when-to-use-evenfire.md](docs/concepts/when-to-use-evenfire.md) | Fit by category || [docs/faq.md](docs/faq.md) | FAQ & troubleshooting || [ARCHITECTURE.md](ARCHITECTURE.md) | Architecture & data flow |-| [docs/crds/README.md](docs/crds/README.md) | Config as code (the 8 CRDs) |+| [docs/crds/README.md](docs/crds/README.md) | Config as code (the 9 CRDs) || [docs/llms.txt](docs/llms.txt) | Map for coding agents |**Components**: every deployable service has its own README (the deep dive):@@ -242,7 +244,7 @@ Contributor loop: [CONTRIBUTING.md](CONTRIBUTING.md).| Component | Role || ------------------------------------------------------------------------------ | ----------------------------------------------------- || [mcp-host](mcp-host/README.md) | Agent runtime: LLM loop, tools, approval gate |-| [channel-reader](channel-reader/README.md) | Telegram / Email / Slack ingress |+| [channel-reader](channel-reader/README.md) | Telegram / Email / Slack / Teams ingress || [control-api](control-api/README.md) | Control plane: CRDs, secrets, token mint, usage || [control-ui](control-ui/README.md) | Admin dashboard || [profile-ui](profile-ui/README.md) | End-user profile and invitation confirmation |diff --git a/channel-reader/README.md b/channel-reader/README.mdindex 01278221f..8ff2517df 100644--- a/channel-reader/README.md+++ b/channel-reader/README.md@@ -1,6 +1,6 @@# Clerum Channel Reader-A Node.js/TypeScript application that fetches messages from Telegram, Email (IMAP), and Slack. `CommunicationChannel` config controls transport reachability and optional sender pre-filters. Workflow approval identity verification is a separate Profile UI flow and is enforced only by workflow approval/trigger handling.+A Node.js/TypeScript application that receives messages from Telegram, Email (IMAP), Slack, and Microsoft Teams. `CommunicationChannel` config controls transport reachability and optional sender pre-filters. Workflow approval identity verification is a separate Profile UI flow and is enforced only by workflow approval/trigger handling.## Modesdiff --git a/channel-reader/package-lock.json b/channel-reader/package-lock.jsonindex 1c9eee879..26d79a923 100644--- a/channel-reader/package-lock.json+++ b/channel-reader/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-channel-reader",- "version": "0.1.105",+ "version": "0.1.106","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-channel-reader",- "version": "0.1.105",+ "version": "0.1.106","license": "SEE LICENSE IN LICENSE","dependencies": {"@kubernetes/client-node": "^1.0.0",diff --git a/channel-reader/package.json b/channel-reader/package.jsonindex d1dcd22a4..14b79bbf4 100644--- a/channel-reader/package.json+++ b/channel-reader/package.json@@ -1,6 +1,6 @@{"name": "clerum-channel-reader",- "version": "0.1.105",+ "version": "0.1.106","description": "Watches CommunicationChannel CRDs and fetches messages from Telegram, Email, and Slack","main": "dist/main.js","engines": {diff --git a/charts/clerum-crds/Chart.yaml b/charts/clerum-crds/Chart.yamlindex d71d64ce9..12a6703f9 100644--- a/charts/clerum-crds/Chart.yaml+++ b/charts/clerum-crds/Chart.yaml@@ -1,6 +1,6 @@apiVersion: v2name: clerum-crds-description: Custom Resource Definitions for Clerum (CommunicationChannel, Context, Host, LlmHook, McpServer, WorkflowRecipe, WorkflowRecipePolicy). WorkflowRun CRD has been removed; workflow runs are now DB-first in control-postgres.+description: Custom Resource Definitions for Clerum (CommunicationChannel, Context, GlobalFileSystem, Host, LlmHook, McpServer, SharedFileSystem, WorkflowRecipe, WorkflowRecipePolicy). WorkflowRun CRD has been removed; workflow runs are now DB-first in control-postgres.type: applicationversion: 0.8.0appVersion: "1"diff --git a/control-ui/README.md b/control-ui/README.mdindex 10b228951..00be5964e 100644--- a/control-ui/README.md+++ b/control-ui/README.md@@ -19,25 +19,26 @@ Control UI requires an admin login — it is not an open dashboard.## Sections-Sidebar destinations map to canonical App Router routes (`components/Sidebar/constants.tsx`):--| Sidebar label | Route | Contents |-| ----------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |-| Agents | `/hosts` | Host list, detail tabs, guided creation wizard, per-tool approval overrides |-| Connectors | `/mcp-servers` | MCP server resources: list, create, edit, egress policy |-| Installed plugins | `/plugins` | Installed plugins by namespace/name: editor, secrets, integrations, runs |-| Shared Files | `/shared-filesystems` | Shared filesystem resources |-| Global Files | `/gfs` | Global File System browser and grant delegation |-| Marketplace | `/marketplace` | Connectors catalog plus the org-named tab `/marketplace/org` (entries, credentials, connection) — the folded Publisher |-| External Channels | `/communication-channels` | Communication channel resources |-| Users & Teams | `/profile-admin/users` | Users, teams, and admins administration |-| Contexts | `/contexts` | Context resources with per-context tabs |-| Secrets | `/secrets` | Secrets by scope, plus recipe secrets (values are write-only from the UI) |-| Outputs | `/outputs` | Generated outputs |-| Cost & Usage | `/cost/usage`, `/cost/llm-prices`, `/cost/token-budgets` | Token usage dashboard, model prices, token budgets |-| Settings | `/settings` | Control settings panel |--Routes not in the sidebar: `/control-admins/new` (invite a control admin), `/plugin-workload-sdk` (SDK grants and invocation search), and the public token flows listed above. Old top-level `/usage`, `/llm-prices`, and `/token-budgets` paths permanently redirect under `/cost/*` (`next.config.js`).+Sidebar destinations map to the public routes in `app/constants/routes.ts` (`components/Sidebar/constants.tsx`). Several public routes are rewrites onto older physical `app/` folders (for example `/agents` → `app/hosts`, `/connectors` → `app/mcp-servers`, `/agent-files` → `app/shared-filesystems`); see `next.config.js`.++| Sidebar label | Public route | Contents |+| --------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |+| Users & Teams | `/users-and-teams/users` | Users, teams (admin / inviter / member roles), and control admins |+| Agents | `/agents` | Agent (Host) list, detail tabs, guided creation wizard; creates a private Context per agent |+| Marketplace | `/marketplace` | Catalog plus the org tab `/marketplace/org` (entries, credentials, connection), formerly Publisher |+| Installed Connectors | `/connectors` | MCP servers: list, create (incl. remote/OAuth), edit, credentials, egress policy |+| Installed Plugins | `/plugins` | Installed plugins by namespace/name: editor, secrets, integrations, runs |+| Installed Guardrails | `/guardrails` | Installed guardrail hooks (`LlmHook`) and their install editor |+| Files | `/agent-files` | Shared filesystem resources |+| Files › EvenDrive | `/global-file-system` | Global File System browser and grant delegation |+| Files › Agent Outputs | `/agent-outputs/recipe-artifacts` | Generated outputs |+| External Channels | `/external-channels` | Communication channel resources |+| LLM Models | `/llm-models` | Model allowlist catalog and discovery review |+| Secrets | `/secrets/llm` | Secrets by scope, LLM subscriptions, recipe secrets (values are write-only from the UI) |+| Cost & Usage | `/cost-and-usage/usage`, `/cost-and-usage/llm-prices`, `/cost-and-usage/token-budgets` | Token usage dashboard, model prices, token budgets |+| Settings | `/settings/ui` | Control settings panel |++Routes not in the sidebar: `/users-and-teams/admins/new` (invite a control admin; `/control-admins/new` redirects there), `/plugin-workload-sdk` (SDK grants and invocation search), `/traces/*` (hidden Traces section), and the public token flows listed above. Legacy paths such as `/cost/*`, `/registry`, `/publisher/*`, `/mcp-servers`, `/hosts` and `/contexts` redirect to their current locations (`next.config.js`, `components/LegacyContextRedirect`).## Notable Featuresdiff --git a/control-ui/package-lock.json b/control-ui/package-lock.jsonindex 131a17269..89df19642 100644--- a/control-ui/package-lock.json+++ b/control-ui/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-ui",- "version": "0.1.728",+ "version": "0.1.729","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-ui",- "version": "0.1.728",+ "version": "0.1.729","dependencies": {"@clerum/display-field": "file:../packages/display-field","@clerum/frontend-components": "file:../packages/frontend-components",diff --git a/control-ui/package.json b/control-ui/package.jsonindex 6cda74840..a23f3ab42 100644--- a/control-ui/package.json+++ b/control-ui/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-ui",- "version": "0.1.728",+ "version": "0.1.729","private": true,"scripts": {"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",diff --git a/docs/README.md b/docs/README.mdindex 4610e7c7d..3cfb99ce6 100644--- a/docs/README.md+++ b/docs/README.md@@ -69,7 +69,7 @@ Use this index for long-form docs.| Doc | Description || -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |-| [CRD index](crds/README.md) | All 8 `clerum.io` CRDs |+| [CRD index](crds/README.md) | All 9 `clerum.io` CRDs || [Workflow SDK](../packages/workflow-sdk/README.md) | `@clerum/workflow-sdk` — build custom workflow coordinator images || [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) |diff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex 3b6218181..81872f958 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -12,7 +12,7 @@ evenfire is a Kubernetes-native platform for LLM orchestration with multi-channe>> - For every service and which controller creates it → [/ARCHITECTURE.md](../../ARCHITECTURE.md)> - For namespaces, trust boundaries, NetworkPolicy layers and the WRC → [platform-topology.md](platform-topology.md)-> - For all eight CRDs → [docs/crds/](../crds/)+> - For all nine CRDs → [docs/crds/](../crds/)---@@ -117,9 +117,9 @@ matrix, including the Profile UI.All CRDs belong to the `clerum.io` API group, version `v1alpha1`. They are installed via the Helm chart at `charts/clerum-crds`.-The platform ships **eight** CRDs. This section covers the four on the message-path in depth. The other four — `WorkflowRecipe`, `WorkflowRecipePolicy`,-`SharedFileSystem`, `GlobalFileSystem` — have reference pages under+The platform ships **nine** CRDs. This section covers the four on the message+path in depth. The other five — `LlmHook`, `WorkflowRecipe`,+`WorkflowRecipePolicy`, `SharedFileSystem`, `GlobalFileSystem` — have reference pages under[docs/crds/](../crds/), which is the complete set.### 2.1 CommunicationChannel@@ -1386,7 +1386,7 @@ npm run dev### Helm Chart: clerum-crds-Installs the eight CRDs. Must be installed before deploying any services.+Installs the nine CRDs. Must be installed before deploying any services.```bashhelm install clerum-crds ./charts/clerum-crdsdiff --git a/docs/concepts/open-core-and-hosted.md b/docs/concepts/open-core-and-hosted.mdindex 047963733..feb8b501d 100644--- a/docs/concepts/open-core-and-hosted.md+++ b/docs/concepts/open-core-and-hosted.md@@ -12,7 +12,7 @@ Everything needed to run the full platform yourself — single-tenant, hardened,and not held back:- **Every service**, including the `mcp-host` agent runtime.-- The **eight `clerum.io` CRDs** and the CRD Helm chart.+- The **nine `clerum.io` CRDs** and the CRD Helm chart.- The **full security model** — default-deny NetworkPolicies, per-workloadsecurity contexts, the service-to-service JWT chain, and human-in-the-loopapprovals.diff --git a/docs/crds/README.md b/docs/crds/README.mdindex 4b9cd5fb3..c7b3fcbc4 100644--- a/docs/crds/README.md+++ b/docs/crds/README.md@@ -1,6 +1,6 @@# CRD Reference-evenfire defines **8** Custom Resource Definitions under the `clerum.io/v1alpha1`+evenfire defines **9** Custom Resource Definitions under the `clerum.io/v1alpha1`API group (historical code name — see [code names](../concepts/code-names.md)).Install via the Helm chart:@@ -13,16 +13,17 @@ kubectl apply -f ./charts/clerum-crds/crds/## CRDs-| CRD | Kind | Scope | Purpose | Reference |-| -------------------- | ---------------------- | ---------- | ------------------------------------------------------------------- | -------------------------------------------------- |-| Host | `Host` | Namespaced | Agent instance: model provider, context, secret, channels, approval | [host.md](host.md) |-| Context | `Context` | Namespaced | MCP server allowlist (and related scope) for Hosts | [context.md](context.md) |-| McpServer | `McpServer` | Namespaced | Connector deployment (image, transport, auth, env, egress) | [mcpserver.md](mcpserver.md) |-| CommunicationChannel | `CommunicationChannel` | Namespaced | Telegram / Email / Slack config + authorized users | [communicationchannel.md](communicationchannel.md) |-| WorkflowRecipe | `WorkflowRecipe` | Namespaced | Multi-workload composition with MCP registration | [workflowrecipe.md](workflowrecipe.md) |-| WorkflowRecipePolicy | `WorkflowRecipePolicy` | Namespaced | Governance policy for WorkflowRecipes | [workflowrecipepolicy.md](workflowrecipepolicy.md) |-| SharedFileSystem | `SharedFileSystem` | Namespaced | Per-team shared workspace (read-only to agents) | [sharedfilesystem.md](sharedfilesystem.md) |-| GlobalFileSystem | `GlobalFileSystem` | Namespaced | Brokered global drive with audited access | [globalfilesystem.md](globalfilesystem.md) |+| CRD | Kind | Scope | Purpose | Reference |+| -------------------- | ---------------------- | ---------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------- |+| Host | `Host` | Namespaced | Agent instance: model provider, context, secret, channels, approval | [host.md](host.md) |+| Context | `Context` | Namespaced | MCP server allowlist (and related scope) for Hosts; Control UI auto-creates one per agent | [context.md](context.md) |+| McpServer | `McpServer` | Namespaced | Connector deployment (image, transport, auth incl. OAuth, env, egress) | [mcpserver.md](mcpserver.md) |+| LlmHook | `LlmHook` | Namespaced | Installed guardrail hook called by mcp-host around LLM/tool calls | [llmhook.md](llmhook.md) |+| CommunicationChannel | `CommunicationChannel` | Namespaced | Telegram / Email / Slack / Microsoft Teams config + authorized users | [communicationchannel.md](communicationchannel.md) |+| WorkflowRecipe | `WorkflowRecipe` | Namespaced | Multi-workload composition with MCP registration | [workflowrecipe.md](workflowrecipe.md) |+| WorkflowRecipePolicy | `WorkflowRecipePolicy` | Namespaced | Governance policy for WorkflowRecipes | [workflowrecipepolicy.md](workflowrecipepolicy.md) |+| SharedFileSystem | `SharedFileSystem` | Namespaced | Per-team shared workspace (read-only to agents) | [sharedfilesystem.md](sharedfilesystem.md) |+| GlobalFileSystem | `GlobalFileSystem` | Namespaced | Brokered global drive with audited access | [globalfilesystem.md](globalfilesystem.md) |## Relationships@@ -34,6 +35,7 @@ Host|-- secretRef --> K8s Secret (API keys)|-- channels[] --> CommunicationChannel (by name)|-- approval --> policy for tool gates+ |-- guardrails.hooks --> LlmHook (0..N, llm-hooks namespace)WorkflowRecipe --governed by--> WorkflowRecipePolicyGlobalFileSystem (singleton-style governed drive; API via gfs-controller)@@ -46,13 +48,14 @@ Ready-to-apply manifests:## Service ownership-| CRD | Primary consumers |-| -------------------- | --------------------------------------------------- |-| Host | mcp-host |-| Context | host-context-controller |-| McpServer | host-context-controller |-| CommunicationChannel | channel-reader |-| WorkflowRecipe | workflow-recipes (WRC) |-| WorkflowRecipePolicy | workflow-recipes (WRC) |-| SharedFileSystem | host-context-controller, workspace-files-controller |-| GlobalFileSystem | host-context-controller, gfs-controller |+| CRD | Primary consumers |+| -------------------- | ------------------------------------------------------ |+| Host | mcp-host |+| Context | host-context-controller |+| McpServer | host-context-controller |+| LlmHook | host-context-controller (reconciles), mcp-host (reads) |+| CommunicationChannel | channel-reader |+| WorkflowRecipe | workflow-recipes (WRC) |+| WorkflowRecipePolicy | workflow-recipes (WRC) |+| SharedFileSystem | host-context-controller, workspace-files-controller |+| GlobalFileSystem | host-context-controller, gfs-controller |diff --git a/docs/crds/communicationchannel.md b/docs/crds/communicationchannel.mdindex ddabdc902..a40718054 100644--- a/docs/crds/communicationchannel.md+++ b/docs/crds/communicationchannel.md@@ -9,7 +9,7 @@## PurposeCommunicationChannel defines one or more communication channel groups (Telegram,-Email, Slack) with their allowed user identifiers. The channel-reader service+Email, Slack, Microsoft Teams) with their allowed user identifiers. The channel-reader servicewatches these CRDs, polls each configured channel for new messages fromauthorized senders, and forwards them to the mcp-host.Telegram personal approval accounts are verified separately from Profile UI.@@ -21,7 +21,7 @@ Telegram personal approval accounts are verified separately from Profile UI.| Field | Type | Required | Description || ------------------------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `spec.hostRef` | string | yes | Reference to the Host this channel configuration belongs to. The channel-reader uses this to filter which channels it processes. |-| `spec.credentialsSecretRef` | object | no | Reference (`{ name }`) to a Secret in the `channels` namespace holding provider credentials for this channel — keyed by type: `telegram-bot-token`, `slack-bot-token`, `slack-signing-secret`, `email-username`, `email-password`. Auto-created as `cc-<ccname>-credentials` when set via the Control UI; raw YAML may point at a shared Secret. |+| `spec.credentialsSecretRef` | object | no | Reference (`{ name }`) to a Secret in the `channels` namespace holding provider credentials for this channel — keyed by type: `telegram-bot-token`, `slack-bot-token`, `slack-signing-secret`, `teams-app-password`, `email-username`, `email-password`. Auto-created as `cc-<ccname>-credentials` when set via the Control UI; raw YAML may point at a shared Secret. || `spec.access` | object | no | Users and teams allowed to connect conversations to this channel: `access.users[]` and `access.teams[]` (string lists). The Control UI restricts these to principals that already have access to `hostRef`. |### Telegram@@ -61,6 +61,8 @@ Telegram personal approval accounts are verified separately from Profile UI.| `spec.slack` | object[] | no | List of Slack channel groups. || `spec.slack[].channelId` | string | yes | Slack channel identifier. When `userIds` are configured, must be a stable Slack channel ID, not a display name (e.g. `C0123456789`, `D0123456789`, or `G0123456789`). Legacy `userNames`-only groups may retain an existing channel display name. || `spec.slack[].workspaceId` | string | with userIds | Slack workspace/team ID (e.g. `T0123456789`). Required when `userIds` are configured so provider-originated workflow approval decisions bind to stable workspace identity; not required for legacy `userNames`-only groups. |+| `spec.slack[].conversationType` | string | no | Slack conversation type captured at setup. |+| `spec.slack[].title` | string | no | Slack conversation title captured at setup. || `spec.slack[].userIds` | string[] | yes for workflow approvals | Allowed Slack user IDs for this group (e.g. `U0123456789`). Workflow approval decisions use this stable identity. || `spec.slack[].userNames` | string[] | legacy | Legacy allowed Slack usernames for non-workflow chat filtering. Usernames are not accepted as workflow approval identity. || `spec.slack[].replyOnlyWhenMentioned` | boolean | no | If `true`, only process messages that include an app mention of this bot (`<@USER_ID>`). Non-approval messages are dropped until Slack `auth.test` returns a bot `user_id`. `/approve` and `/deny` commands are always accepted from allowed senders. |@@ -81,7 +83,35 @@ Telegram personal approval accounts are verified separately from Profile UI.| `spec.slackSettings.replyOnlyWhenMentioned` | boolean | no | If `true`, process Slack messages only when the app is mentioned. || `spec.slackSettings.replyInThreads` | boolean | no | If `true`, app responses are posted in a thread for the triggering message and follow-ups in that thread continue there. |-At least one channel group (`telegram`, `email`, or `slack`) should be defined for the+### Microsoft Teams++Teams messages arrive through the Bot Framework webhook (see+[Connect Microsoft Teams](../how-to/connect-teams.md)). Conversations are+recorded here as users confirm them.++| Field | Type | Required | Description |+|-------|------|----------|-------------|+| `spec.teams` | object[] | no | List of confirmed Teams conversations. |+| `spec.teams[].channelId` | string | yes | Teams conversation ID from the Bot Framework activity. |+| `spec.teams[].tenantId` | string | yes | Microsoft Entra tenant ID for the conversation. |+| `spec.teams[].serviceUrl` | string | no | Bot Framework service URL captured from the activity. |+| `spec.teams[].conversationType` | string | no | `personal`, `groupChat`, or `channel`. |+| `spec.teams[].teamId` / `teamsChannelId` | string | no | Team and channel IDs when the conversation is a team channel. |+| `spec.teams[].userIds` | string[] | no | Allowed Teams user IDs for this conversation. |+| `spec.teams[].title` | string | no | Conversation title captured at setup. |+| `spec.teams[].confirmedByUserId` / `confirmedAt` | string | no | evenfire user who confirmed the conversation, and when. |+| `spec.teams[].replyInThreads` | boolean | no | `false` posts replies at the conversation root; missing means reply in the source thread. |++#### Teams global settings++| Field | Type | Required | Description |+|-------|------|----------|-------------|+| `spec.teamsSettings.appName` | string | no | Teams app or bot name shown during user setup. |+| `spec.teamsSettings.tenantId` | string (UUID) | no | Microsoft Entra tenant ID for the bot. |+| `spec.teamsSettings.appId` | string (UUID) | no | Microsoft app (client) ID for the bot. The client secret stays in `credentialsSecretRef` as `teams-app-password`. |+| `spec.teamsSettings.replyOnlyWhenMentioned` | boolean | no | If `true`, process Teams messages only when the bot is mentioned. |++At least one channel group (`telegram`, `email`, `slack`, or `teams`) should be defined for theCRD to be useful, though the schema does not enforce this.### Telegram Upgrade Note@@ -101,7 +131,7 @@ entry for that user.## Additional Printer Columns-`kubectl get channels` displays: Host, Telegram Groups, Email Groups, Slack Groups.+`kubectl get channels` displays: Host, Telegram Groups, Email Groups, Slack Groups, Teams Groups.## Examplediff --git a/docs/crds/host.md b/docs/crds/host.mdindex 6aab6c8b1..23877a459 100644--- a/docs/crds/host.md+++ b/docs/crds/host.md@@ -9,19 +9,22 @@Host is the central entity that binds an LLM model provider to a context (MCP server allowlist),a Kubernetes Secret containing API keys, and one or more communication channels. Each Host-represents a single LLM agent instance.+represents a single LLM agent instance (an "agent" in Control UI and the Desktop App).## Spec Fields| Field | Type | Required | Description ||-------|------|----------|-------------|-| `spec.host` | string | yes | Host identifier (e.g. `chatLLM`). |-| `spec.contextRef` | string | yes | Reference to the Context CRD name (e.g. `context1`) that defines which MCP servers this host can access. |-| `spec.secretRef` | string | yes | Name of the Kubernetes Secret containing LLM API keys (`openai-api-key`, `claude-api-key`, `zai-api-key`, `bailian-api-key`). |+| `spec.host` | string | yes | Display name for the agent (free text, spaces and capitals allowed). The immutable identifier is `metadata.name`. |+| `spec.contextRef` | string | yes | Reference to the Context CRD name that defines which MCP servers this host can access. Control UI creates a private Context per agent automatically; you only manage Contexts directly when working with CRDs. |+| `spec.secretRef` | string | conditional | Name of the Kubernetes Secret holding static LLM API keys, one data key per provider slot (e.g. `openai-api-key`, `claude-api-key`, `groq-api-key`; see [LLM providers](../llm-providers/README.md)). Required whenever the primary or a fallback uses a static-credential provider; optional only when every target is the same subscription provider. || `spec.channels` | string[] | no | List of CommunicationChannel CRD names this host interacts with. || `spec.model` | object | no | LLM model configuration. |-| `spec.model.provider` | string | no | LLM provider. One of: `openai`, `claude`, `zai`, `bailian`. |-| `spec.model.name` | string | no | Model name (e.g. `gpt-5.4-mini`, `claude-opus-4-7`, `glm-5.1`). |+| `spec.model.provider` | string | no | One of the 24 provider ids in [`packages/llm-providers`](../../packages/llm-providers/index.cjs): `openai`, `claude`, `zai`, `bailian`, `vertex`, `bedrock`, `openrouter`, `gemini`, `deepseek`, `groq`, `together`, `fireworks`, `mistral`, `xai`, `cerebras`, `deepinfra`, `perplexity`, `moonshot`, `nebius`, `novita`, `minimax`, `azure`, `codex-subscription`, `grok-subscription`. |+| `spec.model.name` | string | no | Model name (e.g. `gpt-5.4-mini`, `claude-opus-4-7`, `glm-5.1`). Must be enabled in the operator model allowlist. |+| `spec.model.connectionRef` | string | no | Named subscription connection this Host is assigned to (subscription providers only). |+| `spec.allowedModels[]` | object[] | no | Up to 32 `{provider, model}` pairs users may switch between per session. Each pair must exist in the global allowlist. |+| `spec.llmPolicy` | object | no | Opt-in provider fallback. `fallbacks[]` (1–8 ordered `{provider, model, credentialSlot?}`), `triggerOn[]` (subset of `insufficient_quota`, `auth`, `provider_unavailable`, `rate_limited`; default all), `cooldownSeconds` (default 300) before the primary is retried. A Host may use at most one subscription provider across primary and fallbacks. || `spec.workflowControl.scopes` | string[] | no | Workflow broker scopes this Host may receive in its mcp-host-control JWT. Valid values: `workflow:list`, `workflow:read`, `workflow:trigger`, `workflow:approval:resolve`, `workflow:approval:decide`. `workflow_status` and `workflow_health` are covered by `workflow:read`; there is no native `workflow_read` tool. `workflow:approval:resolve` is required for provider identity resolution through this first-party Host; `workflow:approval:decide` is required when a bound channel-reader relays provider-originated workflow approval decisions. || `spec.approval` | object | no | Tool approval configuration -- controls who can approve tool executions. || `spec.approval.defaultPolicy` | string | no | Who can approve tool calls. One of: `cli_only` (HTTP endpoints only), `channel_users` (any authorized channel user), `designated_approvers` (only users in approvers list). |@@ -39,6 +42,7 @@ represents a single LLM agent instance.| `spec.desktop` | object | no | Desktop environment configuration. || `spec.desktop.browser` | boolean | no | Enable Playwright browser tools (`browser_open`, `browser_screenshot`, etc.). || `spec.desktop.x11` | boolean | no | Enable X11 desktop tools (`desktop_screenshot`, `desktop_click`, `desktop_type`, etc.). |+| `spec.lifecycle.stateless` | boolean | no | Default `false`. Enables the stateless lifecycle: session state is persisted to the workspace volume and the controller may scale the agent to zero while idle (`status.lifecycle.state: suspended`). Rejected at reconcile (condition `StatelessEnableRejected`) for Hosts with channels or a desktop. || `spec.personalization` | object | no | Identity files (admin-managed, read-only to the agent). || `spec.personalization.enabled` | boolean | no | Whether mcp-host should reconcile identity files from this block. || `spec.personalization.identity` | string | no | Content of `IDENTITY.md` (system-prompt section "## Identity"). |@@ -46,6 +50,30 @@ represents a single LLM agent instance.| `spec.personalization.agents` | string | no | Content of `AGENTS.md` (system-prompt section "## Agent Instructions"). || `spec.personalization.user` | string | no | Content of `USER.md` (system-prompt section "## User Context"). |+| `spec.guardrails` | object | no | Opt-in guardrail policy. A Host without it runs no rules or hooks. See [Guardrails](#guardrails). |++### Guardrails++| Field | Description |+|-------|-------------|+| `guardrails.rules[]` | Ordered tool-lane rules evaluated top-down: `{id, action: allow\|ask\|deny, reasonCode, match: {tool, arguments[]}}`. |+| `guardrails.hooks.<phase>[]` | Installed [LlmHook](llmhook.md) references `{id, digest}` per phase: `preToolUse`, `postToolUse`, `preCall`, `moderate`, `postCallSuccess`, `onError`. |+| `guardrails.builtins[]` | First-party hooks compiled into mcp-host (e.g. `prompt-shaping`, `token-trim`). |+| `guardrails.minInstalledHookTrustLevel` | `low` \| `mid` \| `high`: minimum platform-assigned trust level an installed hook needs to run on this Host. |+| `guardrails.capabilityCeiling[]` | Upper bound on hook capabilities: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. |+| `guardrails.approvalPolicies[]` | Approval policies available to `ask` decisions: `cli_only`, `channel_users`, `designated_approvers`. |+| `guardrails.limits` | `maxRules` (100), `maxHooksPerPhase` (8), `maxHookTimeoutMs` (5000), `maxHookOutputBytes` (65536). |++Apply the CRD before any component writes `spec.guardrails`: the API server+silently prunes fields an older CRD does not know.++## Status Fields++| Field | Description |+|-------|-------------|+| `status.lifecycle` | Stateless lifecycle state: `state` (`active` \| `draining` \| `suspended`), `wakeHandledGeneration`, `reason`. |+| `status.conditions[]` | Standard conditions (e.g. `StatelessEnableRejected`). |+## Additional Printer Columns`kubectl get hosts` displays: Host, Context, Secret, Provider.diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.mdnew file mode 100644index 000000000..1450066f5--- /dev/null+++ b/docs/crds/llmhook.md@@ -0,0 +1,113 @@+# LlmHook CRD Reference++**API Group:** `clerum.io`+**Version:** `v1alpha1`+**Scope:** Namespaced (installed hooks live in the `llm-hooks` namespace)+**Reconciled by:** host-context-controller · **Read by:** mcp-host++## Purpose++An LlmHook is an installed **guardrail hook**: an HTTP service that mcp-host+calls at defined points of an agent turn, either around the LLM call (LLM lane)+or around a tool call (tool lane). A hook can deny, rewrite, substitute a+result, or add context, but only within the capabilities an admin granted it.++A Host opts in by listing hooks under `Host.spec.guardrails.hooks.<phase>[]`+(see [Host CRD](host.md)). A Host without a `guardrails` block runs no hooks.++- **Image targets:** host-context-controller deploys a Deployment, Service,+ and NetworkPolicy in `llm-hooks`. Hooks that share an image digest are+ co-located on one pod and routed by `spec.path`.+- **Service and remote targets:** nothing is deployed.+- **Who writes what:** mcp-host only reads LlmHook CRs. Only the controller+ writes `status`.++Control UI installs hooks from the registry (**Installed Guardrails**). The+install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,+`mid` or `high`) that hook authors cannot set. The Host's+`guardrails.minInstalledHookTrustLevel` is checked against that annotation.++## Spec Fields++| Field | Type | Required | Description |+| -------------------------------------------- | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `spec.target` | object | yes | Exactly one of `image`, `service`, `remote`. |+| `spec.target.image.ref` | string | yes (image) | Container image. Validated against the image allowlist and digest-pinned at install. |+| `spec.target.image.port` | int | yes (image) | Port the hook HTTP server listens on (1–65535). |+| `spec.target.image.imagePullSecrets` | string[] | no | Pull secret names in `llm-hooks`. |+| `spec.target.image.envSecret` | string | no | The hook's own credential Secret in `llm-hooks`. It can never reference a Host or LLM-key Secret. |+| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. Looser than McpServer egress: no private-range hardening yet. |+| `spec.target.image.security.addCapabilities` | string[] | no | Subset of `CHOWN`, `FOWNER`, `DAC_OVERRIDE`, `NET_BIND_SERVICE`. |+| `spec.target.service` | object | yes (service) | Existing in-cluster Service: `name`, `namespace`, `port`. |+| `spec.target.remote.baseUrl` | string | yes (remote) | External endpoint mcp-host dials directly. Must be `https://`; SSRF-validated at dial time. |+| `spec.target.remote.authHeadersSecret` | string | no | Secret supplying auth headers for the remote endpoint. |+| `spec.path` | string | no (default `/`) | Calls go to `{endpoint}{path}/v1/{point}`. Co-located image hooks must use distinct paths. |+| `spec.lifecyclePoints` | string[] | yes (1–6) | LLM lane: `preCall`, `moderate`, `postCallSuccess`, `onError`. Tool lane: `preToolUse`, `postToolUse`. |+| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |+| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |+| `spec.failMode` | `open` \| `closed` | no (default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. |+| `spec.timeoutMs` | int | no (default 5000) | Per-call timeout. |+| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |+| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Must fall within the Host's `guardrails.capabilityCeiling`, and is re-checked on every hook response. |+| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |++### Admission rules++- `remote.baseUrl` must start with `https://`.+- A hook granted `may_deny` must use `failMode: closed`.+- `contentAccess: metadata` is rejected for `moderate`, `postCallSuccess`,+ `onError`, `preToolUse` and `postToolUse`, which are inherently+ content-bearing.+- A content-bearing hook that has `egressBindings` or a `remote` target can+ only be installed at trust level `high`.++## Status Fields++| Field | Description |+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `status.observedDigest` | Image digest actually running. mcp-host binds `Host.spec.guardrails.hooks[].digest` against this, and fails closed (or skips with an alert) on mismatch. |+| `status.readyReplicas` | Ready replicas (image targets only). |+| `status.lastReconciled` | Timestamp of the last successful reconcile. |+| `status.conditions[]` | Standard conditions (`Deployed`, `Ready`) with `observedGeneration`. |++`kubectl get llmhooks -n llm-hooks` shows Path, Order, FailMode, Digest, and Ready.++## Example++```yaml+apiVersion: clerum.io/v1alpha1+kind: LlmHook+metadata:+ name: pii-redactor+ namespace: llm-hooks+spec:+ target:+ image:+ ref: ghcr.io/example/pii-redactor@sha256:<digest>+ port: 8080+ path: /pii+ lifecyclePoints: [postCallSuccess]+ capabilities: [may_substitute_result]+ failMode: closed+ timeoutMs: 3000+```++Referenced from a Host:++```yaml+spec:+ guardrails:+ capabilityCeiling: [may_deny, may_substitute_result]+ hooks:+ postCallSuccess:+ - id: pii-redactor+ digest: sha256:<digest>+```++A zero-dependency reference implementation of the `/v1` protocol lives in+[`hooks/reference-guardrail-hook/`](../../hooks/reference-guardrail-hook/).++## Related++- [Host CRD](host.md): `spec.guardrails`+- [CRD Index](README.md)diff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.mdindex 22cf4a5d1..73b38b4f2 100644--- a/docs/crds/mcpserver.md+++ b/docs/crds/mcpserver.md@@ -41,10 +41,58 @@ HCC-owned servers, and exposes discovery/status for WRC-owned servers.| Field | Type | Required | Description ||-------|------|----------|-------------|| `spec.auth` | object | no | Authentication configuration for the mcp-host connecting to this server. |-| `spec.auth.type` | string | no | Authentication type. One of: `none`, `bearer`, `basic`, `apiKey`. |+| `spec.auth.type` | string | no | Authentication type. One of: `none`, `bearer`, `basic`, `apiKey`, `oauth`. `oauth` requires `spec.oauth` and forbids `secretRef`/`secretKey`. || `spec.auth.secretRef` | string | no | Name of the Kubernetes Secret containing auth credentials. || `spec.auth.secretKey` | string | no | Key within the secret to use (default depends on auth type). |+### OAuth (`spec.oauth`)++Present only when `spec.auth.type: oauth`. control-api runs the OAuth 2.1+authorize, token and refresh flow. Tokens are resolved per connection at call+time and are **never mounted into the connector pod**.++> **Enable the broker first.** `MCP_OAUTH_BROKER_ENABLED` is **off by default**+> in `deploy/base` (the minikube overlay turns it on). While it is off,+> OAuth connectors keep asking for consent and never get a token. Also set+> `CONTROL_API_OAUTH_CALLBACK_BASE_URL` to the browser-reachable control-api+> origin; otherwise callbacks fall back to an internal hostname.++There are three configuration styles, chosen by `source`, which can't change+after creation:++- **Built-in provider** (`source` absent): one of the known adapters in+ `provider`.+- **`remote`**: endpoints pinned from discovery when the remote-connector+ wizard installs the server.+- **`generic`**: an operator-configured client with explicit endpoints and+ wire options.++| Field | Applies to | Description |+|-------|-----------|-------------|+| `oauth.id` | all | Stable client identifier; also the callback path segment. Immutable. |+| `oauth.provider` | built-in | `salesforce`, `slack`, `notion`, `microsoft-graph`, `google`, `monday`, `clickup`, `vercel`. Immutable. |+| `oauth.clientIdRef` / `oauth.clientSecretRef` | all | `{name, key}` of Secrets in the `mcp-servers` namespace holding the client id / secret. |+| `oauth.scopes[]` | all | Scopes to request. Include the provider's offline/refresh scope when `backgroundAccess` is true. |+| `oauth.backgroundAccess` | all | Allow use by a workload with no live human session. |+| `oauth.grantScope` | all | `user` (default): every user authorizes their own grant. `context`: one shared identity per Context, which one member bootstraps and others inherit. Immutable. |+| `oauth.source` | — | absent (built-in), `remote`, or `generic`. Immutable. |+| `oauth.clientMode` | remote | `public` (PKCE, no secret) or `confidential`. |+| `oauth.authorizationEndpoint`, `tokenEndpoint`, `resource` | remote, generic | Pinned endpoints; `resource` is the RFC 8707 resource indicator. |+| `oauth.registrationEndpoint`, `issuer`, `issForCallback` | remote | Dynamic client registration URL, issuer, and the RFC 9207 `iss` validated on callback. |+| `oauth.bearerInBody`, `supportsRefresh` | remote (`supportsRefresh` also generic) | Pinned at install. `bearerInBody` must be `false`. |+| `oauth.tokenRequestFormat`, `tokenAuthMethod`, `scopeSeparator`, `sendScope`, `usePkce`, `includeResponseType`, `refreshEndpoint`, `extraAuthorizeParams` | generic | Wire options for non-standard authorization servers. |++**Redirect URI to register** with the provider:++- Built-in and `generic`:+ `<CONTROL_API_OAUTH_CALLBACK_BASE_URL>/api/v1/oauth-callback/<oauth.id>`.+- `remote`: `/api/v1/oauth-callback/remote` when the authorization server+ advertises RFC 9207, otherwise `/api/v1/oauth-callback/remote/<serverName>`.+ With dynamic registration, the install id is appended and registered+ automatically.++The Control UI wizard shows the exact URI.+### Server Configuration| Field | Type | Required | Default | Description |@@ -182,6 +230,7 @@ API translates to this explicit `egressClass: public-web` CRD shape.| `status.resolvedEgressIPs[].dns` | string | The DNS hostname that was resolved. || `status.resolvedEgressIPs[].ips` | string[] | Resolved IP addresses. || `status.resolvedEgressIPs[].resolvedAt` | date-time | When the resolution occurred. |+| `status.conditions[]` | object[] | Standard conditions written by host-context-controller (e.g. `SecretResolved`, `Ready`) with `reason` (e.g. `SecretNotFound`) and `observedGeneration`. Control UI uses them to show connectors whose credentials are still missing. |## Additional Printer Columnsdiff --git a/docs/deploy/llm-providers.md b/docs/deploy/llm-providers.mdindex 0c9f0e8da..36a82f152 100644--- a/docs/deploy/llm-providers.md+++ b/docs/deploy/llm-providers.md@@ -5,9 +5,10 @@ credentials (including the multi-slot providers **Google Vertex AI** and**Amazon Bedrock**), how to manage the operator-declared model allowlist, and howthe per-session model selector behaves in the desktop app.-The canonical provider set — **23 providers**, from `openai`, `claude`+The canonical provider set — **24 providers**, from `openai`, `claude`(Anthropic), `zai` and `bailian` through the own-SDK `vertex` / `bedrock` to the-OpenAI-compatible additions and `azure` — and their credential slots live in the+OpenAI-compatible additions, `azure`, and the two sign-in subscription providers+(`codex-subscription`, `grok-subscription`, off by default in `deploy/base`) — and their credential slots live in theshared `@clerum/llm-providers` package, which the Control UI, control-api,mcp-host, and the workflow runtime all consume. See the[providers overview](../llm-providers/README.md) for the full list and the@@ -86,7 +87,7 @@ deliberately absent from the recipe CRD's provider enum, so a recipe pinningeither is rejected at admission. The workflow `configure` transport carries asingle credential string, which can deliver neither Bedrock's key pair norAzure's required endpoint. Both remain fully supported for interactive Hosts;-the other 20 providers are admissible in recipes — see the+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.diff --git a/docs/deploy/minikube.md b/docs/deploy/minikube.mdindex 0aba64c01..dab93edb2 100644--- a/docs/deploy/minikube.md+++ b/docs/deploy/minikube.md@@ -4,9 +4,10 @@ Reference guide for deploying the **full** evenfire platform on local minikube(all services, JWT auth chain, NetworkPolicies). Historical scripts and profilesmay still say **clerum** ([code names](../concepts/code-names.md)).-> **New here?** For a 10-minute agent-only try without Kubernetes, use the-> [Quickstart](../get-started/quickstart.md) first. This guide is the full local-> platform path (Path C in the [learning path](../get-started/learning-path.md)).+> **New here?** Start with the [Quickstart](../get-started/quickstart.md): it+> brings up this same full platform with one command and walks you to a first+> chat. This guide is the in-depth reference for the full local platform path+> (Path C in the [learning path](../get-started/learning-path.md)).Includes the correct order of operations, the JWT authentication chain, and known issues.@@ -124,9 +125,9 @@ before enabling the feature flag.When deployable code changed and the E2E runner will manage port-forwardsitself, force the sync and skip the short-lived background port-forward refresh.Inner `pre-gate-sync` may use `--skip-port-forwards`; never pass that globally-into `make minikube-t2`. Do not kill this lane's `branch-profile-pf`.-`make minikube-pf-all-bg` is a gate refresh only; it must not replace-`branch-profile-pf`.+into `make minikube-t2`. On a branch-owned profile, keep `branch-profile-pf`+running: `make minikube-pf-all-bg` only refreshes forwards for a gate and does+not replace it.```bashmake minikube-pre-gate-sync GATE=<gate-name> ARGS="--force-cluster-sync --skip-port-forwards"@@ -160,18 +161,15 @@ npm run uiopen http://localhost:3000```-`make minikube-setup` seeds the default test user and agent/context access. `npm run ui` keeps the required API port-forwards open while it runs the local frontends.+`make minikube-setup` seeds the `[email protected]` admin (default `minimal`+seed profile) and the `chatllm` agent with its context. `npm run ui` keeps the required API port-forwards open while it runs the local frontends.-For a branch-owned profile, the host-side hold for Control UI / Desktop is-the first-hand entry point `scripts/minikube-profiles/branch.mk`.-Implementation: `scripts/minikube-profiles/branch-profile.sh`.-HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.-Profile-owned random ports only (never shared `:3000`/`:8090`).-`make minikube-pf-all-bg` is a gate refresh only; it must not replace-`branch-profile-pf`. Do not start UI PFs from a sandboxed agent shell. Run-the make target on the host. Do not kill this lane's `branch-profile-pf`.-`branch-profile-pf-health` starts PFs then STOPS them on EXIT — do not use-it as the lasting hold.+**Branch-owned profiles** (contributors running several clusters side by+side) use `scripts/minikube-profiles/branch.mk` instead of the shared+`:3000`/`:8090` mapping. It forwards on profile-owned random ports and must+run on the host, not inside a sandboxed shell. `branch-profile-pf` is the+lasting hold; `branch-profile-pf-health` starts forwards, checks them, and+stops them on exit.```bashMINIKUBE_PROFILE=<owned-profile> \@@ -606,8 +604,8 @@ kubectl rollout restart deployment/rpc-proxy -n rpc-proxy --context clerum-test## Port Forwards for the Desktop App-On a branch-owned profile, do not use the shared `:3000`/`:8090` mapping-below. First-hand entry point `scripts/minikube-profiles/branch.mk`:+On a branch-owned profile, use `scripts/minikube-profiles/branch.mk` instead+of the shared `:3000`/`:8090` mapping below:```bashMINIKUBE_PROFILE=<owned-profile> \@@ -617,11 +615,8 @@ MINIKUBE_PROFILE=<owned-profile> \make -f scripts/minikube-profiles/branch.mk branch-profile-health```-Implementation: `scripts/minikube-profiles/branch-profile.sh`.-HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.-`make minikube-pf-all-bg` is a gate refresh only; it must not replace-`branch-profile-pf`. `branch-profile-pf-health` starts PFs then STOPS them-on EXIT — do not use it as the lasting hold.+`branch-profile-pf` is the lasting hold; `branch-profile-pf-health` stops its+forwards on exit, and `make minikube-pf-all-bg` does not replace either.The shared `clerum-test` Desktop mapping remains:diff --git a/docs/desktop-ui-ux/README.md b/docs/desktop-ui-ux/README.mdindex 718322a85..5ba1604f4 100644--- a/docs/desktop-ui-ux/README.md+++ b/docs/desktop-ui-ux/README.md@@ -10,7 +10,5 @@ This folder is the source of truth for desktop UX decisions, with a focus on end## Current Documents-- `teams-experience-source-of-truth.md`:- - deep analysis of current `control-ui` and `desktop-app` teams flows- - endpoint mapping and reuse constraints- - UX requirements and implementation plan for a user-friendly desktop Teams section+- [`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/faq.md b/docs/faq.mdindex a20ec2c30..3ae7df1b7 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -113,7 +113,7 @@ dmg/squirrel/deb/rpm/zip, covering macOS, Windows, and Linux. See### How many CRDs are there?-Eight under `clerum.io`: Host, Context, McpServer, CommunicationChannel,+Nine under `clerum.io`: Host, Context, McpServer, LlmHook, CommunicationChannel,WorkflowRecipe, WorkflowRecipePolicy, SharedFileSystem, GlobalFileSystem.Index: [CRDs](crds/README.md).diff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.mdindex 01d14e82c..dcd6bd181 100644--- a/docs/get-started/minikube.md+++ b/docs/get-started/minikube.md@@ -4,8 +4,10 @@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 whichever-single LLM key you set in `.env`.+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@@ -24,7 +26,8 @@ runs it automatically first (bypass with `SKIP_PREREQS=true`).git clone https://github.com/evenfire-ai/evenfire.git && cd evenfirecp .env.example .env# edit .env: set ADMIN_PASSWORD (required — no default ships) and ONE LLM key-# (setup infers the matching provider)+# (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 safemake minikube-status # wait for every deployment READY```diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex 366dee0c2..4cd0e11cf 100644--- a/docs/get-started/quickstart.md+++ b/docs/get-started/quickstart.md@@ -18,10 +18,14 @@ named `chatllm` you can message immediately.- **Node.js 24+** (service builds; desktop app)- **git**, **make**, and **ruby** (ruby renders the control-api DB migrationoverlay; ships with macOS, `apt-get install ruby` on Debian/Ubuntu)-- One LLM API key from any of the 22 supported providers (e.g. OpenAI,- Anthropic Claude, Google Gemini, Groq, Mistral, Z.AI, Alibaba Bailian) —- optional for setup (it boots with placeholders), but the agent can't call a- model without one. Full list: [../deploy/llm-providers.md](../deploy/llm-providers.md)+- One LLM API key. Setup picks the agent's provider automatically from+ `OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY` or `BAILIAN_API_KEY`+ (first one set wins). For any other supported provider (Gemini, Groq,+ Mistral, … see [the full list](../llm-providers/README.md)) put its key in+ `.env` **and** set `CLERUM_MODEL_PROVIDER` and `CLERUM_MODEL_NAME`. The pair+ must be enabled in the model allowlist, or setup stops with+ `HOST_MODEL_UNKNOWN`. Without any key, setup still boots, but the agent+ can't reply until you add one.## 1. Configure@@ -118,30 +122,10 @@ screen — live activity, artifacts, sandbox UIs — see## 4. Say hello — the API-The headless path exercises the production JWT chain end to end. With-`make minikube-pf-all` holding port-forwards in another terminal-(control-api :8090, external-rest-api :8091, rpc-proxy :8094, mcp-host :8080)-on the shared `clerum-test` profile. For a branch-owned profile, first-hand-entry point `scripts/minikube-profiles/branch.mk`:--```bash-MINIKUBE_PROFILE=<owned-profile> \- make -f scripts/minikube-profiles/branch.mk branch-profile-pf--MINIKUBE_PROFILE=<owned-profile> \- make -f scripts/minikube-profiles/branch.mk branch-profile-health-```--Implementation: `scripts/minikube-profiles/branch-profile.sh`.-HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.-This is the host-side hold for Control UI / Desktop. Profile-owned random-ports only (never shared `:3000`/`:8090`). `make minikube-pf-all-bg` is a-gate refresh only; it must not replace `branch-profile-pf`. Do not start UI-PFs from a sandboxed agent shell. Run the make target on the host. Do not-kill this lane's `branch-profile-pf`. `branch-profile-pf-health` starts PFs-then STOPS them on EXIT — do not use it as the lasting hold.--Shared-profile curl example (fixed ports):+The headless path exercises the production JWT chain end to end. Keep+`make minikube-pf-all` running in another terminal; it holds the+port-forwards open (control-api :8090, external-rest-api :8091,+rpc-proxy :8094, mcp-host :8080). Then:```bashEXT=http://localhost:8091 RPC=http://localhost:8094 HOST=chatllm@@ -202,7 +186,7 @@ Details: [Connect Telegram](../how-to/connect-telegram.md).| `minikube start` fails on memory | Raise Docker Desktop to ≥10 GB RAM / 6 CPUs — or, if you can't spare it, `MINIKUBE_MEMORY=9216 MINIKUBE_IMAGE_TAG=latest make minikube-setup` (stock Docker Desktop's ~9.9 GB is just under the 10 GB default) || Pods `Pending` early on | Calico is still coming up — wait, then `make minikube-status` || postgres CrashLoopBackOff after cold start | `make minikube-setup ARGS="--reset-db --skip-build"` |-| Port-forwards die | Shared profile: re-run `make minikube-pf-all` (it holds them open; Ctrl-C stops). Branch-owned profile: `MINIKUBE_PROFILE=<owned-profile> make -f scripts/minikube-profiles/branch.mk branch-profile-pf` (do not use `branch-profile-pf-health` as the lasting hold; do not replace it with `make minikube-pf-all-bg`) |+| Port-forwards die | Re-run `make minikube-pf-all` (it holds them open; Ctrl-C stops) |## Next stepsdiff --git a/docs/get-started/registry-quickstart.md b/docs/get-started/registry-quickstart.mdindex 15b6e1069..c37d3e074 100644--- a/docs/get-started/registry-quickstart.md+++ b/docs/get-started/registry-quickstart.md@@ -91,12 +91,12 @@ press **Install**.| Field | Notes || --------------- | ------------------------------------------------------------------------------------------------- || **Name** | Optional. Left blank, it is generated from the entry name and version. Must be a valid K8s name. |-| **Context** | **Required.** The agent context that gets the tool. || **Credentials** | Only if the entry declares them. Fill in **all** fields or **none** (empty installs it pending). || **Egress** | Review the external hosts the connector needs. Default-deny networking means unlisted hosts fail. |The install runs as a server-side saga: it verifies the bundle digest, creates-the `McpServer`, wires it into the context, and rolls back if a step fails.+the `McpServer` with its own private access scope, and rolls back if a step+fails. Afterwards, grant it to agents from **Installed Connectors**.Verify it landed:@@ -184,7 +184,8 @@ A **local** connector runs from an image the registry hosts under your org. Pushit before publishing the entry that points at it. Recipes have no image and skipthis step.-**Publisher → Docker credentials** (`/publisher/credentials`) generates a push+**Marketplace → _your org_ → Credentials** (`/marketplace/org/credentials`,+formerly Publisher → Docker credentials) generates a pushcredential and shows your exact coordinate. Log in with the literal username`_`, then push into `<org>/<name>`:diff --git a/docs/how-to/add-mcp-server.md b/docs/how-to/add-mcp-server.mdindex 956fab9b7..501884093 100644--- a/docs/how-to/add-mcp-server.md+++ b/docs/how-to/add-mcp-server.md@@ -83,7 +83,7 @@ Check:## Option C — the Control UI-Connectors → `/mcp-servers` → **Create** builds the same `McpServer` resource+**Installed Connectors** (`/connectors`) → **Create** builds the same `McpServer` resourceas Option B, through a guided form (identity, transport/runtime, secrets) plusan `EgressEditor` step for the egress policy: closed-by-default, withprivate, metadata, link-local, and reserved IPv4 ranges rejected outright.diff --git a/docs/how-to/publish-plugin-to-registry.md b/docs/how-to/publish-plugin-to-registry.mdindex 38ad35883..5f0603026 100644--- a/docs/how-to/publish-plugin-to-registry.md+++ b/docs/how-to/publish-plugin-to-registry.md@@ -91,7 +91,8 @@ curl -s -H "Authorization: Bearer $REGISTRY_API_KEY" \A **local** connector runs from an image the registry hosts under your org. Pushit before publishing the entry that references it.-**Control UI → Publisher → Docker credentials** (`/publisher/credentials`)+**Control UI → Marketplace → _your org_ → Credentials**+(`/marketplace/org/credentials`, formerly Publisher → Docker credentials)generates a durable push credential and hands you the login command, adownloadable `dockerconfigjson` for CI, and your exact push coordinate. A keyminted at **Marketplace → API keys** works identically — both are `efrk_` orgdiff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.mdindex be556c39f..aed32259a 100644--- a/docs/llm-providers/README.md+++ b/docs/llm-providers/README.md@@ -22,7 +22,7 @@ by (potentially) three different people.```mermaidflowchart LRsubgraph P["1. PROVIDER — who serves the model"]- P1["Host CRD spec.model.provider<br/>one of 22 ids<br/>chosen by the operator"]+ P1["Host CRD spec.model.provider<br/>one of 24 ids<br/>chosen by the operator"]endsubgraph M["2. MODEL — which model of that provider"]M1["allowlist llm_allowed_models<br/>operator-declared in Control UI<br/>user picks within it, per chat"]@@ -51,7 +51,7 @@ A few rules that follow from this split, and that surprise people:## 2. Which providers are supported-**23 providers**, defined once in+**24 providers**, defined once in[`packages/llm-providers/index.cjs`](../../packages/llm-providers/index.cjs) —the single source of truth consumed by mcp-host, control-api, the workflowruntime, the host controller and the Control UI.@@ -111,12 +111,31 @@ Azure is OpenAI-shaped but has no fixed base URL (per-resource endpoint), itauthenticates with an `api-key` header instead of `Authorization: Bearer`, and**its "model" is your Azure deployment name**, not a catalog id.+### Group D — subscription sign-in, no API key (2)++| Provider | id | Credential | Feature flags (all default `false` in `deploy/base`) |+| ---------------------------- | -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |+| ChatGPT (Codex) subscription | `codex-subscription` | OAuth sign-in held by control-api, no Secret slot | `CONTROL_API_CODEX_SUBSCRIPTION_ENABLED`, `MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` |+| Grok subscription | `grok-subscription` | OAuth sign-in held by control-api, no Secret slot | `CONTROL_API_GROK_SUBSCRIPTION_ENABLED`, `MCP_HOST_GROK_SUBSCRIPTION_ENABLED`, `WRC_GROK_SUBSCRIPTION_ENABLED` (recipes) |++These providers use a subscription account instead of an API key. An admin+signs in from Control UI (**Secrets → LLM → Subscriptions**,+`/secrets/llm/subscriptions`); control-api+keeps the OAuth tokens, and model traffic goes through the in-cluster+`codex-llm-proxy` / `grok-llm-proxy`. A Host selects a sign-in with+`spec.model.connectionRef` and needs no `secretRef` when every target is+the same subscription provider. A Host may use at most one subscription+provider. They are **off in `deploy/base`** and switched on in the minikube+overlay. Wire-level details:+[Codex transport contract](../architecture/codex-subscription-transport-contract.md),+[Grok transport contract](../architecture/grok-subscription-transport-contract.md).+### Important: not every provider works everywhere-| Surface | Providers supported |-| ----------------------------- | --------------------------------------- |-| Interactive Host (chat agent) | all **22** |-| WorkflowRecipe LLM steps | **20** — `bedrock` and `azure` excluded |+| Surface | Providers supported |+| ----------------------------- | ---------------------------------------------------- |+| Interactive Host (chat agent) | all **24** (subscription providers need their flags) |+| WorkflowRecipe LLM steps | **22** — `bedrock` and `azure` excluded |`bedrock` and `azure` are deliberately absent from the WorkflowRecipe CRD enum:the workflow `configure` transport carries a **single** credential string, so it@@ -388,7 +407,7 @@ failing over on those would just mask bugs.### Known sharp edge: workflow steps and the secret mapping-The WorkflowRecipe CRD admits **20** providers, but the shipped+The WorkflowRecipe CRD admits **22** providers, but the shipped`clerum-model-secret-mapping` ConfigMap([`deploy/base/mcp-host/model-secret-mapping.yaml`](../../deploy/base/mcp-host/model-secret-mapping.yaml))maps only **five**: `openai`, `claude`, `zai`, `bailian`, `vertex`.diff --git a/docs/llms.txt b/docs/llms.txtindex 306380b4e..f65171cd7 100644--- a/docs/llms.txt+++ b/docs/llms.txt@@ -35,7 +35,7 @@- 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 23 providers, including oauth-broker ChatGPT, mental model, support matrix): llm-providers/README.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@@ -54,6 +54,7 @@- Host: crds/host.md- Context: crds/context.md- McpServer: crds/mcpserver.md+- LlmHook (installed guardrail hooks): crds/llmhook.md- CommunicationChannel: crds/communicationchannel.md- WorkflowRecipe: crds/workflowrecipe.md- WorkflowRecipePolicy: crds/workflowrecipepolicy.mddiff --git a/docs/meta/claims-guardrails.md b/docs/meta/claims-guardrails.mdindex 9c0b89967..0b1425080 100644--- a/docs/meta/claims-guardrails.md+++ b/docs/meta/claims-guardrails.md@@ -11,8 +11,8 @@ caveats over absolute language.| Do not write | Prefer || ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- || Per-domain egress allowlisting for SaaS connectors | Port/CIDR egress with documented FQDN limits |-| “Any model” / every provider under the sun | The 23 canonical providers (README table); OpenAI-compatible entries are config |-| A provider outside the shared package as shipped | Only the 23 ids in `packages/llm-providers/index.cjs` ([overview](../llm-providers/README.md)) |+| “Any model” / every provider under the sun | The 24 canonical providers (README table); OpenAI-compatible entries are config |+| A provider outside the shared package as shipped | Only the 24 ids in `packages/llm-providers/index.cjs` ([overview](../llm-providers/README.md)) || Context memory always-on | Built-in pre-pruning + tiered compaction; **configurable** || Usage/cost in Grafana / `monitoring/` | control-api + control-ui (token dashboards, prices, budgets) || Token budgets as a security boundary | Cost control; fail-open |diff --git a/docs/surfaces/control-ui.md b/docs/surfaces/control-ui.mdindex 679b689fa..0e7aa2a4b 100644--- a/docs/surfaces/control-ui.md+++ b/docs/surfaces/control-ui.md@@ -21,7 +21,7 @@ Control UI is that loop, and it is the only place in the platform where allfive steps live together.1. **See it** — `UsageDashboard` (`components/UsageDashboard`), at- `/cost/usage`. A stacked-area chart of input/output tokens over time, with+ `/cost-and-usage/usage`. A stacked-area chart of input/output tokens over time, with**8 group-by dimensions**: team, model, agent (host), desktop user, recipe,provider, LLM secret, and source kind(`components/UsageDashboard/types.ts`). The desktop-user dimension is what@@ -31,8 +31,8 @@ five steps live together._Dev cluster, demo tenant._-2. **Cap it** — `TokenBudgetTable` (`/cost/token-budgets`) and- `LlmPriceTable` (`/cost/llm-prices`): per-1M-token model prices (input,+2. **Cap it** — `TokenBudgetTable` (`/cost-and-usage/token-budgets`) and+ `LlmPriceTable` (`/cost-and-usage/llm-prices`): per-1M-token model prices (input,output, cache read/write) and budgets with a scope, a period, and aprogress bar against the limit. Budgets are cost control and are **not** asecurity boundary. A budget can be set to `warn` (observation only, never@@ -77,12 +77,12 @@ five steps live together._Dev cluster, demo tenant._5. **Govern what gets installed** — `RegistryCatalog`- (`components/RegistryCatalog.tsx`), at `/registry`: marketplace entries- (connectors and plugins) with trust levels (high / mid / low) and a- guided install flow, plus org-scoped publish API keys (create / reveal /- revoke) at `/registry/keys`. Connector images are checked against an- allowlist, audit-mode by default, on both the direct `/mcp-servers`- Create form and registry installs — but that check is a no-op unless an+ (`components/RegistryCatalog.tsx`), under **Marketplace** (`/marketplace`):+ entries (connectors, plugins, guardrails) with trust levels+ (high / mid / low) and a guided install flow, plus org-scoped publish API+ keys (create / reveal / revoke) at `/marketplace/keys`. Connector images are+ checked against an allowlist, audit-mode by default, on both the direct+ `/connectors` Create form and registry installs — but that check is a no-op unless anoperator turns on enforcement, since the shipped default is off. Theaudit signal instead comes later, at reconcile: for a non-allowlistedimage, `host-context-controller` logs a would-be denial ("audit mode,@@ -96,7 +96,7 @@ five steps live together.registry) before it can install or[publish](../how-to/publish-plugin-to-registry.md) under its own org.- + _Dev cluster, demo tenant._## Every screen writes a CRD@@ -111,31 +111,32 @@ caveat to the heading: the `GlobalFileSystem` CRD itself is applied out of band(kustomize), and the Global File System screen only manages the brokered gfsresources and grants inside it — it never writes that CR.-| Sidebar label | Route | CRD / control-api resource |-| ------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------- |-| Agent Files | `/agent-files` | `SharedFileSystem` |-| Agent Outputs | `/agent-outputs/recipe-artifacts` | outputs (non-CRD) |-| Agents | `/agents` | `Host` |-| Connectors | `/connectors` | `McpServer` |-| Contexts | `/contexts` | `Context` |-| Cost & Usage | `/cost-and-usage/usage`, `/cost-and-usage/llm-prices`, `/cost-and-usage/token-budgets` | cost (non-CRD) |-| External Channels | `/external-channels` | `CommunicationChannel` |-| Global File System | `/global-file-system` | gfs resources & grants (non-CRD) |-| LLM Models | `/llm-models`, `/llm-models/discovery` | tabbed model allowlist and discovery review (non-CRD) |-| Marketplace | `/marketplace/connectors` | registry (non-CRD) |-| Plugins | `/plugins` | `WorkflowRecipe` |-| Publisher | `/publisher` | publisher (non-CRD) |-| Secrets | `/secrets/llm` | secrets (non-CRD) |-| Settings | `/settings/ui` | settings (non-CRD) |-| Users & Teams | `/users-and-teams/users` | users/teams (non-CRD) |+| Sidebar label | Route | CRD / control-api resource |+| --------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------- |+| Users & Teams | `/users-and-teams/users` | users/teams (non-CRD) |+| Agents | `/agents` | `Host` (plus a private `Context` created per agent) |+| Marketplace | `/marketplace/connectors`; your org's entries and credentials under `/marketplace/org/*` | registry (non-CRD) |+| Installed Connectors | `/connectors` | `McpServer` |+| Installed Plugins | `/plugins` | `WorkflowRecipe` |+| Installed Guardrails | `/guardrails` | `LlmHook` |+| Files | `/agent-files` | `SharedFileSystem` |+| Files › EvenDrive | `/global-file-system` | gfs resources & grants (non-CRD) |+| Files › Agent Outputs | `/agent-outputs/recipe-artifacts` | outputs (non-CRD) |+| External Channels | `/external-channels` | `CommunicationChannel` |+| LLM Models | `/llm-models`, `/llm-models/discovery` | tabbed model allowlist and discovery review (non-CRD) |+| Secrets | `/secrets/llm` | secrets (non-CRD) |+| Cost & Usage | `/cost-and-usage/usage`, `/cost-and-usage/llm-prices`, `/cost-and-usage/token-budgets` | cost (non-CRD) |+| Settings | `/settings/ui` | settings (non-CRD) |++Contexts no longer have their own screen: the agent wizard and connector+installs create and maintain a private `Context` per agent, and old `/contexts`+links redirect to Agents. The former **Publisher** screens now live under+**Marketplace › your org** (`/publisher/*` redirects there). A **Traces**+section (`/traces/*`) exists but is hidden from the sidebar.Secret **values are write-only from the UI**: the Secrets screen lets anadmin create or replace a value, but never displays one back.-The **Publisher** entry appears in the sidebar only when publishing is enabled-for the org (`isPublisherEnabled`, `components/Sidebar/index.tsx`); it is hidden-otherwise.-## How it is wiredThe browser only ever calls same-origin `/control-api/*`. A Next.js routediff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.mdindex da93088c6..e159e90a5 100644--- a/docs/surfaces/desktop-app.md+++ b/docs/surfaces/desktop-app.md@@ -95,11 +95,15 @@ link.## Screens-The app's top-level navigation (`NavItem` in-`desktop-app/ui/src/uiTypes.ts`) covers: chat, agents, mcp-servers, contexts,-teams, workflows, sandbox-ui, files, and settings. Outside that authenticated-shell sit two more states: the auth page (login) and `UnavailablePage`, shown-instead of login when a required backend dependency is unreachable.+The app's top-level routes (`DESKTOP_ROUTES` in+`desktop-app/ui/src/constants/navigation.ts`) are: **Chat** (`chat`),+**Apps** (`sandbox-ui`), **Agents** (`agents`), **Connectors**+(`mcp-servers`), **Plugins** (`workflows`), **EvenDrive** (`files`), a file+`preview` view, and **Settings**. Inside an agent, the workspace has+Connectors, Members, Shared files and Activity sub-routes. Outside that+authenticated shell sit the first-run onboarding flow, the auth page (login),+and `UnavailablePage`, shown instead of login when a required backend+dependency is unreachable.Two screens worth calling out specifically:diff --git a/docs/testing/desktop-headful-journeys.md b/docs/testing/desktop-headful-journeys.mdindex b8e41d69c..dc491fb9b 100644--- a/docs/testing/desktop-headful-journeys.md+++ b/docs/testing/desktop-headful-journeys.md@@ -48,7 +48,7 @@ journey always runs.```bashcd desktop-app# dev Evenfire must be closed (process-wide single-instance lock)-make gcp-dev-pf-desktop # keep control-api/external-rest/rpc-proxy forwarded+make -C .. minikube-pf-desktop # keep control-api/external-rest/rpc-proxy forwardednpm run qa:recorder:navigation # one journeynpm run qa:recorder:all # all 13 specs / 22 testsdiff --git a/docs/testing/e2e-guide.md b/docs/testing/e2e-guide.mdindex b5d582995..16913bc9c 100644--- a/docs/testing/e2e-guide.md+++ b/docs/testing/e2e-guide.md@@ -116,17 +116,11 @@ phase. Direct `npx vitest` runs still require a held port-forward terminal:make minikube-pf-all```-For Control UI / Desktop on a branch-owned profile, the first-hand entry-point `scripts/minikube-profiles/branch.mk` is the-host-side hold. Implementation:-`scripts/minikube-profiles/branch-profile.sh`.-HARD DENY: do not `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.-Profile-owned random ports only (never shared `:3000`/`:8090`).-`make minikube-pf-all-bg` is a gate refresh only; it must not replace-`branch-profile-pf`. Do not start UI PFs from a sandboxed agent shell. Run-the make target on the host. Do not kill this lane's `branch-profile-pf`.-`branch-profile-pf-health` starts PFs then STOPS them on EXIT — do not use-it as the lasting hold.+On a branch-owned profile, use `scripts/minikube-profiles/branch.mk` instead+of the shared `:3000`/`:8090` mapping. It forwards on profile-owned random+ports and must run on the host. `branch-profile-pf` is the lasting hold;+`branch-profile-pf-health` stops its forwards on exit, and+`make minikube-pf-all-bg` (a gate refresh) does not replace either.```bashMINIKUBE_PROFILE=<owned-profile> \@@ -254,13 +248,7 @@ This ensures E2E tests validate the real production flow, not a weakened test-mo## Unit test suites-Every service in the root Makefile's `TEST_SERVICES` list ships its own vitest suite (mcp-host, workflow-recipes, mcp-servers, control-api, host-context-controller, rpc-proxy, desktop-app, and the rest). Exact per-service counts drift as code changes, so this guide does not pin them — count them yourself, or run the suite:--```bash-make test-counts # prints unit-test file and case counts- # (it()/test() cases in *.test.ts, excluding- # node_modules, tests/e2e, and dist)-```+Every service in the root Makefile's `TEST_SERVICES` list ships its own vitest suite (mcp-host, workflow-recipes, mcp-servers, control-api, host-context-controller, rpc-proxy, desktop-app, and the rest). Exact per-service counts drift as code changes, so this guide does not pin them; run the suites to see them.`npm test` inside each service directory is the source of truth for what actually passes.diff --git a/host-context-controller/README.md b/host-context-controller/README.mdindex 60c952037..0f28dce18 100644--- a/host-context-controller/README.md+++ b/host-context-controller/README.md@@ -188,7 +188,7 @@ GET /health{ "status": "ok", "ready": true }```-The server also exposes `GET /` (API information), `GET /ready` (readiness; 503 until the controller has started), `GET /metrics` (Prometheus), and `GET /api/v1/desktop/:hostRef` (desktop status; requires the `CONTEXT_MAPPER_DESKTOP_API_TOKEN` bearer token — the check is skipped when that variable is empty).+The server also exposes `GET /` (API information), `GET /ready` (readiness: `200` once the controller is running and its McpServer, Context and Host watches are synced; otherwise `503` with a `reasons[]` list such as `controller_stopped`, `mcp_watch_unsynced`, `context_watch_unsynced`, `host_watch_unsynced`), `GET /metrics` (Prometheus), and `GET /api/v1/desktop/:hostRef` (desktop status; requires the `CONTEXT_MAPPER_DESKTOP_API_TOKEN` bearer token — the check is skipped when that variable is empty).### Temporary system inventory (PR 2 compatibility)diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.jsonindex 35ab630fe..dabaeca28 100644--- a/host-context-controller/package-lock.json+++ b/host-context-controller/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-host-context-controller",- "version": "0.1.381",+ "version": "0.1.382","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-host-context-controller",- "version": "0.1.381",+ "version": "0.1.382","license": "SEE LICENSE IN LICENSE","dependencies": {"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",diff --git a/host-context-controller/package.json b/host-context-controller/package.jsonindex 6a9df9017..4f0e9abfe 100644--- a/host-context-controller/package.json+++ b/host-context-controller/package.json@@ -1,6 +1,6 @@{"name": "clerum-host-context-controller",- "version": "0.1.381",+ "version": "0.1.382","description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API","main": "dist/main.js","engines": {diff --git a/packages/workflow-sdk/README.md b/packages/workflow-sdk/README.mdindex b818b2fd0..83cd3483c 100644--- a/packages/workflow-sdk/README.md+++ b/packages/workflow-sdk/README.md@@ -82,7 +82,7 @@ stubbed in — replace `runStep` with your own logic).```ts// coordinator.ts-import { WorkflowSDK, emitLog, type StepSpec } from '@clerum/workflow-sdk'+import { type StepSpec, WorkflowSDK, emitLog } from '@clerum/workflow-sdk'async function runStep(step: StepSpec): Promise<unknown> {// Your deterministic business logic, or delegate agentic work to@@ -158,28 +158,28 @@ if (result.status === 'failed') {## Public API reference-| Export | Kind | Purpose |-| --- | --- | --- |-| `WorkflowSDK` | class | Top-level façade; `static fromEnvironment()` builds and wires everything. |-| `WorkflowSDK.fromEnvironment()` | static method | `Promise<WorkflowSDK>` — the single init call. |-| `sdk.config` (`ConfigLoader`) | class | Loads config from env; `getConfig()`, `getSpec()`. |-| `sdk.coordinator` (`StepCoordinator`) | class | `resolveOrder()`, `injectSignal()`, `runWorkflow()`. |-| `sdk.status` (`StatusReporter`) | class | `reportStepStatus()`, `reportWorkflowStatus()`, `getWorkflowStatus()`. |-| `sdk.signals` (`SignalPoller`) | class | `pollSignals()`, `pushSignal()`, `hasSignal()`, `consumeSignal()`, `stop()`. |-| `sdk.mcpHost` / `requireMcpHost()` (`McpHostClient`) | class | `executeAgentStep()`, `healthCheck()`. |-| `updatePhase()` / `updateStepState()` / `shutdown()` | methods | Mirror local REST state; graceful teardown. |-| `renderPrompt()` | function | Interpolates `{{...}}` placeholders in a prompt template. |-| `loadSoul()` | function | Reads a `SOUL.md` artifact from `/etc/workflow/souls` (path-traversal guarded). |-| `requestModelInjection()` | function | POSTs a `{stepId, provider, model}` model binding to WRC. |-| `createFileRuntimeTokenProvider()` / `createStaticRuntimeTokenProvider()` / `requireRuntimeToken()` | functions | Build / resolve runtime token providers. |-| `withRetry()` / `computeBackoff()` | functions | Retry helper and exponential backoff (capped at 300s). |-| `emitLog()` / `initLogger()` | functions | Structured JSON logging to stdout. |-| `createServer()` / `start()` / `stop()` / `safeEqual()` | functions | REST server helpers (health/status/signal routes; constant-time compare). |-| `WorkflowSDKInitError` / `CycleDetectedError` / `McpHostNotConfiguredError` | error classes | Init, DAG-cycle, and unconfigured-mcp-host failures. |-| `RegistryClient` and registry types | interfaces/types | Registry connection contract (defined in this package). |-| Config/spec types | types | `WorkflowConfig`, `WorkflowRecipeSpec`, `StepSpec`, `AgentSpec`, `ToolScope`, `PromptSpec`, `WorkflowPhase`, `StepPhase`, `Signal`. |-| mcp-host types | types | `AgentStepRequest`, `AgentStepResult`, `StepMcpServerRef`, `AllowedToolsConfig`. |-| Misc types | types | `StepContext`, `StepExecutor`, `WorkflowStateRef`, `RetryOptions`, `PromptContext`, `SignalCallback`, `RuntimeTokenProvider`. |+| Export | Kind | Purpose |+| --------------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |+| `WorkflowSDK` | class | Top-level façade; `static fromEnvironment()` builds and wires everything. |+| `WorkflowSDK.fromEnvironment()` | static method | `Promise<WorkflowSDK>` — the single init call. |+| `sdk.config` (`ConfigLoader`) | class | Loads config from env; `getConfig()`, `getSpec()`. |+| `sdk.coordinator` (`StepCoordinator`) | class | `resolveOrder()`, `injectSignal()`, `runWorkflow()`. |+| `sdk.status` (`StatusReporter`) | class | `reportStepStatus()`, `reportWorkflowStatus()`, `getWorkflowStatus()`. |+| `sdk.signals` (`SignalPoller`) | class | `pollSignals()`, `pushSignal()`, `hasSignal()`, `consumeSignal()`, `stop()`. |+| `sdk.mcpHost` / `requireMcpHost()` (`McpHostClient`) | class | `executeAgentStep()`, `healthCheck()`. |+| `updatePhase()` / `updateStepState()` / `shutdown()` | methods | Mirror local REST state; graceful teardown. |+| `renderPrompt()` | function | Interpolates `{{...}}` placeholders in a prompt template. |+| `loadSoul()` | function | Reads a `SOUL.md` artifact from `/etc/workflow/souls` (path-traversal guarded). |+| `requestModelInjection()` | function | POSTs a `{stepId, provider, model}` model binding to WRC. |+| `createFileRuntimeTokenProvider()` / `createStaticRuntimeTokenProvider()` / `requireRuntimeToken()` | functions | Build / resolve runtime token providers. |+| `withRetry()` / `computeBackoff()` | functions | Retry helper and exponential backoff (capped at 300s). |+| `emitLog()` / `initLogger()` | functions | Structured JSON logging to stdout. |+| `createServer()` / `start()` / `stop()` / `safeEqual()` | functions | REST server helpers (health/status/signal routes; constant-time compare). |+| `WorkflowSDKInitError` / `CycleDetectedError` / `McpHostNotConfiguredError` | error classes | Init, DAG-cycle, and unconfigured-mcp-host failures. |+| `RegistryClient` and registry types | interfaces/types | Registry connection contract (defined in this package). |+| Config/spec types | types | `WorkflowConfig`, `WorkflowRecipeSpec`, `StepSpec`, `AgentSpec`, `ToolScope`, `PromptSpec`, `WorkflowPhase`, `StepPhase`, `Signal`. |+| mcp-host types | types | `AgentStepRequest`, `AgentStepResult`, `StepMcpServerRef`, `AllowedToolsConfig`. |+| Misc types | types | `StepContext`, `StepExecutor`, `WorkflowStateRef`, `RetryOptions`, `PromptContext`, `SignalCallback`, `RuntimeTokenProvider`. |## Building a coordinator image@@ -248,9 +248,11 @@ Build and ship as if policy is strict:## Full guide-For the complete walkthrough — build/ship details, the snippet-vs-agentic split, capability-gating, and the end-to-end example — see `docs/features/custom-coordinator-*.md` in this-repository.+For recipe-side configuration see the+[WorkflowRecipe CRD reference](../../docs/crds/workflowrecipe.md) and the+[WorkflowRecipes operations guide](../../docs/deploy/workflow-recipes-guide.md); the gates a+custom coordinator image must pass are in+[Custom coordinator E2E gates](../../docs/testing/custom-coordinator-e2e-gates.md).## Licensediff --git a/packages/workflow-sdk/package-lock.json b/packages/workflow-sdk/package-lock.jsonindex 489bc3722..f976b5ecd 100644--- a/packages/workflow-sdk/package-lock.json+++ b/packages/workflow-sdk/package-lock.json@@ -1,12 +1,12 @@{"name": "@clerum/workflow-sdk",- "version": "1.0.31-beta.0",+ "version": "1.0.32-beta.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@clerum/workflow-sdk",- "version": "1.0.31-beta.0",+ "version": "1.0.32-beta.0","license": "SEE LICENSE IN LICENSE","dependencies": {"@clerum/workflow-runtime-core": "file:../workflow-runtime-core"diff --git a/packages/workflow-sdk/package.json b/packages/workflow-sdk/package.jsonindex 33b9734a6..db0c37e1c 100644--- a/packages/workflow-sdk/package.json+++ b/packages/workflow-sdk/package.json@@ -1,6 +1,6 @@{"name": "@clerum/workflow-sdk",- "version": "1.0.31-beta.0",+ "version": "1.0.32-beta.0","description": "Clerum Workflow SDK — TypeScript library for workflow coordinator Pods","main": "dist/index.js","types": "dist/index.d.ts",diff --git a/workflow-recipes/README.md b/workflow-recipes/README.mdindex 05652d52a..788ff5326 100644--- a/workflow-recipes/README.md+++ b/workflow-recipes/README.md@@ -112,7 +112,7 @@ Test files are co-located with source in `src/` (e.g., `reconciler/resourceBuild## Further Reading- [WorkflowRecipe CRD reference](../docs/crds/workflowrecipe.md)-- [Workflow Recipes feature hub](../docs/features/workflow-recipes.md)+- [WorkflowRecipes operations guide](../docs/deploy/workflow-recipes-guide.md)## Source Layoutdiff --git a/workflow-recipes/package-lock.json b/workflow-recipes/package-lock.jsonindex 7c554403c..03766c6f1 100644--- a/workflow-recipes/package-lock.json+++ b/workflow-recipes/package-lock.json@@ -1,12 +1,12 @@{"name": "workload-recipes-controller",- "version": "0.1.470",+ "version": "0.1.471","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "workload-recipes-controller",- "version": "0.1.470",+ "version": "0.1.471","license": "SEE LICENSE IN LICENSE","dependencies": {"@aws-sdk/client-s3": "^3.1009.0",diff --git a/workflow-recipes/package.json b/workflow-recipes/package.jsonindex 85b1a9380..7280a3569 100644--- a/workflow-recipes/package.json+++ b/workflow-recipes/package.json@@ -1,6 +1,6 @@{"name": "workload-recipes-controller",- "version": "0.1.470",+ "version": "0.1.471","description": "Workload Recipes Controller (WRC) - WorkloadRecipe lifecycle management and MCP server interface","main": "dist/main.js","engines": {