feat: add asset manifest knowledge ingest

README.md

@@ -53,10 +53,79 @@ curl http://localhost:8000/api/v1/health | jq .
 
 Open the interactive Swagger docs at <http://localhost:8000/docs>.
 
-## Ingest documents
+## Ingest TeamHUB assets
+
+TeamHUB modules should call `POST /api/v1/knowledge-ingest` with an
+`AssetManifest`. The original file stays in the owner module's MinIO/S3 bucket;
+LegacyHUB reads it by `bucket` + `object_key`, verifies `size_bytes` and
+`sha256`, records an idempotent ingest job by
+`asset_id + sha256 + manifest_version`, then builds OCR/search projections.
+
+```bash
+curl -X POST http://localhost:8000/api/v1/knowledge-ingest \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: ${LEGACYHUB_API_KEY}" \
+  -H "Idempotency-Key: evt_01J..." \
+  -d '{
+        "manifest": {
+          "manifest_version": "1.0",
+          "asset": {
+            "asset_id": "asset_01J...",
+            "owner_module": "mailhub",
+            "owner_record_type": "document",
+            "owner_record_id": "doc_01J...",
+            "asset_kind": "document",
+            "title": "incoming-letter.pdf",
+            "original_filename": "incoming-letter.pdf",
+            "content_type": "application/pdf",
+            "size_bytes": 184220,
+            "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "created_at": "2026-06-14T12:00:00Z",
+            "created_by": "staff:123"
+          },
+          "storage": {
+            "provider": "s3",
+            "bucket": "teamhub-mailhub-originals",
+            "object_key": "mailhub/2026/06/14/asset_01J/original/incoming-letter.pdf",
+            "version_id": null
+          },
+          "security": {
+            "gate_status": "approved",
+            "classification": "internal",
+            "av_status": "clean",
+            "content_scan_status": "clean",
+            "pii_status": "reviewed",
+            "approved_at": "2026-06-14T12:03:00Z",
+            "approved_by": "staff:123",
+            "quarantine_reason": null
+          },
+          "retention": {
+            "policy_id": "mailhub-default",
+            "retain_until": null,
+            "legal_hold": false,
+            "legal_hold_reason": null
+          },
+          "derivatives": [],
+          "links": []
+        },
+        "ingest_options": {
+          "generate_derivatives": true,
+          "index_full_text": true,
+          "index_vectors": true,
+          "emit_events": true
+        }
+      }'
+```
+
+Manifests with `security.gate_status != "approved"` are rejected without reading
+object storage. Container-local paths such as `/data/input/...`, `C:\...`, or
+`file://...` are invalid in the manifest contract.
+
+## Ingest local folders (deprecated)
 
 Mount a folder into the container at `/data/input` (the compose file already
-mounts `./data/input` for you), drop PDFs into it, and call:
+mounts `./data/input` for you), drop PDFs into it, and call the compatibility
+endpoint:
 
 ```bash
 curl -X POST http://localhost:8000/api/v1/ingest/folder \