diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index e6ef5a2..58d16c7 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -44,3 +44,12 @@ updates:
     ignore:
       - dependency-name: "*"
         update-types: ["version-update:semver-major"]
+
+  # The pinned base image of the container image (packaging/container/Dockerfile).
+  - package-ecosystem: "docker"
+    directory: "/packaging/container"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
diff --git a/.github/scripts/openapi-drift-issue.sh b/.github/scripts/openapi-drift-issue.sh
new file mode 100755
index 0000000..a1970ee
--- /dev/null
+++ b/.github/scripts/openapi-drift-issue.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+# Keeps one open issue per label in step with the state of the OpenAPI check.
+#
+#   openapi-drift-issue.sh report <label> <title> <body-file> [<marker>]
+#       Opens an issue with the label, or comments on the open one. With a marker, nothing is
+#       posted when the issue or one of its comments already contains it.
+#   openapi-drift-issue.sh resolve <label> <comment>
+#       Comments on and closes the open issue with the label, if there is one.
+#
+# Needs gh, GH_TOKEN and GITHUB_REPOSITORY. Titles, bodies and comments are passed to gh as files or
+# arguments, never evaluated.
+set -euo pipefail
+
+mode=${1:?mode}
+label=${2:?label}
+
+ensure_label() {
+  local found
+  found=$(gh label list --repo "$GITHUB_REPOSITORY" --search "$label" --json name --jq '.[].name')
+  if ! grep -Fxq -- "$label" <<<"$found"; then
+    gh label create "$label" --repo "$GITHUB_REPOSITORY" --color D4C5F9 \
+      --description "Reported by the OpenAPI sync workflow" > /dev/null
+  fi
+}
+
+open_issue() {
+  gh issue list --repo "$GITHUB_REPOSITORY" --label "$label" --state open --json number --jq '.[0].number // empty'
+}
+
+case "$mode" in
+  report)
+    title=${3:?title}
+    body_file=${4:?body file}
+    marker=${5:-}
+    ensure_label
+    number=$(open_issue)
+    if [ -z "$number" ]; then
+      gh issue create --repo "$GITHUB_REPOSITORY" --title "$title" --label "$label" --body-file "$body_file"
+    elif [ -n "$marker" ] && gh issue view "$number" --repo "$GITHUB_REPOSITORY" --json body,comments \
+      --jq '[.body, (.comments[].body)] | join("\n")' | grep -Fq -- "$marker"; then
+      echo "Issue #$number already reports this state"
+    else
+      gh issue comment "$number" --repo "$GITHUB_REPOSITORY" --body-file "$body_file"
+      echo "Commented on issue #$number"
+    fi
+    ;;
+  resolve)
+    comment=${3:?comment}
+    number=$(open_issue)
+    if [ -n "$number" ]; then
+      gh issue close "$number" --repo "$GITHUB_REPOSITORY" --reason completed --comment "$comment"
+      echo "Closed issue #$number"
+    else
+      echo "No open issue with the label $label"
+    fi
+    ;;
+  *)
+    echo "unknown mode: $mode" >&2
+    exit 2
+    ;;
+esac
diff --git a/.github/scripts/openapi-drift-report.py b/.github/scripts/openapi-drift-report.py
new file mode 100755
index 0000000..c2b72c4
--- /dev/null
+++ b/.github/scripts/openapi-drift-report.py
@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+"""Writes the issue body that reports a difference between openapi/v1.json and the published document.
+
+Usage: openapi-drift-report.py <oasdiff> <dir> <run-url>
+
+<dir> is the output directory of openapi-sync.py (it holds `published.json` and `vendored.json`);
+`body.md` is written there and `breaking=true|false` is printed for $GITHUB_OUTPUT.
+
+oasdiff runs in both directions, since either side may be the one that is behind:
+  vendored -> published  breaking: a client built from openapi/v1.json may fail against the published document
+  published -> vendored  breaking: a client built from the published document may fail against openapi/v1.json
+Breaking means an oasdiff change of level ERR, as `oasdiff breaking --fail-on ERR` counts it.
+
+The text oasdiff prints comes from the published document, so it is untrusted: it is truncated and
+only ever placed inside a code fence longer than any backtick run it contains. Any failure of
+oasdiff is an error (exit 1), never a quiet pass.
+"""
+
+import hashlib
+import json
+import pathlib
+import re
+import subprocess
+import sys
+
+MAX_CHARS = 8000
+ERR_LEVEL = 3
+
+
+def run(oasdiff, directory, *args):
+    result = subprocess.run(
+        [oasdiff, *args], cwd=directory, capture_output=True, text=True, errors="replace", timeout=300
+    )
+    if result.returncode != 0:
+        raise SystemExit(f"error: oasdiff {args[0]} failed (exit {result.returncode}): {result.stderr.strip()[:500]}")
+    return result.stdout
+
+
+def breaking(oasdiff, directory, base, revision):
+    try:
+        changes = json.loads(run(oasdiff, directory, "breaking", base, revision, "-f", "json") or "[]")
+    except ValueError as e:
+        raise SystemExit(f"error: oasdiff breaking printed output that is not JSON: {e}")
+    if not isinstance(changes, list):
+        raise SystemExit("error: oasdiff breaking printed an unexpected document")
+    return [c for c in changes if isinstance(c, dict) and c.get("level", 0) >= ERR_LEVEL]
+
+
+def clean(text):
+    return re.sub(r"[\x00-\x08\x0b-\x1f\x7f]", "", text)
+
+
+def fenced(text):
+    """Truncates `text` and wraps it in a fence that no backtick run inside it can close."""
+    text = clean(text).strip()
+    note = ""
+    if len(text) > MAX_CHARS:
+        text, note = text[:MAX_CHARS], "\n[truncated]"
+    fence = "`" * max(3, max((len(m) for m in re.findall(r"`+", text)), default=0) + 1)
+    return f"{fence}text\n{text}{note}\n{fence}"
+
+
+def info_version(path):
+    return json.loads(path.read_text())["info"]["version"]
+
+
+def main():
+    oasdiff, directory, run_url = sys.argv[1], pathlib.Path(sys.argv[2]), sys.argv[3]
+    published = directory / "published.json"
+    digest = hashlib.sha256(published.read_bytes()).hexdigest()
+    vendored_digest = hashlib.sha256((directory / "vendored.json").read_bytes()).hexdigest()
+    forward = breaking(oasdiff, directory, "vendored.json", "published.json")
+    backward = breaking(oasdiff, directory, "published.json", "vendored.json")
+    changelog = run(oasdiff, directory, "changelog", "published.json", "vendored.json")
+    summary = run(oasdiff, directory, "summary", "published.json", "vendored.json")
+
+    def lines(changes):
+        return "\n".join(f"{c.get('operation', '')} {c.get('path', '')}: {c.get('text', '')}".strip() for c in changes) or "none"
+
+    def verdict(changes):
+        return f"**yes**, {len(changes)} breaking change(s)" if changes else "no"
+
+    body = f"""The published `/v1` OpenAPI document differs in content from the vendored `openapi/v1.json`. Key order and whitespace are not compared.
+
+| | Published document | `openapi/v1.json` |
+|---|---|---|
+| `info.version` | `{info_version(published)}` | `{info_version(directory / "vendored.json")}` |
+| SHA-256 | `{digest}` | `{vendored_digest}` |
+
+**Breaking changes, according to [oasdiff](https://github.com/oasdiff/oasdiff)**
+
+- From `openapi/v1.json` to the published document (a client built from the vendored copy may fail against the published one): {verdict(forward)}
+- From the published document to `openapi/v1.json` (a client built from the published document may fail against the vendored copy): {verdict(backward)}
+
+**Breaking changes from `openapi/v1.json` to the published document**
+
+{fenced(lines(forward))}
+
+**Breaking changes from the published document to `openapi/v1.json`**
+
+{fenced(lines(backward))}
+
+**Summary, published to vendored**
+
+{fenced(summary)}
+
+**Changelog, published to vendored**
+
+{fenced(changelog)}
+
+The vendored document is not updated automatically. Decide whether the API or the vendored copy is behind, then fix that side.
+
+Reported by the OpenAPI sync workflow: {run_url}
+
+<!-- openapi-drift:{digest} -->
+"""
+    (directory / "body.md").write_text(body)
+    print(f"breaking={'true' if forward or backward else 'false'}")
+    print(f"published_sha256={digest}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/scripts/openapi-sync.py b/.github/scripts/openapi-sync.py
index a5e72ec..5cb1ecc 100755
--- a/.github/scripts/openapi-sync.py
+++ b/.github/scripts/openapi-sync.py
@@ -1,20 +1,19 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
 # Copyright 2026 Hodeitek S.L.
-"""Compares openapi/v1.json with the document the API publishes and, when their content differs,
-replaces the vendored copy and updates what records it (openapi/README.md, xtask's EXPECTED_SHA256).
+"""Compares openapi/v1.json with the document the API publishes. Changes nothing in the repository.
 
 Usage: openapi-sync.py <url> <out-dir>
 
-Content means the JSON value: key order and whitespace do not count. On a difference the published
-bytes are written unchanged, as openapi/README.md requires, and <out-dir> receives `old.json` (the
-previous copy), `summary.md` and `version.txt`. Exits 0 in both cases and prints `changed=true` or
-`changed=false`; anything wrong with the published document is an error (exit 1).
+Content means the JSON value: key order and whitespace do not count. <out-dir> receives
+`published.json` (the published bytes, unchanged) and `vendored.json` (a copy of openapi/v1.json).
+Prints `changed=true` or `changed=false` and the two `info.version` values, as `key=value` lines
+fit for $GITHUB_OUTPUT, and exits 0 in both cases; anything wrong with the published document, or
+a failure to fetch it, is an error (exit 1) so the caller fails closed.
 
 Run from the repository root. Uses only the standard library.
 """
 
-import hashlib
 import json
 import pathlib
 import re
@@ -22,8 +21,6 @@
 import urllib.request
 
 SPEC = pathlib.Path("openapi/v1.json")
-README = pathlib.Path("openapi/README.md")
-XTASK = pathlib.Path("xtask/src/main.rs")
 MAX_BYTES = 5 * 1024 * 1024
 USER_AGENT = "hodeishield-cli-openapi-sync (+https://github.com/Hodeitek/hodeishield-cli)"
 
@@ -41,7 +38,7 @@ def check(document, url):
     if not str(document.get("openapi", "")).startswith("3."):
         raise SystemExit(f"error: {url} is not an OpenAPI 3 document")
     version = document.get("info", {}).get("version")
-    # It ends up in a branch commit, a pull request title and workflow outputs: plain text only.
+    # It ends up in an issue and in workflow outputs: plain text only.
     if not isinstance(version, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._+-]{0,39}", version):
         raise SystemExit(f"error: {url} has a missing or unusual info.version")
     if not document.get("paths"):
@@ -66,19 +63,12 @@ def canonical(document):
     return json.dumps(document, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
 
 
-def operations(document):
-    methods = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
-    return {
-        f"{method.upper()} {path}"
-        for path, item in document["paths"].items()
-        for method in item
-        if method in methods
-    }
-
-
 def main():
     url, out = sys.argv[1], pathlib.Path(sys.argv[2])
-    published = fetch(url)
+    try:
+        published = fetch(url)
+    except OSError as e:
+        raise SystemExit(f"error: cannot fetch {url}: {e}")
     try:
         new = json.loads(published)
     except ValueError as e:
@@ -87,46 +77,13 @@ def main():
     local_refs_only(new, url)
     current = SPEC.read_bytes()
     old = json.loads(current)
-    if canonical(new) == canonical(old):
-        print("changed=false")
-        return
-
     out.mkdir(parents=True, exist_ok=True)
-    (out / "old.json").write_bytes(current)
-    SPEC.write_bytes(published)
-    digest = hashlib.sha256(published).hexdigest()
-    old_digest = hashlib.sha256(current).hexdigest()
-    version, old_version = new["info"]["version"], old["info"]["version"]
-    ops, old_ops = operations(new), operations(old)
-    non_get = sorted(op for op in ops if not op.startswith("GET "))
-    count = f"{len(ops)}, all `GET`" if not non_get else str(len(ops))
-
-    readme = README.read_text()
-    readme = re.sub(r"(\| `info\.version` \| `)[^`]*(` \|)", rf"\g<1>{version}\g<2>", readme)
-    readme = re.sub(r"(\| SHA-256 \| `)[0-9a-f]{64}(` \|)", rf"\g<1>{digest}\g<2>", readme)
-    readme = re.sub(r"(\| Operations \| )[^|\n]*?( \|)", rf"\g<1>{count}\g<2>", readme)
-    README.write_text(readme)
-    xtask = XTASK.read_text()
-    xtask, replaced = re.subn(
-        r'(const EXPECTED_SHA256: &str = ")[0-9a-f]{64}(";)', rf"\g<1>{digest}\g<2>", xtask
-    )
-    if replaced != 1:
-        raise SystemExit(f"error: EXPECTED_SHA256 not found in {XTASK}")
-    XTASK.write_text(xtask)
-
-    lines = [
-        f"- `info.version`: `{old_version}` → `{version}`",
-        f"- SHA-256: `{old_digest[:12]}…` → `{digest[:12]}…`",
-        f"- Operations: {len(old_ops)} → {len(ops)}",
-    ]
-    for label, items in (("Added", sorted(ops - old_ops)), ("Removed", sorted(old_ops - ops))):
-        if items:
-            lines.append(f"- {label} operations: " + ", ".join(f"`{op}`" for op in items))
-    if non_get:
-        lines.append("- **Not read-only**: " + ", ".join(f"`{op}`" for op in non_get))
-    (out / "summary.md").write_text("\n".join(lines) + "\n")
-    (out / "version.txt").write_text(version + "\n")
-    print("changed=true")
+    (out / "published.json").write_bytes(published)
+    (out / "vendored.json").write_bytes(current)
+    changed = canonical(new) != canonical(old)
+    print(f"changed={'true' if changed else 'false'}")
+    print(f"published_version={new['info']['version']}")
+    print(f"vendored_version={old['info'].get('version')}")
 
 
 if __name__ == "__main__":
diff --git a/.github/scripts/package-manifests.py b/.github/scripts/package-manifests.py
index 843a228..aa5d751 100644
--- a/.github/scripts/package-manifests.py
+++ b/.github/scripts/package-manifests.py
@@ -12,7 +12,9 @@
 
 Every URL points at an asset of the release and every hash comes from its SHA256SUMS, so a file
 missing from the release is an error. The winget installer is the MSI when the release has one
-(its product code must then be given), otherwise the zip with the portable exe inside.
+(its product code must then be given), otherwise the zip with the portable exe inside. The Scoop
+manifest also lists the arm64 zip when the release has one; winget stays x64 only until there is an
+arm64 MSI.
 
 Uses only the standard library.
 """
@@ -48,6 +50,9 @@ def asset(target, ext):
     x86_url, x86_sha = asset("x86_64-unknown-linux-musl", "tar.gz")
     arm_url, arm_sha = asset("aarch64-unknown-linux-musl", "tar.gz")
     zip_url, zip_sha = asset("x86_64-pc-windows-msvc", "zip")
+    # Releases before the Windows arm64 build do not have this zip: Scoop then lists 64bit only.
+    has_arm64_zip = f"hodeishield-{version}-aarch64-pc-windows-msvc.zip" in sums
+    arm64_zip_url, arm64_zip_sha = asset("aarch64-pc-windows-msvc", "zip") if has_arm64_zip else (None, None)
     msi_name = f"hodeishield-{version}-x86_64-pc-windows-msvc.msi"
     has_msi = msi_name in sums
     if has_msi and not (product_code and re.fullmatch(r"\{[0-9A-F-]{36}\}", product_code)):
@@ -98,18 +103,25 @@ def install
 
     manifest = out / "scoop" / "bucket" / "hodeishield.json"
     manifest.parent.mkdir(parents=True, exist_ok=True)
+    scoop_arch = {"64bit": {"url": zip_url, "hash": zip_sha}}
+    scoop_autoupdate = {"64bit": {
+        "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-x86_64-pc-windows-msvc.zip"
+    }}
+    if has_arm64_zip:
+        scoop_arch["arm64"] = {"url": arm64_zip_url, "hash": arm64_zip_sha}
+        scoop_autoupdate["arm64"] = {
+            "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-aarch64-pc-windows-msvc.zip"
+        }
     manifest.write_text(json.dumps({
         "version": version,
         "description": DESCRIPTION,
         "homepage": "https://hodeishield.com",
         "license": "Apache-2.0",
-        "architecture": {"64bit": {"url": zip_url, "hash": zip_sha}},
+        "architecture": scoop_arch,
         "bin": "hodeishield.exe",
         "checkver": {"github": f"https://github.com/{REPO}"},
         "autoupdate": {
-            "architecture": {"64bit": {
-                "url": f"https://github.com/{REPO}/releases/download/v$version/hodeishield-$version-x86_64-pc-windows-msvc.zip"
-            }},
+            "architecture": scoop_autoupdate,
             "hash": {"url": "$baseurl/SHA256SUMS"},
         },
     }, indent=4) + "\n")
diff --git a/.github/scripts/proxy-tls-fake-api.py b/.github/scripts/proxy-tls-fake-api.py
new file mode 100644
index 0000000..cd1af0d
--- /dev/null
+++ b/.github/scripts/proxy-tls-fake-api.py
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+"""A tiny HTTPS stand-in for the API, used only by proxy-tls-test.sh.
+
+Usage: proxy-tls-fake-api.py CERT KEY PORT LOGFILE
+
+It answers GET /v1/vendors with one vendor and logs one line per request to LOGFILE, so the test
+can tell which requests reached it. It binds to 127.0.0.1 only.
+"""
+
+import json
+import ssl
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlsplit
+
+VENDOR = {
+    "id": "v1",
+    "name": "Example Hosting",
+    "legal_name": None,
+    "domain": "example.com",
+    "category": None,
+    "vendor_type": None,
+    "access_level": None,
+    "business_criticality": "high",
+    "data_sensitivity": None,
+    "economic_impact": None,
+    "active": True,
+    "monitoring_status": None,
+    "last_scan_at": "2026-03-04T05:06:07.000Z",
+    "lei": None,
+    "hq_country": None,
+    "created_at": "2026-01-01T00:00:00Z",
+    "updated_at": "2026-01-01T00:00:00Z",
+}
+PAGE = {
+    "data": [VENDOR],
+    "pagination": {"page": 1, "per_page": 50, "total": 1, "total_pages": 1},
+}
+
+
+def main() -> None:
+    cert, key, port, logfile = sys.argv[1], sys.argv[2], int(sys.argv[3]), sys.argv[4]
+    log = open(logfile, "a", buffering=1, encoding="utf-8")
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            path = urlsplit(self.path).path
+            log.write(f"GET {path}\n")
+            if path == "/v1/vendors":
+                body = json.dumps(PAGE).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+            else:
+                body = b"{}"
+                self.send_response(404)
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *_args) -> None:
+            pass
+
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    context.load_cert_chain(cert, key)
+    server = ThreadingHTTPServer(("127.0.0.1", port), Handler)
+    server.socket = context.wrap_socket(server.socket, server_side=True)
+    server.serve_forever()
+
+
+main()
diff --git a/.github/scripts/proxy-tls-test.sh b/.github/scripts/proxy-tls-test.sh
new file mode 100755
index 0000000..145a0dd
--- /dev/null
+++ b/.github/scripts/proxy-tls-test.sh
@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+#
+# Proves the README's "Networking: proxies and TLS inspection" claims on Linux, end to end, with a
+# real TLS-inspecting proxy (mitmproxy) and a fake API, all on this machine:
+#
+#   1. HTTPS_PROXY set, proxy CA not trusted       -> exit 7, "error: Could not reach the API:", certificate
+#   2. proxy CA in the system store                -> works, and the proxy saw the request
+#   3. proxy CA only in SSL_CERT_FILE              -> works
+#   4. NO_PROXY covers the host                    -> the proxy is not used
+#   5. lower-case https_proxy                      -> works like HTTPS_PROXY
+#   6. --verbose                                   -> the request line goes to stderr only
+#
+# The API is reached as api.test:8443, mapped to 127.0.0.1 in /etc/hosts, because the CLI never uses
+# a proxy for a loopback URL. The fake API's certificate comes from one throwaway CA that only the
+# proxy trusts; the proxy re-signs with another throwaway CA, the one the CLI must trust.
+#
+# This is meant to run in CI (GitHub Actions): it edits /etc/hosts and the system certificate store,
+# and case 1 is a deliberate failure. It refuses to run elsewhere.
+#
+# Usage: proxy-tls-test.sh PATH_TO_HODEISHIELD PATH_TO_MITMPROXY_DIR
+set -euo pipefail
+
+if [ "${GITHUB_ACTIONS:-}" != "true" ]; then
+  echo "proxy-tls-test.sh edits /etc/hosts and the system certificate store: it only runs in GitHub Actions." >&2
+  exit 2
+fi
+BIN=$(realpath "${1:?usage: proxy-tls-test.sh HODEISHIELD MITMPROXY_DIR}")
+MITM=$(realpath "${2:?usage: proxy-tls-test.sh HODEISHIELD MITMPROXY_DIR}")
+SCRIPTS=$(cd "$(dirname "$0")" && pwd)
+
+HOST=api.test
+API_PORT=8443
+PROXY_PORT=8080
+API_URL="https://$HOST:$API_PORT"
+REQ_RE="GET https://$HOST:$API_PORT/v1/vendors"
+
+WORK=$(mktemp -d)
+PIDS=()
+# shellcheck disable=SC2329  # invoked by the EXIT trap
+cleanup() {
+  for pid in "${PIDS[@]}"; do kill "$pid" 2> /dev/null || true; done
+  rm -rf "$WORK"
+}
+trap cleanup EXIT
+
+# --- Throwaway certificates -------------------------------------------------------------------
+make_ca() {
+  openssl req -x509 -newkey rsa:2048 -nodes -days 2 -subj "/CN=Test $1 CA" \
+    -addext "basicConstraints=critical,CA:TRUE" -addext "keyUsage=critical,keyCertSign,cRLSign" \
+    -keyout "$WORK/$1-ca.key" -out "$WORK/$1-ca.crt" 2> /dev/null
+}
+make_ca upstream # signs the fake API's certificate; trusted by the proxy only
+make_ca proxy    # the "corporate" CA the proxy re-signs with; what the CLI must trust
+
+openssl req -newkey rsa:2048 -nodes -subj "/CN=$HOST" \
+  -keyout "$WORK/api.key" -out "$WORK/api.csr" 2> /dev/null
+openssl x509 -req -in "$WORK/api.csr" -CA "$WORK/upstream-ca.crt" -CAkey "$WORK/upstream-ca.key" \
+  -CAcreateserial -days 2 -out "$WORK/api.crt" \
+  -extfile <(printf 'subjectAltName=DNS:%s\nbasicConstraints=CA:FALSE\n' "$HOST") 2> /dev/null
+
+mkdir "$WORK/confdir"
+cat "$WORK/proxy-ca.key" "$WORK/proxy-ca.crt" > "$WORK/confdir/mitmproxy-ca.pem"
+cp "$WORK/proxy-ca.crt" "$WORK/confdir/mitmproxy-ca-cert.pem"
+
+# --- Name, fake API, proxy --------------------------------------------------------------------
+echo "127.0.0.1 $HOST" | sudo tee -a /etc/hosts > /dev/null
+
+: > "$WORK/api.log"
+python3 -I "$SCRIPTS/proxy-tls-fake-api.py" "$WORK/api.crt" "$WORK/api.key" "$API_PORT" "$WORK/api.log" &
+PIDS+=($!)
+
+PYTHONUNBUFFERED=1 "$MITM/mitmdump" --set "confdir=$WORK/confdir" \
+  --set "ssl_verify_upstream_trusted_ca=$WORK/upstream-ca.crt" \
+  --listen-host 127.0.0.1 --listen-port "$PROXY_PORT" --flow-detail 1 > "$WORK/proxy.log" 2>&1 &
+PIDS+=($!)
+
+wait_port() {
+  for _ in $(seq 1 50); do
+    if (echo > "/dev/tcp/127.0.0.1/$1") 2> /dev/null; then return 0; fi
+    sleep 0.2
+  done
+  echo "nothing is listening on port $1" >&2
+  cat "$WORK/proxy.log" >&2 || true
+  exit 1
+}
+wait_port "$API_PORT"
+wait_port "$PROXY_PORT"
+
+# --- Helpers ----------------------------------------------------------------------------------
+RESULTS=()
+FAILED=0
+record() { # case, description, PASS|FAIL, detail
+  RESULTS+=("$1|$2|$3|$4")
+  if [ "$3" != PASS ]; then FAILED=1; fi
+}
+
+# Runs the CLI with a clean proxy/certificate environment plus the given NAME=value pairs.
+# Usage: cli [NAME=value ...] -- args...   Leaves rc, $WORK/out and $WORK/err.
+cli() {
+  local extra=()
+  while [ "$1" != -- ]; do extra+=("$1"); shift; done
+  shift
+  rc=0
+  env -u HTTPS_PROXY -u https_proxy -u HTTP_PROXY -u http_proxy -u ALL_PROXY -u all_proxy \
+    -u NO_PROXY -u no_proxy -u SSL_CERT_FILE -u SSL_CERT_DIR \
+    HODEISHIELD_CONFIG="$WORK/config.toml" HODEISHIELD_API_KEY=hsk_test_0123456789abcdef \
+    HODEISHIELD_API_URL="$API_URL" DBUS_SESSION_BUS_ADDRESS=unix:path=/nonexistent/hodeishield-test \
+    NO_COLOR=1 "${extra[@]}" "$BIN" "$@" > "$WORK/out" 2> "$WORK/err" || rc=$?
+}
+
+count() { grep -c -- "$2" "$1" || true; }
+proxy_seen() { count "$WORK/proxy.log" "$REQ_RE"; }
+api_seen() { count "$WORK/api.log" "GET /v1/vendors"; }
+
+# Waits (up to 5 s) for the proxy log to show more requests than $1.
+wait_proxy_above() {
+  for _ in $(seq 1 25); do
+    if [ "$(proxy_seen)" -gt "$1" ]; then return 0; fi
+    sleep 0.2
+  done
+  return 1
+}
+
+show_failure() {
+  echo "--- case $1: exit $rc"
+  echo "--- stdout"; head -c 2000 "$WORK/out"
+  echo "--- stderr"; head -c 2000 "$WORK/err"
+}
+
+# A successful run: exit 0 and the vendor on stdout as JSON.
+works() { [ "$rc" -eq 0 ] && jq -e '.data[0].id == "v1"' "$WORK/out" > /dev/null 2>&1; }
+
+PROXY=http://127.0.0.1:$PROXY_PORT
+
+# --- Case 1: the proxy's CA is not trusted ----------------------------------------------------
+p0=$(proxy_seen) a0=$(api_seen)
+cli HTTPS_PROXY="$PROXY" -- vendors list --json
+sleep 1
+if [ "$rc" -eq 7 ] && [[ "$(cat "$WORK/err")" == "error: Could not reach the API:"* ]] \
+  && grep -qiE 'certificate|UnknownIssuer' "$WORK/err" \
+  && [ "$(proxy_seen)" -eq "$p0" ] && [ "$(api_seen)" -eq "$a0" ]; then
+  record 1 "HTTPS_PROXY, proxy CA not trusted: exit 7, certificate error, nothing delivered" PASS "exit $rc"
+else
+  record 1 "HTTPS_PROXY, proxy CA not trusted: exit 7, certificate error, nothing delivered" FAIL "exit $rc"
+  show_failure 1
+fi
+
+# --- Case 3: the proxy's CA only in SSL_CERT_FILE (run before it enters the system store) -----
+p0=$(proxy_seen)
+cli HTTPS_PROXY="$PROXY" SSL_CERT_FILE="$WORK/proxy-ca.crt" -- vendors list --json
+if works && wait_proxy_above "$p0"; then
+  record 3 "proxy CA only in SSL_CERT_FILE: works through the proxy" PASS "exit $rc"
+else
+  record 3 "proxy CA only in SSL_CERT_FILE: works through the proxy" FAIL "exit $rc"
+  show_failure 3
+fi
+
+# --- Case 4: NO_PROXY covers the host: direct, the proxy never sees it ------------------------
+p0=$(proxy_seen) a0=$(api_seen)
+cli HTTPS_PROXY="$PROXY" NO_PROXY="$HOST" SSL_CERT_FILE="$WORK/upstream-ca.crt" -- vendors list --json
+sleep 1
+if works && [ "$(api_seen)" -gt "$a0" ] && [ "$(proxy_seen)" -eq "$p0" ]; then
+  record 4 "NO_PROXY covers the host: direct to the API, proxy bypassed" PASS "exit $rc"
+else
+  record 4 "NO_PROXY covers the host: direct to the API, proxy bypassed" FAIL "exit $rc"
+  show_failure 4
+fi
+
+# --- Case 2: the proxy's CA in the system store ------------------------------------------------
+sudo cp "$WORK/proxy-ca.crt" /usr/local/share/ca-certificates/hodeishield-test-proxy-ca.crt
+sudo update-ca-certificates > /dev/null
+p0=$(proxy_seen)
+cli HTTPS_PROXY="$PROXY" -- vendors list --json
+if works && wait_proxy_above "$p0"; then
+  record 2 "proxy CA in the system store: works, the proxy saw the request" PASS "exit $rc"
+else
+  record 2 "proxy CA in the system store: works, the proxy saw the request" FAIL "exit $rc"
+  show_failure 2
+fi
+
+# --- Case 5: lower-case https_proxy ------------------------------------------------------------
+p0=$(proxy_seen)
+cli https_proxy="$PROXY" -- vendors list --json
+if works && wait_proxy_above "$p0"; then
+  record 5 "lower-case https_proxy works like upper-case" PASS "exit $rc"
+else
+  record 5 "lower-case https_proxy works like upper-case" FAIL "exit $rc"
+  show_failure 5
+fi
+
+# --- Case 6: --verbose writes the request line to stderr only ----------------------------------
+cli HTTPS_PROXY="$PROXY" -- --verbose vendors list --json
+if works && grep -qE "^GET https://api\.test:8443/v1/vendors.* → 200 " "$WORK/err" \
+  && ! grep -q "GET " "$WORK/out"; then
+  record 6 "--verbose: request line on stderr, stdout stays clean JSON" PASS "exit $rc"
+else
+  record 6 "--verbose: request line on stderr, stdout stays clean JSON" FAIL "exit $rc"
+  show_failure 6
+fi
+
+# --- Report ------------------------------------------------------------------------------------
+echo
+printf '%-5s %-78s %s\n' CASE DESCRIPTION RESULT
+while IFS='|' read -r n desc result _detail; do
+  printf '%-5s %-78s %s\n' "$n" "$desc" "$result"
+done < <(printf '%s\n' "${RESULTS[@]}" | sort)
+if [ "$FAILED" -ne 0 ]; then
+  echo
+  echo "--- proxy log"; tail -n 40 "$WORK/proxy.log"
+  echo "--- fake API log"; tail -n 20 "$WORK/api.log"
+fi
+exit "$FAILED"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4e8dc18..217a195 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -85,7 +85,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        # windows-11-arm is the GitHub-hosted native Windows on Arm runner: the aarch64 Windows
+        # build is tested where it runs, not only cross-compiled.
+        os: [ubuntu-latest, macos-latest, windows-latest, windows-11-arm]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -107,6 +109,10 @@ jobs:
       - name: cargo test
         run: cargo test --workspace --locked
 
+      - name: cargo clippy (Windows on Arm)
+        if: matrix.os == 'windows-11-arm'
+        run: cargo clippy --workspace --all-targets --locked -- -D warnings
+
       # The Visual C++ runtime is not part of Windows: the executable must not import it (see
       # .cargo/config.toml).
       - name: Build the executable (Windows)
@@ -120,7 +126,10 @@ jobs:
           $ErrorActionPreference = "Stop"
           $vswhere = Join-Path ${env:ProgramFiles(x86)} "Microsoft Visual Studio\Installer\vswhere.exe"
           if (-not (Test-Path -LiteralPath $vswhere)) { throw "vswhere.exe not found at $vswhere" }
-          $dumpbin = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -find "VC\Tools\MSVC\**\bin\Hostx64\x64\dumpbin.exe" | Select-Object -First 1
+          # The host's own toolset first (exactly what the x64 leg always used), any host otherwise.
+          $arch = if ($env:RUNNER_ARCH -eq "ARM64") { "arm64" } else { "x64" }
+          $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host$arch\$arch\dumpbin.exe" | Select-Object -First 1
+          if (-not $dumpbin) { $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host*\*\dumpbin.exe" | Select-Object -First 1 }
           if (-not $dumpbin -or -not (Test-Path -LiteralPath $dumpbin)) { throw "dumpbin.exe not found through vswhere" }
           $exes = @(Get-ChildItem -LiteralPath target/debug -File -Filter hodeishield.exe)
           if ($exes.Count -eq 0) { throw "No .exe found to inspect in target/debug" }
@@ -139,6 +148,26 @@ jobs:
           }
           if ($failed) { exit 1 }
 
+      # The leg must build the architecture it is named after, not the host's by accident.
+      - name: Check the executable targets the runner's architecture (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        env:
+          EXPECTED: ${{ matrix.os == 'windows-11-arm' && 'AA64 machine (ARM64)' || '8664 machine (x64)' }}
+        run: |
+          $ErrorActionPreference = "Stop"
+          $vswhere = Join-Path ${env:ProgramFiles(x86)} "Microsoft Visual Studio\Installer\vswhere.exe"
+          # The host's own toolset first (exactly what the x64 leg always used), any host otherwise.
+          $arch = if ($env:RUNNER_ARCH -eq "ARM64") { "arm64" } else { "x64" }
+          $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host$arch\$arch\dumpbin.exe" | Select-Object -First 1
+          if (-not $dumpbin) { $dumpbin = & $vswhere -latest -products * -find "VC\Tools\MSVC\**\bin\Host*\*\dumpbin.exe" | Select-Object -First 1 }
+          if (-not $dumpbin -or -not (Test-Path -LiteralPath $dumpbin)) { throw "dumpbin.exe not found through vswhere" }
+          $headers = & $dumpbin /nologo /headers target/debug/hodeishield.exe
+          if ($LASTEXITCODE -ne 0) { throw "dumpbin /headers failed" }
+          if (-not ($headers | Select-String -SimpleMatch $env:EXPECTED -Quiet)) {
+            throw "hodeishield.exe is not a '$env:EXPECTED' executable"
+          }
+
   deny:
     name: deny
     runs-on: ubuntu-latest
@@ -199,6 +228,21 @@ jobs:
       - name: shellcheck
         run: shellcheck -s sh install.sh packaging/repo/*.sh
 
+      - name: Every curl call in install.sh is HTTPS-only
+        run: |
+          awk '
+            { line = line $0 }
+            /\\$/ { sub(/\\$/, "", line); next }
+            line !~ /^[ \t]*#/ && line ~ /(^|[ (`;|&])curl -/ {
+              seen++
+              if (line !~ /--proto .=https./ || line !~ /--tlsv1\.2/) {
+                print "install.sh: curl call without --proto =https and --tlsv1.2: " line; bad = 1
+              }
+            }
+            { line = "" }
+            END { if (bad || !seen) { if (!seen) print "install.sh: no curl call found"; exit 1 } }
+          ' install.sh
+
       - name: Install cosign
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
         with:
diff --git a/.github/workflows/container-image.yml b/.github/workflows/container-image.yml
new file mode 100644
index 0000000..e7677c7
--- /dev/null
+++ b/.github/workflows/container-image.yml
@@ -0,0 +1,178 @@
+name: Container image
+
+# When a release is published (not while it is a draft), builds ghcr.io/hodeitek/hodeishield-cli for
+# linux/amd64 and linux/arm64 from that release's own musl binaries, signs the image by digest with
+# cosign (keyless) and attaches the release's CycloneDX SBOM as a signed attestation. Nothing is
+# compiled here: the binaries come from the release archives, which are checked against the
+# release workflow's signed SHA256SUMS first. No `latest` tag is ever written.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: container-image
+  cancel-in-progress: false
+
+env:
+  IMAGE: ghcr.io/hodeitek/hodeishield-cli
+
+jobs:
+  image:
+    name: build, push and sign the image
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # Publishing to a registry is approved by the same reviewer as the other package channels.
+    environment: packaging
+    permissions:
+      contents: read
+      packages: write # to push the image with the job's own token; no other job has it
+      id-token: write # for cosign's Sigstore keyless (OIDC) signing
+    steps:
+      - name: Read the release version
+        id: version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+          PRERELEASE: ${{ github.event.release.prerelease }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || [ "$PRERELEASE" = true ]; then
+            echo "::notice::$TAG is not a stable release; no container image is published."
+            exit 0
+          fi
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout
+        if: steps.version.outputs.version != ''
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install cosign
+        if: steps.version.outputs.version != ''
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+        with:
+          cosign-release: "v3.1.3"
+
+      # Only the two Linux archives, their SBOMs and the file that vouches for them are downloaded.
+      - name: Download and verify the release files
+        if: steps.version.outputs.version != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          files=()
+          for t in x86_64-unknown-linux-musl aarch64-unknown-linux-musl; do
+            files+=("hodeishield-${VERSION}-${t}.tar.gz" "hodeishield-${VERSION}-${t}.cdx.json")
+          done
+          mkdir rel
+          args=(-p SHA256SUMS -p SHA256SUMS.sigstore.json)
+          for f in "${files[@]}"; do args+=(-p "$f"); done
+          gh release download "v$VERSION" -R "$GITHUB_REPOSITORY" -D rel "${args[@]}"
+          cosign verify-blob --bundle rel/SHA256SUMS.sigstore.json \
+            --certificate-identity "https://github.com/${GITHUB_REPOSITORY}/.github/workflows/release.yml@refs/tags/v${VERSION}" \
+            --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+            --certificate-github-workflow-trigger push rel/SHA256SUMS
+          for f in "${files[@]}"; do grep "  ${f}\$" rel/SHA256SUMS; done > rel/files.sums
+          [ "$(wc -l < rel/files.sums)" = 4 ]
+          (cd rel && sha256sum -c files.sums)
+
+      # amd64/ and arm64/ are the names the Dockerfile's TARGETARCH picks from.
+      - name: Stage the build context
+        if: steps.version.outputs.version != ''
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          mkdir -p ctx/amd64 ctx/arm64 ext
+          for pair in x86_64-unknown-linux-musl:amd64 aarch64-unknown-linux-musl:arm64; do
+            t="${pair%%:*}" arch="${pair##*:}"
+            tar -xzf "rel/hodeishield-${VERSION}-${t}.tar.gz" -C ext
+            d="ext/hodeishield-${VERSION}-${t}"
+            [ -f "$d/hodeishield" ] && [ ! -L "$d/hodeishield" ]
+            cp "$d/hodeishield" "ctx/$arch/hodeishield"
+            cp "$d/LICENSE" "$d/NOTICE" ctx/
+          done
+          # Both Linux targets are built from the same dependency set, so one SBOM describes the
+          # image; this checks that claim instead of assuming it.
+          python3 - "rel/hodeishield-${VERSION}-x86_64-unknown-linux-musl.cdx.json" "rel/hodeishield-${VERSION}-aarch64-unknown-linux-musl.cdx.json" <<'PY'
+          import json, sys
+          a, b = (sorted(c["purl"] for c in json.load(open(p))["components"]) for p in sys.argv[1:])
+          if a != b:
+              sys.exit("the two Linux SBOMs list different components")
+          print(len(a), "components, identical for both architectures")
+          PY
+          find ctx -type f | sort
+
+      - name: Set up Buildx
+        if: steps.version.outputs.version != ''
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - name: Log in to ghcr.io
+        if: steps.version.outputs.version != ''
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      # Only COPY steps, so building the arm64 image needs no emulation.
+      - name: Build and push
+        if: steps.version.outputs.version != ''
+        id: build
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          docker buildx build ctx \
+            --file packaging/container/Dockerfile \
+            --platform linux/amd64,linux/arm64 \
+            --tag "${IMAGE}:${VERSION}" \
+            --label "org.opencontainers.image.title=hodeishield" \
+            --label "org.opencontainers.image.version=${VERSION}" \
+            --label "org.opencontainers.image.source=https://github.com/${GITHUB_REPOSITORY}" \
+            --label "org.opencontainers.image.licenses=Apache-2.0" \
+            --provenance=false --sbom=false \
+            --metadata-file "$RUNNER_TEMP/build.json" \
+            --push
+          digest=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1]))['containerimage.digest'])" "$RUNNER_TEMP/build.json")
+          [[ "$digest" =~ ^sha256:[0-9a-f]{64}$ ]] || { echo "::error::unexpected digest: $digest"; exit 1; }
+          echo "digest=$digest" >> "$GITHUB_OUTPUT"
+          echo "Pushed ${IMAGE}:${VERSION} as ${digest}"
+
+      # Keyless, and by digest: the tag can move, the digest cannot.
+      - name: Sign the image
+        if: steps.version.outputs.version != ''
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: cosign sign --yes "${IMAGE}@${DIGEST}"
+
+      - name: Attach the SBOM as an attestation
+        if: steps.version.outputs.version != ''
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          cosign attest --yes --type cyclonedx \
+            --predicate "rel/hodeishield-${VERSION}-x86_64-unknown-linux-musl.cdx.json" \
+            "${IMAGE}@${DIGEST}"
+
+      # Checks what a user will check, with the constraints the README gives, then runs the image.
+      - name: Verify the signature and the attestation, and run the image
+        if: steps.version.outputs.version != ''
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          identity="https://github.com/${GITHUB_REPOSITORY}/.github/workflows/container-image.yml@refs/tags/v${VERSION}"
+          verify=(--certificate-identity "$identity"
+            --certificate-oidc-issuer https://token.actions.githubusercontent.com
+            --certificate-github-workflow-trigger release)
+          cosign verify "${verify[@]}" "${IMAGE}@${DIGEST}" > /dev/null
+          cosign verify-attestation --type cyclonedx "${verify[@]}" "${IMAGE}@${DIGEST}" > /dev/null
+          [ "$(docker run --rm "${IMAGE}@${DIGEST}" --version)" = "hodeishield ${VERSION}" ]
+          docker buildx imagetools inspect "${IMAGE}@${DIGEST}"
diff --git a/.github/workflows/openapi-sync.yml b/.github/workflows/openapi-sync.yml
index 1f5d1fa..19853cd 100644
--- a/.github/workflows/openapi-sync.yml
+++ b/.github/workflows/openapi-sync.yml
@@ -1,16 +1,20 @@
 name: OpenAPI sync
 
-# Keeps openapi/v1.json in step with the document the API publishes. Once a week (and on demand)
-# it compares the two by content; if they differ, it opens or updates ONE pull request against dev
-# with the new document, the regenerated client and a summary, labelled `breaking-change` when
-# oasdiff finds one. It never pushes to main and never merges anything.
+# Checks that openapi/v1.json still matches the document the API publishes. Once a week (and on
+# demand) it compares the two by content. If they differ it opens, or comments on, ONE issue
+# (label `openapi-drift`) with both versions, whether oasdiff finds a breaking change and in which
+# direction, and a summary; when they match again it closes that issue. The run is red whenever the
+# documents differ, so the scheduled run shows it too. Nothing is committed, pushed or merged: the
+# vendored copy is the reference, and a person decides which side is behind.
+#
+# A document that cannot be fetched or parsed, or an oasdiff failure, is reported the same way, in
+# an issue labelled `openapi-check-failed`, and the run is red.
 on:
   schedule:
     - cron: "17 5 * * 1" # Mondays, 05:17 UTC
   workflow_dispatch:
 
-permissions:
-  contents: read
+permissions: {}
 
 concurrency:
   group: openapi-sync
@@ -18,18 +22,21 @@ concurrency:
 
 env:
   SPEC_URL: https://api.hodeishield.com/v1/openapi.json
-  BRANCH: chore/openapi-sync
+  DRIFT_LABEL: openapi-drift
+  FAILED_LABEL: openapi-check-failed
   OASDIFF_VERSION: "1.32.1"
   OASDIFF_SHA256: 7c8939fc49b75ee11fec66a5b83b37a2fca6aee109fed85013b1ba2ac2a1ee7f
 
 jobs:
-  sync:
-    name: sync
+  check:
+    name: check
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 10
     permissions:
-      contents: write # the sync branch and its commit
-      pull-requests: write # the pull request and its labels
+      contents: read
+      issues: write # the report issue and its label
+    env:
+      GH_TOKEN: ${{ github.token }}
     steps:
       - name: Checkout dev
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -39,22 +46,15 @@ jobs:
 
       - name: Compare with the published document
         id: compare
-        run: python3 .github/scripts/openapi-sync.py "$SPEC_URL" "$RUNNER_TEMP/sync" | tee -a "$GITHUB_OUTPUT"
-
-      - name: Install pinned toolchain
-        if: steps.compare.outputs.changed == 'true'
-        run: rustup show
-
-      - name: Regenerate the client
-        if: steps.compare.outputs.changed == 'true'
-        id: codegen
         run: |
-          if cargo xtask codegen > "$RUNNER_TEMP/codegen.log" 2>&1; then
-            echo "ok=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "ok=false" >> "$GITHUB_OUTPUT"
-          fi
-          cat "$RUNNER_TEMP/codegen.log"
+          python3 .github/scripts/openapi-sync.py "$SPEC_URL" "$RUNNER_TEMP/sync" > "$RUNNER_TEMP/compare.out"
+          cat "$RUNNER_TEMP/compare.out" >> "$GITHUB_OUTPUT"
+
+      - name: Close the drift issue
+        if: steps.compare.outputs.changed == 'false'
+        run: >
+          .github/scripts/openapi-drift-issue.sh resolve "$DRIFT_LABEL"
+          "The published document and openapi/v1.json match again."
 
       # Pinned and checked against the checksum recorded above; bumped by hand in the periodic
       # dependency review (CONTRIBUTING.md).
@@ -68,109 +68,42 @@ jobs:
           echo "${OASDIFF_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
           tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" oasdiff
 
-      - name: Write the pull request description
+      - name: Describe the difference
         if: steps.compare.outputs.changed == 'true'
-        id: body
-        env:
-          CODEGEN_OK: ${{ steps.codegen.outputs.ok }}
+        id: report
         run: |
-          set -euo pipefail
-          old="$RUNNER_TEMP/sync/old.json"
-          oasdiff="$RUNNER_TEMP/oasdiff"
-          breaking=false
-          if ! "$oasdiff" breaking "$old" openapi/v1.json --fail-on ERR > "$RUNNER_TEMP/breaking.txt" 2>&1; then
-            breaking=true
-          fi
-          "$oasdiff" changelog "$old" openapi/v1.json -f markdown > "$RUNNER_TEMP/changelog.md" 2>&1 || true
-          {
-            echo "The document published at \`$SPEC_URL\` differs in content from \`openapi/v1.json\`. This pull request takes the published bytes unchanged, updates the recorded version and SHA-256, and regenerates the client."
-            echo
-            cat "$RUNNER_TEMP/sync/summary.md"
-            echo
-            if [ "$breaking" = true ]; then
-              echo "**⚠ Breaking changes found by oasdiff** (label \`breaking-change\`): an older CLI may fail against the new contract. Review before merging."
-            else
-              echo "No breaking changes found by oasdiff."
-            fi
-            echo
-            echo '```'
-            head -c 20000 "$RUNNER_TEMP/breaking.txt"
-            echo '```'
-            if [ "$CODEGEN_OK" != true ]; then
-              echo
-              echo "**⚠ \`cargo xtask codegen\` failed**; the client is not regenerated. Output:"
-              echo '```'
-              tail -c 5000 "$RUNNER_TEMP/codegen.log"
-              echo '```'
-            fi
-            echo
-            echo "<details><summary>oasdiff changelog</summary>"
-            echo
-            head -c 30000 "$RUNNER_TEMP/changelog.md"
-            echo
-            echo "</details>"
-            echo
-            echo "Opened by the weekly OpenAPI sync workflow. Pull requests it opens do not start CI on their own: close and reopen this one to run the checks. Never merged automatically."
-          } > "$RUNNER_TEMP/body.md"
-          echo "breaking=$breaking" >> "$GITHUB_OUTPUT"
-          echo "version=$(cat "$RUNNER_TEMP/sync/version.txt")" >> "$GITHUB_OUTPUT"
+          python3 .github/scripts/openapi-drift-report.py "$RUNNER_TEMP/oasdiff" "$RUNNER_TEMP/sync" \
+            "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" > "$RUNNER_TEMP/report.out"
+          cat "$RUNNER_TEMP/report.out" >> "$GITHUB_OUTPUT"
 
-      # The commit is made through the GraphQL API so GitHub signs it: dev only accepts signed
-      # commits. The branch is reset to dev first, so it always holds exactly one sync commit.
-      - name: Commit to the sync branch
+      - name: Open or update the drift issue
         if: steps.compare.outputs.changed == 'true'
         env:
-          GH_TOKEN: ${{ github.token }}
-          VERSION: ${{ steps.body.outputs.version }}
-        run: |
-          set -euo pipefail
-          base=$(git rev-parse HEAD)
-          if gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$BRANCH" > /dev/null 2>&1; then
-            gh api -X PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$base" -F force=true > /dev/null
-          else
-            gh api -X POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$base" > /dev/null
-          fi
-          python3 - "$base" > "$RUNNER_TEMP/commit.json" <<'EOF'
-          import base64, json, os, subprocess, sys
-          files = subprocess.run(["git", "diff", "--name-only"], check=True, capture_output=True, text=True).stdout.split()
-          message = {
-              "headline": f"Sync the /v1 OpenAPI document from the API ({os.environ['VERSION']})",
-              "body": "Takes the document the API publishes, unchanged, updates its recorded version and\n"
-                      "SHA-256, and regenerates the client.\n\n"
-                      "Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>",
-          }
-          additions = [{"path": f, "contents": base64.b64encode(open(f, "rb").read()).decode()} for f in files]
-          query = """mutation($input: CreateCommitOnBranchInput!) {
-            createCommitOnBranch(input: $input) { commit { oid url } } }"""
-          print(json.dumps({"query": query, "variables": {"input": {
-              "branch": {"repositoryNameWithOwner": os.environ["GITHUB_REPOSITORY"], "branchName": os.environ["BRANCH"]},
-              "expectedHeadOid": sys.argv[1],
-              "message": message,
-              "fileChanges": {"additions": additions},
-          }}}))
-          EOF
-          gh api graphql --input "$RUNNER_TEMP/commit.json" --jq '.data.createCommitOnBranch.commit.url'
+          PUBLISHED_SHA256: ${{ steps.report.outputs.published_sha256 }}
+        run: >
+          .github/scripts/openapi-drift-issue.sh report "$DRIFT_LABEL"
+          "The published /v1 OpenAPI document differs from openapi/v1.json"
+          "$RUNNER_TEMP/sync/body.md" "openapi-drift:$PUBLISHED_SHA256"
 
-      - name: Open or update the pull request
+      - name: Fail on drift
+        id: drift
         if: steps.compare.outputs.changed == 'true'
-        env:
-          GH_TOKEN: ${{ github.token }}
-          VERSION: ${{ steps.body.outputs.version }}
-          BREAKING: ${{ steps.body.outputs.breaking }}
         run: |
-          set -euo pipefail
-          title="chore(api): sync openapi v1 from platform $VERSION"
-          number=$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$BRANCH" --base dev --state open --json number --jq '.[0].number // empty')
-          if [ -z "$number" ]; then
-            url=$(gh pr create --repo "$GITHUB_REPOSITORY" --base dev --head "$BRANCH" --title "$title" --body-file "$RUNNER_TEMP/body.md")
-            number=${url##*/}
-          else
-            gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --title "$title" --body-file "$RUNNER_TEMP/body.md" > /dev/null
-          fi
-          gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --add-label api-sync > /dev/null
-          if [ "$BREAKING" = true ]; then
-            gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --add-label breaking-change > /dev/null
-          else
-            gh pr edit "$number" --repo "$GITHUB_REPOSITORY" --remove-label breaking-change > /dev/null 2>&1 || true
-          fi
-          echo "Pull request #$number"
+          echo "The published document differs from openapi/v1.json; see the issue labelled $DRIFT_LABEL." >&2
+          exit 1
+
+      # Reached only when the check itself completed, with or without drift.
+      - name: Close the report of an earlier failed check
+        if: success() || steps.drift.conclusion == 'failure'
+        run: .github/scripts/openapi-drift-issue.sh resolve "$FAILED_LABEL" "The check completed again."
+
+      - name: Report a failed check
+        if: failure() && steps.drift.conclusion != 'failure'
+        run: |
+          {
+            echo "The weekly OpenAPI check could not complete, so it is unknown whether the published /v1 OpenAPI document and openapi/v1.json match."
+            echo
+            echo "The log of the run shows the step that failed: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          } > "$RUNNER_TEMP/failed.md"
+          .github/scripts/openapi-drift-issue.sh report "$FAILED_LABEL" \
+            "The OpenAPI check could not complete" "$RUNNER_TEMP/failed.md"
diff --git a/.github/workflows/proxy-tls.yml b/.github/workflows/proxy-tls.yml
new file mode 100644
index 0000000..fa89115
--- /dev/null
+++ b/.github/workflows/proxy-tls.yml
@@ -0,0 +1,78 @@
+name: Proxy and TLS inspection
+
+# Checks the README's "Networking: proxies and TLS inspection" claims on Linux against a real
+# TLS-inspecting proxy (mitmproxy) and a fake API, both on the runner, with throwaway certificates:
+# nothing secret is used and nothing leaves the machine except the download of mitmproxy. Case 1
+# is a deliberate certificate failure, so the script is only meant to run here (see
+# .github/scripts/proxy-tls-test.sh).
+on:
+  pull_request:
+    paths:
+      - "Cargo.lock"
+      - "crates/hodeishield-api/**"
+      - "crates/hodeishield-cli/**"
+      - ".github/scripts/proxy-tls-*"
+      - ".github/workflows/proxy-tls.yml"
+  push:
+    branches: [dev, main]
+    paths:
+      - "Cargo.lock"
+      - "crates/hodeishield-api/**"
+      - "crates/hodeishield-cli/**"
+      - ".github/scripts/proxy-tls-*"
+      - ".github/workflows/proxy-tls.yml"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: proxy-tls-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  proxy-tls:
+    name: proxy-tls
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    env:
+      # Official Linux release of mitmproxy, pinned by version and checksum. Bumped by hand.
+      # The download site publishes no checksum file, so the SHA-256 is the one of the
+      # release archive as downloaded when it was pinned (trust on first use). mitmproxy
+      # is only a test tool here and is never shipped. When bumping, record the new
+      # archive's SHA-256 the same way.
+      MITMPROXY_VERSION: "12.2.3"
+      MITMPROXY_SHA256: 2e95286b618fa6fd33e5e62a78c2e5112571d85f42ec2bac29b97ee242bdb5c5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install pinned toolchain
+        run: rustup show
+
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        with:
+          key: proxy-tls
+
+      - name: Build the CLI
+        run: cargo build --locked -p hodeishield-cli
+
+      - name: Install mitmproxy
+        run: |
+          set -euo pipefail
+          archive="mitmproxy-${MITMPROXY_VERSION}-linux-x86_64.tar.gz"
+          curl --proto '=https' --tlsv1.2 -fsSL -o "$RUNNER_TEMP/$archive" \
+            "https://downloads.mitmproxy.org/${MITMPROXY_VERSION}/${archive}"
+          echo "${MITMPROXY_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
+          mkdir "$RUNNER_TEMP/mitmproxy"
+          tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP/mitmproxy"
+
+      - name: Run the proxy cases
+        run: bash .github/scripts/proxy-tls-test.sh target/debug/hodeishield "$RUNNER_TEMP/mitmproxy"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a827518..f7c59ec 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -392,10 +392,21 @@ jobs:
           if-no-files-found: error
           retention-days: 7
 
+  # x86_64 builds on the x64 runner. arm64 builds natively on the GitHub-hosted Windows 11 Arm
+  # runner (as aarch64 Linux does on ubuntu-24.04-arm), so the C code of aws-lc-sys is compiled by
+  # the toolchain that will also run the CI tests, with no cross-compilation.
   build-windows:
-    name: build (x86_64-pc-windows-msvc)
+    name: build (${{ matrix.target }})
     needs: version
-    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+          - os: windows-11-arm
+            target: aarch64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -406,18 +417,20 @@ jobs:
         run: rustup show
 
       - name: Build
-        run: cargo build --release --locked --target x86_64-pc-windows-msvc -p hodeishield-cli
+        run: cargo build --release --locked --target ${{ matrix.target }} -p hodeishield-cli
 
       - name: Stage the unsigned executable for the signing job
         shell: pwsh
+        env:
+          TARGET: ${{ matrix.target }}
         run: |
           New-Item -ItemType Directory -Path stage | Out-Null
-          Copy-Item -Path "target/x86_64-pc-windows-msvc/release/$env:BIN_NAME.exe", "LICENSE", "NOTICE", "README.md" -Destination stage
+          Copy-Item -Path "target/$env:TARGET/release/$env:BIN_NAME.exe", "LICENSE", "NOTICE", "README.md" -Destination stage
 
       - name: Upload the unsigned executable
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: unsigned-x86_64-pc-windows-msvc
+          name: unsigned-${{ matrix.target }}
           path: stage/*
           if-no-files-found: error
           retention-days: 1
@@ -432,11 +445,25 @@ jobs:
   # Environment secrets (release-signing): AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID
   # (directory identifiers, kept out of public logs). Environment variables: AZURE_SIGNING_ENDPOINT,
   # AZURE_SIGNING_ACCOUNT_NAME, AZURE_CERTIFICATE_PROFILE_NAME.
+  #
+  # One job per architecture; each pauses for the same `release-signing` approval. The signing
+  # itself does not depend on the architecture of the exe, so both run on the x64 runner, which
+  # also hosts the x64 dumpbin used to inspect them.
   sign-windows:
-    name: sign and package (x86_64-pc-windows-msvc)
+    name: sign and package (${{ matrix.target }})
     needs: [version, build-windows]
     runs-on: windows-latest
     timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-pc-windows-msvc
+            key: x64
+            machine: "8664 machine (x64)"
+          - target: aarch64-pc-windows-msvc
+            key: arm64
+            machine: "AA64 machine (ARM64)"
     environment: ${{ needs.version.outputs.sign_windows == 'true' && 'release-signing' || '' }}
     permissions:
       contents: read
@@ -444,15 +471,21 @@ jobs:
     env:
       VERSION: ${{ needs.version.outputs.version }}
       SIGN: ${{ needs.version.outputs.sign_windows }}
+      TARGET: ${{ matrix.target }}
+      MACHINE: ${{ matrix.machine }}
+      KEY: ${{ matrix.key }}
     # The digest of the exe this job hands to the MSI build. A job output cannot be rewritten by
-    # another job, so `windows-msi` checks what it downloads against this, not against a name.
+    # another job, so `windows-msi` checks what it downloads against this, not against a name. The
+    # name carries the architecture, because the legs of a matrix share their outputs otherwise:
+    # each leg sets only its own (output names cannot use expressions).
     outputs:
-      exe_sha256: ${{ steps.handoff.outputs.exe_sha256 }}
+      exe_sha256_x64: ${{ steps.handoff.outputs.exe_sha256_x64 }}
+      exe_sha256_arm64: ${{ steps.handoff.outputs.exe_sha256_arm64 }}
     steps:
       - name: Download the unsigned executable
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          name: unsigned-x86_64-pc-windows-msvc
+          name: unsigned-${{ matrix.target }}
           path: stage
 
       # Anything else in the hand-off would be packaged, and possibly signed, as ours.
@@ -494,6 +527,13 @@ jobs:
               Write-Host "::error::$($exe.Name) imports the Visual C++ runtime ($($runtime -join ', ')), which Windows does not include."
               $failed = $true
             }
+            # The archive name says which architecture this is: the file must really be that one.
+            $headers = & $dumpbin /nologo /headers $exe.FullName
+            if ($LASTEXITCODE -ne 0) { throw "dumpbin /headers failed on $($exe.FullName)" }
+            if (-not ($headers | Select-String -SimpleMatch $env:MACHINE -Quiet)) {
+              Write-Host "::error::$($exe.Name) is not a '$env:MACHINE' executable, which $env:TARGET requires."
+              $failed = $true
+            }
           }
           if ($failed) { exit 1 }
 
@@ -567,10 +607,12 @@ jobs:
         shell: pwsh
         run: |
           $hash = (Get-FileHash -LiteralPath stage\hodeishield.exe -Algorithm SHA256).Hash.ToLower()
-          "exe_sha256=$hash" | Out-File -Append -Encoding utf8 $env:GITHUB_OUTPUT
+          "exe_sha256_$env:KEY=$hash" | Out-File -Append -Encoding utf8 $env:GITHUB_OUTPUT
           Write-Host "hodeishield.exe $hash"
 
+      # The MSI is built for x64 only (an arm64 MSI is a follow-up).
       - name: Upload the signed executable for the MSI build
+        if: matrix.key == 'x64'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: windows-msi-input
@@ -582,7 +624,7 @@ jobs:
         shell: pwsh
         run: |
           $ErrorActionPreference = "Stop"
-          $stageName = "hodeishield-$env:VERSION-x86_64-pc-windows-msvc"
+          $stageName = "hodeishield-$env:VERSION-$env:TARGET"
           $dir = Join-Path $env:RUNNER_TEMP $stageName
           New-Item -ItemType Directory -Path $dir, dist | Out-Null
           Copy-Item stage/* $dir
@@ -591,7 +633,7 @@ jobs:
       - name: Upload archive
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: archive-x86_64-pc-windows-msvc
+          name: archive-${{ matrix.target }}
           path: dist/*.zip
           if-no-files-found: error
           retention-days: 7
@@ -608,7 +650,7 @@ jobs:
       contents: read
     env:
       VERSION: ${{ needs.version.outputs.version }}
-      EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256 }}
+      EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256_x64 }}
       # Pinned to 5.x: later WiX releases add maintenance-fee terms to their licence, to be reviewed
       # before moving. Bumped by hand in the periodic dependency review (CONTRIBUTING.md).
       WIX_VERSION: "5.0.2"
@@ -723,7 +765,7 @@ jobs:
       - name: Check the MSI before signing it
         shell: powershell
         env:
-          EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256 }}
+          EXE_SHA256: ${{ needs.sign-windows.outputs.exe_sha256_x64 }}
         run: |
           $ErrorActionPreference = "Stop"
           $msi = (Resolve-Path "msi\hodeishield-$env:VERSION-x86_64-pc-windows-msvc.msi").Path
@@ -921,7 +963,8 @@ jobs:
             x86_64-unknown-linux-musl:x86_64-unknown-linux-musl \
             aarch64-unknown-linux-musl:aarch64-unknown-linux-musl \
             universal-apple-darwin:aarch64-apple-darwin \
-            x86_64-pc-windows-msvc:x86_64-pc-windows-msvc; do
+            x86_64-pc-windows-msvc:x86_64-pc-windows-msvc \
+            aarch64-pc-windows-msvc:aarch64-pc-windows-msvc; do
             name="${pair%%:*}"
             target="${pair##*:}"
             cargo cyclonedx --manifest-path crates/hodeishield-cli/Cargo.toml --format json \
@@ -994,8 +1037,9 @@ jobs:
             echo "archive-universal-apple-darwin hodeishield-$V-universal-apple-darwin.tar.gz"
             [ "$SIGN_MACOS" = true ] && echo "archive-universal-apple-darwin hodeishield-$V-universal-apple-darwin.pkg"
             echo "archive-x86_64-pc-windows-msvc hodeishield-$V-x86_64-pc-windows-msvc.zip"
+            echo "archive-aarch64-pc-windows-msvc hodeishield-$V-aarch64-pc-windows-msvc.zip"
             [ "$SIGN_WINDOWS" = true ] && echo "archive-msi hodeishield-$V-x86_64-pc-windows-msvc.msi"
-            for t in x86_64-unknown-linux-musl aarch64-unknown-linux-musl universal-apple-darwin x86_64-pc-windows-msvc; do
+            for t in x86_64-unknown-linux-musl aarch64-unknown-linux-musl universal-apple-darwin x86_64-pc-windows-msvc aarch64-pc-windows-msvc; do
               echo "archive-sbom hodeishield-$V-$t.cdx.json"
             done
             echo "archive-packages hodeishield_${pv}-1_amd64.deb"
diff --git a/.github/workflows/repo-builder-tests.yml b/.github/workflows/repo-builder-tests.yml
new file mode 100644
index 0000000..6ee356f
--- /dev/null
+++ b/.github/workflows/repo-builder-tests.yml
@@ -0,0 +1,61 @@
+name: Repository builder tests
+
+# Runs the security tests of the APT and DNF repository builder (packaging/repo/build.sh and
+# publish.sh) against a throwaway MinIO, with throwaway keys and synthetic packages: nothing secret
+# is used, and nothing is published. The cases that must be refused plant forged packages and indexes
+# in the bucket on purpose, so they run here and are not meant to be run by hand
+# (packaging/repo/repo-test.sh, CONTRIBUTING.md).
+on:
+  pull_request:
+    paths:
+      - "packaging/repo/**"
+      - "packaging/nfpm.yaml"
+      - ".github/workflows/repo-builder-tests.yml"
+  push:
+    branches: [dev, main]
+    paths:
+      - "packaging/repo/**"
+      - "packaging/nfpm.yaml"
+      - ".github/workflows/repo-builder-tests.yml"
+  workflow_dispatch:
+  schedule:
+    - cron: "17 5 * * 1" # Mondays, 05:17 UTC: the clients and the pinned image move on their own
+
+permissions: {}
+
+concurrency:
+  group: repo-builder-tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: repository builder security tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    permissions:
+      contents: read
+    env:
+      # The same nfpm as the release workflow's.
+      NFPM_VERSION: "2.47.0"
+      NFPM_SHA256: 0660ca602b2d2d2ae4781a06c692b3eeb9d437ffea05b831d76e41f4a3188783
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install nfpm
+        run: |
+          set -euo pipefail
+          archive="nfpm_${NFPM_VERSION}_Linux_x86_64.tar.gz"
+          curl -sSfL -o "$RUNNER_TEMP/$archive" \
+            "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/${archive}"
+          echo "${NFPM_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
+          tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" nfpm
+
+      - name: Run the tests
+        run: |
+          set -euo pipefail
+          # MinIO is licensed under the GNU AGPL v3; it is built and run here only as a throwaway test
+          # service inside CI and is never shipped or distributed with the CLI or its packages.
+          NFPM="$RUNNER_TEMP/nfpm" sh packaging/repo/repo-test.sh
diff --git a/CHANGELOG.md b/CHANGELOG.md
index da2fec0..dc2746d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,128 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 
 ## [Unreleased]
 
-## [0.3.1] - 2026-10-11
+## [0.4.0] - 2026-10-12
+
+### Added
+
+- Each release now includes a Windows on Arm build, `hodeishield-<version>-aarch64-pc-windows-msvc.zip`.
+  It is built natively on a Windows on Arm runner, its `hodeishield.exe` is signed with Authenticode
+  like the x64 one and checked to need no Visual C++ runtime, and the archive is listed in
+  `SHA256SUMS`, signed with Sigstore, covered by the build provenance and has its own SBOM. The
+  Scoop manifest offers it to Windows on Arm; the MSI and winget package remain x64 only. CI now
+  runs the tests, clippy and the import check on Windows on Arm too.
+  ([#37](https://github.com/Hodeitek/hodeishield-cli/issues/37))
+
+- On an interactive terminal, the CLI now tells you in one line on standard error when a newer
+  release exists. It asks GitHub's public releases API (no credential or identifier is sent) at most
+  once a day, stays silent with `--json`, `--csv`, `completions`, when standard error is not a
+  terminal and when `CI` is set, and never changes a command's output or exit code. Turn it off with
+  `HODEISHIELD_NO_UPDATE_CHECK=1` or `hodeishield config set update_check false`; the README's
+  "New-version notice" section lists exactly what is sent.
+  ([#38](https://github.com/Hodeitek/hodeishield-cli/issues/38))
+- A container image, `ghcr.io/hodeitek/hodeishield-cli`, for `linux/amd64` and `linux/arm64`, built
+  for each stable release: the release's own binary on a distroless base, running as a non-root
+  user, tagged with the exact version only. It is signed by digest with Sigstore and carries the
+  release's SBOM as a signed attestation. ([#36](https://github.com/Hodeitek/hodeishield-cli/issues/36))
+- Several client tenants with one portfolio key. `hodeishield tenants list` lists the client
+  tenants the key may read. The key is created by an organisation administrator of an active MSSP
+  organisation and goes in `HODEISHIELD_API_KEY`. The global `--tenant <slug|id>` selects one client
+  for any read command, including `get` and `compliance posture`, and prints the line
+  `Client tenant: <slug> (<id>)` on standard error. `--all-tenants` reads every client on a `list` command and adds
+  `tenant_id`, `tenant_slug` and `tenant_name` to each row in `--json` and `--csv` (a `TENANT`
+  column in the table). An unknown client fails with exit code 5, before any data is read. Without
+  these options nothing changes. `--all-tenants` asks one client at a time and skips clients that
+  are inactive or whose licence is not in force, with a note on standard error; the command still
+  exits 0 when only inactive clients are skipped. A client whose licence status the CLI does not
+  know is not read and is named on standard error. A client that fails when it is read because its
+  licence is not in force (exit code 8) or it is not found (exit code 5) is also named and skipped.
+  In both cases the other clients' data is printed and the command then exits non-zero (with the
+  code of the first client that failed, or 1 for an unknown licence status), so a script never takes
+  a partial result for a complete one. Any other failure stops the run before anything is printed,
+  for example exit code 6 (naming the limit) when a rate limit is exhausted. Against an API without
+  portfolio access the commands fail with exit code 7. The README has a new "Several tenants (MSSP)"
+  section. ([#54](https://github.com/Hodeitek/hodeishield-cli/issues/54),
+  [#45](https://github.com/Hodeitek/hodeishield-cli/issues/45))
+
+### Changed (scripting surface)
+
+- In a session where the system keychain cannot be reached (a Windows SSH or other network logon,
+  or a Secret Service on Linux that is locked or does not answer) and no API key is set, commands
+  such as `whoami` no longer fail with a raw platform error and exit code 1. They now say that the
+  system keychain is not available in this session, suggest `HODEISHIELD_API_KEY` for remote and
+  automated sessions, and exit with 3, the code for "not authenticated". With the key set, nothing
+  changes. What to do: treat exit 3 as "this session cannot keep a login, use an API key", and do
+  not rely on exit 1 for this case. ([#111](https://github.com/Hodeitek/hodeishield-cli/issues/111))
+- A failed command no longer exits 0 when the API's error message happens to contain the words
+  "Broken pipe". The CLI now treats a failure as a closed output pipe (`hodeishield ... | head -1`,
+  which still exits 0 silently) only when writing to standard output fails with that I/O error,
+  never because of the text of a message. What to do: a script that relied on exit 0 after such a
+  failed command must now handle the documented non-zero code (see "Exit codes" in the README).
+  ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
+- A broken pipe from anything other than standard output (a network connection, a file, the
+  configuration being saved) no longer ends a command with exit code 0 and no message. Only a write
+  to standard output that fails because the reader went away is treated as a closed pipe; any other
+  broken pipe is reported as an error with a non-zero exit code. What to do: as above, handle the
+  non-zero code instead of expecting exit 0. ([#105](https://github.com/Hodeitek/hodeishield-cli/issues/105))
+
+### Changed
+
+- The README documents more of how to use and depend on the CLI: the interface stability policy,
+  with what a script can rely on ([#58](https://github.com/Hodeitek/hodeishield-cli/issues/58), [#92](https://github.com/Hodeitek/hodeishield-cli/pull/92)); using the CLI behind a proxy or
+  TLS inspection ([#25](https://github.com/Hodeitek/hodeishield-cli/issues/25), [#89](https://github.com/Hodeitek/hodeishield-cli/pull/89)); the beta programme and its terms
+  ([#52](https://github.com/Hodeitek/hodeishield-cli/issues/52), [#90](https://github.com/Hodeitek/hodeishield-cli/pull/90)); defining a profile before signing in to it, and waiting for
+  `msiexec` in a silent install ([#87](https://github.com/Hodeitek/hodeishield-cli/pull/87)).
+  `SECURITY.md` now says what happens after a vulnerability report, where a notice about an affected
+  release appears (the README has an empty place for it), and how advisories are published, from
+  a template kept in `docs/` ([#120](https://github.com/Hodeitek/hodeishield-cli/issues/120)).
+  `SECURITY.md` now states the support period (from 1.0.0, five years of security fixes per major
+  version; until then, the latest 0.x release), and `docs/user-information.md` gathers the contact
+  details, secure use, updating, removal and where the SBOM is published
+  ([#127](https://github.com/Hodeitek/hodeishield-cli/issues/127),
+  [#128](https://github.com/Hodeitek/hodeishield-cli/issues/128)).
+- The alerts `--severity` filter now shows in `--help` the values the API lists (`critical`, `high`,
+  `medium`, `low`, `info`), and warns on standard error about a value the API does not list or has
+  deprecated. For the deprecated values (`critico`, `alto`, `medio`, `bajo`, accepted until
+  2027-01-14) the warning names the value to use instead. The value is still sent as typed, and exit
+  codes do not change. The CLI now follows version 2026-10-16 of the API document.
+  ([#53](https://github.com/Hodeitek/hodeishield-cli/issues/53))
+- Errors that involve a client tenant now say so and what to do. An unknown client tenant (404
+  `TENANT_NOT_FOUND`) points to `hodeishield tenants list`; a portfolio key rejected for a missing
+  scope points to an organisation administrator; a rate limit names whether it is the key's, the
+  organisation's or the client tenant's own, and says whether other clients are affected; a
+  credential that covers several clients without `--tenant` or `--all-tenants` is told to pick one;
+  and `--tenant` with a credential for one tenant only is told to leave it out. Messages and
+  hints go to standard error; exit codes do not change. ([#54](https://github.com/Hodeitek/hodeishield-cli/issues/54),
+  [#45](https://github.com/Hodeitek/hodeishield-cli/issues/45))
+
+### Fixed
+
+- Terminal output cleaning now also replaces the line and paragraph separators (U+2028, U+2029),
+  the deprecated format characters U+206A to U+206F and the tag characters and variation selectors supplement
+  (U+E0000 to U+E0FFF), which display differently from what they contain. This applies to tables,
+  detail views, CSV and the escaping of `--json` output. ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
+- CSV output now also defuses a field whose first character after any leading whitespace is `=`,
+  `+`, `-` or `@`, or one of their full-width forms (for example `" =1+1"`, or a no-break space
+  before `=cmd`). It decides on the text as it is written, because some spreadsheet applications
+  trim the whitespace before evaluating the cell. Numbers are still written as they are.
+  ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
+- `install.sh` now looks up the latest release over HTTPS only, with TLS 1.2 or newer, as the
+  download already did, so a redirect cannot lead that lookup to another protocol.
+  ([#106](https://github.com/Hodeitek/hodeishield-cli/issues/106))
+- `hodeishield login` now checks that the system keychain can keep a session before it opens the
+  browser or shows a device code, and stops there with the usual pointer to API keys. If saving the
+  session still fails after the app has issued tokens, the CLI revokes the refresh token and then
+  the access token, says so on standard error and exits non-zero, instead of leaving an active
+  grant that nothing holds. The hint for a missing keychain now names the one for your system
+  (Secret Service, the Keychain prompt, or Credential Manager). ([#101](https://github.com/Hodeitek/hodeishield-cli/issues/101))
+- A stalled or slow local connection can no longer keep the browser sign-in listener busy past its
+  timeout. Each connection now has a total time limit for its request, and no read waits beyond the
+  overall sign-in deadline, and the deadline is checked before every connection is accepted, so a
+  process sending a byte every few seconds, or connecting over and over, cannot block the real
+  redirect or stop `hodeishield login` from timing out. A client that resets its connection before
+  it is accepted no longer ends the sign-in. ([#104](https://github.com/Hodeitek/hodeishield-cli/issues/104))
+
+## [0.3.1] - 2026-10-10
 
 ### Fixed
 
@@ -91,7 +212,8 @@ commands, `--json` output and exit codes. Each release's notes start with its se
 - Profiles (`config`), shell completions, and release archives for Linux, macOS and Windows signed
   with Sigstore and with SLSA provenance.
 
-[Unreleased]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Hodeitek/hodeishield-cli/compare/v0.1.1...v0.2.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da9c01d..1456741 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,8 +39,18 @@ cargo xtask man target/man        # generate man pages
 cargo deny check && cargo audit   # dependency policy and advisories
 ```
 
-CI runs the tests on Linux, macOS and Windows and the other checks on Linux; a pull request needs
-them all green.
+CI runs the tests on Linux, macOS, Windows and Windows on Arm and the other checks on Linux; a pull
+request needs them all green.
+
+### The scripting surface is tested
+
+`crates/hodeishield-cli/tests/contract.rs` pins what [Stability](README.md#stability) promises
+scripts: the exit codes 0 to 8, the shape of `--json` output (including fields the CLI does not
+know), the `--csv` header and quoting rules, and which stream carries data and which carries notes
+and errors. The expectations are written out in full so a change shows in review. If one of these
+tests fails, either the change is a mistake or it breaks the scripting surface: in the second case
+edit the expectation on purpose and add a line under `### Changed (scripting surface)` in
+`CHANGELOG.md`.
 
 ### Dependency updates
 
@@ -63,7 +73,8 @@ dependency: it changes only by a deliberate decision.
 
 `crates/hodeishield-api/src/generated.rs` is generated from the vendored OpenAPI document
 `openapi/v1.json` by `cargo xtask codegen`. Do not edit it by hand. To follow a new version of `/v1`,
-see [openapi/README.md](openapi/README.md).
+see [openapi/README.md](openapi/README.md). A weekly workflow reports, in an issue, when the
+published document no longer matches that copy; it does not change the repository.
 
 ### Trying the CLI against your organisation
 
@@ -74,13 +85,39 @@ export HODEISHIELD_API_KEY=...   # never commit or paste it anywhere
 cargo run -- vendors list
 ```
 
+## Design
+
+A short vocabulary for designing or refactoring a module, adapted from
+[aihero.dev/codebase-design](https://www.aihero.dev/skills-codebase-design). A **module** is anything
+with an interface and an implementation, at any scale: a function, a file, a crate. Its **interface**
+is everything a caller must know to use it: signature, invariants, errors and ordering. A **seam** is
+a place where behaviour can change without editing that place, and an **adapter** is a concrete
+implementation plugged into one. **Depth** is the behaviour available per unit of interface, and
+**locality** means that what changes together lives together.
+
+- **Depth lives in the interface.** Judge a module by how little a caller must learn, not by how
+  much code it hides. `hodeishield-api` is the model: the CLI calls `client.list_vendors(&params)`
+  and gets typed results, while URL building, authentication, retries, rate limits and the response
+  size cap stay behind it.
+- **Deletion test.** Imagine deleting the module and inlining it into its callers. If the
+  complexity vanishes, it was a pass-through and should not exist; if it spreads to every caller, it
+  is earning its place.
+- **The interface is the test surface.** Test through the interface. A test that reaches past it
+  pins the implementation and breaks on every refactor.
+- **One adapter is a hypothetical seam; two make it real.** Add a trait only when a second
+  implementation exists today, a test double included. `TokenStore` qualifies: the OS keychain and
+  the in-memory store used by tests both implement it.
+- **Locality.** Table, JSON and CSV rendering, including the sanitising of terminal control
+  characters, lives in `output.rs`, so a change to it touches one module, not every command.
+
 ## Pull requests
 
 - Branch from `dev` and open the pull request against `dev`. `main` only receives releases.
 - Keep changes focused, with tests for new behaviour.
 - Add a line under `## [Unreleased]` in `CHANGELOG.md` for any change a user or a script would
   notice. A release renames that section to `## [X.Y.Z] - YYYY-MM-DD`; the release workflow refuses
-  a tag without it and uses the section as the release notes.
+  a tag without it and uses the section as the release notes. A change to the scripting surface
+  goes under `### Changed (scripting surface)`; see [Stability](README.md#stability).
 - Commits must be signed (GPG or SSH) and use a clear, imperative message in English. Reference
   the issue it resolves with `Closes #N` in the commit message.
 - Commit messages and pull request descriptions must not mention Claude: no session trailer, no
@@ -110,7 +147,11 @@ after everything they list; packages and by-hash indexes are immutable, so a cli
 index can still finish its update). Only `hodeishield` packages vouched for by the previously signed
 index (an RPM, by the repository key's signature) or by the release's verified `SHA256SUMS` are
 published, and anything else found in the bucket stops the job, so write access to the bucket alone
-cannot get a package signed. The bucket user needs list, read and write permissions
+cannot get a package signed. The `Repository builder tests` workflow checks this on every change to
+`packaging/repo` and weekly (`packaging/repo/repo-test.sh`): with throwaway keys and a throwaway bucket it
+publishes releases, installs and upgrades from the result with apt and dnf, and plants forged packages
+and indexes that the builder and the clients must refuse. Those cases run in CI only and are not meant
+to be run ad hoc. The bucket user needs list, read and write permissions
 only: nothing is ever deleted or overwritten. It runs after the same approval and is skipped while
 the `packaging` environment has no `PACKAGES_S3_ENDPOINT`. It needs the variables
 `PACKAGES_S3_ENDPOINT`, `PACKAGES_S3_REGION` and `PACKAGES_S3_BUCKET`, the secrets
@@ -128,6 +169,16 @@ and it is closed when the check passes again; a release less than 48 hours old t
 only raises a warning, since the `repos` job waits for an approval. On such an issue, first check who
 can write to the bucket, then re-run the `repos` job for the latest release to publish current indexes.
 
+Publishing a release also starts the **Container image** workflow. After the same `packaging`
+environment approval, it downloads the release's two Linux musl archives and SBOMs, verifies
+`SHA256SUMS` with cosign (the same identity as above) and the files against it, and builds
+`ghcr.io/hodeitek/hodeishield-cli` for `linux/amd64` and `linux/arm64` from `packaging/container/Dockerfile`
+without compiling anything. It pushes the exact-version tag only (no `latest`) with the job's own
+`GITHUB_TOKEN` (`packages: write`, held by no other job), signs the image by digest with cosign,
+attaches the SBOM with `cosign attest --type cyclonedx`, then verifies both and runs the image. Stable
+releases only. The base image is pinned by digest and bumped by dependabot. The first time, the package
+is private: a maintainer makes it public in the package settings once the first image exists.
+
 winget is submitted by hand, and only with the maintainers' approval, because it is a public
 submission to another project:
 
@@ -152,6 +203,11 @@ An issue is closed as soon as the fix reaches `main`, never left open once fixed
   with the reason. A security issue is closed only with evidence that it is fixed or not exploitable.
 - After a merge into `dev`, the issues the pull request mentions get the same review.
 
+## Design decisions
+
+Significant design choices are written up in [docs/decisions](docs/decisions), one numbered
+file each, with a status (Proposed, Accepted, Rejected or Superseded).
+
 ## Security issues
 
 Do not open a public issue: see [SECURITY.md](SECURITY.md).
diff --git a/Cargo.lock b/Cargo.lock
index 31c67db..fb882c9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -195,13 +195,13 @@ dependencies = [
 
 [[package]]
 name = "async-recursion"
-version = "1.1.1"
+version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b43422f69d8ff38f95f1b2bb76517c91589a924d1559a0e935d7c8ce0274c11"
+checksum = "4f8abc12baad266b1c8cec146854c195b5864b4221d4b2ca7296a7ae82d9e451"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -236,7 +236,7 @@ checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -357,9 +357,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.5.1"
+version = "1.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f360145194ee8e21db5ee7f3fcd4fe52210864c75c985dae33218202c8bbe040"
+checksum = "50a649af8a827553c29fb0cb4bd4a6f1a0dd695bd3232b9bc98bd9c8a3ffbb8b"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -441,7 +441,7 @@ dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -607,9 +607,9 @@ dependencies = [
 
 [[package]]
 name = "ctutils"
-version = "0.4.2"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
+checksum = "03bb0e1cc970d482d121d9a1744999169b69a07470b3d644a7894e53fcaf4574"
 dependencies = [
  "cmov",
 ]
@@ -671,7 +671,7 @@ checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -837,7 +837,7 @@ checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -909,9 +909,9 @@ dependencies = [
 
 [[package]]
 name = "h2"
-version = "0.4.19"
+version = "0.4.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ef8e5e5a340588f4452631496976cf8636d4a7ecf600239fdc27615d2530bc16"
+checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -970,7 +970,7 @@ dependencies = [
 
 [[package]]
 name = "hodeishield-api"
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
  "mockito",
  "reqwest",
@@ -983,7 +983,7 @@ dependencies = [
 
 [[package]]
 name = "hodeishield-cli"
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
  "apple-native-keyring-store",
  "assert_cmd",
@@ -1067,9 +1067,9 @@ dependencies = [
 
 [[package]]
 name = "hyper"
-version = "1.11.1"
+version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27b501faa50e7a26c3d3560ca625132f4078a17771f4810baf70475ae48cbe43"
+checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -1351,9 +1351,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.189"
+version = "0.2.190"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
 
 [[package]]
 name = "libredox"
@@ -1420,9 +1420,9 @@ dependencies = [
 
 [[package]]
 name = "mio"
-version = "1.2.3"
+version = "1.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b18443e9c262bfe8fa82f51666e2642c53393f7e5c27b3e1aeab922cff5b9d8"
+checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee"
 dependencies = [
  "libc",
  "wasi",
@@ -1540,9 +1540,9 @@ dependencies = [
 
 [[package]]
 name = "objc2"
-version = "0.6.4"
+version = "0.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+checksum = "08849bbd4767dfae9457696856ae1c84fe4e0281bbe4a7abff2d0e06fb7981f8"
 dependencies = [
  "objc2-encode",
 ]
@@ -1780,9 +1780,9 @@ dependencies = [
 
 [[package]]
 name = "quinn-proto"
-version = "0.11.18"
+version = "0.11.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"
+checksum = "0e750cca55fe4f0439a15d0bb529da9651e79993e8e72c61a899a36d462befbe"
 dependencies = [
  "aws-lc-rs",
  "bytes",
@@ -1803,9 +1803,9 @@ dependencies = [
 
 [[package]]
 name = "quinn-udp"
-version = "0.5.15"
+version = "0.5.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
+checksum = "af66907df18639dcf4db56ca65490cabc4b27a97dbadd96f2926cca73298f016"
 dependencies = [
  "cfg_aliases",
  "libc",
@@ -2224,14 +2224,14 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.151"
+version = "1.0.152"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+checksum = "1741ab7a6cc54a03a89b5d563ed60075c277d9e3cfa73ad0c1f23f23974703c6"
 dependencies = [
  "indexmap",
  "itoa",
@@ -2249,14 +2249,14 @@ checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
 name = "serde_spanned"
-version = "1.1.1"
+version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6662b5879511e06e8999a8a235d848113e942c9124f211511b16466ee2995f26"
+checksum = "4e7523beb55eece201a2356bee0bbca0d1ab466c14c07703b2e0ee6d42cb0c2c"
 dependencies = [
  "serde_core",
 ]
@@ -2330,9 +2330,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "smallvec"
-version = "1.16.2"
+version = "1.16.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f9395f0f0eee849a9b707b2f06bb92a6a422090e2123bb2ef8e87a0e61892a8e"
+checksum = "5b3dc8af474f516a851ff4bd12db780f948b9250ad37211e4eec0bccea54e01b"
 
 [[package]]
 name = "socket2"
@@ -2375,9 +2375,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.6"
+version = "3.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
+checksum = "d62a2e0561533f2ca2561d0cf27fd9fedb640a1bf2616ff5d5c80d99017faadc"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2401,7 +2401,7 @@ checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -2471,7 +2471,7 @@ checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -2492,9 +2492,9 @@ checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"
 
 [[package]]
 name = "tokio"
-version = "1.53.1"
+version = "1.53.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+checksum = "e95f91fcc7a621e8b030f6aa23c71fe9838ae2fb4d8118b75602a328f5144044"
 dependencies = [
  "bytes",
  "libc",
@@ -2517,9 +2517,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-util"
-version = "0.7.19"
+version = "0.7.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
+checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b"
 dependencies = [
  "bytes",
  "futures-core",
@@ -2531,9 +2531,9 @@ dependencies = [
 
 [[package]]
 name = "toml"
-version = "1.1.6+spec-1.1.0"
+version = "1.1.8+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "920602543f0911ab71da12c50d59701da54c196d1a2bf5cb4b75667f137a406a"
+checksum = "20489e00e4d8741d6be680764cc12e270655e375a20d1011e844a9c3379e678d"
 dependencies = [
  "indexmap",
  "serde_core",
@@ -2546,18 +2546,18 @@ dependencies = [
 
 [[package]]
 name = "toml_datetime"
-version = "1.1.1+spec-1.1.0"
+version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+checksum = "2b86d767906c6c42421dcba507eb9d203e779497710a47782a224bb871653053"
 dependencies = [
  "serde_core",
 ]
 
 [[package]]
 name = "toml_edit"
-version = "0.25.15+spec-1.1.0"
+version = "0.25.17+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1340ea94a5856333492c9064b02c778b191dd2c853778d9609debdcdfea3a614"
+checksum = "e3641d5bbb5349a79e1020a242d251efbc546ad8048d133958323ce9c40a9c9c"
 dependencies = [
  "indexmap",
  "toml_datetime",
@@ -2567,18 +2567,18 @@ dependencies = [
 
 [[package]]
 name = "toml_parser"
-version = "1.1.3+spec-1.1.0"
+version = "1.1.5+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
+checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c"
 dependencies = [
  "winnow",
 ]
 
 [[package]]
 name = "toml_writer"
-version = "1.1.2+spec-1.1.0"
+version = "1.1.3+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
+checksum = "06bdbd8cfc056b8d2e2e85f29b56a3bdbecb527cef81eb39e3e7b98af4652770"
 
 [[package]]
 name = "tower"
@@ -2730,9 +2730,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.26.1"
+version = "1.28.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
+checksum = "7cc1186384beb7dd8eedea376413fd654937285ea6c9cfbb928dc3043ea4b606"
 dependencies = [
  "js-sys",
  "serde_core",
@@ -2760,9 +2760,9 @@ dependencies = [
 
 [[package]]
 name = "want"
-version = "0.3.1"
+version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b"
 dependencies = [
  "try-lock",
 ]
@@ -2825,7 +2825,7 @@ dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "wasm-bindgen-shared",
 ]
 
@@ -3066,7 +3066,7 @@ checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
 
 [[package]]
 name = "xtask"
-version = "0.3.1"
+version = "0.4.0"
 dependencies = [
  "clap",
  "clap_mangen",
@@ -3094,7 +3094,7 @@ checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "synstructure",
 ]
 
@@ -3153,7 +3153,7 @@ dependencies = [
  "proc-macro-crate",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "zbus_names",
  "zvariant",
  "zvariant_utils",
@@ -3181,18 +3181,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.59"
+version = "0.8.62"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6df92bf3d9227be3d53173901ddbffac2babc27ae50f397776ffd6dc33f800cb"
+checksum = "86502bf56ac7c77571a32e2647bb2a15894565e981fb2a48d7bde2d91c965a9d"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.59"
+version = "0.8.62"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ac4f328cf2f05d084e496c3e9c3f33ed0a183656a16e1fcec4d464d8373aec82"
+checksum = "5457206954b06561e2608c7e19cf58b1926586d999c246eebe4502f7e2039d1a"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3216,15 +3216,15 @@ checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "synstructure",
 ]
 
 [[package]]
 name = "zeroize"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879"
 
 [[package]]
 name = "zerotrie"
@@ -3256,7 +3256,7 @@ checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
 ]
 
 [[package]]
@@ -3289,7 +3289,7 @@ dependencies = [
  "proc-macro-crate",
  "proc-macro2",
  "quote",
- "syn 3.0.6",
+ "syn 3.0.7",
  "zvariant_utils",
 ]
 
@@ -3302,6 +3302,6 @@ dependencies = [
  "proc-macro2",
  "quote",
  "serde",
- "syn 3.0.6",
+ "syn 3.0.7",
  "winnow",
 ]
diff --git a/Cargo.toml b/Cargo.toml
index 9dd5bfb..f27fa9c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,7 +5,7 @@ default-members = ["crates/hodeishield-api", "crates/hodeishield-cli"]
 
 [workspace.package]
 authors = ["Hodeitek S.L. <info@hodeitek.com>"]
-version = "0.3.1"
+version = "0.4.0"
 edition = "2024"
 rust-version = "1.98"
 license = "Apache-2.0"
diff --git a/README.md b/README.md
index 8bcc9fb..7c9e9ac 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,9 @@
 
 # HodeiShield CLI
 
+<!-- security-notice:start -->
+<!-- security-notice:end -->
+
 [![Latest release](https://img.shields.io/github/v/release/Hodeitek/hodeishield-cli?sort=semver)](https://github.com/Hodeitek/hodeishield-cli/releases/latest)
 [![CI](https://github.com/Hodeitek/hodeishield-cli/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Hodeitek/hodeishield-cli/actions/workflows/ci.yml?query=branch%3Amain)
 [![License: Apache-2.0](https://img.shields.io/github/license/Hodeitek/hodeishield-cli)](LICENSE)
@@ -11,6 +14,8 @@ The official command-line client for [HodeiShield](https://hodeishield.com), by
 [Hodeitek](https://hodeitek.com). HodeiShield covers third-party risk, supply-chain security and
 compliance (NIS2, DORA, ISO 27001, ENS).
 
+Security policy, how to report a vulnerability and where advisories appear: [SECURITY.md](SECURITY.md).
+
 ## Quick start
 
 ```sh
@@ -34,7 +39,8 @@ endpoint agents from a terminal or a script.
 - **Verifiable.** Every release is signed with Sigstore (keyless, from GitHub Actions) and carries
   SLSA build provenance.
 
-> The CLI is at version 0.x: commands and output may still change before 1.0.
+> The CLI is at version 0.x: commands and output may still change before 1.0. See
+> [Stability](#stability) for what may change and how it is announced.
 
 ## Install
 
@@ -48,15 +54,16 @@ section), and put `hodeishield` (`hodeishield.exe` on Windows) somewhere on your
 | Linux arm64 | `hodeishield-<version>-aarch64-unknown-linux-musl.tar.gz` |
 | macOS (Apple silicon and Intel) | `hodeishield-<version>-universal-apple-darwin.tar.gz` |
 | Windows x86_64 | `hodeishield-<version>-x86_64-pc-windows-msvc.zip` |
+| Windows arm64 | `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (from 0.4.0) |
 
-`<version>` has no leading `v`: release `v0.3.1` ships `hodeishield-0.3.1-…`. The Linux binaries are
-statically linked and run on any distribution. Homebrew and Scoop packages are also available
-(next section).
+`<version>` has no leading `v`: release `v0.4.0` ships `hodeishield-0.4.0-…`. The Linux binaries are
+statically linked and run on any distribution. Homebrew and Scoop packages (next section) and a
+[container image](#container-image) are also available.
 
 From source, with the Rust toolchain installed (pin the release tag you want):
 
 ```sh
-cargo install --locked --git https://github.com/Hodeitek/hodeishield-cli --tag v0.3.1 hodeishield-cli
+cargo install --locked --git https://github.com/Hodeitek/hodeishield-cli --tag v0.4.0 hodeishield-cli
 ```
 
 ### Homebrew and Scoop
@@ -70,11 +77,16 @@ scoop bucket add hodeishield https://github.com/Hodeitek/scoop-hodeishield
 scoop install hodeishield                                       # Windows, per user
 ```
 
+`scoop bucket add` needs Git: on a fresh Scoop, run `scoop install git` first. Scoop's own installer
+refuses an elevated (administrator) shell unless it is run with `-RunAsAdmin`; installing per user,
+from a normal shell, is the recommended way and needs no administrator rights.
+
 The [Homebrew tap](https://github.com/Hodeitek/homebrew-hodeishield) and the
 [Scoop bucket](https://github.com/Hodeitek/scoop-hodeishield) are updated from each release's own
 files and `SHA256SUMS` when it is published, and both check those hashes when installing. Homebrew
-also installs the man pages and shell completions. A winget package has been submitted and is
-waiting for review by the winget community repository; it is not available yet.
+also installs the man pages and shell completions. Scoop picks the arm64 build on Windows on Arm
+automatically. A winget package has been submitted and is waiting for review by the winget community
+repository; it is not available yet.
 
 ### Debian, Ubuntu, Fedora, RHEL and other Linux distributions
 
@@ -101,12 +113,23 @@ It installs for all users in `%ProgramFiles%\HodeiShield CLI` and adds that fold
 Silent installation, for Intune, Group Policy or any other deployment tool:
 
 ```powershell
-msiexec /i hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart /l*v hodeishield-install.log
-msiexec /x hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart     # uninstall
+$p = Start-Process msiexec -Wait -PassThru -ArgumentList '/i hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart /l*v hodeishield-install.log'
+$p.ExitCode      # 0 = installed, 3010 = installed and a restart is pending
+# uninstall
+$p = Start-Process msiexec -Wait -PassThru -ArgumentList '/x hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart /l*v hodeishield-uninstall.log'
+$p.ExitCode
 ```
 
-- **Intune:** add it as a *Line-of-business app* (MSI), or as a *Windows app (Win32)* with the
-  commands above. Intune reads the product code from the MSI for detection.
+Run `msiexec` through `Start-Process -Wait -PassThru` in PowerShell. Called directly, as
+`msiexec /i ...`, it returns at once while the installer keeps running, and `$LASTEXITCODE` is not
+updated (it keeps the value of an earlier command), so a script would carry on before the install
+is done and could not tell whether it worked. From `cmd.exe`, use `start /wait msiexec /i ...`. Deployment tools such as Intune and Group Policy
+run the installer themselves and wait for it as usual.
+
+- **Intune:** add it as a *Line-of-business app* (MSI), or as a *Windows app (Win32)* whose install
+  command is the plain command line
+  `msiexec /i hodeishield-<version>-x86_64-pc-windows-msvc.msi /qn /norestart` (and the same with
+  `/x` to uninstall), not the PowerShell snippet above. Intune reads the product code from the MSI for detection.
 - **Group Policy:** *Computer Configuration → Policies → Software Settings → Software installation*,
   assign the MSI from a network share that the computers can read.
 - Every version shares the upgrade code `{32B34E35-7A3F-422A-AC44-59204CD0D59D}`, which detection
@@ -134,6 +157,48 @@ sh install.sh --version $v
 It needs `cosign` to check the archive's signature and stops if it is missing; `--no-verify` skips
 that check (the checksum still runs). `sh install.sh --help` lists the options (`--dir`, `--no-man`).
 
+### Container image
+
+From 0.4.0, each stable release also publishes a multi-architecture (`linux/amd64`, `linux/arm64`)
+image at `ghcr.io/hodeitek/hodeishield-cli`, for CI jobs and container pipelines. It holds only the
+release's own `hodeishield` binary on a
+[distroless](https://github.com/GoogleContainerTools/distroless) static base (no shell, no package
+manager, CA certificates included) and runs as a non-root user. There is no `latest` tag: use the
+exact version, or better its digest.
+
+```sh
+v=0.4.0   # the version you want
+docker pull ghcr.io/hodeitek/hodeishield-cli:$v
+docker run --rm -e HODEISHIELD_API_KEY ghcr.io/hodeitek/hodeishield-cli:$v vendors list
+```
+
+`HODEISHIELD_API_KEY` is passed through from your environment (`-e NAME` without a value) so the key
+never appears on the command line. `hodeishield login` does not work in a container (there is no
+browser and no system keychain): use a tenant API key, see [Authenticate](#authenticate).
+
+The image is signed by digest with cosign (keyless) and carries the release's CycloneDX SBOM as a
+signed attestation. Verify both before you rely on the image:
+
+```sh
+v=0.4.0
+image=ghcr.io/hodeitek/hodeishield-cli:$v
+cosign verify $image \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/container-image.yml@refs/tags/v$v \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  --certificate-github-workflow-trigger release
+
+cosign verify-attestation --type cyclonedx $image \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/container-image.yml@refs/tags/v$v \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  --certificate-github-workflow-trigger release
+```
+
+Both commands print the digest they verified; pin that digest
+(`ghcr.io/hodeitek/hodeishield-cli@sha256:...`) in your pipeline, since a tag can be moved and a
+digest cannot. The binary in the image is the one in the release's Linux musl archives, checked
+against the release's signed `SHA256SUMS` before the image is built. The image's own base image is
+pinned by digest in [packaging/container/Dockerfile](packaging/container/Dockerfile).
+
 ### Man pages
 
 From 0.2.0, the Linux and macOS archives include a man page for every command in `man/`. To read
@@ -153,9 +218,9 @@ Each release has a `SHA256SUMS` file, a Sigstore bundle (`*.sigstore.json`) for
 ```sh
 sha256sum --ignore-missing -c SHA256SUMS
 
-cosign verify-blob hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz \
-  --bundle hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+cosign verify-blob hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz \
+  --bundle hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push
 ```
@@ -183,7 +248,7 @@ xattr -d com.apple.quarantine ./hodeishield   # "No such xattr" means there was
 Or download with `curl`, which does not set that attribute in the first place:
 
 ```sh
-curl -LO https://github.com/Hodeitek/hodeishield-cli/releases/download/v0.3.1/hodeishield-0.3.1-universal-apple-darwin.tar.gz
+curl -LO https://github.com/Hodeitek/hodeishield-cli/releases/download/v0.4.0/hodeishield-0.4.0-universal-apple-darwin.tar.gz
 ```
 
 **Windows, before 0.2.0.** Unblock the archive before unpacking it, so the executable does not
@@ -194,10 +259,12 @@ Unblock-File .\hodeishield-0.1.1-x86_64-pc-windows-msvc.zip
 Expand-Archive .\hodeishield-0.1.1-x86_64-pc-windows-msvc.zip
 ```
 
-If you already unpacked it, run `Unblock-File` on `hodeishield.exe` instead. SmartScreen can also
-warn about a signed file that is still new to it; in either case, if it shows "Windows protected
-your PC", choose **More info → Run anyway** («Más información → Ejecutar de todos modos» on a
-Spanish system).
+If you already unpacked it, run `Unblock-File` on `hodeishield.exe` instead. Windows PowerShell
+5.1's `Expand-Archive` does not copy the download mark to the unpacked files, so unblocking matters
+when you unpack with File Explorer's "Extract All" or another tool that carries the mark over.
+SmartScreen can also warn about a signed file that is still new to it; in either case, if it shows
+"Windows protected your PC", choose **More info → Run anyway** («Más información → Ejecutar de todos
+modos» on a Spanish system).
 
 ## Authenticate
 
@@ -225,7 +292,21 @@ hodeishield logout           # revokes the token at the app and removes it from
 
 You sign in to [app.hodeishield.com](https://app.hodeishield.com) as usual (2FA, passkey or SSO), and
 on the consent screen you choose **the one tenant** the CLI may read. A sign-in token never covers
-more than that tenant, and it only reads. To use another tenant, sign in again with another profile (`--profile`).
+more than that tenant, and it only reads. To use an unrelated tenant, define another profile and sign in
+to it:
+
+```sh
+hodeishield config set --profile client-b api_url https://api.hodeishield.com
+hodeishield login --profile client-b
+```
+
+A profile that has not been defined is refused (`Profile ... is not defined`).
+
+`login` first checks that the system keychain is available and stops before opening the browser or
+showing a code if it is not; use a tenant API key on such a machine.
+
+An MSSP reads its clients with one credential instead: see
+[Several tenants (MSSP)](#several-tenants-mssp).
 
 With `--device`, open the address the CLI prints on any device and **type the code by hand**: the app
 does not accept a link with the code filled in, on purpose.
@@ -239,6 +320,11 @@ Service — GNOME Keyring, KWallet — on Linux) and refreshed automatically, al
 access token early. Without a keychain, signing in is refused rather than falling back to a file: use
 an API key there.
 
+The keychain can also be out of reach in a session that has one on the machine, such as an SSH or
+other remote logon on Windows. With no API key set, commands then stop with exit code 3 and say that
+the system keychain is not available in this session; set `HODEISHIELD_API_KEY` in remote or
+automated sessions. With the key set, the keychain is not read at all.
+
 To cut the CLI's access from elsewhere, revoke it in [the app](https://app.hodeishield.com) under
 **Account → Application access**. Signing out of the web app does not cut it.
 
@@ -267,6 +353,103 @@ rest. `--all` stops with an error past 100,000 items (or 1,000 pages); narrow th
 or walk it with `--page`. Every list takes `--sort` and `--order`; `--help` on any command lists
 what it accepts.
 
+### Several tenants (MSSP)
+
+An MSSP reads all of its client tenants with **one** credential: a **portfolio key**, created in the
+app by an organisation administrator of an active MSSP organisation, in the MSSP area (API keys).
+Nobody else can create one: not a tenant administrator, and not a platform operator acting outside
+an MSSP organisation. You do not need
+a profile, a key or a sign-in per client, and you should not set them up that way.
+
+A portfolio key reads only, always expires (90 days by default, 365 at most), and works on the
+HodeiShield API only. It can be limited when it is created to some of your clients and to source IP
+ranges; a request from another address is refused like an unknown key (exit code 3). Signing in
+with `hodeishield login` does not cover a whole portfolio: use the key. Rotate your portfolio keys
+before they expire, so scripts do not stop working; a new key and its predecessor both work for up
+to 7 days while the old one is in force.
+
+**1. Use the credential as any other key.**
+
+```sh
+export HODEISHIELD_API_KEY=hsp_3f2a9c0d1b4e_...   # the portfolio key; keep it in your CI's secret store
+```
+
+The key starts with `hsp_`, a 12-character identifier and `_`, then a long secret. The first 16
+characters identify the key in the app and in audit entries; the CLI never prints any part of the
+key. The same variable takes a tenant API key as before.
+
+**2. List the client tenants it may read.**
+
+```console
+$ hodeishield tenants list
+SLUG    NAME        ORGANISATION  TYPE    STATUS  LICENCE   ID
+acme    Acme S.L.   Acme Group    client  active  in_force  11111111-1111-4111-8111-111111111111
+beta    Beta Corp   Beta Group    client  active  grace     22222222-2222-4222-8222-222222222222
+```
+
+It takes `--json`, `--csv`, `--page` and `--all` like any list, sorted by name. It includes your
+own organisation's tenants (`TYPE` `own` for the internal one) and clients that are inactive or have
+no licence in force, which the `STATUS` and `LICENCE` columns tell apart. A key that was limited to
+some tenants when it was created lists and reads only those. The list is read from the API each
+time: a client added to or removed from your portfolio shows up on the next command.
+
+**3. Select the client a read command reads.** The selection goes with the command and is never
+remembered, so a later command cannot read another client by surprise.
+
+```sh
+hodeishield --tenant acme vendors list            # one client, by slug or id
+hodeishield --all-tenants alerts list --status open
+```
+
+- `--tenant <slug|id>` works on every read command (`list`, `get`, `compliance posture`). The CLI
+  prints `Client tenant: acme (<id>)` on standard error, so a log shows which client was read;
+  standard output is exactly what it is without a selection.
+- `--all-tenants` works on `list` commands and `compliance controls`. It fetches every page of each
+  client (`--per-page` applies, `--page` does not) and adds the tenant to each row: a `TENANT`
+  column in the table, and `tenant_id`, `tenant_slug` and `tenant_name` fields in `--json` and
+  `--csv`. Clients that are inactive, or whose licence status is `inactive`, are skipped with a
+  note on standard error. A client in its grace period is read. A client whose licence status this
+  CLI does not know is not read either; it is named on standard error (`licence status … is not
+  known to this version; not read`) and the command exits non-zero, so nothing goes missing
+  silently. Clients are asked one after the other. In the table, a slug with characters other
+  than `a-z`, `0-9` and `-` is followed by the start of the client's id, so look-alike names can be
+  told apart; `--json` and `--csv` carry the full values.
+- The tenant on a row is the one whose own request returned it. The CLI asks the API about one
+  client at a time, and refuses an answer that does not confirm that client.
+
+```sh
+hodeishield --all-tenants alerts list --status open --json \
+  | jq -r '.[] | [.tenant_slug, .severity, .title] | @tsv'
+hodeishield --all-tenants vendors list --criticality critical --csv > critical-vendors.csv
+```
+
+**4. When something is not readable.**
+
+- A client that is not in your portfolio (or that you mistyped) fails with `No client tenant … in
+  this credential's portfolio.` and exit code 5, before anything is read.
+- With `--all-tenants`, a client that cannot be read on its own account (for example its licence is
+  not in force, exit code 8) is reported on standard error and skipped; the command prints the
+  others and still exits non-zero, so a script does not mistake a partial result for a complete
+  one. This is the only signal of a partial result: check the exit code, and read standard error
+  for which clients were left out. A client named by both an id and a slug of another client
+  (a slug can look like an id) is refused as ambiguous; use the id shown by `tenants list`.
+- Without `--tenant` or `--all-tenants`, a portfolio key is refused by the API, and the CLI tells
+  you to choose. A single-tenant key or sign-in behaves exactly as before; asking it for a client
+  fails with exit code 4 (it lacks the portfolio scope).
+- A client you named that is deactivated, or whose licence is not in force, fails with exit code 8.
+- A portfolio key is limited to 100 requests per minute, and all the portfolio keys of your
+  organisation together to 600 (the API may change these numbers); a client tenant's own limits
+  can be lower. The CLI waits out a short `Retry-After` and retries; if the wait is longer, or the
+  limit is still exhausted, the command stops with exit code 6 and says which limit it hit
+  (`portfolio_key`, `portfolio_org`, `portfolio_tenant` or `tenant`), instead of asking the next
+  client. Use `--per-page 200` and narrow with filters to need fewer requests.
+- Against an API that does not offer portfolio access yet, `tenants list`, `--tenant` and
+  `--all-tenants` fail with `This API does not offer portfolio access yet.` and exit code 7. Nothing
+  else changes.
+
+**5. Revoke access.** Revoke the portfolio key in the app, in the MSSP area; it stops working on its
+next request. A client leaving your portfolio is dropped from the list on the next command.
+
 ### JSON for scripts
 
 `--json` prints the body the API returned, unchanged, including fields newer than your CLI. With
@@ -302,17 +485,41 @@ hodeishield vendors list --all --csv > vendors.csv
 | 0 | Success |
 | 1 | Error (invalid input, configuration, unexpected answer) |
 | 2 | Invalid command line |
-| 3 | Not authenticated: no credential, or the API rejected it |
+| 3 | Not authenticated: no credential (also when the system keychain cannot be reached in this session), or the API rejected it |
 | 4 | The credential lacks the scope the command needs |
 | 5 | Not found (or not in your organisation) |
 | 6 | Rate limit exhausted (the CLI already retried short waits) |
-| 7 | The API could not be reached or failed |
+| 7 | The API could not be reached or failed, or does not offer portfolio access yet |
 | 8 | The tenant's licence is not in force: a tenant administrator must renew or reactivate it |
 
 Errors go to stderr with a hint and, when the API gave one, a **request id**: quote it when you
 contact support. `--verbose` logs each request's method, URL, status and request id to stderr, never
 a credential.
 
+## Stability
+
+The CLI follows [Semantic Versioning](https://semver.org/). Its **scripting surface** is what a
+script can depend on:
+
+- the command names and flags;
+- the field names and types in `--json` and `--csv` output;
+- the exit codes 0 to 8 and what each one means (see [Exit codes](#exit-codes));
+- what goes to standard output (the data) and to standard error (notes and errors).
+
+While the version is 0.x, a change that breaks the scripting surface only ships in a minor version
+(0.2 to 0.3, never 0.2.0 to 0.2.1), and the changelog lists it under **Changed (scripting
+surface)**, with what to do about it. Read that heading before you upgrade. Patch releases fix bugs
+and do not break the scripting surface. A 1.0 release will be announced in the changelog.
+
+Adding to the scripting surface is not a breaking change: new commands and flags, and new fields in
+`--json` output. Giving an existing case a different exit code is a breaking change, even when the
+code is new (0.2.0 moved an inactive licence from 4 to 8). Write scripts to ignore the fields they
+do not know: `--json` prints the body the API returned, so it can gain fields at any time.
+
+The table output and the messages on standard error are for people and may change in any release.
+Scripts should use `--json` or `--csv` for data, and the exit code for what happened, and should not
+parse tables or messages.
+
 ## Configure
 
 Settings come from, in order: flags, environment variables, the profile in the configuration file,
@@ -323,6 +530,7 @@ hodeishield config show                      # the settings in effect
 hodeishield config path                      # where the file is
 hodeishield --profile staging config set api_url https://api.example.test
 hodeishield config use staging               # make it the default profile
+hodeishield config set update_check false    # no new-version notice (global, not per profile)
 hodeishield --profile default vendors list   # or pick one per command
 ```
 
@@ -333,12 +541,85 @@ hodeishield --profile default vendors list   # or pick one per command
 | `HODEISHIELD_API_URL` | API base URL |
 | `HODEISHIELD_APP_URL` | App base URL (sign-in) |
 | `HODEISHIELD_CONFIG` | Path of the configuration file |
+| `HODEISHIELD_NO_UPDATE_CHECK` | Any non-empty value turns off the [new-version notice](#new-version-notice) |
 
 The configuration file holds URLs and sign-in settings only, never a credential. URLs must use HTTPS;
 plain HTTP is accepted only for `localhost`.
 
+## New-version notice
+
+On an interactive terminal the CLI tells you, in one line on standard error, when a newer release
+exists:
+
+```
+A newer version of hodeishield is available: 0.4.0 (you have 0.3.0). See https://github.com/Hodeitek/hodeishield-cli/releases
+```
+
+It never updates anything. Privacy, in full:
+
+- **What is sent.** One unauthenticated `GET` to GitHub's public API,
+  `https://api.github.com/repos/Hodeitek/hodeishield-cli/releases/latest`, with a 2 second limit.
+  Only what HTTP requires goes with it, including `User-Agent: hodeishield-cli/<version>` and
+  `Accept`. No API key, token, profile, tenant, command or machine identifier is sent, and nothing
+  goes to HodeiShield: GitHub sees your IP address, as it does for any request. Your proxy settings
+  apply (see [Networking](#networking-proxies-and-tls-inspection)).
+- **When.** At most once every 24 hours, after the command has finished and printed its output.
+  The time of the last attempt, and the version it found, are kept in `update-check.json` next to
+  the configuration file (see `hodeishield config path`). A failed attempt (offline, timeout,
+  GitHub unavailable) is silent, is not repeated before the next day, and never changes a command's
+  output or exit code. Add `--verbose` to see why nothing was shown.
+- **Where it is silent.** When standard error is not a terminal, with `--json` and `--csv`, for
+  `completions`, and whenever the `CI` environment variable is set, to any value. The notice goes to
+  standard error, so a terminal on standard error is what decides, not whether standard output is
+  piped.
+- **Turning it off.** `export HODEISHIELD_NO_UPDATE_CHECK=1`, or once for all profiles
+  `hodeishield config set update_check false` (`config unset update_check` restores the default).
+  With either, no request is made.
+
 Shell completions: `hodeishield completions bash|zsh|fish|powershell|elvish`.
 
+## Networking: proxies and TLS inspection
+
+The CLI reaches `api.hodeishield.com` and `app.hodeishield.com` over HTTPS (port 443). Behind a
+corporate proxy, nothing needs configuring in the CLI itself; it follows the proxy settings of the
+machine.
+
+- **Proxy variables.** `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` and `NO_PROXY` are honoured, and so
+  are their lower-case forms. Since all traffic is HTTPS, `HTTPS_PROXY` (or `ALL_PROXY`) is the one
+  that matters; use `NO_PROXY` for hosts that must be reached directly.
+
+  ```sh
+  export HTTPS_PROXY=http://proxy.example.com:3128
+  export NO_PROXY=localhost,127.0.0.1
+  hodeishield vendors list
+  ```
+
+- **Operating system settings.** On macOS and Windows the system proxy settings are read as well,
+  next to the variables. On Linux only the variables are read.
+- **Certificates.** The CLI trusts the operating system's certificate store, not a bundled list. If
+  your organisation inspects TLS and its CA is installed in that store (the usual case on managed
+  Windows and macOS machines, or after `update-ca-certificates` / `update-ca-trust` on Linux), the
+  CLI trusts the proxy's certificates with no further setup. On Linux you can also point
+  `SSL_CERT_FILE` (a PEM file) or `SSL_CERT_DIR` at your CA certificates.
+- **What cannot be configured.** There is no CLI option to add a CA or to skip certificate
+  verification, and `SSL_CERT_FILE` / `SSL_CERT_DIR` have no effect on macOS and Windows: add the CA
+  to the system store there.
+- **Sign-in on this machine.** `hodeishield login` waits for the browser on `127.0.0.1`; that
+  redirect is made by your browser to the CLI, not by the CLI, so the CLI's proxy settings do not
+  apply to it (the CLI also never uses a proxy when its API or app URL is a loopback address). Your
+  browser's own proxy settings apply to the sign-in page. Where the browser cannot reach the
+  machine, use `hodeishield login --device`.
+
+To diagnose, add `--verbose`: each API request is logged to standard error with its URL, status,
+time and request id, followed by each retry and its reason. A failure to connect, including a proxy
+that refuses the connection or a certificate that is not trusted, ends with exit code 7 and a
+message that starts with `Could not reach the API:` (or `Could not reach the app` during sign-in)
+followed by the cause. A certificate error there usually means the proxy's CA is missing from the
+store described above.
+
+This behaviour comes from the CLI's HTTP library. It is verified on Linux in CI against a
+TLS-inspecting proxy; macOS and Windows have not been verified yet.
+
 ## Repository layout
 
 - `crates/hodeishield-cli` — the `hodeishield` binary.
@@ -351,7 +632,14 @@ Shell completions: `hodeishield completions bash|zsh|fish|powershell|elvish`.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). To report a vulnerability,
 use [GitHub private reporting](https://github.com/Hodeitek/hodeishield-cli/security/advisories/new)
-or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public issue.
+or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public issue. Security
+advisories are published under
+[Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories).
+
+From 1.0.0, each major version is supported with security fixes for five years; during 0.x, fixes go
+into the latest 0.x release ([Supported versions](SECURITY.md#supported-versions)).
+[docs/user-information.md](docs/user-information.md) gathers the manufacturer's contact details, the
+support period, secure use, how to update and remove the CLI, and where the SBOM is published.
 
 ## License
 
@@ -363,6 +651,10 @@ to them (Apache-2.0 §6).
 
 ## About
 
+HodeiShield is in beta. To request access, visit
+[https://hodeishield.com/en/beta](https://hodeishield.com/en/beta) and review the
+[beta terms of service](https://hodeishield.com/en/beta/terms).
+
 - [HodeiShield](https://hodeishield.com): the third-party risk, supply-chain security and
   compliance platform that this CLI reads from; sign in at
   [app.hodeishield.com](https://app.hodeishield.com) and create API keys there.
diff --git a/SECURITY.md b/SECURITY.md
index 4ede4b2..7b0e321 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -15,11 +15,133 @@ what you expected, and a proof of concept if you have one. **Never include a rea
 if one was exposed, revoke it in the app first.
 
 We will acknowledge your report, keep you informed while we investigate, and credit you in the
-advisory unless you prefer otherwise.
+advisory if you want to be credited.
+
+- Encrypted email: not offered at the moment.
+- Bug bounty: there is no bounty programme; we credit reporters publicly in the advisory.
+
+## What happens after you report
+
+A report made through GitHub opens a draft security advisory that only you and the maintainers can
+see; we talk to you there. A report made by email is answered by email.
+
+| Step | What you get | When |
+|---|---|---|
+| Acknowledgement | Confirmation that we received the report | Within 3 business days |
+| First assessment | Whether it is a vulnerability, its severity, and whether we know of it being exploited | Within 10 business days |
+| Status updates | Progress on the fix and the expected release, until the advisory is published | At least every 14 days |
+| Fix | A release that fixes it, and the published advisory | See the targets below |
+
+### Severity and fix targets
+
+We rate severity with [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) and use
+its qualitative ratings. You can comment on the rating in the advisory or by email. The targets
+below are for shipping a fixed release, counted from the first assessment.
+
+| Severity | CVSS v3.1 base score | Target to ship a fix |
+|---|---|---|
+| Critical | 9.0 – 10.0 | 7 days |
+| High | 7.0 – 8.9 | 30 days |
+| Medium | 4.0 – 6.9 | 90 days |
+| Low | 0.1 – 3.9 | The next release |
+
+### Coordinated disclosure
+
+We ask you to keep the vulnerability confidential until the advisory is published, and we agree
+the publication date with you. The coordinated disclosure period is 90 days from your report. If
+a fix is not released by then, we publish the advisory with the workarounds we know of, unless we
+agree a short extension with you. If the vulnerability is being actively exploited,
+we may publish earlier, with workarounds (see [Security notices](#security-notices)).
+
+### Safe harbour
+
+We will not take legal action against you, or ask anyone else to, for research that follows this
+policy in good faith: you report to us privately and give us reasonable time to fix the issue before
+you disclose it; you access only the data you need to show the vulnerability, and do not keep,
+change or share anyone else's data; you do not degrade the service or harm its users; and you test
+only against accounts and tenants you own or are allowed to use. If in doubt, ask us first.
+
+## Security notices
+
+If a release is affected by a vulnerability that is being actively exploited, or by a severe
+incident (for example a compromised release or release pipeline), we tell users in these places,
+in this order:
+
+1. **The GitHub security advisory** for this repository, under
+   [Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories). It is
+   published or updated first, before a fix is available if necessary, and says which versions are
+   affected, what to do in the meantime, and whether a fix is in progress.
+2. **A short notice at the top of [README.md](README.md)**, linking to the advisory. The README
+   keeps an empty block for it between the markers `<!-- security-notice:start -->` and
+   `<!-- security-notice:end -->`; the notice goes between them, as a quote with a blank line
+   before and after it:
+
+   ```markdown
+   <!-- security-notice:start -->
+
+   > **Security notice:** versions 0.x.y to 0.x.z are affected by GHSA-xxxx-xxxx-xxxx. Update to
+   > 0.x.w; until then, see the advisory for a workaround.
+
+   <!-- security-notice:end -->
+   ```
+
+   The notice is updated when the fix ships and removed when it no longer applies, leaving the
+   block empty. The README inside a release archive is a copy taken when that release was built:
+   check the repository's README, not the copy you downloaded.
+3. **The release notes of the release that fixes it**, under `### Security` in that release's
+   section of [CHANGELOG.md](CHANGELOG.md), which the release workflow uses as the release notes.
+   Each entry links to the advisory.
+
+To be told, watch this repository's releases on GitHub (*Watch → Custom → Releases*) or follow
+[its releases feed](https://github.com/Hodeitek/hodeishield-cli/releases.atom), and check the
+advisories page. The CLI's own [new-version notice](README.md#new-version-notice) tells you on an
+interactive terminal that a newer release exists, but not whether it fixes a vulnerability.
+
+## How advisories are published
+
+Every fixed vulnerability gets a GitHub security advisory in this repository, written from
+[docs/security-advisory-template.md](docs/security-advisory-template.md) so that every advisory has
+the same fields:
+
+- a description of the vulnerability and its impact;
+- who is affected: which commands, configurations and install channels;
+- the affected versions and the fixed versions;
+- the severity, with its CVSS v3.1 vector;
+- workarounds, how to check whether you are affected, and how to update;
+- the timeline (reported, fixed, published), the credit, and references.
+
+The advisory is published when the fixed release is out, or earlier as described in
+[Security notices](#security-notices).
+
+Each advisory has a GHSA identifier. Its machine-readable form is the advisory record that GitHub's
+REST API returns, for example
+`https://api.github.com/repos/Hodeitek/hodeishield-cli/security-advisories?state=published`, which
+lists the identifiers, affected and patched versions, CVSS vector and credits as JSON. Advisories
+are published on GitHub. When a vulnerability needs a CVE identifier, we request it through the
+advisory, with GitHub as the CVE Numbering Authority.
 
 ## Supported versions
 
-Only the latest release receives fixes.
+From 1.0.0, each major version of `hodeishield` is supported for five years, counted from the
+release of its first version (1.0.0 for version 1). A supported major version receives security
+fixes. They ship in a new release of that major version: to get them, update to the latest release
+of your major version.
+
+Security fixes stay available to you while your version is supported, even if your HodeiShield
+subscription has ended: every release is a public download, and installing or updating the CLI
+never requires a subscription.
+
+**Before 1.0.** While the 0.x series is current, security fixes go into the latest 0.x release.
+The 0.x series has no end-of-support date until 1.0.0 is released.
+
+| Version | Supported | Security fixes until |
+|---|---|---|
+| 0.x | Yes, in the latest 0.x release | No end date until 1.0.0 is released |
+
+The end-of-support date of each major version is published in this table and in the release
+notes. Twelve months before a major version's support ends, an end-of-support notice is published
+here, in the security notice block at the top of [README.md](README.md) (see
+[Security notices](#security-notices)) and in the release notes.
 
 ## What is in scope
 
diff --git a/crates/hodeishield-api/src/client.rs b/crates/hodeishield-api/src/client.rs
index 6b9f8fc..6f4612e 100644
--- a/crates/hodeishield-api/src/client.rs
+++ b/crates/hodeishield-api/src/client.rs
@@ -29,6 +29,50 @@ pub struct Operation {
     /// Scopes the credential needs. A template such as `compliance.<framework>:read` stands for the
     /// scope of the framework being read.
     pub scopes: &'static [&'static str],
+    /// The vocabulary the document publishes for a query parameter (`x-hs-known-values`), as
+    /// `(parameter, values)` pairs, only for the parameters that have one. The vocabularies are
+    /// open: the server may accept a value that is not listed, so use this to help and to warn,
+    /// never to refuse. Read it through [`Operation::known_values`].
+    pub known_values: &'static [(&'static str, &'static [&'static str])],
+    /// The values the document marks as deprecated for a query parameter
+    /// (`x-hs-deprecated-values`), only for the parameters that have some. The server still
+    /// accepts them until their sunset date. Read it through [`Operation::deprecated_values`].
+    pub deprecated_values: &'static [DeprecatedValues],
+    /// Whether a client built for one client tenant selects that tenant on this operation and
+    /// checks the answer's confirmation. True for the data operations, false for the portfolio
+    /// listing, which is never scoped.
+    pub tenant_scoped: bool,
+}
+
+impl Operation {
+    /// The values the document lists for the query parameter `param`, in document order, or `None`
+    /// when it publishes no vocabulary for it.
+    #[must_use]
+    pub fn known_values(&self, param: &str) -> Option<&'static [&'static str]> {
+        self.known_values
+            .iter()
+            .find(|(name, _)| *name == param)
+            .map(|(_, values)| *values)
+    }
+
+    /// The deprecated values the document lists for the query parameter `param`, or `None` when
+    /// it lists none.
+    #[must_use]
+    pub fn deprecated_values(&self, param: &str) -> Option<&'static DeprecatedValues> {
+        self.deprecated_values.iter().find(|d| d.param == param)
+    }
+}
+
+/// Values of a query parameter that the API still accepts but has deprecated, as the document
+/// lists them (`x-hs-deprecated-values` and `x-hs-deprecated-values-sunset`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DeprecatedValues {
+    /// The query parameter, e.g. `severity`.
+    pub param: &'static str,
+    /// The deprecated values, in document order.
+    pub values: &'static [&'static str],
+    /// The last day the API accepts them (`YYYY-MM-DD`), when the document gives one.
+    pub sunset: Option<&'static str>,
 }
 
 /// A successful answer: the typed body, the body exactly as received (for `--json`, so fields this
@@ -54,6 +98,9 @@ pub struct ResponseMeta {
     pub rate_limit: Option<RateLimit>,
     /// `Retry-After`, in seconds.
     pub retry_after: Option<u64>,
+    /// `X-HS-Tenant` of a 2xx answer: the tenant id, lowercase, when the header is present exactly
+    /// once and holds a UUID. Informational only; this is not a tenant-isolation check.
+    pub tenant_id: Option<String>,
 }
 
 /// The `RateLimit-*` headers of an answer: the limit closest to being exhausted.
@@ -98,10 +145,25 @@ impl ResponseMeta {
             request_id: text("x-request-id"),
             rate_limit,
             retry_after: number("retry-after"),
+            tenant_id: if status.is_success() {
+                tenant_header(headers)
+            } else {
+                None
+            },
         }
     }
 }
 
+/// The single `X-HS-Tenant` value, when it is a canonical UUID (any case), lowercased.
+fn tenant_header(headers: &HeaderMap) -> Option<String> {
+    let mut values = headers.get_all("x-hs-tenant").iter();
+    let value = values.next()?.to_str().ok()?;
+    if values.next().is_some() {
+        return None;
+    }
+    crate::portfolio::is_uuid(value).then(|| value.to_ascii_lowercase())
+}
+
 /// What the client reports about each request it sends, for `--verbose`. It carries no header and
 /// no credential.
 #[derive(Debug, Clone)]
@@ -135,6 +197,15 @@ pub struct RetryEvent<'a> {
 type Observer = Arc<dyn Fn(&RequestEvent<'_>) + Send + Sync>;
 type RetryObserver = Arc<dyn Fn(&RetryEvent<'_>) + Send + Sync>;
 type Renew = Arc<dyn Fn() -> Option<SecretString> + Send + Sync>;
+type AnswerCheck = Arc<dyn Fn(&HeaderMap) -> Result<(), Error> + Send + Sync>;
+
+/// Extra headers a client sends on data requests, and the check its successful answers must pass.
+/// The portfolio module fills it in; this file knows nothing about what the headers mean.
+#[derive(Clone, Default)]
+pub(crate) struct Scope {
+    pub(crate) headers: HeaderMap,
+    pub(crate) check: Option<AnswerCheck>,
+}
 
 /// Builds a [`Client`].
 pub struct ClientBuilder {
@@ -149,6 +220,7 @@ pub struct ClientBuilder {
     observer: Option<Observer>,
     retry_observer: Option<RetryObserver>,
     renew: Option<Renew>,
+    pub(crate) scope: Scope,
 }
 
 impl fmt::Debug for ClientBuilder {
@@ -268,6 +340,7 @@ impl ClientBuilder {
             observer: self.observer,
             retry_observer: self.retry_observer,
             renew: self.renew,
+            scope: self.scope,
         })
     }
 }
@@ -285,6 +358,7 @@ pub struct Client {
     observer: Option<Observer>,
     retry_observer: Option<RetryObserver>,
     renew: Option<Renew>,
+    scope: Scope,
 }
 
 impl fmt::Debug for Client {
@@ -321,6 +395,7 @@ impl Client {
             observer: None,
             retry_observer: None,
             renew: None,
+            scope: Scope::default(),
         }
     }
 
@@ -369,24 +444,29 @@ impl Client {
         std::thread::sleep(wait);
     }
 
+    /// A GET. The operation decides whether the client's tenant selection applies: scope headers
+    /// are sent and checked only when `operation.tenant_scoped`.
     pub(crate) fn get<T: DeserializeOwned>(
         &self,
         operation: &'static Operation,
         path: String,
         query: Vec<(&'static str, String)>,
     ) -> Result<ApiResponse<T>, Error> {
+        let scoped = operation.tenant_scoped;
         let url = self.url(&path, &query);
         let mut rate_limit_retries = 0;
         let mut transient_retries = 0;
         let mut renewed = false;
         loop {
             let started = Instant::now();
-            let response = match self
+            let mut request = self
                 .http
                 .get(url.clone())
-                .header(AUTHORIZATION, self.authorization()?)
-                .send()
-            {
+                .header(AUTHORIZATION, self.authorization()?);
+            if scoped {
+                request = request.headers(self.scope.headers.clone());
+            }
+            let response = match request.send() {
                 Ok(response) => response,
                 Err(e)
                     if (e.is_connect() || e.is_timeout())
@@ -415,8 +495,14 @@ impl Client {
                     elapsed: started.elapsed(),
                 });
             }
+            // A scoped answer that does not carry the scope that was asked for is never decoded.
+            let verdict = match (&self.scope.check, scoped, status.is_success()) {
+                (Some(check), true, true) => check(response.headers()),
+                _ => Ok(()),
+            };
             let body = read_body(response, MAX_RESPONSE_BYTES).map_err(Error::Body)?;
             if status.is_success() {
+                verdict?;
                 let raw: serde_json::Value =
                     serde_json::from_slice(&body).map_err(|source| Error::Decode {
                         operation: operation.id,
@@ -588,6 +674,33 @@ pub fn encode_path_segment(segment: &str) -> Result<String, Error> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn known_values_are_looked_up_by_parameter() {
+        let operation = Operation {
+            id: "listThings",
+            method: "GET",
+            path: "/v1/things",
+            summary: "List things",
+            scopes: &[],
+            known_values: &[("severity", &["critical", "high"])],
+            deprecated_values: &[DeprecatedValues {
+                param: "severity",
+                values: &["alto"],
+                sunset: Some("2027-01-14"),
+            }],
+            tenant_scoped: true,
+        };
+        assert_eq!(
+            operation.known_values("severity"),
+            Some(&["critical", "high"][..])
+        );
+        assert_eq!(operation.known_values("page"), None);
+        let deprecated = operation.deprecated_values("severity").expect("listed");
+        assert_eq!(deprecated.values, &["alto"]);
+        assert_eq!(deprecated.sunset, Some("2027-01-14"));
+        assert_eq!(operation.deprecated_values("page"), None);
+    }
+
     fn client(base: &str) -> Client {
         Client::new(base.parse().expect("url"), SecretString::from("hsk_test")).expect("client")
     }
diff --git a/crates/hodeishield-api/src/error.rs b/crates/hodeishield-api/src/error.rs
index 02523e6..02937b1 100644
--- a/crates/hodeishield-api/src/error.rs
+++ b/crates/hodeishield-api/src/error.rs
@@ -86,6 +86,27 @@ pub enum Error {
     /// An id or slug that would change which resource the path addresses.
     #[error("{0:?} is not a valid identifier")]
     InvalidPathArgument(String),
+    /// The API has no portfolio listing (it answered `404` or `405` for the route).
+    #[error("this API does not offer portfolio access (HTTP {status} for the tenant listing)")]
+    PortfolioNotOffered {
+        /// The status the route answered with.
+        status: u16,
+    },
+    /// A client tenant identifier that is not a UUID.
+    #[error("{0:?} is not a valid client tenant identifier")]
+    InvalidTenant(String),
+    /// The API answered for another client tenant than the one asked for, or did not say which.
+    #[error(
+        "the API did not confirm the client tenant that was asked for (asked for {requested}, \
+         answer says {})",
+        answered.as_deref().unwrap_or("nothing")
+    )]
+    TenantMismatch {
+        /// The tenant the request named.
+        requested: String,
+        /// What the answer's header said, when it said anything.
+        answered: Option<String>,
+    },
 }
 
 impl Error {
diff --git a/crates/hodeishield-api/src/generated.rs b/crates/hodeishield-api/src/generated.rs
index 495df14..db4a5c5 100644
--- a/crates/hodeishield-api/src/generated.rs
+++ b/crates/hodeishield-api/src/generated.rs
@@ -13,7 +13,7 @@
 use serde::{Deserialize, Serialize};
 
 /// `info.version` of the OpenAPI document this client was generated from.
-pub const OPENAPI_VERSION: &str = "2026-09-28";
+pub const OPENAPI_VERSION: &str = "2026-10-16";
 
 /// The server the OpenAPI document declares.
 pub const DEFAULT_SERVER: &str = "https://api.hodeishield.com";
@@ -28,7 +28,7 @@ pub struct ErrorBody {
     pub message: String,
     /// Also the `X-Request-Id` response header.
     pub request_id: String,
-    /// Diagnostic. Not part of the frozen contract.
+    /// Diagnostic, except `code` and the keys the operation’s error descriptions name, which are contract.
     #[serde(default)]
     pub details: Option<serde_json::Map<String, serde_json::Value>>,
 }
@@ -121,7 +121,7 @@ pub struct Alert {
     pub vendor_id: String,
     /// Alert family, e.g. `breach`, `cve`, `rating_drop`.
     pub r#type: String,
-    /// critical | high | medium | low, when classified.
+    /// critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.
     #[serde(default)]
     pub severity: Option<String>,
     pub title: String,
@@ -168,9 +168,9 @@ pub struct Risk {
     pub title: String,
     #[serde(default)]
     pub description: Option<String>,
-    /// Risk domain, as configured by the tenant.
+    /// Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational.
     pub domain: String,
-    /// identified | assessed | treated | accepted | closed | …
+    /// Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed.
     pub status: String,
     /// mitigate | accept | transfer | avoid.
     #[serde(default)]
@@ -337,6 +337,38 @@ pub struct ListEndpointsResponse {
     pub pagination: Pagination,
 }
 
+/// The organisation the tenant belongs to: the MSSP itself for the tenants it holds directly (including its internal one), or the client organisation.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Organization {
+    pub id: String,
+    pub name: String,
+}
+
+/// A client tenant an MSSP portfolio key may select.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct PortfolioTenant {
+    /// Stable identifier (lowercase). The ONLY value `X-HS-Tenant` accepts.
+    pub id: String,
+    /// Display name. Untrusted text.
+    pub name: String,
+    /// Short name, unique across the platform. A client may resolve a slug to an `id` from this list; the server never accepts a slug as a selector.
+    pub slug: String,
+    /// The organisation the tenant belongs to: the MSSP itself for the tenants it holds directly (including its internal one), or the client organisation.
+    pub organization: Organization,
+    /// True only for the MSSP’s own internal tenant.
+    pub internal: bool,
+    /// Whether the tenant is enabled. A deactivated tenant is listed but cannot be read.
+    pub active: bool,
+    /// Open vocabulary: `in_force` (licence in force), `grace` (grace period: reads are served), `inactive` (none, suspended, revoked or expired: data operations answer 403 `LICENCE_INACTIVE`). Treat an unknown value as "may not be readable". A tenant is readable when `active` is true and `licence_status` is not `inactive`.
+    pub licence_status: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ListPortfolioTenantsResponse {
+    pub data: Vec<PortfolioTenant>,
+    pub pagination: Pagination,
+}
+
 /// Accepted values of a query parameter.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum VendorSort {
@@ -776,6 +808,47 @@ impl std::str::FromStr for EndpointStatus {
     }
 }
 
+/// Accepted values of a query parameter.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum PortfolioTenantSort {
+    /// `name`
+    Name,
+    /// `slug`
+    Slug,
+}
+
+impl PortfolioTenantSort {
+    /// Every accepted value, as sent on the wire.
+    pub const VALUES: &'static [&'static str] = &["name", "slug"];
+
+    /// The value as sent on the wire.
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Name => "name",
+            Self::Slug => "slug",
+        }
+    }
+}
+
+impl std::fmt::Display for PortfolioTenantSort {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+impl std::str::FromStr for PortfolioTenantSort {
+    type Err = crate::ParseEnumError;
+
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        match value {
+            "name" => Ok(Self::Name),
+            "slug" => Ok(Self::Slug),
+            _ => Err(crate::ParseEnumError::new(value, Self::VALUES)),
+        }
+    }
+}
+
 /// Query parameters of `listVendors`.
 #[derive(Debug, Clone, Default, PartialEq)]
 pub struct ListVendorsParams {
@@ -843,7 +916,7 @@ pub struct ListAlertsParams {
     pub order: Option<Order>,
     /// Filter by the derived status.
     pub status: Option<AlertStatus>,
-    /// Exact severity match.
+    /// Exact severity match, in the vocabulary the response uses (critical | high | medium | low | info). The legacy Spanish values (critico, alto, medio, bajo, info) are still accepted and mean the same; they are documented as accepted until 2027-01-14, so move to the English ones.
     pub severity: Option<String>,
     /// Only alerts about this vendor.
     pub vendor_id: Option<String>,
@@ -1091,6 +1164,40 @@ impl ListEndpointsParams {
     }
 }
 
+/// Query parameters of `listPortfolioTenants`.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ListPortfolioTenantsParams {
+    /// 1-based page number. Defaults to 1.
+    pub page: Option<i64>,
+    /// Items per page, 1..200. Defaults to 50.
+    pub per_page: Option<i64>,
+    /// Field to order by. One of: name, slug.
+    pub sort: Option<PortfolioTenantSort>,
+    /// Sort direction. Defaults to desc.
+    pub order: Option<Order>,
+}
+
+impl ListPortfolioTenantsParams {
+    /// The query string, in document order, without the parameters that are unset.
+    #[must_use]
+    pub fn query_pairs(&self) -> Vec<(&'static str, String)> {
+        let mut pairs = Vec::new();
+        if let Some(value) = &self.page {
+            pairs.push(("page", value.to_string()));
+        }
+        if let Some(value) = &self.per_page {
+            pairs.push(("per_page", value.to_string()));
+        }
+        if let Some(value) = &self.sort {
+            pairs.push(("sort", value.as_str().to_owned()));
+        }
+        if let Some(value) = &self.order {
+            pairs.push(("order", value.as_str().to_owned()));
+        }
+        pairs
+    }
+}
+
 /// Every `/v1` operation, as the OpenAPI document describes it.
 pub mod operations {
     use crate::Operation;
@@ -1102,6 +1209,9 @@ pub mod operations {
         path: "/v1/vendors",
         summary: "List third parties",
         scopes: &["supply_risk:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/vendors/{id}`: Fetch one third party.
@@ -1111,6 +1221,9 @@ pub mod operations {
         path: "/v1/vendors/{id}",
         summary: "Fetch one third party",
         scopes: &["supply_risk:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/alerts`: List supply-chain alerts.
@@ -1120,6 +1233,13 @@ pub mod operations {
         path: "/v1/alerts",
         summary: "List supply-chain alerts",
         scopes: &["supply_risk:read"],
+        known_values: &[("severity", &["critical", "high", "medium", "low", "info"])],
+        deprecated_values: &[crate::DeprecatedValues {
+            param: "severity",
+            values: &["critico", "alto", "medio", "bajo"],
+            sunset: Some("2027-01-14"),
+        }],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/alerts/{id}`: Fetch one alert.
@@ -1129,6 +1249,9 @@ pub mod operations {
         path: "/v1/alerts/{id}",
         summary: "Fetch one alert",
         scopes: &["supply_risk:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/risks`: List risk-register entries.
@@ -1138,6 +1261,9 @@ pub mod operations {
         path: "/v1/risks",
         summary: "List risk-register entries",
         scopes: &["supply_risk:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/risks/{id}`: Fetch one risk-register entry.
@@ -1147,6 +1273,9 @@ pub mod operations {
         path: "/v1/risks/{id}",
         summary: "Fetch one risk-register entry",
         scopes: &["supply_risk:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/compliance/controls`: List control status for a framework.
@@ -1156,6 +1285,9 @@ pub mod operations {
         path: "/v1/compliance/controls",
         summary: "List control status for a framework",
         scopes: &["compliance.<framework>:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/compliance/frameworks/{framework}`: Framework posture summary.
@@ -1165,6 +1297,9 @@ pub mod operations {
         path: "/v1/compliance/frameworks/{framework}",
         summary: "Framework posture summary",
         scopes: &["compliance.<framework>:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/evidence`: List security evidence.
@@ -1174,6 +1309,9 @@ pub mod operations {
         path: "/v1/evidence",
         summary: "List security evidence",
         scopes: &["evidence:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/evidence/{id}`: Fetch one evidence item.
@@ -1183,6 +1321,9 @@ pub mod operations {
         path: "/v1/evidence/{id}",
         summary: "Fetch one evidence item",
         scopes: &["evidence:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
     };
 
     /// `GET /v1/endpoints`: List enrolled endpoint agents.
@@ -1192,6 +1333,21 @@ pub mod operations {
         path: "/v1/endpoints",
         summary: "List enrolled endpoint agents",
         scopes: &["endpoints:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: true,
+    };
+
+    /// `GET /v1/portfolio/tenants`: List the client tenants of an MSSP portfolio.
+    pub const LIST_PORTFOLIO_TENANTS: Operation = Operation {
+        id: "listPortfolioTenants",
+        method: "GET",
+        path: "/v1/portfolio/tenants",
+        summary: "List the client tenants of an MSSP portfolio",
+        scopes: &["portfolio:read"],
+        known_values: &[],
+        deprecated_values: &[],
+        tenant_scoped: false,
     };
 
     /// All operations, in document order.
@@ -1207,6 +1363,7 @@ pub mod operations {
         LIST_EVIDENCE,
         GET_EVIDENCE,
         LIST_ENDPOINTS,
+        LIST_PORTFOLIO_TENANTS,
     ];
 }
 
@@ -1441,4 +1598,25 @@ impl crate::Client {
             params.query_pairs(),
         )
     }
+
+    /// List the client tenants of an MSSP portfolio.
+    ///
+    /// Every tenant the presented PORTFOLIO key may select with `X-HS-Tenant`: the MSSP’s own tenants (its internal one included) and every tenant of its active client organisations, active or not, licensed or not, narrowed to the key’s client subset when it has one. Membership is evaluated live on every request. Only a portfolio key (`hsp_…`) can call this operation; this operation never takes `X-HS-Tenant`.
+    ///
+    /// Required scope: `portfolio:read`. Published in `/v1` since 2026-10-16.
+    ///
+    /// # Errors
+    ///
+    /// [`crate::Error`] when the request cannot be sent, the API answers with an error, or the
+    /// body does not match the document.
+    pub fn list_portfolio_tenants(
+        &self,
+        params: &ListPortfolioTenantsParams,
+    ) -> Result<crate::ApiResponse<ListPortfolioTenantsResponse>, crate::Error> {
+        self.get(
+            &operations::LIST_PORTFOLIO_TENANTS,
+            "/v1/portfolio/tenants".to_owned(),
+            params.query_pairs(),
+        )
+    }
 }
diff --git a/crates/hodeishield-api/src/lib.rs b/crates/hodeishield-api/src/lib.rs
index b1b39b5..78b513e 100644
--- a/crates/hodeishield-api/src/lib.rs
+++ b/crates/hodeishield-api/src/lib.rs
@@ -24,12 +24,13 @@
 
 mod client;
 mod error;
+pub mod portfolio;
 #[allow(missing_docs)]
 #[path = "generated.rs"]
 pub mod v1;
 
 pub use client::{
-    ApiResponse, Client, ClientBuilder, MAX_RESPONSE_BYTES, Operation, RateLimit, RequestEvent,
-    ResponseMeta, RetryEvent, encode_path_segment, is_loopback_host, read_body,
+    ApiResponse, Client, ClientBuilder, DeprecatedValues, MAX_RESPONSE_BYTES, Operation, RateLimit,
+    RequestEvent, ResponseMeta, RetryEvent, encode_path_segment, is_loopback_host, read_body,
 };
 pub use error::{ApiError, ApiErrorBody, Error, ParseEnumError};
diff --git a/crates/hodeishield-api/src/portfolio.rs b/crates/hodeishield-api/src/portfolio.rs
new file mode 100644
index 0000000..1e104be
--- /dev/null
+++ b/crates/hodeishield-api/src/portfolio.rs
@@ -0,0 +1,360 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! Client tenants of a portfolio credential: list them, and read one of them.
+//!
+//! This module follows the published `/v1` portfolio contract (contract version `2026-10-16`):
+//!
+//! - `GET /v1/portfolio/tenants` (`listPortfolioTenants`), scope `portfolio:read`, paginated like
+//!   every `/v1` list (`page`, `per_page`, `sort`, `order`; the API's default order is descending,
+//!   so this client asks for ascending);
+//! - the client tenant is selected on each of the data operations with one optional `X-HS-Tenant`
+//!   request header holding the tenant's UUID, and every successful answer to such a request
+//!   repeats the tenant it read in an `X-HS-Tenant` response header (lowercase UUID). Error
+//!   answers never carry it, and the listing neither takes nor returns it;
+//! - a tenant is readable when it is active and its `licence_status` is `in_force` or `grace`. The
+//!   `licence_status` vocabulary is open: a value this client does not know counts as not
+//!   readable.
+//!
+//! The version string of the API description is not compared with anything. Whether an API offers
+//! portfolio access is found by asking for the listing: a `404` or `405` on that route becomes
+//! [`Error::PortfolioNotOffered`].
+//!
+//! # Relation to the generated client
+//!
+//! The listing operation is described by the vendored `openapi/v1.json`: its method, path, scope
+//! and the fact that it is never tenant-scoped come from the generated
+//! [`LIST_PORTFOLIO_TENANTS`](crate::v1::operations::LIST_PORTFOLIO_TENANTS). This file adds what
+//! the generated code does not provide: [`ClientBuilder::tenant`] and its confirmation check, the
+//! readability of a [`Tenant`], and the mapping of a missing route to
+//! [`Error::PortfolioNotOffered`].
+//!
+//! # Interface
+//!
+//! - [`Client::list_tenants`] lists the client tenants the credential may read.
+//! - [`ClientBuilder::tenant`] makes every data call of the built client read that tenant. The
+//!   client then refuses any successful answer that does not name the same tenant, so data of one
+//!   client is never returned as if it were another's.
+
+use crate::client::Scope;
+use crate::error::Error;
+use crate::v1::operations::LIST_PORTFOLIO_TENANTS;
+use crate::v1::{Order, Pagination};
+use crate::{ApiResponse, Client, ClientBuilder};
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+/// Request and response header that selects, and confirms, the client tenant.
+const TENANT_HEADER: HeaderName = HeaderName::from_static("x-hs-tenant");
+
+/// A client tenant of the portfolio. Text fields come from the server and are untrusted.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Tenant {
+    /// Stable identifier (a UUID): what selects the tenant.
+    pub id: String,
+    /// Display name.
+    pub name: String,
+    /// Short name, unique across the platform, for people and scripts.
+    pub slug: String,
+    /// The organisation the tenant belongs to: the MSSP's own for the tenants it holds directly.
+    pub organization: TenantOrganization,
+    /// Whether this is the MSSP's own internal tenant rather than a client's.
+    pub internal: bool,
+    /// Whether the tenant is enabled.
+    pub active: bool,
+    /// `in_force`, `grace` or `inactive`. The vocabulary is open: other values may appear.
+    pub licence_status: String,
+}
+
+/// Whether a [`Tenant`] can be expected to be readable.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Readability {
+    /// Active, with a licence in force or in its grace period.
+    Readable,
+    /// Deactivated, or its licence status is `inactive`: the API would answer `403`.
+    Inactive,
+    /// Active, with a licence status this client does not know. The vocabulary is open, so such a
+    /// tenant is neither assumed readable nor assumed inactive.
+    Unknown,
+}
+
+impl Tenant {
+    /// Whether this tenant is readable, inactive, or has a licence status this client does not
+    /// know.
+    #[must_use]
+    pub fn readability(&self) -> Readability {
+        if !self.active {
+            return Readability::Inactive;
+        }
+        match self.licence_status.as_str() {
+            "in_force" | "grace" => Readability::Readable,
+            "inactive" => Readability::Inactive,
+            _ => Readability::Unknown,
+        }
+    }
+
+    /// Whether reading this tenant can be expected to work: it is active and its licence is in
+    /// force or in its grace period. A licence status this client does not know counts as not
+    /// readable, since the vocabulary is open.
+    #[must_use]
+    pub fn readable(&self) -> bool {
+        self.readability() == Readability::Readable
+    }
+}
+
+/// The organisation a [`Tenant`] belongs to.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TenantOrganization {
+    /// Identifier of the organisation.
+    pub id: String,
+    /// Display name.
+    pub name: String,
+}
+
+/// The answer of [`Client::list_tenants`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ListTenantsResponse {
+    /// One page of tenants.
+    pub data: Vec<Tenant>,
+    /// Where this page sits in the whole list.
+    pub pagination: Pagination,
+}
+
+/// What [`Client::list_tenants`] sends.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ListTenantsParams {
+    /// 1-based page number.
+    pub page: Option<i64>,
+    /// Items per page, 1..200.
+    pub per_page: Option<i64>,
+    /// Sort by `name` or `slug`.
+    pub sort: Option<TenantSort>,
+    /// Direction. The API's default is descending.
+    pub order: Option<Order>,
+}
+
+/// The fields the tenant listing can be sorted by.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TenantSort {
+    /// `name`
+    Name,
+    /// `slug`
+    Slug,
+}
+
+impl TenantSort {
+    /// The value as sent on the wire.
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Name => "name",
+            Self::Slug => "slug",
+        }
+    }
+}
+
+impl ListTenantsParams {
+    /// Alphabetical by name, the order a person expects.
+    #[must_use]
+    pub fn alphabetical(page: Option<i64>, per_page: Option<i64>) -> Self {
+        Self {
+            page,
+            per_page,
+            sort: Some(TenantSort::Name),
+            order: Some(Order::Asc),
+        }
+    }
+
+    fn query_pairs(&self) -> Vec<(&'static str, String)> {
+        let mut pairs = Vec::new();
+        if let Some(page) = self.page {
+            pairs.push(("page", page.to_string()));
+        }
+        if let Some(per_page) = self.per_page {
+            pairs.push(("per_page", per_page.to_string()));
+        }
+        if let Some(sort) = self.sort {
+            pairs.push(("sort", sort.as_str().to_owned()));
+        }
+        if let Some(order) = self.order {
+            pairs.push(("order", order.as_str().to_owned()));
+        }
+        pairs
+    }
+}
+
+impl Client {
+    /// The client tenants this credential may read. The listing is never scoped to a tenant, even
+    /// on a client built with [`ClientBuilder::tenant`].
+    ///
+    /// Required scope: `portfolio:read`.
+    ///
+    /// # Errors
+    ///
+    /// [`Error`] when the request cannot be sent, the API answers with an error (a credential
+    /// without portfolio scope gets `403`), or the body does not match the contract.
+    /// [`Error::PortfolioNotOffered`] when the API has no such route.
+    pub fn list_tenants(
+        &self,
+        params: &ListTenantsParams,
+    ) -> Result<ApiResponse<ListTenantsResponse>, Error> {
+        self.get(
+            &LIST_PORTFOLIO_TENANTS,
+            LIST_PORTFOLIO_TENANTS.path.to_owned(),
+            params.query_pairs(),
+        )
+        .map_err(|error| match error {
+            // A 404/405 that carries one of the portfolio contract's own codes comes from an
+            // API that does offer the portfolio: it stays the API's error.
+            Error::Api(api) if matches!(api.status, 404 | 405) && !is_portfolio_code(&api) => {
+                Error::PortfolioNotOffered { status: api.status }
+            }
+            other => other,
+        })
+    }
+}
+
+/// Whether the error answer names one of the portfolio contract's `details.code` values.
+fn is_portfolio_code(api: &crate::ApiError) -> bool {
+    api.body
+        .as_ref()
+        .and_then(|body| body.details.as_ref())
+        .and_then(|details| details.get("code"))
+        .and_then(serde_json::Value::as_str)
+        .is_some_and(|code| code.starts_with("TENANT_") || code == "LICENCE_INACTIVE")
+}
+
+impl ClientBuilder {
+    /// Makes every data call of the built client read the client tenant `id`.
+    ///
+    /// The built client sends the selection on each request and returns an answer only when it
+    /// confirms the same tenant; otherwise the call fails with [`Error::TenantMismatch`].
+    ///
+    /// # Errors
+    ///
+    /// [`Error::InvalidTenant`] when `id` is not a UUID.
+    pub fn tenant(mut self, id: &str) -> Result<Self, Error> {
+        if !is_uuid(id) {
+            return Err(Error::InvalidTenant(id.to_owned()));
+        }
+        let wanted = id.to_ascii_lowercase();
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            TENANT_HEADER,
+            HeaderValue::from_str(&wanted).map_err(|_| Error::InvalidTenant(id.to_owned()))?,
+        );
+        let check = move |answer: &HeaderMap| {
+            // Header names compare case-insensitively (the map does it); the answer must carry
+            // exactly one value, the lowercase UUID of the tenant that was read.
+            let mut values = answer.get_all(TENANT_HEADER).iter();
+            let answered = match (values.next(), values.next()) {
+                (Some(value), None) => value.to_str().ok().map(str::to_owned),
+                _ => None,
+            };
+            if answered.as_deref() == Some(wanted.as_str()) {
+                Ok(())
+            } else {
+                Err(Error::TenantMismatch {
+                    requested: wanted.clone(),
+                    answered,
+                })
+            }
+        };
+        self.scope = Scope {
+            headers,
+            check: Some(Arc::new(check)),
+        };
+        Ok(self)
+    }
+}
+
+/// Whether `text` is a UUID in the 8-4-4-4-12 form, in any case. The one check for tenant ids: the
+/// tenant selection and the `X-HS-Tenant` metadata both use it.
+#[must_use]
+pub fn is_uuid(text: &str) -> bool {
+    let groups: Vec<&str> = text.split('-').collect();
+    groups.len() == 5
+        && groups
+            .iter()
+            .zip([8, 4, 4, 4, 12])
+            .all(|(g, len)| g.len() == len && g.bytes().all(|b| b.is_ascii_hexdigit()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn recognises_uuids_only() {
+        assert!(is_uuid("0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e"));
+        assert!(is_uuid("0B8F2A52-6A0E-4D5C-9D3E-1F2A3B4C5D6E"));
+        for bad in [
+            "",
+            "acme",
+            "0b8f2a52-6a0e-4d5c-9d3e",
+            "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6",
+            "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6g",
+            "a, b",
+        ] {
+            assert!(!is_uuid(bad), "{bad:?}");
+        }
+    }
+
+    fn tenant(active: bool, licence: &str) -> Tenant {
+        Tenant {
+            id: "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e".to_owned(),
+            name: "Acme".to_owned(),
+            slug: "acme".to_owned(),
+            organization: TenantOrganization {
+                id: "o".to_owned(),
+                name: "Acme Group".to_owned(),
+            },
+            internal: false,
+            active,
+            licence_status: licence.to_owned(),
+        }
+    }
+
+    #[test]
+    fn a_tenant_is_readable_only_when_active_with_a_known_good_licence() {
+        assert!(tenant(true, "in_force").readable());
+        assert!(tenant(true, "grace").readable());
+        assert!(!tenant(true, "inactive").readable());
+        assert!(!tenant(false, "in_force").readable());
+        assert!(!tenant(false, "grace").readable());
+        // The vocabulary is open: what is not known is not assumed readable.
+        assert!(!tenant(true, "suspended_soon").readable());
+        assert!(!tenant(true, "").readable());
+        assert!(!tenant(true, "IN_FORCE").readable());
+    }
+
+    #[test]
+    fn inactive_and_unknown_tenants_are_told_apart() {
+        use Readability::{Inactive, Readable, Unknown};
+        assert_eq!(tenant(true, "in_force").readability(), Readable);
+        assert_eq!(tenant(true, "grace").readability(), Readable);
+        assert_eq!(tenant(true, "inactive").readability(), Inactive);
+        assert_eq!(tenant(false, "in_force").readability(), Inactive);
+        // Deactivated wins over a status nobody knows.
+        assert_eq!(tenant(false, "suspended_soon").readability(), Inactive);
+        assert_eq!(tenant(true, "suspended_soon").readability(), Unknown);
+        assert_eq!(tenant(true, "").readability(), Unknown);
+        assert_eq!(tenant(true, "IN_FORCE").readability(), Unknown);
+    }
+
+    #[test]
+    fn the_listing_asks_for_ascending_names_when_told_to() {
+        let pairs = ListTenantsParams::alphabetical(Some(2), Some(200)).query_pairs();
+        assert_eq!(
+            pairs,
+            vec![
+                ("page", "2".to_owned()),
+                ("per_page", "200".to_owned()),
+                ("sort", "name".to_owned()),
+                ("order", "asc".to_owned()),
+            ]
+        );
+        assert!(ListTenantsParams::default().query_pairs().is_empty());
+    }
+}
diff --git a/crates/hodeishield-api/tests/api.rs b/crates/hodeishield-api/tests/api.rs
index 608c751..261797c 100644
--- a/crates/hodeishield-api/tests/api.rs
+++ b/crates/hodeishield-api/tests/api.rs
@@ -82,6 +82,62 @@ fn list_sends_the_bearer_and_the_query_and_keeps_unknown_fields_in_raw() {
     assert_eq!(page.raw["data"][0]["field_added_later"]["nested"], true);
 }
 
+const TENANT: &str = "3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5d";
+
+fn tenant_meta(status: usize, headers: &[&str]) -> hodeishield_api::ResponseMeta {
+    let mut server = mockito::Server::new();
+    let mut mock = server.mock("GET", "/v1/vendors").with_status(status);
+    for value in headers {
+        mock = mock.with_header("x-hs-tenant", value);
+    }
+    let body = if status == 200 {
+        r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":0}}"#
+    } else {
+        r#"{"error":{"code":"forbidden","message":"no","request_id":"r"}}"#
+    };
+    let _mock = mock.with_body(body).create();
+    match client(&server).list_vendors(&ListVendorsParams::default()) {
+        Ok(page) => page.meta,
+        Err(e) => e.api().expect("api error").meta.clone(),
+    }
+}
+
+#[test]
+fn the_tenant_header_of_a_2xx_answer_is_kept_lowercase() {
+    assert_eq!(
+        tenant_meta(200, &[TENANT]).tenant_id.as_deref(),
+        Some(TENANT)
+    );
+    let upper = TENANT.to_ascii_uppercase();
+    assert_eq!(
+        tenant_meta(200, &[upper.as_str()]).tenant_id.as_deref(),
+        Some(TENANT)
+    );
+}
+
+#[test]
+fn a_missing_malformed_or_duplicated_tenant_header_gives_none() {
+    assert_eq!(tenant_meta(200, &[]).tenant_id, None);
+    for bad in [
+        "",
+        "not-a-uuid",
+        "3f2b8c1a0d4e4f6a9b7c5e1d2a3b4c5d",
+        "3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5",
+        "3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5g",
+        "{3f2b8c1a-0d4e-4f6a-9b7c-5e1d2a3b4c5d}",
+    ] {
+        assert_eq!(tenant_meta(200, &[bad]).tenant_id, None, "{bad:?}");
+    }
+    let other = "11111111-2222-4333-8444-555555555555";
+    assert_eq!(tenant_meta(200, &[TENANT, other]).tenant_id, None);
+    assert_eq!(tenant_meta(200, &[TENANT, TENANT]).tenant_id, None);
+}
+
+#[test]
+fn a_tenant_header_on_an_error_answer_is_ignored() {
+    assert_eq!(tenant_meta(403, &[TENANT]).tenant_id, None);
+}
+
 #[test]
 fn path_arguments_are_encoded() {
     let mut server = mockito::Server::new();
@@ -606,3 +662,575 @@ fn retry_observer_receives_expected_events() {
     unavailable.assert();
     success.assert();
 }
+
+// The portfolio contract (version 2026-10-16): the listing, the tenant selection and its echo.
+
+/// The shape of a portfolio key: `hsp_`, 12 hex, `_`, 64 hex.
+const PORTFOLIO_KEY: &str =
+    "hsp_3f2a9c0d1b4e_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+
+const TENANT_A: &str = "11111111-1111-4111-8111-111111111111";
+const TENANT_B: &str = "22222222-2222-4222-8222-222222222222";
+const EMPTY_PAGE: &str =
+    r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":0}}"#;
+
+fn tenant_client(server: &mockito::Server, tenant: &str) -> Client {
+    Client::builder(
+        server.url().parse().expect("url"),
+        SecretString::from(PORTFOLIO_KEY),
+    )
+    .tenant(tenant)
+    .expect("a UUID")
+    .build()
+    .expect("client")
+}
+
+#[test]
+fn list_tenants_decodes_the_listing_and_never_sends_a_tenant() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let mut server = mockito::Server::new();
+    let mock = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_header("authorization", format!("Bearer {PORTFOLIO_KEY}").as_str())
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(format!(
+            r#"{{"data":[{{"id":"{TENANT_A}","name":"Acme","slug":"acme","organization":{{"id":"o1","name":"Acme Group"}},"internal":false,"active":true,"licence_status":"in_force","later":1}},{{"id":"{TENANT_B}","name":"Beta","slug":"beta","organization":{{"id":"o2","name":"Beta Group"}},"internal":true,"active":false,"licence_status":"something_new"}}],"pagination":{{"page":1,"per_page":50,"total":2,"total_pages":1}}}}"#
+        ))
+        .create();
+    // Even a client built for one tenant lists the whole portfolio.
+    let response = tenant_client(&server, TENANT_B)
+        .list_tenants(&ListTenantsParams::default())
+        .expect("listing");
+    mock.assert();
+    assert_eq!(response.data.data[0].slug, "acme");
+    assert_eq!(response.data.data[0].licence_status, "in_force");
+    assert_eq!(response.raw["data"][0]["later"], 1);
+    // An unknown licence status decodes, and is not readable.
+    let beta = &response.data.data[1];
+    assert_eq!(beta.licence_status, "something_new");
+    assert!(!beta.readable() && beta.internal);
+    assert!(response.data.data[0].readable());
+}
+
+#[test]
+fn a_selected_tenant_travels_on_data_calls_and_must_be_confirmed() {
+    let mut server = mockito::Server::new();
+    let ok = server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", TENANT_A)
+        // Header names are case-insensitive; the value is the lowercase UUID.
+        .with_header("X-HS-Tenant", TENANT_A)
+        .with_header("Vary", "X-HS-Tenant")
+        .with_body(EMPTY_PAGE)
+        .create();
+    tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("confirmed answer");
+    ok.assert();
+}
+
+#[test]
+fn an_answer_for_another_tenant_or_for_none_is_refused() {
+    let mut server = mockito::Server::new();
+    let other = server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("another tenant");
+    assert!(
+        matches!(&err, Error::TenantMismatch { answered: Some(a), .. } if a == TENANT_B),
+        "{err:?}"
+    );
+    other.remove();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("no confirmation");
+    assert!(
+        matches!(err, Error::TenantMismatch { answered: None, .. }),
+        "{err:?}"
+    );
+}
+
+#[test]
+fn a_client_without_a_tenant_sends_no_selection_and_checks_nothing() {
+    let mut server = mockito::Server::new();
+    let mock = server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(EMPTY_PAGE)
+        .create();
+    client(&server)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("plain call");
+    mock.assert();
+}
+
+#[test]
+fn a_tenant_that_is_not_a_uuid_is_refused_before_any_request() {
+    for bad in [
+        "acme",
+        "",
+        "11111111-1111-4111-8111-111111111111, 22222222-2222-4222-8222-222222222222",
+    ] {
+        let err = Client::builder(
+            "https://api.example.test".parse().expect("url"),
+            SecretString::from("k"),
+        )
+        .tenant(bad)
+        .expect_err("not a UUID");
+        assert!(matches!(err, Error::InvalidTenant(_)), "{bad:?}");
+    }
+}
+
+#[test]
+fn the_tenant_is_sent_in_lowercase_and_the_echo_must_be_exactly_that() {
+    let lower = "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e";
+    let upper = lower.to_ascii_uppercase();
+    let mut server = mockito::Server::new();
+    // The request carries the lowercase form even when the caller gave capitals.
+    let sent = server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", lower)
+        .with_header("x-hs-tenant", lower)
+        .with_body(EMPTY_PAGE)
+        .create();
+    tenant_client(&server, &upper)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("lowercase echo");
+    sent.assert();
+    // An echo in capitals is not what the contract promises: refused.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", &upper)
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, lower)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("not the contract's form");
+    assert!(matches!(err, Error::TenantMismatch { .. }), "{err:?}");
+}
+
+#[test]
+fn an_echo_that_names_two_tenants_is_refused() {
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", TENANT_A)
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body(EMPTY_PAGE)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("two values");
+    assert!(matches!(err, Error::TenantMismatch { .. }), "{err:?}");
+}
+
+#[test]
+fn every_data_operation_sends_the_selection_and_checks_the_echo() {
+    use hodeishield_api::v1::{
+        ListAlertsParams, ListComplianceControlsParams, ListEndpointsParams, ListEvidenceParams,
+        ListRisksParams,
+    };
+    let mut server = mockito::Server::new();
+    let any = server
+        .mock("GET", mockito::Matcher::Any)
+        .match_header("x-hs-tenant", TENANT_A)
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body(EMPTY_PAGE)
+        .expect(5)
+        .create();
+    let c = tenant_client(&server, TENANT_A);
+    fn refused<T>(r: Result<T, Error>) -> bool {
+        matches!(r, Err(Error::TenantMismatch { .. }))
+    }
+    assert!(refused(c.list_alerts(&ListAlertsParams::default())));
+    assert!(refused(c.list_risks(&ListRisksParams::default())));
+    assert!(refused(c.list_evidence(&ListEvidenceParams::default())));
+    assert!(refused(c.list_endpoints(&ListEndpointsParams::default())));
+    assert!(refused(c.list_compliance_controls(
+        &ListComplianceControlsParams {
+            page: None,
+            per_page: None,
+            sort: None,
+            order: None,
+            framework: "nis2".to_owned(),
+            status: None,
+        }
+    )));
+    any.assert();
+}
+
+#[test]
+fn an_error_answer_is_reported_as_the_api_error_whatever_the_header_says() {
+    // The contract has no echo on errors; a client must not mistake one for a mismatch, nor hide
+    // the real refusal behind it.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant in this credential's portfolio.","request_id":"r","details":{"code":"TENANT_NOT_FOUND"}}}"#)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("not in the portfolio");
+    let api = err.api().expect("the API's own error");
+    assert_eq!(api.status, 404);
+    let details = api
+        .body
+        .as_ref()
+        .and_then(|b| b.details.as_ref())
+        .expect("details");
+    assert_eq!(details["code"], "TENANT_NOT_FOUND");
+}
+
+#[test]
+fn the_listing_asks_for_the_order_it_is_given() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let mut server = mockito::Server::new();
+    let mock = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("page".into(), "2".into()),
+            mockito::Matcher::UrlEncoded("per_page".into(), "200".into()),
+            mockito::Matcher::UrlEncoded("sort".into(), "name".into()),
+            mockito::Matcher::UrlEncoded("order".into(), "asc".into()),
+        ]))
+        .with_body(EMPTY_PAGE)
+        .create();
+    client(&server)
+        .list_tenants(&ListTenantsParams::alphabetical(Some(2), Some(200)))
+        .expect("listing");
+    mock.assert();
+}
+
+#[test]
+fn a_listing_that_breaks_the_contract_is_a_decode_error() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let mut server = mockito::Server::new();
+    // `organization` is never null.
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_body(format!(
+            r#"{{"data":[{{"id":"{TENANT_A}","name":"A","slug":"a","organization":null,"internal":false,"active":true,"licence_status":"in_force"}}],"pagination":{{"page":1,"per_page":50,"total":1,"total_pages":1}}}}"#
+        ))
+        .create();
+    let err = client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("null organization");
+    assert!(matches!(err, Error::Decode { .. }), "{err:?}");
+}
+
+#[test]
+fn an_api_without_the_listing_route_is_told_apart_from_other_errors() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    for status in [404_usize, 405] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .with_status(status)
+            .with_body(r#"{"error":{"code":"not_found","message":"Not found","request_id":"r"}}"#)
+            .create();
+        let err = client(&server)
+            .list_tenants(&ListTenantsParams::default())
+            .expect_err("no route");
+        assert!(
+            matches!(&err, Error::PortfolioNotOffered { status: s } if usize::from(*s) == status),
+            "{status}: {err:?}"
+        );
+    }
+    // Other statuses stay what the API said, and a 404 on a data operation is not this.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["portfolio:read"]}}}"#)
+        .create();
+    server
+        .mock("GET", "/v1/vendors/v1")
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"x","request_id":"r"}}"#)
+        .create();
+    let c = client(&server);
+    let err = c
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("403");
+    assert_eq!(err.api().map(|a| a.status), Some(403));
+    let err = c.get_vendor("v1").expect_err("404");
+    assert_eq!(err.api().map(|a| a.status), Some(404));
+}
+
+#[test]
+fn a_portfolio_429_is_retried_after_a_short_retry_after_and_reports_its_scope_otherwise() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    let body = r#"{"error":{"code":"rate_limited","message":"x","request_id":"r","details":{"scope":"portfolio_key","limit":100,"window_seconds":60,"retry_after_seconds":1}}}"#;
+    // Within the wait the client accepts: waited out, then served.
+    let mut server = mockito::Server::new();
+    let limited = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(429)
+        .with_header("retry-after", "1")
+        .with_body(body)
+        .expect(1)
+        .create();
+    let served = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_body(EMPTY_PAGE)
+        .expect(1)
+        .create();
+    client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect("served after the wait");
+    limited.assert();
+    served.assert();
+    // Longer than the client accepts: one request, and the scope is in the error.
+    let mut server = mockito::Server::new();
+    let once = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(429)
+        .with_header("retry-after", "600")
+        .with_body(body)
+        .expect(1)
+        .create();
+    let err = client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("too long to wait");
+    once.assert();
+    let api = err.api().expect("API error");
+    assert_eq!(api.status, 429);
+    assert_eq!(api.meta.retry_after, Some(600));
+    let details = api
+        .body
+        .as_ref()
+        .and_then(|b| b.details.as_ref())
+        .expect("details");
+    assert_eq!(details["scope"], "portfolio_key");
+}
+
+#[test]
+fn a_portfolio_key_is_sent_whole_and_never_shown() {
+    let server = mockito::Server::new();
+    let c = tenant_client(&server, TENANT_A);
+    let shown = format!("{c:?}");
+    let secret = PORTFOLIO_KEY.rsplit('_').next().expect("secret part");
+    assert!(
+        !shown.contains(secret) && !shown.contains(PORTFOLIO_KEY),
+        "{shown}"
+    );
+    let builder = Client::builder(
+        server.url().parse().expect("url"),
+        SecretString::from(PORTFOLIO_KEY),
+    );
+    let shown = format!("{builder:?}");
+    assert!(!shown.contains(secret), "{shown}");
+}
+
+// Review follow-ups: the echo is checked on every operation, on every attempt, and only on success.
+
+fn tenant_client_retrying(server: &mockito::Server, tenant: &str) -> Client {
+    Client::builder(
+        server.url().parse().expect("url"),
+        SecretString::from(PORTFOLIO_KEY),
+    )
+    .tenant(tenant)
+    .expect("a UUID")
+    .transient_retries(2, Duration::from_millis(1))
+    .rate_limit_retries(1, Duration::from_secs(5))
+    .build()
+    .expect("client")
+}
+
+#[test]
+fn every_single_item_operation_checks_the_echo() {
+    let mut server = mockito::Server::new();
+    let any = server
+        .mock("GET", mockito::Matcher::Any)
+        .match_header("x-hs-tenant", TENANT_A)
+        .with_header("x-hs-tenant", TENANT_B)
+        .with_body("{}")
+        .expect(5)
+        .create();
+    let c = tenant_client(&server, TENANT_A);
+    fn refused<T>(r: Result<T, Error>) -> bool {
+        matches!(r, Err(Error::TenantMismatch { .. }))
+    }
+    assert!(refused(c.get_vendor("v1")));
+    assert!(refused(c.get_alert("a1")));
+    assert!(refused(c.get_risk("r1")));
+    assert!(refused(c.get_evidence("e1")));
+    assert!(refused(c.get_framework_posture("nis2")));
+    any.assert();
+}
+
+#[test]
+fn an_answer_after_a_retry_is_checked_too() {
+    // A 503 and then a 200 that confirms nothing, or another tenant: refused in both cases.
+    for echo in [None, Some(TENANT_B)] {
+        let mut server = mockito::Server::new();
+        let unavailable = server
+            .mock("GET", "/v1/vendors")
+            .with_status(503)
+            .expect(1)
+            .create();
+        let mut served = server.mock("GET", "/v1/vendors").with_body(EMPTY_PAGE);
+        if let Some(echo) = echo {
+            served = served.with_header("x-hs-tenant", echo);
+        }
+        let served = served.expect(1).create();
+        let err = tenant_client_retrying(&server, TENANT_A)
+            .list_vendors(&ListVendorsParams::default())
+            .expect_err("unconfirmed answer after a retry");
+        assert!(
+            matches!(err, Error::TenantMismatch { .. }),
+            "{echo:?}: {err:?}"
+        );
+        unavailable.assert();
+        served.assert();
+    }
+    // The same after a 429 that is waited out.
+    for echo in [None, Some(TENANT_B)] {
+        let mut server = mockito::Server::new();
+        let limited = server
+            .mock("GET", "/v1/vendors")
+            .with_status(429)
+            .with_header("retry-after", "1")
+            .expect(1)
+            .create();
+        let mut served = server.mock("GET", "/v1/vendors").with_body(EMPTY_PAGE);
+        if let Some(echo) = echo {
+            served = served.with_header("x-hs-tenant", echo);
+        }
+        let served = served.expect(1).create();
+        let err = tenant_client_retrying(&server, TENANT_A)
+            .list_vendors(&ListVendorsParams::default())
+            .expect_err("unconfirmed answer after a wait");
+        assert!(
+            matches!(err, Error::TenantMismatch { .. }),
+            "{echo:?}: {err:?}"
+        );
+        limited.assert();
+        served.assert();
+    }
+    // A confirmed answer after a retry is served.
+    let mut server = mockito::Server::new();
+    server.mock("GET", "/v1/vendors").with_status(503).create();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_header("x-hs-tenant", TENANT_A)
+        .with_body(EMPTY_PAGE)
+        .create();
+    tenant_client_retrying(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect("confirmed after a retry");
+}
+
+#[test]
+fn a_redirect_on_a_scoped_client_is_an_error_and_the_target_gets_nothing() {
+    let mut server = mockito::Server::new();
+    let mut elsewhere = mockito::Server::new();
+    let never = elsewhere
+        .mock("GET", mockito::Matcher::Any)
+        .expect(0)
+        .create();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_header("x-hs-tenant", TENANT_A)
+        .with_status(302)
+        .with_header("location", &format!("{}/steal", elsewhere.url()))
+        .with_header("x-hs-tenant", TENANT_A)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("redirect");
+    assert_eq!(err.api().map(|a| a.status), Some(302), "{err:?}");
+    never.assert();
+}
+
+#[test]
+fn only_a_decodable_success_is_one_even_with_the_right_echo() {
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(204)
+        .with_header("x-hs-tenant", TENANT_A)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("no body");
+    assert!(matches!(err, Error::Decode { .. }), "{err:?}");
+
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(304)
+        .with_header("x-hs-tenant", TENANT_A)
+        .create();
+    let err = tenant_client(&server, TENANT_A)
+        .list_vendors(&ListVendorsParams::default())
+        .expect_err("not modified is not data");
+    assert_eq!(err.api().map(|a| a.status), Some(304), "{err:?}");
+}
+
+#[test]
+fn the_listing_is_unscoped_by_its_operation_and_the_data_operations_are_scoped() {
+    use hodeishield_api::v1::operations;
+    let listing = operations::LIST_PORTFOLIO_TENANTS;
+    assert_eq!(listing.method, "GET");
+    assert_eq!(listing.path, "/v1/portfolio/tenants");
+    assert_eq!(listing.scopes, ["portfolio:read"]);
+    assert!(!listing.tenant_scoped);
+    let data: Vec<_> = operations::ALL
+        .iter()
+        .filter(|op| op.id != listing.id)
+        .collect();
+    assert!(data.len() >= 11);
+    assert!(data.iter().all(|op| op.tenant_scoped));
+}
+
+#[test]
+fn a_404_or_405_with_a_portfolio_code_is_the_apis_own_error() {
+    use hodeishield_api::portfolio::ListTenantsParams;
+    for (status, code) in [
+        (404_usize, "TENANT_NOT_FOUND"),
+        (405, "TENANT_SELECTOR_NOT_SUPPORTED"),
+        (404, "TENANT_SOMETHING_NEW"),
+    ] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .with_status(status)
+            .with_body(format!(
+                r#"{{"error":{{"code":"not_found","message":"x","request_id":"r","details":{{"code":"{code}"}}}}}}"#
+            ))
+            .create();
+        let err = client(&server)
+            .list_tenants(&ListTenantsParams::default())
+            .expect_err("API error");
+        assert_eq!(
+            err.api().map(|a| a.status),
+            Some(u16::try_from(status).expect("status")),
+            "{status} {code}: {err:?}"
+        );
+    }
+    // An unrelated code, or none, still means the route is not there.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"x","request_id":"r","details":{"code":"SOMETHING_ELSE"}}}"#)
+        .create();
+    let err = client(&server)
+        .list_tenants(&ListTenantsParams::default())
+        .expect_err("no route");
+    assert!(
+        matches!(err, Error::PortfolioNotOffered { status: 404 }),
+        "{err:?}"
+    );
+}
diff --git a/crates/hodeishield-cli/src/auth/loopback.rs b/crates/hodeishield-cli/src/auth/loopback.rs
index d0a14be..c34dcd0 100644
--- a/crates/hodeishield-cli/src/auth/loopback.rs
+++ b/crates/hodeishield-cli/src/auth/loopback.rs
@@ -15,10 +15,33 @@ use std::time::{Duration, Instant};
 
 const CALLBACK_PATH: &str = "/callback";
 
+/// The most a single read may wait for the next bytes of a request.
+const READ_TIMEOUT: Duration = Duration::from_secs(5);
+/// The most a single connection may take to deliver its whole request head. The listener serves one
+/// connection at a time, so this bounds how long a stalled or trickling client can hold it.
+const CONNECTION_DEADLINE: Duration = Duration::from_secs(10);
+
+/// How long the listener waits on one connection. Injectable so tests need not sleep for seconds.
+#[derive(Debug, Clone, Copy)]
+struct Limits {
+    read: Duration,
+    connection: Duration,
+}
+
+impl Default for Limits {
+    fn default() -> Self {
+        Self {
+            read: READ_TIMEOUT,
+            connection: CONNECTION_DEADLINE,
+        }
+    }
+}
+
 #[derive(Debug)]
 pub struct Loopback {
     listener: TcpListener,
     redirect_uri: String,
+    limits: Limits,
 }
 
 /// What the browser brought back.
@@ -40,6 +63,7 @@ impl Loopback {
         Ok(Self {
             listener,
             redirect_uri: format!("http://127.0.0.1:{port}{CALLBACK_PATH}"),
+            limits: Limits::default(),
         })
     }
 
@@ -59,38 +83,79 @@ impl Loopback {
     ) -> Result<Callback> {
         let deadline = Instant::now() + timeout;
         loop {
+            // Checked before every accept, not only when idle: a client that keeps connecting keeps
+            // the queue full, and must not be able to postpone the timeout.
+            let left = deadline.saturating_duration_since(Instant::now());
+            if left.is_zero() {
+                return Err(timed_out());
+            }
             match self.listener.accept() {
                 Ok((stream, _)) => {
-                    if let Some(result) = handle(stream, state, issuer, require_iss) {
+                    let request = Request {
+                        state,
+                        issuer,
+                        require_iss,
+                        limits: self.limits,
+                        deadline,
+                    };
+                    if let Some(result) = handle(stream, &request) {
                         return result;
                     }
                 }
                 Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
-                    if Instant::now() >= deadline {
-                        return Err(Failure::new(
-                            Kind::NotAuthenticated,
-                            "Timed out waiting for the browser to finish signing in.",
-                        )
-                        .hint("Run `hodeishield login` again, or `hodeishield login --device`."));
-                    }
-                    std::thread::sleep(Duration::from_millis(100));
+                    std::thread::sleep(Duration::from_millis(100).min(left));
                 }
+                // A client that reset before we accepted it (reported on macOS, the BSDs and
+                // Windows) is not the end of the sign-in.
+                Err(e) if is_aborted_connection(e.kind()) => {}
                 Err(e) => return Err(e.into()),
             }
         }
     }
 }
 
-/// `None`: not the callback, keep waiting. `Some`: the sign-in ended, one way or another.
-fn handle(
-    mut stream: TcpStream,
-    state: &str,
-    issuer: &str,
+fn timed_out() -> Failure {
+    Failure::new(
+        Kind::NotAuthenticated,
+        "Timed out waiting for the browser to finish signing in.",
+    )
+    .hint("Run `hodeishield login` again, or `hodeishield login --device`.")
+}
+
+fn is_aborted_connection(kind: std::io::ErrorKind) -> bool {
+    matches!(
+        kind,
+        std::io::ErrorKind::ConnectionAborted | std::io::ErrorKind::ConnectionReset
+    )
+}
+
+/// What `handle` checks a connection against.
+struct Request<'a> {
+    state: &'a str,
+    issuer: &'a str,
     require_iss: bool,
-) -> Option<Result<Callback>> {
+    limits: Limits,
+    /// When the whole sign-in gives up; no connection may outlive it.
+    deadline: Instant,
+}
+
+/// `None`: not the callback, keep waiting. `Some`: the sign-in ended, one way or another.
+fn handle(mut stream: TcpStream, request: &Request<'_>) -> Option<Result<Callback>> {
+    let Request {
+        state,
+        issuer,
+        require_iss,
+        ..
+    } = *request;
     let _ = stream.set_nonblocking(false);
-    let _ = stream.set_read_timeout(Some(Duration::from_secs(5)));
-    let target = read_request_target(&mut stream)?;
+    // A client that never reads the answer must not hold the listener either.
+    let _ = stream.set_write_timeout(Some(request.limits.read));
+    let connection_deadline = Instant::now() + request.limits.connection;
+    let target = read_request_target(
+        &mut stream,
+        request.limits.read,
+        connection_deadline.min(request.deadline),
+    )?;
     let (path, query) = target.split_once('?').unwrap_or((target.as_str(), ""));
     if path != CALLBACK_PATH {
         respond(&mut stream, "404 Not Found", "Not found.");
@@ -177,10 +242,23 @@ fn handle(
 }
 
 /// The request target of a `GET` request line, or `None` for anything else.
-fn read_request_target(stream: &mut TcpStream) -> Option<String> {
+///
+/// Every read waits for at most `read_timeout` and never past `deadline`, so a client that sends a
+/// byte now and then cannot hold the connection beyond it.
+fn read_request_target(
+    stream: &mut TcpStream,
+    read_timeout: Duration,
+    deadline: Instant,
+) -> Option<String> {
     let mut buffer = Vec::with_capacity(1024);
     let mut chunk = [0_u8; 1024];
     while !buffer.windows(4).any(|w| w == b"\r\n\r\n") && buffer.len() < 16 * 1024 {
+        let left = deadline.saturating_duration_since(Instant::now());
+        let wait = read_timeout.min(left);
+        // A zero timeout is an error for the socket; out of time means stop reading.
+        if wait.is_zero() || stream.set_read_timeout(Some(wait)).is_err() {
+            break;
+        }
         match stream.read(&mut chunk) {
             Ok(0) | Err(_) => break,
             Ok(n) => buffer.extend_from_slice(&chunk[..n]),
@@ -302,4 +380,124 @@ mod tests {
         ]);
         assert!(result.expect_err("denied").message.contains("denied"));
     }
+
+    /// Connects and sends one byte every `pause`, `count` times, stopping when the server hangs up.
+    fn trickle(uri: &str, pause: Duration, count: u32) -> std::thread::JoinHandle<()> {
+        let addr = uri
+            .trim_start_matches("http://")
+            .split('/')
+            .next()
+            .expect("host")
+            .to_owned();
+        let mut stream = TcpStream::connect(addr).expect("connect");
+        std::thread::spawn(move || {
+            for _ in 0..count {
+                if stream.write_all(b"x").is_err() {
+                    return;
+                }
+                std::thread::sleep(pause);
+            }
+        })
+    }
+
+    #[test]
+    fn an_aborted_connection_does_not_end_the_sign_in() {
+        use std::io::ErrorKind::*;
+        assert!(is_aborted_connection(ConnectionAborted));
+        assert!(is_aborted_connection(ConnectionReset));
+        assert!(!is_aborted_connection(WouldBlock));
+        assert!(!is_aborted_connection(PermissionDenied));
+    }
+
+    #[test]
+    fn the_overall_timeout_holds_while_clients_keep_connecting() {
+        let loopback = Loopback::bind().expect("bind");
+        let uri = loopback.redirect_uri().to_owned();
+        let addr = uri
+            .trim_start_matches("http://")
+            .split('/')
+            .next()
+            .expect("host")
+            .to_owned();
+        let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let flag = stop.clone();
+        let churn = std::thread::spawn(move || {
+            while !flag.load(std::sync::atomic::Ordering::Relaxed) {
+                // Connect and close at once, so there is always something waiting to be accepted.
+                drop(TcpStream::connect(&addr));
+            }
+        });
+        let started = Instant::now();
+        let result = loopback.wait(
+            "expected-state",
+            "https://app.example.test",
+            false,
+            Duration::from_millis(400),
+        );
+        let elapsed = started.elapsed();
+        stop.store(true, std::sync::atomic::Ordering::Relaxed);
+        churn.join().expect("churn");
+        assert!(
+            result.expect_err("timeout").message.contains("Timed out"),
+            "timed out"
+        );
+        assert!(elapsed < Duration::from_secs(3), "{elapsed:?}");
+    }
+
+    fn quick(read_ms: u64, connection_ms: u64) -> Limits {
+        Limits {
+            read: Duration::from_millis(read_ms),
+            connection: Duration::from_millis(connection_ms),
+        }
+    }
+
+    #[test]
+    fn a_trickling_client_is_cut_off_and_the_real_callback_still_gets_in() {
+        let mut loopback = Loopback::bind().expect("bind");
+        // Each byte arrives well inside the read timeout, so only the connection deadline stops it.
+        loopback.limits = quick(1_000, 300);
+        let uri = loopback.redirect_uri().to_owned();
+        let slow = trickle(&uri, Duration::from_millis(50), 100);
+        let started = Instant::now();
+        let real = {
+            let uri = uri.clone();
+            std::thread::spawn(move || hit(&uri, "/callback?code=abc&state=expected-state"))
+        };
+        let result = loopback.wait(
+            "expected-state",
+            "https://app.example.test",
+            false,
+            Duration::from_secs(10),
+        );
+        assert!(
+            started.elapsed() < Duration::from_secs(3),
+            "{:?}",
+            started.elapsed()
+        );
+        assert_eq!(result.expect("real callback").code.expose_secret(), "abc");
+        assert!(real.join().expect("client").starts_with("HTTP/1.1 200"));
+        slow.join().expect("trickler");
+    }
+
+    #[test]
+    fn the_overall_timeout_holds_while_a_trickling_client_is_connected() {
+        let mut loopback = Loopback::bind().expect("bind");
+        loopback.limits = quick(1_000, 5_000);
+        let uri = loopback.redirect_uri().to_owned();
+        let slow = trickle(&uri, Duration::from_millis(50), 100);
+        let started = Instant::now();
+        let result = loopback.wait(
+            "expected-state",
+            "https://app.example.test",
+            false,
+            Duration::from_millis(400),
+        );
+        let elapsed = started.elapsed();
+        assert!(
+            result.expect_err("timeout").message.contains("Timed out"),
+            "timed out"
+        );
+        assert!(elapsed < Duration::from_secs(2), "{elapsed:?}");
+        slow.join().expect("trickler");
+    }
 }
diff --git a/crates/hodeishield-cli/src/auth/mod.rs b/crates/hodeishield-cli/src/auth/mod.rs
index b6790d0..53df31b 100644
--- a/crates/hodeishield-cli/src/auth/mod.rs
+++ b/crates/hodeishield-cli/src/auth/mod.rs
@@ -33,19 +33,34 @@ pub fn api_key_from_env() -> Option<SecretString> {
         .map(SecretString::from)
 }
 
+/// Whether a credential string is a portfolio key (starts with `hsp_`).
+pub fn is_portfolio_key(credential: &SecretString) -> bool {
+    credential.expose_secret().starts_with("hsp_")
+}
+
 /// The credential for an API call: the environment's API key, else the profile's sign-in token,
 /// refreshed if it is about to expire.
 pub fn credential_for_api(
     settings: &Settings,
     store: &dyn TokenStore,
 ) -> Result<(SecretString, CredentialSource)> {
-    if let Some(key) = api_key_from_env() {
+    credential_with(api_key_from_env(), settings, store)
+}
+
+/// [`credential_for_api`] with the environment's API key given, so it can be tested without
+/// touching the process environment. With a key, the store is not read.
+fn credential_with(
+    env_key: Option<SecretString>,
+    settings: &Settings,
+    store: &dyn TokenStore,
+) -> Result<(SecretString, CredentialSource)> {
+    if let Some(key) = env_key {
         return Ok((key, CredentialSource::ApiKey));
     }
     let token = match current_token(settings, store) {
         Ok(Some(token)) => token,
         Ok(None) => return Err(not_signed_in(settings)),
-        Err(failure) => return Err(explain_store_failure(failure, settings)),
+        Err(failure) => return Err(explain_store_failure(failure)),
     };
     // A sign-in token only goes to the API it was obtained for: a changed profile, environment or
     // `--api-url` must not be able to send it elsewhere.
@@ -81,19 +96,30 @@ pub fn not_signed_in(settings: &Settings) -> Failure {
     ))
 }
 
-/// Turns a raw store failure into words about what to do, when the underlying reason is that this
-/// machine has no keychain to sign in to. Any other store failure (a corrupt entry, say) passes
-/// through unchanged: it already says what happened.
-pub fn explain_store_failure(failure: Failure, settings: &Settings) -> Failure {
-    if failure.message.starts_with(store::KEYCHAIN_UNAVAILABLE) {
-        not_signed_in(settings).hint(format!(
-            "Set a tenant API key: export {API_KEY_ENV}=<key>. Signing in is not possible on \
-             this machine: {}.",
-            failure.message
-        ))
+/// Turns a store failure into words about what to do, when the underlying reason is that the
+/// keychain cannot be reached (none on this machine, or not from this session, as over SSH on
+/// Windows): it is "not authenticated" (exit code 3), with a pointer to the API key. Any other
+/// store failure (a corrupt entry, say) passes through unchanged: it already says what happened.
+pub fn explain_store_failure(failure: Failure) -> Failure {
+    let Some(rest) = failure.message.strip_prefix(store::KEYCHAIN_UNAVAILABLE) else {
+        return failure;
+    };
+    let reason = rest.trim_start_matches(':').trim();
+    let detail = if reason.is_empty() {
+        String::new()
     } else {
-        failure
-    }
+        format!(": {reason}")
+    };
+    Failure::new(
+        Kind::NotAuthenticated,
+        format!("The system keychain is not available in this session{detail}"),
+    )
+    .hint(match failure.hint {
+        // Keep what the store said about this platform (allow the Keychain prompt, start a Secret
+        // Service...), then the way out that works in a remote session.
+        Some(platform) => format!("{platform} In remote or automated sessions, set {API_KEY_ENV}."),
+        None => format!("In remote or automated sessions, set {API_KEY_ENV}."),
+    })
 }
 
 /// The profile's sign-in token, refreshed when needed. `None` when not signed in.
@@ -461,4 +487,117 @@ mod tests {
             "the dead token is removed"
         );
     }
+
+    /// A store whose answer is fixed; with `panic_on_use` it proves the store is never touched.
+    struct FixedStore {
+        load_error: std::sync::Mutex<Option<keyring_core::Error>>,
+        panic_on_use: bool,
+    }
+
+    impl TokenStore for FixedStore {
+        fn load(&self, _profile: &str) -> Result<Option<StoredToken>> {
+            assert!(!self.panic_on_use, "the store must not be read");
+            match self.load_error.lock().expect("lock").take() {
+                Some(error) => Err(store::read_failure(error)),
+                None => Ok(None),
+            }
+        }
+        fn save(&self, _: &str, _: &StoredToken) -> Result<()> {
+            unreachable!()
+        }
+        fn delete(&self, _: &str) -> Result<bool> {
+            unreachable!()
+        }
+        fn check_available(&self, _: &str) -> Result<()> {
+            unreachable!()
+        }
+    }
+
+    fn io_error() -> Box<dyn std::error::Error + Send + Sync> {
+        "Windows ERROR_NO_SUCH_LOGON_SESSION".into()
+    }
+
+    fn assert_keychain_unreachable(error: keyring_core::Error) {
+        let store = FixedStore {
+            load_error: std::sync::Mutex::new(Some(error)),
+            panic_on_use: false,
+        };
+        let err = credential_with(None, &settings("https://app.example.test"), &store)
+            .expect_err("no credential");
+        assert_eq!(err.kind, Kind::NotAuthenticated);
+        assert!(
+            err.message
+                .contains("keychain is not available in this session"),
+            "{}",
+            err.message
+        );
+        let hint = err.hint.expect("hint");
+        // The platform's own advice stays, followed by the remote-session one.
+        assert!(
+            hint.starts_with("Sign-in tokens are only kept in the system keychain."),
+            "{hint}"
+        );
+        assert!(
+            hint.ends_with(" In remote or automated sessions, set HODEISHIELD_API_KEY."),
+            "{hint}"
+        );
+    }
+
+    #[test]
+    fn an_unreachable_keychain_is_not_authenticated_not_a_raw_error() {
+        assert_keychain_unreachable(keyring_core::Error::NoStorageAccess(io_error()));
+    }
+
+    #[test]
+    fn a_platform_failure_reading_the_keychain_is_the_same() {
+        assert_keychain_unreachable(keyring_core::Error::PlatformFailure(io_error()));
+    }
+
+    #[test]
+    fn another_store_failure_is_left_as_it_is() {
+        let failure = explain_store_failure(Failure::general("system keychain: broken entry"));
+        assert_eq!(failure.kind, Kind::General);
+        assert_eq!(failure.message, "system keychain: broken entry");
+    }
+
+    #[test]
+    fn a_failure_without_a_platform_hint_gets_only_the_api_key_one() {
+        let failure = explain_store_failure(Failure::general(format!(
+            "{}: no Secret Service",
+            store::KEYCHAIN_UNAVAILABLE
+        )));
+        assert_eq!(failure.kind, Kind::NotAuthenticated);
+        assert_eq!(
+            failure.hint.as_deref(),
+            Some("In remote or automated sessions, set HODEISHIELD_API_KEY.")
+        );
+    }
+
+    #[test]
+    fn another_keyring_error_stays_a_general_keychain_failure() {
+        let failure = store::read_failure(keyring_core::Error::BadEncoding(vec![0xff]));
+        assert_eq!(failure.kind, Kind::General);
+        assert!(
+            failure.message.starts_with("system keychain:"),
+            "{}",
+            failure.message
+        );
+        assert_eq!(explain_store_failure(failure).kind, Kind::General);
+    }
+
+    #[test]
+    fn an_api_key_in_the_environment_never_touches_the_store() {
+        let store = FixedStore {
+            load_error: std::sync::Mutex::new(None),
+            panic_on_use: true,
+        };
+        let (key, source) = credential_with(
+            Some(SecretString::from("key_1")),
+            &settings("https://app.example.test"),
+            &store,
+        )
+        .expect("key used");
+        assert_eq!(key.expose_secret(), "key_1");
+        assert!(matches!(source, CredentialSource::ApiKey));
+    }
 }
diff --git a/crates/hodeishield-cli/src/auth/oauth.rs b/crates/hodeishield-cli/src/auth/oauth.rs
index 6d620ee..0628c5f 100644
--- a/crates/hodeishield-cli/src/auth/oauth.rs
+++ b/crates/hodeishield-cli/src/auth/oauth.rs
@@ -10,6 +10,7 @@
 use crate::failure::{Failure, Kind, Result, error_chain};
 use base64::Engine as _;
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use hodeishield_api::v1::operations;
 use secrecy::{ExposeSecret, SecretString};
 use serde::Deserialize;
 use sha2::{Digest, Sha256};
@@ -46,8 +47,11 @@ const OFFLINE_ACCESS: &str = "offline_access";
 pub fn default_scopes(metadata: &Metadata) -> Vec<String> {
     let offered = metadata.scopes_supported.as_deref();
     let mut scopes: Vec<String> = Vec::new();
-    let needed = hodeishield_api::v1::operations::ALL
+    let needed = operations::ALL
         .iter()
+        // The tenant listing answers a portfolio key only, never a sign-in: its scope is not
+        // asked for.
+        .filter(|operation| operation.id != operations::LIST_PORTFOLIO_TENANTS.id)
         .flat_map(|operation| operation.scopes.iter().copied())
         .chain([OFFLINE_ACCESS]);
     for scope in needed {
diff --git a/crates/hodeishield-cli/src/auth/store.rs b/crates/hodeishield-cli/src/auth/store.rs
index e18d83a..78edfb6 100644
--- a/crates/hodeishield-cli/src/auth/store.rs
+++ b/crates/hodeishield-cli/src/auth/store.rs
@@ -89,6 +89,9 @@ pub trait TokenStore {
     fn save(&self, profile: &str, token: &StoredToken) -> Result<()>;
     /// Whether there was something to delete.
     fn delete(&self, profile: &str) -> Result<bool>;
+    /// Whether tokens can be kept for this profile, without writing anything. Sign-in checks it
+    /// before it asks the person to approve anything.
+    fn check_available(&self, profile: &str) -> Result<()>;
 }
 
 /// The system keychain.
@@ -101,13 +104,27 @@ fn ensure_store() -> Result<()> {
     STORE_READY
         .get_or_init(|| native_store().map(keyring_core::set_default_store))
         .clone()
-        .map_err(|reason| {
-            Failure::general(format!("{KEYCHAIN_UNAVAILABLE}: {reason}")).hint(
-                "Sign-in tokens are only kept in the system keychain. On Linux, start a Secret \
-                 Service (GNOME Keyring or KWallet); on a server without one, use a tenant API key \
-                 in HODEISHIELD_API_KEY instead.",
-            )
-        })
+        .map_err(|reason| unavailable(&reason))
+}
+
+fn unavailable(reason: &str) -> Failure {
+    Failure::general(format!("{KEYCHAIN_UNAVAILABLE}: {reason}")).hint(unavailable_hint())
+}
+
+/// What to do about a missing keychain, for the platform this build runs on.
+fn unavailable_hint() -> &'static str {
+    if cfg!(target_os = "macos") {
+        "Sign-in tokens are only kept in the system keychain. Allow access when the Keychain \
+         prompt appears (or in Keychain Access), or use a tenant API key in HODEISHIELD_API_KEY \
+         instead."
+    } else if cfg!(windows) {
+        "Sign-in tokens are only kept in the system keychain. Check that Windows Credential \
+         Manager is available, or use a tenant API key in HODEISHIELD_API_KEY instead."
+    } else {
+        "Sign-in tokens are only kept in the system keychain. Start a Secret Service \
+         (GNOME Keyring or KWallet); on a server without one, use a tenant API key in \
+         HODEISHIELD_API_KEY instead."
+    }
 }
 
 #[cfg(target_os = "macos")]
@@ -146,6 +163,19 @@ fn keychain_failure(error: keyring_core::Error) -> Failure {
     Failure::general(format!("system keychain: {error}"))
 }
 
+/// The failure for a keychain read that did not find an entry. When the platform store cannot be
+/// reached from this session (Windows ERROR_NO_SUCH_LOGON_SESSION over SSH, no Secret Service on
+/// Linux), it is worded as an unavailable keychain, which `explain_store_failure` turns into "not
+/// authenticated"; anything else is a plain keychain failure.
+pub(crate) fn read_failure(error: keyring_core::Error) -> Failure {
+    match error {
+        keyring_core::Error::PlatformFailure(_) | keyring_core::Error::NoStorageAccess(_) => {
+            unavailable(&error.to_string())
+        }
+        other => keychain_failure(other),
+    }
+}
+
 impl TokenStore for Keychain {
     fn load(&self, profile: &str) -> Result<Option<StoredToken>> {
         let entry = entry(profile)?;
@@ -158,7 +188,7 @@ impl TokenStore for Keychain {
                 Ok(Some(StoredToken::from_payload(payload)))
             }
             Err(keyring_core::Error::NoEntry) => Ok(None),
-            Err(e) => Err(keychain_failure(e)),
+            Err(e) => Err(read_failure(e)),
         }
     }
 
@@ -177,6 +207,25 @@ impl TokenStore for Keychain {
             Err(e) => Err(keychain_failure(e)),
         }
     }
+
+    /// Reads the profile's entry, which proves the backend answers without writing a secret: an
+    /// entry that does not exist, or that cannot be decoded, still means the keychain works.
+    ///
+    /// Reading the stored entry and discarding it is deliberate: keyring-core 1.0 has no cheaper
+    /// probe that works everywhere. `get_attributes` is not implemented on macOS, and treating
+    /// `NotSupportedByStore` as unavailable would lock macOS users out. The value is dropped
+    /// at once; `zeroize` is not a direct dependency and is not added for this.
+    fn check_available(&self, profile: &str) -> Result<()> {
+        match entry(profile)?.get_password() {
+            Err(
+                e @ (keyring_core::Error::PlatformFailure(_)
+                | keyring_core::Error::NoStorageAccess(_)
+                | keyring_core::Error::NoDefaultStore
+                | keyring_core::Error::NotSupportedByStore(_)),
+            ) => Err(unavailable(&e.to_string())),
+            _ => Ok(()),
+        }
+    }
 }
 
 /// In-memory store for tests.
@@ -210,6 +259,10 @@ impl TokenStore for MemoryStore {
             .remove(profile)
             .is_some())
     }
+
+    fn check_available(&self, _profile: &str) -> Result<()> {
+        Ok(())
+    }
 }
 
 #[cfg(test)]
diff --git a/crates/hodeishield-cli/src/cli.rs b/crates/hodeishield-cli/src/cli.rs
index 3adf6e7..9f52e3d 100644
--- a/crates/hodeishield-cli/src/cli.rs
+++ b/crates/hodeishield-cli/src/cli.rs
@@ -3,9 +3,11 @@
 
 //! Command-line surface.
 
+use crate::filters;
 use clap::builder::{PossibleValuesParser, TypedValueParser};
 use clap::{Args, CommandFactory, Parser, Subcommand};
 use hodeishield_api::ParseEnumError;
+use hodeishield_api::v1::operations;
 use hodeishield_api::v1::{
     AlertSort, AlertStatus, BusinessCriticality, ComplianceControlSort, EndpointSort,
     EndpointStatus, EvidenceSort, Order, RiskSort, VendorSort,
@@ -14,12 +16,17 @@ use std::str::FromStr;
 
 const AFTER_HELP: &str = "\
 Credentials:
-  HODEISHIELD_API_KEY   A tenant API key. When set, it is used for every API call.
+  HODEISHIELD_API_KEY   A tenant API key, or an MSSP portfolio key (hsp_…). When set, it is used for every API call.
   hodeishield login     Otherwise, sign in to the app; the token is kept in the system keychain.
 
+Several client tenants (portfolio credential):
+  hodeishield tenants list                       The client tenants you may read.
+  hodeishield --tenant <slug|id> vendors list    One client.
+  hodeishield --all-tenants vendors list         Every client, with a tenant column.
+
 Exit codes:
   0 ok · 1 error · 2 usage · 3 not authenticated · 4 missing scope · 5 not found
-  6 rate limited · 7 API unreachable or failing · 8 tenant licence not in force";
+  6 rate limited · 7 API unreachable, failing or without portfolio access · 8 tenant licence not in force";
 
 /// Read-only command-line client for HodeiShield.
 ///
@@ -56,6 +63,27 @@ pub struct Cli {
     #[arg(short, long, global = true, help_heading = "Global options")]
     pub verbose: bool,
 
+    /// Read this client tenant (its slug or id) instead of the credential's own. Needs a
+    /// portfolio credential; see `hodeishield tenants list`.
+    #[arg(
+        long,
+        global = true,
+        help_heading = "Client selection (MSSP)",
+        value_name = "SLUG|ID",
+        conflicts_with = "all_tenants"
+    )]
+    pub tenant: Option<String>,
+
+    /// On a list command, read every client tenant of the portfolio and add a tenant column (or
+    /// `tenant_*` fields) to each row. Fetches every page of each tenant.
+    #[arg(
+        long,
+        global = true,
+        help_heading = "Client selection (MSSP)",
+        conflicts_with = "tenant"
+    )]
+    pub all_tenants: bool,
+
     #[command(subcommand)]
     pub command: Command,
 }
@@ -80,6 +108,9 @@ pub enum Command {
     /// Enrolled endpoint agents.
     #[command(subcommand)]
     Endpoints(EndpointsCommand),
+    /// Client tenants a portfolio (MSSP) credential may read.
+    #[command(subcommand)]
+    Tenants(TenantsCommand),
     /// Sign in to the app (browser, or --device without one).
     #[command(long_about = LOGIN_ABOUT)]
     Login(LoginArgs),
@@ -132,11 +163,74 @@ impl Cli {
                 )
                 .exit();
         }
+        if let Some(message) = cli.selection_error() {
+            Self::command()
+                .error(clap::error::ErrorKind::ArgumentConflict, message)
+                .exit();
+        }
         cli
     }
+
+    /// Why the client selection cannot go with this command, if it cannot. It is refused rather
+    /// than ignored: a command that does not read the selected client must not look as if it did.
+    fn selection_error(&self) -> Option<&'static str> {
+        if self.tenant.is_some() && self.all_tenants {
+            return Some("the argument '--tenant' cannot be used with '--all-tenants'");
+        }
+        if self.tenant.is_none() && !self.all_tenants {
+            return None;
+        }
+        if !self.command.reads_tenant_data() {
+            return Some(
+                "'--tenant' and '--all-tenants' only apply to the commands that read tenant data",
+            );
+        }
+        if self.all_tenants {
+            match self.command.paging() {
+                None => {
+                    return Some(
+                        "'--all-tenants' applies to list commands; use '--tenant' to read one \
+                         client",
+                    );
+                }
+                Some(paging) if paging.page.is_some() => {
+                    return Some(
+                        "the argument '--all-tenants' cannot be used with '--page': it fetches \
+                         every page of each tenant",
+                    );
+                }
+                Some(_) => {}
+            }
+        }
+        None
+    }
+}
+
+impl Cli {
+    /// Whether this invocation prints something a program reads: `--json`, `--csv` or the
+    /// completion script. Nothing but that output may be added to such a run.
+    #[must_use]
+    pub(crate) fn prints_for_programs(&self) -> bool {
+        self.json
+            || matches!(self.command, Command::Completions { .. })
+            || self.command.paging().is_some_and(|paging| paging.csv)
+    }
 }
 
 impl Command {
+    /// The commands that read a tenant's data, and so can read a selected client's.
+    fn reads_tenant_data(&self) -> bool {
+        matches!(
+            self,
+            Self::Vendors(_)
+                | Self::Alerts(_)
+                | Self::Risks(_)
+                | Self::Compliance(_)
+                | Self::Evidence(_)
+                | Self::Endpoints(_)
+        )
+    }
+
     /// The paging options, for the commands that list.
     fn paging(&self) -> Option<&Paging> {
         match self {
@@ -146,6 +240,7 @@ impl Command {
             Self::Compliance(ComplianceCommand::Controls(list)) => Some(&list.paging),
             Self::Evidence(EvidenceCommand::List(list)) => Some(&list.paging),
             Self::Endpoints(EndpointsCommand::List(list)) => Some(&list.paging),
+            Self::Tenants(TenantsCommand::List(list)) => Some(&list.paging),
             _ => None,
         }
     }
@@ -179,6 +274,18 @@ where
     PossibleValuesParser::new(values).try_map(|value| T::from_str(&value))
 }
 
+#[derive(Debug, Subcommand)]
+pub enum TenantsCommand {
+    /// List the client tenants this credential may read.
+    List(TenantsList),
+}
+
+#[derive(Debug, Args)]
+pub struct TenantsList {
+    #[command(flatten)]
+    pub paging: Paging,
+}
+
 #[derive(Debug, Subcommand)]
 pub enum VendorsCommand {
     /// List vendors.
@@ -228,7 +335,7 @@ pub struct AlertsList {
     #[arg(long, value_parser = choice::<AlertStatus>(AlertStatus::VALUES))]
     pub status: Option<AlertStatus>,
     /// Exact severity.
-    #[arg(long)]
+    #[arg(long, help = filters::help("Exact severity.", &operations::LIST_ALERTS, "severity"))]
     pub severity: Option<String>,
     /// Only alerts about this vendor id.
     #[arg(long)]
@@ -257,10 +364,10 @@ pub enum RisksCommand {
 #[derive(Debug, Args)]
 pub struct RisksList {
     /// Exact status.
-    #[arg(long)]
+    #[arg(long, help = filters::help("Exact status.", &operations::LIST_RISKS, "status"))]
     pub status: Option<String>,
     /// Exact risk domain.
-    #[arg(long)]
+    #[arg(long, help = filters::help("Exact risk domain.", &operations::LIST_RISKS, "domain"))]
     pub domain: Option<String>,
     /// Only risks linked to this vendor id.
     #[arg(long)]
@@ -292,7 +399,10 @@ pub struct ControlsList {
     #[arg(long, short)]
     pub framework: String,
     /// Exact control status.
-    #[arg(long)]
+    #[arg(
+        long,
+        help = filters::help("Exact control status.", &operations::LIST_COMPLIANCE_CONTROLS, "status")
+    )]
     pub status: Option<String>,
     /// Field to order by.
     #[arg(long, value_parser = choice::<ComplianceControlSort>(ComplianceControlSort::VALUES))]
diff --git a/crates/hodeishield-cli/src/commands/config.rs b/crates/hodeishield-cli/src/commands/config.rs
index f1ccb73..116e29b 100644
--- a/crates/hodeishield-cli/src/commands/config.rs
+++ b/crates/hodeishield-cli/src/commands/config.rs
@@ -20,6 +20,7 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
         }
         ConfigCommand::Show => {
             let settings = ctx.settings()?;
+            let update_check = config::load(&path)?.update_check.unwrap_or(true);
             let value = json!({
                 "config_file": settings.config_path.display().to_string(),
                 "profile": settings.profile,
@@ -27,6 +28,7 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
                 "app_url": settings.app_url.as_str(),
                 "oauth_client_id": settings.oauth_client_id,
                 "oauth_scopes": settings.oauth_scopes,
+                "update_check": update_check,
             });
             if ctx.json {
                 return Ok(print_json(out, &value)?);
@@ -40,8 +42,16 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
             writeln!(out, "app_url          {}", settings.app_url)?;
             writeln!(out, "oauth_client_id  {}", settings.oauth_client_id)?;
             writeln!(out, "oauth_scopes     {scopes}")?;
+            writeln!(out, "update_check     {update_check}")?;
             Ok(())
         }
+        ConfigCommand::Set { key, value } if key == config::UPDATE_CHECK => {
+            edit_global(&path, |file| file.set_update_check(&value))
+        }
+        ConfigCommand::Unset { key } if key == config::UPDATE_CHECK => edit_global(&path, |file| {
+            file.update_check = None;
+            Ok(())
+        }),
         ConfigCommand::Set { key, value } => edit(ctx, &path, |profile| profile.set(&key, &value)),
         ConfigCommand::Unset { key } => edit(ctx, &path, |profile| profile.unset(&key)),
         ConfigCommand::Use { name } => {
@@ -61,6 +71,18 @@ pub fn run(ctx: &Context, command: ConfigCommand, out: &mut dyn Write) -> Result
     }
 }
 
+/// Changes a setting that belongs to the file, not to a profile.
+fn edit_global(
+    path: &std::path::Path,
+    change: impl FnOnce(&mut config::ConfigFile) -> Result<()>,
+) -> Result<()> {
+    let mut file = config::load(path)?;
+    change(&mut file)?;
+    config::save(path, &file)?;
+    eprintln!("Saved in {}.", path.display());
+    Ok(())
+}
+
 /// Changes the profile named by `--profile` (or the default one), creating it if needed.
 fn edit(
     ctx: &Context,
diff --git a/crates/hodeishield-cli/src/commands/mod.rs b/crates/hodeishield-cli/src/commands/mod.rs
index ad117b9..0174e5e 100644
--- a/crates/hodeishield-cli/src/commands/mod.rs
+++ b/crates/hodeishield-cli/src/commands/mod.rs
@@ -6,20 +6,26 @@
 mod config;
 mod resources;
 mod session;
+mod tenants;
 
 use crate::auth::{self, TokenStore};
 use crate::cli::{Cli, Command};
 use crate::config::{Overrides, Settings};
 use crate::failure::{ApiContext, CredentialSource, Result, from_api};
 use hodeishield_api::Client;
+use std::cell::Cell;
 use std::io::Write;
 use std::sync::Arc;
+use tenants::Selection;
 
 pub struct Context {
     pub overrides: Overrides,
     pub json: bool,
     pub verbose: bool,
+    pub selection: Selection,
     pub store: Arc<dyn TokenStore + Send + Sync>,
+    /// Cached information about whether the credential is a portfolio key, set on first API call.
+    is_portfolio_key: Cell<Option<bool>>,
 }
 
 impl Context {
@@ -27,15 +33,36 @@ impl Context {
         crate::config::resolve(&self.overrides)
     }
 
-    /// A `/v1` client with the credential in effect.
-    pub fn api(&self, settings: &Settings) -> Result<(Client, CredentialSource)> {
+    /// A `/v1` client with the credential in effect, reading `tenant` (a client tenant's id) when
+    /// one is given and the credential's own tenant otherwise.
+    pub fn api(
+        &self,
+        settings: &Settings,
+        tenant: Option<&str>,
+    ) -> Result<(Client, CredentialSource)> {
         let (credential, source) = auth::credential_for_api(settings, self.store.as_ref())?;
+        let is_portfolio =
+            source == CredentialSource::ApiKey && auth::is_portfolio_key(&credential);
+        self.is_portfolio_key.set(Some(is_portfolio));
         let mut builder =
             Client::builder(settings.api_url.clone(), credential).user_agent(crate::USER_AGENT);
         if source == CredentialSource::OAuth {
             let (settings, store) = (settings.clone(), Arc::clone(&self.store));
             builder = builder.renew_credential(move || auth::renew(&settings, store.as_ref()));
         }
+        if let Some(tenant) = tenant {
+            builder = builder.tenant(tenant).map_err(|e| {
+                from_api(
+                    e,
+                    &ApiContext {
+                        source,
+                        framework: None,
+                        tenant_selected: true,
+                        is_portfolio_key: is_portfolio,
+                    },
+                )
+            })?;
+        }
         if self.verbose {
             builder = builder.observer(|event| {
                 eprintln!(
@@ -65,11 +92,23 @@ impl Context {
                 &ApiContext {
                     source,
                     framework: None,
+                    tenant_selected: tenant.is_some(),
+                    is_portfolio_key: is_portfolio,
                 },
             )
         })?;
         Ok((client, source))
     }
+
+    /// What a failure message needs to know about a call made with this context's selection.
+    pub fn call<'a>(&self, source: CredentialSource, framework: Option<&'a str>) -> ApiContext<'a> {
+        ApiContext {
+            source,
+            framework,
+            tenant_selected: !matches!(self.selection, Selection::Own),
+            is_portfolio_key: self.is_portfolio_key.get().unwrap_or(false),
+        }
+    }
 }
 
 pub fn run(cli: Cli, out: &mut dyn Write) -> Result<()> {
@@ -80,7 +119,13 @@ pub fn run(cli: Cli, out: &mut dyn Write) -> Result<()> {
         },
         json: cli.json,
         verbose: cli.verbose,
+        selection: match (cli.tenant, cli.all_tenants) {
+            (Some(tenant), _) => Selection::Tenant(tenant),
+            (None, true) => Selection::All,
+            (None, false) => Selection::Own,
+        },
         store: Arc::new(auth::store::Keychain),
+        is_portfolio_key: Cell::new(None),
     };
     match cli.command {
         Command::Vendors(command) => resources::vendors(&ctx, command, out),
@@ -89,6 +134,7 @@ pub fn run(cli: Cli, out: &mut dyn Write) -> Result<()> {
         Command::Compliance(command) => resources::compliance(&ctx, command, out),
         Command::Evidence(command) => resources::evidence(&ctx, command, out),
         Command::Endpoints(command) => resources::endpoints(&ctx, command, out),
+        Command::Tenants(command) => tenants::run(&ctx, command, out),
         Command::Login(args) => session::login(&ctx, &args),
         Command::Logout => session::logout(&ctx),
         Command::Whoami => session::whoami(&ctx, out),
diff --git a/crates/hodeishield-cli/src/commands/resources.rs b/crates/hodeishield-cli/src/commands/resources.rs
index 14b96d6..11343d8 100644
--- a/crates/hodeishield-cli/src/commands/resources.rs
+++ b/crates/hodeishield-cli/src/commands/resources.rs
@@ -4,19 +4,23 @@
 //! The read commands: one per `/v1` collection.
 
 use super::Context;
+use super::tenants::{Selection, Target};
 use crate::cli::{
     AlertsCommand, ComplianceCommand, EndpointsCommand, EvidenceCommand, Paging, RisksCommand,
     VendorsCommand,
 };
-use crate::failure::{ApiContext, CredentialSource, Result, from_api};
+use crate::failure::{ApiContext, CredentialSource, Failure, Kind, Result, from_api};
+use crate::filters::warn_unknown;
 use crate::output::{
-    cell, clean, print_csv, print_detail, print_json, print_table, short_time, table,
+    Rows, cell, clean, print_csv, print_detail, print_json, print_table, short_time, table,
+    tenant_table,
 };
-use comfy_table::Table;
+use hodeishield_api::Client;
+use hodeishield_api::portfolio::Tenant;
 use hodeishield_api::v1::{
     Alert, ComplianceControl, Endpoint, Evidence, ListAlertsParams, ListComplianceControlsParams,
     ListEndpointsParams, ListEvidenceParams, ListRisksParams, ListVendorsParams, Pagination, Risk,
-    Vendor,
+    Vendor, operations,
 };
 use hodeishield_api::{ApiResponse, Error};
 use serde::Serialize;
@@ -26,6 +30,10 @@ use std::io::Write;
 type Fetch<'a, R> =
     dyn FnMut(Option<i64>, Option<i64>) -> std::result::Result<ApiResponse<R>, Error> + 'a;
 
+/// A fetch that still has to be told which client to ask.
+type FetchFrom<'a, R> =
+    dyn FnMut(&Client, Option<i64>, Option<i64>) -> std::result::Result<ApiResponse<R>, Error> + 'a;
+
 /// Most pages `--all` fetches: 200 000 items at the largest page size.
 const MAX_PAGES: i64 = 1_000;
 
@@ -34,9 +42,38 @@ const MAX_PAGES: i64 = 1_000;
 /// hundred MiB at most.
 const MAX_ITEMS: usize = 100_000;
 
-/// Prints one page, or every page with `--all`.
+/// Prints a list for the selected client, or for every client with `--all-tenants`.
 #[allow(clippy::too_many_arguments)]
 fn list<R, T>(
+    ctx: &Context,
+    out: &mut dyn Write,
+    paging: &Paging,
+    noun: &str,
+    api: ApiContext<'_>,
+    targets: &[Target],
+    fetch: &mut FetchFrom<'_, R>,
+    split: fn(R) -> (Vec<T>, Pagination),
+    render: fn(&[T]) -> Rows,
+) -> Result<()> {
+    if matches!(ctx.selection, Selection::All) {
+        return list_across(ctx, out, paging, noun, api, targets, fetch, split, render);
+    }
+    let client = &targets[0].client;
+    list_one(
+        ctx,
+        out,
+        paging,
+        noun,
+        api,
+        &mut |page, per_page| fetch(client, page, per_page),
+        split,
+        render,
+    )
+}
+
+/// Prints one page, or every page with `--all`, of one tenant's list.
+#[allow(clippy::too_many_arguments)]
+pub(super) fn list_one<R, T>(
     ctx: &Context,
     out: &mut dyn Write,
     paging: &Paging,
@@ -44,7 +81,7 @@ fn list<R, T>(
     api: ApiContext<'_>,
     fetch: &mut Fetch<'_, R>,
     split: fn(R) -> (Vec<T>, Pagination),
-    render: fn(&[T]) -> Table,
+    render: fn(&[T]) -> Rows,
 ) -> Result<()> {
     if !paging.all {
         let response = fetch(paging.page, paging.per_page).map_err(|e| from_api(e, &api))?;
@@ -60,7 +97,7 @@ fn list<R, T>(
             let raw_items = response.raw.get("data").and_then(Value::as_array);
             print_csv(out, raw_items.map_or(&[], Vec::as_slice))?;
         } else {
-            print_table(out, &render(&items))?;
+            print_table(out, &render(&items).into_table())?;
         }
         if pagination.total_pages > 1 {
             let next = if pagination.page < pagination.total_pages {
@@ -88,14 +125,145 @@ fn list<R, T>(
     if paging.csv {
         print_csv(out, &raw_items)?;
     } else {
-        print_table(out, &render(&items))?;
+        print_table(out, &render(&items).into_table())?;
     }
     eprintln!("{} {noun}.", items.len());
     Ok(())
 }
 
+/// Every page of every client tenant, each row labelled with the tenant whose request produced it.
+///
+/// A tenant that cannot be read for its own reasons (no licence, left the portfolio) is reported
+/// and skipped, and the command still fails at the end, so a script never takes a partial result
+/// for a complete one. Any other failure stops the walk: tenants are asked one after the other, and
+/// a rate limit (after the client has waited out the short ones) or a missing scope is not retried
+/// against the next tenant.
+#[allow(clippy::too_many_arguments)]
+fn list_across<R, T>(
+    ctx: &Context,
+    out: &mut dyn Write,
+    paging: &Paging,
+    noun: &str,
+    api: ApiContext<'_>,
+    targets: &[Target],
+    fetch: &mut FetchFrom<'_, R>,
+    split: fn(R) -> (Vec<T>, Pagination),
+    render: fn(&[T]) -> Rows,
+) -> Result<()> {
+    let per_page = paging.per_page.or(Some(200));
+    let mut collected: Vec<(&Tenant, Vec<Value>, Vec<T>)> = Vec::new();
+    let mut failures: Vec<Failure> = Vec::new();
+    let mut total = 0_usize;
+    for target in targets {
+        let Some(tenant) = &target.tenant else {
+            continue;
+        };
+        if target.unknown_licence {
+            // The licence vocabulary is open. Not read, but not silently dropped either.
+            eprintln!(
+                "warning: client tenant {}: licence status `{}` is not known to this version; not read",
+                clean(&tenant.slug),
+                clean(&tenant.licence_status)
+            );
+            failures.push(Failure::general("licence status not known"));
+            continue;
+        }
+        let walked = collect_pages(
+            noun,
+            &api,
+            per_page,
+            MAX_ITEMS.saturating_sub(total),
+            &mut |page, per_page| fetch(&target.client, page, per_page),
+            split,
+        );
+        match walked {
+            Ok((raw_items, items)) => {
+                total += items.len();
+                collected.push((tenant, raw_items, items));
+            }
+            Err(failure) if matches!(failure.kind, Kind::NotFound | Kind::LicenceInactive) => {
+                eprintln!(
+                    "warning: client tenant {}: {}",
+                    clean(&tenant.slug),
+                    clean(&failure.message)
+                );
+                failures.push(failure);
+            }
+            Err(failure) => return Err(failure),
+        }
+    }
+
+    if ctx.json || paging.csv {
+        let mut labelled = Vec::new();
+        for (tenant, raw_items, _) in &collected {
+            for item in raw_items {
+                labelled.push(with_tenant(item, tenant)?);
+            }
+        }
+        if ctx.json {
+            print_json(out, &Value::Array(labelled))?;
+        } else {
+            print_csv(out, &labelled)?;
+        }
+    } else {
+        let mut headers = None;
+        let mut groups = Vec::new();
+        for (tenant, _, items) in &collected {
+            if items.is_empty() {
+                continue;
+            }
+            let rows = render(items);
+            headers.get_or_insert(rows.headers);
+            groups.push((tenant.slug.clone(), tenant.id.clone(), rows.rows));
+        }
+        if let Some(headers) = headers {
+            print_table(out, &tenant_table(headers, groups))?;
+        }
+    }
+    if total == 0 {
+        eprintln!("No {noun} found.");
+    } else {
+        eprintln!("{total} {noun} across {} client tenants.", collected.len());
+    }
+    match failures.first() {
+        None => Ok(()),
+        Some(first) => Err(Failure::new(
+            first.kind,
+            format!(
+                "Could not read {} of {} client tenants (see the warnings above); the output covers the others.",
+                failures.len(),
+                targets.len()
+            ),
+        )),
+    }
+}
+
+/// The item with the tenant whose request returned it in front: `tenant_id`, `tenant_slug` and
+/// `tenant_name`. An item that already has such a field is refused rather than overwritten.
+fn with_tenant(item: &Value, tenant: &Tenant) -> Result<Value> {
+    let Value::Object(fields) = item else {
+        return Err(Failure::general(
+            "An item of the answer is not an object, so it cannot be labelled with its tenant.",
+        ));
+    };
+    let mut labelled = serde_json::Map::new();
+    labelled.insert("tenant_id".to_owned(), Value::String(tenant.id.clone()));
+    labelled.insert("tenant_slug".to_owned(), Value::String(tenant.slug.clone()));
+    labelled.insert("tenant_name".to_owned(), Value::String(tenant.name.clone()));
+    for (key, value) in fields {
+        if labelled.contains_key(key) {
+            return Err(Failure::general(format!(
+                "An item already has a field named {}, which the tenant label would overwrite.",
+                clean(key)
+            )));
+        }
+        labelled.insert(key.clone(), value.clone());
+    }
+    Ok(Value::Object(labelled))
+}
+
 /// Walks every page, as received and decoded, stopping with an error past `max_items` items.
-fn collect_pages<R, T>(
+pub(super) fn collect_pages<R, T>(
     noun: &str,
     api: &ApiContext<'_>,
     per_page: Option<i64>,
@@ -157,18 +325,15 @@ fn show<R, T: Serialize>(
     Ok(print_detail(out, &value)?)
 }
 
-fn plain(source: CredentialSource) -> ApiContext<'static> {
-    ApiContext {
-        source,
-        framework: None,
-    }
+fn plain(ctx: &Context, source: CredentialSource) -> ApiContext<'static> {
+    ctx.call(source, None)
 }
 
 pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         VendorsCommand::List(args) => {
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListVendorsParams {
                 q: args.query,
                 category: args.category,
@@ -183,8 +348,9 @@ pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> R
                 out,
                 &args.paging,
                 "vendors",
-                plain(source),
-                &mut |page, per_page| {
+                plain(ctx, source),
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_vendors(&ListVendorsParams {
                         page,
                         per_page,
@@ -196,13 +362,16 @@ pub fn vendors(ctx: &Context, command: VendorsCommand, out: &mut dyn Write) -> R
             )
         }
         VendorsCommand::Get { id } => {
-            show(ctx, out, plain(source), client.get_vendor(&id), |r| &r.data)
+            let (client, source) = ctx.single(&settings)?;
+            show(ctx, out, plain(ctx, source), client.get_vendor(&id), |r| {
+                &r.data
+            })
         }
     }
 }
 
-fn vendor_table(items: &[Vendor]) -> Table {
-    table(
+fn vendor_table(items: &[Vendor]) -> Rows {
+    Rows::new(
         &["ID", "NAME", "DOMAIN", "CRITICALITY", "ACTIVE", "LAST SCAN"],
         items
             .iter()
@@ -222,9 +391,13 @@ fn vendor_table(items: &[Vendor]) -> Table {
 
 pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         AlertsCommand::List(args) => {
+            warn_unknown(
+                &operations::LIST_ALERTS,
+                &[("severity", args.severity.as_deref())],
+            );
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListAlertsParams {
                 status: args.status,
                 severity: args.severity,
@@ -239,8 +412,9 @@ pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Res
                 out,
                 &args.paging,
                 "alerts",
-                plain(source),
-                &mut |page, per_page| {
+                plain(ctx, source),
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_alerts(&ListAlertsParams {
                         page,
                         per_page,
@@ -252,13 +426,16 @@ pub fn alerts(ctx: &Context, command: AlertsCommand, out: &mut dyn Write) -> Res
             )
         }
         AlertsCommand::Get { id } => {
-            show(ctx, out, plain(source), client.get_alert(&id), |r| &r.data)
+            let (client, source) = ctx.single(&settings)?;
+            show(ctx, out, plain(ctx, source), client.get_alert(&id), |r| {
+                &r.data
+            })
         }
     }
 }
 
-fn alert_table(items: &[Alert]) -> Table {
-    table(
+fn alert_table(items: &[Alert]) -> Rows {
+    Rows::new(
         &["ID", "SEVERITY", "STATUS", "TYPE", "TITLE", "CREATED"],
         items
             .iter()
@@ -278,9 +455,16 @@ fn alert_table(items: &[Alert]) -> Table {
 
 pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         RisksCommand::List(args) => {
+            warn_unknown(
+                &operations::LIST_RISKS,
+                &[
+                    ("status", args.status.as_deref()),
+                    ("domain", args.domain.as_deref()),
+                ],
+            );
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListRisksParams {
                 status: args.status,
                 domain: args.domain,
@@ -295,8 +479,9 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
                 out,
                 &args.paging,
                 "risks",
-                plain(source),
-                &mut |page, per_page| {
+                plain(ctx, source),
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_risks(&ListRisksParams {
                         page,
                         per_page,
@@ -308,13 +493,16 @@ pub fn risks(ctx: &Context, command: RisksCommand, out: &mut dyn Write) -> Resul
             )
         }
         RisksCommand::Get { id } => {
-            show(ctx, out, plain(source), client.get_risk(&id), |r| &r.data)
+            let (client, source) = ctx.single(&settings)?;
+            show(ctx, out, plain(ctx, source), client.get_risk(&id), |r| {
+                &r.data
+            })
         }
     }
 }
 
-fn risk_table(items: &[Risk]) -> Table {
-    table(
+fn risk_table(items: &[Risk]) -> Rows {
+    Rows::new(
         &["ID", "TITLE", "DOMAIN", "STATUS", "INHERENT", "RESIDUAL"],
         items
             .iter()
@@ -335,13 +523,14 @@ fn risk_table(items: &[Risk]) -> Table {
 
 pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         ComplianceCommand::Controls(args) => {
-            let api = ApiContext {
-                source,
-                framework: Some(&args.framework),
-            };
+            warn_unknown(
+                &operations::LIST_COMPLIANCE_CONTROLS,
+                &[("status", args.status.as_deref())],
+            );
+            let (targets, source) = ctx.targets(&settings)?;
+            let api = ctx.call(source, Some(&args.framework));
             let mut base = ListComplianceControlsParams::new(args.framework.clone());
             base.status = args.status;
             base.sort = args.sort;
@@ -352,7 +541,8 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
                 &args.paging,
                 "controls",
                 api,
-                &mut |page, per_page| {
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_compliance_controls(&ListComplianceControlsParams {
                         page,
                         per_page,
@@ -364,10 +554,8 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
             )
         }
         ComplianceCommand::Posture { framework } => {
-            let api = ApiContext {
-                source,
-                framework: Some(&framework),
-            };
+            let (client, source) = ctx.single(&settings)?;
+            let api = ctx.call(source, Some(&framework));
             let response = client
                 .get_framework_posture(&framework)
                 .map_err(|e| from_api(e, &api))?;
@@ -397,8 +585,8 @@ pub fn compliance(ctx: &Context, command: ComplianceCommand, out: &mut dyn Write
     }
 }
 
-fn control_table(items: &[ComplianceControl]) -> Table {
-    table(
+fn control_table(items: &[ComplianceControl]) -> Rows {
+    Rows::new(
         &["CONTROL", "STATUS", "EVIDENCE", "LAST EVALUATED"],
         items
             .iter()
@@ -416,9 +604,9 @@ fn control_table(items: &[ComplianceControl]) -> Table {
 
 pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         EvidenceCommand::List(args) => {
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListEvidenceParams {
                 evidence_type: args.evidence_type,
                 source_type: args.source_type,
@@ -433,8 +621,9 @@ pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) ->
                 out,
                 &args.paging,
                 "evidence items",
-                plain(source),
-                &mut |page, per_page| {
+                plain(ctx, source),
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_evidence(&ListEvidenceParams {
                         page,
                         per_page,
@@ -446,15 +635,20 @@ pub fn evidence(ctx: &Context, command: EvidenceCommand, out: &mut dyn Write) ->
             )
         }
         EvidenceCommand::Get { id } => {
-            show(ctx, out, plain(source), client.get_evidence(&id), |r| {
-                &r.data
-            })
+            let (client, source) = ctx.single(&settings)?;
+            show(
+                ctx,
+                out,
+                plain(ctx, source),
+                client.get_evidence(&id),
+                |r| &r.data,
+            )
         }
     }
 }
 
-fn evidence_table(items: &[Evidence]) -> Table {
-    table(
+fn evidence_table(items: &[Evidence]) -> Rows {
+    Rows::new(
         &["ID", "TYPE", "SOURCE", "TITLE", "VALID UNTIL"],
         items
             .iter()
@@ -473,9 +667,9 @@ fn evidence_table(items: &[Evidence]) -> Table {
 
 pub fn endpoints(ctx: &Context, command: EndpointsCommand, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
-    let (client, source) = ctx.api(&settings)?;
     match command {
         EndpointsCommand::List(args) => {
+            let (targets, source) = ctx.targets(&settings)?;
             let base = ListEndpointsParams {
                 status: args.status,
                 silent_since: args.silent_since,
@@ -488,8 +682,9 @@ pub fn endpoints(ctx: &Context, command: EndpointsCommand, out: &mut dyn Write)
                 out,
                 &args.paging,
                 "endpoints",
-                plain(source),
-                &mut |page, per_page| {
+                plain(ctx, source),
+                &targets,
+                &mut |client, page, per_page| {
                     client.list_endpoints(&ListEndpointsParams {
                         page,
                         per_page,
@@ -503,8 +698,8 @@ pub fn endpoints(ctx: &Context, command: EndpointsCommand, out: &mut dyn Write)
     }
 }
 
-fn endpoint_table(items: &[Endpoint]) -> Table {
-    table(
+fn endpoint_table(items: &[Endpoint]) -> Rows {
+    Rows::new(
         &[
             "ID",
             "HOSTNAME",
@@ -539,6 +734,8 @@ mod tests {
         let api = ApiContext {
             source: CredentialSource::ApiKey,
             framework: None,
+            tenant_selected: false,
+            is_portfolio_key: false,
         };
         let total_pages = (total + per_page - 1) / per_page;
         collect_pages(
diff --git a/crates/hodeishield-cli/src/commands/session.rs b/crates/hodeishield-cli/src/commands/session.rs
index 59949af..f8c84e1 100644
--- a/crates/hodeishield-cli/src/commands/session.rs
+++ b/crates/hodeishield-cli/src/commands/session.rs
@@ -16,7 +16,17 @@ use std::time::{Duration, Instant};
 const BROWSER_TIMEOUT: Duration = Duration::from_secs(5 * 60);
 
 pub fn login(ctx: &Context, args: &LoginArgs) -> Result<()> {
-    let settings = ctx.settings()?;
+    login_with(&ctx.settings()?, ctx.store.as_ref(), args)
+}
+
+fn login_with(
+    settings: &crate::config::Settings,
+    store: &dyn auth::TokenStore,
+    args: &LoginArgs,
+) -> Result<()> {
+    // Before anything is asked of the person or the app: a session that cannot be kept is not
+    // worth approving.
+    store.check_available(&settings.profile)?;
     let client_id = settings.oauth_client_id.clone();
     let issuer = oauth::authorization_server(
         &oauth::http_client(&settings.api_url)?,
@@ -97,7 +107,25 @@ pub fn login(ctx: &Context, args: &LoginArgs) -> Result<()> {
         api_url: settings.api_url.as_str().trim_end_matches('/').to_owned(),
         client_id,
     };
-    ctx.store.save(&settings.profile, &token)?;
+    if let Err(failure) = store.save(&settings.profile, &token) {
+        // The grant exists at the app although nothing holds it: end it before reporting.
+        let revoked = revoke_tokens(
+            &http,
+            &metadata,
+            &token.client_id,
+            &token.access_token,
+            token.refresh_token.as_ref(),
+        );
+        eprintln!("{}", unstored_notice(&revoked));
+        return Err(if failure.hint.is_some() {
+            failure
+        } else {
+            failure.hint(format!(
+                "Use a tenant API key instead: export {}=<key>.",
+                auth::API_KEY_ENV
+            ))
+        });
+    }
     let who = oauth::userinfo(&http, &metadata, &token.access_token)
         .ok()
         .flatten()
@@ -117,6 +145,21 @@ pub fn login(ctx: &Context, args: &LoginArgs) -> Result<()> {
     Ok(())
 }
 
+/// What to tell the person when the session could not be kept, given how revoking it went.
+fn unstored_notice(revoked: &Result<()>) -> String {
+    match revoked {
+        Ok(()) => "The session could not be stored on this machine; the tokens issued for it were \
+                   revoked."
+            .to_owned(),
+        Err(revocation) => format!(
+            "The session could not be stored on this machine, and the app did not confirm \
+             revoking the tokens issued for it ({}). Revoke the CLI's access in the app under \
+             \"Application access\".",
+            clean(&revocation.message)
+        ),
+    }
+}
+
 pub fn logout(ctx: &Context) -> Result<()> {
     logout_with(&ctx.settings()?, ctx.store.as_ref())
 }
@@ -149,16 +192,33 @@ fn logout_with(settings: &crate::config::Settings, store: &dyn auth::TokenStore)
 
 pub fn whoami(ctx: &Context, out: &mut dyn Write) -> Result<()> {
     let settings = ctx.settings()?;
+    whoami_with(
+        &settings,
+        auth::api_key_from_env().is_some(),
+        ctx.store.as_ref(),
+        ctx.json,
+        out,
+    )
+}
+
+/// `whoami` with the settings and whether an API key is set given, so it can be tested without the
+/// process environment. With a key, the store is not read.
+fn whoami_with(
+    settings: &crate::config::Settings,
+    has_api_key: bool,
+    store: &dyn auth::TokenStore,
+    json: bool,
+    out: &mut dyn Write,
+) -> Result<()> {
     let mut info = Map::new();
     info.insert("profile".into(), json!(settings.profile));
     info.insert("api_url".into(), json!(settings.api_url.as_str()));
     info.insert("app_url".into(), json!(settings.app_url.as_str()));
 
-    let source = if auth::api_key_from_env().is_some() {
+    let source = if has_api_key {
         Some(CredentialSource::ApiKey)
     } else {
-        let existing = auth::current_token(&settings, ctx.store.as_ref())
-            .map_err(|failure| auth::explain_store_failure(failure, &settings))?;
+        let existing = auth::current_token(settings, store).map_err(auth::explain_store_failure)?;
         match existing {
             Some(token) => {
                 info.insert("issuer".into(), json!(token.issuer));
@@ -192,7 +252,7 @@ pub fn whoami(ctx: &Context, out: &mut dyn Write) -> Result<()> {
         })),
     );
 
-    if ctx.json {
+    if json {
         print_json(out, &Value::Object(info))?;
     } else {
         let mut rows = vec![
@@ -223,40 +283,57 @@ pub fn whoami(ctx: &Context, out: &mut dyn Write) -> Result<()> {
     }
     match source {
         Some(_) => Ok(()),
-        None => Err(auth::not_signed_in(&settings)),
+        None => Err(auth::not_signed_in(settings)),
     }
 }
 
 /// Revokes a stored sign-in at the app that issued it, never at whatever the profile points to
 /// now: the tokens themselves travel in the requests.
 ///
-/// The access token first, then the refresh token, each whatever happened to the other. An access
+/// The refresh token first, then the access token, each whatever happened to the other. An access
 /// token the app no longer knows (one that already expired, say) is not a failure; a refresh token it
 /// does not know, or any other refusal, is reported.
 fn revoke_at_issuer(token: &StoredToken) -> Result<()> {
     let issuer = auth::issuer_url(token)?;
     let http = oauth::http_client(&issuer)?;
     let metadata = oauth::discover(&http, &issuer)?;
-    let access = oauth::revoke(
+    revoke_tokens(
         &http,
         &metadata,
         &token.client_id,
         &token.access_token,
-        "access_token",
-    );
-    let refresh = token
-        .refresh_token
-        .as_ref()
-        .map(|refresh| oauth::revoke(&http, &metadata, &token.client_id, refresh, "refresh_token"));
-    let mut problems = Vec::new();
-    if let Err(failure) = access {
-        problems.push(failure.message);
-    }
+        token.refresh_token.as_ref(),
+    )
+}
+
+/// The revocation requests themselves (RFC 7009), refresh token first so it cannot mint another
+/// access token while the first is being ended.
+fn revoke_tokens(
+    http: &reqwest::blocking::Client,
+    metadata: &oauth::Metadata,
+    client_id: &str,
+    access_token: &secrecy::SecretString,
+    refresh_token: Option<&secrecy::SecretString>,
+) -> Result<()> {
+    let refresh = refresh_token
+        .map(|refresh| oauth::revoke(http, metadata, client_id, refresh, "refresh_token"));
+    let access = oauth::revoke(http, metadata, client_id, access_token, "access_token");
+    // In request order (refresh token, then access token); the same text twice is said once, which
+    // is what a missing revocation endpoint produces.
+    let mut problems: Vec<String> = Vec::new();
+    let mut report = |problem: String| {
+        if !problems.contains(&problem) {
+            problems.push(problem);
+        }
+    };
     match refresh {
-        Some(Ok(Revocation::Unknown(detail))) => problems.push(detail),
-        Some(Err(failure)) => problems.push(failure.message),
+        Some(Ok(Revocation::Unknown(detail))) => report(detail),
+        Some(Err(failure)) => report(failure.message),
         Some(Ok(Revocation::Revoked)) | None => {}
     }
+    if let Err(failure) = access {
+        report(failure.message);
+    }
     if problems.is_empty() {
         Ok(())
     } else {
@@ -283,6 +360,7 @@ mod tests {
     use super::*;
     use crate::auth::TokenStore;
     use crate::auth::store::MemoryStore;
+    use crate::cli::LoginArgs;
     use crate::config::{ConfigFile, Overrides, resolve_with};
     use secrecy::{ExposeSecret, SecretString};
 
@@ -494,4 +572,416 @@ mod tests {
         issuer.mock("POST", "/revoke").with_status(400).create();
         assert!(revoke_at_issuer(&signed_in(&issuer, None)).is_err());
     }
+
+    #[test]
+    fn a_missing_revocation_endpoint_is_reported_once_in_request_order() {
+        let mut issuer = mockito::Server::new();
+        issuer
+            .mock("GET", "/.well-known/oauth-authorization-server")
+            .with_body(
+                json!({
+                    "issuer": issuer.url(),
+                    "token_endpoint": format!("{}/token", issuer.url()),
+                })
+                .to_string(),
+            )
+            .create();
+        let err = revoke_at_issuer(&signed_in(&issuer, Some("rt"))).expect_err("no endpoint");
+        assert_eq!(err.message, "The app does not offer token revocation.");
+
+        // Different problems keep the order of the requests: refresh token first.
+        let issuer = revocation_server(500, 500);
+        let err = revoke_at_issuer(&signed_in(&issuer, Some("rt"))).expect_err("refused");
+        let refresh = err.message.find("refresh token").expect("refresh");
+        let access = err.message.find("access token").expect("access");
+        assert!(refresh < access, "{}", err.message);
+    }
+
+    /// A store for the sign-in tests: it can be unreachable from the start, or fail on save.
+    struct BrokenStore {
+        available: bool,
+    }
+
+    impl TokenStore for BrokenStore {
+        fn load(&self, _profile: &str) -> Result<Option<StoredToken>> {
+            Ok(None)
+        }
+
+        fn save(&self, _profile: &str, _token: &StoredToken) -> Result<()> {
+            Err(Failure::general("system keychain: cannot write"))
+        }
+
+        fn delete(&self, _profile: &str) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn check_available(&self, _profile: &str) -> Result<()> {
+            if self.available {
+                Ok(())
+            } else {
+                Err(Failure::general(format!(
+                    "{}: no Secret Service",
+                    crate::auth::store::KEYCHAIN_UNAVAILABLE
+                ))
+                .hint("use HODEISHIELD_API_KEY"))
+            }
+        }
+    }
+
+    fn settings_for(
+        api: &mockito::ServerGuard,
+        app: &mockito::ServerGuard,
+    ) -> crate::config::Settings {
+        let app = app.url();
+        let env = |name: &str| (name == "HODEISHIELD_APP_URL").then(|| app.clone());
+        let overrides = Overrides {
+            profile: None,
+            api_url: Some(api.url()),
+        };
+        resolve_with(
+            &ConfigFile::default(),
+            std::path::PathBuf::new(),
+            &overrides,
+            env,
+        )
+        .expect("settings")
+    }
+
+    /// A store whose keychain cannot be reached from this session; reading is the only thing it does.
+    struct UnreachableStore;
+
+    impl TokenStore for UnreachableStore {
+        fn load(&self, _profile: &str) -> Result<Option<StoredToken>> {
+            Err(crate::auth::store::read_failure(
+                keyring_core::Error::NoStorageAccess("Windows ERROR_NO_SUCH_LOGON_SESSION".into()),
+            ))
+        }
+        fn save(&self, _: &str, _: &StoredToken) -> Result<()> {
+            unreachable!()
+        }
+        fn delete(&self, _: &str) -> Result<bool> {
+            unreachable!()
+        }
+        fn check_available(&self, _: &str) -> Result<()> {
+            unreachable!()
+        }
+    }
+
+    #[test]
+    fn whoami_with_an_unreachable_keychain_is_not_authenticated() {
+        let (api, app) = (mockito::Server::new(), mockito::Server::new());
+        let settings = settings_for(&api, &app);
+        let mut out = Vec::new();
+        let err = whoami_with(&settings, false, &UnreachableStore, false, &mut out)
+            .expect_err("no credential");
+        assert_eq!(err.kind, crate::failure::Kind::NotAuthenticated);
+        assert!(
+            err.message
+                .starts_with("The system keychain is not available in this session"),
+            "{}",
+            err.message
+        );
+        assert!(
+            err.hint.as_deref().is_some_and(
+                |h| h.ends_with("In remote or automated sessions, set HODEISHIELD_API_KEY.")
+            ),
+            "{:?}",
+            err.hint
+        );
+        assert!(out.is_empty(), "nothing is printed before the failure");
+    }
+
+    #[test]
+    fn whoami_with_an_api_key_does_not_read_the_store() {
+        let (api, app) = (mockito::Server::new(), mockito::Server::new());
+        let settings = settings_for(&api, &app);
+        let mut out = Vec::new();
+        whoami_with(&settings, true, &UnreachableStore, true, &mut out).expect("key set");
+        assert!(String::from_utf8(out).expect("utf8").contains("api_key"));
+    }
+
+    const DEVICE: LoginArgs = LoginArgs {
+        device: true,
+        no_browser: false,
+    };
+
+    /// An app that offers the device flow, issues `at-new` / `rt-new`, and revokes whatever it is
+    /// asked to; the hints of the revocation requests are recorded in the order they arrive.
+    fn device_app(
+        api: &mut mockito::ServerGuard,
+        app: &mut mockito::ServerGuard,
+        revoke_status: usize,
+    ) -> (
+        std::sync::Arc<std::sync::Mutex<Vec<String>>>,
+        Vec<mockito::Mock>,
+    ) {
+        let revoked = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+        let seen = std::sync::Arc::clone(&revoked);
+        let url = app.url();
+        let mocks = vec![
+            api.mock("GET", "/.well-known/oauth-protected-resource")
+                .with_status(404)
+                .create(),
+            app.mock("GET", "/.well-known/oauth-authorization-server")
+                .with_body(
+                    json!({
+                        "issuer": url,
+                        "token_endpoint": format!("{url}/token"),
+                        "device_authorization_endpoint": format!("{url}/device/code"),
+                        "revocation_endpoint": format!("{url}/revoke"),
+                        "scopes_supported": ["offline_access"],
+                    })
+                    .to_string(),
+                )
+                .create(),
+            app.mock("POST", "/device/code")
+                .with_body(
+                    json!({
+                        "device_code": "dc", "user_code": "ABCD-EFGH",
+                        "verification_uri": format!("{url}/device"),
+                        "expires_in": 600, "interval": 1,
+                    })
+                    .to_string(),
+                )
+                .expect(1)
+                .create(),
+            app.mock("POST", "/token")
+                .with_body(
+                    json!({
+                        "access_token": "at-new", "refresh_token": "rt-new",
+                        "token_type": "Bearer", "expires_in": 3600,
+                    })
+                    .to_string(),
+                )
+                .expect(1)
+                .create(),
+            app.mock("POST", "/revoke")
+                .with_body_from_request(move |request| {
+                    let form: Vec<(String, String)> =
+                        url::form_urlencoded::parse(request.body().expect("body"))
+                            .into_owned()
+                            .collect();
+                    let get = |key: &str| {
+                        form.iter()
+                            .find(|(k, _)| k == key)
+                            .map(|(_, v)| v.clone())
+                            .unwrap_or_default()
+                    };
+                    seen.lock().expect("lock").push(format!(
+                        "{}={}",
+                        get("token_type_hint"),
+                        get("token")
+                    ));
+                    Vec::new()
+                })
+                .with_status(revoke_status)
+                .expect(2)
+                .create(),
+        ];
+        (revoked, mocks)
+    }
+
+    #[test]
+    fn an_unavailable_store_stops_login_before_the_app_is_asked_for_anything() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let calls: Vec<_> = [&mut api, &mut app]
+            .into_iter()
+            .flat_map(|server| {
+                ["GET", "POST"].map(|method| {
+                    server
+                        .mock(method, mockito::Matcher::Any)
+                        .expect(0)
+                        .create()
+                })
+            })
+            .collect();
+        let settings = settings_for(&api, &app);
+        let err =
+            login_with(&settings, &BrokenStore { available: false }, &DEVICE).expect_err("refused");
+        assert!(
+            err.message
+                .starts_with(crate::auth::store::KEYCHAIN_UNAVAILABLE),
+            "{}",
+            err.message
+        );
+        assert!(err.hint.as_deref().is_some_and(|h| h.contains("API_KEY")));
+        assert_eq!(format!("{:?}", err.kind), "General");
+        for call in &calls {
+            call.assert();
+        }
+    }
+
+    #[test]
+    fn tokens_that_cannot_be_stored_are_revoked_refresh_token_first() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let (revoked, mocks) = device_app(&mut api, &mut app, 200);
+        let settings = settings_for(&api, &app);
+        let err = login_with(&settings, &BrokenStore { available: true }, &DEVICE)
+            .expect_err("save fails");
+        assert_eq!(err.message, "system keychain: cannot write");
+        assert!(err.hint.as_deref().is_some_and(|h| h.contains("API_KEY")));
+        assert_eq!(
+            *revoked.lock().expect("lock"),
+            ["refresh_token=rt-new", "access_token=at-new"]
+        );
+        for mock in &mocks {
+            mock.assert();
+        }
+        // Nothing the person sees carries a token.
+        let notice = unstored_notice(&Ok(()));
+        assert!(notice.contains("revoked"), "{notice}");
+        let all = format!("{err:?} {notice}");
+        assert!(!all.contains("-new"), "{all}");
+    }
+
+    #[test]
+    fn a_failed_revocation_is_said_without_showing_any_token() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let (revoked, mocks) = device_app(&mut api, &mut app, 500);
+        let settings = settings_for(&api, &app);
+        let err = login_with(&settings, &BrokenStore { available: true }, &DEVICE)
+            .expect_err("save fails");
+        assert_eq!(err.message, "system keychain: cannot write");
+        assert_eq!(revoked.lock().expect("lock").len(), 2);
+        for mock in &mocks {
+            mock.assert();
+        }
+        // The notice login prints is built from the same revocation result.
+        let token = StoredToken {
+            access_token: SecretString::from("at-new"),
+            refresh_token: Some(SecretString::from("rt-new")),
+            ..signed_in(&app, None)
+        };
+        let revocation = revoke_at_issuer(&token).expect_err("the app answered 500");
+        let notice = unstored_notice(&Err(revocation));
+        assert!(notice.contains("did not confirm"), "{notice}");
+        let all = format!("{err:?} {} {notice}", err.message);
+        for secret in ["at-new", "rt-new"] {
+            assert!(!all.contains(secret), "{all}");
+        }
+    }
+
+    #[test]
+    fn the_notice_for_unrevoked_tokens_points_to_the_app() {
+        let notice = unstored_notice(&Err(Failure::general("the app refused to revoke")));
+        assert!(
+            notice.contains("did not confirm") && notice.contains("Application access"),
+            "{notice}"
+        );
+    }
+
+    #[test]
+    fn a_store_that_works_keeps_the_session_and_revokes_nothing() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let (revoked, mocks) = device_app(&mut api, &mut app, 200);
+        let settings = settings_for(&api, &app);
+        let store = MemoryStore::default();
+        login_with(&settings, &store, &DEVICE).expect("signed in");
+        let kept = store.load("default").expect("load").expect("stored");
+        assert_eq!(kept.access_token.expose_secret(), "at-new");
+        assert!(revoked.lock().expect("lock").is_empty());
+        // The revocation mock is the last one: it was never reached.
+        for mock in &mocks[..4] {
+            mock.assert();
+        }
+    }
+
+    #[test]
+    fn login_finds_the_sign_in_server_through_the_api_and_asks_for_the_scopes_it_needs() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let issuer = format!("{}/api/auth", app.url());
+        let resource = api
+            .mock("GET", "/.well-known/oauth-protected-resource")
+            .with_body(
+                json!({ "resource": api.url(), "authorization_servers": [issuer] }).to_string(),
+            )
+            .expect(1)
+            .create();
+        // RFC 8414 §3.1: the issuer's path goes after the well-known segment.
+        app.mock("GET", "/.well-known/oauth-authorization-server/api/auth")
+            .with_body(
+                json!({
+                    "issuer": issuer,
+                    "token_endpoint": format!("{issuer}/oauth2/token"),
+                    "device_authorization_endpoint": format!("{issuer}/device/code"),
+                    "scopes_supported": ["supply_risk:read", "compliance.nis2:read", "radar:read", "offline_access"],
+                })
+                .to_string(),
+            )
+            .create();
+        let device = app
+            .mock("POST", "/api/auth/device/code")
+            .match_body(mockito::Matcher::AllOf(vec![
+                mockito::Matcher::UrlEncoded("client_id".into(), "hodeishield-cli".into()),
+                mockito::Matcher::UrlEncoded(
+                    "scope".into(),
+                    "supply_risk:read compliance.nis2:read offline_access".into(),
+                ),
+            ]))
+            .with_body(
+                json!({
+                    "device_code": "dc", "user_code": "ABCD-EFGH",
+                    "verification_uri": format!("{}/device", app.url()),
+                    "expires_in": 600, "interval": 1,
+                })
+                .to_string(),
+            )
+            .expect(1)
+            .create();
+        // Denied at the end, so nothing is stored.
+        let token = app
+            .mock("POST", "/api/auth/oauth2/token")
+            .match_body(mockito::Matcher::UrlEncoded(
+                "client_id".into(),
+                "hodeishield-cli".into(),
+            ))
+            .with_status(400)
+            .with_body(r#"{"error":"access_denied"}"#)
+            .expect(1)
+            .create();
+        let settings = settings_for(&api, &app);
+        let store = MemoryStore::default();
+        let err = login_with(&settings, &store, &DEVICE).expect_err("denied");
+        assert!(err.message.contains("denied"), "{}", err.message);
+        assert_eq!(
+            err.kind.exit_code(),
+            crate::failure::Kind::NotAuthenticated.exit_code()
+        );
+        assert!(store.load("default").expect("load").is_none());
+        resource.assert();
+        device.assert();
+        token.assert();
+    }
+
+    #[test]
+    fn login_says_clearly_when_the_app_does_not_offer_it() {
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        api.mock("GET", "/.well-known/oauth-protected-resource")
+            .with_status(404)
+            .create();
+        app.mock("GET", mockito::Matcher::Regex("^/.well-known/".into()))
+            .with_status(404)
+            .expect(2)
+            .create();
+        let settings = settings_for(&api, &app);
+        let err = login_with(&settings, &MemoryStore::default(), &DEVICE).expect_err("none");
+        assert!(
+            err.message
+                .contains("does not offer sign-in for the CLI yet"),
+            "{}",
+            err.message
+        );
+        assert!(
+            err.hint
+                .as_deref()
+                .is_some_and(|h| h.contains("HODEISHIELD_API_KEY"))
+        );
+        assert_eq!(err.kind, crate::failure::Kind::General);
+    }
 }
diff --git a/crates/hodeishield-cli/src/commands/tenants.rs b/crates/hodeishield-cli/src/commands/tenants.rs
new file mode 100644
index 0000000..4a25c08
--- /dev/null
+++ b/crates/hodeishield-cli/src/commands/tenants.rs
@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! Client tenants: the `tenants` command and the selection of which client a read command reads.
+//!
+//! The CLI depends on the interface of `hodeishield_api::portfolio` only: it lists tenants and builds
+//! a client bound to one of them. How the selection travels on the wire is not known here.
+
+use super::Context;
+use super::resources::{collect_pages, list_one};
+use crate::cli::TenantsCommand;
+use crate::config::Settings;
+use crate::failure::{ApiContext, CredentialSource, Failure, Kind, Result};
+use crate::output::{Rows, clean};
+use hodeishield_api::Client;
+use hodeishield_api::portfolio::{
+    ListTenantsParams, ListTenantsResponse, Readability, Tenant, is_uuid,
+};
+use std::collections::HashSet;
+use std::io::Write;
+
+/// Which client tenant the read commands read.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Selection {
+    /// The credential's own tenant: what the CLI did before portfolios, with no tenant label.
+    Own,
+    /// One client, by slug or id.
+    Tenant(String),
+    /// Every client of the portfolio.
+    All,
+}
+
+/// A client to ask, and the tenant it is bound to. `tenant` is `None` only for [`Selection::Own`].
+/// Each target has its own client, so a request for one tenant can never carry another's selection.
+#[derive(Debug)]
+pub struct Target {
+    pub client: Client,
+    pub tenant: Option<Tenant>,
+    /// Set for a tenant of `--all-tenants` whose licence status this version does not know: it is
+    /// not read, and the walk reports it and fails at the end.
+    pub unknown_licence: bool,
+}
+
+impl Context {
+    /// The clients to read for the selection. For [`Selection::Own`] this is one client and no
+    /// request is made; otherwise the portfolio is listed first.
+    pub fn targets(&self, settings: &Settings) -> Result<(Vec<Target>, CredentialSource)> {
+        let selected = match &self.selection {
+            Selection::Own => {
+                let (client, source) = self.api(settings, None)?;
+                return Ok((
+                    vec![Target {
+                        client,
+                        tenant: None,
+                        unknown_licence: false,
+                    }],
+                    source,
+                ));
+            }
+            selected => selected,
+        };
+        let (lister, source) = self.api(settings, None)?;
+        let is_portfolio = self.is_portfolio_key.get().unwrap_or(false);
+        let portfolio = list_portfolio(&lister, source, is_portfolio)?;
+        let tenants = match selected {
+            Selection::Tenant(wanted) => {
+                let tenant = find(&portfolio, wanted)?;
+                eprintln!(
+                    "Client tenant: {} ({})",
+                    clean(&tenant.slug),
+                    clean(&tenant.id)
+                );
+                vec![tenant]
+            }
+            _ => {
+                // Inactive tenants are skipped on purpose. A tenant whose licence status this
+                // version does not know is not read either, but it stays in the list so the walk
+                // can report it and fail: nothing is silently missing.
+                let idle = portfolio
+                    .iter()
+                    .filter(|t| t.readability() == Readability::Inactive)
+                    .count();
+                if idle > 0 {
+                    eprintln!(
+                        "Skipping {idle} inactive client tenants (see `hodeishield tenants list`)."
+                    );
+                }
+                portfolio
+                    .into_iter()
+                    .filter(|t| t.readability() != Readability::Inactive)
+                    .collect()
+            }
+        };
+        let targets = tenants
+            .into_iter()
+            .map(|tenant| {
+                let (client, _) = self.api(settings, Some(&tenant.id))?;
+                let unknown_licence = matches!(selected, Selection::All)
+                    && tenant.readability() == Readability::Unknown;
+                Ok(Target {
+                    client,
+                    tenant: Some(tenant),
+                    unknown_licence,
+                })
+            })
+            .collect::<Result<_>>()?;
+        Ok((targets, source))
+    }
+
+    /// The one client a single-item command reads.
+    pub fn single(&self, settings: &Settings) -> Result<(Client, CredentialSource)> {
+        let (mut targets, source) = self.targets(settings)?;
+        match (targets.pop(), targets.is_empty()) {
+            (Some(target), true) => Ok((target.client, source)),
+            _ => Err(
+                Failure::general("This command reads one client tenant at a time.")
+                    .hint("Use --tenant <slug|id>; --all-tenants works on list commands."),
+            ),
+        }
+    }
+}
+
+/// Every client tenant of the portfolio.
+fn list_portfolio(
+    lister: &Client,
+    source: CredentialSource,
+    is_portfolio_key: bool,
+) -> Result<Vec<Tenant>> {
+    let api = ApiContext {
+        source,
+        framework: None,
+        tenant_selected: false,
+        is_portfolio_key,
+    };
+    let mut totals: Vec<i64> = Vec::new();
+    let (_, mut tenants) = collect_pages(
+        "client tenants",
+        &api,
+        Some(200),
+        100_000,
+        &mut |page, per_page| {
+            let response = lister.list_tenants(&ListTenantsParams::alphabetical(page, per_page))?;
+            totals.push(response.data.pagination.total);
+            Ok(response)
+        },
+        |r: ListTenantsResponse| (r.data, r.pagination),
+    )
+    .map_err(|failure| {
+        if failure.kind == Kind::Forbidden {
+            failure.hint(
+                "--tenant and --all-tenants need a portfolio credential. Without them the CLI \
+                 reads the credential's own tenant.",
+            )
+        } else {
+            failure
+        }
+    })?;
+    // The portfolio can change while it is walked: a tenant may then appear on two pages, or on
+    // none. Each tenant is read once, and the change is said out loud.
+    if totals.windows(2).any(|pair| pair[0] != pair[1]) {
+        eprintln!(
+            "warning: the number of client tenants changed while they were listed ({}); a tenant \
+             may be missing. Run the command again.",
+            totals
+                .iter()
+                .map(i64::to_string)
+                .collect::<Vec<_>>()
+                .join(", then ")
+        );
+    }
+    let mut seen = HashSet::new();
+    tenants.retain(|tenant| seen.insert(tenant.id.to_ascii_lowercase()));
+    Ok(tenants)
+}
+
+/// The tenant the user named, by id or slug. One that is not in the portfolio is reported the way
+/// the API reports it: not found, with no hint about whether it exists elsewhere.
+fn find(portfolio: &[Tenant], wanted: &str) -> Result<Tenant> {
+    // An input shaped like a UUID may be an id, but a slug can have that shape too: if it matches
+    // an id of one tenant and the slug of another, it is ambiguous, never resolved to one of them.
+    let by_id = is_uuid(wanted);
+    let mut matches = portfolio.iter().filter(|t| {
+        t.slug.eq_ignore_ascii_case(wanted) || (by_id && t.id.eq_ignore_ascii_case(wanted))
+    });
+    match (matches.next(), matches.next()) {
+        (Some(tenant), None) => Ok(tenant.clone()),
+        (Some(_), Some(_)) => Err(Failure::general(format!(
+            "More than one client tenant is called {}.",
+            clean(wanted)
+        ))
+        .hint("Use its id: see `hodeishield tenants list`.")),
+        _ => Err(Failure::new(
+            Kind::NotFound,
+            format!(
+                "No client tenant {} in this credential's portfolio.",
+                clean(wanted)
+            ),
+        )
+        .hint("List the client tenants you may read with `hodeishield tenants list`.")),
+    }
+}
+
+pub fn run(ctx: &Context, command: TenantsCommand, out: &mut dyn Write) -> Result<()> {
+    let TenantsCommand::List(args) = command;
+    let settings = ctx.settings()?;
+    let (client, source) = ctx.api(&settings, None)?;
+    let is_portfolio = ctx.is_portfolio_key.get().unwrap_or(false);
+    list_one(
+        ctx,
+        out,
+        &args.paging,
+        "client tenants",
+        ApiContext {
+            source,
+            framework: None,
+            tenant_selected: false,
+            is_portfolio_key: is_portfolio,
+        },
+        &mut |page, per_page| client.list_tenants(&ListTenantsParams::alphabetical(page, per_page)),
+        |r| (r.data, r.pagination),
+        tenant_rows,
+    )
+    .map_err(|failure| {
+        if failure.kind == Kind::Forbidden {
+            failure.hint("Listing client tenants needs a portfolio credential.")
+        } else {
+            failure
+        }
+    })
+}
+
+fn tenant_rows(items: &[Tenant]) -> Rows {
+    Rows::new(
+        &[
+            "SLUG",
+            "NAME",
+            "ORGANISATION",
+            "TYPE",
+            "STATUS",
+            "LICENCE",
+            "ID",
+        ],
+        items
+            .iter()
+            .map(|t| {
+                vec![
+                    clean(&t.slug),
+                    clean(&t.name),
+                    clean(&t.organization.name),
+                    if t.internal { "own" } else { "client" }.to_owned(),
+                    if t.active { "active" } else { "inactive" }.to_owned(),
+                    clean(&t.licence_status),
+                    clean(&t.id),
+                ]
+            })
+            .collect(),
+    )
+}
diff --git a/crates/hodeishield-cli/src/config.rs b/crates/hodeishield-cli/src/config.rs
index 248acc6..71c3fb9 100644
--- a/crates/hodeishield-cli/src/config.rs
+++ b/crates/hodeishield-cli/src/config.rs
@@ -25,6 +25,9 @@ pub struct ConfigFile {
     /// Profile used when neither `--profile` nor `HODEISHIELD_PROFILE` names one.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub default_profile: Option<String>,
+    /// Whether to look for a newer release once a day. Global, not per profile. Unset: yes.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub update_check: Option<bool>,
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub profiles: BTreeMap<String, Profile>,
 }
@@ -46,8 +49,33 @@ pub struct Profile {
     pub oauth_scopes: Option<Vec<String>>,
 }
 
-/// The keys `config set` and `config unset` accept.
-pub const KEYS: &[&str] = &["api_url", "app_url", "oauth_client_id", "oauth_scopes"];
+/// The keys `config set` and `config unset` accept. `update_check` is global; the rest belong to a
+/// profile.
+pub const KEYS: &[&str] = &[
+    "api_url",
+    "app_url",
+    "oauth_client_id",
+    "oauth_scopes",
+    UPDATE_CHECK,
+];
+
+/// The one global key.
+pub const UPDATE_CHECK: &str = "update_check";
+
+impl ConfigFile {
+    pub fn set_update_check(&mut self, value: &str) -> Result<()> {
+        self.update_check = Some(match value.trim().to_ascii_lowercase().as_str() {
+            "true" => true,
+            "false" => false,
+            _ => {
+                return Err(Failure::general(format!(
+                    "update_check: `{value}` is not true or false."
+                )));
+            }
+        });
+        Ok(())
+    }
+}
 
 impl Profile {
     pub fn set(&mut self, key: &str, value: &str) -> Result<()> {
@@ -350,6 +378,16 @@ mod tests {
         }
     }
 
+    #[test]
+    fn update_check_is_a_global_boolean() {
+        let mut config = ConfigFile::default();
+        assert!(config.set_update_check("maybe").is_err());
+        config.set_update_check("False").expect("set");
+        assert_eq!(config.update_check, Some(false));
+        let text = toml::to_string_pretty(&config).expect("toml");
+        assert_eq!(text.trim(), "update_check = false");
+    }
+
     #[test]
     fn unknown_keys_are_refused() {
         let mut profile = Profile::default();
diff --git a/crates/hodeishield-cli/src/failure.rs b/crates/hodeishield-cli/src/failure.rs
index a3c0bda..296c88d 100644
--- a/crates/hodeishield-cli/src/failure.rs
+++ b/crates/hodeishield-cli/src/failure.rs
@@ -20,9 +20,10 @@ pub enum Kind {
     NotFound,
     /// A rate limit is exhausted (429). Exit code 6.
     RateLimited,
-    /// The API could not be reached or failed (network, 5xx). Exit code 7.
+    /// The API could not be reached, failed (network, 5xx), or lacks a feature the command needs
+    /// (no portfolio listing). Exit code 7.
     Unavailable,
-    /// The tenant holds no licence in force (403 `LICENCE_INACTIVE`). Exit code 8.
+    /// The tenant holds no licence in force, or is deactivated (403 `LICENCE_INACTIVE`). Exit code 8.
     LicenceInactive,
 }
 
@@ -48,6 +49,18 @@ pub struct Failure {
     pub message: String,
     pub hint: Option<String>,
     pub request_id: Option<String>,
+    /// Whether this failure is the reader of standard output going away
+    /// (`hodeishield ... | head -1`). Only [`Failure::closed_stdout`] sets it, and the caller does
+    /// that only for an `io::Error` of kind [`std::io::ErrorKind::BrokenPipe`] seen while writing
+    /// to standard output (see `output::Tracked`). The conversion from [`std::io::Error`] never
+    /// sets it: a broken pipe on a socket, a file or a config write is a real failure, and so is
+    /// message text, which can come from the API.
+    pub closed_pipe: bool,
+    /// Whether this failure was converted from an `io::Error` of kind
+    /// [`std::io::ErrorKind::BrokenPipe`], wherever it came from. On its own it means nothing:
+    /// `main` treats the failure as a closed reader only when standard output also saw the
+    /// broken pipe, so an unrelated failure after the reader went away still fails.
+    pub(crate) broken_pipe: bool,
 }
 
 impl Failure {
@@ -57,6 +70,8 @@ impl Failure {
             message: message.into(),
             hint: None,
             request_id: None,
+            closed_pipe: false,
+            broken_pipe: false,
         }
     }
 
@@ -64,6 +79,13 @@ impl Failure {
         Self::new(Kind::General, message)
     }
 
+    /// Marks this failure as the reader of standard output having gone away.
+    #[must_use]
+    pub fn closed_stdout(mut self) -> Self {
+        self.closed_pipe = true;
+        self
+    }
+
     #[must_use]
     pub fn hint(mut self, hint: impl Into<String>) -> Self {
         self.hint = Some(hint.into());
@@ -79,7 +101,9 @@ impl fmt::Display for Failure {
 
 impl From<std::io::Error> for Failure {
     fn from(error: std::io::Error) -> Self {
-        Self::general(error.to_string())
+        let mut failure = Self::general(error.to_string());
+        failure.broken_pipe = error.kind() == std::io::ErrorKind::BrokenPipe;
+        failure
     }
 }
 
@@ -116,10 +140,12 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                                 && s.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
                         })
                         .map_or_else(String::new, |s| format!(" (licence: {s})"));
-                    Failure::new(
-                        Kind::LicenceInactive,
-                        format!("The tenant's licence is not in force{state}."),
-                    )
+                    let message = if detail(&api, "licence") == Some("tenant_inactive") {
+                        "The tenant is deactivated.".to_owned()
+                    } else {
+                        format!("The tenant's licence is not in force{state}.")
+                    };
+                    Failure::new(Kind::LicenceInactive, message)
                     .hint(
                         "Ask a tenant administrator to renew or reactivate it. Signing in again or \
                          using another key of this tenant will not help.",
@@ -131,6 +157,12 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                         .iter()
                         .map(|s| context.fill_scope(s))
                         .collect();
+                    let hint = if context.is_portfolio_key {
+                        "Ask an organisation administrator of your MSSP organisation for a key or \
+                         access with that scope."
+                    } else {
+                        "Ask a tenant administrator for a key or access with that scope."
+                    };
                     Failure::new(
                         Kind::Forbidden,
                         format!(
@@ -138,27 +170,80 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
                             scopes.join(", ")
                         ),
                     )
-                    .hint("Ask a tenant administrator for a key or access with that scope.")
+                    .hint(hint)
+                }
+                404 => {
+                    let failure = Failure::new(
+                        Kind::NotFound,
+                        server_message.unwrap_or_else(|| "Not found.".to_owned()),
+                    );
+                    if detail(&api, "code") == Some("TENANT_NOT_FOUND") {
+                        failure.hint(
+                            "The client tenant is not in this credential's portfolio (or it left \
+                             it). `hodeishield tenants list` shows the ones you may read.",
+                        )
+                    } else {
+                        failure
+                    }
                 }
-                404 => Failure::new(
-                    Kind::NotFound,
-                    server_message.unwrap_or_else(|| "Not found.".to_owned()),
-                ),
                 429 => {
                     let wait = api
                         .meta
                         .retry_after
                         .map_or_else(String::new, |s| format!(" Try again in {s} s."));
                     let scope = detail(&api, "scope").map_or_else(String::new, |s| format!(" (limit: {s})"));
-                    Failure::new(
+                    let hint = match detail(&api, "scope") {
+                        Some("portfolio_key") => Some(
+                            "This portfolio key has used its requests for the minute. A script \
+                             that reads many client tenants should pause between runs.",
+                        ),
+                        Some("portfolio_org") => Some(
+                            "All portfolio keys of your organisation share this limit; another key \
+                             or script may be using it.",
+                        ),
+                        Some("portfolio_tenant") => Some(
+                            "This client tenant's own limit is used up; other client tenants are \
+                             not affected.",
+                        ),
+                        // The plain `tenant` limit is also what a single-tenant key hits: the
+                        // client wording fits only when a client tenant was selected.
+                        Some("tenant") if context.tenant_selected => Some(
+                            "This client tenant's own limit is used up; other client tenants are \
+                             not affected.",
+                        ),
+                        _ => None,
+                    };
+                    let failure = Failure::new(
                         Kind::RateLimited,
                         format!("Rate limit exhausted{scope}.{wait}"),
-                    )
+                    );
+                    match hint {
+                        Some(hint) => failure.hint(hint),
+                        None => failure,
+                    }
+                }
+                400 => {
+                    let failure = Failure::general(format!(
+                        "The API rejected the request: {}.",
+                        server_message.unwrap_or_else(|| "invalid request".to_owned())
+                    ));
+                    match detail(&api, "code") {
+                        Some("TENANT_REQUIRED") => failure.hint(
+                            "This credential covers several client tenants: pick one with \
+                             --tenant <slug|id>, or every one with --all-tenants on a list. \
+                             `hodeishield tenants list` shows them.",
+                        ),
+                        Some("TENANT_SELECTOR_NOT_SUPPORTED") => failure.hint(
+                            "This credential reads one tenant only; leave out --tenant and \
+                             --all-tenants.",
+                        ),
+                        Some("TENANT_HEADER_INVALID") => failure.hint(
+                            "The CLI sent a tenant selection the API could not read. This is a \
+                             bug: please report it.",
+                        ),
+                        _ => failure,
+                    }
                 }
-                400 => Failure::general(format!(
-                    "The API rejected the request: {}.",
-                    server_message.unwrap_or_else(|| "invalid request".to_owned())
-                )),
                 status if status >= 500 => Failure::new(
                     Kind::Unavailable,
                     format!(
@@ -179,6 +264,20 @@ pub fn from_api(error: hodeishield_api::Error, context: &ApiContext<'_>) -> Fail
             "The answer to {operation} does not match the API description this CLI was built from: {source}."
         ))
         .hint("Your CLI may be older than the API. Check for a newer release."),
+        hodeishield_api::Error::PortfolioNotOffered { .. } => Failure::new(
+            Kind::Unavailable,
+            "This API does not offer portfolio access yet.",
+        )
+        .hint(
+            "Reading several client tenants with one credential needs a newer API, or the API URL \
+             is not the HodeiShield /v1 API. Without --tenant and --all-tenants the CLI reads the \
+             credential's own tenant as before.",
+        ),
+        other @ hodeishield_api::Error::TenantMismatch { .. } => Failure::general(other.to_string())
+            .hint(
+                "Nothing was shown, so that no client's data appears under another's name. Check \
+                 the API URL and try again; if it persists, contact support.",
+            ),
         other => Failure::general(other.to_string()),
     }
 }
@@ -221,6 +320,10 @@ pub struct ApiContext<'a> {
     pub source: CredentialSource,
     /// The framework of a compliance call, to fill `compliance.<framework>:read`.
     pub framework: Option<&'a str>,
+    /// Whether the call reads a selected client tenant (`--tenant` or `--all-tenants`).
+    pub tenant_selected: bool,
+    /// Whether the credential is a portfolio key (starts with `hsp_`).
+    pub is_portfolio_key: bool,
 }
 
 impl ApiContext<'_> {
@@ -231,3 +334,26 @@ impl ApiContext<'_> {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Error, ErrorKind};
+
+    #[test]
+    fn converting_an_io_error_never_marks_a_closed_pipe() {
+        assert!(!Failure::from(Error::from(ErrorKind::BrokenPipe)).closed_pipe);
+        assert!(!Failure::from(Error::from(ErrorKind::NotFound)).closed_pipe);
+        assert!(
+            Failure::from(Error::from(ErrorKind::BrokenPipe))
+                .closed_stdout()
+                .closed_pipe
+        );
+    }
+
+    #[test]
+    fn message_text_never_marks_a_closed_pipe() {
+        assert!(!Failure::general("Broken pipe").closed_pipe);
+        assert!(!Failure::from(Error::other("Broken pipe")).closed_pipe);
+    }
+}
diff --git a/crates/hodeishield-cli/src/filters.rs b/crates/hodeishield-cli/src/filters.rs
new file mode 100644
index 0000000..7842793
--- /dev/null
+++ b/crates/hodeishield-cli/src/filters.rs
@@ -0,0 +1,330 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The values the API document lists for a filter (`x-hs-known-values`): shown in `--help` and
+//! checked before a request. The lists are open vocabularies, so a value that is not listed is
+//! warned about and sent exactly as typed; nothing here refuses a value or rewrites it.
+//!
+//! The document may also mark values as deprecated (`x-hs-deprecated-values`, with the last day
+//! they are accepted in `x-hs-deprecated-values-sunset`). Such a value gets its own warning, which
+//! points to the listed values, and is still sent exactly as typed.
+
+use crate::output::clean;
+use hodeishield_api::Operation;
+
+/// The help text of a filter flag: `base`, plus the values the document lists for `param`, when it
+/// lists any. Without a list the help is `base` unchanged.
+pub fn help(base: &str, operation: &Operation, param: &str) -> String {
+    match operation.known_values(param) {
+        Some(values) if !values.is_empty() => {
+            format!("{base} Known values: {}.", values.join(", "))
+        }
+        _ => base.to_owned(),
+    }
+}
+
+/// Replacements for the deprecated values of the alert `severity` filter.
+///
+/// This table exists only because the API document lists the deprecated values without their
+/// replacements. Remove it, and its use in [`deprecated_hint`], after the sunset, 2027-01-14.
+const SEVERITY_REPLACEMENTS: &[(&str, &str)] = &[
+    ("critico", "critical"),
+    ("alto", "high"),
+    ("medio", "medium"),
+    ("bajo", "low"),
+];
+
+/// The listed value that replaces the deprecated `value`, when [`SEVERITY_REPLACEMENTS`] knows one
+/// and the document lists it.
+fn replacement(operation: &Operation, param: &str, value: &str) -> Option<&'static str> {
+    if operation.id != "listAlerts" || param != "severity" {
+        return None;
+    }
+    let (_, current) = SEVERITY_REPLACEMENTS
+        .iter()
+        .find(|(deprecated, _)| deprecated.eq_ignore_ascii_case(value))?;
+    operation
+        .known_values(param)
+        .is_some_and(|known| known.contains(current))
+        .then_some(*current)
+}
+
+/// The warning for a value the document marks as deprecated for `param` (matched without regard
+/// to case), or `None` when it does not.
+fn deprecated_hint(operation: &Operation, param: &str, value: &str) -> Option<String> {
+    let deprecated = operation.deprecated_values(param)?;
+    if !deprecated
+        .values
+        .iter()
+        .any(|d| d.eq_ignore_ascii_case(value))
+    {
+        return None;
+    }
+    let until = deprecated.sunset.map_or_else(String::new, |date| {
+        format!(", accepted by the API until {date}")
+    });
+    let known = operation.known_values(param).filter(|v| !v.is_empty());
+    let advice = match (replacement(operation, param, value), known) {
+        (Some(current), _) => format!("; use `{current}`"),
+        (None, Some(known)) => format!("; use one of the listed values ({})", known.join(", ")),
+        (None, None) => String::new(),
+    };
+    Some(format!(
+        "warning: `{}` is a deprecated value for --{}{until}{advice}. Sending it as typed.",
+        clean(value),
+        param.replace('_', "-"),
+    ))
+}
+
+/// The warnings for the `(parameter, value)` pairs the user gave: one per value the document marks
+/// as deprecated for that parameter, and one per value that is not in the list it publishes. A
+/// parameter without either list never warns. The match against the list is exact and
+/// case-sensitive, as the API is; a value that differs only by case also gets the listed spelling
+/// as a hint.
+pub fn warnings(operation: &Operation, filters: &[(&str, Option<&str>)]) -> Vec<String> {
+    filters
+        .iter()
+        .filter_map(|&(param, value)| {
+            let value = value?;
+            let known = operation.known_values(param).filter(|v| !v.is_empty());
+            if known.is_some_and(|known| known.contains(&value)) {
+                return None;
+            }
+            if let Some(hint) = deprecated_hint(operation, param, value) {
+                return Some(hint);
+            }
+            let known = known?;
+            let tail = known
+                .iter()
+                .find(|k| k.eq_ignore_ascii_case(value))
+                .map_or_else(
+                    || "sending it anyway.".to_owned(),
+                    |k| format!("did you mean `{k}`? Sending it anyway."),
+                );
+            Some(format!(
+                "warning: `{}` is not one of the values the API lists for --{} ({}); {tail}",
+                clean(value),
+                param.replace('_', "-"),
+                known.join(", "),
+            ))
+        })
+        .collect()
+}
+
+/// Prints [`warnings`] to stderr.
+pub fn warn_unknown(operation: &Operation, filters: &[(&str, Option<&str>)]) {
+    for warning in warnings(operation, filters) {
+        eprintln!("{warning}");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use hodeishield_api::DeprecatedValues;
+
+    const WITH_LISTS: Operation = Operation {
+        id: "listAlerts",
+        method: "GET",
+        path: "/v1/alerts",
+        summary: "List alerts",
+        scopes: &[],
+        known_values: &[("severity", &["critical", "high", "medium", "low"])],
+        deprecated_values: &[],
+        tenant_scoped: true,
+    };
+
+    const WITHOUT_LISTS: Operation = Operation {
+        known_values: &[],
+        ..WITH_LISTS
+    };
+
+    #[test]
+    fn an_unlisted_value_warns_and_names_the_options() {
+        assert_eq!(
+            warnings(&WITH_LISTS, &[("severity", Some("urgent"))]),
+            [
+                "warning: `urgent` is not one of the values the API lists for --severity \
+              (critical, high, medium, low); sending it anyway."
+            ]
+        );
+    }
+
+    #[test]
+    fn a_listed_value_or_no_value_is_silent() {
+        assert!(warnings(&WITH_LISTS, &[("severity", Some("high"))]).is_empty());
+        assert!(warnings(&WITH_LISTS, &[("severity", None)]).is_empty());
+    }
+
+    #[test]
+    fn a_difference_only_in_case_suggests_the_listed_spelling() {
+        assert_eq!(
+            warnings(&WITH_LISTS, &[("severity", Some("High"))]),
+            [
+                "warning: `High` is not one of the values the API lists for --severity \
+              (critical, high, medium, low); did you mean `high`? Sending it anyway."
+            ]
+        );
+    }
+
+    #[test]
+    fn a_parameter_without_a_list_never_warns() {
+        assert!(warnings(&WITH_LISTS, &[("category", Some("anything"))]).is_empty());
+        assert!(warnings(&WITHOUT_LISTS, &[("severity", Some("urgent"))]).is_empty());
+    }
+
+    const ALERTS: Operation = Operation {
+        known_values: &[("severity", &["critical", "high", "medium", "low", "info"])],
+        deprecated_values: &[DeprecatedValues {
+            param: "severity",
+            values: &["critico", "alto", "medio", "bajo", "urgente"],
+            sunset: Some("2027-01-14"),
+        }],
+        ..WITH_LISTS
+    };
+
+    #[test]
+    fn a_deprecated_value_with_a_replacement_points_to_it() {
+        assert_eq!(
+            warnings(&ALERTS, &[("severity", Some("alto"))]),
+            [
+                "warning: `alto` is a deprecated value for --severity, accepted by the API until \
+                 2027-01-14; use `high`. Sending it as typed."
+            ]
+        );
+        for (deprecated, current) in [
+            ("critico", "critical"),
+            ("medio", "medium"),
+            ("bajo", "low"),
+        ] {
+            let out = warnings(&ALERTS, &[("severity", Some(deprecated))]);
+            assert!(out[0].contains(&format!("use `{current}`")), "{out:?}");
+        }
+    }
+
+    #[test]
+    fn a_deprecated_value_is_matched_without_regard_to_case() {
+        let out = warnings(&ALERTS, &[("severity", Some("ALTO"))]);
+        assert_eq!(out.len(), 1);
+        assert!(out[0].starts_with("warning: `ALTO` is a deprecated value for --severity"));
+        assert!(out[0].contains("use `high`"), "{out:?}");
+    }
+
+    #[test]
+    fn a_deprecated_value_without_a_replacement_points_to_the_listed_values() {
+        assert_eq!(
+            warnings(&ALERTS, &[("severity", Some("urgente"))]),
+            [
+                "warning: `urgente` is a deprecated value for --severity, accepted by the API \
+                 until 2027-01-14; use one of the listed values (critical, high, medium, low, \
+                 info). Sending it as typed."
+            ]
+        );
+        // A replacement the document does not list is not offered.
+        let unlisted = Operation {
+            known_values: &[("severity", &["urgent"])],
+            ..ALERTS
+        };
+        let out = warnings(&unlisted, &[("severity", Some("alto"))]);
+        assert!(
+            out[0].ends_with("use one of the listed values (urgent). Sending it as typed."),
+            "{out:?}"
+        );
+    }
+
+    #[test]
+    fn a_deprecated_value_without_a_sunset_or_a_list() {
+        let no_sunset = Operation {
+            id: "listRisks",
+            known_values: &[("min_score", &["low", "high"])],
+            deprecated_values: &[DeprecatedValues {
+                param: "min_score",
+                values: &["bajo"],
+                sunset: None,
+            }],
+            ..WITH_LISTS
+        };
+        assert_eq!(
+            warnings(&no_sunset, &[("min_score", Some("bajo"))]),
+            [
+                "warning: `bajo` is a deprecated value for --min-score; use one of the listed \
+                 values (low, high). Sending it as typed."
+            ]
+        );
+        let no_list = Operation {
+            known_values: &[],
+            ..no_sunset
+        };
+        assert_eq!(
+            warnings(&no_list, &[("min_score", Some("bajo"))]),
+            ["warning: `bajo` is a deprecated value for --min-score. Sending it as typed."]
+        );
+    }
+
+    #[test]
+    fn the_replacements_apply_to_the_alert_severity_filter_only() {
+        let other = Operation {
+            id: "listRisks",
+            ..ALERTS
+        };
+        let out = warnings(&other, &[("severity", Some("alto"))]);
+        assert!(out[0].contains("use one of the listed values"), "{out:?}");
+    }
+
+    #[test]
+    fn a_current_severity_is_silent() {
+        for value in ["critical", "high", "medium", "low", "info"] {
+            assert!(warnings(&ALERTS, &[("severity", Some(value))]).is_empty());
+        }
+    }
+
+    #[test]
+    fn an_unrelated_severity_keeps_the_generic_warning() {
+        let out = warnings(&ALERTS, &[("severity", Some("urgent"))]);
+        assert!(
+            out[0].contains("is not one of the values the API lists"),
+            "{out:?}"
+        );
+    }
+
+    /// Fails when the document adds or removes a deprecated severity, so the table above follows
+    /// it, and when a replacement is not a listed value.
+    #[test]
+    fn the_replacements_match_the_generated_alert_severity_filter() {
+        let operation = hodeishield_api::v1::operations::LIST_ALERTS;
+        let deprecated = operation
+            .deprecated_values("severity")
+            .expect("the document deprecates severity values");
+        let mut listed: Vec<&str> = deprecated.values.to_vec();
+        listed.sort_unstable();
+        let mut mapped: Vec<&str> = SEVERITY_REPLACEMENTS.iter().map(|(d, _)| *d).collect();
+        mapped.sort_unstable();
+        assert_eq!(mapped, listed);
+        let known = operation.known_values("severity").expect("listed values");
+        for (_, current) in SEVERITY_REPLACEMENTS {
+            assert!(known.contains(current), "{current}");
+        }
+    }
+
+    #[test]
+    fn control_characters_in_the_value_are_not_echoed() {
+        let out = warnings(&WITH_LISTS, &[("severity", Some("a\u{1b}[31mb"))]);
+        assert!(!out[0].contains('\u{1b}'), "{out:?}");
+    }
+
+    #[test]
+    fn help_lists_the_values_only_when_the_document_does() {
+        assert_eq!(
+            help("Exact severity.", &WITH_LISTS, "severity"),
+            "Exact severity. Known values: critical, high, medium, low."
+        );
+        assert_eq!(
+            help("Exact severity.", &WITHOUT_LISTS, "severity"),
+            "Exact severity."
+        );
+        assert_eq!(
+            help("Exact category.", &WITH_LISTS, "category"),
+            "Exact category."
+        );
+    }
+}
diff --git a/crates/hodeishield-cli/src/lib.rs b/crates/hodeishield-cli/src/lib.rs
index 9d21bc9..1974beb 100644
--- a/crates/hodeishield-cli/src/lib.rs
+++ b/crates/hodeishield-cli/src/lib.rs
@@ -12,9 +12,11 @@ pub mod cli;
 mod commands;
 mod config;
 mod failure;
+mod filters;
 mod output;
+mod update_check;
 
-use std::io::{ErrorKind, Write};
+use std::io::Write;
 use std::process::ExitCode;
 
 pub const USER_AGENT: &str = concat!(
@@ -27,21 +29,48 @@ pub const USER_AGENT: &str = concat!(
 #[must_use]
 pub fn main() -> ExitCode {
     let cli = cli::Cli::parse_checked();
+    let for_programs = cli.prints_for_programs();
+    let verbose = cli.verbose;
     let stdout = std::io::stdout();
-    let mut out = std::io::BufWriter::new(stdout.lock());
+    let mut out = std::io::BufWriter::new(output::Tracked::new(stdout.lock()));
     let result = commands::run(cli, &mut out);
     let flushed = out.flush();
+    let stdout_closed = out.get_ref().closed();
+    // After the command's own work and output, so it never delays them.
+    update_check::notify(for_programs, verbose);
+    exit_code(result, flushed, stdout_closed)
+}
+
+/// Reports the outcome and maps it to the exit code. `stdout_closed` says that writing to
+/// standard output failed with a broken pipe (`hodeishield vendors list | head -1`): a failure
+/// that is that broken pipe is not an error. A broken pipe from anywhere else is, and so is any
+/// other failure, even after the reader of standard output went away.
+fn exit_code(
+    result: failure::Result<()>,
+    flushed: std::io::Result<()>,
+    stdout_closed: bool,
+) -> ExitCode {
+    let result = result.map_err(|failure| {
+        if stdout_closed && failure.broken_pipe {
+            failure.closed_stdout()
+        } else {
+            failure
+        }
+    });
     match result {
         Ok(()) => match flushed {
             Ok(()) => ExitCode::SUCCESS,
-            // `hodeishield vendors list | head` closes the pipe early: that is not an error.
-            Err(e) if e.kind() == ErrorKind::BrokenPipe => ExitCode::SUCCESS,
+            Err(e) if stdout_closed && e.kind() == std::io::ErrorKind::BrokenPipe => {
+                ExitCode::SUCCESS
+            }
             Err(e) => {
                 eprintln!("error: {e}");
                 ExitCode::FAILURE
             }
         },
-        Err(failure) if failure.message.contains("Broken pipe") => ExitCode::SUCCESS,
+        // Decided where standard output is written, never on message text (which can come from
+        // the API) nor on the kind of an error from somewhere else.
+        Err(failure) if failure.closed_pipe => ExitCode::SUCCESS,
         Err(failure) => {
             // Messages can carry text from the API or the app: clean it like any other output.
             eprintln!("error: {}", output::clean(&failure.message));
@@ -55,3 +84,57 @@ pub fn main() -> ExitCode {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Error, ErrorKind};
+
+    fn is_success(code: ExitCode) -> bool {
+        format!("{code:?}") == format!("{:?}", ExitCode::SUCCESS)
+    }
+
+    #[test]
+    fn a_closed_standard_output_exits_0() {
+        let failure = failure::Failure::from(Error::from(ErrorKind::BrokenPipe));
+        assert!(is_success(exit_code(Err(failure), Ok(()), true)));
+        let flush = Err(Error::from(ErrorKind::BrokenPipe));
+        assert!(is_success(exit_code(Ok(()), flush, true)));
+    }
+
+    #[test]
+    fn a_broken_pipe_from_somewhere_else_is_a_failure() {
+        // A socket, a file or a config write failing with a broken pipe is not a closed reader.
+        let failure = failure::Failure::from(Error::from(ErrorKind::BrokenPipe));
+        assert!(!is_success(exit_code(Err(failure), Ok(()), false)));
+        let flush = Err(Error::from(ErrorKind::BrokenPipe));
+        assert!(!is_success(exit_code(Ok(()), flush, false)));
+    }
+
+    #[test]
+    fn another_failure_after_standard_output_closed_is_still_a_failure() {
+        let failure = failure::Failure::general("the API said no");
+        assert!(!is_success(exit_code(Err(failure), Ok(()), true)));
+        let flush = Err(Error::from(ErrorKind::StorageFull));
+        assert!(!is_success(exit_code(Ok(()), flush, true)));
+    }
+
+    #[test]
+    fn tracked_output_notices_only_a_broken_pipe() {
+        struct Failing(ErrorKind);
+        impl Write for Failing {
+            fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
+                Err(Error::from(self.0))
+            }
+            fn flush(&mut self) -> std::io::Result<()> {
+                Err(Error::from(self.0))
+            }
+        }
+        let mut other = output::Tracked::new(Failing(ErrorKind::PermissionDenied));
+        assert!(other.write_all(b"x").is_err());
+        assert!(!other.closed());
+        let mut closed = output::Tracked::new(Failing(ErrorKind::BrokenPipe));
+        assert!(closed.write_all(b"x").is_err());
+        assert!(closed.closed());
+    }
+}
diff --git a/crates/hodeishield-cli/src/output.rs b/crates/hodeishield-cli/src/output.rs
index 3069868..b4e3ee2 100644
--- a/crates/hodeishield-cli/src/output.rs
+++ b/crates/hodeishield-cli/src/output.rs
@@ -10,6 +10,47 @@ use comfy_table::{ContentArrangement, Table, presets};
 use serde_json::Value;
 use std::io::Write;
 
+/// Standard output (or any writer) that remembers whether a write or flush failed with
+/// [`std::io::ErrorKind::BrokenPipe`], so the caller can tell "the reader of standard output went
+/// away" from a broken pipe anywhere else (a socket, a file), which must stay a failure.
+pub struct Tracked<W> {
+    inner: W,
+    closed: bool,
+}
+
+impl<W> Tracked<W> {
+    pub fn new(inner: W) -> Self {
+        Self {
+            inner,
+            closed: false,
+        }
+    }
+
+    /// Whether a write or flush hit a closed pipe.
+    pub fn closed(&self) -> bool {
+        self.closed
+    }
+
+    fn note<T>(&mut self, result: std::io::Result<T>) -> std::io::Result<T> {
+        if let Err(e) = &result {
+            self.closed |= e.kind() == std::io::ErrorKind::BrokenPipe;
+        }
+        result
+    }
+}
+
+impl<W: Write> Write for Tracked<W> {
+    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+        let result = self.inner.write(buf);
+        self.note(result)
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        let result = self.inner.flush();
+        self.note(result)
+    }
+}
+
 /// Replaces control characters (escape sequences, carriage returns, …) with `�`.
 pub fn clean(text: &str) -> String {
     text.chars()
@@ -18,7 +59,20 @@ pub fn clean(text: &str) -> String {
 }
 
 /// Control characters (C0, DEL, C1) and the invisible or direction-changing format characters that
-/// can make text display as something it is not.
+/// can make text display as something it is not:
+///
+/// - U+00AD, U+061C, U+180E, U+200B..U+200F, U+202A..U+202E, U+2060..U+2064, U+2066..U+2069,
+///   U+FEFF and U+FFF9..U+FFFB: soft hyphen, zero-width and direction marks and embeddings,
+///   isolates, the word joiner and invisible operators, the zero-width no-break space and the
+///   interlinear annotation anchors, which hide text or reorder it.
+/// - U+2028 and U+2029: the line and paragraph separators, which some terminals and viewers treat
+///   as a line break although `\n` is what the caller checked for.
+/// - U+206A..U+206F: the deprecated format characters (symmetric swapping, Arabic shaping, digit
+///   shapes), which are invisible and which bidi-aware renderers still act on. With U+2066..U+2069
+///   they form one range; U+2065 is unassigned and stays out.
+/// - U+E0000..U+E0FFF: the tag characters and the variation selectors supplement (U+E0100..U+E01EF)
+///   inside the invisible block, which can carry hidden text. The variation selectors U+FE00..U+FE0F
+///   are left alone on purpose: U+FE0F selects the emoji presentation of visible text.
 fn is_unsafe(c: char) -> bool {
     c.is_control()
         || matches!(
@@ -27,11 +81,14 @@ fn is_unsafe(c: char) -> bool {
                 | '\u{061c}'
                 | '\u{180e}'
                 | '\u{200b}'..='\u{200f}'
+                | '\u{2028}'
+                | '\u{2029}'
                 | '\u{202a}'..='\u{202e}'
                 | '\u{2060}'..='\u{2064}'
-                | '\u{2066}'..='\u{2069}'
+                | '\u{2066}'..='\u{206f}'
                 | '\u{feff}'
                 | '\u{fff9}'..='\u{fffb}'
+                | '\u{e0000}'..='\u{e0fff}'
         )
 }
 
@@ -65,6 +122,58 @@ pub fn short_time(value: Option<&str>) -> String {
     }
 }
 
+/// A table's header and rows, before they are laid out: what a command knows how to say about its
+/// items. [`tenant_table`] adds the client column when a list spans tenants.
+#[derive(Debug)]
+pub struct Rows {
+    pub headers: &'static [&'static str],
+    pub rows: Vec<Vec<String>>,
+}
+
+impl Rows {
+    pub fn new(headers: &'static [&'static str], rows: Vec<Vec<String>>) -> Self {
+        Self { headers, rows }
+    }
+
+    pub fn into_table(self) -> Table {
+        table(self.headers, self.rows)
+    }
+}
+
+/// What leads a row of a multi-tenant table. A slug made only of `[a-z0-9-]` is shown as it is. Any
+/// other slug (it may hold look-alike letters, so that two tenants would read the same) is shown
+/// with the start of the tenant's id, which differs. `--json` and `--csv` carry the full values.
+pub fn tenant_label(slug: &str, id: &str) -> String {
+    let plain = !slug.is_empty()
+        && slug
+            .bytes()
+            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-');
+    if plain {
+        slug.to_owned()
+    } else {
+        let short: String = id.chars().take(8).collect();
+        format!("{} [{}]", clean(slug), clean(&short))
+    }
+}
+
+/// Rows of several client tenants in one table, each led by the tenant's slug (see
+/// [`tenant_label`]). The text is the server's, so it is sanitised like every other cell.
+pub fn tenant_table(headers: &[&str], groups: Vec<(String, String, Vec<Vec<String>>)>) -> Table {
+    let mut all = vec!["TENANT"];
+    all.extend_from_slice(headers);
+    let rows = groups
+        .into_iter()
+        .flat_map(|(slug, id, rows)| {
+            let label = tenant_label(&slug, &id);
+            rows.into_iter().map(move |mut row| {
+                row.insert(0, label.clone());
+                row
+            })
+        })
+        .collect();
+    table(&all, rows)
+}
+
 pub fn table(headers: &[&str], rows: Vec<Vec<String>>) -> Table {
     let mut table = Table::new();
     table
@@ -158,7 +267,7 @@ pub fn print_csv(out: &mut dyn Write, items: &[Value]) -> std::io::Result<()> {
     if columns.is_empty() {
         return Ok(());
     }
-    let header: Vec<String> = columns.iter().map(|c| csv_field(&defuse(c))).collect();
+    let header: Vec<String> = columns.iter().map(|c| csv_field(&csv_text(c))).collect();
     write!(out, "{}\r\n", header.join(","))?;
     for item in items {
         let record: Vec<String> = columns
@@ -177,26 +286,15 @@ fn csv_cell(value: Option<&Value>) -> String {
         None | Some(Value::Null) => String::new(),
         Some(Value::Number(n)) => n.to_string(),
         Some(Value::Bool(b)) => b.to_string(),
-        Some(Value::String(s)) => defuse(s),
-        Some(other) => defuse(&other.to_string()),
+        Some(Value::String(s)) => csv_text(s),
+        Some(other) => csv_text(&other.to_string()),
     }
 }
 
-/// A spreadsheet runs a cell that starts with `=`, `+`, `-` or `@` (and, in some, a tab or carriage
-/// return) as a formula; a leading `'` makes it text (CWE-1236). Numbers never pass through here, so
-/// `-5` stays a number.
-fn defuse(text: &str) -> String {
-    if text.starts_with(['=', '+', '-', '@', '\t', '\r']) {
-        format!("'{text}")
-    } else {
-        text.to_owned()
-    }
-}
-
-/// One RFC 4180 field: quoted when it holds a comma, a quote, a line break or a leading or trailing
-/// space, with quotes doubled. Tabs and line breaks are kept; every other character [`clean`]
-/// replaces is replaced here too, as the file may well be printed to a terminal.
-fn csv_field(text: &str) -> String {
+/// Text for a CSV field, in the form it will be written: every character [`clean`] replaces is
+/// replaced here too (tabs and line breaks are kept), as the file may well be printed to a terminal,
+/// and only then is the result checked by [`defuse`], so the decision is made on what is written.
+fn csv_text(text: &str) -> String {
     let text: String = text
         .chars()
         .map(|c| {
@@ -207,10 +305,36 @@ fn csv_field(text: &str) -> String {
             }
         })
         .collect();
+    defuse(&text)
+}
+
+/// A spreadsheet runs a cell whose first character is `=`, `+`, `-` or `@` (and, in some, a tab or
+/// carriage return) as a formula, and some trim leading whitespace first, so the first character
+/// after any Unicode whitespace (spaces, no-break space, line breaks, …) counts too, as do the
+/// full-width forms `＝`, `＋`, `－` and `＠`, which some applications fold to the ASCII ones. A
+/// leading `'` makes the cell text (CWE-1236). Numbers never pass through here, so `-5` stays a
+/// number.
+fn defuse(text: &str) -> String {
+    let first = text.trim_start_matches(char::is_whitespace).chars().next();
+    if text.starts_with(['\t', '\r'])
+        || matches!(
+            first,
+            Some('=' | '+' | '-' | '@' | '\u{ff1d}' | '\u{ff0b}' | '\u{ff0d}' | '\u{ff20}')
+        )
+    {
+        format!("'{text}")
+    } else {
+        text.to_owned()
+    }
+}
+
+/// One RFC 4180 field: quoted when it holds a comma, a quote, a line break or a leading or trailing
+/// space, with quotes doubled.
+fn csv_field(text: &str) -> String {
     if text.contains([',', '"', '\r', '\n']) || text.starts_with(' ') || text.ends_with(' ') {
         format!("\"{}\"", text.replace('"', "\"\""))
     } else {
-        text
+        text.to_owned()
     }
 }
 
@@ -257,12 +381,49 @@ mod tests {
         );
     }
 
+    #[test]
+    fn separators_format_characters_and_tags_are_replaced() {
+        for c in [
+            '\u{2028}',
+            '\u{2029}',
+            '\u{206a}',
+            '\u{206f}',
+            '\u{feff}',
+            '\u{fff9}',
+            '\u{fffa}',
+            '\u{fffb}',
+            '\u{e0000}',
+            '\u{e0041}',
+            '\u{e007f}',
+            '\u{e0100}',
+            '\u{e01ef}',
+            '\u{e0fff}',
+        ] {
+            assert_eq!(
+                clean(&format!("a{c}b")),
+                "a\u{fffd}b",
+                "U+{:04X}",
+                u32::from(c)
+            );
+        }
+        // The neighbours of the ranges are visible or unassigned text and stay as they are.
+        let kept = "\u{2027}\u{202f}\u{2065}\u{2070}\u{fe0f}\u{e1000}";
+        assert_eq!(clean(kept), kept);
+        assert_eq!(
+            clean("caf\u{e9} \u{1f600} \u{4e2d}"),
+            "caf\u{e9} \u{1f600} \u{4e2d}"
+        );
+    }
+
     #[test]
     fn json_escapes_what_could_drive_the_terminal_without_changing_the_value() {
-        let value = serde_json::json!({"name": "a\u{9b}31m\u{7f}\u{202e}b\u{1b}"});
+        let value = serde_json::json!({"name": "a\u{9b}31m\u{7f}\u{202e}b\u{1b}\u{e0041}\u{2028}"});
         let mut out = Vec::new();
         print_json(&mut out, &value).expect("print");
         let text = String::from_utf8(out).expect("utf8");
+        // A tag character outside the BMP is escaped as a surrogate pair.
+        assert!(text.contains("\\udb40\\udc41"), "{text:?}");
+        assert!(text.contains("\\u2028"), "{text:?}");
         assert!(text.chars().all(|c| !is_unsafe(c) || c == '\n'), "{text:?}");
         let back: Value = serde_json::from_str(&text).expect("still JSON");
         assert_eq!(back, value);
@@ -308,6 +469,51 @@ mod tests {
         );
     }
 
+    #[test]
+    fn a_tenant_column_leads_each_row_and_is_sanitised() {
+        let t = tenant_table(
+            &["ID"],
+            vec![
+                (
+                    "acme".to_owned(),
+                    "11111111-0000".to_owned(),
+                    vec![vec!["1".into()]],
+                ),
+                (
+                    "ev\u{1b}il".to_owned(),
+                    "22222222-0000".to_owned(),
+                    vec![vec!["2".into()], vec!["3".into()]],
+                ),
+            ],
+        );
+        let mut out = Vec::new();
+        print_table(&mut out, &t).expect("print");
+        let text = String::from_utf8(out).expect("utf8");
+        let lines: Vec<&str> = text.lines().collect();
+        assert!(
+            lines[0].starts_with("TENANT") && lines[0].ends_with("ID"),
+            "{text}"
+        );
+        assert!(
+            lines[1].starts_with("acme") && lines[1].ends_with('1'),
+            "{text}"
+        );
+        assert!(lines[2].starts_with("ev\u{fffd}il [22222222]"), "{text:?}");
+        assert!(!text.contains('\u{1b}'));
+    }
+
+    #[test]
+    fn only_plain_slugs_stand_alone_in_the_tenant_column() {
+        let id = "0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e";
+        assert_eq!(tenant_label("acme-2", id), "acme-2");
+        // Cyrillic "а" (U+0430) looks like Latin "a"; the id tells the tenants apart.
+        assert_eq!(tenant_label("\u{430}cme", id), "\u{430}cme [0b8f2a52]");
+        assert_eq!(tenant_label("Acme", id), "Acme [0b8f2a52]");
+        assert_eq!(tenant_label("ac me", id), "ac me [0b8f2a52]");
+        assert_eq!(tenant_label("", id), " [0b8f2a52]");
+        assert_ne!(tenant_label("acme", id), tenant_label("\u{430}cme", id));
+    }
+
     #[test]
     fn tables_have_no_trailing_spaces() {
         let t = table(
@@ -364,6 +570,23 @@ mod tests {
             "'=1+1,'+1,'-1,'@SUM(A1),'\tx,\"'\rx\",-5,\"[\"\"=x\"\"]\",a=b\r\n"
         );
         assert!(csv(&serde_json::json!([{"=bad": 1}])).starts_with("'=bad\r\n"));
+        assert!(csv(&serde_json::json!([{" =bad": 1}])).starts_with("' =bad\r\n"));
+        assert!(csv(&serde_json::json!([{"\u{a0}@bad": 1}])).starts_with("'\u{a0}@bad\r\n"));
+    }
+
+    #[test]
+    fn csv_defuses_formulas_after_leading_whitespace() {
+        let text = csv(&serde_json::json!([{
+            "space": " =1+1", "spaces": "  @SUM(A1)", "nbsp": "\u{a0}=cmd", "em": "\u{2003}+1",
+            "nel": "\u{85}-1", "zw": "\u{200b}=x", "wide": " \u{ff1d}1", "wideplus": "\u{ff0b}1",
+            "widedash": "\u{ff0d}1", "wideat": "\u{3000}\u{ff20}x", "lf": "\n=x", "mixed": " \t -2",
+            "plain": " a=b", "only": "   ", "dash": " - note", "ok": "a =b"
+        }]));
+        let record = text.split_once("\r\n").expect("header").1;
+        assert_eq!(
+            record,
+            "' =1+1,'  @SUM(A1),'\u{a0}=cmd,'\u{2003}+1,\u{fffd}-1,\u{fffd}=x,' \u{ff1d}1,'\u{ff0b}1,'\u{ff0d}1,'\u{3000}\u{ff20}x,\"'\n=x\",' \t -2,\" a=b\",\"   \",' - note,a =b\r\n"
+        );
     }
 
     #[test]
diff --git a/crates/hodeishield-cli/src/update_check.rs b/crates/hodeishield-cli/src/update_check.rs
new file mode 100644
index 0000000..0957494
--- /dev/null
+++ b/crates/hodeishield-cli/src/update_check.rs
@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The notice that a newer release exists.
+//!
+//! The interface is one function, [`notify`], called once after a command has finished and its
+//! output has been flushed. It decides, asks and prints; the caller learns nothing and nothing can
+//! fail: every error is dropped (logged with `--verbose`).
+//!
+//! What it does, and the conditions that bound it:
+//!
+//! - one unauthenticated `GET` to GitHub's public "latest release" endpoint of this repository,
+//!   with a 2 second limit and only the `User-Agent` (`hodeishield-cli/<version>`) and `Accept`
+//!   headers: no API key, token, profile, tenant or machine identifier;
+//! - at most once in 24 hours, remembered in `update-check.json` next to the configuration file
+//!   (the attempt is recorded even when it fails, so a slow network costs the 2 seconds once a day);
+//! - only when standard error is a terminal, the run prints nothing for programs (`--json`,
+//!   `--csv`, `completions`), `CI` is unset, and neither `HODEISHIELD_NO_UPDATE_CHECK` nor
+//!   `update_check = false` in the configuration file opts out;
+//! - the notice is one line on standard error, shown on the run that made the query.
+//!
+//! Two variables exist for the test suite and are not documented to users:
+//! `HODEISHIELD_UPDATE_CHECK_URL` replaces the endpoint (honoured only for a loopback address, so
+//! it can never send the request anywhere else) and `HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL`
+//! stands in for a terminal on standard error.
+
+use serde::{Deserialize, Serialize};
+use std::io::IsTerminal;
+use std::path::Path;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+use url::Url;
+
+const LATEST_RELEASE: &str =
+    "https://api.github.com/repos/Hodeitek/hodeishield-cli/releases/latest";
+const RELEASES_PAGE: &str = "https://github.com/Hodeitek/hodeishield-cli/releases";
+const INTERVAL_SECS: u64 = 24 * 60 * 60;
+const TIMEOUT: Duration = Duration::from_secs(2);
+const MAX_BODY_BYTES: u64 = 1024 * 1024;
+const CACHE_FILE: &str = "update-check.json";
+
+/// What is remembered between runs.
+#[derive(Debug, Serialize, Deserialize)]
+struct Cache {
+    /// Seconds since the Unix epoch of the last query, successful or not.
+    checked_at: u64,
+    /// The version the last successful query reported.
+    #[serde(default)]
+    latest: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct Release {
+    tag_name: String,
+}
+
+/// Prints the new-version notice when it is due and wanted. `for_programs` is true when this run
+/// printed machine-readable output.
+pub fn notify(for_programs: bool, verbose: bool) {
+    let log = |message: &str| {
+        if verbose {
+            eprintln!("update check: {message}");
+        }
+    };
+    if for_programs || !wanted() {
+        return;
+    }
+    let Ok(config_path) = crate::config::path() else {
+        return;
+    };
+    match crate::config::load(&config_path) {
+        Ok(config) if config.update_check != Some(false) => {}
+        _ => return,
+    }
+    let cache_path = config_path.with_file_name(CACHE_FILE);
+    let now = unix_now();
+    if read_cache(&cache_path).is_some_and(|c| now.saturating_sub(c.checked_at) < INTERVAL_SECS) {
+        log("checked less than 24 hours ago");
+        return;
+    }
+    let latest = match fetch_latest() {
+        Ok(version) => Some(version),
+        Err(reason) => {
+            log(&reason);
+            None
+        }
+    };
+    if let Err(e) = write_cache(
+        &cache_path,
+        &Cache {
+            checked_at: now,
+            latest: latest.clone(),
+        },
+    ) {
+        log(&format!("cannot write {}: {e}", cache_path.display()));
+    }
+    if let Some(latest) = latest.filter(|l| is_newer(l, env!("CARGO_PKG_VERSION"))) {
+        eprintln!(
+            "A newer version of hodeishield is available: {latest} (you have {}). See {RELEASES_PAGE}",
+            env!("CARGO_PKG_VERSION")
+        );
+    }
+}
+
+/// Interactive, not CI and not opted out by the environment.
+fn wanted() -> bool {
+    let set = |name: &str| std::env::var_os(name).is_some_and(|v| !v.is_empty());
+    let terminal =
+        std::io::stderr().is_terminal() || set("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL");
+    terminal && std::env::var_os("CI").is_none() && !set("HODEISHIELD_NO_UPDATE_CHECK")
+}
+
+fn endpoint() -> Url {
+    endpoint_for(
+        std::env::var("HODEISHIELD_UPDATE_CHECK_URL")
+            .ok()
+            .as_deref(),
+    )
+}
+
+fn endpoint_for(override_url: Option<&str>) -> Url {
+    override_url
+        .and_then(|v| Url::parse(v).ok())
+        .filter(hodeishield_api::is_loopback_host)
+        .unwrap_or_else(|| Url::parse(LATEST_RELEASE).expect("constant URL"))
+}
+
+fn fetch_latest() -> Result<String, String> {
+    let url = endpoint();
+    let mut builder = reqwest::blocking::Client::builder();
+    if hodeishield_api::is_loopback_host(&url) {
+        builder = builder.no_proxy();
+    }
+    let http = builder
+        .user_agent(format!("hodeishield-cli/{}", env!("CARGO_PKG_VERSION")))
+        .timeout(TIMEOUT)
+        .connect_timeout(TIMEOUT)
+        .redirect(reqwest::redirect::Policy::none())
+        .https_only(!hodeishield_api::is_loopback_host(&url))
+        .build()
+        .map_err(|e| format!("cannot start the HTTP client: {e}"))?;
+    let response = http
+        .get(url)
+        .header("Accept", "application/vnd.github+json")
+        .send()
+        .map_err(|e| format!("request failed: {e}"))?;
+    if !response.status().is_success() {
+        return Err(format!("the answer was HTTP {}", response.status()));
+    }
+    let body = hodeishield_api::read_body(response, MAX_BODY_BYTES).map_err(|e| e.to_string())?;
+    let release: Release = serde_json::from_slice(&body).map_err(|e| format!("bad answer: {e}"))?;
+    release_version(&release.tag_name)
+        .ok_or_else(|| "the release tag is not a plain version".to_owned())
+}
+
+/// The version a release tag stands for, as `major.minor.patch`. The tag comes from the network and
+/// is printed, so it is rebuilt from the parsed numbers: build metadata after a `+` is dropped by
+/// the parser and must not reach the terminal.
+fn release_version(tag: &str) -> Option<String> {
+    parse_version(tag).map(|(major, minor, patch)| format!("{major}.{minor}.{patch}"))
+}
+
+/// `1.2.3` or `v1.2.3` as numbers. Pre-releases (`1.2.3-rc.1`) are not versions to announce, so
+/// they are refused; build metadata (`+abc`) is ignored.
+fn parse_version(text: &str) -> Option<(u64, u64, u64)> {
+    let text = text.trim().trim_start_matches('v');
+    let text = text.split('+').next()?;
+    let mut parts = text.split('.');
+    let mut next = || parts.next()?.parse::<u64>().ok();
+    let version = (next()?, next()?, next()?);
+    parts.next().is_none().then_some(version)
+}
+
+fn is_newer(latest: &str, current: &str) -> bool {
+    match (parse_version(latest), parse_version(current)) {
+        (Some(latest), Some(current)) => latest > current,
+        _ => false,
+    }
+}
+
+fn unix_now() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.as_secs())
+}
+
+fn read_cache(path: &Path) -> Option<Cache> {
+    serde_json::from_slice(&std::fs::read(path).ok()?).ok()
+}
+
+fn write_cache(path: &Path, cache: &Cache) -> std::io::Result<()> {
+    if let Some(dir) = path.parent().filter(|d| !d.as_os_str().is_empty()) {
+        std::fs::create_dir_all(dir)?;
+    }
+    std::fs::write(path, serde_json::to_vec(cache)?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_printed_version_is_rebuilt_from_the_numbers() {
+        assert_eq!(release_version("v1.2.3").as_deref(), Some("1.2.3"));
+        assert_eq!(
+            release_version("v9.9.9+\u{9b}2J\u{202e}\u{1b}[31m").as_deref(),
+            Some("9.9.9")
+        );
+        assert_eq!(release_version("v1.2.3-rc.1"), None);
+    }
+
+    #[test]
+    fn versions_compare_as_numbers() {
+        assert!(is_newer("0.10.0", "0.9.9"));
+        assert!(is_newer("v1.0.0", "0.3.0"));
+        assert!(!is_newer("0.3.0", "0.3.0"));
+        assert!(!is_newer("0.2.9", "0.3.0"));
+    }
+
+    #[test]
+    fn only_a_loopback_address_can_replace_the_endpoint() {
+        assert_eq!(endpoint_for(None).as_str(), LATEST_RELEASE);
+        assert_eq!(
+            endpoint_for(Some("https://example.test/latest")).as_str(),
+            LATEST_RELEASE
+        );
+        assert_eq!(
+            endpoint_for(Some("http://127.0.0.1:8080/latest")).as_str(),
+            "http://127.0.0.1:8080/latest"
+        );
+    }
+
+    #[test]
+    fn prereleases_and_junk_are_not_announced() {
+        assert!(!is_newer("0.4.0-rc.1", "0.3.0"));
+        assert!(!is_newer("nightly", "0.3.0"));
+        assert!(!is_newer("0.4", "0.3.0"));
+        assert!(!is_newer("0.4.0.1", "0.3.0"));
+        assert_eq!(parse_version("0.4.0+build5"), Some((0, 4, 0)));
+    }
+}
diff --git a/crates/hodeishield-cli/tests/cli.rs b/crates/hodeishield-cli/tests/cli.rs
index cf26883..0875f97 100644
--- a/crates/hodeishield-cli/tests/cli.rs
+++ b/crates/hodeishield-cli/tests/cli.rs
@@ -183,6 +183,69 @@ fn a_missing_scope_exits_4_and_names_the_framework_scope() {
         .stderr(predicate::str::contains("request id: req_abc"));
 }
 
+#[test]
+fn an_api_message_that_says_broken_pipe_still_fails() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/risks/r1")
+        .with_status(404)
+        .with_body(
+            r#"{"error":{"code":"not_found","message":"Broken pipe","request_id":"req_bp"}}"#,
+        )
+        .create();
+    env.api(&server)
+        .args(["risks", "get", "r1"])
+        .assert()
+        .code(5)
+        .stderr(predicate::str::contains("error: Broken pipe"));
+}
+
+/// Unix only: the child gets a plain pipe and sees `EPIPE` once the reader is gone. Windows reports
+/// a closed pipe with other codes, and this suite cannot confirm that mapping there.
+#[cfg(unix)]
+#[test]
+fn a_closed_output_pipe_exits_0_silently() {
+    use std::io::Read;
+    use std::process::{Command, Stdio};
+
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let filler = "x".repeat(1000);
+    let items: Vec<String> = (0..1000)
+        .map(|i| vendor(&format!("v{i}"), &filler))
+        .collect();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(200)
+        .with_body(page(&items, 1, 1000, 1))
+        .create();
+    let mut child = Command::new(assert_cmd::cargo::cargo_bin("hodeishield"))
+        .args(["--json", "vendors", "list"])
+        .env_clear()
+        .env("HODEISHIELD_CONFIG", &env.config)
+        .env(
+            "DBUS_SESSION_BUS_ADDRESS",
+            "unix:path=/nonexistent/hodeishield-test",
+        )
+        .env("HODEISHIELD_API_KEY", KEY)
+        .env("HODEISHIELD_API_URL", server.url())
+        .env("NO_COLOR", "1")
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn");
+    // Read a little, then hang up while about a megabyte is still to come.
+    let mut stdout = child.stdout.take().expect("stdout");
+    let mut first = [0_u8; 16];
+    stdout.read_exact(&mut first).expect("first bytes");
+    drop(stdout);
+    let output = child.wait_with_output().expect("wait");
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    assert!(output.stderr.is_empty(), "{output:?}");
+}
+
 #[test]
 fn an_inactive_licence_exits_8_without_blaming_a_scope() {
     let env = Env::new();
@@ -382,100 +445,39 @@ fn config_profiles_round_trip() {
     assert!(text.contains("default_profile = \"staging\""), "{text}");
 }
 
+/// Without a reachable Secret Service (as in every test here) signing in is refused before the app
+/// is asked for anything. Only on Linux: elsewhere the real keychain would be consulted.
+#[cfg(all(unix, not(target_os = "macos")))]
 #[test]
-fn login_finds_the_sign_in_server_through_the_api_and_asks_for_the_scopes_it_needs() {
-    let env = Env::new();
-    let mut api = mockito::Server::new();
-    let mut app = mockito::Server::new();
-    let issuer = format!("{}/api/auth", app.url());
-    let resource = api
-        .mock("GET", "/.well-known/oauth-protected-resource")
-        .with_body(
-            serde_json::json!({ "resource": api.url(), "authorization_servers": [issuer] })
-                .to_string(),
-        )
-        .expect(1)
-        .create();
-    // RFC 8414 §3.1: the issuer's path goes after the well-known segment.
-    app.mock("GET", "/.well-known/oauth-authorization-server/api/auth")
-        .with_body(
-            serde_json::json!({
-                "issuer": issuer,
-                "token_endpoint": format!("{issuer}/oauth2/token"),
-                "device_authorization_endpoint": format!("{issuer}/device/code"),
-                "scopes_supported": ["supply_risk:read", "compliance.nis2:read", "radar:read", "offline_access"],
+fn login_is_refused_up_front_when_there_is_no_keychain_to_keep_the_session_in() {
+    for args in [&["login"][..], &["login", "--device"][..]] {
+        let env = Env::new();
+        let mut api = mockito::Server::new();
+        let mut app = mockito::Server::new();
+        let untouched: Vec<_> = [&mut api, &mut app]
+            .into_iter()
+            .flat_map(|server| {
+                ["GET", "POST"].map(|method| {
+                    server
+                        .mock(method, mockito::Matcher::Any)
+                        .expect(0)
+                        .create()
+                })
             })
-            .to_string(),
-        )
-        .create();
-    let device = app
-        .mock("POST", "/api/auth/device/code")
-        .match_body(mockito::Matcher::AllOf(vec![
-            mockito::Matcher::UrlEncoded("client_id".into(), "hodeishield-cli".into()),
-            mockito::Matcher::UrlEncoded(
-                "scope".into(),
-                "supply_risk:read compliance.nis2:read offline_access".into(),
-            ),
-        ]))
-        .with_body(
-            serde_json::json!({
-                "device_code": "dc",
-                "user_code": "ABCD-EFGH",
-                "verification_uri": format!("{}/device", app.url()),
-                "expires_in": 600,
-                "interval": 1,
-            })
-            .to_string(),
-        )
-        .expect(1)
-        .create();
-    // Denied at the end, so no token exists to store: on macOS and Windows the test would otherwise
-    // write to the machine's real keychain.
-    let token = app
-        .mock("POST", "/api/auth/oauth2/token")
-        .match_body(mockito::Matcher::UrlEncoded(
-            "client_id".into(),
-            "hodeishield-cli".into(),
-        ))
-        .with_status(400)
-        .with_body(r#"{"error":"access_denied"}"#)
-        .expect(1)
-        .create();
-    env.cmd()
-        .env("HODEISHIELD_API_URL", api.url())
-        .env("HODEISHIELD_APP_URL", app.url())
-        .args(["login", "--device"])
-        .assert()
-        .code(3)
-        .stderr(predicate::str::contains("ABCD-EFGH"))
-        .stderr(predicate::str::contains("denied"));
-    resource.assert();
-    device.assert();
-    token.assert();
-}
-
-#[test]
-fn login_says_clearly_when_the_app_does_not_offer_it() {
-    let env = Env::new();
-    let mut api = mockito::Server::new();
-    let mut app = mockito::Server::new();
-    api.mock("GET", "/.well-known/oauth-protected-resource")
-        .with_status(404)
-        .create();
-    app.mock("GET", mockito::Matcher::Regex("^/.well-known/".into()))
-        .with_status(404)
-        .expect(2)
-        .create();
-    env.cmd()
-        .env("HODEISHIELD_API_URL", api.url())
-        .env("HODEISHIELD_APP_URL", app.url())
-        .args(["login", "--device"])
-        .assert()
-        .code(1)
-        .stderr(predicate::str::contains(
-            "does not offer sign-in for the CLI yet",
-        ))
-        .stderr(predicate::str::contains("HODEISHIELD_API_KEY"));
+            .collect();
+        env.cmd()
+            .env("HODEISHIELD_API_URL", api.url())
+            .env("HODEISHIELD_APP_URL", app.url())
+            .args(args)
+            .assert()
+            .code(1)
+            .stdout(predicate::str::is_empty())
+            .stderr(predicate::str::contains("system keychain is not available"))
+            .stderr(predicate::str::contains("HODEISHIELD_API_KEY"));
+        for mock in &untouched {
+            mock.assert();
+        }
+    }
 }
 
 #[test]
@@ -709,3 +711,1387 @@ fn compliance_controls_csv() {
     assert!(stdout.contains("failing"), "{stdout}");
     assert_no_key(&output);
 }
+
+/// The vendored document lists no values for these filters, so they are sent exactly as typed,
+/// without a warning, and the command succeeds. (The warning itself is covered by the unit tests
+/// of `filters`, with operations that carry lists.)
+#[test]
+fn free_form_filters_are_sent_as_typed_without_a_warning() {
+    for (args, path, param, value) in [
+        (
+            &["vendors", "list", "--category", "Cloud Host"][..],
+            "/v1/vendors",
+            "category",
+            "Cloud Host",
+        ),
+        (
+            &["risks", "list", "--domain", "Cyber"],
+            "/v1/risks",
+            "domain",
+            "Cyber",
+        ),
+        (
+            &["risks", "list", "--status", "OPEN"],
+            "/v1/risks",
+            "status",
+            "OPEN",
+        ),
+        (
+            &[
+                "compliance",
+                "controls",
+                "--framework",
+                "nis2",
+                "--status",
+                "Covered",
+            ],
+            "/v1/compliance/controls",
+            "status",
+            "Covered",
+        ),
+    ] {
+        let env = Env::new();
+        let mut server = mockito::Server::new();
+        let mock = server
+            .mock("GET", path)
+            .match_query(mockito::Matcher::UrlEncoded(param.into(), value.into()))
+            .with_body(page(&[], 1, 0, 1))
+            .expect(1)
+            .create();
+        let output = env.api(&server).args(args).output().expect("run");
+        assert!(output.status.success(), "{args:?}: {output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(!stderr.contains("warning:"), "{args:?}: {stderr}");
+        mock.assert();
+    }
+}
+
+/// The vendored document lists the alert severities and deprecates some older ones: a value that
+/// is not listed, or a deprecated one, gets a warning and is still sent exactly as typed.
+#[test]
+fn listed_and_deprecated_severities_warn_and_are_sent_as_typed() {
+    for (value, expected) in [
+        ("high", None),
+        ("High", Some("did you mean `high`? Sending it anyway.")),
+        (
+            "alto",
+            Some(
+                "warning: `alto` is a deprecated value for --severity, accepted by the API until \
+                 2027-01-14; use `high`. Sending it as typed.",
+            ),
+        ),
+    ] {
+        let env = Env::new();
+        let mut server = mockito::Server::new();
+        let mock = server
+            .mock("GET", "/v1/alerts")
+            .match_query(mockito::Matcher::UrlEncoded(
+                "severity".into(),
+                value.into(),
+            ))
+            .with_body(page(&[], 1, 0, 1))
+            .expect(1)
+            .create();
+        let output = env
+            .api(&server)
+            .args(["alerts", "list", "--severity", value])
+            .output()
+            .expect("run");
+        assert!(output.status.success(), "{value}: {output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        match expected {
+            Some(warning) => assert!(stderr.contains(warning), "{value}: {stderr}"),
+            None => assert!(!stderr.contains("warning:"), "{value}: {stderr}"),
+        }
+        mock.assert();
+    }
+}
+
+// Client tenants, against a mock of the published portfolio contract (version 2026-10-16).
+
+/// The shape of a portfolio key: `hsp_`, 12 hex, `_`, 64 hex. Its secret part must never be shown.
+const PORTFOLIO_KEY: &str =
+    "hsp_3f2a9c0d1b4e_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+
+const ACME: &str = "11111111-1111-4111-8111-111111111111";
+const BETA: &str = "22222222-2222-4222-8222-222222222222";
+const OLD: &str = "33333333-3333-4333-8333-333333333333";
+
+fn tenant(id: &str, slug: &str, active: bool, licence: &str) -> String {
+    format!(
+        r#"{{"id":"{id}","name":"{slug} S.L.","slug":"{slug}","organization":{{"id":"o-{slug}","name":"{slug} Group"}},"internal":false,"active":{active},"licence_status":"{licence}"}}"#
+    )
+}
+
+fn portfolio(tenants: &[String]) -> String {
+    page(tenants, 1, tenants.len() as i64, 1)
+}
+
+fn mock_portfolio(server: &mut mockito::Server, tenants: &[String]) -> mockito::Mock {
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        // The API's default order is descending; the CLI asks for alphabetical.
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("sort".into(), "name".into()),
+            mockito::Matcher::UrlEncoded("order".into(), "asc".into()),
+        ]))
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(portfolio(tenants))
+        .create()
+}
+
+/// A vendor list for one tenant, confirmed the way the API confirms a selection.
+fn mock_vendors(server: &mut mockito::Server, tenant_id: &str, names: &[&str]) -> mockito::Mock {
+    let items: Vec<String> = names.iter().map(|n| vendor(&format!("v-{n}"), n)).collect();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", tenant_id)
+        .with_header("x-hs-tenant", tenant_id)
+        .with_body(page(&items, 1, items.len() as i64, 1))
+        .create()
+}
+
+fn two_clients() -> [String; 2] {
+    [
+        tenant(ACME, "acme", true, "in_force"),
+        tenant(BETA, "beta", true, "grace"),
+    ]
+}
+
+#[test]
+fn tenants_list_prints_the_portfolio_as_table_json_and_csv() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let listing = mock_portfolio(&mut server, &two_clients());
+    let table = env
+        .api(&server)
+        .args(["tenants", "list"])
+        .output()
+        .expect("run");
+    assert!(table.status.success(), "{table:?}");
+    let stdout = String::from_utf8_lossy(&table.stdout);
+    assert!(stdout.starts_with("SLUG"), "{stdout}");
+    assert!(
+        stdout.contains("acme") && stdout.contains(BETA) && stdout.contains("grace"),
+        "{stdout}"
+    );
+
+    let json = env
+        .api(&server)
+        .args(["tenants", "list", "--json"])
+        .output()
+        .expect("run");
+    let body: serde_json::Value = serde_json::from_slice(&json.stdout).expect("json");
+    assert_eq!(body["data"][1]["slug"], "beta");
+
+    let csv = env
+        .api(&server)
+        .args(["tenants", "list", "--csv"])
+        .output()
+        .expect("run");
+    assert!(String::from_utf8_lossy(&csv.stdout).starts_with("id,name,slug,"));
+    listing.expect_at_least(3).assert();
+}
+
+#[test]
+fn a_tenant_is_selected_by_slug_or_id_and_the_table_stays_as_it_was() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let beta = mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    for selector in ["beta", "BETA", BETA] {
+        let output = env
+            .api(&server)
+            .args(["--tenant", selector, "vendors", "list"])
+            .output()
+            .expect("run");
+        assert!(output.status.success(), "{selector}: {output:?}");
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        assert!(
+            stdout.starts_with("ID") && stdout.contains("Beta Hosting"),
+            "{stdout}"
+        );
+        assert!(
+            !stdout.contains("TENANT") && !stdout.contains("Acme"),
+            "{stdout}"
+        );
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(
+            stderr.contains(&format!("Client tenant: beta ({BETA})")),
+            "{stderr}"
+        );
+        assert_no_key(&output);
+    }
+    beta.expect(3).assert();
+    acme.expect(0).assert();
+}
+
+#[test]
+fn a_selected_tenant_with_json_is_the_api_body_unchanged() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let body = format!(r#"{{"data":{}}}"#, vendor("v-1", "Acme Hosting"));
+    server
+        .mock("GET", "/v1/vendors/v-1")
+        .match_header("x-hs-tenant", ACME)
+        .with_header("x-hs-tenant", ACME)
+        .with_body(&body)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "get", "v-1", "--json", "--tenant", "acme"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let shown: serde_json::Value = serde_json::from_slice(&output.stdout).expect("json");
+    assert_eq!(
+        shown,
+        serde_json::from_str::<serde_json::Value>(&body).expect("json")
+    );
+}
+
+#[test]
+fn all_tenants_labels_every_row_with_the_tenant_that_returned_it() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    mock_vendors(&mut server, ACME, &["Acme Hosting", "Shared Name"]);
+    mock_vendors(&mut server, BETA, &["Beta Hosting", "Shared Name"]);
+
+    let table = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(table.status.success(), "{table:?}");
+    let stdout = String::from_utf8_lossy(&table.stdout);
+    let lines: Vec<&str> = stdout.lines().collect();
+    assert!(
+        lines[0].starts_with("TENANT") && lines[0].contains("ID"),
+        "{stdout}"
+    );
+    assert_eq!(lines.len(), 5, "{stdout}");
+    let row = |name: &str, slug: &str| {
+        lines
+            .iter()
+            .any(|l| l.starts_with(slug) && l.contains(name))
+    };
+    assert!(
+        row("Acme Hosting", "acme") && row("Beta Hosting", "beta"),
+        "{stdout}"
+    );
+    assert!(
+        !row("Acme Hosting", "beta") && !row("Beta Hosting", "acme"),
+        "{stdout}"
+    );
+    assert!(String::from_utf8_lossy(&table.stderr).contains("4 vendors across 2 client tenants."));
+
+    let json = env
+        .api(&server)
+        .args(["--json", "vendors", "list", "--all-tenants"])
+        .output()
+        .expect("run");
+    let items: serde_json::Value = serde_json::from_slice(&json.stdout).expect("json");
+    let items = items.as_array().expect("array");
+    assert_eq!(items.len(), 4);
+    assert_eq!(items[0]["tenant_id"], ACME);
+    assert_eq!(items[0]["tenant_slug"], "acme");
+    assert_eq!(items[0]["name"], "Acme Hosting");
+    assert_eq!(items[0]["added_later"], 1, "unknown fields are kept");
+    assert_eq!(items[3]["tenant_slug"], "beta");
+
+    let csv = env
+        .api(&server)
+        .args(["vendors", "list", "--all-tenants", "--csv"])
+        .output()
+        .expect("run");
+    let text = String::from_utf8_lossy(&csv.stdout);
+    assert!(
+        text.starts_with("tenant_id,tenant_slug,tenant_name,id,"),
+        "{text}"
+    );
+    assert!(
+        text.contains(&format!("{BETA},beta,beta S.L.,v-Beta Hosting,")),
+        "{text}"
+    );
+}
+
+#[test]
+fn all_tenants_skips_inactive_clients_and_says_so() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant(ACME, "acme", true, "in_force"),
+            tenant(OLD, "old", false, "inactive"),
+        ],
+    );
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("Skipping 1 inactive client tenants"));
+}
+
+#[test]
+fn a_tenant_that_cannot_be_read_is_reported_and_the_command_still_fails() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r1","details":{"code":"LICENCE_INACTIVE","licence":"expired"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(8), "{output:?}");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("Acme Hosting"), "{stdout}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(stderr.contains("warning: client tenant beta"), "{stderr}");
+    assert!(
+        stderr.contains("Could not read 1 of 2 client tenants"),
+        "{stderr}"
+    );
+}
+
+#[test]
+fn a_client_outside_the_portfolio_fails_clearly_without_reading_any_data() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let data = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .expect(0)
+        .create();
+    for selector in ["stranger", "44444444-4444-4444-8444-444444444444"] {
+        let output = env
+            .api(&server)
+            .args(["vendors", "list", "--tenant", selector])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(5), "{selector}: {output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(
+            stderr.contains(&format!(
+                "No client tenant {selector} in this credential's portfolio."
+            )),
+            "{stderr}"
+        );
+        assert!(output.stdout.is_empty());
+    }
+    data.assert();
+}
+
+#[test]
+fn the_server_refusing_a_selected_client_is_not_found_too() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant in this credential's portfolio.","request_id":"r2"}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list", "--tenant", "acme"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("No such tenant"));
+}
+
+#[test]
+fn an_answer_that_does_not_confirm_the_client_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    // The server answers with the other client's confirmation.
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_header("x-hs-tenant", BETA)
+        .with_body(page(&[vendor("v1", "Beta Hosting")], 1, 1, 1))
+        .create();
+    for args in [&["--tenant", "acme"][..], &["--all-tenants"][..]] {
+        let output = env
+            .api(&server)
+            .args(args)
+            .args(["vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(1), "{args:?}: {output:?}");
+        assert!(output.stdout.is_empty(), "{output:?}");
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains("did not confirm the client tenant")
+        );
+    }
+}
+
+#[test]
+fn without_a_selection_nothing_changes_for_a_single_tenant_credential() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let listing = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .expect(0)
+        .create();
+    let vendors = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_body(page(&[vendor("v1", "Example Hosting")], 1, 1, 1))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.starts_with("ID") && !stdout.contains("TENANT"),
+        "{stdout}"
+    );
+    assert!(!String::from_utf8_lossy(&output.stderr).contains("Client tenant"));
+    listing.assert();
+    vendors.assert();
+}
+
+#[test]
+fn selecting_a_client_with_a_single_tenant_credential_explains_what_is_missing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r3"}}"#)
+        .create();
+    for args in [&["--tenant", "acme"][..], &["--all-tenants"][..]] {
+        let output = env
+            .api(&server)
+            .args(args)
+            .args(["vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(4), "{output:?}");
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(stderr.contains("portfolio:read"), "{stderr}");
+        assert!(stderr.contains("need a portfolio credential"), "{stderr}");
+    }
+    let output = env
+        .api(&server)
+        .args(["tenants", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+}
+
+#[test]
+fn a_portfolio_credential_without_a_selection_is_told_how_to_select() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(400)
+        .with_body(r#"{"error":{"code":"invalid_request","message":"X-HS-Tenant is required","request_id":"r4","details":{"code":"TENANT_REQUIRED"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1));
+    assert!(String::from_utf8_lossy(&output.stderr).contains("--all-tenants"));
+}
+
+#[test]
+fn tenant_names_from_the_server_cannot_drive_the_terminal() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[tenant(ACME, "ac\\u001b[2Jme", true, "in_force")],
+    );
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let all = format!(
+        "{}{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert!(!all.contains('\u{1b}'), "{all:?}");
+    assert!(all.contains("ac\u{fffd}[2Jme"), "{all:?}");
+}
+
+#[test]
+fn the_selection_is_refused_where_it_cannot_apply() {
+    let env = Env::new();
+    for args in [
+        &["--tenant", "acme", "--all-tenants", "vendors", "list"][..],
+        &["--tenant", "acme", "whoami"][..],
+        &["--all-tenants", "tenants", "list"][..],
+        &["--all-tenants", "vendors", "get", "v1"][..],
+        &["--all-tenants", "compliance", "posture", "nis2"][..],
+        &["--all-tenants", "vendors", "list", "--page", "2"][..],
+    ] {
+        let output = env.cmd().args(args).output().expect("run");
+        assert_eq!(output.status.code(), Some(2), "{args:?}: {output:?}");
+    }
+}
+
+/// Runs the CLI with a real-shaped portfolio key, so a leak of the secret part would show.
+fn portfolio_cmd(env: &Env, server: &mockito::Server) -> Command {
+    let mut cmd = env.cmd();
+    cmd.env("HODEISHIELD_API_KEY", PORTFOLIO_KEY)
+        .env("HODEISHIELD_API_URL", server.url());
+    cmd
+}
+
+fn assert_no_portfolio_secret(output: &std::process::Output) {
+    let all = format!(
+        "{}{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let secret = PORTFOLIO_KEY.rsplit('_').next().expect("secret part");
+    assert!(
+        !all.contains(secret),
+        "the key's secret part leaked:\n{all}"
+    );
+    assert!(!all.contains(PORTFOLIO_KEY), "the key leaked:\n{all}");
+}
+
+#[test]
+fn a_portfolio_key_in_its_published_format_is_sent_as_a_bearer_and_never_shown() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let bearer = format!("Bearer {PORTFOLIO_KEY}");
+    let listing = server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .match_header("authorization", bearer.as_str())
+        .with_body(portfolio(&two_clients()))
+        .create();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("authorization", bearer.as_str())
+        .match_header("x-hs-tenant", ACME)
+        .with_header("x-hs-tenant", ACME)
+        .with_body(page(&[vendor("v1", "Acme Hosting")], 1, 1, 1))
+        .create();
+    for args in [
+        &["tenants", "list"][..],
+        &["--tenant", "acme", "vendors", "list"][..],
+    ] {
+        let output = portfolio_cmd(&env, &server)
+            .args(args)
+            .output()
+            .expect("run");
+        assert!(output.status.success(), "{args:?}: {output:?}");
+        assert_no_portfolio_secret(&output);
+    }
+    // A refused key is reported without echoing it either.
+    let mut rejected = mockito::Server::new();
+    rejected
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .with_status(401)
+        .with_body(
+            r#"{"error":{"code":"unauthorized","message":"Invalid API key","request_id":"r"}}"#,
+        )
+        .create();
+    let output = portfolio_cmd(&env, &rejected)
+        .args(["tenants", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(3), "{output:?}");
+    assert_no_portfolio_secret(&output);
+    listing.expect_at_least(2).assert();
+}
+
+#[test]
+fn all_tenants_skips_what_is_not_readable_by_the_contract_rule() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let off = "55555555-5555-4555-8555-555555555555";
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant(ACME, "acme", true, "in_force"),
+            tenant(BETA, "beta", true, "grace"),
+            // Listed by the server, but a client reading them would get a 403.
+            tenant(OLD, "old", true, "inactive"),
+            tenant(off, "off", false, "in_force"),
+        ],
+    );
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let beta = mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("Skipping 2 inactive client tenants"),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains("2 vendors across 2 client tenants."),
+        "{stderr}"
+    );
+    acme.assert();
+    beta.assert();
+}
+
+#[test]
+fn an_api_that_does_not_offer_the_portfolio_says_so_with_its_own_exit_code() {
+    let env = Env::new();
+    for status in [404, 405] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .match_query(mockito::Matcher::Any)
+            .with_status(status)
+            .with_body(r#"{"error":{"code":"not_found","message":"Not found","request_id":"r"}}"#)
+            .create();
+        let data = server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .expect(0)
+            .create();
+        for args in [
+            &["tenants", "list"][..],
+            &["--tenant", "acme", "vendors", "list"][..],
+            &["--all-tenants", "vendors", "list"][..],
+        ] {
+            let output = env.api(&server).args(args).output().expect("run");
+            assert_eq!(
+                output.status.code(),
+                Some(7),
+                "{status} {args:?}: {output:?}"
+            );
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            assert!(
+                stderr.contains("does not offer portfolio access yet"),
+                "{stderr}"
+            );
+            assert!(output.stdout.is_empty());
+        }
+        data.assert();
+    }
+}
+
+#[test]
+fn a_rate_limit_stops_an_all_tenants_walk_and_names_its_scope() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    // A wait too long to sit out: the walk ends, and the second client is never asked.
+    let limited = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", ACME)
+        .with_status(429)
+        .with_header("retry-after", "600")
+        .with_body(r#"{"error":{"code":"rate_limited","message":"x","request_id":"r9","details":{"scope":"portfolio_key","limit":100,"window_seconds":60,"retry_after_seconds":600}}}"#)
+        .expect(1)
+        .create();
+    let second = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .expect(0)
+        .create();
+    let output = portfolio_cmd(&env, &server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(6), "{output:?}");
+    assert!(output.stdout.is_empty());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(stderr.contains("(limit: portfolio_key)"), "{stderr}");
+    assert!(stderr.contains("Try again in 600 s."), "{stderr}");
+    assert_no_portfolio_secret(&output);
+    limited.assert();
+    second.assert();
+}
+
+#[test]
+fn a_short_rate_limit_is_waited_out_and_the_walk_goes_on() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let limited = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", ACME)
+        .with_status(429)
+        .with_header("retry-after", "1")
+        .with_body(r#"{"error":{"code":"rate_limited","message":"x","request_id":"r9","details":{"scope":"portfolio_tenant","limit":60,"window_seconds":60,"retry_after_seconds":1}}}"#)
+        .expect(1)
+        .create();
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let beta = mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    limited.assert();
+    acme.assert();
+    beta.assert();
+}
+
+#[test]
+fn a_missing_data_scope_stops_the_walk_instead_of_failing_once_per_tenant() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let refused = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#)
+        .expect(1)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("supply_risk:read"));
+    refused.assert();
+}
+
+#[test]
+fn a_missing_scope_with_a_portfolio_key_hints_organisation_administrator() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#)
+        .create();
+    let output = portfolio_cmd(&env, &server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+    assert!(stderr.contains("organisation administrator"), "{stderr}");
+    assert!(!stderr.contains("tenant administrator"), "{stderr}");
+}
+
+#[test]
+fn a_missing_scope_with_a_regular_key_hints_tenant_administrator() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert_eq!(output.status.code(), Some(4), "{output:?}");
+    assert!(stderr.contains("tenant administrator"), "{stderr}");
+    assert!(!stderr.contains("organisation administrator"), "{stderr}");
+}
+
+#[test]
+fn a_deactivated_client_is_a_licence_refusal_not_a_missing_resource() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(403)
+        .with_body(r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"LICENCE_INACTIVE","licence":"tenant_inactive"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(8), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("The tenant is deactivated."));
+}
+
+#[test]
+fn a_tenant_the_server_does_not_know_gets_the_same_answer_as_one_it_hides() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant in this credential's portfolio.","request_id":"r2","details":{"code":"TENANT_NOT_FOUND"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("No such tenant in this credential's portfolio."),
+        "{stderr}"
+    );
+    assert!(stderr.contains("tenants list"), "{stderr}");
+}
+
+#[test]
+fn the_selector_errors_of_the_contract_are_explained() {
+    let env = Env::new();
+    for (code, expected) in [
+        ("TENANT_SELECTOR_NOT_SUPPORTED", "leave out --tenant"),
+        ("TENANT_HEADER_INVALID", "please report it"),
+    ] {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .with_status(400)
+            .with_body(format!(
+                r#"{{"error":{{"code":"invalid_request","message":"x","request_id":"r","details":{{"code":"{code}","parameter":"X-HS-Tenant"}}}}}}"#
+            ))
+            .create();
+        let output = env
+            .api(&server)
+            .args(["vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(1), "{code}: {output:?}");
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains(expected),
+            "{code}"
+        );
+    }
+}
+
+#[test]
+fn an_echo_in_the_wrong_form_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let mixed = "0B8F2A52-6A0E-4D5C-9D3E-1F2A3B4C5D6E";
+    mock_portfolio(&mut server, &[tenant(mixed, "acme", true, "in_force")]);
+    // The contract's echo is lowercase; capitals are not what an honest server sends.
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", mixed.to_ascii_lowercase().as_str())
+        .with_header("x-hs-tenant", mixed)
+        .with_body(page(&[vendor("v1", "Acme Hosting")], 1, 1, 1))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(output.stdout.is_empty());
+}
+
+// Review follow-ups.
+
+const STRANGE: &str = "44444444-4444-4444-8444-444444444444";
+
+/// A tenant with a free-form name and slug (quotes and non-ASCII letters included).
+fn tenant_named(id: &str, slug: &str, name: &str) -> String {
+    serde_json::json!({
+        "id": id,
+        "name": name,
+        "slug": slug,
+        "organization": {"id": "o", "name": "Group"},
+        "internal": false,
+        "active": true,
+        "licence_status": "in_force",
+    })
+    .to_string()
+}
+
+fn never_read(server: &mut mockito::Server) -> mockito::Mock {
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .expect(0)
+        .create()
+}
+
+#[test]
+fn an_unknown_licence_status_is_not_read_is_named_and_fails_the_command() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant(ACME, "acme", true, "in_force"),
+            tenant(OLD, "old", true, "inactive"),
+            tenant(STRANGE, "strange", true, "a_status_from_the_future"),
+        ],
+    );
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let strange = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", STRANGE)
+        .expect(0)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(stdout.contains("Acme Hosting"), "{stdout}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    // "inactive" is said of the inactive tenant only.
+    assert!(
+        stderr.contains("Skipping 1 inactive client tenants"),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains(
+            "warning: client tenant strange: licence status `a_status_from_the_future` is not known to this version; not read"
+        ),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains("Could not read 1 of 2 client tenants"),
+        "{stderr}"
+    );
+    acme.assert();
+    strange.assert();
+}
+
+#[test]
+fn a_walk_where_one_tenant_is_mismatched_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    // Beta is asked for and answers with Acme's confirmation.
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .with_header("x-hs-tenant", ACME)
+        .with_body(page(&[vendor("v9", "Acme Hosting")], 1, 1, 1))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(output.stdout.is_empty(), "{output:?}");
+}
+
+#[test]
+fn a_second_page_that_is_not_confirmed_prints_nothing() {
+    let env = Env::new();
+    for args in [
+        &["--tenant", "acme", "vendors", "list", "--all"][..],
+        &["--all-tenants", "vendors", "list", "--all"][..],
+    ] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(&mut server, &[tenant(ACME, "acme", true, "in_force")]);
+        let page_of = |n: i64, name: &str| page(&[vendor(&format!("v{n}"), name)], n, 120, 3);
+        for (n, echo) in [(1_i64, ACME), (2, BETA)] {
+            server
+                .mock("GET", "/v1/vendors")
+                .match_query(mockito::Matcher::UrlEncoded("page".into(), n.to_string()))
+                .match_header("x-hs-tenant", ACME)
+                .with_header("x-hs-tenant", echo)
+                .with_body(page_of(n, &format!("Item {n}")))
+                .create();
+        }
+        let output = env.api(&server).args(args).output().expect("run");
+        assert_eq!(output.status.code(), Some(1), "{args:?}: {output:?}");
+        assert!(output.stdout.is_empty(), "{args:?}: {output:?}");
+    }
+}
+
+#[test]
+fn a_walk_stops_with_nothing_on_stdout_when_a_later_tenant_fails() {
+    let env = Env::new();
+    let scope = r#"{"error":{"code":"forbidden","message":"x","request_id":"r","details":{"code":"INSUFFICIENT_SCOPE","missing":["supply_risk:read"]}}}"#;
+    let unauthorised = r#"{"error":{"code":"unauthorized","message":"x","request_id":"r"}}"#;
+    let down = r#"{"error":{"code":"unavailable","message":"x","request_id":"r"}}"#;
+    for (status, body, expected) in [(401, unauthorised, 3), (503, down, 7), (403, scope, 4)] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(&mut server, &two_clients());
+        mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+        server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .match_header("x-hs-tenant", BETA)
+            .with_status(status)
+            // A zero wait keeps the retries of the 503 quick.
+            .with_header("retry-after", "0")
+            .with_body(body)
+            .create();
+        let output = env
+            .api(&server)
+            .args(["--all-tenants", "vendors", "list"])
+            .output()
+            .expect("run");
+        assert_eq!(output.status.code(), Some(expected), "{status}: {output:?}");
+        assert!(output.stdout.is_empty(), "{status}: {output:?}");
+    }
+}
+
+#[test]
+fn tenant_labels_in_csv_cannot_run_as_formulas() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, "+cmd", r#"=HYPERLINK("http://example.invalid","x")"#),
+            tenant_named(BETA, "beta", "-2+3"),
+        ],
+    );
+    mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    mock_vendors(&mut server, BETA, &["Beta Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list", "--csv"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let text = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        text.contains(&format!(
+            "{ACME},'+cmd,\"'=HYPERLINK(\"\"http://example.invalid\"\",\"\"x\"\")\","
+        )),
+        "{text}"
+    );
+    assert!(text.contains(&format!("{BETA},beta,'-2+3,")), "{text}");
+    assert!(
+        !text.contains(",+cmd,") && !text.contains(",=HYPERLINK"),
+        "{text}"
+    );
+}
+
+#[test]
+fn slug_resolution_is_case_insensitive_and_never_guesses() {
+    let env = Env::new();
+    // Mixed-case input finds the slug.
+    let mut server = mockito::Server::new();
+    mock_portfolio(&mut server, &two_clients());
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let output = env
+        .api(&server)
+        .args(["--tenant", "AcMe", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    acme.assert();
+
+    // Two slugs that differ only in case are ambiguous.
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, "Acme", "One"),
+            tenant_named(BETA, "acme", "Two"),
+        ],
+    );
+    let data = never_read(&mut server);
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("More than one client tenant"));
+    assert!(output.stdout.is_empty());
+    data.assert();
+
+    // A slug with a Cyrillic "а" is not matched by the ASCII word.
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[tenant_named(ACME, "\u{430}cme", "Look-alike")],
+    );
+    let data = never_read(&mut server);
+    let output = env
+        .api(&server)
+        .args(["--tenant", "acme", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    data.assert();
+
+    // A slug shaped like a UUID that is also another tenant's id is ambiguous.
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, BETA, "Slug is an id"),
+            tenant_named(BETA, "beta", "Has that id"),
+        ],
+    );
+    let data = never_read(&mut server);
+    let output = env
+        .api(&server)
+        .args(["--tenant", BETA, "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("More than one client tenant"));
+    assert!(output.stdout.is_empty());
+    data.assert();
+}
+
+#[test]
+fn an_id_that_is_not_a_uuid_fails_before_any_data_request() {
+    let env = Env::new();
+    for args in [
+        &["--all-tenants", "vendors", "list"][..],
+        &["--tenant", "weird", "vendors", "list"][..],
+    ] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(
+            &mut server,
+            &[
+                tenant(ACME, "acme", true, "in_force"),
+                tenant("not-a-uuid", "weird", true, "in_force"),
+            ],
+        );
+        let data = never_read(&mut server);
+        let output = env.api(&server).args(args).output().expect("run");
+        assert_eq!(output.status.code(), Some(1), "{args:?}: {output:?}");
+        assert!(output.stdout.is_empty());
+        data.assert();
+    }
+}
+
+#[test]
+fn a_portfolio_key_without_a_selection_sends_no_tenant_header() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let required = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", mockito::Matcher::Missing)
+        .with_status(400)
+        .with_body(r#"{"error":{"code":"invalid_request","message":"X-HS-Tenant is required","request_id":"r4","details":{"code":"TENANT_REQUIRED"}}}"#)
+        .expect(1)
+        .create();
+    let output = portfolio_cmd(&env, &server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(1), "{output:?}");
+    assert!(String::from_utf8_lossy(&output.stderr).contains("--all-tenants"));
+    required.assert();
+}
+
+#[test]
+fn look_alike_slugs_are_told_apart_by_id_in_the_table_only() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    mock_portfolio(
+        &mut server,
+        &[
+            tenant_named(ACME, "acme", "Real"),
+            tenant_named(BETA, "\u{430}cme", "Look-alike"),
+        ],
+    );
+    mock_vendors(&mut server, ACME, &["Real Hosting"]);
+    mock_vendors(&mut server, BETA, &["Fake Hosting"]);
+    let table = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    let stdout = String::from_utf8_lossy(&table.stdout);
+    assert!(
+        stdout.lines().any(|l| l.starts_with("acme ")) && stdout.contains("\u{430}cme [22222222]"),
+        "{stdout}"
+    );
+    let json = env
+        .api(&server)
+        .args(["--json", "--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    let items: serde_json::Value = serde_json::from_slice(&json.stdout).expect("json");
+    assert_eq!(items[1]["tenant_slug"], "\u{430}cme");
+}
+
+#[test]
+fn a_tenant_listed_on_two_pages_is_read_once_and_a_changing_total_is_reported() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    for (n, items, total) in [
+        (
+            1_i64,
+            vec![
+                tenant(ACME, "acme", true, "in_force"),
+                tenant(BETA, "beta", true, "grace"),
+            ],
+            120,
+        ),
+        (2, vec![tenant(BETA, "beta", true, "grace")], 121),
+    ] {
+        server
+            .mock("GET", "/v1/portfolio/tenants")
+            .match_query(mockito::Matcher::UrlEncoded("page".into(), n.to_string()))
+            .with_body(page(&items, n, total, 2))
+            .create();
+    }
+    let acme = mock_vendors(&mut server, ACME, &["Acme Hosting"]);
+    let beta = server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .match_header("x-hs-tenant", BETA)
+        .with_header("x-hs-tenant", BETA)
+        .with_body(page(&[vendor("vb", "Beta Hosting")], 1, 1, 1))
+        .expect(1)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert!(output.status.success(), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("changed while they were listed (120, then 121)"),
+        "{stderr}"
+    );
+    assert!(
+        stderr.contains("2 vendors across 2 client tenants."),
+        "{stderr}"
+    );
+    acme.assert();
+    beta.assert();
+}
+
+#[test]
+fn a_404_with_a_portfolio_code_on_the_listing_is_not_taken_for_a_missing_feature() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/portfolio/tenants")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(r#"{"error":{"code":"not_found","message":"No such tenant","request_id":"r","details":{"code":"TENANT_NOT_FOUND"}}}"#)
+        .create();
+    let output = env
+        .api(&server)
+        .args(["--all-tenants", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(5), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        !stderr.contains("does not offer portfolio access"),
+        "{stderr}"
+    );
+}
+
+#[test]
+fn the_client_wording_of_a_tenant_rate_limit_needs_a_selected_client() {
+    let env = Env::new();
+    let limit = |scope: &str| {
+        format!(
+            r#"{{"error":{{"code":"rate_limited","message":"x","request_id":"r","details":{{"scope":"{scope}","retry_after_seconds":600}}}}}}"#
+        )
+    };
+    let wording = "own limit is used up";
+    // A single-tenant key, no selection: the previous message, with no client advice.
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(429)
+        .with_header("retry-after", "600")
+        .with_body(limit("tenant"))
+        .create();
+    let output = env
+        .api(&server)
+        .args(["vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(6), "{output:?}");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("(limit: tenant)") && !stderr.contains(wording),
+        "{stderr}"
+    );
+
+    // With a client selected, or for the portfolio's per-client limit, the advice is given.
+    for (scope, args) in [
+        ("tenant", &["--tenant", "acme", "vendors", "list"][..]),
+        (
+            "portfolio_tenant",
+            &["--tenant", "acme", "vendors", "list"][..],
+        ),
+        ("portfolio_tenant", &["vendors", "list"][..]),
+    ] {
+        let mut server = mockito::Server::new();
+        mock_portfolio(&mut server, &two_clients());
+        server
+            .mock("GET", "/v1/vendors")
+            .match_query(mockito::Matcher::Any)
+            .with_status(429)
+            .with_header("retry-after", "600")
+            .with_body(limit(scope))
+            .create();
+        let output = env.api(&server).args(args).output().expect("run");
+        assert_eq!(
+            output.status.code(),
+            Some(6),
+            "{scope} {args:?}: {output:?}"
+        );
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains(wording),
+            "{scope} {args:?}: {output:?}"
+        );
+    }
+}
diff --git a/crates/hodeishield-cli/tests/contract.rs b/crates/hodeishield-cli/tests/contract.rs
new file mode 100644
index 0000000..65ebd8b
--- /dev/null
+++ b/crates/hodeishield-cli/tests/contract.rs
@@ -0,0 +1,641 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The scripting surface, pinned.
+//!
+//! The README ("Stability") promises scripts four things: the exit codes 0 to 8, the shape of
+//! `--json` and `--csv` output, and which stream carries what. The tests here fail when any of
+//! them changes, so a breaking change is always a deliberate edit of an expectation below, together
+//! with a "Changed (scripting surface)" entry in the changelog.
+//!
+//! Everything runs the real binary against a mock `/v1`, offline, with a throw-away configuration
+//! file and without access to the keychain.
+
+use assert_cmd::Command;
+use serde_json::{Value, json};
+use std::path::PathBuf;
+use std::process::Output;
+
+const KEY: &str = "hsk_test_0123456789abcdef";
+
+struct Env {
+    _dir: tempfile::TempDir,
+    config: PathBuf,
+}
+
+impl Env {
+    fn new() -> Self {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let config = dir.path().join("config.toml");
+        Self { _dir: dir, config }
+    }
+
+    fn cmd(&self) -> Command {
+        let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+        for var in [
+            "HODEISHIELD_API_KEY",
+            "HODEISHIELD_API_URL",
+            "HODEISHIELD_APP_URL",
+            "HODEISHIELD_PROFILE",
+            "HODEISHIELD_OAUTH_CLIENT_ID",
+        ] {
+            cmd.env_remove(var);
+        }
+        cmd.env("HODEISHIELD_CONFIG", &self.config)
+            .env(
+                "DBUS_SESSION_BUS_ADDRESS",
+                "unix:path=/nonexistent/hodeishield-test",
+            )
+            .env("NO_COLOR", "1");
+        cmd
+    }
+
+    fn api(&self, url: &str, args: &[&str]) -> Output {
+        self.cmd()
+            .env("HODEISHIELD_API_KEY", KEY)
+            .env("HODEISHIELD_API_URL", url)
+            .args(args)
+            .output()
+            .expect("run")
+    }
+}
+
+fn out(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stdout).into_owned()
+}
+
+fn err(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stderr).into_owned()
+}
+
+// ---------------------------------------------------------------------------------------------
+// Exit codes
+// ---------------------------------------------------------------------------------------------
+
+/// Every exit code the README documents, with a command that ends in it.
+#[test]
+fn exit_code_contract() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let url = server.url();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_body(r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":1}}"#)
+        .create();
+    for (path, status, headers, body) in [
+        (
+            "/v1/alerts",
+            403,
+            vec![],
+            r#"{"error":{"code":"forbidden","message":"no","request_id":"r"}}"#,
+        ),
+        (
+            "/v1/risks",
+            404,
+            vec![],
+            r#"{"error":{"code":"not_found","message":"gone","request_id":"r"}}"#,
+        ),
+        (
+            "/v1/evidence",
+            429,
+            // Longer than the CLI is willing to wait, so it gives up at once.
+            vec![("retry-after", "3600")],
+            r#"{"error":{"code":"rate_limited","message":"slow down","request_id":"r"}}"#,
+        ),
+        (
+            "/v1/endpoints",
+            403,
+            vec![],
+            r#"{"error":{"code":"forbidden","message":"no","request_id":"r","details":{"code":"LICENCE_INACTIVE","licence":"none"}}}"#,
+        ),
+        (
+            "/v1/compliance/controls",
+            401,
+            vec![],
+            r#"{"error":{"code":"unauthorized","message":"bad","request_id":"r"}}"#,
+        ),
+    ] {
+        let mut mock = server
+            .mock("GET", path)
+            .match_query(mockito::Matcher::Any)
+            .with_status(status);
+        for (name, value) in headers {
+            mock = mock.with_header(name, value);
+        }
+        mock.with_body(body).create();
+    }
+
+    // Nothing listens on port 9 of the loopback interface.
+    let unreachable = "http://127.0.0.1:9";
+
+    struct Case {
+        code: i32,
+        meaning: &'static str,
+        run: Output,
+    }
+    let cases = [
+        Case {
+            code: 0,
+            meaning: "success",
+            run: env.api(&url, &["vendors", "list"]),
+        },
+        Case {
+            code: 1,
+            meaning: "error: invalid input",
+            run: env.api(&url, &["risks", "get", ".."]),
+        },
+        Case {
+            code: 2,
+            meaning: "invalid command line",
+            run: env.api(&url, &["vendors", "list", "--no-such-flag"]),
+        },
+        Case {
+            code: 3,
+            meaning: "not authenticated: the API rejected the key",
+            run: env.api(&url, &["compliance", "controls", "--framework", "nis2"]),
+        },
+        Case {
+            code: 4,
+            meaning: "missing scope",
+            run: env.api(&url, &["alerts", "list"]),
+        },
+        Case {
+            code: 5,
+            meaning: "not found",
+            run: env.api(&url, &["risks", "list"]),
+        },
+        Case {
+            code: 6,
+            meaning: "rate limited",
+            run: env.api(&url, &["evidence", "list"]),
+        },
+        Case {
+            code: 7,
+            meaning: "API unreachable",
+            run: env.api(unreachable, &["vendors", "list"]),
+        },
+        Case {
+            code: 8,
+            meaning: "licence not in force",
+            run: env.api(&url, &["endpoints", "list"]),
+        },
+    ];
+    for case in cases {
+        assert_eq!(
+            case.run.status.code(),
+            Some(case.code),
+            "exit code {} ({}): {:?}",
+            case.code,
+            case.meaning,
+            case.run
+        );
+        if case.code != 0 {
+            assert!(
+                case.run.stdout.is_empty(),
+                "exit code {} must leave stdout empty: {:?}",
+                case.code,
+                out(&case.run)
+            );
+        }
+    }
+}
+
+/// 3 also means "no credential at all", which needs no network.
+#[test]
+fn no_credential_exits_3() {
+    let env = Env::new();
+    let output = env
+        .cmd()
+        .args(["--api-url", "http://127.0.0.1:9", "vendors", "list"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(3), "{output:?}");
+    assert!(output.stdout.is_empty());
+}
+
+/// A server error (5xx) is exit code 7 as well, and says nothing on stdout.
+#[test]
+fn a_failing_api_exits_7() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .with_status(500)
+        .with_header("retry-after", "0")
+        .with_body(r#"{"error":{"code":"internal","message":"boom","request_id":"r"}}"#)
+        .expect_at_least(1)
+        .create();
+    let output = env.api(&server.url(), &["vendors", "list"]);
+    assert_eq!(output.status.code(), Some(7), "{output:?}");
+    assert!(output.stdout.is_empty());
+}
+
+// ---------------------------------------------------------------------------------------------
+// Fixtures: one item per resource, with every field the API describes and one it does not.
+// ---------------------------------------------------------------------------------------------
+
+struct Resource {
+    /// The command words before `list`.
+    command: &'static [&'static str],
+    /// Extra arguments the list needs.
+    list_args: &'static [&'static str],
+    path: &'static str,
+    /// An item as the API sends it, plus the unknown field `added_later`.
+    item: &'static str,
+    /// The CSV header: the item's fields, in the order the API sends them.
+    csv_header: &'static str,
+}
+
+const RESOURCES: [Resource; 5] = [
+    Resource {
+        command: &["vendors"],
+        list_args: &[],
+        path: "/v1/vendors",
+        item: r#"{"id":"v1","name":"Example Hosting","legal_name":null,"domain":"example.com","category":null,"vendor_type":null,"access_level":null,"business_criticality":"high","data_sensitivity":null,"economic_impact":null,"active":true,"monitoring_status":null,"last_scan_at":"2026-03-04T05:06:07.000Z","lei":null,"hq_country":null,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z","added_later":{"k":[1,2]}}"#,
+        csv_header: "id,name,legal_name,domain,category,vendor_type,access_level,business_criticality,data_sensitivity,economic_impact,active,monitoring_status,last_scan_at,lei,hq_country,created_at,updated_at,added_later",
+    },
+    Resource {
+        command: &["alerts"],
+        list_args: &[],
+        path: "/v1/alerts",
+        item: r#"{"id":"a1","vendor_id":"v1","type":"cve","severity":"high","title":"Example alert","description":null,"source_url":null,"economic_impact":null,"status":"open","acknowledged_at":null,"resolved_at":null,"resolution_reason":null,"created_at":"2026-01-01T00:00:00Z","added_later":"x"}"#,
+        csv_header: "id,vendor_id,type,severity,title,description,source_url,economic_impact,status,acknowledged_at,resolved_at,resolution_reason,created_at,added_later",
+    },
+    Resource {
+        command: &["risks"],
+        list_args: &[],
+        path: "/v1/risks",
+        item: r#"{"id":"r1","title":"Example risk","description":null,"domain":"operations","status":"identified","treatment":null,"treatment_notes":null,"threat_source":null,"vulnerability":null,"likelihood_inherent":3,"impact_inherent":4,"inherent_score":12,"likelihood_residual":null,"impact_residual":null,"residual_score":null,"source":"manual","owner_user_id":null,"vendor_id":null,"control_codes":["1.1","1.2"],"review_date":null,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z","added_later":true}"#,
+        csv_header: "id,title,description,domain,status,treatment,treatment_notes,threat_source,vulnerability,likelihood_inherent,impact_inherent,inherent_score,likelihood_residual,impact_residual,residual_score,source,owner_user_id,vendor_id,control_codes,review_date,created_at,updated_at,added_later",
+    },
+    Resource {
+        command: &["evidence"],
+        list_args: &[],
+        path: "/v1/evidence",
+        item: r#"{"id":"e1","evidence_type":"policy","source_type":"manual","source_id":"s1","title":"Example evidence","description":null,"vendor_id":null,"asset_id":null,"auto_generated":false,"valid_until":null,"created_at":"2026-01-01T00:00:00Z","added_later":7}"#,
+        csv_header: "id,evidence_type,source_type,source_id,title,description,vendor_id,asset_id,auto_generated,valid_until,created_at,added_later",
+    },
+    Resource {
+        command: &["endpoints"],
+        list_args: &[],
+        path: "/v1/endpoints",
+        item: r#"{"id":"n1","producer":"agent","producer_kind":"edr","status":"active","signature_alg":"ed25519","agent_version":"1.2.3","hostname":"host.example.test","enrolled_at":"2026-01-01T00:00:00Z","last_seen_at":null,"revoked_at":null,"added_later":null}"#,
+        csv_header: "id,producer,producer_kind,status,signature_alg,agent_version,hostname,enrolled_at,last_seen_at,revoked_at,added_later",
+    },
+];
+
+const CONTROLS: Resource = Resource {
+    command: &["compliance"],
+    list_args: &["--framework", "nis2"],
+    path: "/v1/compliance/controls",
+    item: r#"{"framework":"nis2","control_code":"1.1","status":"covered","evidence_count":5,"last_evaluated_at":null,"added_later":[]}"#,
+    csv_header: "framework,control_code,status,evidence_count,last_evaluated_at,added_later",
+};
+
+fn list_body(resource: &Resource) -> String {
+    format!(
+        r#"{{"data":[{}],"pagination":{{"page":1,"per_page":50,"total":1,"total_pages":1,"added_later":"p"}},"added_later_top":1}}"#,
+        resource.item
+    )
+}
+
+fn list_args(resource: &Resource, extra: &[&'static str]) -> Vec<&'static str> {
+    let mut args: Vec<&'static str> = Vec::new();
+    args.extend_from_slice(resource.command);
+    args.push(if resource.command == ["compliance"] {
+        "controls"
+    } else {
+        "list"
+    });
+    args.extend_from_slice(resource.list_args);
+    args.extend_from_slice(extra);
+    args
+}
+
+fn all_resources() -> impl Iterator<Item = &'static Resource> {
+    RESOURCES.iter().chain(std::iter::once(&CONTROLS))
+}
+
+// ---------------------------------------------------------------------------------------------
+// --json
+// ---------------------------------------------------------------------------------------------
+
+/// A list prints the API's body as it came: `data` and `pagination` at the top, in that order, and
+/// every field the CLI does not know passes through, at every level.
+#[test]
+fn json_list_is_the_api_body_with_unknown_fields_passed_through() {
+    let env = Env::new();
+    for resource in all_resources() {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", resource.path)
+            .match_query(mockito::Matcher::Any)
+            .with_body(list_body(resource))
+            .create();
+        let output = env.api(&server.url(), &list_args(resource, &["--json"]));
+        assert_eq!(
+            output.status.code(),
+            Some(0),
+            "{}: {output:?}",
+            resource.path
+        );
+        let text = out(&output);
+        let printed: Value = serde_json::from_str(&text).expect("json");
+        let sent: Value = serde_json::from_str(&list_body(resource)).expect("fixture");
+        assert_eq!(
+            printed, sent,
+            "{}: the body is passed through",
+            resource.path
+        );
+        let top: Vec<&String> = printed.as_object().expect("object").keys().collect();
+        assert_eq!(
+            top,
+            ["data", "pagination", "added_later_top"],
+            "{}: top-level keys and their order",
+            resource.path
+        );
+        assert!(text.starts_with("{\n  \"data\": [\n    {\n"), "{text}");
+        assert!(text.ends_with("}\n"), "one trailing newline: {text:?}");
+        assert!(
+            err(&output).is_empty(),
+            "{}: {}",
+            resource.path,
+            err(&output)
+        );
+    }
+}
+
+/// `--all --json` prints one array of every item (not a page), unchanged.
+#[test]
+fn json_all_is_an_array_of_the_items() {
+    let env = Env::new();
+    for resource in all_resources() {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", resource.path)
+            .match_query(mockito::Matcher::Any)
+            .with_body(list_body(resource))
+            .create();
+        let output = env.api(&server.url(), &list_args(resource, &["--json", "--all"]));
+        assert_eq!(
+            output.status.code(),
+            Some(0),
+            "{}: {output:?}",
+            resource.path
+        );
+        let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+        let sent: Value = serde_json::from_str(resource.item).expect("fixture");
+        assert_eq!(printed, Value::Array(vec![sent]), "{}", resource.path);
+    }
+}
+
+/// `get` prints the API's body, `{"data": {...}}`, with unknown fields.
+#[test]
+fn json_get_is_the_api_body_with_unknown_fields_passed_through() {
+    let env = Env::new();
+    for resource in &RESOURCES[..4] {
+        let name = resource.command[0];
+        let id = "x1";
+        let path = format!("{}/{id}", resource.path);
+        let body = format!(r#"{{"data":{},"added_later_top":1}}"#, resource.item);
+        let mut server = mockito::Server::new();
+        server.mock("GET", path.as_str()).with_body(&body).create();
+        let output = env.api(&server.url(), &["--json", name, "get", id]);
+        assert_eq!(output.status.code(), Some(0), "{name}: {output:?}");
+        let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+        assert_eq!(
+            printed,
+            serde_json::from_str::<Value>(&body).expect("fixture"),
+            "{name}"
+        );
+        let top: Vec<&String> = printed.as_object().expect("object").keys().collect();
+        assert_eq!(top, ["data", "added_later_top"], "{name}");
+    }
+}
+
+/// `compliance posture` prints the API's body, `{"data": {...}}`.
+#[test]
+fn json_posture_is_the_api_body_with_unknown_fields_passed_through() {
+    let env = Env::new();
+    let body = r#"{"data":{"framework":"nis2","controls_total":3,"by_status":{"covered":2,"missing":1},"evidence_total":9,"last_evaluated_at":null,"added_later":1}}"#;
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/compliance/frameworks/nis2")
+        .with_body(body)
+        .create();
+    let output = env.api(&server.url(), &["--json", "compliance", "posture", "nis2"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+    assert_eq!(
+        printed,
+        serde_json::from_str::<Value>(body).expect("fixture")
+    );
+}
+
+/// `whoami --json` is an object with these fields, in this order (an API key has no more).
+#[test]
+fn json_whoami_fields() {
+    let env = Env::new();
+    let server = mockito::Server::new();
+    let output = env.api(&server.url(), &["--json", "whoami"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    let printed: Value = serde_json::from_str(&out(&output)).expect("json");
+    let keys: Vec<&String> = printed.as_object().expect("object").keys().collect();
+    assert_eq!(keys, ["profile", "api_url", "app_url", "credential"]);
+    assert_eq!(printed["credential"], json!("api_key"));
+    assert_eq!(printed["api_url"], json!(format!("{}/", server.url())));
+}
+
+// ---------------------------------------------------------------------------------------------
+// --csv
+// ---------------------------------------------------------------------------------------------
+
+/// The header is the item's top-level fields in the order the API sends them, including a field
+/// the CLI does not know; the record follows, and both end in CRLF.
+#[test]
+fn csv_header_of_every_list_command() {
+    let env = Env::new();
+    for resource in all_resources() {
+        let mut server = mockito::Server::new();
+        server
+            .mock("GET", resource.path)
+            .match_query(mockito::Matcher::Any)
+            .with_body(list_body(resource))
+            .create();
+        let output = env.api(&server.url(), &list_args(resource, &["--csv"]));
+        assert_eq!(
+            output.status.code(),
+            Some(0),
+            "{}: {output:?}",
+            resource.path
+        );
+        let text = out(&output);
+        let (header, rest) = text.split_once("\r\n").expect("a CRLF-terminated header");
+        assert_eq!(header, resource.csv_header, "{}", resource.path);
+        assert!(rest.ends_with("\r\n"), "{}: {rest:?}", resource.path);
+        assert_eq!(rest.matches("\r\n").count(), 1, "one record: {rest:?}");
+        assert!(
+            !text.contains("\n\n") && !text.starts_with('\u{feff}'),
+            "{text:?}"
+        );
+        // Every line break is CRLF: removing those leaves no bare LF.
+        assert!(!text.replace("\r\n", "").contains('\n'), "{text:?}");
+    }
+}
+
+/// A full CSV document, character for character: the header, a record with every kind of value,
+/// the quoting of RFC 4180 and the guard that keeps a spreadsheet from running a cell as a formula.
+#[test]
+fn csv_document_snapshot() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/alerts")
+        .match_query(mockito::Matcher::Any)
+        .with_body(
+            r#"{"data":[
+{"id":"a1","vendor_id":"v","type":"cve","severity":"+high","title":"=1+1","description":"-x","source_url":"@SUM(A1)","economic_impact":-5,"status":"open","acknowledged_at":null,"resolved_at":null,"resolution_reason":null,"created_at":"2026-01-01T00:00:00Z"},
+{"id":"a2","vendor_id":"v","type":"cve","severity":"say \"hi\"","title":"plain, with comma","description":"two\nlines","source_url":" padded ","economic_impact":2.5,"status":"a=b","acknowledged_at":null,"resolved_at":null,"resolution_reason":null,"created_at":"2026-01-01T00:00:00Z"}
+],"pagination":{"page":1,"per_page":50,"total":2,"total_pages":1}}"#,
+        )
+        .create();
+    let output = env.api(&server.url(), &["alerts", "list", "--csv"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    assert_eq!(
+        out(&output),
+        "id,vendor_id,type,severity,title,description,source_url,economic_impact,status,\
+         acknowledged_at,resolved_at,resolution_reason,created_at\r\n\
+         a1,v,cve,'+high,'=1+1,'-x,'@SUM(A1),-5,open,,,,2026-01-01T00:00:00Z\r\n\
+         a2,v,cve,\"say \"\"hi\"\"\",\"plain, with comma\",\"two\nlines\",\" padded \",2.5,a=b,,,,2026-01-01T00:00:00Z\r\n"
+    );
+}
+
+/// No items: nothing on stdout (not even a header), a note on stderr.
+#[test]
+fn csv_without_items_prints_nothing() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/risks")
+        .match_query(mockito::Matcher::Any)
+        .with_body(r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":1}}"#)
+        .create();
+    let output = env.api(&server.url(), &["risks", "list", "--csv"]);
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    assert!(output.stdout.is_empty(), "{:?}", out(&output));
+    assert_eq!(err(&output), "No risks found.\n");
+}
+
+// ---------------------------------------------------------------------------------------------
+// Standard output and standard error
+// ---------------------------------------------------------------------------------------------
+
+/// Notes about paging go to stderr in every output format; stdout holds only the data.
+#[test]
+fn notes_go_to_stderr_and_data_to_stdout() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    let body = format!(
+        r#"{{"data":[{}],"pagination":{{"page":1,"per_page":1,"total":2,"total_pages":2}}}}"#,
+        RESOURCES[1].item
+    );
+    server
+        .mock("GET", "/v1/alerts")
+        .match_query(mockito::Matcher::Any)
+        .with_body(&body)
+        .create();
+
+    let table = env.api(&server.url(), &["alerts", "list"]);
+    assert_eq!(table.status.code(), Some(0), "{table:?}");
+    assert!(out(&table).starts_with("ID"), "{}", out(&table));
+    assert!(!out(&table).contains("Page 1 of 2"));
+    assert_eq!(
+        err(&table),
+        "Page 1 of 2 (2 alerts). Next: --page 2, or --all.\n"
+    );
+
+    for flag in ["--json", "--csv"] {
+        let output = env.api(&server.url(), &["alerts", "list", flag]);
+        assert_eq!(output.status.code(), Some(0), "{flag}: {output:?}");
+        assert!(!out(&output).contains("Page 1 of 2"), "{flag}");
+        if flag == "--json" {
+            serde_json::from_str::<Value>(&out(&output)).expect("stdout is only JSON");
+            assert!(
+                err(&output).is_empty(),
+                "no note beside JSON: {}",
+                err(&output)
+            );
+        } else {
+            assert_eq!(
+                err(&output),
+                "Page 1 of 2 (2 alerts). Next: --page 2, or --all.\n"
+            );
+        }
+    }
+}
+
+/// `--verbose` logs the requests to stderr and leaves stdout parseable.
+#[test]
+fn verbose_logging_never_reaches_stdout() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors/v1")
+        .with_body(format!(r#"{{"data":{}}}"#, RESOURCES[0].item))
+        .create();
+    let output = env.api(
+        &server.url(),
+        &["--verbose", "--json", "vendors", "get", "v1"],
+    );
+    assert_eq!(output.status.code(), Some(0), "{output:?}");
+    serde_json::from_str::<Value>(&out(&output)).expect("stdout is only JSON");
+    assert!(
+        err(&output).contains("GET http://127.0.0.1:"),
+        "{}",
+        err(&output)
+    );
+}
+
+/// An error writes nothing to stdout in any output format, and starts its stderr with `error: `.
+#[test]
+fn errors_write_to_stderr_only() {
+    let env = Env::new();
+    let mut server = mockito::Server::new();
+    server
+        .mock("GET", "/v1/vendors")
+        .match_query(mockito::Matcher::Any)
+        .with_status(404)
+        .with_body(
+            r#"{"error":{"code":"not_found","message":"Nothing here.","request_id":"req_1"}}"#,
+        )
+        .create();
+    for flag in ["--json", "--csv", ""] {
+        let mut args = vec!["vendors", "list"];
+        if !flag.is_empty() {
+            args.push(flag);
+        }
+        let output = env.api(&server.url(), &args);
+        assert_eq!(output.status.code(), Some(5), "{flag}: {output:?}");
+        assert!(output.stdout.is_empty(), "{flag}: {:?}", out(&output));
+        assert_eq!(
+            err(&output),
+            "error: Nothing here.\nrequest id: req_1\n",
+            "{flag}"
+        );
+    }
+}
+
+/// A usage error also leaves stdout empty.
+#[test]
+fn usage_errors_write_to_stderr_only() {
+    let env = Env::new();
+    let output = env
+        .cmd()
+        .args(["vendors", "frobnicate"])
+        .output()
+        .expect("run");
+    assert_eq!(output.status.code(), Some(2), "{output:?}");
+    assert!(output.stdout.is_empty(), "{:?}", out(&output));
+    assert!(!err(&output).is_empty());
+}
diff --git a/crates/hodeishield-cli/tests/update_check.rs b/crates/hodeishield-cli/tests/update_check.rs
new file mode 100644
index 0000000..e47e82c
--- /dev/null
+++ b/crates/hodeishield-cli/tests/update_check.rs
@@ -0,0 +1,311 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Hodeitek S.L.
+
+//! The new-version notice: when it appears, when it stays silent, and that it never costs a
+//! command its output or its exit code.
+//!
+//! The release endpoint is a mock on loopback (`HODEISHIELD_UPDATE_CHECK_URL`) and a terminal on
+//! standard error is simulated (`HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL`); both exist for these
+//! tests. The binary under test is version 0.x of this workspace, so `v99.0.0` is always newer.
+
+use assert_cmd::Command;
+use mockito::{Mock, Server};
+use std::path::PathBuf;
+use std::process::Output;
+
+const NOTICE: &str = "A newer version of hodeishield is available: 99.0.0";
+
+struct Env {
+    _dir: tempfile::TempDir,
+    config: PathBuf,
+}
+
+impl Env {
+    fn new() -> Self {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let config = dir.path().join("config.toml");
+        Self { _dir: dir, config }
+    }
+
+    fn cache(&self) -> PathBuf {
+        self.config.with_file_name("update-check.json")
+    }
+
+    /// A run that is not on a terminal, so it never asks: for changing the configuration.
+    fn quiet(&self, args: &[&str]) -> Output {
+        Command::cargo_bin("hodeishield")
+            .expect("binary")
+            .env("HODEISHIELD_CONFIG", &self.config)
+            .args(args)
+            .output()
+            .expect("run")
+    }
+
+    /// A run on an interactive terminal, against `release_url`.
+    fn run(&self, release_url: &str, args: &[&str]) -> Output {
+        let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+        for var in [
+            "CI",
+            "HODEISHIELD_NO_UPDATE_CHECK",
+            "HODEISHIELD_API_KEY",
+            "HODEISHIELD_API_URL",
+            "HODEISHIELD_PROFILE",
+        ] {
+            cmd.env_remove(var);
+        }
+        cmd.env("HODEISHIELD_CONFIG", &self.config)
+            .env("HODEISHIELD_UPDATE_CHECK_URL", release_url)
+            .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+            .env("NO_COLOR", "1")
+            .args(args)
+            .output()
+            .expect("run")
+    }
+}
+
+fn release(server: &mut Server, tag: &str) -> Mock {
+    server
+        .mock("GET", "/latest")
+        .match_header(
+            "user-agent",
+            concat!("hodeishield-cli/", env!("CARGO_PKG_VERSION")),
+        )
+        .with_body(format!(r#"{{"tag_name":"{tag}","draft":false}}"#))
+        .create()
+}
+
+fn url(server: &Server) -> String {
+    format!("{}/latest", server.url())
+}
+
+fn stderr(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stderr).into_owned()
+}
+
+fn stdout(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stdout).into_owned()
+}
+
+#[test]
+fn a_newer_release_is_announced_on_stderr_only() {
+    let env = Env::new();
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(1).create();
+    let output = env.run(&url(&server), &["config", "path"]);
+    assert!(output.status.success());
+    assert!(stderr(&output).contains(NOTICE), "{}", stderr(&output));
+    assert!(
+        stderr(&output).contains("you have 0."),
+        "{}",
+        stderr(&output)
+    );
+    assert!(!stdout(&output).contains("newer version"));
+    mock.assert();
+}
+
+#[test]
+fn the_same_or_an_older_release_says_nothing() {
+    for tag in [
+        concat!("v", env!("CARGO_PKG_VERSION")),
+        "v0.0.1",
+        "v99.0.0-rc.1",
+    ] {
+        let env = Env::new();
+        let mut server = Server::new();
+        let mock = release(&mut server, tag).expect(1).create();
+        let output = env.run(&url(&server), &["config", "path"]);
+        assert!(output.status.success());
+        assert!(!stderr(&output).contains("newer version"), "{tag}");
+        mock.assert();
+    }
+}
+
+#[test]
+fn it_asks_at_most_once_a_day() {
+    let env = Env::new();
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(1).create();
+    let first = env.run(&url(&server), &["config", "path"]);
+    let second = env.run(&url(&server), &["config", "path"]);
+    assert!(stderr(&first).contains(NOTICE));
+    assert!(!stderr(&second).contains("newer version"));
+    mock.assert();
+
+    // A check older than a day is made again.
+    std::fs::write(env.cache(), r#"{"checked_at":1,"latest":"0.1.0"}"#).expect("age the cache");
+    let third = env.run(&url(&server), &["config", "path"]);
+    assert!(stderr(&third).contains(NOTICE));
+}
+
+#[test]
+fn json_and_csv_and_completions_stay_clean_and_make_no_request() {
+    let env = Env::new();
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(0).create();
+    let mut api = Server::new();
+    api.mock("GET", mockito::Matcher::Any)
+        .with_header("content-type", "application/json")
+        .with_body(r#"{"data":[],"pagination":{"page":1,"per_page":50,"total":0,"total_pages":0}}"#)
+        .create();
+    let release_url = url(&server);
+    let api_url = api.url();
+    for args in [
+        vec!["--json", "config", "show"],
+        vec!["vendors", "list", "--csv"],
+        vec!["completions", "bash"],
+    ] {
+        let mut cmd_args = vec!["--api-url", api_url.as_str()];
+        cmd_args.extend(&args);
+        let output = {
+            let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+            cmd.env_remove("CI")
+                .env_remove("HODEISHIELD_NO_UPDATE_CHECK")
+                .env("HODEISHIELD_CONFIG", &env.config)
+                .env("HODEISHIELD_API_KEY", "hsk_test_0123456789abcdef")
+                .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+                .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+                .args(&cmd_args)
+                .output()
+                .expect("run")
+        };
+        assert!(output.status.success(), "{args:?}: {}", stderr(&output));
+        assert!(!stderr(&output).contains("newer version"), "{args:?}");
+    }
+    mock.assert();
+}
+
+#[test]
+fn without_a_terminal_ci_or_with_an_opt_out_nothing_is_asked() {
+    let mut server = Server::new();
+    let mock = release(&mut server, "v99.0.0").expect(0).create();
+    let release_url = url(&server);
+
+    // Standard error is not a terminal (the test harness pipes it).
+    let env = Env::new();
+    let output = Command::cargo_bin("hodeishield")
+        .expect("binary")
+        .env_remove("CI")
+        .env_remove("HODEISHIELD_NO_UPDATE_CHECK")
+        .env_remove("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL")
+        .env("HODEISHIELD_CONFIG", &env.config)
+        .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+        .args(["config", "path"])
+        .output()
+        .expect("run");
+    assert!(!stderr(&output).contains("newer version"));
+
+    // CI, with any value.
+    for ci in ["true", "0", "false"] {
+        let env = Env::new();
+        let mut cmd = Command::cargo_bin("hodeishield").expect("binary");
+        let output = cmd
+            .env("HODEISHIELD_CONFIG", &env.config)
+            .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+            .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+            .env("CI", ci)
+            .args(["config", "path"])
+            .output()
+            .expect("run");
+        assert!(!stderr(&output).contains("newer version"), "CI={ci}");
+    }
+
+    // The environment opt-out.
+    let env = Env::new();
+    let output = Command::cargo_bin("hodeishield")
+        .expect("binary")
+        .env_remove("CI")
+        .env("HODEISHIELD_CONFIG", &env.config)
+        .env("HODEISHIELD_UPDATE_CHECK_URL", &release_url)
+        .env("HODEISHIELD_UPDATE_CHECK_ASSUME_TERMINAL", "1")
+        .env("HODEISHIELD_NO_UPDATE_CHECK", "1")
+        .args(["config", "path"])
+        .output()
+        .expect("run");
+    assert!(!stderr(&output).contains("newer version"));
+
+    // The configuration opt-out, set the way a user sets it.
+    let env = Env::new();
+    let set = env.quiet(&["config", "set", "update_check", "false"]);
+    assert!(set.status.success(), "{}", stderr(&set));
+    let output = env.run(&release_url, &["config", "path"]);
+    assert!(!stderr(&output).contains("newer version"));
+    let shown = env.quiet(&["--json", "config", "show"]);
+    let shown: serde_json::Value = serde_json::from_slice(&shown.stdout).expect("json");
+    assert_eq!(shown["update_check"], false);
+
+    // Unsetting it brings the default back.
+    env.quiet(&["config", "unset", "update_check"]);
+    let shown = env.quiet(&["--json", "config", "show"]);
+    let shown: serde_json::Value = serde_json::from_slice(&shown.stdout).expect("json");
+    assert_eq!(shown["update_check"], true);
+
+    mock.assert();
+}
+
+#[test]
+fn update_check_must_be_a_boolean() {
+    let env = Env::new();
+    let output = env.run(
+        "http://127.0.0.1:9/",
+        &["config", "set", "update_check", "maybe"],
+    );
+    assert_eq!(output.status.code(), Some(1));
+    assert!(stderr(&output).contains("not true or false"));
+}
+
+#[test]
+fn failures_are_silent_and_do_not_change_the_exit_code() {
+    let mut server = Server::new();
+    let bodies: [(usize, &str); 3] = [
+        (500, "oops"),
+        (200, "not json"),
+        (200, r#"{"tag_name":"nightly"}"#),
+    ];
+    for (status, body) in bodies {
+        let env = Env::new();
+        server.reset();
+        server
+            .mock("GET", "/latest")
+            .with_status(status)
+            .with_body(body)
+            .create();
+        let ok = env.run(&url(&server), &["config", "path"]);
+        assert!(ok.status.success());
+        assert_eq!(stderr(&ok), "");
+        // The failed attempt is remembered, so it is not repeated at once.
+        assert!(env.cache().exists());
+
+        let failing = env.run(&url(&server), &["--profile", "missing", "config", "show"]);
+        assert_eq!(failing.status.code(), Some(1));
+    }
+
+    // Nothing listens: the connection is refused.
+    let env = Env::new();
+    let output = env.run("http://127.0.0.1:9/latest", &["config", "path"]);
+    assert!(output.status.success());
+    assert_eq!(stderr(&output), "");
+}
+
+#[test]
+fn an_unwritable_cache_never_fails_the_command() {
+    let env = Env::new();
+    // A directory where the cache file should be.
+    std::fs::create_dir(env.cache()).expect("dir");
+    let mut server = Server::new();
+    let _mock = release(&mut server, "v99.0.0").create();
+    let output = env.run(&url(&server), &["config", "path"]);
+    assert!(output.status.success());
+}
+
+#[test]
+fn verbose_explains_why_it_stayed_quiet() {
+    let env = Env::new();
+    let mut server = Server::new();
+    server.mock("GET", "/latest").with_status(500).create();
+    let output = env.run(&url(&server), &["--verbose", "config", "path"]);
+    assert!(
+        stderr(&output).contains("update check:"),
+        "{}",
+        stderr(&output)
+    );
+}
diff --git a/docs/decisions/0001-sign-in-without-a-keychain.md b/docs/decisions/0001-sign-in-without-a-keychain.md
new file mode 100644
index 0000000..6a3d9d3
--- /dev/null
+++ b/docs/decisions/0001-sign-in-without-a-keychain.md
@@ -0,0 +1,156 @@
+# 0001. Signing in on a machine without a keychain
+
+- Status: Proposed
+- Issue: [#39](https://github.com/Hodeitek/hodeishield-cli/issues/39)
+- Deciders: maintainers
+
+This is a proposal. Nothing here is decided or implemented; the recommendation is the author's.
+
+## Context
+
+`hodeishield login` stores its tokens (an access token and, by default, a refresh token) in the
+system keychain and nowhere else (`crates/hodeishield-cli/src/auth/store.rs:1-6`). On Linux the only
+backend is the Secret Service over D-Bus, through `zbus-secret-service-keyring-store`
+(`crates/hodeishield-cli/Cargo.toml:47-48`, `store.rs:127-131`). There is no kernel keyring (keyutils)
+backend and no file fallback.
+
+On a machine with no Secret Service (an SSH server, a container, WSL without a desktop session, a CI
+runner) this is what happens today:
+
+- The store is first touched when the token is saved (`commands/session.rs:100`), after the whole
+  browser or `--device` flow has finished. The person completes sign-in and consent, then gets
+  "the system keychain is not available" (`store.rs:17,100-110`). The token already issued is not
+  revoked by the CLI, so it stays valid at the app until revoked there.
+- The error points to `HODEISHIELD_API_KEY` (`auth/mod.rs:87-97`); the README says the same
+  (`README.md:294-297`, and for containers `README.md:160-161`).
+- `--device` does not help: it avoids the browser, not the storage.
+
+Who is affected: people who work from a jump host or a remote shell with their own identity (the
+motivating case in the issue: MSSP staff), containers, and CI. A tenant API key works everywhere
+(`auth/mod.rs:38-45`), but it is one more long-lived secret per tenant, it is not tied to a person,
+and someone has to create it.
+
+What is at stake: a sign-in token reads one tenant's supply-chain risk data. The access token is
+short-lived; the refresh token is long-lived and is the sensitive part. The README promises that
+tokens are "never in a file" (`README.md:30`, `cli.rs:103-104`), so any option that writes a file
+changes a documented guarantee.
+
+Existing seam: `TokenStore` (`store.rs:87-93`) has `load`, `save` and `delete` per profile, with a
+test-only `MemoryStore` (`store.rs:185`). The CLI builds the store in one place
+(`commands/mod.rs:83`). A new store is a new implementation of that trait plus a way to choose it.
+
+## Options
+
+### A. Keep keychain-only; document API keys for headless use
+
+Change nothing in behaviour. Improve the experience: refuse early (before opening a browser or
+printing a device code) when no keychain is reachable, and say what to do; expand the README with a
+"servers and containers" recipe.
+
+- Security: best. No new storage, no weaker path. API keys can be scoped to read scopes and rotated.
+- Effort: small (an early check, a message, docs).
+- Consequences: the issue's use case is answered with "request an API key", not with the person's own
+  identity. Per-tenant keys must be issued and tracked by someone.
+
+### B. Linux kernel session keyring (keyutils) as a fallback
+
+Store the payload with `keyctl` in the session or user keyring when no Secret Service is present.
+
+- Security: the secret is kernel memory, never on disk, and not readable by other users. But it is
+  scoped to a keyring, not a person's login: a user keyring is readable by every process of that user;
+  a session keyring is visible only to that session's processes.
+- Lifetime: it does not survive a reboot. A session keyring disappears when the last process of the
+  session ends, so a new SSH connection would be signed out; a user keyring (`@u`) survives
+  across sessions until reboot or key timeout, but with defaults that vary by distribution and
+  container runtime. Containers often block the `keyctl` syscall under the default seccomp profile.
+- Effort: medium. A new backend crate (or direct syscalls), Linux only, behind a selection rule and
+  tests that need a real kernel keyring.
+- Consequences: helps SSH servers somewhat, containers and WSL unreliably. Behaviour (survives or not)
+  would be surprising to users and needs documenting per mode.
+
+### C. Encrypted file store with a passphrase
+
+Write the payload to a file in the config directory, encrypted with a key derived (for example with
+Argon2id) from a passphrase.
+
+- Where the key comes from: a prompt on a terminal, or an environment variable / file descriptor for
+  non-interactive use (for example `HODEISHIELD_PASSPHRASE`).
+- UX: a prompt on every command that needs the token, or a passphrase in the environment, which in
+  practice moves the secret from one place to another. Without a terminal and without the variable
+  the command must fail clearly.
+- Threat model: protects a stolen disk, backup or file copy; does not protect against code running as
+  the same user once the passphrase is in memory or in the environment. A weak passphrase makes the
+  file an offline-guessing target for a long-lived refresh token.
+- Effort: large. New crypto dependencies to vet (`deny.toml`), file format and versioning, prompting,
+  locking against concurrent refreshes, key rotation, tests.
+- Consequences: works in all environments with a terminal; the largest new security surface to own.
+
+### D. Plaintext file with 0600 permissions behind an explicit opt-in
+
+Store the payload in a file in the config directory, mode 0600 in a 0700 directory, only when the
+person opts in (for example `HODEISHIELD_INSECURE_STORAGE=file` or a config key), with a warning on
+every sign-in.
+
+- Security: weakest. Anyone who can read the file (same user, root, backups, a mis-mounted volume, an
+  image layer) holds a refresh token valid until revoked. Permissions do not protect against malware
+  running as the user. This reverses the "never in a file" promise for those who opt in.
+- Effort: small to medium (store, permission checks and refusal if the file is looser than 0600,
+  Windows ACL handling, docs, tests).
+- Consequences: common practice in other CLIs, and it solves every environment, but it normalises the
+  exact exposure the CLI was designed to avoid. Requests to remove the opt-in guard would follow.
+
+### E. No storage: print a token once or keep it in memory for one command
+
+For example `hodeishield login --print-token` runs the flow and prints only the access token, to be
+exported as an environment variable for the session; or the CLI uses the access token only within
+one invocation.
+
+- Security: good if the refresh token is never requested or never stored. The access token is
+  short-lived, so exposure is limited to its lifetime; it can appear in shell history or process
+  environment if handled carelessly.
+- Effort: small to medium. The CLI would need to request no `offline_access` scope, accept an access
+  token from the environment (a new credential source in `auth/mod.rs:38`), and print it safely
+  (stdout only, never with other text).
+- Consequences: no refresh, so the person signs in again when the token expires (the lifetime is set
+  by the app). Fine for a short task on a jump host; poor for unattended jobs, which should use an API
+  key. Interactive device flow from a remote shell is natural here.
+
+### F. Delegate to an external credential helper
+
+The CLI calls a configured program (as some tools do with git or Docker credential helpers) to load
+and save the payload, so people bring their own vault.
+
+- Security: depends on the helper; the CLI never writes a file. The helper's protocol and trust (the
+  program path comes from configuration) become part of the threat model.
+- Effort: medium (protocol, spawn without a shell, error handling, docs). Larger audience needed to
+  justify it.
+
+## Recommendation (the author's, not a decision)
+
+Security first: the refresh token is the asset, and the options that never write it to disk or
+plaintext are A, E, and B. In that order of preference:
+
+1. Do A now, regardless: fail early, before the browser or device code, and document the headless
+   path. This fixes the worst part of the current behaviour (completing sign-in and then failing,
+   leaving an unrevoked token) at almost no risk.
+2. Add E for the jump-host case: a sign-in that requests no refresh token and does not store anything,
+   with the access token handed to the shell explicitly. It keeps personal identity without a stored
+   long-lived secret, and costs one new credential source.
+3. Do not implement D or C unless the maintainers accept new storage risk. If a file is needed
+   anyway, prefer C over D, and only with a design review of the format and the passphrase handling.
+   B is worth a spike only if SSH-server users report that E is not enough.
+
+If the maintainers choose not to add any alternative store, the second acceptance criterion of #39 is
+met by A: the README recommends API keys and explains why.
+
+## Open questions for the maintainers
+
+1. Is "tokens never in a file" a product guarantee to keep, or a default that an opt-in may change?
+2. Can the app issue an access token without a refresh token (no `offline_access`) with a useful
+   lifetime for a jump-host session? What is that lifetime?
+3. Should a person's own sign-in be preferred over per-tenant API keys for MSSP staff, or are API keys
+   an acceptable answer given they can be scoped and rotated?
+4. For containers and CI, is an API key always the intended answer (so options B to D are out of scope
+   there)?
+5. Should the CLI revoke the token it just obtained when it cannot store it (today it does not)?
+6. Which platforms matter most: SSH servers, WSL, containers, CI?
diff --git a/docs/security-advisory-template.md b/docs/security-advisory-template.md
new file mode 100644
index 0000000..bfc890c
--- /dev/null
+++ b/docs/security-advisory-template.md
@@ -0,0 +1,112 @@
+# Security advisory template
+
+Every security advisory for `hodeishield` is written from this template, as described in
+[SECURITY.md](../SECURITY.md#how-advisories-are-published), so that every advisory has the same
+fields in the same order. Copy everything below the line into a new GitHub security advisory for
+this repository, fill in each field, and delete the parts in *italics*. Keep a heading and write
+"None" rather than removing it, so readers and scripts find the same sections every time.
+
+The first table maps to the fields of GitHub's advisory form; the rest is the advisory's
+description.
+
+---
+
+| Advisory form field | Value |
+|---|---|
+| Title | *One line: the component, the flaw and its effect, e.g. "Sign-in token sent to a redirected host".* |
+| Affected versions | *A range, e.g. `>= 0.2.0, < 0.3.2`.* |
+| Patched versions | *e.g. `0.3.2`.* |
+| Severity | *Critical, High, Medium or Low, from the CVSS v3.1 base score.* |
+| CVSS v3.1 vector | *e.g. `CVSS:3.1/AV:N/AC:H/PR:N/UI:R/S:U/C:H/I:N/A:N`.* |
+| Weakness | *CWE identifier, if one fits.* |
+| Credits | *Reporter, as they asked to be credited, or "None" if they prefer not to be.* |
+
+## Summary
+
+*Two or three sentences: what is wrong, what an attacker can do, and what to do about it.*
+
+## Affected versions
+
+*Every release in the range, and every install channel that shipped them. Say if a channel was not
+affected.*
+
+## Fixed versions
+
+*The first release with the fix, with a link to its release page.*
+
+## Severity
+
+*The rating and the CVSS v3.1 vector, with one sentence on why each metric that is not obvious was
+chosen.*
+
+## Impact
+
+*What an attacker gains (for example a credential, the ability to hide terminal output, a tampered
+download) and what they need first (network position, a crafted URL or identifier, local access,
+the user running a particular command).*
+
+## Who is affected
+
+*The commands, flags, environment variables, configuration settings and platforms involved, e.g.
+"anyone who signs in with `hodeishield login` on Windows", "scripts that set
+`HODEISHIELD_API_KEY` together with a custom API URL". Say who is not affected.*
+
+## Workarounds
+
+*What to do until you can update, or "None: update". If a credential may have been exposed, say
+which one and to revoke it in the app.*
+
+## How to check whether you are affected
+
+```sh
+hodeishield --version
+```
+
+*Compare the version with the affected range above. Add any other check: a configuration value, a
+file, an environment variable, a log line from `--verbose`. For the container image, check the tag
+or digest your pipeline pins.*
+
+## How to update
+
+Verify every download as described in
+[docs/verifying-releases.md](https://github.com/Hodeitek/hodeishield-cli/blob/main/docs/verifying-releases.md).
+*Delete the channels that did not ship an affected version.*
+
+- **Release archive (Linux, macOS, Windows):** download the archive for your platform from the
+  release page of `<fixed version>`, verify it, and replace the `hodeishield` binary on your `PATH`.
+- **Homebrew:** `brew update && brew upgrade hodeishield`
+- **Scoop:** `scoop update` then `scoop update hodeishield`
+- **Debian, Ubuntu (`.deb`) and Fedora, RHEL (`.rpm`):** download the `<fixed version>` package,
+  verify it, and install it with the same `sudo apt install ./...` or `sudo dnf install ./...`
+  command as the first time.
+- **Windows installer (MSI):** install the `<fixed version>` MSI; it upgrades the installed version
+  in place.
+- **Install script (Linux and macOS):** download and verify the `install.sh` of `<fixed version>`,
+  then run `sh install.sh --version <fixed version>`.
+- **Container image:** pull `ghcr.io/hodeitek/hodeishield-cli:<fixed version>`, verify it with
+  `cosign verify`, and pin the new digest in your pipeline.
+- **From source:**
+  `cargo install --locked --force --git https://github.com/Hodeitek/hodeishield-cli --tag v<fixed version> hodeishield-cli`
+
+## Timeline
+
+| Date (UTC) | Event |
+|---|---|
+| *YYYY-MM-DD* | Reported |
+| *YYYY-MM-DD* | Fixed in `<fixed version>` |
+| *YYYY-MM-DD* | Advisory published |
+
+*Add other dates that matter, such as when exploitation was first seen or when the first notice was
+published.*
+
+## Credit
+
+*Who reported it and how they asked to be named, or "Reported privately; the reporter asked not to
+be named".*
+
+## References
+
+- *The release notes of `<fixed version>`.*
+- *The pull request or commit with the fix, once public.*
+- *The CVE identifier, if one was assigned.*
+- *Anything else a reader needs: related advisories, upstream issues.*
diff --git a/docs/user-information.md b/docs/user-information.md
new file mode 100644
index 0000000..67b202e
--- /dev/null
+++ b/docs/user-information.md
@@ -0,0 +1,181 @@
+# User information
+
+This document gathers in one place what you need to know to use `hodeishield` securely: who makes
+it, how to reach us, how long it is supported, and how to update and remove it. Where the details
+live in [README.md](../README.md) or [SECURITY.md](../SECURITY.md), it links to them.
+
+Each release keeps the copy of this document that applies to it, in that release's tag:
+`https://github.com/Hodeitek/hodeishield-cli/blob/v<version>/docs/user-information.md`. Releases
+up to 0.3.1 were published before this document existed; for them, the README and SECURITY.md in
+their tag apply.
+
+## Product
+
+- **Name:** HodeiShield CLI. The command is `hodeishield` (`hodeishield.exe` on Windows); the
+  source repository is [Hodeitek/hodeishield-cli](https://github.com/Hodeitek/hodeishield-cli).
+- **Version:** `hodeishield --version` prints the installed version. Versions follow
+  [Semantic Versioning](https://semver.org/) and each release is tagged `v<version>`.
+- **Releases:** every release, with its files and notes, is on the
+  [releases page](https://github.com/Hodeitek/hodeishield-cli/releases), at
+  `https://github.com/Hodeitek/hodeishield-cli/releases/tag/v<version>`. The notes of every
+  release, with its date, are also in [CHANGELOG.md](../CHANGELOG.md).
+
+## Manufacturer and contact
+
+Hodeitek S.L., Markole 17, 20550 Aretxabaleta, Gipuzkoa, Spain.
+
+- Email: [info@hodeitek.com](mailto:info@hodeitek.com)
+- Website: [hodeitek.com](https://hodeitek.com)
+- Bug reports and documentation problems that are not about security:
+  [GitHub issues](https://github.com/Hodeitek/hodeishield-cli/issues), as described in
+  [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Reporting a vulnerability
+
+The point of contact for vulnerabilities in `hodeishield` is the maintainers, through either of
+these two means:
+
+- [GitHub private vulnerability reporting](https://github.com/Hodeitek/hodeishield-cli/security/advisories/new)
+  (the *Security* tab of the repository → *Report a vulnerability*);
+- email to [security@hodeitek.com](mailto:security@hodeitek.com).
+
+Never report a vulnerability in a public issue. What to include, how quickly you get an answer and
+how a fix is disclosed are in [SECURITY.md](../SECURITY.md#what-happens-after-you-report). Published
+advisories are under
+[Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories), and
+[Security notices](../SECURITY.md#security-notices) lists where an affected release is announced.
+
+## Intended purpose
+
+`hodeishield` is a read-only command-line client for the public `/v1` API of
+[HodeiShield](https://hodeishield.com). It reads one organisation's third-party inventory,
+supply-chain alerts, risk register, compliance posture, evidence and endpoint agents, from a
+terminal or a script. Every command reads: its requests to the API are `GET` only, and it cannot
+change data in your organisation. It needs a HodeiShield account to sign in with, or a tenant API
+key.
+
+## Security properties and secure use
+
+What the CLI guarantees (read only, credentials never written to disk in clear text, printed or
+logged, HTTPS only, no redirects followed, signed releases) is in
+[SECURITY.md](../SECURITY.md#what-the-cli-guarantees). To use it securely:
+
+- **Verify every download** before you run it: [Verify a download](../README.md#verify-a-download)
+  and [docs/verifying-releases.md](verifying-releases.md). For the container image, verify it and
+  pin its digest ([Container image](../README.md#container-image)).
+- **Pick the right credential** ([Authenticate](../README.md#authenticate)). People sign in with
+  `hodeishield login`: the token is kept in the system keychain, covers one tenant and only reads.
+  Scripts, CI and servers use a tenant API key with only the read scopes they need, kept in the CI's
+  secret store and passed in the environment, not on a command line. When
+  `HODEISHIELD_API_KEY` is set, it is used for every call, whatever else is configured.
+- **Keep the configuration file free of credentials.** It holds URLs and sign-in settings only,
+  and URLs must use HTTPS; plain HTTP is accepted only for `localhost`
+  ([Configure](../README.md#configure)).
+- **Treat output as your organisation's data.** `--json` and `--csv` output, and the request URLs
+  that `--verbose` logs, can contain identifiers and filter values from your organisation, but never
+  the CLI's credential. Text from the API is cleaned of terminal control characters before
+  it is printed, and CSV cells that a spreadsheet would run as a formula are prefixed with `'`
+  ([CSV output](../README.md#csv-output)).
+- **Behind a proxy or TLS inspection**, the CLI trusts the operating system's certificate store and
+  has no option to skip certificate verification: install your organisation's CA in that store
+  ([Networking](../README.md#networking-proxies-and-tls-inspection)).
+- **Cut access you no longer need**: `hodeishield logout`, or revoke the CLI's access in the app
+  under **Account → Application access**; revoke an API key in the app as soon as it is not needed
+  or may have been exposed.
+
+Known limitations:
+
+- The macOS binary is not yet signed with an Apple Developer ID or notarized
+  ([#50](https://github.com/Hodeitek/hodeishield-cli/issues/50)); the Sigstore signature is the
+  proof that it is genuine (see
+  [If macOS or Windows blocks the binary](../README.md#if-macos-or-windows-blocks-the-binary)).
+- Use behind a TLS-inspecting proxy is verified on Linux only; macOS and Windows have not been
+  verified yet.
+- The [new-version notice](../README.md#new-version-notice) makes at most one unauthenticated
+  request a day to GitHub's public API, so GitHub sees your IP address. It can be turned off (see
+  [Updating](#updating)).
+
+## Support period
+
+From 1.0.0, each major version is supported with security fixes for five years, and the fixes ship
+in the latest release of that major version. While a version is supported, security fixes stay
+available even after your HodeiShield subscription ends. How this applies to the current 0.x
+series, the end-of-support date of each major version and how end of support is announced are in
+[SECURITY.md](../SECURITY.md#supported-versions).
+
+## Updating
+
+`hodeishield` never updates itself. On an interactive terminal it tells you, at most once a day,
+that a newer release exists ([New-version notice](../README.md#new-version-notice)); update through
+the channel you installed it with. Before you move to a new minor version while the CLI is at 0.x,
+read **Changed (scripting surface)** in its release notes ([Stability](../README.md#stability)).
+
+| Installed with | To update |
+|---|---|
+| Release archive | Download the new archive, verify it, and replace the binary. |
+| Homebrew | `brew upgrade hodeishield` |
+| Scoop | `scoop update hodeishield` |
+| `.deb` / `.rpm` | Verify the newer package and install it with the same `apt install` or `dnf install` command. |
+| MSI | Install the newer MSI; it upgrades the older one in place. |
+| `install.sh` | Download and verify the new release's `install.sh` and run it with `--version` (and the same `--dir`, if you used one). |
+| Container image | Pull the new exact-version tag (there is no `latest` tag), verify it and pin its digest. |
+| `cargo install` | Run the same command with the new `--tag`. |
+
+To turn off the new-version notice, set `HODEISHIELD_NO_UPDATE_CHECK` to any non-empty value, or
+run `hodeishield config set update_check false` once for all profiles (`config unset update_check`
+restores it). With either, the CLI makes no request to GitHub.
+
+## Decommissioning
+
+To stop using `hodeishield` on a machine and leave nothing behind:
+
+1. **Sign out of every profile you signed in to**: `hodeishield logout`, and
+   `hodeishield logout --profile <name>` for each other profile. This revokes the token at the app
+   and removes it from the system keychain. If the CLI warns that the app did not confirm the
+   revocation, revoke the CLI's access in the app under **Account → Application access**.
+2. **Revoke the tenant API keys** the machine used, in the app, and remove them from the
+   environment and secret stores that held them.
+3. **Delete the configuration file and the update-check record.** `hodeishield config path` prints
+   where the configuration file is; `update-check.json` is next to it. By default:
+
+   | System | Directory |
+   |---|---|
+   | Linux | `~/.config/hodeishield/` (or `$XDG_CONFIG_HOME/hodeishield/`) |
+   | macOS | `~/Library/Application Support/com.Hodeitek.HodeiShield/` |
+   | Windows | `%APPDATA%\Hodeitek\HodeiShield\config\` |
+
+   The files are `config.toml` and `update-check.json`. If you set `HODEISHIELD_CONFIG`, they are
+   that file and `update-check.json` in its directory.
+4. **Uninstall the CLI** with the channel you installed it with:
+
+   | Installed with | To uninstall |
+   |---|---|
+   | Release archive | Delete the `hodeishield` binary, and any man pages you copied. |
+   | Homebrew | `brew uninstall hodeishield` |
+   | Scoop | `scoop uninstall hodeishield` |
+   | `.deb` / `.rpm` | `sudo apt remove hodeishield` or `sudo dnf remove hodeishield` |
+   | MSI | **Settings → Apps**, or `msiexec /x` ([Windows installer](../README.md#windows-installer-msi)) |
+   | `install.sh` | Delete `hodeishield` from the directory it installed to (`/usr/local/bin` or `~/.local/bin`, or your `--dir`), and the `hodeishield*.1` man pages from the `share/man/man1` directory beside it (for example `/usr/local/share/man/man1`). |
+   | Container image | Remove the image, for example `docker image rm ghcr.io/hodeitek/hodeishield-cli:<version>`. |
+   | `cargo install` | `cargo uninstall hodeishield-cli` |
+
+If the CLI is already gone and a sign-in was left in the keychain, revoke the access in the app
+(**Account → Application access**), then delete the entry, one per profile, whose service is
+`hodeishield-cli` and whose account is the profile name: on macOS with Keychain Access or
+`security delete-generic-password -s hodeishield-cli -a <profile>`, on Windows in Credential Manager
+(*Windows Credentials*, named `<profile>.hodeishield-cli`), and on Linux with
+`secret-tool clear service hodeishield-cli username <profile>`.
+
+## Software bill of materials
+
+From 0.2.0, each release publishes a [CycloneDX](https://cyclonedx.org) software bill of materials
+(SBOM) for each archive, `<archive-name>.cdx.json`, attached to the release with its own Sigstore
+signature and listed in `SHA256SUMS`. It lists every crate compiled into that binary, with its
+version, licence and package URL. The `.deb`, `.rpm` and MSI packages contain the binary of a
+matching archive, which that archive's SBOM describes. The container image carries the release's
+CycloneDX SBOM as a signed attestation.
+
+The SBOM is intended for users: use it to check which components a release contains and whether any
+of them has a known vulnerability. How to verify it is in
+[docs/verifying-releases.md](verifying-releases.md) and
+[Container image](../README.md#container-image).
diff --git a/docs/verifying-releases.md b/docs/verifying-releases.md
index f060d04..87e25f0 100644
--- a/docs/verifying-releases.md
+++ b/docs/verifying-releases.md
@@ -7,6 +7,10 @@ Every release of `hodeishield-cli` publishes, for each platform archive:
   "bundle" files produced by **keyless** `cosign sign-blob` (no private key:
   the workflow signs using its GitHub Actions OIDC identity, and the
   signature is recorded in the public Rekor transparency log).
+- `hodeishield-<version>-aarch64-pc-windows-msvc.zip` (Windows on Arm, from 0.4.0),
+  checksummed, signed with Sigstore, covered by the provenance and accompanied by its
+  SBOM like the other archives. Its `hodeishield.exe` carries the same Authenticode signature
+  (section 5). There is no arm64 MSI yet.
 - `hodeishield-<version>-x86_64-pc-windows-msvc.msi` (from 0.3.0), with its own
   `.sigstore.json` and listed in `SHA256SUMS`. The MSI and the `hodeishield.exe` inside it are both
   signed with Authenticode (section 5); the exe is the same as in the `.zip`, whose SBOM describes it.
@@ -21,14 +25,14 @@ Every release of `hodeishield-cli` publishes, for each platform archive:
   [`slsa-framework/slsa-github-generator`](https://github.com/slsa-framework/slsa-github-generator)
   generic generator.
 
-The steps below use `v0.3.1` and `hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz`
+The steps below use `v0.4.0` and `hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz`
 as examples — substitute the actual version and archive you downloaded.
 
 ## 1. Download the files
 
 From the release page, download:
 
-- the archive you want (e.g. `hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz`)
+- the archive you want (e.g. `hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz`)
 - `SHA256SUMS`
 - the matching `<archive>.sigstore.json`
 - `SHA256SUMS.sigstore.json`
@@ -51,7 +55,7 @@ Requires [`cosign`](https://github.com/sigstore/cosign) (v2 or newer).
 ```sh
 cosign verify-blob \
   --bundle SHA256SUMS.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push \
   SHA256SUMS
@@ -61,11 +65,11 @@ Repeat for the archive itself, using its own `.sigstore.json`:
 
 ```sh
 cosign verify-blob \
-  --bundle hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+  --bundle hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz.sigstore.json \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push \
-  hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz
+  hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz
 ```
 
 A successful verification confirms the file was signed by the
@@ -78,11 +82,11 @@ The SBOM is verified the same way, with its own bundle:
 
 ```sh
 cosign verify-blob \
-  --bundle hodeishield-0.3.1-x86_64-unknown-linux-musl.cdx.json.sigstore.json \
-  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.3.1 \
+  --bundle hodeishield-0.4.0-x86_64-unknown-linux-musl.cdx.json.sigstore.json \
+  --certificate-identity https://github.com/Hodeitek/hodeishield-cli/.github/workflows/release.yml@refs/tags/v0.4.0 \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
   --certificate-github-workflow-trigger push \
-  hodeishield-0.3.1-x86_64-unknown-linux-musl.cdx.json
+  hodeishield-0.4.0-x86_64-unknown-linux-musl.cdx.json
 ```
 
 ## 4. Verify SLSA build provenance
@@ -91,10 +95,10 @@ Requires [`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier).
 
 ```sh
 slsa-verifier verify-artifact \
-  hodeishield-0.3.1-x86_64-unknown-linux-musl.tar.gz \
+  hodeishield-0.4.0-x86_64-unknown-linux-musl.tar.gz \
   --provenance-path hodeishield.intoto.jsonl \
   --source-uri github.com/Hodeitek/hodeishield-cli \
-  --source-tag v0.3.1
+  --source-tag v0.4.0
 ```
 
 `hodeishield.intoto.jsonl` is attached to the release and covers every
diff --git a/install.sh b/install.sh
index 45acb31..74fbfba 100755
--- a/install.sh
+++ b/install.sh
@@ -78,7 +78,7 @@ case "$(uname -s)" in
 esac
 
 if [ -z "$version" ]; then
-  latest=$(curl -fsSLI -o /dev/null -w '%{url_effective}' "https://github.com/${REPO}/releases/latest") ||
+  latest=$(curl -fsSLI --proto '=https' --tlsv1.2 -o /dev/null -w '%{url_effective}' "https://github.com/${REPO}/releases/latest") ||
     die "could not find the latest release"
   version=${latest##*/}
   version=${version#v}
diff --git a/openapi/README.md b/openapi/README.md
index b09a71d..1282ecf 100644
--- a/openapi/README.md
+++ b/openapi/README.md
@@ -6,18 +6,20 @@ from it; nothing in that client is written by hand from memory.
 
 | Field | Value |
 |---|---|
-| `info.version` | `2026-09-28` |
-| SHA-256 | `103e86f38f7b3eff45a0f764c8142b4bdd2e8d576385b1b4ccf588cbf0518fb3` |
-| Operations | 11, all `GET` |
+| `info.version` | `2026-10-16` |
+| SHA-256 | `1321a417aba28e7b60dbc28a35ce2dc3711d8973b985107f7701d70ff3be6b0d` |
+| Operations | 12, all `GET` |
 
 ## Updating it
 
-The **OpenAPI sync** workflow (`.github/workflows/openapi-sync.yml`) does this every Monday, and on
-demand: it compares this copy with the published document by content (key order and whitespace do
-not count) and, when they differ, opens or updates one pull request against `dev`. That pull request
-contains the published bytes, the steps below and a summary, with the label `breaking-change` when
-[oasdiff](https://github.com/oasdiff/oasdiff) finds one. A maintainer reviews and merges it; nothing
-is merged automatically. By hand:
+The **OpenAPI sync** workflow (`.github/workflows/openapi-sync.yml`) checks this copy every Monday, and
+on demand: it compares it with the published document by content (key order and whitespace do not
+count). When they differ it opens, or comments on, one issue labelled `openapi-drift`, with both
+`info.version` values, whether [oasdiff](https://github.com/oasdiff/oasdiff) finds a breaking change
+(and in which direction) and a summary, and the run is red. When they match again it closes the issue.
+If the published document cannot be fetched or compared, an issue labelled `openapi-check-failed`
+reports that instead. The workflow never changes this copy or opens a pull request: a maintainer
+decides whether the API or this copy is behind. To take the published document, by hand:
 
 1. Replace `v1.json` with the new document, unchanged.
 2. Update the version and SHA-256 above and in `xtask/src/main.rs` (`EXPECTED_SHA256`).
diff --git a/openapi/v1.json b/openapi/v1.json
index 6256d0f..5ab3c5f 100644
--- a/openapi/v1.json
+++ b/openapi/v1.json
@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"Hodei-Shield API","version":"2026-09-28","summary":"Third-party risk and compliance posture, for your own systems.","description":"## Versioning\n\n`/v1` is frozen. These changes are **compatible** and will happen inside it\nwithout notice:\n\n- a new operation;\n- a new **optional** query parameter;\n- a new field in a response object;\n- a new value in a field documented as an open vocabulary (`status`,\n  `severity`, `evidence_type`, the keys of `by_status`);\n- a new `error.code`, always with the HTTP status its siblings already use;\n- anything under `error.details`, which is diagnostic and not part of the\n  contract.\n\nWrite your client so those do not break it: ignore unknown fields, do not\nswitch exhaustively on a documented-open vocabulary, and treat an unknown\n`error.code` as \"an error of this HTTP status\".\n\nThese changes are **incompatible** and will NOT happen inside `/v1`. They go\nto `/v2`, and `/v1` keeps serving:\n\n- removing or renaming an operation, a parameter or a field;\n- changing the type, the unit or the meaning of a field;\n- making an optional parameter required, or narrowing what one accepts;\n- changing which scope an operation requires;\n- changing the HTTP status an existing `error.code` is sent with.\n\n## Read-only\n\n`/v1` only reads. Every operation is a `GET`. Any other method (`POST`, `PUT`,\n`PATCH`, `DELETE`) on a path that exists answers **405** with `Allow: GET`, and on\na path that does not exist answers **404**: neither changes any state. A write\nwill be offered only as a new operation, which is a compatible change, once a\ncustomer asks for a concrete one.\n\n## Authentication\n\nEvery operation takes `Authorization: Bearer <tenant API key>`. A key belongs\nto ONE tenant and carries an explicit list of scopes; it can read nothing\noutside that tenant, whatever it asks for. Each operation below declares the\nscope it requires. A key that authenticates but lacks the scope is answered\n**403**, never 404: you are told what you are missing, not that the resource\ndoes not exist.\n\n## Errors\n\nEvery error has the same body:\n\n```json\n{ \"error\": { \"code\": \"forbidden\", \"message\": \"…\", \"request_id\": \"…\" } }\n```\n\nBranch on `code`, log `request_id`, show `message` to nobody but yourself.\n`request_id` is also the `X-Request-Id` response header, and it is what\nsupport will ask you for.\n\n## Rate limits\n\nEvery response that got past authentication carries the limit that is closest\nto being exhausted:\n\n- `RateLimit-Limit` — requests allowed in the window;\n- `RateLimit-Remaining` — requests left in the current window;\n- `RateLimit-Reset` — **seconds** until the window renews;\n- `RateLimit-Policy` — `<limit>;w=<window seconds>`.\n\nThree limits apply, each per one-minute window: per API key, per organisation\n(all of its keys together) and per service. The first two come from the licence\nof the organisation the key belongs to: a higher licence tier has more room, and\nan MSSP partner has more than a direct customer of the same tier. Read the\ncurrent limit from `RateLimit-Limit` and `RateLimit-Policy` rather than\nhard-coding it. When one is exhausted the answer is\n**429** with `error.code: \"rate_limited\"`, `Retry-After` (seconds) and\n`error.details.scope` (`key`, `tenant` or `service`) saying which. Your\norganisation's usage never counts against another's. Windows are fixed, so a\nclient can burst up to twice the limit across a window boundary: back off on\n`Retry-After` rather than pacing to the second. The limits are part of the\nservice, not of the frozen contract: they may be raised without notice.\n\n## Pagination, filtering and ordering\n\nEvery collection takes `page` and `per_page` (max 200) and answers with a\n`pagination` object carrying `total` and `total_pages`. Every collection\ntakes `sort` (an enum of the fields THAT collection can order by) and\n`order` (`asc`/`desc`, default `desc`). Filters are exact matches unless\nthe parameter says otherwise.","contact":{"name":"Hodeitek S.L.","url":"https://hodeishield.com"}},"servers":[{"url":"https://api.hodeishield.com"}],"tags":[{"name":"vendors"},{"name":"alerts"},{"name":"risks"},{"name":"compliance"},{"name":"evidence"},{"name":"endpoints"}],"paths":{"/v1/vendors":{"get":{"operationId":"listVendors","summary":"List third parties","description":"The tenant third-party inventory, newest first by default. Soft-deleted vendors are never returned.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, name.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","name"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring of the name or the domain.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"category","in":"query","required":false,"description":"Exact category match.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"active","in":"query","required":false,"description":"Filter by the operational flag.","schema":{"type":"string"}},{"name":"business_criticality","in":"query","required":false,"description":"Exact criticality match.","schema":{"type":"string","enum":["low","medium","high","critical"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/vendors/{id}":{"get":{"operationId":"getVendor","summary":"Fetch one third party","description":"The same object `listVendors` returns, for a single vendor.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts":{"get":{"operationId":"listAlerts","summary":"List supply-chain alerts","description":"Alerts raised against the tenant vendors. Poll incrementally with `since` plus `order=asc`.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at.","schema":{"default":"created_at","type":"string","enum":["created_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Filter by the derived status.","schema":{"type":"string","enum":["open","acknowledged","resolved"]}},{"name":"severity","in":"query","required":false,"description":"Exact severity match.","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"vendor_id","in":"query","required":false,"description":"Only alerts about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"since","in":"query","required":false,"description":"Only alerts created at or after this RFC 3339 instant.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low, when classified.","type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts/{id}":{"get":{"operationId":"getAlert","summary":"Fetch one alert","description":"The same object `listAlerts` returns, for a single alert.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low, when classified.","type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks":{"get":{"operationId":"listRisks","summary":"List risk-register entries","description":"The tenant risk register, with inherent and residual figures.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, inherent_score, residual_score.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","inherent_score","residual_score"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":24}},{"name":"domain","in":"query","required":false,"description":"Exact domain match.","schema":{"type":"string","minLength":1,"maxLength":20}},{"name":"vendor_id","in":"query","required":false,"description":"Only risks linked to this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"min_inherent_score","in":"query","required":false,"description":"Only risks whose inherent score is at least this.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain, as configured by the tenant."},"status":{"type":"string","description":"identified | assessed | treated | accepted | closed | …"},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks/{id}":{"get":{"operationId":"getRisk","summary":"Fetch one risk-register entry","description":"The same object `listRisks` returns, for a single entry.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Risk identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain, as configured by the tenant."},"status":{"type":"string","description":"identified | assessed | treated | accepted | closed | …"},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/compliance/controls":{"get":{"operationId":"listComplianceControls","summary":"List control status for a framework","description":"Per-control status of one framework. Requires the read scope OF THAT FRAMEWORK: `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: control_code, last_evaluated_at.","schema":{"default":"control_code","type":"string","enum":["control_code","last_evaluated_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"framework","in":"query","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":20}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Framework slug the control belongs to."},"control_code":{"type":"string","description":"Control identifier inside the framework."},"status":{"type":"string","description":"missing | partial | covered, as evaluated by the platform."},"evidence_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Evidence items currently linked to the control."},"last_evaluated_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["framework","control_code","status","evidence_count","last_evaluated_at"],"additionalProperties":false,"description":"The tenant status of one framework control."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/compliance/frameworks/{framework}":{"get":{"operationId":"getFrameworkPosture","summary":"Framework posture summary","description":"Counts of evaluated controls by status for one framework, for a dashboard tile. Requires `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"framework","in":"path","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"framework":{"type":"string"},"controls_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Controls the platform has evaluated."},"by_status":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Control count per status. Keys are whatever statuses exist; may grow."},"evidence_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of the evidence linked across the evaluated controls."},"last_evaluated_at":{"description":"Most recent control evaluation, RFC 3339 UTC. Null if never evaluated.","type":["string","null"]}},"required":["framework","controls_total","by_status","evidence_total","last_evaluated_at"],"additionalProperties":false,"description":"Posture summary for one framework."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/evidence":{"get":{"operationId":"listEvidence","summary":"List security evidence","description":"Evidence held for the tenant. Use `expiring_before` plus `sort=valid_until&order=asc` for a renewal queue.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, valid_until.","schema":{"default":"created_at","type":"string","enum":["created_at","valid_until"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"evidence_type","in":"query","required":false,"description":"Exact type match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"source_type","in":"query","required":false,"description":"Exact producer match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"vendor_id","in":"query","required":false,"description":"Only evidence about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"expiring_before","in":"query","required":false,"description":"Only evidence with a `valid_until` strictly before this `YYYY-MM-DD`.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/evidence/{id}":{"get":{"operationId":"getEvidence","summary":"Fetch one evidence item","description":"The same object `listEvidence` returns, for a single item.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"id","in":"path","required":true,"description":"Evidence identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/endpoints":{"get":{"operationId":"listEndpoints","summary":"List enrolled endpoint agents","description":"The endpoint agents enrolled in this tenant. `silent_since` selects the ones that have gone quiet, including those that never reported.\n\nRequired scope: `endpoints:read`. Published in `/v1` since 2026-09-20.","tags":["endpoints"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: enrolled_at, last_seen_at, producer.","schema":{"default":"enrolled_at","type":"string","enum":["enrolled_at","last_seen_at","producer"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","enum":["active","revoked"]}},{"name":"silent_since","in":"query","required":false,"description":"Agents last seen before this RFC 3339 instant, or never seen at all.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"producer":{"type":"string","description":"The agent name, unique among the active ones of the tenant."},"producer_kind":{"type":"string","description":"What kind of producer it is."},"status":{"type":"string","description":"active | revoked."},"signature_alg":{"type":"string","description":"Algorithm this enrollment signs with."},"agent_version":{"type":["string","null"]},"hostname":{"description":"Last hostname the agent reported.","type":["string","null"]},"enrolled_at":{"type":"string","description":"RFC 3339, UTC."},"last_seen_at":{"description":"RFC 3339, UTC. Null until the first envelope.","type":["string","null"]},"revoked_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["id","producer","producer_kind","status","signature_alg","agent_version","hostname","enrolled_at","last_seen_at","revoked_at"],"additionalProperties":false,"description":"An endpoint agent enrolled in this tenant."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range. `error.details` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key or an OAuth access token; the cases are not distinguished). The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but does not carry the scope this operation requires. `error.details.missing` lists the scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` (`key`, `tenant` or `service`) which limit it was.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["endpoints:read"]}],"x-hs-scope":{"scopes":["endpoints:read"]}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","method_not_allowed","rate_limited","internal_error","service_unavailable"],"description":"Closed vocabulary; new members may be added (see Versioning)."},"message":{"type":"string","description":"For a human reading a log. Not stable; do not parse it."},"request_id":{"type":"string","description":"Also the `X-Request-Id` response header."},"details":{"type":"object","additionalProperties":true,"description":"Diagnostic. Not part of the frozen contract."}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A tenant API key, created in the console under Settings → API keys with the minimum scopes it needs."},"oauth2":{"type":"oauth2","description":"A USER access token (`hs_at_…`) issued by the HodeiShield console, the OAuth 2.1 authorization server at `https://app.hodeishield.com/api/auth` (metadata: `/.well-known/oauth-authorization-server` on its origin). Authorization code with PKCE (S256, mandatory) for applications with a browser; the RFC 8628 device authorization grant (`https://app.hodeishield.com/api/auth/device/code`) for those without one. Every token is bound to ONE user and ONE tenant, chosen by the user on the consent screen, and carries read scopes only; the tenant is re-checked against what the user can see on every request. Public clients register themselves (RFC 7591) at `/oauth2/register`; the HodeiShield CLI is pre-registered as `hodeishield-cli`. Revocation: RFC 7009 at `/oauth2/revoke`, or by the user in the console under Account → Application access.","flows":{"authorizationCode":{"authorizationUrl":"https://app.hodeishield.com/api/auth/oauth2/authorize","tokenUrl":"https://app.hodeishield.com/api/auth/oauth2/token","refreshUrl":"https://app.hodeishield.com/api/auth/oauth2/token","scopes":{"supply_risk:read":"Read supply_risk data of the tenant the token is bound to.","compliance.nis2:read":"Read compliance.nis2 data of the tenant the token is bound to.","compliance.ens:read":"Read compliance.ens data of the tenant the token is bound to.","compliance.iso27001:read":"Read compliance.iso27001 data of the tenant the token is bound to.","compliance.dora:read":"Read compliance.dora data of the tenant the token is bound to.","compliance.gdpr:read":"Read compliance.gdpr data of the tenant the token is bound to.","compliance.soc2:read":"Read compliance.soc2 data of the tenant the token is bound to.","compliance.iso42001:read":"Read compliance.iso42001 data of the tenant the token is bound to.","compliance.nistcsf:read":"Read compliance.nistcsf data of the tenant the token is bound to.","compliance.pcidss:read":"Read compliance.pcidss data of the tenant the token is bound to.","compliance.euaiact:read":"Read compliance.euaiact data of the tenant the token is bound to.","compliance.hipaa:read":"Read compliance.hipaa data of the tenant the token is bound to.","compliance.cmmc:read":"Read compliance.cmmc data of the tenant the token is bound to.","compliance.cyberessentials:read":"Read compliance.cyberessentials data of the tenant the token is bound to.","compliance.uaeia:read":"Read compliance.uaeia data of the tenant the token is bound to.","compliance.sama:read":"Read compliance.sama data of the tenant the token is bound to.","compliance.saudiecc:read":"Read compliance.saudiecc data of the tenant the token is bound to.","compliance.ndpa:read":"Read compliance.ndpa data of the tenant the token is bound to.","radar:read":"Read radar data of the tenant the token is bound to.","connectors:read":"Read connectors data of the tenant the token is bound to.","endpoints:read":"Read endpoints data of the tenant the token is bound to.","hodeiai:read":"Read hodeiai data of the tenant the token is bound to.","virtual_ciso:read":"Read virtual_ciso data of the tenant the token is bound to.","simulator:read":"Read simulator data of the tenant the token is bound to.","evidence:read":"Read evidence data of the tenant the token is bound to.","reports:read":"Read reports data of the tenant the token is bound to.","management:read":"Read management data of the tenant the token is bound to.","offline_access":"Issue a refresh token (30 days, rotated on every use)."}}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]}]}
\ No newline at end of file
+{"openapi":"3.1.0","info":{"title":"Hodei-Shield API","version":"2026-10-16","summary":"Third-party risk and compliance posture, for your own systems.","description":"## Versioning\n\n`/v1` is frozen. These changes are **compatible** and will happen inside it\nwithout notice:\n\n- a new operation;\n- a new **optional** query parameter;\n- a new field in a response object;\n- a new value in a field documented as an open vocabulary (`status`,\n  `severity`, `evidence_type`, the keys of `by_status`);\n- a new `error.code`, always with the HTTP status its siblings already use;\n- anything under `error.details`, which is diagnostic and not part of the\n  contract — except `error.details.code` and the keys the error table of\n  the operation names (`missing`, `licence`, `parameter`, `scope`,\n  `limit`, `window_seconds`, `retry_after_seconds`): those are contract.\n  `error.details.code` is an OPEN vocabulary: a value, once published, keeps\n  its meaning and the HTTP status it is sent with; new values may be added.\n\nWrite your client so those do not break it: ignore unknown fields, do not\nswitch exhaustively on a documented-open vocabulary, and treat an unknown\n`error.code` as \"an error of this HTTP status\".\n\nThese changes are **incompatible** and will NOT happen inside `/v1`. They go\nto `/v2`, and `/v1` keeps serving:\n\n- removing or renaming an operation, a parameter or a field;\n- changing the type, the unit or the meaning of a field;\n- making an optional parameter required, or narrowing what one accepts;\n- changing which scope an operation requires;\n- changing the HTTP status an existing `error.code` is sent with.\n\n## Read-only\n\n`/v1` only reads. Every operation is a `GET`. Any other method (`POST`, `PUT`,\n`PATCH`, `DELETE`) on a path that exists answers **405** with `Allow: GET`, and on\na path that does not exist answers **404**: neither changes any state. A write\nwill be offered only as a new operation, which is a compatible change, once a\ncustomer asks for a concrete one.\n\n## Authentication\n\nEvery operation takes `Authorization: Bearer <credential>`. Three credentials\nexist:\n\n- a **tenant API key** (`hsk_…`): belongs to ONE tenant and carries an\n  explicit list of scopes; it can read nothing outside that tenant, whatever it\n  asks for;\n- a user's **OAuth access token** (`hs_at_…`): one user, ONE tenant chosen\n  at consent, read scopes only;\n- an MSSP **portfolio key** (`hsp_…`): held by a managed security service\n  provider, it reads ANY of its client tenants, ONE per request, selected with\n  the request header `X-HS-Tenant: <tenant id>` (a UUID, never a slug).\n  `GET /v1/portfolio/tenants` lists the tenants it may select. Read-only, with\n  a mandatory expiry. A tenant outside the key's portfolio answers **404**\n  (`error.details.code: \"TENANT_NOT_FOUND\"`), exactly as one that does not\n  exist.\n\nEvery successful (2xx) answer of a data operation carries `X-HS-Tenant` with\nthe id of the tenant whose data the body holds, for every credential; no error\ncarries it. A tenant API key or OAuth token may send `X-HS-Tenant` only with\nits own tenant's id; any other value is a **400**\n(`TENANT_SELECTOR_NOT_SUPPORTED`).\n\nEach operation below declares the scope it requires. A credential that\nauthenticates but lacks the scope is answered **403**\n(`error.details.code: \"INSUFFICIENT_SCOPE\"`), never 404: you are told what you\nare missing, not that the resource does not exist.\n\n## Errors\n\nEvery error has the same body:\n\n```json\n{ \"error\": { \"code\": \"forbidden\", \"message\": \"…\", \"request_id\": \"…\" } }\n```\n\nBranch on `code`, log `request_id`, show `message` to nobody but yourself.\n`request_id` is also the `X-Request-Id` response header, and it is what\nsupport will ask you for.\n\n## Rate limits\n\nEvery response that got past authentication carries the limit that is closest\nto being exhausted:\n\n- `RateLimit-Limit` — requests allowed in the window;\n- `RateLimit-Remaining` — requests left in the current window;\n- `RateLimit-Reset` — **seconds** until the window renews;\n- `RateLimit-Policy` — `<limit>;w=<window seconds>`.\n\nThree limits apply, each per one-minute window: per API key, per organisation\n(all of its keys together) and per service. The first two come from the licence\nof the organisation the key belongs to: a higher licence tier has more room, and\nan MSSP partner has more than a direct customer of the same tier. Read the\ncurrent limit from `RateLimit-Limit` and `RateLimit-Policy` rather than\nhard-coding it. When one is exhausted the answer is\n**429** with `error.code: \"rate_limited\"`, `Retry-After` (seconds) and\n`error.details.scope` (`key`, `tenant` or `service`) saying which. A\nportfolio key is limited per key (`portfolio_key`), per provider across all\nits portfolio keys (`portfolio_org`) and per service; once the selected tenant\nis known to be in its portfolio, the client tenant's own limit (`tenant`) and\nthe provider's share of it (`portfolio_tenant`) apply too. Your\norganisation's usage never counts against another's. Windows are fixed, so a\nclient can burst up to twice the limit across a window boundary: back off on\n`Retry-After` rather than pacing to the second. The limits are part of the\nservice, not of the frozen contract: they may be raised without notice.\n\n## Pagination, filtering and ordering\n\nEvery collection takes `page` and `per_page` (max 200) and answers with a\n`pagination` object carrying `total` and `total_pages`. Every collection\ntakes `sort` (an enum of the fields THAT collection can order by) and\n`order` (`asc`/`desc`, default `desc`). Filters are exact matches unless\nthe parameter says otherwise. A parameter or field with a known vocabulary lists\nit in `x-hs-known-values` (an OpenAPI extension, not a JSON Schema `enum`: the\nserver still accepts what it accepted before). Values retired from a parameter\nare listed in `x-hs-deprecated-values`, with the date until which the server is\ndocumented to accept them in `x-hs-deprecated-values-sunset`.\n\n## Contract changes\n\nCorrections and additions to the published contract, newest first. They ship\nwith the contract version (`info.version`) named in each entry. Detect a\ncapability by the operation, not by this string: the portfolio contract is\npresent when `GET /v1` lists `listPortfolioTenants`.\n\n- **2026-10-16 — addition: MSSP portfolio keys.** A third credential, the\n  portfolio key (`hsp_…`); the operation `GET /v1/portfolio/tenants`\n  (`listPortfolioTenants`, scope `portfolio:read`); the optional request\n  header `X-HS-Tenant` on every data operation, echoed on every 2xx answer of\n  them for every credential, with `Vary: X-HS-Tenant`;\n  `error.details.code` becomes contract (`TENANT_HEADER_INVALID`,\n  `TENANT_REQUIRED`, `TENANT_SELECTOR_NOT_SUPPORTED`, `TENANT_NOT_FOUND`,\n  `INSUFFICIENT_SCOPE`, `LICENCE_INACTIVE`), and every scope 403 now carries\n  `INSUFFICIENT_SCOPE`; three new 429 `details.scope` values\n  (`portfolio_key`, `portfolio_org`, `portfolio_tenant`). Nothing existing\n  was removed, renamed or re-statused.\n\n- **2026-10-16 — correction: alert `severity` is English.** `GET /v1/alerts`\n  and `GET /v1/alerts/{id}` returned `severity` as stored, in Spanish\n  (`critico`, `alto`, `medio`, `bajo`, `info`), while this document\n  promised `critical | high | medium | low`. They now return `critical`,\n  `high`, `medium`, `low` and `info` (`info` is added to the documented\n  values). **This changes what an integrator who adapted to the Spanish values\n  receives.** The `severity` filter accepts both the English values and the\n  Spanish ones; the Spanish ones are documented as accepted until\n  **2027-01-14** (90 days after this version), so switch to the English ones\n  before then. A value outside both lists is still matched exactly and matches\n  nothing. `GET /v1/risks`: the descriptions of `domain` and `status` named\n  values that do not exist; they now list the real ones (no value changed).","contact":{"name":"Hodeitek S.L.","url":"https://hodeishield.com"}},"servers":[{"url":"https://api.hodeishield.com"}],"tags":[{"name":"vendors"},{"name":"alerts"},{"name":"risks"},{"name":"compliance"},{"name":"evidence"},{"name":"endpoints"},{"name":"Portfolio"}],"paths":{"/v1/vendors":{"get":{"operationId":"listVendors","summary":"List third parties","description":"The tenant third-party inventory, newest first by default. Soft-deleted vendors are never returned.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, name.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","name"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring of the name or the domain.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"category","in":"query","required":false,"description":"Exact category match.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"active","in":"query","required":false,"description":"Filter by the operational flag.","schema":{"type":"string"}},{"name":"business_criticality","in":"query","required":false,"description":"Exact criticality match.","schema":{"type":"string","enum":["low","medium","high","critical"]}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/vendors/{id}":{"get":{"operationId":"getVendor","summary":"Fetch one third party","description":"The same object `listVendors` returns, for a single vendor.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["vendors"],"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier of the vendor in this tenant."},"name":{"type":"string","description":"Display name."},"legal_name":{"description":"Registered legal name, when it differs.","type":["string","null"]},"domain":{"description":"Primary domain, lowercase, no scheme.","type":["string","null"]},"category":{"description":"Free-text category assigned by the tenant.","type":["string","null"]},"vendor_type":{"description":"Kind of third party (provider, product, …).","type":["string","null"]},"access_level":{"description":"Level of access the vendor has to the tenant systems.","type":["string","null"]},"business_criticality":{"description":"low | medium | high | critical, as set by the tenant.","type":["string","null"]},"data_sensitivity":{"description":"public | internal | confidential | restricted.","type":["string","null"]},"economic_impact":{"description":"Estimated economic impact of an outage, in the tenant currency.","type":["number","null"]},"active":{"type":"boolean","description":"Whether the vendor is operationally enabled."},"monitoring_status":{"description":"Continuous-monitoring state.","type":["string","null"]},"last_scan_at":{"description":"RFC 3339, UTC. Null if never scanned.","type":["string","null"]},"lei":{"description":"Legal Entity Identifier (ISO 17442), for DORA RoI.","type":["string","null"]},"hq_country":{"description":"Head-office country, ISO 3166-1 alpha-2.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","name","legal_name","domain","category","vendor_type","access_level","business_criticality","data_sensitivity","economic_impact","active","monitoring_status","last_scan_at","lei","hq_country","created_at","updated_at"],"additionalProperties":false,"description":"A third party in the tenant inventory."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts":{"get":{"operationId":"listAlerts","summary":"List supply-chain alerts","description":"Alerts raised against the tenant vendors. Poll incrementally with `since` plus `order=asc`.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at.","schema":{"default":"created_at","type":"string","enum":["created_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Filter by the derived status.","schema":{"type":"string","enum":["open","acknowledged","resolved"]}},{"name":"severity","in":"query","required":false,"description":"Exact severity match, in the vocabulary the response uses (critical | high | medium | low | info). The legacy Spanish values (critico, alto, medio, bajo, info) are still accepted and mean the same; they are documented as accepted until 2027-01-14, so move to the English ones.","schema":{"x-hs-known-values":["critical","high","medium","low","info"],"x-hs-deprecated-values":["critico","alto","medio","bajo"],"x-hs-deprecated-values-sunset":"2027-01-14","type":"string","minLength":1,"maxLength":40}},{"name":"vendor_id","in":"query","required":false,"description":"Only alerts about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"since","in":"query","required":false,"description":"Only alerts created at or after this RFC 3339 instant.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.","x-hs-known-values":["critical","high","medium","low","info"],"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/alerts/{id}":{"get":{"operationId":"getAlert","summary":"Fetch one alert","description":"The same object `listAlerts` returns, for a single alert.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["alerts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The vendor this alert is about (`/v1/vendors/{id}`)."},"type":{"type":"string","description":"Alert family, e.g. `breach`, `cve`, `rating_drop`."},"severity":{"description":"critical | high | medium | low | info, when classified. Open vocabulary: a new value is a compatible change.","x-hs-known-values":["critical","high","medium","low","info"],"type":["string","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"source_url":{"description":"Where the finding came from, when public.","type":["string","null"]},"economic_impact":{"type":["number","null"]},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"Derived: resolved if closed, acknowledged if taken, otherwise open."},"acknowledged_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolved_at":{"description":"RFC 3339, UTC.","type":["string","null"]},"resolution_reason":{"description":"Why it was closed, when it was.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","vendor_id","type","severity","title","description","source_url","economic_impact","status","acknowledged_at","resolved_at","resolution_reason","created_at"],"additionalProperties":false,"description":"A supply-chain alert raised against one vendor."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks":{"get":{"operationId":"listRisks","summary":"List risk-register entries","description":"The tenant risk register, with inherent and residual figures.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, updated_at, inherent_score, residual_score.","schema":{"default":"created_at","type":"string","enum":["created_at","updated_at","inherent_score","residual_score"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":24}},{"name":"domain","in":"query","required":false,"description":"Exact domain match.","schema":{"type":"string","minLength":1,"maxLength":20}},{"name":"vendor_id","in":"query","required":false,"description":"Only risks linked to this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"min_inherent_score","in":"query","required":false,"description":"Only risks whose inherent score is at least this.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational."},"status":{"type":"string","description":"Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed."},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/risks/{id}":{"get":{"operationId":"getRisk","summary":"Fetch one risk-register entry","description":"The same object `listRisks` returns, for a single entry.\n\nRequired scope: `supply_risk:read`. Published in `/v1` since 2026-09-20.","tags":["risks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Risk identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"type":["string","null"]},"domain":{"type":"string","description":"Risk domain: vendor | cyber | data | operational | compliance | concentration | strategic | legal | financial | reputational."},"status":{"type":"string","description":"Risk lifecycle status: identified | assessed | treatment_planned | treatment_implemented | closed."},"treatment":{"description":"mitigate | accept | transfer | avoid.","type":["string","null"]},"treatment_notes":{"type":["string","null"]},"threat_source":{"type":["string","null"]},"vulnerability":{"type":["string","null"]},"likelihood_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"impact_inherent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"inherent_score":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"likelihood_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"impact_residual":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"residual_score":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"manual | imported | derived."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"User of this tenant who owns the risk."},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor this risk is about, when any."},"control_codes":{"type":"array","items":{"type":"string"},"description":"Framework control codes linked to the risk."},"review_date":{"description":"Calendar date, `YYYY-MM-DD`.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."},"updated_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","title","description","domain","status","treatment","treatment_notes","threat_source","vulnerability","likelihood_inherent","impact_inherent","inherent_score","likelihood_residual","impact_residual","residual_score","source","owner_user_id","vendor_id","control_codes","review_date","created_at","updated_at"],"additionalProperties":false,"description":"An entry of the tenant risk register."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["supply_risk:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["supply_risk:read"]}}},"/v1/compliance/controls":{"get":{"operationId":"listComplianceControls","summary":"List control status for a framework","description":"Per-control status of one framework. Requires the read scope OF THAT FRAMEWORK: `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: control_code, last_evaluated_at.","schema":{"default":"control_code","type":"string","enum":["control_code","last_evaluated_at"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"framework","in":"query","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","minLength":1,"maxLength":20}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Framework slug the control belongs to."},"control_code":{"type":"string","description":"Control identifier inside the framework."},"status":{"type":"string","description":"missing | partial | covered, as evaluated by the platform."},"evidence_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Evidence items currently linked to the control."},"last_evaluated_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["framework","control_code","status","evidence_count","last_evaluated_at"],"additionalProperties":false,"description":"The tenant status of one framework control."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/compliance/frameworks/{framework}":{"get":{"operationId":"getFrameworkPosture","summary":"Framework posture summary","description":"Counts of evaluated controls by status for one framework, for a dashboard tile. Requires `compliance.<framework>:read`.\n\nRequired scope: `compliance.<framework>:read`. Published in `/v1` since 2026-09-20.","tags":["compliance"],"parameters":[{"name":"framework","in":"path","required":true,"description":"Framework slug. One of: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa.","schema":{"type":"string"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"framework":{"type":"string"},"controls_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Controls the platform has evaluated."},"by_status":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Control count per status. Keys are whatever statuses exist; may grow."},"evidence_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of the evidence linked across the evaluated controls."},"last_evaluated_at":{"description":"Most recent control evaluation, RFC 3339 UTC. Null if never evaluated.","type":["string","null"]}},"required":["framework","controls_total","by_status","evidence_total","last_evaluated_at"],"additionalProperties":false,"description":"Posture summary for one framework."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}],"x-hs-scope":{"template":"compliance.<framework>:read"}}},"/v1/evidence":{"get":{"operationId":"listEvidence","summary":"List security evidence","description":"Evidence held for the tenant. Use `expiring_before` plus `sort=valid_until&order=asc` for a renewal queue.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: created_at, valid_until.","schema":{"default":"created_at","type":"string","enum":["created_at","valid_until"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"evidence_type","in":"query","required":false,"description":"Exact type match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"source_type","in":"query","required":false,"description":"Exact producer match.","schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"vendor_id","in":"query","required":false,"description":"Only evidence about this vendor.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"expiring_before","in":"query","required":false,"description":"Only evidence with a `valid_until` strictly before this `YYYY-MM-DD`.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/evidence/{id}":{"get":{"operationId":"getEvidence","summary":"Fetch one evidence item","description":"The same object `listEvidence` returns, for a single item.\n\nRequired scope: `evidence:read`. Published in `/v1` since 2026-09-20.","tags":["evidence"],"parameters":[{"name":"id","in":"path","required":true,"description":"Evidence identifier.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"evidence_type":{"type":"string","description":"What kind of evidence this is."},"source_type":{"type":"string","description":"Which subsystem produced it."},"source_id":{"type":"string","description":"Its identifier inside that subsystem."},"title":{"type":"string"},"description":{"type":["string","null"]},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The vendor it is about, when any."},"asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The asset it is about, when any."},"auto_generated":{"type":"boolean","description":"False when a person uploaded it."},"valid_until":{"description":"Calendar date, `YYYY-MM-DD`. Null = no expiry.","type":["string","null"]},"created_at":{"type":"string","description":"RFC 3339, UTC."}},"required":["id","evidence_type","source_type","source_id","title","description","vendor_id","asset_id","auto_generated","valid_until","created_at"],"additionalProperties":false,"description":"One item of security evidence."}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["evidence:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["evidence:read"]}}},"/v1/endpoints":{"get":{"operationId":"listEndpoints","summary":"List enrolled endpoint agents","description":"The endpoint agents enrolled in this tenant. `silent_since` selects the ones that have gone quiet, including those that never reported.\n\nRequired scope: `endpoints:read`. Published in `/v1` since 2026-09-20.","tags":["endpoints"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: enrolled_at, last_seen_at, producer.","schema":{"default":"enrolled_at","type":"string","enum":["enrolled_at","last_seen_at","producer"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"status","in":"query","required":false,"description":"Exact status match.","schema":{"type":"string","enum":["active","revoked"]}},{"name":"silent_since","in":"query","required":false,"description":"Agents last seen before this RFC 3339 instant, or never seen at all.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"X-HS-Tenant","in":"header","required":false,"description":"The tenant to read, as its id (a UUID, any case). REQUIRED with a portfolio key (`hsp_…`); with a tenant API key or an OAuth token, optional and accepted only when it equals the credential’s own tenant. Never a slug.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"X-HS-Tenant":{"description":"The id (lowercase UUID) of the tenant whose data this body holds, for every credential. Present on every 2xx answer of a data operation and on no error. A client that selected a tenant must refuse a 2xx whose echo is missing or different.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"producer":{"type":"string","description":"The agent name, unique among the active ones of the tenant."},"producer_kind":{"type":"string","description":"What kind of producer it is."},"status":{"type":"string","description":"active | revoked."},"signature_alg":{"type":"string","description":"Algorithm this enrollment signs with."},"agent_version":{"type":["string","null"]},"hostname":{"description":"Last hostname the agent reported.","type":["string","null"]},"enrolled_at":{"type":"string","description":"RFC 3339, UTC."},"last_seen_at":{"description":"RFC 3339, UTC. Null until the first envelope.","type":["string","null"]},"revoked_at":{"description":"RFC 3339, UTC.","type":["string","null"]}},"required":["id","producer","producer_kind","status","signature_alg","agent_version","hostname","enrolled_at","last_seen_at","revoked_at"],"additionalProperties":false,"description":"An endpoint agent enrolled in this tenant."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource in this tenant. With a portfolio key, also: the selected tenant does not exist or is not in this key’s portfolio (`error.details.code` is `TENANT_NOT_FOUND`; the two cases are one answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"oauth2":["endpoints:read"]},{"portfolioKey":[]}],"x-hs-scope":{"scopes":["endpoints:read"]}}},"/v1/portfolio/tenants":{"get":{"operationId":"listPortfolioTenants","summary":"List the client tenants of an MSSP portfolio","description":"Every tenant the presented PORTFOLIO key may select with `X-HS-Tenant`: the MSSP’s own tenants (its internal one included) and every tenant of its active client organisations, active or not, licensed or not, narrowed to the key’s client subset when it has one. Membership is evaluated live on every request. Only a portfolio key (`hsp_…`) can call this operation; this operation never takes `X-HS-Tenant`.\n\nRequired scope: `portfolio:read`. Published in `/v1` since 2026-10-16.","tags":["Portfolio"],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Items per page, 1..200. Defaults to 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"sort","in":"query","required":false,"description":"Field to order by. One of: name, slug.","schema":{"default":"name","type":"string","enum":["name","slug"]}},{"name":"order","in":"query","required":false,"description":"Sort direction. Defaults to desc.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Stable identifier (lowercase). The ONLY value `X-HS-Tenant` accepts."},"name":{"type":"string","description":"Display name. Untrusted text."},"slug":{"type":"string","description":"Short name, unique across the platform. A client may resolve a slug to an `id` from this list; the server never accepts a slug as a selector."},"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false,"description":"The organisation the tenant belongs to: the MSSP itself for the tenants it holds directly (including its internal one), or the client organisation."},"internal":{"type":"boolean","description":"True only for the MSSP’s own internal tenant."},"active":{"type":"boolean","description":"Whether the tenant is enabled. A deactivated tenant is listed but cannot be read."},"licence_status":{"type":"string","description":"Open vocabulary: `in_force` (licence in force), `grace` (grace period: reads are served), `inactive` (none, suspended, revoked or expired: data operations answer 403 `LICENCE_INACTIVE`). Treat an unknown value as \"may not be readable\". A tenant is readable when `active` is true and `licence_status` is not `inactive`.","x-hs-known-values":["in_force","grace","inactive"]}},"required":["id","name","slug","organization","internal","active","licence_status"],"additionalProperties":false,"description":"A client tenant an MSSP portfolio key may select."}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The page that was served."},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items per page in effect."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total items matching the filters, across all pages."},"total_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of pages at this `per_page`."}},"required":["page","per_page","total","total_pages"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A parameter is missing, malformed or out of range: `error.details.issues` names it. Or the `X-HS-Tenant` header was refused (`error.details.parameter` is `X-HS-Tenant`): `TENANT_HEADER_INVALID` (not exactly one UUID), `TENANT_REQUIRED` (a portfolio key on a data operation without it) or `TENANT_SELECTOR_NOT_SUPPORTED` (on `listPortfolioTenants`, or a tenant API key / OAuth token naming a tenant other than its own) in `error.details.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No credential, or one that is unknown, malformed, revoked or expired (a tenant API key, an OAuth access token or a portfolio key; the cases are not distinguished), a portfolio key whose organisation is no longer an active MSSP, or a portfolio key used from an address outside its allowed ranges. The `WWW-Authenticate` header carries `resource_metadata`, the RFC 9728 document that names the authorization server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential authenticated but may not perform this operation. Either it does not carry the scope the operation requires (`error.details.code` is `INSUFFICIENT_SCOPE` and `error.details.missing` lists the scopes), or the tenant read (the credential’s own, or the one a portfolio key selected) is deactivated or holds no licence in force: none, suspended, revoked or expired, or a write during the grace period (`error.details.code` is `LICENCE_INACTIVE` and `error.details.licence` says which). Re-authenticating does not help with the second.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rate limit is exhausted. `Retry-After` says when to come back and `error.details.scope` which limit it was: `key`, `tenant` or `service`; with a portfolio key also `portfolio_key`, `portfolio_org` or `portfolio_tenant`.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the window that is closest to being exhausted.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Requests left in that window.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until that window renews.","schema":{"type":"integer","minimum":0}},"RateLimit-Policy":{"description":"`<limit>;w=<window seconds>`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side. `error.request_id` is what support needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service cannot verify credentials right now. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"portfolioKey":[]}],"x-hs-scope":{"scopes":["portfolio:read"]}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","method_not_allowed","rate_limited","internal_error","service_unavailable"],"description":"Closed vocabulary; new members may be added (see Versioning)."},"message":{"type":"string","description":"For a human reading a log. Not stable; do not parse it."},"request_id":{"type":"string","description":"Also the `X-Request-Id` response header."},"details":{"type":"object","additionalProperties":true,"description":"Diagnostic, except `code` and the keys the operation’s error descriptions name, which are contract.","properties":{"code":{"type":"string","description":"OPEN vocabulary (a value keeps its meaning and its HTTP status; new values may be added): `TENANT_HEADER_INVALID`, `TENANT_REQUIRED`, `TENANT_SELECTOR_NOT_SUPPORTED` (400), `INSUFFICIENT_SCOPE`, `LICENCE_INACTIVE` (403), `TENANT_NOT_FOUND` (404).","x-hs-known-values":["TENANT_HEADER_INVALID","TENANT_REQUIRED","TENANT_SELECTOR_NOT_SUPPORTED","INSUFFICIENT_SCOPE","LICENCE_INACTIVE","TENANT_NOT_FOUND"]}}}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A tenant API key, created in the console under Settings → API keys with the minimum scopes it needs."},"portfolioKey":{"type":"http","scheme":"bearer","description":"An MSSP portfolio key (`hsp_…`), created by an organisation administrator of an active managed security service provider in the console’s MSSP area (API keys). It lists the provider’s client tenants (`portfolio:read`) and reads ONE of them per request, selected with `X-HS-Tenant`, with the same data scopes a tenant API key uses. Read-only; mandatory expiry (default 90 days, at most 365); optional client subset and source IP ranges. Refused with 401 everywhere but `/v1`."},"oauth2":{"type":"oauth2","description":"A USER access token (`hs_at_…`) issued by the HodeiShield console, the OAuth 2.1 authorization server at `https://app.hodeishield.com/api/auth` (metadata: `/.well-known/oauth-authorization-server` on its origin). Authorization code with PKCE (S256, mandatory) for applications with a browser; the RFC 8628 device authorization grant (`https://app.hodeishield.com/api/auth/device/code`) for those without one. Every token is bound to ONE user and ONE tenant, chosen by the user on the consent screen, and carries read scopes only; the tenant is re-checked against what the user can see on every request. Public clients register themselves (RFC 7591) at `/oauth2/register`; the HodeiShield CLI is pre-registered as `hodeishield-cli`. Revocation: RFC 7009 at `/oauth2/revoke`, or by the user in the console under Account → Application access.","flows":{"authorizationCode":{"authorizationUrl":"https://app.hodeishield.com/api/auth/oauth2/authorize","tokenUrl":"https://app.hodeishield.com/api/auth/oauth2/token","refreshUrl":"https://app.hodeishield.com/api/auth/oauth2/token","scopes":{"supply_risk:read":"Read supply_risk data of the tenant the token is bound to.","compliance.nis2:read":"Read compliance.nis2 data of the tenant the token is bound to.","compliance.ens:read":"Read compliance.ens data of the tenant the token is bound to.","compliance.iso27001:read":"Read compliance.iso27001 data of the tenant the token is bound to.","compliance.dora:read":"Read compliance.dora data of the tenant the token is bound to.","compliance.gdpr:read":"Read compliance.gdpr data of the tenant the token is bound to.","compliance.soc2:read":"Read compliance.soc2 data of the tenant the token is bound to.","compliance.iso42001:read":"Read compliance.iso42001 data of the tenant the token is bound to.","compliance.nistcsf:read":"Read compliance.nistcsf data of the tenant the token is bound to.","compliance.pcidss:read":"Read compliance.pcidss data of the tenant the token is bound to.","compliance.euaiact:read":"Read compliance.euaiact data of the tenant the token is bound to.","compliance.hipaa:read":"Read compliance.hipaa data of the tenant the token is bound to.","compliance.cmmc:read":"Read compliance.cmmc data of the tenant the token is bound to.","compliance.cyberessentials:read":"Read compliance.cyberessentials data of the tenant the token is bound to.","compliance.uaeia:read":"Read compliance.uaeia data of the tenant the token is bound to.","compliance.sama:read":"Read compliance.sama data of the tenant the token is bound to.","compliance.saudiecc:read":"Read compliance.saudiecc data of the tenant the token is bound to.","compliance.ndpa:read":"Read compliance.ndpa data of the tenant the token is bound to.","radar:read":"Read radar data of the tenant the token is bound to.","connectors:read":"Read connectors data of the tenant the token is bound to.","endpoints:read":"Read endpoints data of the tenant the token is bound to.","hodeiai:read":"Read hodeiai data of the tenant the token is bound to.","virtual_ciso:read":"Read virtual_ciso data of the tenant the token is bound to.","simulator:read":"Read simulator data of the tenant the token is bound to.","evidence:read":"Read evidence data of the tenant the token is bound to.","reports:read":"Read reports data of the tenant the token is bound to.","ai_governance:read":"Read ai_governance data of the tenant the token is bound to.","management:read":"Read management data of the tenant the token is bound to.","offline_access":"Issue a refresh token (30 days, rotated on every use)."}}}}}},"security":[{"bearerAuth":[]},{"oauth2":[]},{"portfolioKey":[]}]}
\ No newline at end of file
diff --git a/packaging/container/Dockerfile b/packaging/container/Dockerfile
new file mode 100644
index 0000000..c6ad107
--- /dev/null
+++ b/packaging/container/Dockerfile
@@ -0,0 +1,19 @@
+# The HodeiShield CLI image. It contains only the release's own, already verified binary (see
+# .github/workflows/container-image.yml), never one built here, on a base image with CA
+# certificates and nothing else: no shell and no package manager.
+#
+# Build context: a directory holding amd64/hodeishield and arm64/hodeishield, the binaries from the
+# release's x86_64 and aarch64 musl archives, plus LICENSE and NOTICE.
+#
+# The base is gcr.io/distroless/static-debian12:nonroot, pinned by the digest of its multi-arch
+# index (dependabot proposes newer digests). It ships /etc/ssl/certs/ca-certificates.crt, which the
+# CLI reads as the operating system's trust store, and runs as uid/gid 65532.
+FROM gcr.io/distroless/static-debian12:nonroot@sha256:afa5c872c891853ca7fcf1f12c3edb23f7eeef36189728842dd51042ff57f7ab
+
+ARG TARGETARCH
+
+COPY --chmod=0555 ${TARGETARCH}/hodeishield /usr/local/bin/hodeishield
+COPY LICENSE NOTICE /licenses/
+
+USER 65532:65532
+ENTRYPOINT ["/usr/local/bin/hodeishield"]
diff --git a/packaging/repo/repo-test-minio.Dockerfile b/packaging/repo/repo-test-minio.Dockerfile
new file mode 100644
index 0000000..b454958
--- /dev/null
+++ b/packaging/repo/repo-test-minio.Dockerfile
@@ -0,0 +1,14 @@
+# The S3-compatible server and client that repo-test.sh publishes to: MinIO, built from its source at
+# the releases below (the project no longer publishes images or binaries). Go fetches the modules
+# through the checksum database, so what is built is fixed by the two tags and the Go image.
+# MinIO is licensed under the GNU AGPL v3; it is built and run here only as a throwaway test
+# service inside CI and is never shipped or distributed with the CLI or its packages.
+# Bumped by hand in the periodic dependency review (CONTRIBUTING.md).
+ARG BASE
+FROM golang:1.24-trixie@sha256:5835f052b784aa39f2fe9070def3568605c8bc3fcd810f10402066348b61e716 AS build
+ENV GOBIN=/out CGO_ENABLED=0
+RUN go install github.com/minio/minio@RELEASE.2025-09-07T16-13-09Z \
+  && go install github.com/minio/mc@RELEASE.2025-08-13T08-35-41Z
+
+FROM ${BASE}
+COPY --from=build /out/minio /out/mc /usr/local/bin/
diff --git a/packaging/repo/repo-test.sh b/packaging/repo/repo-test.sh
new file mode 100644
index 0000000..3344c90
--- /dev/null
+++ b/packaging/repo/repo-test.sh
@@ -0,0 +1,778 @@
+#!/bin/sh
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Hodeitek S.L.
+#
+# Security tests of the repository builder (build.sh and publish.sh). They run in CI only, in the
+# repository-builder-tests workflow: the cases that must be refused plant forged packages and indexes
+# in a bucket on purpose, and nothing here is meant to be run by hand.
+#
+#   repo-test.sh
+#
+# Environment:
+#   NFPM          absolute path to the nfpm binary (the version pinned in the workflow)
+#
+# Everything is made here and thrown away: the signing keys (a certify-only RSA 4096 primary with a
+# signing subkey, like the real one, and a second key for the forgeries), synthetic hodeishield
+# packages built with nfpm from a one-line program, and a MinIO whose publishing user may list, read
+# and write but not delete (built from source: repo-test-minio.Dockerfile). The real build.sh and publish.sh run in the image named in
+# packaging/repo/image. The bucket is then served over HTTP to an apt and a dnf client.
+#
+# Every case has an expected outcome, and the run fails if any case ends otherwise:
+#   - publishing a valid release must work (into an empty bucket, on top, again, and a third time);
+#   - the builder must refuse a bucket that holds anything the signed index does not vouch for, an
+#     index that is not the signed one, or a release that is not the hodeishield package, and then
+#     leave the bucket exactly as it was;
+#   - the clients must refuse a tampered index, a corrupt package and a package that is not signed
+#     with the repository key, and must install and upgrade from the untampered repository.
+
+set -eu
+
+here=$(cd "$(dirname "$0")" && pwd)
+root=$(cd "$here/../.." && pwd)
+: "${NFPM:?}"
+for need in docker jq curl gzip sha256sum; do
+  command -v "$need" > /dev/null || {
+    printf 'repo-test.sh: %s is required\n' "$need" >&2
+    exit 2
+  }
+done
+# shellcheck source=/dev/null
+. "$here/image"
+
+builder=rt-builder
+net=rt-net
+minio=rt-minio
+mcbox=rt-mc
+rootuser=rtroot
+rootpass="rtroot-secret-123"
+pubuser=pubuser
+pubpass="pubuser-secret-123"
+srv=http://$minio:9000
+
+uid=$(id -u)
+gid=$(id -g)
+work=$(mktemp -d "${TMPDIR:-/tmp}/repo-test.XXXXXX")
+results=$work/results.tsv
+: > "$results"
+failed=0
+mkdir -p "$work/bin" "$work/t"
+
+# Only the cases that must pass, to check the harness itself.
+positive_only=${REPO_TEST_POSITIVE_ONLY:-}
+
+print_table() {
+  [ -s "$results" ] || return 0
+  printf '\n%-6s %-62s %-46s %s\n' RESULT CASE EXPECTED GOT
+  awk -F'\t' '{ printf "%-6s %-62s %-46s %s\n", $4, $1, $2, $3 }' "$results"
+  printf '\n%s cases, %s failed\n' "$(wc -l < "$results" | tr -d ' ')" \
+    "$(awk -F'\t' '$4 == "FAIL" { n++ } END { print n + 0 }' "$results")"
+}
+
+cleanup() {
+  status=$?
+  trap - EXIT
+  print_table
+  docker rm -f "$minio" "$mcbox" > /dev/null 2>&1 || true
+  docker network rm "$net" > /dev/null 2>&1 || true
+  rm -rf "$work"
+  if [ "$status" = 0 ] && [ "$failed" != 0 ]; then
+    status=1
+  fi
+  exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+group() { printf '::group::%s\n' "$*"; }
+endgroup() { printf '::endgroup::\n'; }
+
+# A path under $work, as the containers see it (they mount $work at /w).
+inw() { printf '/w/%s' "${1#"$work"/}"; }
+
+# record <case> <expected> <got> <PASS|FAIL>
+record() {
+  printf '%s\t%s\t%s\t%s\n' "$1" "$2" "$3" "$4" >> "$results"
+  if [ "$4" != PASS ]; then
+    failed=1
+    printf '::error::%s: expected %s, got %s\n' "$1" "$2" "$3"
+  fi
+}
+
+# --- The builder image ---------------------------------------------------------------------------------
+group "Build the repository image"
+# shellcheck disable=SC2153
+docker build --quiet --tag "$builder" - << EOF
+FROM $IMAGE
+RUN apt-get update -qq && apt-get install -y -qq --no-install-recommends $PACKAGES \
+  && rm -rf /var/lib/apt/lists/*
+EOF
+endgroup
+
+# Runs a command in the builder image, with $work at /w.
+tool() {
+  docker run --rm --user "$uid:$gid" --env HOME=/tmp --volume "$work:/w" --workdir /w "$builder" "$@"
+}
+
+# --- Helper scripts that run in the builder image -----------------------------------------------------
+cat > "$work/bin/keys.sh" << 'EOF'
+set -eu
+export HOME=/tmp
+quiet() { gpg --batch --quiet --pinentry-mode loopback --passphrase '' "$@"; }
+fingerprint() { gpg --batch --with-colons --list-keys | awk -F: '$1 == "fpr" { print $10; exit }'; }
+
+# The repository key: a primary that can only certify, and a signing subkey. Only the subkey's secret
+# part reaches the keyring that the builder uses.
+GNUPGHOME=/w/gnupg-primary
+export GNUPGHOME
+mkdir -m 700 "$GNUPGHOME"
+quiet --quick-generate-key 'HodeiShield repository test key <repo-test@example.invalid>' rsa4096 cert never
+primary=$(fingerprint)
+quiet --quick-add-key "$primary" rsa4096 sign never
+gpg --batch --armor --export "$primary" > /w/pub.asc
+quiet --export-secret-subkeys "$primary" > /w/subkey.gpg
+gpgconf --kill all
+
+GNUPGHOME=/w/gnupg-sign
+export GNUPGHOME
+mkdir -m 700 "$GNUPGHOME"
+gpg --batch --quiet --import /w/subkey.gpg
+sub=$(gpg --batch --with-colons --list-secret-keys |
+  awk -F: '$1 == "ssb" { sign = ($12 ~ /s/) } $1 == "fpr" && sign { print $10; sign = 0 }')
+[ "$(printf '%s\n' "$sub" | grep -c .)" = 1 ]
+printf '%s!\n' "$sub" > /w/signing_key
+gpgconf --kill all
+rm -f /w/subkey.gpg
+
+# Another key, for forgeries.
+GNUPGHOME=/w/gnupg-evil
+export GNUPGHOME
+mkdir -m 700 "$GNUPGHOME"
+quiet --quick-generate-key 'Another key <other@example.invalid>' rsa2048 sign never
+other=$(fingerprint)
+printf '%s\n' "$other" > /w/evil.fpr
+gpg --batch --armor --export "$other" > /w/evil.asc
+gpgconf --kill all
+EOF
+
+# signrpm.sh <gnupghome> <key> <public key> <rpm>...
+cat > "$work/bin/signrpm.sh" << 'EOF'
+set -eu
+export HOME=/tmp
+home=$1 key=$2 pub=$3
+shift 3
+db=$(mktemp -d)
+trap 'rm -rf "$db"' EXIT
+rpm --dbpath "$db" --import "$pub"
+GNUPGHOME=$home rpmsign --define "_dbpath $db" --define "_gpg_name $key" \
+  --define "_gpg_digest_algo sha512" --addsign "$@" > /dev/null
+EOF
+
+# rpmrepo.sh <dir>: a DNF repository of the packages in <dir>, with repomd.xml signed by the repository key.
+cat > "$work/bin/rpmrepo.sh" << 'EOF'
+set -eu
+export HOME=/tmp GNUPGHOME=/w/gnupg-sign
+createrepo_c --quiet --no-database --general-compress-type=gz "$1"
+gpg --batch --yes --local-user "$(cat /w/signing_key)" --digest-algo SHA512 --armor --detach-sign \
+  --output "$1/repodata/repomd.xml.asc" "$1/repodata/repomd.xml"
+EOF
+
+# evilsign.sh <in> <out>: clear-signs a file with the other key.
+cat > "$work/bin/evilsign.sh" << 'EOF'
+set -eu
+export HOME=/tmp GNUPGHOME=/w/gnupg-evil
+gpg --batch --yes --local-user "$(cat /w/evil.fpr)" --digest-algo SHA512 --clearsign --output "$2" "$1"
+EOF
+
+# --- Client scripts (run as root in the apt and dnf containers) --------------------------------------
+cat > "$work/bin/apt-client.sh" << 'EOF'
+# apt-client.sh ok <url 1> <url 2> <version 1> <version 2>
+# apt-client.sh refuse <index|package> <url> [<pattern>]
+set -u
+export DEBIAN_FRONTEND=noninteractive
+only="-o Dir::Etc::sourcelist=/etc/apt/sources.list.d/hodeishield.list -o Dir::Etc::sourceparts=/nonexistent"
+setup() {
+  mkdir -p /etc/apt/keyrings
+  curl -fsS "$1/gpg.key" -o /etc/apt/keyrings/hodeishield.asc || { echo "SETUP: cannot fetch the key"; exit 90; }
+  echo "deb [signed-by=/etc/apt/keyrings/hodeishield.asc] $1/apt stable main" > /etc/apt/sources.list.d/hodeishield.list
+}
+mode=$1
+shift
+case $mode in
+ok)
+  set -e
+  setup "$1"
+  apt-get $only update
+  apt-get $only install -y hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $3" ]
+  setup "$2"
+  apt-get $only update
+  apt-get $only install -y --only-upgrade hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $4" ]
+  echo "OK: installed $3 and upgraded to $4, with the repository's signatures checked"
+  ;;
+refuse)
+  kind=$1 url=$2 pattern=${3:-.}
+  setup "$url"
+  out=$(apt-get $only update 2>&1)
+  rc=$?
+  echo "$out"
+  if [ "$kind" = index ]; then
+    [ "$rc" != 0 ] || { echo "NOT REFUSED: apt-get update accepted the index"; exit 1; }
+  else
+    [ "$rc" = 0 ] || { echo "SETUP: apt-get update failed on a valid index"; exit 1; }
+  fi
+  out2=$(apt-get $only install -y hodeishield 2>&1)
+  rc2=$?
+  echo "$out2"
+  [ "$rc2" != 0 ] || { echo "NOT REFUSED: hodeishield was installed"; exit 1; }
+  if dpkg -s hodeishield > /dev/null 2>&1; then
+    echo "NOT REFUSED: hodeishield is installed"
+    exit 1
+  fi
+  line=$(printf '%s\n%s\n' "$out" "$out2" | grep -E "$pattern" | head -n 1)
+  [ -n "$line" ] || { echo "NOT REFUSED FOR THE EXPECTED REASON"; exit 1; }
+  echo "REFUSED: $line"
+  ;;
+esac
+EOF
+
+cat > "$work/bin/dnf-client.sh" << 'EOF'
+# dnf-client.sh ok <url 1> <url 2> <version 1> <version 2>
+# dnf-client.sh refuse <index|package> <url> [<pattern>]
+set -uf
+dnfq="dnf -y --disablerepo=* --enablerepo=hodeishield"
+repo=/etc/yum.repos.d/hodeishield.repo
+setup() {
+  curl -fsS "$1/rpm/hodeishield.repo" -o "$repo" || { echo "SETUP: cannot fetch the .repo file"; exit 90; }
+  sed -i "s#https://packages.hodeishield.com#$1#g" "$repo"
+  grep -qx 'gpgcheck=1' "$repo" && grep -qx 'repo_gpgcheck=1' "$repo" || { echo "SETUP: signature checks are off"; exit 90; }
+}
+mode=$1
+shift
+case $mode in
+ok)
+  set -e
+  setup "$1"
+  $dnfq install hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $3" ]
+  sed -i "s#$1#$2#g" "$repo"
+  dnf clean all
+  $dnfq upgrade --refresh hodeishield
+  [ "$(hodeishield --version)" = "hodeishield $4" ]
+  grep -qx 'gpgcheck=1' "$repo" && grep -qx 'repo_gpgcheck=1' "$repo"
+  echo "OK: installed $3 and upgraded to $4, with gpgcheck and repo_gpgcheck on"
+  ;;
+refuse)
+  kind=$1 url=$2 pattern=${3:-.}
+  setup "$url"
+  out=$($dnfq makecache 2>&1)
+  rc=$?
+  echo "$out"
+  if [ "$kind" = index ]; then
+    [ "$rc" != 0 ] || { echo "NOT REFUSED: dnf accepted the metadata"; exit 1; }
+  else
+    [ "$rc" = 0 ] || { echo "SETUP: dnf could not read valid metadata"; exit 1; }
+  fi
+  out2=$($dnfq install hodeishield 2>&1)
+  rc2=$?
+  echo "$out2"
+  [ "$rc2" != 0 ] || { echo "NOT REFUSED: hodeishield was installed"; exit 1; }
+  if rpm -q hodeishield > /dev/null 2>&1; then
+    echo "NOT REFUSED: hodeishield is installed"
+    exit 1
+  fi
+  line=$(printf '%s\n%s\n' "$out" "$out2" | grep -E "$pattern" | head -n 1)
+  [ -n "$line" ] || { echo "NOT REFUSED FOR THE EXPECTED REASON"; exit 1; }
+  echo "REFUSED: $line"
+  ;;
+esac
+EOF
+
+# --- Keys ------------------------------------------------------------------------------------------------
+group "Throwaway keys"
+tool sh /w/bin/keys.sh
+signing_key=$(cat "$work/signing_key")
+find "$work" -maxdepth 1 -type f | sort | tr '\n' ' '
+printf '\nsigning subkey %s\n' "$signing_key"
+endgroup
+
+# --- Packages ------------------------------------------------------------------------------------------
+# mkpkgs <out dir> <name> <version> <what the program prints>: .deb and .rpm for amd64 and arm64.
+mkpkgs() {
+  out=$1 name=$2 version=$3 says=$4
+  config=$root/packaging/nfpm.yaml
+  if [ "$name" != hodeishield ]; then
+    config=$work/nfpm-$name.yaml
+    sed "s/^name: hodeishield\$/name: $name/" "$root/packaging/nfpm.yaml" > "$config"
+  fi
+  stage=$(mktemp -d "$work/stage.XXXXXX")
+  mkdir -p "$stage/man" "$stage/completions" "$out"
+  printf '#!/bin/sh\necho "%s"\n' "$says" > "$stage/hodeishield"
+  chmod 755 "$stage/hodeishield"
+  printf '.TH HODEISHIELD 1\n' | gzip -9n > "$stage/man/hodeishield.1.gz"
+  for completion in hodeishield.bash _hodeishield hodeishield.fish; do
+    printf '# test\n' > "$stage/completions/$completion"
+  done
+  cp "$root/LICENSE" "$root/NOTICE" "$stage/"
+  for arch in amd64 arm64; do
+    for packager in deb rpm; do
+      (cd "$stage" && VERSION=$version ARCH=$arch "$NFPM" package -f "$config" -p "$packager" -t "$out/" > /dev/null)
+    done
+  done
+  rm -rf "$stage"
+}
+
+group "Synthetic packages"
+pk=$work/pk
+mkpkgs "$pk/v1" hodeishield 0.2.0 "hodeishield 0.2.0"
+mkpkgs "$pk/v2" hodeishield 0.2.1 "hodeishield 0.2.1"
+mkpkgs "$pk/v3" hodeishield 0.2.2 "hodeishield 0.2.2"
+ls "$pk/v1" "$pk/v2" "$pk/v3"
+endgroup
+
+# --- MinIO ------------------------------------------------------------------------------------------------
+group "MinIO"
+docker build --quiet --tag rt-minio-image --build-arg BASE="$IMAGE" - < "$here/repo-test-minio.Dockerfile" > /dev/null
+docker network create "$net" > /dev/null
+docker run -d --name "$minio" --network "$net" --env MINIO_ROOT_USER="$rootuser" \
+  --env MINIO_ROOT_PASSWORD="$rootpass" rt-minio-image minio server /data > /dev/null
+docker run -d --name "$mcbox" --network "$net" --user "$uid:$gid" --env MC_CONFIG_DIR=/tmp/mc \
+  --volume "$work:/w" rt-minio-image sleep 86400 > /dev/null
+mcx() { docker exec "$mcbox" mc "$@"; }
+tries=0
+until mcx alias set r "$srv" "$rootuser" "$rootpass" > /dev/null 2>&1; do
+  tries=$((tries + 1))
+  [ "$tries" -lt 60 ] || {
+    echo "repo-test.sh: MinIO did not start" >&2
+    docker logs "$minio" >&2
+    exit 1
+  }
+  sleep 1
+done
+# The publishing user may list, read and write, never delete (like the real one).
+cat > "$work/policy.json" << 'EOF'
+{"Version": "2012-10-17", "Statement": [
+  {"Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::rt-*"]},
+  {"Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject"], "Resource": ["arn:aws:s3:::rt-*/*"]}]}
+EOF
+mcx admin policy create r rt-nodelete /w/policy.json > /dev/null
+mcx admin user add r "$pubuser" "$pubpass" > /dev/null
+mcx admin policy attach r rt-nodelete --user "$pubuser" > /dev/null
+mcx alias set u "$srv" "$pubuser" "$pubpass" > /dev/null
+endgroup
+
+newbucket() {
+  mcx mb --quiet "r/$1" > /dev/null
+  mcx anonymous set download "r/$1" > /dev/null
+}
+# clone <from> <to>
+clone() {
+  newbucket "$2"
+  mcx mirror --quiet "r/$1" "r/$2" > /dev/null
+}
+# put <bucket> <key> <file>
+put() { mcx cp --quiet "$(inw "$3")" "r/$1/$2" > /dev/null; }
+# del <bucket> <key>
+del() { mcx rm --quiet "r/$1/$2" > /dev/null; }
+# get <bucket> <key> <file>
+get() { mcx cat "r/$1/$2" > "$3"; }
+# snap <bucket>: every object with its size, ETag and modification time.
+snap() { mcx ls --recursive --json "r/$1" | jq -r '[.key, (.size | tostring), .etag, .lastModified] | @tsv' | sort; }
+# packages_of <bucket>: the packages in the bucket.
+packages_of() { snap "$1" | awk -F'\t' '$1 ~ /^apt\/pool\// || $1 ~ /^rpm\/[^\/]*\/[^\/]*\.rpm$/'; }
+# hash_of <InRelease> <arch>: the SHA256 that the signed index gives for that architecture's Packages.
+hash_of() {
+  awk -v f="main/binary-$2/Packages" '/^[^ ]/ { s = ($0 == "SHA256:"); next } s && $3 == f { print $1 }' "$1"
+}
+
+# publish <bucket> <new packages dir>: runs publish.sh as the workflow does; sets $out and $rc.
+publish() {
+  rc=0
+  out=$(docker run --rm --network "$net" --user "$uid:$gid" --env HOME=/tmp \
+    --env PACKAGES_S3_ENDPOINT="$srv" --env PACKAGES_S3_REGION=us-east-1 --env PACKAGES_S3_BUCKET="$1" \
+    --env PACKAGES_S3_ACCESS_KEY_ID="$pubuser" --env PACKAGES_S3_SECRET_ACCESS_KEY="$pubpass" \
+    --env SIGNING_KEY="$signing_key" --env GNUPGHOME=/gnupg --env PUBLIC_KEY=/gpg.key \
+    --volume "$work/gnupg-sign:/gnupg" --volume "$work/pub.asc:/gpg.key:ro" \
+    --volume "$here:/repo:ro" --volume "$2:/new:ro" \
+    "$builder" sh /repo/publish.sh /new 2>&1) || rc=$?
+}
+
+# must_publish <case> <description> <bucket> <new dir>
+must_publish() {
+  group "$1 $2"
+  publish "$3" "$4"
+  if [ "$rc" = 0 ] && printf '%s\n' "$out" | grep -q '^Repository built and verified'; then
+    verdict=PASS
+    got="exit 0, repository built and verified"
+  else
+    verdict=FAIL
+    got="exit $rc"
+    printf '%s\n' "$out"
+  fi
+  printf '%s\n' "$out" | tail -n 3
+  endgroup
+  record "$1 $2" "publishes" "$got" "$verdict"
+}
+
+# must_refuse <case> <description> <bucket> <message (regex)> [<new dir>]
+# The bucket is as the caller left it; publishing must fail with that message and change nothing.
+must_refuse() {
+  id=$1 desc=$2 bucket=$3 message=$4 newdir=${5:-$pk/v3}
+  group "$id $desc"
+  before=$(snap "$bucket")
+  publish "$bucket" "$newdir"
+  after=$(snap "$bucket")
+  verdict=PASS
+  if [ "$rc" = 0 ]; then
+    verdict=FAIL
+    got="PUBLISHED (exit 0)"
+  else
+    got="refused (exit $rc)"
+    line=$(printf '%s\n' "$out" | grep -E "$message" | head -n 1 || true)
+    if [ -z "$line" ]; then
+      verdict=FAIL
+      got="$got, for another reason"
+    fi
+  fi
+  if [ "$before" = "$after" ]; then
+    got="$got, bucket and InRelease unchanged"
+  else
+    verdict=FAIL
+    got="$got, BUCKET CHANGED"
+    printf '%s\n' "$before" > "$work/t/before"
+    printf '%s\n' "$after" > "$work/t/after"
+    diff -u "$work/t/before" "$work/t/after" || true
+  fi
+  [ "$verdict" = PASS ] || printf '%s\n' "$out"
+  printf '%s\n' "$out" | tail -n 3
+  endgroup
+  record "$id $desc" "refused, nothing uploaded" "$got" "$verdict"
+}
+
+# --- Must pass: publishing -------------------------------------------------------------------------------
+newbucket rt-v1
+must_publish P1 "release 0.2.0 into an empty bucket" rt-v1 "$pk/v1"
+for key in gpg.key index.html apt/dists/stable/InRelease apt/dists/stable/Release.gpg rpm/hodeishield.repo \
+  rpm/x86_64/repodata/repomd.xml.asc rpm/aarch64/repodata/repomd.xml.asc; do
+  mcx stat "r/rt-v1/$key" > /dev/null 2>&1 || record "P1 $key is published" present missing FAIL
+done
+
+clone rt-v1 rt-v2
+must_publish P2 "release 0.2.1 on top of 0.2.0" rt-v2 "$pk/v2"
+get rt-v2 apt/pool/main/h/hodeishield/hodeishield_0.2.0-1_amd64.deb "$work/t/old.deb" ||
+  record "P2 the earlier release is still there" present missing FAIL
+get rt-v2 apt/dists/stable/main/binary-amd64/Packages "$work/t/Packages"
+if grep -q '^Version: 0.2.0-1$' "$work/t/Packages" && grep -q '^Version: 0.2.1-1$' "$work/t/Packages"; then
+  record "P2 the index lists both releases" "0.2.0 and 0.2.1" "0.2.0 and 0.2.1" PASS
+else
+  record "P2 the index lists both releases" "0.2.0 and 0.2.1" "see Packages" FAIL
+fi
+
+before=$(packages_of rt-v2)
+must_publish P3 "release 0.2.1 again (idempotent)" rt-v2 "$pk/v2"
+if [ "$before" = "$(packages_of rt-v2)" ]; then
+  record "P3 published packages untouched" "same objects" "same objects" PASS
+else
+  record "P3 published packages untouched" "same objects" "CHANGED" FAIL
+fi
+
+clone rt-v2 rt-ctl
+must_publish P4 "release 0.2.2 on the base of the refusal cases" rt-ctl "$pk/v3"
+
+# --- Must pass: clients ----------------------------------------------------------------------------------
+docker build --quiet --tag rt-apt-client - << 'EOF' > /dev/null
+FROM debian:stable
+RUN apt-get update -qq && apt-get install -y -qq --no-install-recommends curl ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+EOF
+
+# client <apt|dnf> <case> <description> <expected> <script args...>: the script exits 0 when it got what it expected.
+client() {
+  kind=$1 id=$2 desc=$3 expected=$4
+  shift 4
+  case $kind in
+    apt) image=rt-apt-client ;;
+    dnf) image=rockylinux:9 ;;
+  esac
+  group "$id $desc"
+  rc=0
+  out=$(docker run --rm --network "$net" --volume "$work/bin:/b:ro" "$image" sh "/b/$kind-client.sh" "$@" 2>&1) || rc=$?
+  printf '%s\n' "$out" | tail -n 40
+  endgroup
+  line=$(printf '%s\n' "$out" | grep -E '^(OK|REFUSED):' | tail -n 1 || true)
+  if [ "$rc" = 0 ] && [ -n "$line" ]; then
+    record "$id $desc" "$expected" "$(printf '%s' "$line" | cut -c1-120)" PASS
+  else
+    record "$id $desc" "$expected" "exit $rc: $(printf '%s\n' "$out" | tail -n 1 | cut -c1-100)" FAIL
+  fi
+}
+
+client apt P5 "apt (debian:stable) installs 0.2.0, upgrades to 0.2.1" "installs and upgrades" \
+  ok "$srv/rt-v1" "$srv/rt-v2" 0.2.0 0.2.1
+client dnf P6 "dnf (rockylinux:9) installs 0.2.0, upgrades to 0.2.1" "installs and upgrades" \
+  ok "$srv/rt-v1" "$srv/rt-v2" 0.2.0 0.2.1
+
+if [ -n "$positive_only" ]; then
+  exit 0
+fi
+
+# --- The forgeries ------------------------------------------------------------------------------------
+group "Forged packages and indexes"
+mkpkgs "$pk/evil" hodeishield 9.9.9 "evil"
+mkpkgs "$pk/ssh" openssh-server 99.0.0 "not hodeishield"
+mkpkgs "$pk/alt" hodeishield 0.2.1 "hodeishield 0.2.1 with another payload"
+evil_deb=$pk/evil/hodeishield_9.9.9-1_amd64.deb
+ssh_deb=$pk/ssh/openssh-server_99.0.0-1_amd64.deb
+ssh_rpm=openssh-server-99.0.0-1.x86_64.rpm
+# The same .rpm files signed with the repository key, and with another key.
+mkdir -p "$work/ours" "$work/other"
+cp "$pk/v1/hodeishield-0.2.0-1.x86_64.rpm" "$pk/ssh/$ssh_rpm" "$work/ours/"
+cp "$pk/evil/hodeishield-9.9.9-1.x86_64.rpm" "$pk/v2/hodeishield-0.2.1-1.x86_64.rpm" "$work/other/"
+tool sh /w/bin/signrpm.sh /w/gnupg-sign "$signing_key" /w/pub.asc \
+  /w/ours/hodeishield-0.2.0-1.x86_64.rpm "/w/ours/$ssh_rpm"
+tool sh /w/bin/signrpm.sh /w/gnupg-evil "$(cat "$work/evil.fpr")" /w/evil.asc \
+  /w/other/hodeishield-9.9.9-1.x86_64.rpm /w/other/hodeishield-0.2.1-1.x86_64.rpm
+# An index that lists an extra package, and the signed Release of the base, to forge from.
+base=rt-v2
+get rt-v2 apt/dists/stable/InRelease "$work/t/InRelease"
+get rt-v2 apt/dists/stable/Release "$work/t/Release"
+get rt-v1 apt/dists/stable/InRelease "$work/t/InRelease.old"
+real_hash=$(hash_of "$work/t/InRelease" amd64)
+get rt-v2 "apt/dists/stable/main/binary-amd64/by-hash/SHA256/$real_hash" "$work/t/Packages.real"
+{
+  cat "$work/t/Packages.real"
+  printf '\nPackage: hodeishield\nVersion: 9.9.9-1\nArchitecture: amd64\n'
+  printf 'Filename: pool/main/h/hodeishield/hodeishield_9.9.9-1_amd64.deb\nSize: %s\nSHA256: %s\n' \
+    "$(wc -c < "$evil_deb" | tr -d ' ')" "$(sha256sum < "$evil_deb" | cut -d' ' -f1)"
+} > "$work/t/Packages.evil"
+evil_hash=$(sha256sum < "$work/t/Packages.evil" | cut -d' ' -f1)
+evil_size=$(wc -c < "$work/t/Packages.evil" | tr -d ' ')
+awk -v old="$real_hash" -v new="$evil_hash" -v size="$evil_size" \
+  '$1 == old && $3 == "main/binary-amd64/Packages" { print " " new " " size " " $3; next } { print }' \
+  "$work/t/Release" > "$work/t/Release.evil"
+tool sh /w/bin/evilsign.sh /w/t/Release.evil /w/t/InRelease.evil
+endgroup
+
+H=apt/pool/main/h/hodeishield
+IR=apt/dists/stable/InRelease
+BH=apt/dists/stable/main/binary-amd64/by-hash/SHA256
+
+# fresh <id>: a copy of the base to plant things in.
+fresh() { clone "$base" "rt-$1"; }
+
+# Things in the pool that are not the package the signed index vouches for.
+fresh b01
+put rt-b01 apt/pool/main/o/openssh-server/openssh-server_99.0.0-1_amd64.deb "$ssh_deb"
+must_refuse B01 "deb of another package, outside the expected path" rt-b01 "build.sh: unexpected files in the bucket"
+
+fresh b02
+put rt-b02 "$H/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B02 "planted hodeishield deb, not in the signed index" rt-b02 "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b03
+put rt-b03 "$H/hodeishield_9.9.9-1_amd64.deb" "$ssh_deb"
+must_refuse B03 "other package's deb renamed hodeishield_9.9.9" rt-b03 "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b04
+put rt-b04 "$H/hodeishield_0.2.1-1_amd64.deb" "$evil_deb"
+must_refuse B04 "published deb overwritten with another payload" rt-b04 "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b05
+printf 'not a package\n' > "$work/t/README"
+put rt-b05 "$H/README" "$work/t/README"
+must_refuse B05 "stray file in the pool" rt-b05 "build.sh: unexpected files in the bucket"
+
+fresh b06
+put rt-b06 "$H/sub/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B06 "deb in a subdirectory of the pool" rt-b06 "build.sh: unexpected files in the bucket"
+
+fresh b07
+put rt-b07 "$H/hodeishield_9 9_amd64.deb" "$evil_deb"
+put rt-b07 "$H/-hodeishield_9.9_amd64.deb" "$evil_deb"
+must_refuse B07 "deb file names with a space or a leading dash" rt-b07 "build.sh: unexpected files in the bucket"
+
+# Things among the RPMs.
+fresh b08
+put rt-b08 rpm/x86_64/hodeishield-9.9.9-1.x86_64.rpm "$pk/evil/hodeishield-9.9.9-1.x86_64.rpm"
+must_refuse B08 "unsigned rpm" rt-b08 "build.sh: .* is not signed with the repository key"
+
+fresh b09
+put rt-b09 rpm/x86_64/hodeishield-9.9.9-1.x86_64.rpm "$work/other/hodeishield-9.9.9-1.x86_64.rpm"
+must_refuse B09 "rpm signed by another key" rt-b09 "build.sh: .* is not signed with the repository key"
+
+fresh b10
+put rt-b10 "rpm/x86_64/$ssh_rpm" "$work/ours/$ssh_rpm"
+must_refuse B10 "rpm of another package signed with our key" rt-b10 "build.sh: unexpected files in the bucket"
+
+fresh b11
+put rt-b11 rpm/x86_64/hodeishield-99.0.0-1.x86_64.rpm "$work/ours/$ssh_rpm"
+must_refuse B11 "our-key rpm named hodeishield with another package inside" rt-b11 \
+  "build.sh: .* is not the hodeishield package for x86_64"
+
+fresh b12
+put rt-b12 rpm/aarch64/hodeishield-0.2.0-1.aarch64.rpm "$work/ours/hodeishield-0.2.0-1.x86_64.rpm"
+must_refuse B12 "our-key x86_64 rpm under an aarch64 name" rt-b12 "build.sh: .* is not the hodeishield package for aarch64"
+
+fresh b13
+put rt-b13 rpm/x86_64/hodeishield-0.2.5-1.x86_64.rpm "$work/ours/hodeishield-0.2.0-1.x86_64.rpm"
+must_refuse B13 "our-key rpm renamed to another version" rt-b13 "build.sh: .* is not the hodeishield package for x86_64"
+
+fresh b14
+put rt-b14 rpm/noarch/hodeishield-0.2.0-1.noarch.rpm "$work/ours/hodeishield-0.2.0-1.x86_64.rpm"
+must_refuse B14 "rpm in an unexpected architecture directory" rt-b14 "build.sh: unexpected files in the bucket"
+
+fresh b15
+put rt-b15 "rpm/x86_64/x digests signatures OK.rpm" "$pk/evil/hodeishield-9.9.9-1.x86_64.rpm"
+must_refuse B15 "rpm whose file name imitates rpm's verdict" rt-b15 "build.sh: unexpected files in the bucket"
+
+# The signed index.
+fresh b16
+put rt-b16 "$BH/$real_hash" "$work/t/Packages.evil"
+put rt-b16 "$H/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B16 "tampered by-hash Packages and a planted deb" rt-b16 \
+  "build.sh: the published Packages \(amd64\) does not match the published InRelease"
+
+fresh b17
+sed 's/^Codename: stable$/Codename: stablf/' "$work/t/InRelease" > "$work/t/InRelease.edit"
+put rt-b17 "$IR" "$work/t/InRelease.edit"
+must_refuse B17 "InRelease edited after signing" rt-b17 "build.sh: the published InRelease does not verify"
+
+fresh b18
+cat "$work/t/InRelease" "$work/t/InRelease" > "$work/t/InRelease.two"
+put rt-b18 "$IR" "$work/t/InRelease.two"
+must_refuse B18 "InRelease with two signed blocks" rt-b18 \
+  "(build|publish).sh: the published InRelease (is not a single signed message|does not give one SHA256)"
+
+fresh b19
+{ printf 'text before the signed message\n'; cat "$work/t/InRelease"; } > "$work/t/InRelease.before"
+put rt-b19 "$IR" "$work/t/InRelease.before"
+must_refuse B19 "InRelease with text before the signed message" rt-b19 \
+  "build.sh: the published InRelease is not a single signed message"
+
+fresh b20
+{ cat "$work/t/InRelease"; printf 'text after the signed message\n'; } > "$work/t/InRelease.after"
+put rt-b20 "$IR" "$work/t/InRelease.after"
+must_refuse B20 "InRelease with text after the signed message" rt-b20 \
+  "build.sh: the published InRelease is not a single signed message"
+
+fresh b21
+put rt-b21 "$IR" "$work/t/InRelease.evil"
+put rt-b21 "$BH/$evil_hash" "$work/t/Packages.evil"
+put rt-b21 "$H/hodeishield_9.9.9-1_amd64.deb" "$evil_deb"
+must_refuse B21 "InRelease re-signed with another key, with its Packages and deb" rt-b21 \
+  "build.sh: the published InRelease does not verify"
+
+fresh b22
+del rt-b22 "$IR"
+must_refuse B22 "InRelease removed while the pool is not empty" rt-b22 \
+  "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b23
+put rt-b23 "$IR" "$work/t/InRelease.old"
+must_refuse B23 "an older InRelease, validly signed" rt-b23 \
+  "build.sh: .* is in the bucket but neither in the signed index"
+
+fresh b24
+put rt-b24 "$IR" "$work/policy.json"
+must_refuse B24 "InRelease replaced by a file that is not signed" rt-b24 \
+  "publish.sh: the published InRelease does not give one SHA256"
+
+fresh b25
+del rt-b25 "$H/hodeishield_0.2.0-1_amd64.deb"
+must_refuse B25 "a deb that the signed index lists is gone" rt-b25 "build.sh: the signed index lists .*, which is not in the bucket"
+
+# The release itself.
+fresh n01
+must_refuse N01 "release holds a deb of another package" rt-n01 "build.sh: not a hodeishield package file" "$pk/ssh"
+
+fresh n02
+mkdir -p "$work/n02"
+cp "$ssh_deb" "$work/n02/hodeishield_0.2.2-1_amd64.deb"
+must_refuse N02 "release holds another package's deb named hodeishield" rt-n02 \
+  "build.sh: .* is not the hodeishield package" "$work/n02"
+
+fresh n03
+mkdir -p "$work/n03"
+cp "$pk/ssh/$ssh_rpm" "$work/n03/hodeishield-0.2.2-1.x86_64.rpm"
+must_refuse N03 "release holds another package's rpm named hodeishield" rt-n03 \
+  "build.sh: .* is not the hodeishield package for its architecture" "$work/n03"
+
+fresh n04
+mkdir -p "$work/n04"
+cp "$pk/alt/hodeishield_0.2.1-1_amd64.deb" "$work/n04/"
+must_refuse N04 "same deb file name as a published one, other content" rt-n04 \
+  "build.sh: .* is already published with different content" "$work/n04"
+
+fresh n05
+mkdir -p "$work/n05"
+cp "$pk/alt/hodeishield-0.2.1-1.x86_64.rpm" "$work/n05/"
+must_refuse N05 "same rpm file name as a published one, other content" rt-n05 \
+  "build.sh: .* is already published with different content" "$work/n05"
+
+# The user of the bucket cannot delete, as in production.
+rc=0
+mcx rm --quiet "u/rt-ctl/gpg.key" > /dev/null 2>&1 || rc=$?
+if [ "$rc" != 0 ] && mcx stat "r/rt-ctl/gpg.key" > /dev/null 2>&1; then
+  record "S1 the publishing user cannot delete" "delete denied" "denied" PASS
+else
+  record "S1 the publishing user cannot delete" "delete denied" "ALLOWED" FAIL
+fi
+
+# --- Clients must refuse -----------------------------------------------------------------------------------
+# Tampered copies of the published repository (rt-v2), served as they are.
+sig='BADSIG|signature verification failed|is not signed'
+fresh c1
+sed 's/^Codename: stable$/Codename: stablf/' "$work/t/InRelease" > "$work/t/InRelease.c1"
+put rt-c1 "$IR" "$work/t/InRelease.c1"
+client apt C1 "apt: InRelease tampered" "update and install refused" refuse index "$srv/rt-c1" "$sig"
+
+fresh c2
+del rt-c2 "$IR"
+sed 's/^Codename: stable$/Codename: stablf/' "$work/t/Release" > "$work/t/Release.c2"
+put rt-c2 apt/dists/stable/Release "$work/t/Release.c2"
+client apt C2 "apt: Release tampered (no InRelease)" "update and install refused" refuse index "$srv/rt-c2" "$sig"
+
+fresh c3
+get rt-v2 rpm/x86_64/repodata/repomd.xml "$work/t/repomd.xml"
+sed 's#<revision>#<revision>9#' "$work/t/repomd.xml" > "$work/t/repomd.xml.c3"
+cmp -s "$work/t/repomd.xml" "$work/t/repomd.xml.c3" && {
+  echo "repo-test.sh: repomd.xml has no <revision>" >&2
+  exit 1
+}
+put rt-c3 rpm/x86_64/repodata/repomd.xml "$work/t/repomd.xml.c3"
+client dnf C3 "dnf: repomd.xml tampered" "metadata and install refused" refuse index "$srv/rt-c3" 'Bad GPG signature'
+
+# flip <file>: the same file with one byte changed.
+flip() {
+  cp "$1" "$2"
+  printf 'X' | dd of="$2" bs=1 seek=200 conv=notrunc 2> /dev/null
+}
+
+fresh c4
+get rt-v2 "$H/hodeishield_0.2.1-1_amd64.deb" "$work/t/c4.deb"
+flip "$work/t/c4.deb" "$work/t/c4.bad.deb"
+cmp -s "$work/t/c4.deb" "$work/t/c4.bad.deb" && exit 1
+put rt-c4 "$H/hodeishield_0.2.1-1_amd64.deb" "$work/t/c4.bad.deb"
+client apt C4 "apt: corrupt deb (one byte changed)" "install refused" refuse package "$srv/rt-c4" 'Hash Sum mismatch|unexpected size'
+
+fresh c5
+get rt-v2 rpm/x86_64/hodeishield-0.2.1-1.x86_64.rpm "$work/t/c5.rpm"
+flip "$work/t/c5.rpm" "$work/t/c5.bad.rpm"
+cmp -s "$work/t/c5.rpm" "$work/t/c5.bad.rpm" && exit 1
+put rt-c5 rpm/x86_64/hodeishield-0.2.1-1.x86_64.rpm "$work/t/c5.bad.rpm"
+client dnf C5 "dnf: corrupt rpm (one byte changed)" "install refused" refuse package "$srv/rt-c5" "checksum doesn't match|Cannot download"
+
+# A repository whose metadata is signed with the repository key but whose only package is not.
+for pair in c6:pk/v2 c7:other; do
+  id=${pair%%:*} dir=${pair##*:}
+  mkdir -p "$work/$id/x86_64"
+  cp "$work/$dir/hodeishield-0.2.1-1.x86_64.rpm" "$work/$id/x86_64/"
+  tool sh /w/bin/rpmrepo.sh "/w/$id/x86_64"
+  fresh "$id"
+  mcx rm --recursive --force "r/rt-$id/rpm/x86_64" > /dev/null
+  mcx mirror --quiet "/w/$id/x86_64" "r/rt-$id/rpm/x86_64" > /dev/null
+done
+client dnf C6 "dnf: unsigned rpm, gpgcheck=1" "install refused" refuse package "$srv/rt-c6" \
+  'is not signed|GPG check FAILED'
+client dnf C7 "dnf: rpm signed by another key, gpgcheck=1" "install refused" refuse package "$srv/rt-c7" \
+  'Public key for .* is not installed|GPG check FAILED'
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 39fcbcd..b91e5c5 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -13,7 +13,8 @@
 //!
 //! Rules it applies:
 //! - Response objects become structs that ignore unknown fields, so a newer `/v1` (which only adds)
-//!   does not break an older client.
+//!   does not break an older client. An object declared open (`additionalProperties: true`) stays
+//!   a JSON map instead, so none of its keys is lost.
 //! - Enums in responses stay `String`: the contract says vocabularies may grow.
 //! - Enums in query parameters become Rust enums: the client only sends what the document lists.
 //! - Two schemas with the same shape become one type; two different shapes wanting the same name
@@ -31,7 +32,7 @@ use std::process::{Command, ExitCode, Stdio};
 const SPEC: &str = "openapi/v1.json";
 const OUT: &str = "crates/hodeishield-api/src/generated.rs";
 /// SHA-256 of `openapi/v1.json`. Updating the document means updating this and `openapi/README.md`.
-const EXPECTED_SHA256: &str = "103e86f38f7b3eff45a0f764c8142b4bdd2e8d576385b1b4ccf588cbf0518fb3";
+const EXPECTED_SHA256: &str = "1321a417aba28e7b60dbc28a35ce2dc3711d8973b985107f7701d70ff3be6b0d";
 
 /// Type names that the default naming rules would get wrong, keyed by the schema's location.
 const RENAMES: &[(&str, &str)] = &[
@@ -174,6 +175,12 @@ struct Param {
     ty: String,
     required: bool,
     is_enum: bool,
+    /// The values `x-hs-known-values` lists, in document order; empty without the extension.
+    known_values: Vec<String>,
+    /// The values `x-hs-deprecated-values` lists, in document order; empty without the extension.
+    deprecated_values: Vec<String>,
+    /// `x-hs-deprecated-values-sunset`: the last day the deprecated values are accepted.
+    sunset: Option<String>,
     doc: Option<String>,
 }
 
@@ -186,6 +193,8 @@ struct OperationDef {
     path_params: Vec<Param>,
     query_params: Vec<Param>,
     response: String,
+    /// Whether the operation takes the `X-HS-Tenant` header that selects a client tenant.
+    tenant_scoped: bool,
 }
 
 struct Generator<'a> {
@@ -376,6 +385,7 @@ impl<'a> Generator<'a> {
 
         let mut path_params = Vec::new();
         let mut query_params = Vec::new();
+        let mut tenant_scoped = false;
         for param in operation
             .get("parameters")
             .and_then(Value::as_array)
@@ -387,6 +397,12 @@ impl<'a> Generator<'a> {
                 .and_then(Value::as_str)
                 .ok_or_else(|| format!("{id}: parameter without name"))?;
             let location = param.get("in").and_then(Value::as_str).unwrap_or_default();
+            // The tenant selection is not an argument of the generated function: the client adds it
+            // to every request of an operation that takes it (see `ClientBuilder::tenant`).
+            if location == "header" && name.eq_ignore_ascii_case("X-HS-Tenant") {
+                tenant_scoped = true;
+                continue;
+            }
             let required = param
                 .get("required")
                 .and_then(Value::as_bool)
@@ -411,6 +427,9 @@ impl<'a> Generator<'a> {
                 ty,
                 required,
                 is_enum,
+                known_values: known_values(&id, name, param)?,
+                deprecated_values: deprecated_values(&id, name, param)?,
+                sunset: sunset(&id, name, param)?,
                 doc: param
                     .get("description")
                     .and_then(Value::as_str)
@@ -445,6 +464,7 @@ impl<'a> Generator<'a> {
             path_params,
             query_params,
             response,
+            tenant_scoped,
         });
         Ok(())
     }
@@ -511,6 +531,11 @@ impl<'a> Generator<'a> {
     }
 
     fn object_type(&mut self, schema: &Value, hint: &str, location: &str) -> Result<String> {
+        // An object declared open keeps every key it is sent: a struct would drop the ones it does
+        // not list. Its listed properties are documented, not typed.
+        if schema.get("additionalProperties") == Some(&Value::Bool(true)) {
+            return Ok("serde_json::Map<String, serde_json::Value>".to_owned());
+        }
         let Some(properties) = schema.get("properties").and_then(Value::as_object) else {
             return match schema.get("additionalProperties") {
                 Some(additional @ Value::Object(_)) => {
@@ -743,16 +768,47 @@ impl<'a> Generator<'a> {
         out.push_str("/// Every `/v1` operation, as the OpenAPI document describes it.\npub mod operations {\n    use crate::Operation;\n\n");
         for op in &self.operations {
             let scopes: Vec<String> = op.scopes.iter().map(|s| format!("{s:?}")).collect();
+            let known: Vec<String> = op
+                .query_params
+                .iter()
+                .filter(|p| !p.known_values.is_empty())
+                .map(|p| {
+                    let values: Vec<String> =
+                        p.known_values.iter().map(|v| format!("{v:?}")).collect();
+                    format!("({:?}, &[{}])", p.json_name, values.join(", "))
+                })
+                .collect();
+            let deprecated: Vec<String> = op
+                .query_params
+                .iter()
+                .filter(|p| !p.deprecated_values.is_empty())
+                .map(|p| {
+                    let values: Vec<String> = p
+                        .deprecated_values
+                        .iter()
+                        .map(|v| format!("{v:?}"))
+                        .collect();
+                    format!(
+                        "crate::DeprecatedValues {{ param: {:?}, values: &[{}], sunset: {:?} }}",
+                        p.json_name,
+                        values.join(", "),
+                        p.sunset
+                    )
+                })
+                .collect();
             let _ = writeln!(
                 out,
-                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}] }};\n",
+                "    /// `GET {}`: {}.\n    pub const {}: Operation = Operation {{ id: {:?}, method: \"GET\", path: {:?}, summary: {:?}, scopes: &[{}], known_values: &[{}], deprecated_values: &[{}], tenant_scoped: {} }};\n",
                 op.path,
                 op.summary,
                 screaming(&op.id),
                 op.id,
                 op.path,
                 op.summary,
-                scopes.join(", ")
+                scopes.join(", "),
+                known.join(", "),
+                deprecated.join(", "),
+                op.tenant_scoped
             );
         }
         let all: Vec<String> = self.operations.iter().map(|op| screaming(&op.id)).collect();
@@ -818,6 +874,67 @@ fn render_doc(out: &mut String, doc: Option<&str>, indent: &str) {
     }
 }
 
+/// The extension `key` of a parameter: on its `schema`, where the document puts it, or else on the
+/// parameter object itself.
+fn extension<'v>(param: &'v Value, key: &str) -> Option<&'v Value> {
+    param
+        .get("schema")
+        .and_then(|schema| schema.get(key))
+        .or_else(|| param.get(key))
+}
+
+/// The extension `key` of a parameter as a list of strings, in document order; empty when it is
+/// absent. When present it must be an array of strings, anything else is an error.
+fn string_list(operation: &str, name: &str, param: &Value, key: &str) -> Result<Vec<String>> {
+    let Some(list) = extension(param, key) else {
+        return Ok(Vec::new());
+    };
+    list.as_array()
+        .and_then(|items| {
+            items
+                .iter()
+                .map(|v| v.as_str().map(str::to_owned))
+                .collect::<Option<Vec<_>>>()
+        })
+        .ok_or_else(|| format!("{operation}.{name}: {key} must be an array of strings"))
+}
+
+/// The vocabulary `x-hs-known-values` publishes for a query parameter, in document order.
+fn known_values(operation: &str, name: &str, param: &Value) -> Result<Vec<String>> {
+    string_list(operation, name, param, "x-hs-known-values")
+}
+
+/// The values `x-hs-deprecated-values` lists for a query parameter, in document order: still
+/// accepted by the API, but on their way out.
+fn deprecated_values(operation: &str, name: &str, param: &Value) -> Result<Vec<String>> {
+    string_list(operation, name, param, "x-hs-deprecated-values")
+}
+
+/// `x-hs-deprecated-values-sunset`: the last day the deprecated values are accepted. Optional; when
+/// present it must be a `YYYY-MM-DD` date and the parameter must list deprecated values.
+fn sunset(operation: &str, name: &str, param: &Value) -> Result<Option<String>> {
+    let key = "x-hs-deprecated-values-sunset";
+    let Some(value) = extension(param, key) else {
+        return Ok(None);
+    };
+    let date = value
+        .as_str()
+        .filter(|date| {
+            date.len() == 10
+                && date.bytes().enumerate().all(|(i, b)| match i {
+                    4 | 7 => b == b'-',
+                    _ => b.is_ascii_digit(),
+                })
+        })
+        .ok_or_else(|| format!("{operation}.{name}: {key} must be a YYYY-MM-DD date"))?;
+    if deprecated_values(operation, name, param)?.is_empty() {
+        return Err(format!(
+            "{operation}.{name}: {key} without x-hs-deprecated-values"
+        ));
+    }
+    Ok(Some(date.to_owned()))
+}
+
 fn operation_id(operation: &Value) -> Result<&str> {
     operation
         .get("operationId")
@@ -958,4 +1075,255 @@ mod tests {
         assert_eq!(resource_name("getFrameworkPosture"), "FrameworkPosture");
         assert_eq!(resource_name("listComplianceControls"), "ComplianceControl");
     }
+
+    /// A minimal document with one operation whose `severity` query parameter carries `extension`
+    /// (when given) and whose `page` parameter never does.
+    fn document(extension: Option<Value>) -> Value {
+        let mut severity = serde_json::json!({
+            "name": "severity", "in": "query", "schema": {"type": "string"}
+        });
+        if let Some(extension) = extension {
+            severity["x-hs-known-values"] = extension;
+        }
+        document_with(severity, &[])
+    }
+
+    /// The same document with the `severity` parameter given whole, and `headers` added after the
+    /// query parameters.
+    fn document_with(severity: Value, headers: &[Value]) -> Value {
+        let mut parameters = vec![
+            severity,
+            serde_json::json!({"name": "page", "in": "query", "schema": {"type": "string"}}),
+        ];
+        parameters.extend(headers.iter().cloned());
+        serde_json::json!({
+            "info": {"version": "test"},
+            "servers": [{"url": "https://api.example.test"}],
+            "components": {"schemas": {}},
+            "paths": {"/v1/things": {"get": {
+                "operationId": "listThings",
+                "summary": "List things",
+                "x-hs-scope": {"scopes": ["things:read"]},
+                "parameters": parameters,
+                "responses": {"200": {"content": {"application/json": {"schema": {
+                    "type": "object",
+                    "properties": {"ok": {"type": "boolean"}},
+                    "required": ["ok"]
+                }}}}}
+            }}}
+        })
+    }
+
+    fn generate(extension: Option<Value>) -> Result<String> {
+        generate_from(&document(extension))
+    }
+
+    fn generate_from(spec: &Value) -> Result<String> {
+        Generator::new(spec)
+            .run()
+            .map(|out| out.split_whitespace().collect::<Vec<_>>().join(" "))
+    }
+
+    /// A `severity` parameter whose schema carries `extensions`, as the published document does.
+    fn severity_schema(extensions: Value) -> Value {
+        let mut schema = serde_json::json!({"type": "string"});
+        for (key, value) in extensions.as_object().expect("object") {
+            schema[key] = value.clone();
+        }
+        serde_json::json!({"name": "severity", "in": "query", "schema": schema})
+    }
+
+    #[test]
+    fn known_values_are_emitted_in_document_order() {
+        let out =
+            generate(Some(serde_json::json!(["critical", "high", "info"]))).expect("generates");
+        assert!(
+            out.contains(r#"known_values: &[("severity", &["critical", "high", "info"])]"#),
+            "{out}"
+        );
+    }
+
+    #[test]
+    fn a_parameter_without_the_extension_has_no_known_values() {
+        let out = generate(None).expect("generates");
+        assert!(out.contains("known_values: &[]"), "{out}");
+        assert!(!out.contains("known_values: &[("), "{out}");
+    }
+
+    #[test]
+    fn an_empty_vocabulary_is_the_same_as_none() {
+        let out = generate(Some(serde_json::json!([]))).expect("generates");
+        assert!(out.contains("known_values: &[]"), "{out}");
+    }
+
+    #[test]
+    fn a_malformed_extension_is_a_generator_error() {
+        for bad in [
+            serde_json::json!("critical"),
+            serde_json::json!({"critical": true}),
+            serde_json::json!(["critical", 3]),
+            serde_json::json!(null),
+        ] {
+            let err = generate(Some(bad.clone())).expect_err("malformed");
+            assert_eq!(
+                err, "listThings.severity: x-hs-known-values must be an array of strings",
+                "{bad}"
+            );
+        }
+    }
+
+    #[test]
+    fn known_values_are_read_from_the_parameter_schema() {
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-known-values": ["critical", "high"]})),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(
+            out.contains(r#"known_values: &[("severity", &["critical", "high"])]"#),
+            "{out}"
+        );
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-known-values": "critical"})),
+            &[],
+        );
+        assert_eq!(
+            generate_from(&spec).expect_err("malformed"),
+            "listThings.severity: x-hs-known-values must be an array of strings"
+        );
+    }
+
+    #[test]
+    fn deprecated_values_and_their_sunset_are_emitted_in_document_order() {
+        let spec = document_with(
+            severity_schema(serde_json::json!({
+                "x-hs-known-values": ["critical", "high"],
+                "x-hs-deprecated-values": ["critico", "alto"],
+                "x-hs-deprecated-values-sunset": "2027-01-14"
+            })),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(
+            out.contains(concat!(
+                r#"deprecated_values: &[crate::DeprecatedValues { param: "severity", "#,
+                r#"values: &["critico", "alto"], sunset: Some("2027-01-14") }]"#
+            )),
+            "{out}"
+        );
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-deprecated-values": ["alto"]})),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(out.contains("values: &[\"alto\"], sunset: None"), "{out}");
+    }
+
+    #[test]
+    fn a_parameter_without_deprecated_values_has_none() {
+        let out = generate(Some(serde_json::json!(["critical"]))).expect("generates");
+        assert!(out.contains("deprecated_values: &[]"), "{out}");
+        let spec = document_with(
+            severity_schema(serde_json::json!({"x-hs-deprecated-values": []})),
+            &[],
+        );
+        let out = generate_from(&spec).expect("generates");
+        assert!(out.contains("deprecated_values: &[]"), "{out}");
+    }
+
+    #[test]
+    fn malformed_deprecated_values_are_a_generator_error() {
+        for (extensions, expected) in [
+            (
+                serde_json::json!({"x-hs-deprecated-values": "alto"}),
+                "listThings.severity: x-hs-deprecated-values must be an array of strings",
+            ),
+            (
+                serde_json::json!({"x-hs-deprecated-values": ["alto", 1]}),
+                "listThings.severity: x-hs-deprecated-values must be an array of strings",
+            ),
+            (
+                serde_json::json!({
+                    "x-hs-deprecated-values": ["alto"],
+                    "x-hs-deprecated-values-sunset": "14/01/2027"
+                }),
+                "listThings.severity: x-hs-deprecated-values-sunset must be a YYYY-MM-DD date",
+            ),
+            (
+                serde_json::json!({
+                    "x-hs-deprecated-values": ["alto"],
+                    "x-hs-deprecated-values-sunset": 20_270_114
+                }),
+                "listThings.severity: x-hs-deprecated-values-sunset must be a YYYY-MM-DD date",
+            ),
+            (
+                serde_json::json!({"x-hs-deprecated-values-sunset": "2027-01-14"}),
+                "listThings.severity: x-hs-deprecated-values-sunset without \
+                 x-hs-deprecated-values",
+            ),
+            (
+                serde_json::json!({
+                    "x-hs-deprecated-values": [],
+                    "x-hs-deprecated-values-sunset": "2027-01-14"
+                }),
+                "listThings.severity: x-hs-deprecated-values-sunset without \
+                 x-hs-deprecated-values",
+            ),
+        ] {
+            let spec = document_with(severity_schema(extensions.clone()), &[]);
+            let err = generate_from(&spec).expect_err("malformed");
+            assert_eq!(err, expected, "{extensions}");
+        }
+    }
+
+    #[test]
+    fn the_tenant_header_marks_the_operation_tenant_scoped() {
+        let severity =
+            || serde_json::json!({"name": "severity", "in": "query", "schema": {"type": "string"}});
+        for name in ["X-HS-Tenant", "x-hs-tenant"] {
+            let header = serde_json::json!({
+                "name": name, "in": "header", "required": false,
+                "schema": {"type": "string", "format": "uuid"}
+            });
+            let out = generate_from(&document_with(severity(), &[header])).expect("generates");
+            assert!(out.contains("tenant_scoped: true"), "{out}");
+            // The header is not an argument of the generated function.
+            assert!(!out.to_lowercase().contains("x_hs_tenant"), "{out}");
+        }
+        let out = generate_from(&document_with(severity(), &[])).expect("generates");
+        assert!(out.contains("tenant_scoped: false"), "{out}");
+    }
+
+    #[test]
+    fn an_open_object_stays_a_map_even_when_it_lists_properties() {
+        let mut spec = document(None);
+        let response = "/paths/~1v1~1things/get/responses/200/content/application~1json/schema";
+        let properties = &mut spec.pointer_mut(response).expect("response schema")["properties"];
+        properties["details"] = serde_json::json!({
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {"code": {"type": "string"}}
+        });
+        let out = generate_from(&spec).expect("generates");
+        assert!(
+            out.contains("pub details: Option<serde_json::Map<String, serde_json::Value>>"),
+            "{out}"
+        );
+        assert!(!out.contains("pub struct Details"), "{out}");
+    }
+
+    #[test]
+    fn any_other_header_parameter_is_a_generator_error() {
+        let header = serde_json::json!({
+            "name": "X-Other", "in": "header", "schema": {"type": "string"}
+        });
+        let spec = document_with(
+            serde_json::json!({"name": "severity", "in": "query", "schema": {"type": "string"}}),
+            &[header],
+        );
+        assert_eq!(
+            generate_from(&spec).expect_err("unsupported"),
+            "listThings.X-Other: parameters in `header` are not supported"
+        );
+    }
 }