@trawlme/cli 3.9.0 → 3.10.0

package/README.md

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

@@ -25,19 +25,31 @@ export interface Run {
         selectors?: Record<string, number>;
     } | null;
     blocked?: boolean;
+    block?: {
+        kind?: string | null;
+    } | null;
+    /** @deprecated trawl_node#1950 renamed this to `block.kind`. Kept as a read
+     * fallback (see detectWallVendor) for the window where this CLI is
+     * published ahead of the trawl_node prod tag — a prod backend served from
+     * the pre-#1950 tag still returns this flat field, not `block.kind`. Drop
+     * once prod is confirmed on a tag containing #1950. */
     blockType?: string | null;
     proxyTier?: string | null;
-    regressionDetected?: boolean;
     baselineLength?: number | null;
     fixVersionId?: string | null;
     createdAt?: string;
     time?: number | null;
     triggeredBy?: string | null;
+    /** trawl_node#1975 — freeform failure classification (`'auth'` = login-wall
+     * empty run, cookies are the fix). Not a TS union — trawl_node's own set
+     * is additive/open, so this CLI must stay read-safe against a future
+     * value it doesn't know about yet, same posture as `block.kind` above. */
+    failureKind?: string | null;
 }
 /**
- * Resolve a known anti-bot vendor (or auth) name from a worker `blockType`
- * string. Returns null when the run succeeded, when there is no `blockType`
- * signal at all, or when `blockType` names something other than a known
+ * Resolve a known anti-bot vendor name from a worker `block.kind`
+ * string. Returns null when the run succeeded, when there is no `block.kind`
+ * signal at all, or when `block.kind` names something other than a known
  * vendor (e.g. `proxy-domain-gate`, `rate_limited_per_host`) — those stay on
  * the genuine-error path since we can't honestly attribute them to a specific
  * "no reliable bypass" wall.
@@ -45,12 +57,43 @@ export interface Run {
  * `blocked` is deliberately NOT consulted here (#177): it is a mid-run,
  * attempt-level signal the worker only stamps on one envelope shape, so it
  * reads `false` on the great majority of genuinely walled runs (the early-block
- * throw path sets `blockType` but never `blocked` — 63 of 64 walled runs
+ * throw path sets `block.kind` but never `blocked` — 63 of 64 walled runs
  * measured on prod). `status === true` wins instead: a run that ultimately
- * returned data was not walled, even if an earlier tier's `blockType` stamp
+ * returned data was not walled, even if an earlier tier's `block.kind` stamp
  * survived on the row.
+ *
+ * trawl_node#1950 renamed the flat `blockType` field to nested `block.kind`.
+ * Read `block?.kind` first, falling back to the deprecated flat `blockType` —
+ * this CLI can be published (and talk to prod) before the trawl_node prod tag
+ * containing #1950 is cut (see the `Run.blockType` doc comment), so a prod
+ * 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 detectWallVendor(run: Pick<Run, 'status' | 'statusDetail' | 'blockType'>): string | null;
+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

@@ -2,23 +2,25 @@ import { api } from '../lib/api.js';
 import chalk from 'chalk';
 import { formatDate } from '../lib/format.js';
 /**
- * Known anti-bot vendors (+ auth) that the worker's `blockType` field may name.
- * Ordered by first-match; `blockType` is a freeform worker string, not an enum
- * (see the `Run.blockType` doc comment), so this is a best-effort substring
- * match against the real field — never an invented/mocked value.
+ * Known anti-bot vendors that the worker's `block.kind` field may name
+ * (ex-flat `blockType`, trawl_node#1950). Ordered by first-match;
+ * `block.kind` is a freeform worker string, not an enum (see the `Run.block`
+ * doc comment), so this is a best-effort substring match against the real
+ * field — never an invented/mocked value.
  *
  * `datadome`/`perimeterx`/`akamai`/`cloudflare` are literal substrings the
- * current worker emits (detect.js). `kasada` and `auth` are forward-compatible:
- * the issue (#62 / wall-registry WS-7) names them as genuine walls, but the
- * current worker vocabulary does not yet emit them — these branches light up
- * automatically if/when a future worker classifier does, without a CLI change.
+ * current worker emits (detect.js). `kasada` is forward-compatible: the issue
+ * (#62 / wall-registry WS-7) names it as a genuine wall, but the current
+ * worker vocabulary does not yet emit it — this branch lights up
+ * automatically if/when a future worker classifier does, without a CLI
+ * change.
  *
- * The `auth` pattern is delimiter-anchored (`^`/`$`/`-_:`) rather than a bare
- * substring so it matches worker-style tokens (`auth`, `auth-wall`, `auth_wall`,
- * `login:auth`) without false-matching `oauth`/`authorization`/`author`. It uses
- * `[-_:]` (not `\b`) because `_` is a JS `\w` char, so `\bauth\b` would miss the
- * underscore-delimited `auth_wall` form the worker's `rate_limited_per_host`-style
- * naming favors.
+ * trawl_cli#182 — an `auth` entry used to live here, rendering a login wall
+ * as "walled: auth — no reliable bypass". Removed: unlike a real anti-bot
+ * vendor, a login wall's own reliable bypass is the user's session cookies,
+ * so that verdict was wrong, not just early. `failureKind==='auth'`
+ * (trawl_node#1975) is the honest signal for a login wall — see the
+ * dedicated branch in `formatDoctor` below.
  */
 const WALL_VENDOR_PATTERNS = [
     [/datadome/i, 'DataDome'],
@@ -26,12 +28,11 @@ const WALL_VENDOR_PATTERNS = [
     [/perimeterx/i, 'PerimeterX'],
     [/akamai/i, 'Akamai'],
     [/cloudflare/i, 'Cloudflare'],
-    [/(?:^|[-_:])auth(?:$|[-_:])/i, 'auth'],
 ];
 /**
- * Resolve a known anti-bot vendor (or auth) name from a worker `blockType`
- * string. Returns null when the run succeeded, when there is no `blockType`
- * signal at all, or when `blockType` names something other than a known
+ * Resolve a known anti-bot vendor name from a worker `block.kind`
+ * string. Returns null when the run succeeded, when there is no `block.kind`
+ * signal at all, or when `block.kind` names something other than a known
  * vendor (e.g. `proxy-domain-gate`, `rate_limited_per_host`) — those stay on
  * the genuine-error path since we can't honestly attribute them to a specific
  * "no reliable bypass" wall.
@@ -39,28 +40,58 @@ const WALL_VENDOR_PATTERNS = [
  * `blocked` is deliberately NOT consulted here (#177): it is a mid-run,
  * attempt-level signal the worker only stamps on one envelope shape, so it
  * reads `false` on the great majority of genuinely walled runs (the early-block
- * throw path sets `blockType` but never `blocked` — 63 of 64 walled runs
+ * throw path sets `block.kind` but never `blocked` — 63 of 64 walled runs
  * measured on prod). `status === true` wins instead: a run that ultimately
- * returned data was not walled, even if an earlier tier's `blockType` stamp
+ * returned data was not walled, even if an earlier tier's `block.kind` stamp
  * survived on the row.
+ *
+ * trawl_node#1950 renamed the flat `blockType` field to nested `block.kind`.
+ * Read `block?.kind` first, falling back to the deprecated flat `blockType` —
+ * this CLI can be published (and talk to prod) before the trawl_node prod tag
+ * containing #1950 is cut (see the `Run.blockType` doc comment), so a prod
+ * response can still be the pre-#1950 flat shape for a while.
  */
 export function detectWallVendor(run) {
     // A run that returned data was not walled. `status === true` is not the whole
     // predicate: trawl_node flips a degraded-but-non-empty run to
     // `status:false, statusDetail:'regression'` (scraps.service.js, #1112) via a
-    // patch that never clears `blockType` — so keying on `status` alone would
+    // patch that never clears `block.kind` — so keying on `status` alone would
     // print "no reliable bypass" next to "Regression: length N vs baseline M",
     // which is the same contradiction this guard exists to remove.
     if (run.status === true || run.statusDetail === 'regression')
         return null;
-    if (!run.blockType)
+    const kind = run.block?.kind ?? run.blockType ?? null;
+    if (!kind)
         return null; // no signal at all
     for (const [pattern, label] of WALL_VENDOR_PATTERNS) {
-        if (pattern.test(run.blockType))
+        if (pattern.test(kind))
             return label;
     }
     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',
@@ -70,8 +101,8 @@ const TIER_LABELS = {
 };
 const RUN_ALLOWLIST = [
     '_id', 'status', 'statusDetail', 'length', 'errorMessage', 'errorSnapshot',
-    'emptyContext', 'blocked', 'blockType', 'proxyTier', 'regressionDetected', 'baselineLength',
-    'fixVersionId', 'createdAt', 'time', 'triggeredBy',
+    'emptyContext', 'blocked', 'block', 'blockType', 'proxyTier', 'baselineLength',
+    'fixVersionId', 'createdAt', 'time', 'triggeredBy', 'failureKind',
 ];
 const FIX_ALLOWLIST = [
     'outcome', 'classification', 'reason', 'fixDiff', 'dryRunResults',
@@ -124,14 +155,81 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
     lines.push(`${chalk.bold(scrapTitle)}  ${badge}${run.statusDetail ? ` (${run.statusDetail})` : ''}`);
     lines.push(chalk.dim(`  Run ID:  ${run._id}`));
     // Error message — an honest accept-wall string for known-walled scraps
-    // (DataDome/Kasada/PerimeterX/Akamai/auth terminal verdict from the worker),
+    // (DataDome/Kasada/PerimeterX/Akamai terminal verdict from the worker),
     // otherwise the real error (genuine transient failure).
+    //
+    // trawl_cli#182 — the wall-vendor verdict (this CLI's own
+    // WALL_VENDOR_PATTERNS matched against block.kind/blockType) and the
+    // login-wall hint (node's failureKind==='auth', trawl_node#1975) are two
+    // INDEPENDENT server-derived signals with no shared contract: node's block
+    // classifier (modules/historys/helpers/failureKind.js BLOCK_TYPE_PATTERN)
+    // and this CLI's vendor table live in different repos and can legitimately
+    // disagree. Concretely, `kasada` matches this CLI's table but is absent
+    // from node's block pattern, and the deprecated flat `blockType` fallback
+    // is a field node's classifier no longer reads at all — so a run can come
+    // back `failureKind:'auth'` (the server says login wall) while also
+    // matching a vendor here (this CLI says Kasada/DataDome/etc), both true
+    // signals about the same run, neither one wrong.
+    //
+    // trawl_cli#169 precedent: never assert client-side what only the server
+    // knows. Silently picking a winner between two disagreeing signals is
+    // exactly that — printing "no reliable bypass" alone asserts the run is
+    // NOT an auth wall (may stop someone from trying a fixable cookie
+    // problem); printing the cookie hint alone asserts the run is NOT a
+    // vendor wall (may send someone chasing cookies against a wall no cookie
+    // fixes). This CLI cannot tell which is true without either importing
+    // node's BLOCK_TYPE_PATTERN (a second source of truth for the same list —
+    // how this defect got here) or re-detecting the login URL itself (the
+    // client-side re-derivation this fix deliberately rejects). So when both
+    // fire, render ONE hedged line naming both readings instead of picking:
+    // never emit the bare "no reliable bypass" verdict in that case — it is
+    // exactly the false precision this branch exists to avoid.
+    //
+    // `conflictingSignals` is deliberately NOT gated on `scrapId` the way the
+    // plain hint below is: the false "no reliable bypass" verdict is wrong
+    // regardless of whether we also have an id to build an actionable command
+    // for, so a scrapId-less conflicting run must still avoid it. Only the
+    // action line degrades (to a generic Settings pointer) when there's no id.
+    //
+    // Single-signal cases are untouched: a plain vendor match (no
+    // failureKind:'auth') still gets "no reliable bypass"; a plain
+    // failureKind:'auth' (no vendor match) still gets the plain hint block
+    // below. `errMsg` stays suppressed whenever any hint form (conflicting or
+    // plain) is about to render — node's own `errorMessage` for an auth run
+    // (historys.service.js ~line 774) IS the hint copy verbatim, literal
+    // `<id>` placeholder and all, so printing it here would just be a second
+    // rendering of the same information. If neither hint form renders (no
+    // vendor conflict and no scrapId for the plain hint), fall back to node's
+    // raw message rather than dropping the error entirely.
     const wallVendor = detectWallVendor(run);
     const errMsg = run.errorMessage ?? run.errorSnapshot?.errorMessage;
-    if (wallVendor) {
+    // trawl_cli#182 — same `status`/`statusDetail` guard as `detectWallVendor`
+    // above, and for the same reason (see its doc comment): `failureKind` is a
+    // terminal classification trawl_node stamps once
+    // (modules/historys/services/historys.service.js ~line 837), but
+    // `patchForRegression` (modules/scraps/services/scraps.service.js ~line
+    // 1972) can flip `status`/`statusDetail` to success/regression LATER,
+    // without ever clearing `failureKind`. Left unguarded, a run that
+    // ultimately succeeded or degraded could still carry a stale
+    // `failureKind:'auth'` and render the login-wall hint (or the
+    // conflicting-signals hedge) right next to a green "success" badge or a
+    // "Regression: length N vs baseline M" line — the exact contradiction
+    // `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 = isAuthWall(run);
+    const authHintWillRender = authWall && Boolean(scrapId);
+    const conflictingSignals = Boolean(wallVendor) && authWall;
+    if (conflictingSignals) {
+        lines.push(chalk.dim('  Error:   ') + chalk.yellow(`conflicting signals — the server reported ${wallVendor} on this run, but also classified it as a login wall; can't tell which is true here`));
+        lines.push(chalk.dim(scrapId
+            ? `  → cookies might help, but this may still be a genuine ${wallVendor} block: trawl scraps account session set ${scrapId} -c cookies.json`
+            : `  → cookies might help, but this may still be a genuine ${wallVendor} block (see app Settings → Account)`));
+    }
+    else if (wallVendor) {
         lines.push(chalk.dim('  Error:   ') + chalk.red(`walled: ${wallVendor} — no reliable bypass`));
     }
-    else if (errMsg) {
+    else if (errMsg && !authHintWillRender) {
         lines.push(chalk.dim('  Error:   ') + chalk.red(errMsg));
     }
     // Failed selector
@@ -149,8 +247,32 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
         const page = run.emptyContext.page;
         lines.push(chalk.dim('  Empty context:   ') + `url=${page.url ?? '?'}  anchors=${page.totalAnchors ?? '?'}`);
     }
-    // Regression detail
-    if (run.regressionDetected) {
+    // Login-wall hint (trawl_node#1975 `failureKind==='auth'`) — trust node's
+    // verdict, never re-detect the login URL client-side. Hypothesis-framed
+    // ("likely fix"), not a promise: measured cases (Reddit/X/Instagram) had
+    // valid cookies and stayed walled. Gated on `scrapId` alone (via
+    // `authHintWillRender` above, shared with the generic error line so the
+    // two can't drift apart), NOT the `scrapId ?? run._id` fallback used
+    // elsewhere here — `run._id` is a history id, and the session-set command
+    // on one silently targets the wrong document.
+    //
+    // trawl_cli#182 — excludes `conflictingSignals`: when a wall-vendor match
+    // also fired, the combined hedged line above already covers the cookie
+    // suggestion. Rendering this plain, unhedged block too would stack a
+    // second verdict under the first (and directly contradict it, since this
+    // block asserts the run IS a login wall with no caveat) — exactly the
+    // two-verdicts-for-one-run defect this fix removes. Exactly one verdict
+    // block renders per run.
+    if (authHintWillRender && !conflictingSignals) {
+        lines.push('');
+        lines.push(chalk.yellow('  Login wall (hypothesis): ') + 'this looks like a login redirect — your own session cookies are the likely fix.');
+        lines.push(chalk.dim(`  → trawl scraps account session set ${scrapId} -c cookies.json   (or app Settings → Account)`));
+    }
+    // Regression detail. trawl_node#1950 dropped the redundant `regressionDetected`
+    // boolean — it was `true` on every row iff `statusDetail === 'regression'`,
+    // so read that directly (works against a pre- or post-#1950 backend alike,
+    // no CLI/backend sequencing gap: `statusDetail` isn't part of this rename).
+    if (run.statusDetail === 'regression') {
         lines.push(chalk.dim('  Regression:      ') + `length ${run.length ?? '?'} vs baseline ${run.baselineLength ?? '?'}`);
     }
     // Autofix summary (when fix exists)

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,10 @@ 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';
 /**
  * Print a usage/validation error consistently: human text to stderr, or a
  * machine envelope on stdout under --json (never both — reportError is the
@@ -1234,7 +1235,9 @@ export function attachHistoryCommand(parent, attachOpts = {}) {
             time: h.time ?? null,
             tier: h.proxyTier ?? null,
             failureKind: h.failureKind ?? null,
-            blockType: h.blockType ?? null,
+            // trawl_node#1950 renamed blockType to block.kind; fall back to the
+            // deprecated flat field for a prod backend not yet on that tag.
+            blockType: h.block?.kind ?? h.blockType ?? null,
             createdAt: h.createdAt ?? null,
         }));
         if (opts.json) {
@@ -1260,7 +1263,9 @@ export function attachRunInfoCommand(parent, attachOpts = {}) {
             time: h.time ?? null,
             tier: h.proxyTier ?? null,
             failureKind: h.failureKind ?? null,
-            blockType: h.blockType ?? null,
+            // trawl_node#1950 renamed blockType to block.kind; fall back to the
+            // deprecated flat field for a prod backend not yet on that tag.
+            blockType: h.block?.kind ?? h.blockType ?? null,
             errorMessage: h.errorSnapshot?.errorMessage ?? null,
             selector: h.errorSnapshot?.selector ?? null,
             emptyContext: h.emptyContext ?? null,
@@ -1272,6 +1277,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 });
@@ -1656,6 +1668,13 @@ scraps
     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/index.js

@@ -15,6 +15,7 @@ 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';
@@ -537,6 +538,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/config.d.ts

@@ -13,6 +13,7 @@ interface TrawlConfig {
      * Same optional/absent-means-enabled shape as `updateNotifier` above. */
     tips?: boolean;
     referralTipShownAt: number;
+    skillsNudgeShownAt: number;
 }
 declare const config: Conf<TrawlConfig>;
 /**

package/dist/lib/config.js

@@ -17,6 +17,7 @@ const config = new Conf({
         telemetry: true,
         telemetryUserId: '',
         referralTipShownAt: 0,
+        skillsNudgeShownAt: 0,
     },
 });
 /**

package/dist/lib/skills.d.ts

@@ -1,5 +1,34 @@
 export declare function getBundledSkillsVersion(): string;
 export declare function listBundledSkills(): string[];
+/**
+ * #184 defect 1 — the ownership-refusal thrown below serves two different
+ * audiences on two different channels, and one string can't correctly serve
+ * both:
+ *
+ *  - A human who just typed `trawl skills install`/`update` reaches this via
+ *    an uncaught throw (index.ts's generic error path prints `.message`
+ *    verbatim) — that reader can decide whether to add `--force`, so the
+ *    guidance belongs on this channel. `.message` (below) keeps it.
+ *  - `bootstrapSkillsOnLogin` also catches this exact throw and relays its
+ *    text into `skipped[].reason`, which `login.ts` prints to stderr — a
+ *    channel this feature's own doc comments say must never carry a command
+ *    phrased as an instruction, because this CLI is driven by AI agents and
+ *    this platform can feed a CLI's own stderr back into an agent's own
+ *    context. `Pass --force to overwrite it anyway` is exactly that kind of
+ *    instruction: an agent "obeying" it calls `installSkill`'s own
+ *    `rmSync(recursive)` on a directory the user owns and trawl did not
+ *    create — the destroy-the-user's-files incident this class of bug
+ *    produces.
+ *
+ * `.relayableReason` carries the identical fact — this path exists, trawl
+ * did not create it, so it was left untouched — with the imperative sentence
+ * removed, for every channel that is not a direct, synchronous reply to a
+ * human's own typed command.
+ */
+export declare class SkillOwnershipRefusalError extends Error {
+    readonly relayableReason: string;
+    constructor(dest: string);
+}
 /**
  * Ownership guard (#73, extended #86 finding 7): this does `rmSync(recursive)`
  * on the target dir before reinstalling, so it must never do that to a dir
@@ -50,3 +79,130 @@ export declare function removeOrphanedSkills(scope: 'user' | 'local'): string[];
  * `TRAWL_TELEMETRY=0`), for users who manage their skills by hand.
  */
 export declare function autoUpdateInstalledSkills(): void;
+/**
+ * #184 — one line, reused everywhere the CLI installs a skill mid-invocation
+ * (login's bootstrap below, lib/skillsNudge.ts's two nudges): skills are
+ * discovered at Claude Code SESSION START, so a skill written to disk right
+ * now is invisible to whatever session is already running. Stated as a
+ * fact, never an imperative ("restart Claude Code") — this text can be
+ * relayed into an AI agent's own context (this CLI's whole incident was an
+ * agent driving it), and a command phrased there must never read as an
+ * instruction the agent is being told to obey.
+ */
+export declare const RESTART_CLAUDE_CODE_NOTE = "Claude Code must be restarted to see them \u2014 skills are loaded at session start, not mid-session.";
+/**
+ * #184 — pure gate shared by every skills-related write/print that must
+ * never fire under `--json` (a machine consumer needs pure stdout and there
+ * is no human reading a suggestion anyway), on a non-TTY invocation (a CI
+ * runner or an agent driving this CLI as a subprocess has no Claude Code
+ * session to discover a newly-installed skill in the first place), or when
+ * `TRAWL_SKILLS_SYNC=0` (the existing auto-sync opt-out, extended here: a
+ * user who manages skills by hand does not want the CLI touching that dir
+ * for ANY reason — install or nudge alike). Every signal is a parameter,
+ * exactly like lib/tips.ts's `isReferralTipDue`, so this is testable
+ * without mocking env/TTY. `isTTY`'s exact definition (stdout-only vs
+ * stdin+stdout) is the CALLER's call — see bootstrapSkillsOnLogin below vs
+ * lib/skillsNudge.ts for the two different answers this codebase already
+ * gives elsewhere (confirm.ts's `isInteractive` vs tips.ts's own check).
+ */
+export declare function isSkillsActionAllowed(opts: {
+    json?: boolean;
+    isTTY: boolean;
+    optedOut: boolean;
+}): boolean;
+/**
+ * #184 — the "install on login, and only there" half of the never-installed
+ * bootstrap (see the module doc comment on `autoUpdateInstalledSkills`
+ * above for the "elsewhere: suggest, never install" half, which lives in
+ * lib/skillsNudge.ts instead). `autoUpdateInstalledSkills` deliberately
+ * never installs (`if (!isSkillInstalled) continue`) — it only keeps an
+ * EXISTING install in sync. A user who has never run any `trawl skills`
+ * command and never logged in before this shipped has nothing installed at
+ * all, and nothing in the CLI's startup path ever puts anything there: the
+ * CLI is competent, the agent reading its skills is not — the incident this
+ * issue exists to prevent. `login` is the one intentional human setup
+ * moment (the only place a human types credentials), so it is the ONLY
+ * place this function is ever called from (see commands/login.ts) — never
+ * from the generic startup path.
+ *
+ * Gated by `isSkillsActionAllowed` exactly like every other skills-related
+ * side effect: a non-interactive `trawl login` (CI's `TRAWL_TOKEN=x trawl
+ * login --json`, or any non-TTY invocation) writes nothing — that machine
+ * has no Claude Code session to discover a skill in, and `--json`'s stdout
+ * contract has no room for a plain-text confirmation line anyway. Also
+ * skipped entirely under `TRAWL_SKILLS_SYNC=0`.
+ *
+ * Installs every bundled skill NOT YET OWNED by trawl at `scope` (default
+ * 'user' — the global location a fresh `npx @trawlme/cli login` writes to;
+ * 'local' is opt-in via the same --local convention `trawl skills install`
+ * already uses everywhere else, kept for parity/tests). "Owned" means a
+ * readable `.version` marker (#184 review MAJOR — NOT mere path existence:
+ * see below for why that distinction matters here). One skill's install
+ * throwing must never blank out the others (#91's posture, applied here):
+ * each is wrapped individually, and the function reports exactly what
+ * landed. Returns `null` (nothing written, nothing to report) ONLY when
+ * gated out, or when every bundled skill is already owned (the re-sync
+ * loop above already keeps an existing install's version current) — the
+ * genuine "nothing to do" case. Never throws — a broken bootstrap must
+ * never turn a successful login into a failed one.
+ *
+ * #184 review (BLOCK + MAJOR) — two cases used to collapse into the exact
+ * same `null`/silence as genuine "nothing to do":
+ *
+ *  1. (BLOCK) Every install attempt failing outright (an unwritable
+ *     `~/.claude/skills`, e.g.) used to return `null` — indistinguishable
+ *     from "already installed" or "never attempted at all" on a first-run
+ *     machine, the precise false-success shape #184 exists to prevent.
+ *  2. (MAJOR) A bundled skill name colliding with a PRE-EXISTING,
+ *     marker-less directory the CLI doesn't own. The action set here used
+ *     to be computed from `isSkillInstalled` (mere `existsSync`), which
+ *     can't tell "we already installed this" from "something else already
+ *     lives at this path" — a foreign dir was silently read as "already
+ *     installed, nothing to do", so `installSkill`'s ownership-refusal
+ *     guard was never even reached and the collision went unreported
+ *     anywhere. The action set below is computed from *ownership*
+ *     (`getInstalledVersion(...) !== null`) instead, so a foreign
+ *     collision is genuinely attempted — hits the same guard `installSkill`
+ *     already enforces elsewhere, throws, and is captured below — rather
+ *     than silently skipped as if it were a prior trawl install.
+ *
+ * Whenever there was anything to attempt, the result is now ALWAYS a
+ * non-null object reporting both what landed (`installed`) and what didn't
+ * (`skipped`, each with a RELAYABLE reason — see `SkillOwnershipRefusalError`
+ * above: the ownership-refusal case reports `.relayableReason` [fact only,
+ * no `--force` imperative], every other throw [skill-not-found, raw fs
+ * errors like EACCES] reports `.message` as before, since those were never
+ * imperative to begin with), so `login.ts` can print an honest, distinct
+ * line for a skip instead of falling through to the generic "not installed"
+ * nudge as if login had done nothing, or silently omitting a name from the
+ * success line as if it had never been requested.
+ *
+ * #184 defect 2 — `error` (present whenever the function returns non-null)
+ * distinguishes a THIRD case from both "nothing to do" (`null`) and "one or
+ * more skills failed" (`skipped`): "could not even determine what to
+ * install" — `listBundledSkills()` returning an empty list (its own
+ * contract silently swallows a missing/renamed `skills/` dir into `[]`; see
+ * its doc comment) or `getSkillsPackageRoot()` throwing outright (the
+ * `@trawlme/skills` package itself unresolvable — a broken node_modules
+ * entry). Both used to fall through to `notOwned.length === 0` or the outer
+ * catch below, landing on the exact same `null` as a fully-up-to-date
+ * install — a genuinely corrupted bundle produced ZERO signal, not even a
+ * failed-attempt line, because nothing was ever attempted. `error` is
+ * `null` on every ordinary path (including genuine "all already owned",
+ * which still short-circuits to the `null` return below) and non-null only
+ * for this diagnostic-failure case, where `installed`/`skipped` are both
+ * empty because no skill name was ever known to attempt.
+ */
+export declare function bootstrapSkillsOnLogin(opts?: {
+    json?: boolean;
+    isTTY?: boolean;
+    scope?: 'user' | 'local';
+}): {
+    installed: string[];
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+    dest: string;
+    error: string | null;
+} | null;

package/dist/lib/skills.js

@@ -24,6 +24,40 @@ function getSkillsBase(scope) {
     const base = scope === 'local' ? join(process.cwd(), '.claude') : join(homedir(), '.claude');
     return join(base, 'skills');
 }
+/**
+ * #184 defect 1 — the ownership-refusal thrown below serves two different
+ * audiences on two different channels, and one string can't correctly serve
+ * both:
+ *
+ *  - A human who just typed `trawl skills install`/`update` reaches this via
+ *    an uncaught throw (index.ts's generic error path prints `.message`
+ *    verbatim) — that reader can decide whether to add `--force`, so the
+ *    guidance belongs on this channel. `.message` (below) keeps it.
+ *  - `bootstrapSkillsOnLogin` also catches this exact throw and relays its
+ *    text into `skipped[].reason`, which `login.ts` prints to stderr — a
+ *    channel this feature's own doc comments say must never carry a command
+ *    phrased as an instruction, because this CLI is driven by AI agents and
+ *    this platform can feed a CLI's own stderr back into an agent's own
+ *    context. `Pass --force to overwrite it anyway` is exactly that kind of
+ *    instruction: an agent "obeying" it calls `installSkill`'s own
+ *    `rmSync(recursive)` on a directory the user owns and trawl did not
+ *    create — the destroy-the-user's-files incident this class of bug
+ *    produces.
+ *
+ * `.relayableReason` carries the identical fact — this path exists, trawl
+ * did not create it, so it was left untouched — with the imperative sentence
+ * removed, for every channel that is not a direct, synchronous reply to a
+ * human's own typed command.
+ */
+export class SkillOwnershipRefusalError extends Error {
+    relayableReason;
+    constructor(dest) {
+        super(`Refusing to overwrite "${dest}" — it was not installed by trawl (no .version marker). ` +
+            `Pass --force to overwrite it anyway.`);
+        this.name = 'SkillOwnershipRefusalError';
+        this.relayableReason = `"${dest}" already exists and was not installed by trawl (no .version marker) — left untouched.`;
+    }
+}
 /**
  * Ownership guard (#73, extended #86 finding 7): this does `rmSync(recursive)`
  * on the target dir before reinstalling, so it must never do that to a dir
@@ -58,8 +92,7 @@ export function installSkill(name, scope, opts = {}) {
         }
         const owned = installedVersion !== null;
         if (!owned && !opts.force) {
-            throw new Error(`Refusing to overwrite "${dest}" — it was not installed by trawl (no .version marker). ` +
-                `Pass --force to overwrite it anyway.`);
+            throw new SkillOwnershipRefusalError(dest);
         }
         rmSync(dest, { recursive: true, force: true });
     }
@@ -196,3 +229,195 @@ export function autoUpdateInstalledSkills() {
         // Silent: skill auto-update should never block the CLI
     }
 }
+/**
+ * #184 — one line, reused everywhere the CLI installs a skill mid-invocation
+ * (login's bootstrap below, lib/skillsNudge.ts's two nudges): skills are
+ * discovered at Claude Code SESSION START, so a skill written to disk right
+ * now is invisible to whatever session is already running. Stated as a
+ * fact, never an imperative ("restart Claude Code") — this text can be
+ * relayed into an AI agent's own context (this CLI's whole incident was an
+ * agent driving it), and a command phrased there must never read as an
+ * instruction the agent is being told to obey.
+ */
+export const RESTART_CLAUDE_CODE_NOTE = 'Claude Code must be restarted to see them — skills are loaded at session start, not mid-session.';
+/**
+ * #184 — pure gate shared by every skills-related write/print that must
+ * never fire under `--json` (a machine consumer needs pure stdout and there
+ * is no human reading a suggestion anyway), on a non-TTY invocation (a CI
+ * runner or an agent driving this CLI as a subprocess has no Claude Code
+ * session to discover a newly-installed skill in the first place), or when
+ * `TRAWL_SKILLS_SYNC=0` (the existing auto-sync opt-out, extended here: a
+ * user who manages skills by hand does not want the CLI touching that dir
+ * for ANY reason — install or nudge alike). Every signal is a parameter,
+ * exactly like lib/tips.ts's `isReferralTipDue`, so this is testable
+ * without mocking env/TTY. `isTTY`'s exact definition (stdout-only vs
+ * stdin+stdout) is the CALLER's call — see bootstrapSkillsOnLogin below vs
+ * lib/skillsNudge.ts for the two different answers this codebase already
+ * gives elsewhere (confirm.ts's `isInteractive` vs tips.ts's own check).
+ */
+export function isSkillsActionAllowed(opts) {
+    if (opts.json)
+        return false;
+    if (!opts.isTTY)
+        return false;
+    if (opts.optedOut)
+        return false;
+    return true;
+}
+/**
+ * #184 — the "install on login, and only there" half of the never-installed
+ * bootstrap (see the module doc comment on `autoUpdateInstalledSkills`
+ * above for the "elsewhere: suggest, never install" half, which lives in
+ * lib/skillsNudge.ts instead). `autoUpdateInstalledSkills` deliberately
+ * never installs (`if (!isSkillInstalled) continue`) — it only keeps an
+ * EXISTING install in sync. A user who has never run any `trawl skills`
+ * command and never logged in before this shipped has nothing installed at
+ * all, and nothing in the CLI's startup path ever puts anything there: the
+ * CLI is competent, the agent reading its skills is not — the incident this
+ * issue exists to prevent. `login` is the one intentional human setup
+ * moment (the only place a human types credentials), so it is the ONLY
+ * place this function is ever called from (see commands/login.ts) — never
+ * from the generic startup path.
+ *
+ * Gated by `isSkillsActionAllowed` exactly like every other skills-related
+ * side effect: a non-interactive `trawl login` (CI's `TRAWL_TOKEN=x trawl
+ * login --json`, or any non-TTY invocation) writes nothing — that machine
+ * has no Claude Code session to discover a skill in, and `--json`'s stdout
+ * contract has no room for a plain-text confirmation line anyway. Also
+ * skipped entirely under `TRAWL_SKILLS_SYNC=0`.
+ *
+ * Installs every bundled skill NOT YET OWNED by trawl at `scope` (default
+ * 'user' — the global location a fresh `npx @trawlme/cli login` writes to;
+ * 'local' is opt-in via the same --local convention `trawl skills install`
+ * already uses everywhere else, kept for parity/tests). "Owned" means a
+ * readable `.version` marker (#184 review MAJOR — NOT mere path existence:
+ * see below for why that distinction matters here). One skill's install
+ * throwing must never blank out the others (#91's posture, applied here):
+ * each is wrapped individually, and the function reports exactly what
+ * landed. Returns `null` (nothing written, nothing to report) ONLY when
+ * gated out, or when every bundled skill is already owned (the re-sync
+ * loop above already keeps an existing install's version current) — the
+ * genuine "nothing to do" case. Never throws — a broken bootstrap must
+ * never turn a successful login into a failed one.
+ *
+ * #184 review (BLOCK + MAJOR) — two cases used to collapse into the exact
+ * same `null`/silence as genuine "nothing to do":
+ *
+ *  1. (BLOCK) Every install attempt failing outright (an unwritable
+ *     `~/.claude/skills`, e.g.) used to return `null` — indistinguishable
+ *     from "already installed" or "never attempted at all" on a first-run
+ *     machine, the precise false-success shape #184 exists to prevent.
+ *  2. (MAJOR) A bundled skill name colliding with a PRE-EXISTING,
+ *     marker-less directory the CLI doesn't own. The action set here used
+ *     to be computed from `isSkillInstalled` (mere `existsSync`), which
+ *     can't tell "we already installed this" from "something else already
+ *     lives at this path" — a foreign dir was silently read as "already
+ *     installed, nothing to do", so `installSkill`'s ownership-refusal
+ *     guard was never even reached and the collision went unreported
+ *     anywhere. The action set below is computed from *ownership*
+ *     (`getInstalledVersion(...) !== null`) instead, so a foreign
+ *     collision is genuinely attempted — hits the same guard `installSkill`
+ *     already enforces elsewhere, throws, and is captured below — rather
+ *     than silently skipped as if it were a prior trawl install.
+ *
+ * Whenever there was anything to attempt, the result is now ALWAYS a
+ * non-null object reporting both what landed (`installed`) and what didn't
+ * (`skipped`, each with a RELAYABLE reason — see `SkillOwnershipRefusalError`
+ * above: the ownership-refusal case reports `.relayableReason` [fact only,
+ * no `--force` imperative], every other throw [skill-not-found, raw fs
+ * errors like EACCES] reports `.message` as before, since those were never
+ * imperative to begin with), so `login.ts` can print an honest, distinct
+ * line for a skip instead of falling through to the generic "not installed"
+ * nudge as if login had done nothing, or silently omitting a name from the
+ * success line as if it had never been requested.
+ *
+ * #184 defect 2 — `error` (present whenever the function returns non-null)
+ * distinguishes a THIRD case from both "nothing to do" (`null`) and "one or
+ * more skills failed" (`skipped`): "could not even determine what to
+ * install" — `listBundledSkills()` returning an empty list (its own
+ * contract silently swallows a missing/renamed `skills/` dir into `[]`; see
+ * its doc comment) or `getSkillsPackageRoot()` throwing outright (the
+ * `@trawlme/skills` package itself unresolvable — a broken node_modules
+ * entry). Both used to fall through to `notOwned.length === 0` or the outer
+ * catch below, landing on the exact same `null` as a fully-up-to-date
+ * install — a genuinely corrupted bundle produced ZERO signal, not even a
+ * failed-attempt line, because nothing was ever attempted. `error` is
+ * `null` on every ordinary path (including genuine "all already owned",
+ * which still short-circuits to the `null` return below) and non-null only
+ * for this diagnostic-failure case, where `installed`/`skipped` are both
+ * empty because no skill name was ever known to attempt.
+ */
+export function bootstrapSkillsOnLogin(opts = {}) {
+    try {
+        const optedOut = process.env['TRAWL_SKILLS_SYNC'] === '0';
+        if (!isSkillsActionAllowed({ json: opts.json, isTTY: opts.isTTY ?? false, optedOut }))
+            return null;
+        const scope = opts.scope ?? 'user';
+        const dest = getSkillsBase(scope);
+        let bundled;
+        try {
+            bundled = listBundledSkills();
+        }
+        catch (err) {
+            // getSkillsPackageRoot() threw (require.resolve failed — the
+            // `@trawlme/skills` package itself isn't resolvable). Report as a
+            // diagnostic failure, not the outer catch's generic `null`.
+            return {
+                installed: [],
+                skipped: [],
+                dest,
+                error: `could not read the bundled Claude skills package — ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (bundled.length === 0) {
+            // The package resolved but reports zero skills — in practice this
+            // package always ships at least one, so an empty list here is
+            // corruption (e.g. its `skills/` dir renamed/deleted underneath it),
+            // not a legitimate "nothing to do".
+            return {
+                installed: [],
+                skipped: [],
+                dest,
+                error: 'the bundled Claude skills package reports no skills to install — it may be missing or corrupted',
+            };
+        }
+        const notOwned = bundled.filter((name) => {
+            try {
+                return getInstalledVersion(name, scope) === null;
+            }
+            catch {
+                // An unreadable `.version` (e.g. EISDIR) is no more proof of
+                // ownership than a missing one — treat it as actionable too, same
+                // as installSkill's own owned-check does (#91's posture).
+                return true;
+            }
+        });
+        if (notOwned.length === 0)
+            return null;
+        const installed = [];
+        const skipped = [];
+        for (const name of notOwned) {
+            try {
+                installSkill(name, scope);
+                installed.push(name);
+            }
+            catch (err) {
+                // One bad skill (e.g. a marker-less foreign dir refusing overwrite,
+                // or an EACCES on an unwritable skills dir) must not blank the
+                // others — skip it, keep going, but never drop WHY silently: the
+                // caller needs this to tell "attempted and failed" apart from
+                // "nothing to do".
+                const reason = err instanceof SkillOwnershipRefusalError
+                    ? err.relayableReason
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+                skipped.push({ name, reason });
+            }
+        }
+        return { installed, skipped, dest, error: null };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/skillsNudge.d.ts

@@ -0,0 +1,33 @@
+export declare const SKILLS_NUDGE_TEXT = "Claude skills not installed \u2014 `trawl skills install` installs them (Claude Code must be restarted to see them \u2014 skills are loaded at session start, not mid-session.)";
+export declare const AUTH_WALL_SKILLS_NUDGE_TEXT = "This looks like a login wall and Claude skills are not installed \u2014 `trawl skills install` installs the guidance for it too (Claude Code must be restarted to see them \u2014 skills are loaded at session start, not mid-session.)";
+/**
+ * Pure gate — true when the throttled, generic "elsewhere" suggestion
+ * should print. Every external signal is a parameter, exactly like
+ * isReferralTipDue, so this is testable without mocking fs/env/Date.
+ */
+export declare function isSkillsNudgeDue(opts: {
+    json?: boolean;
+    isTTY: boolean;
+    optedOut: boolean;
+    skillsPresent: boolean;
+    lastShownAt: number;
+    now: number;
+}): boolean;
+/**
+ * Best-effort generic nudge (#184 point 2) — called once per CLI invocation
+ * from index.ts's runCli, on every command. Never throws.
+ */
+export declare function maybeSuggestSkillsInstall(opts?: {
+    json?: boolean;
+}): void;
+/**
+ * Safety-net nudge (#184 point 5) — called from `doctor`/`run-info` right
+ * when the run they just showed carries a live `failureKind:'auth'` verdict
+ * (see commands/doctor.ts's `isAuthWall`). Deliberately unthrottled by the
+ * 7-day timestamp — see this module's doc comment for why — but still
+ * capped to one nudge per process via the same `nudgedThisProcess` flag the
+ * generic nudge sets. Never throws.
+ */
+export declare function maybeSuggestSkillsForAuthWall(opts?: {
+    json?: boolean;
+}): void;

package/dist/lib/skillsNudge.js

@@ -0,0 +1,137 @@
+/**
+ * #184 — the "elsewhere: suggest, never install" half of the skills
+ * bootstrap story (lib/skills.ts's `bootstrapSkillsOnLogin` is the "install
+ * on login" half). Writing into `~/.claude/skills` as a side effect of an
+ * unrelated command is a filesystem mutation nobody asked for — this module
+ * only ever PRINTS a line naming the command that installs them. Never
+ * installs anything itself.
+ *
+ * Two nudges, one shared "at most once per process" guard:
+ *  - `maybeSuggestSkillsInstall` — the generic, throttled nudge (once per
+ *    NUDGE_THROTTLE_MS across ALL commands, mirrors lib/tips.ts's referral
+ *    tip throttle exactly).
+ *  - `maybeSuggestSkillsForAuthWall` — the safety-net nudge (#184 point 5):
+ *    fires from `doctor`/`run-info` when the run they just showed carries a
+ *    live `failureKind:'auth'` verdict and skills are absent. Deliberately
+ *    UNTHROTTLED by the 7-day timestamp: sharing that throttle would mean a
+ *    routine command on day 0 (stamping the generic nudge's timestamp)
+ *    silently suppresses THIS nudge on day 1 when the user actually hits
+ *    the auth wall the whole issue exists for — the exact failure this
+ *    safety net is supposed to catch. It mirrors trawl_cli#182's own
+ *    login-wall hint in `formatDoctor`, which also prints unthrottled every
+ *    time the condition is true.
+ *  - `nudgedThisProcess` still caps the two at "one nudge per invocation"
+ *    combined: `doctor` on an auth-walled, skills-absent run can print the
+ *    auth-wall nudge inside its own action, and index.ts's generic
+ *    post-command nudge (which does not know `doctor` already said
+ *    something) would otherwise print a second, redundant line right after
+ *    it. Whichever fires first wins; reset per test via a fresh module
+ *    import (see skillsNudge.test.ts's `freshImport` helper, mirroring
+ *    tips.test.ts).
+ *
+ * Gate shape mirrors lib/tips.ts's isReferralTipDue/maybeShowReferralTip
+ * throughout (json/isTTY/opt-out/throttle, pure gate separated from the
+ * side-effecting caller, cheap checks before any filesystem read) — same
+ * reasoning applies verbatim.
+ */
+import chalk from 'chalk';
+import config from './config.js';
+import { listBundledSkills, isSkillInstalled, isSkillsActionAllowed, RESTART_CLAUDE_CODE_NOTE } from './skills.js';
+/** Max once per 7 days — same window as lib/tips.ts's referral tip. */
+const NUDGE_THROTTLE_MS = 7 * 24 * 60 * 60 * 1000;
+// #184 constraint A — a FACT about CLI state plus the command name, never an
+// instruction to the reader ("install the skills"/"you should run…"). This
+// output is not only read by a human at a terminal: this platform can relay
+// a CLI's own stdout/stderr into an AI agent's context (the incident this
+// issue exists to prevent was exactly an agent driving this CLI), and
+// third-party content returned into agent context must never read as an
+// instruction the agent is being told to obey. State the fact, name the
+// command, stop there.
+export const SKILLS_NUDGE_TEXT = `Claude skills not installed — \`trawl skills install\` installs them (${RESTART_CLAUDE_CODE_NOTE})`;
+export const AUTH_WALL_SKILLS_NUDGE_TEXT = `This looks like a login wall and Claude skills are not installed — \`trawl skills install\` installs the guidance for it too (${RESTART_CLAUDE_CODE_NOTE})`;
+/** One nudge per process, whichever of the two below fires first. */
+let nudgedThisProcess = false;
+/**
+ * Pure gate — true when the throttled, generic "elsewhere" suggestion
+ * should print. Every external signal is a parameter, exactly like
+ * isReferralTipDue, so this is testable without mocking fs/env/Date.
+ */
+export function isSkillsNudgeDue(opts) {
+    if (!isSkillsActionAllowed({ json: opts.json, isTTY: opts.isTTY, optedOut: opts.optedOut }))
+        return false;
+    if (opts.skillsPresent)
+        return false;
+    return opts.now - opts.lastShownAt >= NUDGE_THROTTLE_MS;
+}
+/**
+ * Read-only — checks both scopes, mirrors `trawl skills list`'s own
+ * "installed anywhere" question. Failing toward `false` (not installed) on
+ * an unreadable skills dir is the safe default here: the worst case is one
+ * extra nudge line, never a missed one — the opposite failure (silently
+ * assuming "present" and staying quiet) is the exact gap this issue exists
+ * to close.
+ */
+function anyBundledSkillInstalled() {
+    try {
+        return listBundledSkills().some((name) => isSkillInstalled(name, 'user') || isSkillInstalled(name, 'local'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Shared body for both exported nudges below: the cheap json/TTY/opt-out
+ * gate, the "one nudge per process" cap, the skills-presence check, and the
+ * actual print — everything the two nudges have in common. `useThrottle`
+ * is the one real difference between them (see the module doc comment for
+ * why the safety-net nudge deliberately opts out of it), so it stays an
+ * explicit parameter here rather than two near-identical function bodies.
+ * Never throws.
+ */
+function tryPrintNudge(opts, text, useThrottle) {
+    try {
+        if (nudgedThisProcess)
+            return;
+        const json = Boolean(opts.json);
+        const isTTY = Boolean(process.stdout.isTTY);
+        const optedOut = process.env['TRAWL_SKILLS_SYNC'] === '0';
+        // Cheap checks first (mirrors tips.ts #153's "never pay when not due")
+        // — only touch the filesystem once json/TTY/opt-out already say "maybe".
+        if (!isSkillsActionAllowed({ json, isTTY, optedOut }))
+            return;
+        if (useThrottle) {
+            const lastShownAt = config.get('skillsNudgeShownAt') || 0;
+            const now = Date.now();
+            const due = isSkillsNudgeDue({ json, isTTY, optedOut, skillsPresent: anyBundledSkillInstalled(), lastShownAt, now });
+            if (!due)
+                return;
+            config.set('skillsNudgeShownAt', now);
+        }
+        else if (anyBundledSkillInstalled()) {
+            return;
+        }
+        nudgedThisProcess = true;
+        console.error(chalk.dim(text));
+    }
+    catch {
+        // silent — a broken nudge must never break a command
+    }
+}
+/**
+ * Best-effort generic nudge (#184 point 2) — called once per CLI invocation
+ * from index.ts's runCli, on every command. Never throws.
+ */
+export function maybeSuggestSkillsInstall(opts = {}) {
+    tryPrintNudge(opts, SKILLS_NUDGE_TEXT, true);
+}
+/**
+ * Safety-net nudge (#184 point 5) — called from `doctor`/`run-info` right
+ * when the run they just showed carries a live `failureKind:'auth'` verdict
+ * (see commands/doctor.ts's `isAuthWall`). Deliberately unthrottled by the
+ * 7-day timestamp — see this module's doc comment for why — but still
+ * capped to one nudge per process via the same `nudgedThisProcess` flag the
+ * generic nudge sets. Never throws.
+ */
+export function maybeSuggestSkillsForAuthWall(opts = {}) {
+    tryPrintNudge(opts, AUTH_WALL_SKILLS_NUDGE_TEXT, false);
+}

package/package.json

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