@myelinbridge/cli 0.13.0 → 0.14.0

package/README.md

@@ -1,195 +1,260 @@
 # @myelinbridge/cli
 
-Push R&D data deliveries into [Myelin](https://myelinbridge.com) from a pipeline —
-preflight against the client's published quality rules, resumable upload, submit,
-and track review outcomes. Full API reference: https://myelinbridge.com/developers.
+Deliver R&D data to your client through [Myelin](https://myelinbridge.com), from a
+terminal or a script: run the client's quality checks on a folder before uploading a
+byte, upload with resume, hand the delivery over for review, follow the outcome.
 
-## Quick start (~10 minutes from key to first submit)
+Node 20 or later. Nothing to install: `npx @myelinbridge/cli <command>` fetches it on
+each run. Or `npm i -g @myelinbridge/cli` once, and the binary is `myelin`.
+Full API reference: https://myelinbridge.com/developers.
 
-```bash
-export MYELIN_API_KEY=myl_live_…     # created by your bridge owner in Bridge → API
-
-npx @myelinbridge/cli ping                 # verifies auth, prints your projects
-npx @myelinbridge/cli datasets             # what you can deliver to, and whose move it is
-npx @myelinbridge/cli contract --dataset onco1-wes            # what is expected of your delivery
-npx @myelinbridge/cli sample-depth 1 --dataset onco1-wes      # once, before your first submit
-npx @myelinbridge/cli roles --dataset onco1-wes               # which file plays which role
-npx @myelinbridge/cli roles set samplesheet /metadata/samplesheet.csv --dataset onco1-wes
-npx @myelinbridge/cli check ./run_042 --dataset onco1-wes    # validate BEFORE uploading a byte
-npx @myelinbridge/cli push  ./run_042 --dataset onco1-wes --submit
-```
-
-- **Declare your sample depth once, first.** The client creates and describes the
-  dataset; you own your output structure, so you tell Myelin at which folder depth a
-  sample sits — `0` = the delivery root is one sample, `1` (default) = each top-level
-  folder is a sample, `2` = one level deeper. Sample-scoped quality checks group by it,
-  so getting it right up front is what makes per-sample verdicts mean anything. It is
-  **idempotent** (safe to assert on every pipeline run, before and after the lock) and
-  **locks once your first batch leaves draft**, so that verdicts stay comparable across
-  deliveries — after that, re-asserting the current value still succeeds and only a
-  *change* exits `2`. This is the only dataset field you can write.
-
-- **Declare which file plays which role — whenever you like (0.11.0).** Quality
-  checks read files by ROLE (`samplesheet`, `checksum_manifest`, `qc_report`,
-  `subject_roster`, `capture_bed`), not by a filing convention you never agreed
-  to. `roles` shows what is declared and what Myelin detected in your
-  deliveries; `roles set <role> <path>` confirms a file; `roles none <role>`
-  states your dataset has no such file (a statement, not a gap). Nothing is
-  ever required to deliver — an undeclared role just means the checks that read
-  it report *"could not check"* instead of running, so declaring is how you
-  activate more checks before upload and catch problems before review does.
-  Unlike `sample-depth` it **never locks**, and it is idempotent, so a pipeline
-  can assert it on every run. The samplesheet is **sticky**: send it once and
-  every later delivery reconciles against it — a partial delivery (93 of 96) is
-  reported as a state, never as a failure.
-
-- **Your client's own fields show up, read-only (0.12.0).** Clients can define
-  their own metadata fields on datasets (a sponsor study code, a work order, a
-  therapeutic area). `contract` prints them under CLIENT FIELDS — including a
-  required field nobody has filled in yet, shown as *"— required, not filled
-  in yet"* (0.12.2) — and `check` tells you the same thing via preflight;
-  informational only: their team fills them in Myelin, there is nothing to
-  change in your delivery, and metadata never moves the exit code. In
-  `--json`, datasets carry a `metadata` object
-  (`{key: {label, type, value, required?}}` — `required: true` and
-  `value: null` mark a required field with no value yet) and preflight
-  carries `metadata.missing_required`.
-
-- **A missing path in `roles set` is refused, not guessed (0.11.1).** Flags are
-  not positional arguments: `roles set samplesheet --dataset onco1-wes` (path
-  omitted) used to declare the samplesheet at the literal path `--dataset` and
-  print a tick. Every samplesheet check then reported *"could not check — the
-  declared file is not in the delivery"* on a delivery that was fine. The
-  command now exits with its usage line instead.
-
-- **`--dataset` takes the slug in any case (0.11.0).** Slugs are matched
-  case-insensitively (`onco1-wes` and `ONCO1-WES` name the same dataset); an id
-  or an exact name works too.
-
-- **Resume = re-run.** `push` is idempotent: already-uploaded files are skipped
-  (path + size), and within a large file, parts that already landed are skipped
-  too (S3 multipart). Uploads go direct to storage over short-lived presigned
-  URLs — no credential is stored on your machine, and revoking the API key cuts
-  off signing immediately.
-- **A corporate proxy is not our problem to ignore (0.13.0).** `HTTPS_PROXY`,
-  `HTTP_PROXY` and `NO_PROXY` are honoured on every call — the API and the part
-  uploads alike. Before this the CLI dialled straight out and a pipeline host
-  whose only egress is a proxy could not deliver at all. The hosts and ports to
-  allow are written down under **For your IT department** below.
-- **Transient failures retry themselves.** Since 0.8.0 a rate limit (`429`)
-  waits out `Retry-After` and retries on every command, and a part upload that
-  hits a storage hiccup (5xx, an edge timeout, an expired URL) re-signs, backs
-  off, and retries up to 4 attempts before surfacing — an unattended pipeline
-  run survives a blip. A retried `--submit` whose first attempt actually landed
-  gets a success echo (`already_submitted: true`), not a false failure.
-- **Slow connections shrink their parts.** Since 0.9.0, when the same part dies
-  twice on a timeout (the edge kills any PUT that runs too long — HTTP 524),
-  `push` restarts the file with smaller parts, 64 → 16 → 5 MB, instead of
-  retrying the same slice into the same wall. A hospital-grade uplink down to
-  roughly 30 KB/s can now complete a delivery; it is slower, but it finishes.
-- **Every file is fingerprinted.** Since 0.7.0, `push` computes an MD5 of each
-  file while it uploads and records it with the delivery. If the client's
-  quality contract includes a checksum-manifest check, your delivery verifies
-  against your own `md5_manifest.csv` instead of reading as "unverifiable".
-- **Read the contract before you build the delivery.** `contract` prints what the
-  client expects — every check as one plain sentence, grouped by what it answers
-  (completeness, structure, validity, consistency, integrity, privacy), and marked
-  `!` when a failure blocks validation or `?` when the client's reviewer confirms
-  it rather than asking you to fix it. It also tells you which checks `check` can
-  verify locally and which only run once the files are uploaded, so nothing about
-  the bar is a surprise at review time.
-
-- **`check` costs nothing.** It evaluates your local file list against the dataset's
-  quality checks server-side — same engine, same verdicts as submit — without
-  uploading. Exit code 2 means the delivery would not be validatable as it stands:
-  a blocking rule fails, **or** a blocking rule could not be evaluated at all.
-- **A check has five answers, not three** (since 0.10.0). Alongside *passed*,
-  *flagged* and *failed*, the engine can now say it **could not check** something
-  (a missing precondition, or a rule it cannot evaluate) and that a rule **does
-  not apply** to your delivery. This matters to you in one specific way: a rule
-  the client wrote badly used to come back as a *failure on your delivery*. It
-  now says the rule could not be evaluated, and tells you it is not yours to fix.
-  `check` prints the count it could not check and what each one needs — supply it
-  and those checks run on your next delivery, which is fewer rejections later.
-- **Some checks are confirmed, not fixed.** A rule marked *needs confirmation*
-  asks nothing of you: the client's reviewer records what they decided and the
-  delivery proceeds. `check` reports these and never exits 2 on them.
-- **The fix loop is machine-readable.** On `changes_requested`,
-  `myelin status <batch> --json` returns the failed files, reviewer comments, and
-  rule remediation hints; fix, re-`push --submit`, unchanged files keep their
-  review votes.
-- **Limits.** `push` declares 500 files per call and chunks automatically — nothing
-  for you to split. `check` sends your whole file list in one preflight
-  call, which accepts at most 10 000 files — a larger delivery cannot be preflighted
-  by `check` today (the API answers `400 too_many_files`); its checks still run at
-  submit. A delivery holds at most 25 000 files (submit refuses above that with
-  `422 submit_blocked`), and a checksum manifest is inspected up to 16 MiB.
-
-## If you are the client, not the partner
+## First delivery
 
-Two kinds of key exist, and they are not interchangeable. Everything above needs a
-**partner key** (write: upload, submit). A **client key** is read-only and answers the
-question your own systems ask once the data has landed: *the bucket is full of UUIDs —
-what is this?*
-
-Where they live follows from what they are. A **partner key belongs to one bridge**, because a
-partner does. A **client key belongs to your organisation**: one key, every partner, one answer.
-Your organisation admin creates it in **Organisation → API keys**. To narrow one to a single
-partner's data, scope it to that partner's projects.
+Your client's bridge owner creates your key in **Bridge → API**. It starts with
+`myl_live_` and is shown once.
 
 ```bash
-export MYELIN_API_KEY=myl_live_…
+export MYELIN_API_KEY=myl_live_…       # Windows: setx MYELIN_API_KEY myl_live_…  (then open a new terminal)
+
+npx @myelinbridge/cli ping                                          # 1. the key works, and what it can reach
+npx @myelinbridge/cli datasets                                      # 2. what you can deliver to
+npx @myelinbridge/cli contract --dataset onco1-wes                  # 3. what the client expects of a delivery
+npx @myelinbridge/cli check ./run_042 --dataset onco1-wes           # 4. their checks on your folder — nothing is uploaded
+npx @myelinbridge/cli push  ./run_042 --dataset onco1-wes --submit  # 5. upload, then hand over for review
+npx @myelinbridge/cli status ONCO1-WES-001 --watch                  # 6. follow the review
+```
 
-# What has landed, newest first (page with --cursor from the printed next_cursor)
-myelin deliveries --dataset <dataset-id>
+That is the whole path. Four things worth knowing about it:
+
+- **`check` uploads nothing.** It sends your file list, and the same engine that runs
+  at submit answers. Exit code `2` means the delivery could not be validated as it
+  stands: a blocking check failed, or a blocking check could not be evaluated at all.
+  Exit `0` here means the checks that can run before upload pass; checks that read
+  file contents run at submit, and `contract` tells you which ones. Above 10 000 files
+  `check` cannot run (`too_many_files`, exit `1`): skip it, the same checks run at submit.
+- **`push` sends every file under the folder** (dotfiles included, symlinks followed; a
+  broken link or an unreadable file stops the command and is named), and it is safe to
+  re-run: files already uploaded are skipped, and inside a large file, parts that already
+  landed are skipped too. A crashed run resumes with the same command. Stage a clean
+  folder if your pipeline leaves work files behind. `push` does not run `check` first.
+  Without `--submit` the draft stays open, one per dataset, and you submit it later, from
+  the CLI or from the portal; a later `push` of a different folder joins that same draft.
+  At the end it prints the delivery's name (`ONCO1-WES-001`), which `status` and `recall`
+  take.
+- **One delivery at a time per dataset.** While a delivery is submitted or in review,
+  `push` to that dataset exits `2` with `delivery_locked` until the reviewer validates it
+  or sends it back. `recall` takes it back while it is still `submitted`. If you deliver
+  more often than your client reviews, agree a turnaround with them, or ask for one
+  dataset per run.
+- **After `--submit`, a person decides.** A reviewer on your client's side opens the
+  delivery in their portal and either validates it, after which Myelin copies the files
+  into their bucket, or asks for changes; the turnaround is theirs, and Myelin notifies
+  them. `status` tells you what to fix: on `changes_requested` it prints the files the
+  reviewer flagged, their comments, and a hint per failed rule. Fix, `push --submit`
+  again: files you did not touch keep their review votes.
+- **`datasets` empty, or `dataset_not_active`?** The client has not finished setup on
+  their side. Three things must exist first, all created by them: an active bridge, a
+  project your key is scoped to, and an activated dataset inside it. Ask your client
+  contact, naming the missing piece.
+
+### What you will see
+
+An example session, human mode. Your names, rules and counts will differ; the shape will not.
 
-# What is this object, exactly?
-myelin resolve gs://acme-landing/inbox/acme-cro/4319…/de99…/7aa5…/data/SAMPLE_01/reads.fastq.gz
-#   file · gs://…/reads.fastq.gz
-#     project   ONCO1 — Oncology discovery
-#     dataset   WES batch 7 (Genomics)
-#     batch     ONCO1-WES-007 · #7
-#     validated 2026-08-07T18:05:12Z · delivered 2026-08-07T18:06:20Z
-#     manifest  gs://…/7aa5…/_myelin/manifest.json
-#     file      reads.fastq.gz · 4096 bytes
+```
+$ myelin ping
+✓ key "pipeline" (myl_live_Yxwfeh…) · bridge Acme ↔ Genos CRO · 1 project(s)
+Next: myelin datasets
+
+$ myelin datasets
+PROJECT  DATASET    STATUS  YOUR MOVE?
+ONCO1    onco1-wes  active  —
+Next: myelin contract --dataset onco1-wes
+
+$ myelin contract --dataset onco1-wes
+WES cohort — delivery contract v3
+6 checks · 3 block validation · 5 checkable before upload · 1 reviewed by a person
+
+COMPLETENESS — is everything here?
+  ! a samplesheet is present at the delivery root
+  ! every sample in the samplesheet has R1 and R2 reads
+STRUCTURE — is it laid out as agreed?
+  · file names follow {sample}_{lane}_{R1|R2}.fastq.gz
+INTEGRITY — are the bytes what you say they are?
+  ! every file matches your checksum manifest (checked at submission)
+REVIEWER JUDGEMENT — decided by a person, not the engine
+  · the consent scope covers this cohort
+
+Run "myelin check <dir> --dataset onco1-wes" to test 5 of these locally.
+
+$ myelin check ./run_042 --dataset onco1-wes
+Evaluating 129 files (26.1 GB) against quality checks v3…
+✓ samplesheet present          passed
+✗ paired reads complete        failed — BLOCKING
+    hint: S07 has R1 but no R2 — add S07_L001_R2.fastq.gz or drop S07 from the samplesheet
+✓ file naming                  passed
+… checksum manifest matches    reads file contents; runs at submit
+○ consent scope                a reviewer decides this
+1 blocking issue(s). Fix before pushing to avoid a review round-trip.
+$ echo $?
+2
+
+$ myelin push ./run_042 --dataset onco1-wes --submit        # after the fix
+Draft ONCO1-WES-004 created.
+Uploading 130/130 files (26.1 GB) · resumable
+  ✓ /samplesheet.csv (1/130)
+  ✓ /S01/S01_L001_R1.fastq.gz (2/130)
+  …
+All files confirmed.
+Submitting… auto-checks: 5 passed, 0 flagged, 0 failed of 6.
+✓ Batch submitted for review. Track: myelin status ONCO1-WES-004 --watch
+
+$ myelin status ONCO1-WES-004 --watch
+ONCO1-WES-004: submitted — reviewer's move.
+ONCO1-WES-004: in_review — reviewer's move.
+ONCO1-WES-004: transferred — delivered to your client’s bucket.
 ```
 
-`resolve` accepts a full `gs://`/`s3://` URI, a bare prefix, or a single id, and answers at
-whatever granularity the path supports.
+### Two optional declarations
 
-Each delivery also carries the same record **as a file**, written next to the data at
-`_myelin/manifest.json` (plus `_myelin/files.csv`, a flat table you can load straight into a
-warehouse). Prefer the file for anything auditable: it is frozen at delivery time, needs no
-credentials, and does not depend on Myelin being reachable. Use the API when you want it live.
+- **`sample-depth`** is the folder depth a sample sits at: `1` means each top-level
+  folder is one sample and is the default, `0` means the whole delivery is one sample,
+  `2` one level deeper. Set it only if the default is wrong for your layout. It locks
+  once your first delivery leaves draft, so per-sample verdicts stay comparable; if you
+  are not sure which depth your client expects, ask before the first submit.
+- **`roles`** says which file plays which role: `samplesheet`, `checksum_manifest`,
+  `qc_report`, `subject_roster`, `capture_bed`. Nothing is required to deliver; a role
+  you declare turns on the checks that read that file, so more of the contract is
+  verified before review. `roles none <role>` records that your dataset has no such
+  file. It never locks. A checksum manifest is read in the shapes tools write: plain
+  `md5sum` output, or a delimited file with a filename column and an md5 column, paths
+  relative to the delivery root.
+
+## Commands
 
-A partner key calling these gets `403 wrong_key_side`, and vice versa.
+`<ds>` is a dataset slug (any case), an id, or an exact name, as `datasets` prints them.
 
-## Machine mode
+| Command | Key | What it does |
+|---|---|---|
+| `ping` | partner | Checks the key and prints the bridge and the projects it can reach. |
+| `datasets` | partner | Lists the datasets you can deliver to, and whose move it is. |
+| `contract --dataset <ds>` | partner | Every check the dataset expects, one sentence each: `!` blocks validation, `~` is confirmed by the client's reviewer rather than fixed by you. Says which checks `check` can run locally. |
+| `check <dir> --dataset <ds>` | partner | Runs the dataset's checks on your local file list, server-side, without uploading. Exit `2` when a blocking check fails or could not be evaluated. |
+| `push <dir> --dataset <ds> [--submit] [--replace]` | partner | Creates or resumes the dataset's draft and uploads what has not landed yet. `--submit` hands it to review. `--replace` overwrites a path already declared with a different size or checksum, which otherwise exits `2`. |
+| `status <batch> [--watch]` | partner | Where the delivery stands and whose move it is; on `changes_requested`, what to fix. Takes an id or a display name. `--watch` polls every 20 s and returns at the first final state: exit `0` at `transferred`, `2` at `changes_requested`, `1` at `rejected` or `transfer_failed`. A review can take days: for an unattended job, prefer a webhook. |
+| `recall <batch>` | partner | Takes a submitted delivery back before the review starts; it becomes a draft again. Once a reviewer has opened it, `recall_failed`. |
+| `projects` | partner | The projects this key is scoped to, with their status. |
+| `sample-depth <0-5> --dataset <ds>` | partner | Declares the folder depth a sample sits at. Idempotent; locks once a delivery leaves draft. |
+| `roles [set <role> <path> / none <role> / clear <role>] --dataset <ds>` | partner | Shows, declares or clears which file plays which role. Idempotent, never locks. |
+| `sandbox <file>` | partner | Uploads one file under 4 MB as the partner-side test transfer your client's bridge-activation checklist asks for. Not a test environment, and not a step before `push`. |
+| `deliveries [--project <id>] [--dataset <id>] [--since <iso>] [--limit <n>] [--cursor <ts>]` | client | What landed in your bucket, newest first. Page with `--cursor` from the printed `next_cursor`. |
+| `resolve <path or prefix or id>` | client | A `gs://` or `s3://` path, a bare prefix or an id, back to the project, dataset, delivery and file it belongs to. |
+| `version` | | Prints the CLI version. |
+| `help [<command>]` | | This list, or one command in detail. Works without a key. |
+
+## From a script
+
+Every command takes `--json`: one JSON object on stdout, no prose. Exit codes:
+`0` ok · `1` error · `2` blocked, meaning a blocking check failed or could not be
+evaluated, a declared path conflicts, or the API refused on the delivery's state or the
+client's setup (`delivery_locked`, `submit_blocked`, `dataset_not_active`,
+`api_disabled`, `bridge_paused`, `sample_depth_locked`).
 
-Every command takes `--json`. Exit codes: `0` ok · `1` error · `2` blocked
-(blocking preflight failure, **a blocking rule the engine could not evaluate**,
-locked delivery, blocked submit, locked sample depth).
+```bash
+myelin check "$OUT" --dataset onco1-wes || exit $?
+myelin push  "$OUT" --dataset onco1-wes --submit
+```
 
-`check --json` carries the numbers to branch on rather than the prose:
+Things a script should know:
+
+- **An unknown option is an error** (`push --sumbit` exits `1` before a byte moves).
+- **Pin the version you tested** in a pipeline: `npx @myelinbridge/cli@<version>`. Bare
+  `npx @myelinbridge/cli` runs whatever is latest today. `--json` shapes and exit codes
+  follow the API's rule: fields may appear, existing ones keep their meaning.
+- **Rotating a key revokes the old one at once.** There is no overlap window, so rotate
+  between runs, not during one; a run that starts with a revoked key fails `401` and
+  resumes with the new key. A key may also carry an expiry the client chose when creating
+  it (`GET /v1/me` → `expires_at`).
+- **No client-side timeout on API calls, by design**: a preflight of 10 000 files takes
+  minutes. Bound the command with your runner's timeout if you need one. A connection
+  refused, a DNS failure or a socket that never answers is reported at once (exit `1`) and
+  not retried; a `429` and a failed part upload are (see below).
+- **`status --watch` exits `0` at `transferred`, `2` at `changes_requested`, `1` at
+  `rejected` or `transfer_failed`.** A network blip mid-watch is retried five times; if the
+  runner dies, re-run it: the state is server-side and nothing is lost.
+- **`--json` shapes.** `ping`, `contract`, `check`, `deliveries` and `resolve` print the API
+  response as is. `datasets` prints `{ datasets: [{ project, dataset, status, quality_version,
+  open_draft, id }] }`. `push` prints `{ batch_id, files, submitted: false }` for a draft and
+  the submit response (`{ batch_id, status, already_submitted, auto_checks }`) with
+  `--submit`. `status` prints `{ batch }`, plus `findings` on `changes_requested`. The delivery
+  name that `status` takes is `batch.display_name`; the id works too.
+- **Paths** are relative to the delivery root, `/`-separated; a leading `/` is optional.
+
+`check --json` carries the numbers to branch on:
 
 | Field | |
 |---|---|
-| `blocking_failures` | Blocking rules that were evaluated and failed. Unchanged meaning since the first release. |
-| `blocking_not_evaluated` | Blocking rules the engine could not evaluate. **New in 0.10.0** — these stop the reviewer validating just as surely, which is why `check` now exits `2` on them too. |
-| `must_acknowledge_failures` | Rules the client asked to be told about. Reported, never exited on. |
-| `counts` | `passed`, `flagged`, `failed`, `not_evaluated`, `not_applicable` (which sum to `evaluated`), plus `deferred`, `manual` and `checks` (`evaluated + deferred + manual === checks`). |
-
-Every per-check result carries `details.abstained` when the engine did not
-conclude: `rule` means **the client's rule** could not be evaluated and there is
-nothing on your side to fix; `data` means something the check needs is missing
-from the delivery; `nothing_to_evaluate` means the rule matched none of your
-files. Branch on that before you page anyone.
-
-API errors carry structure, not just prose: in `--json` mode an error is
-`{ "error", "code", "status", "request_id" }` — branch on `code`, and quote the
-`request_id` when reporting a problem (it is printed in human mode too; it lets
-Myelin find the exact server-side log line). `myelin version` prints the CLI
-version.
+| `blocking_failures` | Blocking checks that were evaluated and failed. |
+| `blocking_not_evaluated` | Blocking checks the engine could not evaluate. These stop the reviewer validating just as surely, so `check` exits `2` on them too. |
+| `must_acknowledge_failures` | Checks the client asked to be told about. Reported, never exited on. |
+| `counts` | `passed`, `flagged`, `failed`, `not_evaluated`, `not_applicable`, plus `deferred` and `manual`. |
+| `metadata.missing_required` | The client's own required fields still empty on the dataset. Informational: their team fills them in Myelin, nothing to change in your delivery, and it never moves the exit code. |
+
+A check that did not conclude says why in `details.abstained`: `rule` means the
+client's own rule could not be evaluated and there is nothing on your side to fix;
+`data` means something the check needs is missing from your delivery; `nothing_to_evaluate`
+means the rule matched none of your files.
+
+An API error in `--json` mode is `{ "error", "code", "status", "request_id" }`. Branch on
+`code`; quote `request_id` when you report a problem, it names the exact server-side log
+line. The id is printed in human mode too.
+
+## What push does when something goes wrong
+
+- **A crash or a lost connection.** Re-run the same command. A file already uploaded at
+  the same path and size is skipped; within a large file, parts that already landed are
+  skipped.
+- **A rate limit.** A `429` waits out `Retry-After` and retries, on every command.
+- **A part that fails.** On a storage error, an edge timeout or an expired upload URL,
+  the part is re-signed and retried with backoff, four attempts, before the error surfaces.
+- **A slow uplink.** When the same part dies twice on a timeout, the file restarts with
+  smaller parts, 64 → 16 → 5 MiB. A link down to roughly 30 KB/s completes; slowly, but
+  it finishes.
+- **A retried `--submit`.** If the first attempt actually landed, the retry is answered
+  with `already_submitted: true`, not a failure.
+- **Checksums.** An MD5 of each file is computed while it uploads and recorded with the
+  delivery, so a checksum-manifest check verifies against your own manifest.
+
+Uploads go straight to storage over short-lived presigned URLs. No credential for the
+client's storage is ever on your machine, and revoking the key cuts off signing at once.
+
+## Limits
+
+| | |
+|---|---|
+| Files per delivery | 25 000. Submit refuses above that. |
+| Files per `check` | 10 000 in one call. A larger delivery cannot be preflighted by `check`; its checks still run at submit. |
+| Files per declare call | 500. `push` chunks automatically. |
+| Per-file size | 20 GiB by default, set per deployment. |
+| Checksum manifest | Inspected up to 16 MiB. |
+| API rate | 120 requests per minute per key. Part uploads go direct to storage and do not count. |
+| Throughput | On the order of 100 MB/s aggregate on a clean link (four parts in parallel); a 100 GB run is around twenty minutes. Your uplink is the limit. |
+
+## Where your files are, and for how long
+
+Uploads land in Myelin's holding area, Supabase Storage in the EU (Ireland), never in your
+client's bucket. There they can be read by you, by your client's reviewers on that project,
+and by the transfer worker's service identity; Myelin's own operator role has no
+customer-data access. Once the reviewer validates, the files are copied into the client's
+bucket and the copy is verified. The holding copy is purged after that verified delivery, or
+after a rejection, plus a grace window of seven days by default; each purge writes an audit
+row. An empty draft with no activity for 24 hours is purged; a draft holding uploaded files
+is kept, and its owner reminded. The full position is at https://myelinbridge.com/security.
+
+There is no self-serve test environment. To rehearse without real data, ask your client for
+a dataset created for that purpose, or ask Myelin for a sandbox. Questions about the setup on
+the client's side go to your client contact; questions about the API go to the address on
+https://myelinbridge.com/developers.
 
 ## Environment
 
@@ -197,13 +262,39 @@ version.
 |---|---|
 | `MYELIN_API_KEY` | Required. Created by your bridge owner in **Bridge → API**. |
 | `MYELIN_API_URL` | Optional. Defaults to `https://myelinbridge.com/api/v1`. |
-| `MYELIN_API_HEADER` | Optional. Extra headers sent with every API call, one `Name: value` per line — for a Myelin deployment fronted by something that authenticates before Myelin does (a corporate gateway, an SSO-protected preview). It can never override `Authorization`. |
-| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Optional, honoured since **0.13.0** — see below. Lowercase spellings read too. |
+| `MYELIN_API_HEADER` | Optional. Extra headers sent with every API call, one `Name: value` per line, for a Myelin deployment fronted by something that authenticates before Myelin does. It can never override `Authorization`. |
+| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Optional. Honoured on every call; lowercase spellings read too. See below. |
+
+## If you are the client, not the partner
+
+Everything above needs a **partner key**. A **client key** is read-only and answers the
+question your own systems ask once the data has landed: the bucket is full of ids, what
+is this? Your organisation admin creates it in **Organisation → API keys**; one key covers
+every partner. To narrow one to a single partner's data, scope it to that partner's projects.
+
+```bash
+export MYELIN_API_KEY=myl_live_…
+
+myelin deliveries --dataset <dataset-id>        # what has landed, newest first
+myelin resolve gs://acme-landing/inbox/acme-cro/4319…/de99…/7aa5…/data/SAMPLE_01/reads.fastq.gz
+#   file · gs://…/reads.fastq.gz
+#     project   ONCO1 — Oncology discovery
+#     dataset   WES cohort (Genomics)
+#     batch     ONCO1-WES-007 · #7
+#     validated 2026-08-07T18:05:12Z · delivered 2026-08-07T18:06:20Z
+#     manifest  gs://…/7aa5…/_myelin/manifest.json
+```
+
+Each delivery also carries the same record **as a file**, written next to the data at
+`_myelin/manifest.json`, with `_myelin/files.csv` beside it as a flat table. Prefer the
+file for anything auditable: it is frozen at delivery time, needs no credentials, and does
+not depend on Myelin being reachable. A partner key calling these gets `403 wrong_key_side`,
+and vice versa.
 
 ## For your IT department
 
-Everything below is derived from what the code actually connects to. If you need
-to hand one page to a network team, hand them this one.
+Everything below is derived from what the code actually connects to. If you need to hand
+one page to a network team, hand them this one.
 
 ### What the CLI needs to reach
 
@@ -215,14 +306,14 @@ Outbound **TCP 443 only**, to two hosts:
 | `cdjlhyyrbogzkoaujzmj.storage.supabase.co` | the bytes — uploads go **straight to storage** over short-lived presigned URLs, never through the API host |
 
 The second one surprises people, and it is the single commonest way a delivery
-half-works: `myelin ping` and `myelin check` succeed, `myelin push` stalls on
-part 1. Since 0.13.0 that failure names the host it could not reach, so the
-allowlist gap is legible from the error.
+half-works: `myelin ping` and `myelin check` succeed, `myelin push` stalls on part 1.
+That failure names the host it could not reach, so the allowlist gap is legible from
+the error.
 
-If your client runs Myelin at their own address, `MYELIN_API_URL` names the
-first host and the second is that deployment's storage host. You never have to
-guess it — every Myelin deployment publishes the authoritative list in its own
-`content-security-policy` header:
+If your client runs Myelin at their own address, `MYELIN_API_URL` names the first host
+and the second is that deployment's storage host. You never have to guess it: every
+Myelin deployment publishes the authoritative list in its own `content-security-policy`
+header:
 
 ```bash
 curl -sI https://myelinbridge.com | tr ';' '\n' | grep connect-src
@@ -242,29 +333,28 @@ Supabase API host, because sign-in and the session live there:
 | `cdjlhyyrbogzkoaujzmj.supabase.co` | 443 | sign-in and session |
 | `cdjlhyyrbogzkoaujzmj.storage.supabase.co` | 443 | browser uploads, the same presigned PUTs the CLI makes |
 
-Plain HTTPS is enough. The policy also permits `wss:` to the Supabase host, but
-the portal opens no WebSocket today — if your proxy distinguishes the two, you
-do not need to allow WebSocket upgrades for the portal to work.
+Plain HTTPS is enough. The policy also permits `wss:` to the Supabase host, but the
+portal opens no WebSocket today; if your proxy distinguishes the two, you do not need to
+allow WebSocket upgrades for the portal to work.
 
-Nothing else is contacted: scripts and fonts are served by the application
-itself and no analytics or tracker host is involved. That is not a promise in a
-README — it is the `content-security-policy` header above, which the browser
-enforces on every response.
+Nothing else is contacted: scripts and fonts are served by the application itself and no
+analytics or tracker host is involved. That is not a promise in a README; it is the
+`content-security-policy` header above, which the browser enforces on every response.
 
 ### What you do *not* need to open
 
-- **No inbound anything.** Nothing connects to your network. The one exception
-  is opt-in and yours to choose: if you register a webhook endpoint, Myelin
-  makes an outbound HTTPS call to an address you publish.
-- **No access to the destination bucket.** The client's cloud bucket is written
-  by Myelin, server-side, after review. A partner never touches it and never
-  needs a credential for it.
+- **No inbound anything.** Nothing connects to your network. The one exception is opt-in
+  and yours to choose: if you register a webhook endpoint, Myelin makes an outbound HTTPS
+  call to an address you publish.
+- **No access to the destination bucket.** The client's cloud bucket is written by
+  Myelin, server-side, after review. A partner never touches it and never needs a
+  credential for it.
 - **No FTP, SSH, rsync or fixed source IPs.** One protocol, one port.
 
 ### Behind a proxy
 
-Set the standard variables — the CLI honours them on every call, the API and
-the part uploads alike:
+Set the standard variables; the CLI honours them on every call, the API and the part
+uploads alike:
 
 ```bash
 export HTTPS_PROXY=http://proxy.corp.example:8080
@@ -273,28 +363,24 @@ myelin ping        # prints "via proxy http://proxy.corp.example:8080" when one
 ```
 
 - `HTTPS_PROXY` for https targets, `HTTP_PROXY` for http, `NO_PROXY` to exclude.
-  Lowercase spellings (`https_proxy`, …) are read too — both are in the wild.
-- Credentials go in the URL: `http://user:pass@proxy:8080` (Basic). They are
-  never printed, logged, or echoed in an error.
-- `NO_PROXY` accepts a host, a suffix (`.corp.example`, `*.corp.example`),
-  `host:port`, an IPv4 CIDR (`10.0.0.0/8`), or `*` for everything.
-- **HTTP CONNECT proxies only.** A `socks5://` value is refused with a message
-  rather than silently bypassed — a CLI that quietly dials direct while you
-  believe it is proxied is worse than one that stops.
+  Lowercase spellings (`https_proxy`, …) are read too; both are in the wild.
+- Credentials go in the URL: `http://user:pass@proxy:8080` (Basic). They are never
+  printed, logged, or echoed in an error.
+- `NO_PROXY` accepts a host, a suffix (`.corp.example`, `*.corp.example`), `host:port`,
+  an IPv4 CIDR (`10.0.0.0/8`), or `*` for everything.
+- **HTTP CONNECT proxies only.** A `socks5://` value is refused with a message rather
+  than silently bypassed: a CLI that quietly dials direct while you believe it is proxied
+  is worse than one that stops.
+- **Basic proxy authentication only.** An NTLM or Kerberos proxy is not supported; put a
+  local CONNECT proxy that speaks it (cntlm, px) in front and point `HTTPS_PROXY` at that.
 - A typo in a proxy variable fails immediately, before any command runs.
-- **TLS terminates at Myelin, not at your proxy.** Through a CONNECT tunnel the
-  proxy sees the hostname and nothing else. If your proxy performs TLS
-  interception, point Node at its CA:
-  `export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-root.pem`.
-
-Before 0.13.0 the CLI ignored all three variables — Node's `fetch` does — so on
-a host whose only egress is a proxy every command failed with `fetch failed`.
-If you are running an older version behind a proxy, upgrade rather than work
-around it.
+- **TLS terminates at Myelin, not at your proxy.** Through a CONNECT tunnel the proxy sees
+  the hostname and nothing else. If your proxy performs TLS interception, point Node at
+  its CA: `export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-root.pem`.
 
 ## Webhooks instead of polling
 
-Register an HTTPS endpoint (portal Bridge → API, or `POST /v1/webhook-endpoints`)
-to receive signed events (`batch.validated`, `batch.changes_requested`,
-`batch.transferred`, …). Verification snippets: https://myelinbridge.com/developers.
-Polling fallback: `GET /v1/events?cursor=…`.
+Register an HTTPS endpoint (portal Bridge → API, or `POST /v1/webhook-endpoints`) to
+receive signed events (`batch.validated`, `batch.changes_requested`, `batch.transferred`,
+…). Verification snippets: https://myelinbridge.com/developers. Polling fallback:
+`GET /v1/events?cursor=…`.

package/bin/myelin.js

@@ -918,6 +918,7 @@ async function cmdPing() {
   // ordinary output is unchanged.
   const via = proxyForUrl(new URL(API_URL))
   if (via) out(`  via proxy ${via.display}`)
+  out('Next: myelin datasets')
 }
 
 async function cmdProjects() {
@@ -944,11 +945,19 @@ async function cmdDatasets() {
   }
   emit({ datasets: rows })
   if (!JSON_MODE) {
+    if (rows.length === 0) {
+      // The commonest first-run dead end, and nothing on the partner's side
+      // fixes it: the client has not activated a dataset in a project this
+      // key is scoped to. Say so, rather than printing an empty table.
+      out('No dataset to deliver to yet. The client activates one on their side, in a project this key is scoped to — ask your client contact.')
+      return
+    }
     const lines = table(
       ['PROJECT', 'DATASET', 'STATUS', 'YOUR MOVE?'],
       rows.map((r) => [r.project, r.dataset, r.status, r.open_draft ? 'yes — open draft to finish' : '—']),
     )
     for (const line of lines) out(line)
+    out(`Next: myelin contract --dataset ${rows[0].dataset}`)
   }
 }
 
@@ -998,8 +1007,11 @@ async function cmdContract() {
       // was not `blocking` a "should", so a `must_acknowledge` rule — the one
       // that demands a named decision from the reviewer — printed identically
       // to a warning nobody has to read.
+      // `?` is what `check` and `status` print for "not checked"; the reviewer-
+      // confirmed rung gets its own glyph so one mark means one thing across
+      // the three commands (first-contact review, 2026-09-19).
       const mark =
-        c.severity === 'blocking' ? '!' : c.severity === 'must_acknowledge' ? '?' : '·'
+        c.severity === 'blocking' ? '!' : c.severity === 'must_acknowledge' ? '~' : '·'
       const when = c.runs_at === 'preflight' ? '' : ' (checked at submission)'
       const note =
         c.severity === 'must_acknowledge'
@@ -1157,8 +1169,10 @@ async function cmdCheck() {
   // true, and the coverage is stated the rest of the time — framed as a
   // capability to gain, because it is one: more checks running before you send
   // means fewer rejections after.
+  const next = `Next: myelin push ${dir} --dataset ${dsRef} --submit`
   if (!k || k.passed + k.not_applicable === k.evaluated) {
     out('All checks that run before upload pass.')
+    out(next)
     return
   }
   const rest = []
@@ -1168,6 +1182,7 @@ async function cmdCheck() {
   if (k.not_evaluated > 0) {
     out(`Supply what ${k.not_evaluated === 1 ? 'it needs' : 'they need'} and ${k.not_evaluated === 1 ? 'it runs' : 'they run'} on your next delivery.`)
   }
+  out(next)
 }
 
 async function cmdPush() {
@@ -1204,7 +1219,10 @@ async function cmdPush() {
   }
   const created = expectOk(createRes, 'create batch')
   const batchId = created.batch_id
-  out(`Draft ${created.resumed ? 'resumed' : 'created'} (${batchId.slice(0, 8)}…).`)
+  // The display name (ONCO1-WES-004) is what a person passes to `status` and
+  // `recall`; the create call answers with the id only, so read it once.
+  const batchName = (await api('GET', `/batches/${batchId}`)).json?.batch?.display_name ?? batchId
+  out(`Draft ${batchName} ${created.resumed ? 'resumed' : 'created'}.`)
 
   // 2. declare in chunks of 500 — idempotent, so re-running skips what's done
   const declared = []
@@ -1267,7 +1285,7 @@ async function cmdPush() {
     if (j.already_submitted) {
       // A retried submit whose first attempt actually landed: the API echoes
       // success instead of failing, and so do we — nothing to redo.
-      out(`✓ Batch already submitted (${j.status}) — nothing to redo. Track: myelin status ${batchId} --watch`)
+      out(`✓ Batch already submitted (${j.status}) — nothing to redo. Track: myelin status ${batchName} --watch`)
     } else {
       // ⚠ This line used to print three numbers and no denominator, which was
       // exhaustive until the engine could abstain — after that, an abstention
@@ -1285,7 +1303,7 @@ async function cmdPush() {
       if (a.must_acknowledge_failures) {
         out(`  ${a.must_acknowledge_failures} check(s) your client asked to be told about — nothing to fix.`)
       }
-      out(`✓ Batch submitted for review. Track: myelin status ${batchId} --watch`)
+      out(`✓ Batch submitted for review. Track: myelin status ${batchName} --watch`)
     }
   } else {
     emit({ batch_id: batchId, files: declared.length, submitted: false })
@@ -1293,27 +1311,53 @@ async function cmdPush() {
   }
 }
 
+// A batch by id or by display name (`ONCO1-WES-004`), as `push` prints it.
+// Shared by `status` and `recall`.
+async function resolveBatch(ref) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(ref)) {
+    const r = await api('GET', `/batches/${ref}`)
+    if (r.status === 200) return expectOk(r, 'batch').batch
+    die(`Batch ${ref} not found in this key's scope`)
+  }
+  // Paged: a key that has delivered more than a hundred times still finds
+  // its batch by name.
+  let cursor = null
+  for (;;) {
+    const list = expectOk(
+      await api('GET', `/batches?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`),
+      'batches',
+    )
+    const hit = list.batches.find((b) => b.display_name === ref)
+    if (hit) return expectOk(await api('GET', `/batches/${hit.id}`), 'batch').batch
+    if (!list.next_cursor) die(`No batch named "${ref}" in this key's scope`)
+    cursor = list.next_cursor
+  }
+}
+
 async function cmdStatus() {
   const ref = args[1]
-  if (!ref) die('Usage: myelin status <batch-id|display-name> [--watch]')
+  // `myelin status --watch` used to take "--watch" as the batch name and go
+  // to the network with it; a flag is never a batch.
+  if (!ref || ref.startsWith('--')) die('Usage: myelin status <batch-id|display-name> [--watch]')
 
-  const findBatch = async () => {
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(ref)) {
-      const r = await api('GET', `/batches/${ref}`)
-      if (r.status === 200) return expectOk(r, 'batch').batch
-      die(`Batch ${ref} not found in this key's scope`)
-    }
-    const list = expectOk(await api('GET', '/batches?limit=100'), 'batches')
-    const hit = list.batches.find((b) => b.display_name === ref)
-    if (!hit) die(`No batch named "${ref}" in this key's scope`)
-    return expectOk(await api('GET', `/batches/${hit.id}`), 'batch').batch
-  }
+  const findBatch = () => resolveBatch(ref)
 
   const print = async (batch) => {
-    emit({ batch })
-    out(`${batch.display_name}: ${batch.status} — ${batch.court === 'partner' ? 'your move.' : batch.court === 'reviewer' ? "reviewer's move." : batch.court === 'system' ? 'transferring…' : 'done.'}`)
+    // "done." used to cover rejected and transfer_failed alike. A final state
+    // says what it is; the rest says whose move it is.
+    const tail =
+      batch.status === 'transferred' ? 'delivered to your client’s bucket.'
+      : batch.status === 'rejected' ? 'rejected — final.'
+      : batch.status === 'transfer_failed' ? 'transfer failed on the Myelin side — nothing to redo; ask your client contact.'
+      : batch.court === 'partner' ? 'your move.'
+      : batch.court === 'reviewer' ? "reviewer's move."
+      : batch.court === 'system' ? 'transferring…'
+      : 'done.'
+    out(`${batch.display_name}: ${batch.status} — ${tail}`)
+    let findings = null
     if (batch.status === 'changes_requested') {
       const f = expectOk(await api('GET', `/batches/${batch.id}/findings`), 'findings')
+      findings = f
       if (f.request_changes_comment) out(`  reviewer: "${f.request_changes_comment}"`)
       for (const fr of f.file_reviews.filter((x) => x.verdict === 'failed')) {
         out(`  ✗ ${fr.path}  (${fr.reviewer ?? 'reviewer'}: ${fr.comment ?? 'failed'})`)
@@ -1336,20 +1380,55 @@ async function cmdStatus() {
         )
       }
     }
+    emit(findings ? { batch, findings } : { batch })
     return batch
   }
 
   let batch = await print(await findBatch())
   if (flag('watch')) {
+    // Nothing to wait for on a draft: it is the partner's own move.
+    if (batch.status === 'draft') {
+      out('  nothing to wait for — it is your move: myelin push <dir> --dataset <ds> --submit')
+      process.exitCode = 2
+      return
+    }
     const terminal = ['transferred', 'rejected', 'changes_requested', 'transfer_failed']
+    let misses = 0
     while (!terminal.includes(batch.status)) {
       await new Promise((r) => setTimeout(r, 20_000))
-      const next = await findBatch()
+      let next
+      try {
+        next = await findBatch()
+        misses = 0
+      } catch (err) {
+        // A network blip mid-watch used to end the command with exit 1 after
+        // hours of polling. Five consecutive misses is a real outage.
+        if (!(err instanceof CliExit) || ++misses >= 5) throw err
+        process.exitCode = 0
+        out(`  (could not reach the API — retrying, ${misses}/5)`)
+        continue
+      }
       if (next.status !== batch.status) batch = await print(next)
     }
+    // A pipeline branches on the exit code: 0 delivered, 2 your move, 1 final.
+    if (batch.status === 'changes_requested') process.exitCode = 2
+    else if (batch.status === 'rejected' || batch.status === 'transfer_failed') process.exitCode = 1
   }
 }
 
+// Take a submitted delivery back before the review starts. The page and the
+// API's own `delivery_locked` message both said "recall it" while the CLI had
+// no way to (first-contact review, 2026-09-19).
+async function cmdRecall() {
+  const ref = args[1]
+  if (!ref || ref.startsWith('--')) die('Usage: myelin recall <batch-id|display-name>')
+  const batch = await resolveBatch(ref)
+  const r = await api('POST', `/batches/${batch.id}/recall`)
+  if (r.status !== 200) apiDie('recall', r)
+  emit(r.json)
+  out(`✓ ${batch.display_name} recalled — it is a draft again (${r.json.status}). Fix, then: myelin push <dir> --dataset <ds> --submit`)
+}
+
 async function cmdSandbox() {
   const file = args[1]
   if (!file) die('Usage: myelin sandbox <file>')
@@ -1406,6 +1485,10 @@ async function cmdRoles() {
   if (sub === 'set' || sub === 'none' || sub === 'clear') {
     const role = args[2]
     if (!role) die(`Usage: myelin roles ${sub} <role>${sub === 'set' ? ' <path>' : ''} --dataset <slug|id>`)
+    // A misspelt role used to travel to the API and come back as a 400; the
+    // five names are known here.
+    const KNOWN_ROLES = ['samplesheet', 'checksum_manifest', 'qc_report', 'subject_roster', 'capture_bed']
+    if (!KNOWN_ROLES.includes(role)) die(`Unknown role "${role}" — one of ${KNOWN_ROLES.join(', ')}`)
     const body = { role }
     if (sub === 'set') {
       const path = args[3]
@@ -1455,39 +1538,193 @@ async function cmdRoles() {
   }
 }
 
-function cmdHelp() {
-  console.log(`myelin — Partner Ingestion CLI
+// ——— help ———
+//
+// Two doors, both open WITHOUT a key: `myelin help [<command>]` and
+// `myelin <command> --help`. The developer reading this is usually waiting for
+// a key from the bridge owner, and the manual is the one thing they can use
+// meanwhile. The overview lists the commands in the order a first delivery
+// runs them, so the list is also the path. No version numbers anywhere in this
+// text: a change ships as the current behaviour, not as a diff against a past
+// no partner has lived (founder, 2026-09-19). `scripts/test-cli-docs.ts` holds
+// this text, the README's table and the /developers table to the same set of
+// commands, and fails on a semver literal in any of them.
+
+const HELP = {
+  ping: {
+    usage: 'myelin ping',
+    what: 'Checks the key and prints the bridge it belongs to and the projects it can reach.',
+    notes: [
+      'Run this first. If it succeeds but `datasets` prints nothing, the client has not',
+      'activated a dataset yet — nothing on your side fixes that; ask your client contact.',
+    ],
+  },
+  datasets: {
+    usage: 'myelin datasets',
+    what: 'Lists the datasets you can deliver to, and whose move it is on each.',
+    notes: [
+      'DATASET is the slug you pass to --dataset (any case). "YOUR MOVE? yes" means a',
+      'draft of yours is open and waiting to be finished or submitted.',
+    ],
+  },
+  contract: {
+    usage: 'myelin contract --dataset <ds>',
+    what: 'Prints what the client expects of a delivery: every check, one sentence each.',
+    notes: [
+      '  !  blocks validation if it fails',
+      '  ~  is confirmed by the client’s reviewer, never fixed by you',
+      'Also says which checks `check` can run locally and which run once the files are up,',
+      'and the client’s own fields on the dataset (read-only, informational).',
+    ],
+  },
+  check: {
+    usage: 'myelin check <dir> --dataset <ds>',
+    what: 'Runs the dataset’s checks on your local folder, server-side, without uploading a byte.',
+    notes: [
+      'Exit 2 when a blocking check failed OR could not be evaluated — both stop the',
+      'reviewer validating. Checks that read file contents run at submit; they are listed',
+      'as deferred here. Safe to run as often as you like.',
+    ],
+  },
+  push: {
+    usage: 'myelin push <dir> --dataset <ds> [--submit] [--replace]',
+    what: 'Creates or resumes the dataset’s draft and uploads what has not landed yet.',
+    notes: [
+      '--submit   hand the delivery over for review once every file is up',
+      '--replace  overwrite a path already declared with a different size or checksum',
+      '           (without it, that path exits 2)',
+      'Every file under <dir> is sent, dotfiles included, symlinks followed; a broken link',
+      'or an unreadable file stops the command and is named. Stage a clean folder if your',
+      'pipeline leaves work files behind.',
+      'Re-run the same command to resume: uploaded files, and uploaded parts of a large',
+      'file, are skipped. One draft per dataset; without --submit it stays open, and a',
+      'later push of a DIFFERENT folder joins that same draft. While a delivery is',
+      'submitted or in review, push to that dataset exits 2 (delivery_locked).',
+      'push does not run check first — run check yourself. At the end it prints the',
+      'delivery name (ONCO1-WES-004) that `status` and `recall` take.',
+    ],
+  },
+  status: {
+    usage: 'myelin status <batch> [--watch]',
+    what: 'Where a delivery stands and whose move it is. Takes an id or a display name.',
+    notes: [
+      'On changes_requested: the files the reviewer flagged, their comments, and a hint',
+      'per failed rule. Fix, then `push --submit` again — untouched files keep their votes.',
+      '--watch polls every 20 s and returns at the first final state, with an exit code',
+      'a script can branch on: 0 transferred · 2 changes_requested (your move) ·',
+      '1 rejected or transfer_failed. A network blip mid-watch is retried five times.',
+      'A review can take days: for an unattended job prefer a webhook (see /developers).',
+      'In --json, changes_requested carries the findings too.',
+    ],
+  },
+  recall: {
+    usage: 'myelin recall <batch>',
+    what: 'Takes a submitted delivery back before the review starts. It becomes a draft again.',
+    notes: [
+      'Only while the status is submitted. Once a reviewer has opened it (in_review) the',
+      'API answers recall_failed; wait for their decision instead.',
+    ],
+  },
+  projects: {
+    usage: 'myelin projects',
+    what: 'Lists the projects this key is scoped to, with their status.',
+    notes: [],
+  },
+  'sample-depth': {
+    usage: 'myelin sample-depth <0-5> --dataset <ds>',
+    what: 'Declares the folder depth a sample sits at. Optional; the default is 1.',
+    notes: [
+      '  0  the delivery root is one sample',
+      '  1  each top-level folder is one sample (default)',
+      '  2  one level deeper, and so on',
+      'Set it only if the default is wrong for your layout. Idempotent; it locks once your',
+      'first delivery leaves draft, so per-sample verdicts stay comparable.',
+    ],
+  },
+  roles: {
+    usage: 'myelin roles [set <role> <path> | none <role> | clear <role>] --dataset <ds>',
+    what: 'Shows, declares or clears which file plays which role. Optional; never locks.',
+    notes: [
+      'Roles: samplesheet, checksum_manifest, qc_report, subject_roster, capture_bed.',
+      'Nothing is required to deliver. Declaring a role turns on the checks that read',
+      'that file, so more of the contract is verified before review. `none` records that',
+      'your dataset has no such file. Idempotent — safe to assert on every run.',
+    ],
+  },
+  sandbox: {
+    usage: 'myelin sandbox <file>',
+    what: 'Uploads one file under 4 MB as the partner-side test transfer your client’s bridge-activation checklist asks for.',
+    notes: ['It proves the route works. Not a test environment, and not a step before push.'],
+  },
+  deliveries: {
+    usage: 'myelin deliveries [--project <id>] [--dataset <id>] [--since <iso>] [--limit <n>] [--cursor <ts>]',
+    what: 'What landed in your bucket, newest first. Needs a CLIENT key (Organisation → API keys).',
+    notes: ['Page with --cursor, passing back the printed next_cursor verbatim.'],
+  },
+  resolve: {
+    usage: 'myelin resolve <path|prefix|id>',
+    what: 'What a path in your bucket is: project, dataset, delivery, file. Needs a CLIENT key.',
+    notes: ['Accepts a gs:// or s3:// URI, a bare prefix, or a single id.'],
+  },
+  version: {
+    usage: 'myelin version',
+    what: 'Prints the CLI version.',
+    notes: [],
+  },
+  help: {
+    usage: 'myelin help [<command>]',
+    what: 'This list, or one command in detail. Works without a key.',
+    notes: [],
+  },
+}
 
-Setup:
-  export MYELIN_API_KEY=myl_live_…        (create in Bridge → API)
-  export MYELIN_API_URL=…                 (optional; default https://myelinbridge.com/api/v1)
-  export MYELIN_API_HEADER="Name: value"  (optional; extra headers, one per line —
-                                           for a gateway that authenticates ahead of Myelin)
-  export HTTPS_PROXY=http://proxy:8080    (optional; HTTP_PROXY / NO_PROXY honoured too,
-                                           either case — see README "For your IT department")
-
-Commands:
-  ping                                    verify the key; show bridge + projects
-  projects                                list scoped projects
-  datasets                                list datasets with "your move" hints
-  sample-depth <0-5> --dataset <slug|id>  declare the folder depth a sample sits at (locks after 1st submit)
-  roles [set|none|clear …] --dataset <…>  which file plays each role (samplesheet, checksum list, …) —
-                                          declaring one activates the checks that read it; never locks
-  contract --dataset <slug|id>            what this dataset expects of your delivery
-  check <dir> --dataset <slug|id>         preflight local files against quality rules (no upload)
-  push <dir> --dataset <slug|id>          create/resume a delivery and upload (resumable; re-run to resume)
-       [--submit] [--replace]
-  status <batch|name> [--watch]           review status + fix-loop findings
-  sandbox <file>                          partner-side test transfer (bridge activation)
-
-Client-side commands (need a CLIENT key — Organisation → API keys):
-  deliveries [--project <id>]             what landed in your destination bucket
-             [--dataset <id>] [--since <iso>] [--limit <n>] [--cursor <ts>]
-  resolve <path|prefix|id>                what a path in your bucket actually is —
-                                          project, dataset, batch, file
+function cmdHelp(name) {
+  if (name && !HELP[name]) die(`Unknown command "${name}" — run: myelin help`)
+  // "Every command accepts --json" includes this one.
+  if (JSON_MODE) {
+    emit(name ? { command: name, ...HELP[name] } : { commands: HELP })
+    return
+  }
+  if (name) {
+    const h = HELP[name]
+    console.log(`Usage: ${h.usage}\n\n${h.what}${h.notes.length ? '\n\n' + h.notes.join('\n') : ''}`)
+    return
+  }
+  console.log(`myelin — deliver R&D data to your client through Myelin
+
+Usage: myelin <command> [--json]
+       myelin help <command>
+
+Commands, in the order a first delivery runs them:
+  ping                                    the key works, and what it can reach
+  datasets                                what you can deliver to, and whose move it is
+  contract --dataset <ds>                 what the client expects of a delivery
+  check <dir> --dataset <ds>              their checks on your folder — nothing is uploaded
+  push <dir> --dataset <ds> [--submit]    upload (resumable, re-run to resume), then hand over
+  status <batch> [--watch]                follow the review; on changes_requested, what to fix
+
+Optional:
+  recall <batch>                          take a submitted delivery back before review starts
+  projects                                the projects this key is scoped to
+  sample-depth <0-5> --dataset <ds>       the folder depth a sample sits at (default 1)
+  roles … --dataset <ds>                  which file plays which role; turns on more checks
+  sandbox <file>                          the connectivity test bridge activation asks for
+
+Client-side commands (a CLIENT key, from Organisation → API keys):
+  deliveries                              what landed in your bucket
+  resolve <path|prefix|id>                what a path in your bucket is
 
   version                                 print the CLI version
+  help [<command>]                        this list, or one command in detail
+
+Setup:
+  export MYELIN_API_KEY=myl_live_…        the key your bridge owner created in Bridge → API
+  export MYELIN_API_URL=…                 optional; default https://myelinbridge.com/api/v1
+  export MYELIN_API_HEADER="Name: value"  optional; extra headers, one per line, for a gateway
+                                          that authenticates ahead of Myelin
+  export HTTPS_PROXY=http://proxy:8080    optional; HTTP_PROXY / NO_PROXY honoured too
 
+<ds> is a dataset slug (any case), an id, or an exact name, as \`datasets\` prints them.
 Every command accepts --json. Exit codes: 0 ok · 1 error · 2 blocked.
 Errors print the API request id — include it when reporting a problem.`)
 }
@@ -1564,15 +1801,14 @@ async function cmdResolve() {
 }
 
 // ——— main ———
-if (!command || command === 'help' || command === '--help') {
-  cmdHelp()
-  process.exit(0)
-}
-if (command === 'version' || command === '--version' || command === '-v') {
-  console.log(JSON_MODE ? JSON.stringify({ version: VERSION }) : VERSION)
-  process.exit(0)
-}
-
+//
+// Order matters, and it is the order a developer without a key needs: help
+// and version answer before the key is looked at, an unknown command is
+// reported as unknown rather than as a missing key, and only a real command
+// about to call the API asks for MYELIN_API_KEY. The previous order checked
+// the key first, so `myelin push --help` and `myelin upload ./x` both answered
+// "Set MYELIN_API_KEY" — the manual was closed to exactly the person waiting
+// for a key (2026-09-19).
 const commands = {
   ping: cmdPing,
   projects: cmdProjects,
@@ -1583,16 +1819,70 @@ const commands = {
   check: cmdCheck,
   push: cmdPush,
   status: cmdStatus,
+  recall: cmdRecall,
   sandbox: cmdSandbox,
   deliveries: cmdDeliveries,
   resolve: cmdResolve,
 }
-try {
-  if (!KEY) die('Set MYELIN_API_KEY (create a key in Bridge → API).')
-  assertProxyEnvUsable()
+
+// The options each command accepts. Anything else spelled `--…` is an error
+// before a byte moves: `push --sumbit` used to upload, not submit, and exit 0
+// — a green CI job that delivered nothing (first-contact review, 2026-09-19).
+// `--json`, `--help` and `-h` are global and handled before this table.
+const OPTIONS = {
+  ping: [],
+  projects: [],
+  datasets: [],
+  'sample-depth': ['dataset'],
+  roles: ['dataset'],
+  contract: ['dataset'],
+  check: ['dataset'],
+  push: ['dataset', 'submit', 'replace'],
+  status: ['watch'],
+  recall: [],
+  sandbox: [],
+  deliveries: ['project', 'dataset', 'since', 'limit', 'cursor'],
+  resolve: [],
+}
+
+async function main() {
+  if (!command || command === 'help' || command === '--help' || command === '-h') return cmdHelp(args[1])
+  if (flag('help') || args.includes('-h')) return cmdHelp(command)
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(JSON_MODE ? JSON.stringify({ version: VERSION }) : VERSION)
+    return
+  }
   const fn = commands[command]
   if (!fn) die(`Unknown command "${command}" — run: myelin help`)
+  const stray = args.slice(1).find((a) => a.startsWith('--') && !OPTIONS[command].includes(a.slice(2)))
+  if (stray) die(`Unknown option "${stray}" for ${command} — run: myelin help ${command}`)
+  // Usage before the key: `myelin push` with nothing else used to answer
+  // "MYELIN_API_KEY is not set" instead of saying what push takes.
+  const NEEDS = {
+    contract: { dataset: true },
+    check: { positional: true, dataset: true },
+    push: { positional: true, dataset: true },
+    'sample-depth': { positional: true, dataset: true },
+    roles: { dataset: true },
+    status: { positional: true },
+    recall: { positional: true },
+    sandbox: { positional: true },
+    resolve: { positional: true },
+  }[command]
+  if (NEEDS) {
+    const positional = args[1]
+    const missingPositional = NEEDS.positional && (!positional || positional.startsWith('--'))
+    if (missingPositional || (NEEDS.dataset && !opt('dataset'))) die(`Usage: ${HELP[command].usage}`)
+  }
+  // The first error every partner sees. It used to say "create a key in
+  // Bridge → API" — an instruction to the one person who cannot do that.
+  if (!KEY) die('MYELIN_API_KEY is not set. Your client creates the key for you (Bridge → API, on their side) and sends it. `myelin help` works without one.')
+  assertProxyEnvUsable()
   await fn()
+}
+
+try {
+  await main()
 } catch (err) {
   // die() already printed and set the code; anything else is a real bug and
   // deserves its stack.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myelinbridge/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Myelin Partner Ingestion CLI — push R&D data deliveries from a pipeline: preflight against the client's quality rules, resumable upload, submit, track review outcomes.",
   "type": "module",
   "bin": {