diff --git a/docs/vantage/vulnerabilities.md b/docs/vantage/vulnerabilities.md
new file mode 100644
index 0000000..b3eb103
--- /dev/null
+++ b/docs/vantage/vulnerabilities.md
@@ -0,0 +1,94 @@
+---
+id: vulnerabilities
+title: Vulnerabilities
+sidebar_label: Vulnerabilities
+---
+
+Each Linux server reports the packages it has installed. Vantage matches them
+against the security advisories published by that server's own distribution and
+raises a finding for anything not yet patched.
+
+Requires the **vulnerability scanning** feature on your licence. Without it,
+agents collect nothing at all — there is no inventory stored and no findings
+page to read.
+
+## What gets scanned
+
+Linux servers running `apt`, `dnf`/`yum`, `apk`, `zypper` or `pacman`. Agents
+report their package list hourly, and only when it has changed since the last
+report.
+
+Windows servers are not scanned.
+
+Some distributions publish no machine-readable advisory feed. Those servers
+show **unsupported** on their own page rather than appearing as having no
+vulnerabilities — the two are very different answers, and only one of them is
+good news.
+
+## Why versions look "wrong"
+
+A finding names the version your distribution ships, not the upstream release.
+Ubuntu's `openssl 3.0.2-0ubuntu1.15` carries security fixes backported into
+what still calls itself 3.0.2, so public CVE databases listing "3.0.2" as
+vulnerable are describing upstream, not your machine.
+
+Vantage matches against your distribution's own advisories, which is why a
+server can be running a version some scanners flag while Vantage correctly
+reports it as patched.
+
+For the same reason a severity here may be lower than the one you find on a CVE
+website. Debian and Red Hat routinely downgrade a rating when the vulnerable
+code path is not reachable in the way they build the package. Their rating is
+the accurate one for the package you are actually running.
+
+## The board
+
+`/vulnerabilities` groups findings by CVE. One row per CVE with the number of
+affected servers, expandable to the individual servers — the same CVE across
+forty machines is one decision, not forty.
+
+Severity counts at the top filter the list when clicked. The state tabs switch
+between **open**, **accepted** and **fixed**.
+
+The vulnerability database's age is shown above the board. If a pull has failed
+for long enough for the data to be stale, that becomes a warning: a low count
+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.
+
+Vantage never patches automatically. An unattended upgrade triggered by a third
+party's data feed is a fleet-wide change nobody chose.
+
+## Accepting a finding
+
+Some findings cannot be fixed today: a kernel CVE waiting on a reboot window,
+or one with no vendor fix published at all.
+
+**Accept** hides a finding from counts and alerts until a date you choose, with
+a reason that is recorded in the audit log along with your name. On that date it
+reopens by itself.
+
+The expiry is required. A dismissal with no end date is how a finding gets
+forgotten, and it is exactly what an auditor will ask to see.
+
+## Alerts
+
+Alert rules live with your notification channels, under
+**Settings → Notification Channels**. A rule has a minimum severity, an optional
+server tag filter, and one or more channels.
+
+A rule sends **one digest per scan** summarising what newly opened — never one
+message per finding. A database refresh can open several hundred findings at
+once, and a message each would flood the channel.
+
+Findings that were already open do not re-alert.
+
+## Fleet-wide package search
+
+`GET /api/packages/search?name=openssl` answers which servers run a given
+package and at what version, across the whole fleet. Useful during an incident
+before a finding exists for it.
diff --git a/sidebars.ts b/sidebars.ts
index 75ff65c..716c1a4 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -26,6 +26,7 @@ const sidebars: SidebarsConfig = {
                 "vantage/ssh-keys",
                 "vantage/workflows",
                 "vantage/monitors",
+                "vantage/vulnerabilities",
                 "vantage/notification-channels",
                 "vantage/secrets",
                 "vantage/browser-console",