docs: Self review of doc pages

docs/vantage/audit-log.md

@@ -4,7 +4,8 @@ title: Audit log
 sidebar_label: Audit log
 ---
 
-Every mutating API path writes an audit event. The log is at **Audit**.
+Anything that changes something is recorded, whether it was done in the UI or by
+a script. The log is at **Audit Log**.
 
 ## What an event carries
 
@@ -23,21 +24,24 @@ keys and assignments, workflow and step changes, runs triggered, monitors and
 channels, secret groups and reveals, console sessions opened, settings and
 member changes, licence installs.
 
-Reads are not recorded, with one deliberate exception: **revealing a secret**
-writes an event, because reading that particular thing is an act rather than a
-lookup.
+Simply looking at something is not recorded, with one exception: **revealing a
+secret** is.
 
 ## What is not recorded
 
-- Sign-ins and sign-out.
+- Sign-ins and sign-outs.
 - Anything inside a console session.
 - Step output. That lives in the run log, kept under the workflow retention
   setting rather than with the audit log.
 
 ## Retention
 
-Audit events are not swept by the workflow log retention setting that setting
-governs run logs only. Audit history stays until the instance does.
+How long audit events are kept comes from your licence: 30 days on Free, a year
+on Professional, and unlimited on Enterprise. See
+[Licensing and entitlements](../hq/licensing-and-entitlements.md).
+
+This is separate from the workflow log retention setting, which covers run logs
+only.
 
 :::warning It is a log, not a control
 The audit log tells you what happened. It does not restrict what can happen, and
@@ -45,18 +49,11 @@ an admin can do anything an admin can do. Use roles for restriction and the log
 for accountability.
 :::
 
-## Getting events out
+## Searching and exporting
 
-`GET /api/audit` returns one page of events as JSON:
+The page searches by actor, detail and event type, and filters by category, such
+as `workflow`, `key` or `server`. The count shown is the number of matching
+events, not the number on screen.
 
-```json
-{ "events": [ ... ], "total": 3214 }
-```
-
-It accepts `limit` (default 50, maximum 200), `skip`, `q` to search actor,
-details and event type, and `category` to match the part of an event type
-before the dot — `workflow`, `key`, `server`. `total` counts everything
-matching the filter, not the page, so a short page is not the end of the log.
-
-There is no streaming or push export; if you need events in a SIEM, poll that
-endpoint, walking `skip` until you have `total`.
+The same events are available from the API if you want them in a log system of
+your own. See [Automating Vantage](../reference/rest-api.md).