@slicedearth/whoisleuth-cli 1.45.0 → 2.0.0

package/docs/cli-reference.md

@@ -1,25 +1,18 @@
 # WHOISleuth CLI reference
 
-This complete reference documents every supported command contract. For a
-short installation and first-use path, start with the [CLI guide](cli.md).
+The WHOISleuth CLI runs locally. Installed `whoisleuth <command> --help`,
+`whoisleuth commands` and `whoisleuth manual` are the exact grammar, option and
+command authorities for that installed version. The public
+[CLI reference](https://whoisleuth.com/cli) provides a searchable view generated
+from the same registry.
 
-The first-party command-line interface runs the same local classification and
-lookup modules as the Express and serverless adapters. It does not call the
-hosted WHOISleuth deployment.
-
-`whoisleuth --help` displays the copyright, AGPL-3.0-only licence, and official
-source location. It groups commands by investigation, discovery, saved-evidence,
-integrity, and calibration workflows. `whoisleuth <command> --help` displays the
-command's purpose, focused invocation, example, and collection boundary without
-printing the full command list. `whoisleuth commands --json` exposes those same
-contracts as a stable local catalogue for wrappers and terminal tooling.
-Packaged copies include `LICENSE`, `NOTICE`, and
-`TRADEMARKS.md` alongside the CLI documentation.
+This page records the common interfaces and the boundaries that matter across
+commands. The generated [privacy/data-flow catalogue](https://github.com/slicedearth/whoisleuth/blob/main/docs/privacy-data-flow-catalogue.md)
+contains the exhaustive recipient, retention and export metadata.
 
 ## Installation
 
-Public releases require Node.js 24 or later and install the `whoisleuth`
-command:
+Public releases require Node.js 24 or later:
 
 ```bash
 npm exec --yes --ignore-scripts --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
@@ -27,1329 +20,127 @@ npm install --global --ignore-scripts @slicedearth/whoisleuth-cli
 whoisleuth doctor
 ```
 
-Update and verify an existing global installation with:
-
-```bash
-npm install --global --ignore-scripts @slicedearth/whoisleuth-cli@latest
-whoisleuth --version
-```
-
-The scoped package and application share one semantic version. The package runs
-locally and does not call the hosted WHOISleuth deployment. Networked commands
-contact only the sources described by their collection profile; offline review,
-comparison, verification, completion, and manual commands remain local.
-
-## Commands
+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`.
 
-```bash
-node bin/whoisleuth.mts lookup example.com
-node bin/whoisleuth.mts lookup AS13335 --json
-printf 'example.com\n' | node bin/whoisleuth.mts lookup --json
-node bin/whoisleuth.mts lookup example.com --deep
-node bin/whoisleuth.mts lookup example.com --deep --plan --json
-node bin/whoisleuth.mts lookup example.com --deep --summary
-node bin/whoisleuth.mts lookup example.com --deep --verbose
-node bin/whoisleuth.mts lookup example.com --deep --markdown --output lookup.md
-node bin/whoisleuth.mts lookup example.com --deep --json --strict-exit --events
-node bin/whoisleuth.mts lookup example.test --deep --observer workstation-a --vantage office-egress --json > office.json
-cat domains.txt | node bin/whoisleuth.mts bulk --jsonl
-node bin/whoisleuth.mts bulk domains.txt --csv --registered-only
-node bin/whoisleuth.mts bulk domains.txt --domains --inconclusive-only
-node bin/whoisleuth.mts bulk domains.txt --queries --errors-only
-node bin/whoisleuth.mts bulk domains.txt --concurrency 4
-node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json
-node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json --resume
-node bin/whoisleuth.mts ct-search 'example brand' --json
-node bin/whoisleuth.mts discover example.com --preset common --jsonl
-node bin/whoisleuth.mts discover example.test --dictionary private-terms.txt --snapshot discovery-state.json --json
-node bin/whoisleuth.mts discover-scan example.test --scan-limit 50 --checkpoint candidate-scan.json --json
-node bin/whoisleuth.mts discover-scan example.test --deep --scan-limit 20 --resolver 192.0.2.53 --observation-snapshot observed-candidates.json --csv
-node bin/whoisleuth.mts posture example.com --selectors selector1 --retired-selectors selector0 --mail-profile defensive-no-mail --json
-node bin/whoisleuth.mts http example.com --json
-node bin/whoisleuth.mts tls example.com --json
-node bin/whoisleuth.mts registry-support example.uk --json
-node bin/whoisleuth.mts registry-doctor lookup.json --json
-node bin/whoisleuth.mts registry-cohort saved-lookups.jsonl --json
-node bin/whoisleuth.mts registry-scaffold --profile example-profile --suffix test --scenario registered
-node bin/whoisleuth.mts risk-calibrate calibration.json --json
-node bin/whoisleuth.mts lookalike-calibrate reviewed-candidates.json --json
-node bin/whoisleuth.mts verify-artifact workspace.json --json
-node bin/whoisleuth.mts verify-artifact lookup.json --json
-node bin/whoisleuth.mts verify-artifact workspace-encrypted.json --passphrase-file passphrase.txt --json
-node bin/whoisleuth.mts source-report lookup.json --json
-node bin/whoisleuth.mts inspect-archive workspace.json --json
-node bin/whoisleuth.mts inspect-archive workspace.json --search example.invalid --json
-node bin/whoisleuth.mts sign-artifact response-packet.json --private-key-file analyst-private.pem > response-packet.signed.json
-node bin/whoisleuth.mts ct-intake certificate-events.json --json > external-findings.json
-node bin/whoisleuth.mts map-observations observation-mapping.json --json > external-findings.json
-node bin/whoisleuth.mts oam-export external-findings.json --json > asset-bridge.json
-node bin/whoisleuth.mts manifest lookup.json comparison.json --workflow 'domain review' --json > investigation-manifest.json
-node bin/whoisleuth.mts verify-signature response-packet.signed.json --public-key-file analyst-public.pem
-node bin/whoisleuth.mts lookup example.com --deep --json > lookup.json
-node bin/whoisleuth.mts compare lookup.json --json
-node bin/whoisleuth.mts page-compare official.json candidate.json --json
-node bin/whoisleuth.mts mail-review bulk.json --json
-node bin/whoisleuth.mts review-evidence dnssec-evidence.json --json
-node bin/whoisleuth.mts review-evidence trust-store-comparison.json --json
-node bin/whoisleuth.mts domain-control domain-control-input.json --json
-node bin/whoisleuth.mts assurance domain-assurance-input.json --json
-node bin/whoisleuth.mts change-packet domain-change-packet-input.json --json
-node bin/whoisleuth.mts sharing-review response-packet.json --marking amber --recipient-scope organization --purpose 'Reviewed incident handoff' --human-reviewed --personal-data-reviewed --redactions-confirmed --json
-node bin/whoisleuth.mts workflow-plan domain-triage example.test --json
-node bin/whoisleuth.mts workflow-run domain-triage example.test --approve-network --json --output run.json
-node bin/whoisleuth.mts brief lookup.json
-node bin/whoisleuth.mts case-pack cases.json --audience trusted --reviewed --json
-node bin/whoisleuth.mts monitor-once control-manifest.json --previous prior-control.json --junit
-node bin/whoisleuth.mts diff first-lookup.json second-lookup.json --json
-node bin/whoisleuth.mts reconcile office.json mobile.json external.json --json
-node bin/whoisleuth.mts timeline first-observation.json second-observation.json latest-observation.json --json
-node bin/whoisleuth.mts export lookup.json > evidence.json
-node bin/whoisleuth.mts export lookup.json --markdown > evidence.md
-node bin/whoisleuth.mts export lookup.json --html > evidence.html
-node bin/whoisleuth.mts doctor
-node bin/whoisleuth.mts doctor --network --json
-node bin/whoisleuth.mts commands --json
-node bin/whoisleuth.mts completion zsh
-node bin/whoisleuth.mts completion powershell
-node bin/whoisleuth.mts manual | man -l -
-```
-
-These examples run from a checked-out repository; replace
-`node bin/whoisleuth.mts` with `whoisleuth` after installation. The root
-application package remains private. A separate scoped CLI archive is assembled
-from the exact executable dependency closure, installed in a temporary
-directory, and smoke tested with:
+## Find and inspect commands
 
 ```bash
-npm run cli:package:check
-```
-
-The check includes only the executable, reachable TypeScript modules, CLI
-guide, licence, notices, and trademark terms. It excludes application routes,
-deployment adapters, tests, and development tools. Direct runtime dependencies
-are pinned to the exact versions exercised by the reviewed repository lockfile.
-The package and its dependencies require no lifecycle scripts, so the install
-examples disable them explicitly.
-Its generated manifest stays private. Release-candidate assembly is a separate
-explicit operation and never publishes from a developer checkout. Use the
-scoped package name; an unqualified `npx whoisleuth` is not this project.
-
-Lookup defaults to the conservative fast profile. `--deep` must be requested
-explicitly and can add bounded WHOIS, DNS, website, TLS, registrar RDAP, and
-observed-network IP RDAP work for a domain. The browser Console's optional
-security.txt and external intelligence selections are not CLI flags; the CLI
-does not run those actions implicitly.
-
-For a directly entered public IP address, `lookup --deep` can also run one
-bounded reverse-DNS query. Terminal output shows the explicit source state and
-up to five normalised PTR names; JSON retains up to eight. PTR names are
-operator-published routing context, not proof of hosting control or ownership.
-Fast lookups do not run this query.
-
-`lookup --plan` performs classification and prints a versioned preflight without
-starting collection. It lists the normalised target, selected fast or deep
-mode, planned source families, conditional operations, and the data each family
-may receive. The plan cannot predict live feature configuration, cache state,
-redirects, referrals, source availability, or an exact request count. It can be
-combined with `--json`, but not with report, detail, strict-exit, progress-event,
-or quiet options.
-
-Only one query is accepted by `lookup`. Multiple-input processing belongs to
-the explicit `bulk` command rather than being silently inferred by `lookup`.
-Standard input is capped at 4 KiB and must contain one non-empty line.
-
-`registry-support` is an offline catalogue view. It accepts one domain, bare
-suffix, or leading-dot suffix as an argument or on stdin and makes no network
-request. Its output is described below.
-
-`doctor` is offline by default. It checks the Node runtime, platform, terminal
-capabilities, and availability of offline command families. `doctor --network`
-adds independent bounded public-DNS, HTTPS/RDAP bootstrap, and WHOIS port 43
-checks against fixed IANA diagnostic infrastructure. The three probes run
-within the same per-probe ceiling so one stalled transport does not block the
-others. The report retains only state, HTTP status, and a bounded explanation,
-not resolved addresses or response content. A failed optional network check
-returns the partial-failure exit code rather than claiming that all CLI
-collection is unavailable.
-
-`completion bash`, `completion zsh`, `completion fish`, and `completion
-powershell` print static shell completion scripts to stdout. The command does
-not edit a shell profile or make a network request. Review the generated script
-before sourcing it or placing it in the relevant shell completion directory.
-`manual` prints a generated roff manual page and likewise changes no local
-configuration.
-
-`commands` prints the installed command catalogue without running collection or
-reading evidence. `commands --json` emits version 1 of the
-`whoisleuth.cli.command-catalogue` schema, including each command's usage,
-example, declared collection mode, collection scope, and boundary. This is the
-supported discovery contract for local wrappers; it is not a permission grant
-or a substitute for focused help.
-
-Focused command help and the generated manual classify every operation as
-offline or networked and state the relevant target, input, and concurrency
-ceiling. These labels describe observable behaviour rather than granting
-authorisation. The packaged `DISCLOSURE` defines the intended defensive scope;
-operators remain responsible for law, provider terms, and authorisation.
-
-## Deployment boundary
-
-The CLI runs locally. The serverless deployment publishes only `frontend/build`
-and packages functions only from `netlify/functions`, so `bin/` and `cli/` are
-not part of the hosted static site or function bundle. The application root and
-ordinary package-check candidate remain private. Explicitly reviewed CLI
-release candidates can be published under the scoped public package described
-in the installation section.
-
-Commands that query RDAP, WHOIS, DNS, HTTP, TLS, or Certificate Transparency do
-so directly from the machine running the CLI. They do not use the hosted login,
-hosted session, or deployment usage controls; upstream providers can see and
-rate-limit the local machine's network address. Offline `discover`, `compare`,
-`page-compare`, `mail-review`, `review-evidence`, `domain-control`, `assurance`, `change-packet`,
-`sharing-review`, `workflow-plan`, `brief`, `case-pack`, `registry-cohort`,
-`registry-scaffold`, `diff`, `reconcile`, `timeline`,
-`risk-calibrate`, `lookalike-calibrate`, `registry-doctor`, `verify-artifact`, `source-report`,
-`map-observations`, `oam-export`, `export`,
-`commands`, `completion`, and `manual` operations make no network requests. Commands write
-to stdout unless the analyst deliberately selects a local output file.
-
-## Output
-
-Human-readable terminal output is the default. On an interactive terminal it
-uses restrained semantic colour, groups Lookup evidence by purpose, wraps
-prose to the detected terminal width, and shows transient progress on stderr
-for slower collection. State remains explicit in text, so colour is never the
-only distinction. Redirected terminal output, JSON, and JSONL contain no ANSI
-sequences or progress text. `--no-color` and a non-empty conventional
-`NO_COLOR` environment variable disable colour; `WHOISLEUTH_NO_PROGRESS=1`
-disables the transient indicator. Command examples remain one copyable line
-even when prose is wrapped for a narrow terminal.
-
-Every command accepts `--output <file>` as a safer alternative to shell
-redirection. WHOISleuth buffers bounded output, creates a private temporary file
-beside the destination, syncs it, and publishes it atomically with mode `0600`.
-An existing destination is refused. `--force` is valid only with `--output` and
-allows an intentional atomic replacement. A failed or cancelled command does
-not publish a partial output file. Output is capped at 32 MiB.
-
-`--config <file> --profile <name>` reads a strict version-1 local configuration
-document of at most 64 KiB. Without `--config`, the path is
-`$XDG_CONFIG_HOME/whoisleuth/config.json`. A profile may contain no more than
-16 safe defaults drawn from `--no-color`, `--summary`, `--verbose`, `--fast`,
-`--concurrency`, `--observer`, and `--vantage`. It cannot supply a target,
-Deep mode, output path, network approval, failure policy, credential, or
-arbitrary argument. Explicit command options override profile defaults from
-the same group.
-
-Lookup, Bulk, and `monitor-once` can emit bounded JUnit XML. Owned-domain
-Posture can emit SARIF only when `--owned-domain` confirms the passive target
-boundary. The reports contain categorical source or posture findings rather
-than raw evidence. Supported network commands accept an explicit comma-
-separated `--fail-on` policy from `source-failure`, `inconclusive`, `danger`,
-and `material-drift`; a match returns the partial-result exit code after the
-normal output is emitted.
-
-`lookup --markdown` and `lookup --html` build the existing normalised evidence
-report directly after one completed domain lookup. They do not start a second
-collection. These report formats reject IP and ASN inputs before collection;
-JSON and terminal output remain available for those query types.
-
-Lookup terminal output supports three detail levels. The standard view keeps
-the normal bounded evidence summary. `--summary` keeps the source states and
-key findings while omitting endpoints and supporting detail. `--verbose` adds
-the document generation time and the existing bounded per-source collection
-timings. These switches are presentation-only and cannot be combined with
-`--json`; they do not change collection or the result document.
-
-`--json` writes one versioned document to standard output:
-
-```json
-{
-  "schema": "whoisleuth.cli.lookup",
-  "version": 1,
-  "generatedAt": "2026-07-14T00:00:00.000Z",
-  "mode": "fast",
-  "query": "example.com",
-  "type": "domain"
-}
+whoisleuth --help
+whoisleuth commands --common
+whoisleuth commands --group investigate --mode network
+whoisleuth lookup --help
+whoisleuth lookup example.test --deep --plan --json
 ```
 
-The complete document also carries the normalised `rdap`, `whois`,
-`availability`, and `diagnostics` sections returned by the shared lookup
-orchestrator. Machine output goes to stdout. Usage and lookup errors go to
-stderr, so redirected JSON is not mixed with diagnostics.
-
-Human-readable domain lookup output separately shows the registrar RDAP status
-and endpoint whenever the shared lookup diagnostics represent that follow-up.
-Deep mode may report success, unsupported, not found, or an explicit failure;
-fast mode reports the existing skipped state. IP, ASN, and lookup responses
-without registrar diagnostics remain unchanged. These source states are
-provenance only and do not decide availability or imply safety.
-
-When a deep domain response includes registry interpretation version 1, the
-terminal summary also shows the lifecycle label, separately attributed RDAP and
-WHOIS disclosure states, reconciliation state, and complete, partial, and
-unavailable publication counts. It does not print published contact routes.
-The JSON document retains the bounded interpretation and its limitations.
-
-A deep domain lookup can also show the status, selected public address, and
-registered network name from the bounded observed network context. It uses the
-same address and IP RDAP source represented in the JSON document. This is
-point-in-time edge or network-registration context, not proof of the origin
-host, hosting control, ownership, intent, or maliciousness. Fast and compact
-commands do not run the enrichment.
-
-The deep terminal summary also reports the website activity state, page title,
-DNS, HTTP, and TLS source states, bounded publisher-declared structured
-identity entities, up to six bounded technology indicators, a browser-library
-profile count, and the four passive security-posture counts.
-These are concise projections of the same evidence already present in the
-lookup response. The browser-library line counts apparent components and
-catalogue advisory matches without retaining script references or raw
-signatures. These summaries make no extra request, omit raw evidence
-descriptions, and do not turn a technology or advisory match, or a missing
-posture signal, into proof of exploitability, hosting control, ownership, or
-maliciousness. Use `--json` when the full bounded evidence, limitations, and
-source diagnostics are required.
-
-`lookup --strict-exit` is an opt-in automation policy. It still emits the
-ordinary complete output document, but returns exit code 4 when a requested
-diagnostic source is partial, unavailable, rate-limited, timed out, or failed.
-The default exit contract remains unchanged, so inconclusive source health does
-not silently break existing scripts.
-
-`lookup --events` and `bulk --events` write versioned
-`whoisleuth.cli.progress` version 1 JSONL lifecycle events to stderr while the
-ordinary final result stays on stdout. Events contain only the command,
-sequence, time, source state or Bulk item index, categorical failure reasons,
-and final exit status. They do not contain a target, query, endpoint, file
-path, error detail, or evidence value. Human progress and error text are
-suppressed while events are active. `--events` cannot be combined with
-`--output`, because the final event must describe the same completed stdout
-delivery observed by the caller.
-
-Pressing Ctrl-C asks an in-flight Lookup or Bulk run to stop, suppresses any
-partial final result, flushes an enabled Bulk checkpoint, and exits with code
-130. SIGTERM follows the same graceful cleanup path and exits with code 143.
-Already started network operations remain subject to their existing hard
-timeouts while the shared in-process API unwinds; the executable terminates
-after CLI cleanup. A second Ctrl-C removes any known unpublished temporary
-output file on a best-effort basis before exiting immediately.
-
-Bulk can persist compact progress with `--checkpoint <file>`. A new checkpoint
-is private, bounded to 16 MiB, versioned, and tied to the exact ordered input
-and scan mode by SHA-256. It stores only compact per-item results, never full
-Lookup responses. Checkpoint schema 2 records a nullable per-row observation
-time. Schema 1 remains readable, but its resumed rows keep observation time
-unknown rather than inheriting the resume time. Reusing the same path is
-refused unless `--resume` is also
-specified. Resume revalidates the complete untrusted document and skips only
-the exact completed rows; changed input, mode, schema, digest, or malformed
-results fail closed.
-
-Bulk JSON, JSONL, and item documents use schema version 3. Each row includes
-`observedAt` and a `collectionOrigin` of `current_run` or
-`resumed_checkpoint`; the top-level `generatedAt` remains the report creation
-time. HTTP JSON uses schema version 2 and adds the explicit `assessment` field.
-The legacy `activityStatus` field remains for compatibility, but is `null`
-when collection is inconclusive rather than labelling the target unreachable.
-Consumers should use `assessment`; older version-1 `unreachable` values remain
-historical inconclusive labels, not proof that a target cannot be reached.
-
-If checkpoint persistence fails after collection, WHOISleuth still emits the
-completed final result, reports the checkpoint limitation, and exits with code
-4. The last successfully published checkpoint remains available, but it may
-not contain the final completed items.
-
-`diff <left.json> <right.json>` compares two different saved domain Lookup
-documents entirely offline. It reuses the bounded Bulk comparison model for
-registration, DNS, page identity, mail, certificate, and relationship fields,
-keeps missing and unavailable evidence distinct, and makes no ownership or
-maliciousness inference. The output records both original observation times.
-
-`lookup --observer <label> --vantage <label>` can add two bounded analyst labels
-to a saved Lookup document. The labels identify the person or process that ran
-the observation and the collection context chosen by that analyst; they are
-not verified identities, network measurements, or proof of independent
-collection. They do not change which sources are queried.
-
-`reconcile <observation.json> <observation.json> [...]` accepts from 2 to 5
-saved Lookup documents for the same domain and compares their bounded fields
-offline. It keeps agreement, disagreement, and non-comparable evidence
-separate, retains observation times and optional analyst labels, and copies no
-filenames or raw registration payloads. Distinct complete label pairs are
-reported as labelled collection contexts only; majority agreement is not
-treated as truth or authority.
-
-`timeline <observation.json> <observation.json> [...]` accepts from 2 to 20
-saved Lookup documents for one domain, orders them by their validated
-observation times, and compares each adjacent pair offline. The 32 MiB aggregate
-input ceiling is enforced while files are read and again by the timeline
-builder. Output retains normalised field states and observation times but no
-input filenames or raw registry payloads. A difference can reflect a domain
-change or changed collection conditions, so the command makes no current-state,
-ownership, intent, safety, or maliciousness conclusion.
-
-When diagnostics version 5, 6, 7, or 8 reports a documented registry collection
-constraint, terminal output also shows the suffix, WHOIS and RDAP access
-profiles, and the bounded limitation. This is static access-policy context: it
-does not make another request, and restricted, unpublished, or unavailable
-machine access is not evidence that a domain is unregistered or safe.
-
-## Exit codes
+The command index groups work under Investigate, Respond, Assure and Utilities.
+Filters combine by intersection. `commands --json` emits the versioned local
+catalogue without reading evidence or running the selected commands.
+
+An eligible domain, reserved documentation domain, IP address or ASN can occupy
+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.
+
+`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.
+
+## Requests and authorisation
+
+Offline commands read only supplied arguments, files, standard input and
+installed catalogues. Networked commands contact the sources named by their
+focused help; those sources can observe and rate-limit the operator's network
+address. The CLI does not inherit hosted login, provider configuration or
+hosted operation limits.
+
+`lookup --plan` classifies a target and lists intended source families and
+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.
+
+`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
+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.
+
+The repository-only rendered-capture package is outside hosted and distributable
+collection. It executes remote page JavaScript only for an explicitly
+authorised route set, and each admitted resource operator receives the exact
+requested URL. Captures and screenshots remain local until the operator deletes
+them.
+
+## Files, output and automation
+
+File inputs are bounded before parsing; directories, devices and named pipes are
+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.
+
+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.
+
+`--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.
 
 | Code | Meaning |
 | ---: | --- |
-| 0 | Command completed. Individual sources may still be partial or inconclusive; inspect diagnostics. |
-| 2 | Invalid command, option, input, or stdin shape. |
-| 3 | The requested lookup, collection, or comparison operation could not run. |
-| 4 | A bounded operation completed partially, such as Bulk item failures or failed explicit Doctor network checks. |
-| 70 | Unexpected CLI bootstrap failure. |
-| 130 | The analyst cancelled the command. No partial final result was emitted. |
-| 143 | The process received SIGTERM. No partial final result was emitted. |
-
-This release supports `lookup`, `bulk`, `ct-search`, `ct-intake`, `map-observations`, `oam-export`, `discover`, `discover-scan`, `posture`,
-`http`, `tls`, `registry-support`, `registry-doctor`, `registry-cohort`, `registry-scaffold`, `risk-calibrate`,
-`lookalike-calibrate`, `verify-artifact`,
-`inspect-archive`, `manifest`, `sign-artifact`, `verify-signature`, `source-report`,
-`compare`, `page-compare`, `mail-review`, `review-evidence`, `brief`, `case-pack`, `domain-control`,
-`monitor-once`, `assurance`, `change-packet`, `sharing-review`, `workflow-plan`, `workflow-run`, `diff`, `reconcile`, `timeline`,
-`export`, `doctor`, `commands`, `completion`, and `manual`. Additional command families
-are added as separate bounded increments rather than exposing incomplete
-aliases.
-
-## Registry capability coverage
-
-`registry-support` projects the embedded, versioned registry compatibility
-catalogue for one domain or suffix. It distinguishes an explicit
-fixture-backed or access-documented suffix profile from the generic IANA
-discovery profile and reports the RDAP and WHOIS discovery/access paths,
-WHOIS query and parser profiles, fixture scenarios,
-verification references, documentation references, and the catalogue's
-limitation. The same document includes a dated, official-source aggregate of
-generic, generic-restricted, sponsored, and infrastructure RDAP coverage. That
-snapshot is separate from the suffix profile and from live reachability.
-
-Terminal output is bounded and control-safe. `--json` emits version 3 of the
-`whoisleuth.cli.registry-support` schema. Unknown but syntactically valid
-suffixes retain the generic `discovery_only` profile; malformed input exits
-with code 2. The command never probes a registry or tests current reachability.
-Coverage is context only and cannot decide registration, availability,
-ownership, safety, or maliciousness.
-
-`registry-doctor [lookup.json]` compares one saved domain Lookup with the same
-reviewed local capability profile. It reports whether RDAP and WHOIS collection
-states align with allowed, permission-required, or unsupported access, counts
-bounded normalised publication fields, and reports publication-quality context
-for object identity, base conformance, redaction metadata, required self links,
-and event consistency. A missing identifier or metadata field is a publication
-omission, not a failed lookup. The command is offline, makes no retry, and
-cannot establish current registry reachability.
-
-`registry-cohort [lookups.json|lookups.jsonl]` aggregates from 1 to 500 saved
-Lookups into suffix and capability-profile cohorts. It retains only target-free
-counts for source alignment and publication-quality states. A cohort with
-fewer than five samples is labelled insufficient rather than treated as a
-quality result, and repeated observations from one environment are not assumed
-representative.
-
-`registry-scaffold --profile <id> --suffix <suffix> --scenario <state>` emits
-one bounded, sanitised synthetic fixture scaffold from the installed registry
-catalogue. The three supported states are `registered`, `not_found`, and
-`inconclusive`. It does not fetch a live response, include a real target, or
-alter the embedded catalogue.
-
-The offline RDAP supplied-evidence review implements the request shape defined
-by RFC 9536 for `resources`, `domains`, `nameservers`, and `entities`. It also
-validates a supplied server's `reverse_search_properties_mapping` response
-before preparing a request. Only registered IANA property paths and exact
-supported resource/property pairs are accepted. Preparing the request neither
-proves that a particular server supports it nor sends a reverse search; active
-execution remains gated on a reviewed server policy, privacy boundary, and
-deterministic fixtures.
-
-The separate maintenance command `npm run rdap-extensions:drift` compares the
-pinned official RDAP extension fixture with the reviewed local interpretation
-catalogue entirely offline. `--live` performs one bounded manual fetch from the
-fixed official CSV URL and reports added, removed, renamed, status-changed,
-unrecognized, and local-only identifiers. `--json` emits
-`whoisleuth.rdap-extension-drift-audit` version 1. Drift exits with status 1 and
-requires specification and fixture review; the command never enables an
-extension, changes authority or availability logic, or issues reverse search.
-
-`npm run service-dependencies:audit` validates the passive service-dependency
-catalogue entirely offline. It checks the catalogue digest, duplicate
-identifiers and target suffixes, evidence classes, source and licence
-treatment, source dates, and a fixed 180-day review age. `--json` emits
-`whoisleuth.service-dependency-signature-audit` version 1. A stale or changed
-signature requires manual provider and benign-fixture review; the command
-never resolves a target, checks an account, or tests claimability.
-
-## Offline Risk calibration
-
-`risk-calibrate` replays a versioned analyst-labelled fixture dataset through
-the exact Risk model shared with the web application. It does not perform a
-lookup, contact the hosted deployment, persist the dataset, alter model weights,
-choose a threshold, or tune the model automatically. The report compares fixed
-thresholds from 40 through 90 and identifies 70 as the current review band. It
-also reports F1, balanced accuracy, Wilson 95% intervals, deliberately small
-scan-depth and review-reason strata, and a current-versus-previous model replay.
-Strata with fewer than 20 included labels are marked insufficient rather than
-presented as reliable performance estimates.
-
-The JSON report derives a bounded `interoperabilityTags` list from the
-analyst-owned disposition and review reason. The mapping uses reviewed MISP
-taxonomy terms only where the meaning is unambiguous. Tags do not change a
-score, disposition, or case, and no MISP service is contacted.
-
-Input is capped at 2 MiB and 500 records. Each record requires a unique bounded
-ID, an ASCII DNS hostname, one existing analyst disposition, and a strict
-whitelist of current scoring inputs. Unknown fields are discarded; arrays,
-strings, ages, booleans, provider records, and external findings are revalidated
-and bounded before scoring. The accepted dataset envelope is:
-
-```json
-{
-  "schema": "whoisleuth.risk-calibration-dataset",
-  "version": 2,
-  "records": [
-    {
-      "id": "fixture-1",
-      "domain": "login.example.test",
-      "analystDisposition": "confirmed_abuse",
-      "reviewReasonCode": "confirmed_credential_abuse",
-      "evidence": {
-        "availability": "registered",
-        "mutationTypes": ["dictionary"],
-        "hasPasswordField": true
-      }
-    }
-  ]
-}
-```
-
-`confirmed_abuse` is treated as a positive calibration label; `false_positive`
-and `expected` are negative labels. `unreviewed`, `suspicious`, and
-`closed_no_action` remain contextual and are excluded from threshold quality
-metrics, as are records for which Risk is not applicable. Terminal output caps
-its record list at 100 while `--json` retains the complete bounded report,
-factor breakdowns, score bands, confidence intervals, bounded strata, model
-comparison counts, and per-threshold confusion metrics. Analyst
-dispositions and heuristic scores are review context: neither proves
-maliciousness or safety.
-
-The authenticated Monitor workspace can deliberately create the accepted
-dataset from explicitly selected cases. Selection is available only when a case
-has a reviewed disposition and retained normalised evidence. That local export
-contains the case ID, domain, disposition, optional reviewed reason code, and a
-bounded whitelist of current scoring inputs. A matched review-language signal
-is exported as a fixed indicator, not as captured page text. It excludes notes,
-tags, assertions, actions, contacts, raw
-source data, provider payloads, and stored Risk scores. Before download, a local
-review step shows the selected, included, and excluded counts, the domains and
-dispositions that will be written, and the excluded evidence classes. The CLI
-still validates every exported record and never trains, tunes, or changes the
-Risk model.
-
-## Lookalike review-yield calibration
-
-`lookalike-calibrate [dataset.json]` summarises reviewed candidate outcomes by
-mutation family without retaining domains, candidate identifiers, analyst
-notes, or evidence values in its output. Input uses
-`whoisleuth.lookalike-calibration-input` version 1, is capped at 2 MiB and 5,000
-unique opaque records, and requires one reviewed disposition plus from 1 to 12
-bounded mutation-family identifiers per record.
-
-The report keeps exact disposition counts, review-lead rate, false-positive
-rate, and a per-family sample state. Fewer than 20 reviewed observations remains
-`insufficient`. The command is diagnostic only: it does not tune candidate
-generation, filtering, ranking, or Risk, and a useful historical yield does not
-establish that a current candidate is malicious or safe.
-
-## Offline artefact verification
-
-`verify-artifact` validates a supported local artefact without printing its
-evidence contents. Input is capped at 15 MiB. It currently recognises ordinary
-and encrypted workspace archives, case-response packets, acquisition-decision
-exports, domain-comparison exports, Bulk mail-exposure exports, and Bulk review
-manifests. Reviewed CLI case packs are checked against their canonical digest,
-bounded browser-importable case collection, audience, and review marker. The
-command also verifies the internal digests of a complete investigation
-capsule, including its evidence, brief, graph, and optional analyst-record
-projections, and that capsule can be passed to `sign-artifact`. It also validates the bounded versioned structure of saved CLI
-Lookup JSON. Because saved Lookup documents do not embed a checksum or
-signature, that result is reported as `structure_valid` with content integrity
-explicitly unchecked. Saved Lookup validation retains its stricter 8 MiB
-document ceiling.
-
-For an ordinary workspace archive, the command validates the versioned
-structure, section byte counts, record counts, and per-section checksums. For a
-supported signed review artefact, it validates the declared SHA-256 digest. An
-encrypted archive without `--passphrase-file` can establish only that the
-envelope is structurally valid; it reports `envelope_valid` and explicitly
-leaves authenticated encryption and inner checksums unchecked.
-
-Supplying a separate passphrase file, capped at 1 KiB, allows authenticated
-decryption followed by the ordinary workspace checks. The passphrase is never
-accepted as a command-line value, printed, or retained. Verification detects
-changes against the artefact's declared contract; it does not authenticate the
-analyst or establish that an observation was accurate or remains current.
-
-## Privacy-safe source reliability report
-
-`source-report` summarises source states, durations, truncation, and rate-limit
-counts from one version-1 CLI Lookup, Bulk, or Bulk-item document, a JSON array
-of up to 100 such documents, or an array containing only previously generated
-source-reliability reports. Lookup documents and reports cannot be mixed.
-Merged reports preserve exact state and sample totals and add bounded ranges
-for each input report's median and p95 duration, a bounded source timeline,
-fast/deep/unknown cohorts, and the earliest and latest valid report generation
-times. Exact duplicate reports are rejected so one saved report is not
-accidentally counted twice. Per-source failure, partial, truncation, and
-rate-limit rates remain separate. The command does not pretend that aggregate
-timing distributions can reconstruct the original target-level samples. Input
-is capped at 12 MiB and traversal, source, duration, and output counts are
-bounded.
-
-The report retains only fixed source identifiers and aggregate operational
-counts. It does not output targets, queries, endpoints, source limitations, raw
-evidence, or provider payloads. Observation-envelope duration and the
-potentially overlapping Lookup timing are reported separately and never added
-together. It is a local engineering diagnostic, not analytics, a source-quality
-score, or evidence that a collector is currently healthy.
-
-## Workspace archive inspection
-
-`inspect-archive` verifies an ordinary or encrypted workspace archive and then
-reports its versioned sections, counts, byte sizes, and checksum states without
-printing stored records. An encrypted archive requires
-`--passphrase-file`; passphrases are never accepted on the command line.
-
-An optional `--search` is exact and case-insensitive across a fixed allowlist
-of target fields. Default matches disclose only the section, field name, and a
-SHA-256 digest. `--reveal` must be selected explicitly to print the matched
-value. Notes, contacts, raw evidence, arbitrary object fields, and partial text
-search are excluded. Unicode domain searches are canonicalized to their
-DNS-safe ASCII form before exact comparison. `--require-match` makes a
-no-match result fail for automation and is valid only with `--search`.
-Traversal, input size, matches, depth, arrays, and strings are bounded.
-
-Version 2 of the inspection report adds a content digest over the ordered
-section identifiers, schema versions, record counts, and normalised section
-content. It deliberately excludes JSON formatting and each section envelope's
-export time, so two separately exported archives with the same retained
-workspace content have the same identity. `--expect-content-digest <sha256:digest>`
-fails when that identity differs, which supports deliberate transfer checks
-without printing records. Matching digests detect equivalent retained content;
-they do not authenticate who created it or establish that its evidence is
-accurate or current. The report separately identifies the source archive
-version and the installed reader version.
-
-## Optional evidence-package signing
-
-`sign-artifact` signs a locally verified case-response packet or supported
-review manifest with an externally managed Ed25519 private key:
-
-```bash
-node bin/whoisleuth.mts sign-artifact packet.json --private-key-file analyst-private.pem > packet.signed.json
-node bin/whoisleuth.mts verify-signature packet.signed.json --public-key-file analyst-public.pem
-```
-
-The signed package embeds the public key, key identifier, signature time, and
-original artefact. Verification first checks the exact package field set and
-signature, then the artefact's own checksums or manifest. A result is reported
-as `signature_valid`; signer trust is separately reported as `trusted_key` or
-`embedded_key_only`. Without a separately supplied trusted public key,
-verification establishes only that the package is internally self-consistent.
-WHOISleuth does not generate, store, recover, rotate, publish, or establish
-trust in signing keys.
-
-## Reproducible investigation manifest
-
-`manifest <artefact.json> [...] --workflow <label>` reads from 1 to 16 ordered
-JSON artefacts and emits `whoisleuth.investigation-manifest` version 1. Each
-entry records its sequence, bounded schema and version metadata, exact UTF-8
-content digest, canonical JSON digest, and byte count. The manifest also records
-the installed CLI version and can include an externally calculated
-`--configuration-digest sha256:...` without copying configuration values.
-
-Source paths, filenames, command-line arguments, and artefact contents are not
-retained. Individual artefacts are capped at 15 MiB and the ordered set at
-32 MiB. The manifest carries its own canonical integrity digest, works with
-`verify-artifact`, and can be passed to `sign-artifact`. Reproduction still
-requires the exact digested artefacts, compatible source services, and any
-separately held configuration; matching digests do not establish observation
-accuracy or freshness.
-
-## Bulk lookup
-
-`bulk` accepts a newline-delimited file or stdin. It preserves input order,
-removes case-insensitive duplicates, and returns a result for every retained
-query. Input is capped at 1 MiB. Fast mode is capped at 500 queries with four
-workers by default. Deep mode is capped at 50 queries with two workers by
-default. Explicit concurrency cannot exceed eight in fast mode or three in
-deep mode.
-
-Bulk uses the shared compact lookup response, so it does not retain raw RDAP
-objects or WHOIS response bodies. `--json` returns one bounded collection;
-`--jsonl` emits one self-contained versioned item per line. `--domains` emits
-only successfully normalised domain names, while `--queries` preserves the
-selected bounded input queries and is suitable for an exact retry queue.
-Version 2 adds a
-bounded `dnsSummary` projection for observed A, AAAA, NS, and MX records plus
-null MX, SPF, and DMARC state. `--csv` writes fixed columns for automation,
-including the DNS summaries and explicit outcome.
-
-`--registered-only`, `--inconclusive-only`, and `--errors-only` are mutually
-exclusive output filters. The first retains registered, for-sale, and expiring
-authority-aware states. The second retains unknown authority states and failed
-rows. The third retains only rows whose lookup operation failed, which is useful
-for producing an exact retry queue without treating an inconclusive successful
-lookup as an operational error. Filtering does not change collection and never
-converts an unavailable or failed source into an unregistered result. Machine
-documents record collected and emitted counts. A mixture of successful and
-failed queries exits with code 4 while preserving every collected result before
-output filtering. For example, `bulk domains.txt --queries --errors-only`
-produces only the exact failed inputs while retaining the partial-failure exit.
-
-## Certificate Transparency search
-
-`ct-search` accepts one keyword as an argument or on stdin and calls the same
-bounded Certificate Transparency module as the web application. It contacts
-the upstream public log search service directly from the local machine; it
-does not call the hosted WHOISleuth deployment. Quote a multi-word keyword so
-the shell passes it as one argument.
-
-Terminal output summarises certificate rows, observed hostnames, canonical
-registrable-domain matches, observation times, bounded certificate-issuance
-groups, and completeness. An issuance group contains names observed together
-in one public certificate record; a cross-domain group is a review lead, not
-an attribution or ownership finding. Terminal output shows at most 100 matches
-and five hostnames per match, with explicit omission notes. `--json` returns
-the complete bounded structured result in the versioned
-`whoisleuth.cli.ct-search` schema. The certificate-group cap is reported
-separately from the registrable-domain result cap. CT observations do not prove
-that a website is active or malicious.
-
-## Local certificate event intake
-
-`ct-intake [events.json]` reads `whoisleuth.ct-event-batch` version 1 entirely
-offline. Each source-qualified event supplies a log identifier, observation
-time, certificate SHA-256 digest, one or more DNS names, completeness, and
-optional issuer, expiry, and limitations. Unknown fields, malformed names,
-unsupported completeness values, and oversized batches are rejected.
-
-JSON output uses the existing `whoisleuth.external-findings` version 3 contract
-and can be deliberately imported into the browser Console. Wildcard names are
-normalised to their base DNS name, exact event/domain duplicates are removed,
-and deterministic output is capped at 100 findings, 25 domains, and 20 findings
-per domain to match the browser import boundary. Omission is stated in each
-retained finding when the supplied batch exceeds those limits. The command
-makes no request and treats every certificate event as a review lead, not proof
-that the certificate was served, requested, or controlled by the named domain.
-
-## Declarative observation interchange
-
-`map-observations [mapping.json]` reads
-`whoisleuth.external-observation-mapping` version 1 and applies one strict,
-declarative profile to at most 500 local records. The profile selects bounded
-dotted field paths for the domain, summary, observation time, optional
-reference, and optional completeness. It fixes one source, evidence class, and
-finding category for the batch. Profiles cannot contain scripts, templates,
-computed expressions, network endpoints, or executable callbacks. Prototype
-paths and unknown fields are rejected.
-
-The resulting JSON is the existing browser-compatible
-`whoisleuth.external-findings` version 3 contract. It retains source identity,
-observation time, completeness, and limitations, while stating that field
-semantics were not independently verified. Deterministic output is capped at
-100 findings, 25 domains, and 20 findings per domain. The command makes no
-request and never interprets an omitted field as a negative observation.
-
-`oam-export [external-findings.json]` projects that strict findings document
-into `whoisleuth.open-asset-model-bridge` version 1. It uses the documented
-[OWASP Open Asset Model](https://github.com/owasp-amass/open-asset-model)
-vocabulary for bounded `FQDN`, `IPAddress`, and `TLSCertificate` assets plus
-`dns_record` and `san_dns_name` relations. Only typed A, AAAA, and SHA-256
-certificate observations create infrastructure assets or relations. Other
-findings remain represented by their FQDN asset.
-
-This bridge wrapper is not a claim that every receiving implementation accepts
-one universal native serialisation. Receivers must validate the projection
-against their supported model version. WHOISleuth preserves source and
-completeness as discovery metadata, does not invent a confidence score, and
-does not treat an edge as proof of ownership, control, coordination, intent,
-safety, or maliciousness.
-
-## Lookalike discovery
-
-`discover` runs the same pure, bounded lookalike generator as the Discover
-tool without making network requests. It accepts a brand label or a
-domain with one suffix label. The default TLD set is `com,net,org`; replace it
-with `--tlds com,net` when narrower coverage is wanted.
-
-Generation presets are `common`, `impersonation`, and `all` (the default).
-Keyboard-aware mutations support `qwerty` (the default), `azerty`, and
-`qwertz`; `--keyboard all` uses their bounded combined neighbour set, including
-adjacent number-row keys. Supply a UTF-8 text file with
-`--dictionary terms.txt` to add up to 100 local terms when
-using the `impersonation` or `all` preset. Dictionary input is capped at 4,096
-bytes and individual terms at 32 characters. Machine output records accepted
-and rejected term counts but never copies the private terms into its metadata.
-
-Use `--families <ids>` instead of `--preset` to run an exact comma-separated
-selection. Supported IDs are `character_addition`, `character_omission`,
-`character_duplication`, `character_transposition`, `pluralization`,
-`tld_embedding`, `www_prefix`, `hyphenation`, `separator_omission`,
-`word_reordering`, `keyboard_substitution`, `keyboard_insertion`, `vowel_swap`,
-`bitsquatting`, `ascii_homoglyph`, `unicode_homoglyph`,
-`unicode_whole_label`, `unicode_homoglyph_depth_2`, `dictionary`,
-`dictionary_token_replacement`, `tld_typo`, and `tld_substitution`. Machine
-output records the normalised custom selection. A custom dictionary file
-requires `dictionary` or `dictionary_token_replacement` in that selection.
-
-`--domains` writes the unique candidate names only. `--snapshot <file>` keeps
-one private, versioned local observation of the normalised seed, generation
-configuration, custom-dictionary digest, and candidate set. The first run
-creates the snapshot; later runs report added and removed candidates before
-atomically replacing it. The snapshot never stores private dictionary terms.
-Use the same command from a local scheduler such as cron or a system timer to
-perform repeatable discovery runs. WHOISleuth does not install a scheduler,
-run a background daemon, or infer that an added candidate is registered,
-active, available, or malicious.
-
-Dotted subdomain permutations are intentionally excluded because the lookup
-pipeline validates a hostname's registrable parent. The CLI does not present
-authoritative parent registration evidence as proof that a generated hostname
-exists.
-
-Terminal output is capped at 200 candidates with an explicit notice. Versioned
-JSON and JSONL use `whoisleuth.cli.discover` schema version 2 and retain the
-complete bounded candidate set and mutation provenance. Internationalised
-candidates show the DNS-safe ASCII form and readable Unicode form together in
-terminal output. The Impersonation and All presets can add up to six
-deterministic whole-label Unicode candidates when every letter has a reviewed
-same-script replacement. The command generates candidates only. It does not
-claim that a domain is registered, active, or malicious.
-
-`unicode_homoglyph_depth_2` is an explicit `--families` option and is never
-enabled by a preset. It replaces exactly two ASCII letters with characters
-from the same reviewed script, ranks curated mappings first, and returns at
-most 256 candidates. JSON and terminal output report generated candidates,
-cross-script or invalid combinations omitted by policy, and lower-ranked
-label variants omitted by the family or overall generation budget.
-
-## Supervised candidate scan
-
-`discover-scan` composes the same bounded generator with the compact Lookup
-collector. Unlike `discover`, it is an explicitly networked command. It selects
-the first deterministic candidates up to `--scan-limit`, processes fixed
-chunks sequentially, and retains each registration and DNS source state. Fast
-mode is the default and accepts at most 500 candidates. Explicit `--deep` mode
-is capped at 50 candidates and concurrency 3 because it can add WHOIS, DNS,
-HTTP, TLS, page, and technology work for every selected candidate.
-
-Use `--chunk-size 1-100`, `--concurrency 1-8`, and the existing private
-`--checkpoint <file> [--resume]` boundary to control a run. The checkpoint is
-tied to the exact ordered candidate set and scan mode. A new generation order,
-limit, or mode requires another checkpoint. `--resolver` accepts at most three
-literal IPv4 or IPv6 recursive-resolver addresses and applies them only to DNS
-observations in this local run. Resolver hostnames and automatic third-party
-resolver selection are not supported. The selected resolvers can observe the
-queried candidates and may apply their own logging and retention policies.
-
-An optional newline-delimited `--allowlist` accepts at most 500 domains and 64
-KiB. Matching candidates remain in evidence and are labelled `suppressed` in
-the review queue; the full list and unmatched entries are not copied into
-output, while each matching scanned candidate necessarily exposes that match.
-Allowlisting never deletes a result or asserts that it is safe. Output filters
-select registered, inconclusive, acquisition-review, or
-suppressed rows without changing whole-run counts or source health. JSON,
-JSONL, CSV, and domain-list forms retain mutation provenance and explicit
-review lanes. The queue provides next manual actions, not automatic lookup,
-acquisition, blocking, submission, or enforcement.
-
-Deep compact results can group exact shared addresses, nameservers, and mail
-servers observed across at least two candidates. These bounded relationships
-are pivot leads only. Common hosting, delivery, registrar, and mail services
-can produce the same relationship without common ownership or control.
-
-`--observation-snapshot <file>` keeps a private versioned local projection of
-registration state, confidence, and bounded A, AAAA, NS, MX, null-MX, SPF, and
-DMARC summaries for the exact candidate set, mode, and resolver selection.
-Version 2 records registration and DNS observation times and latest component
-states separately; version 1 is read and normalised on the next write. A later
-identical run reports material field changes only for components collected
-with enough completeness to support the comparison. If registration or DNS is
-partial or unavailable, the prior usable evidence for that component is
-preserved and the attempt is reported as unavailable rather than converting
-missing data into a removal. Raw registry
-records, contacts, page content, and request details are excluded. Snapshot
-differences are review prompts, not proof of ownership, control, intent,
-safety, or maliciousness.
-
-## Domain posture audit
-
-`posture` runs the standard-profile form of the owned-domain DNS and
-email-security audit used by Brand Profiles. It queries registry status and
-DNSSEC evidence, nameserver delegation, SPF, DMARC, MX, CAA, MTA-STS, TLS-RPT,
-and BIMI directly from the local machine. Literal SPF include and redirect
-branches are expanded within fixed depth, policy-query, DNS-term, void-answer,
-cycle, and time bounds. External DMARC reporting authorisation and external
-nameserver, mail, SPF, and reporting dependencies are separately reported.
-Supply up to ten known active and retired DKIM selectors in total with
-`--selectors selector1,selector2` and `--retired-selectors selector0`;
-selectors cannot be reliably discovered from DNS, so no-selector output
-reports DKIM as not checked. Use `--mail-profile standard`,
-`--mail-profile defensive-no-mail`, or `--mail-profile parked` to make the
-intended mail posture explicit rather than inferring it from DNS.
-
-Terminal output shows each pass, review, action, or informational result and
-caps displayed records at five per check with an explicit omission notice.
-Versioned JSON retains the complete bounded report, including SPF traversal,
-DMARC authorisation, and dependency provenance. Warnings and dangers are
-findings rather than command failures; transient resolver or policy-fetch
-failures remain informational and should be retried before changing DNS.
-
-## HTTP intelligence
-
-`http` runs the same bounded safe homepage probe used by a deep lookup. It
-tries HTTPS before HTTP, follows only validated public-network redirects, caps
-each attempt at six seconds, and captures at most 300,000 response bytes for
-hashing and metadata. A non-success HTTP response still proves that a web
-service answered; failure of both schemes remains inconclusive rather than
-evidence that no website exists.
-
-The command reports normalised redirect, response, content, selected security-
-header, body-hash, completeness, and attempt provenance. Captured homepage text
-is never written to terminal or JSON output. Query strings are removed by the
-shared HTTP evidence normalizer, and terminal values are additionally bounded
-and control-safe.
-
-## TLS intelligence
-
-`tls` runs the same bounded one-connection TLS collector used by deep lookups.
-It resolves the hostname once through the public-address guard, validates every
-answer, connects directly to the first validated address on port 443, and keeps
-the original hostname for SNI and certificate identity checking. Resolution
-and handshake work share a five-second deadline.
-
-The report retains the negotiated protocol, ALPN and cipher, runtime trust and
-hostname checks, certificate validity, bounded subject and issuer names, SANs,
-SAN class counts, signature algorithm and OID, extended-key-usage purposes,
-classified Authority Information Access presence counts, SHA-256 certificate
-and public-key fingerprints, a bounded certificate chain, and neutral
-findings. AIA responder and issuer locations are classified as HTTP, HTTPS, or
-other and then discarded; they are not retained or followed. The collector
-stores no certificate bytes, session material, or application data and does
-not enumerate supported protocol or cipher suites.
-A failed collection is inconclusive rather than proof that no TLS service
-exists.
-
-## Registry-source comparison
-
-`compare` reads one version-1 `whoisleuth.cli.lookup` domain document from a
-file or stdin and emits a version-3 `whoisleuth.cli.compare` document. Its
-primary comparison reconciles normalised registry RDAP and WHOIS fields. When
-the saved deep lookup also represents the optional registrar RDAP follow-up,
-an additional sibling comparison reconciles the portable registry and
-registrar RDAP publication fields. The command does not repeat the lookup,
-contact the hosted deployment, or treat a conflict as a command failure. Use a
-deep lookup when multiple sources are wanted; a fast lookup deliberately
-records WHOIS as skipped, and comparison preserves that state as unavailable
-rather than misreporting RDAP-only publication.
-
-Input is capped at 8 MiB and must retain the lookup schema, mode, source
-diagnostics, and normalised parsed source sections. Per-value, list, and event
-bounds are revalidated because saved JSON is treated as untrusted input. A
-successful registrar source must include a normalised object and agree with
-its diagnostic status. Raw RDAP JSON, registrar contacts and source-specific
-handles, WHOIS response bodies, availability evidence, and unrelated lookup
-fields are not copied into the comparison result.
-
-When the saved Lookup contains valid version-5, version-6, or version-7, context-only
-registry-access diagnostics, version 3 retains their bounded suffix, access profiles, and
-limitation. Terminal output labels the same collection context explicitly.
-It explains source reachability only and cannot decide registration,
-availability, ownership, safety, or maliciousness. Older documents and saved
-lookups without that context do not gain a registry-access field.
-
-Terminal and versioned JSON output cover domain identity, registry object ID,
-registrar, registrar IANA ID, lifecycle dates, DNSSEC, statuses, and name
-servers. The shared comparison model normalises harmless case, punctuation,
-ordering, and date-precision differences while distinguishing conflicts,
-one-source publication, redaction, incomplete sources, and unavailable
-sources. This is source reconciliation, not an availability, ownership, or
-maliciousness decision.
-
-## Static page comparison
-
-`page-compare <left.json> <right.json>` reads two different version-1 saved
-Deep domain Lookup documents and compares the already-retained static page
-identity, exact and perceptual favicon evidence, technology identifiers, TLS
-issuer label, and TLS public-key fingerprint. DOM structure is compared first
-by its exact bounded tag-sequence digest, then, when both captures provide it,
-by a parse5-tokenized structural SimHash. It makes no request and requires
-complete supported static page-identity observations on both sides.
-
-Each page component remains independent. Exact, similar, overlapping,
-different, unavailable, and partial evidence are not collapsed into a score.
-Matching components are investigative relationships rather than proof of
-copying, common ownership, control, intent, safety, or maliciousness. Static
-comparison does not execute JavaScript; use the optional local rendered
-capture package only when that additional active behaviour is authorised.
-
-## Passive mail exposure review
-
-`mail-review [bulk.json|bulk.jsonl]` reads version-2 Bulk output locally and
-summarises MX, null MX, SPF, DMARC, and mail-provider relationships. It keeps
-authenticated mail, authentication gaps, incomplete authentication evidence,
-no explicit MX, null MX, and incomplete DNS evidence as separate states.
-Shared-provider relationships are based only on the registrable domain of an
-observed MX hostname and do not establish shared ownership or control.
-
-The command makes no DNS or SMTP request and retains no source path. It does
-not test message acceptance, relay behaviour, mailbox existence, catch-all
-behaviour, SMTP banners, or whether a mail server is rogue, safe, or malicious.
-
-An analyst may add a bounded `tlsaEvidence` object to a version-2 Bulk item for
-offline DANE review. It must name the exact `_25._tcp.<mx-host>` service, and
-that host must occur in the same item's retained MX evidence. A certificate
-association match is complete only when `dnssecState` is `validated`. TLSA
-usages 0 and 1 additionally require `pkixValidationState: "validated"`.
-Usages 0 and 2 compare against the bounded `authorityMaterials` array; usages
-1 and 3 compare against the supplied leaf certificate or SPKI. Mismatched
-service names, missing certificate roles, unvalidated prerequisites, malformed
-material, and truncation remain invalid, partial, or untrusted rather than
-becoming a DANE match.
-
-## Offline supplied-evidence review
-
-`review-evidence [evidence.json]` accepts one version-1 JSON input and performs
-only deterministic local parsing, comparison, or request planning. Input is
-capped at 16 MiB. The command never retrieves DNS, opens SMTP, contacts an
-RDAP server, submits a resolver query, or looks up an address in a hosted
-GeoIP service.
-
-Supported input schemas are:
-
-- `whoisleuth.dnssec-evidence-input`: compares bounded DS and DNSKEY records,
-  recalculates DNSKEY key tags and supported DS digests, and reviews supplied
-  RRSIG validity windows at `observedAt`. `consistent` describes only the
-  supplied DS/DNSKEY relationship. It does not authenticate a chain to a root
-  trust anchor, validate RRSIG cryptography, or prove that a missing record is
-  absent.
-- `whoisleuth.tlsa-evidence-input`: binds TLSA records to one explicit
-  `_port._transport.hostname` service and compares supplied leaf or authority
-  certificate/SPKI bytes. `matched` requires independently validated DNSSEC;
-  PKIX-TA and PKIX-EE usages also require an independently validated PKIX path.
-  The command does not retrieve the certificate or negotiate STARTTLS.
-- `whoisleuth.rdap-search-input`: normalises a supplied RDAP search-help
-  response and prepares an exact supported reverse-search request without
-  sending it. If the document also contains a previously obtained `response`,
-  the command checks its bounded property mappings against the reviewed
-  registration and reports omitted or unrecognised mappings without treating
-  the response as authoritative or complete.
-- `whoisleuth.rpki-route-input`: compares a route prefix and origin ASN with a
-  bounded analyst-supplied VRP set.
-- `whoisleuth.local-geoip-query`: queries an analyst-supplied bounded prefix
-  database whose source, version, and licence metadata remain in the result.
-- `whoisleuth.local-mmdb-query`: with an explicit `--mmdb <database-file>`,
-  queries one analyst-supplied MaxMind DB file locally. The query document must
-  carry `address`, `sourceLabel`, `databaseVersion`, and `license`. WHOISleuth
-  does not bundle, download, update, license, transmit, or retain the database.
-  The nested result uses the same address, network, country, region, city, ASN,
-  source, and limitation fields as the bounded JSON-prefix path. This mode is
-  CLI-only because a hosted or browser deployment cannot open an analyst's
-  local file; its JSON result remains portable to website-compatible evidence
-  archives and reports.
-- `whoisleuth.encrypted-dns-plan-input`: validates an explicitly reviewed
-  encrypted-DNS provider contract and prepares a bounded query plan. It does
-  not execute the plan.
-- `whoisleuth.zone-intent.input`: parses either a deliberately supported,
-  bounded BIND master-file subset or normalised DNS records and compares it
-  with one separately attributed observation. TXT values are reduced to
-  SHA-256 digests, unsupported directives and records remain rejected, and an
-  incomplete observation never becomes a missing-record conclusion. The
-  review does not contact a resolver or apply a DNS change.
-- `whoisleuth.domain-portfolio.input`: reviews up to 500 analyst-supplied
-  domain inventory rows for exact registrar, DNS, mail, certificate and
-  recovery concentration, renewal-review gaps and internal recovery-domain
-  dependencies. Account labels and provider assignments remain analyst
-  assertions, and the review makes no provider or account request.
-- `whoisleuth.domain-change.input`: compares bounded, separately labelled
-  authority and resolver observations; reviews CDS, CDNSKEY and CSYNC
-  publication consistency; inventories supplied SRV services and ACME
-  dependencies; and records TLS key continuity, stapling, embedded timestamp,
-  and HSTS preload context. TXT values are retained only as SHA-256 digests.
-  The result is an offline review gate, not a DNSSEC validation, preload-list
-  lookup, certificate-authority request, or permission to apply a change.
-- `whoisleuth.dns-convergence.input`: compares the latest supplied observation
-  from at least two labelled resolvers or network vantages. It preserves
-  converged, divergent, unexpected, incomplete, and insufficient record-set
-  states, can compare against optional expected values, and projects a simple
-  observation-time plus TTL cache horizon. It does not query DNS or decide
-  which divergent value is authoritative, and supplied TTLs do not reveal
-  actual cache age or resolver refresh policy.
-- `whoisleuth.nameserver-preflight.input`: reviews an intended nameserver set
-  against separately attributed direct-service observations before a
-  delegation change. It checks authoritative service, the served NS set, SOA
-  evidence, public addresses and in-bailiwick glue readiness without querying
-  DNS, opening a socket or changing registry configuration.
-- `whoisleuth.trust-store-comparison.input`: compares an already-observed,
-  bounded certificate-chain SHA-256 fingerprint set with up to 16
-  analyst-supplied trust-store snapshots. Each snapshot carries its own name,
-  version, source, review time, completeness, and no more than 2,048 anchor
-  fingerprints. Exact intersections, complete non-observations, and
-  inconclusive inputs remain separate. A match does not build or validate a
-  certificate path, and non-observation does not mean a client would reject
-  the chain because served chains commonly omit their root.
-
-The common output is `whoisleuth.cli.offline-evidence-review` version 1. It
-retains the nested result's explicit state and limitations. A locally
-consistent relationship is not converted into a claim about current
-publication, ownership, safety, or maliciousness.
-
-`review-evidence --strict-exit` is an opt-in local automation boundary. It
-returns the partial-failure exit code when an input family exposes an explicit
-failed `gate`, or when a zone-intent comparison is incomplete or contains a
-difference, missing value or unexpected value. Other evidence families retain
-their ordinary exit behaviour; the flag does not invent a pass/fail policy for
-them. JSON is still emitted before the exit status is selected.
-
-## Domain control manifests
-
-`domain-control [input.json]` builds or reviews a bounded desired-state
-manifest without making a request or changing configuration. A manifest input
-uses `whoisleuth.domain-control-manifest-input` version 1, includes an expiry,
-and may record expected nameservers, DS, MX, CAA, TLS issuer, TLS SPKI
-fingerprint, registrar-lock preference, and a renewal-review date for up to 100
-domains. Empty fields mean unconfigured; they do not require a record to be
-absent.
-
-The emitted `whoisleuth.domain-control-manifest` version 1 is normalised and
-protected by a canonical SHA-256 digest. It can also be passed to
-`sign-artifact` for an optional local Ed25519 signature. Integrity and
-signature verification detect changes and authenticate possession of the
-selected key; neither establishes that the desired state is correct. Manifest
-input and verification reject unknown fields, and verification rejects
-non-canonical content rather than returning a shape that differs from the
-normalised contract covered by the digest.
-
-A review input uses `whoisleuth.domain-control-review-input` version 1 and
-contains one manifest plus separately attributed observations. Only a complete
-`observed` field may produce `drift`. Partial, unavailable, unsupported, and
-missing observations remain inconclusive, and unrelated observations are
-counted but ignored. The review performs no DNS, RDAP, HTTP, TLS, SMTP, or
-registrar request.
-
-## Domain assurance review
-
-`assurance [input.json]` reviews one bounded analyst-authored workflow entirely
-offline. Version 1 inputs remain supported. Version 2 adds optional
-`customChecks` to retirement inputs and remains the current normalised output
-version. The input uses `whoisleuth.domain-assurance.input` and one of three
-fixed kinds:
-
-- `planned-change` records a bounded window, evidence-backed milestones,
-  rollback criteria, and post-change checks;
-- `recovery-dependencies` reviews up to 100 domains across registrar, DNS,
-  mail, certificate, and recovery providers and highlights exact provider
-  concentration; and
-- `retirement` checks the fixed decommissioning controls without treating an
-  unchecked item as complete. Version 2 can add up to 20 analyst-defined checks,
-  each with a bounded identifier, label, expected boolean, and true, false, or
-  null observed value.
-
-Provider labels, readiness confirmations, evidence references, and expected
-states remain analyst assertions. The output preserves incomplete and
-needs-review states and gives every negative state an explicit review reason.
-The versioned input rejects unknown fields and contradictory evidence attached
-to an unfinished check. It stores no credentials, makes no request, and changes
-no registrar, DNS, mail, certificate, or recovery configuration.
-
-## Domain change assurance packet
-
-`change-packet [input.json]` combines one pre-change domain review, one
-post-change domain review, and one planned-change assurance input for the same
-domain. The input uses `whoisleuth.domain-change-packet.input` version 1. The
-command revalidates each nested contract, summarises changed authoritative
-record sets, and emits `whoisleuth.domain-change-packet` version 1 with a
-canonical SHA-256 integrity digest.
-
-The packet is ready only when both supplied observation reviews and the change
-plan pass their own bounded gates. Partial or unavailable evidence remains a
-review reason. Packet assembly performs no collection or configuration change,
-and digest validity does not authenticate the analyst. A reviewed packet can be
-passed to `sign-artifact` when the operator has an independently managed
-Ed25519 signing-key lifecycle.
-
-## Pre-sharing review
-
-`sharing-review [artifact.json]` performs a redacted local preflight before an
-analyst deliberately shares an artefact. The analyst must select a TLP 2.0
-marking, a recipient scope, and a bounded purpose. Optional confirmations record
-human review, personal-data review, and redaction review. The command validates
-supported artefact integrity where possible, detects stricter embedded TLP
-markings, and reports only key-category counts plus bounded, control-free schema
-and integer version metadata. It emits no content values and copies no raw
-evidence.
-
-An imported stricter marking cannot be downgraded by the requested marking, and
-recipient scope is checked against the effective marking. Evading this local
-preflight remains possible, so the result is a review aid rather than access
-control, legal advice, or recipient authorisation.
-
-## Fixed investigation plans
-
-`workflow-plan <recipe> <domain|brand>` turns one of four fixed recipes into a
-versioned `whoisleuth.cli.investigation-plan` document. Supported recipes are
-`domain-triage`, `lookalike-review`, `owned-domain-review`, and
-`historical-comparison`. Each step names an existing CLI command, carries its
-arguments as a JSON array, declares whether it is offline or networked, and
-marks network-disclosure or analyst-selection approval gates.
-
-The command is plan-only. It does not execute a step, construct a shell script,
-interpret a placeholder as a file path, read an artefact, make a request,
-change a case, or submit evidence. Analysts deliberately run selected commands
-after reviewing their collection boundaries. This provides repeatable
-domain-specific workflows without an arbitrary automation or plugin surface.
-
-## Local handoffs and one-shot monitoring
-
-`brief [lookup.json]` reads one saved Lookup and emits version 2 of the bounded
-`whoisleuth.cli.lookup-brief` contract. It separates retained facts,
-contradictions, incomplete source states, and manual actions. Each action
-states its evidence basis and expected outcome; it does not run the action or
-create a case.
-
-`case-pack [cases.json] --audience <internal|trusted|public> --reviewed` reads a
-browser case export containing at most 25 normalised cases, applies the selected
-redaction boundary, and emits a browser-importable case collection with a
-canonical SHA-256 digest and redaction manifest. It refuses an invalid,
-duplicate, larger, or generated package above the browser's 2 MiB import limit
-rather than silently omitting records or evidence. Trusted output removes notes,
-recipient values, and manual-pivot targets. Public output additionally removes
-actions and analyst assertions. The review flag records an explicit choice; it
-does not prove recipient authorisation or factual correctness.
-
-`verify-artifact` recognises the complete case-pack envelope before browser
-import. It checks the canonical digest, supported case-export schema, bounded
-case count, report count, audience and explicit review marker without printing
-case contents. This detects a changed hand-off file but does not authenticate
-the analyst, recipient, source observations, or review decision.
-
-`monitor-once [manifest.json]` performs one bounded Deep control review for at
-most 20 manifest domains with concurrency capped at three. An optional
-`--previous` checkpoint adds local first/last-observed comparison. It is not a
-daemon or scheduler, retains compact normalised observations rather than raw
-payloads, and keeps failed collection incomplete. JSON, JUnit, and explicit
-failure policies are supported.
-
-`workflow-run <recipe> <subject>` executes only concrete steps from the four
-installed fixed recipes. Network steps require `--approve-network` for that
-invocation. Analyst-selection placeholders always pause. A bounded `--resume`
-state must match the exact recipe and subject, cannot add commands or shell
-syntax, and is not evidence that earlier results remain current.
-
-## Optional local rendered capture
-
-`packages/web-capture` is a private repo-local Playwright package, not part of
-the distributable core CLI or hosted application. It requires an explicit
-authorisation flag and one new output directory:
-
-```bash
-npm run capture:local -- https://example.test --output-dir ./capture-example --authorize-rendered-capture
-npm run capture:compare -- ./official/manifest.json ./candidate/manifest.json --json
-```
-
-It writes a fixed 1024x768 PNG, screenshot SHA-256 and perceptual dHash, a DOM
-digest containing hashes and bounded element counts rather than markup or page
-text, and a version-2 `whoisleuth.web-capture-manifest` compatible with the
-Cases importer. Version-1 manifests remain importable.
-
-Rendered capture executes page JavaScript. It caps HTTP(S) requests and request
-hostnames, blocks downloads, service workers, WebSockets, WebRTC, WebTransport,
-non-read methods, credentials, non-default ports, and private or reserved
-addresses, and retains
-no request path, query, headers, bodies, cookies, credentials, DOM markup, or
-page text. Every browser request is intercepted, its hostname is resolved again,
-and the bounded response is fetched through WHOISleuth's public-address-pinned
-transport. Individual responses are capped at 4 MiB and all fetched response
-bodies together are capped at 24 MiB. Redirect destinations pass through the
-same interception and validation before collection continues. Use a disposable
-network-restricted environment for untrusted targets because rendered page code
-still executes inside the isolated browser process.
-
-The separate offline comparison command accepts two selected version-2 local
-capture manifests. It first verifies each referenced screenshot and DOM digest
-against its declared size, SHA-256, screenshot dimensions, and perceptual hash;
-it also validates bounded source and limitation metadata and requires the DOM,
-manifest, and source collection times to agree. It then
-compares screenshot distance, exact rendered DOM and visible-text digests,
-bounded element counts, page identity, technologies, and request-domain sets.
-It does not recrawl either target, reveal the input paths, or collapse the
-independent components into a similarity or maliciousness score. A missing
-perceptual hash remains unavailable rather than becoming a visual difference.
-
-## Lookup evidence export
-
-`export` converts one version-1 `whoisleuth.cli.lookup` domain document from a
-file or stdin into the same versioned `whoisleuth.lookup-evidence` JSON package
-produced by the web Lookup tool. It performs no lookup and writes only to
-stdout, so use ordinary shell redirection when a file is wanted. Pretty JSON is
-the default; `--compact` emits one compact JSON line for pipeline use, while
-`--markdown` produces a readable source-attributed summary and `--html`
-produces a self-contained printable report. Compact, Markdown, and HTML output
-are mutually exclusive.
-
-The saved input is capped at 8 MiB and revalidated using the same schema,
-source-status, parsed-data, scalar, list, and event boundaries as `compare`.
-The export retains query context, source diagnostics, normalised registry data,
-raw registry RDAP JSON, the raw WHOIS referral chain, availability analysis,
-and the shared registry-source comparison. Version 23 can add the exact local
-SSLBL comparison already represented by a deep full Lookup. Version 21 adds the bounded registry
-lifecycle, disclosure, publication-quality, reconciliation, and abuse-routing
-interpretation derived from the already-collected sources. Registrar RDAP raw
-data, contacts, entities, links, notices, and source-specific handles remain
-excluded. Schema version 20 replaces selected security-policy values in
-retained HTTP evidence
-with presence-only markers and can include fixed response-policy findings from
-an already-represented deep lookup. Version 19 additionally retains the bounded credential-surface projection
-when the saved deep lookup represents it. Version 18 retains the bounded structured identity projection
-when the saved deep lookup represents it. Version 17 retains the normalised portable-field comparison, explicit
-source-health states, a strict bounded projection of observed network
-registration, an optional normalised security.txt disclosure source, HTTPS
-service-binding publications, and the passive browser-library profile when the
-saved deep lookup represents them. Raw IP RDAP payloads, security.txt response
-bodies, script references, matched script content, and contact entities remain
-excluded.
-
-Markdown output summarises query context, assessment state, registry sources,
-source reconciliation, network observations, and collection diagnostics. It
-escapes all upstream text as untrusted content, bounds displayed values and
-lists, and deliberately omits raw RDAP JSON and full WHOIS response bodies.
-Use JSON when the complete evidence package or machine processing is required.
-The browser Console reuses this bounded Markdown renderer for domain results
-after first reducing the typed Lookup response to the known normalised fields
-needed by the report. It separately offers bounded IP and ASN summaries from
-their normalised RDAP and source-health fields; IP reports can also include
-bounded reverse-DNS context already collected by Lookup. The browser action
-does not change the CLI input or output contract.
-When a version-5, version-6, or version-7 lookup records a documented registry-access constraint, both
-Markdown and HTML include that context in collection diagnostics without
-changing its non-authoritative interpretation. Both formats also include the
-selected address and bounded network registration when present, together with
-the edge-versus-origin limitation.
-
-HTML uses the same bounded summary model as Markdown. The generated document
-contains inline styling for screen and print, but no scripts, forms, active
-links, or external resources. A restrictive embedded Content Security Policy
-provides defence in depth when the local file is opened in a browser. All
-registry values are HTML-escaped and displayed as text.
-
-This is a deliberately rich evidence package. Raw registry sources can contain
-publicly published contact data, and deep availability evidence can contain
-bounded website, DNS, mail, page-identity, and TLS observations. Review and
-secure the output before sharing it. The CLI does not add browser-only IDN
-profile analysis, so that optional evidence field is `null`.
+| 0 | The command completed; individual sources can still be partial. |
+| 2 | The command, option or input was invalid. |
+| 3 | Collection, lookup or comparison failed. |
+| 4 | The result was partial or a selected evidence policy was not met. |
+| 70 | The CLI could not complete bootstrap. |
+| 130 | The analyst cancelled; no partial final result was emitted. |
+| 143 | SIGTERM stopped the process; no partial final result was emitted. |
+
+## Portable documents and compatibility
+
+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 v6 and exact public v5. 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 27. Exact public schema 26 remains readable and can contain
+public contact fields; current schema 27 excludes raw registration payloads,
+expanded contacts, credentials, complete query-bearing URLs and provider
+payloads.
+
+`verify-artifact` checks a recognised structure and its applicable integrity
+contract. `interchange-report` describes retained and omitted fields.
+`sign-artifact` and `verify-signature` keep artefact validity, signature
+validity and signer trust separate. None of these checks establishes that
+evidence is accurate, current, safe to share or attributable to a person.
+
+## Command-family boundaries
+
+- Evidence collection commands retain separate source states. A failed or
+  missing supporting source is not converted into absence, availability or a
+  favourable score.
+- Discover and Certificate Transparency commands produce review candidates.
+  Generation, publication and shared infrastructure do not establish ownership,
+  control, activity, intent or maliciousness.
+- 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 prepare local Cases, packets and sharing reviews. They do not
+  submit, publish, notify or grant 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 for analyst-selection placeholders.
+
+Use the installed focused help for positional inputs, exact ceilings, options,
+network effects, outputs and command-specific exit behaviour.