@kontextmind/kxm 0.7.94 → 0.7.96

package/docs/guides/browser-automation.md

@@ -0,0 +1,160 @@
+# 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.
+
+## 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.
+- 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).
+
+## Components
+
+| Component | Role |
+|---|---|
+| Steel | Runs isolated Chromium sessions and exposes a REST API, a CDP WebSocket and a session viewer |
+| `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 |
+
+## Configure the Steel endpoint
+
+The KXM browser library reads these variables, and the shell procedure below uses the same names so both agree.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `STEEL_API_URL` | A KontextMind-operated deployment | Base URL of your Steel API. Always set it |
+| `STEEL_UI_URL` | `$STEEL_API_URL/ui` | Base URL of the session viewer |
+| `STEEL_API_KEY` | A `pass-cli` lookup | The 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 |
+
+> [!WARNING]
+> Set `STEEL_API_URL` and `STEEL_API_KEY` explicitly. Without them the library falls back to KontextMind's own deployment and vault item, which are not yours to use.
+
+```bash
+export STEEL_API_URL="https://steel.example.com"
+# Read the key from your secret manager; <vault> and <item> are yours.
+export STEEL_API_KEY="$(pass-cli item view --vault-name '<vault>' --item-title '<item>' --field STEEL_API_KEY)"
+export USE_PASS_CLI=false
+```
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /v1/sessions` | Create a session; body `{"timeout": <ms>}` |
+| `GET /v1/sessions/<id>` | Inspect one session; `GET /v1/sessions` lists them all |
+| `POST /v1/sessions/<id>/release` | Release a session |
+| `POST /v1/scrape`, `POST /v1/screenshot` | One-shot page fetch or screenshot without a session |
+| `wss://<steel-host>/v1/devtools?sessionId=<id>&apiKey=<key>` | CDP endpoint for `agent-browser` and Playwright |
+| `$STEEL_UI_URL?sessionId=<id>` | Session viewer for human takeover |
+
+The CDP URL carries the API key in its query string. Treat it as a secret: never paste it into chat, a prompt, an issue or a log.
+
+## Run a browser task
+
+1. Define a helper that sends the key as a header read from standard input, so it never appears in a process list:
+
+   ```bash
+   steel() {  # usage: steel METHOD PATH [JSON-BODY]
+     local args=(-sS -X "$1" "$STEEL_API_URL$2" -H @- -H 'Content-Type: application/json')
+     if [ -n "${3:-}" ]; then args+=(-d "$3"); fi
+     printf 'x-steel-api-key: %s\n' "$STEEL_API_KEY" | curl "${args[@]}"
+   }
+   ```
+
+2. Create a session. Use one session per task; 300,000 ms (5 minutes) is the default. Your Steel deployment sets the maximum; the skills assume 30 minutes.
+
+   ```bash
+   SESSION_ID=$(steel POST /v1/sessions '{"timeout": 300000}' | jq -r .id)
+   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"`.
+4. For a quick fetch that needs no session, scrape instead:
+
+   ```bash
+   steel POST /v1/scrape '{"url": "https://example.com"}'
+   ```
+
+5. Release the session when the task ends, even when it failed. Disconnecting a client does not release the session; it stays open for a human until it is released or times out.
+
+   ```bash
+   steel POST "/v1/sessions/$SESSION_ID/release"
+   ```
+
+<details><summary>PowerShell</summary>
+
+```powershell
+$headers = @{ "x-steel-api-key" = $env:STEEL_API_KEY }
+$session = Invoke-RestMethod -Method Post -Uri "$env:STEEL_API_URL/v1/sessions" -Headers $headers -ContentType "application/json" -Body '{"timeout": 300000}'
+Invoke-RestMethod -Method Post -Uri "$env:STEEL_API_URL/v1/sessions/$($session.id)/release" -Headers $headers
+```
+
+</details>
+
+## Hand control to a human
+
+When a site asks for MFA, a CAPTCHA, SSO or sensitive consent, the agent stops and a person takes over. The diagram shows who controls the session in each state.
+
+```mermaid
+stateDiagram-v2
+  [*] --> AGENT_CONTROL: session created
+  AGENT_CONTROL --> HUMAN_CONTROL: login, MFA, CAPTCHA or consent needed
+  HUMAN_CONTROL --> VERIFY_AUTHENTICATION: operator confirms completion
+  VERIFY_AUTHENTICATION --> AGENT_CONTROL: agent confirms signed-in state
+  AGENT_CONTROL --> RELEASED: task done
+  HUMAN_CONTROL --> RELEASED: operator abandons
+  RELEASED --> [*]
+```
+
+1. **Pause.** The agent stops all automated input and says why it needs a person.
+2. **Share the viewer link.** It gives the operator `$STEEL_UI_URL?sessionId=<id>`, never the CDP URL.
+3. **Operator acts.** The operator opens the viewer, completes the step, and confirms in the terminal, for example `auth complete`.
+4. **Verify, then resume.** The agent inspects the page, confirms the signed-in state, refreshes its DOM snapshot, and only then continues.
+
+The KXM browser library tracks these states in the process that owns the session. Steel itself does not know them; in a shell-driven task they are a protocol the agent announces. Only one controller, agent or human, acts at a time.
+
+## Control cost and resources
+
+- **Timeouts.** Sessions end on their own when the timeout expires. Set a longer timeout at creation when a person will need time for a login step.
+- **Orphan sweeps.** List sessions with `steel GET /v1/sessions` and release any you do not track. The library flags untracked sessions older than 10 minutes, and tracked ones idle that long unless a human holds them.
+- **Shared memory.** Give Chromium a large `/dev/shm`, or tabs crash. On Kubernetes, mount a memory-backed `emptyDir` there; the reference deployment uses 2 GiB.
+- **No shared profiles.** Concurrent sessions must not write to the same browser profile.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `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 |
+| 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 |
+
+## Knowledge base
+
+- [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 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)
+- [How do I take over a browser session to log in?](../kb/how-to-take-over-session.md)
+- [Why did authentication disappear?](../kb/why-authentication-disappeared.md)
+- [Why did automation open a different browser?](../kb/why-automation-opened-different-browser.md)
+- [Why can I view a session but not control it?](../kb/why-session-viewer-cannot-control.md)
+
+## Prompt templates
+
+- [Starting browser work](../prompts/browser-start.md)
+- [Exploring an application](../prompts/browser-explore.md)
+- [Requesting human takeover](../prompts/browser-takeover.md)
+- [Diagnosing and recovering a failed session](../prompts/browser-diagnose-recover.md)
+- [Reproducing a UI bug and writing a Playwright test](../prompts/browser-repro-fix.md)
+- [Capturing UI section annotations](../prompts/browser-annotate-feedback.md)
+
+## Next steps
+
+- The seven browser skills: [Agent skills](agent-skills.md#browser-automation-skills)
+- 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/guides/context-and-memory.md

@@ -0,0 +1,352 @@
+# Context and memory
+
+KXM gives every agent the same deterministic answer to "what does this project know?": a token-budgeted context packet assembled from durable records, temporal state that only changes through evidence-bound promotion, and memory authored in Git. This page is for operators and agent authors. After reading it you can assemble and inspect packets, promote state, write memory, and predict exactly what a Runtime agent receives.
+
+What sets this apart:
+
+- **Deterministic.** No model, clock or randomness takes part in selection, so the same records and request always give the same packet.
+- **Provenance-bound.** Every item records where it came from, and its origin caps its authority. Summarizing an item never raises that authority.
+- **Isolated.** A packet never mixes projects' stored records. A foreign item in the pool is refused, not filtered. One exception: a hub that serves several projects attaches its own checkout's authored memory and promoted skills to every project that asks; see [Limits and known issues](#limits-and-known-issues).
+- **Logged without leaking.** The hub log records ids, counts, scores and the size of the task, never task text or item bodies. The `audit` returned to the caller echoes the caller's own request, task included.
+- **Git is the authority for memory.** Agents propose memory and state; people promote them.
+
+## Before you begin
+
+- The `kxm` CLI. See [Install](../start/install.md).
+- A running [hub](../glossary.md#hub) for the `kxm context` commands. `kxm memory` and `kxm skills` need no hub.
+- The hub admin token in `KXM_AUTH_TOKEN`. `kxm context` authenticates as the control plane. Agents use their own project credentials through tools instead, never the admin token.
+
+```bash
+# Load the admin token from your secret manager; never commit it.
+export KXM_AUTH_TOKEN="replace-with-admin-token"
+```
+
+<details><summary>PowerShell</summary>
+
+```powershell
+$env:KXM_AUTH_TOKEN = "replace-with-admin-token"
+```
+
+</details>
+
+## Where context comes from
+
+| Source | Stored in | Written by | Becomes |
+|---|---|---|---|
+| Temporal state | Hub SQLite | Agents propose; operators promote | `state` items |
+| Workflow [journal](../glossary.md#journal) | Hub SQLite | Coordinators and the hub | `knowledge`, `evidence` or `skill` items |
+| Authored memory | `.kxm/memory/*.md` in Git | People, through a reviewed PR | `knowledge` items |
+| Promoted skills | `.kxm/skills/promoted/` in Git | `kxm skills promote`, then a PR | `skill` items |
+
+The journal only exists for hub workflow runs. Runs started with `kxm run` have no journal; see [Continuous improvement](continuous-improvement.md).
+
+## Context items
+
+A context item is one record in the pool. It has a `kind` (`evidence`, `state`, `episode`, `knowledge` or `skill`), a project, a summary of at most 4,000 characters with secrets redacted, immutable provenance, an authority, a confidence (`verified`, `probable` or `uncertain`) and optional lifecycle fields: `status`, `stateKey` and a validity window.
+
+Authority is ordered `policy` > `instruction` > `evidence` > `hypothesis`. The origin in `provenance.sourceType` sets the ceiling. An item that claims more authority than its origin allows is refused with `context_authority_violation`. An item that carries a control-plane field such as `permissions`, `tools`, `token` or `apiKey` is refused the same way: context informs agents, it never grants them anything.
+
+Journal entries enter the pool as items with evidence authority and `probable` confidence:
+
+| Journal category | Item kind |
+|---|---|
+| `plan`, `decision`, `lesson` | `knowledge` |
+| `skill-candidate` | `skill`, status `proposed`, never selected |
+| All other categories | `evidence` |
+
+Limits: 256 items per packet, a task of at most 2,000 characters, a budget of 512 to 200,000 tokens, and a derivation lineage of at most 64 ancestors.
+
+## Role policies
+
+The requesting role decides which kinds a packet prefers and its default budget.
+
+| Role | Kinds, in priority order | Journal categories read | Default budget |
+|---|---|---|---:|
+| `repro` | episode, knowledge, evidence | error, lesson, observation, contradiction | 8,000 |
+| `planner` | state, knowledge, evidence | plan, decision, contradiction, observation, hypothesis, experiment | 16,000 |
+| `critic` | knowledge, evidence, episode | contradiction, error, lesson, experiment | 12,000 |
+| `implementer` | knowledge, state, skill, episode, evidence | plan, decision, lesson, state-change | 16,000 |
+| `verifier` | evidence, knowledge, episode | plan, error, lesson, contradiction | 8,000 |
+| Any other name | knowledge, evidence | lesson, observation | 32,000 |
+
+Only `implementer` asks for the `skill` kind, so only that role receives promoted skills unless a request passes `--kinds` or `includeKinds`.
+
+## Assemble a context packet
+
+Operators use `kxm context get`. Agents call the `kxm_context` tool, which fills in their project from their credentials.
+
+```bash
+kxm context get demo --role planner --task "Which branch do we release from?" --json \
+  | jq -c '{state: [.packet.currentState[].summary], gaps: .packet.unresolvedGaps, relevance: .audit.relevance}'
+```
+
+Expected output:
+
+```text
+{"state":["Releases are cut from the main branch"],"gaps":[],"relevance":{"taskTokens":2,"matchedCandidates":1,"selected":[0.791]}}
+```
+
+The flowchart shows how the hub turns the pool into a packet.
+
+```mermaid
+flowchart TD
+  POOL[("Pool: state, journal items,<br/>authored memory, hash-verified skills")] --> ISO{"Every item in this<br/>project or _shared?"}
+  ISO -- no --> REFUSE["Refuse:<br/>context_isolation_violation"]
+  ISO -- yes --> LIVE["Drop superseded<br/>and rejected items"]
+  LIVE --> ELIG["Keep open contradictions and<br/>requested kinds; drop inert proposals"]
+  ELIG --> RANK[Rank by nine keys]
+  RANK --> FIT[Fill the budget first-fit]
+  FIT --> PACKET[Packet sections]
+  FIT --> GAPS[unresolvedGaps]
+  FIT --> AUDIT[audit and audit.relevance]
+```
+
+### How candidates are ranked
+
+An item is eligible when it is an open contradiction, or when it is a requested kind and not an inert proposal. Non-current state and proposed skills are inert, so proposals never consume budget. Eligible items are ordered by these keys, in order:
+
+1. Open contradictions first.
+2. The requested project before `_shared` defaults (operator-scope memory).
+3. Task-matched items (sharing at least one word with the task) before unmatched ones.
+4. The role's kind priority.
+5. BM25 relevance of the item's summary and state key to the task. Tokens are lowercased and Unicode-normalized, a fixed English stopword list is dropped, and plurals are folded.
+6. Confidence.
+7. Authority.
+8. Recency, newest first, from the item's own timestamps.
+9. Id, by code unit.
+
+### Budget and gaps
+
+The budget is filled first-fit: an item that does not fit is skipped, and smaller items keep filling the space. Tokens are estimated at four characters each over the summary, id, kind and source reference. That estimate enforces the budget; it is not billing. `unresolvedGaps` reports what was left out:
+
+| Gap | Meaning |
+|---|---|
+| `budget of <n> tokens reached; <m> candidates deferred` | Some eligible items did not fit |
+| `budget of <n> tokens cannot fit any selected context` | Nothing fit |
+| `context item limit reached; refine the task or kinds` | 256 items were selected |
+| `no context records exist for this project yet` | The pool is empty |
+
+### Packet sections and audit
+
+Every selected item lands in exactly one section: `currentState`, `knowledge`, `evidence`, `episodes`, `skills` or `contradictions`. The `evidence` section holds journal errors, observations, hypotheses, experiments and state changes. The packet also carries `workingState`, `provenanceSummary` (counts by origin) and `estimatedTokens`.
+
+The `audit` object lists `selectedIds`, `candidateCount`, `excludedSuperseded`, the budget and the gaps. `audit.relevance` holds numbers only: `taskTokens` (distinct task words), `matchedCandidates` (eligible items sharing a task word) and `selected` (each selected item's rounded score, in `selectedIds` order). `audit.request` echoes your request, including the task text; the hub log records only the task's size.
+
+## Recall records
+
+Recall searches the live pool and returns metadata, never summaries. Operators use `kxm context recall`; agents call `kxm_recall`.
+
+```bash
+kxm context recall demo --query "release branch" --json | jq -c '.items[] | {kind, status, origin: .sourceType, relevance}'
+```
+
+Expected output:
+
+```text
+{"kind":"state","status":"current","origin":"peer","relevance":0.791}
+```
+
+Items whose summary or state key contains the whole query, ignoring case, come first. Items that share a word with the query follow, by BM25 relevance, then id. Items with neither are left out, and an empty query returns every item in id order. The default limit is 25 and the maximum is 100.
+
+## Manage temporal state
+
+Temporal state holds one authoritative value per key, such as `release.branch`, with its full history. Agents propose a value with the `kxm_promote` tool; despite its name, the tool only proposes. An operator promotes the proposal with evidence.
+
+```json
+{"key": "release.branch", "summary": "Releases are cut from the main branch", "authority": "evidence", "confidence": "verified", "evidenceRefs": ["pr:12"]}
+```
+
+The hub answers with a `proposalId`. Review the evidence, then promote it:
+
+```bash
+kxm context promote demo <proposal-id> --evidence review:pr-12 --json \
+  | jq -c '.state | {status, authority, origin: .provenance.sourceType, evidenceRefs}'
+```
+
+Expected output:
+
+```text
+{"status":"current","authority":"evidence","origin":"peer","evidenceRefs":["pr:12","review:pr-12"]}
+```
+
+Read the value now, or as it was at an earlier time:
+
+```bash
+kxm context state demo release.branch --json | jq -c '.state | {summary, status, authority}'
+kxm context state demo release.branch --as-of 2026-09-01T00:00:00Z --json
+```
+
+The state diagram shows the lifecycle, and the flowchart shows the highest authority each origin can grant.
+
+```mermaid
+stateDiagram-v2
+  [*] --> proposed: propose with 1 to 32 evidence refs
+  proposed --> current: promote with evidence<br/>(admin token, promoter is not the author)
+  proposed --> rejected: proposal record closed by promotion
+  current --> superseded: a later promotion of the same key
+  superseded --> [*]: purged 7 days after validUntil
+  note right of current: promotion mints a new current item<br/>and sets validUntil on the old one
+```
+
+```mermaid
+flowchart LR
+  HUMAN[human] -- at most --> POLICY[policy]
+  WORKFLOW[workflow] -- at most --> POLICY
+  GIT[git] -- at most --> INSTRUCTION[instruction]
+  PEER[peer: agent proposals] -- at most --> EVIDENCE[evidence]
+  TOOL[tool] -- at most --> EVIDENCE
+  EXTERNAL[external] -- at most --> EVIDENCE
+  DERIVED[derived] -- at most --> EVIDENCE
+```
+
+The rules the hub enforces:
+
+- **Origin follows the credential, never a name.** A proposal made with an agent key is `peer` origin and capped at `evidence`; claiming `instruction` or `policy` is refused with `context_authority_violation`. A proposal made with the admin token is `human` origin, which can claim up to `policy`, and needs a configured admin token.
+- **`proposedBy` must name the caller**, or the hub refuses with `state_proposer_mismatch` and logs a security alert.
+- **Promotion is control plane only.** It needs a configured `KXM_AUTH_TOKEN` with no loopback bypass; without one the hub answers 503 `admin_auth_not_configured`.
+- **The author cannot promote.** `state_promotion_invalid` refuses it. `kxm context promote` promotes as `kxm-admin`, which is also the author of any proposal made with the admin token; the check separates agents from operators, not one operator from another.
+- **Promotion keeps the origin.** A promoted agent proposal stays `peer` origin at `evidence` authority.
+- **Contradictions stay visible.** Competing proposals for one key are open contradictions and appear in every packet's `contradictions` section. Two current values for one key make `kxm context state` answer 409 `state_contradiction`.
+
+## Read episodes and explain an item
+
+`kxm context episode <project>` (tool `kxm_episode`) returns journal errors, lessons, observations and experiments for the project's retained runs as full items, oldest first, at most 50. Add `--run <run-id>` to limit it to one run.
+
+`kxm context explain <project> <item-id>` returns whether the item exists, its derivation lineage, its evidence references and the source of each ancestor. It is an operator query; there is no `kxm_explain` tool. `kxm explain` (without `context`) is a different command: it estimates a mode's prompt footprint.
+
+## Compile the knowledge wiki
+
+The wiki is a reviewable Markdown view of the pool, never the authoritative store.
+
+> [!IMPORTANT]
+> The wiki commands ship, but the wiki is not a selected feature: the project's release policy defers it, so do not build a process on it. Its section pages also list pending state proposals and unreviewed journal entries under the heading "compiled from reviewed records".
+
+```bash
+# Preview the pages, then write them under the repository root.
+kxm context wiki-compile demo
+kxm context wiki-compile demo --out .
+kxm context wiki-lint demo
+```
+
+Pages land under `.kxm/knowledge/wiki/`: one page per section (`architecture`, `decisions`, `incidents`, `patterns`), a temporal-state page that keeps superseded values visible, a contradictions page, a superseded-history page and `index.md`. Every claim links its record id and source. Compilation never resolves a contradiction. Output is deterministic except the timestamp in `index.md`, so diffs stay small. `wiki-lint` checks for broken references, orphan pages, stale state links and hidden contradictions, and exits 1 on an error.
+
+## Author Git memory
+
+Git memory is the durable, reviewed layer: facts a person has approved, versioned with the code. Each fact is a Markdown file with `kxm.memory.v1` front matter.
+
+`.kxm/memory/test-runner.md`:
+
+```yaml
+---
+schema: kxm.memory.v1
+id: test-runner
+scope: project            # agent, project, run or operator
+kind: convention          # free-form label
+summary: Run the test suite with npm test before every commit
+provenance:
+  sourceType: git
+  sourceRef: docs/testing.md
+authority: instruction    # instruction, evidence or promoted
+confidence: verified
+lifecycle: active         # only active facts are loaded
+evidenceRefs: []
+---
+```
+
+`instruction` and `promoted` authority become `instruction` in packets; `evidence` stays `evidence`. Operator-scope facts become `_shared` defaults. Control-plane fields are refused, and summaries are redacted. One malformed file stops the whole load, so validate before you commit.
+
+The workflow:
+
+1. Record a candidate. It lands in `.kxm/memory/candidates/cand_<scope>_<hex>.md` at `evidence` authority and is never loaded from there.
+
+   ```bash
+   kxm memory note "Use pnpm, not npm, in this repository" --kind convention
+   ```
+
+2. Promote it by pull request: move the file into `.kxm/memory/`, give it a stable id and the authority reviewers agree on, and merge.
+3. Check what agents will see, then refresh the projection blocks:
+
+   ```bash
+   kxm memory brief
+   kxm memory sync --dry-run
+   kxm memory sync
+   ```
+
+`kxm memory sync` writes only the project's memory block, the active facts from `.kxm/memory/`, between `<!-- kxm:memory:start -->` and `<!-- kxm:memory:end -->`. It updates whichever of `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` already exist, appends the block to a file that has no markers, and changes nothing outside them. It never creates one of these files or copies KXM's own instructions into it, and it exits 1 when none of the three exists. Create the file your harness reads yourself.
+
+Sync also refuses malformed markers rather than guess which text is yours. Each file must hold exactly one start marker followed by one end marker, or neither. For an orphan marker, an end before its start or a second block, sync names the file and the problem, exits 1 and writes no file at all. Keep one pair, or delete both so sync appends a fresh block.
+
+| Where memory reaches agents | How |
+|---|---|
+| Any harness that reads `AGENTS.md`, `CLAUDE.md` or `GEMINI.md` | The projection block, after `kxm memory sync` and a commit |
+| Claude Code with the KXM plugin | The SessionStart hook adds the same text `kxm memory brief` prints |
+| Pi with the KXM extension | `/kxm memory` shows the brief |
+| Runtime agent steps | Dispatch context, below |
+
+## Context for Runtime agents
+
+When `kxm run` dispatches an agent step, the Runtime adds project memory and promoted skills to the agent's prompt. It reads only local Git and the project tree, never the hub, so dispatch works with the hub down.
+
+- **Sources.** Active `.kxm/memory/*.md` facts with `project` or `operator` scope, and promoted skills whose content hash verifies. Candidates are never read. `agent` and `run` scopes are skipped because nothing binds them to one agent or run.
+- **Committed content only.** The memory and promoted-skill files must be tracked and clean at `HEAD`, and the memory revision (a hash over those files) must match the one the run pinned when it was created.
+- **Selection.** The same arbiter picks items, with the step instructions and prompt as the task and a budget of 4,000 tokens. The role comes from the agent id: an exact role name, or a role followed by a hyphen (`critic-arch` is a critic); any other id is a custom role.
+- **Rendering.** Items appear under **Environment & Memory**: shared defaults, then at most five project items, then **Active Skills**. A skill is delivered as its name, description and pinned hash reference, not its full `SKILL.md`.
+
+When something is withheld, the step still runs without it and a gap is recorded in the packet's `budget.unresolvedGaps` and the `dispatch_context_assembled` log event, never in the prompt:
+
+| Gap | Meaning |
+|---|---|
+| `dispatch_context_withheld:uncommitted` | A memory or promoted-skill file is modified, untracked or ignored |
+| `dispatch_context_withheld:git_unavailable` | `git status` failed or took longer than 5 seconds |
+| `dispatch_context_withheld:memory_revision_drift` | Memory or skills changed since the run pinned its revision |
+| `dispatch_context_memory_unreadable` | A memory file does not parse |
+| `dispatch_context_memory_rejected:<id>` | One fact could not become a context item |
+| `dispatch_context_skill_unverified:<id>` | A promoted skill does not match its hash |
+| `dispatch_context_skills_unreadable` | The promoted skills could not be listed |
+| `dispatch_context_render_deferred:<n>` | More project items were selected than the prompt renders |
+| `dispatch_context_not_loaded` | Context could not be loaded before this step |
+| `dispatch_context_failed` | Loading or assembly failed unexpectedly |
+
+A project with no memory and no promoted skill dispatches exactly as before.
+
+### Prompt layout and pruning
+
+The agent's prompt is the step's `instructions`, then a Markdown context packet. Its header names the project, the agent ID as the role, the step, the attempt, the permission ceiling and the allowed outcomes. Numbered sections follow: **1. Objective** (the run prompt), **2. Acceptance Criteria** (one line per required evidence key), **3. Plan Pointer** (step N of M), and **5. Environment & Memory**. Section 4, predecessor outputs, is not filled by Runtime dispatch today.
+
+Before rendering, the packet is pruned to a budget of 16,000 tokens, estimated at four characters per token over the rendered text. When it is over budget, pruning removes items in a fixed order until it fits:
+
+1. Shared defaults (L1).
+2. Episode items, then project knowledge items (L2).
+3. Predecessor artifact snippets, then the artifact lists (L5).
+
+The objective, the plan pointer and the acceptance criteria are never removed. If the packet still does not fit, its `budget.unresolvedGaps` records `context_budget_exceeded_task_inviolable`. Removed items are not recorded as gaps.
+
+## Limits and known issues
+
+- **The hub misses authored memory with the default layout.** The hub looks for `.kxm/memory` two directories above its database file. With the default `.kxm/state/kxm.db` that resolves inside `.kxm/`, so `kxm context get`, `recall`, `explain` and `wiki-compile` see no memory facts. Runtime dispatch context reads memory correctly.
+- **A multi-project hub shares one checkout's memory and skills.** The hub reads authored memory from its own checkout and promoted skills from `.kxm/skills` in the directory it started in, and attaches both to every project that asks, labeled as that project's. Do not rely on a shared hub to keep memory or skills apart between projects.
+- **The `episodes` section is usually empty.** No record in the hub pool has the `episode` kind today. Use `kxm context episode` for episodic records.
+- **`--run` and `--stage` do not filter.** They are recorded in the audit only.
+- **History is short.** The hub purges superseded state and closed proposals 7 days after they end, so `--as-of` only reaches back that far. Terminal runs and their journal are purged on the same schedule.
+- **The wiki compiles every retained journal entry and pending proposal**, not only reviewed ones. Its index links the temporal-state page at the wrong path, and `wiki-lint` can report a false `stale_state_link` on that page when a superseded value sits close to the Current heading.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `kxm context` answers 401 `invalid_auth` | `KXM_AUTH_TOKEN` is unset or wrong | Export the hub admin token |
+| Promotion answers 503 `admin_auth_not_configured` | The hub started without `KXM_AUTH_TOKEN` | Restart the hub with an admin token |
+| Promotion answers `state_promotion_invalid` | The promoter is the proposal's author | Promote as a different identity |
+| A proposal answers `context_authority_violation` | An agent claimed `instruction` or `policy` | Propose at `evidence` or `hypothesis` |
+| An agent request answers `context_isolation_violation` | It named a project other than its own | Use the agent's own project |
+| `kxm context state` answers 409 `state_contradiction` | Two current values exist for one key | Promote one value with evidence |
+| A Runtime step lacks expected memory | A dispatch gap withheld it | Commit the memory files and start a new run |
+| `memory sync failed: none of AGENTS.md, CLAUDE.md, GEMINI.md exists` | Sync never creates an instruction file | Create the file your harness reads, then sync again |
+| `memory sync failed: <file> has …; wrote no file` | The file has an orphan marker, an end before its start, or a second block | Keep one marker pair, or delete both, then sync again |
+
+## Next steps
+
+- Turn run evidence into ranked improvements: [Continuous improvement](continuous-improvement.md)
+- Govern reusable procedures: [Governed skills](governed-skills.md)
+- Understand who may do what: [Trust model](../concepts/trust-model.md)
+- Every flag and output key: [CLI reference](../reference/cli-reference.md#kxm-context) and [MCP and Pi tools](../reference/tools.md)