Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: address second-round review on operate and contribute docs
Jose Gabriel Ramirez Encinasca6350d7ae7b
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a2929173f..abaddd658 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -152,8 +152,10 @@ for private reporting.## CLA-This project requires a signed Contributor License Agreement. Contributions-may be used in the project's commercial / managed editions.+The project plans to require a signed Contributor License Agreement, and+contributions may be used in the project's commercial / managed editions.-See [CLA.md](CLA.md) for the agreement and how to accept it (it is a draft,-pending legal review).+The agreement in [CLA.md](CLA.md) is a draft pending legal review and is not+open for signing yet: no CLA bot runs on pull requests and there is no+signature record. You cannot sign it today. Once it is final, CLA.md will say+how to accept it.diff --git a/desktop-app/README.md b/desktop-app/README.mdindex 58b07dfd9..8875295ba 100644--- a/desktop-app/README.md+++ b/desktop-app/README.md@@ -68,7 +68,7 @@ The app now auto-populates default RPC `hostRefs` from authorized agent names re- `EXTERNAL_REST_API_BASE_URL` (default: `http://127.0.0.1:8091`)- `RPC_PROXY_BASE_URL` (default: `http://127.0.0.1:8094`)-- `MEMBER_REGISTRATION_SERVICE_BASE_URL` (no working default — falls back to the placeholder `https://example.com`, so set it explicitly; locally this is usually `http://127.0.0.1:8092`)+- `MEMBER_REGISTRATION_SERVICE_BASE_URL` (default: `https://registration.evenfire.ai`, the hosted service — set it when you run your own; locally this is usually `http://127.0.0.1:8092`)- `REQUEST_TIMEOUT_MS` (default: `60000`)## Architecture@@ -231,16 +231,16 @@ npm run test:e2e:all # Phase 1 + Phase 2### Environment Configuration (`.env.e2e`)-| Variable | Default | Description |-| -------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |-| `EXTERNAL_REST_API_BASE_URL` | `http://localhost:8091` | external-rest-api URL |-| `RPC_PROXY_BASE_URL` | `http://localhost:8094` | rpc-proxy URL |-| `MEMBER_REGISTRATION_SERVICE_BASE_URL` | `https://example.com` (placeholder — set it) | member-registration-service activation URL. There is no working default: unset, it silently points at `example.com`. |-| `E2E_DEV_LOGIN_EMAIL` | `[email protected]` | Test-only login email (must have agent access) |-| `E2E_DEV_LOGIN_EMAIL_2` | `[email protected]` | Second user, required by the cross-device session tests |-| `E2E_DEV_LOGIN_NAME` | `Test User` | Test-only login display name |-| `E2E_HOST_REF` | `chatllm` | Agent hostRef to test against |-| `E2E_ALLOW_DEV_PORT_FORWARD` | unset (off) | Set to `1`/`true` to let the Playwright global-setup guard accept localhost port-forward URLs |+| Variable | Default | Description |+| -------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |+| `EXTERNAL_REST_API_BASE_URL` | `http://localhost:8091` | external-rest-api URL |+| `RPC_PROXY_BASE_URL` | `http://localhost:8094` | rpc-proxy URL |+| `MEMBER_REGISTRATION_SERVICE_BASE_URL` | `https://registration.evenfire.ai` | member-registration-service activation URL. Unset or empty, it points at the hosted evenfire service; set it for your own. |+| `E2E_DEV_LOGIN_EMAIL` | `[email protected]` | Test-only login email (must have agent access) |+| `E2E_DEV_LOGIN_EMAIL_2` | `[email protected]` | Second user, required by the cross-device session tests |+| `E2E_DEV_LOGIN_NAME` | `Test User` | Test-only login display name |+| `E2E_HOST_REF` | `chatllm` | Agent hostRef to test against |+| `E2E_ALLOW_DEV_PORT_FORWARD` | unset (off) | Set to `1`/`true` to let the Playwright global-setup guard accept localhost port-forward URLs |## Notesdiff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex d887f134b..42e83fc36 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -533,9 +533,11 @@ a `Set<string>` so an unchanged hostRef triggers exactly one reconcile.**RBAC:** HCC's `host-context-controller-channels-runtime` Role grants`get/list/watch` on `communicationchannels.clerum.io` in the `channels`-namespace. **Applied out-of-band** with-[`deploy/scripts/bootstrap-rbac.sh`](../../deploy/scripts/bootstrap-rbac.sh),-because a deploy service account should not be able to grant RBAC.+namespace. It lives in `deploy/base/channels/rbac.yaml`, so the overlay apply+creates it. Where the CD identity is not allowed to patch Roles, apply it once+out of band with+[`deploy/scripts/bootstrap-rbac.sh`](../../deploy/scripts/bootstrap-rbac.sh)+and an admin kubeconfig.---diff --git a/docs/deploy/minikube.md b/docs/deploy/minikube.mdindex 74c7c889a..bdc35599c 100644--- a/docs/deploy/minikube.md+++ b/docs/deploy/minikube.md@@ -98,11 +98,17 @@ otherwise surfaces at the migration gate as`control_api_runtime relation privileges differ from the explicit access contract`.On a fresh cluster (no volume, no reset state) there is nothing to delete andsetup continues. On a cluster that already has the volume, the reset refuses to-run unless you name the exact volume it may delete:+run unless you name the exact volume it may delete. This deletes all data in+that volume, so check the UID yourself before passing it — do not read it inline:```bash-CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane \- get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" make minikube-setup+# 1. Inspect the volume you are about to delete and note its UID+kubectl --context clerum-test -n control-plane get pvc control-postgres-data \+ -o custom-columns=NAME:.metadata.name,UID:.metadata.uid,CREATED:.metadata.creationTimestamp++# 2. Paste that UID as a literal value+CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> make minikube-setup+# or keep the data instead:make minikube-setup REUSE_DB=true```@@ -678,10 +684,14 @@ make minikube-pf-desktop # Re-establish port forwards## Restart With Database Wipe```bash-# Deletes the postgres PVC, recreates it, restarts control-api.-# Name the exact PVC it may delete (or `none` if there is none):-CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane \- get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" make minikube-db-reset+# Destructive: deletes the postgres PVC and all its data, recreates it,+# restarts control-api.+# 1. Inspect the PVC it will delete and note its UID:+kubectl --context clerum-test -n control-plane get pvc control-postgres-data \+ -o custom-columns=NAME:.metadata.name,UID:.metadata.uid,CREATED:.metadata.creationTimestamp++# 2. Paste that UID as a literal value (or `none` if there is no PVC):+CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> make minikube-db-reset# → Allows re-running the initial admin setup in Control UI```@@ -1137,11 +1147,18 @@ re-applies the manifests.### Postgres CrashLoopBackOff (WAL corruption)-Common after cold starts. The setup script detects and auto-fixes this, but you can also force a DB rebuild:+Common after cold starts. The setup script detects an invalid checkpoint and+stops; it does not repair the volume, because automatic destructive recovery is+disabled. Fix it by rebuilding the DB, which deletes all data in the+`control-postgres-data` volume:```bash-CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane \- get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" \+# 1. Inspect the PVC you are about to delete and note its UID+kubectl --context clerum-test -n control-plane get pvc control-postgres-data \+ -o custom-columns=NAME:.metadata.name,UID:.metadata.uid,CREATED:.metadata.creationTimestamp++# 2. Paste that UID as a literal value+CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> \make minikube-setup ARGS="--reset-db --skip-build"```diff --git a/docs/deploy/production.md b/docs/deploy/production.mdindex 7cdb5620a..fcc215a41 100644--- a/docs/deploy/production.md+++ b/docs/deploy/production.md@@ -193,7 +193,7 @@ of copying minikube's choices.| Setting | Base value | What to do || ----------------------------------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| API server `cidr` in `allow-k8s-api-egress-control-plane`, `-mcp-host`, `-channels` | `10.109.0.1/32` | Patch to your API server endpoint IP (`kubectl get endpoints kubernetes -n default`). The minikube template [`k8s-api-ip.yaml.template`](../../deploy/overlays/minikube/patches/k8s-api-ip.yaml.template) explains why this is an `ipBlock`. |+| API server `cidr` in `allow-k8s-api-egress-control-plane`, `-mcp-host`, `-channels` | `10.109.0.1/32` | Patch to your API server endpoint IP (`kubectl --context "$KCTX" get endpoints kubernetes -n default`). The minikube template [`k8s-api-ip.yaml.template`](../../deploy/overlays/minikube/patches/k8s-api-ip.yaml.template) explains why this is an `ipBlock`. || `CONTEXT_MAPPER_HOST_WORKSPACE_STORAGE_CLASS` (HCC) | `do-block-storage-retain` | Set to a block StorageClass in your cluster. || `storageClassName` on `control-postgres-data` and `clerum-workflow-output` | unset | Patch, or rely on your default StorageClass. || `CONTEXT_MAPPER_HOST_IMAGE_PULL_SECRET` (HCC) | `clerum` | Name your pull Secret in `mcp-host`, or set `""` if none is needed (minikube sets `""`). |@@ -212,19 +212,28 @@ scripts under [`deploy/scripts`](../../deploy/scripts) take a `CONTEXT` and arethe ones to use elsewhere. Several of them also require `ALLOWED_CONTEXTS`, anexact allowlist of kube-contexts they may touch.+Pick one kube-context for the whole install and pass it explicitly to every+command; do not rely on your kubeconfig's current context. The examples use+`KCTX`, and the same value goes into each script's `CONTEXT`:++```bash+KCTX=<your-context>+kubectl --context "$KCTX" cluster-info # confirm this is the cluster you mean+```+1. **CRDs.**```bash- helm install clerum-crds ./charts/clerum-crds+ helm --kube-context "$KCTX" install clerum-crds ./charts/clerum-crds# After chart upgrades, re-apply the CRD YAML (Helm 3 does not upgrade crds/):- kubectl apply -f ./charts/clerum-crds/crds/+ kubectl --context "$KCTX" apply -f ./charts/clerum-crds/crds/```2. **Namespaces.** The key scripts write into existing namespaces, so createthem first:```bash- kubectl apply -f deploy/base/namespaces.yaml+ kubectl --context "$KCTX" apply -f deploy/base/namespaces.yaml```Your overlay apply (step 4) adds the deny-all baselines, Roles and@@ -234,7 +243,7 @@ exact allowlist of kube-contexts they may touch.3. **Keys and secrets.** Run[`deploy/scripts/gen-jwt-keys.sh`](../../deploy/scripts/gen-jwt-keys.sh)- with `CONTEXT=<your-context>`. It creates the four RSA-4096 key pairs+ with `CONTEXT="$KCTX"`. It creates the four RSA-4096 key pairs(session, rpc, admin, wrc), the OAuth state HMAC and encryption key, theControl UI CSRF secret, the prompt-history encryption key, and theSecrets and public-key ConfigMaps that carry them. Then run@@ -266,7 +275,7 @@ exact allowlist of kube-contexts they may touch.- Secrets for LLM keys and channel credentials are separate; see[LLM providers (operator guide)](llm-providers.md).-4. **Apply your overlay** (`kubectl apply -k <your-overlay>`), with the+4. **Apply your overlay** (`kubectl --context "$KCTX" apply -k <your-overlay>`), with theghcr component pinned to one release tag.5. **Database migrations and roles.** Run@@ -275,8 +284,11 @@ exact allowlist of kube-contexts they may touch.[`provision-control-api-runtime-roles.sh`](../../deploy/scripts/provision-control-api-runtime-roles.sh).If you use the Global File System, follow[GFS permission-store credential lifecycle](gfs-permission-store.md)- (`provision-gfs-db.sh`, `provision-gfs-runtime.sh`; production contexts- need `--allow-prod`).+ (`provision-gfs-db.sh`, `provision-gfs-runtime.sh`).+ `provision-gfs-runtime.sh` refuses a non-dev context unless it is listed in+ `ALLOWED_CONTEXTS` or you pass `--allow-prod`. `provision-gfs-db.sh` has no+ such guard: it runs against whatever `CONTEXT` you give it, so check that+ value before you run it.6. **First admin.** control-api creates the bootstrap admin from`CONTROL_API_ADMIN_BOOTSTRAP_USERNAME`, `CONTROL_API_ADMIN_BOOTSTRAP_EMAIL`diff --git a/docs/deploy/releases-and-upgrades.md b/docs/deploy/releases-and-upgrades.mdindex 738505b67..b7f8e8194 100644--- a/docs/deploy/releases-and-upgrades.md+++ b/docs/deploy/releases-and-upgrades.md@@ -42,8 +42,10 @@ for what the hook does to your commits.## How a release is made-Images are built once, on the `dev` branch. A release never rebuilds them. It-copies the exact images that `dev` already built to the release tag.+Images are built by `build-publish.yml`: automatically on every push to `dev`,+or when a maintainer runs that workflow by hand (`workflow_dispatch`, optionally+with `build_all`). A release never rebuilds them. It copies images that were+already built to the release tag.```textpush to dev ──► build-publish.yml ──► ghcr.io/evenfire-ai/<image>:sha-<7> and :latest@@ -206,7 +208,8 @@ Read the notes for every release you skip over, not only the target release.2. **Apply the CRDs first.**```bash- kubectl apply -f ./charts/clerum-crds/crds/+ KCTX=<your-context> # the cluster you are upgrading; never rely on the current context+ kubectl --context "$KCTX" apply -f ./charts/clerum-crds/crds/````helm upgrade` does not update files in a chart's `crds/` directory, so youdiff --git a/docs/faq.md b/docs/faq.mdindex 4fcbdbc6e..363e664af 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -72,9 +72,11 @@ allowlist it in the Context: [Add an MCP server](how-to/add-mcp-server.md).### Telegram bot ignores me-Your numeric user id must be allowlisted-(`CLERUM_TELEGRAM_USER_ID` in `.env`, or CRD `userIds`). Usernames alone are-not enough. See [Connect Telegram](how-to/connect-telegram.md).+The sender must be allowed on the channel: the access list of a channel+created in the Control UI's External Channels page, or the numeric Telegram+user ids in CRD `userIds` (usernames alone are not enough). On minikube,+`.env` Telegram variables do not configure the channel; create it in the+Control UI. See [Connect Telegram](how-to/connect-telegram.md).## Platformdiff --git a/docs/get-started/dev-mode.md b/docs/get-started/dev-mode.mdindex da7861cc5..5d0a4d6f2 100644--- a/docs/get-started/dev-mode.md+++ b/docs/get-started/dev-mode.md@@ -17,6 +17,13 @@ native tool, guardrails or an MCP server.You need Node.js 24 and an API key for one[supported provider](../llm-providers/README.md).+mcp-host has no setting to bind only to localhost, and with+`CLERUM_ENABLE_AUTH=false` any client that reaches port `8080` can send the+edge headers, approve its own shell commands and run them. Before you start it+this way, make sure no other machine can reach that port (a host firewall rule,+or a network you control). Otherwise use [Run it in Docker](#run-it-in-docker),+which publishes the port on `127.0.0.1` only.+```bashcd mcp-hostnpm ci@@ -144,4 +151,5 @@ docker run --rm -p 127.0.0.1:8080:8080 \The root `docker-compose.yml` declares the same dev-mode settings, plus anoptional channel-reader under the `telegram` profile. Its mcp-host build doesnot work as written: it uses `context: ./mcp-host`, so the Dockerfile cannot-find `packages/`. Use the commands above instead.+find `packages/`. It also publishes `8080:8080` on all interfaces with auth+off. Use the commands above instead.diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex c2fd5ae0e..3e188f533 100644--- a/docs/get-started/quickstart.md+++ b/docs/get-started/quickstart.md@@ -79,7 +79,7 @@ CRDs → JWT signing keys → secrets from `.env` → service images pulled from`ghcr.io/evenfire-ai` → deploy → readiness wait with auto-recovery → seed →verify.-**You do not build images.** The 23 service images are published for+**You do not build images.** The 25 service images are published for`linux/amd64` and `linux/arm64`, so an Apple Silicon Mac pulls a native imageinstead of compiling anything. MCP servers are not loaded into the cluster atall — they are installed on demand from the evenfire registry.@@ -184,10 +184,12 @@ curl -s -X POST "$RPC/api/v1/rpc/hosts/$HOST/approvals/approve" \## 5. Optional: chat from Telegram-1. Create a bot with [@BotFather](https://t.me/BotFather); get your numeric- user id (e.g. via `@userinfobot`).-2. Set `CLERUM_TELEGRAM_BOT_TOKEN` and `CLERUM_TELEGRAM_USER_ID` in `.env`.-3. Re-run `make minikube-setup REUSE_DB=true ARGS="--skip-build"` and message your bot.+1. Create a bot with [@BotFather](https://t.me/BotFather) and copy its token.+2. In the Control UI, open **External Channels** → **Create**, pick your Host+ and the Telegram provider, enter the bot handle and token, and grant access+ to your user.+3. Message your bot. (Setting the Telegram variables in `.env` and re-running+ setup does not enable Telegram on minikube.)Approval requests arrive on Telegram with inline **Approve / Deny** buttons.Details: [Connect Telegram](../how-to/connect-telegram.md).@@ -199,7 +201,7 @@ Details: [Connect Telegram](../how-to/connect-telegram.md).| Agent never replies | No real LLM key in `.env`; with several keys, set `CLERUM_MODEL_PROVIDER` explicitly (see step 1) || `minikube start` fails on memory | Raise Docker Desktop to ≥10 GB RAM / 6 CPUs — or, if you can't spare it, `MINIKUBE_MEMORY=9216 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 | `CONTROL_DB_RESET_PVC_UID="$(kubectl --context clerum-test -n control-plane get pvc control-postgres-data -o jsonpath='{.metadata.uid}')" make minikube-setup ARGS="--reset-db --skip-build"` |+| postgres CrashLoopBackOff after cold start | Rebuild the DB — this deletes all its data. First print and check the volume's UID: `kubectl --context clerum-test -n control-plane get pvc control-postgres-data -o jsonpath='{.metadata.uid}'`. Then paste it: `CONTROL_DB_RESET_PVC_UID=<uid-from-previous-step> make minikube-setup ARGS="--reset-db --skip-build"` ([details](../deploy/minikube.md#postgres-crashloopbackoff-wal-corruption)) || Port-forwards die | Re-run `make minikube-pf-all` (it holds them open; Ctrl-C stops) |## Next stepsdiff --git a/docs/how-to/connect-telegram.md b/docs/how-to/connect-telegram.mdindex 8cd8f753c..2d4e0cfcd 100644--- a/docs/how-to/connect-telegram.md+++ b/docs/how-to/connect-telegram.md@@ -6,21 +6,18 @@ Reach an evenfire agent from Telegram.1. Complete the [Quickstart](../get-started/quickstart.md) so the platform runs.2. Create a bot via [@BotFather](https://t.me/BotFather); copy the bot token.-3. Find your numeric Telegram **user id** (not username), e.g. via `@userinfobot`.-4. Set in `.env`:--```bash-CLERUM_TELEGRAM_BOT_TOKEN=<bot-token>-CLERUM_TELEGRAM_USER_ID=<your-numeric-user-id>-```--5. Re-apply secrets and redeploy:--```bash-make minikube-setup REUSE_DB=true ARGS="--skip-build"-```--6. Message the bot from the allowed user account.+3. In the Control UI, open **External Channels** (`/external-channels`) →+ **Create**, pick your Host and the Telegram provider, enter the bot handle,+ paste the bot token as the write-only credential, and grant access to the+ users who may use it. See+ [In the Control UI](#in-the-control-ui) below.+4. Message the bot from the allowed user account.++Putting `CLERUM_TELEGRAM_BOT_TOKEN` / `CLERUM_TELEGRAM_USER_ID` in `.env` and+re-running `make minikube-setup` does **not** enable Telegram: setup no longer+writes channel credentials from `.env`, and the default minikube+`CommunicationChannel` declares no Telegram entry. channel-reader reads those+variables only in its standalone dev mode.`channel-reader` polls Telegram and forwards allowed senders to `mcp-host`.Users not in the allowlist are dropped.@@ -58,7 +55,7 @@ API server rejects the resource without them.## In the Control UI-External Channels → `/communication-channels` → **Create** builds the same+External Channels → `/external-channels` → **Create** builds the same`CommunicationChannel` resource as the CRD path above: pick the host, theTelegram provider, add the bot token as a write-only credential, and grantaccess to specific users/teams — writing `spec.access.users` /diff --git a/docs/operations/monitoring.md b/docs/operations/monitoring.mdindex 1c8efd3a9..d600f4081 100644--- a/docs/operations/monitoring.md+++ b/docs/operations/monitoring.md@@ -53,35 +53,51 @@ clusters want. Override both at install time.The dashboard ConfigMap must exist before Grafana starts, because`grafana/values.yaml` mounts the `grafana-dashboards` ConfigMap.+Every command below names the target cluster explicitly. Set `KCTX` to your+minikube profile (`clerum-test` by default) and check it before you run+anything:+```bash+KCTX=clerum-test+kubectl --context "$KCTX" get nodes # confirm this is the cluster you mean+# Helm repo + monitoring namespace-make -C monitoring setup+helm repo add grafana https://grafana.github.io/helm-charts+helm repo update+kubectl --context "$KCTX" apply -f monitoring/namespace.yaml# Dashboard ConfigMap (before Grafana)-kubectl create configmap grafana-dashboards \+kubectl --context "$KCTX" create configmap grafana-dashboards \--from-file=monitoring/dashboards/loki-grafana-dashboard.json \-n monitoring# Loki + Promtail, with a minikube storage class and a smaller volume-helm install loki grafana/loki-stack --version 2.9.10 -n monitoring \+helm --kube-context "$KCTX" install loki grafana/loki-stack --version 2.9.10 \+ -n monitoring \-f monitoring/loki/values.yaml \--set loki.persistence.storageClassName=standard \--set loki.persistence.size=10Gi# Grafana-helm install grafana grafana/grafana -n monitoring \+helm --kube-context "$KCTX" install grafana grafana/grafana -n monitoring \-f monitoring/grafana/values.yaml \--set persistence.storageClassName=standard-make -C monitoring status+kubectl --context "$KCTX" get pods,daemonset,pvc -n monitoring# Control UI already uses localhost:3000 on minikube, so forward Grafana elsewhere:-kubectl port-forward -n monitoring svc/grafana 3001:80 # then open localhost:3001+kubectl --context "$KCTX" port-forward -n monitoring svc/grafana 3001:80 # then open localhost:3001```The admin user is `admin`. The values file does not set a password. Set`adminPassword` with `--set` or an existing Secret, or read the one the chart-generates. On a cluster whose StorageClass matches the values files, the plain-`make -C monitoring install_loki` and `install_grafana` targets work as-is.+generates. On a cluster whose StorageClass matches the values files, the same+`helm --kube-context` commands work without the `--set` overrides.++The targets in `monitoring/Makefile` (`setup`, `install_*`, `upgrade_*`,+`uninstall_*`, `status`, `port_forward_grafana`) take no context: they run+`kubectl` and `helm` against your kubeconfig's **current** context. Use them+only after `kubectl config current-context` shows the intended cluster; the+explicit commands above are the safer default.## Logs@@ -91,11 +107,11 @@ picks them up. The format differs by service:| Service | Format | Level variable || ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------- || control-api | Pino JSON, `svc: control-api`, ISO timestamps, token paths removed | `LOG_LEVEL` |-| workspace-files-controller | Pino and Pino HTTP JSON | |-| codex-llm-proxy, grok-llm-proxy | Pino JSON | |+| workspace-files-controller | Pino and Pino HTTP JSON | `LOG_LEVEL` |+| codex-llm-proxy, grok-llm-proxy | Pino JSON | `LOG_LEVEL` || mcp-host | JSON lines (`timestamp`, `level`, `component`, `msg`), sensitive keys redacted | `LOG_LEVEL` || host-context-controller | JSON lines from its own logger, sensitive keys redacted | `LOG_LEVEL` |-| workflow-recipes (controller and coordinator), workflow-approval-request-reader | JSON lines from their own loggers | |+| workflow-recipes (controller and coordinator), workflow-approval-request-reader | JSON lines from their own loggers | `LOG_LEVEL` |Other services may still print plain text. Don't assume every line is JSON.The repository logging standard is in [CLAUDE.md](../../CLAUDE.md) underdiff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.mdindex ac4f199f3..1f898b367 100644--- a/docs/surfaces/desktop-app.md+++ b/docs/surfaces/desktop-app.md@@ -202,8 +202,8 @@ Six `npm` scripts in `desktop-app/package.json` drive the makers, each running`electron-forge make --platform=<platform> --arch=<arch>`. Packaging runs`npm run build` first through the forge `prePackage` hook (set`EVENFIRE_SKIP_PACKAGE_BUILD=1` to reuse an existing build). `desktop-app/Makefile`-has no packaging targets — only install, build, dev, start, clean, and-port-forward helpers — so use the scripts directly:+has no packaging targets — only install, build, dev, start, clean,+reinstall, and port-forward helpers — so use the scripts directly:| Script | Platform | Arch | Makers || -------------------- | -------- | ----- | --------------------- |@@ -215,10 +215,11 @@ port-forward helpers — so use the scripts directly:| `make:linux:arm64` | linux | arm64 | zip, deb, rpm |Output lands in `desktop-app/out/` (git-ignored). Run the macOS scripts on a-macOS host: signing, notarization, and the adaptive-icon step (`xcrun actool`)-are all gated on the **build host** being macOS. The adaptive-icon-step is best-effort and falls back to the static icon unless-`EVENFIRE_REQUIRE_ADAPTIVE_ICONS=1`.+macOS host. Signing and notarization run only when the **build host** is macOS+(and `ENABLE_APPLE_CODESIGN=1`). The adaptive-icon step (`xcrun actool`) runs+for every **darwin target**, whatever the host, and needs `xcrun`, which exists+only on macOS. It is best-effort: on failure it falls back to the static icon,+unless `EVENFIRE_REQUIRE_ADAPTIVE_ICONS=1` makes the failure stop the build.The package is built with ASAR integrity validation, `OnlyLoadAppFromAsar`, andthe `RunAsNode`, `NODE_OPTIONS`, and inspector-argument fuses turned off.@@ -279,7 +280,10 @@ installers. The user-facing flow is inYou ship **one** packaged app, not a build per customer. A packaged build does**not** read `EXTERNAL_REST_API_BASE_URL` or `RPC_PROXY_BASE_URL` from theenvironment — those apply only to unpackaged dev runs, since-`desktop-app/src/config.ts` gates them behind `!app.isPackaged`. Instead, each+`desktop-app/src/config.ts` gates them behind `!app.isPackaged`. (The one+exception is a packaged build launched with `--evenfire-desktop-dev-package`+whose two URLs are the localhost defaults; it is for local packaging tests.)+Instead, eachuser points the installed app at whatever instance they want — your hostedservice, a teammate's, or local `make`-forwarded services — from the app's own**Environment** screen: name it, paste the External REST API URL, Save. The RPC@@ -290,9 +294,9 @@ config file. Adding and switching environments and the invitation setup pathare covered in [Desktop setup & updates](../how-to/desktop-setup-and-updates.md).Two variables **do** apply to a packaged build, read from the environment or-the bundled `.env.prod`: `MEMBER_REGISTRATION_SERVICE_BASE_URL` — which has-**no working default**, so left unset it silently falls back to the placeholder-`https://example.com` — and `REQUEST_TIMEOUT_MS`.+the bundled `.env.prod`: `MEMBER_REGISTRATION_SERVICE_BASE_URL` — left unset+(or empty) it falls back to `https://registration.evenfire.ai`, the hosted+evenfire service, so set it when you run your own — and `REQUEST_TIMEOUT_MS`.## The `member-registration-service` gapdiff --git a/monitoring/README.md b/monitoring/README.mdindex fc839ec5c..ebf2ca512 100644--- a/monitoring/README.md+++ b/monitoring/README.md@@ -32,7 +32,7 @@ make setupmake install_loki# Create the dashboards ConfigMap first: Grafana's values mount it-kubectl create configmap grafana-dashboards \+kubectl --context <your-context> create configmap grafana-dashboards \--from-file=dashboards/loki-grafana-dashboard.json \-n monitoring@@ -43,6 +43,12 @@ make install_grafana## Makefile Targets+These targets pass no `--context` / `--kube-context`: they run `kubectl` and+`helm` against your kubeconfig's **current** context. Check+`kubectl config current-context` before you run any of them, or use the+explicit commands in+[docs/operations/monitoring.md](../docs/operations/monitoring.md#install-on-minikube).+| Target | Description ||--------|-------------|| `setup` | Add Grafana Helm repo + create namespace |@@ -72,7 +78,7 @@ The `grafana/values.yaml` configures:The setup steps above create the `grafana-dashboards` ConfigMap that Grafana's values reference. To recreate it after editing the dashboard:```bash-kubectl create configmap grafana-dashboards \+kubectl --context <your-context> create configmap grafana-dashboards \--from-file=dashboards/loki-grafana-dashboard.json \-n monitoring```@@ -81,6 +87,10 @@ kubectl create configmap grafana-dashboards \```bashmake port_forward_grafana-# Open http://localhost:3000+# Open localhost:3000# Default user: admin (password set via secret or Helm override)```++On minikube the Control UI already uses local port 3000. Forward Grafana to+another port instead:+`kubectl --context <your-context> port-forward -n monitoring svc/grafana 3001:80`.