@kontextmind/kxm 0.7.95 → 0.7.97

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

@@ -0,0 +1,231 @@
+# CI and release
+
+Every pull request and every push to `main` that changes code runs a
+three-minute merge-safety gate, the complete suite with coverage floors runs
+nightly, every merge to `main` cuts a patch release, and every release is
+verified before it reaches npm. This
+page explains which checks run where, how a merge becomes a published version,
+and which smoke tests stay manual. It is for contributors and maintainers.
+
+## The pipeline at a glance
+
+A merged pull request flows through CI, an automatic tag, a verified GitHub
+release and an npm publish; the nightly job adds the slower suites.
+
+```mermaid
+flowchart LR
+  PR[Pull request] -->|"validate:pr, docs lint, plugin validation"| MERGE{Merged?}
+  MERGE -->|yes| MAIN[main]
+  MAIN -->|"same three-minute validate:pr"| PUSH[Push CI]
+  MAIN -->|"Auto-Release: next patch tag"| TAG[Tag vX.Y.Z]
+  TAG -->|dispatch| REL[Release workflow]
+  REL -->|"verify, stamp version, pack"| GH[GitHub release<br/>kxm-X.Y.Z.tgz]
+  GH -->|"sha256 verified"| NPM[npm publish]
+  MAIN -->|"daily 04:00 UTC"| NIGHT[Nightly<br/>complete suite]
+```
+
+All workflows live in `.github/workflows/`. Every job runs on the organization's
+ARC runner scale set, and `test/core/ci-contract.test.ts` pins the
+runner selector, job names, coverage floors and release triggers. Change a
+workflow and that test together.
+
+## What runs where
+
+| Trigger | Workflow (job) | What it runs |
+|---|---|---|
+| Before you push | Local | `npm run verify` |
+| Pull request and push to `main` | `ci.yml` (Validate, two Node legs) | `validate:pr`, the three-minute gate; skipped for documentation-only changes |
+| Pull request and push | `ci.yml` (Docs lint) | `lint:docs` and `check:versions`, always |
+| Pull request and push | `ci.yml` (Plugin validation) | `claude plugin validate --strict` on the marketplace and the plugin; skipped for documentation-only changes |
+| Daily at 04:00 UTC, or manual | `nightly.yml` | `test:coverage:complete`, `check`, `check:generated`, `npm pack --dry-run` |
+| Merged pull request | `auto-release.yml` | Tags the merge commit and dispatches `release.yml` |
+| Tag push or dispatch | `release.yml` | Verifies, packs and publishes (see [Release flow](#release-flow)) |
+| Manual only | `smoke.yml` | Real Pi smoke, currently disabled (see [Smoke tests](#smoke-tests)) |
+
+The npm scripts behind those rows:
+
+| Script | Composition |
+|---|---|
+| `verify` | `npm test` (core and package unit tests), `check`, `check:generated` |
+| `validate:pr` | `build`, `typecheck`, a compact contract and smoke set of nine `test/core` files, `check:versions`, and the generated-`dist` check |
+| `validate:ci` | `test:coverage` (core and package tests, 91/80/92 floors), `check`, `npm pack --dry-run`; not run by CI today, available locally |
+| `test:coverage:complete` | Core, simulation and package tests with 93/80/93 floors |
+| `check` | `typecheck`, `lint:docs`, `check:versions` |
+
+Three differences matter when a check fails on one side only:
+
+- CI runs a compact contract and smoke set, not the core suite. The full core
+  suite and the package unit tests under `packages/core/*/tests` run in your
+  local `npm run verify`; run it before every push.
+- Coverage and `test/simulations` run only in the nightly complete suite, never
+  on a pull request or a push to `main`.
+- A regression the compact set misses can reach `main` and show up in the
+  nightly run, so treat a nightly failure as a release blocker.
+
+### Validate matrix and required checks
+
+The Validate job runs on Node 22.19.0 and Node 24, on Linux, with a
+three-minute job timeout. The branch ruleset
+requires the job names `Validate (linux, Node 22.19.0)` and
+`Validate (linux, Node 24)`, so renaming the job or the matrix means updating
+the ruleset in the same change. A newer push cancels an older pull request run;
+runs on `main` are never cancelled.
+
+### CI jobs stay queued while a runner is online
+
+Every Linux workflow targets the ARC runner scale set `kontextmind-doks`. That
+name is the scale set, not a custom label on a repository runner. The scale set
+belongs to the selected-repository runner group `KontextMind DOKS ARC`, which
+must allow this public repository. The legacy repository runner `km-gh-rn01`
+must not carry the `kontextmind-doks` label; adding it bypasses ARC and
+serializes the build queue.
+
+Check GitHub routing first:
+
+```bash
+gh api repos/kontextmind/kxm/actions/runners \
+  --jq '.runners[] | {name, status, busy, labels: [.labels[].name]}'
+gh api orgs/kontextmind/actions/runner-groups \
+  --jq '.runner_groups[] | select(.name == "KontextMind DOKS ARC") |
+    {name, visibility, allows_public_repositories}'
+```
+
+Then check ARC in the cluster:
+
+```bash
+kubectl -n arc-runners get autoscalingrunnerset kontextmind-doks
+kubectl -n arc-runners get ephemeralrunners,pods
+```
+
+The capacity policy keeps one warm runner, bursts to four, and requests three
+CPUs per runner so the node-pool autoscaler adds capacity instead of packing
+CPU-bound jobs onto busy nodes. If jobs stay queued while the listener is
+assigned zero jobs, check the runner group's selected repository and public
+repository access. If ARC has pending pods, check node capacity and the cluster
+autoscaler. Do not relabel `km-gh-rn01` or push an empty commit as a routing
+workaround.
+
+> [!NOTE]
+> Windows legs are paused, not removed. Windows stays a supported target, and
+> Windows-specific fixtures (for example the `pi.cmd` worker launch in
+> `test/core/worker.test.ts`) run when you test on Windows locally.
+
+### The docs-only classifier
+
+The first job, Classify changes, lists the changed paths and sets `code=false`
+when every path matches `*.md`, `docs/*`, `.kxm/assets/*`, `LICENSE`, the issue
+and PR templates, or `dependabot.yml`. Validate and Plugin validation read it:
+for a documentation-only change they report success without checking out the
+code, so the required job names still pass. Docs lint always runs.
+`ci-contract.test.ts` pins this behavior.
+
+> [!WARNING]
+> Several tests and code paths read documentation files by path. A pull request
+> that only moves or renames a pinned doc is classified documentation-only, so
+> CI does not run the tests that would catch the broken path; the next code
+> change fails instead. For any docs move, update the pinned readers in the same
+> pull request (see [Pinned paths](writing-docs.md#pinned-paths)) and run
+> `npm run verify` locally before you push.
+
+## Release flow
+
+KXM releases a patch version for every merged pull request. No one bumps
+versions by hand.
+
+1. **Auto-Release** (`auto-release.yml`) runs when a pull request to `main` is
+   merged. It finds the newest `vX.Y.Z` tag, adds one to the patch number, tags
+   the merge commit, and dispatches the Release workflow for that tag.
+2. **Release** (`release.yml`) checks out the tag, and takes its release helper
+   scripts from `main`. It runs `npm run check:generated` against the tagged
+   tree, stamps the tag's version into every version surface, runs
+   `npm run validate:ci`, and packs `kxm-<version>.tgz`. The step summary records
+   the tarball's sha256.
+3. `scripts/kxm-release-github.mjs` creates a draft GitHub release, uploads the
+   tarball, and checks the digest GitHub reports against the local one. The
+   workflow then publishes the draft.
+4. **Publish npm** runs in the protected `npm-publish` environment. It skips a
+   version already on npm. Otherwise `scripts/kxm-publish-npm.mjs` confirms the
+   GitHub release is published, downloads the asset, verifies its sha256
+   against the release digest, and runs `npm publish` on that exact file.
+
+Every step is idempotent. Rerunning the Release workflow for a tag that is
+already published or already on npm reports it and changes nothing.
+
+### Skip a release
+
+Auto-Release skips a merge when the pull request has the `no-release` label, or
+when its head branch starts with `chore/release-`.
+
+### Versions
+
+The version in the repository's `package.json` stays at its base value. The
+release job stamps the tag's version into the package, the lockfile, the plugin
+package and manifest, the marketplace entry, the MCP server constant, and every
+workspace package, in the runner's workspace only. The stamp is never committed
+back.
+
+- Do not edit version fields in a pull request. `npm run check:versions` fails
+  when any surface differs from the root `package.json`.
+- Auto-Release only increments the patch number. For a minor or major release,
+  push a `vX.Y.0` tag yourself; `release.yml` also runs on tag pushes, and
+  later merges continue from that tag.
+- `scripts/kxm-bump-version.mjs` and `scripts/check-versions.mjs` read the same
+  package list from `scripts/package-surfaces.mjs`, so the gate and the writer
+  cannot disagree.
+
+### Changelog
+
+Add user-visible changes to `CHANGELOG.md` under `## Unreleased`, in the same
+pull request. Keep an entry to a few lines and link the doc page that explains
+the behavior. Add an `### Upgrade note` when an operator must act.
+
+No release step moves those entries into a dated section. Auto-Release tags a
+patch for each merged pull request, but nothing cuts the changelog, so
+everything released since its newest dated section is still listed under
+`## Unreleased`.
+
+## Smoke tests
+
+Smoke tests prove what unit tests cannot: that the packed artifact installs,
+and that real harnesses complete a turn.
+
+| Smoke | How to run | What it proves |
+|---|---|---|
+| Packed install | Part of the core suite: `test/core/package-install.test.ts` | The packed CLI and hub run from a clean local and global install |
+| Real Pi smoke | `KXM_SMOKE=1 KXM_SMOKE_MODELS=<model-a>,<model-b> node scripts/smoke-multi-pi.mjs` | Two supervised Pi workers discover each other, exchange requests and replies, and recover across a restart |
+| Container install | `just docker-install-smoke` | The tarball installs into a fresh container with a fresh Pi, and two providers complete a live turn |
+
+The real Pi smoke calls paid models, so it never runs by default. Its workflow,
+`smoke.yml`, is manual and stays skipped until the repository variable
+`KXM_SMOKE_RUNNER` names a runner with Pi credentials. Both smoke models run as
+long-lived Pi workers, so each must pass the Pi native-vendor brake: pick two
+non-native routes such as
+`openrouter/qwen/qwen3-coder-plus,openrouter/z-ai/glm-5.3-flash`, never `xai/…`
+or `anthropic/…`. The container smoke needs
+Docker, a `pass-cli` session and a local Pi model store. It keeps secrets in a
+mode-600 file inside a temporary directory; set `KXM_SMOKE_VAULT` to read keys
+from your own vault.
+
+### Manual checks before announcing a release
+
+Automation cannot prove that a harness UI renders correctly. Before you
+announce a release:
+
+1. Install the published version:
+   `npm install --global --omit=peer @kontextmind/kxm@<version>`.
+2. Connect two current Pi sessions, run `/kxm hub`, and complete one inbound
+   round trip.
+3. Install the marketplace plugin in a clean Claude Code profile and confirm
+   that `kxm_list` answers.
+4. Check pushed channel delivery only when the target Claude Code version
+   supports channels.
+
+If a behavior can only be checked by hand, add it to this list rather than
+implying automated coverage.
+
+## Related
+
+- [Develop KXM](development.md): the local gate and generated artifacts
+- [Test matrix](test-matrix.md): which test proves which behavior
+- [Write KXM documentation](writing-docs.md): doc gates and pinned paths
+- [Upgrade KXM](../operations/upgrade.md): the operator side of a new version

package/docs/contributing/development.md

@@ -0,0 +1,362 @@
+# Develop KXM
+
+Set up a source checkout, learn where each part of KXM lives, and run the same
+gate CI runs before you push. This page is for contributors who change the CLI,
+the [hub](../glossary.md#hub), the [Runtime](../glossary.md#runtime), the Pi
+extension, the Claude Code plugin, or the bundled skills.
+
+## Before you begin
+
+- Node.js 22.19 or newer on the 22 line, or Node.js 24 or newer. The
+  `engines` field in `package.json` is the authority.
+- npm and Git.
+- Optional tools, needed only for the matching task:
+  - [Pi](https://pi.dev) to load the extension from source.
+  - The Claude Code CLI to validate the plugin manifests locally.
+  - [`just`](https://github.com/casey/just) for the
+    [assignment runner](assignment-runner.md).
+  - Docker for the clean-container install smoke.
+
+## Set up a checkout
+
+```bash
+git clone https://github.com/kontextmind/kxm.git
+cd kxm
+npm ci
+node scripts/kxm.mjs --help
+```
+
+`node scripts/kxm.mjs` is the `kxm` binary from `package.json` `bin`. It runs the
+committed bundle `plugins/kxm/dist/cli.js`, not the TypeScript source. A source
+change is invisible until you rebuild:
+
+```bash
+npm run build
+```
+
+Use `node scripts/kxm.mjs` wherever the user docs show `kxm`.
+
+### Keep experiments away from real state
+
+A source build uses the same default hub (`http://127.0.0.1:7331`), user state
+root, configuration and telemetry directories as an installed `kxm`. Point every
+experiment at throwaway directories and a hub you start yourself on another
+port:
+
+```bash
+# Run in a scratch Git repository, not in your KXM checkout.
+export KXM_STATE_HOME="$(mktemp -d)"
+export KXM_USER_CONFIG_DIR="$(mktemp -d)"
+export KXM_USER_TELEMETRY_DIR="$(mktemp -d)"
+export KXM_PORT=47331
+export KXM_SERVER_URL="http://127.0.0.1:$KXM_PORT"
+node /path/to/kxm/scripts/kxm.mjs hub start
+```
+
+In a second terminal with the same variables:
+
+```bash
+node /path/to/kxm/scripts/kxm.mjs hub view
+node /path/to/kxm/scripts/kxm.mjs hub stop
+```
+
+Expected output of `hub view`:
+
+```text
+hub health=true ready=true · loopback hub
+```
+
+`KXM_STATE_HOME` must be an absolute path. The hub writes its database and logs
+under `.kxm/` in the directory where you start it.
+
+### Load the Pi extension from source
+
+Pi loads the TypeScript extension directly, so it needs no build step:
+
+```bash
+pi --no-extensions -e ./plugins/kxm/src/extension.ts
+```
+
+`--no-extensions` turns off Pi's package discovery, so only the listed extensions
+load. Add another `-e` for each provider extension your models need.
+
+### Validate the Claude Code plugin
+
+With the Claude Code CLI installed, run the same strict manifest validation as
+CI. Validation reads the manifests only; the plugin itself runs the committed
+`plugins/kxm/dist/mcp-server.js`, so rebuild before you try it in Claude Code.
+
+```bash
+npm run validate:claude
+```
+
+## Repository layout
+
+The tree below lists what is tracked in Git. Directories marked "not shipped" are
+excluded from the npm package.
+
+```text
+.
+├── plugins/kxm/            The product: CLI, hub, Runtime, Pi extension, MCP server
+│   ├── src/                TypeScript source (cli/, context/, providers/ inside)
+│   ├── dist/               Generated, committed bundles (see Generated artifacts)
+│   ├── skills/             Bundled Agent Skills, one <name>/SKILL.md each
+│   ├── skill-suite.json    Skill manifest: names, paths, owned commands
+│   ├── .claude-plugin/     Claude Code plugin manifest (plugin.json)
+│   └── .mcp.json           MCP server launch for the plugin
+├── .claude-plugin/         Claude marketplace catalog (marketplace.json)
+├── packages/core/tui/      @kontextmind/tui workspace package
+├── scripts/                kxm.mjs, hub and worker wrappers, build, release, runners
+├── schemas/                JSON Schemas for YAML resources, events and records
+├── docs/                   User, operator and contributor documentation
+├── examples/               Runnable transport examples and project fixtures
+├── test/                   core/, simulations/, fixtures/, helpers/ (not shipped)
+├── .kxm/                   This repository's own KXM project definition
+├── .agents/skills/         Generated mirror of the bundled skills (not shipped)
+├── .github/                CI, release, issue and PR templates (not shipped)
+├── .claude/                Developer harness notes and commands (not shipped)
+├── plans/                  Internal planning and tracking (not shipped)
+├── justfile                Developer recipes for the assignment runner
+└── AGENTS.md, CLAUDE.md, GEMINI.md   Agent instructions with generated blocks
+```
+
+The workspace layout for `packages/` is described in
+[Packages and workspaces](packages.md). The `.kxm/` layout is described in
+[`.kxm/README.md`](../../.kxm/README.md).
+
+## Packaging standards
+
+KXM ships one product through four native package formats. Each format reads
+its own manifest, and `npm run check:versions` keeps every version field equal.
+
+### npm package
+
+`@kontextmind/kxm` is published publicly.
+
+| Field | What it declares |
+|---|---|
+| `bin` | `kxm` → `scripts/kxm.mjs` |
+| `exports` | `./core`, `./runtime`, `./client`, `./extension`, `./mcp` from `plugins/kxm/dist`, and `./tui` |
+| `files` | `plugins/kxm/{dist,src,skills}`, `scripts`, `docs`, `examples`, `schemas`, the plugin manifests, and selected `.kxm` files |
+| `engines` | Node `^22.19.0 \|\| >=24.0.0` |
+| `peerDependencies` | Pi and `typebox`, both optional |
+
+Everything under `docs/` ships in the tarball, so a link from `docs/` into
+`plans/` is dead for npm readers. `.npmignore` drops logs, state and generated
+assets even inside listed directories. Inspect the result with
+`npm pack --dry-run`.
+
+### Claude Code plugin and marketplace
+
+| File | Role |
+|---|---|
+| `.claude-plugin/marketplace.json` | Marketplace catalog; its `kxm` entry points at `./plugins/kxm` |
+| `plugins/kxm/.claude-plugin/plugin.json` | Plugin manifest: `userConfig`, the `SessionStart` hook, the channel, and `mcpServers` |
+| `plugins/kxm/.mcp.json` | Launches `dist/mcp-server.js` over stdio and maps `userConfig` to `KXM_*` variables |
+| `plugins/kxm/dist/claude-hook.js` | The bundled, read-only `SessionStart` hook script |
+
+A marketplace install clones the repository, so the plugin can use only committed
+files. That is why the bundles in `dist/` are tracked. For what the plugin does,
+see the [plugin README](../../plugins/kxm/README.md).
+
+### Pi package
+
+The root `package.json` carries the `pi-package` keyword and a `pi` block:
+`pi.extensions` lists `./plugins/kxm/src/extension.ts` and `pi.skills` lists
+`./plugins/kxm/skills`. Pi loads the TypeScript source itself.
+
+### Agent Skills
+
+Each bundled skill is a directory `plugins/kxm/skills/<name>/` with a `SKILL.md`.
+`plugins/kxm/skill-suite.json` declares every skill and the top-level `kxm`
+commands it owns. `test/core/skill-suite.test.ts` enforces the rules:
+
+- The directory name equals the frontmatter `name` and the manifest `name`.
+- The frontmatter parses as strict YAML. Quote any value that contains a colon followed by a space.
+- The `description` is at most 1,024 characters.
+- Every top-level `kxm` command is owned by exactly one skill.
+- `.agents/skills/` matches the authored skills byte for byte.
+
+For what each skill covers, see [Agent skills](../guides/agent-skills.md).
+
+## The development loop
+
+1. Branch from `main`. Keep one concern per branch and one clear concern per
+   commit.
+2. Change the source and the test that proves the change. Update
+   [the test matrix](test-matrix.md) when you add a behavior.
+3. Rebuild with `npm run build` when you touched anything that is bundled.
+4. Run the focused test file while you iterate (see
+   [Test conventions](#test-conventions)).
+5. Update the user docs and `CHANGELOG.md` (under `## Unreleased`) for any
+   user-visible change.
+6. Stage the source change together with the regenerated files. The commit gate
+   compares generated files with the staged copy.
+7. Run the commit gate, `npm run verify`, fix what it reports, then commit.
+8. Push and open a pull request. The template asks for the slice issue and the
+   `npm run verify` result.
+
+Maintainers who delegate work to coding agents use the
+[assignment runner](assignment-runner.md) for steps 2 to 7.
+
+## Generated artifacts
+
+`npm run build` regenerates the files below. They are committed because the
+Claude marketplace installs from Git and npm consumers install without dev
+dependencies. Neither can run a build or strip TypeScript at install time.
+
+| Artifact | Produced by | Consumers |
+|---|---|---|
+| `plugins/kxm/dist/cli.js`, `server.js`, `runtime-supervisor.js`, `claude-hook.js` | `scripts/build-runtime.mjs` | `kxm`, the hub, the Runtime supervisor, the plugin hook |
+| `plugins/kxm/dist/core.js`, `runtime.js`, `client.js`, `extension.js` | `scripts/build-runtime.mjs` | The package `exports` |
+| `plugins/kxm/dist/mcp-server.js` | `npm run build:mcp` | The Claude plugin and `@kontextmind/kxm/mcp` |
+| `packages/core/tui/dist/index.js` | `npm run build:packages` | `@kontextmind/kxm/tui` |
+| `.agents/skills/<name>/…` | `scripts/emit-codex-artifacts.mjs` | Harnesses that read `.agents/skills` |
+| `AGENTS.md` block between the `kxm:codex:commands` markers | `scripts/emit-codex-artifacts.mjs` | Codex and other `AGENTS.md` readers |
+| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` blocks between the `kxm:memory` markers | `syncHarnessMemory` (same as `kxm memory sync`) | Every harness, from `.kxm/memory/*.md` |
+
+Never edit a generated file by hand. Edit its source and rebuild.
+
+`npm run check:generated` rebuilds, then fails if any artifact is missing, not
+tracked, or different from the staged copy. Stage the rebuilt files
+(`git add plugins/kxm/dist packages/core/tui/dist .agents AGENTS.md CLAUDE.md GEMINI.md`)
+before you run it.
+
+## The commit gate
+
+Run `npm run verify` before every commit you push. It is the same gate for
+people and for agents.
+
+```bash
+npm run verify
+```
+
+It runs three scripts in order:
+
+| Step | Script | What it checks |
+|---|---|---|
+| 1 | `npm test` | Build, then `test/core/*.test.ts` and `packages/core/*/tests/unit/*.test.ts` |
+| 2 | `npm run check` | `tsc --noEmit`, `markdownlint-cli2`, and version surfaces |
+| 3 | `npm run check:generated` | Generated artifacts are tracked and match the staged copy |
+
+Other scripts you will use:
+
+| Script | Use it for |
+|---|---|
+| `npm run test:core` | The core suite only (CI runs a smaller contract set; see [CI and release](ci-and-release.md)) |
+| `npm run test:simulations` | `test/simulations/*.test.ts` |
+| `npm run test:coverage` | Core suite with coverage floors |
+| `npm run test:coverage:complete` | Core plus simulations with the higher nightly floors |
+| `npm run lint:docs` | Markdown lint only |
+| `npm run validate:pr` | The three-minute CI gate; see [CI and release](ci-and-release.md) |
+| `npm run validate:ci` | Coverage suite, `check` and a package dry run (not run by CI today) |
+| `npm run validate:claude` | Strict Claude plugin and marketplace validation |
+
+Plugin validation needs the Claude Code CLI, so it is a CI job rather than part
+of `verify`. Do not add a third gate script: `test/core/ci-contract.test.ts`
+refuses one.
+
+### Coverage floors
+
+| Run | Lines | Branches | Functions |
+|---|---:|---:|---:|
+| `test:coverage:core` (pushes to `main`, releases) | 91% | 80% | 92% |
+| `test:coverage:complete` (nightly) | 93% | 80% | 93% |
+
+Coverage measures `plugins/kxm/src/**/*.ts` and `packages/core/*/src/**/*.ts`.
+The floors only move up. A pull request may raise a floor. No pull request may
+lower one: when coverage drops, add tests.
+
+Three files are excluded because they run only as spawned bundles, so coverage
+would attribute their lines to `dist`, never to the source. Each is exercised
+as a child process instead:
+
+- `plugins/kxm/src/server.ts`, the hub entry;
+- `plugins/kxm/src/mcp-server.ts`, the MCP stdio entry;
+- `plugins/kxm/src/runtime-supervisor.ts`, the Runtime supervisor entry.
+
+An exclusion needs a reason other than "hard to test".
+
+## Test conventions
+
+Tests use the built-in `node:test` runner and run TypeScript through
+`--experimental-strip-types`. There is no Jest or Vitest.
+
+### Write one focused test per behavior
+
+- Name each test after the behavior it proves, as a sentence. For example,
+  `"MCP server never registers with the persisted admin token"`.
+- Assert the observable contract: an exit code, a JSON field, an error code, a
+  file on disk. Do not assert log wording unless the wording is the contract.
+- Prove the refusal as well as the success. Fail-closed paths need their own test.
+- Put the test next to its peers in `test/core/<area>.test.ts`, and add a row to
+  [the test matrix](test-matrix.md).
+
+### Run one file or one test
+
+Build once, then run the file directly:
+
+```bash
+npm run build
+node --disable-warning=ExperimentalWarning --experimental-strip-types \
+  --test test/core/improve.test.ts
+# Narrow to tests whose names match a pattern.
+node --disable-warning=ExperimentalWarning --experimental-strip-types \
+  --test --test-name-pattern="same-ask" test/core/improve.test.ts
+```
+
+Several suites spawn the built bundles, so a stale `dist` fails them. Rebuild
+before you trust a failure.
+
+### Isolate all state
+
+A test must never read or write the operator's hub, state root, configuration or
+credentials. Use the shared helpers:
+
+| Helper | What it isolates |
+|---|---|
+| `isolateSessionEnvironment()` in `test/helpers/session-env.ts` | Points `KXM_STATE_HOME` and `KXM_USER_CONFIG_DIR` at a temp directory and clears session tokens |
+| `createTestMesh(context)` in `test/helpers.ts` | Starts an in-memory hub on port `0` with a test token, closed when the test ends |
+| `committedKxmProject(prefix, …)` in `test/helpers/project.ts` | Creates a committed KXM project and a separate state root in temp directories |
+| `test/helpers/harness-fake.ts` | Fake spawns and auth fixtures for `scripts/harness-run.mjs`, so no real harness or login is needed |
+
+Other rules:
+
+- Create files only under `mkdtempSync(join(tmpdir(), …))` and remove them when
+  the test ends.
+- Bind servers to port `0`. Never assume `7331` is free.
+- Make no network calls outside loopback, and never call a paid model. Real-model
+  checks are opt-in smoke tests (see [CI and release](ci-and-release.md#smoke-tests)).
+- Tests must pass on Node 22.19 and Node 24.
+
+## Change the protocol
+
+Routes, request fields, status transitions, delivery modes, limits and
+authentication are the protocol. A change to any of them needs:
+
+- integration tests;
+- an update to `plugins/kxm/skills/kxm/references/protocol.md`;
+- an update to the matching page in `docs/`;
+- a `CHANGELOG.md` entry;
+- a compatibility note when existing clients could break.
+
+Prefer additive changes. KXM does not keep backward-compatible aliases for
+retired names: an old name fails closed instead.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `generated artifacts changed after build` | `dist`, a skill mirror or a generated block differs from the index | Run `npm run build`, stage the listed files, rerun |
+| `generated artifacts are not tracked by git` | A new bundle or skill file was never added | `git add` the listed paths |
+| `… version … does not match …` from `check:versions` | A version surface was edited by hand | Revert it; releases stamp versions (see [CI and release](ci-and-release.md#versions)) |
+| A doc test fails after a docs move | A test or code path reads that doc | See [pinned paths](writing-docs.md#pinned-paths) |
+| A CLI change has no effect | `node scripts/kxm.mjs` runs the old bundle | `npm run build` |
+
+## Next steps
+
+- Understand what CI runs on your pull request: [CI and release](ci-and-release.md)
+- Write or update a docs page: [Write KXM documentation](writing-docs.md)
+- Find the test that proves a behavior: [Test matrix](test-matrix.md)
+- Add a workspace package: [Packages and workspaces](packages.md)
+- Look up a command: [CLI reference](../reference/cli-reference.md)