Skip to main content

Incident Notices Runbook

Use this runbook for the starter kit's platform-wide public status notices.

Scope​

  • Notices are global across public portal and platform surfaces.
  • Maintenance mode always takes precedence over notices.
  • Notices are informational banners, not access controls.

Operator SOP​

  • Limit posting rights to active platform_admin operators.
  • Use degraded_performance for slowdowns or delays with partial functionality.
  • Use partial_outage when a public-facing workflow is failing for some users.
  • Use security_notice for customer-visible security advisories that do not require a full maintenance lock.
  • Use billing_notice only for customer-visible billing interruptions or invoicing issues.
  • Archive a notice once the customer-facing impact is resolved.
  • Keep archived notices available in admin history unless there is a separate retention requirement.

Publish Checklist​

  1. Open Platform Settings > Control Plane.
  2. Confirm maintenance mode is off if you expect the notice to be public.
  3. Create or update the notice with a clear title, customer-facing message, and valid start/end window.
  4. Confirm the notice appears on: /<locale>/portal /<locale>/platform/login
  5. If maintenance mode is enabled, confirm the banner is suppressed on those same public pages.
  6. Archive the notice after resolution and confirm the banner disappears.

Deployment Checklist​

  1. Run pnpm --filter @starter/backend codegen.
  2. Deploy the Convex schema and functions.
  3. Verify the control-plane query and mutations succeed against the target deployment.
  4. Run the focused tests: pnpm --filter @starter/backend test -- tests/platform/system-settings.test.ts pnpm --filter @starter/app exec vitest run tests/public/incident-banner.test.tsx tests/public/status-layouts.test.tsx tests/scaffolding/starterkit-policy-scaffolding.test.ts

Copy Guidance​

  • Keep titles short and scannable.
  • Keep the message specific about user impact.
  • Avoid internal-only wording such as ticket IDs, vendor names, or mitigation details that do not help customers.