@kontextmind/kxm 0.7.125 → 0.7.127

package/docs/reference/cli-reference.md

@@ -100,7 +100,7 @@ kxm -V
 
 `--dry-run` changes nothing: no file is written, deleted, or moved, no request that changes hub or Runtime state is sent, no process is started, and no remote command runs. A command that cannot say what it would do without doing some of it refuses the flag instead of acting.
 
-- Plan with `planned`: `backup`, `restore`, `config set`, `role add|remove|modify|set-host|resume`, `workflow add|remove|modify`, `goal create`, `task create|run|sync`, `memory note|sync`, `skills evaluate|promote|reject`, `context promote`, `context wiki-compile --out`, `auth token`, `session token`, `session brief`, and `ssh run|file|close`. Each prints its normal result plus `dryRun: true` and `planned`, a list of `{action, target}` entries whose `action` is `write`, `delete`, `move`, `request`, or `ssh`. Text mode prints `dry run: <summary>` and one indented `would <action> <target>` line per entry (`session brief` appends `dry run: would write <file>` lines to the brief instead).
+- Plan with `planned`: `backup`, `restore`, `config set`, `role add|remove|modify|resume`, `workflow add|remove|modify`, `goal create`, `task create|run|sync`, `memory note|sync`, `skills evaluate|promote|reject`, `context promote`, `context wiki-compile --out`, `auth token`, `session token`, `session brief`, and `ssh run|file|close`. Each prints its normal result plus `dryRun: true` and `planned`, a list of `{action, target}` entries whose `action` is `write`, `delete`, `move`, `request`, or `ssh`. Text mode prints `dry run: <summary>` and one indented `would <action> <target>` line per entry (`session brief` appends `dry run: would write <file>` lines to the brief instead).
 - Plan in their own shape (described in each section): `init`, `run`, `runs drive|cancel`, `docs build|serve`, `runtime start|stop|sync-retry`, `hub start|stop|bind|unbind`, `session start|stop`, `agent worker`, `dash`, `studio serve`, `models inventory-refresh`, `routes admit|disable`, `update`, `completion install`, `workflow start|signal|export|checkpoint|record|wait`, every `peer` subcommand, `gate degrade|signal`, `skills create`, and `improve report`. `gate github watch --dry-run` still polls GitHub but does not post the signal.
 - Read-only commands run as usual, without leaving a trace: a local SQLite store is opened without creating `-wal` or `-shm` files, and `runs status|list|receipt` only attach to a running Runtime supervisor. With no supervisor running they exit 2 with `dry_run_unsupported` instead of starting one. `context wiki-compile --dry-run` still asks the hub to compile, which is a read.
 - Refused: `kxm models` (the interactive screen) and `kxm prices acknowledge` exit 2 with `dry_run_unsupported`. The CLI keeps one list of the commands that answer `--dry-run` and refuses every other command the same way before it runs, so a command added without dry-run support fails closed.
@@ -142,10 +142,10 @@ Exit 2 covers an unknown command or option, a missing argument or required optio
 
 | Location | Contents | Used by |
 |---|---|---|
-| Project files under `<project>/.kxm/` (reviewed in Git) | `project.yaml`, `agents/`, `workflows/`, `gates.yaml`, `repo/`, `template-provenance.yaml`, `routes.yaml`, `models/inventory.yaml`, `roles/`, `role-hosts.yaml`, `modes.yaml`, `prices.yaml` | `init`, `trust`, `run`, `models`, `routes`, `role`, `workflow definitions\|add\|remove\|modify`, `explain`, `studio` |
+| Project files under `<project>/.kxm/` (reviewed in Git) | `project.yaml`, `agents/`, `workflows/`, `gates.yaml`, `repo/`, `template-provenance.yaml`, `routes.yaml`, `models/inventory.yaml`, `roles/`, `roles`, `modes.yaml`, `prices.yaml` | `init`, `trust`, `run`, `models`, `routes`, `role`, `workflow definitions\|add\|remove\|modify`, `explain`, `studio` |
 | Local project records under `<project>/.kxm/` | `config.yaml` (project scope), `goals/`, `tasks/`, `memory/`, `skills/`, `candidates/`, `backups/`, `run/ssh-sockets/` | `config`, `goal`, `task`, `memory`, `skills`, `improve`, `backup`, `ssh` |
 | Workspace directories (`.kxm/state`, `.kxm/logs`, `.kxm/assets`, `.kxm/config`; moved by `--workspace` or `KXM_*_DIR`) | hub SQLite store `state/kxm.db` (or `KXM_DATA_PATH`), `state/hub.pid`, `state/session-brief.json`, `state/lanes.json` (mode 0600 lane records), `logs/telemetry.jsonl`, `logs/kxm-hub.jsonl`, `assets/sessions/`, `assets/workflows/`, `assets/improvements/`, `assets/retrospectives/`, legacy `config/agents.json` and `config/gates.json` | `hub`, `session`, `dash`, `lane`, `agent worker`, `workflow list\|get\|export`, `gate`, `improve`, `routing report` |
-| User config directory (`KXM_USER_CONFIG_DIR`, default `~/.config/kxm`) | `config.yaml` (user scope), `session.token`, global `roles/` and `workflows/`, `role-hosts.yaml`, `completions/` | `config --scope user`, `auth token`, `session brief\|token`, `role`/`workflow` with `--scope global`, `studio serve`, `completion install` |
+| User config directory (`KXM_USER_CONFIG_DIR`, default `~/.config/kxm`) | `config.yaml` (user scope), `session.token`, global `roles/` and `workflows/`, `roles`, `completions/` | `config --scope user`, `auth token`, `session brief\|token`, `role`/`workflow` with `--scope global`, `studio serve`, `completion install` |
 | User state root (`KXM_STATE_HOME`; macOS `~/Library/Application Support/KXM`; Linux `$XDG_STATE_HOME/kxm` or `~/.local/state/kxm`; Windows `%LOCALAPPDATA%\KXM`) | `hub-env.json` (persisted hub credentials), `hub-binding.json`, `runtime/` (Runtime supervisor registry and per-project run stores), `update.yaml`, repository bindings | `hub start\|bind\|unbind`, every hub client, `run`, `runs`, `runtime`, `tenant status`, `update`, `init --repository`, and (read-only, the project's run store) `improve` and `routing report` |
 
 `init`, `trust`, `run`, `runs`, `docs build`, `docs serve`, `runtime sync-retry`, `tenant status`, and `studio layout` find the project root by walking up from the current directory. `improve` and `routing report` use the current directory's Git root when it holds `.kxm/project.yaml`, to find the project's Runtime run store (and, for `improve`, its configuration and default candidate directory). `config`, `role`, `workflow definitions|add|remove|modify`, `goal`, `task`, `memory`, `skills`, `backup`, `restore`, `studio serve`, and `ssh` (socket directory) use `.kxm` in the current directory. Run those from the project root.
@@ -1023,7 +1023,7 @@ Opens an interactive screen over `.kxm/models/inventory.yaml` that shows each mo
 
 - Needs an interactive terminal. With `--json` or without a TTY it exits 2 with `interactive_tty_required`.
 - `r` and `x` also mark the model `admitted` in `.kxm/routes.yaml`. So `x` re-admits a disabled route while it removes the role binding, and `r` admits the route as well as binding it.
-- `r` writes a roster entry `{model: <inventory id>, enabled: true}` with no harness, creating the role file if needed. The inventory id is often a bare model (`grok-4.6`), which the Runtime's roster check does not match against an agent's `provider/model`; edit the entry to the full selector.
+- `r` binds the role only when a `kxm.model.v2` file matches the inventory id (`model`, or `vendor/model`). It appends `{route: <route-id>}` and creates a v2 role file when the role is new. A selector with no matching model file is refused with `unknown route` before either file is written. `kxm models` does not write a v1 roster entry.
 
 ```bash
 kxm models --json
@@ -1151,7 +1151,9 @@ kxm routes disable --dry-run --json
 
 ## `kxm role`
 
-Manages role definitions (`kxm.role.v1`) and role-seat host bindings (`kxm.role-hosts.v1`). Local scope is `.kxm/roles/` and `.kxm/role-hosts.yaml` in the current directory; global scope is `<KXM_USER_CONFIG_DIR>/roles/` and `<KXM_USER_CONFIG_DIR>/role-hosts.yaml`. A local role with the same ID overrides a global one. `kxm role` with no subcommand runs `role list`. For `--pick` without a value on a non-interactive shell, set `KXM_PICK_SELECT` to an index or ID. Errors from this group are plain text on stderr, even with `--json`.
+Manages role definitions (`kxm.role.v2`). A role file is `.kxm/roles/<role>.yaml` in the project, or `<KXM_USER_CONFIG_DIR>/roles/<role>.yaml` for global scope. A local role with the same ID overrides a global one. `kxm role` with no subcommand runs `role list`. For `--pick` without a value on a non-interactive shell, set `KXM_PICK_SELECT` to an index or ID. Errors from this group are plain text on stderr, even with `--json`.
+
+A roster entry is `{route, effort, mode}`. `route` names `.kxm/models/<route-id>.yaml`. The first entry is the primary route. `kxm role add --route` writes that roster. `kxm role modify --add-route` and `--remove-route` change it.
 
 ### `kxm role list`
 
@@ -1193,35 +1195,32 @@ Prints a role definition as YAML.
 kxm role get writer --scope local
 ```
 
-Not run with a configured role; in a fresh project it exits 1 with `kxm: role 'writer' not found`.
+In a fresh project this exits 1 with `kxm: role 'writer' not found`. This checkout's writer is the `kxm role get writer --json` example under [`kxm role modify`](#kxm-role-modify).
 
 ### `kxm role add`
 
 ```text
-kxm role add [roleId] [--file <path>] [--description <text>] [--skills <skills>] [--harness <harness>] [--model <model>] [--scope global|local] [--overwrite] [--pick [selection]]
+kxm role add [roleId] [--file <path>] [--description <text>] [--skills <skills>] [--route <route-id>] [--scope global|local] [--overwrite] [--pick [selection]]
 ```
 
-Adds a role definition. Without a role ID, or with `--pick`, you choose from the built-in templates (`writer`, `planner`, `critic-arch`, `critic-cli`, `verifier`) and, for local scope, existing global roles; a global role with a template's ID is not offered. The choice is written under its own ID with its content: the template, or a copy of the global role's file, with `--description`, `--skills`, and `--model` (with `--harness`) replacing its description, skills, and roster. With `--file`, the YAML file is used and its `id` is replaced by the role ID. Otherwise a role with only the given options is written.
+Adds a role definition. Without a role ID, or with `--pick`, local scope offers existing global roles. The choice is written under its own ID: a copy of the global role file, with `--description`, `--skills`, and `--route` replacing its description, skills, and roster. Repeat `--route`. The first id is the primary roster entry. With `--file`, the YAML file is used and its `id` is replaced by the role ID. `--route` does not replace the file's roster. Otherwise a role with only the given options is written.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--file` | `<path>` | none | Path to YAML role definition file |
 | `--description` | `<text>` | `Role <id>` | Role description |
 | `--skills` | `<skills>` | none | Comma-separated skills list |
-| `--harness` | `<harness>` | `pi` when `--model` is set | Primary harness name (e.g. grok, claude, agy, pi) |
-| `--model` | `<model>` | none | Primary model identifier (e.g. grok-4.6, fable, gemini-3.8-flash-high) |
+| `--route` | `<route-id>` | none | Route id under `.kxm/models/`. Repeatable. The first id is primary |
 | `--scope` | `<scope>` | `local` | Configuration scope: global or local (default: local) |
 | `--overwrite` | none | off | Overwrite existing role definition if present |
-| `--pick` | `[selection]` | none | Pick from available role templates (index or id) |
+| `--pick` | `[selection]` | none | Pick a global role to copy (index or id) |
 
-- Writes `<scope dir>/roles/<id>.yaml`. `--dry-run` plans the write and writes nothing.
-- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/roles/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new role in place of any file of that ID. The loader reads only `writer.yaml`, whose enabled roster must include the `implementer` agent's model (see [Roles](config-reference.md#kxmrolesroleyaml-kxmrolev1)). If the project would not load, the command refuses with `role_invalid`, lists each issue and writes nothing, also under `--dry-run`, and `--overwrite` replaces a `writer.yaml` the loader refuses. Global scope is not checked, because no loader reads it.
-- Refusals exit 2 and honor `--json`: `project_not_found` and `role_invalid` (with `issues`, each `{phase, code, file, message}`). An existing role without `--overwrite` exits 1 with a plain `role add failed: role_already_exists: ...` line, also under `--dry-run`.
+- Writes `.kxm/roles/<id>.yaml` in local scope, or `<KXM_USER_CONFIG_DIR>/roles/<id>.yaml` in global scope. `--dry-run` plans the write and writes nothing.
+- Each `--route` is checked the same way as `kxm role modify --add-route`. If `.kxm/models/<route-id>.yaml` is missing, the command exits 1 and writes `kxm: route '<route-id>' is not a file under .kxm/models/` to stderr. It does not write the role file, including under `--dry-run`. `--file` checks every `roster[].route` the same way before writing, in local scope and in global scope.
+- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/roles/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new role in place of any file of that ID. The loader reads only `writer.yaml`, whose roster must name a route whose model is the `implementer` agent's model (see [Roles](config-reference.md#kxmrolesroleyaml-kxmrolev2)). If the project would not load, the command refuses with `role_invalid`, lists each issue and writes nothing, also under `--dry-run`, and `--overwrite` replaces a `writer.yaml` the loader refuses. Global scope is not checked, because no loader reads it.
+- Refusals exit 2 and honor `--json`: `project_not_found` and `role_invalid` (with `issues`, each `{phase, code, file, message}`). A missing `--route` file, and an existing role without `--overwrite`, exit 1 with a plain stderr line, also under `--dry-run` (`kxm: route '<route-id>' is not a file under .kxm/models/`, or `role add failed: role_already_exists: ...`).
 - JSON keys: `roleId`, `id`, `filePath`, `scope`.
 
-> [!WARNING]
-> Most built-in template entries, and `--model` as you type it, are bare model IDs such as `grok-4.6`, `fable`, and `gemini-2.5-pro`. The Runtime's roster check needs the agent's full `provider/model` selector, so a live attempt under a local `writer.yaml` copied from the template is refused (`producer_route_unsupported: … not in role 'writer' roster`). Write `--model xai/grok-4.6`, or edit the entries to full selectors, before you drive live runs.
-
 ```bash
 kxm role add demo-role --description "Demo role" --dry-run --json
 ```
@@ -1230,14 +1229,14 @@ kxm role add demo-role --description "Demo role" --dry-run --json
 {"schema":"kxm.cli-result.v1","ok":true,"command":"role add","roleId":"demo-role","id":"demo-role","filePath":"/work/proj/.kxm/roles/demo-role.yaml","scope":"local","dryRun":true,"planned":[{"action":"write","target":"/work/proj/.kxm/roles/demo-role.yaml"}]}
 ```
 
-Add a reviewer role with a Claude model, and copy a built-in template into global scope (Not run):
+Add a reviewer whose primary route is `fable-claude`, with `grok-native` second (Not run):
 
 ```bash
-kxm role add reviewer --description "Independent reviewer" --harness claude --model fable --skills kxm
+kxm role add reviewer --description "Independent reviewer" --route fable-claude --route grok-native --skills kxm
 ```
 
 ```bash
-kxm role add --pick critic-arch --scope global
+kxm role add --pick reviewer --scope local
 ```
 
 ### `kxm role remove`
@@ -1267,88 +1266,46 @@ kxm role remove demo-role --dry-run --json
 ### `kxm role modify`
 
 ```text
-kxm role modify [roleId] [--description <text>] [--add-skill <skill>] [--remove-skill <skill>] [--add-model <harness:model>] [--remove-model <model>] [--scope global|local] [--pick [selection]]
+kxm role modify [roleId] [--description <text>] [--add-skill <skill>] [--remove-skill <skill>] [--add-route <route-id>] [--remove-route <route-id>] [--scope global|local] [--pick [selection]]
 ```
 
-Updates an existing role's description, skills, or model roster and rewrites its file.
+Updates an existing role's description, skills, or route roster and rewrites its file.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--description` | `<text>` | unchanged | Updated description |
 | `--add-skill` | `<skill>` | none | Skill to add |
 | `--remove-skill` | `<skill>` | none | Skill to remove |
-| `--add-model` | `<harness:model>` | none | Model to add to roster |
-| `--remove-model` | `<model>` | none | Model to remove from roster |
+| `--add-route` | `<route-id>` | none | Route id to add. Must be `.kxm/models/<route-id>.yaml` |
+| `--remove-route` | `<route-id>` | none | Route id to remove from the roster |
 | `--scope` | `<scope>` | first match | Configuration scope: global or local |
 | `--pick` | `[selection]` | none | Pick a role to modify (index or id) |
 
-- `--add-model` without a colon uses harness `pi`. `--dry-run` returns the modified role and plans the write without making it.
+- `--add-route` checks that `.kxm/models/<route-id>.yaml` exists in the project. If it does not, the command exits 1 and writes `kxm: route '<route-id>' is not a file under .kxm/models/` to stderr. It does not write the role file. `--remove-route` drops a roster entry by id and does not require the model file. `--dry-run` returns the modified role and plans the write without making it, after the same existence check.
 - JSON keys: `roleId`, `id`, `role`, `filePath`, `scope`.
 
 ```bash
-kxm role modify demo-role --add-skill kxm --dry-run --json
-```
-
-```text
-{"schema":"kxm.cli-result.v1","ok":true,"command":"role modify","roleId":"demo-role","id":"demo-role","role":{"schema":"kxm.role.v1","id":"demo-role","description":"Demo role","skills":["kxm"],"roster":[]},"filePath":"/work/proj/.kxm/roles/demo-role.yaml","scope":"local","dryRun":true,"planned":[{"action":"write","target":"/work/proj/.kxm/roles/demo-role.yaml"}]}
-```
-
-Add a Claude model to a role's roster (Not run):
-
-```bash
-kxm role modify reviewer --add-model claude:fable --add-skill kxm-peer
+kxm role get writer --json
 ```
 
-### `kxm role hosts`
-
 ```text
-kxm role hosts [--scope all|global|local]
+{"schema":"kxm.cli-result.v1","ok":true,"command":"role get","roleId":"writer","scope":"local","filePath":"/work/kxm/.kxm/roles/writer.yaml","role":{"schema":"kxm.role.v2","id":"writer","purpose":"writer","permission":"edit","description":"Primary implementation agent.","skills":[],"roster":[{"route":"grok-native","effort":"medium"},{"route":"qwen-openrouter-pi","effort":"medium"},{"route":"gemini-agy"}]}}
 ```
 
-Lists role seats (`critic-arch`, `critic-cli`, `planner`, `verifier`, `writer`, plus any configured seat) and the host, model, and effort each resolves to, with the source of the decision (`override`, `role-hosts`, `seat-default`, `role-roster`, or `fallback`). The listing is display-only: no dispatch path reads seats or `role-hosts.yaml`, so a run's harness and model still come from the agent file.
-
-| Option | Argument | Default | Description |
-|---|---|---|---|
-| `--scope` | `<scope>` | `all` | Filter by scope: all, global, or local |
-
-- Reads only. JSON keys: `scope`, `filePath`, `seats` (`seatId`, `host`, `model`, `provider`, `effort`, `source`, `configuredHost`, `configuredModel`), `hostProviders`.
+Captured from this checkout with `node scripts/kxm.mjs role get writer --json`. The path is shortened to `/work/kxm`.
 
 ```bash
-kxm role hosts
+kxm role modify writer --add-skill kxm --dry-run --json
 ```
 
 ```text
-ROLE SEATS (default):
-  critic-arch      -> host: pi            [anthropic/claude-fable-5.1]  (via seat-default)
-  critic-cli       -> host: pi            [openai/gpt-5.6-sol]          (via seat-default)
-  planner          -> host: pi            [anthropic/claude-fable-5.1]  (via seat-default)
-  verifier         -> host: pi            [evaluator]                   (via seat-default)
-  writer           -> host: grok          [x-ai/grok-4.6]               (via seat-default)
+{"schema":"kxm.cli-result.v1","ok":true,"command":"role modify","roleId":"writer","id":"writer","role":{"schema":"kxm.role.v2","id":"writer","purpose":"writer","permission":"edit","description":"Primary implementation agent.","skills":["kxm"],"roster":[{"route":"grok-native","effort":"medium"},{"route":"qwen-openrouter-pi","effort":"medium"},{"route":"gemini-agy"}]},"filePath":"/work/kxm/.kxm/roles/writer.yaml","scope":"local","dryRun":true,"planned":[{"action":"write","target":"/work/kxm/.kxm/roles/writer.yaml"}]}
 ```
 
-### `kxm role set-host`
-
-```text
-kxm role set-host <seatId> <host> [--model <model>] [--effort low|medium|high|xhigh] [--scope global|local]
-```
-
-Binds a role seat to a host in `role-hosts.yaml`. The binding changes what `kxm role hosts` shows, not what runs.
-
-| Option | Argument | Default | Description |
-|---|---|---|---|
-| `--model` | `<model>` | none | Model identifier for this seat |
-| `--effort` | `<effort>` | none | Effort level: low, medium, high, xhigh |
-| `--scope` | `<scope>` | `local` | Configuration scope: global or local (default: local) |
-
-- Writes `.kxm/role-hosts.yaml` (or the global file). `--dry-run` plans the write and writes nothing.
-- JSON keys: `seatId`, `host`, `binding`, `filePath`, `scope`.
+Add an existing route to a role's roster (Not run):
 
 ```bash
-kxm role set-host writer claude --model fable --effort high --dry-run --json
-```
-
-```text
-{"schema":"kxm.cli-result.v1","ok":true,"command":"role set-host","seatId":"writer","host":"claude","binding":{"host":"claude","model":"fable","effort":"high"},"filePath":"/work/proj/.kxm/role-hosts.yaml","scope":"local","dryRun":true,"planned":[{"action":"write","target":"/work/proj/.kxm/role-hosts.yaml"}]}
+kxm role modify reviewer --add-route fable-claude --add-skill kxm-peer
 ```
 
 ### `kxm role resume`

package/docs/reference/config-reference.md

@@ -26,11 +26,10 @@ Related pages:
 | `.kxm/repo/repo.yaml` (in each repository) | `kxm.repository.v1` | Per-repository definition | You; `kxm init` creates the control one | Yes, in the repository it describes |
 | `.kxm/project/env.yaml`, `.kxm/repo/env.yaml` | `kxm.environment.v1` | Portable, non-secret environment | You | Yes |
 | `.kxm/agents/<id>.yaml` | `kxm.agent.v1` | Agent harness, model, and permission ceilings | You; `kxm init` creates two | Yes |
-| `.kxm/models/<id>.yaml` | `kxm.model.v1` | Named model profiles for selectors | You | Yes |
+| `.kxm/models/<id>.yaml` | `kxm.model.v2` | One model route (harness, vendor, status, permissions) | You; `kxm init` | Yes |
 | `.kxm/workflows/<id>.yaml` | `kxm.workflow.v1` | Ordered steps and typed transitions | You; `kxm init` creates `default` | Yes |
 | `.kxm/gates.yaml` | `kxm.gate-registry.v1` | The executable gate registry | You; `kxm init` creates it | Yes |
-| `.kxm/roles/<role>.yaml` | `kxm.role.v1` | Model rosters per role | You, `kxm role`, `kxm models` | Yes |
-| `.kxm/role-hosts.yaml` | `kxm.role-hosts.v1` | Role seat to host bindings (display only) | `kxm role set-host` | Yes, unless you ignore it |
+| `.kxm/roles/<role>.yaml` | `kxm.role.v2` | Model rosters per role | You, `kxm role`, `kxm models` | Yes |
 | `.kxm/routes.yaml` | `kxm.routes.v2` | Admitted and disabled model routes | You, `kxm routes`, `kxm models` | Yes |
 | `.kxm/roster.yaml` | `kxm.developer-roster.v1` | Developer assignment roster for the KXM source repository | Maintainers | Yes, and it must be committed |
 | `.kxm/prices.yaml` | `kxm.prices.v1` | Dated, hash-pinned list prices | You | Yes |
@@ -86,7 +85,7 @@ Cost accounting:
 | Revisions pinned on every run | `configRevision` (the bundle), memory revision (`.kxm/memory` without `candidates/`, plus `.kxm/skills/promoted`), executor policy, tool policy (agent and step `tools` plus the gate registry) | `kxm run` |
 
 Nothing validates `routes.yaml`, `roles/` (other than `writer.yaml`),
-`role-hosts.yaml`, `roster.yaml`, `prices.yaml`, `inventory.yaml`,
+`roles`, `roster.yaml`, `prices.yaml`, `inventory.yaml`,
 `config.yaml`, `modes.yaml`, memory, tasks, goals, or webhook JSON during
 `kxm init`. Their own readers report problems when they run. None of them are
 part of `configRevision`, and `kxm trust check` does not see them: a change to
@@ -454,7 +453,7 @@ Error codes: `executor_unknown`, `harness_unknown`, `tool_preset_unknown`,
 `model_tag_unresolved`, `harness_unhosted_model`,
 `pi_native_impersonation_blocked`, the path codes under
 [Rules shared by the project bundle](#rules-shared-by-the-project-bundle), and
-`role_roster_conflicts_with_agent` (see [Roles](#kxmrolesroleyaml-kxmrolev1)).
+`role_roster_conflicts_with_agent` (see [Roles](#kxmrolesroleyaml-kxmrolev2)).
 
 Commands: `kxm init` creates `coordinator` (`claude`, `anthropic/fable`) and
 `implementer` (`grok`, `xai/grok-4.6`) and admits both selectors in
@@ -464,47 +463,48 @@ selectors too, but skips Google guide candidates because the Runtime cannot
 reach the `antigravity` Pi provider yet; `kxm run` and the Runtime read them;
 `kxm trust` diffs them.
 
-## `.kxm/models/<id>.yaml` (`kxm.model.v1`)
+## `.kxm/models/<id>.yaml` (`kxm.model.v2`)
 
-Named model profiles that agent and step selectors can reference by `profile`
-or `tag`. The filename is the profile ID; `inventory.yaml` in the same
-directory is reserved for the generated inventory and is skipped by this
-loader.
+One model route. The filename is the route id (`inventory.yaml` in the same
+directory is the generated catalog and is skipped). `kxm config` validation
+checks the file against `schemas/model.schema.json`. `origin` is required when
+`harness` is `pi` and optional otherwise. When `origin` is present, `source`
+is a project-relative evidence file and `sha256` is the SHA-256 of that file's
+bytes.
 
 | Field | Type and allowed values | Required, default | What reads it |
 |---|---|---|---|
-| `schema` | `kxm.model.v1` | Required | Loader |
-| `provider` | Identifier | Required | Loader: selector resolution, harness pairing, provider diversity |
-| `model` | String, 1 to 200 characters | Required | Loader: same |
-| `thinking` | String, 1 to 64 characters | Optional | Not read by any code path yet |
-| `tags` | Unique identifiers, at most 32 | Optional | Loader: `tag` selectors |
-| `capabilities` | Unique identifiers, at most 32 | Optional | Loader: `tag` selectors with `capabilities` |
-| `priority` | Integer, -10,000 to 10,000 | Optional | Not read by any code path yet |
-| `fallbacks` | Up to 8 selectors | Optional | Loader checks references (`model_profile_unknown`, `model_tag_unresolved`) and cycles (`model_fallback_cycle`); nothing fails over yet |
-| `limits.contextTokens`, `limits.outputTokens` | Integer, at least 1 | Optional | Not read by any code path yet |
-| `limits.timeoutMs` | Integer, 0 to 31,536,000,000 | Optional | Not read by any code path yet |
-
-Profiles are load-time data only. The Runtime's live route resolution reads
-the agent file directly and does not consult profiles.
+| `schema` | `kxm.model.v2` | Required | Loader |
+| `id` | Kebab identifier, 1 to 64 characters | Optional; the filename is the id | Loader |
+| `harness` | Identifier, 1 to 64 characters | Required | Developer ceilings and dispatch membership |
+| `model` | String, 1 to 200 characters | Required | Dispatch membership (`model`, `vendor/model`, `harness/model`) |
+| `vendor` | String, 1 to 64 characters | Required | The lab that trained the model, not the biller |
+| `status` | `admitted`, `candidate`, or `retired` | Required | A role roster may use only `admitted` |
+| `permissions` | One or two of `edit`, `read-only` | Required | Must stay inside the harness ceiling |
+| `origin.source` | String, 1 to 512 characters | Required with `origin.sha256` when `origin` is set; required for `harness: pi` | Evidence path |
+| `origin.sha256` | 64 hex characters | Required with `origin.source` | Must match the evidence file |
+| `thinking` | String, 1 to 64 characters | Optional | Recorded on the route |
+| `tags`, `capabilities` | Unique identifiers, at most 32 | Optional | Selector tags |
+| `priority` | Integer, -10,000 to 10,000 | Optional | Recorded on the route |
+| `fallbacks` | Up to 8 `profile`, `tag`, or `provider`+`model` objects | Optional | Reference check |
+| `limits.contextTokens`, `limits.outputTokens` | Integer, at least 1 | Optional | Recorded on the route |
+| `limits.timeoutMs` | Integer, 0 to 31,536,000,000 | Optional | Recorded on the route |
 
 ```yaml
-# .kxm/models/critic-claude.yaml — the filename is the profile id.
-schema: kxm.model.v1
-provider: anthropic
-model: fable
-thinking: high
-tags: [critic]
-capabilities: [tools, structured-output]
-priority: 100
-fallbacks:
-  - profile: critic-sol
-limits:
-  contextTokens: 200000
-  outputTokens: 32000
-  timeoutMs: 1800000
+schema: kxm.model.v2
+id: grok-native
+harness: grok
+model: grok-4.7
+vendor: xai
+status: admitted
+permissions:
+  - edit
+origin:
+  source: .kxm/roster.yaml
+  sha256: b2bd628604e8fec5afdff2a1f2c104ed14ff785686bb1f38272bc972a310c806
 ```
 
-Commands: the loader in `kxm init`, `kxm run`, and `kxm trust`.
+Commands: `kxm init`, `kxm run`, and `kxm trust` load these files. `kxm role modify --add-route` refuses a route id that has no file here (exit 1). Dispatch membership for a role reads `harness`, `model`, and `vendor`. The developer assignment runner still reads `.kxm/roster.yaml` until P2.
 
 ## `.kxm/workflows/<id>.yaml` (`kxm.workflow.v1`)
 
@@ -957,98 +957,63 @@ policy revision pinned on each run. `kxm gate artifacts-exist --path <file>` is
 separate CLI check against the workspace assets directory (`KXM_ASSETS_DIR`),
 not this registry.
 
-## `.kxm/roles/<role>.yaml` (`kxm.role.v1`)
-
-Role files hold model rosters. Three different readers use them, and they
-read different fields:
-
-| Reader | File | Fields it reads | Effect |
-|---|---|---|---|
-| Project loader (`validateBundle`) | `.kxm/roles/writer.yaml` only | `roster[].model`, `roster[].enabled` | Cross-checks the writer roster against the `implementer` agent's model (see below). Parsed as restricted YAML. |
-| Runtime route check (`listRoleBindings` in `plugins/kxm/src/routes.ts`) | `.kxm/roles/<role>.yaml`, role = agent ID, `writer` for `implementer` | `roster[].model` | The agent's `provider/model` must appear exactly. `enabled` is ignored, so a disabled entry still admits. The role name comes from the filename. |
-| `kxm role` commands (`plugins/kxm/src/role.ts`) | `.kxm/roles/*.yaml` and `~/.config/kxm/roles/*.yaml` | Everything below | Listing and editing only. A file without `schema: kxm.role.v1` is silently skipped. A local file overrides a global one with the same ID. A local `kxm role add` runs the project loader check above first and refuses with `role_invalid` a role the loader would reject. |
+## `.kxm/roles/<role>.yaml` (`kxm.role.v2`)
 
-The loader check applies when the agent `implementer` (or else `writer`)
-declares a model and the roster has at least one enabled entry. One enabled
-entry must then equal `provider/model`, equal the bare model, or end with
-`/<model>`; otherwise the load fails with `role_roster_conflicts_with_agent`.
+One role. The filename is the role id. `kxm config` validation checks the file
+against `schemas/role.schema.json`.
 
-Write roster models as the full `provider/model` string. `kxm role add --model
-grok-4.6` writes a bare model ID, which satisfies the loader check but not the
-Runtime route check. `kxm role modify <role> --add-model grok:xai/grok-4.6`
-writes the full form.
+`listRoleBindings` reads `roster[].route`. Dispatch treats `implementer` as
+`writer` and requires the agent selector to be one of the selectors named by
+those route files (`model`, `vendor/model`, or `harness/model`). The writer
+cross-check (`role_roster_conflicts_with_agent`) does the same comparison
+against the `implementer` agent's model, or the `writer` agent when there is
+no implementer. `kxm role` reads and writes these files. A file without
+`schema: kxm.role.v2` is skipped by `kxm role`. A local file overrides a
+global one with the same id.
 
 | Field | Type | Required, default | What reads it |
 |---|---|---|---|
-| `schema` | `kxm.role.v1` | Required by `kxm role` | `kxm role` commands |
-| `id` | String | Optional, the filename | `kxm role` commands; the loader and Runtime use the filename |
-| `description` | String | Optional | `kxm role` commands |
-| `roster[].model` | String, `provider/model` | Required per entry | Loader (writer only), Runtime route check |
-| `roster[].enabled` | Boolean | Optional, `true` | Loader writer check only |
-| `roster[].harness` | String | Optional | `kxm role list` and `kxm role hosts` display |
-| `roster[].provider` | String | Optional | `kxm role hosts` display |
-| `roster[].effort` | `low`, `medium`, `high`, or `xhigh` | Optional | `kxm role hosts` display; not passed to any producer |
-| `roster[].mode` | `headless`, `interactive`, or `either` | Optional | Not read by any code path yet |
-| `skills`, `tools`, `produces`, `consumes`, `policy` | See `schemas/role.schema.json` | Optional | Stored and shown by `kxm role`; not read by any code path yet |
-
-Roster order is priority by convention, and `kxm role list` shows the first
-entry as the primary. No code path fails over along the roster yet: the
-Runtime only checks membership, and the model comes from the agent file.
-
-`schemas/role.schema.json` describes a stricter shape (required
-`description`, required `harness` per entry, `model` as a selector object, no
-`enabled`). No loader enforces it, and the role files the Runtime reads do not
-follow it.
+| `schema` | `kxm.role.v2` | Required | Loader and `kxm role` |
+| `purpose` | `writer`, `planner`, `reviewer-arch`, `reviewer-cli`, or `experiment` | Required | Developer ceilings |
+| `permission` | `edit` or `read-only` | Required | Must be granted by every roster route |
+| `description` | String, 1 to 2,000 characters | Required | `kxm role` |
+| `roster[].route` | Kebab route id, 1 to 64 characters | Required per entry | Must name `.kxm/models/<route>.yaml` |
+| `id` | Identifier | Optional; the filename | `kxm role` |
+| `extends` | Identifier of another role in the same project | Optional | Refused when the chain cycles |
+| `roster[].effort` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Optional | Must be inside the harness ceiling when set |
+| `roster[].mode` | `headless`, `interactive`, or `either` | Optional | Recorded on the entry |
+| `policy.fallback.onError` | Unique `rate_limit`, `transport`, `provider_unavailable` | Optional | Recorded on the role |
+| `policy.fallback.maxSwitches` | Integer, at least 0 | Optional | Recorded on the role |
+| `policy.fallback.revert` | `next_run` or `never` | Optional | Recorded on the role |
+| `skills`, `tools`, `produces`, `consumes` | See `schemas/role.schema.json` | Optional | `kxm role` |
+| `policy.vendorIndependenceRequired`, `policy.maxTransitions`, `policy.requiresGateVerification` | Boolean, or a positive integer for `maxTransitions` | Optional | Recorded on the role |
+
+Roster order is preference. `kxm role list` shows the first route as the
+primary. The Runtime checks membership. The model that runs still comes from
+the agent file. The developer assignment runner still reads `.kxm/roster.yaml`
+until P2.
 
 ```yaml
-# .kxm/roles/writer.yaml — the filename is the role id the Runtime looks up.
-schema: kxm.role.v1
+schema: kxm.role.v2
 id: writer
-description: Primary implementation role.
-roster:                       # order is priority
-  - model: xai/grok-4.6       # full provider/model string
+purpose: writer
+permission: edit
+description: Primary implementation agent.
+roster:
+  - route: grok-native
     effort: medium
-    enabled: true
-  - model: openrouter/qwen/qwen3-coder-plus
+  - route: qwen-openrouter-pi
     effort: medium
-    enabled: true
 ```
 
-Validated with `kxm init --json` (writer cross-check), `kxm role list --json`,
-and the Runtime's `listRoleBindings`.
-
-Commands: `kxm role list|get|add|remove|modify` (`--scope global|local`);
-`kxm models` (interactive) adds or removes `{model, enabled: true}` entries
-while admitting a route; the Runtime reads rosters on every live attempt.
-
-## `.kxm/role-hosts.yaml` (`kxm.role-hosts.v1`)
-
-Seat-to-host bindings for display. Read and written only by `kxm role hosts`
-and `kxm role set-host`; no dispatch path reads it. Location:
-`.kxm/role-hosts.yaml` (or `.yml`, or `role-hosts.json`) locally and
-`~/.config/kxm/role-hosts.yaml` globally; local seats override global ones.
+`kxm role add --route <route-id>` writes the roster. Repeat the option; the first id is primary. `kxm role modify <role> --add-route <route-id>` appends a route that already
+has a model file. `--remove-route <route-id>` drops one. Validated with
+`kxm config` and `kxm role list --json`.
 
-| Field | Type | Notes |
-|---|---|---|
-| `schema` | `kxm.role-hosts.v1` | A file with a different `schema` is ignored |
-| `seats.<seat>.host` | String | Harness shown for the seat |
-| `seats.<seat>.model` | String | Model shown for the seat |
-| `seats.<seat>.effort` | `low`, `medium`, `high`, or `xhigh` | |
-| `hostProviders.<host>` | String | Provider shown for a host |
-
-Seats without a binding fall back to built-in defaults (`planner`, `writer`,
-`critic-arch`, `critic-cli`, `verifier`), then to the role roster's first entry.
-
-```yaml
-schema: kxm.role-hosts.v1
-seats:
-  writer:
-    host: grok
-    model: xai/grok-4.6
-    effort: medium
-```
+`kxm models` does not write a v1 roster entry (a model id with an enabled flag). Its `r` and `x` keys call `setRouteState`, which appends `{route}` only when a `kxm.model.v2` file matches the inventory id. A selector with no matching model file is the `unknown route` path: the role file is left unchanged.
 
-Written by `kxm role set-host writer grok --model xai/grok-4.6 --effort medium`.
+Commands: `kxm role list|get|add|remove|modify` (`--scope global|local`, and `add --route`, `modify --add-route`, `modify --remove-route`);
+the Runtime reads rosters on every live attempt.
 
 ## `.kxm/routes.yaml` (`kxm.routes.v2`)
 
@@ -1723,7 +1688,7 @@ Everything under `.kxm/` at the project root falls into one of three groups.
 | Path | Group | Written by |
 |---|---|---|
 | `project.yaml`, `repo/`, `project/env.yaml`, `agents/`, `models/*.yaml` (except `inventory.yaml`), `workflows/`, `gates.yaml`, `template-provenance.yaml` | Tracked configuration (the bundle) | You and `kxm init` |
-| `roles/`, `routes.yaml`, `prices.yaml`, `modes.yaml`, `role-hosts.yaml`, `roster.yaml` | Tracked configuration outside the bundle | You and their commands |
+| `roles/`, `routes.yaml`, `prices.yaml`, `modes.yaml`, `roster.yaml` | Tracked configuration outside the bundle | You and their commands |
 | `config.yaml` | Tracked if the project wants shared preferences; otherwise ignore it | `kxm config set` |
 | `memory/`, `skills/`, `candidates/`, `goals/` | Tracked durable records | Their commands |
 | `models/inventory.yaml` | Generated; track it if you want a reviewed snapshot | `kxm models inventory-refresh` |
@@ -1775,7 +1740,7 @@ and `$XDG_STATE_HOME/kxm` (default `~/.local/state/kxm`) on Linux.
 
 The **user configuration directory** is `KXM_USER_CONFIG_DIR`, default
 `~/.config/kxm`. It holds `config.yaml`, global `roles/` and `workflows/`,
-`role-hosts.yaml`, `session.token`, and shell completion scripts. Global
+`session.token`, and shell completion scripts. Global
 workflows are listed by `kxm workflow definitions` but never loaded by
 `kxm run`.
 

package/docs/reference/harness-routing.md

@@ -133,21 +133,28 @@ The harness and the selector have to agree. Pi refuses `provider: xai` and `open
 
 ### Role roster entries
 
-A role file lists the selectors a role may run. For example, `.kxm/roles/writer.yaml`:
+A `kxm.role.v2` role file lists route ids, not selectors. Each `roster[].route` is resolved through `.kxm/models/<route-id>.yaml`, which carries `harness`, `model`, `vendor`, `status`, and `permissions`. The entry itself may set `effort` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`) and `mode` (`headless`, `interactive`, or `either`). This checkout's writer role is `.kxm/roles/writer.yaml`:
 
 ```yaml
-schema: kxm.role.v1
+schema: kxm.role.v2
 id: writer
+purpose: writer
+permission: edit
+description: Primary implementation agent.
+# Rotation priority = order. Effort default: medium for implementation.
 roster:
-  - model: xai/grok-4.6
-    enabled: true
-  - model: openrouter/qwen/qwen3-coder-plus
-    enabled: true
+  - route: grok-native
+    effort: medium
+  - route: qwen-openrouter-pi
+    effort: medium
+  - route: gemini-agy
 ```
 
-Every roster entry is a selector. When the engine checks the roster, it reads only `model`. The role schema accepts a `harness:` key on an entry, but dispatch never reads it: the harness still comes from the agent that runs the step. `kxm role list` prints the first entry as `(harness:xai/grok-4.6)`; there, "harness" is a placeholder label, not a harness.
+`grok-native` resolves to `.kxm/models/grok-native.yaml`: harness `grok`, model `grok-4.7`, vendor `xai`, status `admitted`, permission `edit`. `qwen-openrouter-pi` is harness `pi`, model `openrouter/qwen/qwen3-coder-plus`, vendor `alibaba`. `gemini-agy` is harness `agy`, model `gemini-3.8-flash-high`, vendor `google`. `kxm role list` prints the first route id as the primary, for example `(grok-native)`.
 
-The consequence matters when a roster mixes routes, as this one does. If the implementer agent declares `harness: grok`, only `xai/grok-4.6` can run under it. Under that agent, a Pi selector fails closed with `grok_not_authenticated: grok harness not detected (harness_unhosted_model)`. To run a Pi selector, create a separate agent with `harness:` omitted. The engine does not walk the roster to fail over on its own.
+The model that runs a step still comes from the agent file. The harness is the agent's `harness:`, or Pi when the agent omits it. A route file records which harness can host that model; it does not replace the agent. If the implementer agent declares `harness: grok`, only the Grok selector can run under it. A Pi selector under that agent fails closed with `grok_not_authenticated: grok harness not detected (harness_unhosted_model)`. To run a Pi selector, create a separate agent with `harness:` omitted. The engine does not walk the roster to fail over on its own.
+
+Dispatch still reads `.kxm/roster.yaml` until P2. Role files are what `kxm role` and the Runtime membership check use.
 
 ### Route ids in `.kxm/routes.yaml`
 

package/examples/project/.kxm/models/critic-claude.yaml

@@ -1,6 +1,10 @@
-schema: kxm.model.v1
-provider: anthropic
+schema: kxm.model.v2
+harness: claude
 model: claude-fable-5-1
+vendor: anthropic
+status: admitted
+permissions:
+  - read-only
 tags:
   - critic
 capabilities:

package/examples/project/.kxm/models/critic-gemini.yaml

@@ -1,6 +1,10 @@
-schema: kxm.model.v1
-provider: google
+schema: kxm.model.v2
+harness: agy
 model: gemini-3.1-pro-preview
+vendor: google
+status: admitted
+permissions:
+  - read-only
 tags:
   - critic
 capabilities:

package/examples/project/.kxm/models/critic-grok.yaml

@@ -1,6 +1,10 @@
-schema: kxm.model.v1
-provider: xai
+schema: kxm.model.v2
+harness: grok
 model: grok-4.6
+vendor: xai
+status: admitted
+permissions:
+  - read-only
 thinking: high
 tags:
   - critic

package/examples/project/.kxm/models/implementation.yaml

@@ -1,6 +1,10 @@
-schema: kxm.model.v1
-provider: anthropic
+schema: kxm.model.v2
+harness: claude
 model: claude-sonnet-4-6
+vendor: anthropic
+status: admitted
+permissions:
+  - read-only
 thinking: high
 tags:
   - implementation