How-to: Platform admin & observability (internal staff)

Run the platform end to end: manage users, act as any account, watch live health and usage, and reach out to customers who need help — all from the internal staff surfaces.

Who this is for: CoverGuard staff only (internal super-admins). Customers never see these pages. See also the CoverGuard Admin persona guide.

Getting in

Sign in with your validated `@coverguard.io` email — you're auto-elevated to super-admin (email verification required). One internal-staff tab then appears in the top nav, to the right of Sys Admin: Admin (the platform `/admin` pages). It's role-gated — customers never see it. Observability now lives inside the Admin console (Admin → Observability) rather than as its own top-level tab. The Admin tab keys off your real role only, so it always shows for staff (see troubleshooting if it's missing).

Platform admin (/admin)

• Overview (/admin) — system-wide stats and the full live Observability dashboard,

merged onto one page (see below). Launch readiness sits at the very top: one row per piece of configuration this deployment needs, each marked OK, Blocking or Advisory in words as well as colour. Read it first — if something here is Blocking, the numbers further down the page are describing a deployment that cannot serve properly anyway. Advisory means real but not urgent: worth fixing, not worth stopping for. No row ever shows a configured value, only whether one is present. The read-only account/subscription/Record KPIs + role breakdown + jump-to-a-tool grid follow; the platform-health + business dashboard comes below that.

• Users (/admin/users) — list/search users; change persona (not to/from admin roles);

Act as a user; provision a user's AI key.

• API-key approvals — approve/suspend partner keys (the KEY_NOT_APPROVED gate).
• Agent rules (/admin/rules) — override out-of-the-box agents' objectives ("rules")

for future installs.

• Demo accounts (/admin/demo-accounts) — list / (re)provision seeded demo accounts.

Act-as (impersonation)

1. From `/admin/users`, click Act as on a user.
2. You now see and operate their exact account (an overlay — you keep your own login). A

banner shows who you're viewing.

1. Click Exit in the banner to stop.

Rules: you can't act-as a peer super-admin; act-as always uses the managed AI key (never the target's BYOK); start/stop are audited.

Observability (PlatformPulse, Admin → Overview, /admin)

The single "is the platform healthy right now?" view. It's merged into the Admin → Overview page — scroll past the system-overview stats and it's right there (it used to be its own Observability tab; the old /admin/observability link redirects to /admin). It has two views (toggle at the top):

• AI dashboard (default) — a Power BI-style, AI-forward view over real production data:

time/area/source slicers, an auto-updating AI headline, an Ask bar ("why did the error rate spike?"), and a per-card Explain / Draft AI drawer (grounded managed-key answers, with a deterministic fallback when no AI key is set).

• Classic (?view=classic) — the original single-column live dashboard over the same

telemetry pipeline:

• Overview — event counts, error rate, active users, by-area/by-source.
• Trends — time-series from the 5-minute rollups.
• Health — composed component health (DB, ingest, error rate, AI key, error

tracking). Amber here means "this needs attention soon", not "the platform is down" — for example, Error tracking (Sentry) turns amber in production when no error-reporting destination is set, or when one is set but isn't accepting reports. Nothing customers touch is broken, but crashes are going unrecorded, so anything that does break will be much harder to explain afterwards.

This row covers one of three places crashes happen, not all of them. It reports the API service only. Crashes in the website's own server code, and crashes in someone's browser, are tracked separately and a green row here says nothing about either — check Server error tracking and Browser error tracking in the Launch readiness panel at the top of the page for those two. If the browser one is Advisory and says the setting was added after the last build, the fix is to redeploy: the setting is already saved, it just has not reached the version of the app people are loading yet.

To confirm error tracking really works rather than just being switched on, open Run the Sentry check from the bottom of the Launch readiness panel. It asks each part of the app whether its error reporting actually started, and lets you send a deliberate test error to confirm it shows up in Sentry. Be aware the test buttons create real entries in Sentry and count against your plan's quota; they are tagged so you can filter them out later.

• Focus feed — users to flag now, from real signals (dunning, error bursts, carrier

exits).

• Platform metrics — business + operational snapshot (users, subscriptions, agents,

CRM pipeline, AI spend, queue/webhook health), downloadable as a CSV report.

• Activation funnel — new-user activation by persona (was the old Usage page).
• Events — recent raw events; per-user timelines.
• SLO — error rate, availability, p95.

Staff → user outreach (from the Focus feed)

1. On a Focus row, AI-draft a message (managed key, guardrail-screened; it **never

auto-sends**).

1. Review/edit it.
2. Send — it's persisted, the user is notified (and optionally emailed).

Recipients can opt out (the send path returns RECIPIENT_OPTED_OUT for them). Draft and send are rate-limited per staffer. Every Focus action is logged.

Activity history (audit)

One append-only history of meaningful user and property actions, queryable by user, company/team, property, event type, and time window. It answers "what did this user / company / property actually do?" — the audit spine behind support and compliance questions.

Troubleshooting

See Admin & staff tools troubleshooting.

• Admin/Observability 403 → staff email not yet verified, or role not elevated.
• Act-as blocked → target is a peer super-admin, or invalid.
• Empty AI usage / observability data → data accrues forward from when telemetry /

event ingest was enabled.

• Outreach send blocked → recipient opted out, or you hit the per-staffer rate limit.

Do this next

Start on the Observability Focus feed — it surfaces the users who need attention right now — then act-as one to see exactly what they see.

• CoverGuard Admin persona guide — your staff playbook
• CoverGuard Advisor & BYOK — provisioning a user's AI key
• Admin & staff tools troubleshooting