fix: codify #164 runtime credential and db contracts

docs/reference/dev-runtime-boundary.md

@@ -84,6 +84,49 @@ this agreement offline. A live pass still requires `/health/live` to report
 `db.ready=true`, `db.connected=true`, and `liveDbEvidence=true` with secret
 values redacted.
 
+The DB readiness contract is layered:
+
+| Layer | Required evidence |
+| --- | --- |
+| DNS | The configured target resolves from the `hwlab-cloud-api` runtime path and is not a `.invalid` placeholder. |
+| TCP | A redacted TCP probe reaches the configured Postgres port. |
+| Auth | Authenticated database access succeeds without printing the connection string. |
+| Schema | Required HWLAB schema/migration checks pass without using fixture output as live evidence. |
+
+`*.invalid` and `hwlab-dev-db.invalid` are forbidden DEV runtime targets. They
+may appear only as negative test fixtures; source and runtime health must not
+treat them as desired DEV DB endpoints.
+
+## Code Agent Provider Contract
+
+`hwlab-cloud-api` runs the DEV Code Agent provider through OpenAI Responses.
+Source-controlled manifests must declare only env names, Secret references, and
+non-secret egress settings:
+
+| Field | Value |
+| --- | --- |
+| Provider env | `HWLAB_CODE_AGENT_PROVIDER=openai` |
+| Model env | `HWLAB_CODE_AGENT_MODEL=gpt-5.5` |
+| Provider Secret | `OPENAI_API_KEY` from `hwlab-code-agent-provider/openai-api-key` |
+| DEV egress/base URL | `HWLAB_CODE_AGENT_OPENAI_BASE_URL=http://172.26.26.227:17680/v1/responses` |
+
+DEV pods must not call `https://api.openai.com/v1/responses` directly. The base
+URL must use the approved DEV egress/proxy path so provider reachability is a
+repeatable deployment contract instead of a one-off runtime patch.
+
+Reports, smokes, and health payloads may show Secret name/key presence,
+`missingEnv`, provider status, model, trace IDs, and redacted egress status.
+They must never print the OpenAI API key, bearer token, database URL password,
+kubeconfig material, or other secret values.
+
+## Hotfix To Source Rule
+
+DEV runtime hotfixes are temporary recovery actions. After a hotfix proves the
+minimal live path, the durable follow-up is source automation: update manifests,
+contracts, docs, and tests so future rollouts reproduce the same env and safety
+boundaries. The runner must not re-execute the live hotfix, restart services,
+read Secrets, mutate PROD, or claim live evidence from source-only changes.
+
 ## Runtime Substitution Ban
 
 UniDesk services, provider-gateway, backend-core, microservice proxies, local
@@ -98,5 +141,7 @@ M4, or M5 live evidence.
   read-only k3s visibility command.
 - [docs/dev-acceptance-matrix.md](../dev-acceptance-matrix.md): DEV endpoint
   and health acceptance.
+- [pikasTech/HWLAB#164](https://github.com/pikasTech/HWLAB/issues/164):
+  Code Agent provider and DB live hotfix follow-up contract.
 - [pikasTech/HWLAB#61](https://github.com/pikasTech/HWLAB/issues/61): manual
   rollout review and automation requirements.