@trawlme/cli 1.18.1 → 1.18.2

package/README.md

@@ -10,6 +10,8 @@ Command-line client for [Trawl](https://trawl.me) — manage your scraps from th
 
 ## Install
 
+Requires Node.js >= 20.
+
 ```bash
 npm install -g @trawlme/cli
 ```
@@ -41,8 +43,8 @@ trawl token                                  Print the stored session JWT (for M
 ```
 trawl scraps list [--json] [--status <success|failure|never>] [--limit <n>] [--page <n>]
 trawl scraps get <id> [--json]
-trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>]
-trawl scraps update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--force-tier <tier0|tier1|tier2|tier3|tier4>]
+trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--json]
+trawl scraps update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--force-tier <tier0|tier1|tier2|tier3|tier4>] [--json]
 trawl scraps run <id> [--watch]
 trawl scraps trigger <id> [--watch] [--wait]
 trawl scraps watch <id>
@@ -53,15 +55,16 @@ trawl scraps doctor <id> [--json] [--autofix]
 trawl scraps autofix <id> [--json]
 trawl scraps snapshot <id> [--error] [-o <file>]
 trawl scraps banner <id> -f <file>
-trawl scraps rm <id> [--force]
+trawl scraps delete <id> [--force]         Alias: rm
 ```
 
-- `--tier` forces a proxy tier; `--force-tier` raises the proxy-tier ceiling past the auto-cap (history-gated: may be refused or cost more).
+- `--tier` forces a proxy tier; `--force-tier` raises the proxy-tier ceiling past the auto-cap (history-gated: may be refused or cost more). `create --json`/`update --json` print the full scrap object (including the `_tierOverride` outcome) on stdout; a refused tier override exits 1 with a standard `--json` error envelope.
 - `scraps doctor` diagnoses the last run (error, failed selector, block status, page state, autofix outcome); `--autofix` includes the full autofix diff/dry-run/knowledge.
 - `scraps autofix` shows the last auto-fix attempt on its own (decision, diff, dry-run, knowledge).
 - `scraps snapshot --error` fetches the error-path snapshot instead of the normal one; `-o <file>` writes to a file instead of stdout.
 - `scraps history` lists past runs (newest first); `scraps run-info <hid>` shows details of a single run from that history.
-- `scraps data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail.
+- `scraps data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail. `[]` on stdout means a genuine zero-item successful run — a scrap that has never run, whose last run failed, or whose payload aged out of retention returns a `--json` error envelope (exit 4/1/4 respectively) instead.
+- `scraps get` (and anything reading through it, like `scraps data`'s default path) embeds only the newest 100 history rows on the returned scrap object — `scraps run-info` and `scraps doctor` fetch a single run directly and are unaffected by that cap.
 
 ### Scrap accounts
 
@@ -80,13 +83,15 @@ trawl scraps account session set <id> -c <file>
 The CLI bundles a Claude Code skill that teaches Claude how to use `trawl`. Once installed, Claude can manage scraps for you via prompts.
 
 ```
-trawl skills list                            List bundled skills and install status
-trawl skills install [<skill>] [--local]     Install all (or one). Default: ~/.claude/skills/
-trawl skills uninstall [<skill>] [--local]   Remove
-trawl skills update [<skill>] [--local]      Reinstall (force sync with CLI version)
+trawl skills list                                     List bundled skills and install status
+trawl skills install [<skill>] [--local] [--force]    Install all (or one). Default: ~/.claude/skills/
+trawl skills uninstall [<skill>] [--local]            Remove
+trawl skills update [<skill>] [--local] [--force]     Reinstall (force sync with CLI version)
 ```
 
-Skills auto-update silently when you upgrade the CLI — no need to re-install manually.
+Skills auto-update when you upgrade the CLI — no need to re-install manually — but it is not silent: it prints an honest `trawl: re-synced skill "<name>" (<scope>) <old> → <new>` line to stderr whenever it rewrites a skill dir, so a rewrite is never invisible. Opt out with `TRAWL_SKILLS_SYNC=0`.
+
+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).
 
 You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
 
@@ -108,7 +113,7 @@ trawl telemetry status   Show current state, telemetry ID, and opt-out instructi
 - Node.js version
 - Platform (e.g. `darwin`, `linux`, `win32`)
 - Command duration (`duration_ms`)
-- Exit code (`0` = success, `1` = error)
+- Exit code — the full 0–5 range below, not just success/failure (see [Exit codes](#exit-codes))
 - Error name if the command failed (e.g. `ApiError`) — never the error message or stack
 - An opaque, randomly-generated telemetry ID (`cli_<uuid>`) stored locally in your config file
 
@@ -131,13 +136,32 @@ TRAWL_TELEMETRY=0 trawl scraps list
 
 **Why:** usage data helps us prioritise CLI features and catch silent errors before users report them.
 
+## Exit codes
+
+Every command exits with one of these codes — scripts and agents driving the CLI unattended can branch on the exact failure kind instead of a uniform pass/fail:
+
+| Code | Meaning                                                                 |
+|------|--------------------------------------------------------------------------|
+| `0`  | Success                                                                 |
+| `1`  | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug) |
+| `2`  | Usage error (bad flag/value, invalid ID, missing required argument, unknown option/command) |
+| `3`  | Auth error (not logged in, or the session token is expired/invalid — run `trawl login`) |
+| `4`  | Not found (no such resource, or — for `scraps data` — no persisted payload to read) |
+| `5`  | Network error (the API host is unreachable, DNS/connection/TLS failure, or the request timed out) |
+
+Under `--json`, a failing command emits a single error envelope on stdout — `{"error":{"message","status?","kind"}}` — instead of prose; the human-readable line always goes to stderr, never stdout.
+
 ## Environment variables
 
-| Variable           | Description                                                       |
-|--------------------|-------------------------------------------------------------------|
-| `TRAWL_TOKEN`      | JWT token — bypasses login prompt, useful for CI/CD               |
-| `TRAWL_API_URL`    | Override the API base URL for the session (takes precedence over `trawl login --url`) |
-| `TRAWL_TELEMETRY`  | Set to `0` to disable telemetry for the current session           |
+| Variable             | Description                                                       |
+|-----------------------|--------------------------------------------------------------------|
+| `TRAWL_TOKEN`         | JWT token — bypasses login prompt, useful for CI/CD               |
+| `TRAWL_API_URL`       | Override the API base URL for the session (takes precedence over `trawl login --url`) |
+| `TRAWL_TELEMETRY`     | Set to `0` to disable telemetry for the current session           |
+| `DO_NOT_TRACK`        | Set to `1` to disable telemetry (cross-vendor convention, https://consoledonottrack.com) — same effect as `TRAWL_TELEMETRY=0` |
+| `TRAWL_CONFIG_DIR`    | Override where the config file (token, API URL, telemetry state) is stored — useful for hermetic CI runs or concurrent `trawl login`s that must not share one on-disk file |
+| `TRAWL_TIMEOUT`       | Override the per-request fetch timeout in milliseconds (default `30000`) |
+| `TRAWL_SKILLS_SYNC`   | Set to `0` to disable the startup skills auto-sync entirely       |
 
 Session override (no `trawl login` mutation, ideal for CI/QA against another env):
 

package/dist/commands/scraps.js

@@ -5,21 +5,18 @@ import { api } from '../lib/api.js';
 import { table, json } from '../lib/format.js';
 import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
-import { classifyError } from '../lib/errors.js';
+import { classifyError, reportError, UsageError } from '../lib/errors.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
 /**
- * Print a usage/validation error consistently: human text to stderr always;
- * when the invoking command supports --json, ALSO emit a machine envelope on
- * stdout instead of leaving stdout silent/prose. Sets exit code 2 (usage) —
- * distinct from a business-logic refusal (which stays 1) or an unmapped
- * ApiError/NetworkError (handled centrally in index.ts). (#71)
+ * Print a usage/validation error consistently: human text to stderr, or a
+ * machine envelope on stdout under --json (never both — reportError is the
+ * single formatting path shared with index.ts's central catch, #86 finding
+ * 9). Sets exit code 2 (usage) — distinct from a business-logic refusal
+ * (which stays 1) or an unmapped ApiError/NetworkError (handled centrally in
+ * index.ts). (#71)
  */
 function usageError(message, opts = {}) {
-    console.error(chalk.red(`✗ ${message}`));
-    if (opts.json) {
-        console.log(JSON.stringify({ error: { message, kind: 'usage' } }));
-    }
-    process.exitCode = 2;
+    process.exitCode = reportError(new UsageError(message), { json: opts.json });
 }
 function lastStatus(scrap) {
     const last = scrap.history?.[0];
@@ -73,7 +70,7 @@ scraps
     .option('--status <status>', 'Filter by last run status (success|failure|never)')
     .option('--limit <n>', 'Show only the first N results', (v) => parseInt(v, 10))
     .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)', (v) => parseInt(v, 10))
-    .action(async (opts) => {
+    .action(async (opts, cmd) => {
     // Guard: --limit and --page are mutually exclusive
     if (opts.limit !== undefined && opts.page !== undefined) {
         usageError('--limit and --page are mutually exclusive. Use one or the other.', { json: opts.json });
@@ -105,12 +102,22 @@ scraps
         // Spinner already failed by oraPromise — report with the scrap-specific
         // prefix kept, but route through the shared classifier so exit code +
         // --json envelope stay consistent with every other command. (#71)
+        //
+        // This bespoke catch (kept for the "Failed to fetch scraps:" prefix,
+        // which the shared reportError() can't add) used to silently swallow
+        // --debug: unlike the central index.ts catch, it never printed the raw
+        // stack trace. optsWithGlobals() reads --debug off the ROOT command
+        // (this leaf has no --debug of its own) so it can honor the flag
+        // locally instead. (#86 finding 9)
+        const isDebug = Boolean(cmd.optsWithGlobals().debug || process.env['DEBUG']);
         const { exitCode, envelope } = classifyError(err);
         const message = `Failed to fetch scraps: ${envelope.message}`;
+        if (isDebug)
+            console.error(err);
         if (opts.json) {
             console.log(JSON.stringify({ error: { ...envelope, message } }));
         }
-        else {
+        else if (!isDebug) {
             console.error(chalk.red(`✗ ${message}`));
         }
         process.exitCode = exitCode;
@@ -155,6 +162,58 @@ scraps
     console.log(chalk.dim(`  Updated:  `) + new Date(data.updatedAt).toLocaleString());
 });
 const VALID_TIERS = ['tier0', 'tier1', 'tier2', 'tier3', 'tier4'];
+/**
+ * #86 findings 4/5 — shared honest-tier renderer for `create --tier` and
+ * `update --tier/--force-tier`. Reads the typed `_tierOverride` echoed back
+ * by the server (#1559) so both commands show the SAME truth: a refusal, an
+ * allowed ceiling raise (+ spend warning), or a silently clamped proxyTier.
+ * Human-mode output only — a --json caller gets the same truth for free from
+ * the full scrap object (which already includes `_tierOverride`).
+ */
+function renderTierOverrideHuman(data) {
+    const ov = data._tierOverride;
+    if (!ov)
+        return;
+    if (ov.refused) {
+        console.error(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
+            + chalk.dim(` (requested ${ov.requestedMaxTier ?? '—'}; kept the registry cap)`));
+    }
+    else if (ov.effectiveMaxTier) {
+        console.log(chalk.green(`  ✓ tier ceiling: ${ov.effectiveMaxTier}`)
+            + chalk.dim(` (${ov.reason ?? ''}${ov.provider ? `, ${ov.provider}` : ''})`));
+        if (ov.warning)
+            console.log(chalk.yellow(`    ⚠ ${ov.warning}`));
+    }
+    if (ov.proxyTier) {
+        if (ov.proxyTier.clamped) {
+            console.log(chalk.yellow(`  ⚠ proxyTier requested ${ov.proxyTier.requested} → applied ${ov.proxyTier.effective}`)
+                + chalk.dim(` (${ov.proxyTier.reason ?? 'capped'})`));
+        }
+        else {
+            console.log(chalk.dim(`  proxyTier: `) + ov.proxyTier.effective);
+        }
+    }
+}
+/**
+ * #86 finding 4b — old-server fallback. When a tier was requested but the
+ * response carries no `_tierOverride` at all, the server is too old to
+ * confirm what actually got applied. Echoing the REQUESTED value as if it
+ * were the outcome is exactly the silent-clamp lie #1559 fixed — warn
+ * instead, on stderr (safe under --json too; stdout purity is untouched).
+ */
+function warnIfUnconfirmedTier(data, tierWasRequested, id) {
+    if (data._tierOverride || !tierWasRequested)
+        return;
+    console.error(chalk.yellow(`  ⚠ Server did not confirm the tier change (older server) — verify with: trawl scraps get ${id}`));
+}
+/** #86 finding 5 — the standard error envelope for a refused tier override,
+ * routed through the same reportError() central formatting path used
+ * everywhere else (exit 1: a business-logic refusal, not a usage error). */
+function reportTierRefusal(data, wantsJson) {
+    const ov = data._tierOverride;
+    const message = `Tier ceiling override refused: ${ov?.reason ?? 'unknown'} (requested ${ov?.requestedMaxTier ?? '—'}; kept the registry cap)`;
+    return reportError(new Error(message), { json: wantsJson });
+}
 // create
 scraps
     .command('create')
@@ -164,9 +223,10 @@ scraps
     .option('-r, --request <request>', 'Request/query')
     .option('-d, --description <text>', 'Scrap description')
     .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
+    .option('--json', 'Output as JSON')
     .action(async (opts) => {
     if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
-        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`);
+        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
     const data = await oraPromise(() => api.post('/api/scraps', {
@@ -176,7 +236,24 @@ scraps
         ...(opts.description !== undefined && { description: opts.description }),
         ...(opts.tier !== undefined && { proxyTier: opts.tier }),
     }), { text: 'Creating scrap…', successText: (d) => `Scrap created: ${chalk.bold(d._id)}` });
+    // #86 finding 4a — read _tierOverride back from the POST response and
+    // render it exactly like `update` does; never echo the requested tier as
+    // if it were applied when an older server doesn't confirm it.
+    const tierWasRequested = opts.tier !== undefined;
+    warnIfUnconfirmedTier(data, tierWasRequested, data._id);
+    const refused = Boolean(data._tierOverride?.refused);
+    if (opts.json) {
+        if (refused) {
+            process.exitCode = reportTierRefusal(data, true);
+            return;
+        }
+        json(data);
+        return;
+    }
     console.log(chalk.dim(`  Title: ${data.title}`));
+    renderTierOverrideHuman(data);
+    if (refused)
+        process.exitCode = 1;
 });
 // update
 scraps
@@ -196,14 +273,15 @@ scraps
     .option('--params-file <path>', 'Runtime params from a JSON file')
     .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
     .option('--force-tier <tier>', `Raise the proxy-tier ceiling PAST the auto-cap (${VALID_TIERS.join('|')}) — history-gated: may be refused or cost more`)
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
-        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`);
+        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
     if (opts.forceTier !== undefined && !VALID_TIERS.includes(opts.forceTier)) {
-        usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`);
+        usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
     const body = {};
@@ -241,11 +319,11 @@ scraps
             parsed = JSON.parse(raw);
         }
         catch (e) {
-            usageError(`Invalid JSON for --params: ${e.message}`);
+            usageError(`Invalid JSON for --params: ${e.message}`, { json: opts.json });
             return;
         }
         if (!Array.isArray(parsed)) {
-            usageError('--params must be a JSON array of objects');
+            usageError('--params must be a JSON array of objects', { json: opts.json });
             return;
         }
         body.params = parsed;
@@ -259,6 +337,10 @@ scraps
             body.proxyTier = opts.forceTier;
     }
     if (Object.keys(body).length === 0) {
+        if (opts.json) {
+            process.exitCode = reportError(new UsageError('Nothing to update. Provide at least one option.'), { json: true });
+            return;
+        }
         console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
         return;
     }
@@ -266,42 +348,35 @@ scraps
         text: 'Updating scrap…',
         successText: (d) => `Scrap updated: ${chalk.bold(d._id)}`,
     });
-    // #1559 — surface the effective tier + clamp/refuse reason (fixes the
-    // silent-clamp: the server may persist a lower tier than requested).
-    const ov = data._tierOverride;
+    // #1559 / #86 findings 4b/5 — surface the effective tier + clamp/refuse
+    // reason (fixes the silent-clamp: the server may persist a lower tier
+    // than requested), and NEVER echo the requested value as applied when
+    // the server doesn't confirm it (old-server fallback below).
+    const tierWasRequested = opts.tier !== undefined || opts.forceTier !== undefined;
+    warnIfUnconfirmedTier(data, tierWasRequested, id);
+    const refused = Boolean(data._tierOverride?.refused);
+    if (opts.json) {
+        if (refused) {
+            process.exitCode = reportTierRefusal(data, true);
+            return;
+        }
+        json(data);
+        return;
+    }
     const shown = data;
     for (const key of Object.keys(body)) {
-        // Only suppress the raw proxyTier/proxyMaxTier echo when _tierOverride is
-        // present to report the truth. Against an older server (no _tierOverride)
-        // fall back to echoing the requested value from the body, so the tier is
-        // never silently dropped (worse than a misleading echo).
-        if ((key === 'proxyTier' || key === 'proxyMaxTier') && ov)
+        // Tier keys are rendered exclusively by renderTierOverrideHuman /
+        // warnIfUnconfirmedTier above — never echo them here, whether or not
+        // _tierOverride came back (an old-server echo of the REQUESTED value
+        // is exactly the silent-clamp lie #1559 fixed).
+        if (key === 'proxyTier' || key === 'proxyMaxTier')
             continue;
         const src = key in shown ? shown[key] : body[key];
         console.log(chalk.dim(`  ${key}: `) + String(src ?? '—'));
     }
-    if (ov) {
-        if (ov.refused) {
-            console.error(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
-                + chalk.dim(` (requested ${ov.requestedMaxTier ?? '—'}; kept the registry cap)`));
-            process.exitCode = 1;
-        }
-        else if (ov.effectiveMaxTier) {
-            console.log(chalk.green(`  ✓ tier ceiling: ${ov.effectiveMaxTier}`)
-                + chalk.dim(` (${ov.reason ?? ''}${ov.provider ? `, ${ov.provider}` : ''})`));
-            if (ov.warning)
-                console.log(chalk.yellow(`    ⚠ ${ov.warning}`));
-        }
-        if (ov.proxyTier) {
-            if (ov.proxyTier.clamped) {
-                console.log(chalk.yellow(`  ⚠ proxyTier requested ${ov.proxyTier.requested} → applied ${ov.proxyTier.effective}`)
-                    + chalk.dim(` (${ov.proxyTier.reason ?? 'capped'})`));
-            }
-            else {
-                console.log(chalk.dim(`  proxyTier: `) + ov.proxyTier.effective);
-            }
-        }
-    }
+    renderTierOverrideHuman(data);
+    if (refused)
+        process.exitCode = 1;
 });
 // run
 scraps
@@ -332,6 +407,25 @@ function renderScrapItems(items, asJson) {
     }
     console.log(chalk.dim('  Use --json for full output.'));
 }
+/**
+ * #86 finding 6 — `data`'s honest empty-vs-error distinction, for both --json
+ * and human prose. Before this, EVERY non-array outcome (never run, last run
+ * failed, or the payload aged out of retention) collapsed to the SAME `[]` /
+ * "No data yet." — indistinguishable from a genuine zero-item successful run.
+ * That's a lie under --json: an agent can't tell "nothing to show" from "go
+ * look at what actually happened". Mirrors reportError's dual json/human
+ * shape (human line to stderr always; --json ALSO gets a machine envelope on
+ * stdout) with a caller-chosen exit code + kind, since these states are not
+ * all "usage" (2) — never-run / aged-out-of-retention are not_found (4), a
+ * failed last run is a business-logic failure (1).
+ */
+function reportDataState(message, exitCode, kind, wantsJson) {
+    console.error(chalk.red(`✗ ${message}`));
+    if (wantsJson) {
+        console.log(JSON.stringify({ error: { message, kind } }));
+    }
+    process.exitCode = exitCode;
+}
 // data
 scraps
     .command('data <id>')
@@ -397,17 +491,31 @@ scraps
     // it's just pulled from the most recent history row instead of a fresh
     // run. Retention keeps this only for the newest row per (scrap, status)
     // bucket (config.trawl.keepData, default 1); older rows null it out.
+    //
+    // #86 finding 6 — [] is reserved for a GENUINE zero-item successful run.
+    // Every other outcome below is an honest error envelope instead: never
+    // run (not_found/4), last run failed (1), or the payload aged out of
+    // retention (not_found/4) all used to collapse into the same silent [].
     const scrap = await api.get(`/api/scraps/${id}`);
-    const hid = scrap.history?.[0]?._id;
-    if (!hid) {
-        if (opts.json) {
-            json([]);
-            return;
-        }
-        console.log(chalk.dim('No data yet. Run the scrap first, or pass --fresh to launch one now.'));
+    const last = scrap.history?.[0];
+    if (!last?._id) {
+        reportDataState(`Scrap ${id} has never run. Run it first (trawl scraps run ${id}) or pass --fresh to launch one now.`, 4, 'not_found', opts.json);
         return;
     }
-    const detail = await api.get(`/api/historys/${hid}`);
+    // #86 review — node persists status=false for a GENUINE zero-item run
+    // too (historys schema: status boolean|null + statusDetail
+    // success/error/empty/regression; a zero-item run is status=false +
+    // statusDetail='empty', and the embedded history rows from GET
+    // /api/scraps/:id include statusDetail via the repository populate
+    // select). An 'empty' run is the one case [] is FOR — only a real
+    // failure (error/regression/unknown detail) gets the run_failed
+    // envelope.
+    const isEmptyRun = last.status === false && last.statusDetail === 'empty';
+    if (last.status === false && !isEmptyRun) {
+        reportDataState(`Last run failed — see: trawl scraps data ${id} --errors`, 1, 'run_failed', opts.json);
+        return;
+    }
+    const detail = await api.get(`/api/historys/${last._id}`);
     let items;
     if (typeof detail?.data === 'string' && detail.data) {
         try {
@@ -418,12 +526,14 @@ scraps
         }
     }
     if (!Array.isArray(items)) {
-        if (opts.json) {
-            json([]);
+        if (isEmptyRun) {
+            // A genuine zero-item run whose payload is '[]' or absent — both are
+            // the SAME honest answer: no items, exit 0. Never the retention
+            // message (nothing aged out; there was nothing to persist).
+            renderScrapItems([], opts.json);
             return;
         }
-        console.log(chalk.dim('No persisted data for the last run (it may have failed, or aged out of retention). '
-            + 'Pass --fresh to launch a new run (consumes execute quota).'));
+        reportDataState(`No persisted data for the last successful run of ${id} — it aged out of retention. Pass --fresh to launch a new run.`, 4, 'not_found', opts.json);
         return;
     }
     renderScrapItems(items, opts.json);
@@ -708,8 +818,9 @@ account
     const data = await oraPromise(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
     const acc = data.account;
     if (opts.json) {
-        const { json: jsonFn } = await import('../lib/format.js');
-        return jsonFn(acc ?? null);
+        // #86 finding 12 — `json` is already statically imported at the top of
+        // this file; the dynamic import here was pure dead weight.
+        return json(acc ?? null);
     }
     if (!acc) {
         console.log(chalk.dim('No account data available.'));

package/dist/commands/skills.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { listBundledSkills, installSkill, uninstallSkill, getBundledSkillsVersion, getInstalledVersion, isSkillInstalled, } from '../lib/skills.js';
+import { listBundledSkills, installSkill, uninstallSkill, getBundledSkillsVersion, getInstalledVersion, isSkillInstalled, removeOrphanedSkills, } from '../lib/skills.js';
+import { UsageError } from '../lib/errors.js';
 function pickScope(opts) {
     return opts.local ? 'local' : 'user';
 }
@@ -9,7 +10,9 @@ function pickSkills(arg) {
     if (!arg || arg === 'all')
         return all;
     if (!all.includes(arg)) {
-        throw new Error(`Unknown skill "${arg}". Available: ${all.join(', ') || '(none)'}`);
+        // Usage error (exit 2), not a generic bug (exit 1) — the caller typed a
+        // skill name that doesn't exist. (#86 finding 3)
+        throw new UsageError(`Unknown skill "${arg}". Available: ${all.join(', ') || '(none)'}`);
     }
     return [arg];
 }
@@ -45,11 +48,12 @@ skills
     .command('install [skill]')
     .description('Install one or all bundled skills')
     .option('--local', 'Install at project level (./.claude/skills) instead of user level (~/.claude/skills)')
+    .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
     for (const name of targets) {
-        const dest = installSkill(name, scope);
+        const dest = installSkill(name, scope, { force: opts.force });
         console.log(chalk.green(`✓ Installed "${name}"`) + chalk.dim(` at ${dest}`));
     }
     console.log(chalk.dim('  Restart Claude Code if it was already running.'));
@@ -73,11 +77,19 @@ skills
     .command('update [skill]')
     .description('Reinstall over the existing skill (force sync with CLI version)')
     .option('--local', 'Update at project level')
+    .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
     for (const name of targets) {
-        const dest = installSkill(name, scope);
+        const dest = installSkill(name, scope, { force: opts.force });
         console.log(chalk.green(`✓ Updated "${name}"`) + chalk.dim(` at ${dest}`));
     }
+    // #86 review — same orphan sweep as the startup auto-sync: an explicit
+    // `skills update` must also drop CLI-owned dirs whose skill was renamed
+    // or removed upstream (e.g. 1.0.0's `trawl` → 1.3.1's `trawl-cli`),
+    // instead of leaving a stale ghost teaching outdated usage. Only the
+    // scope being updated is swept; marker-less dirs are never touched.
+    // removeOrphanedSkills prints its own honest stderr line per removal.
+    removeOrphanedSkills(scope);
 });

package/dist/commands/token.js

@@ -1,21 +1,27 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import config from '../lib/config.js';
+import { getToken } from '../lib/config.js';
+import { ApiError, notLoggedInError } from '../lib/api.js';
+import { reportError } from '../lib/errors.js';
 import { decodeExp } from '../lib/jwt.js';
 export const token = new Command('token')
     .description('Print the stored session JWT (for MCP Bearer auth)')
     .action(() => {
-    const stored = config.get('token');
+    // getToken() resolves TRAWL_TOKEN env first, then the stored config
+    // token (see config.ts:47-51) — matching every other token consumer in
+    // the CLI instead of reading the config store directly. (#86 finding 1)
+    const stored = getToken();
     if (!stored) {
-        console.error(chalk.red('✗ Not logged in. Run: trawl login'));
-        process.exitCode = 1;
+        // Auth-classified (ApiError 401 → exit 3, kind:"auth"), not a generic
+        // exit 1 — an agent scripting `trawl token` needs to tell "not logged
+        // in" apart from an arbitrary bug. (#86 finding 1)
+        process.exitCode = reportError(notLoggedInError());
         return;
     }
     const exp = decodeExp(stored);
     const nowSeconds = Math.floor(Date.now() / 1000);
     if (exp !== null && exp < nowSeconds) {
-        console.error(chalk.red('✗ Session token expired. Run: trawl login to refresh.'));
-        process.exitCode = 1;
+        process.exitCode = reportError(new ApiError(401, 'Session token expired. Run: trawl login to refresh.'));
         return;
     }
     // Print the raw token first (so it can be piped / copied)

package/dist/index.d.ts

@@ -18,10 +18,36 @@ export declare function createProgram(): Command;
 /** True when this module is the process entrypoint (not merely imported by a test). */
 export declare function isEntryPoint(argv1: string | undefined, moduleUrl: string): boolean;
 /**
- * True when the invocation is a pure `--help`/`--version` query. These must not
- * trigger the skills auto-sync (a filesystem-mutating startup side effect) — a
- * user running `trawl --version` never expects it to rewrite their skills dirs.
- * (#73)
+ * True when the invocation is a pure `--help`/`--version` query, a bare
+ * `trawl` with no subcommand (commander prints top-level help and exits), or
+ * `trawl help [command]`. None of these should trigger the skills auto-sync
+ * (a filesystem-mutating startup side effect) — a user running `trawl
+ * --version` (or just `trawl`) never expects it to rewrite their skills
+ * dirs. (#73, extended #86 finding 7 for the bare-invocation + `help`
+ * subcommand cases)
  */
 export declare function isHelpOrVersion(argv: string[]): boolean;
+/** Best-effort scan for a `--json` flag in raw argv, used only when parsing
+ * itself failed before any command's own `.opts()` could be resolved (a
+ * commander usage error — unknown option/command, missing required arg). Same
+ * "argv scan, never trust flag values" caveat as isHelpOrVersion: positional
+ * values are never mistaken for `--json` since they don't equal the literal
+ * string. (#86 finding 3)
+ */
+export declare function hasJsonFlag(argv: string[]): boolean;
+/**
+ * Commander's default (no exitOverride) calls `process.exit()` directly for
+ * a usage error (unknown option/command, missing required arg) or a
+ * --help/--version/`help` query — bypassing runCli's try/catch/finally
+ * entirely, so the telemetry shutdown() flush below never runs and a usage
+ * error exits 1 (the generic bug bucket) instead of its own distinct code.
+ * `program.exitOverride()` on the root command alone does NOT fix this for
+ * subcommands added via `addCommand()` (login/scraps/skills/telemetry/token
+ * are each built as standalone Command instances in their own module and
+ * only ever copy inherited settings — including exitOverride — from a parent
+ * at `.command()` construction time, which for these root-level modules never
+ * happens). Every node in the tree needs its own exitOverride() call, so this
+ * walks the whole tree and installs it everywhere. (#86 finding 3)
+ */
+export declare function applyExitOverride(cmd: Command): void;
 export declare function runCli(argv?: string[]): Promise<void>;

package/dist/index.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import chalk from 'chalk';
+import { Command, CommanderError } from 'commander';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -11,7 +10,7 @@ import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
-import { classifyError } from './lib/errors.js';
+import { classifyError, reportError } from './lib/errors.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -63,19 +62,66 @@ export function isEntryPoint(argv1, moduleUrl) {
     return argv1 !== undefined && moduleUrl === pathToFileURL(argv1).href;
 }
 /**
- * True when the invocation is a pure `--help`/`--version` query. These must not
- * trigger the skills auto-sync (a filesystem-mutating startup side effect) — a
- * user running `trawl --version` never expects it to rewrite their skills dirs.
- * (#73)
+ * True when the invocation is a pure `--help`/`--version` query, a bare
+ * `trawl` with no subcommand (commander prints top-level help and exits), or
+ * `trawl help [command]`. None of these should trigger the skills auto-sync
+ * (a filesystem-mutating startup side effect) — a user running `trawl
+ * --version` (or just `trawl`) never expects it to rewrite their skills
+ * dirs. (#73, extended #86 finding 7 for the bare-invocation + `help`
+ * subcommand cases)
  */
 export function isHelpOrVersion(argv) {
-    return argv.some((a) => a === '-h' || a === '--help' || a === '-V' || a === '--version');
+    if (argv.some((a) => a === '-h' || a === '--help' || a === '-V' || a === '--version'))
+        return true;
+    const args = argv.slice(2);
+    if (args.length === 0)
+        return true;
+    if (args[0] === 'help')
+        return true;
+    return false;
 }
+/** Best-effort scan for a `--json` flag in raw argv, used only when parsing
+ * itself failed before any command's own `.opts()` could be resolved (a
+ * commander usage error — unknown option/command, missing required arg). Same
+ * "argv scan, never trust flag values" caveat as isHelpOrVersion: positional
+ * values are never mistaken for `--json` since they don't equal the literal
+ * string. (#86 finding 3)
+ */
+export function hasJsonFlag(argv) {
+    return argv.includes('--json');
+}
+/**
+ * Commander's default (no exitOverride) calls `process.exit()` directly for
+ * a usage error (unknown option/command, missing required arg) or a
+ * --help/--version/`help` query — bypassing runCli's try/catch/finally
+ * entirely, so the telemetry shutdown() flush below never runs and a usage
+ * error exits 1 (the generic bug bucket) instead of its own distinct code.
+ * `program.exitOverride()` on the root command alone does NOT fix this for
+ * subcommands added via `addCommand()` (login/scraps/skills/telemetry/token
+ * are each built as standalone Command instances in their own module and
+ * only ever copy inherited settings — including exitOverride — from a parent
+ * at `.command()` construction time, which for these root-level modules never
+ * happens). Every node in the tree needs its own exitOverride() call, so this
+ * walks the whole tree and installs it everywhere. (#86 finding 3)
+ */
+export function applyExitOverride(cmd) {
+    cmd.exitOverride();
+    for (const sub of cmd.commands)
+        applyExitOverride(sub);
+}
+/** Commander's own codes for a successful --help/--version/`help` query —
+ * these already printed their own output (to stdout) via commander itself;
+ * runCli's catch must treat them as a clean exit, not an error. (#86 finding 3) */
+const HELP_OR_VERSION_CODES = new Set(['commander.helpDisplayed', 'commander.help', 'commander.version']);
 export async function runCli(argv = process.argv) {
     if (!isHelpOrVersion(argv))
         autoUpdateInstalledSkills();
     initPostHog();
     const program = createProgram();
+    // Must run before parseAsync — installs on every node in the tree,
+    // including subcommands added via addCommand() that don't otherwise
+    // inherit it. (#86 finding 3)
+    applyExitOverride(program);
     registerAllowedCommands(collectCommandNames(program));
     // Track start times + the currently-resolved command per instance, so the
     // catch handler below can derive the exact same safe name the success path
@@ -102,31 +148,60 @@ export async function runCli(argv = process.argv) {
         await program.parseAsync(argv);
     }
     catch (err) {
-        // Map the error to a distinct exit code + machine envelope instead of a
-        // uniform 1 — agents driving this CLI unattended need to tell
-        // auth-expired (3) from not-found (4) from network-down (5) from a bad
-        // flag (2) apart from an arbitrary bug (1). (#71)
-        const { exitCode, envelope } = classifyError(err);
-        // Capture error telemetry from the resolved command only — never argv.
-        void captureCommand(resolveCommandName(currentCommand), {
-            exit_code: exitCode,
-            error: err.name,
-        });
         const { debug } = program.opts();
         const isDebug = Boolean(debug || process.env['DEBUG']);
-        // A --json subcommand must keep stdout pure JSON even on failure — read
-        // the resolved command's own --json flag (never argv) so the error
-        // envelope lands on the same channel the success path would have used.
-        const wantsJson = Boolean(currentCommand?.opts()?.json);
-        if (isDebug)
-            console.error(err);
-        if (wantsJson) {
-            console.log(JSON.stringify({ error: envelope }));
+        if (err instanceof CommanderError) {
+            // Commander's own parse-time errors (exitOverride, #86 finding 3) —
+            // a distinct family from our ApiError/NetworkError/UsageError/generic
+            // Error taxonomy, so classifyError/reportError don't apply here.
+            if (HELP_OR_VERSION_CODES.has(err.code)) {
+                // --help / --version / `trawl help` already printed their own
+                // output via commander itself — nothing else to print, just adopt
+                // commander's suggested exit code (0) and fall through to the
+                // shared shutdown() flush below.
+                process.exitCode = err.exitCode;
+            }
+            else {
+                // A usage error (unknown option/command, missing required arg, …) —
+                // commander already wrote its own human-readable line to stderr via
+                // Command#error(), so this never duplicates it. Force exit code 2
+                // (usage) regardless of whichever code commander suggests (it
+                // defaults these to 1), and add the --json machine envelope when
+                // resolvable — parsing failed before any command's own --json flag
+                // could be read off `currentCommand` (preAction never fired), so
+                // scan raw argv instead. (#86 finding 3)
+                if (isDebug)
+                    console.error(err);
+                if (hasJsonFlag(argv)) {
+                    console.log(JSON.stringify({ error: { message: err.message, kind: 'usage' } }));
+                }
+                process.exitCode = 2;
+                void captureCommand(resolveCommandName(currentCommand), { exit_code: 2, error: 'CommanderError' });
+            }
         }
-        else if (!isDebug) {
-            console.error(chalk.red('✗ ' + envelope.message));
+        else {
+            // Map the error to a distinct exit code + machine envelope instead of a
+            // uniform 1 — agents driving this CLI unattended need to tell
+            // auth-expired (3) from not-found (4) from network-down (5) from a bad
+            // flag (2) apart from an arbitrary bug (1). (#71)
+            const { exitCode } = classifyError(err);
+            // Capture error telemetry from the resolved command only — never argv.
+            void captureCommand(resolveCommandName(currentCommand), {
+                exit_code: exitCode,
+                error: err.name,
+            });
+            // A --json subcommand must keep stdout pure JSON even on failure — read
+            // the resolved command's own --json flag (never argv) so the error
+            // envelope lands on the same channel the success path would have used.
+            const wantsJson = Boolean(currentCommand?.opts()?.json);
+            if (isDebug)
+                console.error(err);
+            // reportError is the single formatting path (#86 finding 9) — prints
+            // EITHER the --json envelope (stdout) OR the human "✗ message" line
+            // (stderr), never both; `quiet` skips the human line when the raw
+            // stack was already dumped above under --debug.
+            process.exitCode = reportError(err, { json: wantsJson, quiet: isDebug });
         }
-        process.exitCode = exitCode;
     }
     finally {
         // Flush + close telemetry before the process exits. A `process.on('exit')`

package/dist/lib/api.d.ts

@@ -11,6 +11,17 @@ export declare class ApiError extends Error {
 export declare class NetworkError extends Error {
     constructor(message: string);
 }
+/**
+ * The single "no token available" error — every call site in this file that
+ * needs a token (request/upload/getText/stream) used to throw its own copy
+ * of `new Error('Not logged in. Run: trawl login')`, which fell through
+ * classifyError's generic branch (exit 1, kind:"unknown") — indistinguishable
+ * from an arbitrary bug. Auth-classifying it as an ApiError(401) puts it on
+ * the exact same exit-3 / kind:"auth" path a real 401 response already takes.
+ * `trawl token` (src/commands/token.ts) reuses this too, so "no token" means
+ * the same thing everywhere it can be observed. (#86 findings 1/2)
+ */
+export declare function notLoggedInError(): ApiError;
 export declare const api: {
     get: <T>(path: string) => Promise<T>;
     getText: (path: string) => Promise<string>;

package/dist/lib/api.js

@@ -25,6 +25,19 @@ export class NetworkError extends Error {
         this.name = 'NetworkError';
     }
 }
+/**
+ * The single "no token available" error — every call site in this file that
+ * needs a token (request/upload/getText/stream) used to throw its own copy
+ * of `new Error('Not logged in. Run: trawl login')`, which fell through
+ * classifyError's generic branch (exit 1, kind:"unknown") — indistinguishable
+ * from an arbitrary bug. Auth-classifying it as an ApiError(401) puts it on
+ * the exact same exit-3 / kind:"auth" path a real 401 response already takes.
+ * `trawl token` (src/commands/token.ts) reuses this too, so "no token" means
+ * the same thing everywhere it can be observed. (#86 findings 1/2)
+ */
+export function notLoggedInError() {
+    return new ApiError(401, 'Not logged in. Run: trawl login');
+}
 const DEFAULT_TIMEOUT_MS = 30_000;
 /** Effective fetch timeout — TRAWL_TIMEOUT env override (ms), default 30s. (#71) */
 function getTimeoutMs() {
@@ -166,7 +179,7 @@ async function throwIfError(res, isPublic = false) {
 async function request(path, options = {}) {
     const token = getToken();
     if (!token)
-        throw new Error('Not logged in. Run: trawl login');
+        throw notLoggedInError();
     const url = `${getApiUrl()}${path}`;
     const res = await safeFetch(url, {
         ...options,
@@ -197,7 +210,7 @@ async function request(path, options = {}) {
 async function upload(path, formData) {
     const token = getToken();
     if (!token)
-        throw new Error('Not logged in. Run: trawl login');
+        throw notLoggedInError();
     const url = `${getApiUrl()}${path}`;
     // Do NOT set Content-Type — fetch sets it automatically with the correct multipart boundary
     const res = await safeFetch(url, {
@@ -246,7 +259,7 @@ async function publicPost(path, body, baseUrlOverride) {
 async function getText(path) {
     const token = getToken();
     if (!token)
-        throw new Error('Not logged in. Run: trawl login');
+        throw notLoggedInError();
     const url = `${getApiUrl()}${path}`;
     const res = await safeFetch(url, {
         headers: {
@@ -275,7 +288,7 @@ export const api = {
     stream: async function* (path) {
         const token = getToken();
         if (!token)
-            throw new Error('Not logged in. Run: trawl login');
+            throw notLoggedInError();
         const url = `${getApiUrl()}${path}`;
         // No AbortSignal.timeout here — a long-running `watch`/`--watch` stream is
         // expected to sit open indefinitely; only connection-level failures

package/dist/lib/skills.d.ts

@@ -1,14 +1,44 @@
 export declare function getBundledSkillsVersion(): string;
 export declare function listBundledSkills(): string[];
-export declare function installSkill(name: string, scope: 'user' | 'local'): 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
+ * the CLI didn't install. `autoUpdateInstalledSkills()` already checks this
+ * itself before ever calling here (it skips marker-less dirs outright), but
+ * the explicit `trawl skills install`/`update` commands used to call straight
+ * through with no such check — a pre-existing user-authored
+ * `.claude/skills/<name>` dir that happens to collide with a bundled skill
+ * name would get silently deleted and overwritten. A missing `.version`
+ * marker on an EXISTING dest now refuses the install/reinstall unless
+ * `force` is passed.
+ */
+export declare function installSkill(name: string, scope: 'user' | 'local', opts?: {
+    force?: boolean;
+}): string;
 export declare function uninstallSkill(name: string, scope: 'user' | 'local'): string | null;
 export declare function getInstalledVersion(name: string, scope: 'user' | 'local'): string | null;
 export declare function isSkillInstalled(name: string, scope: 'user' | 'local'): boolean;
+/**
+ * #86 review — orphan cleanup. The re-sync loop in autoUpdateInstalledSkills
+ * iterates listBundledSkills() — the NEW package's names only. When a bundled
+ * skill is RENAMED between package versions (1.0.0 shipped `trawl`, 1.3.1
+ * renamed it `trawl-cli`), the old marker-owned dir is never visited again: a
+ * stale ghost skill teaching outdated CLI usage stays installed forever,
+ * alongside the new one. This sweeps each scope's skills base dir for
+ * installed dirs that (a) carry a `.version` marker — the same ownership
+ * proof as everywhere else; a marker-less user-authored dir is NEVER touched,
+ * whatever its name — and (b) are no longer in the bundled set, and removes
+ * them with one honest stderr line (same style as the re-sync line).
+ * Returns the removed names (for the explicit `skills update` path to
+ * summarize).
+ */
+export declare function removeOrphanedSkills(scope: 'user' | 'local'): string[];
 /**
  * Re-installs any CLI-owned skill whose installed version doesn't match the
- * bundled one. Called on CLI startup to keep skills in sync with the CLI
- * version. Never throws — failures are silent so they don't break unrelated
- * commands.
+ * bundled one, and removes CLI-owned skills that are no longer bundled at all
+ * (renamed/dropped upstream — see removeOrphanedSkills). Called on CLI
+ * startup to keep skills in sync with the CLI version. Never throws —
+ * failures are silent so they don't break unrelated commands.
  *
  * Ownership guard (#73): `installSkill` does `rmSync(recursive)` on the target
  * dir, so this MUST only ever touch dirs the CLI itself installed. Proof of

package/dist/lib/skills.js

@@ -24,14 +24,32 @@ function getSkillsBase(scope) {
     const base = scope === 'local' ? join(process.cwd(), '.claude') : join(homedir(), '.claude');
     return join(base, 'skills');
 }
-export function installSkill(name, scope) {
+/**
+ * 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
+ * the CLI didn't install. `autoUpdateInstalledSkills()` already checks this
+ * itself before ever calling here (it skips marker-less dirs outright), but
+ * the explicit `trawl skills install`/`update` commands used to call straight
+ * through with no such check — a pre-existing user-authored
+ * `.claude/skills/<name>` dir that happens to collide with a bundled skill
+ * name would get silently deleted and overwritten. A missing `.version`
+ * marker on an EXISTING dest now refuses the install/reinstall unless
+ * `force` is passed.
+ */
+export function installSkill(name, scope, opts = {}) {
     const src = join(getSkillsPackageRoot(), 'skills', name);
     if (!existsSync(src)) {
         throw new Error(`Skill "${name}" not found in @trawlme/skills`);
     }
     const dest = join(getSkillsBase(scope), name);
-    if (existsSync(dest))
+    if (existsSync(dest)) {
+        const owned = getInstalledVersion(name, scope) !== 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.`);
+        }
         rmSync(dest, { recursive: true, force: true });
+    }
     mkdirSync(dest, { recursive: true });
     cpSync(src, dest, { recursive: true });
     writeFileSync(join(dest, '.version'), getBundledSkillsVersion(), 'utf8');
@@ -53,11 +71,52 @@ export function getInstalledVersion(name, scope) {
 export function isSkillInstalled(name, scope) {
     return existsSync(join(getSkillsBase(scope), name));
 }
+/**
+ * #86 review — orphan cleanup. The re-sync loop in autoUpdateInstalledSkills
+ * iterates listBundledSkills() — the NEW package's names only. When a bundled
+ * skill is RENAMED between package versions (1.0.0 shipped `trawl`, 1.3.1
+ * renamed it `trawl-cli`), the old marker-owned dir is never visited again: a
+ * stale ghost skill teaching outdated CLI usage stays installed forever,
+ * alongside the new one. This sweeps each scope's skills base dir for
+ * installed dirs that (a) carry a `.version` marker — the same ownership
+ * proof as everywhere else; a marker-less user-authored dir is NEVER touched,
+ * whatever its name — and (b) are no longer in the bundled set, and removes
+ * them with one honest stderr line (same style as the re-sync line).
+ * Returns the removed names (for the explicit `skills update` path to
+ * summarize).
+ */
+export function removeOrphanedSkills(scope) {
+    const base = getSkillsBase(scope);
+    if (!existsSync(base))
+        return [];
+    const bundled = new Set(listBundledSkills());
+    const removed = [];
+    for (const name of readdirSync(base)) {
+        const dir = join(base, name);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue; // raced away / unreadable — nothing to clean
+        }
+        if (bundled.has(name))
+            continue;
+        // No `.version` marker → not ours → never delete it.
+        if (getInstalledVersion(name, scope) === null)
+            continue;
+        rmSync(dir, { recursive: true, force: true });
+        process.stderr.write(`trawl: removed orphaned skill "${name}" (${scope}) — no longer bundled with this CLI version\n`);
+        removed.push(name);
+    }
+    return removed;
+}
 /**
  * Re-installs any CLI-owned skill whose installed version doesn't match the
- * bundled one. Called on CLI startup to keep skills in sync with the CLI
- * version. Never throws — failures are silent so they don't break unrelated
- * commands.
+ * bundled one, and removes CLI-owned skills that are no longer bundled at all
+ * (renamed/dropped upstream — see removeOrphanedSkills). Called on CLI
+ * startup to keep skills in sync with the CLI version. Never throws —
+ * failures are silent so they don't break unrelated commands.
  *
  * Ownership guard (#73): `installSkill` does `rmSync(recursive)` on the target
  * dir, so this MUST only ever touch dirs the CLI itself installed. Proof of
@@ -89,6 +148,11 @@ export function autoUpdateInstalledSkills() {
                 process.stderr.write(`trawl: re-synced skill "${name}" (${scope}) ${installed} → ${bundledVersion}\n`);
             }
         }
+        // Migration gap (#86 review): also drop marker-owned dirs whose skill
+        // was renamed/removed upstream, or they linger as stale ghosts forever.
+        for (const scope of ['user', 'local']) {
+            removeOrphanedSkills(scope);
+        }
     }
     catch {
         // Silent: skill auto-update should never block the CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.18.1",
+  "version": "1.18.2",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "url": "https://github.com/comes-io/trawl_cli/issues"
   },
   "dependencies": {
-    "@trawlme/skills": "^1.0.0",
+    "@trawlme/skills": "1.3.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "conf": "^15.1.0",