docs(patching): no dispatch in the last 15 minutes, running patches finish, 45 minute reboot wait

docs/hq/licensing-and-entitlements.md

@@ -40,6 +40,9 @@ Four features are enabled per instance rather than bundled into a tier:
 No tier includes them by default; you enable them on the instances that need
 them.
 
+[Patching](../vantage/patching.md) is available on every tier and is not a
+feature you enable: security patching is never paid for.
+
 ## Increases and reductions
 
 An increase takes effect when payment confirms, and the entitlement is promoted

docs/reference/api-tokens.md

@@ -61,6 +61,7 @@ satisfies a `:read` requirement for it - you do not need to tick both.
 | `monitors`  | Monitors, incidents, uptime and notification channels |
 | `vulns`     | Vulnerability findings, packages and scan rules      |
 | `workloads` | Containers and systemd units, including control actions and logs |
+| `patching`  | Maintenance windows, patch policies and patch runs. `patching:write` creates and edits them and starts or cancels runs |
 | `settings`  | Instance settings, members, single sign-on, licence, and token management itself |
 
 A token created with only `servers:read` can list and inspect servers but

docs/vantage/patching.md

@@ -0,0 +1,121 @@
+---
+id: patching
+title: Patching
+sidebar_label: Patching
+---
+
+Patching installs OS updates on your servers inside a **maintenance window**
+you choose, and records what happened on every server. It is available on every
+tier: security patching is never a paid feature.
+
+Three things work together:
+
+| Thing                  | What it answers                                             |
+| ----------------------- | ----------------------------------------------------------- |
+| A maintenance window   | *When.* "Sundays 02:00 to 04:00, Europe/London"             |
+| A patch policy         | *What and where.* "Security updates on every `env:prod` server, reboot if needed" |
+| A patch run            | *What happened.* One record per window, with a result per server |
+
+Clicking **Apply updates** on a server or on the vulnerabilities page also
+creates a run, so every patch Vantage performs has a record.
+
+## Maintenance windows
+
+**Patching → Windows → New window.** A window has a name, a start time written
+as five-field cron, a timezone and a length from 15 minutes to 12 hours. The
+editor shows the next three windows, computed by the same code that opens
+them.
+
+The timezone is stored by name, so a 02:00 window stays at 02:00 across
+daylight-saving changes. A window never starts while the previous one is still
+open, including on the night the clocks go back and 01:30 happens twice.
+
+A window used by a policy cannot be deleted. Move the policy to another window
+first.
+
+## Patch policies
+
+**Patching → Policies → New policy.** Owners and admins can create policies.
+
+| Setting        | Meaning |
+| -------------- | ------- |
+| Window         | The maintenance window the policy runs in |
+| Targets        | Named servers, tags, or both, exactly as for [workflows](./workflows.md#targeting). Tags are read when the window opens |
+| What to install | **Security updates only** or **All pending updates** |
+| Reboots        | **Never reboot**, or **Reboot if required** |
+| At most this many at once | How many servers patch at the same time. 0 means no limit |
+| Alert channels | Told when a run finishes with anything other than every server succeeding |
+
+**Run now** opens a window of the policy's usual length starting immediately.
+It is the way to try a policy before trusting it with a Sunday.
+
+### Security updates only
+
+| Package manager | How security-only works |
+| --------------- | ----------------------- |
+| apt (Debian, Ubuntu) | Only your `-security` sources are used |
+| dnf, yum (RHEL, Rocky, Alma, Fedora) | `--security` |
+| zypper (SUSE) | Security patches only |
+| Windows | The Security Updates and Critical Updates classifications |
+| apk (Alpine), pacman (Arch) | **Not supported.** These publish no security metadata, so the server reports *unsupported* and nothing is installed |
+
+Security-only never falls back to installing everything.
+
+### Reboots
+
+With **Reboot if required**, a server reboots only when its OS reports that a
+reboot is owed, and only if at least 5 minutes of the window remain. The agent
+reports first, then reboots after one minute.
+
+Vantage then waits for the server to come back. The reboot counts as done when
+the agent reports a boot time later than the reboot, with no reboot still
+owed. A server that does not come back within 45 minutes is marked failed.
+
+With **Never reboot**, the server shows **reboot required** instead.
+
+## What happens during a window
+
+- Servers start patching as the window opens, up to the concurrency limit.
+- A server whose agent is offline is retried while the window is open.
+- No server starts patching in the last 15 minutes of a window. Servers still
+  waiting then are marked when the window closes.
+- Servers already patching are allowed to finish, even past the window end
+  (up to 2 hours from when each started). Interrupting a package manager is
+  worse than letting it finish late.
+- A reboot only happens if at least 5 minutes of the window remain.
+- A policy whose previous run is still going skips the window, and says so on
+  the policy.
+
+## Patch runs
+
+**Patching → Runs** lists every run. Open one to see each server's result, how
+many updates were installed, reboot times, and the last part of the package
+manager's output.
+
+| Server status | Meaning |
+| ------------- | ------- |
+| queued | Waiting for a concurrency slot |
+| waiting for agent | The agent is offline; retried while the window is open |
+| patching | Installing now |
+| rebooting | Rebooted; waiting for it to come back |
+| succeeded | Patched, and rebooted and back if a reboot was owed and allowed |
+| failed | The package manager failed, the agent did not answer, or the reboot did not complete |
+| unsupported | Security-only on a server with no security metadata |
+| agent too old | The agent must be updated before it can take part |
+| missed, offline | Offline for the whole window |
+| window closed | Still waiting when the window ended |
+| cancelled | The run was cancelled before this server started |
+
+A run is **succeeded** when every server succeeded, **failed** when none did,
+and **partial** otherwise. Anyone can cancel a running run: servers already
+patching finish, and nothing further starts.
+
+Runs are kept for the same time as workflow logs (**Settings → Monitoring**).
+
+## Agent version
+
+Patch policies need agent **1.4.0** or later. An older agent would ignore
+"security only" and install everything, so Vantage does not send it policy
+work: it shows **agent too old** until you update it
+(see [Agent updates](../operations/agent-updates.md)). **Apply updates** still
+works on an older agent, but the run cannot report a result.

docs/vantage/servers.md

@@ -93,16 +93,16 @@ Agents check for pending package updates hourly and report the count - the
 machine's own package manager on Linux, the Windows Update COM API on Windows.
 From the server page you can:
 
-- **Apply updates** runs that check's install path and reports back. The agent
-  never reboots the machine; if one is owed, a **reboot required** badge
-  appears on the next inventory snapshot instead.
+- **Apply updates** installs every pending update now, without rebooting, and
+  opens the [patch run](./patching.md#patch-runs) recording the result. If a
+  reboot is owed, a **reboot required** badge appears on the next inventory
+  snapshot.
 - **Update agent** upgrades the Vantage agent on that machine. See
   [Agent updates](../operations/agent-updates.md).
 
-:::warning Applying updates is not scheduled or staged
-It runs immediately, on that machine. If you need ordering, health checks or a
-test machine first, build it as a [workflow](./workflows.md) instead.
-:::
+The panel also shows which [patch policy](./patching.md) covers the server and
+when its next window opens. To patch on a schedule, security-only, or with
+reboots, use a patch policy.
 
 ### Console
 

docs/vantage/vulnerabilities.md

@@ -55,12 +55,12 @@ against three-week-old data is not the same as a low count.
 
 ## Fixing something
 
-A finding with a known fixed version gets an **Apply updates** button, which
-runs the same OS update the server page offers. There is no separate patching
-mechanism.
+A finding with a known fixed version gets an **Apply updates** button. It
+installs every pending update on that server now and opens the
+[patch run](./patching.md#patch-runs) so you can see the result.
 
-Vantage never patches automatically. Applying updates is always something you
-ask for.
+To keep servers patched without clicking, create a
+[patch policy](./patching.md) with **Security updates only**.
 
 ## Accepting a finding
 

sidebars.ts

@@ -27,6 +27,7 @@ const sidebars: SidebarsConfig = {
                 "vantage/workflows",
                 "vantage/monitors",
                 "vantage/vulnerabilities",
+                "vantage/patching",
                 "vantage/workloads",
                 "vantage/notification-channels",
                 "vantage/status-pages",