@kontextmind/kxm 0.7.95 → 0.7.97

package/docs/start/quickstart-pi.md

@@ -0,0 +1,213 @@
+# Quick start: Pi
+
+This tutorial connects two Pi agents through a KXM [hub](../glossary.md#hub) and has one ask the other for a review. It takes about ten minutes once Node.js, Git and Pi are installed. At the end, a planner and a reviewer exchange a durable request, and you can add Claude Code to the same project.
+
+## Before you begin
+
+- Node.js 22.19 or newer on the 22.x line, or Node.js 24 or newer, and Git.
+- Pi, signed in to a model provider. Install it with `npm install --global @earendil-works/pi-coding-agent`; the [Pi documentation](https://pi.dev/docs/latest) covers sign-in.
+- A Git repository for the project, and three terminals.
+
+Every agent in one project uses the same hub URL, project key and project token, and each needs a unique name. The hub's admin token stays with you, the operator; no agent gets it.
+
+## 1. Install
+
+Install the `kxm` CLI with npm, and the KXM package into Pi:
+
+```bash
+npm install --global --omit=peer @kontextmind/kxm
+pi install git:github.com/kontextmind/kxm@main
+kxm --version
+```
+
+`kxm --version` prints the installed version. The Pi package adds the KXM extension and skills to Pi but does not put `kxm` on your `PATH`; only the npm install does. [Install KXM](install.md) covers other options.
+
+## 2. Initialize the project
+
+In the first terminal, before you start Pi or a hub in this repository:
+
+```bash
+cd <your-repo>
+kxm init --name "<display-name>"
+printf '%s\n' '.kxm/state/' '.kxm/logs/' '.kxm/backups/' >> .gitignore
+git add .gitignore .kxm
+git commit -m "Add KXM project configuration"
+```
+
+`kxm init` prints `initialized KXM project at <repo-root>`. It writes the project's agents, gates and a default workflow under `.kxm/`, and no ignore rules, so the second command adds them.
+
+> [!NOTE]
+> In an interactive terminal, `kxm init` offers to install shell completion and to add workflow-guide agents for the harnesses you have signed in to. Both are safe to decline. Set `KXM_SKIP_COMPLETION_PROMPT=1` and `KXM_SKIP_GUIDE_SETUP_PROMPT=1` to skip them.
+
+## 3. Start the hub
+
+In the second terminal, from the repository root, create a token for the project `demo` and start the hub. The commands keep any projects the hub already saved:
+
+```bash
+# The user state root is KXM_STATE_HOME when set; the default below is for macOS.
+# On Linux, use "${XDG_STATE_HOME:-$HOME/.local/state}/kxm/hub-env.json" instead.
+HUB_ENV="${KXM_STATE_HOME:-$HOME/Library/Application Support/KXM}/hub-env.json"
+export KXM_NEW_PROJECT_TOKEN="$(openssl rand -hex 32)"
+export KXM_PROJECT_TOKENS="$(node -e '
+const fs = require("node:fs");
+const [file, project] = process.argv.slice(1);
+const saved = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")).projectTokens ?? {} : {};
+saved[project] = process.env.KXM_NEW_PROJECT_TOKEN;
+process.stdout.write(JSON.stringify(saved));
+' "$HUB_ENV" demo)"
+kxm hub start
+```
+
+<details><summary>PowerShell</summary>
+
+```powershell
+$bytes = New-Object byte[] 32
+[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
+$env:KXM_NEW_PROJECT_TOKEN = ($bytes | ForEach-Object { $_.ToString('x2') }) -join ''
+$stateRoot = if ($env:KXM_STATE_HOME) { $env:KXM_STATE_HOME } else { Join-Path $env:LOCALAPPDATA 'KXM' }
+$hubEnv = Join-Path $stateRoot 'hub-env.json'
+$env:KXM_PROJECT_TOKENS = node -e "const fs=require('node:fs');const [f,p]=process.argv.slice(1);const s=fs.existsSync(f)?JSON.parse(fs.readFileSync(f,'utf8')).projectTokens??{}:{};s[p]=process.env.KXM_NEW_PROJECT_TOKEN;process.stdout.write(JSON.stringify(s))" $hubEnv 'demo'
+kxm hub start
+```
+
+</details>
+
+Expected output:
+
+```text
+kxm hub: using newly generated KXM_AUTH_TOKEN from <state-root>/hub-env.json
+kxm hub listening at http://127.0.0.1:7331; storage=<repo-root>/.kxm/state/kxm.db; auth=token
+```
+
+Keep this terminal open. The hub generates its admin token on the first start and saves it, with the project tokens, in `hub-env.json`. `KXM_PROJECT_TOKENS` replaces the saved project map rather than adding to it, which is why the command starts from the saved map.
+
+> [!TIP]
+> The Pi extension can start a hub for you: with the default `hub.autoStart: background`, it reuses a healthy bound hub or starts a detached one. This tutorial starts the hub by hand so that you create the project token yourself.
+
+## 4. Bind this machine to the hub
+
+In the first terminal:
+
+```bash
+kxm hub bind http://127.0.0.1:7331
+```
+
+Expected output:
+
+```text
+bound hub http://127.0.0.1:7331 · loopback · health=on
+```
+
+## 5. Confirm the session
+
+```bash
+kxm hub view
+kxm session status
+```
+
+Expected output:
+
+```text
+hub health=true ready=true · loopback hub
+1 session claim(s), 0 recovery envelope(s)
+```
+
+The hub is healthy and ready, and its process is the one session claim.
+
+## 6. Start the planner
+
+Still in the first terminal, give the agent the project token, which the command reads from `hub-env.json` without printing it, and an identity:
+
+```bash
+HUB_ENV="${KXM_STATE_HOME:-$HOME/Library/Application Support/KXM}/hub-env.json"
+export KXM_AUTH_TOKEN="$(node -e 'process.stdout.write(JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).projectTokens[process.argv[2]] ?? "")' "$HUB_ENV" demo)"
+export KXM_SERVER_URL=http://127.0.0.1:7331
+export KXM_PROJECT=demo
+export KXM_AGENT_NAME=planner
+export KXM_AGENT_PURPOSE="Plans work and coordinates handoffs"
+pi
+```
+
+<details><summary>PowerShell</summary>
+
+```powershell
+$stateRoot = if ($env:KXM_STATE_HOME) { $env:KXM_STATE_HOME } else { Join-Path $env:LOCALAPPDATA 'KXM' }
+$env:KXM_AUTH_TOKEN = (Get-Content -Raw (Join-Path $stateRoot 'hub-env.json') | ConvertFrom-Json).projectTokens.'demo'
+$env:KXM_SERVER_URL = "http://127.0.0.1:7331"
+$env:KXM_PROJECT = "demo"
+$env:KXM_AGENT_NAME = "planner"
+$env:KXM_AGENT_PURPOSE = "Plans work and coordinates handoffs"
+pi
+```
+
+</details>
+
+Pi reports `Connected to the KXM hub as planner`. In Pi, run:
+
+```text
+/kxm hub
+```
+
+Expected output:
+
+```text
+kxm hub view: health=ok; planner; 1 online agent(s)
+```
+
+> [!NOTE]
+> Without `KXM_AUTH_TOKEN`, the extension signs in with the project token saved for this project on this machine, and never with the saved admin token. With neither, it reports the fix and stays offline. Set the project token so that each agent holds only its own project's credential.
+
+## 7. Start the reviewer and send a request
+
+In the third terminal, run the `HUB_ENV`, `KXM_AUTH_TOKEN`, `KXM_SERVER_URL` and `KXM_PROJECT` lines from step 6, then set a different identity and start Pi:
+
+```bash
+export KXM_AGENT_NAME=reviewer
+export KXM_AGENT_PURPOSE="Reviews plans and code for correctness risks"
+pi
+```
+
+In the planner's Pi session, ask:
+
+```text
+Use the kxm skill. List peers, ask reviewer to examine the current plan for
+its three highest correctness risks, and wait for the response.
+```
+
+The planner calls `kxm_list`, `kxm_send` and `kxm_await`. The reviewer's Pi receives the request as a new turn, and the extension returns that turn's final response as the reply. The planner then shows the reviewer's answer.
+
+The hub stores the request as a durable record that moves from `queued` to `delivered` to `replied`, so it survives a hub restart. `kxm_await` waits at most 60 seconds; a slower reply stays pending, and the planner can check it later with `kxm_get`. [Message peer agents](../guides/peer-messaging.md) covers fanout, cancellation and delivery modes.
+
+## 8. Add Claude Code (optional)
+
+Claude Code can join the same project. Install the plugin as in [Quick start: Claude Code](quickstart-claude-code.md#5-install-the-plugin), with `project` set to `demo`, a unique `agent_name` such as `claude-reviewer`, and `auth_token` left blank on this machine. Then ask Claude to call `kxm_list`: the planner and the reviewer appear.
+
+## Your first useful topology
+
+Start with two or three agents that have clear, separate jobs:
+
+| Role | Good responsibilities |
+|---|---|
+| Planner | Break down work, define ownership, collect results |
+| Builder | Implement one bounded change |
+| Reviewer | Check correctness, tests, security or documentation |
+
+KXM does not coordinate file ownership. Do not let two agents edit the same files in one checkout: use separate Git worktrees, or give one agent write ownership.
+
+## Troubleshooting
+
+| Message or symptom | Cause | Fix |
+|---|---|---|
+| `agent name already active in project: <name>` | Another live Pi agent in the project uses the name | Set a different `KXM_AGENT_NAME` and restart Pi |
+| `/kxm hub` prints `no agent connected` | The extension could not register | Check `KXM_SERVER_URL`, `KXM_PROJECT` and `KXM_AUTH_TOKEN`, then restart Pi |
+| `invalid project authentication token` | `KXM_AUTH_TOKEN` is not the hub's token for `KXM_PROJECT` | Read the token again as in step 6 |
+| `kxm init` prints `legacy state is not migrated by this build` | Pi or a hub ran here before `kxm init` | See [Check the project](quickstart-claude-code.md#check-the-project) |
+
+[Troubleshooting](../operations/troubleshooting.md) covers workers, sessions and the hub.
+
+## Next steps
+
+- Keep Pi agents running unattended: [Run supervised Pi workers](../guides/pi-workers.md)
+- Run a workflow end to end: [Run your first workflow](first-workflow.md)
+- Send, fan out and cancel requests: [Message peer agents](../guides/peer-messaging.md)
+- Hub and agent settings: [Environment variables and limits](../reference/configuration.md)

package/docs/templates/README.md

@@ -1,95 +1,100 @@
-# KXM Documentation Templates & Workflow Integration Guide
-
-This directory contains standardized Markdown documentation templates adapted for KXM multi-agent orchestration, the 5-layer memory architecture, and the workflow taxonomy defined in [`docs/workflow-guide.md`](../workflow-guide.md).
-
-## Core Principles
-
-1. **Markdown + YAML Frontmatter + Mermaid:** Standardized metadata for automated indexing by the Context Arbiter, paired with human-readable text and conservative Mermaid diagrams.
-
-2. **Separation of Concerns:** Keep **what should happen** (Feature / Architecture / Test Plan), **what was decided** (ADR), and **what actually happened** (Test Report / Witness Receipt / Postmortem) distinct.
-
-3. **Immutable Evidence Chains:** Every test or review report must reference an exact commit pin (`git rev-parse HEAD`), deterministic branch (`kxm/run-<id>-<description>`), and content-addressed artifact reference (`artifact:<path>@sha256:<digest>`).
-
-4. **Context Arbiter Integration:** Frontmatter fields (`authority`, `confidence`, `summary`, `tags`) inform token budgeting in `kxm.context-packet.v2`: layer pruning plus lexical task-relevance ordering in the arbiter.
-
----
-
-## Template Directory
-
-| Template | File | Primary Workflow Stage | Key Outputs |
-
+# Artifact templates
+
+These templates give the artifacts a KXM workflow produces a common shape:
+feature specifications, research briefs, bug reports, architecture designs,
+decision records, test plans and reports, reviews, handoffs, runbooks and
+postmortems. Agents and people fill them in during a run. For a human-facing
+docs page, use the page template in
+[Write KXM documentation](../contributing/writing-docs.md) instead.
+
+## Principles
+
+1. **Markdown, YAML frontmatter and Mermaid.** The frontmatter carries metadata
+   for indexing, the body stays readable, and diagrams are plain Mermaid.
+2. **Keep plans, decisions and outcomes apart.** What should happen (feature,
+   architecture, test plan), what was decided (ADR), and what actually happened
+   (test report, witness receipt, postmortem) are separate artifacts.
+3. **Pin every piece of evidence.** A test or review report cites an exact
+   commit (`git rev-parse HEAD`), a branch such as
+   `kxm/run-<run-id>-<description>`, and content-addressed artifacts written as
+   `artifact:<path>@sha256:<digest>`.
+4. **Use the context vocabulary.** The `authority`, `confidence`, `summary` and
+   `tags` fields use the same values as KXM context items, so an indexer can
+   weigh an artifact. No KXM code reads this frontmatter today, and no JSON
+   Schema validates `kxm.doc.v1` yet.
+
+## Templates
+
+| Template | Use it for | Stage | Key outputs |
 |---|---|---|---|
-| **Feature Specification** | [`feature.md`](feature.md) | Stage 1: Requirements & Scope | Observable behavior, acceptance criteria table, user flow diagram. |
-
-| **Research Brief** | [`research.md`](research.md) | Stage 1: Discovery & Spike | Falsifiable hypotheses, evidence register, option comparison matrix. |
-| **Bug Investigation & Fix** | [`bug-fix.md`](bug-fix.md) | Stages 1–3: Repro, Fix, Verify | Repro before oracle, sequenceDiagram, exact test command, before/after evidence. |
-
-| **Architecture Design** | [`architecture.md`](architecture.md) | Stage 1: Architecture & System Design | Trust boundaries, component ownership, runtime scenarios, failure modes. |
-| **Architecture Decision Record (ADR)** | [`adr.md`](adr.md) | Ongoing: Technical Decisions | Decision drivers, considered options with pros/cons, consequences, revisit triggers. |
-
-| **Test Plan** | [`test-plan.md`](test-plan.md) | Stage 2: Verification Design | Risk-to-coverage matrix, test cases, environment prerequisites, entry/exit criteria. |
-| **Test Execution Report** | [`test-report.md`](test-report.md) | Stage 3: Witness Verification | Exact build/commit, execution timestamps, case outcomes, coverage diff. |
-
-| **Dual-Critic Review Report** | [`review.md`](review.md) | Stage 4: Critic Quorum | Independent Fable (arch) and Astra/Sol (CLI) findings, severity, quorum verdict. |
-| **Structured Handoff Manifest** | [`handoff.md`](handoff.md) | Inter-stage transitions | `kxm.handoff-manifest.v1` mapping, baseCommit, candidateTreeHash, deliverables. |
-
-| **Operational Runbook** | [`runbook.md`](runbook.md) | Reliability & Ops | Diagnosis steps, safe mitigation commands, rollback triggers, escalation paths. |
-| **Incident Postmortem** | [`postmortem.md`](postmortem.md) | Post-incident Retrospective | Timeline of events, root cause analysis, preventive action items. |
-
----
-
-## Workflow Guide Integration Matrix
-
-The 11 templates map directly across the 7 Areas and 22 Workflows in [`docs/workflow-guide.md`](../workflow-guide.md):
+| [Feature specification](feature.md) | A new capability | Requirements and scope | Observable behavior, acceptance criteria, user flow |
+| [Research brief](research.md) | A spike or evaluation | Discovery | Falsifiable hypotheses, evidence register, option comparison |
+| [Bug investigation and fix](bug-fix.md) | A defect | Reproduce, fix, verify | Failing reproduction first, exact test command, before and after evidence |
+| [Architecture design](architecture.md) | A system or subsystem | Design | Trust boundaries, component ownership, failure modes |
+| [Architecture decision record](adr.md) | A technical decision | Any | Drivers, options with trade-offs, consequences, revisit triggers |
+| [Test plan](test-plan.md) | Verification design | Before implementation | Risk-to-coverage matrix, test cases, entry and exit criteria |
+| [Test execution report](test-report.md) | A witness run | Verification | Exact commit, case outcomes, coverage |
+| [Dual-critic review](review.md) | Independent review | Review | Findings by severity, `PASS` or `BLOCK` per critic |
+| [Handoff manifest](handoff.md) | A stage transition | Between stages | `kxm.handoff-manifest.v1` fields, base commit, deliverables |
+| [Operational runbook](runbook.md) | Diagnosis and mitigation | Operations | Triage steps, safe commands, rollback, escalation |
+| [Incident postmortem](postmortem.md) | A blameless retrospective | After an incident | Timeline, root cause, corrective actions |
+
+## How the templates fit a workflow
+
+Planning artifacts feed implementation and testing, which feed verification and
+review; runbooks and postmortems cover operations.
 
 ```mermaid
 flowchart TD
-    subgraph PlanStage ["1. Planning & Design"]
+    subgraph Plan ["1. Plan and design"]
         F["feature.md"]
         R["research.md"]
         A["architecture.md"]
         ADR["adr.md"]
     end
 
-    subgraph ExecStage ["2. Implementation & Testing"]
+    subgraph Build ["2. Implement and test"]
         B["bug-fix.md"]
         TP["test-plan.md"]
-        H1["handoff.md (Plan -> Write)"]
+        H1["handoff.md (plan to write)"]
     end
 
-    subgraph VerifyStage ["3. Verification & Review"]
-        TR["test-report.md (Witness)"]
-        REV["review.md (Dual Critics)"]
-        H2["handoff.md (Write -> Critic)"]
+    subgraph Verify ["3. Verify and review"]
+        TR["test-report.md (witness)"]
+        REV["review.md (two critics)"]
+        H2["handoff.md (write to review)"]
     end
 
-    subgraph OpsStage ["4. Operations & Maintenance"]
+    subgraph Operate ["4. Operate"]
         RB["runbook.md"]
         PM["postmortem.md"]
     end
 
-    PlanStage --> ExecStage
-    ExecStage --> VerifyStage
-    VerifyStage --> OpsStage
-
+    Plan -->|approved plan| Build
+    Build -->|candidate| Verify
+    Verify -->|accepted change| Operate
 ```
 
-### Mapping by Area
-
-1. **Software Engineering (`software-engineering`)**
-   - `feature-delivery`: [`feature.md`](feature.md) $\rightarrow$ [`architecture.md`](architecture.md) $\rightarrow$ [`test-plan.md`](test-plan.md) $\rightarrow$ [`review.md`](review.md).
-   - `bug-investigation`: [`bug-fix.md`](bug-fix.md) with mandatory reproduction test before oracle.
-   - `refactoring-migration`: [`architecture.md`](architecture.md) + [`adr.md`](adr.md) + [`test-report.md`](test-report.md).
-
-2. **Design & Experience (`design-experience`)**
-   - `ui-ux-design-system`: [`feature.md`](feature.md) (user flows) + [`review.md`](review.md) (a11y audits).
-
-3. **Data & Analytics (`data-analytics`)**
-   - `data-pipeline-etl`: [`architecture.md`](architecture.md) (data flows, contracts) + [`runbook.md`](runbook.md).
-
-4. **Research & Strategy (`research-strategy`)**
-   - `technology-evaluation` / `market-research`: [`research.md`](research.md) with evidence registers and confidence bounds.
-
-5. **Security & Reliability (`security-reliability`)**
-   - `vulnerability-audit`: [`review.md`](review.md) (threat model) + [`bug-fix.md`](bug-fix.md).
-   - `incident-response`: [`runbook.md`](runbook.md) (triage/mitigation) $\rightarrow$ [`postmortem.md`](postmortem.md) (blameless retrospective).
+## Templates by workflow
+
+The slugs below come from the [workflow catalog](../reference/workflow-catalog.md).
+They are documentation identifiers only; they imply no runtime configuration.
+
+| Area | Workflow | Templates |
+|---|---|---|
+| Software engineering | `build-feature` | `feature.md`, then `architecture.md`, `test-plan.md`, `review.md` |
+| Software engineering | `refactor-repair-regressions` | `architecture.md`, `adr.md`, `test-report.md` |
+| Software engineering | `stabilize-flaky-tests` | `bug-fix.md` with a failing reproduction first, then `test-report.md` |
+| Software engineering | `design-software-system` | `architecture.md`, `adr.md` |
+| Software engineering | `maintain-documentation` | `review.md` for the accuracy audit |
+| Design and experience | `build-design-system`, `audit-visual-accessibility` | `feature.md` for user flows, `review.md` for accessibility findings |
+| Data and analytics | `analyze-dataset`, `query-business-intelligence` | `research.md` for the evidence register, `architecture.md` for data flows |
+| Research and strategy | `prepare-decision-brief` | `research.md`, then `adr.md` for the decision |
+| Security and reliability | `patch-vulnerability` | `review.md` for the threat model, `bug-fix.md` for the fix |
+| Security and reliability | `investigate-incident` | `runbook.md` for triage, then `postmortem.md` |
+
+## Related
+
+- [Write KXM documentation](../contributing/writing-docs.md): the docs page template and style rules
+- [Workflow catalog](../reference/workflow-catalog.md): workflow and role slugs
+- [Assignment runner](../contributing/assignment-runner.md): witness, critics and acceptance in the KXM repository

package/docs/templates/adr.md

@@ -2,7 +2,7 @@
 schema: "kxm.doc.v1"
 id: "ADR-0001"
 type: "adr"
-title: "Title of Architecture Decision"
+title: "ADR-<nnnn>: <decision title>"
 project: "kxm"
 status: "proposed" # proposed | accepted | superseded | deprecated | rejected
 owner: "@owner"
@@ -19,13 +19,13 @@ details:
   superseded_by: null
 ---
 
-# ADR-0001: <Title of Architecture Decision>
+# ADR-0001: <Title of architecture decision>
 
-## Context & Problem Statement
+## Context and problem statement
 
 <Describe the technical context, operational dilemma, or architectural friction. What forces are compelling this decision?>
 
-## Decision Drivers
+## Decision drivers
 
 1. **Driver 1:** <e.g., Eliminate native compilation failures across Node versions>
 
@@ -33,7 +33,7 @@ details:
 
 3. **Driver 3:** <e.g., Maintain fail-closed security invariants without loopback bypasses>
 
-## Considered Options
+## Considered options
 
 - **Option A:** <Name of Option A>
 
@@ -41,9 +41,9 @@ details:
 
 - **Option C:** <Name of Option C>
 
-## Evaluation & Tradeoff Matrix
+## Evaluation and tradeoff matrix
 
-### Option A: <Name of Option A>
+### Option A: <name of option A>
 
 - **Good, because:** <Advantage 1>
 
@@ -53,33 +53,33 @@ details:
 
 - **Bad, because:** <Drawback 2>
 
-### Option B: <Name of Option B>
+### Option B: <name of option B>
 
 - **Good, because:** <Advantage 1>
 
 - **Bad, because:** <Drawback 1>
 
-## Decision Outcome
+## Decision outcome
 
 **Chosen Option:** **Option A**, because <comprehensive justification referencing drivers>.
 
-### Positive Consequences
+### Positive consequences
 
 - <Favorable outcome 1>
 
 - <Favorable outcome 2>
 
-### Negative Consequences & Accepted Tradeoffs
+### Negative consequences and accepted tradeoffs
 
 - <Technical debt, limitation, or operational overhead incurred>
 
-## Confirmation & Verification Strategy
+## Confirmation and verification strategy
 
 - **Verification Gate:** <Exact test suite or contract check enforcing this decision>
 
 - **Enforcement Mechanism:** <Linter, type-check, or CI rule that prevents regressions>
 
-## Revisit Conditions
+## Revisit conditions
 
 This decision should be formally re-evaluated if:
 

package/docs/templates/architecture.md

@@ -2,7 +2,7 @@
 schema: "kxm.doc.v1"
 id: "ARCH-0001"
 type: "architecture"
-title: "System / Subsystem Architecture Design"
+title: "Architecture: <system or subsystem>"
 project: "kxm"
 status: "draft" # draft | in_review | approved | superseded | archived
 owner: "@owner"
@@ -18,103 +18,87 @@ details:
   baseline_commit: "<git-sha>"
 ---
 
-# Architecture: <System / Subsystem Name>
+# Architecture: <system or subsystem name>
 
-## Purpose & Scope
+## Purpose and scope
 
-- **Core Mission:** <What capability does this subsystem deliver?>
+- **Mission:** <What capability does this subsystem deliver?>
+- **Callers:** <Who interacts with it: operators, agents, workers, external webhooks?>
+- **State of this document:** <Current, proposed, or target architecture. Say which.>
 
-- **Audience & Callers:** <Who interacts with this system (interactive operators, workers, external webhooks)?>
-
-- **Architecture State:** <Explicitly state whether this document reflects current, proposed, or target architecture>
-
-## Goals, Quality Attributes & Constraints
-
-| Goal / Constraint | Business or Technical Driver | Measurement Metric / Hard Boundary |
+## Goals, quality attributes and constraints
 
+| Goal or constraint | Driver | Measure or hard boundary |
 |---|---|---|
-| Fail-Closed Security | Prevent privilege escalation | Reject missing tokens; zero loopback bypasses |
+| Fail-closed security | Prevent privilege escalation | Missing or wrong credentials are refused; no loopback bypass |
+| Deterministic replay | Forensic debugging and audit | Folding the event log reproduces the same state |
+| <Latency or throughput goal> | <Operator responsiveness> | <For example, p50 dispatch under 200 ms> |
 
-| Deterministic Replay | Forensic debugging & auditability | Folded event stream produces identical state |
-| Low Latency Dispatch | Operator responsiveness | Sub-200ms dispatch P50 |
+## Context and trust boundaries
 
-## Context & Trust Boundaries
+External requests pass a credential check before they reach the subsystem, which
+owns its durable state.
 
 ```mermaid
 flowchart TB
-    subgraph External ["Untrusted External Perimeter"]
-        Caller["Operator / External Webhook / CI"]
+    subgraph External ["Untrusted perimeter"]
+        Caller["Operator, webhook sender or CI"]
     end
 
-    subgraph AuthPlane ["Access Control Plane (Trust Boundary)"]
-        TokenVal["Token Validator (Admin / Session / Attempt)"]
+    subgraph Auth ["Trust boundary"]
+        Check["Credential check (admin, project or session)"]
     end
 
-    subgraph Internal ["KXM Core Domain"]
-        Engine["Temporal Workflow Engine"]
-        Memory["5-Layer Memory & Context Arbiter"]
-        Store[("SQLite Store: .kxm/state/kxm.db")]
+    %% Replace these labels with your own components and store.
+    subgraph Internal ["Subsystem"]
+        Engine["Core component"]
+        Context["Supporting component"]
+        Store[("Durable store, for example .kxm/state/kxm.db")]
     end
 
-    Caller -->|Request + Token| TokenVal
-    TokenVal -->|Authorized Call| Engine
-    Engine --> Memory
-    Engine --> Store
-
+    Caller -->|request and credential| Check
+    Check -->|authorized call| Engine
+    Engine -->|reads| Context
+    Engine -->|writes| Store
 ```
 
-*Context flow: External requests enter through the Access Control Plane. Authorized calls interact with the Temporal Engine and Context Arbiter, backed by durable SQLite storage.*
-
-## Component Responsibilities & Ownership
-
-| Component | Responsibility | Public Interface / Contract | Owned State / Tables | Team / Role Owner |
-
-|---|---|---|---|---|
-| Workflow Engine | DAG scheduling & loop transitions | `KxmEngine.drive()` | `run_events`, `workflow_runs` | Engine Lead |
-
-| Context Arbiter | Token budgeting & context compilation | `arbitrate()` | In-memory pool + Git memory | Memory Lead |
-| External Effects Ledger | CAS leasing & idempotency | `ExternalEffectsLedger` | `external_effects` | Platform Lead |
-
-## Runtime Execution Scenarios
-
-### 1. Happy Path Dispatch & Settlement
-
-1. Step dispatch compiles `FormalContextPacket` (`kxm.context-packet.v2`).
-
-2. Worker executes in isolated branch `kxm/run-<id>-<description>`.
-
-3. Worker submits `kxm.handoff-manifest.v1` with witness receipt.
-
-4. Engine commits transition and notifies critics.
-
-### 2. Failure & Rework Path
-
-1. Critic issues structured rejection findings with blocker severity.
-
-2. Engine transitions step to `rejected_rework_required`.
-
-3. Attempts counter increments; router dispatches to next eligible writer.
+## Component responsibilities
 
-## Data Contracts, Storage & Invariants
+| Component | Responsibility | Public interface | Owned state |
+|---|---|---|---|
+| <Runtime engine> | <Schedules steps, attempts and transitions> | <`KxmRunScheduler`> | <`events`, `runs`, `run_state` in the Runtime event store> |
+| <Context arbiter> | <Assembles role-aware packets within a budget> | <`arbitrate()`> | <None; reads context items and Git memory> |
+| <Hub store> | <Messages, workflow runs and leases> | <HTTP API> | <`messages`, `workflow_runs`, `leases` in `kxm.db`> |
 
-- **Source of Truth:** Local-first SQLite (`.kxm/state/kxm.db`) using native `DatabaseSync` (`node:sqlite`).
+## Runtime scenarios
 
-- **Journal Mode:** WAL mode with `busy_timeout = 5000ms` and `synchronous = NORMAL`.
+### Happy path
 
-- **Branch Naming Invariant:** `kxm/run-<cleanId>-<slug>` generated deterministically.
+1. <Step dispatch builds a context packet for the target role.>
+2. <The worker runs on its own branch, for example `kxm/run-<run-id>-<description>`.>
+3. <The worker returns a structured result with its witness evidence.>
+4. <The engine records the transition and hands off to the critics.>
 
-- **Commit Pinning:** Never fall back to mutable `HEAD`; strictly pin `reviewedCommit`.
+### Failure and rework
 
-## Security & Isolation
+1. <How a failed attempt or a critic block is recorded.>
+2. <Which transition, retry budget, or human action decides what runs next.>
+3. <What stops the loop: a budget, a terminal status, or an operator.>
 
-- **Token Model:** 3-tier model (AdminToken, SessionToken, AttemptToken).
+## Data contracts, storage and invariants
 
-- **Process Isolation:** Worker processes run as detached children with bounded stdio frames.
+- **Source of truth:** <store and schema, for example SQLite through `node:sqlite`>
+- **Durability settings:** <for example WAL, a 5-second busy timeout, `synchronous = NORMAL`>
+- **Naming invariants:** <branch, ID, or path conventions the subsystem relies on>
+- **Pinning:** <which revisions are pinned per run, and what is never read from a mutable `HEAD`>
 
-- **Git Worktree Lock:** Concurrent worktree mutations acquire `.git/kxm-worktree.lock`.
+## Security and isolation
 
-## Architectural Decisions (ADR Index)
+- **Credentials:** <which credentials the subsystem accepts and what each may do>
+- **Process isolation:** <how child processes are bounded: stdio frames, output caps, process groups>
+- **Concurrency control:** <locks or leases that serialize shared mutations>
+- **Not guaranteed:** <for example exactly-once external effects, or sandboxing>
 
-- [`ADR-0001: SQLite Native node:sqlite Engine`](../decisions/ADR-0001.md)
+## Architectural decisions
 
-- [`ADR-0002: Deterministic Run Branching`](../decisions/ADR-0002.md)
+- `ADR-<nnnn>: <title>`: link each record in [`docs/adr/`](../adr/README.md).