@trawlme/cli 3.10.0 → 3.11.0

package/README.md

@@ -79,7 +79,7 @@ trawl spec [--json]                            Print a versioned, machine-readab
 - `list`/`get` also show a **health** badge next to the status badge. By default it reads the scrap's own `lastCronOutcome` field (always present, no extra cost): `⚠ cron paused` when the last scheduled tick was skipped for being unhealthy, `—` otherwise — a breadcrumb of the last tick, not a live read (never set on a no-cron scrap, can lag by one tick). `list --unhealthy` asks the API to filter to scraps whose *current* consecutive-failure streak is 3+ (trawl_node's own threshold) and annotates each with the exact `consecutiveFailedRuns`/`unhealthySince` — shown instead of the badge whenever present, and never re-derived client-side from history. `--json` carries whichever fields the request produced: `lastCronOutcome` always, `consecutiveFailedRuns`/`unhealthySince` only when `--unhealthy` was passed. **Old-server safety:** a server predating trawl_node#1952 silently ignores the unknown `--unhealthy` query param and returns everything, unfiltered — the CLI detects that (no returned item carries `consecutiveFailedRuns`) and prints a stderr warning instead of presenting the full list as "your unhealthy scraps".
 - **Long-running calls (`create`, `run`, `data --fresh`, `trigger --wait`):** these hit server-side paths that can legitimately take 30–250s+ (AI generation + scrap creation + a first run for `create`; proxy tier escalation + AI-fix retries for the other three) — the CLI arms a 300s timeout for exactly these four call sites instead of the generic 30s default. `TRAWL_TIMEOUT` (see below) still overrides ALL requests, including these — set it if you need a tighter or looser ceiling than 300s, but note a global override that tight also clamps `create`.
 - **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `run --watch` and `trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears. The watched run's outcome drives the exit code too, in BOTH human and `--json` mode: a genuinely failed terminal run, a poll timeout, or a persistently unreachable API all exit non-zero — a clean successful run is the only exit `0`. A run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>` (human mode) — see the `--json` shape below. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
-- `spec --json` prints the CLI's own command tree — `{specVersion, cliVersion, commands[], exitCodes, errorKinds, kindExitCodes}` — DERIVED at runtime by walking the live commander tree (never a hand-maintained file, which would silently drift from reality). Each entry in `commands[]` carries its full path (e.g. `"scraps account session set"`), description, `hidden` (the legacy `scraps <verb>` aliases above), `leaf` (false for a pure namespace/group node like `scraps`/`skills`/`telemetry` — invoking one directly is a guaranteed-failing tool, not a real command), `aliases`, `arguments`, and `options`; `exitCodes`/`errorKinds`/`kindExitCodes` are read from the exact same source `classifyError` uses (see [Exit codes](#exit-codes)) — never a second copy. `kindExitCodes` is the inverse of `exitCodes`: `kind -> exitCode`, since exit code `1` alone is a shared bucket (`api`/`refused`/`unknown`/`in_progress`/`run_failed`/`upgrade_failed`) that `exitCodes`' flat label can't disambiguate. Without `--json`, `spec` prints one short human line (version + visible command count) pointing at `--json`.
+- `spec --json` prints the CLI's own command tree — `{specVersion, cliVersion, commands[], exitCodes, errorKinds, kindExitCodes, docsUrl?, llmsUrl?}` — DERIVED at runtime by walking the live commander tree (never a hand-maintained file, which would silently drift from reality). Each entry in `commands[]` carries its full path (e.g. `"scraps account session set"`), description, `hidden` (the legacy `scraps <verb>` aliases above), `leaf` (false for a pure namespace/group node like `scraps`/`skills`/`telemetry` — invoking one directly is a guaranteed-failing tool, not a real command), `aliases`, `arguments`, `options`, and an optional per-command `docs` deep link (e.g. every `scraps account *` command points at the account-sessions guide); `exitCodes`/`errorKinds`/`kindExitCodes` are read from the exact same source `classifyError` uses (see [Exit codes](#exit-codes)) — never a second copy. `kindExitCodes` is the inverse of `exitCodes`: `kind -> exitCode`, since exit code `1` alone is a shared bucket (`api`/`refused`/`unknown`/`in_progress`/`run_failed`/`upgrade_failed`) that `exitCodes`' flat label can't disambiguate. `docsUrl` is resolved server-first (`externalDocs.url` on the configured API base's own OpenAPI document, when declared), else derived from a KNOWN first-party `trawl.me` API host, else **omitted entirely** — never a guessed URL pointed at the wrong docs host for a self-hosted install. `llmsUrl` and every per-command `docs` link are narrower: they only ever come from that same known-host derivation, NEVER from a server-declared `docsUrl` — this CLI's own guide slugs have no reason to exist on a third party's own docs root, so a self-hosted server that declares `externalDocs.url` gets a correct top-level `docsUrl` but no `llmsUrl` and no per-command `docs` links. A `failureKind:"auth"` run's JSON payload (`doctor`/`data --errors`/`run-info`) carries the same `docs` field, by the same known-host-only rule. Without `--json`, `spec` prints one short human line (version + visible command count) pointing at `--json`.
 - `run --json`/`trigger --json` bypass the spinner and print the raw launch/trigger payload on stdout; combined with `--watch`, every intermediate progress line stays suppressed (stdout stays pure JSON) and, once the watch reaches its outcome, exactly ONE final NDJSON line is emitted: `{"runId","status"}` (the honest terminal status — `success`/`error`/`empty`/`regression`/…), `{"runId","status":"timeout"}` on a poll timeout, or `{"runId","status":"poll_error","error"}` if the API stays unreachable for several consecutive polls — `process.exitCode` is non-zero for all three except a genuine success. `scraps watch --json` emits one raw JSON object per activity line (NDJSON) instead of the formatted `[time] message` text — there's no single final payload to wait for on a live stream.
 
 ### Scrap management

package/dist/commands/scraps.js

@@ -12,6 +12,34 @@ import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix, isAuthWa
 import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 import { maybeShowReferralTip } from '../lib/tips.js';
 import { maybeSuggestSkillsForAuthWall } from '../lib/skillsNudge.js';
+import { getApiUrl } from '../lib/config.js';
+import { resolveDocsUrls, resolveFailureKindDocsUrl } from '../lib/docs.js';
+/**
+ * #185 — `{ docs }` (spreadable, empty object when nothing to add) for a
+ * run's JSON payload (`doctor`/`data --errors`/`run-info`), keyed on
+ * trawl_node's `failureKind` (NOT errors.ts's unrelated `ErrorEnvelope.kind`
+ * — see docs.ts's `FAILURE_KIND_DOC_PATHS` doc comment for why those two
+ * `'auth'`s must never be conflated). Reuses `isAuthWall` — the SAME
+ * staleness guard `formatDoctor`'s human hint and the #184 skills nudge
+ * already share (a `failureKind:'auth'` stamp survives a later
+ * success/regression patch, see `isAuthWall`'s own doc comment) — so a run
+ * that ultimately succeeded or degraded never carries a stale `docs` link
+ * either, exactly the invariant `detectWallVendor`/`isAuthWall` already
+ * enforce for the human-facing surfaces. One call site, one rule, reused by
+ * all three JSON surfaces below instead of three copies that could drift.
+ */
+function runDocsField(run) {
+    if (!isAuthWall(run))
+        return {};
+    // Whole resolved object (never just `.docsUrl`) so resolveFailureKindDocsUrl
+    // can gate on rung provenance — see docs.ts's DocsUrls.docsUrlIsDerived.
+    // This call never supplies `externalDocsUrl`, so `docsUrl` here can only
+    // ever be rung-2-derived or absent — never a rung-1 server-declared root —
+    // but the gate stays explicit rather than relying on that as an invariant.
+    const resolved = resolveDocsUrls({ apiBaseUrl: getApiUrl() });
+    const docs = resolveFailureKindDocsUrl(run.failureKind, resolved);
+    return docs ? { docs } : {};
+}
 /**
  * Print a usage/validation error consistently: human text to stderr, or a
  * machine envelope on stdout under --json (never both — reportError is the
@@ -1065,8 +1093,12 @@ export function attachDataCommand(parent, attachOpts = {}) {
             // --json is honored for BOTH outcomes (success or failure) — an agent
             // parsing `data --errors --json` must always get the flat run object,
             // never prose gated behind a status check. (#71 finding 13)
+            // #185 — `docs` rides alongside as a sibling field on the same flat
+            // object (never nested under `run`, since there's no wrapper shape
+            // here), present only for a live mapped failureKind (see
+            // runDocsField's doc comment).
             if (opts.json)
-                return json(pickRun(result.run));
+                return json({ ...pickRun(result.run), ...runDocsField(result.run) });
             if (result.run.status === true) {
                 console.log(chalk.green('✓ Last run succeeded. No errors to show.'));
                 return;
@@ -1270,6 +1302,11 @@ export function attachRunInfoCommand(parent, attachOpts = {}) {
             selector: h.errorSnapshot?.selector ?? null,
             emptyContext: h.emptyContext ?? null,
             createdAt: h.createdAt ?? null,
+            // #185 — present only for a live mapped failureKind (see
+            // runDocsField's doc comment); omitted, never `docs: undefined`, for
+            // every other run so this object's own JSON.stringify never grows an
+            // unexpected key on existing consumers.
+            ...runDocsField(h),
         };
         if (opts.json) {
             json(info);
@@ -1662,8 +1699,11 @@ scraps
         console.log(chalk.dim('No runs yet.'));
         return;
     }
+    // #185 — `docs` sits alongside `run`/`fix` (present only for a live
+    // mapped failureKind — see runDocsField's doc comment), never nested
+    // inside the allowlisted `run` object.
     if (opts.json)
-        return json({ run: pickRun(result.run), fix: pickFix(result.fix) });
+        return json({ run: pickRun(result.run), fix: pickFix(result.fix), ...runDocsField(result.run) });
     console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
     if (opts.autofix && result.fix) {
         console.log('\n' + formatAutofix(result.fix));

package/dist/commands/spec.d.ts

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import { type DocsUrls } from '../lib/docs.js';
 /**
  * `trawl spec --json` (#170) — a versioned, machine-readable description of
  * the command tree, so an agent can learn the CLI's surface without parsing
@@ -54,6 +55,18 @@ export interface CliSpecCommand {
     aliases: string[];
     arguments: CliSpecArgument[];
     options: CliSpecOption[];
+    /**
+     * #185 — a deep link into a specific guide when one is mapped for this
+     * command (docs.ts's `COMMAND_DOC_PATHS`, e.g. every `scraps account *`
+     * command -> the account-sessions guide). Omitted (never a guessed/generic
+     * link) whenever no guide is mapped, the top-level `docsUrl` itself
+     * couldn't be resolved, OR `docsUrl` resolved from rung 1 (a server-
+     * declared `externalDocs.url`) rather than rung 2 (this CLI's own known-host
+     * derivation) — appending our guide slug onto a third party's own docs root
+     * is exactly the confidently-wrong-404 defect this omission closes. See
+     * `resolveCommandDocsUrl` / `DocsUrls.docsUrlIsDerived`.
+     */
+    docs?: string;
 }
 export interface CliSpec {
     specVersion: 1;
@@ -81,12 +94,30 @@ export interface CliSpec {
      * (errors.ts's KIND_EXIT_CODES) — never a second copy.
      */
     kindExitCodes: Record<string, number>;
+    /**
+     * #185 — where the human-readable guides live, resolved via docs.ts's
+     * ladder (server `externalDocs.url` > derive from the API base's known
+     * `trawl.me` host > omit). Absent (never a guessed URL) when neither rung
+     * resolves — e.g. a self-hosted install with no `externalDocs` declared.
+     */
+    docsUrl?: string;
+    /** #185 — the llms.txt entry point alongside `docsUrl`, when resolvable.
+     *  See docs.ts's module doc comment for why this never rides along with a
+     *  server-declared `docsUrl` it wasn't itself derived from. */
+    llmsUrl?: string;
 }
 /**
  * Build the full spec from a live, already-constructed program (e.g.
  * `createProgram()`'s return value). Includes every node in the tree —
  * hidden legacy aliases (`scraps list`, …) included, flagged via `hidden`,
  * so a consumer that wants only the advertised surface can filter on it.
+ *
+ * #185 — `docs` is an already-RESOLVED `DocsUrls` (docs.ts's ladder run to
+ * completion), never computed in here: `buildSpec` stays pure/synchronous
+ * (no network, no config read) exactly as before, so every existing caller
+ * (the README-vs-spec contract test, the synthetic-tree unit tests) keeps
+ * working unchanged by simply omitting the parameter. Only `spec.ts`'s own
+ * action resolves rung 1 (a bounded fetch) before calling this.
  */
-export declare function buildSpec(program: Command): CliSpec;
+export declare function buildSpec(program: Command, docs?: DocsUrls): CliSpec;
 export declare const spec: Command;

package/dist/commands/spec.js

@@ -1,6 +1,9 @@
 import { Command, Help } from 'commander';
 import { json } from '../lib/format.js';
 import { EXIT_CODE_LABELS, ENVELOPE_KINDS, KIND_EXIT_CODES } from '../lib/errors.js';
+import { getApiUrl } from '../lib/config.js';
+import { api } from '../lib/api.js';
+import { resolveDocsUrls, resolveCommandDocsUrl } from '../lib/docs.js';
 function buildOption(option) {
     const entry = {
         long: option.long ?? '',
@@ -15,8 +18,8 @@ function buildOption(option) {
         entry.default = option.defaultValue;
     return entry;
 }
-function buildCommandEntry(cmd, name, hidden) {
-    return {
+function buildCommandEntry(cmd, name, hidden, docs = {}) {
+    const entry = {
         name,
         description: cmd.description(),
         hidden,
@@ -29,20 +32,29 @@ function buildCommandEntry(cmd, name, hidden) {
         })),
         options: cmd.options.map(buildOption),
     };
+    const docsLink = resolveCommandDocsUrl(name, docs);
+    if (docsLink)
+        entry.docs = docsLink;
+    return entry;
 }
 /**
  * Walk `cmd.commands` recursively, collecting one entry per node under its
  * FULL path name. `hidden` is read via commander's own
  * `Help#visibleCommands()` — the same idiom this codebase already uses
  * (scraps.test.ts's #108 describe block) — rather than reaching for the
- * private, untyped `_hidden` field directly.
+ * private, untyped `_hidden` field directly. The resolved `docs` object,
+ * when present, threads through so every entry can carry its own per-command
+ * `docs` deep link (#185) off the SAME resolved root — never a second lookup
+ * per node, and never flattened to a bare string (see docs.ts's
+ * `DocsUrls.docsUrlIsDerived` — the rung provenance must survive the walk
+ * unchanged so `resolveCommandDocsUrl` can still gate on it at each leaf).
  */
-function walk(cmd, prefix, out) {
+function walk(cmd, prefix, out, docs = {}) {
     const visible = new Set(new Help().visibleCommands(cmd));
     for (const sub of cmd.commands) {
         const name = prefix ? `${prefix} ${sub.name()}` : sub.name();
-        out.push(buildCommandEntry(sub, name, !visible.has(sub)));
-        walk(sub, name, out);
+        out.push(buildCommandEntry(sub, name, !visible.has(sub), docs));
+        walk(sub, name, out, docs);
     }
 }
 /**
@@ -50,11 +62,18 @@ function walk(cmd, prefix, out) {
  * `createProgram()`'s return value). Includes every node in the tree —
  * hidden legacy aliases (`scraps list`, …) included, flagged via `hidden`,
  * so a consumer that wants only the advertised surface can filter on it.
+ *
+ * #185 — `docs` is an already-RESOLVED `DocsUrls` (docs.ts's ladder run to
+ * completion), never computed in here: `buildSpec` stays pure/synchronous
+ * (no network, no config read) exactly as before, so every existing caller
+ * (the README-vs-spec contract test, the synthetic-tree unit tests) keeps
+ * working unchanged by simply omitting the parameter. Only `spec.ts`'s own
+ * action resolves rung 1 (a bounded fetch) before calling this.
  */
-export function buildSpec(program) {
+export function buildSpec(program, docs = {}) {
     const commands = [];
-    walk(program, '', commands);
-    return {
+    walk(program, '', commands, docs);
+    const spec = {
         specVersion: 1,
         cliVersion: program.version() ?? 'unknown',
         commands,
@@ -62,18 +81,71 @@ export function buildSpec(program) {
         errorKinds: [...ENVELOPE_KINDS],
         kindExitCodes: { ...KIND_EXIT_CODES },
     };
+    if (docs.docsUrl)
+        spec.docsUrl = docs.docsUrl;
+    if (docs.llmsUrl)
+        spec.llmsUrl = docs.llmsUrl;
+    return spec;
+}
+/**
+ * #185 — bounds the SOCKET, not just the promise, so a slow/dead server can
+ * never perceptibly slow `spec --json` down. Mirrors lib/tips.ts's
+ * FLAG_CHECK_TIMEOUT_MS for the same reason: this is the one surface allowed
+ * a network call at all, and only because it's a deliberate, once-per-
+ * invocation agent probe.
+ *
+ * This is a REAL wall-clock ceiling, not merely a promise-level one: an
+ * earlier version of this fetch used `api.publicGet` (Node's global
+ * `fetch()` + `AbortSignal.timeout()`), which bounds the promise but not the
+ * OS-level connection — against a routable-but-silently-dropping host (a
+ * dropped SYN, no RST; a realistic firewalled/air-gapped shape, the very
+ * audience this feature cites) the promise rejected at ~2005ms while the
+ * PROCESS didn't exit until ~10.5s later, waiting out Node's own internal
+ * connect-timeout. `api.probeJson` (see its own doc comment in lib/api.ts)
+ * fixes this by managing the raw socket directly — an independent timer
+ * that `req.destroy()`s the connection, never relying on the idle-based
+ * `http.request` `timeout` option. Re-measured after the fix, same
+ * black-holed host, via the exact repro command (`time env
+ * TRAWL_API_URL=https://192.0.2.1 node dist/index.js spec --json`): total
+ * process time ~2.43s/~2.47s across two runs (the 2000ms bound plus Node
+ * startup and spec-tree construction), not ~10.68s.
+ */
+const EXTERNAL_DOCS_FETCH_TIMEOUT_MS = 2_000;
+/**
+ * Rung 1 — read `externalDocs.url` off the OpenAPI document the configured
+ * API base itself serves at `/api/spec.json`. Unset (null) server-side
+ * today, so this resolves to `null` in practice; forward-looking for when
+ * it isn't. ANY failure — network error, timeout, a malformed/unexpected
+ * response shape — is indistinguishable from "not declared" here: resolves
+ * to `null`, never throws (api.probeJson's own contract — see its doc
+ * comment). `spec --json` must stay a pure, reliable, side-effect-free probe
+ * even against an unreachable or ancient server.
+ */
+async function fetchExternalDocsUrl() {
+    const data = await api.probeJson('/api/spec.json', {
+        timeoutMs: EXTERNAL_DOCS_FETCH_TIMEOUT_MS,
+    });
+    const url = data?.externalDocs?.url;
+    return typeof url === 'string' && url ? url : null;
 }
 export const spec = new Command('spec')
     .description('Print a versioned, machine-readable description of the command tree')
     .option('--json', 'Output as JSON')
-    .action((opts) => {
+    .action(async (opts) => {
     // `spec` is registered as a direct child of the program root
     // (index.ts's createProgram), so `.parent` IS that root by the time this
     // action ever runs — commander sets it in `addCommand()`. Falling back
     // to `spec` itself only matters for an isolated unit invocation (e.g. a
     // test driving `spec.parseAsync()` directly, unattached to a program).
     const root = spec.parent ?? spec;
-    const cliSpec = buildSpec(root);
+    const apiBaseUrl = getApiUrl();
+    // #185 — rung 1 (the server fetch) only runs under --json: the
+    // plain-text branch below never reads docsUrl at all, so paying a
+    // network round-trip for it would be pure waste. Rungs 2/3 (sync,
+    // no network) still apply either way via the fallback below.
+    const externalDocsUrl = opts.json ? await fetchExternalDocsUrl() : null;
+    const docs = resolveDocsUrls({ apiBaseUrl, externalDocsUrl });
+    const cliSpec = buildSpec(root, docs);
     if (opts.json) {
         json(cliSpec);
         return;

package/dist/index.d.ts

@@ -32,6 +32,15 @@ export declare function resolveCommandName(actionCommand: Command | undefined):
  */
 export declare function collectCommandNames(root: Command): string[];
 export declare function createProgram(): Command;
+/**
+ * #185 — see the `addHelpText('afterAll', …)` call above for why this is
+ * unconditional (no TTY/--json gate) and why a thrown error must never
+ * escape: commander calls this synchronously while already writing help
+ * output, so a throw here would crash a `--help` invocation, the one code
+ * path this whole feature is not allowed to touch (see docs.ts's own
+ * `docsFooterLine` for the "never a guessed URL" contract this composes).
+ */
+export declare function docsFooterText(): string;
 /**
  * True when this module is the process entrypoint (not merely imported by a test).
  *
@@ -96,6 +105,14 @@ export declare function isBareInvocation(argv: string[]): boolean;
  * overstates its own invariant is worse than no comment, because the next
  * reader trusts it.
  *
+ * #185 — `spec --json` (not plain `spec`) now DOES make its own bounded
+ * (2s), swallowed-on-failure GET for `externalDocs.url` (see spec.ts's
+ * `fetchExternalDocsUrl`) — this is not a regression of the "no mutation"
+ * invariant above (a GET mutates nothing, and any failure — including no
+ * egress at all — degrades to the sync host-derivation fallback, never a
+ * thrown error), just a second, narrower kind of side effect this guard was
+ * never meant to suppress in the first place.
+ *
  * Before this, `trawl spec --json` silently re-synced
  * `~/.claude/skills` (and `./.claude/skills`) and printed `trawl: re-synced
  * skill …` lines to stderr BEFORE the JSON payload — an agent's very first

package/dist/index.js

@@ -20,6 +20,8 @@ import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from '
 import { classifyError, reportError, stripCommanderErrorPrefix, retryFieldsFor } from './lib/errors.js';
 import { renderPinch, pinchEnabled } from './lib/pinch.js';
 import { maybeNotifyUpdate, scheduleUpdateCheck } from './lib/updateNotifier.js';
+import { getApiUrl } from './lib/config.js';
+import { resolveDocsUrls, docsFooterLine } from './lib/docs.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -142,8 +144,37 @@ export function createProgram() {
     program.addCommand(logout);
     program.addCommand(telemetry);
     program.addCommand(upgrade);
+    // #185 — one dim line pointing at the docs, appended after EVERY `--help`
+    // in the tree (registering 'afterAll' on the root fires for a subcommand's
+    // own `--help` too — commander emits the afterAllHelp event on every
+    // ancestor of whichever command's outputHelp() ran, root included).
+    // Gated the way lib/tips.ts gates its own footer-shaped output: a pure,
+    // synchronous helper (docsFooterText, exported for unit testing) wrapped
+    // in try/catch so a broken footer can never turn a clean `--help` into a
+    // crash — but deliberately WITHOUT tips.ts's TTY/--json gate: `--help`
+    // itself never emits a --json payload (nothing here can pollute that
+    // channel), and a docs line inside `--help | less` is exactly the kind of
+    // thing worth keeping, unlike a promotional nudge.
+    program.addHelpText('afterAll', docsFooterText);
     return program;
 }
+/**
+ * #185 — see the `addHelpText('afterAll', …)` call above for why this is
+ * unconditional (no TTY/--json gate) and why a thrown error must never
+ * escape: commander calls this synchronously while already writing help
+ * output, so a throw here would crash a `--help` invocation, the one code
+ * path this whole feature is not allowed to touch (see docs.ts's own
+ * `docsFooterLine` for the "never a guessed URL" contract this composes).
+ */
+export function docsFooterText() {
+    try {
+        const line = docsFooterLine(resolveDocsUrls({ apiBaseUrl: getApiUrl() }).docsUrl);
+        return line ? chalk.dim(line) : '';
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * True when this module is the process entrypoint (not merely imported by a test).
  *
@@ -228,6 +259,14 @@ export function isBareInvocation(argv) {
  * overstates its own invariant is worse than no comment, because the next
  * reader trusts it.
  *
+ * #185 — `spec --json` (not plain `spec`) now DOES make its own bounded
+ * (2s), swallowed-on-failure GET for `externalDocs.url` (see spec.ts's
+ * `fetchExternalDocsUrl`) — this is not a regression of the "no mutation"
+ * invariant above (a GET mutates nothing, and any failure — including no
+ * egress at all — degrades to the sync host-derivation fallback, never a
+ * thrown error), just a second, narrower kind of side effect this guard was
+ * never meant to suppress in the first place.
+ *
  * Before this, `trawl spec --json` silently re-synced
  * `~/.claude/skills` (and `./.claude/skills`) and printed `trawl: re-synced
  * skill …` lines to stderr BEFORE the JSON payload — an agent's very first

package/dist/lib/api.d.ts

@@ -95,6 +95,11 @@ export interface RequestOptions {
 export declare const api: {
     get: <T>(path: string, opts?: RequestOptions) => Promise<T>;
     publicGet: <T>(path: string, opts?: RequestOptions) => Promise<T>;
+    /** See `probeJson`'s own doc comment — hard-bounded, probe-only, never for
+     *  a command's real work. Today's one caller: spec.ts's fetchExternalDocsUrl. */
+    probeJson: <T>(path: string, opts: {
+        timeoutMs: number;
+    }) => Promise<T | null>;
     getText: (path: string, opts?: RequestOptions) => Promise<string>;
     post: <T>(path: string, body?: unknown, opts?: RequestOptions) => Promise<T>;
     put: <T>(path: string, body?: unknown, opts?: RequestOptions) => Promise<T>;

package/dist/lib/api.js

@@ -1,6 +1,8 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 import { getApiUrl, getToken, getAuthMode, getLiveAuthEnvVar } from './config.js';
 import { parseServerJson } from './json.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -518,6 +520,119 @@ async function publicGet(path, reqOpts = {}) {
         throw new Error('Invalid JSON in server response');
     }
 }
+/**
+ * A hard-bounded, PROBE-ONLY GET — never use this for a command's real work
+ * (no auth headers, no retry, no NetworkError-with-cause classification).
+ *
+ * trawl_cli#185 defect: every OTHER fetch in this file rides Node's global
+ * `fetch()` + `AbortSignal.timeout()`, which bounds the PROMISE, not the
+ * process. Aborting a fetch mid-connect does not necessarily tear down an
+ * in-flight TCP/TLS handshake — a documented Node/undici characteristic —
+ * so against a routable-but-silently-dropping host (a dropped SYN, never a
+ * RST — a realistic firewalled/air-gapped shape) the dangling socket keeps
+ * the event loop alive until Node's OWN internal connect-timeout eventually
+ * fires. Measured on this host: a bare `fetch()` + `AbortSignal.timeout(2000)`
+ * against such a host rejects its promise at ~2005ms, but the PROCESS does
+ * not exit until ~10.5s later — not configurable from here, and not paid by
+ * `ECONNREFUSED` (~0.13s) or a failed DNS lookup (~0.29s), only by the
+ * silent-drop shape. Every other command in this file accepts that risk
+ * because the user explicitly asked for that network call (`trawl ping`
+ * hanging on an unreachable host is the command doing its job — nothing to
+ * fix there). This primitive exists for the one case where the network call
+ * ITSELF is optional: `spec --json`'s own doc-discovery probe (the one
+ * command an agent runs to orient itself) has no business costing 10.5s to
+ * learn a host is unreachable, so this manages the raw socket directly.
+ *
+ * The timeout here is an INDEPENDENT `setTimeout` that calls `req.destroy()`
+ * — deliberately NOT `http.request`'s own `timeout` option (idle-based via
+ * `socket.setTimeout`, so it only fires when zero bytes arrive for that
+ * long — a coincidentally-same condition against a silent black hole, but a
+ * dishonest bound in general: it would never fire against a host that
+ * connects instantly then trickles bytes just often enough to reset the
+ * idle clock). Destroying the request/socket on this timer is what actually
+ * frees the OS-level handle so the process can exit promptly instead of
+ * waiting out Node's own multi-second connect-timeout — verified empirically
+ * (same black-holed host): total process time dropped from ~10.5s to ~2.0s
+ * with this change.
+ *
+ * Resolves to `null` on ANY failure (timeout, refusal, non-2xx, malformed
+ * JSON, an unsupported protocol) — never throws — so the one caller
+ * (spec.ts's fetchExternalDocsUrl) needs no try/catch of its own. This is
+ * NOT automatic: `node:http`/`node:https`' own `request()` throws
+ * SYNCHRONOUSLY (`ERR_INVALID_PROTOCOL`) for a URL whose protocol doesn't
+ * match the module (e.g. a stray `ftp://` in a misconfigured `TRAWL_API_URL`)
+ * — inside a Promise executor a synchronous throw becomes a REJECTED
+ * promise, which would have propagated straight through `fetchExternalDocsUrl`
+ * and turned `spec --json` into an error envelope instead of the spec.
+ * Reproduced: `TRAWL_API_URL=ftp://x node dist/index.js spec --json` failed
+ * entirely before this guard was added. The explicit protocol check below
+ * closes that.
+ *
+ * Two more deliberate departures from every other call in this file:
+ *  - `TRAWL_TIMEOUT` (getTimeoutMs's env override, #91) is NOT consulted
+ *    here — `opts.timeoutMs` is absolute. An operator raising that ceiling
+ *    for a genuinely long-running command (e.g. LONG_RUN_TIMEOUT_MS's 300s)
+ *    must never make an OPTIONAL probe wait 300s too; the two knobs measure
+ *    different things and must not share a dial.
+ *  - Redirects are NOT followed (global `fetch()`, used everywhere else in
+ *    this file, follows them by default; raw `http`/`https` `request()`
+ *    does not). For this probe a 3xx is just another non-2xx -> `null` ->
+ *    fall through to rung 2 — an acceptable degradation, not a bug.
+ */
+function probeJson(path, opts) {
+    return new Promise((settle) => {
+        let url;
+        try {
+            url = new URL(`${getApiUrl()}${path}`);
+        }
+        catch {
+            settle(null);
+            return;
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            settle(null);
+            return;
+        }
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            settle(value);
+        };
+        const transport = url.protocol === 'http:' ? httpRequest : httpsRequest;
+        const req = transport(url, { headers: { 'User-Agent': USER_AGENT } }, (res) => {
+            if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                res.resume(); // drain so the socket can be released
+                finish(null);
+                return;
+            }
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                body += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    finish(JSON.parse(body));
+                }
+                catch {
+                    finish(null);
+                }
+            });
+            res.on('error', () => finish(null));
+        });
+        // The independent, non-idle-based ceiling this function exists for —
+        // fires regardless of connect/response state and forcibly destroys the
+        // socket, unlike AbortSignal.timeout() everywhere else in this file.
+        const timer = setTimeout(() => {
+            req.destroy(new Error(`probe to ${url.href} timed out after ${opts.timeoutMs}ms`));
+        }, opts.timeoutMs);
+        req.on('error', () => finish(null));
+        req.end();
+    });
+}
 async function getText(path, reqOpts = {}) {
     const token = getToken();
     if (!token)
@@ -537,6 +652,9 @@ async function getText(path, reqOpts = {}) {
 export const api = {
     get: (path, opts) => request(path, {}, opts),
     publicGet: (path, opts) => publicGet(path, opts),
+    /** See `probeJson`'s own doc comment — hard-bounded, probe-only, never for
+     *  a command's real work. Today's one caller: spec.ts's fetchExternalDocsUrl. */
+    probeJson: (path, opts) => probeJson(path, opts),
     getText: (path, opts) => getText(path, opts),
     post: (path, body, opts) => request(path, {
         method: 'POST',

package/dist/lib/docs.d.ts

@@ -0,0 +1,140 @@
+/**
+ * trawl_cli#185 — ONE source of truth for the docs URL(s) an agent (or
+ * human) can be pointed at from three surfaces: `spec --json` (top-level
+ * `docsUrl`/`llmsUrl` + a per-command `docs` deep link), a run's JSON
+ * payload (`doctor`/`data --errors`/`run-info`, keyed on `failureKind` —
+ * NOT errors.ts's unrelated `ErrorEnvelope.kind`, see the doc comment on
+ * `FAILURE_KIND_DOC_PATHS` below), and the `--help` footer. Three hardcoded
+ * lists here would diverge within months — that exact "same fact computed
+ * in two places" defect has recurred repeatedly across this epic — so every
+ * surface reads these same tables/functions, never its own copy.
+ *
+ * Resolution ladder (issue #185 — all three rungs REQUIRED, in this order,
+ * evaluated PER FIELD, never as one bundled decision — see `resolveDocsUrls`):
+ *
+ *  1. Prefer the server. `externalDocs.url` on the OpenAPI document at
+ *     `<apiBase>/api/spec.json` is the standard OpenAPI field for exactly
+ *     this, and reading it makes a self-hosted install work with ZERO CLI
+ *     change. It is unset (null) server-side today, so this is
+ *     forward-looking — build it anyway, and it must win outright over rung
+ *     2 when present. The one caller allowed to fetch it is `spec.ts`'s own
+ *     action, bounded and swallowed-on-failure (mirrors lib/tips.ts's
+ *     `isReferralProgramUserFacing`) — a deliberate, once-per-invocation
+ *     agent probe, not "every command". Every other surface (an error
+ *     payload on an arbitrary failing command, the `--help` footer) must
+ *     never add a network call or a failure mode to a command nobody asked
+ *     to hit the docs host for — see `resolveDocsUrls`'s `externalDocsUrl`
+ *     parameter, which only ever arrives pre-fetched.
+ *  2. Else derive, by stripping a leading `api.` host label from the
+ *     configured API base — but ONLY for a KNOWN first-party `trawl.me`
+ *     host. `api.trawl.me` -> `trawl.me` (prod: API and docs are genuinely
+ *     on different hosts); `dev.trawl.me` (no `api.` prefix) -> unchanged
+ *     (dev serves docs on the SAME host as its API). A generic, unscoped
+ *     `api.`-strip applied to ANY host is itself a guess — it assumes a
+ *     self-hosted `api.acme.internal` serves docs at `acme.internal`, which
+ *     nothing here can know. Scoping the strip to `trawl.me` is what makes
+ *     rung 3 (below) ever actually fire for a self-hosted base.
+ *  3. Else OMIT the field entirely. Never emit a guessed URL (issue's Rule
+ *     3): a wrong URL sends an agent to a 404 WITH CONFIDENCE, worse than no
+ *     URL at all — a self-hosted install with no server-declared
+ *     `externalDocs` and a base outside `trawl.me` gets no `docsUrl`/
+ *     `llmsUrl`, not a hopeful default pointed at OUR docs host.
+ *
+ * `llmsUrl` has no OpenAPI-standard field to read (rung 1 contributes
+ * nothing to it) — deriving it from the ORIGIN of a server-declared
+ * `externalDocs.url` would itself be a guess for a self-hosted install
+ * (rule 3 again), so `llmsUrl` resolves ONLY via rung 2 (the known-host
+ * derivation) or omission. It never rides along with a rung-1 `docsUrl`.
+ *
+ * PROVENANCE (defect fix, reviewer repro against a live mock server): the
+ * top-level `docsUrl` above is deliberately the FLATTENED "whichever rung
+ * won" value — right for a human reading `spec --json`'s top-level field,
+ * WRONG as an input to `resolveCommandDocsUrl`/`resolveFailureKindDocsUrl`
+ * below. Those two append one of THIS CLI's own hardcoded guide slugs
+ * (`COMMAND_DOC_PATHS`/`FAILURE_KIND_DOC_PATHS`) onto whatever `docsUrl`
+ * resolved — safe onto a rung-2 root we derived ourselves (we know
+ * trawl.me's guide tree), never safe onto a rung-1 root (an arbitrary
+ * third party's own docs site, self-hosted, with no reason to carry our
+ * slugs). A mock server declaring `externalDocs.url: 'http://h/guide'`
+ * used to get `http://h/guide/build-your-scrap/account-sessions` appended
+ * — a confidently-wrong 404. So `DocsUrls.docsUrlIsDerived` carries rung
+ * provenance ALONGSIDE the string (never flattened to a bare string again)
+ * and both deep-link functions now take the whole `DocsUrls`-shaped object
+ * and gate construction on that flag — see its own doc comment below.
+ */
+export interface DocsUrls {
+    docsUrl?: string;
+    llmsUrl?: string;
+    /**
+     * True iff `docsUrl` came from rung 2 (THIS CLI's own derivation from a
+     * KNOWN `trawl.me` host) — the only case where it is safe to append one of
+     * this CLI's own guide slugs onto it (see `resolveCommandDocsUrl`/
+     * `resolveFailureKindDocsUrl`). False when `docsUrl` is a rung-1
+     * SERVER-declared root instead — an arbitrary third party's own docs site,
+     * which has no reason to host our guide slugs, even when that server
+     * happens to run on a `trawl.me` host. Always a defined boolean whenever
+     * `docsUrl` itself is present; undefined only when `docsUrl` is undefined
+     * too (rung 3 — nothing resolved at all).
+     */
+    docsUrlIsDerived?: boolean;
+}
+/**
+ * Rung 2 — see the module doc comment. Returns `{ protocol, host }` for a
+ * KNOWN first-party API base (preserving the base's own protocol rather
+ * than assuming `https:`), or `null` when the base isn't recognized
+ * (self-hosted, a custom domain, `localhost`, an unparseable string, …) —
+ * `null` must propagate to omission (rung 3), never to a guessed host.
+ */
+export declare function deriveDocsOrigin(apiBaseUrl: string): {
+    protocol: string;
+    host: string;
+} | null;
+/** Same rung as `deriveDocsOrigin`, collapsed to just the host string —
+ *  convenience for a caller that only needs the derived host, not the
+ *  protocol (kept as its own export since `docs.test.ts` exercises the host
+ *  derivation independently of protocol handling). */
+export declare function deriveDocsHost(apiBaseUrl: string): string | null;
+/**
+ * The full ladder, PER FIELD (see module doc comment for why `llmsUrl`
+ * cannot ride along with a rung-1 `docsUrl`). Pure and synchronous — no
+ * network, safe to call from any surface (an error payload, the `--help`
+ * footer) without adding latency or a new failure mode. `externalDocsUrl`
+ * is rung 1's input: only ever supplied by `spec.ts`'s action, after its
+ * own bounded, swallowed-on-failure fetch — every other caller omits it and
+ * gets rungs 2/3 only.
+ */
+export declare function resolveDocsUrls(opts: {
+    apiBaseUrl: string;
+    externalDocsUrl?: string | null;
+}): DocsUrls;
+/**
+ * `resolveCommandDocsUrl` returns `undefined` (never a bare path or a
+ * relative link) whenever any of three things is missing — `docsUrl`
+ * unresolved (rung 3 already fired), `docsUrl` resolved but NOT derived
+ * (rung 1 — a server-declared root; see `DocsUrls.docsUrlIsDerived`'s doc
+ * comment for why appending our own guide slug onto a third party's root is
+ * exactly the confidently-wrong-404 defect this gate closes), or no guide is
+ * mapped for this command — so a spec consumer never has to special-case a
+ * partial value. Takes the whole resolved `DocsUrls` object (never a bare
+ * string) specifically so this provenance can never again be flattened away
+ * before it reaches here.
+ */
+export declare function resolveCommandDocsUrl(commandName: string, docs: Pick<DocsUrls, 'docsUrl' | 'docsUrlIsDerived'>): string | undefined;
+/** Same "undefined unless docsUrl is resolved AND derived (rung 2)" gate as
+ *  `resolveCommandDocsUrl` above, same reason — never append this CLI's own
+ *  guide slug onto a rung-1 server-declared root. Callers MUST gate the call
+ *  on their own staleness rule first (e.g. `doctor.ts`'s `isAuthWall`) — this
+ *  function only knows the string-to-path mapping, not whether a stamped
+ *  `failureKind` is still live on a run patched afterward. */
+export declare function resolveFailureKindDocsUrl(kind: string | null | undefined, docs: Pick<DocsUrls, 'docsUrl' | 'docsUrlIsDerived'>): string | undefined;
+/**
+ * `--help` footer text (issue #185 scope item 3) — a single dim line, for
+ * humans, e.g. "Docs: https://trawl.me/docs". Returns `undefined` (never an
+ * empty or guessed line) when no `docsUrl` resolved — mirrors
+ * lib/tips.ts's shape (a pure function separated from IO, so it's testable
+ * without mocking chalk/console) but NOT its TTY gate: tips.ts suppresses a
+ * promotional nudge from piped output, but a docs line inside `--help |
+ * less` is exactly the kind of thing worth keeping. Un-colored here — the
+ * caller (index.ts) applies `chalk.dim` so this stays trivially testable.
+ */
+export declare function docsFooterLine(docsUrl?: string): string | undefined;

package/dist/lib/docs.js

@@ -0,0 +1,238 @@
+/**
+ * trawl_cli#185 — ONE source of truth for the docs URL(s) an agent (or
+ * human) can be pointed at from three surfaces: `spec --json` (top-level
+ * `docsUrl`/`llmsUrl` + a per-command `docs` deep link), a run's JSON
+ * payload (`doctor`/`data --errors`/`run-info`, keyed on `failureKind` —
+ * NOT errors.ts's unrelated `ErrorEnvelope.kind`, see the doc comment on
+ * `FAILURE_KIND_DOC_PATHS` below), and the `--help` footer. Three hardcoded
+ * lists here would diverge within months — that exact "same fact computed
+ * in two places" defect has recurred repeatedly across this epic — so every
+ * surface reads these same tables/functions, never its own copy.
+ *
+ * Resolution ladder (issue #185 — all three rungs REQUIRED, in this order,
+ * evaluated PER FIELD, never as one bundled decision — see `resolveDocsUrls`):
+ *
+ *  1. Prefer the server. `externalDocs.url` on the OpenAPI document at
+ *     `<apiBase>/api/spec.json` is the standard OpenAPI field for exactly
+ *     this, and reading it makes a self-hosted install work with ZERO CLI
+ *     change. It is unset (null) server-side today, so this is
+ *     forward-looking — build it anyway, and it must win outright over rung
+ *     2 when present. The one caller allowed to fetch it is `spec.ts`'s own
+ *     action, bounded and swallowed-on-failure (mirrors lib/tips.ts's
+ *     `isReferralProgramUserFacing`) — a deliberate, once-per-invocation
+ *     agent probe, not "every command". Every other surface (an error
+ *     payload on an arbitrary failing command, the `--help` footer) must
+ *     never add a network call or a failure mode to a command nobody asked
+ *     to hit the docs host for — see `resolveDocsUrls`'s `externalDocsUrl`
+ *     parameter, which only ever arrives pre-fetched.
+ *  2. Else derive, by stripping a leading `api.` host label from the
+ *     configured API base — but ONLY for a KNOWN first-party `trawl.me`
+ *     host. `api.trawl.me` -> `trawl.me` (prod: API and docs are genuinely
+ *     on different hosts); `dev.trawl.me` (no `api.` prefix) -> unchanged
+ *     (dev serves docs on the SAME host as its API). A generic, unscoped
+ *     `api.`-strip applied to ANY host is itself a guess — it assumes a
+ *     self-hosted `api.acme.internal` serves docs at `acme.internal`, which
+ *     nothing here can know. Scoping the strip to `trawl.me` is what makes
+ *     rung 3 (below) ever actually fire for a self-hosted base.
+ *  3. Else OMIT the field entirely. Never emit a guessed URL (issue's Rule
+ *     3): a wrong URL sends an agent to a 404 WITH CONFIDENCE, worse than no
+ *     URL at all — a self-hosted install with no server-declared
+ *     `externalDocs` and a base outside `trawl.me` gets no `docsUrl`/
+ *     `llmsUrl`, not a hopeful default pointed at OUR docs host.
+ *
+ * `llmsUrl` has no OpenAPI-standard field to read (rung 1 contributes
+ * nothing to it) — deriving it from the ORIGIN of a server-declared
+ * `externalDocs.url` would itself be a guess for a self-hosted install
+ * (rule 3 again), so `llmsUrl` resolves ONLY via rung 2 (the known-host
+ * derivation) or omission. It never rides along with a rung-1 `docsUrl`.
+ *
+ * PROVENANCE (defect fix, reviewer repro against a live mock server): the
+ * top-level `docsUrl` above is deliberately the FLATTENED "whichever rung
+ * won" value — right for a human reading `spec --json`'s top-level field,
+ * WRONG as an input to `resolveCommandDocsUrl`/`resolveFailureKindDocsUrl`
+ * below. Those two append one of THIS CLI's own hardcoded guide slugs
+ * (`COMMAND_DOC_PATHS`/`FAILURE_KIND_DOC_PATHS`) onto whatever `docsUrl`
+ * resolved — safe onto a rung-2 root we derived ourselves (we know
+ * trawl.me's guide tree), never safe onto a rung-1 root (an arbitrary
+ * third party's own docs site, self-hosted, with no reason to carry our
+ * slugs). A mock server declaring `externalDocs.url: 'http://h/guide'`
+ * used to get `http://h/guide/build-your-scrap/account-sessions` appended
+ * — a confidently-wrong 404. So `DocsUrls.docsUrlIsDerived` carries rung
+ * provenance ALONGSIDE the string (never flattened to a bare string again)
+ * and both deep-link functions now take the whole `DocsUrls`-shaped object
+ * and gate construction on that flag — see its own doc comment below.
+ */
+/** The one first-party domain this CLI knows to serve docs — see rung 2 in
+ *  the module doc comment above. Deliberately not "any host", so an
+ *  unrecognized (self-hosted/custom) base falls through to omission. */
+const KNOWN_DOCS_DOMAIN = 'trawl.me';
+/**
+ * Rung 2 — see the module doc comment. Returns `{ protocol, host }` for a
+ * KNOWN first-party API base (preserving the base's own protocol rather
+ * than assuming `https:`), or `null` when the base isn't recognized
+ * (self-hosted, a custom domain, `localhost`, an unparseable string, …) —
+ * `null` must propagate to omission (rung 3), never to a guessed host.
+ */
+export function deriveDocsOrigin(apiBaseUrl) {
+    let url;
+    try {
+        url = new URL(apiBaseUrl);
+    }
+    catch {
+        return null;
+    }
+    const hostname = url.hostname.toLowerCase();
+    const stripped = hostname.startsWith('api.') ? hostname.slice('api.'.length) : hostname;
+    if (stripped === KNOWN_DOCS_DOMAIN || stripped.endsWith(`.${KNOWN_DOCS_DOMAIN}`)) {
+        return { protocol: url.protocol, host: stripped };
+    }
+    return null;
+}
+/** Same rung as `deriveDocsOrigin`, collapsed to just the host string —
+ *  convenience for a caller that only needs the derived host, not the
+ *  protocol (kept as its own export since `docs.test.ts` exercises the host
+ *  derivation independently of protocol handling). */
+export function deriveDocsHost(apiBaseUrl) {
+    return deriveDocsOrigin(apiBaseUrl)?.host ?? null;
+}
+/**
+ * The full ladder, PER FIELD (see module doc comment for why `llmsUrl`
+ * cannot ride along with a rung-1 `docsUrl`). Pure and synchronous — no
+ * network, safe to call from any surface (an error payload, the `--help`
+ * footer) without adding latency or a new failure mode. `externalDocsUrl`
+ * is rung 1's input: only ever supplied by `spec.ts`'s action, after its
+ * own bounded, swallowed-on-failure fetch — every other caller omits it and
+ * gets rungs 2/3 only.
+ */
+export function resolveDocsUrls(opts) {
+    const origin = deriveDocsOrigin(opts.apiBaseUrl);
+    const derived = origin
+        ? {
+            docsUrl: `${origin.protocol}//${origin.host}/docs`,
+            llmsUrl: `${origin.protocol}//${origin.host}/llms.txt`,
+            docsUrlIsDerived: true,
+        }
+        : {};
+    if (opts.externalDocsUrl) {
+        // Rung 1 wins for docsUrl outright; llmsUrl stays rung-2-only (see doc
+        // comment) — a self-hosted `externalDocsUrl` outside `trawl.me` yields
+        // `{ docsUrl: <server's own> }` with `llmsUrl` omitted, never guessed.
+        // `docsUrlIsDerived: false` regardless of whether rung 2 ALSO resolved
+        // (e.g. a `trawl.me`-hosted server declaring its own externalDocs) — a
+        // server-declared root is never "derived" by THIS CLI, and never a safe
+        // base for our own guide slugs (see DocsUrls.docsUrlIsDerived).
+        return derived.llmsUrl
+            ? { docsUrl: opts.externalDocsUrl, llmsUrl: derived.llmsUrl, docsUrlIsDerived: false }
+            : { docsUrl: opts.externalDocsUrl, docsUrlIsDerived: false };
+    }
+    return derived;
+}
+/** Join a docs root (e.g. `https://trawl.me/docs`) with a guide path
+ *  suffix (e.g. `build-your-scrap/account-sessions`) — plain string
+ *  concatenation, deliberately NOT `new URL(suffix, docsUrl)`: a
+ *  leading-slash suffix resolved against a URL with its own path component
+ *  (`/docs`) would resolve relative to the ORIGIN, silently dropping
+ *  `/docs` from the result (`new URL('/x', 'https://h/docs')` ==
+ *  `https://h/x`, not `https://h/docs/x`). */
+function joinDocsPath(docsUrl, suffix) {
+    return `${docsUrl.replace(/\/+$/, '')}/${suffix.replace(/^\/+/, '')}`;
+}
+/**
+ * The single source for the account-sessions guide slug — referenced by
+ * BOTH `COMMAND_DOC_PATHS` and `FAILURE_KIND_DOC_PATHS` below. Those two
+ * tables key on different fields (a CLI command's full path name vs a run's
+ * `failureKind`) and legitimately stay separate, but they name the SAME
+ * guide, so the path literal itself must exist exactly once: this is the
+ * "same fact computed in two places" defect class this module's own doc
+ * comment says it exists to prevent, and it has recurred repeatedly across
+ * this epic. Renaming the guide used to require editing two literals in
+ * lockstep — miss one and one surface (a run's `docs` field, or `spec
+ * --json`'s per-command deep link) silently 404s while the other still
+ * works (trawl_cli#185 review).
+ */
+const ACCOUNT_SESSIONS_GUIDE_PATH = 'build-your-scrap/account-sessions';
+/**
+ * Per-command deep links (issue #185 scope item 1) — a command's FULL path
+ * name (matches `CliSpecCommand.name` in spec.ts, e.g.
+ * `"scraps account session set"`) is matched against `prefix` either
+ * exactly or as a whole path SEGMENT prefix (`startsWith(prefix + ' ')`) —
+ * never a bare substring, so a hypothetical future `scraps accounting`
+ * command could never false-match the `scraps account` entry below.
+ */
+const COMMAND_DOC_PATHS = Object.freeze([
+    // Every account/session-management command — set, delete, clear-session,
+    // status, and the nested `session set` — is covered by one prefix entry
+    // rather than one row per leaf, so a new leaf added under `scraps account`
+    // later (e.g. a future `session capture`, trawl_cli#183) inherits the
+    // link for free instead of needing its own row.
+    { prefix: 'scraps account', path: ACCOUNT_SESSIONS_GUIDE_PATH },
+]);
+function docsPathForCommand(commandName) {
+    const match = COMMAND_DOC_PATHS.find((e) => commandName === e.prefix || commandName.startsWith(`${e.prefix} `));
+    return match ? match.path : null;
+}
+/**
+ * `resolveCommandDocsUrl` returns `undefined` (never a bare path or a
+ * relative link) whenever any of three things is missing — `docsUrl`
+ * unresolved (rung 3 already fired), `docsUrl` resolved but NOT derived
+ * (rung 1 — a server-declared root; see `DocsUrls.docsUrlIsDerived`'s doc
+ * comment for why appending our own guide slug onto a third party's root is
+ * exactly the confidently-wrong-404 defect this gate closes), or no guide is
+ * mapped for this command — so a spec consumer never has to special-case a
+ * partial value. Takes the whole resolved `DocsUrls` object (never a bare
+ * string) specifically so this provenance can never again be flattened away
+ * before it reaches here.
+ */
+export function resolveCommandDocsUrl(commandName, docs) {
+    if (!docs.docsUrl || !docs.docsUrlIsDerived)
+        return undefined;
+    const path = docsPathForCommand(commandName);
+    return path ? joinDocsPath(docs.docsUrl, path) : undefined;
+}
+/**
+ * failureKind -> guide path (issue #185 scope item 2). Keyed on trawl_node's
+ * run-level `failureKind` field (trawl_node#1975, surfaced by this CLI's
+ * own `doctor`/`data --errors`/`run-info` JSON payloads since cli#182) —
+ * this is a DIFFERENT axis from errors.ts's `ErrorEnvelope.kind` (a CLI
+ * transport/execution outcome like `"auth"` meaning "you're not logged
+ * into trawl", `"network"`, `"usage"`, …). Both happen to use the string
+ * `"auth"` for unrelated things: this table's `'auth'` means "the SCRAPED
+ * TARGET site showed a login wall", errors.ts's `'auth'` means "the TRAWL
+ * API rejected your OWN credentials". Never merge these two tables — they
+ * are keyed off different fields on different objects, and conflating them
+ * would either miss the run-level guide or wrongly attach it to an
+ * unrelated CLI auth failure.
+ */
+const FAILURE_KIND_DOC_PATHS = Object.freeze({
+    auth: ACCOUNT_SESSIONS_GUIDE_PATH,
+});
+function docsPathForFailureKind(kind) {
+    if (!kind)
+        return null;
+    return FAILURE_KIND_DOC_PATHS[kind] ?? null;
+}
+/** Same "undefined unless docsUrl is resolved AND derived (rung 2)" gate as
+ *  `resolveCommandDocsUrl` above, same reason — never append this CLI's own
+ *  guide slug onto a rung-1 server-declared root. Callers MUST gate the call
+ *  on their own staleness rule first (e.g. `doctor.ts`'s `isAuthWall`) — this
+ *  function only knows the string-to-path mapping, not whether a stamped
+ *  `failureKind` is still live on a run patched afterward. */
+export function resolveFailureKindDocsUrl(kind, docs) {
+    if (!docs.docsUrl || !docs.docsUrlIsDerived)
+        return undefined;
+    const path = docsPathForFailureKind(kind);
+    return path ? joinDocsPath(docs.docsUrl, path) : undefined;
+}
+/**
+ * `--help` footer text (issue #185 scope item 3) — a single dim line, for
+ * humans, e.g. "Docs: https://trawl.me/docs". Returns `undefined` (never an
+ * empty or guessed line) when no `docsUrl` resolved — mirrors
+ * lib/tips.ts's shape (a pure function separated from IO, so it's testable
+ * without mocking chalk/console) but NOT its TTY gate: tips.ts suppresses a
+ * promotional nudge from piped output, but a docs line inside `--help |
+ * less` is exactly the kind of thing worth keeping. Un-colored here — the
+ * caller (index.ts) applies `chalk.dim` so this stays trivially testable.
+ */
+export function docsFooterLine(docsUrl) {
+    return docsUrl ? `Docs: ${docsUrl}` : undefined;
+}

package/docs/agent-quickstart.md

@@ -166,7 +166,15 @@ 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`.
+run `trawl spec --json`. It also carries `docsUrl` (resolved from the server
+when declared, else derived from a known first-party API host, else omitted
+— never a guessed URL) and, where a guide exists, a per-command `docs` deep
+link — but the deep link and `llmsUrl` are narrower than `docsUrl`: they only
+ever come from the known-first-party-host derivation, never from a
+server-declared `docsUrl`, since this CLI's own guide slugs have no reason
+to exist on a third party's own docs root. A `failureKind:"auth"` run's
+payload (`doctor`/`data --errors`/`run-info`) carries the same `docs` field,
+under the same rule.
 
 ## Non-interactive contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {