@trawlme/cli 3.7.5 → 3.8.1

package/dist/lib/errors.d.ts

@@ -37,11 +37,122 @@ export interface ErrorEnvelope {
     message: string;
     status?: number;
     kind: string;
+    /** Is retrying the SAME command, unchanged, worth it? */
+    retryable: boolean;
+    /** Commands worth running next, most useful first. Empty when there is
+     *  nothing honest to suggest — never filled to look helpful. */
+    next?: string[];
 }
 export interface ClassifiedError {
     exitCode: number;
     envelope: ErrorEnvelope;
 }
+/**
+ * The exit-code taxonomy (#71 findings 13/14/60), named once so
+ * `classifyError` below and `spec.ts`'s `buildSpec()` (#170) read the SAME
+ * numbers instead of `spec.ts` hand-listing its own copy — exactly the kind
+ * of second source of truth `tests/contracts/` exists to catch drifting.
+ */
+export declare const EXIT_CODES: Readonly<{
+    SUCCESS: 0;
+    UNKNOWN: 1;
+    USAGE: 2;
+    AUTH: 3;
+    NOT_FOUND: 4;
+    NETWORK: 5;
+}>;
+/** `trawl spec --json`'s `exitCodes` field — a short label per code. Code
+ * `1` is shared by several `kind`s (`api`, `refused`, `unknown`); the label
+ * names the generic/unmapped bucket it represents, not an exhaustive list. */
+export declare const EXIT_CODE_LABELS: Readonly<Record<string, string>>;
+/**
+ * #170 — ONE frozen map, keyed by the existing `kind`, driving the
+ * envelope's new `retryable`/`next` fields. This is also the exhaustive set
+ * of `kind`s `classifyError` can produce — `ERROR_KINDS` below derives its
+ * list from these keys rather than hand-listing them a second time, and
+ * `spec.ts`'s `buildSpec()` reads `ERROR_KINDS`, never its own copy.
+ *
+ * `network` is the one kind worth retrying unchanged. `auth` isn't
+ * retryable but has an honest next step (`trawl login --token <jwt>`).
+ * Everything else (`usage`/`not_found`/`api`/`refused`/`unknown`) is neither
+ * — retrying a bad flag, a missing resource, or an unmapped bug with no new
+ * information just repeats the same failure.
+ *
+ * #170 review F8 — `next` must be an EXECUTABLE next command, not just a verb
+ * name: bare `trawl login` still blocks on an interactive prompt (email then
+ * password) — for a non-interactive caller (stdin closed, the exact
+ * situation an auth failure implies) it fails immediately with its OWN usage
+ * error instead of the login the agent was told to run. `trawl login --token
+ * <jwt>` is the one form of `login` that never prompts.
+ */
+export declare const RETRY_POLICY: Readonly<Record<string, {
+    retryable: boolean;
+    next?: readonly string[];
+}>>;
+/** Every `kind` string `classifyError` can produce — derived from
+ * `RETRY_POLICY`'s keys (see its doc comment), never a second hand list. */
+export declare const ERROR_KINDS: readonly string[];
+/**
+ * Every `kind` a real `--json` error envelope can carry — NOT the same set
+ * as `ERROR_KINDS`. `ERROR_KINDS` is deliberately narrow (exactly what
+ * `classifyError` produces, see its own doc comment — `RETRY_POLICY` must
+ * keep meaning that, `retryFieldsFor` relies on it), but three more kinds
+ * reach a real envelope from hand-built emitters that never go through
+ * `classifyError` at all:
+ *   - `in_progress` — `src/commands/scraps.ts`, `data <id>`'s `reportDataState`
+ *     call for a run still in flight
+ *   - `run_failed`  — same file, same helper, for a last run that failed
+ *   - `upgrade_failed` — `src/commands/upgrade.ts`, when `npm install -g` itself fails
+ *
+ * `spec.ts`'s `errorKinds` field publishes THIS constant, never
+ * `ERROR_KINDS` — an agent that builds its allow-list from the published
+ * spec must not reject a perfectly valid `{"error":{"kind":"in_progress",…}}`
+ * envelope just because it was hand-built instead of classified. Built as a
+ * union (spread `ERROR_KINDS` + list the hand-built kinds) rather than a
+ * second hand-copy of the first group, so the classifyError kinds are
+ * PROVABLY a subset — see errors.test.ts's exhaustiveness check.
+ *
+ * Adding a new hand-built `kind:` literal anywhere in `src/` means
+ * registering it here too, or the published spec will lie about it exactly
+ * like this constant exists to prevent.
+ */
+export declare const ENVELOPE_KINDS: readonly string[];
+/**
+ * #170 review F7 — `spec --json`'s flat `exitCodes` map (`EXIT_CODE_LABELS`)
+ * publishes ONE label per code, which is honest about code `1` being a
+ * generic/unmapped bucket but says nothing about which `kind`s actually land
+ * there. An agent building an `exitCode -> kind` table off `exitCodes` alone
+ * reads `"1":"unknown"` and treats every other kind sharing that code
+ * (`api`/`refused`/`in_progress`/`run_failed`/`upgrade_failed`) as an
+ * unmapped bug it should give up on — instead of honouring the very
+ * `retryable`/`next` fields those envelopes correctly carry.
+ *
+ * This is the inverse direction, `kind -> exitCode`, one entry per
+ * `ENVELOPE_KINDS` member — additive (published as a SIBLING field,
+ * `kindExitCodes`, never replacing `exitCodes`) and keyed off the same
+ * `EXIT_CODES` constants every real call site already uses, so a future exit
+ * code change here can't silently drift from `classifyError`/
+ * `reportDataState`/`upgrade.ts`'s actual behaviour without also changing the
+ * single source those all draw from. errors.test.ts asserts every entry here
+ * against classifyError's REAL returned exitCode for that kind — the closest
+ * an exhaustive hand-map can get to "derived", short of `classifyError`
+ * itself being rewritten to loop over a shared table (out of scope here).
+ */
+export declare const KIND_EXIT_CODES: Readonly<Record<string, number>>;
+/**
+ * Look up the frozen default `retryable`/`next` for a `kind`. Total (never
+ * throws) — a `kind` outside `RETRY_POLICY` (e.g. `scraps data`'s own
+ * `run_failed`/`in_progress` states, which aren't part of `classifyError`'s
+ * taxonomy) falls back to the conservative "not retryable, nothing to
+ * suggest" default. Callers with a genuine kind-is-wrong override (an
+ * `ApiError` 429, `scraps data`'s `in_progress` refusal) pass their own
+ * `retryable`/`next` instead of trusting this lookup — see classifyError and
+ * scraps.ts's `reportDataState`.
+ */
+export declare function retryFieldsFor(kind: string): {
+    retryable: boolean;
+    next?: string[];
+};
 /**
  * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
  * CLI unattended need to tell "you're not logged in" (3) from "that id
@@ -53,8 +164,8 @@ export declare function classifyError(err: unknown): ClassifiedError;
 /**
  * Print a classified error to the correct stream and return its exit code.
  * stdout is reserved for payload — under --json the error itself IS the
- * payload (`{"error":{message,status,kind}}`); otherwise the human-readable
- * line goes to stderr, never stdout. (#71 findings 13/14/60)
+ * payload (`{"error":{message,status,kind,retryable,next?}}`); otherwise the
+ * human-readable line goes to stderr, never stdout. (#71 findings 13/14/60)
  *
  * `quiet` skips the human-readable stderr line (used when the caller already
  * printed a fuller diagnostic, e.g. a raw stack trace under --debug) while

package/dist/lib/errors.js

@@ -43,6 +43,145 @@ export class RefusalError extends Error {
 export function stripCommanderErrorPrefix(message) {
     return message.startsWith('error: ') ? message.slice('error: '.length) : message;
 }
+/**
+ * The exit-code taxonomy (#71 findings 13/14/60), named once so
+ * `classifyError` below and `spec.ts`'s `buildSpec()` (#170) read the SAME
+ * numbers instead of `spec.ts` hand-listing its own copy — exactly the kind
+ * of second source of truth `tests/contracts/` exists to catch drifting.
+ */
+export const EXIT_CODES = Object.freeze({
+    SUCCESS: 0,
+    UNKNOWN: 1,
+    USAGE: 2,
+    AUTH: 3,
+    NOT_FOUND: 4,
+    NETWORK: 5,
+});
+/** `trawl spec --json`'s `exitCodes` field — a short label per code. Code
+ * `1` is shared by several `kind`s (`api`, `refused`, `unknown`); the label
+ * names the generic/unmapped bucket it represents, not an exhaustive list. */
+export const EXIT_CODE_LABELS = Object.freeze({
+    [EXIT_CODES.SUCCESS]: 'success',
+    [EXIT_CODES.UNKNOWN]: 'unknown',
+    [EXIT_CODES.USAGE]: 'usage',
+    [EXIT_CODES.AUTH]: 'auth',
+    [EXIT_CODES.NOT_FOUND]: 'not_found',
+    [EXIT_CODES.NETWORK]: 'network',
+});
+/**
+ * #170 — ONE frozen map, keyed by the existing `kind`, driving the
+ * envelope's new `retryable`/`next` fields. This is also the exhaustive set
+ * of `kind`s `classifyError` can produce — `ERROR_KINDS` below derives its
+ * list from these keys rather than hand-listing them a second time, and
+ * `spec.ts`'s `buildSpec()` reads `ERROR_KINDS`, never its own copy.
+ *
+ * `network` is the one kind worth retrying unchanged. `auth` isn't
+ * retryable but has an honest next step (`trawl login --token <jwt>`).
+ * Everything else (`usage`/`not_found`/`api`/`refused`/`unknown`) is neither
+ * — retrying a bad flag, a missing resource, or an unmapped bug with no new
+ * information just repeats the same failure.
+ *
+ * #170 review F8 — `next` must be an EXECUTABLE next command, not just a verb
+ * name: bare `trawl login` still blocks on an interactive prompt (email then
+ * password) — for a non-interactive caller (stdin closed, the exact
+ * situation an auth failure implies) it fails immediately with its OWN usage
+ * error instead of the login the agent was told to run. `trawl login --token
+ * <jwt>` is the one form of `login` that never prompts.
+ */
+export const RETRY_POLICY = Object.freeze({
+    auth: { retryable: false, next: ['trawl login --token <jwt>'] },
+    network: { retryable: true },
+    usage: { retryable: false },
+    not_found: { retryable: false },
+    api: { retryable: false },
+    refused: { retryable: false },
+    unknown: { retryable: false },
+});
+/** Every `kind` string `classifyError` can produce — derived from
+ * `RETRY_POLICY`'s keys (see its doc comment), never a second hand list. */
+export const ERROR_KINDS = Object.freeze(Object.keys(RETRY_POLICY));
+/**
+ * Every `kind` a real `--json` error envelope can carry — NOT the same set
+ * as `ERROR_KINDS`. `ERROR_KINDS` is deliberately narrow (exactly what
+ * `classifyError` produces, see its own doc comment — `RETRY_POLICY` must
+ * keep meaning that, `retryFieldsFor` relies on it), but three more kinds
+ * reach a real envelope from hand-built emitters that never go through
+ * `classifyError` at all:
+ *   - `in_progress` — `src/commands/scraps.ts`, `data <id>`'s `reportDataState`
+ *     call for a run still in flight
+ *   - `run_failed`  — same file, same helper, for a last run that failed
+ *   - `upgrade_failed` — `src/commands/upgrade.ts`, when `npm install -g` itself fails
+ *
+ * `spec.ts`'s `errorKinds` field publishes THIS constant, never
+ * `ERROR_KINDS` — an agent that builds its allow-list from the published
+ * spec must not reject a perfectly valid `{"error":{"kind":"in_progress",…}}`
+ * envelope just because it was hand-built instead of classified. Built as a
+ * union (spread `ERROR_KINDS` + list the hand-built kinds) rather than a
+ * second hand-copy of the first group, so the classifyError kinds are
+ * PROVABLY a subset — see errors.test.ts's exhaustiveness check.
+ *
+ * Adding a new hand-built `kind:` literal anywhere in `src/` means
+ * registering it here too, or the published spec will lie about it exactly
+ * like this constant exists to prevent.
+ */
+export const ENVELOPE_KINDS = Object.freeze([
+    ...ERROR_KINDS,
+    'in_progress',
+    'run_failed',
+    'upgrade_failed',
+]);
+/**
+ * #170 review F7 — `spec --json`'s flat `exitCodes` map (`EXIT_CODE_LABELS`)
+ * publishes ONE label per code, which is honest about code `1` being a
+ * generic/unmapped bucket but says nothing about which `kind`s actually land
+ * there. An agent building an `exitCode -> kind` table off `exitCodes` alone
+ * reads `"1":"unknown"` and treats every other kind sharing that code
+ * (`api`/`refused`/`in_progress`/`run_failed`/`upgrade_failed`) as an
+ * unmapped bug it should give up on — instead of honouring the very
+ * `retryable`/`next` fields those envelopes correctly carry.
+ *
+ * This is the inverse direction, `kind -> exitCode`, one entry per
+ * `ENVELOPE_KINDS` member — additive (published as a SIBLING field,
+ * `kindExitCodes`, never replacing `exitCodes`) and keyed off the same
+ * `EXIT_CODES` constants every real call site already uses, so a future exit
+ * code change here can't silently drift from `classifyError`/
+ * `reportDataState`/`upgrade.ts`'s actual behaviour without also changing the
+ * single source those all draw from. errors.test.ts asserts every entry here
+ * against classifyError's REAL returned exitCode for that kind — the closest
+ * an exhaustive hand-map can get to "derived", short of `classifyError`
+ * itself being rewritten to loop over a shared table (out of scope here).
+ */
+export const KIND_EXIT_CODES = Object.freeze({
+    auth: EXIT_CODES.AUTH,
+    network: EXIT_CODES.NETWORK,
+    usage: EXIT_CODES.USAGE,
+    not_found: EXIT_CODES.NOT_FOUND,
+    api: EXIT_CODES.UNKNOWN,
+    refused: EXIT_CODES.UNKNOWN,
+    unknown: EXIT_CODES.UNKNOWN,
+    // Hand-built kinds (never routed through classifyError) — in_progress/
+    // run_failed both set via reportDataState's literal `1` (scraps.ts),
+    // upgrade_failed via its own literal `process.exitCode = 1` (upgrade.ts).
+    in_progress: EXIT_CODES.UNKNOWN,
+    run_failed: EXIT_CODES.UNKNOWN,
+    upgrade_failed: EXIT_CODES.UNKNOWN,
+});
+/**
+ * Look up the frozen default `retryable`/`next` for a `kind`. Total (never
+ * throws) — a `kind` outside `RETRY_POLICY` (e.g. `scraps data`'s own
+ * `run_failed`/`in_progress` states, which aren't part of `classifyError`'s
+ * taxonomy) falls back to the conservative "not retryable, nothing to
+ * suggest" default. Callers with a genuine kind-is-wrong override (an
+ * `ApiError` 429, `scraps data`'s `in_progress` refusal) pass their own
+ * `retryable`/`next` instead of trusting this lookup — see classifyError and
+ * scraps.ts's `reportDataState`.
+ */
+export function retryFieldsFor(kind) {
+    const policy = RETRY_POLICY[kind];
+    if (!policy)
+        return { retryable: false };
+    return policy.next ? { retryable: policy.retryable, next: [...policy.next] } : { retryable: policy.retryable };
+}
 /**
  * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
  * CLI unattended need to tell "you're not logged in" (3) from "that id
@@ -57,32 +196,59 @@ export function classifyError(err) {
     // `status:401` — that would claim a server response that never happened.
     // Same exit code / kind as a real server 401 (ApiError below); only the
     // envelope shape differs.
+    //
+    // #169 review round 2, finding 2 — `err.next` is only ever set (in api.ts,
+    // via authNextSteps()) for an apiKey-mode failure, where the frozen
+    // `next` default ("trawl login --token <jwt>") is inert until a live
+    // TRAWL_API_KEY/TRAWL_TOKEN is unset first. Spread AFTER retryFieldsFor so
+    // it overrides that default's `next` key; every other AuthError/ApiError
+    // 401 (jwt mode, notLoggedInError — no credential at all) leaves `err.next`
+    // undefined and keeps the unmodified frozen default, unchanged from before.
     if (err instanceof AuthError) {
-        return { exitCode: 3, envelope: { message, kind: 'auth' } };
+        return {
+            exitCode: EXIT_CODES.AUTH,
+            envelope: { message, kind: 'auth', ...retryFieldsFor('auth'), ...(err.next ? { next: err.next } : {}) },
+        };
     }
     if (err instanceof ApiError) {
-        if (err.status === 401)
-            return { exitCode: 3, envelope: { message, status: 401, kind: 'auth' } };
-        if (err.status === 404)
-            return { exitCode: 4, envelope: { message, status: 404, kind: 'not_found' } };
-        return { exitCode: 1, envelope: { message, status: err.status, kind: 'api' } };
+        if (err.status === 401) {
+            return {
+                exitCode: EXIT_CODES.AUTH,
+                envelope: {
+                    message,
+                    status: 401,
+                    kind: 'auth',
+                    ...retryFieldsFor('auth'),
+                    ...(err.next ? { next: err.next } : {}),
+                },
+            };
+        }
+        if (err.status === 404) {
+            return { exitCode: EXIT_CODES.NOT_FOUND, envelope: { message, status: 404, kind: 'not_found', ...retryFieldsFor('not_found') } };
+        }
+        // #170 — a 429 (rate-limited / quota-exhausted) is the one `api`-kind
+        // response worth retrying, even though the frozen map's default for
+        // `api` is not retryable. Genuinely kind-is-wrong override, not a new
+        // kind — `kind` stays `"api"`.
+        const retry = err.status === 429 ? { retryable: true } : retryFieldsFor('api');
+        return { exitCode: EXIT_CODES.UNKNOWN, envelope: { message, status: err.status, kind: 'api', ...retry } };
     }
     if (err instanceof NetworkError) {
-        return { exitCode: 5, envelope: { message, kind: 'network' } };
+        return { exitCode: EXIT_CODES.NETWORK, envelope: { message, kind: 'network', ...retryFieldsFor('network') } };
     }
     if (err instanceof UsageError) {
-        return { exitCode: 2, envelope: { message, kind: 'usage' } };
+        return { exitCode: EXIT_CODES.USAGE, envelope: { message, kind: 'usage', ...retryFieldsFor('usage') } };
     }
     if (err instanceof RefusalError) {
-        return { exitCode: 1, envelope: { message, kind: 'refused' } };
+        return { exitCode: EXIT_CODES.UNKNOWN, envelope: { message, kind: 'refused', ...retryFieldsFor('refused') } };
     }
-    return { exitCode: 1, envelope: { message, kind: 'unknown' } };
+    return { exitCode: EXIT_CODES.UNKNOWN, envelope: { message, kind: 'unknown', ...retryFieldsFor('unknown') } };
 }
 /**
  * Print a classified error to the correct stream and return its exit code.
  * stdout is reserved for payload — under --json the error itself IS the
- * payload (`{"error":{message,status,kind}}`); otherwise the human-readable
- * line goes to stderr, never stdout. (#71 findings 13/14/60)
+ * payload (`{"error":{message,status,kind,retryable,next?}}`); otherwise the
+ * human-readable line goes to stderr, never stdout. (#71 findings 13/14/60)
  *
  * `quiet` skips the human-readable stderr line (used when the caller already
  * printed a fuller diagnostic, e.g. a raw stack trace under --debug) while

package/docs/agent-quickstart.md

@@ -6,21 +6,75 @@ telemetry, etc.) see the [main README](../README.md) — the human/CI guide.
 
 ## Auth — zero prompts
 
-Set `TRAWL_TOKEN` and every command authenticates without ever touching a
-prompt:
+**Use `TRAWL_API_KEY`, not `TRAWL_TOKEN`, if you can.** A `trawl_*` API key
+is revocable on its own and can be restricted to a set of scraps; a JWT
+(`TRAWL_TOKEN`) is the human's own session — expiring, full-privilege, and
+impossible to revoke without logging that human out everywhere.
+
+Be precise about what "scoped" buys you, because the two axes are not equal
+in practice. A key can carry a **scrap allow-list** (set in the dashboard at
+creation) and an **action scope list** (`trawl:scraps:read` and friends).
+Only the first is reachable from the web app; the second must be passed as an
+explicit `scopes` array when the key is created over the API, and a key
+created without one has **every action granted**. So unless someone minted it
+deliberately through the API, the key you are holding is restricted by scrap,
+not by action. `trawl` picks the right
+`Authorization`/`Cookie` shape automatically based on which one you set —
+never a flag:
+
+```bash
+export TRAWL_API_KEY=trawl_xxx
+trawl list --json
+```
+
+`TRAWL_TOKEN` (a human session JWT) still works — set it only if you don't
+have a key yet — and `TRAWL_API_KEY` always wins when both happen to be set:
 
 ```bash
 export TRAWL_TOKEN=<jwt>
-trawl whoami --json
+trawl list --json
 ```
 
+**What a key cannot do.** Of the twelve core commands below, a scoped key
+covers all of them except `whoami`. Outside the core tier, a key also can't
+reach `scraps update`/`delete`, `scraps account set`/`delete`/`clear-session`,
+`scraps account session set`, `scraps banner`, or `scraps snapshot` (its
+underlying `html-snapshot` route is JWT-only even though the scrap lookup it
+starts from isn't) — nor the standalone SSE **command** `scraps watch`.
+Those, plus `whoami`, stay JWT-only. `scraps account status`, `scraps
+doctor`, and `scraps autofix` are the exceptions inside that same
+management-tier group: all three only ever read routes trawl_node opened to
+keys (`GET /api/scraps/:id`, `GET /api/historys/:hid`, `GET
+/api/scraps/:id/activities`), so all three work fine under a key. (`scraps
+watch` is a separate command, not the same thing as the `--watch` polling
+flag on `run`/`trigger` below, which works fine under a key — do not
+conflate the two.)
+
+This list mirrors trawl_node's route wiring as of this writing, not a
+permanent contract — a route's auth mode can change on either side without
+this doc catching up same-day. Don't trust the list blind for a command not
+named above: the reliable check is the real `--json` envelope, every time —
+a JWT-only command run under a key exits `3` with a `kind:"auth"` envelope
+pointing at `trawl login`, never a silent wrong answer, whether or not this
+paragraph is current. `whoami` catches this client-side and names itself in
+the message; every other JWT-only route above is caught by the real server
+401 instead, so the message says a session is required without naming which
+command hit it.
+
+`trawl token` also needs a word here: `getToken()` (the same resolver every
+command above uses) can hand back `TRAWL_API_KEY` just as easily as a
+session token, so `trawl token`/`$(trawl token)` may print a scoped,
+**non-expiring** API key instead of an expiring JWT — check `--json`'s
+`mode` field (`"apiKey"` or `"jwt"`) if your script branches on which one it
+got.
+
 (Interactive `trawl login` and the `--url`/config-file flow are documented in
 the README's [Authentication](../README.md#authentication) section — an
 agent should never need them.)
 
 ## Core commands (agent + human)
 
-These eleven commands are the CLI's agent+human surface — `--json` is
+These twelve commands are the CLI's agent+human surface — `--json` is
 first-class on every one, and none of them ever blocks on a prompt (see
 [Non-interactive contract](#non-interactive-contract) below):
 
@@ -35,8 +89,9 @@ trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted ru
 trawl history <id> [--json] [-n <limit>]       List past runs for a scrap
 trawl run-info <hid> [--json]                  Show details of a single run
 trawl whoami [--json]                          Show the authenticated user's identity
-trawl token [--json]                           Print the stored session JWT (for MCP Bearer auth)
+trawl token [--json]                           Print the stored credential — API key or session JWT (for MCP Bearer auth)
 trawl ping [--json]                            Health/version handshake against the Trawl API
+trawl spec [--json]                            Print a versioned, machine-readable description of the command tree
 ```
 
 `trawl create` is the closest primitive to "turn this URL + goal into a
@@ -85,11 +140,33 @@ reaches a terminal state (not the whole progress stream), and there is no
 JSON form of an HTML page (irrelevant to the core verbs above — that only
 applies to the management-only `scraps snapshot`).
 
+Capture **stdout alone** — never `2>&1`. Stderr legitimately carries
+human-facing lines even in `--json` mode (the one-time telemetry disclosure
+on first run, the skills re-sync notice, warnings); merging the two streams
+corrupts the payload you're about to parse.
+
 On failure, `--json` emits a single error envelope on stdout instead of
-prose — `{"error":{"message","status?","kind"}}` — and the human-readable
-line goes to stderr, never stdout. `kind` is the machine-readable
-discriminant (`"usage"`/`"auth"`/`"not_found"`/`"network"`/`"api"`/
-`"refused"`/`"unknown"`) a script should switch on.
+prose — `{"error":{"message","status?","kind","retryable","next?"}}` — and
+the human-readable line goes to stderr, never stdout. `kind` is the
+machine-readable discriminant (`"usage"`/`"auth"`/`"not_found"`/`"network"`/
+`"api"`/`"refused"`/`"unknown"`/`"in_progress"`/`"run_failed"`/
+`"upgrade_failed"`) a script should switch on — run `trawl spec --json` for
+the exhaustive, versioned list.
+
+`retryable` is the field a retry loop actually branches on — not `kind`, and
+never a regex over `message` (e.g. "retry shortly" is prose, not a
+contract): `true` means retrying the exact same command, unchanged, is
+worth it (a network blip, a `429`, a run still in progress); `false` means
+it isn't (a bad flag, an expired token, a missing resource — nothing about
+retrying without changes would help). `next` is advisory only — commands
+worth running next, most useful first (e.g. `["trawl login --token <jwt>"]`
+on an auth failure — the one form of `login` that never blocks on an
+interactive prompt) — and **may be empty or absent**: it is never filled in
+just to look helpful, so don't treat its absence as an error.
+
+For the full, versioned machine description of every command (arguments,
+options, aliases, exit codes, error kinds) — instead of parsing this doc —
+run `trawl spec --json`.
 
 ## Non-interactive contract
 
@@ -107,7 +184,7 @@ hanging. Full rule + rationale: README's
 | `0`  | Success |
 | `1`  | Unknown/generic error, or a business-logic outcome (e.g. `create`'s honest `success:false` first-run outcome, `data`'s `run_failed`/`in_progress`) |
 | `2`  | Usage error (bad flag/value, invalid ID, missing required argument, or the non-interactive guard refusing to prompt) |
-| `3`  | Auth error (not logged in, or the session token is expired/invalid) |
+| `3`  | Auth error (not logged in, the session token is expired/invalid, or a JWT-only command — see [above](#auth--zero-prompts) — was run under an API key) |
 | `4`  | Not found (no such resource, or no persisted payload to read) |
 | `5`  | Network error (API host unreachable, DNS/connection/TLS failure, or timeout) |
 
@@ -119,5 +196,5 @@ section — treat that as canonical if the two ever seem to disagree.
 ## Minimal example
 
 ```bash
-TRAWL_TOKEN=<jwt> trawl create https://example.com --prompt "Extract the article title and body text" --json
+TRAWL_API_KEY=trawl_xxx trawl create https://example.com --prompt "Extract the article title and body text" --json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "3.7.5",
+  "version": "3.8.1",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -50,6 +50,7 @@
     "strip-ansi": "^7.2.0"
   },
   "devDependencies": {
+    "@semantic-release/commit-analyzer": "13.0.1",
     "@types/node": "^25.5.2",
     "@vitest/coverage-v8": "^4.1.2",
     "typescript": "^6.0.2",