docs(cli): fix doc/source mismatches around -C scoping, doctor, and run-id

docs/reference/cli/agent.md

@@ -261,6 +261,8 @@ eval "$(paperclipai agent local-cli codexcoder --company-id <company-id> --json
 
 > **Warning:** The minted API key's plaintext token is shown **once**, in the command output. The exports embed it directly. Treat the output as a secret, and revoke the key with `token agent revoke` when the local session is done. See [Authentication](./authentication.md).
 
+> **Note:** The exports do **not** include `PAPERCLIP_RUN_ID`. Some agent-authenticated issue mutations (checkout, release, interactions, in-progress updates) are validated against a heartbeat run and fail with `401 Agent run id required` without one. If a local session hits that error, pass `--run-id <heartbeat-run-id>` on the failing command or export `PAPERCLIP_RUN_ID` — see the `--run-id` flag in [Common Options](./common-options.md).
+
 When skill installation runs, the command prints a per-tool summary (`linked` / `removed` / `skipped` / `failed` counts and the target directory). Broken symlinks are repaired and maintainer-only skills are removed, so re-running `local-cli` is safe and idempotent. Installation requires the bundled `skills` directory to be present in the checkout; if it cannot be found, the command fails rather than installing nothing silently.
 
 ---

docs/reference/cli/common-options.md

@@ -28,6 +28,12 @@ Company-scoped commands add one more flag:
 |---|---|
 | `-C, --company-id <id>` | Company ID. Overrides the profile's default company for this command. |
 
+Client commands also accept a run-scope flag:
+
+| Flag | Use |
+|---|---|
+| `--run-id <id>` | Heartbeat run ID attached to agent-authenticated mutations (issue checkout/release, interactions, in-progress updates). Falls back to the `PAPERCLIP_RUN_ID` environment variable. Without it, the server rejects those mutations with `401 Agent run id required`. Adapter/embodiment contexts export `PAPERCLIP_RUN_ID` automatically; `agent local-cli` does not. |
+
 > **Note:** The short alias `-C` for `--company-id` is registered by commands that opt into company scope. Not every command is company-scoped, so check the per-command reference page if you are unsure whether it applies.
 
 ---
@@ -81,6 +87,8 @@ If a command requires a company and none of these is set, it errors with:
 Company ID is required. Pass --company-id, set PAPERCLIP_COMPANY_ID, or set context profile companyId via `paperclipai context set`.
 ```
 
+> **Note:** Some commands declare `--company-id` as a *required option* instead of relying on this chain — for example `dashboard get`, `agent list`, `agent local-cli`, and the `token agent` commands. For those, the flag must be passed on the command line; the env var and profile fallbacks are never consulted, and omitting the flag fails with a missing-option error. The per-command reference pages call this out.
+
 ---
 
 ## Context profiles

docs/reference/cli/dashboard.md

@@ -18,7 +18,7 @@ paperclipai dashboard get --company-id <company-id>
 
 `dashboard get` issues a single `GET /api/companies/<company-id>/dashboard` and prints the summary. It does not change any state, trigger any runs, or wake any agents — it only reports. This makes it the cheapest way to answer "what is the state of this company right now?" without paging through `issue list`, `agent list`, `approval list`, and `cost summary` separately.
 
-This command is company-scoped, so it needs a company. It does not accept a positional company argument — pass the company with `-C` / `--company-id`, or let it resolve from your environment or profile (see [Resolving the company](#resolving-the-company)).
+This command is company-scoped, and the company must be passed explicitly: `-C` / `--company-id` is a required flag on `dashboard get`, and the usual `PAPERCLIP_COMPANY_ID` / profile fallback does not apply (see [Resolving the company](#resolving-the-company)).
 
 ---
 
@@ -34,7 +34,7 @@ paperclipai dashboard get --company-id <company-id>
 
 | Flag | Use |
 |---|---|
-| `-C, --company-id <id>` | The company to summarize. Required unless resolved from `PAPERCLIP_COMPANY_ID` or your context profile. |
+| `-C, --company-id <id>` | The company to summarize. **Required** — this command does not fall back to `PAPERCLIP_COMPANY_ID` or your context profile. |
 | `--json` | Emit the raw summary object as JSON instead of the formatted read. Use this when scripting. |
 | `--api-base <url>` | Override the API base URL for this call. |
 | `--api-key <token>` | Bearer token for agent-authenticated calls. |
@@ -45,27 +45,21 @@ paperclipai dashboard get --company-id <company-id>
 
 These are the standard client flags shared by every company-scoped CLI command. For the full explanation of how authentication, context, and the API base are resolved, see [Common options](./common-options.md).
 
-> **Note:** `dashboard get` is one of the few commands where `--company-id` is genuinely required by the command definition itself. Even with a default company in your profile, it is worth passing `-C` explicitly in scripts so the target is unambiguous.
+> **Note:** `dashboard get` is one of the few commands where `--company-id` is genuinely required by the command definition itself. Even with a default company in your profile, you must pass `-C` explicitly.
 
 ---
 
 ## Resolving the company
 
-The company is resolved in this order, first match wins:
+Unlike most company-scoped commands, `dashboard get` registers `--company-id` as a **required option**. The general resolution chain described in [Common options](./common-options.md#how-company-scope-is-resolved) — flag, then `PAPERCLIP_COMPANY_ID`, then the profile's `companyId` — never gets a chance to run: if the flag is missing, the command fails immediately with a missing-option error, regardless of what your environment or profile says.
 
-1. `-C` / `--company-id` on the command line
-2. the `PAPERCLIP_COMPANY_ID` environment variable
-3. the `companyId` recorded in the selected context profile
-
-If none of those produce a company, the command fails with a clear error telling you to pass `--company-id`, set `PAPERCLIP_COMPANY_ID`, or set a profile default with `paperclipai context set`.
-
-For an agent persona whose profile is already pinned to one company, the bare command works without any flag:
+So this fails even with `PAPERCLIP_COMPANY_ID` exported or a profile default set:
 
 ```sh
-paperclipai dashboard get
+paperclipai dashboard get            # error: required option '-C, --company-id <id>' not specified
 ```
 
-For a board operator who works across several companies, name the target explicitly each time:
+Always name the target explicitly:
 
 ```sh
 paperclipai dashboard get --company-id <company-id>

docs/reference/cli/output-and-scripting.md

@@ -84,6 +84,8 @@ paperclipai issue list --company-id <company-id> --json 2>/tmp/pc-errors.log
 
 > **Note:** A non-zero exit always means the command did not complete. Check it. In a pipeline like `paperclipai ... --json | jq ...`, the exit status you see is `jq`'s, not the CLI's — set `set -o pipefail` (bash) so an upstream failure fails the whole pipeline.
 
+> **Note:** The inverse does not hold for diagnostics: a standalone [`doctor`](./setup-commands.md#paperclipai-doctor) run that *completes* exits `0` even when individual checks fail. Failed checks are reported in the printed summary, not the exit code — parse the output if a script needs to react to them.
+
 ### Connection errors
 
 If the CLI cannot reach the API, the error message includes the URL it tried and a hint to check `GET /api/health` at that base. When you see this, the fix is almost always the API base resolution (below) pointing somewhere the server is not listening. See [Common Options](common-options.md) for the full resolution order.

docs/reference/cli/overview.md

@@ -121,7 +121,7 @@ Most control-plane commands share the same flags. Learn them once.
 | `--profile <name>` | Select which context profile to use. |
 | `--json` | Emit machine-readable output for scripting. |
 
-Company-scoped commands additionally take `--company-id <id>` (with a short `-C` alias on some, like `run`). For scripting and `--json` patterns, see [Output and scripting](output-and-scripting.md).
+Company-scoped commands additionally take `-C, --company-id <id>` — the short `-C` alias is registered wherever the flag exists. A handful of commands (such as `dashboard get` and `agent local-cli`) declare it as a required option, so the usual env/profile fallback does not apply there. For scripting and `--json` patterns, see [Output and scripting](output-and-scripting.md).
 
 ---
 

docs/reference/cli/setup-commands.md

@@ -117,11 +117,13 @@ It loads the config's `.env`, then runs these checks in order, stopping early on
 
 Each line reports `✓ pass`, `! warn`, or `✗ fail` with a repair hint. The summary counts passed/warned/failed, and a clear "fix and re-run" message is printed when anything fails.
 
+> **Note for scripts:** a standalone `doctor` exits `0` even when checks fail — failure is reported in the printed summary, not the exit code. Don't gate a CI step on `doctor`'s exit status; parse the output instead. (`run` behaves differently: when its built-in doctor pass fails, it stops without starting the server.)
+
 | Flag | Use |
 |---|---|
 | `-c, --config <path>` | Path to the config file. |
 | `-d, --data-dir <path>` | Isolate all local state from `~/.paperclip`. |
-| `--repair` (alias `--fix`) | Attempt to repair fixable issues. |
+| `--repair` | Attempt to repair fixable issues. |
 | `-y, --yes` | Skip the per-repair confirmation prompts. |
 
 > **Warning:** `--repair` can create or update local files (the JWT `.env`, the secrets key, the log directory) when a check knows how to fix the problem. Review the output before running it against a shared or production-like instance, and pair it with `--yes` only when you trust the repairs.