docs consolidation and others

docs/modules/risk-engine/samples/api/README.md

@@ -0,0 +1,3 @@
+Use the root `INGEST_CHECKLIST.md`.
+Place request/response examples here; normalize with `jq -S .`, update `SHA256SUMS`, verify with `sha256sum -c`.
+Include required headers; redact secrets; UTC timestamps only.

docs/modules/risk-engine/samples/api/SHA256SUMS

@@ -0,0 +1,3 @@
+fe460af2699ce335199f6e26597bab4530c6f3f476d4b1f93526175597565d10  README.md
+00f8dc4e466eb95c06545e6336d7b0866b53ac430335b7fd1b7889da13529b93  error-catalog.json
+96926cd81dfb6ff02d62d1fde5d7b2b7b5b3950e50eb651e51b8ae3042ac9506  risk-api-samples.json

docs/modules/risk-engine/samples/api/error-catalog.json

@@ -0,0 +1,13 @@
+{
+  "errors": [
+    {"code": "risk.job.not_found", "message": "Risk job not found", "http_status": 404, "remediation": "Verify job_id"},
+    {"code": "risk.profile.invalid_signature", "message": "Profile DSSE signature failed", "http_status": 400, "remediation": "Re-sign profile and retry"},
+    {"code": "risk.job.rate_limited", "message": "Rate limit exceeded", "http_status": 429, "remediation": "Retry after backoff", "retry_after": 5},
+    {"code": "risk.tenant.scope_denied", "message": "Tenant scope not authorized", "http_status": 403, "remediation": "Provide required scope header"}
+  ],
+  "headers": {
+    "etag": "\"risk-api-sample-etag\"",
+    "x-ratelimit-remaining": 99,
+    "retry-after": 5
+  }
+}

docs/modules/risk-engine/samples/api/risk-api-samples.json

@@ -0,0 +1,61 @@
+{
+  "submit_job_request": {
+    "method": "POST",
+    "path": "/api/v1/risk/jobs",
+    "headers": {
+      "Content-Type": "application/json",
+      "X-Stella-Tenant": "tenant-default"
+    },
+    "body": {
+      "tenant_id": "tenant-default",
+      "context_id": "ctx-001",
+      "profile_id": "default-profile",
+      "findings": [
+        {
+          "finding_id": "finding-123",
+          "component_purl": "pkg:npm/lodash@4.17.20",
+          "advisory_id": "CVE-2024-1234",
+          "trigger": "created"
+        }
+      ],
+      "priority": "normal",
+      "requested_at": "2025-12-05T00:00:00Z"
+    },
+    "response": {
+      "status": 202,
+      "body": {"job_id": "job-001", "status": "queued"}
+    }
+  },
+  "get_job_status": {
+    "method": "GET",
+    "path": "/api/v1/risk/jobs/job-001",
+    "response": {
+      "status": 200,
+      "body": {
+        "job_id": "job-001",
+        "status": "completed",
+        "results": [
+          {
+            "finding_id": "finding-123",
+            "profile_id": "default-profile",
+            "profile_version": "1.0.0",
+            "raw_score": 0.75,
+            "normalized_score": 0.85,
+            "severity": "high",
+            "signal_values": {"cvss": 7.5, "kev": true, "reachability": 0.9},
+            "signal_contributions": {"cvss": 0.4, "kev": 0.3, "reachability": 0.3},
+            "scored_at": "2025-12-05T00:00:02Z"
+          }
+        ]
+      }
+    }
+  },
+  "get_explain": {
+    "method": "GET",
+    "path": "/api/v1/risk/explain/job-001",
+    "response": {
+      "status": 200,
+      "body_ref": "../explain/explain-trace.json"
+    }
+  }
+}