@kontextmind/kxm 0.7.0 → 0.7.10

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.0",
+      "version": "0.7.10",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/roles/writer.yaml

@@ -1,5 +1,7 @@
 schema: kxm.role.v1
 id: writer
 roster:
+  - model: xai/grok-4.6
+    enabled: true
   - model: openrouter/qwen/qwen3-coder-plus
     enabled: true

package/docs/README.md

@@ -9,6 +9,8 @@ This documentation is organized by task. Start with the guide that matches what
 | [Configuration](configuration.md) | Users and operators | Understand every supported setting and default |
 | [Architecture](architecture.md) | Maintainers and integrators | Learn the component boundaries and message lifecycle |
 | [Agent Skills](agent-skills.md) | Users and integrators | Comprehensive skill suite covering all KXM commands with progressive disclosure |
+| [Browser automation](browser-automation.md) | Developers and operators | Self-hosted Steel on DOKS, agent-browser, Playwright, pass-cli, and human takeover |
+| [Skills](skills.md) | Operators and skill authors | Governed candidate lifecycle; also the [repository work delivery](skills/repo-work-delivery.md) skill |
 | [Operations](operations.md) | Hub operators | Run, monitor, secure, and recover the service |
 | [Troubleshooting](troubleshooting.md) | Everyone | Diagnose common installation and delivery failures |
 | [Test matrix](test-matrix.md) | Users and maintainers | Map features and use cases to automated evidence |
@@ -16,6 +18,7 @@ This documentation is organized by task. Start with the guide that matches what
 | [Peer provenance and quorum gates](provenance-gates.md) | Workflow authors and security reviewers | Require durable replies from eligible peer identities without overstating the trust guarantee |
 | [Continuous improvement](continuous-improvement.md) | Product and engineering leads | Turn run evidence into reviewed workflow improvements |
 | [Workflow guide](workflow-guide.md) | Workflow designers and operators | Area -> Workflow -> Stage -> Role taxonomy with documentation slugs, dated research candidates, and selection policy |
+| [Templates](templates/README.md) | Workflow authors | Markdown templates for features, ADRs, reviews, runbooks, and related artifacts |
 | [Agent Envelopes & Quality Gates](agent-communication-envelopes-and-gates.md) | Multi-agent workflow engineers | Production communication envelopes, quality gates, and work loops |
 | [Assignment runner](assignment-runner.md) | Maintainers and developers | Native developer assignments, deterministic witness verification, and multi-vendor dual-critic acceptance |
 | [This host's Pi packages](operator-pi-packages.md) | Maintainers on this development host | Snapshot of operator `pi list` packages and file extensions; not a KXM install requirement |

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

@@ -0,0 +1,103 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0002"
+type: "adr"
+title: "Self-Hosted Steel on DOKS for Reusable Browser Automation and Human Takeover"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+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."
+tags: ["architecture", "decision", "browser", "steel", "doks", "playwright"]
+related: ["docs/browser-automation.md", "docs/agent-skills.md"]
+details:
+  decision_drivers:
+    - "Eliminate per-minute SaaS browser provider costs"
+    - "Support unified same-session human takeover for MFA and sensitive authentication"
+    - "Provide dual exploratory (agent-browser) and regression (Playwright) interfaces"
+    - "Enforce strict credential isolation via pass-cli"
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0002: Self-Hosted Steel on DOKS for Reusable Browser Automation
+
+## Context & 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:
+
+1. **High SaaS Costs**: Commercial cloud providers (e.g. Browserbase) charge steep per-session and per-minute pricing that conflicts with KXM's low-cost operating priority.
+2. **Disconnected Human Takeover**: When login challenges, MFA prompts, or CAPTCHAs occur, local or headless cloud browsers cannot easily hand the live session over to a human operator and seamlessly resume without destroying session state.
+3. **Tool Fragmentation**: Exploratory navigation needs a fast, token-efficient terminal CLI (`agent-browser`), while testing needs durable, assertion-rich frameworks (`Playwright`).
+
+## Decision Drivers
+
+1. **Operating Cost Control**: Keep infrastructure expenses predictable by utilizing our existing DigitalOcean Kubernetes Service (DOKS) cluster (`k8s-agentic-hub`).
+2. **Unified Same-Session Takeover**: Enable a human to interact with the exact same browser tab and session state during authentication gates before handing control back to the agent.
+3. **Dual Automation Interfaces**: Support `agent-browser` for discovery and `Playwright` for permanent regression tests over standard Chrome DevTools Protocol (CDP).
+4. **Authoritative Credential Management**: Ensure `pass-cli` remains the exclusive source of truth for secrets and API keys.
+
+## Considered Options
+
+- **Option A**: Self-hosted Steel (`steel-dev/steel-browser`) deployed on DOKS with Ingress-NGINX and TLS.
+- **Option B**: Paid SaaS browser providers (e.g., Browserbase, Steel Cloud).
+- **Option C**: Local headless Chrome instances spawned on developer workstations.
+
+## Evaluation & Tradeoff Matrix
+
+### Option A: Self-hosted Steel on DOKS (Chosen)
+
+- **Good, because**: Zero marginal per-session fees; fully self-hosted on our Kubernetes cluster.
+- **Good, because**: Built-in REST API, CDP WebSocket proxy, and live session viewer UI (`/ui`).
+- **Good, because**: Both `Playwright` and `agent-browser` connect seamlessly over standard CDP (`wss://steel.kontextmind.com/v1/devtools`).
+- **Good, because**: Dedicated shared memory (`/dev/shm`) and resource limits prevent workstation degradation.
+- **Bad, because**: Requires managing Kubernetes deployment and periodic orphaned session sweeping.
+
+### Option B: Paid SaaS Browser Provider
+
+- **Good, because**: Managed scaling and proxy pools.
+- **Bad, because**: Violates the core cost-efficiency constraint; introduces recurring credit card charges and third-party data transmission risks.
+
+### Option C: Local Chrome Instances
+
+- **Good, because**: No cluster deployment needed.
+- **Bad, because**: High workstation memory and CPU pressure; fragile cross-platform headless setups; cannot easily share live debug sessions across multi-agent environments.
+
+## Decision Outcome
+
+**Chosen Option**: **Option A (Self-hosted Steel on DOKS)**.
+
+### Architecture
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                      KXM Agent / Herdr                      │
+│   (kxm-browser-session, kxm-browser-takeover, pass-cli)     │
+└───────────────┬─────────────────────────────┬───────────────┘
+                │ REST API (create/release)   │ CDP WebSocket
+                ▼                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 DigitalOcean Kubernetes (DOKS)              │
+│                 https://steel.kontextmind.com               │
+│                                                             │
+│   ┌─────────────────────┐       ┌────────────────────────┐  │
+│   │   Steel API & CDP   │◄─────►│    Chromium Sandbox    │  │
+│   │     (Fastify)       │       │    (/dev/shm 2Gi)      │  │
+│   └──────────┬──────────┘       └────────────────────────┘  │
+│              │                                              │
+│              ▼                                              │
+│   ┌─────────────────────┐                                   │
+│   │   Session Viewer    │ ◄─── Human Takeover (MFA/Auth)    │
+│   │       (/ui)         │                                   │
+│   └─────────────────────┘                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Confirmation & Verification Strategy
+
+- **Verification**: Health endpoint `https://steel.kontextmind.com/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_API_KEY` under vault `AI Provider Keys`.

package/docs/agent-skills.md

@@ -10,7 +10,7 @@ authority, admit new writers, or replace trusted `.kxm/roster.json` policy.
 | Feature Area | Skill | Commands Covered | Purpose |
 |---|---|---|---|
 | Core Routing | `kxm` | — | Select the right suite skill; state universal safety rules and portable CLI convention |
-| Project Setup | `kxm-project-setup` | `init`, `migrate`, `trust`, `config`, `completion` | Initialize, migrate, review permission changes, configure, and add shell completion |
+| Project Setup | `kxm-project-setup` | `init`, `migrate`, `trust`, `config`, `completion` | Initialize, migrate, review permission changes, configure, and install shell completion |
 | Harness & Auth | `kxm-harness-auth` | `harness`, `auth`, `update`, `runtime`, `agent` | Inspect authenticated harness capability and operate supported runtimes/workers |
 | Hub Operations | `kxm-hub-ops` | `hub`, `backup`, `restore` | Run and protect the local hub and its durable SQLite state |
 | Session Management | `kxm-session` | `session`, `dash`, `studio` | Resume/inspect operator work and use UI capabilities each harness supports |
@@ -23,6 +23,20 @@ authority, admit new writers, or replace trusted `.kxm/roster.json` policy.
 | Routing & Improve | `kxm-routing-improve` | `routing`, `improve` | Inspect real route quality/cost and propose reviewed improvements |
 | Tasks & Goals | `kxm-tasks` | `suggest`, `goal`, `task` | Recommend workflows and manage goals/tasks with SCM/tracker boundaries |
 
+## Browser Automation Skills
+
+KXM includes dedicated skills for remote browser automation on self-hosted Steel (DOKS), exploratory navigation via `agent-browser`, testing with `Playwright`, and visual feedback. See [Browser Automation Guide](browser-automation.md) and [ADR-0002](adr/ADR-0002-browser-automation-steel-doks.md).
+
+| Feature Area | Skill | Purpose |
+|---|---|---|
+| Browser Sessions | `kxm-browser-session` | Start, attach, inspect, and release Steel sessions on DOKS |
+| Human Takeover | `kxm-browser-takeover` | Handoff protocol for MFA, login, CAPTCHA, and sensitive consent |
+| Credentials & Profiles | `kxm-browser-auth` | Retrieve credentials from `pass-cli` and manage authenticated profiles safely |
+| Exploration | `kxm-browser-explore` | Exploratory navigation, DOM inspection, and workflow mapping via `agent-browser` |
+| Reproduction & Verify | `kxm-browser-verify` | Reproduce UI bugs, gather evidence, and author durable Playwright tests |
+| Diagnostics & Recovery | `kxm-browser-diagnostics` | Investigate Steel connectivity, CDP errors, timeouts, and orphan cleanup |
+| Section Annotation | `kxm-browser-annotate` | Capture DOM sections, attach structured annotations, and feed changes to agents |
+
 ## Installation and Discovery
 
 ### For Pi Users
@@ -89,7 +103,10 @@ The skills in this suite (`kxm-*`) are bundled and operational by default. They
 
 Separately, `kxm skills` manages community or experimental candidates through
 create/evaluate/promote/reject/verify. Those governed skills are distinct from
-this bundled suite. Telemetry cannot auto-promote a skill.
+this bundled suite. Telemetry cannot auto-promote a skill. See
+[Skill candidate lifecycle](skills.md) for the full lifecycle, and
+[Repository work delivery](skills/repo-work-delivery.md) for converting a
+repository request into a delivery prompt.
 
 ## Development and Maintenance
 

package/docs/browser-automation.md

@@ -0,0 +1,116 @@
+---
+schema: "kxm.doc.v1"
+id: "GUIDE-BROWSER-001"
+type: "guide"
+title: "KXM Browser Automation Guide"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Comprehensive guide to browser automation in KXM using self-hosted Steel on DOKS, agent-browser, Playwright, pass-cli, and human takeover."
+tags: ["browser", "automation", "steel", "playwright", "agent-browser", "doks"]
+related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/agent-skills.md"]
+---
+
+# KXM Browser Automation Guide
+
+This guide describes how to use KXM's browser automation capability powered by self-hosted Steel on DigitalOcean Kubernetes (DOKS), `agent-browser` for exploratory inspection, `Playwright` for automated regression testing, and `pass-cli` for credential security.
+
+---
+
+## 1. Architecture & Trust Boundaries
+
+```text
+Herdr / Pi / Agent Harness
+  │
+  ├──► KXM Browser Skills & Prompts (kxm-browser-*)
+  │
+  ├──► pass-cli (Authoritative Vault: "AI Provider Keys")
+  │
+  ├──► agent-browser (Exploratory CLI) ──┐
+  │                                      │ (CDP WebSocket)
+  ├──► Playwright (E2E Test Suites) ────┼──► DOKS Steel Browser Cluster
+  │                                      │   (https://steel.kontextmind.com)
+  └──► Human Operator (Takeover UI) ─────┘   (https://steel.kontextmind.com/ui)
+```
+
+### Key Components
+
+1. **Steel on DOKS (`https://steel.kontextmind.com`)**:
+   - Primary browser execution environment.
+   - Isolated Chromium containers with dedicated shared memory (`/dev/shm`).
+   - Exposed endpoints: REST API (port 443 / 3000), CDP WebSocket proxy (port 443 / 9223), Web UI (`/ui`), OpenAPI docs (`/documentation`).
+2. **`pass-cli`**:
+   - The authoritative store for all long-lived passwords, session tokens, and the `STEEL_API_KEY`.
+   - Never write credentials to tracked git files.
+3. **`agent-browser`**:
+   - Fast, token-efficient terminal CLI for accessibility snapshots, interactive navigation, and exploratory testing.
+4. **`Playwright`**:
+   - High-fidelity assertion engine for bug reproduction, visual proofs, and permanent regression suites.
+
+---
+
+## 2. Getting Started: The First Browser Workflow
+
+### Step 1: Verify Prerequisites
+
+Check that `pass-cli` can access the Steel configuration:
+
+```bash
+pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)"
+```
+
+### Step 2: Launch a Steel Browser Session
+
+```bash
+STEEL_KEY=$(pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --field STEEL_API_KEY)
+
+# Create a 5-minute session
+SESSION_RESP=$(curl -s -X POST https://steel.kontextmind.com/v1/sessions \
+  -H "Content-Type: application/json" \
+  -H "x-steel-api-key: $STEEL_KEY" \
+  -d '{"timeout": 300000}')
+
+SESSION_ID=$(echo "$SESSION_RESP" | jq -r .id)
+echo "Session created: $SESSION_ID"
+```
+
+### Step 3: Run Exploratory Automation or Scrapes
+
+To run a fast scrape without managing sessions:
+
+```bash
+curl -s -X POST https://steel.kontextmind.com/v1/scrape \
+  -H "Content-Type: application/json" \
+  -H "x-steel-api-key: $STEEL_KEY" \
+  -d '{"url": "https://example.com"}'
+```
+
+### Step 4: Release the Session
+
+```bash
+curl -s -X POST https://steel.kontextmind.com/v1/sessions/$SESSION_ID/release \
+  -H "x-steel-api-key: $STEEL_KEY"
+```
+
+---
+
+## 3. Human Takeover Protocol
+
+When authentication challenges (MFA, CAPTCHA, SSO) are encountered:
+
+1. **Agent Pauses**: The agent stops automated actions and sets state to `HUMAN_CONTROL`.
+2. **Emits Link**: Emits the protected URL: `https://steel.kontextmind.com/ui?sessionId=<SESSION_ID>`.
+3. **Human Interacts**: The operator opens the session viewer, completes the login/MFA action, and confirms in the terminal (`auth complete`).
+4. **Agent Verifies**: The agent inspects the resulting page, confirms dashboard/user state, refreshes DOM observations, and returns to `AGENT_CONTROL`.
+
+---
+
+## 4. Resource Controls & Cost Safety
+
+- **Session Timeouts**: Default 300s (5m), max 1800s (30m). Sessions terminate automatically on expiry.
+- **Orphan Sweeping**: Periodically sweep untracked sessions via `GET /v1/sessions` and release idle processes.
+- **Memory Protection**: Kubernetes mounts a 2Gi `emptyDir` memory volume at `/dev/shm` to prevent Chromium tab crashes without exhausting node memory.

package/docs/configuration.md

@@ -74,6 +74,15 @@ rewrites it.
 
 The hub refuses a non-loopback bind without `KXM_AUTH_TOKEN`. Use a long random administrative token even when project tokens are configured, because administrative endpoints such as `/metrics` require it outside loopback.
 
+When `KXM_AUTH_TOKEN` is unset, `kxm hub start` resolves credentials from the
+persisted `kxm.hub-env.v1` file under the user state root
+(`~/.local/state/kxm/hub-env.json`; honors `KXM_STATE_HOME` and platform
+equivalents). A missing admin token is generated once, persisted with `0600`
+permissions, and reused across hub restarts so workers and dashboards on the
+same machine share one stable credential. Explicit `KXM_AUTH_TOKEN` or
+`KXM_PROJECT_TOKENS` environment values take precedence and are persisted for
+later restarts. Delete the file and restart to rotate the generated token.
+
 Project tokens are an authorization boundary. A project-specific token can register only in its mapped project and see only that project's agents and messages. The administrative token remains a fallback for projects without an explicit entry. For provenance-gated workflows, configure an explicit project token and give workers only that token; reserve a distinct administrative token for operations such as quorum degradation approval.
 
 PowerShell example:
@@ -279,7 +288,7 @@ See [Webhook workflows](webhook-workflows.md) for the base schema and the comple
 | `steer` | An active blocker requires a course change | Deliver at the next decision boundary |
 | `nextTurn` | Information should wait for a later turn | Queue context without immediate work |
 
-`followUp` is the safe default. Use [`.kxm/env.example`](../ .kxm/env.example) as a reference, but load values through your shell, supervisor, container platform, or secret manager. Never commit real tokens.
+`followUp` is the safe default. Load values through your shell, supervisor, container platform, or secret manager using the variables documented on this page and in the [KXM Handbook](kxm-handbook.md). Never commit real tokens.
 
 ## Nous providers (opt-in)
 

package/docs/getting-started.md

@@ -61,6 +61,27 @@ kxm init
 
 `kxm init` never copies the package repository's dogfood roster or workflows into a consumer workspace.
 
+When `kxm init` succeeds in an interactive terminal, it offers to install shell
+completion for the detected shell. Accepting writes the completion script
+under the user config directory, appends one idempotent stanza to the shell
+rc file, and, when the kxm bin directory is not already on `PATH`, adds a
+`PATH` export. Declining is safe: run `kxm completion install` later, or set
+`KXM_SKIP_COMPLETION_PROMPT=1` to suppress the offer. Non-interactive,
+`--json`, and `--dry-run` runs never prompt or write shell files.
+
+After the completion offer, an interactive `kxm init` also offers to set up
+workflow-guide agents and workflows for the harnesses you have installed and
+authenticated. Accepting lists the software-engineering workflows from
+[`workflow-guide.md`](workflow-guide.md); pick by number or slug (`all` works
+too). kxm resolves each role's first guide candidate whose harness is
+authenticated and writes only current vNext project resources —
+`.kxm/agents/<role>.yaml` (`kxm.agent.v1`) and `.kxm/workflows/<slug>.yaml`
+(`kxm.workflow.v1`). It never writes retired legacy authority (`.kxm/config`,
+`.kxm/roster.json`). Roles whose candidates have no authenticated harness are
+reported as skipped, not silently downgraded. Guide candidates are dated
+research — verify them before dispatch. Declining is safe: set
+`KXM_SKIP_GUIDE_SETUP_PROMPT=1` to suppress the offer.
+
 ## 3. Start the hub in another terminal
 
 `kxm hub start` is foreground. Keep that terminal running.

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

@@ -0,0 +1,31 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-003"
+type: "kb"
+title: "How are credentials retrieved without exposing them to the model?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Explains safe pass-cli credential delivery and environment piping patterns that avoid LLM context leakage."
+tags: ["browser", "credentials", "pass-cli", "security"]
+related: ["docs/browser-automation.md", "docs/agent-skills.md"]
+---
+
+# How are credentials retrieved without exposing them to the model?
+
+To protect passwords, MFA secrets, and API tokens from leaking into model reasoning traces, KXM enforces strict credential-reference boundaries:
+
+## Mechanisms
+
+1. **Authoritative Store**: All secrets reside in `pass-cli` (Proton Pass).
+2. **In-Process Environment Piping**:
+   - Automated test scripts use `pass-cli run -- npm test` or retrieve credentials directly into child process memory via standard environment variables.
+   - The LLM prompt only receives credential references (e.g., `vault: "AI Provider Keys", item: "Steel Browser (KontextMind DOKS)"`), never raw secret values.
+3. **Log Sanitization**:
+   - The KXM browser client strips API keys and token parameters (`apiKey=[REDACTED]`, `steel_[REDACTED]`) before logging or emitting outputs.
+4. **Human Handoff for High-Privilege Auth**:
+   - For sensitive production accounts or MFA, the agent never touches the credential at all; it invokes `kxm-browser-takeover` and lets the human authenticate directly in the UI.

package/docs/kb/how-to-capture-and-annotate-section.md

@@ -0,0 +1,60 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-009"
+type: "kb"
+title: "How do I capture a UI section and annotate changes for an agent?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Guide to capturing specific DOM elements, attaching visual annotations, and submitting structured change feedback to the agent."
+tags: ["browser", "annotation", "screenshot", "feedback", "ui"]
+related: ["docs/browser-automation.md", "docs/prompts/browser-annotate-feedback.md"]
+---
+
+# How do I capture a UI section and annotate changes for an agent?
+
+When reviewing a web interface in a Steel session, you can isolate a specific component, attach annotations, and deliver structured change requests directly back to an agent.
+
+## Workflow
+
+1. **Capture the Component**:
+   Use Playwright element screenshotting to crop only the affected container:
+
+   ```typescript
+   await page.locator('.billing-card').screenshot({ path: '.kxm/artifacts/browser/billing-card.png' });
+   ```
+
+2. **Draft the Annotation Feedback**:
+   Record the target selector, observed issues, and required fixes:
+
+   ```typescript
+   import { createAnnotationFeedback, formatAnnotationFeedbackPrompt } from "@kontextmind/kxm/runtime";
+
+   const feedback = createAnnotationFeedback({
+     url: "https://app.example.com/settings/billing",
+     sectionSelector: ".billing-card",
+     screenshotPath: ".kxm/artifacts/browser/billing-card.png",
+     overallSummary: "Billing tier layout breaks on mobile viewport",
+     annotations: [
+       {
+         label: "Tier Name Overflow",
+         selector: ".tier-title",
+         note: "Truncate or wrap long tier titles with ellipsis",
+         severity: "fix"
+       }
+     ],
+     requestedChanges: [
+       "Update `.tier-title` CSS to include `truncate` or `break-words`",
+       "Adjust padding on small viewports to `px-4`"
+     ]
+   });
+
+   const prompt = formatAnnotationFeedbackPrompt(feedback);
+   ```
+
+3. **Send to the Agent**:
+   Feed the rendered prompt into the agent session or KXM workflow run. The agent reads the screenshot, navigates to the source code, applies the changes, and verifies the result with Playwright.

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

@@ -0,0 +1,54 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-007"
+type: "kb"
+title: "How do I connect Playwright to the existing Steel session?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Guide to attaching Playwright tests to an active remote Steel browser session using chromium.connectOverCDP()."
+tags: ["browser", "playwright", "cdp", "steel", "testing"]
+related: ["docs/browser-automation.md", "docs/kb/why-automation-opened-different-browser.md"]
+---
+
+# How do I connect Playwright to the existing Steel session?
+
+To run Playwright tests against self-hosted Steel on DOKS instead of a local browser:
+
+## 1. Retrieve the CDP Endpoint
+
+Format the WebSocket CDP URL using the active session ID and API key:
+
+```typescript
+import { formatCDPEndpoint, resolveSteelConfig } from "@kontextmind/kxm/runtime";
+
+const config = resolveSteelConfig();
+const cdpUrl = formatCDPEndpoint({ id: sessionId, websocketUrl: "" }, config);
+```
+
+The resulting URL will look like:
+`wss://steel.kontextmind.com/v1/devtools?sessionId=<SESSION_ID>&apiKey=<STEEL_API_KEY>`
+
+## 2. Connect in Playwright
+
+```typescript
+import { test, expect, chromium } from "@playwright/test";
+
+test("execute test on remote steel session", async () => {
+  const browser = await chromium.connectOverCDP(process.env.STEEL_CDP_URL!);
+  
+  // Use existing context or create one
+  const context = browser.contexts()[0] || await browser.newContext();
+  const page = context.pages()[0] || await context.newPage();
+
+  await page.goto("https://app.example.com");
+  await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+
+  // Disconnecting closes the Playwright CDP socket without terminating the remote container
+  await browser.close();
+});
+```

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

@@ -0,0 +1,54 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-008"
+type: "kb"
+title: "How do I recover an expired session or remove an orphaned browser?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Procedures for detecting and releasing stale or orphaned browser sessions on Steel."
+tags: ["browser", "cleanup", "orphans", "troubleshooting"]
+related: ["docs/browser-automation.md", "docs/kb/why-authentication-disappeared.md"]
+---
+
+# How do I recover an expired session or remove an orphaned browser?
+
+If an automation run crashed or disconnected without calling `/release`, a browser container may remain idling on DOKS.
+
+## 1. List Active Remote Sessions
+
+```bash
+STEEL_KEY=$(pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --field STEEL_API_KEY)
+
+curl -s https://steel.kontextmind.com/v1/sessions \
+  -H "x-steel-api-key: $STEEL_KEY" | jq .
+```
+
+## 2. Release Orphaned Sessions
+
+To terminate a specific stale session:
+
+```bash
+curl -s -X POST https://steel.kontextmind.com/v1/sessions/<SESSION_ID>/release \
+  -H "x-steel-api-key: $STEEL_KEY"
+```
+
+## 3. Automatic Orphan Sweeping via KXM Client
+
+The KXM client provides `checkOrphanedSessions(maxIdleMs)` to automate this:
+
+```typescript
+import { SteelClient } from "@kontextmind/kxm/runtime";
+
+const client = new SteelClient();
+const orphans = await client.checkOrphanedSessions(600000); // > 10 min idle
+
+for (const sessionId of orphans) {
+  console.log(`Releasing orphaned session: ${sessionId}`);
+  await client.releaseSession(sessionId);
+}
+```

package/docs/kb/how-to-resume-after-mfa.md

@@ -0,0 +1,28 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-002"
+type: "kb"
+title: "How does an agent resume after MFA?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Details the verification and observation refresh sequence when resuming automation after MFA."
+tags: ["browser", "mfa", "resume", "verification"]
+related: ["docs/kb/how-to-take-over-session.md", "docs/browser-automation.md"]
+---
+
+# How does an agent resume after MFA?
+
+Once the human completes the MFA challenge in the browser viewer, the agent must not immediately execute blind clicks. It follows this sequence:
+
+1. **State Transition**: Moves from `HUMAN_CONTROL` to `VERIFY_AUTHENTICATION`.
+2. **CDP Re-attachment**: Re-queries the active tab target from the remote Steel CDP endpoint.
+3. **App State Verification**:
+   - Inspects `page.url()` to confirm the browser navigated away from the MFA prompt to the intended destination (e.g. `/dashboard` or `/overview`).
+   - Checks for authenticated elements (e.g. account menu, logout button, user profile avatar).
+4. **Observation Refresh**: Runs a fresh `agent-browser snapshot` or queries fresh DOM locators before executing the next action.
+5. **Restore Control**: Returns to `AGENT_CONTROL` and proceeds with the task.

package/docs/kb/how-to-take-over-session.md

@@ -0,0 +1,32 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-001"
+type: "kb"
+title: "How do I take over a browser session to log in?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Instructions for taking over an active Steel browser session during an authentication gate."
+tags: ["browser", "takeover", "auth", "mfa"]
+related: ["docs/browser-automation.md", "docs/kb/how-to-resume-after-mfa.md"]
+---
+
+# How do I take over a browser session to log in?
+
+When an agent encounters a login screen, OAuth prompt, or security challenge, it triggers the `kxm-browser-takeover` protocol.
+
+## Steps
+
+1. **Copy the Takeover URL**:
+   The agent will emit a message in the terminal with a link like:
+   `https://steel.kontextmind.com/ui?sessionId=<SESSION_ID>`
+2. **Open the Session Viewer**:
+   Open that URL in your desktop browser. You will see the live screencast of the exact remote Chrome container the agent was operating.
+3. **Interact and Authenticate**:
+   Enter the username, password, or security key into the session, or use the devtools inspector (`https://steel.kontextmind.com/v1/devtools/inspector.html`) to trigger the submission.
+4. **Signal Completion**:
+   Return to your Herdr or Pi terminal session and notify the agent: `auth complete` or `proceed`.

package/docs/kb/why-authentication-disappeared.md

@@ -0,0 +1,32 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-004"
+type: "kb"
+title: "Why did authentication disappear?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Diagnosing lost authentication state, session expiration, and ephemeral container recreation."
+tags: ["browser", "authentication", "cookies", "troubleshooting"]
+related: ["docs/browser-automation.md", "docs/kb/why-automation-opened-different-browser.md"]
+---
+
+# Why did authentication disappear?
+
+If an agent was authenticated on a previous step or run and suddenly encounters a login screen again, the root causes are typically:
+
+## Root Causes & Fixes
+
+1. **Session Released or Expired**:
+   - Steel sessions are ephemeral by default. Once a session reaches its timeout (e.g. 5–30 minutes) or is released via `POST /v1/sessions/:id/release`, all memory cookies and local storage are cleared.
+   - **Fix**: To reuse state across tasks, save `storageState` via Playwright and reload it on the next session initialization.
+2. **New Session Launched Instead of Attaching**:
+   - If the agent created a brand-new session instead of passing the existing `sessionId`, it opened a clean Chrome profile.
+   - **Fix**: Verify that the task passes `sessionId` to `getSession()` or uses the existing CDP endpoint.
+3. **Domain / Subdomain Cookie Scoping**:
+   - OAuth flows often set cookies on subdomains (e.g., `auth.example.com`) that do not automatically share with `app.example.com`.
+   - **Fix**: Ensure cookies were issued for the primary domain or that SSO redirect completed fully before saving state.