audit, advisories and doctors/setup work

docs/API_CLI_REFERENCE.md

@@ -65,3 +65,106 @@ For the detailed contract, see `docs/api/overview.md`. The stable rules to keep
 - Determinism: stable ordering, stable ids, UTC ISO-8601 timestamps, and canonical hashing where applicable.
 - Streaming: some endpoints use NDJSON (`application/x-ndjson`) for deterministic, resumable tile/record streams.
 - Offline-first: workflows must remain runnable in air-gapped mode using Offline Kit bundles and locally verifiable signatures.
+
+## stella scan diff
+
+Compare ELF binaries between two container images using section hashes.
+
+### Synopsis
+
+```bash
+stella scan diff --base <image-ref> --target <image-ref> [options]
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--base`, `-b` | Base image reference (tag or digest). |
+| `--target`, `-t` | Target image reference (tag or digest). |
+| `--mode`, `-m` | Analysis mode: `elf`, `pe`, `auto` (default: `auto`, currently uses ELF). |
+| `--emit-dsse`, `-d` | Directory for DSSE attestation output. |
+| `--signing-key` | Path to ECDSA private key (PEM) for DSSE signing. |
+| `--format`, `-f` | Output format: `table`, `json`, `summary` (default: `table`). |
+| `--platform`, `-p` | Platform filter (e.g., `linux/amd64`). |
+| `--include-unchanged` | Include unchanged binaries in output. |
+| `--sections` | Sections to analyze (comma-separated or repeatable). |
+| `--registry-auth` | Path to Docker config for registry authentication. |
+| `--timeout` | Timeout in seconds (default: 300). |
+| `--verbose`, `-v` | Enable verbose output. |
+
+Note: `--emit-dsse` requires `--signing-key` to sign the DSSE envelope.
+
+### Examples
+
+```bash
+# Basic comparison
+stella scan diff --base myapp:1.0.0 --target myapp:1.0.1
+
+# DSSE output with signing key
+stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 \
+  --mode=elf --emit-dsse=./attestations --signing-key=./keys/binarydiff.pem
+
+# JSON output for automation
+stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --format=json > diff.json
+
+# Specific platform
+stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --platform=linux/amd64
+```
+
+### Output
+
+DSSE output produces two files per platform:
+
+```
+attestations/
+  linux-amd64-binarydiff.dsse.json
+  linux-amd64-binarydiff.payload.json
+```
+
+See also: `docs/modules/scanner/binary-diff-attestation.md`.
+
+## stella image inspect
+
+Inspect OCI image manifests and layers.
+
+### Synopsis
+
+```bash
+stella image inspect <reference> [options]
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--resolve-index`, `-r` | Resolve multi-arch index to platform manifests (default: true). |
+| `--print-layers`, `-l` | Include layer details in output (default: true). |
+| `--platform`, `-p` | Platform filter (e.g., `linux/amd64`). |
+| `--output`, `-o` | Output format: `table`, `json` (default: `table`). |
+| `--timeout` | Timeout in seconds (default: 60). |
+| `--verbose`, `-v` | Enable verbose output. |
+
+### Examples
+
+```bash
+# Basic inspection
+stella image inspect nginx:latest
+
+# JSON output
+stella image inspect nginx:latest --output json
+
+# Filter to a single platform
+stella image inspect nginx:latest --platform linux/amd64
+
+# Local registry over HTTP
+stella image inspect http://localhost:5000/myapp:1.0.0
+```
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Image not found |
+| `2` | Error (auth, network, invalid input, timeout) |