@kontextmind/kxm 0.7.95 → 0.7.97

package/docs/guides/continuous-improvement.md

@@ -0,0 +1,228 @@
+# Continuous improvement
+
+KXM turns every run into structured evidence, ranks what keeps going wrong across runs, and proposes fixes that a person reviews and applies through Git. This page is for leads and workflow owners who want workflows to get more reliable and cheaper over time. It covers capture, ranked signals, retrospectives, coded-repeat candidates, and the safeguards that keep learning from turning into unreviewed policy.
+
+What sets this apart:
+
+- **Disagreement is preserved.** Contradictions stay open until evidence resolves them; nothing flattens them into one answer.
+- **Everything is a proposal.** Signals, retrospectives and candidates never change a gate, workflow, permission or skill on their own.
+- **Ranking is deterministic and redacted.** The same journal gives the same order, and merge keys never carry raw summary text.
+
+## Before you begin
+
+- The `kxm` CLI and a running [hub](../glossary.md#hub).
+- For journal capture: a hub workflow run started by a signed webhook or `kxm workflow start`. See [Webhook workflows](webhook-workflows.md).
+- For coded repeats: Runtime runs created with `kxm run` in a KXM project.
+
+> [!IMPORTANT]
+> The journal loop covers hub webhook runs only. Runtime runs (`kxm run`) have no journal: `kxm_workflow_record` answers `workflow_not_found` for a Runtime run id. Runtime learning comes from `kxm improve`, which reads settled attempts instead.
+
+## The learning loop
+
+The flowchart shows the two loops and where a person decides.
+
+```mermaid
+flowchart LR
+  subgraph HUB["Hub workflow runs"]
+    REC[Journal entries<br/>from agents and the hub] --> SIG[Ranked signals<br/>kxm_improvement_report]
+    REC --> RETRO[Retrospective<br/>per terminal run]
+  end
+  subgraph RT["Runtime runs"]
+    EVT[(Run event store<br/>settled attempts)] --> IMP[kxm improve report]
+    IMP --> CAND[Candidates<br/>with proposed diffs]
+  end
+  SIG --> REVIEW{Human review}
+  RETRO --> REVIEW
+  CAND --> REVIEW
+  REVIEW -- reviewed PR --> CHANGE[Gates, workflows,<br/>skills, docs, memory]
+  CHANGE -- next runs --> REC
+  CHANGE -- next runs --> EVT
+```
+
+## Capture: record journal entries
+
+Record entries while the run happens, not only at the end. Only the run's assigned coordinator can write its journal. Agents call `kxm_workflow_record`. The `kxm workflow record` CLI does the same from a shell; it connects as `KXM_AGENT_NAME` (default `cli-<pid>`), so it succeeds only under the coordinator's identity.
+
+| Category | Record it when |
+|---|---|
+| `plan` | You decide how the work will run and who owns it, before implementation |
+| `decision` | You pick an option; name the alternatives and why |
+| `contradiction` | Agents, tests, docs or observed behavior disagree |
+| `error` | A stage, tool, gate, integration or assumption fails |
+| `lesson` | Evidence supports a reusable conclusion (evidence required) |
+| `observation` | Something notable happened, without a causal claim |
+| `hypothesis` | You make a falsifiable claim; keep it when it is disproved |
+| `experiment` | You try something; record the outcome, including failure |
+| `state-change` | An authoritative project fact changed |
+| `skill-candidate` | A procedure worked and is backed by run or receipt evidence (evidence required) |
+
+Each entry has an area (`harness`, `gates`, `implementation`, `workflow`, `documentation`, `security` or `other`), a severity (`info`, `warning` or `error`), a summary of at most 1,000 characters, optional details, up to 32 evidence strings and up to 16 related entries from the same run.
+
+Pass `stageId` (`--stage-id` on the CLI) to bind an entry to a stage. The hub, never the caller, derives the attempt: the current attempt for an in-progress or waiting stage, the last attempt consumed for a finished stage, and none for a stage that has not run. When the stage declares an area, `area` may be omitted.
+
+```bash
+kxm workflow record <run-id> lesson "A flaky test hid a race in the cache" \
+  --stage-id verify --severity warning --evidence https://ci.example.com/run/42
+```
+
+| Refusal | Cause |
+|---|---|
+| `invalid_improvement_area` | No `area`, and no `stageId` whose stage declares one |
+| `invalid_journal_relation` | The `stageId` or a related entry is not part of this run |
+| `journal_evidence_required` | A `lesson` or `skill-candidate` without evidence |
+| `workflow_forbidden` | The caller is not the run's coordinator |
+| `workflow_not_found` | The id is not a hub workflow run, for example a `kxm run` id |
+
+### Entries KXM writes for you
+
+You do not need to record these; each is bound to its stage and attempt where one applies:
+
+- The hub records checkpoint warnings and failures, typed stage transitions, transition-budget exhaustion, external-wait timeouts, coordinator prompt expiry, premature coordinator settlement, and degraded-quorum approvals and their use.
+- The Pi extension records failed tool results and failed turns while a webhook workflow is active, as an allowlisted diagnostic class rather than tool output.
+- A supervised Pi worker records the reason each time it recovers.
+
+Agents still record semantic failures: a false assumption, a rejected design, a flaky result or an integration mismatch.
+
+Never put secrets or unneeded prompt text in the journal. Cite durable references instead: test names, commits, pull requests, check runs, issues or documentation paths. Adding a lowercase `class:<name>` to an entry's evidence lets identical failures merge across runs.
+
+### Governed promotion of journal entries
+
+`skill-candidate`, `hypothesis` and `experiment` entries start `proposed`. A hub administrator decides them once, append-only, through `POST /v1/journal/<entry-id>/promotion` with `to` (`approved`, `rejected` or `quarantined`), at least one evidence reference and a reason. The decider is recorded as `kxm-admin` and can never be the entry's author, and a decided entry never reopens. This changes the entry's learning state only; it never changes a gate, a workflow or a permission. See [HTTP API](../reference/http-api.md).
+
+## Signals: rank what recurs across runs
+
+`kxm_improvement_report` answers for the agent's project with three fields: `reports`, per-area counts with each area's ten most severe errors, contradictions, lessons and skill candidates; `signals`, the top 20 recurring problems; and `entries`, the number of journal entries read. Review the top signals weekly.
+
+Only errors, open contradictions (not yet answered by a related decision or lesson), lessons, and skill candidates still `proposed` count. Entries merge into one signal when they share a key, tried in this order:
+
+1. An evidence class, `class:<name>`, within the same category.
+2. For errors, the workflow definition and stage.
+3. The summary after redaction and normalization: ids, timestamps, hex strings and numbers are folded, so the same failure in two runs keys the same.
+
+Each signal keeps up to 16 run ids and entry ids and a redacted summary of its latest entry. It is scored as:
+
+```text
+priority = frequency × severity weight × workflow cost × confidence
+```
+
+| Factor | Meaning |
+|---|---|
+| Frequency | Distinct runs, counted over the runs the hub still retains |
+| Severity weight | 3 for `error`, 2 for `warning`, 1 for `info`, from the most severe entry |
+| Workflow cost | Mean run attempts (stage attempts plus transitions) over known runs; 1 with `costBasis: "unknown"`. Not dollars |
+| Confidence | 0.5 plus half the share of the signal's entries that cite evidence |
+
+Security signals (area `security`, or class `invalid_auth`, `invalid_identity` or `signal_mismatch`) rank ahead of every priority. Other ties break on frequency, then key, never on insertion order. There is no data-loss override, because no deterministic data-loss marker exists; review data-loss risk by hand.
+
+> [!NOTE]
+> The hub purges terminal runs and their journal 7 days after they end, so frequency only counts recent runs. Export accepted decisions and lessons to version-controlled docs or [Git memory](context-and-memory.md#author-git-memory) if they must outlive that window.
+
+## Retrospectives: one run, reviewed
+
+When a hub run completes or fails, the hub writes a bounded retrospective to `.kxm/assets/retrospectives/<run-id>.json` and `<run-id>.md`. It writes them again when a journal entry arrives or a promotion is decided after the run ended. Regenerate one from the local store, or from an offline snapshot:
+
+```bash
+kxm workflow export <run-id>
+kxm workflow export <run-id> --input snapshot.json
+```
+
+A retrospective holds the stage timeline, counts by category, area and class, open contradictions, decisions, and the last 500 redacted entries. Two fields drive review:
+
+- `recurringErrorClasses` counts `error` entries only, by evidence class.
+- `proposedImprovements` holds up to 12 of the run's error and lesson entries, merged and ranked like the signals above, each with a success measure that names its signal key.
+
+Runs with peer-evidence policies add a metadata-only `evidenceAudit`: configured and effective producer minimums, eligible producers, verified message and producer ids, request and reply hashes, and admin degradation approvals. It never copies message bodies, and its hashes are provenance, not proof that a peer was right. Every file stays `reviewDecision: "proposed"`; export never edits a workflow or weakens a gate.
+
+## Coded repeats (`kxm improve`)
+
+`kxm improve` (the same as `kxm improve report`) finds Runtime agent steps that a script, test or workflow `gate` could do as well as a model. It proposes; it never applies.
+
+```bash
+kxm improve report --dry-run
+```
+
+Expected output, in a directory that is not a KXM project:
+
+```text
+Sources:
+  telemetry /work/demo/.kxm/logs/telemetry.jsonl (exists=false, records=0, duplicatesDropped=0)
+Runtime store not read: no KXM project at /work/demo
+```
+
+### Sources
+
+Inside a KXM project the command reads the project's Runtime event store, `<state>/runtime/projects/<key>/run-events.db`, then `.kxm/logs/telemetry.jsonl`. The key comes from the checkout's real path, so each checkout and worktree has its own store. The store is opened read-only for one query; `kxm improve` never creates, writes or migrates it. A telemetry record whose `attemptId` the store already supplied is dropped. `--file <path>` reads only that file.
+
+The output starts with a `sources` block: each source's path, whether it exists, and its `records`, `skippedInvalid`, `excludedSimulated`, `undecided` and `duplicatesDropped` counts. An unreadable store stops the command with `improve_source_unreadable` and exit 1.
+
+### Groups and outcomes
+
+Records group by workflow, step, agent role and ask. The ask digest covers the workflow, step, step kind, agent, instructions, outcomes and required evidence keys, so one step keeps one digest across runs. No prompt text is read or stored.
+
+Outcomes are resolved from the event log when the report runs and never written back. A back edge is `blocked`; a producer error, an undeclared outcome or a failing terminal is `failed`; a later entry into the same step makes an attempt `reworked`; a completed run makes it `accepted`; a failed run makes it `failed`. Cancelled and still-running runs stay undecided and are left out of the pass rate. Simulated attempts are excluded and counted.
+
+### Candidacy
+
+A group becomes a coded-repeat candidate only when all three hold:
+
+- The same objective was decided in at least 2 runs (`askRecurrence`).
+- At least 0.75 of its decided attempts were accepted (`verifyPassRate`). An attempt superseded by a retry of the same step never counts as a pass.
+- Its step writes no repository (`writesRepository`).
+
+A group that passes the rate but misses reports `excludedReason`: `writes-repository` or `ask-not-repeated`. `weightedRecurrence` weighs each record by `2^(-age / improvement.telemetryHalfLifeDays)`, 14 days by default. It orders rows and never decides candidacy.
+
+### Outputs and promotion readiness
+
+Each candidate is a `kxm.candidate.v1` JSON file plus a proposed diff under `.kxm/candidates/` (or `--out-dir`), and the report is saved under `.kxm/assets/improvements/`. `--dry-run` writes neither. The step and role names pick the template: a verify, gate, test, check or lint step proposes a `.kxm/gates.yaml` command; a plan, review or repro step proposes a governed skill; any other step proposes a `kind: gate` step that runs `scripts/<step>.mjs`, which you write. Diffs contain placeholder hunks.
+
+`promotion[]` reports readiness under `improvement.promotionPolicy` (see [Configuration file reference](../reference/config-reference.md)):
+
+| Policy | Ready for review when |
+|---|---|
+| `manual_pr` (default) | Always; you review and apply the diff in a PR |
+| `critic_quorum` | Two distinct critic receipts are cited; `kxm improve` cites none, so never |
+| `auto_threshold` | Distinct runs, accepted share and mean recorded cost reach `improvement.autoThreshold`; a group with no recorded cost is never ready |
+
+No policy authorizes anything. Every policy ends at an operator PR, activation is a reviewed Git change for future runs, and telemetry cannot grant a tool or skip a gate.
+
+`kxm routing report` reads the same sources to compare verified completion, cost and rework per model route. Use it next to `kxm improve` when a repeat is also expensive. See [Harness routing](../reference/harness-routing.md).
+
+## Review cadence
+
+- **Per run.** Read the retrospective. Group contributing causes, then name an owner and a measurable success condition for each proposed improvement.
+- **Weekly.** Call `kxm_improvement_report` and `kxm improve report`. Check that each merge groups entries that belong together, and pick a few items to trial.
+- **Per release.** For each chosen improvement:
+  1. State the problem and link its evidence.
+  2. Name what it changes: harness, gates, implementation guidance, workflow, docs or security policy.
+  3. Define the expected outcome and a leading indicator.
+  4. Add or update tests before you change enforcement.
+  5. Trial it on a bounded workflow or repository.
+  6. Compare failure rate, cycle time, manual intervention and escaped defects with the baseline.
+  7. Adopt, revise or roll it back, and record the decision in a later run's journal.
+
+## Governance safeguards
+
+- Journal content is evidence, not executable policy.
+- Candidates are proposals. Readiness never authorizes, and no `improvement.*` value activates anything.
+- An agent may propose a gate change but cannot silently weaken a required gate.
+- A peer-quorum reduction must be declared by policy and approved by an administrator for the current attempt, and it is recorded as degraded, not as normal success.
+- Contradictions stay open until evidence resolves them; synthesis must not erase minority risks.
+- Changes to permissions, secrets, merge policy or external side effects need human or repository-authorized approval.
+- Reports are project-scoped. Protect the hub database: the journal can reveal sensitive engineering context.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `kxm_workflow_record` answers `workflow_not_found` | The id belongs to a `kxm run` Runtime run | Use `kxm improve` for Runtime learning |
+| `kxm improve` reads 0 records | Not inside a KXM project, no settled Runtime attempts, or only simulated drives | Check the `sources` block and `excludedSimulated` |
+| `kxm improve` exits 1 with `improve_source_unreadable` | The event store is locked or damaged | Retry, then inspect the path it names |
+| A signal merges unrelated entries | They share a summary shape or a class | Add distinct `class:<name>` evidence |
+| A recurring problem vanished from signals | Its runs were purged after 7 days, or its entry was decided | Export lessons to Git before the window closes |
+
+## Next steps
+
+- Promote a working procedure into a reusable skill: [Governed skills](governed-skills.md)
+- Keep durable lessons where agents read them: [Context and memory](context-and-memory.md)
+- Require independent evidence before a stage passes: [Provenance gates](provenance-gates.md)
+- Every flag and output key: [CLI reference](../reference/cli-reference.md)

package/docs/guides/governed-skills.md

@@ -0,0 +1,173 @@
+# Governed skills
+
+Turn a procedure that worked in a run into a reusable skill your agents can rely on, without letting run-time experience rewrite agent behavior on its own. You submit a candidate, record the results of four protected evaluations, and promote it through a reviewed pull request. Promoted skills are hash-pinned and immutable, and they inform agents but never grant a tool or a permission.
+
+This page covers the `kxm skills` lifecycle. The skills that ship with the plugin are a different thing; see [Agent skills](agent-skills.md).
+
+## Before you begin
+
+- The `kxm` CLI. Run the commands from the repository root: skills live in `.kxm/skills/` under `KXM_WORKDIR` or the current directory. No hub is needed.
+- At least one source for the candidate: a workflow run id, a journal entry id or an evidence receipt.
+- Two identities: the author who creates the candidate, and a different person who decides its promotion.
+
+## The lifecycle
+
+A candidate stays a candidate while evaluations are recorded, and leaves that state only by promotion, quarantine or rejection.
+
+```mermaid
+stateDiagram-v2
+  [*] --> candidate: kxm skills create
+  candidate --> candidate: record a static-review, sandbox,<br/>functional or safety result
+  candidate --> quarantined: functional or safety fails
+  candidate --> promoted: kxm skills promote<br/>(latest result of all four passed)
+  candidate --> rejected: kxm skills reject
+  quarantined --> [*]
+  rejected --> [*]
+  note right of promoted
+    Hash-pinned and immutable.
+    A behavior change is a new
+    candidate with --supersedes.
+  end note
+```
+
+Evaluations can be recorded in any order, and a later result for the same kind replaces the earlier one. A failed `static-review` or `sandbox` result leaves the candidate in place so you can fix and re-evaluate. A failed `functional` or `safety` result quarantines it at once.
+
+## Where skills live
+
+| Path under `.kxm/skills/` | Holds |
+|---|---|
+| `candidates/<id>/` | `SKILL.md` and `metadata.json` for each candidate |
+| `promoted/<id>/` | Copies of promoted candidates |
+| `quarantineds/<id>/` | Quarantined candidates (the code spells this directory name with a trailing `s`) |
+| `rejected/<id>/` | Rejected candidates |
+| `history/<id>.jsonl` | Append-only audit trail: creation, evaluations and decisions, the last 500 records |
+| `patches/<id>.patch` | The diff that promotion emits for review |
+
+Skill ids are content-addressed: `<slug>.<first 12 hex characters of the content hash>`. Changed behavior means changed content, which means a new id. Submitting identical content again is refused.
+
+## Create a candidate
+
+Write the procedure as a Markdown file. KXM adds `name` and `description` front matter when the file has none.
+
+`flaky.md`:
+
+```markdown
+# Triage a flaky test
+
+1. Re-run the failing test three times in isolation.
+2. Record each result as journal evidence.
+```
+
+```bash
+kxm skills create --file flaky.md --name "Triage flaky test" \
+  --description "Isolate and classify a flaky test before changing code" \
+  --created-by agent-a --harness pi --models openrouter/qwen/qwen3-coder-plus \
+  --journal journal_abc
+```
+
+Expected output:
+
+```text
+created skill candidate triage-flaky-test.7f0864c17a97
+```
+
+The candidate must cite at least one source (`--run`, `--journal` or `--receipt`), name its harness, and list 1 to 16 compatible models. Names are at most 64 characters and content at most 32,000. Secrets are redacted from the content and description before anything is written.
+
+## Record evaluations
+
+Each evaluation records a verdict that you or your evaluator produced. KXM does not run the skill, and it provides no sandbox; `sandbox` names the check you performed, it does not create one.
+
+```bash
+kxm skills evaluate triage-flaky-test.7f0864c17a97 --kind static-review --evaluator review-checklist-v1
+kxm skills evaluate triage-flaky-test.7f0864c17a97 --kind sandbox --evaluator scratch-repo-v1
+kxm skills evaluate triage-flaky-test.7f0864c17a97 --kind functional --evaluator flaky-suite-v2 --score 0.92
+kxm skills evaluate triage-flaky-test.7f0864c17a97 --kind safety --evaluator safety-review-v1
+```
+
+Add `--fail` to record a failure, and `--details` for up to 2,000 characters of redacted notes. A failed `functional` or `safety` evaluation prints `(candidate quarantined)` and records the quarantine decision under the evaluator's name. The `optimization` kind is refused: optimization evaluations are disabled and the CLI has no switch to enable them.
+
+## Promote through Git
+
+Promotion needs the latest result of all four kinds to be a pass, at least one durable evidence reference, a decider who is not the author, and content that still matches its hash. Preview it first:
+
+```bash
+kxm skills promote triage-flaky-test.7f0864c17a97 --decided-by reviewer-b --evidence review:pr-31 --dry-run
+```
+
+Expected output:
+
+```text
+dry run: promote skill triage-flaky-test.7f0864c17a97
+  would write /work/demo/.kxm/skills/promoted/triage-flaky-test.7f0864c17a97/SKILL.md
+  would write /work/demo/.kxm/skills/promoted/triage-flaky-test.7f0864c17a97/metadata.json
+  would write /work/demo/.kxm/skills/patches/triage-flaky-test.7f0864c17a97.patch
+  would write /work/demo/.kxm/skills/history/triage-flaky-test.7f0864c17a97.jsonl
+```
+
+Run it without `--dry-run`, then land the result through review:
+
+1. Open a pull request with the new `promoted/<id>/` directory. `patches/<id>.patch` is a new-file diff of exactly those two files, for reviewers who prefer a patch.
+2. Remove the candidate copy in the same pull request. Promotion copies the candidate; it does not move it, so `kxm skills list --state candidate` still shows it.
+3. Merge. From then on the skill is immutable.
+
+> [!IMPORTANT]
+> Promotion writes into your working tree immediately. A hub started from this checkout can serve the promoted skill in `kxm context get` packets as soon as the files exist and verify. Runtime agents receive it only after the files are committed and clean. See [Context for Runtime agents](context-and-memory.md#context-for-runtime-agents).
+
+## Reject a candidate
+
+```bash
+kxm skills reject bump-deps.489552361ce3 --decided-by reviewer-b --reason "Duplicates an existing gate"
+```
+
+Rejection moves the candidate to `rejected/` and keeps its history for future learning. It works on candidates only: a quarantined skill cannot be rejected from the CLI, so quarantine is terminal there. Remove a quarantined directory by pull request if you no longer want it.
+
+## Verify integrity
+
+`kxm skills verify` recomputes the content hash and checks that the front matter has a `name` and a `description`. It checks promoted skills by default; pass `--state` for another state.
+
+```bash
+kxm skills verify triage-flaky-test.7f0864c17a97
+```
+
+Expected output:
+
+```text
+skill triage-flaky-test.7f0864c17a97 integrity verified
+```
+
+An out-of-band edit fails with `content does not match its pinned hash; promoted skills are immutable and require a new candidate/eval cycle`. The hub and the Runtime run the same check. The hub leaves a failing skill out of packets; the Runtime leaves it out and records a `dispatch_context_skill_unverified:<id>` gap.
+
+## Supersede a promoted skill
+
+To change a promoted skill, create a new candidate from the edited content with `--supersedes <old-id>`, and take it through the whole lifecycle. The link is recorded in the new candidate's metadata and history. Nothing retires the old skill automatically: remove its `promoted/` directory in the pull request that adds the new one.
+
+## How promoted skills reach agents
+
+- **Hub packets.** Each promoted skill that verifies becomes a `skill` item at `instruction` authority and `verified` confidence. Its summary is `<name>: <description>` and its source is `skill:<id>@<sha256>`. Only roles that request the `skill` kind receive it, which by default means `implementer`.
+- **Runtime dispatch.** The same item, only when the promoted files are committed and clean, listed under **Active Skills** in the agent's prompt.
+- **What is delivered.** The name, description and pinned hash reference, not the full `SKILL.md` body.
+
+Skill text may shape behavior. It never grants a tool, a permission or an approval.
+
+## Other sources of candidates
+
+- A journal `skill-candidate` entry records that a procedure worked. Its own approval lifecycle is separate: approving the entry does not create a governed skill. See [Continuous improvement](continuous-improvement.md#governed-promotion-of-journal-entries).
+- `kxm improve` can propose a governed skill for a repeated planning, review or repro step. Its diff is a starting point; submit the result with `kxm skills create`.
+
+## Troubleshooting
+
+| Message | Cause | Fix |
+|---|---|---|
+| `a skill candidate must reference at least one source run, journal entry, or evidence receipt` | No `--run`, `--journal` or `--receipt` | Cite the run or entry the skill came from |
+| `identical candidate <id> already exists` | The same content was submitted before | Change the content, or use the existing id |
+| `promotion requires passing <kinds> evaluations` | A kind has no result, or its latest result failed | Record passing evaluations for the listed kinds |
+| `the author of a skill candidate cannot promote it` | `--decided-by` equals `--created-by` | Have a different person decide |
+| `skill <id> not found in candidate` | The skill is quarantined, rejected or already removed | Check `kxm skills list --state <state>` |
+| `optimization evaluations are disabled` | `--kind optimization` | Use one of the four protected kinds |
+
+## Next steps
+
+- See how skills sit beside memory and state in a packet: [Context and memory](context-and-memory.md)
+- Find which steps keep repeating: [Continuous improvement](continuous-improvement.md#coded-repeats-kxm-improve)
+- The skills that ship with KXM: [Agent skills](agent-skills.md)
+- Every flag: [CLI reference](../reference/cli-reference.md)

package/docs/guides/nous-providers.md

@@ -0,0 +1,186 @@
+# Nous providers
+
+Reach Nous Research models from Pi through one of three opt-in provider routes, and check that KXM will actually dispatch them before you depend on one. This page is for operators who run Pi agents and want Nous Portal, the Nous direct API, or a Hermes subscription proxy. None of these routes is a writer route, and none is enabled by default.
+
+Nous routes are Pi *providers*, not a separate harness: there is no Nous `kxm agent worker`, and Pi stays the only long-lived worker. See [Supervised Pi workers](pi-workers.md).
+
+## Before you begin
+
+- Pi installed. For the `nous/` and `nous-proxy/` routes, Pi must also load the KXM extension. See [Install](../start/install.md).
+- A Nous Portal subscription or a Nous API key.
+- For the proxy route only: the Hermes CLI, which you install and log in to yourself. KXM never installs it, logs in, starts the proxy, or makes paid requests for you.
+
+## Choose a route
+
+| Route | Model ids | Registered by | Authenticates with |
+|---|---|---|---|
+| Nous Portal | `nous-portal/<model>` | The third-party Pi package `@jayteelabs/pi-nous-portal-provider` | Pi `/login`, or `NOUS_API_KEY` |
+| Direct API | `nous/<model>` | The KXM Pi extension, when `KXM_NOUS_PROVIDERS` includes `direct` | `NOUS_API_KEY` only |
+| Hermes proxy | `nous-proxy/<model>` | The KXM Pi extension, when `KXM_NOUS_PROVIDERS` includes `proxy` | Your Hermes login, through a loopback proxy |
+
+The Portal route bills your Portal account, not OpenRouter. With `KXM_NOUS_PROVIDERS` unset, the KXM extension starts synchronously and offline: no fetch, no provider registration, no notice.
+
+## Set up Nous Portal
+
+1. Install the provider package into Pi:
+
+   ```bash
+   pi install npm:@jayteelabs/pi-nous-portal-provider
+   ```
+
+2. Log in. In Pi, run `/login`, choose subscription or API key, then Nous Research Portal. Alternatively, export `NOUS_API_KEY` in the shell or supervisor that starts Pi.
+
+   In Pi:
+
+   ```text
+   /login
+   ```
+
+3. Optionally override the endpoints. The package documents `NOUS_PORTAL_BASE_URL` (default `https://portal.nousresearch.com`) and `NOUS_INFERENCE_BASE_URL` (default `https://inference-api.nousresearch.com/v1`).
+
+## Verify the Portal route
+
+Check both that Pi lists the models and that Pi reports the provider ready. KXM trusts only the second check.
+
+```bash
+# Which Portal model ids does this install expose?
+pi --list-models nous-portal
+# Is the provider authenticated? KXM runs this same check before it dispatches.
+pi auth check --provider nous-portal --json
+```
+
+The route is usable only when `status` is `ready`. Model ids change: the reviewed experiment example is `nous-portal/tencent/hy4-preview`, and some installs list `tencent/hy3-preview` instead. Use the ids your install prints.
+
+> [!IMPORTANT]
+> In some installs `pi auth check --provider nous-portal` reports `provider_not_found` even though `pi --list-models` lists Portal models:
+>
+> `{"status":"not_ready","provider":"nous-portal","reason":"provider_not_found"}`
+>
+> KXM treats that answer as not authenticated. `kxm harness list` shows the Pi route as not authenticated, and the Runtime refuses to dispatch it. There is no override: fix the Pi install until the check reports `ready`.
+
+Run a Portal model interactively:
+
+```bash
+pi --model nous-portal/<model-id>
+```
+
+## Enable the direct API
+
+1. Export `NOUS_API_KEY` in the shell or supervisor that starts Pi. The direct route reads only this variable; it does not use credentials stored by Pi `/login`.
+2. Export `KXM_NOUS_PROVIDERS=direct`.
+3. Optionally point `KXM_NOUS_CATALOG_FILE` at a dated price pin. See [Pin a price catalog](#pin-a-price-catalog).
+4. Start Pi. Models appear as `nous/<id>` only when their capacity and verified numeric rates are known, from the live `/v1/models` catalog or from the pin.
+
+```bash
+export NOUS_API_KEY="replace-with-nous-api-key"
+export KXM_NOUS_PROVIDERS=direct
+pi --list-models nous/
+```
+
+## Enable the Hermes proxy
+
+1. Install Hermes if it is missing, then log in: `hermes login --provider nous`. Newer Hermes docs also mention `hermes setup --portal`; that flow is not verified on every CLI.
+2. Start the proxy with `hermes proxy start`, and check it with `hermes proxy status`. The default base URL is `http://127.0.0.1:8645/v1`.
+3. Export `KXM_NOUS_PROVIDERS=proxy`, or `direct,proxy` for both routes.
+4. Start Pi. Models appear as `nous-proxy/<id>`, with `subscription proxy, market ref` in their display name.
+
+If the proxy is down, the extension tells you to run `hermes proxy start`. If it answers unauthorized, the extension tells you to log in again.
+
+## Environment variables
+
+| Variable | Default | Effect |
+|---|---|---|
+| `KXM_NOUS_PROVIDERS` | unset (off) | Comma list of `direct` and `proxy`. An unknown token fails closed: nothing is registered |
+| `NOUS_API_KEY` | unset | API key for the direct route; also accepted by the Portal package |
+| `KXM_NOUS_PROXY_URL` | `http://127.0.0.1:8645/v1` | Proxy base URL. Must be loopback (`127.0.0.1`, `localhost` or `::1`) over `http` or `https`; anything else fails closed |
+| `KXM_NOUS_DISCOVERY_TIMEOUT_MS` | `5000` | Timeout for the `GET /v1/models` discovery request. Must be a positive number |
+| `KXM_NOUS_CATALOG_FILE` | unset | Path to a `kxm.nous-catalog.v1` price pin |
+| `KXM_NOUS_MODELS_URL` | Nous public catalog | Catalog URL that `kxm models refresh` reads for the model inventory |
+
+## Pin a price catalog
+
+A pin supplies capacity and rates when the live catalog is incomplete, so a model is registered with known prices instead of guessed ones.
+
+```json
+{
+  "schema": "kxm.nous-catalog.v1",
+  "recordedAt": "2026-09-20T00:00:00.000Z",
+  "source": "Nous Portal pricing page, checked by the operator",
+  "units": "usd_per_million_tokens",
+  "hash": "sha256:<64 hex characters>",
+  "models": {
+    "<model-id>": {
+      "contextWindow": 131072,
+      "maxTokens": 8192,
+      "cost": { "input": 0.8, "output": 2.4, "cacheRead": 0.08, "cacheWrite": 0.8 },
+      "priceBasis": "list",
+      "billing": "metered",
+      "verified": true
+    }
+  }
+}
+```
+
+`priceBasis` is `list` or `upper-bound`, and `billing` is `metered`, `subscription` or `subscription_plus_usage`. A model may add `tiers`, each with `inputTokensAbove` and its own four rates; the highest rate per component becomes the price, labelled as an upper bound. `hash` is the SHA-256 of the canonical JSON (sorted keys, no whitespace) of `recordedAt`, `source`, `units` and `models`. Compute it with Node:
+
+```bash
+node -e '
+const { createHash } = require("node:crypto");
+const pin = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
+const canon = (v) => v === null || typeof v !== "object" ? JSON.stringify(v)
+  : Array.isArray(v) ? `[${v.map(canon).join(",")}]`
+  : `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canon(v[k])}`).join(",")}}`;
+const { recordedAt, units, models } = pin;
+const source = pin.source.trim();
+console.log("sha256:" + createHash("sha256").update(canon({ recordedAt, source, units, models })).digest("hex"));
+' nous-pin.json
+```
+
+The whole pin is ignored when its hash does not match, its units are missing, it is dated in the future, it is older than 30 days, or any model entry is invalid. An unverified zero rate makes an entry invalid; verified zeros are allowed.
+
+## How prices are read
+
+From the public `GET https://inference-api.nousresearch.com/v1/models` catalog, KXM reads `context_length`, `top_provider.max_completion_tokens`, `architecture.input_modalities`, `supported_parameters` (`tools`, `reasoning`), and the `pricing.prompt`, `completion`, `input_cache_read` and `input_cache_write` per-token prices plus `pricing.overrides[]`. It converts them once to US dollars per million tokens. It never applies `pricing.original` or a blanket discount.
+
+Incomplete or malformed live rates exclude the model rather than drop a costly tier or guess zero, unless a matching pin supplies verified rates and capacity. Context tiers collapse to the highest rate per component, and that upper bound is what Pi's cost calculation sees, so a price never underquotes at a tier threshold. Upper-bound estimates are labelled in `nous/*` and `nous-proxy/*` display names.
+
+## What has been verified
+
+At the last compatibility check (2026-09-07), tests verified one streamed tool call with usage on `qwen/qwen3-coder-plus`, through both the direct API and an OAuth-backed Hermes proxy. Both reported usage.
+
+Still unknown or unverified:
+
+- How much included subscription quota a request consumes, and any extra billed amount.
+- Every other model, and automatic auth refresh.
+- Claude to Nous to Qwen: Nous documents native Messages support for `anthropic/*` only, and Qwen uses chat completions, so that path is unsupported.
+- A mocked bearer token proves header support, not that OAuth credentials are interchangeable.
+
+## Admission and routing rules
+
+A route that Pi can reach is not a route KXM will dispatch. Admission decides that, and it is a reviewed decision, not a configuration tweak.
+
+- **No Nous route is a writer.** `nous-portal/tencent/hy4-preview` is a reviewed read-only experiment example, not a writer. Any other `nous-portal` writer route needs its own reviewed admission.
+- **`nous/` and `nous-proxy/` carry no admission.** Registering them adds models to Pi's list; it grants no writer or router role, and the developer assignment helper does not allowlist them.
+- **Native vendors stay in their own harness.** The Portal also hosts `anthropic/…`, `openai/…`, `x-ai/…` and `google/…` models. Those vendors have native harnesses, so use those instead of the aggregator copy. The Pi native-vendor brake reads the vendor segment, so it refuses `nous-portal/anthropic/…`, `nous-portal/x-ai/…` and the same ids under `nous/` and `nous-proxy/`, at dispatch and when a worker starts; see [What the brake refuses](../reference/harness-routing.md#what-the-brake-refuses).
+- **Auth fails closed.** When `pi auth check` does not report `ready`, KXM refuses the route rather than billing another provider.
+- **The product Runtime dispatches only admitted selectors**, listed under `admitted` in `.kxm/routes.yaml` and, when a role file exists, in that role's roster.
+
+See [Harness routing](../reference/harness-routing.md#nous) for the full decision procedure.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| No `nous/` models appear | `KXM_NOUS_PROVIDERS` is unset, `NOUS_API_KEY` is unset, or no model has verified rates | Export both, or add a valid price pin |
+| Nothing registers and Pi shows an error | `KXM_NOUS_PROVIDERS` has an unknown token, or the discovery timeout is not a positive number | Use only `direct` and `proxy`, and fix the timeout |
+| No `nous-proxy/` models appear | The proxy is down, not logged in, or `KXM_NOUS_PROXY_URL` is not loopback | Run `hermes proxy status`, log in, and use a loopback URL |
+| A pinned model is still missing | The pin's hash, units or date failed, or one entry is invalid, such as an unverified zero rate | Fix the entry, recompute the hash, and refresh the pin within 30 days |
+| KXM refuses a `nous-portal` route that Pi lists | `pi auth check` does not report `ready` | See the `provider_not_found` note above |
+| A route is refused as not admitted | The selector is not in `.kxm/routes.yaml` or the role roster | Admission is a reviewed decision; see [Harness routing](../reference/harness-routing.md) |
+
+## Next steps
+
+- Pick a route for a model reachable more than one way: [Harness routing](../reference/harness-routing.md)
+- Run Pi agents under supervision: [Supervised Pi workers](pi-workers.md)
+- Refresh the model inventory: [`kxm models`](../reference/cli-reference.md#kxm-models)
+- All configuration layers and variables: [Configuration](../reference/configuration.md)