audit, advisories and doctors/setup work

docs/guides/image-inspection-guide.md

@@ -0,0 +1,54 @@
+# Image Inspection Guide
+
+## Overview
+
+`stella image inspect` resolves an OCI image reference, enumerates platform manifests, and lists layers. Use it to confirm what is deployed where and to feed downstream verification workflows.
+
+## Basic usage
+
+```bash
+stella image inspect nginx:latest
+```
+
+## JSON output for automation
+
+```bash
+stella image inspect nginx:latest --output json > image-inspect.json
+```
+
+## Platform filter
+
+```bash
+stella image inspect nginx:latest --platform linux/amd64
+```
+
+## Private registry (HTTP)
+
+For local registries that use HTTP, include the scheme in the reference:
+
+```bash
+stella image inspect http://localhost:5000/myapp:1.0.0
+```
+
+If you need registry auth, configure the `OciRegistry` section in your CLI config (see `docs/modules/scanner/image-inspection.md`).
+
+## CI usage example
+
+```bash
+stella image inspect ghcr.io/org/app:1.2.3 --output json \
+  | jq '.platforms[] | { os: .os, arch: .architecture, layers: (.layers | length) }'
+```
+
+## Troubleshooting
+
+### Authentication required
+- Symptom: `Authentication required` error.
+- Fix: configure `OciRegistry.Auth` in your CLI config or use a registry that allows anonymous pulls.
+
+### Rate limits
+- Symptom: HTTP 429 or warnings about rate limits.
+- Fix: retry later, use authenticated credentials, or mirror to a private registry.
+
+### Unsupported media types
+- Symptom: warnings about unknown manifest media types.
+- Fix: confirm the registry serves OCI or Docker v2 manifests, and ensure the image reference is correct.