docs: Self review of doc pages

This commit is contained in:
2026-08-10 16:32:23 +01:00
parent bd7b3256fc
commit 83c38db92e
34 changed files with 860 additions and 991 deletions
+32 -29
View File
@@ -19,54 +19,57 @@ buying in order to build it.
```mermaid
flowchart LR
A["Buy in HQ"] --> B["Placeholder instance<br/>awaiting_link, no licence"]
B --> C["Install Vantage<br/>get its instance UUID"]
C --> D["Paste the UUID<br/>claim-link"]
D --> E["Licence issued<br/>bound to that UUID"]
A["Buy in Vantage HQ"] --> B["Placeholder instance<br/>no licence yet"]
B --> C["Install Vantage<br/>find its instance ID"]
C --> D["Paste your install's ID"]
D --> E["Licence issued<br/>for that instance"]
```
1. **Overview → Buy self-hosted**, choose tier, term and configuration.
2. Complete checkout. HQ creates a **placeholder** instance in state
`awaiting_link` with no licence attached.
1. On **Overview**, choose **License my own install**, or **Buy a plan** if you
already have an instance. Pick **Self-hosted**, then your tier, billing cycle
and configuration.
2. Complete checkout. Vantage HQ creates a **placeholder** instance, waiting to
be linked, with no licence yet.
3. [Install Vantage](../getting-started/self-hosted-install.md) if you have not
already, and find its instance UUID at **Settings → Licence**.
4. Back in HQ, open the placeholder and paste the UUID.
5. The licence is issued, bound to that UUID. Download it and paste it into your
install.
already, and find its instance ID on the **Licence** page.
4. Back in Vantage HQ, open the placeholder and paste that ID.
5. The licence is issued. Download it and paste it into your install.
:::info Why there is a placeholder at all
A licence binds to an instance UUID, and at the moment of payment that UUID may
not exist yet. Issuing early would mean issuing to nothing; refusing to sell
until you had installed would be the wrong order. The placeholder holds the
purchase until there is something to bind to.
:::info Why there is a placeholder
A licence is issued to one instance, and at the moment you pay, that install may
not exist yet. The placeholder holds your purchase until it does.
:::
## Linking an existing install
## Linking an install you already have
If the install already exists, **Link an instance** takes the UUID directly. A
UUID already claimed by another account is refused with a conflict.
If the install exists before the purchase, the flow is the same: buy, then open
the placeholder from **Overview**, choose **Link install** and paste its instance
ID. An ID already claimed by another account is refused.
For a Free licence there is no placeholder step. See
[Claim a Free licence](../getting-started/claim-free-licence.md).
## Relinking
Rebuilding the host produces a new instance UUID, and the old licence no longer
matches. **Relink** moves the licence to the new UUID and reissues.
Rebuilding the host gives you a new instance ID, which your old licence does not
match. **Relink** moves the licence across and reissues it.
The number of relinks per term is capped, and the portal shows how many you have
left. This is not meant to obstruct disaster recovery if you have exhausted
them for a real reason, ask support.
left. If you have used them all for a genuine reason, ask support.
## Installing the licence
Paste it at **Settings → Licence** in your install. The instance verifies the
signature and checks that the UUID matches its own.
Paste it on the **Licence** page in your install. It confirms the licence was
issued to that instance before applying it.
Pasting works even while the current licence is expired that endpoint is
exempt from the licence check, because it is the route out of degraded mode.
Pasting works even while your current licence has expired, because that is how
you get out of degraded mode.
## Keeping it current
Your install does not fetch licences. When a licence is reissued renewal,
configuration change, relink download the new one from HQ and paste it in.
Your install never downloads a licence by itself. Whenever one is reissued, on
renewal, on a configuration change or after a relink, download it from Vantage
HQ and paste it in.
:::warning Nothing reminds your install
The control plane knows only what its licence says. Expiry emails come from HQ,