@lariocpt/crust-mongo 0.0.0-stage → 0.3.6

package/skills/crust-logs/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: crust-logs
+description: Search a live log stream with crust's `logs` session — it holds a tail/procs/shell source open, keeps a ring buffer, and re-runs every typed pipeline fragment over the buffered past and then the live stream; `json on` parses NDJSON at query time, `search` counts the buffer instantly, `buffer N` resizes without restarting. Use when tailing dev services or containers, when a grep workflow keeps losing history, or when you want to widen a filter over logs you already saw.
+---
+
+# crust logs
+
+## What it is
+
+`logs <source>` keeps the source open and a ring buffer (default 10,000 items)
+behind it, so one query can look at the PAST you already streamed and stay
+attached to the live firehose. Every line you type at `logs>` is an ordinary
+crust pipeline fragment — the whole shell grammar is the query language.
+
+```crust
+logs tail -n 0 -F app.log
+logs procs({web: "bun run dev", api: "bun api.ts"})
+logs docker logs -f my-container
+logs --buffer 50000 tail -F big.log
+```
+
+Boot prints what it holds: `logs: tail -n 0 -F app.log — buffering last 10000
+items (`help` for commands, `exit` to leave)`.
+
+## A fragment runs TWICE
+
+Once over the buffer snapshot, then over the live stream until Ctrl-C, past a
+`-- live --` marker. So side effects fire twice: append with `>>`, never `>`,
+and a `POST` fragment re-sends buffered matches.
+
+- **Ctrl-C once** ends the live view *gracefully* — the stream finishes, so
+  terminal stages flush (a query ending in `stats` prints its summary right
+  then; `wc -l` prints its count). **Ctrl-C twice** hard-cancels a stuck query.
+  The session survives both.
+- A query that fails on the retro pass prints its error and re-prompts. Errors
+  never kill the session or the held source.
+
+## Session commands
+
+| command | what it does |
+| --- | --- |
+| `search <text>` | fixed substring over the BUFFER only — matches highlighted, and a count that always prints, zero included (`search: 5 matching item(s) of 36 buffered`). No live view, no Ctrl-C. For regex/case-folding/live, run a `grep` query |
+| `json on` / `json off` | parse string items at QUERY time (see below) |
+| `buffer` / `buffer N` | report usage (`buffer: 57/10000 items (pushed 57, evicted 0)`) or resize live, newest kept — widen a too-small window without losing the held source |
+| `clear` | empty the buffer (`buffer cleared`) |
+| `help` | the command list, including the double-run note |
+| `exit` / Ctrl-D | tear the source down and leave (procs get SIGTERM→SIGKILL) |
+
+Query errors print and re-prompt; up-arrow recalls earlier queries.
+
+## json on — and the silent zero it prevents
+
+With `json off` (the default) items are the raw strings. A lambda that reads
+fields therefore matches NOTHING, quietly: 50 buffered NDJSON lines, and
+`filter (e => e.level >= 30) | wc -l` reported `0`. `json on` fixes that at
+query time: a string item parsing to a JSON **object or array** reaches your
+lambdas parsed; plain text, strings that parse to primitives (`"42"` stays a
+string), and non-string items flow through unchanged and are counted out loud.
+The ring stores raw items, so `json off` is a lossless revert.
+
+When the buffer looks like NDJSON the session prints, once, on your first
+*pipeline fragment* (not on `help` or `search`):
+
+```
+hint: buffer looks like NDJSON — `json on` parses object lines at query time (`json off` reverts)
+```
+
+It never auto-enables — changing the item type under a lambda you already typed
+would be a false picture.
+
+## Item types by source
+
+- `tail`/shell sources: plain **strings**.
+- `procs({...})`: `{proc, stream, line}` **objects** — the session tells you so
+  at boot (`logs: items are {proc, stream, line} objects — try (l => l.line) or
+  filter (l => l.proc === "web")`). `(l => l.line)` extracts text,
+  `filter (l => l.proc === "web")` selects one process, and `search` still works
+  (it matches each item's rendered form).
+- Pretty-printing is just another stage: `grep api_request | pino-pretty
+  --colorize --singleLine` (`--colorize` forces ANSI through the pipe; local
+  `node_modules/.bin` is on PATH). Normalize `procs` objects first.
+
+## Traps
+
+- `logs` is interactive-only. No tty → exit 2 and a pointer:
+  `logs: interactive session needs a tty — for piped data use `cmd | crust -c 'stdin | …'``.
+  For piped data there is no session — build the pipeline directly.
+- The `logs` line owns its line: `logs tail -F app.log | grep ERROR` refuses
+  (`logs is a crust builtin — it runs in-process, so sh cannot run it`) rather
+  than letting sh report `command not found`. Type the filter at `logs>`.
+- A gate query (`count 1`, `expect 200`) runs against the BUFFER first — a
+  retro failure prints before a single live item arrives. That is the honest
+  order, but it means `logs`+gate reflects history, not just what follows.
+- `search` is buffer-only and fixed-substring: it never sees live items and
+  never interprets regex.
+- Ctrl-C at an idle `logs>` prompt is nothing: it prints `^C` and re-prompts,
+  the source keeps running. `exit` (or Ctrl-D) is the teardown — verified with a
+  `procs` source, including after a Ctrl-C: the group gets SIGTERM→SIGKILL and
+  no `sleep` survives the session.

package/skills/crust-mcp/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: crust-mcp
+description: Drive crust directly from an MCP-capable agent (OpenCode, Claude Code, Codex, Cursor) instead of a shell — `crust mcp` exposes every capability as a first-class tool: run_line, check_line, test_fixture/test_pipes, gen_fixtures, load_run, verify_web_links, plus lifecycle mock servers, supervised procs, and buffered log sessions that stay open across calls. Use when configuring crust as an MCP server, choosing which crust_* tool fits a task, or reasoning about what persists between tool calls and what does not.
+---
+
+# crust over MCP
+
+`crust mcp` speaks JSON-RPC 2.0 over stdio — one message per line. It is a
+whole-process MODE, not a REPL builtin: the MCP host owns stdin and stdout.
+
+## Install & configure
+
+`crust` must be on PATH (either channel works — same binary):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lariocpt/crust/main/install.sh | bash
+# or: npm i -g @lariocpt/crust
+```
+
+Then register it with the agent host — e.g. OpenCode / Claude Code style:
+
+```json
+{ "mcpServers": { "crust": { "command": "crust", "args": ["mcp"] } } }
+```
+
+VS Code uses a DIFFERENT schema in `.vscode/mcp.json` (workspace) or the
+user-level MCP settings — the `mcpServers` shape above silently fails there
+("command is required" or the server just never appears):
+
+```json
+{
+  "servers": {
+    "crust": { "type": "stdio", "command": "/home/user/.local/bin/crust", "args": ["mcp"] }
+  }
+}
+```
+
+Two traps, both verified: (1) `"command"` must be the ABSOLUTE path — a
+GUI-launched VS Code does not inherit the shell's PATH, so bare `"crust"`
+dies `spawn crust ENOENT` if the launcher lives outside the default
+lookup dirs; (2) VS Code's MCP support ships inside the Chat/Copilot Chat
+extension — Code - OSS / VSCodium has no MCP host without an extension
+(Cline, Roo Code or Continue each carry their own MCP settings).
+
+Grammar lands automatically: the one-shot tools pass line/fixture text to a
+fresh crust child untouched, so anything the lexer accepts (`--redirect`,
+new builtins) is an MCP tool call the moment the installed binary has it —
+no MCP-side change per feature.
+
+Verify by hand — the transport is just lines on stdin:
+
+```bash
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' | crust mcp
+```
+
+## Two execution planes — what persists
+
+| Plane | Tools | State |
+| --- | --- | --- |
+| **One-shot** | `crust_run_line`, `crust_check_line`, `crust_test_fixture`, `crust_test_pipes`, `crust_gen_fixtures`, `crust_verify_web_links`, `crust_load_run` | a fresh crust CHILD per call — `cwd`/`env` apply per call and NEVER carry over; pass them explicitly |
+| **Lifecycle** | `crust_mock_server_start/stop/list/violations`, `crust_procs_start/stop`, `crust_logs_open/query/close` | held IN the server across calls; every held job dies when the server exits |
+
+`crust_run_line` runs ordinary crust grammar — one line, `|`-stages, lambdas:
+
+```crust
+range(1,5) | (n => n * n) | stats
+```
+
+## Tool classes and teardown tiers
+
+The `initialize` handshake carries this taxonomy in `instructions` (0.3.6):
+
+- **Static check** — `crust_check_line`: parses, runs nothing.
+- **Execution** — `crust_run_line` and the test/gen tools: arbitrary stages,
+  real side effects. Target approval, credentials, writes and cleanup stay
+  the caller's responsibility.
+- **Network/load generation** — `crust_load_run`, `crust_verify_web_links`:
+  bounded generation, approved non-production targets only.
+- **Long-lived resources** — mock server, procs, log sessions: held by the
+  server process, die when it exits.
+
+Teardown has three tiers and no tool crosses them: **local processes** are
+killed whole (process group, grandchildren included); **mock sessions** close
+(port released — `--state` files/DBs are application data and stay on disk);
+**application data** is never touched — a container, row or queue a proc
+created remotely survives its local teardown, releasing it is your job.
+
+Transport contract: stdio JSON-RPC, one frame per line; one-shot tools spawn
+a fresh crust child per call (`cwd`/`env` per call, nothing persists). A
+refusal whose error string never appears in crust's own output (an
+"unavailable tool" style host error) never reached the server — debug the
+host's spawn command, not crust.
+
+## Honest failure — never a false pass over MCP
+
+A nonzero child exit, a killed timeout, a failed `assert`, a mock validation
+error is an **`isError` result** carrying the verbatim exit code and output.
+Zero matches is answered with an explicit "zero items", never silence. Trust
+`isError`; the text is evidence, not a verdict.
+
+## Picking the right tool
+
+- Validate generated crust first — `crust_check_line` parses without running
+  (files and ports don't need to exist).
+- `crust_procs_start` supervises dev services (env/after/ready/restart per
+  proc). Its stream is queried through `crust_logs_query` — items are
+  `{proc, stream, line}` objects. Gate readiness in a follow-up:
+
+```crust
+wait :3000/health
+```
+
+- `crust_logs_open` holds a tail/shell/`procs({…})` source with a ring buffer;
+  `crust_logs_query` runs a pipeline fragment over the buffered past, then
+  live for `live_ms` — `json: true` parses NDJSON items before the fragment:
+
+```crust
+filter (l => l.proc === "api") | (l => l.line) | grep -i timeout
+```
+
+- `crust_mock_server_start` defaults `port: 0` (OS-assigned) — always take
+  the returned `url`. `proxy: "<upstream>"` turns it into a conformance audit;
+  read findings with `crust_mock_server_violations`.
+- `crust_load_run` composes the documented pipeline (`load … | parallel … |
+  … | stats | assert`); gates go in `assert` — one predicate, or an array of
+  them (0.3.6), one assert stage per gate. An `expect` inside `target` runs BEFORE
+  stats and suppresses the summary when it fails; a post-stats `assert`
+  failure is `isError` with the stats still included. A run that measured
+  nothing is refused (`empty`), never a green gate.
+
+## Limits, stated
+
+- One tool call runs at a time (the interrupt bus is process-global).
+- Output is tail-capped per stream and truncation is always announced.
+- `crust_procs_stop` reports "teardown still in flight past 10s" honestly
+  when a child ignores SIGTERM — crust kills it on server exit.

package/skills/crust-mock-server/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: crust-mock-server
+description: Mock an API from an OpenAPI spec with crust mock-server — example-first responses, stateful CRUD (in-memory or persisted to sqlite/postgres with --state, seedable with --seed), request validation with 422s, and validation-proxy mode that checks a REAL API's spec conformance. Use for mocking backends, frontend dev without a server, contract/conformance testing, or checking whether an API matches its openapi.json.
+---
+
+# crust mock-server
+
+One builtin, four modes, all driven by an OpenAPI 3.x spec (Swagger 2.0
+auto-converts; URL or local json/yaml):
+
+```
+mock-server ./openapi.json -p4000                      # example-first mock
+mock-server ./openapi.json -p4000 --stateful           # + in-memory CRUD
+mock-server ./openapi.json -p4000 --state ./m.sqlite   # + persistent CRUD (implies --stateful)
+mock-server ./openapi.json -p4000 --validate           # + reject bad requests (422)
+mock-server ./openapi.json -p4747 --proxy http://localhost:3001   # conformance proxy
+```
+
+Builtins can't be piped — run the server in one terminal (or `procs()`), and
+pipe against it from another line.
+
+## Mock + stateful
+
+Responses prefer the spec's `example`/`examples`, then synthesize from the
+schema (enum[0], format-aware strings, nested objects). Status pick:
+200 → 201 → other 2xx → `default`. Unknown path → 404; known path, wrong
+method → 405.
+
+`--stateful` pairs `/things` with `/things/{id}` automatically: POST stores
+(id from body or a UUID), GET lists what you stored (shaped to the spec's
+envelope), GET/{id} → 404 for unknown ids, PUT/PATCH shallow-merge, DELETE
+→ 204. Untouched collections keep serving spec examples. Default is
+per-process memory; `--state` persists (below).
+
+**Entity envelopes round-trip.** If the POST's 201 example wraps the entity
+(`{"thing": {"id": …}}` — one object-valued prop, no top-level id), the mock
+detects it: responses are wrapped with the real stored entity inside, request
+bodies wrapped the same way (per the POST's request example) are unwrapped,
+and the store keeps the BARE entity. So capturing a wrapped id works against
+the mock:
+
+```crust
+{"thing": {"name": "x"}} | POST :4000/api/things | assert (r => r.status === 201) | (r => r.json()) | capture TID (t => t.thing.id)
+GET :4000/api/things/$TID | expect 200
+```
+
+Flat specs capture `t.id` exactly as before. Ambiguous shapes (two
+object-valued props, a top-level `id`) stay flat — deterministic, never
+guessed.
+
+## Persistent state (`--state`) and seeding (`--seed`)
+
+Both imply `--stateful` and exclude `--proxy`.
+
+- `--state <path|url>` — bare path or `sqlite://` file, or
+  `postgres://`/`postgresql://` URL (other schemes exit 2). Survives
+  restarts; shared cross-process (reads hit the DB every request, writes are
+  single-statement upserts, last write wins). Boot line shows
+  `(state: sqlite)` / `(state: postgres)`.
+- `--seed <file.json>` — `{ "/api/things": [ {…}, … ] }`; items without an
+  `id` get a uuid. EMPTY collections only: re-booting over a persistent
+  store never duplicates or clobbers. Unknown collection keys warn and boot
+  anyway; invalid file exits 1. Boot line shows `(seeded N)`.
+
+Table contract (created idempotently; assert on it from pipelines):
+`crust_mock_state(collection TEXT, id TEXT, doc TEXT|JSONB, updated_at, PRIMARY KEY (collection, id))`
+where `doc` is the BARE entity as JSON. With the `sql` builtin
+(`DATABASE_URL=sqlite://./m.sqlite` works — Bun.SQL speaks sqlite URLs;
+rows stream one item each):
+
+```crust
+sql "SELECT json_extract(doc, '$.name') AS name FROM crust_mock_state WHERE collection = '/api/things' AND id = '$TID'" | assert (r => r.name === "x")
+```
+
+(postgres: `doc->>'name'` instead of `json_extract`.)
+
+## Failure injection (`PUT /__crust/override`) — mock mode only
+
+Arm the mock to fail when the APP owns the request (no test-controlled
+header possible): `PUT /__crust/override` with `{method, path, status,
+body?, contentType?, times?, match?: {bodyContains}}`. Under `-j/--threads`
+ALWAYS scope with `match.bodyContains` (a unique value the fixture put in
+its own request body) + `times: 1` — unscoped overrides race sibling
+fixtures. An armed override beats --validate/--stateful; `GET` lists,
+`DELETE` clears. Never consulted in --proxy mode.
+
+## Request validation (`--validate`)
+
+Spec-violating requests get **422** (not the API's own 400 — deliberately
+distinguishable) with header `x-crust-validation: request` and body
+`{error, violations: [{pointer, rule, message, expected?, received?, location}]}`.
+Checks: JSON body (type/required/enum/format/pattern/lengths/ranges,
+anyOf/oneOf/allOf), path + query params (coerced by declared type). The
+governing rule: a schema the validator can't judge PASSES — it never
+invents a violation (notably `additionalProperties: false` is not
+enforced unless you add `--strict`). Composes with `--stateful`: an
+invalid POST creates nothing.
+
+`--strict` (implies `--validate`; composes with `--proxy`, both
+directions) enforces a LITERAL `additionalProperties: false` at plain
+object nodes only: allOf-merged objects, nodes with combinator siblings,
+and patternProperties stay exempt — so it still never invents a
+violation for spec composition idioms. Inside anyOf/oneOf branches an
+extra key just fails that branch's selection.
+
+## Validation proxy (`--proxy <upstream>`) — spec-conformance testing
+
+Forwards every request to the real upstream, returns the response
+UNTOUCHED, and records spec violations out-of-band in BOTH directions:
+request violations, undocumented response statuses, undocumented
+content-types, response-schema mismatches (only where the spec has response
+schemas), and `undocumented-operation` for paths the spec doesn't know
+(still forwarded — a browsing frontend keeps working). Upstream down → 502,
+not a violation. Mutually exclusive with `--stateful`.
+
+The findings are pipeable — this is the conformance gate:
+
+```crust
+GET :4747/__crust/violations | (r => r.json()) | (v => v.violations.filter(x => x.direction === "response")) | assert (a => a.length === 0)
+```
+
+The `(r => r.json())` stage is not optional: an HTTP stage hands you the
+response object, so reading `.violations` off it straight away is `undefined`
+and the gate dies with `crust: undefined is not an object (evaluating 'v.violations.filter')` — which looks like a broken assert rather than a missing decode.
+
+`DELETE /__crust/violations` clears between runs; `--report file.ndjson`
+appends every violation as NDJSON for CI artifacts (requires `--proxy`).
+
+Workflow: point your existing test suite's base URL at the proxy port, run
+the suite, then assert zero response-direction violations. (Request-direction
+violations are EXPECTED if your suite includes negative cases — filter by
+direction.)
+
+## Exit codes
+
+0 clean shutdown (SIGINT/SIGTERM) · 1 runtime failure (spec load, bad seed
+file) · 2 bad args (including `--proxy` + `--stateful`/`--state`/`--seed`,
+an unsupported `--state` scheme, or `--report` without `--proxy`).

package/skills/crust-pipelines/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: crust-pipelines
+description: Compose crust pipelines — sources (range, glob, read, tail, GET, load, procs, sql), transforms (TS lambdas, filter, HTTP verbs, parallel), assertions (expect, assert), and request chaining with capture. Use when writing or debugging crust one-liners, `crust -c` scripts, .crust script files, or .pipes lines that mix HTTP, SQL, and processes.
+---
+
+# crust pipelines
+
+crust is a Bun-powered pipeline runner where every command is a typed stream
+(`Pipeline<T>`). Stages compose under `|`. Plain shell still works — a line
+whose stages are all ordinary commands is handed to `sh -c` untouched.
+
+Choose the lightest native stage that preserves correctness, observability,
+and safety — not merely the shortest syntax (full statement: the
+crust-api-testing skill's shared principle).
+
+## How a stage is classified (first token decides)
+
+| You type | You get |
+|---|---|
+| `range(0, 9)` | numbers 0..9 inclusive, one item each |
+| `**/*.ts` | glob source — file paths |
+| `lines **/*.log` | one item per LINE across every match (sorted; zero matches = error). Use this for log mining — `read` gives whole files. Bare `lines` mid-pipeline splits upstream items |
+| `read fixtures/*.json` | whole-file contents, one item per file (sorted; zero matches = error) — the request-body form: `read fixtures/*.json \| POST …` |
+| `tail -F app.log` | native tail source (`-n N`, `-F` follow); the `-n N` cut is a bounded backward read, safe on huge files |
+| `stdin` (alias `-`) | piped-stdin source, one item per line — `docker logs -f X \| crust -c 'stdin \| …'`. Source position only. Bare `cmd \| crust` treats stdin as a SCRIPT, so data pipes need `-c` |
+| `grep ERROR` mid-pipeline | native line-buffered grep (`-i`/`-v`/`-F`, ONE pattern; per-line even on multi-line items) — follow streams don't stall on grep's 4KB pipe buffer. Combined/unknown flags, two positionals, any `$`, or GNU/JS-divergent regex bits (`\`, `[[:`, `{,`, `(?`) = exact system grep via sh; first-stage grep = file grep via sh |
+| `load 30s 100/s` | paced load ticks (see the crust-load-testing skill) |
+| `{"name": "x"}` | JSON-literal source — ONE parsed item (the request body). Invalid JSON is a hard error |
+| `GET :3000/path` | HTTP. First stage: one `Response`. Mid-pipeline: per-item timed `{status, ms, url}` |
+| `POST/PUT/PATCH/DELETE url` | per-item request; upstream item = body (objects auto-JSON) |
+| `GET url --timeout 2s` | per-request timeout on any http stage (`ms`/`s`/`m`); timed paths yield `{status: 0, timedOut: true}`, plain verbs fail the pipeline; unknown `--flags` are errors |
+| `GET url --redirect error\|manual\|follow` | 3xx handling (fetch's `redirect` init): `error` refuses a redirect — plain verbs fail the line, timed paths yield `{status: 0, redirectRefused: true}`; `manual` yields the 3xx so `expect 301` asserts it; `follow` is the default. Fixtures carry it as `input.redirect` |
+| `(x => x * 2)` | TypeScript lambda, per item, async ok — MAPS, never drops (falsy results are emitted as-is) |
+| `filter (l => l.ok)` | keeps items whose predicate is truthy; falsy (`0`, `""`, `null`…) drop; async ok; empty result passes |
+| `assert (r => r.ok)` | falsy FAILS the pipeline; empty upstream also fails |
+| `capture NAME (r => r.id)` | write value to `process.env.NAME` for later lines |
+| `expect 201` / `expect 2xx` | status assertion, counts mismatches, fails at drain |
+| `stats [--every N] [--out f.json]` | summary: count/rps/status histogram/p50/p95/p99 + failure tallies `timedOut`/`redirectRefused` (records, not exits — gate them) |
+| `parallel N` | modifier: fan-out for the NEXT stage (http, lambda, or fn — anything else errors) |
+| `sql "SELECT …" ?-params` | registered fn — `?` is the bind placeholder; rows stream one item each (needs `$DATABASE_URL`) |
+| `range(1,1) \| sql "… WHERE id = ?"` | mid-pipeline, the upstream item BINDS as the first parameter when the line declares none (an explicit param wins); rows stream one item each in both positions |
+| anything else | plain shell via `sh -c` |
+
+`:3000/path` expands to `http://localhost:3000/path` everywhere.
+
+## HTTP result shapes — same syntax, different payloads
+
+Similar HTTP syntax does NOT guarantee identical result shapes. Know which
+shape a stage receives before reaching for `.json()` or gating results
+(verified against crust v0.3.5):
+
+| Context | What the stage emits | Authoring implication |
+|---|---|---|
+| First-stage ordinary verb (`GET :3000/x`) | a `Response` | body parsing is available: `(r => r.json())` |
+| Mid-pipeline ordinary verb, non-GET (per-item, untimed) | a `Response` per item | same — bodies still parseable |
+| Timed per-item path (mid-pipeline `GET` — with or without `parallel` — or `parallel N \| <any other verb>`) | `{status, ms, url}` records; **bodies drained**; network errors are `status: 0` records; `--timeout`/`--redirect error` outcomes are `{status: 0, timedOut/redirectRefused: true}` records | `.json()` does NOT exist on these; gate status and the failure tallies explicitly |
+
+Canonical, version-pinned table: https://lariocpt.github.io/crust-website/docs/http-result-shapes/.
+
+## Completion is not success — three separate outcomes
+
+1. **Execution completed** — the pipeline ran without a fatal stage error (exit 0).
+2. **Request correctness passed** — explicit gates (`expect`, `assert`) accepted the request outcomes.
+3. **Performance passed** — explicit latency/throughput thresholds passed.
+
+`stats` reports measurements; it is not itself a success gate. In timed/load
+paths, timeouts, network failures, and redirect refusals are per-item
+RECORDS (`status: 0` + a tally field), not exits — exit 0 alone is never
+evidence that requests succeeded. Use an explicit expected-status gate
+(`expect 200`/`expect 2xx`), and where stats is in play also check
+`s.timedOut === 0` / `s.redirectRefused === 0`.
+
+## Env expansion — parse time, opt-in per position
+
+`$VAR`/`${VAR}` expand from `process.env` in: URLs, whole `-H` header
+strings, JSON literals, `stats --out` paths, and registered-fn args. They do
+NOT expand inside lambda/`assert`/`capture` bodies (those are JS — use
+`process.env.VAR`) or shell stages (sh does its own). In a script, the
+**positional arguments** expand in those same positions — so `$1` inside a
+`sql "…"` string is the script's `$1`, not a SQL bind: the bound-parameter
+placeholder is `?`, and the trailing quoted args DO env-expand:
+`sql "… WHERE id = ?" "$MY_ID"`.
+
+`$(…)` command substitution lives in shell stages only: sh expands it once
+at the head of a shell stage, and a `$` anywhere in a mid-pipeline stage
+demotes it to sh, so `range(1,3) | grep $(echo 1)` still works. A `$(…)` in
+a *crust* stage (a URL, a lambda, an argument) is **refused before anything
+runs** — it used to build data from the literal text (`getaddrinfo ENOTFOUND
+$(echo`) — so the named route is capture first: `date +%s | capture TS`,
+then `GET :3000/?t=$TS`.
+
+Inside a parenthesized lambda/`assert`/`capture` body, anything goes: the
+tokenizer tracks paren depth and quotes, so literal `|`, `??`, single/double
+quotes, and backticks (template literals) are all safe. In double-quoted
+strings and JSON literals, `\"` escapes work.
+
+## Request chaining with capture
+
+Each line parses right before it runs, so a capture on one line feeds `$VAR`
+on every later line — the chaining contract for REPL, `-c` scripts, and
+`.pipes` files:
+
+```crust
+{"name": "Court"} | POST $BASE/api/buildings -H "authorization: Bearer $TOKEN" | assert (r => r.status === 201) | (r => r.json()) | capture BID (b => b.building.id)
+GET $BASE/api/buildings/$BID -H "authorization: Bearer $TOKEN" | expect 200
+```
+
+- Last item wins; omit the lambda to capture the item itself (objects are
+  JSON-stringified).
+- A nullish captured value or empty upstream fails IMMEDIATELY — a typo'd
+  accessor dies on the capture line, not three lines later as a baffling
+  `""` expansion.
+- Don't capture into `TOKEN`, `BASE`, or `PATH` unless you mean to overwrite
+  them.
+- Capture is also the named route for command output you want downstream:
+  a `$(…)` in a crust stage is refused, so `date +%s | capture TS` followed
+  by `GET :3000/?t=$TS` is the round trip (sh's trailing newline is trimmed
+  off the captured value).
+
+## Verified one-liner patterns
+
+```crust
+# log mining — `lines` yields one item per LINE, which is what filter wants
+# (`read` yields whole FILES, so a filter would test the entire file at once)
+lines **/*.log | grep ERROR | filter (l => !l.includes('healthcheck')) | wc -l
+
+# lambda + shell mixing — items cross as lines (objects as JSON)
+range(1, 5) | (n => n * n) | sort -rn
+
+# HTTP fixture in one line: body | request | status | parsed-body assert
+{"name": "x"} | POST :3000/users | assert (r => r.status === 201) | (r => r.json()) | assert (u => u.id > 0)
+
+# DB verification — rows stream, assert sees each row object
+sql "SELECT count(*)::int AS c FROM users WHERE email = ?" "a@b.c" | assert (r => r.c === 1)
+
+# fan out any per-item work
+read fixtures/*.json | parallel 8 | POST :3000/users | expect 2xx
+
+# follow a log live — native grep emits each match immediately
+tail -n 0 -F app.log | grep ERROR
+
+# any command's output as a source (run under `crust -c`, data piped in)
+stdin | (l => JSON.parse(l)) | filter (e => e.level >= 40) | (e => e.msg)
+```
+
+To ITERATE on filters over one held live stream, use the `logs` builtin
+(`logs tail -n 0 -F app.log`, `logs procs({…})`, `logs docker logs -f c`):
+every line typed at its prompt is a fragment like the ones above, run over
+a buffer of the recent past and then live; Ctrl-C once ends the view and
+flushes terminal stages (bare `stats` prints there), `exit` leaves.
+
+## Traps
+
+- A plain lambda MAPS — `(l => l.includes('ERROR'))` emits `true`/`false`
+  per item, and `(x => cond ? x : null)` prints literal `null` lines. To
+  drop items, use `filter (l => l.includes('ERROR'))`.
+- `filter` passes an empty stream through silently; `assert` fails on EMPTY
+  upstream ("no items reached") — deliberate, it closes the
+  sql-returned-zero-rows silent pass. `expect` does not fail on empty either.
+- `parallel` streams results in COMPLETION order, not input order.
+- `parallel N` before anything except an http verb, lambda, or registered
+  fn is a parse error; so is a trailing `parallel N`.
+- A glob source yields PATHS; `read <glob>` yields file CONTENTS. `POST`ing
+  a glob posts path strings.
+- Builtins (`test-pipes`, `mock-server`, `logs`, …) cannot be piped. A builtin
+  name in a shell context — `mock-server spec.json | grep ok`, `range(0,2) |
+  test-fixture a.ts` — refuses naming the tool instead of letting sh answer
+  `command not found` for a tool crust runs in-process. Put the builtin on its
+  own line; `logs` takes its filters at the `logs>` prompt.
+- No redirect on a crust stage. `<` / `>` mean something only on a SHELL
+  stage, whose text goes to `sh` verbatim: `… | cat > out.json` saves a
+  pipeline, `lines <path>` / `read <path>` feeds a file in. Anywhere else the
+  line is refused — an http stage used to swallow the operator (request ran,
+  nothing written, exit 0). A builtin carrying one refuses too, and the fix is
+  redirecting the whole call: `crust -c 'mock-server spec.json' > mock.log`.
+- Native grep patterns are JS regexes: quoted `'a|b'` ALTERNATES (ERE)
+  where BRE grep matched the literal — use `grep -F 'a|b'` for the literal.
+- `stdin` is single-shot per process: inside a bare `cmd | crust` script it
+  errors (the pipe was already consumed as the script itself).
+- Shell stages get npm-run-style PATH: ancestor `node_modules/.bin` dirs
+  are prepended, so local tool binaries work bare (`| pino-pretty`,
+  `| tsc --noEmit`) — no `node_modules/.bin/` prefix, no global install.
+- In `… | expect 200 | stats`, a failing expect throws at drain BEFORE stats
+  emits — gate status inside a stats assert instead if you need the summary.
+
+## Exit codes
+
+Any stage throw → `crust: <message>` on stderr, line exits 1. `crust -c`,
+`crust file.crust`, and piped stdin all run newline-separated lines through
+the same fail-fast loop and STOP at the first non-zero — put warmup and
+cleanup on their own lines. Blank lines and `#` comments are skipped, so a
+`#!/usr/bin/env crust` shebang works in `.crust` files.
+
+**Cleanup on a later line is happy-path cleanup, not guaranteed teardown.**
+Under fail-fast, an earlier failure means that line never runs. When
+failure-path cleanup is a requirement (containers, temp rows, mock servers),
+use the verified lifecycle hook: `crust.onExit = async (code) => {…}` in
+`init.ts` — it fires on every shutdown-path exit,
+including the fail-fast failure path of `-c`, script, and stdin runs
+(test-pinned by `tests/onexit.test.ts`), and receives the exit code. If a needed
+guarantee is still missing (e.g. `kill -9`), document the limitation rather
+than implying line placement solves it.
+
+## Version and evidence
+
+Behavior here was verified against **crust v0.3.5** — result shapes and
+failure-record semantics by source and through the compiled binary; keep
+approved targets, credentials, and execution restrictions in repository
+policy, not in this skill.