sat/openapi.yaml: no 429/rate-limit documentation anywhere (inconsistent with asm/openapi.yaml)

[dmchaledev]

Problem

asm/openapi.yaml documents rate limiting thoroughly: a ## Rate Limiting section in the top-level description (600 req/min per API key), X-RateLimit-Limit/X-RateLimit-Remaining response headers, and a shared RateLimited response (with Retry-After header + an Error example) that's $ref'd from every operation's '429' response (12 occurrences).

sat/openapi.yaml has zero occurrences of 429, RateLimit, or any rate-limiting language — not in the spec's info.description, not in components/responses, not on any of the 51 operations. This was true before and remains true after #37 (fix(sat): add missing 4xx/5xx error responses across the SAT API), which closed out 400/401/403/404/500 coverage but explicitly scoped to those five codes and never mentioned 429 — see the closed issue #29 that #37 implemented, whose table only lists 400/401/403/404/500.

Given the SAT spec already documents role-based permission gating (403) and a full error envelope (components/schemas/Response), it's very likely the real SAT API also enforces per-key or per-IP rate limits (this is standard for a multi-tenant phishing-simulation platform with bulk campaign/email endpoints) — it's just undocumented. If it doesn't rate-limit at all, that's arguably a product gap worth knowing about too.

Why this matters

• Anyone generating an SDK or MCP tool definitions from sat/openapi.yaml will have no retry/backoff logic to generate, since the spec asserts (by omission) that rate limiting doesn't exist.
• Integrators hitting real 429s from the live API will get a response shape Redoc/generated clients don't know about.
• It's an inconsistency between the two specs in this repo that a reader would reasonably assume is intentional (SAT has no limits) when it's more likely just an oversight.

Proposed fix

Mirror the pattern already established in asm/openapi.yaml:

1. Add a ## Rate Limiting subsection to sat/openapi.yaml's info.description, stating the actual limit (needs confirming with whoever owns the SAT service — this repo can't guess the real number, see hailbytes-sat for the source of truth).
2. Add X-RateLimit-Limit / X-RateLimit-Remaining (or whatever headers the real API actually returns) to components/headers.
3. Add a RateLimited entry to components/responses (reusing the existing Response schema at sat/openapi.yaml:78, the same way Unauthorized/NotFound/InternalError already do) including a Retry-After header.
4. Add '429': { $ref: '#/components/responses/RateLimited' } to the same set of operations that already got 401/403/404/500 treatment in fix(sat): add missing 4xx/5xx error responses across the SAT API #37 — i.e. effectively all 51 operations.

Scope

sat/openapi.yaml only. Needs confirmation of the actual rate-limit policy (limit value, header names, whether it's per-key/per-IP/per-endpoint) from someone with visibility into the SAT service before the exact numbers/headers are filled in — the structural change (schema + wiring) can proceed in parallel using placeholder/TBD values if preferred.