diff --git a/frontend/packages/shared/src/api-error.ts b/frontend/packages/shared/src/api-error.ts
index 0998b118..ff69de49 100644
--- a/frontend/packages/shared/src/api-error.ts
+++ b/frontend/packages/shared/src/api-error.ts
@@ -9,12 +9,14 @@
 //
 // RFC 9457 is this hive's committed error-body contract for first-party
 // APIs (mara: "any api of our own responding with error that is not rfc
-// shaped is a bug to be filed against backend") — so the non-JSON
-// fallback below is a *compatibility* path, not a standing requirement.
-// As of this writing it exists for exactly one known gap: swarm-
-// controller's status route, being converted in a separate in-flight fix.
-// Once every first-party route emits problem+json, the raw-text path only
-// ever fires against a genuine bug (worth filing, not silently absorbing).
+// shaped is a bug to be filed against backend") — every first-party route
+// emits it as of this writing, so the non-JSON fallback below is NOT
+// compatibility with an in-flight backend transition (that transition is
+// finished). It's for bodies we did not author: a caller can be pointed
+// at something that isn't ours, and an nginx-synthesised 502/504 never
+// reaches our handlers at all, so it's plain HTML, not problem+json. A
+// first-party route landing here anyway is a bug to file, not something
+// this reader should quietly paper over.
 
 export interface ProblemDetails {
   type?: string;