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/licensing-and-entitlements.md

@@ -0,0 +1,95 @@
+---
+id: licensing-and-entitlements
+title: Licensing and entitlements
+sidebar_label: Licensing and entitlements
+---
+
+A **licence** is a signed statement of what one instance may do. An
+**entitlement** is the configuration a licence is cut from.
+
+## Tiers
+
+Three tiers, in both deployments. The allowances are identical across cloud and
+self-hosted — what differs is the term on offer, not what you get.
+
+| | Free | Professional | Enterprise |
+| --- | --- | --- | --- |
+| Servers (base) | 3 | 3 | 10 |
+| Monitors | 3 | unlimited | unlimited |
+| Secret groups | 1 | unlimited | unlimited |
+| Notification channels | 1 | unlimited | unlimited |
+| Audit retention | 30 days | 365 days | unlimited |
+| Support | Community | Email, 24×5 | Email and phone, 24×7 |
+
+The server count is **metered**: the base allowance comes with the tier, and you
+buy additional servers on top. That is why Professional shows a real number
+rather than "unlimited" — the number you actually have is the one in your
+entitlement.
+
+## Features
+
+Two are per-instance toggles rather than tier bundles:
+
+| Feature | What it enables |
+| --- | --- |
+| `console` | The [browser console](../vantage/browser-console.md) |
+| `oidc` | Per-instance [single sign-on](../vantage/settings.md#single-sign-on-oidc) |
+
+No tier includes them by default; you enable them on the instances that need
+them.
+
+## Entitlements: desired and granted
+
+Each instance has one entitlement row holding two configurations:
+
+| | Meaning |
+| --- | --- |
+| **Desired** | What you last asked for |
+| **Granted** | What a payment has confirmed |
+
+Checkout is built from **desired**. A licence is only ever signed from
+**granted**. An abandoned checkout therefore leaves a desired that reached
+nothing and changed nothing.
+
+### Increases and reductions
+
+An increase takes effect when payment confirms, and the entitlement is promoted
+desired → granted.
+
+A **reduction** is scheduled rather than immediate: you keep what you paid for
+until the end of the term, and the portal shows the date it drops. The collapse
+happens at renewal.
+
+## What a licence carries
+
+Instance UUID, deployment, tier, resolved limits, features, term and expiry —
+all signed.
+
+Two properties follow from that:
+
+- **A licence is bound to one instance UUID.** Moving it takes a
+  [relink](./self-hosted-instances.md#relinking).
+- **A licence is a snapshot.** Editing a plan later never rewrites an issued
+  licence, the same way editing a workflow step never rewrites a past run.
+
+Verification is local. Your instance does not call HQ to check a licence, and
+signing happens only in HQ.
+
+## Expiry and grace
+
+Expiry is padded with a grace period. Past that, the instance goes into degraded
+mode: it keeps running and keeps your data, but stops letting you do everything.
+
+The way out is a current licence — renew or purchase, then paste it (self-hosted)
+or let it be written for you (cloud).
+
+## Server limits in practice
+
+When you exceed your server allowance, enrolling another one is refused. The
+existing fleet is unaffected. Raise the allowance in the portal, or remove a
+server you are not using.
+
+## Legacy tiers
+
+An older `self_hosted` tier is mapped forward to self-hosted Professional
+wherever it appears. Nothing needs doing about it.