@kontextmind/kxm 0.7.145 → 0.7.147

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.145",
+      "version": "0.7.147",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/README.md

@@ -26,8 +26,26 @@ a `default` workflow, `gates.yaml` and `template-provenance.yaml`.
 | `run/` | SSH control sockets from `kxm ssh` | Ignored |
 
 The role files under `.kxm/roles/` and the model files under `.kxm/models/`
-carry the developer policy. The assignment runner reads them at
-`refs/remotes/origin/main`.
+carry the developer policy. The assignment runner reads them at one commit
+(`HEAD`, which must be an ancestor of `refs/remotes/origin/main`). A rename
+does not rewrite a commit that still uses the old ids. An old id resolves
+only when that id is absent and the other side is present.
+
+Ids in this checkout follow one convention per kind:
+
+| Kind | Convention | This checkout |
+|---|---|---|
+| Role | The purpose: `planner`, `writer`, `reviewer-arch`, `reviewer-cli` | Unchanged |
+| Agent | The same id as its `role` | `planner`, `writer`, `reviewer-arch`, `reviewer-cli` |
+| Route | `<harness>-<model-slug>[-<provider>]`, with `.` written as `-` | `grok-grok-4-7`, `claude-fable`, `pi-qwen3-coder-plus-openrouter` |
+| Workflow | `default`, `land`, or `<role>-only` | `default`, `land`, `writer-only`, `reviewer-arch-only`, `reviewer-cli-only` |
+| Agent step | The agent's role id | `writer`, `reviewer-arch`, `reviewer-cli` |
+
+`coordinator`, `implementer`, `critic-arch`, and `critic-cli` are aliases of
+the agent ids. `implement`, `review-arch`, and `review-cli` are aliases of
+the step ids. Route aliases include `grok-native`, `fable-claude`, and
+`sol-codex`. Using an alias prints `kxm: deprecated <kind> id '<from>' resolves to '<to>'`.
+`opus-claude` does not resolve to another model.
 
 The [configuration reference](../docs/reference/config-reference.md#workspace-layout-tracked-ignored-and-state)
 describes every file, the ignore rules to add, and the state KXM keeps outside

package/.kxm/agents/{coordinator.yaml → planner.yaml}

@@ -1,6 +1,8 @@
 schema: kxm.agent.v1
 purpose: Coordinate the pinned workflow and emit schema-validated commands.
 role: planner
+aliases:
+  - coordinator
 tools:
   preset: coordinator
 defaultRepositoryAccess: read

package/.kxm/agents/{critic-arch.yaml → reviewer-arch.yaml}

@@ -1,6 +1,8 @@
 schema: kxm.agent.v1
 purpose: Architecture critic for the approved workflow change.
 role: reviewer-arch
+aliases:
+  - critic-arch
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/.kxm/agents/{critic-cli.yaml → reviewer-cli.yaml}

@@ -1,6 +1,8 @@
 schema: kxm.agent.v1
 purpose: CLI and verification critic for the approved workflow change.
 role: reviewer-cli
+aliases:
+  - critic-cli
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/.kxm/agents/{implementer.yaml → writer.yaml}

@@ -1,6 +1,8 @@
 schema: kxm.agent.v1
 purpose: Implement the approved change within the declared repository scope.
 role: writer
+aliases:
+  - implementer
 tools:
   preset: workspace-writer
 defaultRepositoryAccess: none

package/.kxm/roles/planner.yaml

@@ -3,7 +3,9 @@ id: planner
 purpose: planner
 permission: read-only
 description: Plans the change before implementation.
-# fable primary (proven planning).
+# claude-fable is primary. The Pi fallback is a different vendor.
 roster:
-  - route: fable-claude
+  - route: claude-fable
+    effort: medium
+  - route: pi-qwen3-8-flash-openrouter
     effort: medium

package/.kxm/roles/reviewer-arch.yaml

@@ -3,7 +3,9 @@ id: reviewer-arch
 purpose: reviewer-arch
 permission: read-only
 description: Independent architecture critic.
-# fable is the required arch critic.
+# claude-fable is the required arch critic. The Pi fallback is a different vendor.
 roster:
-  - route: fable-claude
+  - route: claude-fable
+    effort: medium
+  - route: pi-glm-5-3-flash-openrouter
     effort: medium

package/.kxm/roles/reviewer-cli.yaml

@@ -3,7 +3,9 @@ id: reviewer-cli
 purpose: reviewer-cli
 permission: read-only
 description: Independent CLI and docs critic.
-# sol is the required cli critic.
+# codex-gpt-5-6-sol is the required cli critic. The Pi fallback is a different vendor.
 roster:
-  - route: sol-codex
+  - route: codex-gpt-5-6-sol
+    effort: low
+  - route: pi-qwen3-8-flash-openrouter
     effort: low

package/.kxm/roles/writer.yaml

@@ -5,8 +5,11 @@ permission: edit
 description: Primary implementation agent.
 # Rotation priority = order. Effort default: medium for implementation.
 roster:
-  - route: grok-native
+  - route: grok-grok-4-7
     effort: medium
-  - route: qwen-openrouter-pi
+  - route: pi-qwen3-coder-plus-openrouter
+    effort: medium
+  - route: agy-gemini-3-8-flash-high
+    effort: medium
+  - route: agy-gemini-3-8-flash-medium
     effort: medium
-  - route: gemini-agy

package/.kxm/workflows/default.yaml

@@ -1,37 +1,45 @@
 schema: kxm.workflow.v1
 description: Canonical 4-stage KXM delivery workflow
-coordinator: coordinator
+coordinator: planner
 limits:
   maxTransitions: 8
 steps:
-  - id: implement
+  - id: writer
+    aliases:
+      - implement
     kind: agent
-    agent: implementer
+    agent: writer
     repositories:
       control: write
     maxAttempts: 3
     on:
-      passed: review-arch
+      passed: reviewer-arch
       failed:
         target: $terminal
         terminalStatus: failed
-  - id: review-arch
+  - id: reviewer-arch
+    aliases:
+      - review-arch
+      - critic-arch
     kind: agent
-    agent: critic-arch
+    agent: reviewer-arch
     maxAttempts: 2
     on:
-      passed: review-cli
+      passed: reviewer-cli
       failed:
-        target: implement
+        target: writer
         maxTransitions: 2
-  - id: review-cli
+  - id: reviewer-cli
+    aliases:
+      - review-cli
+      - critic-cli
     kind: agent
-    agent: critic-cli
+    agent: reviewer-cli
     maxAttempts: 2
     on:
       passed: verify
       failed:
-        target: implement
+        target: writer
         maxTransitions: 2
   - id: verify
     kind: gate
@@ -45,5 +53,5 @@ steps:
         target: $terminal
         terminalStatus: completed
       implementation-failure:
-        target: implement
+        target: writer
         maxTransitions: 2

package/.kxm/workflows/land.yaml

@@ -3,7 +3,7 @@
 # `kxm run land --dry-run --json`.
 schema: kxm.workflow.v1
 description: Land the current branch through verify, docs, rebase, merge, release, and milestone gates.
-coordinator: coordinator
+coordinator: planner
 limits:
   maxTransitions: 24
 steps:

package/.kxm/workflows/{review-arch-only.yaml → reviewer-arch-only.yaml}

@@ -1,12 +1,16 @@
 schema: kxm.workflow.v1
 description: One read-only architecture critic step.
-coordinator: coordinator
+aliases:
+  - review-arch-only
+coordinator: planner
 limits:
   maxTransitions: 2
 steps:
-  - id: critic-arch
+  - id: reviewer-arch
+    aliases:
+      - critic-arch
     kind: agent
-    agent: critic-arch
+    agent: reviewer-arch
     repositories:
       control: read
     maxAttempts: 1

package/.kxm/workflows/{review-cli-only.yaml → reviewer-cli-only.yaml}

@@ -1,12 +1,16 @@
 schema: kxm.workflow.v1
 description: One read-only CLI critic step.
-coordinator: coordinator
+aliases:
+  - review-cli-only
+coordinator: planner
 limits:
   maxTransitions: 2
 steps:
-  - id: critic-cli
+  - id: reviewer-cli
+    aliases:
+      - critic-cli
     kind: agent
-    agent: critic-cli
+    agent: reviewer-cli
     repositories:
       control: read
     maxAttempts: 1

package/.kxm/workflows/{implement-only.yaml → writer-only.yaml}

@@ -1,12 +1,16 @@
 schema: kxm.workflow.v1
-description: One implementer step with a drive receipt.
-coordinator: coordinator
+description: One writer step with a drive receipt.
+aliases:
+  - implement-only
+coordinator: planner
 limits:
   maxTransitions: 2
 steps:
-  - id: implement
+  - id: writer
+    aliases:
+      - implement
     kind: agent
-    agent: implementer
+    agent: writer
     repositories:
       control: write
     maxAttempts: 1

package/CHANGELOG.md

@@ -13,8 +13,9 @@ All notable user-facing changes are documented here. The project follows [Semant
   effective value is written on the one-shot evidence. A `cancelling` run whose
   executing attempt's child already exited settles `executing_unrecorded`.
   Admission is released when a drive closes with a handoff, so a later drive
-  is admitted, and `runs status` names the attempt. `implement-only`,
-  `review-arch-only`, and `review-cli-only` are one-step workflows, driven with
+  is admitted, and `runs status` names the attempt. `writer-only`,
+  `reviewer-arch-only`, and `reviewer-cli-only` are one-step workflows
+  (`implement-only`, `review-arch-only`, and `review-cli-only` still resolve), driven with
   `kxm lane run <unit> --workflow <id> --brief <file>`. See
   [kxm lane](docs/reference/cli-reference.md#kxm-lane),
   [runs status](docs/reference/cli-reference.md#kxm-runs-status),
@@ -141,6 +142,44 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Docs match the 2026-09-27 Steel and machine-account infrastructure.**
+  Steel (`steel.kontextmind.com`, alias `steel.theneuro.me`) is reached only
+  through Caddy on `kxmd-proxy` (VM 230) and Authentik forward auth. Direct
+  LAN, tailnet, and host-forward access is blocked. Sessions return
+  `websocketUrl` `wss://steel.kontextmind.com/` (previously
+  `ws://steel-browser/`). The CDP path is `/v1/devtools` with an
+  `Authorization` header. Allowed groups are `steel-users`, `kxmd-users`,
+  `kxmd-admins`, and `kxmd-owners`. `STEEL_API_URL` defaults to
+  `https://steel.kontextmind.com`. `STEEL_API_KEY` is deprecated and is not
+  enforced by Steel or Caddy. Migrate to `STEEL_AUTH_HEADER`, then
+  `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`; those
+  override the key. The `svc-steel` credential is 1Password vault
+  `kontextmind`, item `Steel (svc-steel)`, field `basic_auth`, read with
+  `op read` and never written to disk. Steel requires `kxm` 0.7.135 or
+  newer. Playwright stays on Obscura ([ADR-0005](docs/adr/ADR-0005-obscura-default-playwright.md)).
+  The Proxmox boot order and VM names are in
+  [Deploy KXM](docs/operations/deploy.md#boot-the-kxmd-proxmox-host).
+  Machine accounts follow
+  [ADR-0006](docs/adr/ADR-0006-machine-account-names.md). The DOKS deployment
+  record is superseded by
+  [ADR-0007](docs/adr/ADR-0007-steel-caddy-authentik.md).
+
+- **Workforce ids use one convention, and old ids still resolve.**
+  Role ids stay `planner`, `writer`, `reviewer-arch`, and `reviewer-cli`.
+  Agent ids and agent-step ids use those same names. Route ids are
+  `<harness>-<model-slug>[-<provider>]`. `kxm init` writes `planner.yaml`
+  and `writer.yaml`; `coordinator` and `implementer` remain aliases.
+  `opus-claude` is removed because `opus` is not an admitted selector.
+  `qwen-token-plan/*` and `zai-coding-cn/*` left `.kxm/routes.yaml` because
+  those harnesses are not allowlisted.   `node scripts/workforce-lint.mjs`
+  fails `npm run check` and `npm run validate:pr` when a route, a roster
+  entry, or an id breaks the convention, and when a roster entry omits
+  `effort` or names one outside `off`, `minimal`, `low`, `medium`, `high`,
+  `xhigh`, and `max`. An admitted selector with no route is a warning.
+  The Claude helper accepts `fable` only. #343's architecture critic ran on
+  `opus` because the justfile recipe review-arch hardcoded that model while
+  `reviewer-arch` listed only `fable-claude`. That recipe is gone; a request
+  for `opus` fails closed.
 - **Dispatch reads role and model files, and agents bind a role.**
   `scripts/roster-policy.mjs` builds the developer policy from
   `.kxm/models/*.yaml` and `.kxm/roles/*.yaml` at `refs/remotes/origin/main`.
@@ -148,9 +187,9 @@ All notable user-facing changes are documented here. The project follows [Semant
   and that role's roster. A step `model` does not override that route.
   `kxm routes` prints `policy` (`admitted`, `disabled`) and `membership`
   from the role files. `.kxm/routes.yaml` keeps admitted and disabled
-  selectors. `reviewer-arch` resolves to `fable-claude`. `opus-claude` is
-  admitted and named by no roster, so it is absent from `routes` and the
-  lineups. `gemini-agy` is in the writer lineup. An agent `tools.preset`
+  selectors. `reviewer-arch` resolves to `claude-fable` (alias `fable-claude`).
+  `agy-gemini-3-8-flash-high` (alias `gemini-agy`) is in the writer lineup.
+  An agent `tools.preset`
   may only narrow its role preset; that rule is recorded and enforced in P3.
 
 - **Role and model files are live `kxm.role.v2` and `kxm.model.v2`.**
@@ -455,9 +494,10 @@ All notable user-facing changes are documented here. The project follows [Semant
   into `chromium.connectOverCDP`. Obscura stays the default and sends no Steel
   headers. `STEEL_AUTH_HEADER` overrides the value. The CDP URL omits the credential when
   those variables are set. A 302 to the identity provider fails closed and does
-  not follow the login redirect. `STEEL_API_KEY` still sends the legacy
-  `x-steel-api-key` header and `apiKey` query parameter for the temporary proxy
-  shim, and warns once. See
+  not follow the login redirect. `STEEL_API_KEY` is deprecated. Steel and
+  Caddy do not enforce it. `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then
+  `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN` override it. A client that still
+  has only the legacy key warns once and is not authenticated. See
   [Browser automation](docs/guides/browser-automation.md).
 
 ### Removed

package/docs/README.md

@@ -76,7 +76,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 | [Architecture](concepts/architecture.md) | Integrators, maintainers | The components, message and workflow lifecycles, and KXM's limits |
 | [Trust model](concepts/trust-model.md) | Operators, security reviewers | Who holds which credential, project boundaries, and what provenance proves |
 | [Data and storage](concepts/data-and-storage.md) | Operators, security reviewers | What each store holds, where it lives and how long it is kept |
-| [Architecture decision records](adr/README.md) | Maintainers | The decision records: [browser automation](adr/ADR-0002-browser-automation-steel-doks.md), [Obscura for Playwright](adr/ADR-0005-obscura-default-playwright.md), [SQLite-only store](adr/ADR-0003-sqlite-only-store.md), [edge identity](adr/ADR-0004-edge-identity-authentik.md) |
+| [Architecture decision records](adr/README.md) | Maintainers | The decision records: [browser automation](adr/ADR-0002-browser-automation-steel-doks.md), [Steel through Caddy](adr/ADR-0007-steel-caddy-authentik.md), [Obscura for Playwright](adr/ADR-0005-obscura-default-playwright.md), [machine account names](adr/ADR-0006-machine-account-names.md), [SQLite-only store](adr/ADR-0003-sqlite-only-store.md), [edge identity](adr/ADR-0004-edge-identity-authentik.md) |
 | [KXM contract package](contracts/README.md) | Maintainers, reviewers | The normative specifications for the local-first architecture, listed below |
 
 ### Contracts

package/docs/adr/ADR-0002-browser-automation-steel-doks.md

@@ -4,13 +4,13 @@ id: "ADR-0002"
 type: "adr"
 title: "Self-hosted Steel on DOKS for reusable browser automation and human takeover"
 project: "kxm"
-status: "accepted"
+status: "superseded"
 owner: "@operator"
 created: "2026-09-14"
 updated: "2026-09-27"
 authority: "decision"
 confidence: "verified"
-summary: "Adopt self-hosted Steel on DigitalOcean Kubernetes (DOKS) with agent-browser and Playwright as KXM's primary browser automation infrastructure."
+summary: "The 2026-09-14 choice of self-hosted Steel. The DOKS deployment in this record was superseded on 2026-09-27 by ADR-0007. Obscura is the Playwright default (ADR-0005)."
 tags: ["architecture", "decision", "browser", "steel", "doks", "playwright"]
 related: ["docs/guides/browser-automation.md", "docs/guides/agent-skills.md", "docs/adr/ADR-0005-obscura-default-playwright.md"]
 details:
@@ -20,11 +20,15 @@ details:
     - "Provide dual exploratory (agent-browser) and regression (Playwright) interfaces"
     - "Enforce strict credential isolation via pass-cli"
   supersedes: null
-  superseded_by: null
+  superseded_by: "ADR-0007"
 ---
 
 # ADR-0002: Self-hosted Steel on DOKS for reusable browser automation
 
+## Status
+
+Superseded on 2026-09-27 by [ADR-0007](ADR-0007-steel-caddy-authentik.md) for where Steel runs and how clients authenticate. [ADR-0005](ADR-0005-obscura-default-playwright.md) keeps Obscura as the Playwright default. The sections below are the 2026-09-14 decision. They are not the current deployment. Steel and Caddy do not enforce `STEEL_API_KEY`.
+
 ## Context and problem statement
 
 AI coding agents and orchestration workflows in KXM require browser interaction for UI exploration, DOM mapping, bug reproduction, and end-to-end regression testing. Existing approaches suffered from three core issues:
@@ -100,8 +104,7 @@ AI coding agents and orchestration workflows in KXM require browser interaction
 
 - **Verification**: Health endpoint `$STEEL_API_URL/v1/health` verified with HTTP 200 and Let's Encrypt TLS.
 - **Integration Test**: `test/core/browser.test.ts` validates session lifecycle, CDP endpoint formatting, takeover transitions, and secret redaction.
-- **Security Check**: `pass-cli` verified as the authoritative store for Steel credentials in the operators' password manager.
-- **Edge auth (2026-09-27)**: `steel.kontextmind.com` and `steel.theneuro.me`, including the CDP WebSocket, are behind Authentik forward auth. Steel does not check `STEEL_API_KEY`. Clients send `Authorization: Basic`. Unauthenticated requests are redirected to `id.kxmd.dev`. The legacy `x-steel-api-key` header and `apiKey` query parameter remain a temporary proxy shim.
+- **Security Check**: `pass-cli` was the credential store named in this 2026-09-14 decision. Current clients read the `svc-steel` credential with `op read`, as [ADR-0007](ADR-0007-steel-caddy-authentik.md) records.
 
 ## Related
 

package/docs/adr/ADR-0005-obscura-default-playwright.md

@@ -12,7 +12,7 @@ authority: "decision"
 confidence: "verified"
 summary: "Playwright testing and verification connect to pinned Obscura v0.2.3 over CDP. Steel stays the browser for human takeover, MFA, and the live session viewer."
 tags: ["architecture", "decision", "browser", "obscura", "playwright", "cdp"]
-related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md"]
+related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/adr/ADR-0007-steel-caddy-authentik.md", "docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md"]
 details:
   decision_drivers:
     - "Playwright tests must run without a Steel cluster or a Playwright-managed browser download"
@@ -26,7 +26,7 @@ details:
 
 ## Status
 
-Accepted on 2026-09-27. This record does not supersede [ADR-0002](ADR-0002-browser-automation-steel-doks.md). Steel remains the browser for human takeover, MFA, and the live session viewer.
+Accepted on 2026-09-27. This record does not supersede [ADR-0002](ADR-0002-browser-automation-steel-doks.md). [ADR-0007](ADR-0007-steel-caddy-authentik.md) is the current Steel deployment. Steel remains the browser for remote and hosted sessions, human takeover, MFA, and the live session viewer.
 
 ## Context
 
@@ -79,7 +79,8 @@ Obscura v0.2.3 is a headless Chromium build that speaks the Chrome DevTools Prot
 
 ## Related
 
-- [ADR-0002: Self-hosted Steel on DOKS](ADR-0002-browser-automation-steel-doks.md)
+- [ADR-0002: Self-hosted Steel on DOKS (superseded deployment)](ADR-0002-browser-automation-steel-doks.md)
+- [ADR-0007: Steel through Caddy and Authentik](ADR-0007-steel-caddy-authentik.md)
 - [Browser automation](../guides/browser-automation.md)
 - [How do I connect Playwright to Obscura?](../kb/how-to-connect-playwright-to-obscura.md)
 - [Environment variables and limits](../reference/configuration.md#browser-automation)

package/docs/adr/ADR-0006-machine-account-names.md

@@ -0,0 +1,90 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0006"
+type: "adr"
+title: "Machine account names"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-27"
+updated: "2026-09-27"
+authority: "decision"
+confidence: "verified"
+summary: "New machine accounts use svc-<system>-<purpose>, or svc-<tenant>-<system>-<purpose> when they belong to one tenant. Test accounts add a test- prefix and stay out of production groups."
+tags: ["architecture", "decision", "authentik", "accounts"]
+related: ["docs/adr/ADR-0004-edge-identity-authentik.md", "docs/operations/deploy.md", "docs/contributing/operating-rules.md"]
+details:
+  decision_drivers:
+    - "One readable pattern for platform and tenant machine accounts"
+    - "Test and witness accounts must be unable to enter production groups"
+    - "Existing names stay until an approved inventory authorizes a rename"
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0006: Machine account names
+
+## Status
+
+Accepted on 2026-09-27.
+
+## Context
+
+Authentik machine accounts were created with local names such as `kxm-agent`, `kxm-witness-*`, `witness9`, `kxmdproof`, `kxm-provisioner`, and `agent-ilo-asus`. Those names do not say whether the account is platform-wide, tenant-scoped, or a test identity. Renaming them without an inventory would drop grants that still point at the old name.
+
+## Decision drivers
+
+1. A reader can tell the scope of an account from its name.
+2. Test, witness, and proof accounts must not sit in production groups.
+3. Authentik's own accounts keep the names Authentik assigns.
+4. A rename of an account that already exists waits for an approved inventory.
+
+## Considered options
+
+1. **`svc-` names, with a `test-` prefix for non-production accounts.**
+2. **Keep creating ad hoc names.**
+3. **Put every machine account under Authentik's `ak-*` prefix.**
+
+### Option 1: `svc-` names (chosen)
+
+- Good, because platform and tenant scope are visible in the name.
+- Good, because a `test-` prefix can be excluded from production groups.
+- Bad, because accounts that already exist keep their old names until an inventory is approved.
+
+### Option 2: ad hoc names (rejected)
+
+- Good, because nothing already issued has to change.
+- Bad, because the next account repeats the same ambiguity.
+
+### Option 3: `ak-*` for every machine account (rejected)
+
+- Good, because one prefix would match Authentik-managed users.
+- Bad, because `ak-*` is Authentik's own namespace for outposts and internal users.
+
+## Decision
+
+Create machine accounts with these shapes. `<tenant>` is the tenant slug.
+
+| Scope | Name |
+|---|---|
+| Platform-wide | `svc-<system>-<purpose>` |
+| Tenant-scoped | `svc-<tenant>-<system>-<purpose>` |
+| Test, witness, or proof | The same shapes with a `test-` prefix |
+
+A `test-` account is never a member of a production group.
+
+Authentik-managed accounts are exempt. That includes outposts and any account whose name starts with `ak-`.
+
+The `svc-steel` credential that reaches the Steel server is the account operators use today. This record does not rename it. Names already recorded in plans and handoffs, including `kxm-agent`, `kxm-witness-*`, `witness9`, `kxmdproof`, `kxm-provisioner`, and `agent-ilo-asus`, stay as written until an approved inventory lists each rename. Do not invent a replacement for a specific account.
+
+## Consequences
+
+- New accounts follow the table above.
+- This repository does not assign new names to the recorded accounts.
+- Group names such as `kxmd-owners` are groups, not machine accounts, and this record does not rename them.
+
+## Related
+
+- [Edge identity](ADR-0004-edge-identity-authentik.md)
+- [Deploy KXM](../operations/deploy.md#name-machine-accounts)
+- [Operating rules](../contributing/operating-rules.md)

package/docs/adr/ADR-0007-steel-caddy-authentik.md

@@ -0,0 +1,97 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0007"
+type: "adr"
+title: "Steel is reached only through Caddy and Authentik"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-27"
+updated: "2026-09-27"
+authority: "decision"
+confidence: "verified"
+summary: "The Steel server steel.kontextmind.com is an LXC behind Caddy and Authentik forward auth. Clients use the svc-steel credential. STEEL_API_KEY is not enforced. Playwright stays on Obscura."
+tags: ["architecture", "decision", "browser", "steel", "authentik"]
+related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/adr/ADR-0005-obscura-default-playwright.md", "docs/guides/browser-automation.md", "docs/adr/ADR-0006-machine-account-names.md"]
+details:
+  decision_drivers:
+    - "Steel must not be reachable on the LAN, the tailnet, or a host forward"
+    - "Authentik groups are the access list"
+    - "Credentials stay in 1Password and are read into the process only"
+  supersedes: "ADR-0002"
+  superseded_by: null
+---
+
+# ADR-0007: Steel is reached only through Caddy and Authentik
+
+## Status
+
+Accepted on 2026-09-27. This record supersedes the DigitalOcean Kubernetes deployment in [ADR-0002](ADR-0002-browser-automation-steel-doks.md). [ADR-0005](ADR-0005-obscura-default-playwright.md) still makes Obscura the Playwright default. Steel remains the browser for remote and hosted sessions, human takeover, MFA, and the live session viewer.
+
+## Context
+
+Steel now runs as LXC 240 on the Proxmox host, at startup order 40. Its public name is `steel.kontextmind.com`. `steel.theneuro.me` is an alias of that same server. Caddy on VM 230 (`kxmd-proxy`) is the only listener, and it forwards authentication to Authentik. Direct LAN, tailnet, and host-forward access is blocked.
+
+Sessions return `websocketUrl` `wss://steel.kontextmind.com/`. The previous value was `ws://steel-browser/`. Clients connect Chrome DevTools Protocol at `/v1/devtools` and send `Authorization` on the handshake. The URL does not carry a credential.
+
+Steel and Caddy do not enforce `STEEL_API_KEY`. Clients authenticate as the Authentik user `svc-steel`.
+
+## Decision drivers
+
+1. The browser host is not a second network entrance beside the proxy.
+2. Membership in a known Authentik group is the allow list.
+3. The credential is read at runtime and is not written to disk.
+4. Playwright tests keep the Obscura default from ADR-0005.
+
+## Considered options
+
+1. **Caddy plus Authentik forward auth, with direct paths blocked.**
+2. **Keep the DOKS ingress and a Steel API key.**
+3. **Publish the LXC on the tailnet or a host forward.**
+
+### Option 1: Caddy and Authentik only (chosen)
+
+- Good, because one proxy terminates TLS and applies the group check.
+- Good, because a client that still sends `STEEL_API_KEY` does not get a session.
+- Bad, because clients older than `kxm` 0.7.135 still expect `ws://steel-browser/`.
+
+### Option 2: DOKS and `STEEL_API_KEY` (rejected)
+
+- Good, because existing scripts that sent `x-steel-api-key` would keep working.
+- Bad, because that cluster is no longer where Steel runs, and neither Steel nor Caddy checks the key.
+
+### Option 3: tailnet or host-forward access (rejected)
+
+- Good, because an operator on the tailnet could open the API without the proxy.
+- Bad, because it bypasses Authentik and the group check.
+
+## Decision
+
+Reach Steel only at `https://steel.kontextmind.com` (alias `steel.theneuro.me`) through Caddy and Authentik forward auth. `STEEL_API_URL` defaults to `https://steel.kontextmind.com`.
+
+Authenticate with the `svc-steel` credential. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` together with `STEEL_AUTH_TOKEN`. Those variables override `STEEL_API_KEY`. `STEEL_API_KEY` is deprecated: Steel and Caddy do not enforce it, and a value in the URL is not accepted. Migrate by setting one of the three Authentik variables and dropping the key from the environment.
+
+Read the credential from 1Password at runtime. The vault is `kontextmind`, the item is `Steel (svc-steel)`, and the field is `basic_auth`. Use `op read`. Do not write the value to disk.
+
+```bash
+export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"
+```
+
+The CDP path is `/v1/devtools` with an `Authorization` header.
+
+These Authentik groups may use the server: `steel-users`, `kxmd-users`, `kxmd-admins`, and `kxmd-owners`.
+
+`kxm` 0.7.135 or newer is required. Playwright testing stays on Obscura unless `KXM_BROWSER=steel`.
+
+## Consequences
+
+- A connection to the LXC by LAN address, tailnet address, or host forward fails.
+- A client that only sets `STEEL_API_KEY` is not authenticated.
+- The `svc-steel` name is the live account. [ADR-0006](ADR-0006-machine-account-names.md) does not rename it ahead of an approved inventory.
+
+## Related
+
+- [ADR-0002](ADR-0002-browser-automation-steel-doks.md)
+- [ADR-0005](ADR-0005-obscura-default-playwright.md)
+- [Browser automation](../guides/browser-automation.md)
+- [Deploy KXM](../operations/deploy.md#boot-the-kxmd-proxmox-host)

package/docs/adr/README.md

@@ -7,10 +7,12 @@ An architecture decision record (ADR) captures one significant decision about KX
 | ADR | Decision | Status | Date |
 |---|---|---|---|
 | [ADR-001](../contracts/architecture.md) | Local Runtime, project authority, and aggregate hub | Accepted target | — |
-| [ADR-0002](ADR-0002-browser-automation-steel-doks.md) | Self-hosted Steel for reusable browser automation and human takeover | Accepted | 2026-09-14 |
+| [ADR-0002](ADR-0002-browser-automation-steel-doks.md) | Self-hosted Steel on DOKS (deployment superseded) | Superseded by ADR-0007 | 2026-09-14 |
 | [ADR-0003](ADR-0003-sqlite-only-store.md) | SQLite as the only store | Accepted | 2026-09-17 |
 | [ADR-0004](ADR-0004-edge-identity-authentik.md) | Edge identity with Authentik; the hub owns no browser identity | Accepted | 2026-09-20 |
 | [ADR-0005](ADR-0005-obscura-default-playwright.md) | Obscura is the default browser for Playwright; Steel stays for takeover | Accepted | 2026-09-27 |
+| [ADR-0006](ADR-0006-machine-account-names.md) | Machine account names (`svc-` shapes, `test-` prefix, Authentik exemptions) | Accepted | 2026-09-27 |
+| [ADR-0007](ADR-0007-steel-caddy-authentik.md) | Steel is reached only through Caddy and Authentik | Accepted | 2026-09-27 |
 
 ADR-001 is the original decision record for the local Runtime. It lives with the contracts in [`docs/contracts/architecture.md`](../contracts/architecture.md) because it is the root of those contracts, and it keeps its original three-digit number. Records in this directory continue the sequence from 0002. There is no ADR-0001.