diff --git a/Codex/API/DECISIONS.md b/Codex/API/DECISIONS.md
index 4c369dd..e83b562 100644
--- a/Codex/API/DECISIONS.md
+++ b/Codex/API/DECISIONS.md
@@ -5,6 +5,8 @@
 - Agent does not push heartbeat/state into API.
 - Semantic readiness uses `/ready`, not plain HTTP 200.
 - Portal should consume API-normalized state, not call agents directly for normal state/actions.
+- `/api/instances` and `/api/containers` are distinct contracts: instances is the active list/create surface, while containers is the cleanup/delete/orphan-remediation surface.
+- there is no API-native `/api/agent/:serverId/:action` route in `zpack-api`; any route with that shape is Portal-owned compatibility behavior rather than an API feature.
 - streaming upload proxy behavior should remain separate from generic non-streaming `agentClient.js` transport.
 - websocket console proxy behavior should remain separate from generic non-streaming `agentClient.js` transport.
 - API is now tracked on a Node 24 baseline with repo-local version pinning.
@@ -14,6 +16,8 @@
 - JWT verification hardening is allowed to be contract-sensitive; access, refresh, and IDE proxy tokens may use distinct audience expectations.
 - hosted IDE proxy cookies should default to hardened behavior appropriate for public HTTPS deployments.
 - proxy logging should avoid exposing cookies or detailed forwarded-header values in routine logs.
+- legacy worker-based provisioning is no longer a live API path and should stay archived unless intentionally revived.
+- legacy port allocation / slot reservation is no longer part of the active provisioning model and should stay retired unless intentionally revived end to end.
 
 ## Tracking rule
 - when API work completes, remove it from `OPEN_ITEMS.md`