v1.6: align Board inventory and service guidance

docs/board-data-contract.md

@@ -915,11 +915,27 @@ touched. Pruning needs `--yes` and never signals any process.
 
 `code-mower board list` emits `code_mower.boardInventory.v1`, a local inventory
 of visible Code Mower Board listeners. It reports loopback URL, PID, process
-name, parsed repo hint, serving version, installed package version,
-`restart_recommended`, health, and next action. Local cwd paths are redacted by
-default; `--show-local-paths` is for local debugging only. If the host blocks
-listener inspection, the command reports an unavailable inventory instead of
-calling GitHub or reading repository content.
+name, identity-verified repository, invoking version, serving version,
+installed package version, `restart_recommended`, managed-service identity,
+health, and next action. An identity-verified transient row carries a
+stop-and-install `promotion_command`; a stale managed row carries
+`restart_command`. Both commands use the redacted
+working-directory placeholder `--repo-path .`.
+
+`code-mower board list --repo OWNER/REPO` includes a row only when the Board's
+`/api/identity` response establishes that repository. Command-line repo hints
+never satisfy this filter, so legacy, malformed, and unresponsive listeners
+fail closed. The `filter` block counts matched, identity-unverified, and
+other-repository rows without exposing local paths. Local cwd paths are
+redacted by default; `--show-local-paths` is for local debugging only. If the
+host blocks listener inspection, the command reports an unavailable inventory
+instead of calling GitHub or reading repository content.
+
+The invoking CLI sets `restart_recommended` when `serving_version` differs
+from `invoking_version`, even if the process reports that its own serving and
+installed versions agree. The `local_boards` block in `lanes status` is this
+same enriched inventory, so its text and JSON expose the same versions,
+managed-service fields, and guidance.
 
 `code-mower board stop --port PORT --yes` and `code-mower board stop --pid PID
 --yes` emit `code_mower.boardStop.v1`. Stop only sends a local termination

docs/board-service-lifecycle.md

@@ -346,24 +346,28 @@ Selectors are not exclusive: every selector supplied must agree on one binding.
   not be proven to release the port rather than be undone.
 
 `board list` marks each Board `managed` with its service label, or transient,
-and says when that service's supervision is unconfirmed.
+and says when that service's supervision is unconfirmed. Use `code-mower board
+list --repo OWNER/REPO --json` to filter on the repository established by each
+listener's `/api/identity` response. A legacy, malformed, or unresponsive
+listener cannot satisfy the filter even when its process command line contains
+that repository. Omit `--repo` to inspect those unverified rows globally.
 
-In v1.5.2 the inventory is global: use `code-mower board list --json`, then
-filter the returned rows by their identity-verified `repo` value. The command
-does not accept `--repo`. Responsive rows carry `serving_version`,
+Responsive rows carry `invoking_version`, `serving_version`,
 `installed_version`, `restart_recommended`, `managed`, and `service_label`.
+Staleness is computed by the invoking CLI as well as read from the process, so
+an old Board cannot declare itself current merely because its own serving and
+installed versions agree.
 For one known listener, `GET /api/identity` is the compact identity/version
-probe and `GET /api/status` carries the full `board.version` block. Static HTML
-and `lanes status` are not version-verification surfaces in this release.
-
-When a transient Board needs to survive logout, stop it with the exact selector
-reported by `board list`, then review and install a managed definition with
-`board service render` and `board service install`. When a managed Board is
-stale, use `board service restart` with the same repository path and port.
-Repository-filtered inventory, version parity in `lanes status`, and copyable
-promotion/restart guidance are tracked for v1.6.0 in
-[#1063](https://github.com/codemower-ai/code-mower/issues/1063); do not use
-those planned command shapes with v1.5.2.
+probe and `GET /api/status` carries the full `board.version` block. `lanes
+status` presents the same inventory fields and service identity as `board
+list`.
+
+Every identity-verified transient row includes a copyable `promotion_command`
+that stops the exact repo/port listener and then installs the service. Every
+stale managed row includes its exact `restart_command`. The commands keep local
+paths redacted with `--repo-path .`; run them from the intended checkout, where
+the service lifecycle's origin guard verifies the repository before applying a
+definition.
 
 A `launchctl` that cannot be probed at all is one of those unconfirmed cases,
 not an empty inventory. On macOS the installed definitions are enumerated even

docs/launch-command-surface.md

@@ -48,7 +48,7 @@ Select any additional builder or reviewer explicitly.
 | `code-mower board serve --repo OWNER/REPO --record-events` | Serve the board and append throttled metadata-only local history snapshots while it is open. | yes, local only | GitHub optional |
 | `code-mower board serve --repo OWNER/REPO --agent-adapters-path PATH` | Read opt-in local agent cards from a custom metadata-only adapter directory. | no | no |
 | `code-mower board serve --repo OWNER/REPO --observations-path PATH` | Render local `code_mower.boardObservation.v1` records from a custom read-only directory. The Board consumes that contract and never writes one. | no | no |
-| `code-mower board list --json` | List the global local Board inventory with repo/version, restart hints, ports, and redacted cwd paths by default; v1.5.2 has no `--repo` filter. | no | no |
+| `code-mower board list --repo OWNER/REPO --json` | List only identity-verified local Boards for a repository, with invoking/serving/installed versions, service identity, restart posture, copyable service guidance, ports, and redacted cwd paths by default. Omit `--repo` for the global inventory. | no | no |
 | `code-mower board stop --port PORT --yes` | Stop a local Board listener that the inventory identified as Code Mower. | local process signal | no |
 | `code-mower board record --repo OWNER/REPO` | Append one redacted status snapshot to `.code-mower/board/events.jsonl` for local board history. | yes, local only | GitHub optional |
 | `code-mower board events` | Print recent local board-history events without calling GitHub. | no | no |

docs/quickstart.md

@@ -455,12 +455,13 @@ an explicit `--port` fails with a friendly conflict instead. The printed URL is
 local to that machine or VM unless you create your own tunnel. `lanes status`
 discovers local Board listeners best-effort across common macOS and Linux tools;
 if listener inventory is restricted, GitHub PR/check status still reports.
-Use `code-mower board list --json` to see the global local inventory with
-repo/version, restart hints, and whether each listener is managed or transient.
-In v1.5.2 `board list` does not accept `--repo`; filter its identity-verified
-rows after retrieval. For one known port, verify the version through
-`/api/identity` or the `board.version` block in `/api/status`. Static Board HTML
-and `lanes status` are not version-verification surfaces. Use
+Use `code-mower board list --repo OWNER/REPO --json` to see only Boards whose
+`/api/identity` response verifies that repository. Omit `--repo` for the global
+inventory, including legacy and unresponsive listeners. `board list` and
+`lanes status` report the invoking, serving, and installed versions, compute
+restart posture from invoking/serving parity, and identify managed services.
+Identity-verified transient rows include a copyable `promotion_command`; stale
+managed rows include their exact `restart_command`. Use
 `code-mower board stop --repo OWNER/REPO --yes`, `code-mower board stop --port
 PORT --yes`, or `code-mower board stop --pid PID --yes` only when you want to
 stop a listener that the inventory identified as a high-confidence Code Mower

docs/troubleshooting.md

@@ -142,13 +142,17 @@ version, the installed version, and whether a restart is recommended.
 For a scriptable inventory across all local listeners, use:
 
 ```bash
-code-mower board list --json
+code-mower board list --repo OWNER/REPO --json
 ```
 
-`board list` is a global local inventory in v1.5.2; it does not accept
-`--repo`. Filter the returned rows by their identity-verified `repo` field.
-Each responsive row reports `serving_version`, `installed_version`,
-`restart_recommended`, `managed`, and its service label when managed.
+The repository filter fails closed: a listener is included only when its
+`/api/identity` response establishes that repository. Legacy and unresponsive
+listeners remain visible in the unfiltered inventory, but are never selected
+from a process command-line hint. Each row reports the invoking, serving, and
+installed versions, `restart_recommended`, `managed`, and its service label.
+The invoking CLI marks a Board stale whenever its serving version differs from
+the invoking version, even when the old process reports its own serving and
+installed versions as equal.
 
 For one known Board, query the local status endpoint on its printed port:
 
@@ -158,10 +162,15 @@ curl -fsS http://127.0.0.1:PORT/api/status | python3 -m json.tool
 
 In `/api/status`, inspect `board.version.serving_version`,
 `board.version.installed_version`, and `board.version.restart_recommended`.
-`GET /api/identity` is the smaller identity and version probe. Do not infer the
-version from the static HTML or from `lanes status`; neither is the v1.5.2
-version-verification contract.
-When restart is recommended, stop the old Board process and start it again:
+`GET /api/identity` is the smaller identity and version probe. `lanes status`
+uses the same local inventory fields as `board list`. When a managed Board is
+stale, copy its `restart_command`; for an identity-verified transient Board,
+copy its `promotion_command` to install the persistent service. Both commands
+use `--repo-path .`, so run them from the intended repository checkout, where the
+service lifecycle validates the repository origin.
+
+When restart is recommended for a transient Board, stop the old process and
+start it again:
 
 ```bash
 code-mower board serve --repo OWNER/REPO