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. Launch controls comes next: every switch that decides the launch posture, grouped as Preview messaging, Access, Self-service availability and Progressive rollout. Each row says what the switch is set to and what that means for a visitor, who decides it (Set in the app, Pinned by deployment env, Baked into the web build or Code default), whether changing it Needs redeploy, and who last changed it. The panel changes nothing itself: use its link to the switch's own page (Invitations for invite-only signup, Companies → Platform setup for release flags and the platform mode), or change the variable on the deployment. If the web build's Private Preview or request-access flag disagrees with its API twin, a warning says so. 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, the entitlement test accounts (free, expired, free Record used, over the seat limit) and the three golden properties with the band each is pinned to. Provisioning may take several passes; the page carries on by itself until it is done.

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.
3. 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. Each browser test button then waits 30 seconds before it will send again — click it sooner and the page tells you how long is left instead of sending a second entry — and the page keeps a count of how many test errors you have sent this visit.

• 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. The Status incidents (published live) group counts the incidents posted to the public status page without a release, and how many are still open.
• Activation funnel — new-user activation by persona (was the old Usage page).
• Activation by persona (inside Platform metrics) — for each kind of customer (home buyer, home seller, real estate agent, mortgage, insurance broker), how many people who joined in the selected period went on to search, open a Record and take a next step: saving the property, requesting a quote or downloading the report. Each step shows the share of people who got that far and how many failed or gave up there. A row marked Widens: investigate means more people reached a later step than an earlier one, which usually means people arrived through a shared link or a step is not being recorded. Only customer accounts are counted, not staff or test accounts; activity a staff member records while acting as a customer can still appear, on its own CoverGuard admin row rather than the customer's. Could not be read means the numbers failed to load, not that they are zero; try again shortly.
• 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).
2. Review/edit it.
3. 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.

Posting a status-page incident during an outage

Customers check coverguard.io/status when something breaks. A super-admin can post an incident there while it is happening, and post each update until it is resolved, without waiting for a release: the notice appears within about five minutes. There is no screen for this yet — the on-call engineer posts it through the incident write path described in the incident handbook (docs/incidents/README.md), signed in as a super-admin. Every post is recorded in the audit history under your name, and the text goes straight to the public page, so write it in plain language with no internal names or customer details.

While a component on the status page is not operational, its availability tile reads Not measurable during an outage instead of a percentage: during an outage the failing requests may never be recorded, so a percentage would overstate availability.

Not every row is a live check, and each row that isn't says so underneath it:

• Database and Authentication are checked live. API reads operational whenever the status page can load at all.
• Risk & Search and Carrier Match follow the database, so a fault of their own leaves them green.
• The AI row and Billing & Subscriptions only show whether those services are set up, so an outage at the AI provider or at Stripe leaves them green.

When any of these is down and its row is still green, post an incident the way this section describes. It shows within about five minutes, with no release. The board will not show the problem on its own.

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