@pithy-sh/cli 0.1.0

package/src/docs/catalog.ts

@@ -0,0 +1,246 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { KitErrorPayload } from "@pithy-sh/core/src/error/payload";
+import type { ArgsDef, CommandDef } from "citty";
+import { CATALOG } from "../capabilities/catalog";
+import { HIDDEN_ROOT_FLAGS } from "../commands/alias";
+import { main } from "../main";
+import { ROOT_FLAGS } from "../rootFlags";
+
+/**
+ * What the kit contains, as one file another repository can read.
+ *
+ * `pithy.sh/docs` is 360 pages of hand-written reference and nothing verifies it. The site's own harness
+ * (`marketing/scripts/check/run.mjs`) is where that verification goes — three questions, each answerable
+ * only from here: does every `pithy add <name>` on a page name a real capability, does every flag a page
+ * cites exist in that command's parser, and does every error code a page quotes exist in the kit.
+ *
+ * **The shape of the answer is a decision for this repository, and this is it.** The site's slug check
+ * already asks the first question, and it asks it by reading `capabilities/catalog.ts` off an absolute
+ * path and running a regular expression over the TypeScript. That has failed the way regular expressions
+ * over source fail: the character class was `[a-z-]`, `i18n` has a digit in it, and the catalog entry
+ * simply did not match — so `pithy add i18n` read as an unknown slug on every page that stated it. The
+ * check carries a `names.length < 10` tripwire because a partial read is otherwise indistinguishable
+ * from a complete one.
+ *
+ * So the export is generated from the values themselves — the catalog array, the composed citty tree,
+ * the error union — and committed as strict JSON. A consumer parses it; there is no shape to guess at
+ * and no partial read to detect.
+ *
+ * **JSON, not JSONC**, which is the one place this departs from the repository's config rule: the reader
+ * is another repository's `JSON.parse`, and that tool does not recognize comments. The rationale lives
+ * here, in the generator, which is where `docs/catalog.generated.json` sends anyone who opens it.
+ */
+
+/** Where the generated file lives, relative to the repository root. One string, so nothing spells it twice. */
+export const CATALOG_PATH = "docs/catalog.generated.json";
+
+/** The note the file opens with. See {@link DocsCatalog.$generated} for why it is a field and not a comment. */
+const GENERATED_NOTE =
+  "Generated by packages/cli/src/docs/writeCatalog.ts. Do not edit by hand; run `bun run docs-catalog`. " +
+  "Strict JSON rather than JSONC because the reader is another repository's JSON.parse — see " +
+  "packages/cli/src/docs/catalog.ts for what each section answers.";
+
+/** One capability, as `pithy add` accepts it. */
+export interface CatalogCapability {
+  /** The `pithy add <name>` argument. */
+  name: string;
+  /** The npm package it ships in — `@pithy-sh/<name>` for all but `controlplane`, which ships inside core. */
+  package: string;
+}
+
+/** One command in the tree: the path a caller types, and the flags its parser accepts. */
+export interface CatalogCommand {
+  /** Space-separated, from the root down — `add`, `token mint`. The root itself is not a command. */
+  path: string;
+  /** Every flag spelling the parser answers to: the long form, then any aliases. */
+  flags: string[];
+}
+
+/** One error code the kit defines, and the HTTP status its member pins. */
+export interface CatalogErrorCode {
+  /** `domain/reason`, namespaced per capability. */
+  code: string;
+  /** The status the kit pins to this code. Every kit member pins exactly one. */
+  status: number;
+}
+
+/**
+ * Everything a docs check needs to know about the kit.
+ *
+ * **`commands` answers whether a flag exists on a command, not whether a page may name it.** A page
+ * legitimately cites another command's flag — `docs/commands/deploy.md` writes `pithy provision --env
+ * <name> --yes` while explaining what deploy refuses to do — and prose quotes flags belonging to
+ * neither (`git rev-parse --git-common-dir`). So a consumer matches `<command> --flag` as a pair.
+ * Attributing every flag on a page to that page's command reports correct pages as wrong, which is
+ * worse than no check at all: one that cries wolf gets turned off.
+ */
+export interface DocsCatalog {
+  /**
+   * What this file is, for whoever opens it.
+   *
+   * A generated file says so at the top, and every other one this repository generates says it in a
+   * comment. This one cannot: strict JSON has no comments, and the reason it is strict JSON is the
+   * reader. So the note is a field. It is first because that is where a reader looks, and a consumer
+   * that reads the sections by name never sees it.
+   */
+  $generated: string;
+  capabilities: CatalogCapability[];
+  commands: CatalogCommand[];
+  /** Flags that work on any command, declared by no command — `bin.ts` answers them before citty parses. */
+  globalFlags: string[];
+  errorCodes: CatalogErrorCode[];
+}
+
+/**
+ * Every flag the CLI parses outside a command's `args`, in every spelling.
+ *
+ * A walk of the command tree cannot find one of these: `bin.ts` answers all six before citty is handed
+ * the arguments. So `pithy add --help` and `pithy --pithiest` both cite something real, and a check
+ * reading only the parsers would call each a typo — on a page that is correct.
+ *
+ * **Composed from the modules that decide, never restated.** The two hidden flags were missed on the
+ * first pass, and a literal list here would go stale the same way the moment a seventh landed: hidden
+ * from `--help` is not hidden from a docs check, and nothing would have said so. `ROOT_FLAGS` and
+ * `HIDDEN_ROOT_FLAGS` are exported for this, so a new out-of-band flag reaches the export with nothing
+ * to remember.
+ */
+const GLOBAL_FLAGS: readonly string[] = [...ROOT_FLAGS, ...HIDDEN_ROOT_FLAGS];
+
+/** One arg's declared aliases, in the spelling a caller types: a single letter takes one dash, a word takes two. */
+function aliasFlags(alias: unknown): string[] {
+  const names = typeof alias === "string" ? [alias] : Array.isArray(alias) ? alias : [];
+  return names
+    .filter((name): name is string => typeof name === "string")
+    .map((name) => (name.length === 1 ? `-${name}` : `--${name}`));
+}
+
+/**
+ * The camelCase spelling of a kebab-case arg name, or the name unchanged when it has no dash.
+ *
+ * citty registers `camelCase(name)` and `kebabCase(name)` as aliases of **every** arg it parses, so
+ * `--withPrerequisites` reaches the same value as `--with-prerequisites`. This transform is narrow on
+ * purpose — it handles lowercase kebab and nothing else — and `catalog.test.ts` holds every arg name in
+ * the CLI to that shape, so the narrow version is complete rather than merely convenient. The kebab
+ * direction is a no-op over that domain, which is why only this one exists.
+ */
+function camelSpelling(name: string): string {
+  return name.replace(/-([a-z0-9])/g, (_, char: string) => char.toUpperCase());
+}
+
+/**
+ * Every flag one command's parser answers to.
+ *
+ * Three spellings beyond the declared name, each of them citty's rather than ours, and each one a false
+ * failure for a docs check that does not know about it:
+ *
+ * - **Declared aliases**, long and short.
+ * - **The camelCase form.** citty aliases every arg to its camel and kebab spellings, so
+ *   `--withPrerequisites` works. The `flagsOf` doc used to claim citty does no case mapping. It does.
+ * - **`--no-<name>` on a boolean.** citty strips a `--no-` prefix from any argument before parsing, and
+ *   this CLI documents the result: `ui.ts`'s own description offers `--no-auth for the bare SPA`, and
+ *   `docs/commands/ui.md` puts `[--auth | --no-auth]` in its synopsis. An export without it makes a
+ *   deliberately-documented page read as citing a flag that does not exist — the cries-wolf failure this
+ *   whole shape was chosen to avoid. Emitted for booleans only: citty would also answer `--no-env`, but
+ *   naming that would be claiming a flag rather than reporting one.
+ *
+ * A **positional** is not a flag and is left out: it carries no `--`, so a check looking for one would
+ * never ask about it.
+ */
+export function flagsOf(args: ArgsDef | undefined): string[] {
+  const flags: string[] = [];
+  for (const [name, def] of Object.entries(args ?? {})) {
+    const arg = def as { type?: string; alias?: unknown };
+    if (arg.type === "positional") continue;
+    flags.push(`--${name}`);
+    const camel = camelSpelling(name);
+    if (camel !== name) flags.push(`--${camel}`);
+    flags.push(...aliasFlags(arg.alias));
+    if (arg.type === "boolean") flags.push(`--no-${name}`);
+  }
+  return flags;
+}
+
+/**
+ * citty's `Resolvable<T>`: a value, a promise of one, or a thunk returning either.
+ *
+ * Both `subCommands` and `args` are declared this way, so one resolver covers both. Reading either
+ * unawaited is silent rather than loud — `Object.entries` of a promise or a function is `[]`, so the
+ * command reads as taking no flags and the group as having no children.
+ */
+type Resolvable<T> = T | Promise<T> | (() => T | Promise<T>);
+
+/** One `Resolvable`, resolved. */
+async function resolve<T>(value: Resolvable<T>): Promise<T> {
+  return typeof value === "function" ? await (value as () => T | Promise<T>)() : await value;
+}
+
+/**
+ * Every command under `root`, sorted by the path a caller types.
+ *
+ * Groups are walked **and listed**. `pithy token` takes no flags of its own, but a page that spells one
+ * is still citing a command, and a list that skipped it would have nothing to say about that page.
+ *
+ * All three of citty's subcommand spellings are resolved. This CLI writes thunks so the tree stays lazy;
+ * reading only the literal form would have found the root's twenty-six names and none of their flags.
+ */
+export async function walkCommands(root: CommandDef, prefix: string[] = []): Promise<CatalogCommand[]> {
+  const found: CatalogCommand[] = [];
+  // The container is a `Resolvable` as much as anything inside it, and this repository already builds the
+  // lazy form: `dispatch.ts`'s `ownNamesOnly` returns `subCommands: async () => …`, and `bin.ts` wraps the
+  // tree in it before dispatching. Reading it unawaited takes `Object.entries` of a function — no names,
+  // no children, and a whole subtree missing from the export with nothing to say so, because the
+  // non-empty guard is still satisfied by the commands that did resolve.
+  const declared = root.subCommands === undefined ? {} : await resolve(root.subCommands);
+  const subCommands = declared as Record<string, Resolvable<CommandDef>>;
+  for (const [name, value] of Object.entries(subCommands)) {
+    const child = await resolve(value);
+    const path = [...prefix, name];
+    found.push({
+      path: path.join(" "),
+      flags: flagsOf(child.args === undefined ? undefined : await resolve(child.args)),
+    });
+    found.push(...(await walkCommands(child, path)));
+  }
+  return found.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+/**
+ * The catalog, built from the values the kit runs on.
+ *
+ * Every section is asserted non-empty. Not a floor — a floor is a number somebody has to raise by hand,
+ * and it is wrong the moment they do not — but the one state that can only mean the reader broke: a kit
+ * with no capabilities, no commands or no error codes has never existed. A check running against an
+ * empty section reports `ok` on every page, and that is the result worth refusing to write.
+ */
+export async function buildDocsCatalog(): Promise<DocsCatalog> {
+  const catalog: DocsCatalog = {
+    $generated: GENERATED_NOTE,
+    capabilities: CATALOG.map((entry) => ({ name: entry.name, package: entry.package })).sort((left, right) =>
+      left.name.localeCompare(right.name),
+    ),
+    commands: await walkCommands(main),
+    globalFlags: [...GLOBAL_FLAGS].sort(),
+    errorCodes: KitErrorPayload.options
+      .map((member) => ({ code: member.shape.code.value, status: member.shape.status.value }))
+      .sort((left, right) => left.code.localeCompare(right.code)),
+  };
+  for (const [section, entries] of Object.entries(catalog)) {
+    if (Array.isArray(entries) && entries.length === 0) {
+      throw new Error(`The docs catalog read no ${section}. Fix the reader before trusting it.`);
+    }
+  }
+  return catalog;
+}
+
+/**
+ * The exact bytes the catalog file should hold: two-space JSON, one trailing newline.
+ *
+ * `.generated.` is in the filename because Biome ignores that, and it has to: this expands every array
+ * and Biome's JSON formatter fits short ones onto one line, so the writer and the formatter would each
+ * undo the other on every run. See `biome.jsonc`.
+ */
+export function renderDocsCatalog(catalog: DocsCatalog): string {
+  return `${JSON.stringify(catalog, null, 2)}\n`;
+}

package/src/docs/writeCatalog.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Write `docs/catalog.generated.json` — what the kit contains, for the docs site's own check.
+ *
+ * See `./catalog.ts` for why the export exists and why it is strict JSON. This is the writer, and it is
+ * the same shape as `scripts/stampVersions.ts` at the repository root, for the same reason: the file is
+ * **committed**, so a consumer that is neither this repository nor an installer of it can read it with
+ * no build step — and a committed generated file is exactly the kind that goes stale quietly.
+ *
+ * `--check` fails instead of writing, and runs in CI's whole-repo verify job beside the stamped
+ * versions. Drift here is a docs check reporting `ok` against a kit that has moved: every page passes,
+ * and the pages are wrong.
+ *
+ * **It lives under `src/`, not `scripts/`, and that is forced.** `scripts/tsconfig.json` is a Node-only
+ * program — `types: ["node"]`, no Workers types — because nothing it holds may drag the CLI's graph in
+ * behind it. Building the catalog means composing the real command tree, which reaches every capability
+ * package and every `CryptoKey` and `HTMLRewriter` in them. So the entry script belongs in the program
+ * that already has those types, exactly as `bin.ts` does.
+ */
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readOptionalFile } from "../project/readOptionalFile";
+import { buildDocsCatalog, CATALOG_PATH, renderDocsCatalog } from "./catalog";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+const path = join(REPO_ROOT, CATALOG_PATH);
+const expected = renderDocsCatalog(await buildDocsCatalog());
+
+// `readOptionalFile`, not a swallowed `readFileSync`: absent means "write it", and every other failure
+// has to be loud. A discarded permission error would make `--check` report drift it could not see and
+// a plain run overwrite a file it never read.
+const actual = await readOptionalFile(path);
+
+if (actual === expected) {
+  process.stdout.write(`${CATALOG_PATH} is current.\n`);
+} else if (process.argv.includes("--check")) {
+  process.stderr.write(`${CATALOG_PATH} is stale. Run \`bun run docs-catalog\`.\n`);
+  process.exit(1);
+} else {
+  writeFileSync(path, expected);
+  process.stdout.write(`Wrote ${CATALOG_PATH}.\n`);
+}

package/src/doctor/cloudflare.ts

@@ -0,0 +1,287 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import { CLOUDFLARE_CREDENTIAL_KEYS } from "@pithy-sh/cloudflare/src/env/devVars";
+import {
+  type CloudflareAccountMismatch,
+  type CloudflareConfigOptions,
+  type CloudflareCredentialSource,
+  type CloudflareCredentialSplit,
+  cloudflareCredentialSplit,
+  describeCloudflareAccountMismatch,
+  PITHY_OFFLINE_ENV,
+  resolveCloudflare,
+} from "../cloudflare/config";
+
+/**
+ * Whether `pithy doctor` can reach Cloudflare with the credentials the project is configured with.
+ *
+ * **Why this is a health check and not a note.** The bootstrap `CLOUDFLARE_API_TOKEN` +
+ * `CLOUDFLARE_ACCOUNT_ID` pair (`docs/TOKENS.md`) is the first thing anyone sets up on a new account and
+ * the first thing they get wrong — and every failure downstream is a command that was going to work.
+ * Nothing else reported a bad credential until the command that needed it failed mid-run, which is a
+ * worse place to learn it.
+ *
+ * The two checks are deliberately separate because they fail for different reasons and want different
+ * fixes. A live token scoped to the *wrong account* passes verification and fails everything after it —
+ * the exact mistake available the moment somebody has a second Cloudflare account.
+ */
+export type CloudflareAccessState =
+  /** Neither credential is set. Legitimate before provisioning; never fails the exit. */
+  | "unconfigured"
+  /** The token verified and the account answered. */
+  | "ok"
+  /** `GET /user/tokens/verify` rejected it — wrong value, revoked, or expired. */
+  | "token_invalid"
+  /** The token is live but this account did not answer — usually the wrong account id, or missing permissions. */
+  | "account_unreachable"
+  /**
+   * The project pins `cloudflare.accountId` and the resolved credentials belong to a different account.
+   *
+   * Decided before anything reaches the network, and it stays that way: the one thing worse than
+   * reporting the wrong account would be authenticating as it first. It fails the exit like every other
+   * non-`ok` state, which is the whole guarantee the pin buys (#206).
+   */
+  | "account_mismatch"
+  /**
+   * Nothing was asked of Cloudflare, because the caller said not to — `PITHY_OFFLINE`, or `--offline` (#218).
+   *
+   * **A fifth state rather than reusing `unconfigured`**, even though offline in a scratch config
+   * directory resolves exactly nothing. `unconfigured`'s sentence tells you to set the missing keys "in
+   * `<config>/cloudflare.json`, or the environment" — and the environment is the half this mode is
+   * refusing, so the advice would be for a thing that would not work. Silence is worse still: a
+   * diagnostic that skipped a check and printed nothing has reported a health it never established.
+   *
+   * It never fails the exit, for the reason `unconfigured` does not: nothing was established, and only a
+   * fault positively established may gate CI. An adopter on a plane, and a sandbox with no business
+   * touching an account, get the same green exit and the same honest line.
+   */
+  | "not_checked"
+  /**
+   * The probe itself threw — most often a credentials file that will not parse (#371).
+   *
+   * **Distinct from `not_checked`, which is the caller having said not to look.** One is a decision and
+   * the other is a failure, and a diagnostic that reports "offline" about a broken config file has sent
+   * the reader to unset an environment variable that was never set. It never fails the exit, on the rule
+   * every other establishes-nothing state here follows.
+   */
+  | "probe_failed";
+
+/** What `doctor` learned about the configured Cloudflare credentials. */
+export interface CloudflareAccess {
+  state: CloudflareAccessState;
+  /** Which credential keys were absent, so a half-configured setup names the missing half rather than both. */
+  missing: string[];
+  /** The token's lifecycle status from `GET /user/tokens/verify` (`active`), or null when it could not be read. */
+  tokenStatus: string | null;
+  /**
+   * Set when the account id and the token came from **different sources** — part of the pair from
+   * `<config>/cloudflare.json`, the rest overlaid from the ambient environment.
+   *
+   * Reported alongside the state rather than as one, because it is orthogonal to reachability: mixed
+   * credentials may well reach *an* account. It never fails the exit — the pair may be valid, and only a
+   * fault this project's own config positively establishes may gate CI.
+   */
+  credentialSplit: CloudflareCredentialSplit | null;
+  /**
+   * The credentials file this run resolved — `<config>/cloudflare.json`, or the account-named file the
+   * project selected — named whether or not it exists.
+   *
+   * **Optional, and every field below it is, because they are facts about *this machine's* resolution
+   * rather than about reachability.** A caller that supplies its own probe has no file to name, and
+   * `describeCloudflareAccess` prints exactly what it printed before when nothing names one.
+   */
+  configPath?: string;
+  /** The project's `cloudflare.accountName`, or `null` when it named none. */
+  accountName?: string | null;
+  /** The pin disagreeing with the resolved credentials. Set exactly when the state is `account_mismatch`. */
+  accountMismatch?: CloudflareAccountMismatch | null;
+  /**
+   * Which source supplied the pair — `file`, `environment`, `mixed`, or `null` when neither key resolved.
+   *
+   * The third acceptance criterion of #218, and the one that would have caught the incident on sight: the
+   * report named `~/.config/pithy/cloudflare.json` while the credentials came from a shell nobody in that
+   * session had looked at, and there was no line anywhere that distinguished the two.
+   */
+  credentialSource?: CloudflareCredentialSource | null;
+}
+
+/**
+ * The credential keys this check needs, in the order they are reported — the same group
+ * {@link cloudflareCredentialSplit} watches, because "both must be set" and "both must come from one
+ * account" are two readings of one pair.
+ */
+const REQUIRED_KEYS = CLOUDFLARE_CREDENTIAL_KEYS;
+
+/**
+ * Verify the token against the endpoint that matches its kind.
+ *
+ * **Cloudflare has two, and using the wrong one rejects a working credential.** `/user/tokens/verify`
+ * answers only for user-bound (`cfut_*`) tokens; an account-owned (`cfat_*`) one gets `Invalid API Token`.
+ * `CLAUDE.md` prefers account-owned tokens, so the user endpoint is wrong for the *common* case — a
+ * diagnostic built on it would confidently reject the setup it was written to validate.
+ *
+ * The prefix is the only part of the token read, matching `@pithy-sh/audit`'s actor resolution. An
+ * unrecognised prefix falls back to trying both rather than guessing, since a wrong "invalid" here is
+ * worse than a slower answer.
+ */
+async function verifyByKind(clients: CloudflareClients, apiToken: string): Promise<string | null> {
+  const account = () => clients.accountTokens().verifyToken();
+  const user = () => clients.user().verifyToken();
+  const order = apiToken.startsWith("cfat_") ? [account] : apiToken.startsWith("cfut_") ? [user] : [account, user];
+
+  for (const attempt of order) {
+    try {
+      return (await attempt()).status;
+    } catch {
+      // Try the next shape, or fall through to "rejected".
+    }
+  }
+  return null;
+}
+
+/**
+ * Probe the configured Cloudflare credentials, reading `<config>/cloudflare.json` with the `process.env`
+ * overlay {@link cloudflareEnv} applies — so this reports the same credentials every other command
+ * resolves, in CI as well as locally.
+ *
+ * **It takes no project directory, and that is the finding rather than a simplification.** The
+ * credentials are account-scoped (#182): one account holds many projects, and "can I reach Cloudflare"
+ * has the same answer in every checkout on this machine. Passing a project root implied otherwise, and
+ * the file it named was inside one.
+ *
+ * Never throws: a diagnostic command has to keep working in exactly the broken environment it exists to
+ * diagnose, so every failure becomes a state rather than an exception.
+ */
+export async function checkCloudflareAccess(options: CloudflareConfigOptions): Promise<CloudflareAccess> {
+  // `resolveCloudflare` rather than `cloudflareEnv`: a pinned mismatch is a throw everywhere else, and a
+  // diagnostic that died of the fault it exists to report would leave nothing to read it in.
+  const resolution = resolveCloudflare(options);
+  const vars = resolution.vars;
+  // Resolved from the same file and the same environment, so what is reported is a fact about *this*
+  // resolution rather than about a second one taken a moment later.
+  const credentialSplit = cloudflareCredentialSplit(options);
+  const where = {
+    configPath: resolution.path,
+    accountName: resolution.accountName,
+    accountMismatch: resolution.mismatch,
+    credentialSource: resolution.credentialSource,
+  };
+
+  // Before the credentials are even counted, and long before any of them are used: credentials for an
+  // account this project does not claim must not reach Cloudflare, not even to be verified.
+  if (resolution.mismatch)
+    return { state: "account_mismatch", missing: [], tokenStatus: null, credentialSplit, ...where };
+
+  const missing = REQUIRED_KEYS.filter((key) => !vars[key]);
+
+  // Offline, and this is the whole of doctor's honoring of it: no probe, and a state that says so.
+  //
+  // **After the mismatch and not before it.** That fault is decided from this machine's own files — a
+  // config's pin against a file's account id — so it costs no network and no ambient credential, and
+  // suppressing it would mean the mode hid a real fault as well as a real account. Everything below this
+  // line is the part that reaches Cloudflare, and none of it runs.
+  if (resolution.offline)
+    return { state: "not_checked", missing: [...missing], tokenStatus: null, credentialSplit, ...where };
+
+  if (missing.length > 0)
+    return { state: "unconfigured", missing: [...missing], tokenStatus: null, credentialSplit, ...where };
+
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  const clients = new CloudflareClients({ accountId: vars.CLOUDFLARE_ACCOUNT_ID ?? "", apiToken });
+
+  const tokenStatus = await verifyByKind(clients, apiToken);
+  if (tokenStatus === null)
+    return { state: "token_invalid", missing: [], tokenStatus: null, credentialSplit, ...where };
+
+  // Account-scoped, read-only, and never throws — and it exercises the one permission the bootstrap token
+  // must hold to mint anything (`docs/TOKENS.md`), so a token that cannot mint is caught here rather than
+  // by `pithy token mint`.
+  const reachable = await clients.accountTokens().validateServiceAccess();
+  if (!reachable) return { state: "account_unreachable", missing: [], tokenStatus, credentialSplit, ...where };
+
+  return { state: "ok", missing: [], tokenStatus, credentialSplit, ...where };
+}
+
+/**
+ * The credentials file, abbreviated against the operator's home the way every other path in the report
+ * is. `~/.config/pithy/cloudflare.json` when nothing named one — a stubbed probe, and the default.
+ */
+function configPath(access: CloudflareAccess, home: string | undefined): string {
+  const path = access.configPath ?? "~/.config/pithy/cloudflare.json";
+  return home && path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+
+/** The state's own line, before the split warning {@link describeCloudflareAccess} may append. */
+function describeState(access: CloudflareAccess, home?: string): string {
+  switch (access.state) {
+    case "ok":
+      return `reachable (token ${access.tokenStatus ?? "verified"})`;
+    case "unconfigured":
+      // The file this run actually resolved, when it knows it. `~/.config/pithy/cloudflare.json` is the
+      // right answer for a single-account machine and the wrong one for a project that names an account,
+      // and telling somebody to set a key in a file nothing will read is worse than saying nothing.
+      return `not configured (set ${access.missing.join(" and ")} in ${configPath(access, home)}, or the environment)`;
+    case "token_invalid":
+      return "CLOUDFLARE_API_TOKEN rejected — check the value, or mint a new bootstrap token";
+    case "account_unreachable":
+      return "token is valid but the account did not answer — check CLOUDFLARE_ACCOUNT_ID and the token's permissions";
+    case "account_mismatch":
+      return access.accountMismatch
+        ? `${describeCloudflareAccountMismatch(access.accountMismatch)} Nothing will run against it.`
+        : "the credentials belong to an account this project does not claim";
+    case "not_checked":
+      // **Both levers, and neither claimed.** The first wording said "`PITHY_OFFLINE` is set", which is
+      // false on every `--offline` run — a line about not checking that is itself wrong is the exact
+      // failure this state exists to avoid. Naming both is not hedging: the reader of this line is as
+      // likely to be somebody who did not know the mode was on — a harness, a CI job, a shell profile —
+      // as the person who asked for it, and they need to know what to go and unset.
+      return `not checked — offline (${PITHY_OFFLINE_ENV} or --offline)`;
+    case "probe_failed":
+      // No reason from the throw: a credentials-resolution failure names paths, account ids and, in the
+      // worst case, a value. The file it would have read is the actionable fact and the suffix says it.
+      return "couldn't be checked — the credentials would not resolve";
+  }
+}
+
+/**
+ * The suffix naming where the credentials stand — the file, or the environment that supplied them.
+ *
+ * `; from <file>` was the whole of this and it was a claim about the *resolution*, not about the
+ * credentials: CI resolves a path with nothing at it and authenticates from the environment, and so did
+ * the sandbox run that reached a live account off a forgotten export (#218). So the environment case says
+ * the environment, and names the file it did **not** read, because that file is what the reader was about
+ * to go and check.
+ *
+ * `mixed` keeps the file wording: the split sentence in front of it has already named which key came from
+ * where, in more detail than this can, and repeating it would be the line saying one thing twice.
+ */
+function credentialOrigin(access: CloudflareAccess, home: string | undefined): string {
+  const path = configPath(access, home);
+  if (access.state === "not_checked" || access.state === "probe_failed")
+    return `credentials would resolve from ${path}`;
+  if (access.credentialSource === "environment") return `credentials from the environment, not ${path}`;
+  return `from ${path}`;
+}
+
+/**
+ * The one-line report for {@link renderDoctorText}, and the `action` a failing state should prompt.
+ *
+ * A split group is appended rather than substituted: both facts are true at once, and a reachable state
+ * is exactly what makes the split easy to miss — mixed credentials still reach *an* account.
+ */
+export function describeCloudflareAccess(access: CloudflareAccess, home?: string): string {
+  const state = describeState(access, home);
+  const split = access.credentialSplit;
+  const withSplit = split
+    ? `${state}; credentials come from two places — cloudflare.json sets ${split.fromFile.join(" and ")}, the environment supplies ${split.fromEnvironment.join(" and ")} — set the whole pair in one of them`
+    : state;
+  // The file, on every run that knows one. "Which account am I about to deploy to" must never require
+  // inspection, and once a machine holds `cloudflare.leed.json` beside `cloudflare.other-co.json` the
+  // state line alone does not answer it. The two states that have already named it — a mismatch names
+  // both ids, an unconfigured one names where the missing keys go — are not made to say it twice.
+  const named = access.state === "account_mismatch" || access.state === "unconfigured";
+  if (!access.configPath || named) return withSplit;
+  return `${withSplit}; ${credentialOrigin(access, home)}`;
+}