@kontextmind/kxm 0.7.165 → 0.7.167

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.167",
   "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.167",
   "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>`