docs: status pages

docs/reference/troubleshooting.md

@@ -160,6 +160,27 @@ needs `host`, `port`, `from` and `to`, and Telegram needs both `token` and
 | Instance degraded despite a valid-looking licence | It expired more than a few days ago. Pasting a new one still works, which is how you recover |
 | Cannot enrol another server                       | The server allowance is reached. Raise it in HQ or remove one                                                  |
 
+## A status page 404s or shows no data
+
+**404, and it should be published.** Check the **Published** toggle on the
+page's editor — an unpublished page answers *not found* for everyone,
+including you, with no session exemption. Also check the host: the public URL
+is `<your-instance>.vantage.<yourdomain>/status/<page-id>`, the same
+per-instance subdomain everything else in Vantage uses. A wrong or missing
+subdomain resolves to no instance at all, which is also a 404.
+
+**Loads, but shows an explanation instead of components.** This is not a
+fault — it is the page working as designed. It means either the licence has
+lapsed (a self-hosted instance past its grace period, or a cloud instance
+between billing events) or the current tier does not include the **Status
+pages** feature. Fix the licence or the plan and the same link starts serving
+data again with no republish needed.
+
+**One component reads `Unknown`.** The monitor behind it was deleted while
+still listed on the page. Nothing is checking it any more, so the page says so
+rather than showing a stale up or down. Remove the component from the page,
+or point it at a replacement monitor, in the page's editor.
+
 ## HQ portal problems
 
 The portal is a hosted service, so problems with it are ours to fix rather than

docs/vantage/status-pages.md

@@ -0,0 +1,107 @@
+---
+id: status-pages
+title: Status pages
+sidebar_label: Status pages
+---
+
+A status page is a public page reporting a chosen set of monitors as up-front
+components, with a 90-day history and an uptime percentage per component. It
+needs no session and no token to read — anyone with the link can open it,
+which is the point: it is what you hand a customer instead of an incident
+email.
+
+Requires the **Status pages** licence feature. If the licence lapses, or the
+tier does not include the feature, the page keeps serving — it renders an
+explanation rather than data or a broken page, so a customer who follows an
+old link never sees an error.
+
+## Creating a page
+
+From **Status pages**, choose a page id and a title. The id is 3–40 characters
+of lowercase letters, digits and `-`, starting and ending with a letter or
+digit. It becomes part of the public URL:
+
+```
+https://<your-instance>.vantage.<yourdomain>/status/<page-id>
+```
+
+**The page id cannot be changed after creation.** Once you have shared the
+link, changing the id would break it, so pick something you would still be
+happy with in a year — `platform`, `api`, a customer's own name for a
+dedicated page.
+
+## Draft versus published
+
+A new page starts unpublished. Unpublished pages answer *not found* to
+anyone who requests them, including you, from a browser without a session —
+so you can build out the components and copy before announcing it. Toggle
+**Published** when it is ready. Un-publishing later takes it back to *not
+found* rather than deleting anything.
+
+## Sections and components
+
+A page is organised into **sections** — arbitrary groupings such as "API" or
+"Region: EU" — each holding one or more **components**. A component is a
+monitor plus a **display name** you choose for this page.
+
+The display name is never the monitor's own name unless you type it in. An
+internal monitor name ("prod-db-primary-eu1") is rarely what you want a
+customer reading; give it whatever name makes sense to them, and change it
+for a different page without touching the monitor.
+
+If a monitor listed on a page is later deleted, its component still appears —
+reading `Unknown` rather than up or down, because nothing is checking it any
+more and claiming otherwise would be a false claim of health.
+
+## What a visitor sees
+
+- Component name, current state (up / down / under maintenance / unknown) and
+  a 90-day uptime percentage.
+- A 90-day history bar per component.
+- Any active incidents, upcoming maintenance, and a rolling history of both.
+- An optional banner across the top of the page (info / warning / critical),
+  for anything you want said regardless of component state.
+
+A visitor never sees a target URL, host or port, the check's expected status
+or keyword, latency, a certificate expiry date, failure text, or which
+notification channel is attached. That is a deliberate boundary, not an
+oversight: nothing that would tell a stranger how your infrastructure is
+reachable is on this page.
+
+## Incidents and maintenance
+
+Two kinds of entries appear on a page's timeline:
+
+- **Automatic** — a monitor going down opens an incident on any page that
+  lists it, with no action from you. These appear the moment the monitor's
+  state changes and close the moment it recovers.
+- **Authored** — an incident or maintenance window you create by hand, with
+  its own title, impact and a set of affected components you choose. You
+  post updates to it (Investigating → Identified → Monitoring → Resolved) as
+  the situation develops, and each update is timestamped and kept on the
+  page's history.
+
+An authored incident is attached to one or more pages explicitly when you
+create it — it does not follow a monitor onto every page that monitor happens
+to be listed on.
+
+### Scheduling maintenance
+
+A maintenance window has a scheduled start and end (the end must be after the
+start) and moves through Scheduled → In progress → Completed. While a window
+is in progress and its affected components are within the scheduled time,
+those components are drawn as "under maintenance" instead of up or down.
+
+**Maintenance changes how a day is drawn, never the uptime number itself.**
+The 90-day percentage is computed from what actually happened — a component
+that stayed up throughout a maintenance window still shows as up in its
+history, it is only the live status pill that reads "under maintenance" for
+the duration.
+
+## Delay before an update appears
+
+A visitor's read of a page is cached for up to 30 seconds, so posting an
+update or flipping Published does not necessarily change what a visitor sees
+instantly — though most authoring actions invalidate that cache immediately,
+so in practice it usually shows within a second or two. If a change genuinely
+does not appear, reloading after 30 seconds always will.

sidebars.ts

@@ -29,6 +29,7 @@ const sidebars: SidebarsConfig = {
                 "vantage/vulnerabilities",
                 "vantage/workloads",
                 "vantage/notification-channels",
+                "vantage/status-pages",
                 "vantage/secrets",
                 "vantage/browser-console",
                 "vantage/audit-log",