@trawlme/cli 3.9.1 → 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
@@ -134,6 +134,8 @@ Skills auto-update when you upgrade the CLI — no need to re-install manually
 
 A pre-existing skill directory that trawl did not install itself (no `.version` marker) is never touched — `install`/`update` refuse to overwrite it and require `--force` to proceed. This applies to the CLI-upgrade auto-sync too (it silently skips marker-less dirs rather than refusing, since there is no interactive user to show a refusal to).
 
+**`trawl login` bootstraps any bundled skill you don't have yet** — the one command that does, since it's the one intentional human setup moment (interactive, a real TTY, not `--json`). It prints exactly what it installed and where, plus a fact you need to act on yourself: **Claude Code must be restarted to see them** — skills are loaded at session start, so anything installed mid-session stays invisible until then. Every other command only ever *suggests* running `trawl skills install` (throttled, never under `--json`/non-TTY/`TRAWL_SKILLS_SYNC=0`) — it never writes to `~/.claude/skills` as a side effect of something else you asked for. If you already have every bundled skill, or you're logging in non-interactively (CI, `--json`, `TRAWL_TOKEN=... trawl login`), nothing is written either way.
+
 You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
 
 ### Auth

package/dist/commands/doctor.d.ts

@@ -69,6 +69,31 @@ export interface Run {
  * response can still be the pre-#1950 flat shape for a while.
  */
 export declare function detectWallVendor(run: Pick<Run, 'status' | 'statusDetail' | 'block' | 'blockType'>): string | null;
+/**
+ * #184 — true for a run currently carrying a live (non-stale) login-wall
+ * verdict. Extracted out of `formatDoctor`'s own local `authWall` const so
+ * `commands/scraps.ts`'s `doctor`/`run-info` actions can reuse the EXACT
+ * same guard to decide whether to fire the skills-install safety-net nudge
+ * (lib/skillsNudge.ts `maybeSuggestSkillsForAuthWall`) — one rule, not two
+ * copies that could quietly drift apart.
+ *
+ * Same staleness guard as `detectWallVendor` above and for the same reason:
+ * `failureKind` is a terminal classification trawl_node stamps once, but
+ * `patchForRegression` can flip `status`/`statusDetail` to success/
+ * regression LATER without ever clearing it — so a run that ultimately
+ * succeeded or degraded must never still read as an active auth wall.
+ *
+ * Typed structurally loose (not `Pick<Run, ...>`) on purpose: `Run.status`/
+ * `statusDetail` are required fields, but `scraps.ts`'s own `HistoryRun`
+ * (the run-info command's shape) declares the same three fields OPTIONAL —
+ * a `Pick<Run, ...>` parameter type would reject that caller at compile
+ * time even though every field it actually reads is present at runtime.
+ */
+export declare function isAuthWall(run: {
+    failureKind?: string | null;
+    status?: boolean | null;
+    statusDetail?: string | null;
+}): boolean;
 /**
  * Autofix activity metadata — from the persisted ai_fix_end activity.
  * aiUsage (cost) is stripped server-side; all diagnostics are kept.

package/dist/commands/doctor.js

@@ -69,6 +69,29 @@ export function detectWallVendor(run) {
     }
     return null;
 }
+/**
+ * #184 — true for a run currently carrying a live (non-stale) login-wall
+ * verdict. Extracted out of `formatDoctor`'s own local `authWall` const so
+ * `commands/scraps.ts`'s `doctor`/`run-info` actions can reuse the EXACT
+ * same guard to decide whether to fire the skills-install safety-net nudge
+ * (lib/skillsNudge.ts `maybeSuggestSkillsForAuthWall`) — one rule, not two
+ * copies that could quietly drift apart.
+ *
+ * Same staleness guard as `detectWallVendor` above and for the same reason:
+ * `failureKind` is a terminal classification trawl_node stamps once, but
+ * `patchForRegression` can flip `status`/`statusDetail` to success/
+ * regression LATER without ever clearing it — so a run that ultimately
+ * succeeded or degraded must never still read as an active auth wall.
+ *
+ * Typed structurally loose (not `Pick<Run, ...>`) on purpose: `Run.status`/
+ * `statusDetail` are required fields, but `scraps.ts`'s own `HistoryRun`
+ * (the run-info command's shape) declares the same three fields OPTIONAL —
+ * a `Pick<Run, ...>` parameter type would reject that caller at compile
+ * time even though every field it actually reads is present at runtime.
+ */
+export function isAuthWall(run) {
+    return run.failureKind === 'auth' && run.status !== true && run.statusDetail !== 'regression';
+}
 const TIER_LABELS = {
     tier0: 'Tier 0',
     tier1: 'Tier 1',
@@ -194,7 +217,7 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
     // `detectWallVendor`'s guard already exists to prevent for `block.kind`.
     // One rule, not two coincidences: both checks guard the same two fields
     // against the same after-the-fact patch.
-    const authWall = run.failureKind === 'auth' && run.status !== true && run.statusDetail !== 'regression';
+    const authWall = isAuthWall(run);
     const authHintWillRender = authWall && Boolean(scrapId);
     const conflictingSignals = Boolean(wallVendor) && authWall;
     if (conflictingSignals) {

package/dist/commands/login.js

@@ -4,8 +4,9 @@ import config, { getApiUrl, getLiveAuthEnvVar } from '../lib/config.js';
 import { api } from '../lib/api.js';
 import { requireFreshJwt, requireUrl } from '../lib/validate.js';
 import { promptPassword } from '../lib/prompt.js';
-import { requireInteractive } from '../lib/confirm.js';
+import { requireInteractive, isInteractive } from '../lib/confirm.js';
 import { json } from '../lib/format.js';
+import { bootstrapSkillsOnLogin, RESTART_CLAUDE_CODE_NOTE } from '../lib/skills.js';
 async function promptEmail() {
     const { createInterface } = await import('readline');
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -40,6 +41,62 @@ function reportLoginSuccess(opts, email) {
     if (overrideVar) {
         console.error(chalk.yellow(`⚠ ${overrideVar} is set in your environment — it overrides the token just stored here for every subsequent command until you unset it.`));
     }
+    // #184 — `login` is the ONE intentional human setup moment: bootstrap any
+    // bundled Claude skill the user doesn't have yet. Gated exactly like
+    // every other filesystem-mutating side effect in this CLI
+    // (json/TTY/opt-out — see lib/skills.ts's isSkillsActionAllowed), so a
+    // CI/agent `TRAWL_TOKEN=x trawl login --json` never writes into
+    // ~/.claude/skills on a machine with no Claude Code session to discover
+    // them. `isInteractive` is the exact TTY definition login already uses
+    // for its own email/password prompt gate (lib/confirm.ts) — stdin AND
+    // stdout, not just stdout. `bootstrapped` is `null` ONLY when gated out
+    // (json/non-TTY/opted-out) or when every bundled skill is already owned
+    // by trawl — the genuine "nothing to do" case, where the lines below
+    // naturally never print. It is non-null whenever anything was attempted,
+    // whether or not any of it actually landed — see the block below.
+    //
+    // stderr, same convention as the `overrideVar` warning right above (and
+    // for the same reason): this is orthogonal to the `--json` envelope's
+    // fixed shape below, so it must never risk landing on stdout — a defense
+    // that holds even if `bootstrapSkillsOnLogin`'s own json/TTY gate above it
+    // were ever wrong, not just a style match.
+    //
+    // #184 review (BLOCK + MAJOR) — `bootstrapped` is non-null whenever there
+    // was anything to attempt, whether or not any of it actually landed, so
+    // both halves below must be checked independently: `installed` prints the
+    // success line, `skipped` prints one honest line per skill that was
+    // requested but did NOT land (a permission error, or a pre-existing
+    // marker-less dir the ownership guard refused to overwrite) and WHY —
+    // `reason` is already a relayable, fact-only string (SkillOwnershipRefusalError's
+    // `.relayableReason`, or a raw fs error message) with no imperative, so it
+    // is safe to print verbatim on this channel. A total failure (installed
+    // empty, skipped non-empty) must read as "attempted and failed" — never
+    // fall through to silence, which is indistinguishable from "never
+    // attempted" (the exact false-success shape this issue exists to
+    // prevent). The restart note only applies to what actually landed, so it
+    // stays scoped to that branch.
+    //
+    // #184 defect 2 — `error` is the THIRD case: distinct from both "nothing
+    // to do" (bootstrapped is `null`, nothing prints) and "some/all skills
+    // failed" (`skipped`, above) — it means bootstrapSkillsOnLogin could not
+    // even determine which skills to install (the bundled skills package
+    // looks missing/corrupted). Stated as a fact, same convention as every
+    // other line here.
+    const bootstrapped = bootstrapSkillsOnLogin({ json: opts.json, isTTY: isInteractive(opts) });
+    if (bootstrapped) {
+        if (bootstrapped.error) {
+            console.error(chalk.yellow(`⚠ Claude skills bootstrap: ${bootstrapped.error}`));
+        }
+        if (bootstrapped.installed.length > 0) {
+            console.error(chalk.green(`✓ Installed Claude skill${bootstrapped.installed.length === 1 ? '' : 's'}: `) +
+                `${bootstrapped.installed.join(', ')}` +
+                chalk.dim(` at ${bootstrapped.dest}`));
+            console.error(chalk.yellow(RESTART_CLAUDE_CODE_NOTE));
+        }
+        for (const { name, reason } of bootstrapped.skipped) {
+            console.error(chalk.yellow(`⚠ Claude skill "${name}" install attempted but failed: ${reason}`));
+        }
+    }
     if (opts.json) {
         json({ ok: true, apiUrl: getApiUrl(), config: config.path, ...(email && { email }) });
         return;

package/dist/commands/scraps.js

@@ -8,9 +8,38 @@ import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId, requireUrl } from '../lib/validate.js';
 import { classifyError, reportError, retryFieldsFor, UsageError, RefusalError } from '../lib/errors.js';
 import { confirmDestructive, isInteractive } from '../lib/confirm.js';
-import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
+import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix, isAuthWall } from './doctor.js';
 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
@@ -1064,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;
@@ -1269,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);
@@ -1276,6 +1314,13 @@ export function attachRunInfoCommand(parent, attachOpts = {}) {
         }
         // The blob is an object; the table needs one line. --json keeps it whole.
         table([{ ...info, emptyContext: summarizeEmptyContext(info.emptyContext) }], ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'errorMessage', 'selector', 'emptyContext', 'createdAt']);
+        // #184 safety-net — the run just shown carries a live login-wall
+        // verdict; if Claude's skills aren't installed either, point at the
+        // command that installs them too (never under --json, see the early
+        // return above).
+        if (isAuthWall(h)) {
+            maybeSuggestSkillsForAuthWall();
+        }
     });
 }
 attachRunInfoCommand(scraps, { hidden: true });
@@ -1654,12 +1699,22 @@ 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));
     }
+    // #184 safety-net — formatDoctor already prints the login-wall hint
+    // (#182) above when this is a live auth wall; if Claude's skills aren't
+    // installed either, point at the command that installs them too (never
+    // under --json, see the early return above).
+    if (isAuthWall(result.run)) {
+        maybeSuggestSkillsForAuthWall();
+    }
 });
 // autofix — show full auto-fix attempt detail (diff, dry-run, knowledge)
 scraps

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

@@ -15,10 +15,13 @@ import { whoami } from './commands/whoami.js';
 import { ping } from './commands/ping.js';
 import { spec } from './commands/spec.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
+import { maybeSuggestSkillsInstall } from './lib/skillsNudge.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
 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'));
 /**
@@ -141,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).
  *
@@ -227,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
@@ -537,6 +577,27 @@ export async function runCli(argv = process.argv) {
             catch {
                 // swallow — background refresh must never affect this invocation.
             }
+            // #184 — "elsewhere: suggest, never install" half of the skills
+            // bootstrap story (lib/skills.ts's bootstrapSkillsOnLogin is the
+            // "install on login" half). Only on a clean exit — mirrors the
+            // referral tip's own success-only precedent (lib/tips.ts, called only
+            // after a run genuinely succeeds) and sidesteps a whole class of
+            // parse-error edge cases where `currentCommand` never resolved (so
+            // its own `--json` flag can't be read reliably here either). Running
+            // AFTER the command completed also means a `login` that just
+            // bootstrapped is already reflected in this nudge's own "any skill
+            // installed?" read — no separate command-name exclusion needed, and
+            // no double-message risk with the line `login` may have just printed.
+            if (process.exitCode === undefined || process.exitCode === 0) {
+                try {
+                    maybeSuggestSkillsInstall({
+                        json: Boolean(currentCommand?.opts()?.json),
+                    });
+                }
+                catch {
+                    // swallow — see skillsNudge.ts, this is already self-guarded too.
+                }
+            }
         }
     }
 }

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>;