@kontextmind/kxm 0.7.145 → 0.7.147

package/docs/reference/cli-reference.md

@@ -188,7 +188,7 @@ The starter `defaultHarness: pi` and `npm test` gate are generic settings, not r
 - Global options: `--json` and `--dry-run` only; `--workspace` exits 2 with `workspace_option_unsupported`.
 - `--project-id` must match `prj_` followed by 6 to 128 letters, digits, `_`, or `-`. `--repository` is repeatable; each value must be `<id>=<absolute path>`, and a repeated ID fails with `repository_binding_argument_duplicate`.
 - Needs a Git repository. Does not need a hub or the Runtime.
-- Writes `.kxm/project.yaml`, `.kxm/agents/coordinator.yaml`, `.kxm/agents/implementer.yaml`, `.kxm/gates.yaml`, `.kxm/repo/repo.yaml`, `.kxm/workflows/default.yaml`, and `.kxm/template-provenance.yaml`, using a `.kxm-init-transaction` directory at the Git root while a create or repair is in flight. Repository bindings are written under the user state root, never into Git. `--dry-run` writes nothing.
+- Writes `.kxm/project.yaml`, `.kxm/agents/planner.yaml`, `.kxm/agents/writer.yaml`, `.kxm/gates.yaml`, `.kxm/repo/repo.yaml`, `.kxm/workflows/default.yaml`, and `.kxm/template-provenance.yaml`, using a `.kxm-init-transaction` directory at the Git root while a create or repair is in flight. `planner.yaml` keeps the alias `coordinator`, and `writer.yaml` keeps the alias `implementer`. Repository bindings are written under the user state root, never into Git. `--dry-run` writes nothing.
 - On an interactive terminal without `--json` or `--dry-run`, a successful create or join offers to install shell completion (suppress with `KXM_SKIP_COMPLETION_PROMPT=1`) and to write workflow-guide agents (suppress with `KXM_SKIP_GUIDE_SETUP_PROMPT=1`). Guided setup keeps a role only when one of its guide candidates is on a fixed map of reviewed harness/model pairs and that harness is authenticated; it writes the agent and workflow files, appends those selectors to `.kxm/routes.yaml`, and skips every other candidate. Google candidates are not on the map and are always skipped, because the Runtime's Pi one-shot cannot reach Google's `antigravity` Pi provider yet (see [Harness routing](harness-routing.md#google-through-the-antigravity-pi-provider)).
 - JSON keys: `action` (`planned`, `created`, `joined`, `repaired`, `resumed`, or `validated`), `mode`, `inspectedFrom`, `projectRoot`, `changesRequired`, `legacyInputs`, `issues`, `configRevision`, `files`, `plannedOnly`, and, when relevant, `guidance`, `localBindingFile`, `bindingsChanged`, `repairPlan`, `resumePending`, `transactionKind`.
 - Exit 0 for every completed action and every dry-run plan. Exit 1 when the result is planning-only (legacy state, blocked repair, partial state without provenance) or for `initialization_failed` (with `issues`) and `initialization_io_failed`. A planning-only text result prints the reason and then one `<file>: <code>: <message>` line per validation issue, for example `.kxm/workflows/first.yaml: gate_outcome_impossible: ...`.
@@ -200,7 +200,7 @@ kxm init --dry-run --json
 ```
 
 ```text
-{"schema":"kxm.cli-result.v1","ok":true,"command":"init","action":"planned","mode":"create","inspectedFrom":"/work/proj","projectRoot":"/work/proj","changesRequired":true,"legacyInputs":[],"issues":[],"files":[".kxm/agents/coordinator.yaml",".kxm/agents/implementer.yaml",".kxm/gates.yaml",".kxm/project.yaml",".kxm/repo/repo.yaml",".kxm/template-provenance.yaml",".kxm/workflows/default.yaml"],"plannedOnly":true}
+{"schema":"kxm.cli-result.v1","ok":true,"command":"init","action":"planned","mode":"create","inspectedFrom":"/work/proj","projectRoot":"/work/proj","changesRequired":true,"legacyInputs":[],"issues":[],"files":[".kxm/agents/planner.yaml",".kxm/agents/writer.yaml",".kxm/gates.yaml",".kxm/models/claude-fable.yaml",".kxm/models/grok-grok-4-6.yaml",".kxm/project.yaml",".kxm/repo/repo.yaml",".kxm/roles/planner.yaml",".kxm/roles/writer.yaml",".kxm/routes.yaml",".kxm/template-provenance.yaml",".kxm/workflows/default.yaml"],"plannedOnly":true}
 ```
 
 Create the project:
@@ -419,7 +419,7 @@ kxm trust diff
 
 ```text
 permission diff: sha256:80457232cbfc… -> sha256:7428fde55ca4…
-EXPANSION  .kxm/agents/coordinator.yaml /repositories/control repository-access changed (expansion)
+EXPANSION  .kxm/agents/planner.yaml /repositories/control repository-access changed (expansion)
 1 expansion(s) require explicit reviewed trust action
 ```
 
@@ -452,7 +452,7 @@ kxm trust check
 
 ```text
 permission diff: sha256:80457232cbfc… -> sha256:7428fde55ca4…
-EXPANSION  .kxm/agents/coordinator.yaml /repositories/control repository-access changed (expansion)
+EXPANSION  .kxm/agents/planner.yaml /repositories/control repository-access changed (expansion)
 1 expansion(s) require explicit reviewed trust action
 trust check failed: review every expansion above before merging
 ```
@@ -462,7 +462,7 @@ kxm trust check --json
 ```
 
 ```text
-{"schema":"kxm.cli-result.v1","ok":false,"command":"trust check",...,"requiresReview":true,"expansions":1,"narrowings":0,"neutralChanges":0,"changes":[{"resource":".kxm/agents/coordinator.yaml","path":"/repositories/control","field":"repository-access","direction":"expansion",...}]}
+{"schema":"kxm.cli-result.v1","ok":false,"command":"trust check",...,"requiresReview":true,"expansions":1,"narrowings":0,"neutralChanges":0,"changes":[{"resource":".kxm/agents/planner.yaml","path":"/repositories/control","field":"repository-access","direction":"expansion",...}]}
 ```
 
 <a id="hub-commands"></a>
@@ -1069,7 +1069,7 @@ Lists admitted and disabled routes.
 
 No command-specific options.
 
-- Reads only. JSON keys: `policy` (`schema`, `updatedAt`, `admitted`, `disabled`) and `membership` (strings `<role> <route-id>` from `.kxm/roles/*.yaml`). `policy` has no `roles` field. A model file named by no roster, such as `opus-claude`, is absent from `membership`.
+- Reads only. JSON keys: `policy` (`schema`, `updatedAt`, `admitted`, `disabled`) and `membership` (strings `<role> <route-id>` from `.kxm/roles/*.yaml`). `policy` has no `roles` field. A model file named by no roster is absent from `membership`, and this repository's workforce lint fails on that file.
 
 ```bash
 kxm routes list
@@ -1083,18 +1083,17 @@ admitted openai/gpt-5.6-sol
 admitted openrouter/qwen/qwen3-coder-plus
 admitted openrouter/qwen/qwen3.8-flash
 admitted openrouter/z-ai/glm-5.3-flash
-admitted qwen-token-plan/deepseek-v4.1-flash
-admitted qwen-token-plan/qwen3.8-flash
-admitted qwen-token-plan/qwen3.8-max
 admitted xai/grok-4.7
-admitted zai-coding-cn/glm-5.3
-admitted zai-coding-cn/glm-5.3-flash
-planner fable-claude
-reviewer-arch fable-claude
-reviewer-cli sol-codex
-writer grok-native
-writer qwen-openrouter-pi
-writer gemini-agy
+planner claude-fable
+planner pi-qwen3-8-flash-openrouter
+reviewer-arch claude-fable
+reviewer-arch pi-glm-5-3-flash-openrouter
+reviewer-cli codex-gpt-5-6-sol
+reviewer-cli pi-qwen3-8-flash-openrouter
+writer grok-grok-4-7
+writer pi-qwen3-coder-plus-openrouter
+writer agy-gemini-3-8-flash-high
+writer agy-gemini-3-8-flash-medium
 ```
 
 ```bash
@@ -1102,7 +1101,7 @@ kxm routes list --json
 ```
 
 ```text
-{"schema":"kxm.cli-result.v1","ok":true,"command":"routes list","policy":{"schema":"kxm.routes.v2","updatedAt":"2026-09-24T00:00:00.000Z","admitted":["anthropic/fable","google/gemini-3.8-flash-high","google/gemini-3.8-flash-medium","openai/gpt-5.6-sol","openrouter/qwen/qwen3-coder-plus","openrouter/qwen/qwen3.8-flash","openrouter/z-ai/glm-5.3-flash","qwen-token-plan/deepseek-v4.1-flash","qwen-token-plan/qwen3.8-flash","qwen-token-plan/qwen3.8-max","xai/grok-4.7","zai-coding-cn/glm-5.3","zai-coding-cn/glm-5.3-flash"],"disabled":[]},"membership":["planner fable-claude","reviewer-arch fable-claude","reviewer-cli sol-codex","writer grok-native","writer qwen-openrouter-pi","writer gemini-agy"]}
+{"schema":"kxm.cli-result.v1","ok":true,"command":"routes list","policy":{"schema":"kxm.routes.v2","updatedAt":"2026-09-27T00:00:00.000Z","admitted":["anthropic/fable","google/gemini-3.8-flash-high","google/gemini-3.8-flash-medium","openai/gpt-5.6-sol","openrouter/qwen/qwen3-coder-plus","openrouter/qwen/qwen3.8-flash","openrouter/z-ai/glm-5.3-flash","xai/grok-4.7"],"disabled":[]},"membership":["planner claude-fable","planner pi-qwen3-8-flash-openrouter","reviewer-arch claude-fable","reviewer-arch pi-glm-5-3-flash-openrouter","reviewer-cli codex-gpt-5-6-sol","reviewer-cli pi-qwen3-8-flash-openrouter","writer grok-grok-4-7","writer pi-qwen3-coder-plus-openrouter","writer agy-gemini-3-8-flash-high","writer agy-gemini-3-8-flash-medium"]}
 ```
 
 ### `kxm routes count`
@@ -1247,10 +1246,10 @@ 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 whose primary route is `fable-claude`, with `grok-native` second (Not run):
+Add a reviewer whose primary route is `claude-fable`, with `grok-grok-4-7` second (Not run):
 
 ```bash
-kxm role add reviewer --description "Independent reviewer" --route fable-claude --route grok-native --skills kxm
+kxm role add reviewer --description "Independent reviewer" --route claude-fable --route grok-grok-4-7 --skills kxm
 ```
 
 ```bash
@@ -1307,7 +1306,7 @@ kxm role get writer --json
 ```
 
 ```text
-{"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"}]}}
+{"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-grok-4-7","effort":"medium"},{"route":"pi-qwen3-coder-plus-openrouter","effort":"medium"},{"route":"agy-gemini-3-8-flash-high"},{"route":"agy-gemini-3-8-flash-medium"}]}}
 ```
 
 Captured from this checkout with `node scripts/kxm.mjs role get writer --json`. The path is shortened to `/work/kxm`.
@@ -1317,13 +1316,13 @@ kxm role modify writer --add-skill kxm --dry-run --json
 ```
 
 ```text
-{"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"}]}
+{"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-grok-4-7","effort":"medium"},{"route":"pi-qwen3-coder-plus-openrouter","effort":"medium"},{"route":"agy-gemini-3-8-flash-high"},{"route":"agy-gemini-3-8-flash-medium"}]},"filePath":"/work/kxm/.kxm/roles/writer.yaml","scope":"local","dryRun":true,"planned":[{"action":"write","target":"/work/kxm/.kxm/roles/writer.yaml"}]}
 ```
 
 Add an existing route to a role's roster (Not run):
 
 ```bash
-kxm role modify reviewer --add-route fable-claude --add-skill kxm-peer
+kxm role modify reviewer --add-route claude-fable --add-skill kxm-peer
 ```
 
 ### `kxm role resume`
@@ -1411,7 +1410,7 @@ Refusals (exit 1): `lane_missing`, `lane_dirty`, `lane_run_open`, `lane_git_fail
 
 Creates the lane when the record is absent (same rules as `create`), refuses `lane_run_open` when the last run is not settled, then runs the same path as `kxm run --lane <unit> --brief <file>` and `kxm runs drive <runId> --lane <unit>`. `--wait` and `--timeout-ms` are passed through. The run id is stored on the record. Prints the run envelope and the drive result. That open-run check may start the Runtime supervisor; `--dry-run` only attaches to a supervisor that is already running. `kxm lane status` never starts the supervisor.
 
-`--brief` is required. `--workflow` defaults to the lane project's `defaultWorkflow`. `--base` applies only when the lane is created. A live agent step uses the step `timeoutMs` when it is set, otherwise the project `limits.agentStepTimeoutMs` (default 3,600,000). This repository's `implement-only`, `review-arch-only`, and `review-cli-only` workflows are the lane forms of the retired transport recipes.
+`--brief` is required. `--workflow` defaults to the lane project's `defaultWorkflow`. `--base` applies only when the lane is created. A live agent step uses the step `timeoutMs` when it is set, otherwise the project `limits.agentStepTimeoutMs` (default 3,600,000). This repository's `writer-only`, `reviewer-arch-only`, and `reviewer-cli-only` workflows are the lane forms of the retired transport recipes. `implement-only`, `review-arch-only`, and `review-cli-only` still resolve.
 
 Refusals (exit 1): `brief_unreadable`, `lane_unit_invalid`, `lane_exists`, `lane_base_unresolved`, `lane_run_open`, `lane_git_failed`, `lane_not_project`, `lanes_unreadable`.
 

package/docs/reference/config-reference.md

@@ -55,7 +55,7 @@ to add.
 .kxm/project.yaml ── repositories[] ──> .kxm/repo/repo.yaml (+ env.yaml) in each repository
    │ defaultWorkflow, defaultHarness, limits
    ▼
-.kxm/workflows/<id>.yaml ── coordinator ──> .kxm/agents/coordinator.yaml
+.kxm/workflows/<id>.yaml ── coordinator ──> .kxm/agents/planner.yaml
    │ steps[]
    ├─ kind agent | moa | approval | wait ──> .kxm/agents/<id>.yaml
    │                                           ├─ role ──> .kxm/roles/<role>.yaml
@@ -361,13 +361,14 @@ tool call, shell commands included, and neither confines the process to the
 checkout. A live write step on any other harness is handed off; see
 [Steps the Runtime does not execute yet](#steps-the-runtime-does-not-execute-yet).
 
-Example (the shape `kxm init` writes for `implementer`):
+Example (the shape `kxm init` writes for `writer`):
 
 ```yaml
-# .kxm/agents/implementer.yaml. The filename is the agent id.
+# .kxm/agents/writer.yaml. The filename is the agent id, and it matches role.
 schema: kxm.agent.v1
 purpose: Implement the approved change within the declared repository scope.
 role: writer                      # .kxm/roles/writer.yaml -> .kxm/models/<route>.yaml
+aliases: [implementer]            # deprecated id; still resolves, with a warning
 tools:
   preset: workspace-writer        # coordinator | read-only | workspace-writer | tests-writer
   allow: [read, edit, write, bash]
@@ -383,9 +384,10 @@ network: provider-only            # none | provider-only | restricted | host
 resultSchema: kxm.assignment-result.v1
 ```
 
-`kxm init` creates `coordinator` (`role: planner`) and `implementer`
-(`role: writer`) without `harness` or `model`, and admits `anthropic/fable`
-and `xai/grok-4.6` in `.kxm/routes.yaml`. An interactive `kxm init` can add
+`kxm init` creates `planner` (`role: planner`, alias `coordinator`) and `writer`
+(`role: writer`, alias `implementer`) without `harness` or `model`, and admits
+`anthropic/fable` and `xai/grok-4.6` in `.kxm/routes.yaml`. The model files are
+`claude-fable` and `grok-grok-4-6`. An interactive `kxm init` can add
 workflow-guide agents for reviewed pairs whose harness is authenticated, and
 admits their selectors too, but skips Google guide candidates because the
 Runtime cannot reach the `antigravity` Pi provider yet. `kxm run` and the
@@ -408,7 +410,8 @@ bytes.
 | Field | Type and allowed values | Required, default | What reads it |
 |---|---|---|---|
 | `schema` | `kxm.model.v2` | Required | Loader |
-| `id` | Kebab identifier, 1 to 64 characters | Optional; the filename is the id | Loader |
+| `id` | `<harness>-<model-slug>[-<provider>]`, 1 to 64 characters | Optional; the filename is the id | Loader. This repository's workforce lint requires the pattern |
+| `aliases` | Deprecated route ids, at most 16 | Optional | Still resolve to this file; a warning names the canonical id |
 | `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 |
@@ -425,7 +428,8 @@ bytes.
 
 ```yaml
 schema: kxm.model.v2
-id: grok-native
+id: grok-grok-4-7          # <harness>-<model-slug>; "." in the model id is "-"
+aliases: [grok-native]     # deprecated id; still resolves, with a warning
 harness: grok
 model: grok-4.7
 vendor: xai
@@ -666,11 +670,11 @@ the reason, field, and detail. The Runtime uses these reasons:
 | `gate_uncertain_blocked` | The run is `blocked_uncertain` and waits for an external signal or an operator |
 
 Example (validated with `kxm init --json` and compiled with
-`compileKxmWorkflow`). Besides the `implementer` and `critic-arch` agents and
-the `critic-claude` profile shown above, it needs a `coordinator` agent, a
-`planner` agent (harness `claude`, model `anthropic/fable`, read access), a
-`critic-cli` agent (harness `codex`, model `openai/gpt-5.6-sol`, read access),
-and a second profile tagged `critic`, `critic-sol` (`openai/gpt-5.6-sol`).
+`compileKxmWorkflow`). Besides the `writer` and `reviewer-arch` agents and
+the `critic-claude` profile shown above, it needs a `planner` agent (the
+workflow coordinator; `coordinator` still resolves as an alias), a
+`reviewer-cli` agent, and a second profile tagged `critic`, `critic-sol`
+(`openai/gpt-5.6-sol`). Routes, not agent files, name the harness and model.
 The two providers among the `critic` candidates satisfy
 `distinctBy: [provider]` with `target: 2`.
 
@@ -678,7 +682,7 @@ The two providers among the `critic` candidates satisfy
 # .kxm/workflows/review.yaml — the filename is the workflow id.
 schema: kxm.workflow.v1
 description: Plan, implement, review with two critics, verify, approve, and wait for CI.
-coordinator: coordinator            # agent id; defaults to "coordinator"
+coordinator: planner               # agent id; omitted value falls back to "coordinator", an alias of planner
 limits:
   maxTransitions: 12                # required once any back-edge exists
   maxRunDurationMs: 14400000
@@ -688,7 +692,7 @@ planHash:                           # capture the approved plan when "plan" pass
   stageId: plan
   evidenceKey: plan
 requirePlanHash:                    # writing steps after "plan" must be listed here
-  - implement
+  - writer
   - verify
 steps:
   - id: plan
@@ -704,19 +708,20 @@ steps:
       - key: plan
         kind: artifact
     on:
-      passed: implement             # shorthand transition: a step id
+      passed: writer                # shorthand transition: a step id
       blocked:
         target: $terminal
         terminalStatus: failed
 
-  - id: implement
+  - id: writer
     kind: agent
-    agent: implementer
+    agent: writer
+    aliases: [implement]
     maxAttempts: 3
     repositories:
       control: write
     assignments:
-      allowedAgents: [implementer]
+      allowedAgents: [writer]
       minimum: 1
       target: 1
       maximum: 1
@@ -734,13 +739,13 @@ steps:
 
   - id: review
     kind: moa                       # panel of agents
-    agent: critic-arch              # primary agent; must be in allowedAgents
+    agent: reviewer-arch            # primary agent; must be in allowedAgents
     model:
       tag: critic                   # intersected with each agent's own model ceiling
     repositories:
       control: read
     assignments:
-      allowedAgents: [critic-arch, critic-cli]
+      allowedAgents: [reviewer-arch, reviewer-cli]
       minimum: 2
       target: 2
       maximum: 2
@@ -754,14 +759,14 @@ steps:
         kind: assignment-result
         producerPolicy:
           minimumProducers: 2
-          eligibleAgents: [critic-arch, critic-cli]
+          eligibleAgents: [reviewer-arch, reviewer-cli]
           acceptedStatuses: [passed]
           degradation:
             minimumProducers: 1
     on:
       passed: verify
       changes-requested:            # back-edge: needs maxTransitions
-        target: implement
+        target: writer
         maxTransitions: 2
 
   - id: verify
@@ -777,7 +782,7 @@ steps:
     on:
       passed: approve
       implementation-failure:
-        target: implement
+        target: writer
         maxTransitions: 2
 
   - id: approve
@@ -807,9 +812,9 @@ steps:
         terminalStatus: failed
 ```
 
-This example validates, but a live drive would be handed off at `implement`
-(write access), at `review` (`critic-arch` uses a profile selector), and at
-`approve` and `ci` (dispatched to `coordinator`, which declares no model). Use
+This example validates, but a live drive would be handed off at `writer`
+(write access), at `review` (`reviewer-arch` uses a profile selector), and at
+`approve` and `ci` (dispatched to `coordinator`, which resolves to `planner`). Use
 it as a field reference; the
 [worked example](#worked-example-a-minimal-two-step-project) is one that runs.
 
@@ -822,7 +827,7 @@ compiles and pins the plan, then drives it live, or without models with
 `kxm workflow add <id>` a one-step scaffold, under `.kxm/workflows/` (or
 `~/.config/kxm/workflows/` with `--scope global`, which the loader never
 reads). Both are valid `kxm.workflow.v1` definitions that use only what
-`kxm init` creates: the `coordinator` and `implementer` agents, the `control`
+`kxm init` creates: the `planner` and `writer` agents (`coordinator` and `implementer` remain aliases), the `control`
 repository, and the `test` gate. The templates route gate failures on
 `implementation-failure`. A local add is checked by the project loader first:
 if the project would not load with the new file, it is refused with
@@ -931,9 +936,9 @@ purpose: writer
 permission: edit
 description: Primary implementation agent.
 roster:
-  - route: grok-native
+  - route: grok-grok-4-7
     effort: medium
-  - route: qwen-openrouter-pi
+  - route: pi-qwen3-coder-plus-openrouter
     effort: medium
 ```
 
@@ -1027,50 +1032,51 @@ independent vendors`, and `retired .kxm/roster.json present`.
 
 ```yaml
 # Assembled by scripts/roster-policy.mjs from .kxm/roles/*.yaml and .kxm/models/*.yaml.
+# Route ids are <harness>-<model-slug>[-<provider>]. The first critic in each
+# lineup is the required critic. Later entries are read-only fallbacks.
 routes:
-  grok-native:                  # route id: lowercase words joined by "-"
+  grok-grok-4-7:
     harness: grok
-    model: grok-4.6             # native harnesses take a bare model id
+    model: grok-4.7             # native harnesses take a bare model id
     vendor: xai
     roles: [writer]
     permissions: [edit]
     status: admitted            # admitted | retired
-  qwen-openrouter-pi:
+  pi-qwen3-coder-plus-openrouter:
     harness: pi
     model: openrouter/qwen/qwen3-coder-plus   # Pi: allowed provider prefix + vendor/model
     vendor: alibaba
     roles: [writer]
     permissions: [edit]
     status: admitted
-  fable-claude:
+  claude-fable:
     harness: claude
     model: fable
     vendor: anthropic
     roles: [planner, reviewer-arch]
     permissions: [read-only]
     status: admitted
-  sol-codex:
+  codex-gpt-5-6-sol:
     harness: codex
     model: gpt-5.6-sol
     vendor: openai
     roles: [reviewer-cli]
     permissions: [read-only]
     status: admitted
-lineup:                         # routes admitted for each role
-  writer: [grok-native, qwen-openrouter-pi, gemini-agy]
-  planner: [fable-claude]
-  reviewer-arch: [fable-claude]
-  reviewer-cli: [sol-codex]
+lineup:                         # routes admitted for each role, preference order
+  writer: [grok-grok-4-7, pi-qwen3-coder-plus-openrouter, agy-gemini-3-8-flash-high, agy-gemini-3-8-flash-medium]
+  planner: [claude-fable, pi-qwen3-8-flash-openrouter]
+  reviewer-arch: [claude-fable, pi-glm-5-3-flash-openrouter]
+  reviewer-cli: [codex-gpt-5-6-sol, pi-qwen3-8-flash-openrouter]
 required_critics:
-  review-arch: fable-claude
-  review-cli: sol-codex
+  review-arch: claude-fable
+  review-cli: codex-gpt-5-6-sol
 model_origins:                  # required for every Pi route model
   openrouter/qwen/qwen3-coder-plus:
     vendor: alibaba
     evidence:
-      source: docs/workflow-guide.md
-      commit: 69341ca200c31b98b5ba2371437398f0ce501089
-      sha256: 358d436dbf1b6f3904252afba167e643d33d597d16148ac1286b1c21b81448a4
+      source: plans/evidence/route-qwen-openrouter-pi.md
+      sha256: b15f8a54adc398b33e75609e959076eee310bf4ff6623d0b8470ea3da95e6c54
 ```
 
 Validated with `validateRosterDocument` from `scripts/roster-policy.mjs`,
@@ -1685,8 +1691,8 @@ Directory layout (inside a Git repository):
 └── .kxm/
     ├── project.yaml
     ├── repo/repo.yaml
-    ├── agents/coordinator.yaml
-    ├── agents/implementer.yaml
+    ├── agents/planner.yaml
+    ├── agents/writer.yaml
     ├── gates.yaml
     ├── routes.yaml
     └── workflows/default.yaml
@@ -1717,11 +1723,13 @@ repositoryId: control
 defaultAccess: write
 ```
 
-`.kxm/agents/coordinator.yaml` (every workflow needs its coordinator agent):
+`.kxm/agents/planner.yaml` (every workflow needs its coordinator agent):
 
 ```yaml
 schema: kxm.agent.v1
 purpose: Coordinate the pinned workflow.
+role: planner
+aliases: [coordinator]
 tools:
   preset: coordinator
 defaultRepositoryAccess: read
@@ -1731,15 +1739,13 @@ network: provider-only
 resultSchema: kxm.assignment-result.v1
 ```
 
-`.kxm/agents/implementer.yaml`:
+`.kxm/agents/writer.yaml`:
 
 ```yaml
 schema: kxm.agent.v1
 purpose: Implement the requested change in the control repository.
-harness: grok
-model:
-  provider: xai
-  model: grok-4.6
+role: writer
+aliases: [implementer]
 tools:
   preset: workspace-writer
 defaultRepositoryAccess: none
@@ -1765,13 +1771,14 @@ gates:
 ```yaml
 schema: kxm.workflow.v1
 description: Implement a change, then run the test suite.
-coordinator: coordinator
+coordinator: planner
 limits:
   maxTransitions: 4
 steps:
-  - id: implement
+  - id: writer
     kind: agent
-    agent: implementer
+    agent: writer
+    aliases: [implement]
     maxAttempts: 2
     repositories:
       control: write
@@ -1798,7 +1805,7 @@ steps:
         target: $terminal
         terminalStatus: completed
       implementation-failure:
-        target: implement
+        target: writer
         maxTransitions: 2
 ```
 
@@ -1814,11 +1821,11 @@ disabled: []
 
 Why each piece is there:
 
-- `implement` routes a failure straight to a terminal `failed` status and
+- `writer` routes a failure straight to a terminal `failed` status and
   declares `failed`, the outcome the producer falls back to.
 - `verify` declares `implementation-failure`, the outcome a failing command
   produces. Routing that edge on `failed` instead is refused when the project
-  loads (`gate_outcome_impossible`). The edge back to `implement` makes it a
+  loads (`gate_outcome_impossible`). The edge back to `writer` makes it a
   back-edge, so it carries `maxTransitions: 2` and the workflow carries
   `limits.maxTransitions`.
 - The gate step lists `control: write`; the Runtime refuses command gate steps
@@ -1841,9 +1848,9 @@ kxm runs drive <runId> --simulated --wait    # model-free drive; runs npm test f
 
 The simulated drive records `passed` for the agent step, runs `npm test` in the
 project root, and settles `completed` when it exits 0. When `npm test` fails,
-the run returns to `implement` and fails with `budget_step_attempts` once
-`implement` has used its two attempts. A live drive of this workflow is refused
-today, because the `implement` step has write access (see
+the run returns to `writer` and fails with `budget_step_attempts` once
+`writer` has used its two attempts. A live drive of this workflow is refused
+today, because the `writer` step has write access (see
 [Steps the Runtime does not execute yet](#steps-the-runtime-does-not-execute-yet)).
 Stop the Runtime afterwards with `kxm runtime stop`.
 

package/docs/reference/configuration.md

@@ -200,21 +200,23 @@ The Runtime supervisor runs `kxm run` workflows and syncs their summaries to the
 
 ## Browser automation
 
-Playwright testing and verification use Obscura. Steel is for human takeover, MFA, and the live session viewer. `resolveBrowserCdpEndpoint()` in `plugins/kxm/src/browser.ts` returns the CDP URL. `resolveBrowserCdpConnect()` returns that URL and the handshake headers, and `connectBrowserOverCdp()` passes them to `chromium.connectOverCDP`. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it. See [Browser automation](../guides/browser-automation.md).
+Playwright testing and verification use Obscura. Steel is for remote and hosted browsing, human takeover, MFA, and the live session viewer. `resolveBrowserCdpEndpoint()` in `plugins/kxm/src/browser.ts` returns the CDP URL. `resolveBrowserCdpConnect()` returns that URL and the handshake headers, and `connectBrowserOverCdp()` passes them to `chromium.connectOverCDP`. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it. Steel needs `kxm` 0.7.135 or newer. See [Browser automation](../guides/browser-automation.md) and [ADR-0007](../adr/ADR-0007-steel-caddy-authentik.md).
 
 | Variable | Default | Effect |
 |---|---|---|
-| `KXM_BROWSER` | `obscura` | `obscura` selects the Obscura CDP URL and sends no Steel headers. `steel` selects `formatCDPConnect()` (the session URL plus `Authorization`, or the legacy API-key header) and requires a session id. Any other value throws |
+| `KXM_BROWSER` | `obscura` | `obscura` selects the Obscura CDP URL and sends no Steel headers. `steel` selects `/v1/devtools` plus `Authorization` and requires a session id. Any other value throws |
 | `OBSCURA_CDP_URL` | `http://127.0.0.1:${OBSCURA_PORT:-9222}` | CDP URL passed to `chromium.connectOverCDP()`. When set, it wins over `OBSCURA_PORT` for that URL |
 | `OBSCURA_PORT` | `9222` | TCP port for `obscura serve`. Used in the default CDP URL when `OBSCURA_CDP_URL` is unset. The launcher refuses to start when this port disagrees with the port in `OBSCURA_CDP_URL` |
-| `STEEL_API_URL` | A KontextMind-operated deployment | Base URL of your Steel API. Set it before using `KXM_BROWSER=steel` |
+| `STEEL_API_URL` | `https://steel.kontextmind.com` | Base URL of the Steel API. `steel.theneuro.me` is an alias of that server |
 | `STEEL_UI_URL` | `$STEEL_API_URL/ui` | Base URL of the Steel session viewer |
-| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. Wins over the other Steel auth variables |
+| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. First among the Steel auth variables |
 | `STEEL_AUTH_BASIC` | unset | `base64(user:token)`, with or without a leading `Basic` prefix. Sent as `Authorization: Basic` |
-| `STEEL_AUTH_USER` | unset | Authentik username. Used with `STEEL_AUTH_TOKEN`. An incomplete pair fails closed |
+| `STEEL_AUTH_USER` | unset | Authentik username `svc-steel`. Used with `STEEL_AUTH_TOKEN`. An incomplete pair fails closed |
 | `STEEL_AUTH_TOKEN` | unset | Authentik app password. Used with `STEEL_AUTH_USER` |
-| `STEEL_API_KEY` | A `pass-cli` lookup | Deprecated. Sent as `x-steel-api-key` and as `?apiKey=` on the CDP URL for the temporary proxy shim. The library warns once. Not sent when an Authentik variable is set |
-| `USE_PASS_CLI` | enabled | Set to `false` to disable the legacy `STEEL_API_KEY` `pass-cli` fallback |
+| `STEEL_API_KEY` | unset | Deprecated. Steel and Caddy do not enforce it. The three variables above override it. The library warns once |
+| `USE_PASS_CLI` | enabled | Set to `false` to skip the legacy `STEEL_API_KEY` lookup. That lookup does not authenticate |
+
+`STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` with `STEEL_AUTH_TOKEN`, override `STEEL_API_KEY`. Load field `basic_auth` from 1Password vault `kontextmind`, item `Steel (svc-steel)`, with `op read` into `STEEL_AUTH_BASIC`. Do not write the value to disk. The CDP path is `/v1/devtools` with an `Authorization` header. Sessions return `websocketUrl` `wss://steel.kontextmind.com/`.
 
 Obscura's own `OBSCURA_TIMEZONE` (default `Europe/Berlin`) and `OBSCURA_CDP_TOKEN` (required only for a non-loopback bind) are read by the Obscura process, not by KXM.
 

package/docs/reference/harness-routing.md

@@ -117,7 +117,7 @@ role: writer
 
 ### Model file
 
-This is the native route, from `.kxm/models/grok-native.yaml`:
+This is the native route, from `.kxm/models/grok-grok-4-7.yaml` (alias `grok-native`):
 
 ```yaml
 harness: grok
@@ -151,14 +151,15 @@ permission: edit
 description: Primary implementation agent.
 # Rotation priority = order. Effort default: medium for implementation.
 roster:
-  - route: grok-native
+  - route: grok-grok-4-7
     effort: medium
-  - route: qwen-openrouter-pi
+  - route: pi-qwen3-coder-plus-openrouter
     effort: medium
-  - route: gemini-agy
+  - route: agy-gemini-3-8-flash-high
+  - route: agy-gemini-3-8-flash-medium
 ```
 
-`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)`.
+`grok-grok-4-7` resolves to `.kxm/models/grok-grok-4-7.yaml`: harness `grok`, model `grok-4.7`, vendor `xai`, status `admitted`, permission `edit`. `pi-qwen3-coder-plus-openrouter` is harness `pi`, model `openrouter/qwen/qwen3-coder-plus`, vendor `alibaba`. `agy-gemini-3-8-flash-high` 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-grok-4-7)`. The previous ids (`grok-native`, `qwen-openrouter-pi`, `gemini-agy`) are aliases.
 
 Dispatch resolves a step from the agent `role`, then `.kxm/roles/<role>.yaml`, then the selected `.kxm/models/<route>.yaml`. That model file carries `harness`, `model`, `vendor`, `status`, and `permissions`. The engine walks the roster in order and uses the first admitted route whose model file is readable. A missing or unreadable model file is a refusal (`roster_model_unreadable` at load, `producer_route_unsupported` at dispatch), not a skip to the next entry. A route file that names a harness the model cannot run on still fails closed with `harness_unhosted_model`.
 

package/docs/reference/workflow-catalog.md

@@ -1096,9 +1096,9 @@ These three files live in this repository's `.kxm/workflows`. `kxm init` does no
 
 | Workflow | Runs through |
 |---|---|
-| `implement-only` | `kxm lane run`. Replaces a retired transport recipe. |
-| `review-arch-only` | `kxm lane run`. Replaces a retired transport recipe. |
-| `review-cli-only` | `kxm lane run`. Replaces a retired transport recipe. |
+| `writer-only` | `kxm lane run`. `implement-only` still resolves to this file. |
+| `reviewer-arch-only` | `kxm lane run`. `review-arch-only` still resolves to this file. |
+| `reviewer-cli-only` | `kxm lane run`. `review-cli-only` still resolves to this file. |
 
 ## Related
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.145",
+  "version": "0.7.147",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -45,11 +45,11 @@
     "typecheck": "tsc --noEmit",
     "lint:docs": "markdownlint-cli2",
     "check:versions": "node scripts/check-versions.mjs",
-    "check": "npm run typecheck && npm run lint:docs && npm run check:versions",
+    "check": "npm run typecheck && npm run lint:docs && npm run check:versions && node scripts/workforce-lint.mjs",
     "verify": "npm test && npm run check && npm run check:generated",
     "validate:claude": "claude plugin validate . --strict && claude plugin validate plugins/kxm --strict",
     "validate:ci": "npm run test:coverage && npm run check && npm pack --dry-run",
-    "validate:pr": "npm run build && npm run typecheck && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/artifacts-exist.test.ts test/core/ci-contract.test.ts test/core/envelope.test.ts test/core/envelope-contract.test.ts test/core/protocol.test.ts test/core/repo-root.test.ts test/core/routes-count.test.ts test/core/smoke.test.ts test/core/version-surfaces.test.ts && npm run check:versions && node scripts/check-generated.mjs",
+    "validate:pr": "npm run build && npm run typecheck && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/artifacts-exist.test.ts test/core/ci-contract.test.ts test/core/envelope.test.ts test/core/envelope-contract.test.ts test/core/protocol.test.ts test/core/repo-root.test.ts test/core/routes-count.test.ts test/core/smoke.test.ts test/core/version-surfaces.test.ts && npm run check:versions && node scripts/workforce-lint.mjs && node scripts/check-generated.mjs",
     "validate": "npm run validate:ci && npm run validate:claude",
     "test:packages": "npx nx run-many -t test --output-style=static",
     "check:packages": "npx nx run-many -t build,test:coverage,typecheck --output-style=static",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.145",
+  "version": "0.7.147",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",