@myelinbridge/cli 0.12.2 → 0.14.0

package/README.md

@@ -1,202 +1,386 @@
 # @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.
+
+## First delivery
+
+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_…     # 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
+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
 ```
 
-- **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.
-- **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.
+That is the whole path. Four things worth knowing about it:
 
-## If you are the client, not the partner
+- **`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.
+
+```
+$ 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.
+```
+
+### Two optional declarations
+
+- **`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
 
-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?*
+`<ds>` is a dataset slug (any case), an id, or an exact name, as `datasets` prints them.
 
-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.
+| 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`).
 
 ```bash
-export MYELIN_API_KEY=myl_live_…
+myelin check "$OUT" --dataset onco1-wes || exit $?
+myelin push  "$OUT" --dataset onco1-wes --submit
+```
+
+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 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
 
-# What has landed, newest first (page with --cursor from the printed next_cursor)
-myelin deliveries --dataset <dataset-id>
+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.
 
-# What is this object, exactly?
+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
+
+| Variable | |
+|---|---|
+| `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. 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 batch 7 (Genomics)
+#     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
-#     file      reads.fastq.gz · 4096 bytes
 ```
 
-`resolve` accepts a full `gs://`/`s3://` URI, a bare prefix, or a single id, and answers at
-whatever granularity the path supports.
-
 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.
+`_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.
 
-A partner key calling these gets `403 wrong_key_side`, and vice versa.
+## For your IT department
 
-## Machine mode
+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.
 
-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).
+### What the CLI needs to reach
 
-`check --json` carries the numbers to branch on rather than the prose:
+Outbound **TCP 443 only**, to two hosts:
 
-| Field | |
+| Host | Why |
 |---|---|
-| `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.
+| `myelinbridge.com` | the API — auth, the quality contract, preflight, part signing, submit, status |
+| `cdjlhyyrbogzkoaujzmj.storage.supabase.co` | the bytes — uploads go **straight to storage** over short-lived presigned URLs, never through the API host |
 
-## Environment
+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.
+That failure names the host it could not reach, so the allowlist gap is legible from
+the error.
 
-| Variable | |
-|---|---|
-| `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`. |
+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
+#   connect-src 'self' https://<ref>.supabase.co wss://<ref>.supabase.co https://<ref>.storage.supabase.co
+```
+
+A wildcard rule works if your proxy prefers one: `*.supabase.co`.
+
+### What a person using the web portal needs
+
+Someone reviewing a delivery in a browser needs the two hosts above **plus** the
+Supabase API host, because sign-in and the session live there:
+
+| Host | Port | Why |
+|---|---|---|
+| `myelinbridge.com` | 443 | the application itself |
+| `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.
+
+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 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:
+
+```bash
+export HTTPS_PROXY=http://proxy.corp.example:8080
+export NO_PROXY=.corp.example,10.0.0.0/8
+myelin ping        # prints "via proxy http://proxy.corp.example:8080" when one is in use
+```
+
+- `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.
+- **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`.
 
 ## 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=…`.