@kontextmind/kxm 0.7.145 → 0.7.147

package/docs/contributing/harness-routing-internals.md

@@ -5,6 +5,12 @@ This page records how the KXM repository applies [harness routing](../reference/
 > [!IMPORTANT]
 > The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/*.yaml`, `.kxm/models/*.yaml`, and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
 
+## Current ids (2026-09-27)
+
+The command transcripts below are the 2026-09-23 capture. The files now use one id shape per kind. A route id is `<harness>-<model-slug>[-<provider>]`, with `.` written as `-`. An agent id equals its role. A workflow id is `default`, `land`, or `<role>-only`. An agent step id equals that role.
+
+This checkout's routes are `grok-grok-4-7`, `pi-qwen3-coder-plus-openrouter`, `agy-gemini-3-8-flash-high`, `agy-gemini-3-8-flash-medium`, `claude-fable`, `codex-gpt-5-6-sol`, `pi-qwen3-8-flash-openrouter`, and `pi-glm-5-3-flash-openrouter`. Agents are `planner`, `writer`, `reviewer-arch`, and `reviewer-cli`. `opus-claude` was removed because `opus` is not an admitted selector. `qwen-token-plan/*` and `zai-coding-cn/*` left the admitted list because those harnesses are not allowlisted; their `prices.yaml` rows stay. Old ids resolve as aliases. Every roster entry names an effort. `reviewer-arch` dispatches `claude-fable`. #343's architecture critic ran on opus because the justfile recipe review-arch hardcoded that model; the role file on that commit listed only `fable-claude`. The helper now refuses `opus`.
+
 ## This checkout's routes and roster
 
 `node scripts/kxm.mjs role get writer`:
@@ -64,11 +70,11 @@ On the capture machine, `kxm harness list` showed `claude` detected but logged o
 The issue-127 runner (`kxm assign`, see the [assignment runner](assignment-runner.md)) reads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` at `refs/remotes/origin/main`. See [Developer assignment policy](../reference/config-reference.md#developer-assignment-policy). Routes there name the harness, the model and the vendor explicitly:
 
 ```yaml
-  grok-native:
+  grok-grok-4-7:
     harness: grok
-    model: grok-4.6
+    model: grok-4.7
     vendor: xai
-  qwen-openrouter-pi:
+  pi-qwen3-coder-plus-openrouter:
     harness: pi
     model: openrouter/qwen/qwen3-coder-plus
     vendor: alibaba
@@ -107,19 +113,19 @@ These extend the generic examples on the reference page with this checkout's adm
 | | Native `grok` | Pi + OpenRouter |
 |---|---|---|
 | Selector | `xai/grok-4.6`: admitted, and first in the writer roster | `openrouter/x-ai/grok-4.6`: not admitted |
-| Developer roster | `grok-native`, the writer route with `edit` | Refused: `native vendor cannot use Pi` |
+| Developer roster | `grok-grok-4-7`, the writer route with `edit` | Refused: `native vendor cannot use Pi` |
 | Readiness | `grok` shows auth `yes` | `pi auth check --provider openrouter` returned `not_ready` |
 | Billing | grok.com subscription (OAuth) | $2.00 input, $6.00 output, $0.50 cached input |
 | Context | 500K (Pi's `xai` row; `grok models` does not print one) | 500,000 |
 
-Pi's own `xai` provider reported `ready` (OAuth) on the capture machine. When the grok quota runs out, the next writer in the lineup is `qwen-openrouter-pi`, a different vendor.
+Pi's own `xai` provider reported `ready` (OAuth) on the capture machine. When the grok quota runs out, the next writer in the lineup is `pi-qwen3-coder-plus-openrouter`, a different vendor.
 
 ### GPT-5.6 Sol
 
 | | Native `codex` | Pi + OpenRouter |
 |---|---|---|
 | Selector | `openai/gpt-5.6-sol`: admitted, the CLI critic | `openrouter/openai/gpt-5.6-sol`: not admitted |
-| Developer roster | `sol-codex`: `reviewer-cli`, `read-only` | Refused |
+| Developer roster | `codex-gpt-5-6-sol`: `reviewer-cli`, `read-only` | Refused |
 | Billing | ChatGPT subscription | $2.00 input, $10.00 output, $0.20 cached input |
 | Context | Pi's `openai-codex` row, the same ChatGPT backend, lists 272K | 1,050,000 |
 
@@ -130,7 +136,7 @@ In the inventory, `openai/gpt-5.6-sol` has sources `openrouter+nous` and carries
 | | Native `claude` | Pi + OpenRouter |
 |---|---|---|
 | Selector | `anthropic/fable`: admitted, planner and architecture critic | `openrouter/anthropic/claude-fable-5.1`: not admitted |
-| Developer roster | `fable-claude`: `planner` and `reviewer-arch`, `read-only` | Refused |
+| Developer roster | `claude-fable`: `planner` and `reviewer-arch`, `read-only` | Refused |
 | Readiness | Detected `yes`, auth `no`, dispatch `no (not_authenticated)` | `not_ready` |
 | Billing | claude.ai subscription | $10.00 input, $50.00 output, $0.25 cached input |
 | Context | 1M (Pi's `anthropic` row) | 1,000,000 |
@@ -159,10 +165,10 @@ The code differs from that decision: `.kxm/routes.yaml` admits `google/gemini-3.
 
 | Model | Vendor-plan route | OpenRouter route | Notes |
 |---|---|---|---|
-| Qwen3.8 Flash | `qwen-token-plan/qwen3.8-flash`: admitted, in the writer roster; `ready` (`api_key`) | `openrouter/qwen/qwen3.8-flash`: admitted; $0.15 input, $0.47 output | `prices.yaml` gives both routes the same rates. Prefer the plan when it is authenticated. |
-| Qwen3 Coder Plus | none | `openrouter/qwen/qwen3-coder-plus`: $0.65 input, $3.25 output | The only admitted Pi writer: exact model, `edit` permission. |
-| GLM 5.3 and 5.3 Flash | `zai-coding-cn/glm-5.3` and `…/glm-5.3-flash`: admitted as failover critics and writer | `openrouter/z-ai/glm-5.3-flash`: admitted; $0.09 input, $0.30 output | Z.ai has no native harness. |
-| DeepSeek V4.1 Flash | `qwen-token-plan/deepseek-v4.1-flash`: admitted | `deepseek/deepseek-v4.1-flash` in the OpenRouter feed: $0.15 input, $0.60 output | Bills a DeepSeek model through Alibaba's plan, and passes the product brake because it names no vendor segment. An open admission question, not a precedent. |
+| Qwen3.8 Flash | `qwen-token-plan/qwen3.8-flash`: removed from the admitted list on 2026-09-27; `qwen-token-plan` is not allowlisted | `openrouter/qwen/qwen3.8-flash`: admitted, route `pi-qwen3-8-flash-openrouter`, read-only fallback for planner and reviewer-cli | `prices.yaml` keeps both rows. |
+| Qwen3 Coder Plus | none | `openrouter/qwen/qwen3-coder-plus`: route `pi-qwen3-coder-plus-openrouter` | The only admitted Pi writer: exact model, `edit` permission. |
+| GLM 5.3 and 5.3 Flash | `zai-coding-cn/glm-5.3` and `…/glm-5.3-flash`: removed from the admitted list on 2026-09-27; `zai-coding-cn` is not allowlisted | `openrouter/z-ai/glm-5.3-flash`: admitted, route `pi-glm-5-3-flash-openrouter`, read-only fallback for reviewer-arch | Z.ai has no native harness. |
+| DeepSeek V4.1 Flash | `qwen-token-plan/deepseek-v4.1-flash`: removed from the admitted list on 2026-09-27 | `deepseek/deepseek-v4.1-flash` in the OpenRouter feed | Bills a DeepSeek model through Alibaba's plan. `deepseek` is a native-vendor Pi brake, so this is not a route. |
 
 The developer runner is stricter. Its only Pi writer is `openrouter/qwen/qwen3-coder-plus`, and it does not allowlist `qwen-token-plan` or `zai-coding-cn`. Today OpenRouter is the right answer here for Qwen3 Coder Plus, Qwen3.8 Flash and GLM 5.3 Flash.
 

package/docs/contributing/operating-rules.md

@@ -2,7 +2,7 @@
 title: "Operating rules"
 description: "Standing instructions from the operator that every agent session on this repository follows, with the date each was given. Read before planning, dispatching, landing, or editing the roadmap."
 audience: "agents and maintainers"
-updated: "2026-09-26"
+updated: "2026-09-27"
 ---
 
 # Operating rules
@@ -58,6 +58,18 @@ replacement.
   `impl-bg`) retire last, after one real unit has run through the one-step
   workflows. (2026-09-26.)
 
+## Accounts
+
+- **Machine account names follow [ADR-0006](../adr/ADR-0006-machine-account-names.md).**
+  Platform-wide accounts are `svc-<system>-<purpose>`. Tenant-scoped accounts
+  are `svc-<tenant>-<system>-<purpose>`, where `<tenant>` is the tenant slug.
+  Test, witness, and proof accounts use those shapes with a `test-` prefix
+  and are never members of production groups. Authentik-managed accounts
+  (outposts and `ak-*`) are exempt. Recorded names such as `kxm-agent`,
+  `kxm-witness-*`, `witness9`, and `kxmdproof` stay until an approved
+  inventory. Do not invent a replacement for a specific account.
+  (2026-09-27.)
+
 ## Decisions and debt
 
 - **Every option comes with pros and cons and two recommendations**, the

package/docs/guides/agent-skills.md

@@ -68,7 +68,7 @@ Tools map the same way: peer tools to `kxm-peer`, workflow tools to `kxm-workflo
 
 ## Browser automation skills
 
-Playwright testing and verification use Obscura ([ADR-0005](../adr/ADR-0005-obscura-default-playwright.md)). The Steel skills cover human takeover, MFA, and the live session viewer. Those hosts sit behind Authentik forward auth: send `Authorization: Basic` (`STEEL_AUTH_BASIC`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`) and keep the credential out of URLs. `kxm-browser-verify` owns `vision`. The other browser skills own no `kxm` command. See [Browser automation](browser-automation.md) and [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md).
+Playwright testing and verification use Obscura ([ADR-0005](../adr/ADR-0005-obscura-default-playwright.md)). The Steel skills cover remote and hosted browsing, human takeover, MFA, and the live session viewer. Steel is `https://steel.kontextmind.com`, reached only through Caddy and Authentik ([ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md)). Send `Authorization: Basic` (`STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`) and keep the credential out of URLs. `STEEL_API_KEY` is deprecated and is not enforced. `kxm` 0.7.135 or newer is required for Steel. `kxm-browser-verify` owns `vision`. The other browser skills own no `kxm` command. See [Browser automation](browser-automation.md).
 
 | Skill | Use it to |
 |---|---|

package/docs/guides/browser-automation.md

@@ -5,9 +5,9 @@ Give agents a real browser without giving them your desktop. Playwright testing
 ## Before you begin
 
 - For Playwright: Node, and `node scripts/obscura.mjs` (it downloads pinned Obscura v0.2.3). [ADR-0005](../adr/ADR-0005-obscura-default-playwright.md) records that default.
-- For takeover: a Steel deployment you operate, reachable over HTTPS, and an Authentik app password when that host is behind forward auth. [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md) describes the reference deployment on Kubernetes.
+- For Steel: `kxm` 0.7.135 or newer. [ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md) is the current server. [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md) is the superseded Kubernetes deployment.
 - `curl` and `jq`. Optionally `agent-browser` for exploration. Playwright tests use Obscura; do not run `playwright install`.
-- A secret manager for the Authentik app password and site credentials. The bundled skills use `pass-cli`.
+- The 1Password CLI (`op`) for the `svc-steel` credential. Read it at runtime. Do not write it to disk.
 - The `kxm-browser-*` skills from the plugin or Pi package. See [Agent skills](agent-skills.md#browser-automation-skills).
 
 ## Components
@@ -36,33 +36,37 @@ Set `video: "off"` in Playwright. Obscura does not record video. Connect with th
 
 The KXM browser library reads these variables, and the shell procedure below uses the same names so both agree.
 
-KontextMind's Steel hosts (`steel.kontextmind.com` and `steel.theneuro.me`, including the `wss://` CDP endpoint) sit behind Authentik forward auth at the reverse proxy. Steel itself does not check an API key. Unauthenticated requests receive a 302 redirect to the Authentik login at `id.kxmd.dev`. Authentik accepts an app password only as `Authorization: Basic`. A Bearer token is refused.
+The Steel server is `https://steel.kontextmind.com`. `steel.theneuro.me` is an alias of that same server. The only path is Caddy on `kxmd-proxy` (VM 230) with Authentik forward auth. Direct LAN, tailnet, and host-forward connections are blocked. Unauthenticated requests receive a 302 redirect to `id.kxmd.dev`.
+
+Sessions return `websocketUrl` `wss://steel.kontextmind.com/`. The previous value was `ws://steel-browser/`. Connect Chrome DevTools Protocol at `/v1/devtools` and send `Authorization` on the handshake. The URL never carries a credential.
+
+Authentik accepts the `svc-steel` credential as `Authorization: Basic`. A Bearer token is refused. These groups may connect: `steel-users`, `kxmd-users`, `kxmd-admins`, and `kxmd-owners`. Steel needs `kxm` 0.7.135 or newer.
 
 | Variable | Default | Effect |
 |---|---|---|
-| `STEEL_API_URL` | A KontextMind-operated deployment | Base URL of your Steel API. Always set it |
+| `STEEL_API_URL` | `https://steel.kontextmind.com` | Base URL of the Steel API |
 | `STEEL_UI_URL` | `$STEEL_API_URL/ui` | Base URL of the session viewer |
-| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. Wins over the other auth variables |
-| `STEEL_AUTH_BASIC` | unset | `base64(user:token)`, with or without a leading `Basic` prefix. Sent as `Authorization: Basic` |
-| `STEEL_AUTH_USER` | unset | Authentik username, for example `svc-steel`. Used with `STEEL_AUTH_TOKEN` |
+| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. First in the precedence below |
+| `STEEL_AUTH_BASIC` | unset | `base64(user:token)`, with or without a leading `Basic` prefix |
+| `STEEL_AUTH_USER` | unset | Authentik username `svc-steel`. Used with `STEEL_AUTH_TOKEN` |
 | `STEEL_AUTH_TOKEN` | unset | Authentik app password. Used with `STEEL_AUTH_USER` |
-| `STEEL_API_KEY` | A `pass-cli` lookup | Deprecated. Sent as `x-steel-api-key` and as `?apiKey=` on the CDP URL, which the proxy still accepts as a temporary shim. The library warns once on stderr |
-| `USE_PASS_CLI` | enabled | Set to `false` to disable the legacy `STEEL_API_KEY` `pass-cli` fallback |
+| `STEEL_API_KEY` | unset | Deprecated. Steel and Caddy do not enforce it. See the migration note |
+| `USE_PASS_CLI` | enabled | Turns the legacy `STEEL_API_KEY` lookup off when set to `false` |
 
-Set one Authentik credential. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` together with `STEEL_AUTH_TOKEN`. If only one of the user or token pair is set, configuration fails instead of falling back to the legacy key. When any of those are set, the legacy key is not sent and is not placed in a URL. The `pass-cli` fallback looks up `STEEL_API_KEY` only.
+Set one Authentik credential. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` together with `STEEL_AUTH_TOKEN`. Those three override `STEEL_API_KEY`. If only one of the user or token pair is set, configuration fails closed. When any Authentik variable is set, the legacy key is not sent.
 
 > [!WARNING]
-> Set `STEEL_API_URL` and an Authentik credential explicitly. Without them the library falls back to KontextMind's own deployment and vault item, which are not yours to use. Never put the credential in a URL, a prompt, or a log.
+> `STEEL_API_KEY` is deprecated. Steel and Caddy do not enforce it. A client that still sends `x-steel-api-key` or `?apiKey=` is not authenticated. Migrate by setting one Authentik variable above and removing `STEEL_API_KEY`. Read the credential with `op read`. Never write it to disk, a URL, a prompt, or a log.
 
 ```bash
-export STEEL_API_URL="https://steel.example.com"
-# Read the app password from your secret manager; <vault> and <item> are yours.
-export STEEL_AUTH_USER="svc-steel"
-export STEEL_AUTH_TOKEN="$(pass-cli item view --vault-name '<vault>' --item-title '<item>' --field password)"
-export USE_PASS_CLI=false
+# Optional. This is already the default.
+export STEEL_API_URL="https://steel.kontextmind.com"
+# Vault kontextmind, item "Steel (svc-steel)", field basic_auth.
+# The value stays in this process. Do not redirect it to a file.
+export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"
 ```
 
-`STEEL_AUTH_BASIC` is the same pair already encoded: `printf '%s:%s' "$STEEL_AUTH_USER" "$STEEL_AUTH_TOKEN" | base64 | tr -d '\n'`. Prefer the user and token pair, or the pre-encoded value, and keep them in the environment of the process that calls Steel.
+`STEEL_AUTH_USER` is `svc-steel` when you set the user and token pair instead of `STEEL_AUTH_BASIC`. Keep the value in the environment of the process that calls Steel.
 
 | Endpoint | Purpose |
 |---|---|
@@ -70,20 +74,29 @@ export USE_PASS_CLI=false
 | `GET /v1/sessions/<id>` | Inspect one session; `GET /v1/sessions` lists them all |
 | `POST /v1/sessions/<id>/release` | Release a session |
 | `POST /v1/scrape`, `POST /v1/screenshot` | One-shot page fetch or screenshot without a session |
-| `wss://<steel-host>/v1/devtools?sessionId=<id>` | CDP endpoint. Send `Authorization` on the WebSocket handshake; do not add the credential to this URL |
+| `wss://steel.kontextmind.com/v1/devtools?sessionId=<id>` | CDP path. Send `Authorization` on the handshake. The session `websocketUrl` is `wss://steel.kontextmind.com/` |
 | `$STEEL_UI_URL?sessionId=<id>` | Session viewer for human takeover |
 
 ## Run a browser task
 
-1. Define a helper that sends `Authorization` on stdin, so the secret never appears in a process list:
+1. Define a helper that sends `Authorization` on stdin, so the secret never appears in a process list. `STEEL_API_URL` defaults to `https://steel.kontextmind.com` when unset:
 
    ```bash
    steel() {  # usage: steel METHOD PATH [JSON-BODY]
-     local basic
-     local args=(-sS -X "$1" "$STEEL_API_URL$2" -H @- -H 'Content-Type: application/json')
+     local header args
+     args=(-sS -X "$1" "${STEEL_API_URL:-https://steel.kontextmind.com}$2" -H @- -H 'Content-Type: application/json')
      if [ -n "${3:-}" ]; then args+=(-d "$3"); fi
-     basic="$(printf '%s:%s' "$STEEL_AUTH_USER" "$STEEL_AUTH_TOKEN" | base64 | tr -d '\n')"
-     printf 'Authorization: Basic %s\n' "$basic" | curl "${args[@]}"
+     if [ -n "${STEEL_AUTH_HEADER:-}" ]; then
+       header="$STEEL_AUTH_HEADER"
+     elif [ -n "${STEEL_AUTH_BASIC:-}" ]; then
+       case "$STEEL_AUTH_BASIC" in
+         Basic\ *) header="$STEEL_AUTH_BASIC" ;;
+         *) header="Basic $STEEL_AUTH_BASIC" ;;
+       esac
+     else
+       header="Basic $(printf '%s:%s' "$STEEL_AUTH_USER" "$STEEL_AUTH_TOKEN" | base64 | tr -d '\n')"
+     fi
+     printf 'Authorization: %s\n' "$header" | curl "${args[@]}"
    }
    ```
 
@@ -157,16 +170,18 @@ The KXM browser library tracks these states in the process that owns the session
 
 - **Timeouts.** Sessions end on their own when the timeout expires. Set a longer timeout at creation when a person will need time for a login step.
 - **Orphan sweeps.** List sessions with `steel GET /v1/sessions` and release any you do not track. The library flags untracked sessions older than 10 minutes, and tracked ones idle that long unless a human holds them.
-- **Shared memory.** Give Chromium a large `/dev/shm`, or tabs crash. On Kubernetes, mount a memory-backed `emptyDir` there; the reference deployment uses 2 GiB.
+- **Shared memory.** Give Chromium a large `/dev/shm` on Steel LXC 240, or tabs crash.
 - **No shared profiles.** Concurrent sessions must not write to the same browser profile.
 
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `302` to `id.kxmd.dev` | The request had no Authentik app password | Export `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`, or `STEEL_AUTH_BASIC`. A Bearer token is not accepted |
-| `401` or `403` | Wrong app password, or a legacy key the shim rejected | Re-export the Authentik credential from your secret manager. Re-export `STEEL_API_KEY` only when that is the credential you still use |
-| Requests go to an unexpected host | `STEEL_API_URL` is unset | Export it before starting the agent |
+| `302` to `id.kxmd.dev` | The request had no Authentik credential | Export `STEEL_AUTH_BASIC` from `op read`, or the user and token pair. A Bearer token is not accepted |
+| `401` or `403` | Wrong `svc-steel` credential, or the account is outside the allowed groups | Re-read `basic_auth` with `op read`. `STEEL_API_KEY` does not authenticate |
+| Connection refused on a LAN, tailnet, or host-forward address | Those paths are blocked | Use `https://steel.kontextmind.com` through Caddy |
+| `websocketUrl` is `ws://steel-browser/` | The client is older than `kxm` 0.7.135 | Upgrade `kxm`. The server returns `wss://steel.kontextmind.com/` |
+| Requests go to an unexpected host | `STEEL_API_URL` points somewhere else | Unset it to use `https://steel.kontextmind.com`, or set that URL |
 | Playwright opens a local browser | The client called `chromium.launch()` or `chromium.connect()` | Use the worker-scoped fixture and `connectOverCDP` against Obscura |
 | Steel CDP connects without auth | `connectOverCDP` was called with only the URL | Call `connectOverCDP(url, { headers })` with the headers from `formatCDPConnect()` or `connectBrowserOverCdp()` |
 | `Access to private/internal IP address` | Obscura was started without `--allow-private-network` | Run `node scripts/obscura.mjs`, which passes that flag |
@@ -199,5 +214,6 @@ The KXM browser library tracks these states in the process that owns the session
 
 - The seven browser skills: [Agent skills](agent-skills.md#browser-automation-skills)
 - Why Obscura is the Playwright default: [ADR-0005](../adr/ADR-0005-obscura-default-playwright.md)
-- Why Steel, and the reference deployment: [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md)
+- Where Steel runs now: [ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md)
+- The superseded Kubernetes deployment: [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md)
 - Estimate the `browser` mode's prompt footprint: [`kxm explain`](../reference/cli-reference.md#kxm-explain)

package/docs/kb/how-credentials-retrieved-safely.md

@@ -11,7 +11,7 @@ updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
 summary: "How the Steel client resolves Authentik Basic auth and how browser work keeps secrets out of model context."
-tags: ["browser", "credentials", "pass-cli", "security"]
+tags: ["browser", "credentials", "1password", "security"]
 related: ["docs/guides/browser-automation.md", "docs/guides/agent-skills.md"]
 ---
 
@@ -28,37 +28,36 @@ secret to disk or to a log:
 
 | Setting | Resolved from |
 |---|---|
-| API URL | An explicit override, then `STEEL_API_URL`, then a built-in default |
+| API URL | An explicit override, then `STEEL_API_URL`, then `https://steel.kontextmind.com` |
 | Authentik `Authorization` | `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN` |
-| Legacy API key | An explicit override, then `STEEL_API_KEY`, then a `pass-cli` lookup, and only when no Authentik credential is set |
+| Legacy API key | Deprecated. An explicit override, then `STEEL_API_KEY`, then a leftover lookup, and only when no Authentik credential is set. Steel and Caddy do not enforce it |
 | Session viewer URL | An explicit override, then `STEEL_UI_URL`, then `<api-url>/ui` |
 
-KontextMind's Steel hosts are behind Authentik forward auth. The client sends
-`Authorization: Basic` on every HTTP request and on the CDP WebSocket. A Bearer
-token is not accepted. The legacy key is sent as `x-steel-api-key` and as an
-`apiKey` query parameter, which the proxy still accepts as a temporary shim.
-The library writes one deprecation warning to stderr and does not print the
-key. When an Authentik variable is set, the key is not sent and is not placed
-in a URL.
+The Steel server is behind Caddy and Authentik forward auth. The client sends
+`Authorization: Basic` on every HTTP request and on the CDP WebSocket at
+`/v1/devtools`. A Bearer token is refused. A credential in the URL is refused.
+`STEEL_API_KEY` is deprecated. When an Authentik variable is set, that variable
+overrides the key, and the key is not sent.
 
-The built-in default URL and the `pass-cli` lookup point at the maintainers'
-own Steel deployment and vault. The lookup reads `STEEL_API_KEY` only. Set
-`STEEL_API_URL` and an Authentik credential for yours, and set
-`USE_PASS_CLI=false` to turn the lookup off.
+Read the `svc-steel` credential at runtime and do not write it to disk. The
+1Password vault is `kontextmind`, the item is `Steel (svc-steel)`, and the
+field is `basic_auth`:
 
-## Mechanisms
+```bash
+export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"
+```
+
+`kxm` 0.7.135 or newer is required. Sessions return `websocketUrl`
+`wss://steel.kontextmind.com/`.
 
-1. **One secret store.** Keep secrets in a secret manager, for example Proton
-   Pass through `pass-cli`, and load them into the environment of the process
-   that needs them:
+## Mechanisms
 
-   ```bash
-   # Runs the tests with secrets injected for this process only.
-   pass-cli run -- npm test
-   ```
+1. **One secret store.** Keep the Steel credential in 1Password and load it
+   into the environment of the process that needs it, as the `op read` command
+   above. Do not redirect the command into a file.
 
 2. **References, not values.** A prompt receives a credential reference such
-   as `vault: "<vault>", item: "<item>"`, never the secret itself.
+   as `op://kontextmind/Steel (svc-steel)/basic_auth`, never the secret itself.
 3. **Log sanitization.** The KXM browser client redacts `apiKey=` query values,
    `Authorization` header values, `Basic` credentials, `steel_…` keys, and any
    field named like a key, secret, token, auth or password before it logs or

package/docs/kb/how-to-connect-playwright-to-steel.md

@@ -43,16 +43,19 @@ const { url, headers } = formatCDPConnect(
 );
 ```
 
-The URL has this shape:
+The URL has this shape. The session field `websocketUrl` is the origin
+`wss://steel.kontextmind.com/` (it used to be `ws://steel-browser/`). The
+connect path is `/v1/devtools`:
 
 ```text
-wss://<steel-host>/v1/devtools?sessionId=<session-id>
+wss://steel.kontextmind.com/v1/devtools?sessionId=<session-id>
 ```
 
 `headers` is `{ Authorization: "Basic <base64>" }`. Pass that object to
-Playwright. Do not log it. A legacy `STEEL_API_KEY` still appends `apiKey` to
-the URL for the temporary proxy shim; prefer the Authentik variables so the
-credential stays out of the URL.
+Playwright. Do not log it. `STEEL_API_KEY` is deprecated and is not enforced
+by Steel or Caddy. Do not put `apiKey` on the URL. `STEEL_AUTH_HEADER`, then
+`STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`, override it.
+`kxm` 0.7.135 or newer is required.
 
 ## 2. Connect in Playwright
 

package/docs/kb/how-to-recover-expired-session-or-orphan.md

@@ -22,23 +22,24 @@ browser can keep running on your Steel deployment until its timeout.
 
 ## 1. List active sessions
 
-Load `STEEL_API_URL`, `STEEL_AUTH_USER`, and `STEEL_AUTH_TOKEN` from your secret
-manager first. With `pass-cli`, for example:
+Load the `svc-steel` credential from 1Password into this process. Do not write
+it to disk. `STEEL_API_URL` defaults to `https://steel.kontextmind.com`.
+`STEEL_API_KEY` is deprecated and is not enforced.
 
 ```bash
-export STEEL_API_URL="https://<steel-host>"
-export STEEL_AUTH_USER="svc-steel"
-export STEEL_AUTH_TOKEN="$(pass-cli item view --vault-name "<vault>" --item-title "<item>" --field password)"
-basic="$(printf '%s:%s' "$STEEL_AUTH_USER" "$STEEL_AUTH_TOKEN" | base64 | tr -d '\n')"
-
-printf 'Authorization: Basic %s\n' "$basic" | curl -sS -H @- "$STEEL_API_URL/v1/sessions" | jq .
+export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"
+case "$STEEL_AUTH_BASIC" in
+  Basic\ *) header="$STEEL_AUTH_BASIC" ;;
+  *) header="Basic $STEEL_AUTH_BASIC" ;;
+esac
+printf 'Authorization: %s\n' "$header" | curl -sS -H @- "${STEEL_API_URL:-https://steel.kontextmind.com}/v1/sessions" | jq .
 ```
 
 ## 2. Release an orphaned session
 
 ```bash
-printf 'Authorization: Basic %s\n' "$basic" \
-  | curl -sS -X POST -H @- "$STEEL_API_URL/v1/sessions/<session-id>/release"
+printf 'Authorization: %s\n' "$header" \
+  | curl -sS -X POST -H @- "${STEEL_API_URL:-https://steel.kontextmind.com}/v1/sessions/<session-id>/release"
 ```
 
 ## 3. Sweep orphans with the KXM client

package/docs/kb/why-automation-opened-different-browser.md

@@ -42,6 +42,7 @@ You expected automation to run on Obscura, or on a Steel takeover session, but a
      opens a local browser.
    - **Fix:** use `resolveObscuraCdpEndpoint()` (default
      `http://127.0.0.1:9222`). For a Steel takeover session, set
-     `KXM_BROWSER=steel` and load `STEEL_API_URL` plus `STEEL_AUTH_USER` and
-     `STEEL_AUTH_TOKEN` (or `STEEL_AUTH_BASIC`). A legacy `STEEL_API_KEY` still
-     works through the proxy shim and warns once.
+     `KXM_BROWSER=steel` and load `STEEL_AUTH_BASIC` with `op read` (or
+     `STEEL_AUTH_HEADER`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`).
+     `STEEL_API_KEY` is deprecated. Steel and Caddy do not enforce it.
+     `kxm` 0.7.135 or newer is required for Steel.

package/docs/operations/deploy.md

@@ -279,6 +279,35 @@ server {
 }
 ```
 
+## Boot the kxmd Proxmox host
+
+The Proxmox host starts these guests in the order below. The VMID is the Proxmox guest id. `up` is the delay, in seconds, after that guest starts.
+
+| Order | Guest | VMID | Role | up |
+|---|---|---|---|---|
+| 1 | firewall | 200 | Firewall | |
+| 2 | gateway | 201 | Gateway | |
+| 3 | kxmd-pg | 220 | Postgres | 30 |
+| 4 | kxmd-temporal | 221 | Temporal | 40 |
+| 5 | kxmd-services | 300 | `kxm-control` | 30 |
+| 6 | kxmd-studio | 241 | Hub | 20 |
+
+VM 300 is named `kxmd-services`. VM 230 is named `kxmd-proxy` and runs Caddy. Steel is LXC 240 and uses Proxmox startup order 40.
+
+Steel's public name is `steel.kontextmind.com`. `steel.theneuro.me` is an alias of that same server. Clients reach it only through Caddy and Authentik forward auth. Direct LAN, tailnet, and host-forward access is blocked. See [ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md) and [Browser automation](../guides/browser-automation.md).
+
+## Name machine accounts
+
+New Authentik machine accounts follow [ADR-0006](../adr/ADR-0006-machine-account-names.md):
+
+| Scope | Name |
+|---|---|
+| Platform-wide | `svc-<system>-<purpose>` |
+| Tenant-scoped | `svc-<tenant>-<system>-<purpose>` |
+| Test, witness, or proof | The same shapes with a `test-` prefix |
+
+`<tenant>` is the tenant slug. A `test-` account is never in a production group. Outposts and `ak-*` accounts are Authentik-managed and are exempt. Names already in use, including `kxm-agent`, `kxm-witness-*`, `witness9`, and `kxmdproof`, wait for an approved inventory. Do not invent a new name for one of them. The live Steel account remains `svc-steel`.
+
 ## Plan for scale
 
 Measure concurrent agents, request rate, event-loop delay, database size, disk latency and reconnect frequency for your workload. Terminal messages are purged after `KXM_MESSAGE_RETENTION_MS` (7 days by default), and finished workflow runs and their journals after 7 days. Keep free disk space ahead of the database's growth, and include workflow data in privacy reviews: verified evidence snapshots stay in a run after its source messages are purged.
@@ -304,4 +333,6 @@ See [Troubleshoot KXM](troubleshooting.md) for more.
 - Move to a new release: [Upgrade KXM](upgrade.md)
 - Keep run facts flowing to the hub: [Operate Runtime sync and leases](runtime-sync.md)
 - Understand who can do what: [Trust model](../concepts/trust-model.md)
+- Name machine accounts: [ADR-0006](../adr/ADR-0006-machine-account-names.md)
+- Reach Steel: [ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md)
 - Every hub route: [Hub HTTP API reference](../reference/http-api.md)

package/docs/operations/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshoot KXM
 
-This page is a reference of symptoms, causes and fixes, grouped by area. Start with the quick check, then go to the area that matches: install, hub and authentication, Claude Code, peer messaging, Pi workers, workflows, Runtime runs, context and memory, or operations.
+This page is a reference of symptoms, causes and fixes, grouped by area. Start with the quick check, then go to the area that matches: install, hub and authentication, Claude Code, peer messaging, Pi workers, workflows, Runtime runs, context and memory, Steel, or operations.
 
 ## Start with a quick check
 
@@ -239,6 +239,26 @@ See [Context and memory](../guides/context-and-memory.md).
 
 For backup and restore errors such as `backup_no_stores`, see [Back up and restore KXM](backup-and-restore.md#troubleshooting). The dashboard's action keys do not act on runs; see [Monitor KXM](monitoring.md#keys).
 
+## Steel
+
+Steel is `https://steel.kontextmind.com` (`steel.theneuro.me` is an alias). Caddy and Authentik forward auth are the only path. Playwright tests use Obscura. The procedure is [Browser automation](../guides/browser-automation.md). `kxm` 0.7.135 or newer is required.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Connection refused or timeout on a LAN, tailnet, or host-forward address | Direct access to LXC 240 is blocked | Use `https://steel.kontextmind.com` |
+| `302` to `id.kxmd.dev` | No Authentik credential on the request | Set `STEEL_AUTH_HEADER`, or `STEEL_AUTH_BASIC`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN` |
+| `401` or `403` | The `svc-steel` credential is wrong, or the account is outside `steel-users`, `kxmd-users`, `kxmd-admins`, and `kxmd-owners` | Re-read the credential with `op read`. `STEEL_API_KEY` is not enforced |
+| `websocketUrl` is `ws://steel-browser/` | The client predates `kxm` 0.7.135 | Upgrade `kxm`. The server returns `wss://steel.kontextmind.com/` |
+| CDP fails and the URL contains `apiKey` | `STEEL_API_KEY` was placed on `/v1/devtools` | Connect to `/v1/devtools` with an `Authorization` header and no credential in the URL |
+
+Read the credential into the process only:
+
+```bash
+export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"
+```
+
+The vault is `kontextmind`, the item is `Steel (svc-steel)`, and the field is `basic_auth`. Do not write that value to disk.
+
 ## Collect a useful bug report
 
 Include:
@@ -263,4 +283,6 @@ Never attach tokens, private prompts, credentials, raw `pi-agent-*.log` files, o
 - [Monitor KXM](monitoring.md)
 - [Deploy KXM](deploy.md)
 - [CLI reference](../reference/cli-reference.md)
+- [Browser automation](../guides/browser-automation.md)
+- [Steel through Caddy and Authentik](../adr/ADR-0007-steel-caddy-authentik.md)
 - [Claude Code plugin](../../plugins/kxm/README.md)

package/docs/prompts/browser-diagnose-recover.md

@@ -52,5 +52,5 @@ Use this prompt to troubleshoot unresponsive sessions, CDP attachment errors, au
    - For each orphan, invoke `POST /v1/sessions/:id/release`.
 
 4. **Verify WebSocket / CDP Ingress**:
-   - Ensure the reverse proxy or ingress in front of Steel passes WebSocket upgrades through. On Kubernetes with ingress-nginx, that is the `nginx.ingress.kubernetes.io/websocket-services` annotation.
-   - If the response is a 302 to `id.kxmd.dev`, or CDP fails with 401, send `Authorization: Basic` from `STEEL_AUTH_BASIC` or from `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`. A Bearer token is not accepted. Do not put the credential in the URL. The legacy `x-steel-api-key` header and `?apiKey=` query parameter remain only for the temporary proxy shim.
+   - Steel is reached only through Caddy and Authentik forward auth. Direct LAN, tailnet, and host-forward connections are blocked. The CDP path is `/v1/devtools` with an `Authorization` header.
+   - If the response is a 302 to `id.kxmd.dev`, or CDP fails with 401 or 403, send `Authorization: Basic` from `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`. A Bearer token is not accepted. Do not put the credential in the URL. `STEEL_API_KEY` is deprecated. Steel and Caddy do not enforce it. Sessions return `websocketUrl` `wss://steel.kontextmind.com/`. `kxm` 0.7.135 or newer is required.

package/docs/prompts/browser-start.md

@@ -42,7 +42,7 @@ Use this prompt to initialize a remote browser session on self-hosted Steel for
 ## Instructions for the agent
 
 1. **Verify Credential Reference**:
-   - Resolve the target credentials and the Steel Authentik app password (`STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`, or `STEEL_AUTH_BASIC`) from the secret manager, for example with `pass-cli`, without logging raw values. A Bearer token is not accepted. Keep the credential in a header, not a URL.
+   - Resolve the `svc-steel` credential with `op read 'op://kontextmind/Steel (svc-steel)/basic_auth'` into `STEEL_AUTH_BASIC` (or set `STEEL_AUTH_HEADER`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`). Do not log the value or write it to disk. A Bearer token is not accepted. `STEEL_API_KEY` is deprecated and is not enforced. Keep the credential in a header, not a URL. `STEEL_API_URL` defaults to `https://steel.kontextmind.com`. `kxm` 0.7.135 or newer is required.
    - Do not print credentials to the chat or save them to tracked files.
 
 2. **Launch Remote Steel Session**: