re-vendor(scopes): api:docs cross-cutting docs scope (lockstep w/ nechapi 0ab148b)

Mirrors the merged platform canonical: required_for() maps docs|openapi.json|redoc
→ {realm}:docs. Byte-identical to nechapi/_platform/scopes.py (drift guard green).
Part of #48; deploy = nechapi-platform redeploy + nginx reload.

armada/api/scopes.py

@@ -43,7 +43,13 @@ REALMS = ("api", "admin")  # extensible: add "mail", "data", … as they appear
 def required_for(domain: str, route: str, realm: str = "api") -> str:
     """The scope a request needs, from its (domain, route). `route` is the
     path under the API with the version already stripped (e.g. "/analyze/emotion"
-    or "/"). Returns e.g. "api:audio:analyze:emotion"; "api:audio" for the root."""
+    or "/"). Returns e.g. "api:audio:analyze:emotion"; "api:audio" for the root.
+
+    Docs/spec routes are CROSS-CUTTING: gated by one realm-level `api:docs` scope
+    across every API (not per-domain), so a docs-reader token is decoupled from
+    API-call scopes — and `api:*` still covers it via the subtree wildcard."""
+    if route.strip("/") in ("docs", "openapi.json", "redoc"):
+        return f"{realm}:docs"
     segs = [s for s in route.strip("/").split("/") if s]
     parts = [realm]
     if domain: