feat: documentation site

Docusaurus 3 docs-only site at docsite/, served statically by nginx under
/docs on the marketing host. Covers getting started (self-hosted install
through first server and first licence), the control plane, Vantage HQ,
a reference section and operations.

Wired into docker-compose.site.yml as docsite (3005:80) and into the
image build workflow, rebuilding on its own directory only. Never added
to the self-hosted compose file.

docs/operations/upgrading.md

@@ -0,0 +1,79 @@
+---
+id: upgrading
+title: Upgrading
+sidebar_label: Upgrading
+---
+
+Upgrading the control plane is a pull and a recreate. Agents are versioned and
+upgraded separately — see [Agent updates](./agent-updates.md).
+
+## Upgrade
+
+```bash
+cd /opt/vantage
+docker compose pull
+docker compose up -d --remove-orphans
+```
+
+`--remove-orphans` clears containers for services that no longer exist in the
+Compose file, which is what leaves a stale container running after a service is
+renamed or removed.
+
+## What happens on boot
+
+1. **Migrations** run, recording markers so each runs once.
+2. **Indexes** are ensured. Auth and settings index builders are fatal on
+   failure; secret and workflow ones only warn.
+3. **Default steps** are reseeded from the image, overwriting the `default`
+   library — which is why those steps are read-only.
+
+Watch it:
+
+```bash
+docker compose logs -f server
+```
+
+## Before you upgrade
+
+- **Back up MongoDB.** See [Backups](./backups.md). Migrations are one-way.
+- **Read the release notes** for anything about migrations or environment
+  variables.
+- **Check your `.env`** still supplies everything required. A newly required
+  variable stops the boot rather than defaulting to something unsafe.
+
+## Downgrading
+
+There is no automatic downgrade. Migrations do not roll back, so returning to an
+older image means restoring the database backup taken before the upgrade. This
+is the reason the backup is not optional.
+
+## Zero-downtime
+
+The stack is not designed for it. `docker compose up -d` recreates the server
+container, which is a short interruption:
+
+- Agents reconnect on their own — they retry, and the poll loop is idempotent.
+- Workflow runs in progress lose their command stream. Steps already dispatched
+  finish on the agent, but their results have nowhere to go. **Do not upgrade
+  during a run.**
+- Sessions survive, because they live in Redis rather than in the server.
+
+## Upgrading the hosted deployment
+
+Both Compose files, together:
+
+```bash
+cd /opt/vantage
+docker compose -f docker-compose.yml -f docker-compose.site.yml pull
+docker compose -f docker-compose.yml -f docker-compose.site.yml up -d --remove-orphans
+```
+
+CI builds and pushes images but does **not** deploy them; rolling out is this
+manual step. See [CI/CD](./ci-cd.md).
+
+## After upgrading
+
+- Confirm every service is `running`.
+- Confirm servers return to `active` within a couple of poll intervals.
+- Open a page that touches encryption — a secret group — to confirm
+  `KEY_ENCRYPTION_KEY` came through.