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/people-and-roles.md

@@ -0,0 +1,98 @@
+---
+id: people-and-roles
+title: People and roles
+sidebar_label: People and roles
+---
+
+Two separate things live here: who is in your **account**, and who has access to
+each **instance**.
+
+## Account members
+
+**People** lists everyone in the account.
+
+| Role | Can |
+| --- | --- |
+| `owner` | Everything, including billing |
+| `admin` | Invite, create instances, grant instance access |
+| `member` | Read |
+
+Owners and admins invite; billing is owner-only.
+
+### Inviting someone
+
+1. **People → Invite**.
+2. Enter their email and pick a role.
+3. They receive a link and set their own password at `/accept-invite`.
+
+:::info Why you cannot set their password
+An invitation creates a person with an **empty password hash**, which cannot
+authenticate at all until they set one. If the inviter chose it, that password
+would be a shared credential to every instance the person is later granted
+access to.
+
+The verification endpoint knows the difference: a token belonging to a
+passwordless person reports that a password is needed and is left unspent, so
+the link still works when they get to it.
+:::
+
+### Removing someone
+
+Removing them from the account removes their portal access. See below for what
+happens to their instance access.
+
+## Instance access
+
+Granting access to a **cloud** instance creates a real user inside that
+instance's control plane, with `auth_source: "hq"`.
+
+```mermaid
+flowchart LR
+    P["HQ account member"] -->|grant| U["Control-plane user<br/>auth_source: hq"]
+    U --> I["The instance authenticates<br/>this user like any other"]
+```
+
+The instance authenticates that user exactly as it authenticates anyone else,
+with **no runtime dependency on HQ**. Revoking deletes the row — the control
+plane has no disabled state, and a row that exists is a row that can sign in.
+
+### Granting
+
+On an instance record, **Members → Add**, choose an account member and an
+instance role (`owner`, `admin`, `member`).
+
+One person holds at most one user per instance, so granting twice is refused
+rather than quietly creating a second user.
+
+### Roles inside an instance
+
+Independent of the account role. Someone can be an account `member` and an
+instance `owner`, or the reverse.
+
+### Revoking
+
+Removes the user from the instance immediately. Any live session ends with the
+session, since the user row backing it is gone.
+
+:::warning Self-hosted instances cannot be granted from HQ
+All three member endpoints refuse when the instance is self-hosted. Manage those
+users in the instance itself, at **Settings → Access**.
+:::
+
+## Passwords
+
+Your HQ password is the single source of truth for every user projected from it.
+Changing it in the portal rehashes it and copies the hash to every instance you
+have been granted.
+
+Propagation is best-effort and immediate; a background pass compares and repairs
+every 15 minutes, so a temporarily unreachable instance catches up on its own.
+
+There is no local password-change endpoint for those users in the control plane,
+so there is never a second writer for the hash.
+
+:::warning HQ-managed users are read-only in the instance
+Changing the role of, or deleting, an `hq`-sourced user inside the control plane
+is refused with `409`. Do it from the portal. The UI shows those rows read-only
+with a link back here, but the API is the boundary; the UI is the courtesy.
+:::