@kontextmind/kxm 0.7.132 → 0.7.133

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

package/CHANGELOG.md

@@ -6,6 +6,8 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **Playwright uses Obscura by default.** `resolveBrowserCdpEndpoint()` returns `OBSCURA_CDP_URL` or `http://127.0.0.1:${OBSCURA_PORT:-9222}`. `KXM_BROWSER=steel` still returns the Steel session CDP URL. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it with `--allow-private-network`. `npm run e2e` runs the Playwright smoke test in `test/e2e/` over CDP and does not run `playwright install`. Steel remains the path for human takeover, MFA, and the live session viewer. See [ADR-0005](docs/adr/ADR-0005-obscura-default-playwright.md) and [How do I connect Playwright to Obscura?](docs/kb/how-to-connect-playwright-to-obscura.md).
+
 - **A live agent step uses a configurable one-shot timeout, and a cancelling run recovers when its child has already exited.**
   The bound is the step `timeoutMs`, or the project `limits.agentStepTimeoutMs`
   when the step omits it (minimum 60 seconds, default one hour). A wider step

package/docs/README.md

@@ -26,7 +26,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 | [Continuous improvement](guides/continuous-improvement.md) | Leads, workflow authors | Journals, retrospectives, improvement reports and coded-repeat candidates |
 | [Governed skills](guides/governed-skills.md) | Operators, skill authors | The candidate, evaluation, promotion and rejection lifecycle |
 | [Agent skills](guides/agent-skills.md) | Users of any harness | The bundled `SKILL.md` suite and how each harness loads it |
-| [Browser automation](guides/browser-automation.md) | Developers, operators | Steel browser sessions, Playwright, safe credentials and human takeover |
+| [Browser automation](guides/browser-automation.md) | Developers, operators | Obscura for Playwright, Steel for takeover, safe credentials |
 | [Nous providers](guides/nous-providers.md) | Pi operators | Opt-in Nous Portal models for Pi agents |
 
 ### Browser knowledge base
@@ -35,7 +35,8 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 |---|---|---|
 | [How are credentials retrieved without exposing them to the model?](kb/how-credentials-retrieved-safely.md) | Browser operators | How agents log in without the model seeing secrets |
 | [How do I capture a UI section and annotate changes for an agent?](kb/how-to-capture-and-annotate-section.md) | Browser operators | Send an agent a marked-up UI section to change |
-| [How do I connect Playwright to the existing Steel session?](kb/how-to-connect-playwright-to-steel.md) | Browser operators | Attach Playwright to an existing Steel session |
+| [How do I connect Playwright to Obscura?](kb/how-to-connect-playwright-to-obscura.md) | Browser operators | Attach Playwright to the default Obscura browser |
+| [How do I connect Playwright to the existing Steel session?](kb/how-to-connect-playwright-to-steel.md) | Browser operators | Attach Playwright to a Steel session for takeover |
 | [How do I recover an expired session or remove an orphaned browser?](kb/how-to-recover-expired-session-or-orphan.md) | Browser operators | Restore a session or remove an orphaned browser |
 | [How does an agent resume after MFA?](kb/how-to-resume-after-mfa.md) | Browser operators | Continue agent work after a person completes MFA |
 | [How do I take over a browser session to log in?](kb/how-to-take-over-session.md) | Browser operators | Log in by hand inside an agent's browser session |
@@ -75,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), [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), [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) |
 | [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

@@ -12,7 +12,7 @@ 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/guides/browser-automation.md", "docs/guides/agent-skills.md"]
+related: ["docs/guides/browser-automation.md", "docs/guides/agent-skills.md", "docs/adr/ADR-0005-obscura-default-playwright.md"]
 details:
   decision_drivers:
     - "Eliminate per-minute SaaS browser provider costs"

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

@@ -0,0 +1,85 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0005"
+type: "adr"
+title: "Obscura is the default browser for Playwright"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-27"
+updated: "2026-09-27"
+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"]
+details:
+  decision_drivers:
+    - "Playwright tests must run without a Steel cluster or a Playwright-managed browser download"
+    - "Local pages, including 127.0.0.1, must load in CI"
+    - "Human takeover, MFA, and the live session viewer stay on Steel"
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0005: Obscura is the default browser for Playwright
+
+## 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.
+
+## Context
+
+Playwright in this repository had no config, dependency, or CI job. Skills told agents to attach to a Steel session with `chromium.connectOverCDP(STEEL_CDP_URL)`. That makes every UI test depend on a remote Steel deployment, and it launches a local browser when the CDP URL is missing.
+
+Obscura v0.2.3 is a headless Chromium build that speaks the Chrome DevTools Protocol on loopback. Playwright can attach with `chromium.connectOverCDP()`. It does not speak Playwright's own protocol (`chromium.connect`, `use.connectOptions`). Loading `127.0.0.1` requires `--allow-private-network`. Video recording is unsupported.
+
+## Decision drivers
+
+1. Playwright testing and verification need a default that runs on a developer machine and on `ubuntu-latest`.
+2. A smoke test must assert a page served on `127.0.0.1`, so CI does not depend on the public internet.
+3. Tests must not download Playwright's browser builds (`playwright install`).
+4. Human takeover, MFA, and the live session viewer still need Steel's session API and viewer.
+
+## Considered options
+
+1. **Pinned Obscura over CDP, Steel only when `KXM_BROWSER=steel`.**
+2. **Keep Steel as the Playwright default.**
+3. **`playwright install` and `chromium.launch()` on the runner.**
+
+### Option 1: pinned Obscura (chosen)
+
+- Good, because the launcher downloads one pinned Apache-2.0 archive and the smoke test talks to loopback.
+- Good, because `newContext()` still isolates pages, and screenshots work on the rendering build.
+- Bad, because video recording and full `storageState` are unavailable.
+- Bad, because Linux needs glibc 2.35 or newer, and a non-loopback bind needs `OBSCURA_CDP_TOKEN`.
+
+### Option 2: Steel for every Playwright run (rejected)
+
+- Good, because one CDP path covers tests and takeover.
+- Bad, because tests then require a Steel deployment, an API key, and a network path that CI does not have.
+
+### Option 3: Playwright's downloaded Chromium (rejected)
+
+- Good, because `chromium.launch()` needs no second binary.
+- Bad, because it is a second browser download, and it is the local browser the skills already tell agents to avoid.
+
+## Decision
+
+`resolveBrowserCdpEndpoint()` returns the Obscura CDP URL (`OBSCURA_CDP_URL`, or `http://127.0.0.1:${OBSCURA_PORT:-9222}`). `KXM_BROWSER=steel` returns the existing Steel session URL from `formatCDPEndpoint()`. Any other `KXM_BROWSER` value throws.
+
+`scripts/obscura.mjs` downloads Obscura v0.2.3 for the current OS and architecture, checks the pinned sha256, and serves with `--allow-private-network`. `npm run e2e` ensures that server is ready and runs `playwright test`. The worker-scoped `browser` fixture connects with `chromium.connectOverCDP()`. `video` is `off`.
+
+## Consequences
+
+- Playwright tests and verification use Obscura unless the operator sets `KXM_BROWSER=steel`.
+- Steel session create, release, takeover, and the session viewer are unchanged.
+- CI for this smoke test is `.github/workflows/e2e.yml` on `ubuntu-latest`. It does not enable the paused CI, Nightly, or Real Pi smoke workflows.
+- The `node --test` globs do not collect `test/e2e/`.
+
+## Related
+
+- [ADR-0002: Self-hosted Steel on DOKS](ADR-0002-browser-automation-steel-doks.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/README.md

@@ -10,6 +10,7 @@ An architecture decision record (ADR) captures one significant decision about KX
 | [ADR-0002](ADR-0002-browser-automation-steel-doks.md) | Self-hosted Steel for reusable browser automation and human takeover | Accepted | 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-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.
 

package/docs/contributing/ci-and-release.md

@@ -42,6 +42,7 @@ together.
 | Merged pull request | `auto-release.yml` | Tags the merge commit and dispatches `release.yml` |
 | Tag push or dispatch | `release.yml` | Verifies, packs and publishes (see [Release flow](#release-flow)) |
 | Manual only | `smoke.yml` | Real Pi smoke, currently disabled (see [Smoke tests](#smoke-tests)) |
+| Pull request, or manual | `e2e.yml` | `npm run e2e` on `ubuntu-latest`: Obscura v0.2.3 plus the Playwright smoke test. This workflow does not enable CI, Nightly, or Real Pi smoke |
 
 The npm scripts behind those rows:
 

package/docs/contributing/development.md

@@ -264,6 +264,7 @@ Other scripts you will use:
 | `npm run test:coverage` | Core suite with coverage floors |
 | `npm run test:coverage:complete` | Core plus simulations with the higher nightly floors |
 | `npm run lint:docs` | Markdown lint only |
+| `npm run e2e` | Start Obscura if needed, then Playwright in `test/e2e/` (`node --test` does not collect that directory) |
 | `npm run validate:pr` | The three-minute CI gate; see [CI and release](ci-and-release.md) |
 | `npm run validate:ci` | Coverage suite, `check` and a package dry run (not run by CI today) |
 | `npm run validate:claude` | Strict Claude plugin and marketplace validation |

package/docs/contributing/test-matrix.md

@@ -165,6 +165,8 @@ up or restores stores a running supervisor wrote.
 | Release packs `kxm-<v>.tgz`, uploads to a draft fail-closed, proves the digest and never clobbers | `kxm-release-github.test.ts`, `ci-contract.test.ts` |
 | npm publish requires a published release and a matching asset digest | `kxm-publish-npm.test.ts` |
 | CI required jobs are unconditional; runner selector, coverage floors and release triggers are pinned | `ci-contract.test.ts` |
+| Playwright CDP defaults to Obscura; `KXM_BROWSER=steel` uses the Steel session URL | `browser.test.ts` |
+| Obscura Playwright smoke loads a local page over CDP | `test/e2e/obscura-smoke.spec.ts` via `npm run e2e` (not `node --test`) |
 | Skill suite: manifest shape, one owner per command, strict YAML frontmatter, no legacy names, mirror parity | `skill-suite.test.ts` ("every bundled SKILL.md frontmatter parses as strict YAML") |
 | The extension and MCP server never import the hub, store or workflow; library bundles stay host-neutral | `import-boundary.test.ts` |
 | Workspace packages keep their layers, required files and by-name imports | `package-layers.test.ts` |

package/docs/guides/agent-skills.md

@@ -68,7 +68,7 @@ Tools map the same way: peer tools to `kxm-peer`, workflow tools to `kxm-workflo
 
 ## Browser automation skills
 
-These skills drive a remote Steel browser that you host. They own no `kxm` command. See [Browser automation](browser-automation.md) and [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md).
+Playwright testing and verification use Obscura. The Steel skills cover human takeover, MFA, and the live session viewer. They own no `kxm` command. See [Browser automation](browser-automation.md), [ADR-0005](../adr/ADR-0005-obscura-default-playwright.md), and [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md).
 
 | Skill | Use it to |
 |---|---|
@@ -76,7 +76,7 @@ These skills drive a remote Steel browser that you host. They own no `kxm` comma
 | `kxm-browser-takeover` | Hand a session to a human for MFA, login, CAPTCHA or sensitive consent, then resume |
 | `kxm-browser-auth` | Use stored credentials and authenticated browser profiles safely |
 | `kxm-browser-explore` | Explore a site, inspect its DOM and map a user flow with `agent-browser` |
-| `kxm-browser-verify` | Reproduce a UI bug, gather evidence and write a durable Playwright test |
+| `kxm-browser-verify` | Reproduce a UI bug on Obscura, gather evidence and write a durable Playwright test |
 | `kxm-browser-diagnostics` | Diagnose Steel connectivity, CDP errors and timeouts, and clean up orphaned sessions |
 | `kxm-browser-annotate` | Capture page sections, attach structured annotations and hand the changes to an agent |
 

package/docs/guides/browser-automation.md

@@ -1,11 +1,12 @@
 # Browser automation
 
-Give agents a real browser without giving them your desktop: KXM's browser skills drive a remote [Steel](https://github.com/steel-dev/steel-browser) browser that you host, explore pages with `agent-browser`, verify fixes with Playwright, and hand control to a person for login, MFA or consent. This page is for developers and operators. The `browser` mode names this page as its context file (`kxm explain --mode browser` counts it), so it stays short and procedure-first.
+Give agents a real browser without giving them your desktop. Playwright testing and verification use [Obscura](https://github.com/h4ckf0r0day/obscura) by default. Steel remains for human takeover, MFA, and the live session viewer. Explore pages with `agent-browser`, and hand a Steel session to a person for login, MFA, or consent. This page is for developers and operators. The `browser` mode names this page as its context file (`kxm explain --mode browser` counts it), so it stays short and procedure-first.
 
 ## Before you begin
 
-- A Steel deployment you operate, reachable over HTTPS, and its API key. [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md) describes the reference deployment on Kubernetes.
-- `curl` and `jq`. Optionally `agent-browser` for exploration and Playwright for tests.
+- For Playwright: Node, and `node scripts/obscura.mjs` (it downloads pinned Obscura v0.2.3). [ADR-0005](../adr/ADR-0005-obscura-default-playwright.md) records that default.
+- For takeover: a Steel deployment you operate, reachable over HTTPS, and its API key. [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md) describes the reference deployment on Kubernetes.
+- `curl` and `jq`. Optionally `agent-browser` for exploration. Playwright tests use Obscura; do not run `playwright install`.
 - A secret manager for the API key. The bundled skills use `pass-cli`.
 - The `kxm-browser-*` skills from the plugin or Pi package. See [Agent skills](agent-skills.md#browser-automation-skills).
 
@@ -13,11 +14,23 @@ Give agents a real browser without giving them your desktop: KXM's browser skill
 
 | Component | Role |
 |---|---|
-| Steel | Runs isolated Chromium sessions and exposes a REST API, a CDP WebSocket and a session viewer |
+| Obscura | Default headless browser for Playwright (`chromium.connectOverCDP`) |
+| Steel | Isolated Chromium sessions, a REST API, a CDP WebSocket, and a session viewer for takeover |
 | `agent-browser` | Fast, token-efficient exploration: accessibility snapshots, navigation, DOM inspection |
 | Playwright | Assertions, bug reproductions, visual proof and permanent regression tests |
 | Secret manager | The only place the Steel API key and site credentials live |
-| Human operator | Completes MFA, CAPTCHA, SSO or consent in the session viewer |
+| Human operator | Completes MFA, CAPTCHA, SSO or consent in the Steel session viewer |
+
+## Run Playwright on Obscura
+
+`resolveBrowserCdpEndpoint()` returns the Obscura URL unless `KXM_BROWSER=steel`. The launcher and the settings are in [How do I connect Playwright to Obscura?](../kb/how-to-connect-playwright-to-obscura.md) and [Browser settings](../reference/configuration.md#browser-automation).
+
+```bash
+node scripts/obscura.mjs --ensure
+npm run e2e
+```
+
+Set `video: "off"` in Playwright. Obscura does not record video. Connect with the worker-scoped `browser` fixture and `chromium.connectOverCDP()`. `chromium.connect` and `use.connectOptions` are not supported.
 
 ## Configure the Steel endpoint
 
@@ -70,7 +83,7 @@ The CDP URL carries the API key in its query string. Treat it as a secret: never
    echo "Session: $SESSION_ID"
    ```
 
-3. Attach one automation client over CDP: `chromium.connectOverCDP(<cdp-url>)` in Playwright, or `agent-browser --cdp "<cdp-url>"`. Check the session's state with `steel GET "/v1/sessions/$SESSION_ID"`.
+3. For exploration, attach `agent-browser --cdp "<cdp-url>"`. Playwright tests use Obscura. Set `KXM_BROWSER=steel` and `chromium.connectOverCDP(<cdp-url>)` only when the test must drive this takeover session. Check the session's state with `steel GET "/v1/sessions/$SESSION_ID"`.
 4. For a quick fetch that needs no session, scrape instead:
 
    ```bash
@@ -128,7 +141,8 @@ The KXM browser library tracks these states in the process that owns the session
 |---|---|---|
 | `401` or `403` from Steel | Missing or wrong API key | Re-export `STEEL_API_KEY` from your secret manager |
 | Requests go to an unexpected host | `STEEL_API_URL` is unset | Export it before starting the agent |
-| Playwright opens a local browser | The client did not attach over CDP | Use `connectOverCDP` with the session's CDP URL |
+| Playwright opens a local browser | The client called `chromium.launch()` or `chromium.connect()` | Use the worker-scoped fixture and `connectOverCDP` against Obscura |
+| `Access to private/internal IP address` | Obscura was started without `--allow-private-network` | Run `node scripts/obscura.mjs`, which passes that flag |
 | Signed-in state is gone | The session expired or was released | Create a new session and repeat the takeover |
 | The viewer shows the page but clicks do nothing | The viewer is a screencast, and some capture modes do not forward clicks | Use the DevTools inspector at `$STEEL_API_URL/v1/devtools/inspector.html`, with the agent paused |
 
@@ -136,6 +150,7 @@ The KXM browser library tracks these states in the process that owns the session
 
 - [How are credentials retrieved without exposing them to the model?](../kb/how-credentials-retrieved-safely.md)
 - [How do I capture a UI section and annotate changes for an agent?](../kb/how-to-capture-and-annotate-section.md)
+- [How do I connect Playwright to Obscura?](../kb/how-to-connect-playwright-to-obscura.md)
 - [How do I connect Playwright to the existing Steel session?](../kb/how-to-connect-playwright-to-steel.md)
 - [How do I recover an expired session or remove an orphaned browser?](../kb/how-to-recover-expired-session-or-orphan.md)
 - [How does an agent resume after MFA?](../kb/how-to-resume-after-mfa.md)
@@ -156,5 +171,6 @@ The KXM browser library tracks these states in the process that owns the session
 ## Next steps
 
 - The seven browser skills: [Agent skills](agent-skills.md#browser-automation-skills)
+- Why Obscura is the Playwright default: [ADR-0005](../adr/ADR-0005-obscura-default-playwright.md)
 - Why Steel, and the reference deployment: [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md)
 - Estimate the `browser` mode's prompt footprint: [`kxm explain`](../reference/cli-reference.md#kxm-explain)

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

@@ -0,0 +1,69 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-010"
+type: "kb"
+title: "How do I connect Playwright to Obscura?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-27"
+updated: "2026-09-27"
+authority: "instruction"
+confidence: "verified"
+summary: "Run Playwright against the pinned Obscura headless browser with chromium.connectOverCDP()."
+tags: ["browser", "playwright", "cdp", "obscura", "testing"]
+related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-steel.md", "docs/adr/ADR-0005-obscura-default-playwright.md"]
+---
+
+# How do I connect Playwright to Obscura?
+
+Obscura is the default browser for Playwright testing and verification. Steel remains for human takeover, MFA, and the live session viewer (`KXM_BROWSER=steel`).
+
+Obscura is [h4ckf0r0day/obscura](https://github.com/h4ckf0r0day/obscura) v0.2.3 (Apache-2.0). It speaks the Chrome DevTools Protocol. Playwright's own transport (`chromium.connect`, `use.connectOptions`) does not work. Override the worker-scoped `browser` fixture and call `chromium.connectOverCDP()`.
+
+## 1. Start Obscura
+
+From the repository root:
+
+```bash
+node scripts/obscura.mjs --ensure
+```
+
+The launcher downloads the pinned v0.2.3 archive for this OS and architecture into `.kxm/bin/` (kept out of Git) and starts `obscura serve --port ${OBSCURA_PORT:-9222} --allow-private-network`. `obscura` and `obscura-worker` stay in that directory together. `--allow-private-network` is required: without it, `page.goto("http://127.0.0.1/...")` fails with `Access to private/internal IP address`.
+
+Readiness is HTTP GET `http://127.0.0.1:${OBSCURA_PORT:-9222}/json/version`. The process needs glibc 2.35 or newer on Linux. `--stop` stops the pidfile process. With no flag, the server stays in the foreground.
+
+Do not run `playwright install`. Set `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` when you install npm dependencies so Playwright's postinstall does not download its own browsers.
+
+## 2. Point Playwright at the CDP endpoint
+
+`resolveObscuraCdpEndpoint()` returns `OBSCURA_CDP_URL`, or `http://127.0.0.1:${OBSCURA_PORT:-9222}` when that variable is unset. `ws://127.0.0.1:9222`, `ws://127.0.0.1:9222/devtools/browser`, and `http://127.0.0.1:9222` all connect. `resolveBrowserCdpEndpoint()` returns the same URL unless `KXM_BROWSER=steel`.
+
+```typescript
+import { test as base, chromium, type Browser } from "@playwright/test";
+import { resolveObscuraCdpEndpoint } from "@kontextmind/kxm/runtime";
+
+export const test = base.extend<{}, { browser: Browser }>({
+  browser: [async ({}, use) => {
+    const browser = await chromium.connectOverCDP(resolveObscuraCdpEndpoint());
+    await use(browser);
+    await browser.close();
+  }, { scope: "worker" }],
+});
+
+export { expect } from "@playwright/test";
+```
+
+In `playwright.config.ts`, set `workers: 1`, `video: "off"`, and `trace: "retain-on-failure"`. Video recording is unsupported. `newContext()` isolation works. `storageState` is limited. The browser timezone defaults to `Europe/Berlin`; set `OBSCURA_TIMEZONE` on the Obscura process to override it. KXM does not read `OBSCURA_TIMEZONE`. Obscura ignores `HTTP_PROXY` and `HTTPS_PROXY`.
+
+A bind that is not loopback needs `OBSCURA_CDP_TOKEN` (at least 32 bytes) sent as an `Authorization: Bearer` header. The launcher binds `127.0.0.1` and does not set that token.
+
+## 3. Run the smoke test
+
+`npm run e2e` ensures Obscura is ready, then runs `playwright test`. The repository smoke test serves a page on `127.0.0.1` and asserts that page. It does not need the public internet.
+
+```bash
+npm run e2e
+```
+
+The `node --test` suite does not collect `test/e2e/`.

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

@@ -7,18 +7,20 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-23"
+updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
 summary: "Attach Playwright to an active remote Steel browser session with chromium.connectOverCDP()."
 tags: ["browser", "playwright", "cdp", "steel", "testing"]
-related: ["docs/guides/browser-automation.md", "docs/kb/why-automation-opened-different-browser.md"]
+related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md", "docs/kb/why-automation-opened-different-browser.md"]
 ---
 
 # How do I connect Playwright to the existing Steel session?
 
+Obscura is the default for Playwright testing and verification. Use this page when `KXM_BROWSER=steel` and you are attaching to a live Steel session for human takeover, MFA, or the session viewer. The default path is [How do I connect Playwright to Obscura?](how-to-connect-playwright-to-obscura.md).
+
 Run Playwright against a remote Steel session instead of a local browser by
-connecting over the Chrome DevTools Protocol (CDP).
+connecting over the Chrome DevTools Protocol (CDP). `resolveBrowserCdpEndpoint(session)` returns the same URL as `formatCDPEndpoint()` when `KXM_BROWSER=steel`.
 
 ## 1. Build the CDP endpoint
 

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

@@ -7,19 +7,19 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-23"
+updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
 summary: "Prevent accidental local browser launches and make Playwright and agent-browser attach to remote Steel."
 tags: ["browser", "cdp", "playwright", "agent-browser", "troubleshooting"]
-related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-steel.md"]
+related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md", "docs/kb/how-to-connect-playwright-to-steel.md"]
 ---
 
 # Why did automation open a different browser?
 
-You expected automation to run on your Steel deployment, but a local Chrome
-window opened, or the agent's actions never appeared in the Steel session
-viewer.
+Playwright testing connects to Obscura at `http://127.0.0.1:9222` unless `KXM_BROWSER=steel`. A local Chrome window means the client launched a browser instead of attaching over CDP. The Obscura steps are in [How do I connect Playwright to Obscura?](how-to-connect-playwright-to-obscura.md).
+
+You expected automation to run on Obscura, or on a Steel takeover session, but a local Chrome window opened, or the agent's actions never appeared in the session you were watching.
 
 ## Causes
 
@@ -32,10 +32,13 @@ viewer.
      browser.
    - **Fix:** always pass the session's CDP URL:
      `--cdp "wss://<steel-host>/v1/devtools?sessionId=<session-id>&apiKey=<steel-api-key>"`.
-     Build it with `formatCDPEndpoint()`; see
+     Build the Obscura URL with `resolveObscuraCdpEndpoint()`, or the Steel URL with `formatCDPEndpoint()` when `KXM_BROWSER=steel`. See
+     [How do I connect Playwright to Obscura?](how-to-connect-playwright-to-obscura.md)
+     and
      [How do I connect Playwright to the existing Steel session?](how-to-connect-playwright-to-steel.md).
-3. **Environment variables were missing.**
-   - A script that falls back to local execution when `STEEL_CDP_URL` is
-     unset launches a local browser.
-   - **Fix:** load `STEEL_CDP_URL`, or `STEEL_API_URL` and `STEEL_API_KEY`,
-     from your secret manager before the run.
+3. **The Playwright client had no CDP endpoint.**
+   - A script that falls back to `chromium.launch()` when no CDP URL is set
+     opens a local browser.
+   - **Fix:** use `resolveObscuraCdpEndpoint()` (default
+     `http://127.0.0.1:9222`). For a Steel takeover session, set
+     `KXM_BROWSER=steel` and load `STEEL_API_URL` and `STEEL_API_KEY`.

package/docs/prompts/browser-repro-fix.md

@@ -7,19 +7,19 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-23"
+updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
-summary: "Reproduce a UI defect on Steel, collect evidence, write a Playwright regression, and prove RED then GREEN."
+summary: "Reproduce a UI defect on Obscura, collect evidence, write a Playwright regression, and prove RED then GREEN."
 tags: ["browser", "playwright", "repro", "prompt"]
-related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-steel.md"]
+related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md", "docs/kb/how-to-connect-playwright-to-steel.md"]
 ---
 
 # Task template: reproduce a UI bug and produce a Playwright regression test
 
 ## Purpose
 
-Use this prompt to execute the full UI defect lifecycle: reproducing reported symptoms on self-hosted Steel, collecting diagnostic evidence, writing a durable Playwright test, demonstrating failure before fix (RED), applying the code fix, and demonstrating success afterward (GREEN).
+Use this prompt to execute the full UI defect lifecycle: reproducing reported symptoms on Obscura, collecting diagnostic evidence, writing a durable Playwright test, demonstrating failure before fix (RED), applying the code fix, and demonstrating success afterward (GREEN). Use a Steel session only for human takeover, MFA, or the live session viewer (`KXM_BROWSER=steel`).
 
 ## Canonical skill references
 
@@ -42,7 +42,7 @@ Use this prompt to execute the full UI defect lifecycle: reproducing reported sy
 ## Instructions for the agent
 
 1. **Step 1: Reproduce**:
-   - Connect to a Steel browser session and manually or scriptedly walk the repro steps.
+   - Connect Playwright to Obscura with the worker-scoped `browser` fixture and walk the repro steps. Do not run `playwright install`.
    - Confirm that actual behavior matches `{{ACTUAL_BEHAVIOR}}`.
 
 2. **Step 2: Collect Diagnostic Evidence**:
@@ -53,13 +53,13 @@ Use this prompt to execute the full UI defect lifecycle: reproducing reported sy
    - Use semantic locators (`getByRole`, `getByText`, `getByLabel`) rather than brittle XPath or dynamic classes.
 
 4. **Step 4: Demonstrate Failure (RED)**:
-   - Run the test: `npx playwright test {{TEST_FILE_PATH}}`.
+   - Run the test: `node scripts/obscura.mjs --ensure && playwright test {{TEST_FILE_PATH}}`.
    - Verify the test fails cleanly with an assertion error that directly explains the defect.
 
 5. **Step 5: Implement Code Fix**:
    - Modify the source code to resolve the defect.
 
 6. **Step 6: Demonstrate Success (GREEN)**:
-   - Re-run the Playwright test: `npx playwright test {{TEST_FILE_PATH}}`.
+   - Re-run the Playwright test: `node scripts/obscura.mjs --ensure && playwright test {{TEST_FILE_PATH}}`.
    - Capture clean verification output and screenshot `{{ARTIFACT_DIR}}/after.png`.
-   - Release the Steel session upon completion.
+   - When the run used a Steel takeover session, release that session. An Obscura run has no Steel session to release.

package/docs/reference/configuration.md

@@ -32,7 +32,7 @@ Names that start with `KXM_` are not all operator settings. This map covers ever
 | Runtime supervisor | `KXM_STATE_HOME`, `KXM_RUNTIME_SYNC_INTERVAL_MS`, `KXM_RUNTIME_STOP_GRACE_MS` | [Runtime supervisor settings](#runtime-supervisor-settings) |
 | Operator CLI and sessions | `KXM_USER_CONFIG_DIR`, `KXM_USER_TELEMETRY_DIR`, `KXM_SESSION_TOKEN`, `KXM_SESSION_BRIEF`, `KXM_WORKFLOW_*`, `GITHUB_TOKEN`, and others | [CLI and session settings](#cli-and-session-settings) |
 | Nous model providers | `KXM_NOUS_PROVIDERS`, `KXM_NOUS_PROXY_URL`, `KXM_NOUS_DISCOVERY_TIMEOUT_MS`, `KXM_NOUS_CATALOG_FILE`, `NOUS_API_KEY` | [Nous providers](../guides/nous-providers.md) |
-| Browser automation | `STEEL_API_URL`, `STEEL_API_KEY`, `STEEL_UI_URL`, `USE_PASS_CLI` | [Browser automation](../guides/browser-automation.md) |
+| Browser automation | `KXM_BROWSER`, `OBSCURA_CDP_URL`, `OBSCURA_PORT`, `STEEL_API_URL`, `STEEL_API_KEY`, `STEEL_UI_URL`, `USE_PASS_CLI` | [Browser settings](#browser-automation) |
 | Set by a harness, not by you | `KXM_PROJECT_DIR` (Claude Code plugin), `KXM_ATTEMPT_TOKEN` (Runtime attempts), `KXM_WORKER_IDENTITY_KEY`, `KXM_WORKER_GENERATION`, `KXM_WORKER_CHILD_INCARCATION`, `KXM_WORKER_SESSION_SCOPE` (worker supervisor to its Pi child) | [Internal variables](#internal-variables) |
 | Maintainer and test only | `KXM_SMOKE*`, `KXM_ASSET*`, `KXM_RELEASE_TAG`, `KXM_PUBLISH_WAIT_MS`, `KXM_DETERMINISTIC_TEST_CLOCK`, `KXM_WORKER_STOP_AFTER_MS`, `KXM_STUDIO_ONCE` | [Development](../contributing/development.md) |
 | Maintainer critic script | `KXM_CRITIC_DIR`, `KXM_REVIEW_TARGET` | [Maintainer critic script](#maintainer-critic-script) |
@@ -198,6 +198,22 @@ The Runtime supervisor runs `kxm run` workflows and syncs their summaries to the
 | `KXM_ENTRY` | The running script | Entry point `kxm completion install` resolves the CLI directory from |
 | `KXM_SESSION_ID` | Unset | Session ID stamped on gate command result envelopes |
 
+## Browser automation
+
+Playwright testing and verification use Obscura. Steel is for human takeover, MFA, and the live session viewer. `resolveBrowserCdpEndpoint()` in `plugins/kxm/src/browser.ts` chooses the CDP URL. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it. See [Browser automation](../guides/browser-automation.md).
+
+| Variable | Default | Effect |
+|---|---|---|
+| `KXM_BROWSER` | `obscura` | `obscura` selects the Obscura CDP URL. `steel` selects the Steel session URL from `formatCDPEndpoint()` and requires a session id. Any other value throws |
+| `OBSCURA_CDP_URL` | `http://127.0.0.1:${OBSCURA_PORT:-9222}` | CDP URL passed to `chromium.connectOverCDP()`. When set, it wins over `OBSCURA_PORT` for that URL |
+| `OBSCURA_PORT` | `9222` | TCP port for `obscura serve`. Used in the default CDP URL when `OBSCURA_CDP_URL` is unset. The launcher refuses to start when this port disagrees with the port in `OBSCURA_CDP_URL` |
+| `STEEL_API_URL` | A KontextMind-operated deployment | Base URL of your Steel API. Set it before using `KXM_BROWSER=steel` |
+| `STEEL_UI_URL` | `$STEEL_API_URL/ui` | Base URL of the Steel session viewer |
+| `STEEL_API_KEY` | A `pass-cli` lookup | Steel API key. When unset, the library runs a `pass-cli` lookup of a fixed KontextMind vault item |
+| `USE_PASS_CLI` | enabled | Set to `false` to disable that `pass-cli` fallback |
+
+Obscura's own `OBSCURA_TIMEZONE` (default `Europe/Berlin`) and `OBSCURA_CDP_TOKEN` (required only for a non-loopback bind) are read by the Obscura process, not by KXM.
+
 ## Internal variables
 
 KXM sets these for its own child processes. Do not set them yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.132",
+  "version": "0.7.133",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -38,6 +38,7 @@
     "test:simulations": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/simulations/*.test.ts",
     "test:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts test/simulations/*.test.ts",
     "test": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
+    "e2e": "node scripts/obscura.mjs --ensure && playwright test",
     "test:coverage:core": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=91 --test-coverage-branches=80 --test-coverage-functions=92 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
     "test:coverage:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=93 --test-coverage-branches=80 --test-coverage-functions=93 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts test/simulations/*.test.ts packages/core/*/tests/unit/*.test.ts",
     "test:coverage": "npm run test:coverage:core",
@@ -95,6 +96,7 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.86.1",
     "@modelcontextprotocol/sdk": "1.30.0",
+    "@playwright/test": "1.63.0",
     "@types/node": "26.6.2",
     "ajv": "8.20.0",
     "commander": "15.0.0",

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

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

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

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

package/plugins/kxm/dist/runtime.js

@@ -33383,6 +33383,40 @@ function formatCDPEndpoint(session, config) {
   }
   return `${wsProtocol}//${host}/v1/devtools?${searchParams.toString()}`;
 }
+var DEFAULT_OBSCURA_CDP_URL = "http://127.0.0.1:9222";
+var DEFAULT_OBSCURA_PORT = 9222;
+function obscuraListenPort() {
+  const raw = process.env.OBSCURA_PORT?.trim() ?? "";
+  if (raw === "") return DEFAULT_OBSCURA_PORT;
+  if (!/^[0-9]+$/.test(raw)) {
+    throw new Error(`OBSCURA_PORT must be an integer from 1 to 65535 (received ${JSON.stringify(process.env.OBSCURA_PORT)})`);
+  }
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`OBSCURA_PORT must be an integer from 1 to 65535 (received ${JSON.stringify(process.env.OBSCURA_PORT)})`);
+  }
+  return port;
+}
+function resolveObscuraCdpEndpoint() {
+  const explicit = process.env.OBSCURA_CDP_URL?.trim() ?? "";
+  if (explicit !== "") return explicit;
+  const port = obscuraListenPort();
+  if (port === DEFAULT_OBSCURA_PORT) return DEFAULT_OBSCURA_CDP_URL;
+  return `http://127.0.0.1:${port}`;
+}
+function resolveBrowserCdpEndpoint(session, config) {
+  const browser = (process.env.KXM_BROWSER ?? "").trim().toLowerCase();
+  if (browser === "" || browser === "obscura") {
+    return resolveObscuraCdpEndpoint();
+  }
+  if (browser === "steel") {
+    if (!session?.id) {
+      throw new Error("KXM_BROWSER=steel requires a Steel session id");
+    }
+    return formatCDPEndpoint(session, config ?? resolveSteelConfig());
+  }
+  throw new Error(`Unsupported KXM_BROWSER value ${JSON.stringify(process.env.KXM_BROWSER)}; expected "obscura" or "steel"`);
+}
 function sanitizeLogOutput(input) {
   if (typeof input === "string") {
     return input.replace(/apiKey=[^&]+/g, "apiKey=[REDACTED]").replace(/steel_[a-f0-9]+/g, "steel_[REDACTED]");
@@ -34612,6 +34646,7 @@ export {
   DEFAULT_LOG_MAX_BYTES,
   DEFAULT_LOG_MAX_FILES,
   DEFAULT_MODES_CONFIG,
+  DEFAULT_OBSCURA_CDP_URL,
   DEFAULT_RUNTIME_STOP_GRACE_MS,
   DEFAULT_RUNTIME_SYNC_INTERVAL_MS,
   DEFAULT_SOCKET_DIR,
@@ -34764,7 +34799,9 @@ export {
   redactLogValue,
   registerKxmRuntimeCloseHook,
   resolveActiveMode,
+  resolveBrowserCdpEndpoint,
   resolveDispatchStatus,
+  resolveObscuraCdpEndpoint,
   resolvePassCliApiKey,
   resolveSshHostG,
   resolveSteelConfig,