@vigilbase/cli 0.2.2 → 0.2.4

package/CLOUDFLARE.md

@@ -2,7 +2,7 @@
 
 `vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first (signing in isn't supported on Windows yet). Your organization, permissions, customer links, and allowed zones determine access. The CLI never requires a Cloudflare API key.
 
-`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup`, verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm. It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md)).
+`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup`, verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm. It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/LOCAL.md)).
 
 Customer provider access requires an `active` or `trialing` Cloudflare service
 entitlement for the selected account. Historical/inactive rows and legacy account
@@ -45,7 +45,7 @@ In this table, `C` means `[--customer-id <uuid>]`, `C!` means a required `--cust
 | `cf zero-trust <account-id>` | C | Users, Access applications, tunnels and authentication analytics |
 | `cf developer-platform <account-id>` | C | Workers, Workers analytics and Pages projects |
 | `cf magic-transit <account-id>` | C | Prefixes, routes and traffic analytics |
-| `cf analytics --customer-id <uuid>` | A or Z, `[--days <1..30>]` | Usage and traffic analytics; default 7 days |
+| `cf analytics --customer-id <uuid>` | A or Z, `[--days <1..30>]` (whole days, digits only; other forms give `--days must be an integer.`) | Usage and traffic analytics; default 7 days |
 | `cf checkup [status]` | C A | Setup state and latest completed checkup |
 | `cf checkup start` | C A | Starts a persisted account security checkup |
 | `cf checkup progress <run-uuid>` | None | Persisted progress events, percentage and status |

package/COMMANDS.md

@@ -2,19 +2,21 @@
 
 The CLI uses public scanner APIs on `vigilbase.com` and authenticated APIs on
 `one.vigilbase.com`. Use `vigilbase <command> --help` or
-`vigilbase help <command>` for built-in help, and `vigilbase help <tool>` (for
+`vigilbase help <command>` for built-in help (`vigilbase help cf zones` shows
+the same help as `vigilbase cf zones --help`), and `vigilbase help <tool>` (for
 example `vigilbase help website-security`) for how to run a tool. Examples
-below omit `--json`, which every command supports.
+below omit `--json`, which every command supports. Commands are matched in any
+case.
 
 ## References
 
 | Area | Complete command and API reference |
 | --- | --- |
-| Cloudflare | [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) |
-| Security | [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) |
-| Customers, organizations, monitoring, support | [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/ONE.md) |
-| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) |
-| Sign-in, credentials, configuration, troubleshooting | [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md) |
+| Cloudflare | [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/CLOUDFLARE.md) |
+| Security | [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/SECURITY.md) |
+| Customers, organizations, monitoring, support | [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/ONE.md) |
+| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/LOCAL.md) |
+| Sign-in, credentials, configuration, troubleshooting | [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/README.md) |
 
 The references list the supported operations, filters, response and pagination
 behaviour, API endpoints and access requirements of the CLI.
@@ -24,16 +26,18 @@ behaviour, API endpoints and access requirements of the CLI.
 | Flag | Meaning |
 | --- | --- |
 | `--json`, `-j` | JSON on stdout; progress and browser instructions on stderr |
-| `--help`, `-h` | Help for the named command; makes no API request |
+| `--help`, `-h` | Help for the named command; makes no API request. In a terminal the main help starts with the banner; pipes and files get plain usage |
 | `--version`, `-V` | The installed version: the banner in a terminal, only the version number when stdout is a pipe or a file, `{"name":"@vigilbase/cli","version":"…"}` with `--json` |
 | `--one-url <origin>` | One origin; default `https://one.vigilbase.com` |
-| `--auth-url <origin>` | The Identity issuer to trust; default `https://auth.vigilbase.com`. Staging (`https://identity-staging.vigilbase.com`) or a loopback issuer is trusted only when set here or in `VIGILBASE_AUTH_URL` |
+| `--auth-url <origin>` | The Identity issuer to trust; default `https://auth.vigilbase.com`. A loopback issuer is trusted only when set here or in `VIGILBASE_AUTH_URL`, with a loopback `--one-url` |
 | `--base-url <origin>` | Public origin; default `https://vigilbase.com` |
 | `--timeout <ms>` | Per-request timeout, integer 1–2147483647; default 60000 |
 | `--client-id <id>` | Device authorization client; default `vigilbase-cli` |
 
 Origins must be HTTP(S) URLs without credentials, paths, query strings or
-fragments. One requires HTTPS, except HTTP for loopback development.
+fragments, and use HTTPS except on loopback (`localhost`, `127.0.0.0/8`,
+`[::1]`). An empty flag value is an error; an empty environment variable counts
+as unset. A command checks only the origins it uses.
 `--customer-id` is a command-specific One customer UUID; it does not change the
 session's permissions. API reads may still return 403 when the signed-in role
 lacks access. Unknown flags, flags a command doesn't take (including scope
@@ -41,6 +45,17 @@ flags), missing arguments and extra arguments fail before any API request. A
 missing argument is named with the command's usage, for example
 `Missing <url>. Usage: vigilbase headers <url>` or
 `Missing <customer-id>. Usage: vigilbase customers summary <customer-id>`.
+Invalid values fail the same way, with a message that names the flag and the
+allowed values, for example `--severity must be one of: critical, high, medium, low.`,
+`--limit must be between 1 and 200.` or
+`--start must be an ISO 8601 date-time with an offset, for example 2026-10-12T00:00:00Z.`;
+with `--json` these errors have `"code": "INVALID_ARGUMENT"`. An empty or
+whitespace-only argument counts as missing. An unknown subcommand gives
+``Unknown <group> command "<name>". Run `vigilbase <group> --help` for usage.``
+(also `INVALID_ARGUMENT`). An unknown option gives code `UNKNOWN_OPTION`, with
+`Did you mean --x?` when one is close; a missing or unexpected option value
+gives `INVALID_ARGUMENT` (`--timeout needs a value.`,
+`--json does not take a value.`).
 `cf dns`, `cf waf` and `cf speed-settings` require `--customer-id` before
 they send a request, because One refuses these reads without it. `--style`
 applies only to `badge`.
@@ -56,9 +71,9 @@ issuer's `/.well-known/openid-configuration` (for production,
 | `login` | Device sign-in; `--no-open` for remote terminals. Signing in again with Identity first revokes and removes the sign-in it replaces (before the new device code), unless that one's last refresh had an uncertain result | One `GET /.well-known/oauth-protected-resource`. Identity: discovery, `POST /api/auth/device/code`, polling the token endpoint, then userinfo; you approve at `https://auth.vigilbase.com/device`. Legacy: One `POST /api/auth/device/code`, `POST /api/auth/device/token`, `GET /api/auth/get-session`; you approve at One's `/device` |
 | `login --token-stdin` | Check and save a token piped from a secret manager; the input is bounded and never echoed. A saved Identity sign-in is revoked and removed before the token is saved | One `GET /api/auth/get-session`; Identity revocation when a sign-in is saved |
 | `login --token <bearer>` | Older input, discouraged because arguments can appear in process lists and history. `VIGILBASE_ONE_TOKEN` also works; neither combines with `--token-stdin` | Same as `--token-stdin` |
-| `whoami` | Shows the saved session; signed out is a successful answer. Notes a CLI 0.2.0 `credentials.json` that is being ignored | Identity: discovery and userinfo (a refresh first if due). Legacy: One `GET /api/auth/get-session` |
-| `logout` | Revokes every saved Identity sign-in, signs a legacy session out, then deletes the credential files. A sign-in Identity has already ended counts as revoked; any other failed Identity revocation keeps every file | Identity: discovery, then `POST /api/auth/oauth2/revoke` per saved sign-in. Legacy: One `POST /api/auth/sign-out` (best effort) |
-| `doctor` | Checks the public API, your session and your saved sign-in independently; exits 1 if any check fails | `GET {base-url}/api/v1/agent/tools`. Signed out or legacy: One `GET /api/auth/get-session`. Identity: `GET {issuer}/.well-known/openid-configuration`, then the userinfo endpoint it names (One is not contacted); a refresh at the token endpoint first if the access token expires within 60 seconds |
+| `whoami` | Shows the saved session; signed out is a successful answer. Notes a CLI 0.2.0 `credentials.json` that is being ignored, and names a sign-in saved for another configuration (``A saved sign-in exists for One <origin>, Identity <issuer>, client ID <id>; pass the matching options or run `vigilbase login`.``). When Identity has ended the saved sign-in, it prints `Your saved sign-in was ended by Vigilbase Identity and has been removed.` on stderr and reports you as signed out | Identity: discovery and userinfo (a refresh first if due). Legacy: One `GET /api/auth/get-session` |
+| `logout` | Revokes every saved Identity sign-in, signs a legacy session out, then deletes the credential files. A sign-in Identity has already ended counts as revoked; any other failed Identity revocation keeps every file. JSON: `{success, cleared, warnings}`; `warnings` is `[]` when there are none | Identity: discovery, then `POST /api/auth/oauth2/revoke` per saved sign-in. Legacy: One `POST /api/auth/sign-out` (best effort) |
+| `doctor` | Checks the public API, your session and your saved sign-in independently; exits 1 if any check fails. `signIn` also fails for a sign-in saved for another One origin, Identity issuer or client ID | `GET {base-url}/api/v1/agent/tools`. Signed out or legacy: One `GET /api/auth/get-session`. Identity: `GET {issuer}/.well-known/openid-configuration`, then the userinfo endpoint it names (One is not contacted); a refresh at the token endpoint first if the access token expires within 60 seconds |
 
 Credentials are saved atomically with owner-only permissions in
 `identity-credentials.json` (Identity) or `credentials.json` (legacy One
@@ -74,21 +89,27 @@ logout, directory checks and the config directory.
 `{ok, url?, error?, status?, code?}`. `checks.one.url` is the endpoint it
 checked: One's `get-session`, the discovered userinfo endpoint, or the
 issuer's discovery URL when discovery itself failed. `checks.signIn` has no
-`url`.
+`url`. When a check fails, the top level has the first failing check's
+`error`, `status` and `code`.
 
 `whoami` JSON has `authenticated`, `oneBaseUrl`, `user`, `issuer`,
-`clientId`, `resource`, `organizationId`, `expiresAt`, `scope`, `obtainedAt`,
-`authRequiredTools` and `legacyIdentityFileIgnored`. `expiresAt` and `scope`
-are those of the access token in use, after any refresh `whoami` just made.
-`obtainedAt` is when you signed in; a refresh doesn't change it. Signed out,
-`expiresAt`, `scope` and `obtainedAt` are `null`.
+`clientId`, `resource`, `organizationId`, `savedFor`, `signInEnded`,
+`expiresAt`, `scope`, `obtainedAt`, `authRequiredTools` and
+`legacyIdentityFileIgnored`. `expiresAt` and `scope` are those of the access
+token in use, after any refresh `whoami` just made. `obtainedAt` is when you
+signed in; a refresh doesn't change it. Signed out, `issuer`, `clientId`,
+`resource`, `organizationId`, `expiresAt`, `scope` and `obtainedAt` are `null`.
+`savedFor` is `{oneBaseUrl, issuer, clientId}` when a sign-in is saved for
+another One origin, Identity issuer or client ID (`issuer` and `clientId` are
+`null` for a legacy session), otherwise `null`. `signInEnded` is `true` when
+Identity ended the saved sign-in during this command and its file was removed.
 
 `authRequiredTools` means something different per command. The names stay as
 they are so scripts keep working:
 
 | Command | `authRequiredTools` in JSON |
 | --- | --- |
-| `list`, `doctor` | Every tool that needs a One sign-in, whether you are signed in or not. In `list`, `oneExecutableTools` is what you can run through One now |
+| `list`, `doctor` | Every tool that needs a One sign-in, whether you are signed in or not. In `list`, `oneExecutableTools` is what you can run through One now, and `[]` when `authenticated` is false |
 | `whoami` | The tools your sign-in unlocks: the same tools when signed in, `[]` when signed out |
 | `login` | Every tool that needs a One sign-in; all of them are unlocked once login succeeds |
 
@@ -97,19 +118,45 @@ they are so scripts keep working:
 | Command | Options | API |
 | --- | --- | --- |
 | `list` (alias `tools`) | Lists the public catalog and the One-only scanners | GET `/api/v1/agent/tools` |
-| `run <tool> <target>` | `--via public\|one`; `--public` forces the public API | POST `/api/v1/agent/tools/<tool>/execute` (anonymous) or One POST `/api/tools/<tool>/execute` |
+| `run <tool> <target>` | `--via public\|one`; `--public` (or `--via public`) forces the public API for the public tools | POST `/api/v1/agent/tools/<tool>/execute` (anonymous) or One POST `/api/tools/<tool>/execute` |
 | `headers <url>` | Shortcut for `run security-headers`; same routing options | Same as `run` |
 | `email <domain>` | Shortcut for `run email-security`; same routing options | Same as `run` |
-| `describe <tool>` | `--no-skill` skips fetching skill Markdown | Catalog plus the tool's published skill URL |
+| `describe <tool>` | Prints the tool's full description and a `Target: <target format>` line; `--no-skill` skips fetching skill Markdown | Catalog plus the tool's published skill URL |
 | `skill <tool>` | Prints the complete published skill; JSON includes URL and content | Catalog plus the tool's skill URL |
 | `badge <domain>` | `--style default\|compact\|mini` | None; builds the public badge URL locally |
 
+`badge <domain>` takes a domain. A http(s) URL is reduced to its hostname;
+case, a trailing dot and a leading `www.` are ignored. Anything else exits 1
+with `Enter a domain such as vigilbase.com. Usage: vigilbase badge <domain>`
+before any output. JSON for `badge` is
+`{success: true, domain: <normalised hostname>, style, url}`; `describe` and
+`skill` JSON also start with `success: true`.
+
 Public tools: `security-headers`, `email-security`. One-only tools:
 `website-security`, `react2shell`, `fortibleed-check`. Tools aren't commands of
 their own: run them with `run <tool> <target>` (`vigilbase help <tool>` prints
 that usage offline). Public scans use the
 public API unless you add `--via one`; being signed in doesn't change that.
-`--public` and `--via one` cannot be combined.
+`--public` and `--via one` cannot be combined. A One-only tool with `--public`
+or `--via public` stops before any request with
+``website-security runs only through Vigilbase One: drop --public and run `vigilbase login`.``
+(or `drop --via public`). `run` refuses a tool name it doesn't know locally:
+``Unknown tool "<name>". Run `vigilbase list` for the allowlist.``
+(code `INVALID_ARGUMENT`), as `describe` does. The public API itself answers a One-only tool with 404
+`not_found` and an unknown name with the allowlist URL.
+
+`email <domain>` accepts a fully qualified name with a trailing dot and
+internationalised names (converted to punycode). Names under a public domain,
+such as `test.vigilbase.com`, are accepted; reserved suffixes (`.test`,
+`.example`, `.local`, `.internal`, `.invalid`, `.localhost` and similar) and IP
+addresses are refused by vigilbase.com.
+
+Public scans share an hourly quota of 20 scans per client IP address and 20 per
+target (1,000 an hour overall); the catalog's
+`rateLimit.scanQuota` describes it. When it is used up, the API answers 429
+`rate_limit_exceeded` with `Retry-After` set to the seconds until the quota
+resets (up to an hour), and the CLI exits 2 without retrying. A 503
+`service_unavailable` means only that scan storage is down.
 
 Public paths are relative to `--base-url`. CLI 0.2.1 and earlier call the
 unversioned `/api/agent/tools` instead, which vigilbase.com plans to retire on
@@ -121,15 +168,19 @@ that go through One (`--via one` and the One-only tools) need a sign-in.
 Without one they stop with this error:
 
 ```
-Error: This tool needs a Vigilbase One sign-in: run `vigilbase login`.
+Error: This command needs a Vigilbase One sign-in: run `vigilbase login`.
 ```
 
-Other sign-in errors keep their own message, with that sentence as the hint
-unless the message already says to run `vigilbase login`.
+With `--json` the error has code `NOT_SIGNED_IN`; every One command uses the
+same sentence and code. Other sign-in errors keep their own message, with that
+sentence as the hint unless the message already says to run `vigilbase login`.
+An unsafe or relative config path and Windows get no such hint: `login` would
+fail the same way, so they keep their own fix.
 
 `list` reads your saved sign-in from disk only (no refresh, no network, no wait
 for the lock). In JSON, `authenticated` says whether it looks usable and
-`oneExecutableTools` follows it. If it can't be used, `list` still prints the
+`oneExecutableTools` follows it: the tools you can run through One now, `[]`
+when signed out. If it can't be used, `list` still prints the
 catalog, shows you as signed out and prints one stderr line per run:
 ``Couldn't use your saved sign-in (<reason>); running anonymously. Run `vigilbase login` to fix.``
 For an unsafe config path or credentials file, which `login` would refuse too,
@@ -141,7 +192,23 @@ credentials file is there.
 When a public scan fails and vigilbase.com explains why with a known error
 code, the CLI prints `Error: <message> (<code>)` (JSON: `error`, `code`,
 `status`), with the message cleaned to one line of at most 300 characters.
-Otherwise it prints `Request failed (HTTP <status>).`
+Otherwise it prints a message of its own, never the server's text.
+
+When a scan run through Vigilbase One fails (One answers 422), the CLI prints
+`Error: The scan couldn't be completed. Try again later.` and exits 1. JSON
+has `success: false`, that `error`, `status: 422` and the `toolRunId` One
+recorded, for `vigilbase runs get <toolRunId>`.
+
+When the scanner ran but couldn't assess the target, for example because the
+site answered with a bot verification challenge or an error page, the CLI
+prints `✗ <tool> · <target> · n/a` and the scanner's reason on the next line,
+cleaned to one line of at most 300 characters, and exits 1. This looks the
+same on the public API and through One. JSON has `success: false`, that reason
+as `error`, `toolName`, `target`, `grade: null`, `gradeScore: null`, the
+scanner's `result`, `status: 422`, `code: "scan_unassessed"` and the
+`toolRunId` when one was recorded. Other public failures (for example a 400
+for an invalid target, or a 422 without a result) still print
+`Error: <message> (<code>)`.
 
 ## Account and billing
 
@@ -153,12 +220,12 @@ Otherwise it prints `Request failed (HTTP <status>).`
 | `account endpoints` | `endpoint` | GET `/api/account/endpoints` |
 | `account sessions` | `session` | GET `/api/account/sessions` |
 | `account invites` | `invitations`; optional `list` or `ls` | GET `/api/auth/orgs/invitations` |
-| `account invites create` | `add` alias; `--email <email>`, `--role <role>` (default member), required `--confirm` | POST `/api/auth/orgs/invite` |
+| `account invites create` | `add` alias; the email as `<email>` or `--email <email>` (not both), `--role <role>` (default member), required `--confirm`. Usage: `vigilbase account invites create <email>\|--email <email> [--role <role>] --confirm` | POST `/api/auth/orgs/invite` |
 | `account billing` | Same as the billing commands | Same as billing |
 | `billing` | `summary`, `show`, `status` | GET `/api/account/billing` |
 | `billing portal` | `open`; `--no-open` prints the portal URL without opening a browser | POST `/api/billing/portal` |
 
-Invitations need a One browser session: Identity's management API doesn't accept CLI sign-ins, so `account invites` and `account invites create` answer 403 (`browser_session_required`) and the CLI points you to https://one.vigilbase.com.
+Invitations need a One browser session: Identity's management API doesn't accept CLI sign-ins, so `account invites` and `account invites create` answer 403 (`browser_session_required`): the CLI prints `You don't have access to this.` and points you to https://one.vigilbase.com.
 
 Creating an invitation sends it; `billing portal` starts a Stripe portal
 session. Both are explicit actions. Billing data comes from One's Stripe
@@ -181,6 +248,11 @@ Stripe's billing host before they are printed, opened or put in JSON.
 | `watchdog` | `list`, `targets`, `status` | GET `/api/account/watchdog/targets` |
 | `watchdog scans` | `scan`; `--target-id <UUID>`, `--limit <n>` (1–100, default 20) | GET `/api/account/watchdog/scans` |
 
+Text output prints full IDs: the first column of `runs list` works with
+`runs get`, `watchdog scans` and `account sessions` show complete IDs, and
+`watchdog list` rows are `<target id>  <domain>  <uptime status>  24h=<uptime>`,
+whose target ID is what `watchdog scans --target-id` takes.
+
 Customer-specific Watchdog and monitoring views are in ONE.md.
 
 ## Local Cloudflare Checkup (no sign-in)
@@ -191,7 +263,7 @@ All vigilbase.com paths below are under
 | Command | Options | Requests |
 | --- | --- | --- |
 | `cloudflare-checkup` (≡ `local cloudflare-checkup [run]`) | `--email`, `--account-id`, `--out`, `--overwrite`, `--yes`, `--confirm`, `--no-open`, `--cf-auth auto\|profile\|env\|default` (default `auto`), `--profile`, `--cf-bin`, `--max-requests-per-5min`, `--base-url` (vigilbase.com or loopback), `--timeout` | In order: GET `…/availability` (before the email is asked for), POST `…/request` and `…/verify` (email verification), GET `…/local-session` (before cf runs), allowlisted read-only cf commands, GET `…/local-session` again and POST `…/local-session/snapshot` after you confirm. npm only to install the pinned cf when none is usable (asks first) |
-| `cloudflare-checkup login` | `--profile`, `--no-open`, `--dry-run`, `--cf-bin` | Runs `cf auth create <profile> --scopes …` interactively |
+| `cloudflare-checkup login` | `--profile`, `--no-open`, `--dry-run`, `--cf-bin` | Runs `cf auth create <profile> [--no-browser] --scopes …` interactively (`--no-browser` comes from `--no-open`) |
 | `cloudflare-checkup doctor` | `--cf-auth`, `--profile`, `--cf-bin` | Offline cf mapping check, one `cf auth whoami` |
 | `cloudflare-checkup accounts` | `--cf-auth`, `--profile`, `--cf-bin` | `cf accounts list` (all pages) |
 | `cloudflare-checkup collect` | `--out` (required), `--account-id`, `--overwrite`, `--dry-run`, `--max-requests-per-5min`, cf options | Allowlisted read-only cf commands; writes the snapshot |
@@ -215,25 +287,39 @@ vigilbase.com emails a 6-digit code, and the CLI asks for the code (without a
 terminal, both are read from stdin, one line each; add `--yes`). In a terminal
 both show an interactive timeline on stderr (inputs, arrow-key questions,
 spinners, a collection progress bar); pipes, CI, `TERM=dumb` and `--json` keep
-plain lines and prompts. Ctrl-C exits 130. The address, the code and the
-session code are never echoed, logged, stored or passed to cf or npm. cf output
-and stderr are never echoed; failures carry a stable `code` and a `hint` that
-usually says to run the same command again. See LOCAL.md for the email
+plain lines and prompts. Ctrl-C exits 130 (SIGTERM 143, SIGHUP 129), and a
+cancelled run never uploads. The address, the code and the session code are
+never echoed, logged, stored or passed to cf or npm. cf output and stderr are
+never echoed; failures carry a stable `code` (in plain text after the message,
+for example `Error: Local checkups aren't available right now. (LOCAL_MODE_DISABLED)`)
+and a `hint` that usually says to run the same command again. See LOCAL.md for the email
 verification, the managed cf install, the allowlist, the environment policy,
 the uploaded data and the error codes.
 
 ## Output and effects
 
 Exit codes: **0** success, **1** validation, API, network or sign-in failure,
-**2** HTTP 429 rate limiting. A completed scan whose result is unsuccessful
-also exits 1. A signed-out `whoami` is not a failure, and a healthy `doctor`
-does not need a sign-in. API error JSON keeps the status, code and retry delay
-when available.
+**2** HTTP 429 rate limiting; `cloudflare-checkup` also exits **130**, **143**
+or **129** when cancelled by SIGINT (Ctrl-C), SIGTERM or SIGHUP (128 + the
+signal number). A graded scan exits 0 whatever the grade. Its first line starts
+with `✓` only when the result's `status` is `"secure"` and the grade isn't F;
+otherwise it starts with `•`. Scripts should gate on `.grade` or
+`.result.status`. When vigilbase.com returns a shareable report link, text
+output ends with `  Report: <url>`. A scan that failed exits 1. So does a scan
+the scanner could not grade (result `status` `"error"`, no grade): it prints
+`✗ <tool> · <target> · n/a` and the scanner's message, cleaned to one line of
+at most 300 characters, and JSON has `success: false` with that message as
+`error`. A signed-out `whoami` is not a failure, and a healthy `doctor` does
+not need a sign-in. API error JSON keeps the status, code and retry delay when
+available.
 
 Vigilbase One's error messages are never shown, because they can describe
-One's configuration: the CLI prints `Request failed (HTTP <status>).` When it
-recognises the failure from the route, the status and One's error code, it adds
-a hint of its own (`Hint: …` in text, `hint` in JSON):
+One's configuration. The CLI prints its own message for the status instead:
+``Authentication required. Run `vigilbase login`.`` (401),
+`You don't have access to this.` (403), `Rate limit exceeded.` (429) and
+`Request failed (HTTP <status>).` otherwise. When it recognises the failure
+from the route, the status and One's error code, it adds a hint of its own
+(`Hint: …` in text, `hint` in JSON):
 
 | One answers | Hint |
 | --- | --- |

package/LOCAL.md

@@ -15,7 +15,7 @@ before it asks for your email; when local mode is off it stops with
 your browser at <https://vigilbase.com/tools/cloudflare-checkup>.
 
 `vigilbase cf checkup` runs on Vigilbase One's servers with stored credentials
-(see [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md));
+(see [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/CLOUDFLARE.md));
 `vigilbase cloudflare-checkup` runs on your machine and needs no Vigilbase
 login.
 
@@ -33,8 +33,9 @@ of the CLI (0.1.x) is running instead: `npx` prefers an installed global
 `@vigilbase/cli`. Run `npx @vigilbase/cli@latest cloudflare-checkup` once, or
 update the global install with `npm install -g @vigilbase/cli@latest`. With
 Yarn 4.15+ or pnpm 11+, `yarn dlx` and `pnpm dlx` run an older release for a
-day after each release; use `npx` (see
-[Troubleshooting](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md#troubleshooting)).
+day after each release, and pnpm 10.16+ with `minimumReleaseAge` set refuses
+the new version; use `npx` (see
+[Troubleshooting](https://app.unpkg.com/@vigilbase/cli@0.2.4/files/README.md#troubleshooting)).
 
 The command does everything, in this order, and stops at the first problem
 before any slower step:
@@ -158,17 +159,34 @@ and `vigilbase local cloudflare-checkup run` are the same command.
 Before anything slow, the command checks every flag (no I/O, and `--email`
 only for its shape), that its questions can be answered (on a terminal, or
 with `--yes` without one; `--confirm` answers only the upload question, not
-installing cf), then Node, then that `--out` is writable, then that
-vigilbase.com has local checkups on and accepts this CLI. So no code is emailed
-for a run that could not install cf, confirm the upload or be accepted. It
-verifies your email before cf runs, and checks that the snapshot location is
-writable before collecting, so a long collection is never wasted.
+installing cf), then Node. Then, before it contacts vigilbase.com at all, it
+checks what it can locally:
+
+- with `--cf-auth env`, that `CLOUDFLARE_API_TOKEN` is set
+  (`CF_AUTH_REQUIRED`);
+- `--out`: a directory gives `OUTPUT_EXISTS` with
+  `--out names a directory; it must name a regular file. Nothing was collected.`,
+  and any existing entry, a dangling symbolic link included, gives
+  `OUTPUT_EXISTS` without `--overwrite`. With `--overwrite` a symbolic link is
+  replaced, never followed, unless it points to a directory;
+- without `--out`, that `<config dir>/checkups` can be created (it isn't
+  created yet, so a run that stops here writes nothing);
+- a given `--cf-bin` exists and is Cloudflare's cf (`CF_NOT_FOUND`,
+  `CF_WRONG_BINARY`; nothing is run).
+
+Only then does it ask whether vigilbase.com has local checkups on and accepts
+this CLI. So no code is emailed for a run that could not install cf, confirm
+the upload, write the snapshot or be accepted. It verifies your email before cf
+runs, and checks that the snapshot location is writable before collecting, so a
+long collection is never wasted. `submit` checks the file first, and after the
+availability answer, before it asks for the email, refuses a snapshot over the
+size or zone limit vigilbase.com announced (`SNAPSHOT_TOO_LARGE`).
 
 Two problems can show only once cf runs, after the email was verified: without
-a terminal, a missing cf login (`CF_AUTH_REQUIRED`) and several accounts
-without `--account-id` (`ACCOUNT_SELECTION_REQUIRED`). Running the command
-again with the same address then waits for vigilbase.com's 8 minutes per
-address (the hint says so). In scripts, sign in first (run
+a terminal, a missing cf login in profile mode (`CF_AUTH_REQUIRED`) and several
+accounts without `--account-id` (`ACCOUNT_SELECTION_REQUIRED`). Running the
+command again with the same address then waits for vigilbase.com's 8 minutes
+per address (the hint says so). In scripts, sign in first (run
 `npx @vigilbase/cli cloudflare-checkup login` in a terminal, or set
 `CLOUDFLARE_API_TOKEN`) and pass `--account-id`.
 
@@ -185,7 +203,9 @@ never answered from stdin: use `--account-id` and `--yes`.
 In a terminal, the one command and `submit` show their steps as a timeline on
 stderr (◆ the current step, ◇ a finished one, │ notes, ▲ a warning, ■ the error
 that stopped the run, └ the result). Spinners run while the CLI checks that
-local checkups are available, while vigilbase.com sends or checks the code,
+local checkups are available (`Checking vigilbase.com`, or the host of a
+loopback `--base-url` such as `Checking 127.0.0.1:3001`), while vigilbase.com
+sends or checks the code,
 while the session is checked, while cf is found, checked and installed, and
 while the upload is scored; a progress bar runs while
 collecting (zones done, cf reads done of the estimate, and the time left, from
@@ -223,7 +243,8 @@ the terminal width, also after a resize.
   stdout as well.
 - Ctrl-C at any point gives the terminal back (raw mode off, cursor shown),
   says what happened (for example `Cancelled. Nothing was uploaded.`) and
-  exits 130. Errors and SIGTERM give the terminal back too.
+  exits 130. While cf or npm runs, Ctrl-C, SIGTERM and SIGHUP stop them and
+  exit 130, 143 and 129. Errors and SIGTERM give the terminal back too.
 
 The plain output (the second transcript in the quick start: the
 `Work email for your results:`, `Code from the email:` and
@@ -253,7 +274,12 @@ on this path.
   and the hint
   `Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup`.
   Nothing is emailed and cf is not touched. If vigilbase.com needs a newer CLI
-  or doesn't accept this snapshot format, it stops with `CLI_UPGRADE_REQUIRED`.
+  or doesn't accept this snapshot format, it stops with `CLI_UPGRADE_REQUIRED`:
+  `vigilbase.com requires @vigilbase/cli <version> or newer for this snapshot.`
+  (the hint names `@latest`), or
+  `vigilbase.com does not accept snapshots in the <schemaVersion> format.`
+  with the hint
+  ``Collect a fresh snapshot with the latest CLI: `npx @vigilbase/cli@latest cloudflare-checkup`.``
   If vigilbase.com doesn't answer the check (for example a network error or a
   timeout, after 10 seconds or `--timeout`), the command goes on, and the same
   checks happen when the checkup starts.
@@ -362,8 +388,8 @@ it stops with `CF_NOT_FOUND`).
   The checkup runs none of those commands, so the install is about 75 MB.
 - **Failures:** no npm → `CF_INSTALL_FAILED` with the manual
   `npm install --global cf@1.0.0-beta.13` fallback; then run the command again.
-- **Interruptions:** Ctrl-C while npm runs stops npm and deletes the staging
-  directory. A staging directory left by a crash or a closed terminal is
+- **Interruptions:** Ctrl-C (or SIGTERM or SIGHUP) while npm runs kills npm,
+  deletes the staging directory and exits 130 (143, 129). A staging directory left by a crash or a closed terminal is
   deleted by the next install once it is older than npm's 10-minute timeout,
   and by `logout`.
 
@@ -430,14 +456,28 @@ used a loopback `--base-url`, that command ends with the same `--base-url`.
 All are `vigilbase cloudflare-checkup <command>` or
 `vigilbase local cloudflare-checkup <command>`. They keep their own defaults
 (`--cf-auth profile`, no cf install, no sign-in). They find a cf installed by
-the one command. `collect --dry-run` prints every cf command with
+the one command. A flag a subcommand doesn't take fails with
+`--<flag> is not supported for cloudflare-checkup <subcommand>.` before
+anything runs. `collect --dry-run` prints every cf command with
 `<ZONE_ID>`/`<RULESET_ID>` placeholders, the child-environment variable names
 (never values), the not-collected list and the request formula; it makes no
-Cloudflare and no Vigilbase requests. `submit` checks the file, checks that
+Cloudflare and no Vigilbase requests. It warns as a real collect would: in env
+mode without `CLOUDFLARE_API_TOKEN` it warns with code `CF_AUTH_REQUIRED`
+(`… Without it, a real collect would stop here.`, exit 0), and in profile or
+default mode with the variable set it warns `ENV_TOKEN_NOT_USED`.
+`login --dry-run --cf-bin <path>` checks the path (`CF_NOT_FOUND`,
+`CF_WRONG_BINARY`) without running cf. `submit` checks the file, checks that
 vigilbase.com has local checkups on, verifies your email like the one command,
 then uploads a snapshot collected earlier (accepted for 24 hours) and prints
 the results link.
 
+`inspect` validates a snapshot and shows what it contains. When the snapshot
+can no longer be uploaded it adds `Upload     no longer accepted (collected more than 24 hours ago)`
+or `Upload     not accepted (dated in the future)`, and above 4 MiB it warns
+`The snapshot is larger than 4 MiB, the default upload limit.` Control
+characters in a file name are shown as escapes (`\n`, `\u001b`) in the
+`Snapshot` line of `inspect` and `submit`.
+
 `logout` runs `cf auth delete <profile>` through the cf it finds (an
 interactive passthrough, so cf's own message is shown; cf 1.0.0-beta.13 takes
 only the profile name, refuses `--profile` and a set `CLOUDFLARE_API_TOKEN`,
@@ -513,8 +553,10 @@ passed.
 | page rules, bot management, page shield | `page-rules list --zone Z`, `bot-management get --zone Z`, `client-side-security settings get --zone Z` | single |
 | API Shield | `api-security schema-validation settings get --zone Z`, `api-security schema-validation schemas list --zone Z --omit-source --per-page 100 --page N` | single / until an empty page |
 
-The only other cf argv are `--version`, `auth whoami`, `auth create <p> --scopes …`
-(sign-in, interactive) and `auth delete <p>` (logout, interactive).
+The only other cf argv are `--version`, `auth whoami`,
+`auth create <p> [--no-browser] --scopes …` (sign-in, interactive;
+`--no-browser` comes from `login --no-open`) and `auth delete <p>` (logout,
+interactive).
 
 Before collecting (the one command, `collect`, `collect --dry-run`) and in `doctor`, every template
 runs once with `--dry-run` and placeholder IDs (no credentials, no network);
@@ -538,7 +580,9 @@ are recorded as `possibly_truncated`.
 ## Process and environment policy
 
 - cf runs from a private, empty `0700` temporary directory that is removed
-  afterwards (and on Ctrl-C). Your project's `.env`, `.env.local`,
+  afterwards (and on Ctrl-C, SIGTERM or SIGHUP: cf children get SIGTERM, then
+  SIGKILL after 2 s). A cancelled run never prints a result, and never writes
+  or uploads a snapshot. Your project's `.env`, `.env.local`,
   `cloudflare.config.ts`, directory profile bindings and cf's account cache never
   apply. `CF_DELEGATION=1` stops cf from handing off to a project-local cf.
 - cf's environment is built from an empty object. Copied by name if present:
@@ -551,7 +595,8 @@ are recorded as `possibly_truncated`.
   DO_NOT_TRACK=1 CF_DELEGATION=1` (telemetry off, no prompts, no update checks).
 - `CLOUDFLARE_API_TOKEN` is passed only with `--cf-auth env`, and only to API
   reads (absent → `CF_AUTH_REQUIRED`). In profile and default modes it is removed,
-  because it would override `--profile`; a notice says so.
+  because it would override `--profile`; a notice says so (`ENV_TOKEN_NOT_USED`).
+  `collect --dry-run` lists it in `childEnv` only when it is set.
 - Never passed, by construction: `CLOUDFLARE_API_BASE_URL`, `CF_API_BASE_URL`
   (the primary control against redirecting your token), `CLOUDFLARE_COMPLIANCE_REGION`,
   `CLOUDFLARE_CLIENT_ID`, `CLOUDFLARE_ZONE_ID`, `CLOUDFLARE_ACCESS_CLIENT_ID/SECRET`,
@@ -616,8 +661,8 @@ Each cf response is projected immediately and the raw text discarded. The file
 - zone settings' values, DNSSEC status/algorithm, Universal SSL/Total TLS/page
   shield `enabled`;
 - DNS A/AAAA records with **pseudonymised IPs** (the first two IPv4 or three IPv6
-  groups are kept, the host part becomes a per-prefix counter); names only for
-  non-proxied records;
+  groups are kept, the host part becomes a per-prefix counter,
+  `per_prefix_sequential/1`); names only for non-proxied records;
 - ruleset `id, phase`, `name: 'ddos'` markers, and rules reduced to action,
   `enabled:false`, a `true`/geo-block expression marker, managed-ruleset IDs and
   name keywords; IDs and descriptions only on disabled managed rules and
@@ -632,6 +677,12 @@ file is validated and checked for credential-shaped values (session codes,
 verification tokens, API tokens, JWTs, PEM blocks, bearer strings). `inspect` shows counts of every
 free-text category.
 
+The pseudonymisation is checked, not just claimed: `inspect` and `submit`
+refuse a file whose DNS record contents are not numbered 1, 2, 3… within each
+prefix without gaps (`SNAPSHOT_INVALID`, issue `ip_not_pseudonymized`), and vigilbase.com
+refuses such an upload too. A real address that looks like the first
+pseudonym of its prefix (for example `10.0.0.1`) can't be told apart.
+
 **Projection predicates (disclosure).** To minimise uploads, the projections
 encode selection rules that mirror some checks: which rules count as issue
 rules, the geo-block marker, what makes an access rule broad, the legacy
@@ -656,15 +707,23 @@ collected**. Run the token-based checkup in the browser to include them.
 
 Exit codes: **0** success (any grade, replay, file written, dry run, healthy
 doctor), **1** any other error, **2** `CF_RATE_LIMITED` or a vigilbase.com 429
-(`VIGILBASE_RATE_LIMITED`), **130** cancelled with Ctrl-C. Errors print `code` and a `hint`; JSON errors are
-`{success:false, error, code, status?, retryAfterSec?, hint?}`. Server messages
-are never echoed.
+(`VIGILBASE_RATE_LIMITED`), **130** cancelled with Ctrl-C (SIGINT), **143**
+cancelled by SIGTERM, **129** cancelled by SIGHUP (a closed terminal). Errors
+print `code` and a `hint`. Plain-text errors end with the code in parentheses,
+for example
+`Error: Local checkups aren't available right now. (LOCAL_MODE_DISABLED)`,
+followed by `Hint: …`. JSON errors are
+`{success:false, error, code, status?, retryAfterSec?, hint?}`; a cancelled
+command prints
+`{"success":false,"error":"Cancelled.","code":"CANCELLED","hint":"Nothing was uploaded. Run the same command again when you are ready."}`.
+Server messages are never echoed.
 
 | Code | Fix |
 | --- | --- |
 | `NODE_UNSUPPORTED` | Install Node.js 22.18 or newer from https://nodejs.org, then run the same command again. |
-| `CF_NOT_FOUND` | Run the same command again in a terminal and let it install cf (or add `--yes`), or `npm install --global cf@1.0.0-beta.13`. |
-| `CF_WRONG_BINARY` | Another `cf` (Cloud Foundry, or a pnpm/Volta shim) was found; run the command without `--cf-bin` and let it install cf, or pass `--cf-bin`. |
+| `CWD_UNAVAILABLE` | The current directory no longer exists or cannot be read. Change to a directory that exists and that you can read (for example `cd ~`), then run the same command again. |
+| `CF_NOT_FOUND` | From the one command: run it again in a terminal and let it install cf (add `--yes` when no terminal is available), or `npm install --global cf@1.0.0-beta.13`. From `login`, `doctor`, `accounts`, `collect`, `logout`, and from `run` with `--cf-bin`: run `npx @vigilbase/cli cloudflare-checkup` without `--cf-bin` (it can install cf), install cf with `npm install --global cf@1.0.0-beta.13`, or pass `--cf-bin <path>` to a cf package. |
+| `CF_WRONG_BINARY` | Another `cf` (Cloud Foundry, or a pnpm/Volta shim) was found; run the command without `--cf-bin` and let it install cf, or pass `--cf-bin "$(npm root -g)/cf"`. When the cf package was found but `cf --version` fails, the message is `cf --version failed; the package may be damaged.`: reinstall cf with `npm install --global cf@1.0.0-beta.13`, or run `npx @vigilbase/cli cloudflare-checkup` without `--cf-bin` and let it install the tested cf. |
 | `CF_UNSUPPORTED_VERSION` | Run the same command again without `--cf-bin` and let it install the tested cf. |
 | `CF_ALLOWLIST_MISMATCH` | This cf release renamed a required command; run the same command again without `--cf-bin` and let it install the tested cf for Vigilbase (your own cf is left alone). |
 | `CF_INSTALL_FAILED` | npm is missing or failed, or the download did not match the pinned integrity; `npm install --global cf@1.0.0-beta.13`, then run the same command again. |
@@ -672,14 +731,16 @@ are never echoed.
 | `CF_PERMISSION_DENIED` | Your Cloudflare login cannot read the zones; check its permissions, then run the same command again. With `CLOUDFLARE_API_TOKEN` set (env mode), add the read permissions to the token, or unset it (or use `--cf-auth profile`) to sign in with your browser. |
 | `CF_RATE_LIMITED` | Wait 5 minutes, then run the same command again; add `--max-requests-per-5min 600` if it repeats. |
 | `CF_ERROR` | Run the same command again in a few minutes. |
+| `CANCELLED` | Cancelled with Ctrl-C (or SIGTERM or SIGHUP). Nothing was uploaded. Run the same command again when you are ready. |
 | `ACCOUNT_SELECTION_REQUIRED` | Run the same command again in a terminal to choose, or add `--account-id <ACCOUNT_ID>` (listed in the error). |
 | `ACCOUNT_NOT_VISIBLE` | Check that your Cloudflare user can read the account and its zones. |
-| `ACCOUNT_TOO_LARGE` | Over 100 zones: run the checkup in your browser instead, https://vigilbase.com/tools/cloudflare-checkup. |
+| `ACCOUNT_TOO_LARGE` | Local collection supports up to 100 zones. Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup |
 | `ACCOUNT_MISMATCH` | The checkup is bound to another account; run the same command again without `--account-id`. |
-| `OUTPUT_EXISTS` | Choose another `--out`, or pass `--overwrite`. |
-| `SNAPSHOT_INVALID` / `SNAPSHOT_SECRET_LIKE_VALUE` | Run the same command again (remove the credential-like text from the rule or name first). When `inspect` or `submit` finds no file at the path, check the path, or collect one with `npx @vigilbase/cli cloudflare-checkup collect --out <file>`. |
-| `SNAPSHOT_TOO_LARGE` | Run the checkup in your browser instead, https://vigilbase.com/tools/cloudflare-checkup. |
-| `SNAPSHOT_STALE` | Snapshots are accepted for 24 hours; run the same command again. |
+| `OUTPUT_EXISTS` | Choose another `--out`, or pass `--overwrite`. A directory (or other special file) as `--out` can't be replaced: name a regular file. |
+| `SNAPSHOT_INVALID` | From `run` or `collect`: run the same command again to collect a fresh one. From `inspect`, `submit` (and the re-read before the one command uploads): the file is not a valid snapshot; collect a fresh one with `npx @vigilbase/cli cloudflare-checkup` (or `npx @vigilbase/cli cloudflare-checkup collect --out <file>`). `The snapshot file does not exist.` or `The snapshot path is a symbolic-link loop.`: check the path, or collect one with `collect --out <file>`. `The snapshot file cannot be read (permission denied).`: check the permissions of the file and of its directories, or copy it somewhere you can read it. |
+| `SNAPSHOT_SECRET_LIKE_VALUE` | From `run` or `collect`: remove it from your Cloudflare settings (a name, description or other text field), then run the same command again. From a file: remove the credential-like value from your Cloudflare settings and collect a fresh snapshot. |
+| `SNAPSHOT_TOO_LARGE` | The snapshot is over the upload limit. Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup |
+| `SNAPSHOT_STALE` | Snapshots are accepted for 24 hours. From `run`, run it again; from `submit`, collect a fresh one with `npx @vigilbase/cli cloudflare-checkup`. |
 | `EMAIL_INVALID` | Use your work email (personal and disposable addresses are refused), then run the same command again. |
 | `EMAIL_CODE_INVALID` | Five codes were wrong or not 6 digits; run the same command again for a new code. |
 | `VERIFICATION_INVALID` / `VERIFICATION_EXPIRED` | The code expired, was tried too often, or the checkup closed; run the same command again for a new code. |
@@ -688,7 +749,7 @@ are never echoed.
 | `SESSION_BUSY` | A snapshot for this checkup is still being processed; wait for the results email, or run the same command again. |
 | `SUBMIT_ORIGIN_UNTRUSTED` | Upload only to https://vigilbase.com (or loopback for testing). |
 | `CONFIRMATION_REQUIRED` | Run the command in a terminal, or add `--yes` (and, without `--email`, pipe the address and the code to stdin). |
-| `CLI_UPGRADE_REQUIRED` | vigilbase.com needs a newer CLI (checked before your email is asked for). Run `npx @vigilbase/cli@latest cloudflare-checkup`, or `npm install --global @vigilbase/cli@latest`. |
+| `CLI_UPGRADE_REQUIRED` | vigilbase.com needs a newer CLI, or doesn't accept the snapshot's format (checked before your email is asked for). Run `npx @vigilbase/cli@latest cloudflare-checkup`, or `npm install --global @vigilbase/cli@latest`. |
 | `LOCAL_MODE_DISABLED` | Local checkups aren't available right now. Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup. |
 | `VIGILBASE_RATE_LIMITED` | Wait as long as the error says (`retryAfterSec` in JSON), then run the same command again. |
 | `VIGILBASE_CHALLENGED` | vigilbase.com challenged the request; try another network or contact help@vigilbase.com. |
@@ -698,11 +759,11 @@ JSON success payloads (stdout):
 
 - `collect`: `{success, snapshot:{path,bytes,sha256,schemaVersion,accountId,zoneCount,entries:{total,ok,httpError,notCollected,collectionFailed}}, cf:{version,authSource}, cfInvocations, durationMs, warnings:[{code,message}]}`
 - `collect --dry-run`: `{success, dryRun:true, cf:{version,path,tested}, plan:{accountSelection,account,perZone,perRuleset,notCollected}, verified:{commands,mismatched}, childEnv, requestFormula, warnings}`
-- `inspect`: `{success, snapshot:{path,bytes,sha256,schemaVersion,accountId,accountName,zoneCount,collectedAt,collector}, entries:{byKind}, dataCategories:{memberEmails,accessRuleValues,dnsHostnames,pseudonymizedIps,ruleDescriptions}}`
+- `inspect`: `{success, snapshot:{path,bytes,sha256,schemaVersion,accountId,accountName,zoneCount,collectedAt,collector,uploadable,notUploadableReason?}, entries:{byKind}, dataCategories:{memberEmails,accessRuleValues,dnsHostnames,pseudonymizedIps,ruleDescriptions}, warnings}`; `notUploadableReason` (`older_than_24_hours` or `dated_in_the_future`) only when `uploadable` is false; `warnings` may hold `SNAPSHOT_OVER_DEFAULT_UPLOAD_LIMIT`
 - `submit`: `{success, replayed, snapshotSha256, provenance, report, resultsUrl?}`; `resultsUrl` is the results page when vigilbase.com returned one; never the email address, a code, a token or the session code
 - the one command (`cloudflare-checkup`, `run`): the `submit` fields plus `snapshot` (as in `collect`) and `warnings`
 - `logout`: `{success, profile:{name,removed,problem?}, managedCf:{path,removed,kept?}, warnings, hint?}`; `success` is false (exit 1) when cf could not run (`problem`)
-- `doctor`: `{success, node:{version,supported}, cf:{found,path,version,supported,tested,identityVerified}, auth:{source,profile,authenticated,expiresAt?,scopes,missingRecommendedScopes?,writeScopeCount?}, commands:{verified,mismatched}, warnings, problems}`
+- `doctor`: `{success, node:{version,supported}, cf:{found,path,version,supported,tested,identityVerified}, auth:{source,profile,authenticated,checked,expiresAt?,scopes,missingRecommendedScopes?,writeScopeCount?}, commands:{verified,mismatched}, warnings, problems}`; `auth.checked` is false (and `authenticated` false) when cf was not found or could not run, and the text says `not checked (cf not found)` or `not checked (cf could not run)`
 - `accounts`: `{success, accounts:[{id,name}]}`
 
 ## Windows, pnpm and Volta