Skip to content

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.example
index 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_plan
BAILIAN_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=false
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 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 reference
page each under [docs/crds/](docs/crds/), shipped in
[charts/clerum-crds](charts/clerum-crds/).
```mermaid
flowchart 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] --> capi
pui[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 a
model only together with `CLERUM_MODEL_PROVIDER`; minikube setup refuses it
alone and defaults to `openai/gpt-5.4-mini` when no key is set. See
[mcp-host/README.md](mcp-host/README.md) and
diff --git a/README.md b/README.md
index 33104dbd4..375be659b 100644
--- a/README.md
+++ b/README.md
@@ -78,7 +78,7 @@ Evenfire is a complete platform for running LLM agents that take
Agents 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 to
local models. Keys live in a Kubernetes Secret you create (dev mode: a single
environment 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 testing
Each 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 and
the 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.md
index 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.
## Modes
diff --git a/channel-reader/package-lock.json b/channel-reader/package-lock.json
index 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.json
index 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.yaml
index d71d64ce9..12a6703f9 100644
--- a/charts/clerum-crds/Chart.yaml
+++ b/charts/clerum-crds/Chart.yaml
@@ -1,6 +1,6 @@
apiVersion: v2
name: 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: application
version: 0.8.0
appVersion: "1"
diff --git a/control-ui/README.md b/control-ui/README.md
index 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 Features
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 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.json
index 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.md
index 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.md
index 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.
```bash
helm install clerum-crds ./charts/clerum-crds
diff --git a/docs/concepts/open-core-and-hosted.md b/docs/concepts/open-core-and-hosted.md
index 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-workload
security contexts, the service-to-service JWT chain, and human-in-the-loop
approvals.
diff --git a/docs/crds/README.md b/docs/crds/README.md
index 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--> WorkflowRecipePolicy
GlobalFileSystem (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.md
index ddabdc902..a40718054 100644
--- a/docs/crds/communicationchannel.md
+++ b/docs/crds/communicationchannel.md
@@ -9,7 +9,7 @@
## Purpose
CommunicationChannel 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 service
watches these CRDs, polls each configured channel for new messages from
authorized 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 the
CRD 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.
## Example
diff --git a/docs/crds/host.md b/docs/crds/host.md
index 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.md
new file mode 100644
index 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.md
index 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 Columns
diff --git a/docs/deploy/llm-providers.md b/docs/deploy/llm-providers.md
index 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 how
the 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 the
shared `@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 pinning
either is rejected at admission. The workflow `configure` transport carries a
single credential string, which can deliver neither Bedrock's key pair nor
Azure'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 and
the `clerum-model-secret-mapping` caveat.
diff --git a/docs/deploy/minikube.md b/docs/deploy/minikube.md
index 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 profiles
may 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-forwards
itself, 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.
```bash
make minikube-pre-gate-sync GATE=<gate-name> ARGS="--force-cluster-sync --skip-port-forwards"
@@ -160,18 +161,15 @@ npm run ui
open 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.
```bash
MINIKUBE_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:
```bash
MINIKUBE_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.md
index 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 layouts
diff --git a/docs/faq.md b/docs/faq.md
index 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.md
index 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 evenfire
cp .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 safe
make minikube-status # wait for every deployment READY
```
diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
index 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 migration
overlay; 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:
```bash
EXT=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 steps
diff --git a/docs/get-started/registry-quickstart.md b/docs/get-started/registry-quickstart.md
index 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. Push
it before publishing the entry that points at it. Recipes have no image and skip
this step.
-**Publisher → Docker credentials** (`/publisher/credentials`) generates a push
+**Marketplace → _your org_ → Credentials** (`/marketplace/org/credentials`,
+formerly Publisher → Docker credentials) generates a push
credential 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.md
index 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` resource
as Option B, through a guided form (identity, transport/runtime, secrets) plus
an `EgressEditor` step for the egress policy: closed-by-default, with
private, 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.md
index 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. Push
it 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, a
downloadable `dockerconfigjson` for CI, and your exact push coordinate. A key
minted at **Marketplace → API keys** works identically — both are `efrk_` org
diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.md
index be556c39f..aed32259a 100644
--- a/docs/llm-providers/README.md
+++ b/docs/llm-providers/README.md
@@ -22,7 +22,7 @@ by (potentially) three different people.
```mermaid
flowchart LR
subgraph 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"]
end
subgraph 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 workflow
runtime, the host controller and the Control UI.
@@ -111,12 +111,31 @@ Azure is OpenAI-shaped but has no fixed base URL (per-resource endpoint), it
authenticates 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.txt
index 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.md
diff --git a/docs/meta/claims-guardrails.md b/docs/meta/claims-guardrails.md
index 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.md
index 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 all
five 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.
![Control UI usage dashboard: stacked-area token usage over time, grouped by agent](../assets/control-ui-usage-dashboard.webp)
_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 a
progress bar against the limit. Budgets are cost control and are **not** a
security 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 an
operator turns on enforcement, since the shipped default is off. The
audit signal instead comes later, at reconcile: for a non-allowlisted
image, `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.
- ![Control UI registry catalog at /registry showing trust levels and the install flow](../assets/control-ui-registry-install.webp)
+ ![Control UI marketplace catalog showing trust levels and the install flow (screenshot predates the current sidebar)](../assets/control-ui-registry-install.webp)
_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 gfs
resources 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 an
admin 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 wired
The browser only ever calls same-origin `/control-api/*`. A Next.js route
diff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.md
index 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.md
index b8e41d69c..dc491fb9b 100644
--- a/docs/testing/desktop-headful-journeys.md
+++ b/docs/testing/desktop-headful-journeys.md
@@ -48,7 +48,7 @@ journey always runs.
```bash
cd 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 forwarded
npm run qa:recorder:navigation # one journey
npm run qa:recorder:all # all 13 specs / 22 tests
diff --git a/docs/testing/e2e-guide.md b/docs/testing/e2e-guide.md
index 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.
```bash
MINIKUBE_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.md
index 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.json
index 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.json
index 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.md
index 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).
## License
diff --git a/packages/workflow-sdk/package-lock.json b/packages/workflow-sdk/package-lock.json
index 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.json
index 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.md
index 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 Layout
diff --git a/workflow-recipes/package-lock.json b/workflow-recipes/package-lock.json
index 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.json
index 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": {