@kontextmind/kxm 0.6.0

package/docs/getting-started.md

@@ -0,0 +1,253 @@
+# Getting started
+
+This guide takes you from a clean machine to a successful peer request. Allow about ten minutes once Node.js, Git, and your agent harnesses are installed.
+
+## Before you begin
+
+You need:
+
+- Node.js 22.19 or newer on the 22.x line, or Node.js 24 or newer;
+- Git;
+- GitHub CLI for the command-first release install;
+- Pi for Pi agents;
+- Claude Code only if you want a mixed Pi/Claude pool;
+- access to `kontextmind/kxm` while the repository is private.
+
+All agents in one pool must use the same hub URL, project token, and project name. Keep the hub/operator administrative token separate. Every active agent in that project must have a unique name.
+
+## 1. Install
+
+Pi's Git package installation supplies the extension and Agent Skill but does
+not add `kxm` to `PATH`. Download the packed release through an authenticated
+GitHub CLI session and install that local tarball. Run `gh auth login` first if
+necessary.
+
+PowerShell:
+
+```powershell
+$version = "<release-version>"
+$asset = "kxm-$version.tgz"
+$releaseDir = Join-Path $PWD ".kxm-release"
+New-Item -ItemType Directory -Force -Path $releaseDir | Out-Null
+gh release download "v$version" --repo kontextmind/kxm --pattern $asset --dir $releaseDir --clobber
+npm install --global --omit=peer (Join-Path $releaseDir $asset)
+pi install git:github.com/kontextmind/kxm@main
+kxm --help
+```
+
+Bash:
+
+```bash
+version='<release-version>'
+asset="kxm-${version}.tgz"
+mkdir -p .kxm-release
+gh release download "v${version}" --repo kontextmind/kxm \
+  --pattern "$asset" --dir .kxm-release --clobber
+npm install --global --omit=peer ".kxm-release/$asset"
+pi install git:github.com/kontextmind/kxm@main
+kxm --help
+```
+
+Do not substitute a global `git+https` npm install; the supported global
+operator package is the versioned release tarball. To run from source instead,
+clone the repository, run `npm ci`, and use `node scripts/kxm.mjs` in place
+of `kxm`.
+
+## 2. Initialize the project
+
+```text
+kxm init
+```
+
+`kxm init` never copies the package repository's dogfood roster or workflows into a consumer workspace.
+
+## 3. Start the hub in another terminal
+
+`kxm hub start` is foreground. Keep that terminal running.
+
+PowerShell:
+
+```powershell
+$env:KXM_AUTH_TOKEN = "replace-with-an-admin-token"
+$env:KXM_PROJECT_TOKENS = '{"demo":"replace-with-a-demo-project-token"}'
+kxm hub start
+```
+
+Bash:
+
+```bash
+export KXM_AUTH_TOKEN="replace-with-an-admin-token"
+export KXM_PROJECT_TOKENS='{"demo":"replace-with-a-demo-project-token"}'
+kxm hub start
+```
+
+A successful start prints:
+
+```text
+kxm hub listening at http://127.0.0.1:7331; storage=<workspace>/.kxm/state/kxm.db
+```
+
+The default database survives hub restarts and is ignored by Git.
+
+## 4. Bind this machine to the hub
+
+```text
+kxm hub bind http://127.0.0.1:7331
+```
+
+## 5. Confirm the session
+
+```text
+kxm session brief
+```
+
+## 6. Open Pi and check the hub
+
+Set an identity and start the first agent. Do not give agents the administrative token.
+
+PowerShell:
+
+```powershell
+$env:KXM_SERVER_URL = "http://127.0.0.1:7331"
+$env:KXM_AUTH_TOKEN = "replace-with-a-demo-project-token"
+$env:KXM_PROJECT = "demo"
+$env:KXM_AGENT_NAME = "planner"
+$env:KXM_AGENT_PURPOSE = "Plans work and coordinates handoffs"
+pi
+```
+
+Bash:
+
+```bash
+export KXM_SERVER_URL=http://127.0.0.1:7331
+export KXM_AUTH_TOKEN="replace-with-a-demo-project-token"
+export KXM_PROJECT=demo
+export KXM_AGENT_NAME=planner
+export KXM_AGENT_PURPOSE="Plans work and coordinates handoffs"
+pi
+```
+
+In Pi, run `/kxm hub`. It should show the connected identity and server.
+
+Open a second terminal, repeat the settings, and change only the identity:
+
+```powershell
+$env:KXM_AGENT_NAME = "reviewer"
+$env:KXM_AGENT_PURPOSE = "Reviews plans and code for correctness risks"
+pi
+```
+
+Ask the planner:
+
+```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 should call `kxm_list`, `kxm_send`, and `kxm_await`. The reviewer receives an agent turn and its settled response returns to the planner.
+
+For an executable transport-only demonstration, run `npm run example`. It starts a temporary in-memory hub, completes a planner-to-reviewer round trip, and exits without changing the normal database.
+
+## Connect Claude Code
+
+Keep the same hub running. Inside Claude Code, add the marketplace and install the plugin:
+
+```text
+/plugin marketplace add kontextmind/kxm
+/plugin install kxm
+/reload-plugins
+```
+
+Configure these values when prompted:
+
+| Setting | Example |
+|---|---|
+| KXM server URL | `http://127.0.0.1:7331` |
+| Authentication token | The `demo` project token, not the administrative token |
+| Agent name | `claude-reviewer` |
+| Agent purpose | `Reviews implementation and tests` |
+| Project | `demo` |
+
+Restart Claude Code after configuration. Ask it to use `kxm_list`; the connected Pi agents should appear.
+
+### Optional pushed delivery
+
+Claude channels can inject an inbound request into a running session. They are currently a research-preview feature, and a community channel must be explicitly trusted at launch:
+
+```text
+claude --dangerously-load-development-channels plugin:kxm
+```
+
+Review the trust prompt before accepting it. If an organization administrator has approved the plugin through `allowedChannelPlugins`, use:
+
+```text
+claude --channels plugin:kxm
+```
+
+Without channel mode, Claude can still send requests and receive them by calling `kxm_inbox`, then answer with `kxm_reply`.
+
+## Your first useful topology
+
+Start with two or three purposeful roles:
+
+| Role | Good responsibilities |
+|---|---|
+| Planner | Break down work, define ownership, collect results |
+| Builder | Implement one bounded change |
+| Reviewer | Check correctness, tests, security, or documentation |
+
+Avoid assigning two agents to edit the same files in one checkout. Use separate Git worktrees or give one agent write ownership.
+
+## Next steps
+
+- Use the wiki-ready [KXM Handbook](kxm-handbook.md) for the complete CLI, Pi, Claude, workflow, gate, and recovery reference.
+- Adjust names, project isolation, and network settings in [Configuration](configuration.md).
+- Learn the request lifecycle in [Architecture](architecture.md).
+- Read [Operations](operations.md) before binding beyond localhost.
+- Review the [Test matrix](test-matrix.md) for verified features and example coverage.
+- Start a long-lived coordinator from Jira with [Webhook workflows](webhook-workflows.md).
+- Use [Troubleshooting](troubleshooting.md) if an agent does not appear or a request does not arrive.
+
+## Try the v0.5 context features
+
+With a hub running (`kxm hub start`):
+
+```bash
+# Role-aware context packet for the current project
+kxm context get my-project --role planner --task "plan the CI migration" --budget 8192
+
+# Search durable context records (metadata only)
+kxm context recall my-project --query "flaky"
+
+# Explain evidence and lineage for one context item
+kxm context explain my-project ctx_item_abc123
+
+# Authoritative temporal state (and historical queries)
+kxm context state my-project ci.pipeline
+kxm context state my-project ci.pipeline --as-of 2026-01-15T00:00:00.000Z
+
+# Episodic learning from workflow journals
+kxm context episode my-project
+
+# Compile and lint the knowledge wiki
+kxm context wiki-compile my-project
+kxm context wiki-lint my-project
+
+# Routing telemetry per behavioral configuration
+kxm routing report
+```
+
+State changes follow a propose-then-promote flow: agents propose through the
+`kxm_promote` Pi/MCP tool (or the context API), and an operator promotes with
+durable evidence:
+
+```bash
+kxm context promote my-project ctx_prop_abc123 --evidence "receipt:run_9/verify"
+```
+
+Role-aware packets differ by role: repro agents see prior reproductions and
+incidents; planners see current state and decisions; critics see
+contradictions; implementers see the approved plan and skills; verifiers see
+acceptance evidence. The same requests through Pi (`kxm_context`) or Claude
+Code (MCP) return the same packets — agents never talk to a memory backend
+directly.