feat(billing): implement tenant subscription entitlements system (milestones 0-6)

docs/usage/api.md

@@ -36,3 +36,64 @@ curl -sS -X POST \
   -H "authorization: Bearer <token>" \
   http://localhost:8080/admin/runner/drain?wait_ms=0
 ```
+
+## Document Storage via Control API (S3-backed)
+List documents for a tenant (Control API uses UUID tenant ids):
+```bash
+curl -sS \
+  -H "authorization: Bearer <token>" \
+  -H "x-tenant-id: <tenant-uuid>" \
+  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs"
+```
+
+Upload a document (stores at `docs/<tenant>/<type>/<id>/<filename>`):
+```bash
+curl -sS -X PUT \
+  -H "authorization: Bearer <token>" \
+  -H "x-tenant-id: <tenant-uuid>" \
+  -H "content-type: application/octet-stream" \
+  --data-binary @./bundle.tar.gz \
+  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/deployments/<doc-id>/bundle.tar.gz"
+```
+
+Download by object key (streamed proxy; key must belong to the tenant prefix):
+```bash
+curl -sS -o ./out.tar.gz \
+  -H "authorization: Bearer <token>" \
+  -H "x-tenant-id: <tenant-uuid>" \
+  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/object/<url-encoded-key>"
+```
+
+Delete by object key (requires `control:write`):
+```bash
+curl -sS -X DELETE \
+  -H "authorization: Bearer <token>" \
+  -H "x-tenant-id: <tenant-uuid>" \
+  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/object/<url-encoded-key>"
+```
+
+Presign upload (JSON body; returns `PUT` URL and `key`):
+```bash
+curl -sS -X POST \
+  -H "authorization: Bearer <token>" \
+  -H "content-type: application/json" \
+  -H "x-tenant-id: <tenant-uuid>" \
+  -d '{"doc_type":"deployments","doc_id":"<doc-id>","filename":"bundle.tar.gz","content_type":"application/gzip"}' \
+  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/presign/upload"
+```
+
+Presign download (JSON body with full `key` under that tenant):
+```bash
+curl -sS -X POST \
+  -H "authorization: Bearer <token>" \
+  -H "content-type: application/json" \
+  -H "x-tenant-id: <tenant-uuid>" \
+  -d '{"key":"docs/<tenant-uuid>/deployments/<doc-id>/bundle.tar.gz"}' \
+  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/presign/download"
+```
+
+Environment variables for the Control API (also accept `S3_*` names without the `CONTROL_` prefix; see `S3_PLAN.md`):
+- `CONTROL_S3_ENDPOINT` — S3 API base URL used by the server client
+- `CONTROL_S3_PUBLIC_ENDPOINT` — optional; host used in presigned URLs when browsers must reach a different host than the API (e.g. `localhost:9000` vs `minio:9000` in compose)
+- `CONTROL_S3_REGION`, `CONTROL_S3_BUCKET_DOCS`, `CONTROL_S3_PREFIX_DOCS`, `CONTROL_S3_FORCE_PATH_STYLE`, `CONTROL_S3_INSECURE`
+- Secrets may be mounted as files: `CONTROL_S3_ACCESS_KEY_ID_FILE`, `CONTROL_S3_SECRET_ACCESS_KEY_FILE`