Fix staff-only snags — `/admin` and Observability access, act-as sessions, role grants, thin activity/usage reports, and staff→user outreach.
*For CoverGuard staff (COVERGUARD_ADMIN). How-to guide: Platform admin & observability.*
Access
"Observability / `/admin` pages 403 for me." Auto-elevation to super-admin requires a validated @coverguard.io email — your email_confirmed_at must be set. Verify your email, then sign out and back in so the resolved role picks up. Look-alike domains (e.g. evil-coverguard.io, sub.coverguard.io) do not match — only the exact staff domain.
"A customer can see an internal tab." They shouldn't — the Admin tab (which now contains Observability) is COVERGUARD_ADMIN-only and role-gated (not a demo flag). If a customer reports seeing it, verify their actual role in /admin/users; the company ADMIN persona is a customer role and does not get /admin.
"Where's the Observability tab?" Observability is no longer its own tab — it's merged into Admin → Overview (/admin). Open the Admin tab (it keys off your real role only, so it always shows for staff regardless of any Feature-Flags persona preview); the Overview page leads with the system-overview stats and the full Observability dashboard follows directly below on the same page. Old /observability and /admin/observability links redirect to /admin automatically.
Act-as (impersonation)
"Act-as won't start." You can't act-as a peer super-admin (blocked by design), and the target must be valid. Check the audit log for the impersonate_start attempt.
"I'm stuck in an act-as session." Use the Exit button in the persistent impersonation banner (a full navigation refetches as your real identity). Start/stop are audited.
"Act-as used the wrong AI key." It always uses the managed key — never the target's BYOK key or spend. That's intended.
Roles
"I can't grant someone ADMIN / COVERGUARD_ADMIN in the app." The role-change API refuses to grant or demote admin personas. Admin elevation is by staff domain (validated email) or direct DB action only.
"A self-serve persona breaks signup." Every UserRole the register page can produce must exist as a DB enum value — a missing value makes the signup trigger's role cast fail and roll back the whole signup (it fails before the BUYER fallback). If a new persona 500s signups, confirm the enum migration merged.
Data & reporting
"The AI usage / cost report is empty or thin." ai-kind telemetry accrues forward from when its check constraint was widened (an earlier migration rejected ai rows). Historic gaps are expected; recent data should populate.
"Activity history returns nothing." GET /api/admin/activity requires at least one filter (user / organization / entity / event type / time window) — an unfiltered call is refused to avoid a full-log scan. Add a filter. History was backfilled from domain tables, so it reaches back over past data.
"Observability shows no events / flat trends." Event ingest and rollups accrue forward from when the observability pipeline was enabled; early windows can be sparse. Check component Health for ingest/DB status.
Staff → user outreach
"Draft returns `AI_UNAVAILABLE`." The drafter runs on the managed key and is guardrail-screened; if the managed key is down you get 503 AI_UNAVAILABLE — compose the message manually and send.
"Send is blocked." Either the recipient opted out (RECIPIENT_OPTED_OUT — respect it), or you hit the per-staffer send rate limit. Outreach never auto-sends — a human always reviews first.