@kontextmind/kxm 0.7.165 → 0.7.166

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.165",
+      "version": "0.7.166",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -6,6 +6,22 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **Hub project identity and its access key live in `.kxm/config.yaml`.**
+  `hub.local` and `hub.cloud` hold the URL, the project id to present, and a
+  key reference (`key.op` is an `op://` reference, `key.env` is an environment
+  variable name). A literal token is refused. `op read` runs at use time and
+  the resolved value is not saved. The same order is used everywhere: flag,
+  `KXM_PROJECT`, the active mode's config project, `.kxm/project.yaml`, the
+  package name, then the directory name. `kxm hub bind` and
+  `kxm hub bind --cloud` write the non-secret fields, and `kxm hub view`
+  prints the mode, URL, project id, and key source. The hub's
+  `hub.projects` map uses the same references. `KXM_PROJECT_TOKENS` still
+  replaces that map. Setups whose hub map is keyed by the package name should
+  set `hub.local.project` or `hub.cloud.project` to that name, or keep passing
+  `KXM_PROJECT`: a checkout with `.kxm/project.yaml` otherwise sends that id
+  and gets `project_token_missing`. See
+  [Operate a KXM hub](docs/operations.md#hub-identity-in-config).
+
 - **`kxm hub bind --cloud` attaches a client to a remote hub reached through a loopback forward.**
   The binding records `--token-env` and/or `--token-command` and never the token.
   Later commands, including the environment for a Pi worker, use that source and

package/docs/concepts/trust-model.md

@@ -56,7 +56,7 @@ flowchart LR
 - **Claude Code plugin.** The MCP server uses the plugin's `auth_token` setting, else the project token the hub saved for this project. It never falls back to the saved admin token; without a project token, its tools report that and do nothing.
 - **SessionStart hook.** It reads local state read-only. It mints no token, writes no file, and never prints a token.
 - **Pi extension.** It uses `KXM_AUTH_TOKEN`, else the project token the hub saved for this project. It never uses the saved admin token, nor the one a hub it auto-started generated; without a project token it reports the fix and stays offline.
-- **`kxm peer` and `kxm workflow` agent commands.** They act as a peer agent, so they choose a token as the Pi extension does, and exit 2 with `project_token_missing` when none resolves.
+- **`kxm peer` and `kxm workflow` agent commands.** They act as a peer agent, so they choose a token as the Pi extension does, and exit 2 with `project_token_missing` when none resolves. The message names the project id that was sent and where it came from.
 - **Dashboard and Runtime supervisor.** Operator tools use `KXM_AUTH_TOKEN`, else the saved project token, else the saved admin token.
 
 ## Project isolation

package/docs/glossary.md

@@ -104,7 +104,7 @@ Another [agent](#agent) in the same [project](#project). `kxm_list` and `kxm pee
 
 ### Project
 
-The authentication and discovery namespace on the hub. Every command resolves it the same way: `--project` or `KXM_PROJECT`, then the [project ID](#project-id) in `.kxm/project.yaml`, then the `package.json` name, then the directory name. Its key in the hub's `KXM_PROJECT_TOKENS` holds its token. Agents see only peers in the same project.
+The authentication and discovery namespace on the hub. Every command resolves it the same way: `--project` or `KXM_PROJECT`, then the active mode's `project` in `.kxm/config.yaml`, then the [project ID](#project-id) in `.kxm/project.yaml`, then the `package.json` name, then the directory name. Its token is a key reference in that config, or the matching key in the hub's `KXM_PROJECT_TOKENS`. Agents see only peers in the same project.
 
 ### Project ID
 
@@ -112,7 +112,7 @@ The stable `prj_` identifier in `.kxm/project.yaml`. It is the hub [project](#pr
 
 ### Project token
 
-The credential that the agents of one [project](#project) use. The operator sets it in the hub's `KXM_PROJECT_TOKENS` JSON map, and agents receive it as `KXM_AUTH_TOKEN` or the plugin's `auth_token`. Setting `KXM_PROJECT_TOKENS` replaces the hub's saved map, so list every project each time.
+The credential that the agents of one [project](#project) use. The operator points config at it with `key.op` (`op://vault/item/field`) or `key.env` (an environment variable name), or sets the hub's `KXM_PROJECT_TOKENS` JSON map. The config file never holds the token. Agents receive the resolved value as `KXM_AUTH_TOKEN` or the plugin's `auth_token`. Setting `KXM_PROJECT_TOKENS` replaces the hub's saved map, so list every project each time. A config `hub.projects` map is resolved in memory and is not saved.
 
 ### Session token
 

package/docs/operations/troubleshooting.md

@@ -88,7 +88,7 @@ If a malformed claim remains, read the exact `.pid` JSON in the state directory
 | `hub_bind_unauthenticated` | The URL is remote and this machine has no token for the project; export it and bind again |
 | `hub_credential_unreadable` | Repair or remove `hub-env.json` under the user state root |
 | `cloud_token_missing` | A `--cloud` binding's variable is empty and it has no working command. Export the variable or fix `--token-command`. This machine's hub-env token is not sent |
-| `cloud_flag_required` | `--token-env` or `--token-command` was passed without `--cloud` |
+| `cloud_flag_required` | `--token-command` was passed without `--cloud`. `--token-env` and `--key-op` are key references and are valid on a local bind |
 | 401 after binding a loopback forward | The bind was not `--cloud`, so the client sent the local hub-env token. See [Cross-box peer attach](../operations.md#cross-box-peer-attach) |
 
 ## Claude Code plugin and MCP
@@ -99,7 +99,7 @@ The [plugin troubleshooting guide](../../plugins/kxm/README.md#troubleshooting)
 |---|---|
 | `kxm_*` tools do not appear | Check `/mcp` for the `kxm` server, check `node --version`, run `/reload-plugins`, and confirm `claude plugin list` shows `kxm@kxm` enabled |
 | `KXM hub unreachable at <url>` | Start the hub, or correct `server_url` with `/plugin configure kxm@kxm` |
-| `no project token for project <p>` | Enter the project token at `/plugin configure kxm@kxm`, or add `<p>` to the hub's full `KXM_PROJECT_TOKENS` map and restart the hub |
+| `kxm has no project token for project <p>` | The message names where `<p>` came from. Set `hub.local.project` or `hub.cloud.project` and a key reference in `.kxm/config.yaml`, or add `<p>` to the hub's full `KXM_PROJECT_TOKENS` map and restart the hub. Never paste the token into the file |
 | `KXM hub rejected the project token for project <p>` | Enter the token the hub holds for `<p>` |
 | `tool_policy_denied: Session token on disk is malformed or expired` | Run `kxm session token --clear` |
 | Pushed requests never arrive | Start Claude Code with `claude --dangerously-load-development-channels plugin:kxm@kxm` and accept the trust prompt, or use `kxm_inbox` and `kxm_reply` |

package/docs/operations.md

@@ -92,7 +92,7 @@ Expected output:
 
 ```text
 bound hub http://127.0.0.1:17331 · remote · health=on · token is not stored
-hub health=true ready=true · remote hub
+hub health=true ready=true · remote hub · mode=cloud project=prj_example (.kxm/config.yaml hub.cloud.project) key=env:KXMD_HUB_TOKEN
 ```
 
 `--token-env` and `--token-command` can be combined. A non-empty variable wins.
@@ -115,8 +115,8 @@ kxm hub view
 |---|---|---|
 | Loopback URL | Scope `loopback`. No credential required | Scope `remote`, including an SSH forward |
 | Token stored in `hub-binding.json` | No | No. The file names `tokenEnv` and/or `tokenCommand` |
-| Credential later commands send | `KXM_AUTH_TOKEN`, then this machine's hub-env | The named source only. Hub-env is not a fallback |
-| Missing source | Agent commands report `project_token_missing` | `cloud_token_missing` or `cloud_token_command_failed`. The local admin token is not sent |
+| Credential later commands send | `KXM_AUTH_TOKEN`, then the active mode's key reference in `.kxm/config.yaml`, then this machine's hub-env | The active mode's key reference, then the binding's named source. Hub-env is not a fallback |
+| Missing source | Agent commands report `project_token_missing` and name the project id that was sent | `cloud_token_missing` or `cloud_token_command_failed`. The local admin token is not sent |
 | `kxm hub start` from an extension | May start a local hub | Does not start a local hub when the forward is down (`cloud_hub_unreachable`) |
 
 `kxm hub view`, `kxm tenant status`, `kxm peer`, `kxm workflow` agent commands,
@@ -124,9 +124,60 @@ kxm hub view
 all use that source. `kxm agent worker` puts `KXM_AUTH_TOKEN` in the child
 process environment only. It does not write the token to disk.
 
-The hub project id is the same value for peer commands and `kxm tenant status`:
-`--project` or `KXM_PROJECT`, then the `id` in `.kxm/project.yaml`, then
-`package.json` `name`, then the directory name.
+The hub project id is the same value everywhere: `--project` or `KXM_PROJECT`,
+then the active mode's `project` in `.kxm/config.yaml`, then the `id` in
+`.kxm/project.yaml`, then `package.json` `name`, then the directory name.
+
+### Hub identity in config
+
+Hub URL, mode, project id, and key reference live in `.kxm/config.yaml`
+(`kxm.config.v1`), the same file as `hub.autoStart`. `.kxm/project.yaml` stays
+the stable project id. The project file wins over
+`~/.config/kxm/config.yaml`. `KXM_PROJECT` and `KXM_SERVER_URL` select the
+live connection for one process. They do not rewrite the file.
+
+```yaml
+hub:
+  autoStart: background
+  mode: local                 # local | cloud
+  local:
+    url: http://127.0.0.1:7331
+    project: prj_example      # optional; defaults to the project.yaml id
+    key:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+  cloud:
+    url: https://hub.kxmd.dev
+    project: prj_example
+    key:
+      op: op://Private/kxmd/project-token
+      env: KXMD_HUB_TOKEN
+  projects:                   # hub process map; references only
+    prj_example:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+```
+
+`key.op` is an `op://vault/item/field` reference. `key.env` is an environment
+variable name. A non-empty variable wins; otherwise `op read` runs when the
+client or the hub needs the token. The resolved value is not written to
+config, `hub-binding.json`, or `hub-env.json`. A literal token is refused
+with `hub_config_invalid`.
+
+`kxm hub bind` and `kxm hub bind --cloud` write the mode, URL, project id, and
+key reference. `--key-op` is the `op://` reference for either mode.
+`--token-env` names the variable for either mode. `--token-command` stays
+cloud-only. `kxm hub view` prints the mode, URL, project id, and key source.
+It does not print the token. `kxm hub unbind` removes the binding and
+`hub.mode`, and leaves the `local` and `cloud` blocks in place.
+
+On the hub, `hub.projects` is that same kind of map. `KXM_PROJECT_TOKENS`
+still replaces the map and is saved. A config map is resolved in memory and
+does not replace the saved file.
+
+A setup whose hub map is still keyed by the package name should set
+`hub.local.project` or `hub.cloud.project` to that name. Otherwise clients
+send the `.kxm/project.yaml` id and the hub has no token for it.
 
 ### Remove the binding
 
@@ -134,8 +185,10 @@ The hub project id is the same value for peer commands and `kxm tenant status`:
 kxm hub unbind
 ```
 
-Unbind deletes `hub-binding.json`. It does not delete hub-env, and it does not
-close the SSH forward. Stop the forward by ending the `ssh -N` session.
+Unbind deletes `hub-binding.json` and clears `hub.mode` in `.kxm/config.yaml`.
+The `local` and `cloud` blocks stay, so the next bind can switch mode again.
+It does not delete hub-env, and it does not close the SSH forward. Stop the
+forward by ending the `ssh -N` session.
 
 ## Troubleshooting
 
@@ -143,6 +196,7 @@ close the SSH forward. Stop the forward by ending the `ssh -N` session.
 |---|---|---|
 | 401 `invalid_auth` after binding `127.0.0.1:17331` | The bind was not `--cloud`, so the client sent this machine's hub-env admin token | Bind again with `--cloud` and a token source that holds the remote hub's token. Unset a stale `KXM_AUTH_TOKEN` that points at the local hub |
 | `cloud_token_missing` | `KXMD_HUB_TOKEN` (or the variable you named) is unset or empty, and no command is configured | Export the variable or pass `--token-command`. The local hub-env token is intentionally unused |
+| `project_token_missing` | The project id sent to the hub has no agent token. The message names that id and where it came from | Set `hub.local.project` or `hub.cloud.project` in `.kxm/config.yaml` to the id the hub already knows, and point `key.op` or `key.env` at the token. `KXM_PROJECT` or `--project` overrides the id for one command. Do not paste the token into the file |
 | `cloud_token_command_failed` | `op` exited non-zero, timed out, or printed more than one line | Run the same command in a terminal and sign in to 1Password. Do not paste the token into the binding |
 | Clients through one SSH host get locked out together | The hub rate-limits by agent id, otherwise by source address. Every forward from one SSH session shares `127.0.0.1` on the hub. `sshd` `MaxStartups` and `MaxSessions` can refuse new forwards first | Give each long-lived agent its own name. Raise the SSH limits on that host if many people share one jump host. Do not point two tenants at one hub |
 | `kxm hub view` says `loopback` for the forward | `--cloud` was omitted | Bind again with `--cloud`. `KXM_SERVER_URL` overrides the binding URL and is labeled on its own |

package/docs/reference/cli-reference.md

@@ -477,20 +477,20 @@ Starts, inspects, and stops the local KXM hub, and binds this machine to a hub.
 kxm hub view
 ```
 
-Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote.
+Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote, plus the mode, project id, and key source in effect. The key source is an environment variable name or an `op://` reference. The token is not printed.
 
 No command-specific options.
 
 - Needs a hub to succeed. Reads only.
-- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes.
-- Exit 0 when both probes succeed, 1 otherwise.
+- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes.
+- Exit 0 when both probes succeed, 1 otherwise. A cloud mode with no resolvable key exits 2 with `cloud_token_missing`.
 
 ```bash
 kxm hub view
 ```
 
 ```text
-hub health=true ready=true · loopback hub
+hub health=true ready=true · loopback hub · mode=local project=prj_example (.kxm/project.yaml id) key=hub-env
 ```
 
 ```bash
@@ -569,17 +569,17 @@ kxm hub stop --wait-ms 8000 --json
 ### `kxm hub bind`
 
 ```text
-kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>]
+kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>] [--key-op <op://vault/item/field>]
 ```
 
-Binds this machine to a running hub by writing `hub-binding.json` under the user state root, then probes the hub's health for up to 300 ms. Every hub client uses the binding when `KXM_SERVER_URL` is unset.
+Binds this machine to a running hub by writing `hub-binding.json` under the user state root and the non-secret endpoint (mode, URL, project id, key reference) into `.kxm/config.yaml`, then probes the hub's health for up to 300 ms. Every hub client uses that endpoint when `KXM_SERVER_URL` is unset. The token is never written.
 
 - Arguments: `<url>`, Hub base URL (http or https).
 - A URL with credentials, a query, a fragment, or a scheme other than http or https fails with `hub_url_invalid` (exit 2).
 - A remote (non-loopback) URL is refused with `hub_bind_unauthenticated` (exit 2, `nextAction: "export_kxm_auth_token"`) unless a credential for the current project resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`. A malformed record fails with `hub_credential_unreadable` (exit 2). A loopback URL without `--cloud` still binds with no credential.
-- `--cloud` marks the binding remote even when the URL is a loopback forward. It requires `--token-env`, `--token-command`, or both. The token is not written. A non-empty variable wins; otherwise the command runs. Source flags without `--cloud` fail with `cloud_flag_required`. A missing source later fails with `cloud_token_missing` and does not fall back to hub-env. See [Cross-box peer attach](../operations.md#cross-box-peer-attach).
-- Mutates the binding file. `--dry-run` validates and prints the plan without writing.
-- JSON keys: `url`, `scope`, `file`, `health` (`on`, `off`, or `unknown`), `probeMs`. A cloud bind also returns `cloud`, and `tokenEnv` or `tokenCommand` when set.
+- `--cloud` marks the binding remote even when the URL is a loopback forward. It requires `--token-env`, `--token-command`, `--key-op`, or a combination. The token is not written. A non-empty variable wins; otherwise an `op://` reference is read with `op read`, or the command runs. `--token-command` without `--cloud` fails with `cloud_flag_required`. `--token-env` and `--key-op` are also valid on a local bind and are stored only as references in config. A missing cloud source later fails with `cloud_token_missing` and does not fall back to hub-env. See [Cross-box peer attach](../operations.md#cross-box-peer-attach).
+- Mutates the binding file and `.kxm/config.yaml`. `--dry-run` validates and prints the plan without writing.
+- JSON keys: `url`, `scope`, `file`, `configFile`, `project`, `health` (`on`, `off`, or `unknown`), `probeMs`. A cloud bind also returns `cloud`, and `tokenEnv` or `tokenCommand` when set.
 
 ```bash
 kxm hub bind http://127.0.0.1:7331 --dry-run
@@ -603,7 +603,7 @@ kxm hub bind https://hub.example.com --dry-run --json
 kxm hub unbind
 ```
 
-Removes this machine's hub binding, including a malformed binding record.
+Removes this machine's hub binding, including a malformed binding record, and clears `hub.mode` in `.kxm/config.yaml`. The `hub.local` and `hub.cloud` blocks stay.
 
 No command-specific options.
 
@@ -2469,7 +2469,7 @@ Captured without a GitHub token. With `GITHUB_TOKEN` set, the same command polls
 
 ## `kxm peer`
 
-Peer agent messaging through the hub. Each invocation connects to the hub as a short-lived agent named `KXM_AGENT_NAME` (default `cli-<pid>`) in project `KXM_PROJECT` (default: the `package.json` name, else the directory name), using `KXM_AUTH_TOKEN`, else this project's saved project token from `hub-env.json`. It never uses the persisted admin token: with neither, the command exits 2 with `project_token_missing` (`nextAction: "export_kxm_auth_token"`) before contacting the hub. The `kxm workflow` agent verbs (`checkpoint`, `record`, `wait`, `get`, `list`) connect the same way. That agent appears in `peer list` and the dashboard. Every subcommand accepts `--payload <json>` with the tool's fields as one object; explicit flags override it. Tool policy from `KXM_ATTEMPT_TOKEN`, `KXM_SESSION_TOKEN`, or the on-disk session token is enforced first (`tool_policy_denied`, `session_token_invalid`, `attempt_token_invalid`).
+Peer agent messaging through the hub. Each invocation connects to the hub as a short-lived agent named `KXM_AGENT_NAME` (default `cli-<pid>`). The project id is `--project`, then `KXM_PROJECT`, then the active mode's `project` in `.kxm/config.yaml`, then the `id` in `.kxm/project.yaml`, then the `package.json` name, then the directory name. The token is `KXM_AUTH_TOKEN`, else the active mode's key reference, else this project's saved project token from `hub-env.json`. It never uses the persisted admin token: with none of those, the command exits 2 with `project_token_missing` (`nextAction: "configure_hub_project"`) and names the project id and where it came from, before contacting the hub. The `kxm workflow` agent verbs (`checkpoint`, `record`, `wait`, `get`, `list`) connect the same way. That agent appears in `peer list` and the dashboard. Every subcommand accepts `--payload <json>` with the tool's fields as one object; explicit flags override it. Tool policy from `KXM_ATTEMPT_TOKEN`, `KXM_SESSION_TOKEN`, or the on-disk session token is enforced first (`tool_policy_denied`, `session_token_invalid`, `attempt_token_invalid`).
 
 All subcommands need a hub, honor `--dry-run` (printing the parsed `args` without connecting), print the hub's result object on success, and print `{"ok":false,"error":"command_failed","detail":"..."}` with exit 1 on failure. Malformed `--payload` exits 2 with `invalid_payload`.
 

package/docs/reference/config-reference.md

@@ -1255,20 +1255,28 @@ in `plugins/kxm/src/config.ts`, then the user file
 `$KXM_USER_CONFIG_DIR/config.yaml` (default `~/.config/kxm/config.yaml`), then
 the project file `.kxm/config.yaml` in the current directory. Later layers win
 key by key; arrays are replaced, not merged. The files need no `schema` key.
-Nothing validates keys or values except `hub.autoStart` and the `improvement.*`
-keys, which fall back to their defaults field by field (see the table), but a file
-that is not valid YAML makes every `kxm config` command fail. `kxm improve` loads
-the project file from its project root (the current directory's Git root when it
-holds `.kxm/project.yaml`) rather than from the current directory.
-
-Two groups of keys change behavior today: `hub.autoStart`, and the `improvement.*`
-keys that shape the report `kxm improve` prints. The **Read by** column lists every
-reader found in `plugins/kxm/src`, `scripts/`, and `packages/`; the `kxm config`
-commands themselves are not counted.
+`hub.autoStart` and the `improvement.*` keys fall back to their defaults field
+by field (see the table). `hub.mode`, `hub.local`, `hub.cloud`, and
+`hub.projects` are validated: a literal token is refused with
+`hub_config_invalid`, and a mode other than `local` or `cloud` is refused. A
+file that is not valid YAML makes every `kxm config` command fail. `kxm improve`
+loads the project file from its project root (the current directory's Git root
+when it holds `.kxm/project.yaml`) rather than from the current directory.
+
+The keys that change behavior are the `hub` section below and the
+`improvement.*` keys that shape the report `kxm improve` prints. Hub URL, mode,
+project id, and key reference live here rather than in `.kxm/project.yaml`
+because `hub.autoStart` was already this file's hub setting, and
+`project.yaml` stays the stable hashed project id. The **Read by** column lists
+every reader found in `plugins/kxm/src`, `scripts/`, and `packages/`; the
+`kxm config` commands themselves are not counted.
 
 | Key | Type and allowed values | Default | Read by |
 |---|---|---|---|
 | `hub.autoStart` | `background` or `off`; any other value falls back to `background` | `background` | The Pi extension on load (`plugins/kxm/src/extension.ts`, `hub-autostart.ts`) |
+| `hub.mode` | `local` or `cloud`. Any other value is `hub_config_invalid`. Unset means local unless a cloud binding exists | unset | Every hub client (`hub-identity.ts`): CLI, Pi extension, MCP server, dash, and `kxm agent worker` |
+| `hub.local`, `hub.cloud` | `url` (http or https, no userinfo, query, or fragment), `project` (one line, no spaces), and `key` | unset | The same clients, for the active mode. `project` defaults to the `.kxm/project.yaml` id when omitted |
+| `hub.local.key`, `hub.cloud.key`, `hub.projects.<id>` | `op` is `op://vault/item/field`. `env` is an environment variable name. A string, or a field named like a token, is refused | unset | Clients resolve the active mode's key at use time. The hub process resolves `hub.projects` in memory (`server.ts`). Neither writes the resolved token |
 | `user.name`, `user.email` | String | none | Not read by any code path yet |
 | `user.preferredHarness`, `user.preferredModel` | String | none | Not read by any code path yet |
 | `user.preferredCritics` | Array of strings | `[reviewer-arch, reviewer-cli]` | Not read by any code path yet |
@@ -1302,9 +1310,26 @@ no recorded cost is never ready.
 
 ```yaml
 # .kxm/config.yaml (project scope) or ~/.config/kxm/config.yaml (user scope).
-# Only hub.autoStart and improvement.* change behavior today.
+# The project file wins. Key fields are references, never tokens.
 hub:
   autoStart: background        # background | off
+  mode: local                  # local | cloud
+  local:
+    url: http://127.0.0.1:7331
+    project: prj_example
+    key:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
+  cloud:
+    url: https://hub.kxmd.dev
+    project: prj_example
+    key:
+      op: op://Private/kxmd/project-token
+      env: KXMD_HUB_TOKEN
+  projects:
+    prj_example:
+      op: op://Private/kxm/local-project-token
+      env: KXM_LOCAL_PROJECT_TOKEN
 improvement:
   promotionPolicy: manual_pr   # manual_pr | critic_quorum | auto_threshold (readiness only)
   telemetryHalfLifeDays: 14

package/docs/reference/configuration.md

@@ -108,7 +108,7 @@ Every agent client (the Pi extension, the Claude Code MCP server, and the `kxm p
 |---|---|---|
 | `KXM_SERVER_URL` | `http://127.0.0.1:7331` | Hub base URL. For the CLI, the machine's `kxm hub bind` URL is used when this is unset |
 | `KXM_AUTH_TOKEN` | See below | The project token for this agent's project |
-| `KXM_PROJECT` | `id` in the nearest `.kxm/project.yaml`, else `name` in `package.json` in the working directory, else the directory name | Project for discovery and authentication. An explicit `--project` flag on `kxm peer list` and `kxm tenant status` wins over this variable. The same resolver is used by peer commands, tenant status, workers, the Pi extension, and the Claude Code MCP server |
+| `KXM_PROJECT` | Active mode's `project` in `.kxm/config.yaml`, else `id` in the nearest `.kxm/project.yaml`, else `name` in `package.json` in the working directory, else the directory name | Project for discovery and authentication. An explicit `--project` flag wins over this variable, and this variable wins over the config file. The same resolver is used by peer commands, tenant status, workers, the Pi extension, dash, and the Claude Code MCP server |
 | `KXM_AGENT_NAME` | Harness-specific (see below) | Name peers see; unique among online agents in the project, compared case-insensitively |
 | `KXM_AGENT_PURPOSE` | Harness-specific (see below) | One line peers use to decide what to send this agent |
 
@@ -120,7 +120,7 @@ Every agent client (the Pi extension, the Claude Code MCP server, and the `kxm p
 
 A clean shutdown marks an identity offline. Reconnecting with the same project and name resumes its durable agent ID and rotates its agent key. If the Claude Code name is already online in the project, the MCP server registers once more as `<name>-<pid>`.
 
-A `--cloud` hub binding replaces this table's token lookup for every client, including agents. The token comes from the binding's `--token-env` or `--token-command`, never from this machine's hub-env file, and it is not written to disk. `kxm agent worker` copies it into the child process environment as `KXM_AUTH_TOKEN`.
+A cloud hub mode replaces this table's token lookup for every client, including agents. The token comes from that mode's key reference in `.kxm/config.yaml` (`key.env`, then `key.op` via `op read`), then from the binding's `--token-env` or `--token-command`. It never comes from this machine's hub-env file, and it is not written to disk. `kxm agent worker` copies it into the child process environment as `KXM_AUTH_TOKEN`. Local mode uses `KXM_AUTH_TOKEN`, then the local key reference, then the saved project token, and still never the admin token.
 
 Also check plugin.json is valid JSON.
 

package/docs/reference/tools.md

@@ -64,7 +64,7 @@ Every tool returns its result as JSON text; Pi also attaches the same value as s
 
 | Error text | Harness | Fix |
 |---|---|---|
-| `KXM has no project token for project <p> on this machine` | Claude Code | Set `auth_token` with `/plugin configure kxm@kxm`, or [give the project a token](../start/quickstart-claude-code.md#give-the-project-a-token-on-the-running-hub) on the hub |
+| `kxm has no project token for project <p>` | Claude Code and the Pi extension | The message names where `<p>` came from. Set `hub.local.project` or `hub.cloud.project` and a key reference in `.kxm/config.yaml`, set `auth_token` with `/plugin configure kxm@kxm`, or [give the project a token](../start/quickstart-claude-code.md#give-the-project-a-token-on-the-running-hub) on the hub |
 | `KXM hub unreachable at <url> (<cause>)` | Claude Code | Start the hub with `kxm hub start`, or correct `server_url` |
 | `KXM hub rejected the project token for project <p>` | Claude Code | Enter that project's token from the hub's `KXM_PROJECT_TOKENS` |
 | `kxm hub is not connected; check KXM_SERVER_URL and /kxm hub` | Pi | Start the hub or fix `KXM_SERVER_URL`, then restart the session |

package/docs/start/quickstart-claude-code.md

@@ -181,7 +181,7 @@ Claude Code asks for these options at install. Change them later with `/plugin c
 | `auth_token` | Blank | Blank on the machine that runs the hub. Elsewhere, this project's token. Never the admin token. |
 | `agent_name` | `claude` | The name peers see. A second concurrent session in the project registers as `<name>-<pid>`. |
 | `agent_purpose` | `Claude Code implementation and review agent` | One line that peers use to decide what to send this agent |
-| `project` | Blank | `<hub-project>`. Blank uses the `name` in `package.json`, then the directory name. |
+| `project` | Blank | `<hub-project>`. Blank uses `hub.local.project` or `hub.cloud.project` in `.kxm/config.yaml` for the active mode, then the `id` in `.kxm/project.yaml`, then the `name` in `package.json`, then the directory name. |
 
 With a blank `auth_token`, the plugin uses the project token the hub saved for `project` in `hub-env.json`, and only that token. It never uses the admin token. On another machine, get the project token from whoever runs the hub, through a password manager, and enter it at `/plugin configure kxm@kxm`. [Plugin settings](../reference/config-reference.md#claude-code-plugin-settings) has the full rules.
 
@@ -394,7 +394,7 @@ The `kxm_*` tools and the session brief name the fix for setup problems. Run the
 | Message or symptom | Cause | Fix |
 |---|---|---|
 | `KXM hub unreachable at <url>` | No hub answers at `server_url` | Start the hub with `kxm hub start`, or correct `server_url` and restart Claude Code |
-| `KXM has no project token for project <p> on this machine` | No `auth_token`, and the hub saved no token for `<p>` | Add `<p>` with [step 3](#3-start-the-hub), enter its token, or fix the `project` option |
+| `kxm has no project token for project <p>` | No `auth_token`, and the hub saved no token for `<p>`. The message names where `<p>` came from | Set `hub.<mode>.project` in `.kxm/config.yaml` to the key the hub knows, add a key reference, or add `<p>` with [step 3](#3-start-the-hub). Never paste the token into the file |
 | `KXM hub rejected the project token for project <p>` | `auth_token` is not the hub's token for `<p>` | Enter the right token at `/plugin configure kxm@kxm` |
 | `tool_policy_denied: Session token on disk is malformed or expired` | A stale session token file blocks every tool | Run `kxm session token --clear`; it prints `Session token cleared from disk.` |
 | `tool_policy_denied: KXM_SESSION_TOKEN is malformed or expired` | A bad `KXM_SESSION_TOKEN` in Claude Code's environment | Unset or replace it where you launch Claude Code, then restart it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.165",
+  "version": "0.7.166",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

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.165",
+  "version": "0.7.166",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/README.md

@@ -58,7 +58,7 @@ Claude Code asks for these options when you install the plugin. Change them late
 | `auth_token` | `KXM_AUTH_TOKEN` | Blank | This project's token from the hub's `KXM_PROJECT_TOKENS`. Leave it blank on the machine that runs the hub. Never the hub admin token. Marked sensitive. |
 | `agent_name` | `KXM_AGENT_NAME` | `claude` | Name other agents see. The first active session in a project keeps it; a later concurrent session registers as `<name>-<pid>`. |
 | `agent_purpose` | `KXM_AGENT_PURPOSE` | `Claude Code implementation and review agent` | One line that peers use to decide what to send this agent. |
-| `project` | `KXM_PROJECT` | Blank | Hub project key; must match a key in the hub's `KXM_PROJECT_TOKENS`. Blank uses the `id` in `.kxm/project.yaml`, then `name` from `package.json`, then the directory name. |
+| `project` | `KXM_PROJECT` | Blank | Hub project key. Blank uses the active mode's `project` in `.kxm/config.yaml`, then the `id` in `.kxm/project.yaml`, then `name` from `package.json`, then the directory name. |
 
 The MCP server also receives `KXM_PROJECT_DIR`, set to the directory Claude Code was started in (`CLAUDE_PROJECT_DIR`). It decides the default project key and whether this is a KXM project (one with a `.kxm/` directory).
 
@@ -69,7 +69,7 @@ The plugin acts as an agent of one hub project and authenticates with that proje
 - On the machine that runs the hub, leave `auth_token` blank. The MCP server then uses the project token the hub saved for this project in `hub-env.json` under the user state root (`KXM_STATE_HOME`, or the platform default listed in [State outside the project](../../docs/reference/config-reference.md#state-outside-the-project)). It uses only that entry, never the admin token saved beside it.
 - On any other machine, enter this project's token at `/plugin configure kxm@kxm`. Get it from whoever runs the hub, through your password manager. When the machine is bound with `kxm hub bind --cloud`, leave `auth_token` blank: the MCP server reads the binding's token source and does not store the token. The recipe is [Cross-box peer attach](../../docs/operations.md#cross-box-peer-attach).
 - Never enter the hub admin token. It is the operator's credential. The hub accepts it for any project that has no token of its own, so an agent holding it could act in projects it was never given.
-- Without a project token, every `kxm_*` tool fails with `KXM has no project token for project <p> on this machine`, and the MCP server does not contact the hub.
+- Without a project token, every `kxm_*` tool fails with `kxm has no project token for project <p>`, naming where that id came from, and the MCP server does not contact the hub.
 
 To give a project a token, the operator adds it to `KXM_PROJECT_TOKENS` and restarts the hub. That variable replaces the hub's saved token map rather than merging with it, so it must list every project, existing and new. [Add Claude Code to an existing project](../../docs/start/quickstart-claude-code.md#add-claude-code-to-an-existing-project) has a command that builds the full map. Run it in your own terminal, and never paste tokens or `hub-env.json` into Claude.
 
@@ -210,7 +210,7 @@ No hub answers at `server_url`. Start it with `kxm hub start`, or correct `serve
 
 ### `no project token for project <p>`
 
-The MCP server found neither an `auth_token` nor a token the hub saved for `<p>`, so it did not contact the hub. Enter the project's token at `/plugin configure kxm@kxm`, or add `<p>` to the hub's `KXM_PROJECT_TOKENS`, listing every existing project too because the variable replaces the saved map, and restart the hub. If `<p>` is not the key you expected, set the `project` option.
+The MCP server found neither an `auth_token` nor a token the hub saved for `<p>`, so it did not contact the hub. The message names where `<p>` came from. Enter the project's token at `/plugin configure kxm@kxm`, set `hub.local.project` or `hub.cloud.project` in `.kxm/config.yaml` to the key the hub already knows, or add `<p>` to the hub's `KXM_PROJECT_TOKENS` or `hub.projects` map. `KXM_PROJECT_TOKENS` replaces the saved map, so list every existing project, then restart the hub. Never paste the token into the config file.
 
 ### `KXM hub rejected the project token for project <p>`