@kontextmind/kxm 0.7.4 → 0.7.5

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

package/docs/README.md

@@ -9,6 +9,7 @@ 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 |

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

@@ -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

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/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.

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

@@ -0,0 +1,32 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-005"
+type: "kb"
+title: "Why did automation open a different browser?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Preventing accidental local browser launches and ensuring Playwright and agent-browser connect to remote Steel."
+tags: ["browser", "cdp", "playwright", "agent-browser", "troubleshooting"]
+related: ["docs/browser-automation.md", "docs/kb/how-to-connect-playwright-to-steel.md"]
+---
+
+# Why did automation open a different browser?
+
+If you expected automation to run on DOKS Steel but saw a local Chrome window pop up or failed to see the agent's actions in the Steel session viewer:
+
+## Root Causes
+
+1. **Called `chromium.launch()` Instead of `chromium.connectOverCDP()`**:
+   - `chromium.launch()` spawns a local browser process on the workstation.
+   - **Fix**: In Playwright, always use `chromium.connectOverCDP(cdpUrl)`.
+2. **Missing `--cdp` Flag in `agent-browser`**:
+   - Running `agent-browser open <url>` without `--cdp` spawns a local headless browser.
+   - **Fix**: Always pass `--cdp "wss://steel.kontextmind.com/v1/devtools?sessionId=<id>&apiKey=<key>"`.
+3. **Missing Environment Variables**:
+   - If `STEEL_CDP_URL` is undefined, scripts that fall back to local execution will launch a local browser.
+   - **Fix**: Ensure `STEEL_CDP_URL` or `STEEL_API_KEY` is loaded from `pass-cli`.

package/docs/kb/why-session-viewer-cannot-control.md

@@ -0,0 +1,31 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-006"
+type: "kb"
+title: "Why can I view a session but not control it?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Understanding self-hosted Steel OSS screencast viewer capabilities vs devtools inspector input modes."
+tags: ["browser", "takeover", "steel", "ui"]
+related: ["docs/browser-automation.md", "docs/kb/how-to-take-over-session.md"]
+---
+
+# Why can I view a session but not control it?
+
+In self-hosted open-source Steel (`steel-dev/steel-browser`), the web UI at `/ui` provides a real-time screencast stream, event logs, and network tracking. Depending on browser canvas capture modes, direct clicks on the video canvas may not send synthetic mouse events.
+
+## Resolution
+
+1. **Use the Chrome DevTools Inspector**:
+   Navigate to the devtools inspector page for the session:
+   `https://steel.kontextmind.com/v1/devtools/inspector.html`
+   or open the remote debugger on port 9223.
+2. **Interact via the DOM Console**:
+   The devtools inspector gives full interactive control over the DOM, console, network, and storage.
+3. **Agent Automation Coexistence**:
+   Ensure the agent is in `HUMAN_CONTROL` state so automation does not race or override your clicks.