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/hq/billing.md

@@ -0,0 +1,83 @@
+---
+id: billing
+title: Billing
+sidebar_label: Billing
+---
+
+Paid plans are billed through **Paddle**, which is the merchant of record. Your
+invoice, your card details and your tax handling are all Paddle's; HQ holds a
+customer reference and nothing sensitive.
+
+Billing is **owner-only**.
+
+## Buying
+
+### Cloud
+
+Open the instance, change its configuration to what you want, and check out.
+Checkout runs in the browser.
+
+### Self-hosted
+
+**Buy self-hosted**, then bind the purchase to your install's UUID. See
+[Self-hosted instances](./self-hosted-instances.md).
+
+## What you are buying
+
+A subscription's line items are the configuration: the plan base, the metered
+server count above the base, and any per-instance features. Changing the
+configuration changes the line items.
+
+## Changing configuration
+
+**Instance → Configuration**, adjust servers or features, and save.
+
+- **Increases** take effect when the payment confirms.
+- **Reductions** are scheduled for the end of the term. The portal shows the
+  date and the new value.
+
+## The customer portal
+
+**Billing → Manage** mints a Paddle customer-portal session where you can
+update your payment method, see invoices and cancel.
+
+## How a licence follows a payment
+
+```mermaid
+flowchart LR
+    C["Checkout / change"] --> P["Paddle"]
+    P -->|signed webhook| H["HQ"]
+    H --> G["Entitlement: desired → granted"]
+    G --> L["Licence signed from granted"]
+```
+
+The webhook is the **only** issuing path for paid plans. It is signature
+verified, processed exactly once, and resolved from the subscription's *current*
+line items — so a webhook that arrives out of order still produces the right
+answer rather than replaying a stale state.
+
+A licence is signed from **granted** only. A checkout you abandon changes
+nothing.
+
+## Cancelling and failed payments
+
+Cancelling, or a payment going past due, takes **no immediate licence action**.
+Your licence runs to its grace-padded expiry and then lapses normally. There is
+no mid-term cut-off.
+
+For a cloud Free instance, lapsing eventually leads to deletion — see
+[Free tier](./free-tier.md). Paid instances are not reaped.
+
+## Renewals
+
+At renewal the subscription bills again and the licence is reissued for the new
+term. It is also the only moment a scheduled **reduction** takes effect.
+
+Self-hosted customers: download and paste the reissued licence. Cloud customers:
+nothing to do.
+
+## Free is not in Paddle at all
+
+Free has no subscription, no £0 line item and no Paddle record. It has its own
+renewal, in the portal. An account only acquires a Paddle customer reference
+with its first paid purchase.