@trawlme/cli 1.21.0 → 2.0.0

package/README.md

@@ -8,6 +8,8 @@ Command-line client for [Trawl](https://trawl.me) — manage your scraps from th
 
 > ⚠️ **Early stage.** APIs may change before `1.0`. Pin a version if you depend on this in CI.
 
+> 🤖 **Driving this CLI from an AI agent?** See [docs/agent-quickstart.md](docs/agent-quickstart.md) for the minimal surface (`create`, `--json`, `TRAWL_TOKEN`, exit codes) — this README is the full human/CI guide.
+
 ## Install
 
 Requires Node.js >= 20.
@@ -21,48 +23,52 @@ npm install -g @trawlme/cli
 Three methods:
 
 1. **Interactive** — `trawl login` (prompts for email and password)
-2. **Env var** — `TRAWL_TOKEN=<jwt> trawl scraps list` (CI/CD, bypasses prompt)
+2. **Env var** — `TRAWL_TOKEN=<jwt> trawl list` (CI/CD, bypasses prompt)
 3. **Token flag** — `trawl login --token <jwt>` (CI/CD, direct JWT)
 
 Custom API URL: `trawl login --url https://self-hosted.example.com`
 
 ## Commands
 
+`trawl --help` groups commands into two labeled tiers, in this exact wording: **Core commands (agent + human)** (listed first — `--json` first-class, never interactive) and **Management commands (human/CI)** (grouped below — the full scrap-admin/account/auth/skills/telemetry surface). Commander also prints a small ungrouped `help [command]` entry at the bottom, so "two tiers" describes the labeled sections, not literally every line of `--help` output. This section documents both tiers, in that order; [docs/agent-quickstart.md](docs/agent-quickstart.md) covers just the Core tier for an agent integration.
+
 All commands accept a global `--debug` flag to show full error stack traces on failure. Every command below supports `--json` (a raw payload / structured result on stdout, nothing else) and never blocks on an interactive prompt when `--json` is set or stdin/stdout isn't a real TTY — see [Non-interactive rule](#non-interactive-rule) and [Exit codes](#exit-codes). Two documented exceptions to "single payload": `scraps watch --json` is a live stream, so it emits NDJSON (one JSON object per line) instead; `scraps snapshot --json` only changes behavior on a never-run scrap (`{"status":"no_runs"}`) — when a run exists it still writes the raw HTML snapshot regardless of `--json` (there's no JSON-encoded form of an HTML page to emit).
 
-### Auth
+### Core commands (agent + human)
 
 ```
-trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>] [--json]
-trawl logout [--json]
-trawl token [--json]                         Print the stored session JWT (for MCP Bearer auth)
+trawl create <url> --prompt <goal> [--no-autofix] [--json]   Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
+trawl run <id> [--watch] [--json]              Run a scrap
+trawl list|ls [--json] [--status <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
+trawl get <id> [--json]                        Get scrap details
+trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run — read-only, no quota; --fresh to launch one)
+trawl history <id> [--json] [-n <limit>]       List past runs for a scrap (newest first)
+trawl run-info <hid> [--json]                  Show details of a single run
+trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker (returns immediately)
+trawl whoami [--json]                          Show the authenticated user's identity
+trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
 
-`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `token`'s job). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
+> **No breaking change:** every verb above is also still reachable under its pre-reorg path, `trawl scraps <verb>` (e.g. `trawl scraps list`, `trawl scraps run <id>`) — kept as a hidden alias so scripts written before the surface reorg keep working. `trawl --help` only shows the top-level form above; `trawl scraps --help` only shows the remaining scrap-management commands below.
 
-### Agent core verbs
+`create`/`whoami`/`ping` are fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl create` runs the AI wizard server-side (`POST /api/ai/wizard`): generate scrap code from `--prompt` via LLM, persist the scrap, trigger its FIRST run, and auto-fix on failure (default on — `--no-autofix` disables it, sending `autoFix:false`). `success` is an honest outcome of that first run, not "did the HTTP call succeed" — a failed first run is still a 200 response (the scrap was still created; auto-fix, when enabled, retries in the background), and the CLI exits 1 in that case (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. The call legitimately takes 30–250s+ server-side (AI generation + a real run), same long-run timeout as `run`/`data --fresh`/`trigger --wait` below. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
 
-```
-trawl fetch <url> [--json] [--reason <text>]  One-shot fetch + extract readable content from a public URL (no scrap needed)
-trawl whoami [--json]                         Show the authenticated user's identity
-trawl ping [--json]                           Health/version handshake against the Trawl API
-```
+> **`create` is NOT idempotent, and every wizard-created scrap runs on a DAILY cron by default.** A client-side timeout (exit `5`, a `NetworkError`) does not mean the wizard failed server-side — scrap creation + the first run keep going after the CLI gives up waiting, so the scrap may already exist. Run `trawl list` and look for a matching URL/title **before** retrying — a blind retry creates a DUPLICATE scrap and burns AI-generation quota a second time for the same goal. Separately, the scrap the wizard creates is scheduled to re-run every day at 07:00 UTC (`cron: "0 7 * * *"`, hardcoded server-side, unrelated to `--no-autofix`) — each of those recurring runs consumes execute quota like any other run. Review the generated scrap, then change or disable the schedule with `trawl scraps update <id> --cron <expr>` (or `--no-cron` to disable it). Because the call can legitimately run 250s+, also confirm `TRAWL_TIMEOUT` isn't set to something tighter than `create` needs — the env var always wins over `create`'s own 300s default (see [Environment variables](#environment-variables)), so a value set for another purpose (e.g. a tight CI smoke-test budget) silently clamps `create` too; unset it or raise it before running `create`.
 
-Fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl fetch` is the REST counterpart of the MCP `trawl_fetch_url` tool (same shared engine, `POST /api/scraps/fetch-url`): `status` is an honest outcome (`completed`/`failed`/`empty`/`blocked`), not "did the HTTP call succeed" — a failed fetch is still a 200 response with `status:'failed'` + `error`, and the CLI exits 1 in that case (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. `truncated:true` means the 100KB response cap tripped; `result` is dropped and `url` repoints at the full history row instead. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
+- `list` has a short alias, `ls` (matches `trawl --help`'s `list|ls`).
+- `history` lists past runs (newest first); `run-info <hid>` shows details of a single run from that history.
+- `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 (`--json` on a never-run scrap returns `{"status":"no_runs"}`, exit 0, matching `scraps doctor --json`). `[]` 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. Two more honest states: a run still **in flight** (`status: null` server-side) returns a `kind:"in_progress"` error envelope (exit 1, "retry shortly" — never suggests `--fresh`, which would just 429 against the run already holding the lock); a run whose item count **regressed** vs baseline (`statusDetail: "regression"`) still returns the real, non-empty items on stdout (exit 0) plus a stderr warning pointing at `scraps doctor <id>` — the data itself is genuine even though the run is flagged.
+- `get` (and anything reading through it, like `data`'s default path) embeds only the newest 100 history rows on the returned scrap object — `run-info` and `scraps doctor` fetch a single run directly and are unaffected by that cap. `list`/`get` show a distinct amber `▼` "regression" badge, never the red `✗` a genuine failure gets (matches `scraps doctor`'s own badge).
+- **Long-running calls (`create`, `run`, `data --fresh`, `trigger --wait`):** these hit server-side paths that can legitimately take 30–250s+ (AI generation + scrap creation + a first run for `create`; proxy tier escalation + AI-fix retries for the other three) — the CLI arms a 300s timeout for exactly these four call sites instead of the generic 30s default. `TRAWL_TIMEOUT` (see below) still overrides ALL requests, including these — set it if you need a tighter or looser ceiling than 300s, but note a global override that tight also clamps `create`.
+- **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `run --watch` and `trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears. The watched run's outcome drives the exit code too, in BOTH human and `--json` mode: a genuinely failed terminal run, a poll timeout, or a persistently unreachable API all exit non-zero — a clean successful run is the only exit `0`. A run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>` (human mode) — see the `--json` shape below. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
+- `run --json`/`trigger --json` bypass the spinner and print the raw launch/trigger payload on stdout; combined with `--watch`, every intermediate progress line stays suppressed (stdout stays pure JSON) and, once the watch reaches its outcome, exactly ONE final NDJSON line is emitted: `{"runId","status"}` (the honest terminal status — `success`/`error`/`empty`/`regression`/…), `{"runId","status":"timeout"}` on a poll timeout, or `{"runId","status":"poll_error","error"}` if the API stays unreachable for several consecutive polls — `process.exitCode` is non-zero for all three except a genuine success. `scraps watch --json` emits one raw JSON object per activity line (NDJSON) instead of the formatted `[time] message` text — there's no single final payload to wait for on a live stream.
 
-### Scraps
+### Scrap management
 
 ```
-trawl scraps list [--json] [--status <success|failure|never|running|regression>] [--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>] [--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] [--json]
-trawl scraps trigger <id> [--watch] [--wait] [--json]
 trawl scraps watch <id> [--json]
-trawl scraps data <id> [--json] [--fresh] [--errors]
-trawl scraps history <id> [--json] [-n <limit>]
-trawl scraps run-info <hid> [--json]
 trawl scraps doctor <id> [--json] [--autofix]
 trawl scraps autofix <id> [--json]
 trawl scraps snapshot <id> [--error] [-o <file>] [--json]
@@ -71,16 +77,11 @@ trawl scraps delete <id> [--force] [--json]         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). `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 (`kind:"refused"` — distinct from `"unknown"`, so a script can branch on "the server said no"). When a tier was requested but the server's response carries no `_tierOverride` at all (an older server that can't confirm what actually got applied), a stderr warning is printed either way, and under `--json` the emitted object also carries `"_tierUnconfirmed": true` — the machine-readable counterpart to that warning, since a `--json` caller has no reliable reason to read stderr.
-- `scraps doctor` diagnoses the last run (error, failed selector, block status, page state, autofix outcome); `--autofix` includes the full autofix diff/dry-run/knowledge. A run that is still in flight (`status: null`, server-side) shows a `running` badge, never `failed`; a run whose item count regressed vs baseline (`statusDetail: "regression"`) shows its own amber `regression` badge, never `failed` either (`scraps list`/`get` show the same distinction — a `▼` icon, not the red `✗` a genuine failure gets).
+- `scraps doctor` diagnoses the last run (error, failed selector, block status, page state, autofix outcome); `--autofix` includes the full autofix diff/dry-run/knowledge. A run that is still in flight (`status: null`, server-side) shows a `running` badge, never `failed`; a run whose item count regressed vs baseline (`statusDetail: "regression"`) shows its own amber `regression` badge, never `failed` either.
 - `scraps autofix` shows the last auto-fix attempt on its own (decision, diff, dry-run, knowledge). `--json` on a scrap that has **never run** returns `{"status":"no_runs"}` (exit 0) — distinct from `null`, which means a run exists but had no auto-fix attempt.
 - `scraps snapshot --error` fetches the error-path snapshot instead of the normal one; `-o <file>` writes to a file instead of stdout. On a scrap that has **never run**: `--json` returns `{"status":"no_runs"}` (exit 0), matching `doctor`/`autofix`; `-o <file>` (without `--json`) exits 4 (`not_found`) instead of silently exiting 0 with nothing written — a script checking the exit code alone must be able to tell "no file was produced" from success. `--json` takes priority when both are passed.
-- `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 (`--json` on a never-run scrap returns `{"status":"no_runs"}`, exit 0, matching `doctor --json`). `[]` 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. Two more honest states: a run still **in flight** (`status: null` server-side) returns a `kind:"in_progress"` error envelope (exit 1, "retry shortly" — never suggests `--fresh`, which would just 429 against the run already holding the lock); a run whose item count **regressed** vs baseline (`statusDetail: "regression"`) still returns the real, non-empty items on stdout (exit 0) plus a stderr warning pointing at `scraps doctor <id>` — the data itself is genuine even though the run is flagged.
-- `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.
 - `scraps banner -f <file>` only accepts `png`/`jpg`/`jpeg`/`webp`; any other extension is a usage error (exit 2) instead of silently uploading the file under a fabricated `image/png` Content-Type.
-- **Long-running scrap execute (`scraps run`, `data --fresh`, `trigger --wait`):** these hit the same server-side scrap-execute path, which can legitimately take 30–250s (proxy tier escalation, AI-fix retries) — the CLI arms a 300s timeout for exactly these three call sites instead of the generic 30s default. `TRAWL_TIMEOUT` (see below) still overrides ALL requests, including these — set it if you need a tighter or looser ceiling than 300s for a long-running scrap.
-- **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `scraps run --watch` and `scraps trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears. The watched run's outcome drives the exit code too, in BOTH human and `--json` mode: a genuinely failed terminal run, a poll timeout, or a persistently unreachable API all exit non-zero — a clean successful run is the only exit `0`. A run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>` (human mode) — see the `--json` shape below. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
-- `scraps run --json`/`trigger --json` bypass the spinner and print the raw launch/trigger payload on stdout; combined with `--watch`, every intermediate progress line stays suppressed (stdout stays pure JSON) and, once the watch reaches its outcome, exactly ONE final NDJSON line is emitted: `{"runId","status"}` (the honest terminal status — `success`/`error`/`empty`/`regression`/…), `{"runId","status":"timeout"}` on a poll timeout, or `{"runId","status":"poll_error","error"}` if the API stays unreachable for several consecutive polls — `process.exitCode` is non-zero for all three except a genuine success. `scraps watch --json` emits one raw JSON object per activity line (NDJSON) instead of the formatted `[time] message` text — there's no single final payload to wait for on a live stream. `scraps delete`/`banner --json` print `{"deleted":true,"id"}` / the raw upload response.
+- `scraps delete`/`banner --json` print `{"deleted":true,"id"}` / the raw upload response.
 
 ### Scrap accounts
 
@@ -113,6 +114,16 @@ A pre-existing skill directory that trawl did not install itself (no `.version`
 
 You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
 
+### Auth
+
+```
+trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>] [--json]
+trawl logout [--json]
+trawl token [--json]                         Print the stored session JWT (for MCP Bearer auth)
+```
+
+`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `token`'s job). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
+
 ### Telemetry
 
 ```
@@ -126,7 +137,7 @@ trawl telemetry status [--json]   Show current state, telemetry ID, and opt-out
 `@trawlme/cli` collects anonymous usage data to help us improve the CLI based on real usage patterns. Telemetry is enabled by default.
 
 **What we collect:**
-- Command name (e.g. `scraps list`)
+- Command name (e.g. `list` — the #108 surface reorg renamed a promoted verb's telemetry event from `scraps <verb>` to `<verb>`; invoking the legacy `trawl scraps <verb>` path still emits the pre-reorg `scraps <verb>` name)
 - CLI version
 - Node.js version
 - Platform (e.g. `darwin`, `linux`, `win32`)
@@ -149,7 +160,7 @@ trawl telemetry status [--json]   Show current state, telemetry ID, and opt-out
 trawl telemetry off
 
 # Session-level opt-out (env var, takes precedence)
-TRAWL_TELEMETRY=0 trawl scraps list
+TRAWL_TELEMETRY=0 trawl list
 ```
 
 **Why:** usage data helps us prioritise CLI features and catch silent errors before users report them.
@@ -170,10 +181,10 @@ Every command exits with one of these codes — scripts and agents driving the C
 | Code | Meaning                                                                 |
 |------|--------------------------------------------------------------------------|
 | `0`  | Success                                                                 |
-| `1`  | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug — or a business-logic refusal like `scraps data`'s `run_failed`/`in_progress` states, or `trawl fetch`'s honest `status:'failed'`/`'blocked'` outcome). **Known overload:** `fetch`'s domain-level failure and an arbitrary unmapped bug both land on `1` — a script needs to read the `--json` payload's own `status`/`error` field (for `fetch`) to tell them apart; this is intentional (the REST contract's outcome states are a separate axis from the CLI's transport-error taxonomy) and documented here rather than "resolved" by inventing a new code that would only apply to one command. |
+| `1`  | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug — or a business-logic refusal like `data`'s `run_failed`/`in_progress` states, or `trawl create`'s honest `success:false` first-run outcome). **Known overload:** `create`'s domain-level failure and an arbitrary unmapped bug both land on `1` — a script needs to read the `--json` payload's own `success` field (for `create`) to tell them apart; this is intentional (the REST contract's outcome states are a separate axis from the CLI's transport-error taxonomy) and documented here rather than "resolved" by inventing a new code that would only apply to one command. |
 | `2`  | Usage error (bad flag/value, invalid ID, missing required argument, unknown option/command — including the [non-interactive rule](#non-interactive-rule) refusing to prompt) |
 | `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) |
+| `4`  | Not found (no such resource, or — for `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. `kind` is the machine-readable discriminant (`"usage"`/`"auth"`/`"not_found"`/`"network"`/`"api"`/`"refused"`/`"unknown"`/…) — the short string a script should switch on (`"refused"` is a business-logic refusal the server explicitly reported back, e.g. `scraps create|update`'s tier-ceiling override rejection — distinct from `"unknown"`, which stays reserved for an unmapped bug); `status` is present only when a real HTTP response carried one (never fabricated for a local failure like an expired-locally JWT or a refused confirmation prompt).
@@ -187,13 +198,13 @@ Under `--json`, a failing command emits a single error envelope on stdout — `{
 | `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`; `300000` for `scraps run`/`data --fresh`/`trigger --wait` — this env var always wins over that longer default too) |
+| `TRAWL_TIMEOUT`       | Override the per-request fetch timeout in milliseconds (default `30000`; `300000` for `create`/`run`/`data --fresh`/`trigger --wait` — this env var always wins over that longer default too) |
 | `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):
 
 ```bash
-TRAWL_API_URL=https://dev.trawl.me TRAWL_TOKEN=<jwt> trawl scraps list --json
+TRAWL_API_URL=https://dev.trawl.me TRAWL_TOKEN=<jwt> trawl list --json
 ```
 
 ## API documentation

package/dist/commands/create.d.ts

@@ -0,0 +1,41 @@
+import { Command } from 'commander';
+/**
+ * `POST /api/ai/wizard` response contract (#114, trawl_node —
+ * ai.wizard.service.js#runWizard, shipped S1, contract LOCKED). The wizard
+ * chains, entirely server-side: AI code generation -> scrap creation ->
+ * the FIRST run (ScrapsService.load) -> auto-fix on failure (autoFix
+ * defaults true unless `--no-autofix` maps to `autoFix:false`).
+ *
+ *  - `success` is an HONEST outcome of that first run, not "did the HTTP
+ *    call succeed" — a failed first run is still a 200 response (the scrap
+ *    itself was created either way; auto-fix, when enabled, retries in the
+ *    background). Callers must branch on `success`, never assume 2xx means
+ *    "the scrap works".
+ *  - `scrap` is the full created Scrap object (present whenever creation got
+ *    far enough to persist it — a hard failure before that point surfaces as
+ *    a real HTTP error instead, handled by the shared error path).
+ *  - `historyId` is best-effort (a failed server-side lookup leaves it
+ *    `null`, never breaks the response) — it points at the first run just
+ *    executed.
+ */
+export interface WizardResponse {
+    success: boolean;
+    scrap?: {
+        _id: string;
+        title: string;
+        /**
+         * Cron expression the wizard schedules this scrap on. As of #114/S1
+         * (trawl_node ai.wizard.service.js#runWizard's `scrapBody`) this is
+         * hardcoded server-side to a DAILY run — `'0 7 * * *'` / `cronTimezone:
+         * 'UTC'` — unconditionally, regardless of `--prompt`/`--no-autofix`.
+         * Present on the scrap object returned here (the wizard controller
+         * passes the created scrap straight through, no stripping) — change or
+         * disable it with `trawl scraps update <id> --cron <expr>` / `--no-cron`.
+         */
+        cron?: string | null;
+        cronTimezone?: string;
+        [key: string]: unknown;
+    };
+    historyId?: string | null;
+}
+export declare const create: Command;

package/dist/commands/create.js

@@ -0,0 +1,146 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { oraPromise } from 'ora';
+import { api, LONG_RUN_TIMEOUT_MS, NetworkError } from '../lib/api.js';
+import { json } from '../lib/format.js';
+import { requireUrl, requireString } from '../lib/validate.js';
+/** Best-effort, honest first-run summary — never claims a background retry
+ * happened when auto-fix was disabled for this call, and never claims a
+ * scrap was persisted when the response carries none (#114-F3 — a hard
+ * failure before persistence still comes back as `success:false` with no
+ * `scrap` at all; claiming "auto-fix retrying in the background" then would
+ * be fabricated — there is nothing to retry). */
+function firstRunLabel(data, autoFixEnabled) {
+    if (data.success)
+        return 'succeeded';
+    if (!data.scrap)
+        return 'failed (no scrap was persisted)';
+    if (autoFixEnabled)
+        return 'failed (auto-fix retrying in the background)';
+    return 'failed';
+}
+/** Best-effort human description of a daily cron (`M H * * *`) — the only
+ * shape the wizard's server-side default currently produces. Falls back to
+ * printing the raw expression for anything else rather than guessing at a
+ * schedule the CLI can't actually parse. */
+function describeCron(cron) {
+    const match = /^(\d{1,2})\s+(\d{1,2})\s+\*\s+\*\s+\*$/.exec(cron.trim());
+    if (!match)
+        return cron;
+    const [, min, hour] = match;
+    return `daily ${hour.padStart(2, '0')}:${min.padStart(2, '0')}`;
+}
+/**
+ * #114-F2 — a wizard-created scrap runs on a DAILY cron by default
+ * server-side; surface that up front rather than leaving it to be
+ * discovered later as an unexpected recurring quota charge. Reads the real
+ * `cron`/`cronTimezone` field off the response scrap when present; falls
+ * back to the known wizard default wording ONLY when the field is missing
+ * from the response (an older server, or a future rename) — never invents a
+ * schedule value that might not match what the server actually applied.
+ * Returns null when there's no scrap to schedule at all.
+ */
+function scheduleLabel(scrap) {
+    if (!scrap)
+        return null;
+    if (typeof scrap.cron === 'string' && scrap.cron.trim() !== '') {
+        const tz = typeof scrap.cronTimezone === 'string' && scrap.cronTimezone ? scrap.cronTimezone : 'UTC';
+        return `${describeCron(scrap.cron)} ${tz} (cron ${scrap.cron})`;
+    }
+    return 'scheduled daily by default';
+}
+export const create = new Command('create')
+    .description('Create a persistent, self-healing scrap from a URL + a goal (AI-generated)')
+    .argument('<url>', 'Target public URL (http/https)')
+    .requiredOption('--prompt <goal>', 'What to extract/scrape, in plain language')
+    .option('--no-autofix', 'Disable AI auto-fix on first-run failure (default: on)')
+    .option('--json', 'Output the raw API payload')
+    .action(async (rawUrl, opts) => {
+    // Fast, local usage-errors (exit 2) — never a round-trip to the server
+    // for something we can already tell is bad. Same fail-fast pattern the
+    // former `fetch` command used for its URL argument.
+    const url = requireUrl(rawUrl, 'url');
+    const goal = requireString(opts.prompt, '--prompt');
+    const body = {
+        url,
+        goal,
+        ...(opts.autofix === false && { autoFix: false }),
+    };
+    // #91/#106-F1 long-run pattern — the wizard runs AI generation + scrap
+    // creation + a real FIRST run (+ autofix retries) entirely server-side,
+    // legitimately 30-250s+. The 30s DEFAULT_TIMEOUT_MS would abort it
+    // mid-flight and fabricate a NetworkError timeout for a request that was
+    // always going to succeed.
+    const call = () => api.post('/api/ai/wizard', body, { timeoutMs: LONG_RUN_TIMEOUT_MS });
+    // #106-F2 pattern carried over from `fetch` — under --json stdout must
+    // be provably pure: no spinner channel at all. Only the human path gets
+    // the ora progress indicator; --json calls the API directly.
+    let data;
+    if (opts.json) {
+        data = await call();
+    }
+    else {
+        try {
+            data = await oraPromise(call, {
+                text: `Creating a scrap from ${url}…`,
+                // No verdict symbol here (#106-F3) — ora's success only means "the
+                // HTTP call didn't throw", not "the first run succeeded". The real
+                // outcome renders below via the icon + the First run: line.
+                successText: 'Request complete',
+            });
+        }
+        catch (err) {
+            // #114-F1 — a client-side timeout (NetworkError, "timed out after
+            // …ms" per api.ts's safeFetch) does NOT mean the wizard failed
+            // server-side: the scrap creation + first run keep going on the
+            // server after the CLI gives up waiting, so the scrap may already
+            // exist (or land moments later). Warn BEFORE rethrowing so a retry
+            // isn't the first instinct — a blind retry creates a duplicate scrap
+            // and burns AI-generation quota a second time for the same goal.
+            // Only a NetworkError whose message identifies it as the timeout
+            // branch qualifies — a DNS/connection-refused NetworkError never
+            // reached the server at all, so there's nothing to warn about here.
+            if (err instanceof NetworkError && /timed out/i.test(err.message)) {
+                console.error(chalk.yellow('⚠ The request timed out client-side, but the scrap may STILL have been created server-side — run `trawl list` before retrying (a retry creates a DUPLICATE scrap + burns quota).'));
+            }
+            // Rethrow unchanged so index.ts's classifyError/exit-code taxonomy
+            // stays intact (this stays a NetworkError -> exit 5, same as before).
+            throw err;
+        }
+    }
+    if (opts.json) {
+        json(data);
+    }
+    else {
+        const scrapId = data.scrap?._id;
+        const title = data.scrap?.title ?? url;
+        const autoFixEnabled = opts.autofix !== false;
+        const schedule = scheduleLabel(data.scrap);
+        console.log(`${data.success ? chalk.green('✓') : chalk.red('✗')} ${chalk.bold(title)}`);
+        console.log(chalk.dim(`  Scrap ID:   `) + (scrapId ?? '—'));
+        if (data.historyId)
+            console.log(chalk.dim(`  History ID: `) + data.historyId);
+        console.log(chalk.dim(`  First run:  `) + firstRunLabel(data, autoFixEnabled));
+        if (schedule)
+            console.log(chalk.dim(`  Schedule:   `) + schedule);
+        if (scrapId)
+            console.log(chalk.dim(`  Next step:  `) + `trawl get ${scrapId}`);
+        // #114-F3 — only claim a background retry is happening when a scrap
+        // actually exists to retry (never fabricate progress that isn't real);
+        // `firstRunLabel` above already covers the !scrap / autofix-disabled
+        // wording, this adds the actionable poll target on top.
+        if (!data.success && data.scrap && autoFixEnabled) {
+            const pollTarget = data.historyId
+                ? `\`trawl data ${scrapId}\` or \`trawl run-info ${data.historyId}\``
+                : `\`trawl data ${scrapId}\``;
+            console.log(chalk.yellow(`  Note:       `) +
+                `Auto-fix is retrying in the background — do NOT re-run create; poll ${pollTarget}.`);
+        }
+    }
+    // Honest exit code alongside the honest payload — a --json caller gets
+    // the raw body regardless (never wrapped/altered), but a script checking
+    // the exit code alone must be able to tell "first run failed" from "ran
+    // fine" without parsing. Same contract the former `fetch` command used.
+    if (!data.success)
+        process.exitCode = 1;
+});

package/dist/commands/scraps.d.ts

@@ -1,4 +1,27 @@
 import { Command } from 'commander';
+/**
+ * #108 — surface reorg. `run`/`list`/`get`/`data`/`history`/`run-info`/
+ * `trigger` are promoted to top-level verbs (see index.ts's `createProgram`)
+ * alongside `create`/`whoami`/`ping` (#114 — `create` replaced `fetch` in
+ * that group). Each is built by an exported
+ * `attachXCommand(parent, attachOpts)` factory instead of a fixed
+ * `scraps.command(...)` chain, so it can be attached TWICE with a single
+ * source-of-truth definition: once to `program` (the new canonical
+ * top-level path) and once more, hidden, right back onto `scraps` — so every
+ * pre-#108 `trawl scraps <verb>` invocation keeps resolving unchanged
+ * (`{ hidden: true }` only affects help visibility, never resolution).
+ *
+ * Future-drift guard: ALL `.option()`/`.argument()`/`.action()` wiring for a
+ * promoted verb MUST live INSIDE its `attachXCommand` factory body, never
+ * bolted onto one of its two call sites (index.ts's `createProgram` for the
+ * top-level attach, this file's own `attachXCommand(scraps, { hidden: true
+ * })` call for the legacy one). That's the only thing keeping `trawl run
+ * <id>` and `trawl scraps run <id>` identical — a call-site-only tweak to
+ * one attachment would silently diverge the two.
+ */
+type AttachOptions = {
+    hidden?: boolean;
+};
 export declare const scraps: Command;
 /** The top-of-history snapshot pollRunProgress needs to identify which run
  * it's watching — see captureBeforeRunState.
@@ -115,4 +138,11 @@ export declare function pollRunProgress(id: string, before: BeforeRunState | und
     timeoutMs?: number;
     json?: boolean;
 }): Promise<void>;
+export declare function attachListCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachGetCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachRunCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachDataCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachHistoryCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachRunInfoCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachTriggerCommand(parent: Command, attachOpts?: AttachOptions): Command;
 export {};