@kontextmind/kxm 0.7.95 → 0.7.97

package/docs/prompts/browser-diagnose-recover.md

@@ -2,43 +2,44 @@
 schema: "kxm.doc.v1"
 id: "PROMPT-BROWSER-004"
 type: "prompt"
-title: "Diagnosing and Recovering a Failed Browser Session"
+title: "Diagnose and recover a failed browser session"
 project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-15"
+updated: "2026-09-23"
 authority: "instruction"
 confidence: "verified"
 summary: "Troubleshoot unresponsive Steel sessions, CDP attachment errors, auth loops, and orphaned browser containers."
 tags: ["browser", "diagnostics", "recovery", "prompt"]
-related: ["docs/browser-automation.md", "docs/kb/how-to-recover-expired-session-or-orphan.md"]
+related: ["docs/guides/browser-automation.md", "docs/kb/how-to-recover-expired-session-or-orphan.md"]
 ---
 
-# Task Template: Diagnosing and Recovering a Failed Browser Session
+# Task template: diagnose and recover a failed browser session
 
 ## Purpose
 
-Use this prompt to troubleshoot unresponsive sessions, CDP attachment errors, authentication loops, or orphaned browser containers on DOKS Steel infrastructure.
+Use this prompt to troubleshoot unresponsive sessions, CDP attachment errors, authentication loops, or orphaned browser containers on your Steel deployment.
 
-## Canonical Skill References
+## Canonical skill references
 
 - `kxm-browser-diagnostics`
 - `kxm-browser-session`
 
-## Parameters & Placeholders
+## Parameters and placeholders
 
 - **PROJECT_ID**: `{{PROJECT_ID}}`
+- **STEEL_API_URL**: `{{STEEL_API_URL}}` (your Steel API base URL, from `STEEL_API_URL`)
 - **SESSION_ID**: `{{SESSION_ID}}` (Optional, if specific session is failing)
 - **FAILURE_SYMPTOM**: `{{FAILURE_SYMPTOM}}` (e.g. `CDP_ATTACHMENT_FAILED` | `TIMEOUT_EXPIRED` | `AUTH_LOOP` | `ORPHAN_CLEANUP`)
 - **MAX_IDLE_MINUTES**: `{{MAX_IDLE_MINUTES}}` (Default: `10`)
 
 ---
 
-## Instructions for Agent
+## Instructions for the agent
 
 1. **Check Steel Health**:
-   - Query `https://steel.kontextmind.com/v1/health`.
+   - Query `{{STEEL_API_URL}}/v1/health`.
    - If HTTP 200, Steel server and Chromium engine are healthy.
 
 2. **Inspect Session Status**:
@@ -51,5 +52,5 @@ Use this prompt to troubleshoot unresponsive sessions, CDP attachment errors, au
    - For each orphan, invoke `POST /v1/sessions/:id/release`.
 
 4. **Verify WebSocket / CDP Ingress**:
-   - Ensure WebSocket upgrades are properly proxied through `nginx.ingress.kubernetes.io/websocket-services: "steel"`.
+   - Ensure the reverse proxy or ingress in front of Steel passes WebSocket upgrades through. On Kubernetes with ingress-nginx, that is the `nginx.ingress.kubernetes.io/websocket-services` annotation.
    - If CDP fails with 401, verify `x-steel-api-key` header or `?apiKey=` query parameter.

package/docs/prompts/browser-explore.md

@@ -2,32 +2,32 @@
 schema: "kxm.doc.v1"
 id: "PROMPT-BROWSER-002"
 type: "prompt"
-title: "Exploring an Application with an Authenticated Session"
+title: "Explore an application with an authenticated session"
 project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-15"
+updated: "2026-09-23"
 authority: "instruction"
 confidence: "verified"
 summary: "Exploratory discovery, DOM mapping, and journey inspection via agent-browser attached to a remote Steel session."
 tags: ["browser", "explore", "agent-browser", "prompt"]
-related: ["docs/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-steel.md"]
 ---
 
-# Task Template: Exploring an Application with an Authenticated Session
+# Task template: explore an application with an authenticated session
 
 ## Purpose
 
 Use this prompt to perform exploratory discovery, DOM mapping, flow analysis, or user-journey inspection using `agent-browser` connected to a remote Steel session.
 
-## Canonical Skill References
+## Canonical skill references
 
 - `kxm-browser-explore`
 - `kxm-browser-session`
 - `kxm-browser-takeover`
 
-## Parameters & Placeholders
+## Parameters and placeholders
 
 - **PROJECT_ID**: `{{PROJECT_ID}}`
 - **TASK_ID**: `{{TASK_ID}}`
@@ -39,7 +39,7 @@ Use this prompt to perform exploratory discovery, DOM mapping, flow analysis, or
 
 ---
 
-## Instructions for Agent
+## Instructions for the agent
 
 1. **Attach to Active Session**:
    - Verify `sessionId` and connect `agent-browser` via the remote CDP endpoint.

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

@@ -2,32 +2,32 @@
 schema: "kxm.doc.v1"
 id: "PROMPT-BROWSER-005"
 type: "prompt"
-title: "Reproducing a UI Bug and Producing a Playwright Regression Test"
+title: "Reproduce a UI bug and produce a Playwright regression test"
 project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-15"
+updated: "2026-09-23"
 authority: "instruction"
 confidence: "verified"
 summary: "Reproduce a UI defect on Steel, collect evidence, write a Playwright regression, and prove RED then GREEN."
 tags: ["browser", "playwright", "repro", "prompt"]
-related: ["docs/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-steel.md"]
 ---
 
-# Task Template: Reproducing a UI Bug and Producing a Playwright Regression Test
+# 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).
 
-## Canonical Skill References
+## Canonical skill references
 
 - `kxm-browser-verify`
 - `kxm-browser-session`
 - `kxm-browser-diagnostics`
 
-## Parameters & Placeholders
+## Parameters and placeholders
 
 - **PROJECT_ID**: `{{PROJECT_ID}}`
 - **BUG_ID**: `{{BUG_ID}}` (e.g. `BUG-402-DROPDOWN-CLIPPING`)
@@ -39,7 +39,7 @@ Use this prompt to execute the full UI defect lifecycle: reproducing reported sy
 
 ---
 
-## Instructions for Agent
+## Instructions for the agent
 
 1. **Step 1: Reproduce**:
    - Connect to a Steel browser session and manually or scriptedly walk the repro steps.

package/docs/prompts/browser-start.md

@@ -2,50 +2,51 @@
 schema: "kxm.doc.v1"
 id: "PROMPT-BROWSER-001"
 type: "prompt"
-title: "Starting Browser Work in a KXM Project"
+title: "Start browser work in a KXM project"
 project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-15"
+updated: "2026-09-23"
 authority: "instruction"
 confidence: "verified"
 summary: "Initialize a remote Steel browser session for a project task, verifying credentials, connectivity, and attachment endpoints before automation."
 tags: ["browser", "steel", "session", "prompt"]
-related: ["docs/browser-automation.md", "docs/kb/how-credentials-retrieved-safely.md"]
+related: ["docs/guides/browser-automation.md", "docs/kb/how-credentials-retrieved-safely.md"]
 ---
 
-# Task Template: Starting Browser Work in a KXM Project
+# Task template: start browser work in a KXM project
 
 ## Purpose
 
 Use this prompt to initialize a remote browser session on self-hosted Steel for a specific project task, verifying infrastructure connectivity, credentials, and attachment endpoints before executing automation.
 
-## Canonical Skill References
+## Canonical skill references
 
 - `kxm-browser-session`
 - `kxm-browser-auth`
 
-## Parameters & Placeholders
+## Parameters and placeholders
 
-- **PROJECT_ID**: `{{PROJECT_ID}}` (e.g. `kxm`, `agentic-hub`, `southlake-technical`)
+- **PROJECT_ID**: `{{PROJECT_ID}}` (e.g. `my-app`)
+- **STEEL_API_URL**: `{{STEEL_API_URL}}` (your Steel API base URL, from `STEEL_API_URL`)
 - **TASK_ID**: `{{TASK_ID}}` (e.g. `TASK-104-AUTH-VERIFY`)
 - **TARGET_BASE_URL**: `{{TARGET_BASE_URL}}` (e.g. `https://staging.app.example.com`)
 - **PERMISSION_LEVEL**: `{{PERMISSION_LEVEL}}` (Choose one: `INSPECT_ONLY` | `MUTATE_APPROVED_FORMS` | `FULL_ADMIN`)
-- **CREDENTIAL_REF**: `{{CREDENTIAL_REF}}` (Proton Pass vault and item title, e.g. `Personal -> staging.example.com`)
+- **CREDENTIAL_REF**: `{{CREDENTIAL_REF}}` (a secret manager reference, never a value, e.g. `<vault> -> <item>`)
 - **ARTIFACT_DIR**: `{{ARTIFACT_DIR}}` (e.g. `.kxm/artifacts/browser/{{TASK_ID}}`)
 - **TIMEOUT_MS**: `{{TIMEOUT_MS}}` (Default: `300000`)
 
 ---
 
-## Instructions for Agent
+## Instructions for the agent
 
 1. **Verify Credential Reference**:
-   - Query `pass-cli` for target credentials and `STEEL_API_KEY` without logging raw values.
+   - Resolve the target credentials and `STEEL_API_KEY` from the secret manager, for example with `pass-cli`, without logging raw values.
    - Do not print credentials to the chat or save them to tracked files.
 
 2. **Launch Remote Steel Session**:
-   - Create a session on `https://steel.kontextmind.com/v1/sessions` with timeout `{{TIMEOUT_MS}}`.
+   - Create a session with `POST {{STEEL_API_URL}}/v1/sessions` and timeout `{{TIMEOUT_MS}}`.
    - Capture `sessionId`, `websocketUrl`, and `sessionViewerUrl`.
 
 3. **Verify Target Endpoint Connectivity**:

package/docs/prompts/browser-takeover.md

@@ -2,32 +2,32 @@
 schema: "kxm.doc.v1"
 id: "PROMPT-BROWSER-003"
 type: "prompt"
-title: "Requesting Human Authentication and Resuming Afterward"
+title: "Request human authentication and resume afterward"
 project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-15"
+updated: "2026-09-23"
 authority: "instruction"
 confidence: "verified"
 summary: "Pause automation for MFA, OAuth, or CAPTCHA takeover, then resume after verified human success."
 tags: ["browser", "takeover", "mfa", "prompt"]
-related: ["docs/browser-automation.md", "docs/kb/how-to-take-over-session.md", "docs/kb/how-to-resume-after-mfa.md"]
+related: ["docs/guides/browser-automation.md", "docs/kb/how-to-take-over-session.md", "docs/kb/how-to-resume-after-mfa.md"]
 ---
 
-# Task Template: Requesting Human Authentication and Resuming Afterward
+# Task template: request human authentication and resume afterward
 
 ## Purpose
 
 Use this prompt to pause automation and request operator intervention for multi-factor authentication (MFA), OAuth consent, credential challenges, or CAPTCHAs, then safely resume automation after verified success.
 
-## Canonical Skill References
+## Canonical skill references
 
 - `kxm-browser-takeover`
 - `kxm-browser-session`
 - `kxm-browser-auth`
 
-## Parameters & Placeholders
+## Parameters and placeholders
 
 - **PROJECT_ID**: `{{PROJECT_ID}}`
 - **TASK_ID**: `{{TASK_ID}}`
@@ -35,11 +35,11 @@ Use this prompt to pause automation and request operator intervention for multi-
 - **REASON_FOR_TAKEOVER**: `{{REASON_FOR_TAKEOVER}}` (e.g. "SMS / TOTP MFA challenge detected on login form")
 - **EXPECTED_POST_AUTH_URL**: `{{EXPECTED_POST_AUTH_URL}}` (e.g. `https://app.example.com/dashboard`)
 - **EXPECTED_INDICATOR**: `{{EXPECTED_INDICATOR}}` (e.g. "Header user avatar or dashboard navigation visible")
-- **TAKEOVER_URL**: `https://steel.kontextmind.com/ui?sessionId={{SESSION_ID}}`
+- **TAKEOVER_URL**: `{{STEEL_UI_URL}}?sessionId={{SESSION_ID}}` (`STEEL_UI_URL`, or `{{STEEL_API_URL}}/ui` when that is unset)
 
 ---
 
-## Instructions for Agent
+## Instructions for the agent
 
 1. **Halt Automated Actions Immediately**:
    - Stop issuing automated clicks, keystrokes, or page reloads.