@kontextmind/kxm 0.7.95 → 0.7.96

package/docs/README.md

@@ -1,58 +1,137 @@
-# Documentation
-
-This documentation is organized by task. Start with the guide that matches what you are trying to accomplish.
-
-| Guide | Audience | Purpose |
-|---|---|---|
-| [KXM Handbook](kxm-handbook.md) | Operators, Pi users, and Claude Code users | Wiki-ready installation, configuration, and complete feature guide |
-| [Getting started](getting-started.md) | Pi and Claude Code users | Complete the first successful multi-agent exchange |
-| [Configuration](configuration.md) | Users and operators | Understand every supported setting and default |
-| [CLI reference](cli-reference.md) | Operators and agent authors | Every `kxm` command and subcommand with options, JSON output, and examples |
-| [Configuration file reference](config-reference.md) | Project and workflow authors | Every `.kxm` file schema field by field, with validated examples and a worked two-step project |
-| [Native harness or OpenRouter](harness-routing.md) | Operators choosing models | Decide which route runs a model reachable both natively and through an aggregator, and confirm which route a config line uses |
-| [Architecture](architecture.md) | Maintainers and integrators | Learn the component boundaries and message lifecycle |
-| [Terminal components](tui-components.md) | Maintainers and integrators | The reusable panel kit behind `kxm dash` and every configuration surface |
-| [Packages and workspaces](packages.md) | Maintainers | Workspace layout, Nx targets, Bun task running, and the layer gate |
-| [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. See the [knowledge base](browser-automation.md#knowledge-base) and [prompt templates](browser-automation.md#prompt-templates) |
-| [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 |
-| [Webhook workflows](webhook-workflows.md) | Automation owners | Start durable work from Jira or another signed webhook |
-| [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 |
-| [KXM contract package](contracts/README.md) | Maintainers and reviewers | Review the accepted local-first target architecture and implementation contracts |
-
-Project-level policies live at the repository root:
+# KXM documentation
 
-- [Contributing](../CONTRIBUTING.md)
-- [Security](../SECURITY.md)
-- [Changelog](../CHANGELOG.md)
+KXM connects coding agents through a durable, authenticated [hub](glossary.md#hub) and runs workflows in a local [Runtime](glossary.md#runtime). Start with a quick start, use the guides for tasks, and use the reference for exact commands, files, tools and endpoints. The [glossary](glossary.md) defines every term these pages use.
+
+**Groups:** [Start here](#start-here) · [Guides](#guides) · [Reference](#reference) · [Concepts](#concepts) · [Operations](#operations) · [Contributing](#contributing)
+
+## Start here
+
+| Page | For | What you get |
+|---|---|---|
+| [Install KXM](start/install.md) | Everyone | The `kxm` CLI from npm, the Claude Code plugin, the Pi package, or a source checkout |
+| [Quick start: Claude Code](start/quickstart-claude-code.md) | Claude Code users | A new or existing project connected to a local hub, and how to update the CLI and plugin |
+| [Run your first workflow](start/first-workflow.md) | Project owners | A workflow written, trust-reviewed, run and driven to a verified receipt |
+| [Quick start: Pi](start/quickstart-pi.md) | Pi users | Two Pi agents, or Pi and Claude Code, exchanging peer requests |
+| [Glossary](glossary.md) | Everyone | Every KXM term, including the ones that are easy to confuse |
+
+## Guides
+
+| Page | For | What you get |
+|---|---|---|
+| [Message peer agents](guides/peer-messaging.md) | Agent users | Send, await, fan out, cancel and reply; delivery modes, TTL and idempotency |
+| [Run supervised Pi workers](guides/pi-workers.md) | Operators | Long-lived Pi agents with fallbacks, tool allowlists and one session per workflow run |
+| [Run webhook workflows](guides/webhook-workflows.md) | Automation owners | Signed starts from Jira, GitHub or any webhook, durable waits and signed callbacks |
+| [Peer provenance and quorum gates](guides/provenance-gates.md) | Workflow authors, security reviewers | Stages that require hub-verified replies from eligible peers |
+| [Context and memory](guides/context-and-memory.md) | Agent users, project owners | Context packets, recall, temporal state, episodes, the wiki and Git memory |
+| [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 |
+| [Nous providers](guides/nous-providers.md) | Pi operators | Opt-in Nous Portal models for Pi agents |
+
+### Browser knowledge base
+
+| Page | For | What you get |
+|---|---|---|
+| [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 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 |
+| [Why did authentication disappear?](kb/why-authentication-disappeared.md) | Browser operators | Causes and fixes for a lost login |
+| [Why did automation open a different browser?](kb/why-automation-opened-different-browser.md) | Browser operators | Causes and fixes when a local browser opens instead of the Steel session |
+| [Why can I view a session but not control it?](kb/why-session-viewer-cannot-control.md) | Browser operators | Why the viewer shows the stream but not your clicks, and what to use instead |
+
+### Browser prompt templates
+
+| Page | For | What you get |
+|---|---|---|
+| [Task template: start browser work in a KXM project](prompts/browser-start.md) | Agent operators | A prompt that opens browser work in a KXM project |
+| [Task template: explore an application with an authenticated session](prompts/browser-explore.md) | Agent operators | A prompt for exploring with an authenticated session |
+| [Task template: reproduce a UI bug and produce a Playwright regression test](prompts/browser-repro-fix.md) | Agent operators | A prompt that ends in a Playwright regression test |
+| [Task template: capture UI section annotations and send changes to an agent](prompts/browser-annotate-feedback.md) | Agent operators | A prompt that turns section annotations into changes |
+| [Task template: request human authentication and resume afterward](prompts/browser-takeover.md) | Agent operators | A prompt that asks a person to log in, then resumes |
+| [Task template: diagnose and recover a failed browser session](prompts/browser-diagnose-recover.md) | Agent operators | A prompt for a failed browser session |
+
+## Reference
+
+| Page | For | What you get |
+|---|---|---|
+| [KXM CLI reference](reference/cli-reference.md) | Operators, agent authors | Every `kxm` command with its options, output and examples |
+| [KXM configuration file reference](reference/config-reference.md) | Project and workflow authors | Every `.kxm` file field by field, the workspace layout and configuration layers |
+| [Environment variables and limits](reference/configuration.md) | Operators | Environment variables, limits and defaults for the hub, agents and workers |
+| [Harness routing: native harness or Pi aggregator](reference/harness-routing.md) | Operators choosing models | Native harness or Pi route for a model, admission, and how to check the route used |
+| [Agent tools reference](reference/tools.md) | Agent authors | The `kxm_*` MCP and Pi tools, `/kxm` commands, plugin hooks and plugin options |
+| [Hub HTTP API reference](reference/http-api.md) | Integrators, operators | Hub endpoints for health, metrics, operations, messages, webhooks, signals, leases and sync |
+| [Workflow definition reference](reference/workflow-definitions.md) | Workflow authors | Webhook definition fields, evidence policies and `kxm.workflow.v1` steps |
+| [Workflow catalog](reference/workflow-catalog.md) | Workflow designers | The area, workflow, stage and role taxonomy, with the docs each workflow relies on |
+| [KXM Claude Code plugin](../plugins/kxm/README.md) | Claude Code users | Plugin options, tokens, the SessionStart hook, tools, channel mode and fixes |
+
+## Concepts
+
+| Page | For | What you get |
+|---|---|---|
+| [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) |
+| [KXM contract package](contracts/README.md) | Maintainers, reviewers | The normative specifications for the local-first architecture, listed below |
+
+### Contracts
+
+| Page | For | What you get |
+|---|---|---|
+| [ADR-001: Local Runtime, project authority, and aggregate hub](contracts/architecture.md) | Maintainers | The architecture decision the contracts implement |
+| [Canonical terminology](contracts/terminology.md) | All contributors | The normative definitions the [glossary](glossary.md) builds on |
+| [Durable lifecycles](contracts/lifecycles.md) | Maintainers | Run, step, assignment, attempt, effect and delivery states |
+| [Effects, idempotency, and recovery](contracts/effects-and-recovery.md) | Maintainers | Effect classes, the crash matrix, `blocked_uncertain` and recovery rules |
+| [Hub synchronization contract](contracts/synchronization.md) | Maintainers | What the Runtime sends the hub, and how the hub accepts it |
+| [Routing and cost telemetry](contracts/routing.md) | Maintainers | Routing records, cost bases and the routing report |
+| [Configuration and contract validation](contracts/validation.md) | Maintainers | The YAML parser profile, the validation pipeline, schema evolution and the gate registry |
+| [Migration and compatibility](contracts/migration.md) | Maintainers, operators | What KXM refuses rather than converts, and why |
+
+## Operations
+
+| Page | For | What you get |
+|---|---|---|
+| [Deploy KXM](operations/deploy.md) | Hub operators | Deployment classes, supervision, and hosted per-tenant hubs behind a proxy |
+| [Monitor KXM](operations/monitoring.md) | Hub operators | `kxm dash`, health and readiness, metrics, logs and alerts |
+| [Back up and restore KXM](operations/backup-and-restore.md) | Hub operators | `kxm backup` and `kxm restore`, the state roots, and a stopped-hub recipe |
+| [Upgrade KXM](operations/upgrade.md) | Operators | `kxm update`, the plugin reinstall, rollback and schema ceilings |
+| [Operate Runtime sync and leases](operations/runtime-sync.md) | Operators | The Runtime-to-hub outbox, refusals, `kxm runtime sync-retry` and leases |
+| [Troubleshoot KXM](operations/troubleshooting.md) | Everyone | Symptoms, causes and fixes, grouped by area |
+
+## Contributing
+
+| Page | For | What you get |
+|---|---|---|
+| [Develop KXM](contributing/development.md) | Contributors | Setup, build and verify, packaging, and the repository layout |
+| [CI and release](contributing/ci-and-release.md) | Maintainers | What CI runs on each change and how releases ship |
+| [Write KXM documentation](contributing/writing-docs.md) | Contributors | The style rules, the page template and the docs checks |
+| [Test matrix](contributing/test-matrix.md) | Maintainers | Features and use cases mapped to automated evidence |
+| [Assignment runner](contributing/assignment-runner.md) | Maintainers | Developer assignments, witness verification and dual-critic acceptance |
+| [Packages and workspaces](contributing/packages.md) | Maintainers | Workspace layout, Nx targets, Bun task running and the layer gate |
+| [KXM terminal components](contributing/tui-components.md) | Maintainers, integrators | The panel kit behind `kxm dash` |
+| [Repository work delivery skill](contributing/repo-work-delivery.md) | Contributors | The repository-local skill for delivering a change |
+| [Artifact templates](templates/README.md) | Workflow authors | Document templates and where workflows use them |
+
+The templates: [feature](templates/feature.md) · [bug fix](templates/bug-fix.md) · [ADR](templates/adr.md) · [architecture](templates/architecture.md) · [research](templates/research.md) · [review](templates/review.md) · [test plan](templates/test-plan.md) · [test report](templates/test-report.md) · [runbook](templates/runbook.md) · [postmortem](templates/postmortem.md) · [handoff](templates/handoff.md).
 
 ## Documentation principles
 
-- Put the shortest successful path before optional details.
-- Use the product terms **hub**, **agent**, **peer**, **project**, **request**, and **reply** consistently.
-- Distinguish verified behavior from planned behavior; `docs/contracts` is a planned normative target until activation.
-- Distinguish durable single-node delivery from clustering and exactly-once execution.
-- Update the relevant guide in the same change that modifies user-visible behavior.
-
-## Which docs each workflow relies on
-
-Cross-reference only. Guide slugs imply no runtime config, admission, schema, or
-CLI behavior.
-
-| Workflow slug | Primary docs |
-|---|---|
-| `build-feature` | [Getting started](getting-started.md), [Configuration](configuration.md), [Architecture](architecture.md), [Test matrix](test-matrix.md) |
-| `refactor-repair-regressions` | [Architecture](architecture.md), [Test matrix](test-matrix.md), [Troubleshooting](troubleshooting.md), [Provenance gates](provenance-gates.md) |
-| `stabilize-flaky-tests` | [Test matrix](test-matrix.md), [Operations](operations.md), [Troubleshooting](troubleshooting.md) |
-| `design-software-system` | [Architecture](architecture.md), [Configuration](configuration.md), [KXM contracts](contracts/README.md) |
-| `investigate-incident` | [Operations](operations.md), [Troubleshooting](troubleshooting.md), [Webhook workflows](webhook-workflows.md) |
-| `patch-vulnerability` | [Provenance gates](provenance-gates.md), [Operations](operations.md), [Configuration](configuration.md) |
+- **Shortest path first.** Each page opens with what it helps you do; the working path comes before options and background.
+- **Current behavior only.** Pages describe what the code does today, with no release numbers in prose. Planned behavior lives in [contracts](contracts/README.md) and [decisions](adr/README.md), marked as planned. Changes are recorded in the [changelog](../CHANGELOG.md).
+- **Honest boundaries.** Wherever a feature could be over-read, the page says what is not guaranteed: single node, at-least-once delivery, no sandboxing, provenance rather than truth.
+- **One vocabulary.** Pages use the [glossary](glossary.md) terms and qualify overloaded words such as run, session, gate, skill and project.
+- **Bash first.** Examples show Bash; PowerShell appears only where the syntax differs.
+- **Docs change with code.** A change to user-visible behavior updates the relevant page in the same pull request. [Write KXM documentation](contributing/writing-docs.md) has the full style guide.
+
+## Related
+
+- [Project README](../README.md)
+- [Contributing](../CONTRIBUTING.md)
+- [Security policy](../SECURITY.md)
+- [Code of conduct](../CODE_OF_CONDUCT.md)
+- [Changelog](../CHANGELOG.md)
+- [License](../LICENSE)

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

@@ -2,7 +2,7 @@
 schema: "kxm.doc.v1"
 id: "ADR-0002"
 type: "adr"
-title: "Self-Hosted Steel on DOKS for Reusable Browser Automation and Human Takeover"
+title: "Self-hosted Steel on DOKS for reusable browser automation and human takeover"
 project: "kxm"
 status: "accepted"
 owner: "@operator"
@@ -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/browser-automation.md", "docs/agent-skills.md"]
+related: ["docs/guides/browser-automation.md", "docs/guides/agent-skills.md"]
 details:
   decision_drivers:
     - "Eliminate per-minute SaaS browser provider costs"
@@ -23,9 +23,9 @@ details:
   superseded_by: null
 ---
 
-# ADR-0002: Self-Hosted Steel on DOKS for Reusable Browser Automation
+# ADR-0002: Self-hosted Steel on DOKS for reusable browser automation
 
-## Context & Problem Statement
+## Context and problem statement
 
 AI coding agents and orchestration workflows in KXM require browser interaction for UI exploration, DOM mapping, bug reproduction, and end-to-end regression testing. Existing approaches suffered from three core issues:
 
@@ -33,40 +33,40 @@ AI coding agents and orchestration workflows in KXM require browser interaction
 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
+## Decision drivers
 
-1. **Operating Cost Control**: Keep infrastructure expenses predictable by utilizing our existing DigitalOcean Kubernetes Service (DOKS) cluster (`k8s-agentic-hub`).
+1. **Operating Cost Control**: Keep infrastructure expenses predictable by utilizing the maintainers' existing DigitalOcean Kubernetes Service (DOKS) cluster.
 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
+## 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
+## Evaluation and trade-offs
 
-### Option A: Self-hosted Steel on DOKS (Chosen)
+### 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**: Both `Playwright` and `agent-browser` connect seamlessly over standard CDP (`wss://<steel-host>/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
+### Option B: a 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
+### 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
+## Decision outcome
 
 **Chosen Option**: **Option A (Self-hosted Steel on DOKS)**.
 
@@ -74,14 +74,14 @@ AI coding agents and orchestration workflows in KXM require browser interaction
 
 ```text
 ┌─────────────────────────────────────────────────────────────┐
-│                      KXM Agent / Herdr                      │
+│                      KXM agent                              │
 │   (kxm-browser-session, kxm-browser-takeover, pass-cli)     │
 └───────────────┬─────────────────────────────┬───────────────┘
                 │ REST API (create/release)   │ CDP WebSocket
                 ▼                             ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                 DigitalOcean Kubernetes (DOKS)              │
-│                 https://steel.kontextmind.com               │
+│                 https://<steel-host>                        │
 │                                                             │
 │   ┌─────────────────────┐       ┌────────────────────────┐  │
 │   │   Steel API & CDP   │◄─────►│    Chromium Sandbox    │  │
@@ -96,8 +96,14 @@ AI coding agents and orchestration workflows in KXM require browser interaction
 └─────────────────────────────────────────────────────────────┘
 ```
 
-## Confirmation & Verification Strategy
+## Confirmation and verification
 
-- **Verification**: Health endpoint `https://steel.kontextmind.com/v1/health` verified with HTTP 200 and Let's Encrypt TLS.
+- **Verification**: Health endpoint `$STEEL_API_URL/v1/health` verified with HTTP 200 and Let's Encrypt TLS.
 - **Integration Test**: `test/core/browser.test.ts` validates session lifecycle, CDP endpoint formatting, takeover transitions, and secret redaction.
-- **Security Check**: `pass-cli` verified as the authoritative store for `STEEL_API_KEY` under vault `AI Provider Keys`.
+- **Security Check**: `pass-cli` verified as the authoritative store for `STEEL_API_KEY` in the operators' password manager.
+
+## Related
+
+- [Browser automation](../guides/browser-automation.md)
+- [Agent skills](../guides/agent-skills.md)
+- [Architecture decision records](README.md)

package/docs/adr/ADR-0003-sqlite-only-store.md

@@ -0,0 +1,100 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0003"
+type: "adr"
+title: "SQLite as the only store"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-17"
+updated: "2026-09-23"
+authority: "decision"
+confidence: "verified"
+summary: "Every KXM store is a local SQLite database owned by one process; DuckDB and database servers are rejected as the system of record."
+tags: ["architecture", "decision", "storage", "sqlite"]
+related: ["docs/concepts/data-and-storage.md", "docs/concepts/architecture.md", "docs/contracts/architecture.md"]
+details:
+  decision_drivers:
+    - "Many small durable reads and writes owned by one process"
+    - "No native dependencies in any install"
+    - "Must run in Node.js and in Pi's embedded Bun runtime"
+    - "Single-node deployment with no clustering or failover"
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0003: SQLite as the only store
+
+## Status
+
+Accepted. This record replaces the research note "Storage engine: SQLite vs DuckDB".
+
+## Context
+
+KXM persists state in three places: the hub store (agents, messages, workflow runs, the journal, context, leases, and sync events), the Runtime registry, and one Runtime event store per project. All three are written by a single owning process and read by a few local readers.
+
+The question came up whether KXM should use DuckDB. The premise was inverted: KXM already used SQLite everywhere, and no DuckDB code existed. The real question was whether DuckDB, or any other engine, should become the system of record.
+
+The workload has a clear shape:
+
+- **Transactional, not analytical.** Sending, delivering, and replying to messages, advancing cursors, appending run events, and moving run state are small point reads and writes by ID.
+- **One owner per database.** The hub owns its file, and the Runtime owns the registry and each event store. KXM's production boundary is one process per database, with no clustering, leader election, or shared-state failover.
+- **Two JavaScript runtimes.** The CLI, hub, and Runtime run on Node.js. The Pi extension runs inside Pi's embedded Bun runtime, which has no `node:sqlite`.
+
+## Decision drivers
+
+1. Match the storage engine to a small-write, single-writer workload.
+2. Add no native dependency to any install and no build step.
+3. Run unchanged in Node.js and in Bun.
+4. Keep the single-node boundary simple to operate, back up, and restore.
+
+## Considered options
+
+- **Option A: SQLite.** Node's built-in `node:sqlite`, with `bun:sqlite` as the fallback inside Pi.
+- **Option B: DuckDB** as the primary store.
+- **Option C: a separate database server**, such as PostgreSQL.
+
+### Option A: SQLite (chosen)
+
+- Good, because its design center is embedded, transactional, single-writer storage with point queries, which is KXM's workload.
+- Good, because the supported Node.js versions and Bun ship it built in: no native dependency and no build step.
+- Good, because WAL mode gives concurrent local readers while one process writes.
+- Bad, because one database cannot be shared by several hub processes. KXM accepts that; it is the single-node boundary.
+
+### Option B: DuckDB
+
+- Good, because it is fast at analytical scans over large, columnar datasets.
+- Bad, because that is the wrong workload for a message bus and an event log, and its concurrency model does not improve on SQLite's single writer.
+- Bad, because it adds a large native dependency to every install for no transactional benefit.
+
+### Option C: a separate database server
+
+- Good, because it could serve several hub processes.
+- Bad, because it adds a service to install, secure, and back up, which contradicts a local-first tool that runs on one machine.
+- Bad, because KXM does not cluster hubs, so the extra capability would go unused.
+
+## Decision
+
+Every KXM store is a SQLite database owned by exactly one process:
+
+- The hub store, the Runtime registry, and each Runtime event store use `STRICT` tables and record their schema version in `user_version`.
+- Every store opens in WAL mode with a busy timeout, `synchronous=NORMAL`, and foreign keys on, and refuses a database or sidecar that is a symbolic link.
+- A store whose version is older or newer than the running build is refused, not migrated. The owner recreates it after the operator deletes it.
+
+## Consequences
+
+- KXM installs anywhere a supported Node.js runs, with no database service to operate.
+- A backup is a consistent file copy made with SQLite's `VACUUM INTO`, with no dump format to maintain.
+- Scaling out means running more independent hubs, one per trust domain, not more processes per hub.
+- Upgrading across a store version discards that store's history unless the operator backs it up first. [Data and storage](../concepts/data-and-storage.md#schema-versions-refuse-do-not-migrate) describes the procedure.
+
+### Where a columnar engine could fit later
+
+Analytics over exported, append-only data, such as routing and cost reports, could outgrow SQLite queries. The right shape then is a periodic export to a separate DuckDB file used read-only for analysis. It would never become the hub's or the Runtime's system of record.
+
+## Related
+
+- [Data and storage](../concepts/data-and-storage.md)
+- [Architecture](../concepts/architecture.md)
+- [ADR-001: Local Runtime, project authority, and aggregate hub](../contracts/architecture.md)
+- [Architecture decision records](README.md)

package/docs/adr/ADR-0004-edge-identity-authentik.md

@@ -0,0 +1,99 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0004"
+type: "adr"
+title: "Edge identity with Authentik; the hub owns no browser identity"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-17"
+updated: "2026-09-23"
+authority: "decision"
+confidence: "reviewed"
+summary: "For a hosted, one-tenant-per-box deployment, Authentik authenticates browsers at the reverse proxy and a portal backend calls the loopback hub with existing machine credentials. Hub-side JWT verification and a token broker are rejected, not deferred."
+tags: ["architecture", "decision", "hosting", "authentik", "oidc", "auth"]
+related: ["docs/concepts/trust-model.md", "docs/operations/deploy.md", "docs/concepts/architecture.md"]
+details:
+  decision_drivers:
+    - "One tenant per box, not one hub for many unrelated users"
+    - "Keep the hub's machine credentials and loopback default unchanged"
+    - "A browser-path outage must not stop authorized machine clients"
+    - "No new identity code inside the hub"
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0004: Edge identity with Authentik; the hub owns no browser identity
+
+## Status
+
+Accepted on 2026-09-20. This record replaces the research note "Authentik (OIDC) for user, role, and agent authentication". Options 2 and 3 below were the recommendation for about a month before this decision; they are recorded as rejected, not deferred.
+
+## Context
+
+KXM is hosted as **one tenant per box**: each tenant gets its own hub and Runtime on a dedicated machine, behind a web portal. Browsers need real user authentication for that portal. The question was where user identity should live.
+
+The hub knows three machine credentials, and none carries a user, role, or group:
+
+1. **The admin token** (`KXM_AUTH_TOKEN`), generated and saved by `kxm hub start` when absent. It gates admin routes such as `/metrics`, the operations stream, quorum degradation, and state promotion.
+2. **Project tokens** (`KXM_PROJECT_TOKENS`), a static map read at startup. Every agent route checks the caller's project token.
+3. **Agent keys**, minted at registration and rotated at every reconnect. An agent record has no owner or principal field.
+
+The hub binds loopback by default and refuses to bind beyond loopback without an admin token. Roles and tool policies are not hub-authenticated: the role sent with a context request only selects a context budget and journal categories, and tool policy comes from unsigned, locally minted session tokens. No OIDC, JWT, or JWKS code exists in KXM.
+
+## Decision drivers
+
+1. The deployment is one tenant per box, not one shared hub for many unrelated users.
+2. Machine clients (agents, the Runtime, and the portal backend) already authenticate with working credentials.
+3. A failure on the browser path must deny browsers without stopping authorized machine clients.
+4. The hub should not gain an identity subsystem, a network dependency at authentication time, or a token store.
+
+## Considered options
+
+1. **Forward authentication at the reverse proxy.** An Authentik proxy outpost authenticates browser sessions at the tenant's existing proxy. The hub is unchanged.
+2. **Hub-side JWT verification.** The hub would accept Authentik-issued tokens, verify them against the issuer's keys, and map group claims to admin and project scope.
+3. **A token broker.** A new service or hub route would accept an Authentik ID token and mint per-user project tokens and signed session tokens with tool policies derived from groups.
+
+### Option 1: forward authentication at the proxy (chosen)
+
+- Good, because it is configuration only: no hub code changes.
+- Good, because the hub keeps its token check, and a non-loopback bind still requires a token, so the proxy cannot make the hub anonymous.
+- Good, because an Authentik outage denies browsers but leaves machine clients working.
+- Bad, because the hub records no per-user identity. The portal must keep its own user audit.
+- Bad, because a misconfigured proxy that injects the admin token for every signed-in user would make every user a hub administrator.
+
+### Option 2: hub-side JWT verification (rejected)
+
+- Good, because hub writes could carry a real user principal.
+- Bad, because it adds discovery, key caching, clock-skew handling, and algorithm restrictions to the hub, plus a network dependency at authentication time that must fail closed.
+- Bad, because clients would need token refresh, since access tokens expire.
+
+### Option 3: a token broker (rejected)
+
+- Good, because agents and people would share one identity source.
+- Bad, because project tokens are static at startup, so per-user tokens would need a dynamic token store in the hub.
+- Bad, because a broker-issued session token means nothing until session tokens are signed and verified, which they are not.
+- Bad, because it touches token storage, signing, and revocation at once.
+
+## Decision
+
+Authentik authenticates and authorizes browsers at each tenant's reverse proxy, on the portal's routes. The portal's server-side backend calls the loopback hub and Runtime supervisor with the machine credentials that already work. The hub binds loopback, exposes no public listener, and never receives or interprets a browser identity header.
+
+These stay exactly as they are: the admin-token requirement for a non-loopback bind, the generated and saved admin token, project tokens read at startup, and loopback convenience for local use.
+
+Hub-side JWT verification, mapping groups to tool policies, token signing, dynamic per-user token stores, and OAuth client-credentials or device-flow login for agents are **rejected, not deferred**. Reopening any of them requires a new written decision that names what the portal boundary cannot do, such as per-user attribution of hub writes inside KXM, which per-box tenancy does not need.
+
+## Consequences
+
+- Per-user identity, authorization, and audit belong to the portal and the proxy, not to KXM.
+- Never configure the proxy to add the admin token to every authenticated request. The portal backend holds hub credentials server-side.
+- Agents keep authenticating with project tokens. Holders of one project token remain one trust domain, as the [trust model](../concepts/trust-model.md) describes.
+- Session tokens remain unsigned local tool-policy hints, not identity.
+- One hardening item stays open and is not a hosting prerequisite: the Studio mutation endpoint compares its session token with a plain string comparison and should use a timing-safe one.
+
+## Related
+
+- [Trust model](../concepts/trust-model.md)
+- [Deploy KXM](../operations/deploy.md)
+- [Architecture](../concepts/architecture.md)
+- [Architecture decision records](README.md)

package/docs/adr/README.md

@@ -0,0 +1,33 @@
+# Architecture decision records
+
+An architecture decision record (ADR) captures one significant decision about KXM: the context, the options considered, what was chosen, and what follows from it. Read these when you want to know why KXM works the way it does, or before you propose to change one of these decisions.
+
+## Index
+
+| ADR | Decision | Status | Date |
+|---|---|---|---|
+| [ADR-001](../contracts/architecture.md) | Local Runtime, project authority, and aggregate hub | Accepted target | — |
+| [ADR-0002](ADR-0002-browser-automation-steel-doks.md) | Self-hosted Steel for reusable browser automation and human takeover | Accepted | 2026-09-14 |
+| [ADR-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-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.
+
+> [!NOTE]
+> ADR-001 is an accepted target. It describes the intended split between the Runtime and the hub, and parts of it are not implemented yet. [Architecture](../concepts/architecture.md) describes what the current build does.
+
+## Write a new ADR
+
+1. Take the next free number and name the file `ADR-<number>-<short-slug>.md`.
+2. Start it with the same `kxm.doc.v1` front matter as the existing records, with `type: "adr"` and `authority: "decision"`.
+3. Include these sections: Status, Context, Decision drivers, Considered options, Decision, and Consequences, and end with Related.
+4. Record rejected options with the reason they were rejected, so the next reader does not reopen them without new information.
+5. When a decision replaces an earlier one, set `supersedes` and `superseded_by` in both records instead of editing the old decision.
+6. Add a row to the index above.
+
+## Related
+
+- [Architecture](../concepts/architecture.md)
+- [Trust model](../concepts/trust-model.md)
+- [Data and storage](../concepts/data-and-storage.md)
+- [Contracts](../contracts/README.md)