diff --git a/services/secrets-broker/secrets-broker.contract.md b/services/secrets-broker/secrets-broker.contract.md
index 84188de..06235dc 100644
--- a/services/secrets-broker/secrets-broker.contract.md
+++ b/services/secrets-broker/secrets-broker.contract.md
@@ -153,6 +153,14 @@ infra store; the org path remains the escape hatch if per-user ACLs are ever nee
   future).
 - **Bitwarden Secrets Manager** — Vaultwarden does not implement it; not an option.
 
+## Known limitations (deferred)
+- **`secret put` namespace warning is non-blocking + stderr** — an interactive caller
+  sees the new-top-level-namespace heads-up, but a *scripted* caller that suppresses
+  stderr can still store an item under a typo'd/missing prefix silently (jackdaw-dev,
+  2026-08-12). Deliberately not blocking (some names are legitimately domain-scoped,
+  e.g. `gitea/…`, `certs/…`, so auto-prefixing would misfire). Revisit with an opt-in
+  `--strict` flag (nonzero exit on a new namespace) only if scripted callers appear.
+
 ## Failure modes / rollback
 
 - Broker/vault down → lookups fail, but host `.env` are untouched and authoritative