@kontextmind/kxm 0.7.146 → 0.7.148

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**:

package/docs/reference/configuration.md

@@ -200,21 +200,23 @@ The Runtime supervisor runs `kxm run` workflows and syncs their summaries to the
 
 ## Browser automation
 
-Playwright testing and verification use Obscura. Steel is for human takeover, MFA, and the live session viewer. `resolveBrowserCdpEndpoint()` in `plugins/kxm/src/browser.ts` returns the CDP URL. `resolveBrowserCdpConnect()` returns that URL and the handshake headers, and `connectBrowserOverCdp()` passes them to `chromium.connectOverCDP`. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it. See [Browser automation](../guides/browser-automation.md).
+Playwright testing and verification use Obscura. Steel is for remote and hosted browsing, human takeover, MFA, and the live session viewer. `resolveBrowserCdpEndpoint()` in `plugins/kxm/src/browser.ts` returns the CDP URL. `resolveBrowserCdpConnect()` returns that URL and the handshake headers, and `connectBrowserOverCdp()` passes them to `chromium.connectOverCDP`. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it. Steel needs `kxm` 0.7.135 or newer. See [Browser automation](../guides/browser-automation.md) and [ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md).
 
 | Variable | Default | Effect |
 |---|---|---|
-| `KXM_BROWSER` | `obscura` | `obscura` selects the Obscura CDP URL and sends no Steel headers. `steel` selects `formatCDPConnect()` (the session URL plus `Authorization`, or the legacy API-key header) and requires a session id. Any other value throws |
+| `KXM_BROWSER` | `obscura` | `obscura` selects the Obscura CDP URL and sends no Steel headers. `steel` selects `/v1/devtools` plus `Authorization` and requires a session id. Any other value throws |
 | `OBSCURA_CDP_URL` | `http://127.0.0.1:${OBSCURA_PORT:-9222}` | CDP URL passed to `chromium.connectOverCDP()`. When set, it wins over `OBSCURA_PORT` for that URL |
 | `OBSCURA_PORT` | `9222` | TCP port for `obscura serve`. Used in the default CDP URL when `OBSCURA_CDP_URL` is unset. The launcher refuses to start when this port disagrees with the port in `OBSCURA_CDP_URL` |
-| `STEEL_API_URL` | A KontextMind-operated deployment | Base URL of your Steel API. Set it before using `KXM_BROWSER=steel` |
+| `STEEL_API_URL` | `https://steel.kontextmind.com` | Base URL of the Steel API. `steel.theneuro.me` is an alias of that server |
 | `STEEL_UI_URL` | `$STEEL_API_URL/ui` | Base URL of the Steel session viewer |
-| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. Wins over the other Steel auth variables |
+| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. First among the Steel 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. Used with `STEEL_AUTH_TOKEN`. An incomplete pair fails closed |
+| `STEEL_AUTH_USER` | unset | Authentik username `svc-steel`. Used with `STEEL_AUTH_TOKEN`. An incomplete pair fails closed |
 | `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 for the temporary proxy shim. The library warns once. Not sent when an Authentik variable is set |
-| `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. The three variables above override it. The library warns once |
+| `USE_PASS_CLI` | enabled | Set to `false` to skip the legacy `STEEL_API_KEY` lookup. That lookup does not authenticate |
+
+`STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` with `STEEL_AUTH_TOKEN`, override `STEEL_API_KEY`. Load field `basic_auth` from 1Password vault `kontextmind`, item `Steel (svc-steel)`, with `op read` into `STEEL_AUTH_BASIC`. Do not write the value to disk. The CDP path is `/v1/devtools` with an `Authorization` header. Sessions return `websocketUrl` `wss://steel.kontextmind.com/`.
 
 Obscura's own `OBSCURA_TIMEZONE` (default `Europe/Berlin`) and `OBSCURA_CDP_TOKEN` (required only for a non-loopback bind) are read by the Obscura process, not by KXM.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.146",
+  "version": "0.7.148",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -38,6 +38,7 @@
     "test:simulations": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/simulations/*.test.ts",
     "test:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts test/simulations/*.test.ts",
     "test": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
+    "test:ci-shard": "node scripts/ci-unit-shard.mjs",
     "e2e": "node scripts/obscura.mjs --ensure && playwright test",
     "test:coverage:core": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=91 --test-coverage-branches=80 --test-coverage-functions=92 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
     "test:coverage:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=93 --test-coverage-branches=80 --test-coverage-functions=93 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts test/simulations/*.test.ts packages/core/*/tests/unit/*.test.ts",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.146",
+  "version": "0.7.148",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/claude-hook.js

@@ -724,7 +724,7 @@ function formatShipLine(ship) {
 }
 function readGitShip(cwd) {
   try {
-    const dirty = spawnSync("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
+    const dirty = spawnSync("git", ["--no-optional-locks", "-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
     if (dirty.status !== 0) return void 0;
     const isDirty = dirty.stdout.trim().length > 0;
     const upstream = spawnSync("git", ["-C", cwd, "rev-list", "--count", "@{u}..HEAD"], { encoding: "utf8", windowsHide: true });

package/plugins/kxm/dist/cli.js

@@ -50095,7 +50095,7 @@ function formatShipLine(ship) {
 }
 function readGitShip(cwd) {
   try {
-    const dirty = spawnSync10("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
+    const dirty = spawnSync10("git", ["--no-optional-locks", "-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
     if (dirty.status !== 0) return void 0;
     const isDirty = dirty.stdout.trim().length > 0;
     const upstream = spawnSync10("git", ["-C", cwd, "rev-list", "--count", "@{u}..HEAD"], { encoding: "utf8", windowsHide: true });
@@ -51929,7 +51929,7 @@ var DEFAULT_MODES_CONFIG = Object.freeze({
     browser: {
       description: "Remote Steel browser sessions and visual testing",
       tools: ["steel_session", "steel_scrape", "steel_screenshot"],
-      promptSnippet: "Use Steel on DOKS for browser automation; invoke takeover on MFA."
+      promptSnippet: "Playwright tests use Obscura. Steel is remote browsing and takeover through Caddy and Authentik; send Authorization, never a credential in the URL."
     }
   }
 });

package/plugins/kxm/dist/extension.js

@@ -37099,7 +37099,7 @@ function formatShipLine(ship) {
 }
 function readGitShip(cwd) {
   try {
-    const dirty = spawnSync("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
+    const dirty = spawnSync("git", ["--no-optional-locks", "-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
     if (dirty.status !== 0) return void 0;
     const isDirty2 = dirty.stdout.trim().length > 0;
     const upstream = spawnSync("git", ["-C", cwd, "rev-list", "--count", "@{u}..HEAD"], { encoding: "utf8", windowsHide: true });

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.146";
+var VERSION = "0.7.148";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/dist/runtime.js

@@ -33751,7 +33751,7 @@ var SteelAuthRedirectError = class extends Error {
     this.host = host;
   }
 };
-var LEGACY_STEEL_AUTH_WARNING = "kxm: STEEL_API_KEY is deprecated for Steel. Authentik forward auth accepts app passwords only as Authorization: Basic. Set STEEL_AUTH_BASIC, or STEEL_AUTH_USER and STEEL_AUTH_TOKEN. The legacy x-steel-api-key header and apiKey query parameter remain for the temporary proxy shim.\n";
+var LEGACY_STEEL_AUTH_WARNING = "kxm: STEEL_API_KEY is deprecated for Steel. Steel and Caddy do not enforce it. Set STEEL_AUTH_HEADER, or STEEL_AUTH_BASIC, or STEEL_AUTH_USER and STEEL_AUTH_TOKEN. Those override STEEL_API_KEY. Send Authorization on the request, not in the URL.\n";
 var legacySteelAuthWarned = false;
 function resetLegacySteelAuthWarningForTests() {
   legacySteelAuthWarned = false;
@@ -34057,7 +34057,7 @@ var SteelClient = class {
     return res;
   }
   /**
-   * Launch a new Steel browser session on DOKS.
+   * Launch a new Steel browser session.
    */
   async createSession(options) {
     const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs ?? 3e5;
@@ -34340,7 +34340,7 @@ var DEFAULT_MODES_CONFIG = Object.freeze({
     browser: {
       description: "Remote Steel browser sessions and visual testing",
       tools: ["steel_session", "steel_scrape", "steel_screenshot"],
-      promptSnippet: "Use Steel on DOKS for browser automation; invoke takeover on MFA."
+      promptSnippet: "Playwright tests use Obscura. Steel is remote browsing and takeover through Caddy and Authentik; send Authorization, never a credential in the URL."
     }
   }
 });

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.146",
+  "version": "0.7.148",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-browser-auth/SKILL.md

@@ -1,38 +1,37 @@
 ---
 name: kxm-browser-auth
-description: Retrieve application credentials and manage authenticated browser profiles safely via pass-cli without secret exposure.
+description: Retrieve application credentials and manage authenticated browser profiles without secret exposure. Steel uses the svc-steel credential from 1Password via op read.
 ---
 
 # KXM Browser Credentials & Authenticated Profiles
 
-Use this skill to retrieve target application credentials and manage browser session state securely using `pass-cli` as the sole authoritative store.
+Use this skill to retrieve target application credentials and manage browser session state. The Steel `svc-steel` credential comes from 1Password and is read with `op read`. It is never written to disk.
 
 ## Purpose & Scope
 
-- Enforce `pass-cli` as the single source of truth for credentials and API keys.
+- Read the Steel credential at runtime from 1Password.
 - Prevent secrets from leaking into git repositories, logs, prompts, or model-visible tool outputs.
 - Support safe storage and retrieval of session storage state and authenticated profiles.
 
 ## Credential Retrieval Guidelines
 
-### 1. Authoritative Tool: pass-cli
+### 1. Steel credential: 1Password
 
-Always retrieve credentials and API keys directly from `pass-cli`:
+`STEEL_API_KEY` is deprecated. Steel and Caddy do not enforce it. Authenticate as `svc-steel`. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`. Those override `STEEL_API_KEY`. `STEEL_API_URL` defaults to `https://steel.kontextmind.com`. `kxm` 0.7.135 or newer is required.
 
 ```bash
-# Retrieve target login password into an environment variable or piping mechanism
-pass-cli item view --vault-name "<vault>" --item-title "<title>" --field password
-
-# Retrieve the Authentik app password for Steel. The proxy accepts Authorization: Basic.
-# STEEL_AUTH_USER is the Authentik username (for example svc-steel).
-pass-cli item view --vault-name "<vault>" --item-title "<steel-item>" --field password
+# Vault kontextmind, item "Steel (svc-steel)", field basic_auth.
+# Do not redirect this into a file.
+export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"
 ```
 
+`STEEL_AUTH_USER` is `svc-steel` when you use the user and token pair. Send the value as `Authorization` on `/v1/devtools`. Never put it in the URL.
+
 ### 2. Secret Redaction Invariants
 
 - **Never** write plain passwords, session tokens, or API keys into markdown docs, commit messages, or prompts.
 - **Never** pass plain credentials as unredacted command line arguments in shared logs.
-- Use environment variable injection (`pass-cli run`) or direct in-memory pipes.
+- Keep the `op read` result in the environment of the process that calls Steel.
 
 ### 3. Profile & Storage State Management