Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0

docs/operations/PROJECT_ONBOARDING.md

@@ -0,0 +1,61 @@
+# Project onboarding and service credentials
+
+Open **Projects** with a personal operator or administrator key.
+
+1. Create a project with a stable slug, name, description, owner, environment and optional labels.
+2. Add an exact versioned capability requirement. Select reindex support for incompatible embedding
+   spaces, or schema migration support when required. The requirement uses the stable gateway route.
+3. As administrator, issue a service identity for one explicit binding. Choose a unique client name,
+   purpose and expiry. The binding fixes its capability and workload priority.
+4. Save the returned key in the consumer's secret store or a protected token file. It appears once
+   and the Console hides it after 60 seconds. The database retains a digest, never plaintext.
+5. Expand the integration examples. Set the gateway origin, token-file location and capability in
+   the consumer environment. The examples never contain the issued key.
+6. Paste the service key into the memory-only test field and run **Check connectivity**. This verifies
+   its exact scope without starting inference. The key must belong to the selected identity.
+7. Supply non-sensitive capability-specific JSON and run **Run capability check**. This executes one
+   real gateway request and may load the governed deployment. Image/audio templates require real
+   base64 input; placeholder strings cannot produce a successful test.
+
+The workspace shows blockers, deployment health, current key expiry, last use and the successful
+gateway request ID. Readiness requires current key/current deployment evidence from the last 24
+hours. Rotation, a deployment change, expiry, revocation or stale evidence invalidates the relevant
+checks. Production eligibility is deliberately not inferred; use the project-fit and lifecycle
+approval workflows. A fresh installation with no eligible stable deployment stays visibly blocked.
+
+## Rotation and revocation
+
+Choose immediate replacement, 15 minutes, one hour or 24 hours of overlap. Both the expected
+credential ID and the replacement expiry are sent to the API. Refresh after a conflict. The old
+key expires no later than its original expiry or the overlap deadline; another rotation ends any
+older overlap. Replacement keys are also revealed once.
+
+**Revoke all keys** shows the client, capability and last use. Type the exact client name and
+acknowledge the interruption. Current and overlapping keys immediately stop authorizing new
+requests. Already admitted work may finish. A revoked identity cannot be revived through rotation;
+issue a new service identity if access is needed again. Historical metadata remains auditable.
+
+Legacy single-key rotate/delete routes remain available for compatible automation and use immediate
+revocation; they also use the same transactional claim. New integrations should use the guarded
+plural `/credentials/rotate` and `/credentials/revoke` routes.
+
+## API surface
+
+| Route | Authority | Result |
+| --- | --- | --- |
+| `GET /api/v1/project-workspace` and `/{key}` | Viewer | Persisted requirements, safe client metadata, observed readiness |
+| `POST /api/v1/project-workspace` | Operator | Persist project identity/owner/environment/labels with audit |
+| `POST /api/v1/project-workspace/{key}/requirements` | Operator | Bind an exact compatible requirement with audit |
+| `POST /api/v1/admin/service-clients` | Admin | Issue key once; accepts explicit `project_binding_id` |
+| `GET /api/v1/admin/service-clients/{id}/credentials` | Admin | Most recent 100 key metadata records, never digests/plaintext |
+| `POST /api/v1/admin/service-clients/{id}/credentials/rotate` | Admin | Expected credential ID, overlap seconds and new UTC-aware expiry |
+| `POST /api/v1/admin/service-clients/{id}/credentials/revoke` | Admin | Expected credential ID and exact client-name confirmation |
+| `GET /api/v1/capabilities/{capability}/check` | Scoped service key | Connectivity, client identity and correlation ID; no inference |
+
+Connectivity checks exist for the five implemented embedding, reranking, OCR, vision and
+transcription capability routes. Human keys cannot authenticate there, and service keys cannot
+open the Console. Protected control-plane responses use `Cache-Control: no-store`.
+
+Migration `20260908_0026` adds onboarding metadata and credential supersession. Restore the verified
+pre-migration backup if rollback is necessary after new history exists; do not drop that history.
+See [verification](../quality/RC02_PROJECT_VERIFICATION.md) and [clients](../../clients/README.md).