@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

package/docs/cli-reference.md

@@ -12,20 +12,8 @@ contains the exhaustive recipient, retention and export metadata.
 
 ## Installation
 
-Public releases require Node.js 24 or later. Release verification uses the
-exact Node.js 24 maintainer runtime and separately exercises the installed
-package on Node.js 26:
-
-```bash
-npm exec --yes --ignore-scripts --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
-npm install --global --ignore-scripts @slicedearth/whoisleuth-cli
-whoisleuth doctor
-```
-
-The scoped package and application share one semantic version. The package
-requires no dependency lifecycle scripts and does not call the hosted
-WHOISleuth deployment. From a repository checkout, replace `whoisleuth` with
-`node bin/whoisleuth.mts`.
+Use the [installation guide](cli.md#installation) for runtime requirements,
+installation and updates. The CLI runs locally without a hosted account.
 
 ## Find and inspect commands
 
@@ -46,6 +34,13 @@ command position as Lookup shorthand. Use explicit `lookup` where input needs
 supported URL-like normalisation. Credentials, paths, queries, fragments, ports
 and unsupported special-use targets are rejected by the shorthand.
 
+Explicit `lookup` normally uses only a pasted URL's hostname. Add
+`--deep --exact-url` to collect that page's path and query instead of the
+homepage; fragments are not sent. `--plan` discloses this scope without making
+requests or copying the URL into the plan. Use stdin to keep a sensitive URL
+out of shell history. Saved request provenance omits queries, but paths and
+page-derived text still require review before sharing.
+
 `registry-scaffold` has a separate fixture contract: its `--profile` selects one
 fixed fixture profile and shared `--config` profiles are rejected. It produces
 sanitised local fixture material and makes no registry request.
@@ -63,6 +58,9 @@ disclosures without collecting. Fast is the Lookup default. Deep adds the
 applicable registration, DNS, HTTP, TLS, page, technology and network context.
 Optional browser providers are not implicit CLI actions.
 
+The [message-header review](cli.md#message-header-review) is offline and reports
+publisher claims, not independent DNS or cryptographic validation.
+
 `dnssec-validate` and `mail-transport` are isolated authorised actions. Both
 require a selected literal public resolver, a local trust-anchor document and
 `--owned-or-authorized`; mail transport also requires `--active-probe`. Mail
@@ -70,6 +68,8 @@ transport handles at most three selected MX hosts sequentially, sends `EHLO`
 and uses `STARTTLS` only when advertised. It does not send mail, authenticate,
 test relay, enumerate recipients or retry automatically. DNSSEC, TLSA/DANE,
 PKIX, STARTTLS and SMTP transport remain separate evidence states.
+STARTTLS detection uses the full bounded reply. If the retained capability
+inventory is shortened, the report remains partial and names the omission.
 
 The repository-only rendered-capture package is outside hosted and distributable
 collection. It executes remote page JavaScript only for an explicitly
@@ -84,11 +84,20 @@ refused. Output goes to the terminal unless a command supports `--output`.
 Private output is written atomically and an existing path is refused unless
 replacement is explicit.
 
+`--` ends option processing. All later arguments are literal positional inputs,
+including names such as `--help`. Use `./-evidence.json` for a hyphen-prefixed
+filename when completing paths across shells. Options must precede `--`.
+
 Terminal text is the default. JSON, JSONL, CSV, Markdown, HTML and domain-only
 formats are available only where the installed command declares them.
 Redirected and machine output contains no ANSI or progress text. Diagnostics
 and optional target-free `--events` output use standard error.
 
+For `bulk` and `discover-scan`, `--csv-with-metadata` adds the source schema and
+version, observation and report times, collection origin, scan mode, diagnostic
+version and source-health states. Missing clocks remain `unknown`; a null
+source state is unmeasured, not a negative result. `--csv` keeps the compact columns.
+
 `--fail-on` and `--strict-exit` expose selected evidence states to automation
 without changing the result document. Review focused help for the policies a
 command supports.
@@ -109,16 +118,18 @@ Readers accept only their declared public and current versions. Unknown,
 unreleased historical and future schemas fail before partial interpretation;
 an invalid import is not treated as an empty document.
 
-`inspect-archive` reads current workspace archive v7 and exact versions 5 and 6. It
+`inspect-archive` reads current workspace archive v9 and exact versions 5–8. It
 reports section metadata and digest-only search results unless `--reveal` is
 explicitly selected. It never searches notes, contacts or arbitrary raw fields.
 
 `export` reads supported saved Lookup v1 or v2 and writes current Lookup
-evidence schema 28. Published v2 schema 27 and exact v1 schema 26 remain
-readable. Versions 27 and 28 exclude raw registration payloads, expanded
+evidence schema 29. Published v2 schemas 27 and 28 and exact v1 schema 26 remain
+readable. Versions 27–29 exclude raw registration payloads, expanded
 contacts, credentials, complete query-bearing URLs and provider payloads;
-schema 28 can also retain the bounded, separately attributed registrar-standing
-projection shown by Lookup.
+schemas 28 and 29 also retain the bounded registrar-standing projection.
+Schema 29 identifies the hostname used for DNS, TLS and web observations,
+separately from the registrable domain used by registration sources. Older
+evidence retains its original collection scope.
 
 `verify-artifact` checks a recognised structure and its applicable integrity
 contract. `interchange-report` describes retained and omitted fields.
@@ -126,6 +137,45 @@ contract. `interchange-report` describes retained and omitted fields.
 validity and signer trust separate. None of these checks establishes that
 evidence is accurate, current, safe to share or attributable to a person.
 
+### Signer trust
+
+Use `verify-signature package.json --trust-store-file trust.json --json` to
+check an explicitly selected fingerprint policy offline. The result contains
+the ordinary signature verification and a separate current trust decision.
+Only a matching `trusted` entry succeeds; unknown, `retired`, `revoked` or
+future-reviewed entries return exit code 4, including with `--quiet`.
+Malformed files return 2. Without this option, the existing verification
+output is unchanged. A supplied `--public-key-file` must also match.
+
+The trust file contains no keys. For example:
+
+```json
+{
+  "schema": "whoisleuth.evidence-signer-trust-store",
+  "version": 1,
+  "entries": [{
+    "keyIdSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "label": "Evidence reviewer",
+    "status": "trusted",
+    "updatedAt": "2026-09-01T00:00:00.000Z",
+    "note": "Fingerprint confirmed through the established contact channel."
+  }]
+}
+```
+
+Replace the example fingerprint with the SHA-256 fingerprint of the signer's
+SPKI DER public-key bytes, confirmed through an authenticated channel—not
+merely copied from the package being checked. Review rotation and revocation
+updates through that channel. On rotation, mark the old entry `retired` and
+optionally record `successorKeyIdSha256`; independently confirm and add the
+replacement entry. Use `revoked` for a withdrawn trust decision. Neither a
+successor link nor a claimed signing date overrides current status.
+
+Files support 1,024 distinct entries within 4 MiB. Labels and single-line notes
+allow 160 and 2,048 characters respectively. Reports include only the matching
+entry and the exact file digest. Keep the file and any saved reports under your
+own retention policy. No automatic key discovery, key storage or trust refresh occurs.
+
 ## Command-family boundaries
 
 - Evidence collection commands retain separate source states. A failed or
@@ -137,17 +187,20 @@ evidence is accurate, current, safe to share or attributable to a person.
 - Bulk applies one declared collection contract per target. Fast accepts up to
   500 targets and Deep up to 50; each target remains a separate request.
 - Respond commands package browser-created Cases and prepare local packets,
-  reports and sharing reviews. They do not create durable Cases, submit,
-  publish, notify or grant recipient authorisation.
+  reports and sharing reviews. The offline [`case` workflow](cli.md#local-case-files)
+  also creates and updates ordinary local Case files through explicit, conflict-checked
+  output. Neither workflow submits, publishes, notifies or grants recipient authorisation.
 - Assurance, comparison and calibration commands describe supplied or retained
   evidence. They do not tune the running model, change infrastructure or turn an
   analyst label into observed truth.
 - `workflow-plan` lists fixed installed recipes without executing them.
   `workflow-run` executes only installed steps, requires approval for network
   work and pauses at unresolved analyst selections. Repeat
-  `--select <step-id>=<path-or-value>` in placeholder order to resume a selected
-  step; version-1 checkpoints remain readable and version 2 retains the exact
-  selections in the local checkpoint.
+  `--select <step-id>=<path-or-value>` for remaining placeholders in order, or bind
+  a compatible earlier output with `--use-artifact <step-id>:<input-number>=<earlier-step-id>`.
+  Checkpoints retain exact selections and bindings and distinguish incomplete
+  collection from retryable failures; see [resuming a fixed workflow](cli.md#resuming-a-fixed-workflow)
+  for the supported versions and resume behaviour.
 
 Use the installed focused help for positional inputs, exact ceilings, options,
 network effects, outputs and command-specific exit behaviour.

package/docs/cli.md

@@ -35,6 +35,10 @@ dependency lifecycle scripts. From a repository checkout, replace `whoisleuth`
 with `node bin/whoisleuth.mts`; maintainers can verify the exact package closure
 with `npm run cli:package:check`.
 
+Rendered-page collection uses the separate [optional capture companion](https://github.com/slicedearth/whoisleuth/tree/main/packages/web-capture#install-a-local-candidate),
+not the main CLI. It can be installed from a verified local archive; browser
+installation and each authorised capture remain explicit actions.
+
 ## First commands
 
 Inspect the installed command set and plan one Lookup before collecting:
@@ -56,6 +60,11 @@ whoisleuth lookup example.test --deep --browse
 whoisleuth lookup example.test --deep --markdown --output lookup.md
 ```
 
+Pasted URLs normally select only their hostname. To collect one particular
+page, use `whoisleuth lookup 'https://portal.example.test/review' --deep --exact-url`.
+This sends the path and query to the website, without the fragment. Review
+retained paths and page-derived text before sharing the result.
+
 To continue a reviewed terminal Lookup in the browser, save the completed
 private document from the interactive view:
 
@@ -65,16 +74,21 @@ whoisleuth lookup example.test --deep --browse --save-lookup lookup.json
 
 In Console Lookup, open **Replay exported evidence**, select the file, verify
 its digest and source states, then create or update a browser-local Case. The
-file is not uploaded. Case classification, exact incident links, response
-actions and packet preparation remain deliberate browser steps.
+file is not uploaded. Case classification, exact incident links and response
+actions remain deliberate analyst steps. Ordinary Case files also support the
+offline CLI workflow below.
+When several incident Cases share a domain, select the intended Case before
+retaining replay evidence. Case packs preserve each current Case ID separately;
+trusted and public packs exclude analyst-entered incident titles.
 
 Process selected local input:
 
 ```bash
-whoisleuth bulk domains.txt --csv
+whoisleuth bulk domains.txt --csv-with-metadata
 whoisleuth discover example.test --preset common --jsonl
 whoisleuth verify-artifact lookup.json --json --strict-exit
 whoisleuth compare lookup.json --json
+whoisleuth mail-headers message.eml --json
 whoisleuth brief lookup.json
 ```
 
@@ -82,17 +96,15 @@ One strict domain, IP address or ASN can occupy command position as Lookup
 shorthand. URL-like or ambiguous input requires the explicit `lookup` command.
 Only `bulk` accepts multiple targets.
 
-## Command groups
+`discover` accepts a brand label or registrable domain and supports multi-part
+public suffixes in `--tlds` (for example, `co.uk,com.au`). It preserves the full
+suffix and does not collect candidate evidence; use `discover-scan` only after
+reviewing its separate network plan. Subdomains and URLs are not generation seeds.
 
-The installed registry groups commands under the same analyst vocabulary as the
-application:
+## Command groups
 
-| Group | Common commands |
-| --- | --- |
-| Investigate | `lookup`, `bulk`, `discover`, `ct-search`, `posture`, `http`, `tls`, `compare`, `brief` |
-| Respond | `case-pack`, `change-packet`, `sharing-review`, `export` (local handoff from browser-created Cases) |
-| Assure | `dnssec-validate`, `mail-transport`, `domain-control`, `assurance`, `workflow-plan`, `diff`, `inspect-archive`, `verify-artifact` |
-| Utilities | `doctor`, `commands`, `completion`, `manual`, `registry-scaffold` |
+The installed catalogue groups commands under Investigate, Respond, Assure and
+Utilities, with each command's inputs, output and network boundary.
 
 Filter the canonical index without running the selected commands:
 
@@ -103,12 +115,14 @@ whoisleuth commands --json
 whoisleuth manual | man -l -
 ```
 
-`registry-scaffold` has a separate fixture bootstrap contract: its `--profile`
-selects one fixed fixture profile and it rejects shared `--config` profiles.
-It creates sanitised local fixtures and does not contact a registry.
-
 ## Collection boundaries
 
+For an explicit inherited-policy and direct parent-delegation review, use
+`whoisleuth posture example.test --include-inherited-dns --json`. Without that
+option, posture collection keeps its existing exact-name scope. The extra
+results distinguish recursive policy publication from sampled parent referrals;
+they do not establish name existence, message authentication or DNSSEC validity.
+
 | Mode | Behaviour |
 | --- | --- |
 | Fast Lookup | Registration-first triage without WHOIS or deeper website and TLS collection. |
@@ -122,13 +136,265 @@ their focused help. They do not use the hosted login or hosted usage controls.
 `lookup --plan` lists planned source families and disclosure targets before
 collection. `doctor` is offline unless `--network` is selected.
 
+### Message-header review
+
+`mail-headers` parses only the bounded header block from a selected message file
+or standard input. It extracts domain-only identity, reported SPF, DKIM, DMARC
+and ARC states, exact-domain alignment, and the bounded `Received` route in its
+reported order. It makes no request and does not retain address local parts,
+display names, subject, body, attachments, or raw header values in its output.
+Authentication states are header claims, not an independent DNS or
+cryptographic validation, and alignment differences can be legitimate.
+
 ## Output and automation
 
+### Local Case files
+
+Create a working file, inspect its Case IDs, then append a note:
+
+```sh
+whoisleuth case open --domain example.test --title "Review the selected form" --output cases.json
+whoisleuth case show cases.json
+whoisleuth case note cases.json --note-file note.txt --output cases.json --force
+```
+
+Use `--case-id` when the file contains several Cases. `open` reuses the selected
+Case; `--new-incident --title "Another incident"` creates a distinct ID for the
+same domain. It does not open a browser or collect anything.
+
+`pin`, `assess` and `recheck` read a selected JSON file with `--input`:
+
+```sh
+whoisleuth case pin cases.json --input pin.json --output cases.json --force
+whoisleuth case assess cases.json --input assessment.json --output cases.json --force
+whoisleuth case recheck cases.json --input recheck.json --output cases.json --force
+```
+
+A pin describes the supplied observation, not a new collection. For example:
+
+```json
+{
+  "label": "Selected page observation",
+  "value": "A form was retained in the supplied capture.",
+  "source": "Analyst supplied capture",
+  "observedAt": "2026-09-01T12:00:00.000Z",
+  "completeness": "complete",
+  "sourceState": "complete",
+  "observationHostname": "example.test"
+}
+```
+
+Supply an observation time only when known; use `null` otherwise. Describe
+partial or unavailable evidence honestly. IDs and creation times are allocated
+locally. Unknown fields, truncated values and unsupported formats are rejected.
+
+An assessment includes a reviewed disposition and reason, a summary, a rationale,
+and evidence relationships. Replace `selected-pin-id` with an ID from `case show`:
+
+```json
+{
+  "disposition": "suspicious",
+  "reviewReasonCode": "other_reviewed",
+  "summary": "Review the apparent credential request",
+  "rationale": "The supplied observation needs independent corroboration.",
+  "evidence": [{ "pinId": "selected-pin-id", "stance": "supports" }]
+}
+```
+
+Each fact selects one retained `pinId` or a new `pin` object. Stances are
+`supports`, `contradicts` or `unresolved`; at least one must support the decision.
+Counterevidence and unresolved evidence remain linked, not discarded. Assessment
+summary and rationale use single-line text; note files can contain paragraphs.
+
+A recheck input contains `state`, `observedAt`, `completeness`, `source` and
+`comparisonSummary`, with optional limitations and follow-up time. For example,
+use `state: "unavailable"` and `completeness: "partial"` when a supplied capture
+did not complete. `not_reproduced` requires a saved recheck question from the
+Case's console workflow, its exact `recheck` context, the target
+`observationHostname`, a complete later observation where a baseline exists,
+and `conditionsMatch: "comparable"`. It never means global removal or takedown.
+
+Mutations require an explicit output path and write the complete current Case
+export. They never prune old evidence to fit. Input formatting may use up to
+16 MiB; the canonical store remains limited to 4 MiB and 500 Cases. `show --json`
+can export a selected subset to a **different** path. Ordinary Case imports also
+allow 16 MiB for formatting and export metadata; the stored-data limit remains
+4 MiB. Case packs retain their separate 25-Case selection and 4-MiB source-file
+limits, and include generated reports within the bounded import allowance.
+
+`show` reports the exact file digest. Add `--expect-file-digest sha256:<digest>`
+to reject a file changed since that review. Source/output locks and atomic
+replacement also detect changes during execution. After an interrupted process,
+inspect its adjacent `.workflow.lock` before deliberately removing it. Validation
+or conflict failures leave the Case file unchanged and return 2. Filesystem
+publication failures return 3.
+
+Working files contain private analyst content and file references, not attachment
+bytes. Use `case-pack` for a reviewed audience projection and a separate evidence
+package for selected original files. Nothing is uploaded or reported automatically.
+
+### Portable evidence files
+
+Package selected files without changing their bytes, then verify the ZIP offline:
+
+```sh
+whoisleuth manifest evidence.json screenshot.png --workflow "Evidence review" \
+  --package --output evidence.zip
+whoisleuth verify-artifact evidence.zip --package --json --strict-exit
+whoisleuth manifest evidence.json screenshot.png --workflow "Evidence review" \
+  --folder ./evidence-project
+whoisleuth verify-artifact --folder ./evidence-project --json --strict-exit
+```
+
+Packages admit the 128-file, 64-MiB original selection plus one bounded Case
+export, with a separate manifest allowance. Original-file limits remain unchanged.
+`verify-artifact` uses the same exact ordinary Case reader as `case show`,
+without repairing content. Package verification also reports original-reference
+completeness for each Case file; `--strict-exit` returns 4 when a referenced original is missing.
+An ordinary Case JSON file alone provides structural validity, not a checksum.
+They use generated entry names, not original paths. Ordinary ZIPs and folders
+are private and unencrypted; packaging does not redact selected files. The report distinguishes
+file identity, supported source formats, opaque content, exact capsule/source
+links and capture-manifest attachment matches. Include the capture manifest and
+its screenshot/DOM-digest files together to check their declared bytes; original
+filenames are not needed to establish a match. It does not import files or establish source truth, signature trust or a
+trusted timestamp. Unsupported or rejected entries produce a partial report;
+`--strict-exit` returns 4. Without `--package` or `--folder`, `manifest` produces a
+standalone JSON manifest; exact public version-2 manifests remain readable.
+
+For [BagIt 1.0](https://www.rfc-editor.org/rfc/rfc8493.html) interchange, use
+`--bagit` with `--package` or `--folder` on both commands:
+
+```sh
+whoisleuth manifest evidence.json screenshot.png --workflow "Evidence review" \
+  --bagit --package --output bag.zip
+whoisleuth verify-artifact bag.zip --bagit --package --json --strict-exit
+whoisleuth manifest evidence.json --workflow "Evidence review" --bagit --folder ./bag
+whoisleuth verify-artifact --bagit --folder ./bag --json --strict-exit
+```
+
+BagIt output contains unchanged files under `data/`, SHA-512 payload and tag
+manifests, and the existing source-declaration manifest as a tag file. It is
+unencrypted and cannot be combined with `--passphrase-file`. Verification also
+accepts SHA-256. It checks every manifest, reports absent files and unsupported
+algorithms, and never downloads `fetch.txt` locations. A valid result establishes
+declared byte integrity, not source-format validity, authenticity or factual
+accuracy. Unchecked tags remain explicit; reported entry names are generated.
+
+The bounded reader accepts UTF-8 tags, safe relative paths up to 1,024 UTF-8
+bytes and 16 levels, and the same payload byte/file allowances as evidence
+packages. Tags have a separate allowance of 32 files, 512 KiB each and 2 MiB
+combined. Symbolic links, special files, path collisions and unsupported ZIP
+features are refused. BagIt itself does not impose these implementation limits.
+
+For an encrypted ordinary package, supply a local passphrase file:
+
+```sh
+whoisleuth manifest evidence.json screenshot.png --workflow "Evidence review" \
+  --package --passphrase-file ./package-passphrase.txt --output evidence.wlep
+whoisleuth verify-artifact evidence.wlep --package \
+  --passphrase-file ./package-passphrase.txt --json --strict-exit
+```
+
+The file contains one UTF-8 line of at least 12 characters, at most 1,024 bytes.
+Keep it private and separate from the package. Neither command uploads it or
+includes it in its report. Version-1 encrypted packages protect the entire ZIP,
+including its manifest. Unlocking authenticates the container before validating
+file identities. The report's package digest identifies the decrypted ZIP;
+its input byte count identifies the encrypted file. Wrong passphrases, corrupted
+containers and unsupported versions exit 3 without a verification report.
+Encryption does not establish authorship, factual accuracy or redaction, and
+does not apply to folder exports or separately downloaded JSON backups.
+
+Folders contain `manifest.json` and generated `artifacts/artifact-N` files.
+Creation requires a new destination and never replaces an existing folder.
+Failed writes can leave partial private output; inspect or remove it before
+choosing another destination. Verification rejects symbolic links, unexpected
+trees and unlisted files. Its package digest and byte count describe the
+canonical stored-ZIP representation, not filesystem metadata. These are
+selected evidence exports, not complete workspace backups.
+
+### Resuming a fixed workflow
+
+All recipes listed by `workflow-plan --list` can run through `workflow-run`.
+Planning remains offline. Execution emits a checkpoint; terminal output shows
+retained steps, output identities, missing inputs and the next required action.
+A partial collection
+pauses for review; resuming keeps that observation and does not collect it
+again. Later steps can finish without making the earlier evidence complete:
+the run still exits with code 4. Validation, usage and export failures remain
+failures and are retried on resume. Step diagnostics stay on stderr, separate
+from checkpoint JSON. New network steps still need `--approve-network`.
+
+New runs connect compatible earlier outputs for domain triage, registry review,
+historical comparison and handoff linting. For a complete domain-triage hand-off:
+
+```sh
+whoisleuth workflow-run domain-triage example.test --approve-network \
+  --json --output run.json
+```
+
+Bindings accept Lookup outputs for export, diff, timeline, comparison, source
+reports and briefs; evidence exports for verification; and Case-pack output
+for sharing review. Remaining placeholders use `--select` in order;
+for example, `--select diff=previous.json` keeps the current observation as the
+second input. Supply every input for an uncompleted step to use files instead,
+or override a connection with `--use-artifact <step-id>:<input-number>=<earlier-step-id>`.
+Input numbers start at 1 and refer to the fixed recipe's placeholders.
+`diff` compares saved observations of the same or different domains; `timeline`
+orders observations of one domain. Candidate and domain-control intent inputs
+remain analyst selections. No external file is inferred or extracted automatically.
+`reconcile` lists each observation time and declared observer/vantage, keeping
+disagreement and unavailable evidence separate. Distinct labels do not verify
+independent collection; timing and shared caches can affect the comparison.
+
+For example, registry review can reuse its collection without extracting files:
+
+```sh
+whoisleuth workflow-run registry-disagreement example.test --approve-network \
+  --json --output registry-run.json
+```
+
+The evidence-handoff recipe pauses before any human-review declaration. Review
+the selected material and the listed declarations, then use
+`--confirm-review package` or `--confirm-review lint` for that particular step.
+Confirmation applies only to the current invocation and is not inferred from
+the checkpoint. A completed recipe means its commands ran, not that an
+investigation is resolved or sharing is authorised.
+
+Optional `--interactive` asks for missing paths or values on terminal stderr,
+keeping checkpoint JSON on stdout or in the selected output file. A blank answer
+pauses. Prompts do not grant network approval or confirm review. Redirected input
+and unattended runs use `--select` instead. Resuming a checkpoint preserves its
+recorded connections; new defaults are not applied to old checkpoints.
+
+Checkpoint version 3 reads versions 1 and 2. Older installations reject version
+3. Checkpoints retain exact output schemas, content digests and input bindings;
+changed identities or completed inputs are rejected. Digests identify content,
+not source authenticity, truth or freshness. The checkpoint can contain
+selected local paths and evidence; review it before sharing.
+
+Use `--json --output state.json` for a resumable file, and add `--force` when
+replacing it. File output holds private adjacent `.workflow.lock` files for
+the selected resume and output paths until publication. Another writer is
+refused; changes to either file during execution prevent replacement. State
+files must be regular files without symbolic or additional hard links.
+
+Locks contain only a local process ID and are removed after the run. Following
+an interrupted process, confirm that its owner has stopped before removing its
+abandoned lock. Locks have no automatic expiry. Shell redirection and external
+editors do not participate in this cooperative file-ownership protocol.
+
+### Formats and exit behaviour
+
 Terminal text is the default. Commands expose JSON, JSONL, CSV, Markdown, HTML
 or domain-only output only where declared by the installed registry. Redirected
 and machine output contains no ANSI or transient progress text.
 
 - `--summary` and `--verbose` change presentation, not collection.
+  Verbose Lookup includes retained technology signals and library advisory
+  identifiers. Their source times are separate; ages are measured at output
+  generation, not at a later replay.
 - `lookup --browse` provides an interactive terminal view; press `?` for keys.
 - `--events` writes versioned lifecycle events to stderr.
 - `--strict-exit` and `--fail-on` expose selected evidence states to automation.
@@ -140,17 +406,26 @@ concurrency and observer labels. They cannot add targets, enable Deep
 collection, choose output paths or approve network work. Explicit command
 options override profile defaults.
 
+`source-report` summarises collector-owned health envelopes in saved Lookup
+and Bulk output. Raw publications and extension fields are not interpreted as
+diagnostics, and missing health metadata remains unmeasured.
+
+`mail-review` keeps failed input targets, incomplete DNS coverage and original
+collection times visible. Source-output and review-generation times do not
+stand in for missing observation times. `domain-change` and
+`domain-change-packet` retain authority, resolver and certificate observation
+times; previously published version-2 packets remain verifiable.
+
 ## Exit codes
 
-| Code | Meaning |
-| ---: | --- |
-| 0 | The command completed. |
-| 2 | Invalid command, option or input. |
-| 3 | Collection, lookup or comparison failed. |
-| 4 | The result was partial or a selected evidence policy was not met. |
-| 70 | Internal CLI bootstrap failure. |
-| 130 | The analyst cancelled the command. |
-| 143 | The process received SIGTERM. |
+See the [exit-code reference](cli-reference.md#files-output-and-automation).
+A completed command can still contain partial sources; use the selected
+command's strict-exit policy when automation requires complete evidence.
+
+For scripts, use `whoisleuth verify-artifact evidence.json --json --strict-exit`.
+An incomplete verification returns **4** with that option. Without it, **0**
+means a report was produced, not that the artefact passed verification; inspect
+the report's state and checks.
 
 ## Command details
 

package/lib/abort.mjs

@@ -10,7 +10,10 @@ function abortable(operation, signal) {
         const aborted = () => reject(abortReason(signal));
         signal.addEventListener('abort', aborted, { once: true });
         Promise.resolve()
-            .then(operation)
+            .then(() => {
+            signal.throwIfAborted();
+            return operation();
+        })
             .then(resolve, reject)
             .finally(() => signal.removeEventListener('abort', aborted));
     });