fix: codify #164 runtime credential and db contracts

docs/cloud-api-runtime.md

@@ -18,8 +18,8 @@ and verifies:
   connected.
 - The DB contract reports required env names, redacted Secret refs, env
   injection, connection attempt status, connection result, `liveConnected`,
-  `liveDbEvidence`, and redaction/safety fields without exposing DB URL or
-  secret values.
+  `liveDbEvidence`, DNS/TCP/auth/schema readiness layers, and redaction/safety
+  fields without exposing DB URL or secret values.
 - `gateway.session.register`, `box.resource.register`,
   `box.capability.report`, `hardware.invoke.shell`, `audit.event.query`, and
   `evidence.record.query` round-trip through the same runtime store.
@@ -45,6 +45,8 @@ The source-controlled DEV DNS contract for that endpoint is
 `cloud-api-db.hwlab-dev.svc.cluster.local:5432`. The actual connection string
 still comes from `hwlab-cloud-api-dev-db/database-url`; source records only the
 non-secret host/service/namespace/port contract.
+`.invalid` hosts, including `hwlab-dev-db.invalid`, are forbidden as DEV
+runtime targets and may be used only as negative fixtures.
 
 - `db.configReady`: required env names are present.
 - `db.connectionAttempted`: the runtime tried the live connection path.
@@ -55,6 +57,8 @@ non-secret host/service/namespace/port contract.
   presence, fixtures, and disabled probes must keep this false.
 - `db.redaction` and `db.safety`: confirm values/endpoints are redacted and
   secret material was not read by the health path.
+- `db.readinessLayers`: records DNS, TCP, auth, and schema status separately so
+  DNS/TCP repair cannot be confused with authenticated schema readiness.
 - `db.ready`: currently aliases `db.liveConnected`.
 
 Env presence alone is not treated as green. If the runtime has env injection
@@ -63,3 +67,13 @@ but `db.connectionAttempted` is false, `db.liveConnected` is false, or
 reported blocker.
 
 Fixture: `fixtures/cloud-api-runtime/minimal-runtime.json`.
+
+## Code Agent Provider Boundary
+
+`hwlab-cloud-api` supports OpenAI Responses for the Code Agent chat endpoint.
+DEV source contracts require `OPENAI_API_KEY` from Secret
+`hwlab-code-agent-provider/openai-api-key` and
+`HWLAB_CODE_AGENT_OPENAI_BASE_URL` through the DEV egress/proxy URL. Runtime
+health and `/v1` may report provider status, missing env names, Secret ref
+names, model, and redacted egress status, but must never print the API key or a
+Bearer token.