fix: Fixed chart for ingress

/api-keys shares a raw string prefix with /api, and the proxies in front
of this app do not all match by path segment. Nginx Proxy Manager routes
/api straight to the Go server with a prefix location, so /api-keys never
reached Next at all — it reached a control plane with no such route and
came back as a JSON 404. Traefik's PathPrefix has the same shape of
matcher, which puts the Helm ingress at risk whenever ingress.api.enabled
is on.

The page is /tokens now, which cannot collide with anything, and which
matches the /api/tokens the REST API already publishes. The sidebar still
says API Keys — the label is for the reader, the path is for the router.

A permanent redirect covers anyone who bookmarked the old path today.
Fixing the proxy config instead would have left the trap set for the next
deployment, and for whatever sits in front of it.

.claude/settings.json

@@ -1,24 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|Grep",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "C:/Python314/Scripts/graphify.EXE hook-guard search"
-          }
-        ]
-      },
-      {
-        "matcher": "Read|Glob",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "C:/Python314/Scripts/graphify.EXE hook-guard read"
-          }
-        ]
-      }
-    ]
-  }
-}

.gitea/workflows/server-deploy.yml

@@ -95,6 +95,24 @@ jobs:
                     docker login ${{ vars.DOCKER_HOST }} \
                       -u "${{ secrets.REGISTRY_USER }}" --password-stdin
 
+            - name: Set up Go
+              if: steps.changed.outputs.server == 'true'
+              uses: actions/setup-go@v5
+              with:
+                  go-version: "1.26"
+                  cache: true
+                  cache-dependency-path: server/go.sum
+
+            - name: Verify the OpenAPI document is current
+              if: steps.changed.outputs.server == 'true'
+              run: |
+                  go install github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc5
+                  cd server
+                  swag init --generalInfo cmd/main.go --dir ./,../shared \
+                    --output internal/api/docs --outputTypes json --v3.1
+                  mv -f internal/api/docs/swagger.json internal/api/docs/openapi.json
+                  git diff --exit-code internal/api/docs/openapi.json
+
             - name: Build and push server image
               if: steps.changed.outputs.server == 'true'
               run: |

.gitignore

@@ -14,4 +14,5 @@ installer/checksums-msi.txt
 .next
 *.tsbuildinfo
 graphify-out
-docker-compose.live.yml
+docker-compose.live.yml
+.claude

CLAUDE.md

@@ -434,6 +434,60 @@ same commit.
 
 `UpdateAgentCmd` carries a target version and Gitea base URL; the agent downloads and replaces itself.
 
+### API tokens and OpenAPI
+
+A token is `vt_` plus 32 random bytes hex, shown once at creation and stored
+only as sha256 — the same shape as `servers.agent_token_hash` and the ESO read
+token, and for the same reason: nothing downstream ever needs the plaintext
+back. It belongs to the user who created it, and its role can never exceed
+theirs; see the `api_tokens` note under MongoDB Collections for how that stays
+true across a demotion rather than only at issuance. Scopes are eight
+resources — `servers`, `keys`, `secrets`, `workflows`, `monitors`, `vulns`,
+`workloads`, `settings` — each split into `:read` and `:write`, with `:write`
+satisfying a `:read` requirement on the same resource so a caller does not have
+to hold both. Any signed-in member may mint and revoke their **own** tokens —
+there is no `RequireRole` on `POST /tokens` or `DELETE /tokens/:id` — because
+`roleRank` already bounds what a token can do to no more than its creator's
+own role, so a member cannot use a token to reach past themselves. Owner and
+admin additionally see and revoke every token in the instance — `all=true` on
+`GET /tokens` is gated by `elevated()` in `api/tokens.go`, and
+`RevokeAPIToken` in `services/tokens.go` checks the same owner/admin condition
+before letting a revoke target somebody else's token — neither is a
+`RequireRole` middleware.
+The `settings:read`/`settings:write` entries in `routeScopes` govern a
+**token-authenticated** caller reaching the token endpoints — `RequireScopes`
+no-ops entirely for a cookie session — so they say nothing about which human
+role may call these routes with a session; that is `roleRank` and `elevated()`,
+not the scope map. Expiry is optional per token; `settings.api_token_max_days` caps how
+far out a new one may be set, and when that cap is set a token requested with
+no expiry is refused rather than silently capped — the policy governs
+issuance only and never reaches back to invalidate a token already issued.
+`RateLimitTokens` holds every token to 600 requests/minute in a Redis fixed
+window, answering 429 with `Retry-After`; cookie sessions are untouched; it
+exists so a runaway script cannot take an instance down, not as the general
+API rate-limiting project some future ticket might build.
+
+**The UI calls them API keys and lives at `/tokens`, not on `/settings`.**
+The page is reachable at **every** role, which is the whole reason it is a page:
+`/settings` is owner|admin throughout, so a card there hid a capability every
+member has. `settings.api_token_max_days` stays on `/settings` because it is
+instance policy rather than one person's credentials, and that split is exactly
+what lets the page be ungated. The label differs from the identifiers on
+purpose — the collection is `api_tokens`, the prefix is `vt_`, the routes are
+`/api/tokens`, and renaming a published endpoint to match a nav label would
+break every script already written against it.
+
+`server/internal/api/docs/openapi.json` is a **generated, committed** OpenAPI
+3.1 document — `swag v2` reading `@…` annotations off the handlers — served at
+`GET /api/openapi.json` and rendered as a reference page by a vendored Scalar
+bundle at `GET /api/docs`. `server-deploy.yml` regenerates it on every server
+build and runs `git diff --exit-code` against the committed copy: a handler
+whose annotation drifted from its code fails CI rather than shipping a
+reference that lies. Scalar is vendored (`scalar.standalone.js`, served from
+`GET /api/docs/scalar.js`) rather than pulled from a CDN, because the
+reference page has to work on an air-gapped install with no outbound access at
+all — the same requirement licence verification already meets.
+
 ### Marketing site and sitesvc
 
 `site/` is a separate Next.js app built exactly like `web/` — `output: "standalone"`, run by Node in a `node:26-alpine` image, listening on `3000` and published as `3003`. The contact form posts to `sitesvc`; account signup posts to `admin` (`NEXT_PUBLIC_ADMIN_API_URL`), which creates an HQ account, not an org — the control plane is not touched until the customer later creates a cloud instance from the portal.
@@ -551,6 +605,20 @@ The control plane refuses to change an `hq`-sourced user's role or delete it
 the portal, but the API is the boundary; the UI is a courtesy. There is no local
 password-change endpoint at all, so there is no competing writer for the hash.
 
+**A rename moves the host, and the licence does not care.** `PUT
+/api/instances/:id/name` re-derives the slug from the new name through
+`provision.RenameSlug` — the same rules that named the instance at creation —
+and writes the control plane first, because `instances.slug`'s unique index is
+what settles a race between two accounts reaching for one name. A taken slug is
+a refusal, not an `acme-2`: creation appends a counter because any free slug
+will do, and a rename is a request for one specific host. A licence binds the
+instance UUID, so nothing is reissued and Paddle is not called. The old host
+keeps resolving for up to 60s (`instancehost.go`'s cache, which admin cannot
+reach into), and `km_session` is host-only, so the customer signs in again on
+the new address — the portal says so rather than redirecting them into a login
+screen with no explanation. The 24h cooldown lives on `admin_instances.renamed_at`
+because it is admin's policy; staff bypass it and must not write the field.
+
 ---
 
 ## Auth and Orgs
@@ -661,6 +729,8 @@ licence      GET /license · POST /license                (POST: self-hosted onl
 org          GET,POST /org/users · PUT /org/users/:id/role · DELETE /org/users/:id
 providers    GET,POST /auth/providers · PUT,DELETE /auth/providers/:id
              POST /auth/providers/:id/{test,ack-notice} · GET /auth/presets  (owner|admin)
+tokens       GET /tokens · GET /tokens/scopes · POST /tokens · DELETE /tokens/:id
+             GET /openapi.json · GET /docs
 ```
 
 `GET /license` reports `deployment`, and **`POST /license` answers 409 `cloud_managed` when it is `cloud`**. A cloud instance's licence is written by `admin/internal/inject` straight into the database and never through this endpoint, so the refusal cannot break injection — it only stops a customer pasting over a licence they do not own. `web/` hides the paste form and points at the HQ portal instead, but as with `hq`-managed users, the API is the boundary and the UI is the courtesy.
@@ -692,11 +762,11 @@ GET  /account                                  # account, instances, max_relinks
 POST /instances                                # create a cloud instance (Free tier, one Free per account per deployment)
 POST /instances/:id/renew                      # Free renewal; refuses outside the renewal window
 POST /instances/:id/claim-free                 # issue Free on a linked self-hosted instance
+PUT  /instances/:id/name                       # rename a cloud instance; moves its slug (owner|admin, 24h cooldown)
 POST /instances/link · /instances/:id/relink
 GET  /instances/:id/entitlement
 GET  /checkout/options                         # active plans + catalogue prices for the running PADDLE_ENV
-POST /instances/self-hosted                    # create a paid-checkout placeholder (awaiting_link, no licence)
-POST /instances/:id/claim-link                 # bind a paid placeholder to the real UUID and issue
+POST /instances/self-hosted                    # link (or reuse) the install's real UUID for a paid checkout
 PUT  /instances/:id/entitlement                # set desired config; pushes line items to Paddle (owner|admin)
 POST /billing/portal                           # mint a Paddle customer-portal URL
 GET  /instances/:id/license · /instances/:id/license/download
@@ -718,6 +788,7 @@ Staff-session (`/api/staff`):
 GET,POST /accounts · GET /accounts/:id         # search by name, email, Paddle ID or instance UUID
 GET,POST /instances · GET /instances/:id       # instance + account + licence history + injection state
 POST /instances/:id/issue · /instances/:id/relink
+PUT  /instances/:id/name                       # rename any instance, no cooldown
 GET  /licenses · /subscriptions · /audit · /plans · PUT /plans/:deployment/:tier
 GET,PUT /catalogue
 GET,PUT /instances/:id/entitlement
@@ -730,11 +801,11 @@ GET  /health/injection · /health/billing
 
 Paddle is merchant of record; `admin/internal/paddle` is a thin REST client (no vendor SDK) and the only place that talks to it. **Free is entirely outside Paddle** — the shipped self-serve Free flow owns its own renewal, so no £0 subscription exists; an account learns its `paddle_customer_id` from its first paid webhook. Checkout happens in the browser (`@paddle/paddle-js`, token baked into the adminsite build); the server only updates a live subscription (`PUT /instances/:id/entitlement`) and mints a portal session.
 
-`POST /api/paddle/webhook` is the **only** issuing path for paid plans: signature-verified with `PADDLE_WEBHOOK_SECRET` (boot-required), idempotent via `paddle_events`, and a function of the subscription's _current_ line items — resolved back to a plan and configuration by `catalogue.ResolveItems`, so out-of-order delivery is correct by construction. A confirmed webhook promotes the entitlement `desired`→`granted` and signs from `granted` **only**; a checkout is built from `desired`. `subscription.canceled` and `past_due` take **no licence action** — the licence runs to its (grace-padded) expiry, then the existing lifecycle sweep lapses the instance. A renewal (`transaction.completed`, origin `subscription_recurring`) is the only moment a scheduled reduction collapses `desired` into `granted`. Self-hosted purchase creates a placeholder instance before payment (`POST /instances/self-hosted`); the licence is issued only once the customer pastes the install's real UUID (`POST /instances/:id/claim-link`), because a licence binds to that UUID.
+`POST /api/paddle/webhook` is the **only** issuing path for paid plans: signature-verified with `PADDLE_WEBHOOK_SECRET` (boot-required), idempotent via `paddle_events`, and a function of the subscription's _current_ line items — resolved back to a plan and configuration by `catalogue.ResolveItems`, so out-of-order delivery is correct by construction. A confirmed webhook promotes the entitlement `desired`→`granted` and signs from `granted` **only**; a checkout is built from `desired`. `subscription.canceled` and `past_due` take **no licence action** — the licence runs to its (grace-padded) expiry, then the existing lifecycle sweep lapses the instance. A renewal (`transaction.completed`, origin `subscription_recurring`) is the only moment a scheduled reduction collapses `desired` into `granted`. **Self-hosted purchase requires a standing control plane**: the customer pastes their install's real instance ID, `POST /instances/self-hosted` links it (or reuses one this account already owns, which is how Free upgrades to paid in place), and the checkout's `custom_data` names that UUID from the first event — so the webhook issues with no claim step and there is **no self-hosted placeholder**. A licence binds to the install's UUID, so buying before the install exists only ever deferred the same requirement behind a second identity to rewrite. `Placeholder` is now a cloud-only flag; a non-cloud placeholder reaching `handleSubscription` is a pre-change row and fails loudly rather than being guessed at.
 
 ## MongoDB Collections
 
-`servers` · `keys` · `assignments` · `orgs` · `users` · `auth_providers` · `settings` · `secrets` · `workflows` · `workflow_steps` · `workflow_runs` · `workflow_log_lines` · `workflow_log_seq` · `monitors` · `incidents` · `monitor_rollups` · `notification_channels` · `console_sessions` · `audit_logs` · `server_packages` · `vuln_findings` · `vuln_alert_rules` · `vulndb_meta` · `server_workloads` · `migrations`
+`servers` · `keys` · `assignments` · `orgs` · `users` · `auth_providers` · `settings` · `secrets` · `workflows` · `workflow_steps` · `workflow_runs` · `workflow_log_lines` · `workflow_log_seq` · `monitors` · `incidents` · `monitor_rollups` · `notification_channels` · `console_sessions` · `audit_logs` · `server_packages` · `vuln_findings` · `vuln_alert_rules` · `vulndb_meta` · `server_workloads` · `api_tokens` · `migrations`
 
 Every document except `migrations` carries `org_id`. Struct definitions are the source of truth — see `server/internal/models/`.
 
@@ -753,6 +824,7 @@ Notes that are not obvious from the structs:
 - `vuln_findings` is unique on `(instance_id, server_id, cve_id, package_name)`. That key is what makes a rescan an idempotent upsert rather than a duplicate factory, and what lets `first_seen` survive one. An empty `fixed_in` means no vendor fix exists — a real state, never "not vulnerable".
 - `vulndb_meta` is a singleton and deliberately carries **no** `instance_id`: the vulnerability database is a property of the deployment, not a tenant. Same reasoning as `migrations`, and the reason it is absent from `services.ScopedCollections`.
 - **`services.ScopedCollections` is the canonical registry of tenant-scoped collections**, and `scopedCollectionsForPurge` derives instance deletion from it rather than keeping a second list. A new collection carrying `instance_id` must be added there or its rows outlive the instance.
+- `api_tokens` stores only `sha256` of the token, like `servers.agent_token_hash`. A token's effective role is `min(user.role, token.role)` **recomputed per request**, so demoting somebody demotes their tokens; deleting the user deletes them. Scopes are enforced from a map keyed on the registered gin route pattern, and `AssertScopeMapComplete` **fails boot** when an `/api` route is missing from it — a route added without an entry would otherwise be silently unreachable by every token.
 
 Admin's own database is separate and holds `accounts` · `admin_instances` · `licenses` · `subscriptions` · `plans` · `catalogue` · `entitlements` · `paddle_events` · `staff_users` · `customer_users` · `instance_members` · `admin_audit`. `paddle_events` is the webhook idempotency log, unique on `event_id`: an event is claimed there before processing, and a duplicate of a handled event is a 200 no-op. `instance_members` is unique on `(instance_id, customer_user_id)` — one person holds at most one user in one instance, which makes a grant idempotent-by-refusal rather than silently doubling a projection. It is an _index_ of the control-plane rows, not the authority (see "Grants project, they do not federate"). Admin has no migrations collection; `models.Backfill` runs on every boot and is idempotent by filtering on the absence of what it writes.
 
@@ -950,9 +1022,20 @@ Customer nav is three destinations — Overview, People, Billing. Settings is in
 | `/steps`                                                        | Reusable step library                                                   |
 | `/monitors`, `/monitors/new`, `/monitors/[id][/edit]`           | Checks, uptime, incidents                                               |
 | `/secrets`, `/secrets/[group]`                                  | Vault                                                                   |
+| `/tokens`                                                       | Personal API keys — reachable at **every** role, unlike `/settings`     |
 | `/audit`                                                        | Audit log                                                               |
 | `/settings`, `/settings/notifications`, `/settings/license`     | Members, OIDC, alerts, retention, ESO token · channels · licence        |
 
+**The sidebar is grouped, and the groups are the nav's structure rather than
+decoration.** `web/components/Sidebar.tsx` holds `navGroups` — Fleet, Access,
+Automation, Instance — each rendered with a mono small-caps heading and a
+hairline rule above it, the first group excepted. Grouping is by what the
+operator is doing, not by which service answers: SSH keys, vault secrets and
+API keys sit together under Access because all three are credentials. A group
+whose every item is `adminOnly` disappears **whole**, heading and rule
+included, for a member — a labelled section with nothing under it reads as
+something that failed to load rather than something withheld.
+
 **`/settings` is one page, not a section.** Members and single sign-on used to
 live at `/settings/instance` with their own sidebar entry; they are now the
 **Access** group at the top of `/settings`, above **Monitoring** and

admin/internal/api/checkout.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
 	"strings"
@@ -8,7 +9,6 @@ import (
 
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/audit"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/auth"
-	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/billing"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/catalogue"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/db"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/licensing"
@@ -18,6 +18,7 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
 	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
 )
 
 // checkoutOptions serves everything the browser configurator needs to price a
@@ -43,36 +44,67 @@ func checkoutOptions(c *gin.Context) {
 	})
 }
 
-// createSelfHostedPlaceholder makes an instance row that exists only so a
-// checkout has something to put in custom_data. It carries no licence and is
-// flagged Placeholder until the customer pastes their install's real UUID. The
-// generated id is temporary; linking replaces the identity.
-func createSelfHostedPlaceholder(c *gin.Context) {
+// createSelfHostedCheckout prepares a paid self-hosted checkout against the
+// customer's REAL install UUID, and hands that id back for the checkout's
+// custom_data.
+//
+// A licence binds to the install's UUID, so the buyer must have a control plane
+// standing before they pay — the same precondition self-hosted Free already has.
+// That is what removes the placeholder: there is no temporary identity to
+// rewrite afterwards, the subscription's custom_data names the real instance
+// from the first event, and the webhook issues with no claim step.
+//
+// An id this account already owns is REUSED rather than refused: upgrading a
+// Free self-hosted install to a paid plan is the same purchase form, and
+// refusing it would mean the only route to Professional was to unlink first.
+// A UUID belonging to anyone else is still 409, from the unique index.
+func createSelfHostedCheckout(c *gin.Context) {
 	s := auth.Current(c)
 	var body struct {
-		Name string `json:"name"`
+		InstanceID string `json:"instance_id"`
+		Name       string `json:"name"`
 	}
-	if err := c.ShouldBindJSON(&body); err != nil || body.Name == "" {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "a name is required"})
+	if err := c.ShouldBindJSON(&body); err != nil || strings.TrimSpace(body.InstanceID) == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "instance_id is required"})
 		return
 	}
+	instanceID := strings.TrimSpace(body.InstanceID)
+	name := strings.TrimSpace(body.Name)
 	ctx := c.Request.Context()
-	inst := models.Instance{
-		InstanceID:  uuid.NewString(),
-		AccountID:   s.AccountID,
-		Name:        body.Name,
-		Deployment:  license.DeploymentSelfHosted,
-		Status:      models.StatusAwaitingLink,
-		Placeholder: true,
-		CreatedAt:   time.Now().UTC(),
-	}
-	if _, err := db.Admin("admin_instances").InsertOne(ctx, inst); err != nil {
+
+	var existing models.Instance
+	err := db.Admin("admin_instances").FindOne(ctx,
+		bson.M{"instance_id": instanceID, "account_id": s.AccountID}).Decode(&existing)
+	switch {
+	case err == nil:
+		if existing.Deployment != license.DeploymentSelfHosted {
+			c.JSON(http.StatusBadRequest, gin.H{
+				"error": "that instance is a cloud instance; change its plan from its own page"})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"instance_id": existing.InstanceID})
+		return
+	case !errors.Is(err, mongo.ErrNoDocuments):
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
+
+	if name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "a name is required"})
+		return
+	}
+	inst, err := licensing.LinkInstance(ctx, s.AccountID, instanceID, name)
+	if err != nil {
+		status := http.StatusBadRequest
+		if errors.Is(err, licensing.ErrAlreadyLinked) {
+			status = http.StatusConflict
+		}
+		c.JSON(status, gin.H{"error": err.Error()})
+		return
+	}
 	audit.Write(ctx, models.AuditEntry{
-		Actor: s.Email, Action: "instance.placeholder_created", AccountID: s.AccountID,
-		Target: inst.InstanceID, IP: c.ClientIP()})
+		Actor: s.Email, Action: "instance.checkout_started", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: "self-hosted", IP: c.ClientIP()})
 	c.JSON(http.StatusCreated, gin.H{"instance_id": inst.InstanceID})
 }
 
@@ -208,80 +240,6 @@ func updateEntitlement(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"entitlement": next, "pending": next.Pending()})
 }
 
-// claimPlaceholderLink binds a paid self-hosted placeholder to the customer's
-// real install UUID, then issues.
-//
-// :id is the placeholder (generated at checkout, carried in the subscription's
-// custom_data); the body carries the UUID the install actually reports. The
-// licence must bind to that real UUID (spec 1 has no unbound licence), so the
-// placeholder row's identity is rewritten to it and the subscription re-pointed,
-// then billing issues from the recorded subscription. Linking and claiming stay
-// one call here because, unlike Free, the payment already happened.
-func claimPlaceholderLink(c *gin.Context) {
-	inst, ok := ownedInstance(c, c.Param("id"))
-	if !ok {
-		return
-	}
-	if !inst.Placeholder {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "this instance is already linked"})
-		return
-	}
-	var body struct {
-		InstanceID string `json:"instance_id"`
-	}
-	if err := c.ShouldBindJSON(&body); err != nil || body.InstanceID == "" {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "instance_id is required"})
-		return
-	}
-	ctx := c.Request.Context()
-
-	// The real UUID must be free across every account — the unique index on
-	// instance_id is the tenant-isolation property, so refuse rather than collide.
-	if n, _ := db.Admin("admin_instances").CountDocuments(ctx,
-		bson.M{"instance_id": body.InstanceID}); n > 0 {
-		c.JSON(http.StatusConflict, gin.H{"error": "that instance ID is already linked"})
-		return
-	}
-
-	placeholderID := inst.InstanceID
-	if _, err := db.Admin("admin_instances").UpdateOne(ctx,
-		bson.M{"instance_id": placeholderID},
-		bson.M{
-			"$set": bson.M{
-				"instance_id": body.InstanceID,
-				"status":      models.StatusActive,
-				"placeholder": false,
-			},
-			"$addToSet": bson.M{"previous_instance_ids": placeholderID},
-		}); err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		return
-	}
-
-	// Re-point the subscription rows from the placeholder id to the real UUID so
-	// billing.IssueForInstance finds it, and rewrite Paddle's own copy of
-	// custom_data — written at checkout, it still names the placeholder, and every
-	// later event on this subscription is decoded from it.
-	if err := licensing.RepointSubscriptions(ctx, placeholderID, body.InstanceID, inst.AccountID); err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		return
-	}
-
-	if err := billing.IssueForInstance(ctx, body.InstanceID); err != nil {
-		// The link stuck; issuance did not. The reconciler and a retry recover it,
-		// and the customer is not blocked from linking. Surface it, do not roll back.
-		c.JSON(http.StatusAccepted, gin.H{
-			"instance_id": body.InstanceID,
-			"warning":     "linked, but licence issuance is pending: " + err.Error()})
-		return
-	}
-	audit.Write(ctx, models.AuditEntry{
-		Actor: auth.Current(c).Email, Action: "instance.placeholder_linked",
-		AccountID: inst.AccountID, Target: body.InstanceID,
-		Detail: "from placeholder " + placeholderID, IP: c.ClientIP()})
-	c.JSON(http.StatusOK, gin.H{"instance_id": body.InstanceID})
-}
-
 // billingPortal mints a Paddle customer-portal URL. The account must already
 // have a paddle_customer_id, which it learns from its first subscription webhook.
 func billingPortal(c *gin.Context) {

admin/internal/api/customer.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"log"
@@ -23,6 +24,7 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
 	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
 )
 
 // ownedInstance resolves an instance and confirms the session's account owns it.
@@ -538,6 +540,185 @@ func claimFree(c *gin.Context) {
 	c.JSON(http.StatusCreated, lic)
 }
 
+// renameInstance changes a cloud instance's name and moves it to the slug that
+// name derives to.
+//
+// The control plane is written FIRST, because instances.slug carries the unique
+// index and that index is what actually settles a race between two accounts
+// reaching for the same name. Admin's own row follows; if that write fails the
+// control plane is put back, because HQ printing a host that is not the host is
+// worse than a failed rename.
+//
+// No licence is issued and Paddle is not called: a licence binds the instance
+// UUID, and a rename does not change it.
+func renameInstance(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	if inst.Deployment != license.DeploymentCloud {
+		c.JSON(http.StatusBadRequest, gin.H{"error": selfHostedRefusal})
+		return
+	}
+	if inst.Placeholder {
+		c.JSON(http.StatusConflict, gin.H{"error": "this instance is not provisioned yet"})
+		return
+	}
+
+	var body struct {
+		Name string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+	name := strings.TrimSpace(body.Name)
+	if name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+
+	ctx := c.Request.Context()
+
+	// The unwind and the audit write run on a context detached from the request.
+	// The commonest reason the admin-side write fails at all is the caller
+	// walking away, and an unwind sharing that context fails with it — leaving
+	// the control plane renamed and admin's row not, which is the exact
+	// divergence this handler is arranged to prevent.
+	//
+	// Only the cancellation is detached here; each deadline is derived at its use
+	// site below. A deadline started before the forward work is a deadline the
+	// unwind may never get to use — a control plane slow enough to make the admin
+	// write fail is exactly the one that would have spent it already.
+	detached := context.WithoutCancel(ctx)
+
+	// Claim the cooldown atomically BEFORE the control-plane call. Checking it
+	// and then acting lets two parallel PUTs both pass the check and then
+	// interleave their two-database writes, which ends with the two databases
+	// disagreeing about the host — a worse outcome than either rename losing.
+	// The conditional update IS the cooldown; there is no second reading of it.
+	now := time.Now().UTC()
+	var claimed models.Instance
+	err := db.Admin("admin_instances").FindOneAndUpdate(ctx,
+		bson.M{
+			"instance_id": inst.InstanceID,
+			"account_id":  inst.AccountID,
+			"$or": []bson.M{
+				{"renamed_at": bson.M{"$exists": false}},
+				{"renamed_at": bson.M{"$lte": now.Add(-models.RenameCooldown)}},
+			},
+		},
+		bson.M{"$set": bson.M{"renamed_at": now}}).Decode(&claimed)
+	if err != nil {
+		if !errors.Is(err, mongo.ErrNoDocuments) {
+			log.Printf("renameInstance: claiming the cooldown on %s: %v", inst.InstanceID, err)
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "could not rename the instance"})
+			return
+		}
+		// No match means the cooldown is live or the row has gone; only a
+		// re-read tells those apart, and they are different answers.
+		var cur models.Instance
+		if err := db.Admin("admin_instances").FindOne(ctx,
+			bson.M{"instance_id": inst.InstanceID, "account_id": inst.AccountID}).Decode(&cur); err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+			return
+		}
+		if cur.RenamedAt != nil {
+			until := cur.RenamedAt.Add(models.RenameCooldown)
+			c.JSON(http.StatusTooManyRequests, gin.H{
+				"error":       fmt.Sprintf("this instance was renamed recently; it can be renamed again after %s UTC", until.Format("2 Jan 2006 15:04")),
+				"retry_after": until,
+			})
+			return
+		}
+		// The row is here and its cooldown is spent, yet the claim matched
+		// nothing: it changed under us. Nothing has been written, so refuse
+		// rather than guess which way.
+		log.Printf("renameInstance: cooldown claim on %s matched nothing against an eligible row", inst.InstanceID)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not rename the instance"})
+		return
+	}
+
+	// releaseClaim puts renamed_at back to whatever the claim overwrote — the
+	// previous instant, or absent when there was none. Every failure past the
+	// claim owes the customer their rename back.
+	releaseClaim := func(after string) {
+		undo := bson.M{"$unset": bson.M{"renamed_at": ""}}
+		if claimed.RenamedAt != nil {
+			undo = bson.M{"$set": bson.M{"renamed_at": *claimed.RenamedAt}}
+		}
+		rcCtx, cancel := context.WithTimeout(detached, 5*time.Second)
+		defer cancel()
+		if _, err := db.Admin("admin_instances").UpdateOne(rcCtx,
+			bson.M{"instance_id": inst.InstanceID}, undo); err != nil {
+			log.Printf("renameInstance: releasing the cooldown claim on %s after %s: %v", inst.InstanceID, after, err)
+		}
+	}
+
+	renamed, prevName, prevSlug, err := cloudprov.RenameInstance(ctx, inst.InstanceID, name)
+	switch {
+	case errors.Is(err, provision.ErrSlugTaken):
+		releaseClaim("a taken slug")
+		c.JSON(http.StatusConflict, gin.H{"error": "that name is already in use — try another"})
+		return
+	case errors.Is(err, provision.ErrNameRejected):
+		releaseClaim("a rejected name")
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": err.Error()})
+		return
+	case err != nil:
+		releaseClaim("a failed control-plane rename")
+		log.Printf("renameInstance: control plane rename of %s: %v", inst.InstanceID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not rename the instance"})
+		return
+	}
+
+	// A matched count of zero is a silent version of the same failure: the
+	// control plane moved and admin's row did not.
+	res, err := db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": inst.InstanceID},
+		bson.M{"$set": bson.M{"name": renamed.Name, "slug": renamed.Slug}})
+	if err == nil && res.MatchedCount == 0 {
+		err = errors.New("admin_instances row matched nothing")
+	}
+	if err != nil {
+		// The control plane's own previous values, not admin's copy: admin's may
+		// be stale, and its slug is omitempty.
+		rbCtx, rbCancel := context.WithTimeout(detached, 5*time.Second)
+		if rbErr := cloudprov.RestoreInstanceIdentity(rbCtx, inst.InstanceID, prevName, prevSlug); rbErr != nil {
+			log.Printf("renameInstance: rollback of %s failed: %v", inst.InstanceID, rbErr)
+		}
+		rbCancel()
+		releaseClaim("a failed record write")
+		log.Printf("renameInstance: record rename of %s: %v", inst.InstanceID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not rename the instance"})
+		return
+	}
+
+	if renamed.Slug == prevSlug {
+		// The cooldown exists because a rename moves the DNS host; a cosmetic
+		// edit that derives to the same slug moves nothing, so it should not
+		// spend one. The claim is already written by this point — releasing it
+		// is how that is expressed now the check is atomic.
+		releaseClaim("a rename that did not move the host")
+	}
+
+	s := auth.Current(c)
+	auCtx, auCancel := context.WithTimeout(detached, 5*time.Second)
+	audit.Write(auCtx, models.AuditEntry{
+		Actor: s.Email, Action: "instance.renamed", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: prevSlug + " -> " + renamed.Slug, IP: c.ClientIP()})
+	auCancel()
+
+	c.JSON(http.StatusOK, gin.H{
+		"instance_id": inst.InstanceID,
+		"name":        renamed.Name,
+		"slug":        renamed.Slug,
+		// The same builder the licence emails use, rather than a second opinion
+		// about how a tenant host is spelled. Empty when APP_LOGIN_URL is unset.
+		"login_url": loginURLFor(renamed.Slug),
+	})
+}
+
 // deliver sends a freshly issued licence where it needs to go. Cloud instances
 // are injected; self-hosted customers are emailed and can download.
 //

admin/internal/api/routes.go

@@ -75,11 +75,18 @@ func Routes(cfg config.Config) http.Handler {
 		cust.POST("/instances/:id/claim-free",
 			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
 			claimFree)
+		// Renaming moves the instance's DNS host, so it is owner-or-admin like
+		// every other instance mutation. Cloud only; the handler refuses the rest.
+		cust.PUT("/instances/:id/name",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			renameInstance)
 		cust.GET("/instances/:id/entitlement", getEntitlement)
 		cust.GET("/checkout/options", checkoutOptions)
+		// Paid self-hosted: links (or reuses) the customer's real install UUID so
+		// the checkout can name it. There is no placeholder and no claim step.
 		cust.POST("/instances/self-hosted",
 			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
-			createSelfHostedPlaceholder)
+			createSelfHostedCheckout)
 		// Paid cloud: provisions a real instance the paid webhook then licenses.
 		cust.POST("/instances/cloud",
 			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
@@ -88,9 +95,6 @@ func Routes(cfg config.Config) http.Handler {
 			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
 			updateEntitlement)
 		cust.POST("/billing/portal", billingPortal)
-		cust.POST("/instances/:id/claim-link",
-			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
-			claimPlaceholderLink)
 		cust.GET("/instances/:id/license", getInstanceLicense)
 		cust.GET("/instances/:id/license/download", downloadInstanceLicense)
 		cust.GET("/instances/:id/members", listInstanceMembers)
@@ -119,6 +123,7 @@ func Routes(cfg config.Config) http.Handler {
 		staff.GET("/subscriptions", staffListSubscriptions)
 		staff.POST("/instances/:id/issue", staffIssue)
 		staff.POST("/instances/:id/relink", staffRelink)
+		staff.PUT("/instances/:id/name", staffRenameInstance)
 		staff.GET("/licenses", staffListLicenses)
 		staff.GET("/plans", staffListPlans)
 		// Plans are keyed on the pair now, so the path is too. A single :tier

admin/internal/api/staff.go

@@ -1,18 +1,23 @@
 package api
 
 import (
+	"context"
+	"errors"
 	"fmt"
+	"log"
 	"net/http"
 	"strings"
 	"time"
 
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/audit"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/cloudprov"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/db"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/licensing"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/admin/internal/models"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/shared/license"
 	sharedmodels "gitea.hostxtra.co.uk/mrhid6/vantage/shared/models"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/shared/provision"
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
 	"go.mongodb.org/mongo-driver/v2/bson"
@@ -380,9 +385,12 @@ func staffListLicenses(c *gin.Context) {
 	c.JSON(http.StatusOK, lics)
 }
 
-// staffBillingHealth surfaces webhook handlers that failed and paid-but-unlinked
-// placeholders, so a customer who paid and got nothing is visible rather than
-// stuck in a support queue.
+// staffBillingHealth surfaces webhook handlers that failed and placeholders
+// still awaiting their instance, so a customer who paid and got nothing is
+// visible rather than stuck in a support queue.
+//
+// Placeholders are a cloud-only path now; any self-hosted row still listed here
+// predates the checkout change and needs issuing by hand.
 func staffBillingHealth(c *gin.Context) {
 	ctx := c.Request.Context()
 	failed := []models.PaddleEvent{}
@@ -615,3 +623,106 @@ func staffCreateAccountUser(c *gin.Context) {
 		Actor: s.Email, Action: "customer_user.created", AccountID: accountID, Target: email})
 	c.JSON(http.StatusCreated, gin.H{"pending": true})
 }
+
+// staffRenameInstance renames any instance, with no cooldown.
+//
+// It does NOT write renamed_at: a staff rename must not start the customer's
+// 24h clock, or fixing a name for someone locks them out of fixing it further.
+//
+// On self-hosted it changes admin's label only. There is no control-plane row to
+// write — the install is the customer's — and no slug, because self-hosted has
+// no tenant subdomain.
+//
+// A cloud placeholder is refused outright rather than relabelled: it has no
+// control-plane row yet, so a label-only rename here would be a name that the
+// instance never gets when provisioning finally derives its slug from the
+// checkout's name. The customer endpoint refuses it for the same reason.
+func staffRenameInstance(c *gin.Context) {
+	var body struct {
+		Name string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+	name := strings.TrimSpace(body.Name)
+	if name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+
+	ctx := c.Request.Context()
+	var inst models.Instance
+	if err := db.Admin("admin_instances").FindOne(ctx,
+		bson.M{"instance_id": c.Param("id")}).Decode(&inst); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return
+	}
+	if inst.Deployment == license.DeploymentCloud && inst.Placeholder {
+		c.JSON(http.StatusConflict, gin.H{"error": "this instance is not provisioned yet"})
+		return
+	}
+
+	// The unwind and the audit write must survive the request being cancelled:
+	// an unwind on a dead context leaves the two databases disagreeing, which is
+	// the failure the unwind exists for.
+	//
+	// Only the cancellation is detached here; each deadline is derived at its use
+	// site below. A deadline started before the forward work is a deadline the
+	// unwind may never get to use — a control plane slow enough to make the admin
+	// write fail is exactly the one that would have spent it already.
+	detached := context.WithoutCancel(ctx)
+
+	set := bson.M{"name": name}
+	slug := inst.Slug
+	cloud := inst.Deployment == license.DeploymentCloud
+	// The control plane's own previous values, not admin's copy: admin's may be
+	// stale, and its slug is omitempty, so unwinding from it can write an empty
+	// slug into instances.
+	prevName, prevSlug := inst.Name, inst.Slug
+
+	if cloud {
+		renamed, pName, pSlug, err := cloudprov.RenameInstance(ctx, inst.InstanceID, name)
+		switch {
+		case errors.Is(err, provision.ErrSlugTaken):
+			c.JSON(http.StatusConflict, gin.H{"error": "that name is already in use"})
+			return
+		case errors.Is(err, provision.ErrNameRejected):
+			c.JSON(http.StatusUnprocessableEntity, gin.H{"error": err.Error()})
+			return
+		case err != nil:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		prevName, prevSlug = pName, pSlug
+		slug = renamed.Slug
+		set["slug"] = renamed.Slug
+	}
+
+	// A matched count of zero is the same failure quietly: the control plane
+	// moved and admin's row did not.
+	res, err := db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": inst.InstanceID}, bson.M{"$set": set})
+	if err == nil && res.MatchedCount == 0 {
+		err = errors.New("admin_instances row matched nothing")
+	}
+	if err != nil {
+		if cloud {
+			rbCtx, rbCancel := context.WithTimeout(detached, 5*time.Second)
+			if rbErr := cloudprov.RestoreInstanceIdentity(rbCtx, inst.InstanceID, prevName, prevSlug); rbErr != nil {
+				log.Printf("staffRenameInstance: rollback of %s failed: %v", inst.InstanceID, rbErr)
+			}
+			rbCancel()
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	auCtx, auCancel := context.WithTimeout(detached, 5*time.Second)
+	audit.Write(auCtx, models.AuditEntry{
+		Actor: auth.Current(c).Email, Action: "instance.renamed", AccountID: inst.AccountID,
+		Target: inst.InstanceID, Detail: prevSlug + " -> " + slug, IP: c.ClientIP()})
+	auCancel()
+
+	c.JSON(http.StatusOK, gin.H{"instance_id": inst.InstanceID, "name": name, "slug": slug})
+}

admin/internal/billing/subscription.go

@@ -69,12 +69,12 @@ func handleSubscription(ctx context.Context, ev Event) error {
 		return fmt.Errorf("resolve items for subscription %s: %w", d.ID, err)
 	}
 
-	// Resolve BEFORE recording. A self-hosted subscription's custom_data is
-	// written at checkout and names the placeholder; the claim rewrote the
-	// instance's identity to the install's real UUID and patched Paddle, but that
-	// patch is best-effort and any event already in flight still carries the old
-	// id. Writing it straight through would revert the linked subscription row and
-	// then fail to find the instance, wedging every renewal.
+	// Resolve BEFORE recording. custom_data names whatever id the checkout was
+	// opened against, and a relink since then has rewritten the instance's
+	// identity and patched Paddle — but that patch is best-effort and any event
+	// already in flight still carries the old id. Writing it straight through
+	// would revert the subscription row and then fail to find the instance,
+	// wedging every renewal.
 	instanceID, inst, err := resolveInstance(ctx, d.CustomData.InstanceID)
 	if err != nil {
 		return fmt.Errorf("subscription %s names unknown instance %s: %w",
@@ -102,15 +102,20 @@ func handleSubscription(ctx context.Context, ev Event) error {
 			bson.M{"$set": bson.M{"paddle_customer_id": d.CustomerID}})
 	}
 
-	// Placeholders are the payment-first path: the instance does not exist until
-	// this confirmed-payment event. A cloud placeholder is provisioned here and
-	// then issued (first term). A self-hosted placeholder has no UUID to bind to
-	// until the customer pastes their install's — its subscription is recorded and
-	// the link endpoint issues later.
+	// A cloud placeholder is the payment-first path: the instance does not exist
+	// until this confirmed-payment event, so it is provisioned here and then
+	// issued (first term). Self-hosted has no placeholder — its checkout named
+	// the install's real UUID — so it falls straight through to issuance.
+	// An instance with no licence yet is a first purchase, not a change of plan.
+	// Self-hosted reaches that state through an ordinary link, so the placeholder
+	// flag no longer answers this on its own.
 	reason := models.ReasonEntitlementChange
+	if inst.CurrentLicense == "" {
+		reason = models.ReasonNew
+	}
 	if inst.Placeholder {
 		if inst.Deployment != license.DeploymentCloud {
-			return nil
+			return fmt.Errorf("instance %s is a non-cloud placeholder, which no longer exists", inst.InstanceID)
 		}
 		provisioned, err := completeCloudPlaceholder(ctx, &inst)
 		if err != nil {
@@ -124,8 +129,8 @@ func handleSubscription(ctx context.Context, ev Event) error {
 }
 
 // resolveInstance finds the instance a webhook's custom_data names, following the
-// identity trail when the id is one a placeholder claim or a relink has since
-// replaced. It returns the instance's CURRENT id, which is the only id anything
+// identity trail when the id is one a relink or a cloud placeholder's
+// provisioning has since replaced. It returns the instance's CURRENT id, which is the only id anything
 // else should be written against.
 func resolveInstance(ctx context.Context, customDataID string) (string, models.Instance, error) {
 	var inst models.Instance
@@ -245,30 +250,6 @@ func handleCustomerUpdated(ctx context.Context, ev Event) error {
 	return err
 }
 
-// IssueForInstance issues from an instance's recorded subscription. Called when
-// a self-hosted customer finally links a placeholder they have already paid for.
-func IssueForInstance(ctx context.Context, instanceID string) error {
-	var sub models.Subscription
-	if err := db.Admin("subscriptions").FindOne(ctx,
-		bson.M{"instance_id": instanceID, "status": models.SubActive}).Decode(&sub); err != nil {
-		return fmt.Errorf("no active subscription for %s: %w", instanceID, err)
-	}
-	var inst models.Instance
-	if err := db.Admin("admin_instances").FindOne(ctx,
-		bson.M{"instance_id": instanceID}).Decode(&inst); err != nil {
-		return err
-	}
-	items := make([]catalogue.Item, 0, len(sub.Items))
-	for _, it := range sub.Items {
-		items = append(items, catalogue.Item{PriceID: it.PriceID, Quantity: it.Quantity})
-	}
-	match, err := catalogue.ResolveItems(ctx, paddle.Get().Env(), items)
-	if err != nil {
-		return err
-	}
-	return promoteAndIssue(ctx, &inst, match, models.ReasonNew)
-}
-
 func toSubItems(items []catalogue.Item) []models.SubItem {
 	out := make([]models.SubItem, 0, len(items))
 	for _, it := range items {
@@ -308,7 +289,7 @@ func billingEmailFor(ctx context.Context, accountID string) string {
 
 // instanceNameFor is a best-effort display name for an email subject.
 func instanceNameFor(ctx context.Context, instanceID string) string {
-	// Alias-aware: a cancellation can name a placeholder id, and "your instance"
+	// Alias-aware: a cancellation can name an id a relink has replaced, and "your instance"
 	// in place of the name the customer chose reads like the wrong email.
 	_, inst, err := resolveInstance(ctx, instanceID)
 	if err != nil || inst.Name == "" {

admin/internal/cloudprov/cloudprov.go

@@ -202,3 +202,23 @@ func ProjectedUsers(ctx context.Context, hqUserID string) ([]sharedmodels.User,
 	}
 	return users, nil
 }
+
+// RenameInstance changes a cloud instance's name and moves it to the slug that
+// name derives to.
+//
+// It writes `instances` and nothing else, so admin's control-plane write
+// boundary is unchanged. It issues no licence: a licence binds the instance
+// UUID, which a rename never touches.
+//
+// The previous name and slug come back with the result because they are what an
+// unwind must restore — admin's own copy can be stale, or slugless.
+func RenameInstance(ctx context.Context, instanceID, name string) (inst *sharedmodels.Instance, prevName, prevSlug string, err error) {
+	return provision.RenameInstance(ctx, db.ControlDB(), instanceID, name)
+}
+
+// RestoreInstanceIdentity puts an instance's previous name and slug back, for a
+// caller unwinding a rename whose admin-side write failed. Leaving the two
+// databases disagreeing would have HQ print a host that is not the host.
+func RestoreInstanceIdentity(ctx context.Context, instanceID, name, slug string) error {
+	return provision.RestoreInstanceIdentity(ctx, db.ControlDB(), instanceID, name, slug)
+}

admin/internal/licensing/link.go

@@ -65,7 +65,7 @@ func LinkInstance(ctx context.Context, accountID, instanceID, name string) (*mod
 //
 // The local rewrite is returned as an error — issuance reads the subscription
 // back, so a half-moved row is worth failing on. The Paddle patch only logs: the
-// customer must not be blocked from linking or relinking by an outbound API
+// customer must not be blocked from relinking by an outbound API
 // failure, and the caller has already recorded the old id in
 // previous_instance_ids, which is what makes the webhook path correct whether or
 // not the patch lands.
@@ -151,9 +151,9 @@ func Relink(ctx context.Context, accountID, oldID, newID string, staff bool) (*m
 		return nil, fmt.Errorf("relink: %w", err)
 	}
 
-	// A relink rewrites the instance's identity exactly as a placeholder claim
-	// does, so the same two things have to follow it: the subscription rows that
-	// named the old id, and Paddle's own copy of custom_data. Without this a
+	// A relink rewrites the instance's identity, so two things have to follow it:
+	// the subscription rows that named the old id, and Paddle's own copy of
+	// custom_data. Without this a
 	// renewal after a relink cannot find its instance and the term never extends.
 	if err := RepointSubscriptions(ctx, oldID, newID, accountID); err != nil {
 		return nil, err

admin/internal/lifecycle/lifecycle.go

@@ -182,67 +182,6 @@ func runOnce(ctx context.Context) {
 	if err := Run(runCtx); err != nil {
 		log.Printf("lifecycle: %v", err)
 	}
-	sweepAwaitingLink(runCtx)
-}
-
-// Awaiting-link reminder keys.
-const (
-	noticeLink24 = "link_24"
-	noticeLink72 = "link_72"
-)
-
-// sweepAwaitingLink chases self-hosted instances that were paid for but never
-// linked: the subscription exists, the instance is still a placeholder. It
-// emails a reminder at 24h and again at 72h. The staff dashboard already flags
-// 48h; this is the active chasing on top of that. It never issues or deletes.
-func sweepAwaitingLink(ctx context.Context) {
-	cur, err := db.Admin("admin_instances").Find(ctx, bson.M{
-		"deployment":  license.DeploymentSelfHosted,
-		"placeholder": true,
-		"status":      models.StatusAwaitingLink,
-	})
-	if err != nil {
-		return
-	}
-	var instances []models.Instance
-	if err := cur.All(ctx, &instances); err != nil {
-		return
-	}
-	now := time.Now().UTC()
-	for _, inst := range instances {
-		// Only chase placeholders a customer has actually paid for.
-		n, err := db.Admin("subscriptions").CountDocuments(ctx,
-			bson.M{"instance_id": inst.InstanceID, "status": models.SubActive})
-		if err != nil || n == 0 {
-			continue
-		}
-		if !mail.Enabled() {
-			continue
-		}
-		to := accountEmail(ctx, inst.AccountID)
-		if to == "" {
-			continue
-		}
-		age := now.Sub(inst.CreatedAt)
-		var due string
-		if age > 72*time.Hour && !slices.Contains(inst.NoticesSent, noticeLink72) {
-			due = noticeLink72
-		} else if age > 24*time.Hour && !slices.Contains(inst.NoticesSent, noticeLink24) {
-			due = noticeLink24
-		}
-		if due == "" {
-			continue
-		}
-		if err := mail.Default.SendLinkReminder(to, inst.Name); err != nil {
-			log.Printf("lifecycle: link reminder %s for %s: %v", due, inst.InstanceID, err)
-			continue
-		}
-		if _, err := db.Admin("admin_instances").UpdateOne(ctx,
-			bson.M{"instance_id": inst.InstanceID},
-			bson.M{"$addToSet": bson.M{"notices_sent": due}}); err != nil {
-			log.Printf("lifecycle: record link notice %s for %s: %v", due, inst.InstanceID, err)
-		}
-	}
 }
 
 func accountEmail(ctx context.Context, accountID string) string {

admin/internal/models/models.go

@@ -111,6 +111,15 @@ const GracePeriod = 3 * 24 * time.Hour
 // second mechanism.
 const RenewWindow = 7 * 24 * time.Hour
 
+// RenameCooldown is how long a customer must wait between renames of one
+// instance.
+//
+// A rename moves the instance's DNS host and invalidates every saved link to it,
+// so this exists to make that a considered act rather than a slider. Staff are
+// not subject to it: a support conversation about a name is already a human
+// deciding.
+const RenameCooldown = 24 * time.Hour
+
 type Account struct {
 	ID               bson.ObjectID `bson:"_id,omitempty" json:"-"`
 	AccountID        string        `bson:"account_id" json:"account_id"`
@@ -137,20 +146,26 @@ type Instance struct {
 	Status         string        `bson:"status" json:"status"`
 	CurrentLicense string        `bson:"current_license,omitempty" json:"current_license,omitempty"`
 	RelinkCount    int           `bson:"relink_count" json:"relink_count"`
-	InjectFailedAt *time.Time    `bson:"inject_failed_at,omitempty" json:"inject_failed_at,omitempty"`
+	// RenamedAt is when this instance last changed name, and backs the customer
+	// rename cooldown. It is a pointer because absent means "never renamed"; a
+	// zero time.Time would read as year 1 — an inert cooldown, but only by
+	// accident. Staff renames deliberately leave it alone.
+	RenamedAt      *time.Time `bson:"renamed_at,omitempty" json:"renamed_at,omitempty"`
+	InjectFailedAt *time.Time `bson:"inject_failed_at,omitempty" json:"inject_failed_at,omitempty"`
 	// NoticesSent holds the lifecycle notice keys already emailed for the
 	// CURRENT term ("expiring", "expired", "delete_7", "delete_1"). Renewal
 	// clears it, so the next term starts the sequence again. It is what stops a
 	// restart re-sending a notice.
 	NoticesSent []string `bson:"notices_sent,omitempty" json:"notices_sent,omitempty"`
-	// Placeholder is true while a self-hosted instance row exists only so a
-	// checkout has something to attach custom_data to, before the customer has
-	// pasted their install's real UUID. Cleared when the instance is linked.
+	// Placeholder is true while a paid CLOUD instance row exists only so a
+	// checkout has something to attach custom_data to, before the confirmed
+	// payment provisions it. Cleared once provisioned. Self-hosted has no
+	// placeholder: its checkout names the install's real UUID.
 	Placeholder bool `bson:"placeholder,omitempty" json:"placeholder,omitempty"`
 	// PreviousInstanceIDs is every id this row has carried before its current one.
-	// A self-hosted row's identity is rewritten twice over its life — once when a
-	// paid placeholder is claimed, and again on each relink to a rebuilt server —
-	// and Paddle keeps its own copy of custom_data written at checkout. That copy
+	// A self-hosted row's identity is rewritten on each relink to a rebuilt
+	// server, and Paddle keeps its own copy of custom_data written at checkout.
+	// That copy
 	// is patched on each rewrite, but the patch is best-effort and any event
 	// already in flight still names an old id, so this is what lets a webhook
 	// resolve to the right instance instead of erroring as unknown.

admin/internal/paddle/client.go

@@ -26,8 +26,8 @@ type Client interface {
 	// customer changes their server count or features on an existing plan.
 	UpdateSubscriptionItems(ctx context.Context, paddleSubscriptionID string, items []LineItem) error
 	// UpdateSubscriptionCustomData replaces a subscription's custom_data. Used
-	// when a self-hosted placeholder is claimed: the checkout attached the
-	// placeholder id, and every later webhook must name the real install UUID.
+	// when a self-hosted instance is relinked to a rebuilt server: the checkout
+	// attached the old id, and every later webhook must name the new one.
 	UpdateSubscriptionCustomData(ctx context.Context, paddleSubscriptionID string, data map[string]string) error
 	// PortalSession returns a customer-portal URL for managing billing.
 	PortalSession(ctx context.Context, paddleCustomerID string) (string, error)

adminsite/app/(customer)/billing/page.tsx

@@ -6,7 +6,10 @@ import { NotConnectedPanel } from "@/components/NotConnected";
 import { PageFrame, RailCard, RailFacts } from "@/components/PageFrame";
 import { PageHeader } from "@/components/PageHeader";
 import { ManageBillingButton } from "@/components/ManageBillingButton";
-import { formatDate } from "@/lib/format";
+import { TermSpark } from "@/components/TermBar";
+import { EmptyState, Panel } from "@/components/Panel";
+import { Sub, TBody, TD, TH, THead, TR, Table } from "@/components/Table";
+import { formatDate, licenceState } from "@/lib/format";
 
 export default function BillingPage() {
     const subs = useQuery({ queryKey: ["subscriptions"], queryFn: api.subscriptions });
@@ -22,6 +25,21 @@ export default function BillingPage() {
     // difference between "professional · annual" and knowing which install that is.
     const nameFor = (instanceId?: string) => account.data?.instances.find((i) => i.instance_id === instanceId)?.name;
 
+    /*
+     * A subscription reports when the period ends but not when it began, so the
+     * start is derived from the term. Only the two terms we actually sell are
+     * handled — anything else returns null and the row falls back to the date
+     * alone, because a bar drawn from a guessed span is worse than no bar.
+     */
+    const periodStart = (end: string, term: string): string | null => {
+        const months = /ann|year/i.test(term) ? 12 : /month/i.test(term) ? 1 : 0;
+        if (!months) return null;
+        const d = new Date(end);
+        if (Number.isNaN(d.getTime())) return null;
+        d.setMonth(d.getMonth() - months);
+        return d.toISOString();
+    };
+
     return (
         <div className="grid gap-6">
             <PageHeader
@@ -56,34 +74,53 @@ export default function BillingPage() {
                     </>
                 }
             >
-                {rows.length === 0 ? (
-                    <p className="rounded border border-rule bg-panel p-5 text-ink-2">You have no subscriptions. Cloud instances and self-hosted licences are both bought from the pricing page.</p>
-                ) : (
-                    <div className="overflow-x-auto rounded border border-rule bg-panel">
-                        <table className="w-full border-collapse text-left">
-                            <thead>
-                                <tr className="border-b border-rule bg-panel-2 font-mono text-[0.68rem] uppercase tracking-[0.1em] text-ink-3">
-                                    <th className="px-4 py-2.5 font-normal">Instance</th>
-                                    <th className="px-4 py-2.5 font-normal">Plan</th>
-                                    <th className="px-4 py-2.5 font-normal">Term</th>
-                                    <th className="px-4 py-2.5 font-normal">Status</th>
-                                    <th className="px-4 py-2.5 font-normal">Renews</th>
-                                </tr>
-                            </thead>
-                            <tbody>
-                                {rows.map((s) => (
-                                    <tr key={s.subscription_id} className="border-b border-rule-soft last:border-0">
-                                        <td className="px-4 py-3">{nameFor(s.instance_id) ?? <span className="text-ink-3">Not linked yet</span>}</td>
-                                        <td className="px-4 py-3">{s.tier.replace("_", " ")}</td>
-                                        <td className="px-4 py-3">{s.term}</td>
-                                        <td className="px-4 py-3">{s.status}</td>
-                                        <td className="px-4 py-3 font-mono tabular-nums">{formatDate(s.current_period_end)}</td>
-                                    </tr>
-                                ))}
-                            </tbody>
-                        </table>
-                    </div>
-                )}
+                <Panel title="Subscriptions" meta={rows.length ? `${rows.length}` : undefined} bodyless>
+                    {rows.length === 0 ? (
+                        <EmptyState
+                            title="No subscriptions yet."
+                            body="Cloud instances and self-hosted licences are both bought from the plan page, and each one bills separately."
+                        />
+                    ) : (
+                        <Table stack>
+                            <THead>
+                                <TR className="hover:bg-transparent">
+                                    <TH>Instance</TH>
+                                    <TH>Plan</TH>
+                                    <TH>Billing</TH>
+                                    <TH>Status</TH>
+                                    <TH>Renews</TH>
+                                </TR>
+                            </THead>
+                            <TBody>
+                                {rows.map((s) => {
+                                    const start = periodStart(s.current_period_end, s.term);
+                                    const name = nameFor(s.instance_id);
+                                    return (
+                                        <TR key={s.subscription_id}>
+                                            <TD label="Instance">
+                                                {name ?? <span className="text-ink-3">Not linked yet</span>}
+                                                {name && <Sub>{s.instance_id?.slice(0, 8)}</Sub>}
+                                            </TD>
+                                            <TD label="Plan">{s.tier.replace("_", " ")}</TD>
+                                            <TD label="Billing" className="text-ink-2">
+                                                {s.term}
+                                            </TD>
+                                            <TD label="Status" className="text-ink-2">
+                                                {s.status}
+                                            </TD>
+                                            <TD label="Renews">
+                                                <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+                                                    {start && <TermSpark issuedAt={start} expiresAt={s.current_period_end} state={licenceState(s.current_period_end, true)} />}
+                                                    <span className="font-mono text-[0.78rem] tabular-nums text-ink-2">{formatDate(s.current_period_end)}</span>
+                                                </div>
+                                            </TD>
+                                        </TR>
+                                    );
+                                })}
+                            </TBody>
+                        </Table>
+                    )}
+                </Panel>
             </PageFrame>
         </div>
     );

adminsite/app/(customer)/instances/[id]/page.tsx

@@ -2,17 +2,64 @@
 
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useParams, useRouter } from "next/navigation";
+import Link from "next/link";
 import { useState } from "react";
-import { API_BASE, ApiError, NotConnected, api } from "@/lib/api";
+import { API_BASE, ApiError, NotConnected, api, type License } from "@/lib/api";
 import { NotConnectedPanel } from "@/components/NotConnected";
 import { LicenceDelivery } from "@/components/LicenceDelivery";
 import { MembersPanel } from "@/components/MembersPanel";
 import { RelinkPanel } from "@/components/RelinkPanel";
+import { RenamePanel } from "@/components/RenamePanel";
 import { StatePill } from "@/components/StatePill";
-import { PageFrame, RailCard, RailFacts } from "@/components/PageFrame";
+import { TermBar } from "@/components/TermBar";
+import { EmptyState, Note, Panel } from "@/components/Panel";
+import { PageFrame, RailCard } from "@/components/PageFrame";
 import { PageHeader } from "@/components/PageHeader";
+import { LinkButton } from "@/components/Button";
 import { formatDate, licenceState, limitLabel } from "@/lib/format";
-import { featureLabel } from "@/lib/features";
+import { FEATURE_LABEL, featureDesc, featureLabel } from "@/lib/features";
+import { useSession } from "@/lib/session";
+
+/** One key/value row. The key is the same keyed idiom as everywhere else. */
+function Row({ label, value }: { label: string; value: React.ReactNode }) {
+    return (
+        <div className="flex items-baseline justify-between gap-4">
+            <dt className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">{label}</dt>
+            <dd className="m-0 text-[0.88rem] tabular-nums">{value}</dd>
+        </div>
+    );
+}
+
+/*
+ * Every feature the product sells, granted or not.
+ *
+ * Listing only what is included answers "what do I have" but not "what am I
+ * missing", which is the question someone on this screen is actually weighing
+ * before they click Change plan. The absent ones are struck through rather than
+ * omitted, so the comparison is on the page instead of in another tab.
+ */
+function Features({ granted }: { granted: string[] }) {
+    const all = Object.keys(FEATURE_LABEL);
+    // Anything the licence carries that this build does not know about is still
+    // shown — the map degrades to the raw key, which is ugly but never wrong.
+    const extras = granted.filter((f) => !all.includes(f));
+
+    return (
+        <div className="grid gap-2">
+            <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">Features</span>
+            <div className="flex flex-wrap gap-1.5">
+                {[...all, ...extras].map((f) => {
+                    const on = granted.includes(f);
+                    return (
+                        <span key={f} title={featureDesc(f) || undefined} className={on ? "rounded-sm border border-rule px-2 py-0.5 text-[0.78rem] text-ink-2" : "rounded-sm border border-rule-soft px-2 py-0.5 text-[0.78rem] text-ink-3 line-through decoration-ink-3/60"}>
+                            {featureLabel(f)}
+                        </span>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}
 
 export default function InstancePage() {
     const id = String(useParams().id);
@@ -20,6 +67,10 @@ export default function InstancePage() {
     const qc = useQueryClient();
     const [relinkError, setRelinkError] = useState<string | undefined>();
 
+    // useSession is the app's one way to ask who the caller is — it shares the
+    // ["me"] query, so this adds no request.
+    const { session } = useSession();
+
     const account = useQuery({ queryKey: ["account"], queryFn: api.account });
     const licence = useQuery({
         queryKey: ["license", id],
@@ -29,12 +80,11 @@ export default function InstancePage() {
 
     const relink = useMutation({
         mutationFn: (newId: string) => api.relink(id, newId),
-        onSuccess: (lic) => {
+        onSuccess: (lic: License) => {
             qc.invalidateQueries({ queryKey: ["account"] });
             router.replace(`/instances/${lic.instance_id}`);
         },
-        onError: (err) =>
-            setRelinkError(err instanceof ApiError ? err.message : "Relink failed. Try again."),
+        onError: (err) => setRelinkError(err instanceof ApiError ? err.message : "Relink failed. Try again."),
     });
 
     if (account.error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
@@ -51,121 +101,176 @@ export default function InstancePage() {
     const lic = licence.data;
     const state = licenceState(lic?.expires_at, Boolean(lic));
     const cloud = instance.deployment === "cloud";
+    const mayRename = session?.account_role === "owner" || session?.account_role === "admin";
+    const maxRelinks = account.data?.max_relinks ?? 3;
+    const host = cloud && instance.slug ? `${instance.slug}.vantage.hostxtra.co.uk` : null;
 
     return (
         <div className="grid gap-6">
             <PageHeader
                 back={{ href: "/", label: "Overview" }}
                 title={instance.name || "Unnamed instance"}
-                subtitle={`${cloud ? "Cloud" : "Self-hosted"}${
-                    instance.tier ? ` · ${instance.tier.replace("_", " ")}` : ""
-                } · created ${formatDate(instance.created_at)}`}
-                record={[
-                    { key: "Instance", value: instance.instance_id, copy: true },
-                    ...(lic ? [{ key: "Licence", value: lic.license_id, copy: true }] : []),
-                ]}
+                subtitle={`${cloud ? "Cloud" : "Self-hosted"} instance${instance.tier ? ` on ${instance.tier.replace("_", " ")}` : ""} · created ${formatDate(instance.created_at)}`}
+                /*
+                 * The two things this screen is for, in the header rather than
+                 * hunted for further down. Download is self-hosted only: a cloud
+                 * licence is injected into the control plane directly and there
+                 * is nothing for the customer to do with the file.
+                 */
+                actions={
+                    <>
+                        {lic && !cloud && (
+                            <LinkButton variant="line" external href={api.licenseBlobUrl(instance.instance_id)}>
+                                Download licence
+                            </LinkButton>
+                        )}
+                        {lic && <LinkButton href="/purchase">Renew licence</LinkButton>}
+                    </>
+                }
+                record={[{ key: "Instance", value: instance.instance_id, copy: true }, ...(lic ? [{ key: "Licence", value: lic.license_id, copy: true }] : [])]}
                 status={<StatePill state={state} />}
             />
 
             <PageFrame
                 aside={
-                    <>
-                        <RailCard title="Licence">
-                            {lic ? (
-                                <RailFacts
-                                    rows={[
-                                        { label: "Tier", value: lic.tier.replace("_", " ") },
-                                        { label: "Issued", value: formatDate(lic.issued_at) },
-                                        { label: "Expires", value: formatDate(lic.expires_at) },
-                                        { label: "Reason", value: lic.reason },
-                                    ]}
-                                />
-                            ) : (
-                                <p className="text-[0.82rem] text-ink-2">
-                                    No licence issued yet.
-                                </p>
-                            )}
+                    host ? (
+                        <RailCard title="Console">
+                            <p className="text-[0.82rem] text-ink-2">Servers, workflows and monitors live in the instance itself.</p>
+                            <a href={`https://${host}`} className="inline-flex items-center justify-center gap-2 rounded border border-rule px-3 py-2 text-[0.84rem] font-semibold text-ink no-underline hover:border-accent hover:text-accent">
+                                Open {instance.name || "instance"} &rarr;
+                            </a>
+                            <p className="font-mono text-[0.72rem] text-ink-3">{host}</p>
                         </RailCard>
-
-                        {lic && (
-                            <RailCard title="Included">
-                                <RailFacts
-                                    rows={[
-                                        {
-                                            label: "Servers",
-                                            value: limitLabel(lic.limits.max_servers),
-                                        },
-                                        {
-                                            label: "Secret groups",
-                                            value: limitLabel(lic.limits.max_secret_groups),
-                                        },
-                                        {
-                                            label: "Channels",
-                                            value: limitLabel(lic.limits.max_channels),
-                                        },
-                                        {
-                                            label: "Features",
-                                            // Labelled, not raw keys: this is
-                                            // the customer's own licence, and
-                                            // "vuln_scanning" is not a name
-                                            // anyone bought.
-                                            value: lic.features.map(featureLabel).join(", ") || "none",
-                                        },
-                                    ]}
-                                />
-                            </RailCard>
-                        )}
-
-                        {!cloud && (
-                            <RailCard title="Moves">
-                                <RailFacts
-                                    rows={[
-                                        {
-                                            label: "Relinks used",
-                                            value: `${instance.relink_count} of ${
-                                                account.data?.max_relinks ?? 3
-                                            }`,
-                                        },
-                                    ]}
-                                />
-                                <p className="text-[0.82rem] text-ink-2">
-                                    Moving a licence to a different install counts as one.
-                                </p>
-                            </RailCard>
-                        )}
-                    </>
+                    ) : undefined
                 }
             >
-                {cloud ? (
-                    <MembersPanel instanceId={instance.instance_id} />
-                ) : (
-                    <p className="rounded border border-rule bg-panel p-5 text-ink-2">
-                        Users for this install are managed inside it, in Settings → Instance. We do
-                        not have access to your own deployment.
-                    </p>
+                {/*
+                 * The term leads. This screen is about one licence, and the rail
+                 * carried its issue and expiry dates as two lines of text —
+                 * which is the arithmetic this bar does for the reader.
+                 */}
+                {lic && (
+                    <Panel title="Licence" meta={`${lic.tier.replace("_", " ")} · ${cloud ? "Cloud" : "Self-hosted"}`}>
+                        <TermBar issuedAt={lic.issued_at} expiresAt={lic.expires_at} state={state} />
+
+                        {state === "warn" && <Note tone="warn">Inside 14 days of expiry. Renewing extends the term from the current expiry, not from today, so nothing is lost by renewing early.</Note>}
+                        {state === "expired" && <Note tone="expired">A lapsed licence does not stop the control plane: agents carry on reporting and your servers keep their keys. It stops accepting changes, so nothing new can be deployed until this is renewed.</Note>}
+                    </Panel>
                 )}
 
-                {lic && !cloud && (
-                    <>
-                        <LicenceDelivery
-                            instanceId={instance.instance_id}
-                            blob={lic.blob ?? ""}
-                            downloadUrl={api.licenseBlobUrl(instance.instance_id)}
+                {/*
+                 * What the licence grants, on the screen about that licence.
+                 * These were four rows in a 320px rail card, which is where
+                 * facts go when nobody has decided they matter.
+                 */}
+                {lic && (
+                    <Panel
+                        title="Included"
+                        /* A panel-header action is a quiet link, not a second
+                           full-size button competing with the header's Renew. */
+                        actions={
+                            <Link href="/purchase" className="font-mono text-[0.7rem] uppercase tracking-[0.1em] text-accent no-underline hover:underline">
+                                Change plan &rarr;
+                            </Link>
+                        }
+                    >
+                        <div className="grid gap-x-8 gap-y-2.5 sm:grid-cols-2">
+                            <dl className="grid content-start gap-2.5">
+                                <Row label="Servers" value={limitLabel(lic.limits.max_servers)} />
+                                <Row label="Monitors" value={limitLabel(lic.limits.max_monitors)} />
+                                <Row label="Secret groups" value={limitLabel(lic.limits.max_secret_groups)} />
+                            </dl>
+                            <dl className="grid content-start gap-2.5">
+                                <Row label="Channels" value={limitLabel(lic.limits.max_channels)} />
+                                <Row label="Audit history" value={`${limitLabel(lic.limits.audit_retention_days)} days`} />
+                                <Row label="Issued for" value={lic.reason.replace("_", " ")} />
+                            </dl>
+                        </div>
+
+                        <Features granted={lic.features} />
+                    </Panel>
+                )}
+
+                {/*
+                 * On a self-hosted instance the licence is the errand: someone
+                 * opens this page to fetch the blob and paste it. It sits
+                 * directly under the term, above the panels that only explain
+                 * things.
+                 */}
+                {lic && !cloud && <LicenceDelivery instanceId={instance.instance_id} blob={lic.blob ?? ""} downloadUrl={api.licenseBlobUrl(instance.instance_id)} />}
+
+                {cloud && <MembersPanel instanceId={instance.instance_id} />}
+
+                {/*
+                 * Address rather than "Rename": the panel is about where this
+                 * instance lives, and the rename is how you change it. Cloud
+                 * only — a self-hosted install has no tenant subdomain for us to
+                 * move.
+                 */}
+                {cloud && mayRename && (
+                    <Panel title="Address" meta={host ?? undefined}>
+                        <p className="text-[0.86rem] text-ink-2">
+                            The instance name is where its address comes from. Renaming moves it to a new address and releases the old
+                            one, so saved links and bookmarks to it stop working.
+                        </p>
+                        {/*
+                         * Keyed on the instance: this element stays mounted
+                         * across a navigation between two instance pages, so
+                         * without a key the success note and the typed name
+                         * from one instance surface on the next.
+                         */}
+                        <RenamePanel
+                            key={instance.instance_id}
+                            movesHost
+                            currentName={instance.name}
+                            currentSlug={instance.slug ?? ""}
+                            onRename={async (name) => {
+                                const res = await api.renameInstance(instance.instance_id, name);
+                                qc.invalidateQueries({ queryKey: ["account"] });
+                                return res;
+                            }}
                         />
-                        <RelinkPanel
-                            instanceId={instance.instance_id}
-                            used={instance.relink_count}
-                            max={account.data?.max_relinks ?? 3}
-                            error={relinkError}
-                            onRelink={(newId) => relink.mutate(newId)}
-                        />
-                    </>
+                    </Panel>
+                )}
+
+                {/*
+                 * "Moves" rather than "Relinks": the count is rationed, so the
+                 * headline is how many are left, and the panel explains what
+                 * spends one. Cloud instances cannot move — we own the host —
+                 * so the panel is absent rather than present and refusing.
+                 */}
+                {!cloud && (
+                    <Panel title="Moves" meta={`${Math.max(0, maxRelinks - instance.relink_count)} of ${maxRelinks} left`}>
+                        <p className="text-[0.86rem] text-ink-2">
+                            A licence binds to one install. Rebuilding the host, or moving to different hardware, needs a replacement licence bound to the new ID —
+                            that is a move, and it covers the rest of your current term.
+                        </p>
+                        <RelinkPanel instanceId={instance.instance_id} used={instance.relink_count} max={maxRelinks} error={relinkError} onRelink={(newId) => relink.mutate(newId)} />
+                    </Panel>
+                )}
+
+                {/*
+                 * A panel holding one sentence has not decided what it is for.
+                 * For a self-hosted install the useful content is not "we don't
+                 * do this" but where the thing they came looking for actually
+                 * lives — and why the people on their HQ account are not it.
+                 */}
+                {!cloud && (
+                    <Panel title="Who can sign in" meta="Managed in your install">
+                        <p className="text-[0.86rem] text-ink-2">
+                            You run this deployment, so its users live inside it rather than here. Add and remove them in the instance&rsquo;s own settings.
+                        </p>
+                        <p className="text-[0.82rem] text-ink-3">
+                            People on your Vantage HQ account can see billing and this licence. That is separate from who can sign in to the instance, and granting
+                            one never grants the other.
+                        </p>
+                    </Panel>
                 )}
 
                 {!lic && (
-                    <p className="rounded border border-rule bg-panel p-5 text-ink-2">
-                        No licence has been issued for this instance yet.
-                    </p>
+                    <Panel bodyless>
+                        <EmptyState title="No licence issued yet." body="A licence binds to one install, so it is issued once this instance is linked to the ID its install reports." action={<LinkButton href="/purchase">Get a licence</LinkButton>} />
+                    </Panel>
                 )}
             </PageFrame>
         </div>

adminsite/app/(customer)/instances/link/LinkForm.tsx

@@ -1,74 +0,0 @@
-"use client";
-
-import { useState } from "react";
-import { ApiError, NotConnected, api } from "@/lib/api";
-import { Button } from "@/components/Button";
-import { Field } from "@/components/Field";
-
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-export function LinkForm({
-    onLinked,
-    claimId,
-}: {
-    onLinked: (instanceId: string) => void;
-    // The PAID placeholder awaiting its real install UUID: claim it in place. The
-    // name was chosen at checkout, so it is not asked for again. Self-hosted Free
-    // is created on the purchase page instead, not here.
-    claimId: string;
-}) {
-    const [id, setId] = useState("");
-    const [error, setError] = useState<string | undefined>();
-    const [busy, setBusy] = useState(false);
-
-    async function submit(e: React.FormEvent) {
-        e.preventDefault();
-        const value = id.trim();
-
-        // Checked here so a typo costs nothing and the message is instant.
-        if (!UUID_RE.test(value)) {
-            setError(
-                "That does not look like an instance ID. It should look like the example below.",
-            );
-            return;
-        }
-
-        setBusy(true);
-        setError(undefined);
-        try {
-            const inst = await api.claimLink(claimId, value);
-            onLinked(inst.instance_id);
-        } catch (err) {
-            setError(
-                err instanceof NotConnected
-                    ? "The licensing service is not reachable from this page."
-                    : err instanceof ApiError
-                      ? err.message
-                      : "Could not link that instance. Try again.",
-            );
-        } finally {
-            setBusy(false);
-        }
-    }
-
-    return (
-        <form onSubmit={submit} className="grid gap-4" noValidate>
-            <Field
-                label="Instance ID"
-                value={id}
-                onChange={(e) => setId(e.target.value)}
-                error={error}
-                hint={
-                    <>
-                        Find this on your install&rsquo;s <code>Settings → Licence</code> page, or on
-                        the setup screen just after you first sign in. It looks like{" "}
-                        <code>6a0fe3f0-49d2-4aa1-967c-a3094b200b5d</code>.
-                    </>
-                }
-            />
-            <Button type="submit" disabled={busy} className="justify-self-start">
-                {busy ? "Linking…" : "Link and issue licence"}
-            </Button>
-        </form>
-    );
-}

adminsite/app/(customer)/instances/link/page.tsx

@@ -1,41 +0,0 @@
-"use client";
-
-import { useEffect } from "react";
-import { useRouter, useSearchParams } from "next/navigation";
-import { useQueryClient } from "@tanstack/react-query";
-import { LinkForm } from "./LinkForm";
-import { PageHeader } from "@/components/PageHeader";
-
-export default function LinkPage() {
-    const router = useRouter();
-    const qc = useQueryClient();
-    // This page only claims a PAID placeholder's real install UUID. Self-hosted
-    // Free is created on the purchase page, so with no placeholder to claim there
-    // is nothing to do here send them there.
-    const claimId = useSearchParams().get("claim") ?? undefined;
-
-    useEffect(() => {
-        if (!claimId) router.replace("/purchase");
-    }, [claimId, router]);
-
-    if (!claimId) return null;
-
-    return (
-        <div className="grid max-w-2xl gap-6">
-            <PageHeader
-                back={{ href: "/", label: "Overview" }}
-                title="Link an install"
-                subtitle="Every licence is tied to one install, so we need its ID before we can issue yours. Paste it below and your licence is ready on the next screen."
-            />
-            <LinkForm
-                claimId={claimId}
-                onLinked={(instanceId) => {
-                    qc.invalidateQueries({ queryKey: ["account"] });
-                    // Straight to the download, not back to a list: the licence is
-                    // the thing they came for.
-                    router.push(`/instances/${instanceId}`);
-                }}
-            />
-        </div>
-    );
-}

adminsite/app/(customer)/page.tsx

@@ -6,6 +6,7 @@ import { API_BASE, NotConnected, api, type License } from "@/lib/api";
 import { NotConnectedPanel } from "@/components/NotConnected";
 import { InstanceRecord } from "@/components/InstanceRecord";
 import { PageFrame, RailCard, RailFacts } from "@/components/PageFrame";
+import { Panel } from "@/components/Panel";
 import { PageHeader } from "@/components/PageHeader";
 import { LinkButton } from "@/components/Button";
 import { StatePill } from "@/components/StatePill";
@@ -34,21 +35,55 @@ export default function OverviewPage() {
 
     const live = data.instances.filter((i) => i.status !== "deleted");
 
-    // Work the customer has to do, gathered across every instance. This is the
-    // only account-level view of it each record only knows about itself.
+    /*
+     * Work the customer has to do, gathered across every instance. This is the
+     * only account-level view of it — each record only knows about itself.
+     *
+     * Each item carries the way out of it. It used to be a list of sentences in
+     * the rail, which told someone their licence was expiring and then made
+     * them go and find the instance that owned it; the fix for every one of
+     * these is one click, so the click belongs on the row.
+     */
     const attention = live.flatMap((i) => {
         const lic = byInstance.get(i.instance_id);
         const state = licenceState(lic?.expires_at, Boolean(lic));
-        if (state === "none") return [{ id: i.instance_id, text: `${i.name || "An instance"} is not linked`, note: "" }];
-        if (state === "expired") return [{ id: i.instance_id, text: `${i.name} has expired`, note: "now" }];
-        if (state === "warn")
+        const name = i.name || "An instance";
+
+        if (state === "none")
             return [
                 {
                     id: i.instance_id,
-                    text: `${i.name} expires`,
-                    note: `${daysRemaining(lic!.expires_at)}d`,
+                    text: `${name} has no licence yet`,
+                    note: "Pick a plan and we will issue a licence for this install.",
+                    href: "/purchase",
+                    action: "Get a licence",
+                    tag: "",
                 },
             ];
+        if (state === "expired")
+            return [
+                {
+                    id: i.instance_id,
+                    text: `${name} has expired`,
+                    note: "Servers keep running and agents keep their keys, but changes are disabled until you renew.",
+                    href: `/instances/${i.instance_id}`,
+                    action: "Renew",
+                    tag: "now",
+                },
+            ];
+        if (state === "warn") {
+            const d = daysRemaining(lic!.expires_at);
+            return [
+                {
+                    id: i.instance_id,
+                    text: `${name} expires in ${d} ${d === 1 ? "day" : "days"}`,
+                    note: "Renewing extends the term from the current expiry, so nothing is lost by renewing early.",
+                    href: `/instances/${i.instance_id}`,
+                    action: "Renew",
+                    tag: `${d}d`,
+                },
+            ];
+        }
         return [];
     });
 
@@ -71,32 +106,43 @@ export default function OverviewPage() {
             />
 
             {live.length === 0 ? (
-                <div className="grid max-w-xl gap-3 rounded border border-rule bg-panel p-5">
-                    <h2 className="text-xl">No instances yet</h2>
-                    <p className="text-ink-2">
-                        Create a free cloud instance and we host it, with your licence applied automatically. Or run Vantage on your own server and get its licence free or paid from the purchase page.
-                    </p>
-                    <div className="flex flex-wrap gap-2.5">
-                        <LinkButton href="/purchase">Buy a plan</LinkButton>
+                /*
+                 * An empty screen is an invitation to act, and the two ways in
+                 * are genuinely different products — we host it, or you do. One
+                 * button and a paragraph explaining the other option made the
+                 * self-hosted path read as an afterthought, which it is not.
+                 */
+                <div className="grid gap-4 rounded border border-rule bg-panel p-6">
+                    <div className="grid gap-2">
+                        <h2 className="text-xl">No instances yet</h2>
+                        <p className="max-w-[52ch] text-ink-2">An instance is one Vantage control plane. Start a hosted one in about a minute, or license an install you run yourself.</p>
                     </div>
+
+                    <div className="grid gap-3 sm:grid-cols-2">
+                        <div className="grid content-start gap-2 rounded border border-rule p-4">
+                            <h3 className="text-[1.05rem]">Cloud</h3>
+                            <p className="text-[0.82rem] text-ink-2">We host it, on a subdomain of vantage.hostxtra.co.uk, with the licence applied for you.</p>
+                            <div className="pt-1">
+                                <LinkButton href="/purchase">Create a cloud instance</LinkButton>
+                            </div>
+                        </div>
+                        <div className="grid content-start gap-2 rounded border border-rule p-4">
+                            <h3 className="text-[1.05rem]">Self-hosted</h3>
+                            <p className="text-[0.82rem] text-ink-2">You host it. Get the licence here, then paste your install&rsquo;s ID to bind it.</p>
+                            <div className="pt-1">
+                                <LinkButton variant="line" href="/purchase">
+                                    License my own install
+                                </LinkButton>
+                            </div>
+                        </div>
+                    </div>
+
+                    <p className="text-[0.78rem] text-ink-3">The Free tier covers 5 servers and needs no card.</p>
                 </div>
             ) : (
                 <PageFrame
                     aside={
                         <>
-                            {attention.length > 0 && (
-                                <RailCard title="Needs you" count={attention.length}>
-                                    <ul className="grid gap-2">
-                                        {attention.map((a) => (
-                                            <li key={a.id} className="flex items-center justify-between gap-2.5 text-[0.82rem] text-ink-2">
-                                                <span>{a.text}</span>
-                                                {a.note && <span className="font-mono text-[0.64rem] uppercase tracking-[0.08em] text-warn">{a.note}</span>}
-                                            </li>
-                                        ))}
-                                    </ul>
-                                </RailCard>
-                            )}
-
                             <RailCard title="Your team" count={people.data?.length}>
                                 <ul className="grid gap-2">
                                     {(people.data ?? []).slice(0, 5).map((p) => (
@@ -147,6 +193,32 @@ export default function OverviewPage() {
                         </>
                     }
                 >
+                    {/*
+                     * First in the main column, not in the rail. This is the
+                     * reason the page is open; the rail is for things that are
+                     * merely true. It disappears entirely when there is nothing
+                     * in it rather than saying "all clear", which is a line
+                     * nobody needs to read twice a week.
+                     */}
+                    {attention.length > 0 && (
+                        <Panel title="Needs you" meta={`${attention.length} ${attention.length === 1 ? "item" : "items"}`} bodyless>
+                            <ul className="grid">
+                                {attention.map((a) => (
+                                    <li key={a.id} className="flex flex-wrap items-center justify-between gap-3 border-b border-rule-soft px-4 py-3 last:border-b-0">
+                                        <div className="grid min-w-0 gap-0.5">
+                                            <span className="flex items-center gap-2 text-[0.9rem] font-semibold">
+                                                {a.text}
+                                                {a.tag && <span className="font-mono text-[0.62rem] uppercase tracking-[0.1em] text-warn">{a.tag}</span>}
+                                            </span>
+                                            <span className="text-[0.8rem] text-ink-3">{a.note}</span>
+                                        </div>
+                                        <LinkButton href={a.href}>{a.action}</LinkButton>
+                                    </li>
+                                ))}
+                            </ul>
+                        </Panel>
+                    )}
+
                     {live.map((i, n) => {
                         const lic = byInstance.get(i.instance_id);
                         const state = licenceState(lic?.expires_at, Boolean(lic));

adminsite/app/(customer)/purchase/PurchaseForm.tsx

@@ -142,10 +142,13 @@ export function PurchaseForm() {
         onError: (e) => setError(e instanceof ApiError ? e.message : "Could not create the licence."),
     });
 
+    // Self-hosted checkout names the install's REAL UUID, so the instance is
+    // linked (or an already-owned one reused) before Paddle opens. The webhook
+    // then issues straight onto it — there is no placeholder to claim afterwards.
     const startCheckout = useMutation({
         mutationFn: async () => {
             const trimmed = name.trim();
-            const r = dep === "cloud" ? await api.createCloudCheckout(trimmed) : await api.createSelfHosted(trimmed);
+            const r = dep === "cloud" ? await api.createCloudCheckout(trimmed) : await api.createSelfHostedCheckout(uuid.trim(), trimmed);
             return r.instance_id;
         },
         onSuccess: async (instanceId) => {
@@ -159,12 +162,6 @@ export function PurchaseForm() {
         onError: (e) => setError(e instanceof ApiError ? e.message : "Could not start checkout."),
     });
 
-    const claim = useMutation({
-        mutationFn: () => api.claimLink(pending!.instanceId, uuid.trim()),
-        onSuccess: () => router.push("/"),
-        onError: (e) => setError(e instanceof ApiError ? e.message : "Could not link the install."),
-    });
-
     if (optionsQ.isLoading || account.isLoading) {
         return <p className="text-ink-3">Loading plans…</p>;
     }
@@ -308,11 +305,13 @@ export function PurchaseForm() {
                     </Block>
                 )}
 
-                {selfHostedFree && (
-                    <Block n={3} label="Your install">
+                {dep === "self_hosted" && (
+                    <Block n={paid ? 4 : 3} label="Your install">
                         <div className="grid gap-3 rounded border border-rule bg-panel p-4">
                             <p className="text-[0.86rem] text-ink-2">
-                                Install Vantage on your own server first, then paste the instance ID it reports. We register it and issue your Free licence nothing to pay.
+                                {paid
+                                    ? "Every licence binds to one install, so stand your control plane up first and paste the instance ID it reports. We attach it to your account now and the licence lands the moment payment clears. Already have an instance here? Paste its ID to upgrade it."
+                                    : "Install Vantage on your own server first, then paste the instance ID it reports. We register it and issue your Free licence — nothing to pay."}
                             </p>
                             <label className="grid gap-1">
                                 <span className="text-[0.72rem] font-semibold uppercase tracking-[0.08em] text-ink-3">Instance ID</span>
@@ -380,7 +379,7 @@ export function PurchaseForm() {
                             ) : (
                                 <Cta
                                     label={startCheckout.isPending ? "Starting…" : "Continue to payment"}
-                                    disabled={!name.trim() || items.length === 0 || !accountId || startCheckout.isPending}
+                                    disabled={!name.trim() || items.length === 0 || !accountId || startCheckout.isPending || (dep === "self_hosted" && !UUID_RE.test(uuid.trim()))}
                                     onClick={() => {
                                         setError(null);
                                         startCheckout.mutate();
@@ -389,28 +388,13 @@ export function PurchaseForm() {
                             ))}
 
                         {/* Phase B: after the checkout has been opened. */}
-                        {pending?.deployment === "self_hosted" && (
+                        {pending && (
                             <div className="grid gap-2 border-t border-rule-soft pt-3">
-                                <p className="text-[0.8rem] text-ink-2">Once payment clears, paste the instance ID your install reports (Settings → Licence) to receive your licence.</p>
-                                <input
-                                    value={uuid}
-                                    onChange={(e) => setUuid(e.target.value)}
-                                    placeholder="00000000-0000-0000-0000-000000000000"
-                                    className="rounded border border-rule bg-panel px-2.5 py-2 font-mono text-[0.82rem] text-ink placeholder:text-ink-3"
-                                />
-                                <Cta
-                                    label={claim.isPending ? "Linking…" : "Link and issue licence"}
-                                    disabled={!uuid.trim() || claim.isPending}
-                                    onClick={() => {
-                                        setError(null);
-                                        claim.mutate();
-                                    }}
-                                />
-                            </div>
-                        )}
-                        {pending?.deployment === "cloud" && (
-                            <div className="grid gap-2 border-t border-rule-soft pt-3">
-                                <p className="text-[0.8rem] text-ink-2">Your instance is being set up. Its licence appears the moment payment clears no further steps.</p>
+                                <p className="text-[0.8rem] text-ink-2">
+                                    {pending.deployment === "cloud"
+                                        ? "Your instance is being set up. Its licence appears the moment payment clears — no further steps."
+                                        : "Your install is attached to this account. Its licence appears the moment payment clears — no further steps."}
+                                </p>
                                 <Link href={`/instances/${pending.instanceId}`} className="font-semibold text-accent underline">
                                     Go to your instance
                                 </Link>

adminsite/app/(customer)/users/InvitePanel.tsx

@@ -5,7 +5,7 @@ import { useState } from "react";
 import { API_BASE, ApiError, NotConnected, api, type AccountRole } from "@/lib/api";
 import { useSession } from "@/lib/session";
 import { NotConnectedPanel } from "@/components/NotConnected";
-import { Button } from "@/components/Button";
+import { Button, controlClass } from "@/components/Button";
 import { Field } from "@/components/Field";
 import { PageFrame, RailCard } from "@/components/PageFrame";
 import { formatDate } from "@/lib/format";
@@ -24,6 +24,7 @@ export function InvitePanel() {
     const [email, setEmail] = useState("");
     const [role, setRole] = useState<AccountRole>("member");
     const [error, setError] = useState<string | null>(null);
+    const [confirming, setConfirming] = useState<string | null>(null);
 
     const users = useQuery({ queryKey: ["account-users"], queryFn: api.accountUsers });
     const refresh = () => qc.invalidateQueries({ queryKey: ["account-users"] });
@@ -46,8 +47,14 @@ export function InvitePanel() {
     });
     const remove = useMutation({
         mutationFn: (id: string) => api.removeAccountUser(id),
-        onSuccess: refresh,
-        onError: fail,
+        onSuccess: () => {
+            setConfirming(null);
+            refresh();
+        },
+        onError: (e) => {
+            setConfirming(null);
+            fail(e);
+        },
     });
 
     if (users.error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
@@ -82,11 +89,7 @@ export function InvitePanel() {
                                     <span className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
                                         Account role
                                     </span>
-                                    <select
-                                        value={role}
-                                        onChange={(e) => setRole(e.target.value as AccountRole)}
-                                        className="rounded border border-rule bg-panel-2 px-2.5 py-2 font-mono text-ink"
-                                    >
+                                    <select value={role} onChange={(e) => setRole(e.target.value as AccountRole)} className={controlClass()}>
                                         {assignable.map((r) => (
                                             <option key={r} value={r}>
                                                 {r}
@@ -175,22 +178,46 @@ export function InvitePanel() {
                                             : "Invitation pending"}
                                     </td>
                                     <td className="px-4 py-3 text-right">
-                                        {canManage && !isSelf && (
-                                            <button
-                                                type="button"
-                                                className="text-[0.82rem] font-semibold text-expired underline"
-                                                onClick={() => {
-                                                    if (
-                                                        confirm(
-                                                            `Remove ${u.email}? They lose access to every instance on this account.`,
-                                                        )
-                                                    )
-                                                        remove.mutate(u.user_id);
-                                                }}
-                                            >
-                                                Remove
-                                            </button>
-                                        )}
+                                        {canManage &&
+                                            !isSelf &&
+                                            /*
+                                             * Inline rather than window.confirm(): removing
+                                             * someone here revokes them from every instance
+                                             * on the account, which is more than the word
+                                             * "Remove" beside one row implies, and the
+                                             * browser dialog cannot show the consequence
+                                             * where the eye already is.
+                                             */
+                                            (confirming === u.user_id ? (
+                                                <span className="inline-flex flex-wrap items-center justify-end gap-2">
+                                                    <span className="text-[0.82rem] text-ink-2">
+                                                        Removes access to every instance.
+                                                    </span>
+                                                    <button
+                                                        type="button"
+                                                        className="text-[0.82rem] font-semibold text-expired underline disabled:opacity-50"
+                                                        disabled={remove.isPending}
+                                                        onClick={() => remove.mutate(u.user_id)}
+                                                    >
+                                                        {remove.isPending ? "Removing…" : "Remove"}
+                                                    </button>
+                                                    <button
+                                                        type="button"
+                                                        className="text-[0.82rem] text-ink-2 underline"
+                                                        onClick={() => setConfirming(null)}
+                                                    >
+                                                        Keep
+                                                    </button>
+                                                </span>
+                                            ) : (
+                                                <button
+                                                    type="button"
+                                                    className="text-[0.82rem] font-semibold text-expired underline"
+                                                    onClick={() => setConfirming(u.user_id)}
+                                                >
+                                                    Remove<span className="sr-only"> {u.email}</span>
+                                                </button>
+                                            ))}
                                     </td>
                                 </tr>
                             );

adminsite/app/(staff)/staff/accounts/AccountSearch.tsx

@@ -4,8 +4,10 @@ import { useQuery } from "@tanstack/react-query";
 import Link from "next/link";
 import { useState } from "react";
 import { api } from "@/lib/api";
-import { Field } from "@/components/Field";
 import { formatDate } from "@/lib/format";
+import { EmptyState, Panel } from "@/components/Panel";
+import { controlClass } from "@/components/Button";
+import { Sub, TBody, TD, TH, THead, TR, Table } from "@/components/Table";
 
 export function AccountSearch() {
     const [q, setQ] = useState("");
@@ -14,56 +16,65 @@ export function AccountSearch() {
         queryFn: () => api.staff.accounts(q || undefined),
     });
 
+    const rows = data ?? [];
+
     return (
         <div className="grid gap-4">
-            <Field
-                label="Search"
-                value={q}
-                onChange={(e) => setQ(e.target.value)}
-                hint="Name, email, Paddle customer ID, or an instance UUID."
-            />
-            <div className="overflow-x-auto rounded border border-rule bg-panel">
-                <table className="w-full border-collapse text-left">
-                    <thead>
-                        <tr className="border-b border-rule bg-panel-2 font-mono text-[0.72rem] uppercase tracking-[0.08em] text-ink-3">
-                            <th className="px-4 py-2.5">Account</th>
-                            <th className="px-4 py-2.5">Billing email</th>
-                            <th className="px-4 py-2.5">Status</th>
-                            <th className="px-4 py-2.5">Created</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        {(data ?? []).map((a) => (
-                            <tr
-                                key={a.account_id}
-                                className="border-b border-rule-soft last:border-0"
-                            >
-                                <td className="px-4 py-3">
-                                    <Link
-                                        href={`/staff/accounts/${a.account_id}`}
-                                        className="text-accent underline"
-                                    >
+            <Panel>
+                <label className="grid gap-1.5">
+                    <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">Search</span>
+                    <input
+                        type="search"
+                        value={q}
+                        onChange={(e) => setQ(e.target.value)}
+                        placeholder="Name, email, ctm_… or an instance UUID"
+                        className={controlClass()}
+                    />
+                </label>
+            </Panel>
+
+            <Panel bodyless>
+                <Table>
+                    <THead>
+                        <TR className="hover:bg-transparent">
+                            <TH>Account</TH>
+                            <TH>Billing email</TH>
+                            <TH>Status</TH>
+                            <TH>Created</TH>
+                            <TH />
+                        </TR>
+                    </THead>
+                    <TBody>
+                        {rows.map((a) => (
+                            <TR key={a.account_id}>
+                                <TD>
+                                    <Link href={`/staff/accounts/${a.account_id}`} className="font-semibold text-accent no-underline hover:underline">
                                         {a.name}
                                     </Link>
-                                </td>
-                                <td className="px-4 py-3 font-mono text-[0.82rem]">
-                                    {a.billing_email}
-                                </td>
-                                <td className="px-4 py-3">{a.status}</td>
-                                <td className="px-4 py-3 font-mono tabular-nums">
-                                    {formatDate(a.created_at)}
-                                </td>
-                            </tr>
+                                    <Sub>
+                                        <span className="font-mono">{a.account_id}</span>
+                                    </Sub>
+                                </TD>
+                                <TD className="font-mono text-[0.82rem] text-ink-2">{a.billing_email}</TD>
+                                <TD className="text-ink-2">{a.status}</TD>
+                                <TD className="font-mono tabular-nums text-ink-2">{formatDate(a.created_at)}</TD>
+                                <TD numeric>
+                                    <Link href={`/staff/accounts/${a.account_id}`} className="font-mono text-[0.7rem] uppercase tracking-[0.1em] text-ink-3 no-underline hover:text-accent">
+                                        Open
+                                    </Link>
+                                </TD>
+                            </TR>
                         ))}
-                    </tbody>
-                </table>
-                {!isFetching && (data ?? []).length === 0 && (
-                    <p className="px-4 py-6 text-ink-3">
-                        No account matches that. Try the instance UUID from the customer&rsquo;s
-                        email.
-                    </p>
+                    </TBody>
+                </Table>
+
+                {!isFetching && rows.length === 0 && (
+                    <EmptyState
+                        title={q ? "No account matches that." : "No accounts yet."}
+                        body={q ? "Try the instance UUID from the customer's email — it resolves to the account that owns it." : undefined}
+                    />
                 )}
-            </div>
+            </Panel>
         </div>
     );
 }

adminsite/app/(staff)/staff/accounts/[id]/page.tsx

@@ -6,6 +6,8 @@ import Link from "next/link";
 import { api } from "@/lib/api";
 import { formatDate } from "@/lib/format";
 import { PageHeader } from "@/components/PageHeader";
+import { EmptyState, Panel } from "@/components/Panel";
+import { Sub, TBody, TD, TH, THead, TR, Table } from "@/components/Table";
 
 export default function AccountDetailPage() {
     const id = String(useParams().id);
@@ -17,7 +19,7 @@ export default function AccountDetailPage() {
     if (isLoading || !data) return <p className="text-ink-3">Loading…</p>;
 
     return (
-        <div className="grid gap-8">
+        <div className="grid gap-5">
             <PageHeader
                 back={{ href: "/staff/accounts", label: "Accounts" }}
                 title={data.account.name}
@@ -29,72 +31,126 @@ export default function AccountDetailPage() {
                 ]}
             />
 
-            <Panel title="Instances">
-                <ul className="grid gap-2">
-                    {data.instances.map((i) => (
-                        <li key={i.instance_id} className="flex flex-wrap justify-between gap-2">
-                            <Link href={`/staff/instances/${i.instance_id}`} className="text-accent underline">
-                                {i.name || i.instance_id}
-                            </Link>
-                            <span className="font-mono text-[0.82rem] text-ink-3">
-                                {i.deployment} · {i.tier ?? "no tier"} · {i.status}
-                            </span>
-                        </li>
-                    ))}
-                    {data.instances.length === 0 && <li className="text-ink-3">None.</li>}
-                </ul>
+            {/*
+             * Four lists of "thing · thing · thing" became four tables. Each row
+             * held three or four separate facts run into one string with
+             * middots, which cannot be scanned down a column — and a staff
+             * screen is read by scanning down a column.
+             */}
+            <Panel title="Instances" meta={String(data.instances.length)} bodyless>
+                <Table>
+                    <THead>
+                        <TR className="hover:bg-transparent">
+                            <TH>Instance</TH>
+                            <TH>Deployment</TH>
+                            <TH>Tier</TH>
+                            <TH>Status</TH>
+                            <TH />
+                        </TR>
+                    </THead>
+                    <TBody>
+                        {data.instances.map((i) => (
+                            <TR key={i.instance_id}>
+                                <TD>
+                                    <Link href={`/staff/instances/${i.instance_id}`} className="font-semibold text-accent no-underline hover:underline">
+                                        {i.name || "Unnamed instance"}
+                                    </Link>
+                                    <Sub>
+                                        <span className="font-mono">{i.instance_id.slice(0, 8)}</span>
+                                    </Sub>
+                                </TD>
+                                <TD className="text-ink-2">{i.deployment === "cloud" ? "Cloud" : "Self-hosted"}</TD>
+                                <TD className="text-ink-2">{i.tier?.replace("_", " ") ?? "—"}</TD>
+                                <TD className="text-ink-2">{i.status}</TD>
+                                <TD numeric>
+                                    <Link href={`/staff/instances/${i.instance_id}`} className="font-mono text-[0.7rem] uppercase tracking-[0.1em] text-ink-3 no-underline hover:text-accent">
+                                        Open
+                                    </Link>
+                                </TD>
+                            </TR>
+                        ))}
+                    </TBody>
+                </Table>
+                {data.instances.length === 0 && <EmptyState title="No instances on this account." body="They have signed up but not created or linked anything yet." />}
             </Panel>
 
-            <Panel title="Subscriptions">
-                <ul className="grid gap-2">
-                    {data.subscriptions.map((s) => (
-                        <li key={s.subscription_id} className="flex flex-wrap justify-between gap-2">
-                            <span>
-                                {s.tier.replace("_", " ")} · {s.term}
-                            </span>
-                            <span className="font-mono text-[0.82rem] text-ink-3">
-                                {s.status} · renews {formatDate(s.current_period_end)}
-                            </span>
-                        </li>
-                    ))}
-                    {data.subscriptions.length === 0 && <li className="text-ink-3">None.</li>}
-                </ul>
+            <Panel title="Subscriptions" meta={String(data.subscriptions.length)} bodyless>
+                <Table>
+                    <THead>
+                        <TR className="hover:bg-transparent">
+                            <TH>Tier</TH>
+                            <TH>Billing</TH>
+                            <TH>Status</TH>
+                            <TH>Renews</TH>
+                        </TR>
+                    </THead>
+                    <TBody>
+                        {data.subscriptions.map((s) => (
+                            <TR key={s.subscription_id}>
+                                <TD>{s.tier.replace("_", " ")}</TD>
+                                <TD className="text-ink-2">{s.term}</TD>
+                                <TD className="text-ink-2">{s.status}</TD>
+                                <TD className="whitespace-nowrap font-mono tabular-nums text-ink-2">{formatDate(s.current_period_end)}</TD>
+                            </TR>
+                        ))}
+                    </TBody>
+                </Table>
+                {data.subscriptions.length === 0 && <EmptyState title="No subscriptions." body="Everything on this account is Free, or nothing has been bought yet." />}
             </Panel>
 
-            <Panel title="People">
-                <ul className="grid gap-2">
-                    {data.users.map((u) => (
-                        <li key={u.user_id} className="flex flex-wrap justify-between gap-2">
-                            <span className="font-mono text-[0.82rem]">{u.email}</span>
-                            <span className="font-mono text-[0.82rem] text-ink-3">{u.verified_at ? `verified ${formatDate(u.verified_at)}` : "not verified"}</span>
-                        </li>
-                    ))}
-                    {data.users.length === 0 && <li className="text-ink-3">None this is a cloud account, so its people sign in with their control-plane details.</li>}
-                </ul>
+            <Panel title="People" meta={String(data.users.length)} bodyless>
+                <Table>
+                    <THead>
+                        <TR className="hover:bg-transparent">
+                            <TH>Email</TH>
+                            <TH>Role</TH>
+                            <TH>Verified</TH>
+                        </TR>
+                    </THead>
+                    <TBody>
+                        {data.users.map((u) => (
+                            <TR key={u.user_id}>
+                                <TD className="font-mono text-[0.82rem]">{u.email}</TD>
+                                <TD className="text-ink-2">{u.account_role}</TD>
+                                <TD className="text-ink-2">
+                                    {u.verified_at ? (
+                                        <span className="font-mono tabular-nums">{formatDate(u.verified_at)}</span>
+                                    ) : (
+                                        <span className="font-mono text-[0.7rem] uppercase tracking-[0.1em] text-warn">Not verified</span>
+                                    )}
+                                </TD>
+                            </TR>
+                        ))}
+                    </TBody>
+                </Table>
+                {data.users.length === 0 && (
+                    <EmptyState title="No HQ people on this account." body="This is a cloud account, so its people sign in with their control-plane details instead." />
+                )}
             </Panel>
 
-            <Panel title="Audit">
-                <ul className="grid gap-1 font-mono text-[0.82rem]">
-                    {data.audit.map((e, n) => (
-                        <li key={n} className="flex flex-wrap justify-between gap-2 text-ink-2">
-                            <span>
-                                {e.action} · {e.actor}
-                            </span>
-                            <span className="tabular-nums text-ink-3">{formatDate(e.created_at)}</span>
-                        </li>
-                    ))}
-                    {data.audit.length === 0 && <li className="text-ink-3">Nothing yet.</li>}
-                </ul>
+            <Panel title="Audit" meta="Newest first" bodyless>
+                <Table>
+                    <THead>
+                        <TR className="hover:bg-transparent">
+                            <TH>Date</TH>
+                            <TH>Actor</TH>
+                            <TH>Action</TH>
+                            <TH>Target</TH>
+                        </TR>
+                    </THead>
+                    <TBody>
+                        {data.audit.map((e, n) => (
+                            <TR key={n}>
+                                <TD className="whitespace-nowrap font-mono tabular-nums text-ink-2">{formatDate(e.created_at)}</TD>
+                                <TD className="text-ink-2">{e.actor}</TD>
+                                <TD className="font-mono text-[0.8rem]">{e.action}</TD>
+                                <TD className="text-ink-2">{e.target ?? "—"}</TD>
+                            </TR>
+                        ))}
+                    </TBody>
+                </Table>
+                {data.audit.length === 0 && <EmptyState title="Nothing recorded against this account yet." />}
             </Panel>
         </div>
     );
 }
-
-function Panel({ title, children }: { title: string; children: React.ReactNode }) {
-    return (
-        <section className="grid gap-3 rounded border border-rule bg-panel p-5">
-            <h2 className="text-xl">{title}</h2>
-            {children}
-        </section>
-    );
-}

adminsite/app/(staff)/staff/audit/page.tsx

@@ -4,18 +4,16 @@ import { useQuery } from "@tanstack/react-query";
 import { useState } from "react";
 import { api } from "@/lib/api";
 import { formatDate, formatStamp } from "@/lib/format";
-import { Field } from "@/components/Field";
 import { PageHeader } from "@/components/PageHeader";
+import { controlClass } from "@/components/Button";
+import { EmptyState, Panel } from "@/components/Panel";
+import { Sub, TBody, TD, TH, THead, TR, Table } from "@/components/Table";
 
 export default function AuditPage() {
     const [filter, setFilter] = useState("");
     const { data } = useQuery({ queryKey: ["staff-audit"], queryFn: () => api.staff.audit() });
 
-    const rows = (data ?? []).filter((e) =>
-        filter
-            ? `${e.action} ${e.actor} ${e.target ?? ""}`.toLowerCase().includes(filter.toLowerCase())
-            : true,
-    );
+    const rows = (data ?? []).filter((e) => (filter ? `${e.action} ${e.actor} ${e.target ?? ""}`.toLowerCase().includes(filter.toLowerCase()) : true));
 
     return (
         <div className="grid gap-6">
@@ -24,30 +22,59 @@ export default function AuditPage() {
                 subtitle="Every mutating action across every account, newest first."
                 record={[{ key: "Showing", value: `${rows.length} of ${(data ?? []).length}` }]}
             />
-            <Field
-                label="Filter"
-                value={filter}
-                onChange={(e) => setFilter(e.target.value)}
-                hint="Action, actor or target."
-            />
-            <ul className="grid gap-2 rounded border border-rule bg-panel p-5 font-mono text-[0.82rem]">
-                {rows.map((e, n) => (
-                    <li
-                        key={n}
-                        className="grid gap-1 border-b border-rule-soft pb-2 last:border-0 sm:grid-cols-[11rem_1fr]"
-                    >
-                        <span className="tabular-nums text-ink-3">
-                            {formatDate(e.created_at)} {formatStamp(e.created_at)}
-                        </span>
-                        <span className="text-ink-2">
-                            <b className="text-ink">{e.action}</b> · {e.actor}
-                            {e.target && ` · ${e.target}`}
-                            {e.detail && ` · ${e.detail}`}
-                        </span>
-                    </li>
-                ))}
-                {rows.length === 0 && <li className="text-ink-3">Nothing matches that.</li>}
-            </ul>
+
+            <Panel>
+                <label className="grid gap-1.5">
+                    <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">Filter</span>
+                    <input
+                        type="search"
+                        value={filter}
+                        onChange={(e) => setFilter(e.target.value)}
+                        placeholder="Action, actor or target"
+                        className={controlClass()}
+                    />
+                </label>
+            </Panel>
+
+            {/*
+             * A table, not a list of mono sentences joined by middots. Every row
+             * held five separate facts run together into one string, so nothing
+             * could be scanned down a column — which is the only way anyone
+             * reads an audit log looking for "who did this".
+             */}
+            <Panel bodyless>
+                <Table>
+                    <THead>
+                        <TR className="hover:bg-transparent">
+                            <TH>Time</TH>
+                            <TH>Actor</TH>
+                            <TH>Action</TH>
+                            <TH>Target</TH>
+                            <TH>Detail</TH>
+                        </TR>
+                    </THead>
+                    <TBody>
+                        {rows.map((e, n) => (
+                            <TR key={n}>
+                                <TD className="whitespace-nowrap font-mono text-[0.78rem] tabular-nums text-ink-2">
+                                    {formatStamp(e.created_at)}
+                                    <Sub>{formatDate(e.created_at)}</Sub>
+                                </TD>
+                                <TD className="text-ink-2">{e.actor}</TD>
+                                <TD className="font-mono text-[0.8rem]">{e.action}</TD>
+                                <TD className="text-ink-2">{e.target ?? "—"}</TD>
+                                <TD className="text-[0.82rem] text-ink-3">{e.detail ?? "—"}</TD>
+                            </TR>
+                        ))}
+                    </TBody>
+                </Table>
+                {rows.length === 0 && (
+                    <EmptyState
+                        title={filter ? "Nothing matches that." : "No actions recorded yet."}
+                        body={filter ? "Clear the filter to see the whole log." : "Every licence issued, relinked or reaped is written here as it happens."}
+                    />
+                )}
+            </Panel>
         </div>
     );
 }

adminsite/app/(staff)/staff/catalogue/page.tsx

@@ -4,6 +4,8 @@ import { useState } from "react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { PageHeader } from "@/components/PageHeader";
 import { PageFrame } from "@/components/PageFrame";
+import { Panel } from "@/components/Panel";
+import { TBody, TD, TH, THead, TR, Table } from "@/components/Table";
 import { api, type CatalogueRow, type Term } from "@/lib/api";
 
 const ENVS = ["sandbox", "production"] as const;
@@ -69,35 +71,27 @@ export default function CataloguePage() {
                 {isLoading ? (
                     <p className="text-[0.85rem] text-ink-3">Loading…</p>
                 ) : (
-                    <div className="space-y-6">
+                    <div className="grid gap-4">
                         {groups.map((g) => {
                             const [deployment, tier] = g.split("/");
                             const terms = termsFor(deployment);
                             return (
-                                <section key={g} className="space-y-2">
-                                    <h2 className="text-[0.95rem] font-medium text-ink">
-                                        {deployment === "cloud" ? "Cloud" : "Self-Hosted"}{" "}
-                                        {tier}
-                                    </h2>
-                                    <div className="overflow-x-auto">
-                                        <table className="w-full min-w-[42rem] border-collapse text-[0.82rem]">
-                                            <thead>
-                                                <tr className="border-b border-rule text-left text-ink-3">
-                                                    <th className="py-2 pr-3 font-normal">Component</th>
+                                <Panel key={g} title={`${deployment === "cloud" ? "Cloud" : "Self-Hosted"} ${tier}`} meta={terms.join(" · ")} bodyless>
+                                    <Table className="min-w-[42rem]">
+                                            <THead>
+                                                <TR className="hover:bg-transparent">
+                                                    <TH>Component</TH>
                                                     {ENVS.map((env) =>
                                                         terms.map((t) => (
-                                                            <th
-                                                                key={`${env}-${t}`}
-                                                                className="py-2 pr-3 font-normal"
-                                                            >
+                                                            <TH key={`${env}-${t}`}>
                                                                 {env} / {t}
-                                                            </th>
+                                                            </TH>
                                                         )),
                                                     )}
-                                                    <th className="py-2 font-normal" />
-                                                </tr>
-                                            </thead>
-                                            <tbody>
+                                                    <TH />
+                                                </TR>
+                                            </THead>
+                                            <TBody>
                                                 {rows
                                                     .filter(
                                                         (r) =>
@@ -111,19 +105,11 @@ export default function CataloguePage() {
                                                             JSON.stringify(ids) !==
                                                             JSON.stringify(r.price_ids ?? {});
                                                         return (
-                                                            <tr
-                                                                key={k}
-                                                                className="border-b border-rule/60"
-                                                            >
-                                                                <td className="py-2 pr-3 text-ink">
-                                                                    {componentLabel(r)}
-                                                                </td>
+                                                            <TR key={k}>
+                                                                <TD className="text-ink">{componentLabel(r)}</TD>
                                                                 {ENVS.map((env) =>
                                                                     terms.map((t) => (
-                                                                        <td
-                                                                            key={`${env}-${t}`}
-                                                                            className="py-2 pr-3"
-                                                                        >
+                                                                        <TD key={`${env}-${t}`}>
                                                                             <input
                                                                                 value={
                                                                                     ids[env]?.[t] ?? ""
@@ -145,12 +131,12 @@ export default function CataloguePage() {
                                                                                         },
                                                                                     })
                                                                                 }
-                                                                                className="w-40 rounded border border-rule bg-panel px-2 py-1 font-mono text-[0.78rem] text-ink"
+                                                                                className="w-40 rounded border border-rule bg-panel-2 px-2 py-1 font-mono text-[0.78rem] text-ink focus:border-accent focus:outline-none"
                                                                             />
-                                                                        </td>
+                                                                        </TD>
                                                                     )),
                                                                 )}
-                                                                <td className="py-2">
+                                                                <TD numeric>
                                                                     <button
                                                                         type="button"
                                                                         disabled={
@@ -162,18 +148,17 @@ export default function CataloguePage() {
                                                                                 price_ids: ids,
                                                                             })
                                                                         }
-                                                                        className="rounded border border-accent/50 px-2.5 py-1 text-[0.78rem] text-accent disabled:opacity-40"
+                                                                        className="rounded border border-accent px-2.5 py-1 font-mono text-[0.7rem] uppercase tracking-[0.1em] text-accent disabled:opacity-40"
                                                                     >
                                                                         Save
                                                                     </button>
-                                                                </td>
-                                                            </tr>
+                                                                </TD>
+                                                            </TR>
                                                         );
                                                     })}
-                                            </tbody>
-                                        </table>
-                                    </div>
-                                </section>
+                                            </TBody>
+                                    </Table>
+                                </Panel>
                             );
                         })}
                     </div>

adminsite/app/(staff)/staff/instances/[id]/page.tsx

@@ -8,8 +8,12 @@ import clsx from "clsx";
 import { api, type Deployment, type InjectionState } from "@/lib/api";
 import { Ledger } from "@/components/Ledger";
 import { PageHeader } from "@/components/PageHeader";
+import { TermBar } from "@/components/TermBar";
+import { Panel } from "@/components/Panel";
+import { licenceState } from "@/lib/format";
 import PlanConfigurator, { type PlanChoice } from "@/components/PlanConfigurator";
 import { IssuePanel } from "./IssuePanel";
+import { RenamePanel } from "@/components/RenamePanel";
 
 const INJECTION: Record<InjectionState, { label: string; tone: string }> = {
     current: { label: "Control plane holds the current licence", tone: "text-valid" },
@@ -23,6 +27,7 @@ const INJECTION: Record<InjectionState, { label: string; tone: string }> = {
 
 export default function StaffInstancePage() {
     const id = String(useParams().id);
+    const qc = useQueryClient();
     const { data, isLoading } = useQuery({
         queryKey: ["staff-instance", id],
         queryFn: () => api.staff.instance(id),
@@ -32,6 +37,13 @@ export default function StaffInstancePage() {
     if (isLoading || !data) return <p className="text-ink-3">Loading…</p>;
 
     const inj = data.injection.state ? INJECTION[data.injection.state] : undefined;
+    const current = data.licenses.find((l) => !l.superseded_by);
+    // A cloud placeholder has no control-plane row yet, so there is no host to
+    // move and nothing to rename — the panel's wording and its control are both
+    // read from this one answer rather than from the deployment alone, which is
+    // how they came to contradict each other.
+    const movesHost = data.instance.deployment === "cloud" && !data.instance.placeholder;
+    const cloudPlaceholder = data.instance.deployment === "cloud" && data.instance.placeholder;
 
     return (
         <div className="grid gap-8">
@@ -59,11 +71,53 @@ export default function StaffInstancePage() {
                 {data.injection.applicable && inj && <p className={clsx("font-mono text-[0.72rem]", inj.tone)}>{inj.label}</p>}
             </div>
 
-            <section className="grid gap-3 rounded border border-rule bg-panel p-5">
-                <h2 className="text-xl">Licence history</h2>
+            {/*
+             * The live licence is the one nothing has superseded, which is the
+             * record's own statement of the fact — not its position in the
+             * array, which is the server's ordering and not a guarantee.
+             */}
+            {current && (
+                <Panel title="Current licence" meta={current.license_id}>
+                    <TermBar issuedAt={current.issued_at} expiresAt={current.expires_at} state={licenceState(current.expires_at, true)} className="max-w-xl" />
+                </Panel>
+            )}
+
+            <Panel title="Licence history" meta="Append-only">
                 <Ledger licenses={data.licenses} />
                 <IssuePanel instanceId={data.instance.instance_id} />
-            </section>
+            </Panel>
+
+            {/*
+             * Staff rename has no cooldown and does not start the customer's:
+             * fixing a name on someone's behalf must not spend their next 24
+             * hours.
+             */}
+            <Panel title="Name" meta={movesHost ? "Moves the address" : "Label only"}>
+                {cloudPlaceholder ? (
+                    // The API refuses this with a 409, so offering the control
+                    // would only be a form that cannot succeed.
+                    <p className="text-[0.85rem] text-ink-3">
+                        This instance is not provisioned yet. Its name is set when the checkout provisions it, and it can be renamed after that.
+                    </p>
+                ) : (
+                    /*
+                     * Keyed on the instance so a success note cannot follow staff
+                     * from one instance page to the next — the element stays
+                     * mounted across that navigation.
+                     */
+                    <RenamePanel
+                        key={data.instance.instance_id}
+                        movesHost={movesHost}
+                        currentName={data.instance.name}
+                        currentSlug={data.instance.slug ?? ""}
+                        onRename={async (name) => {
+                            const res = await api.staff.renameInstance(data.instance.instance_id, name);
+                            qc.invalidateQueries({ queryKey: ["staff-instance", id] });
+                            return res;
+                        }}
+                    />
+                )}
+            </Panel>
 
             <EntitlementSection instanceId={data.instance.instance_id} deployment={data.instance.deployment} />
         </div>

adminsite/app/(staff)/staff/licenses/page.tsx

@@ -4,8 +4,14 @@ import { useQuery } from "@tanstack/react-query";
 import Link from "next/link";
 import { useState } from "react";
 import { api, type Tier } from "@/lib/api";
-import { formatDate } from "@/lib/format";
+import { formatDate, licenceState } from "@/lib/format";
 import { PageHeader } from "@/components/PageHeader";
+import { controlClass } from "@/components/Button";
+import { EmptyState, Panel } from "@/components/Panel";
+import { Sub, TBody, TD, TH, THead, TR, Table } from "@/components/Table";
+import { TermSpark } from "@/components/TermBar";
+
+const SELECT = controlClass("w-auto");
 
 export default function LicensesPage() {
     const [tier, setTier] = useState<"" | Tier>("");
@@ -14,9 +20,8 @@ export default function LicensesPage() {
 
     // Filtered here rather than server-side: the endpoint caps at 500 rows and
     // staff are narrowing a list they can already see.
-    const rows = (data ?? []).filter(
-        (l) => (!tier || l.tier === tier) && (!reason || l.reason === reason),
-    );
+    const rows = (data ?? []).filter((l) => (!tier || l.tier === tier) && (!reason || l.reason === reason));
+    const filtered = Boolean(tier || reason);
 
     return (
         <div className="grid gap-6">
@@ -25,78 +30,93 @@ export default function LicensesPage() {
                 subtitle="Append-only. A renewal writes a new row and supersedes the old one."
                 record={[{ key: "Showing", value: `${rows.length} of ${(data ?? []).length}` }]}
             />
-            <div className="flex flex-wrap gap-3">
-                <select
-                    value={tier}
-                    onChange={(e) => setTier(e.target.value as Tier | "")}
-                    className="rounded border border-rule bg-panel-2 px-2.5 py-2"
-                    aria-label="Filter by tier"
-                >
-                    <option value="">All tiers</option>
-                    <option value="free">Free</option>
-                    <option value="professional">Professional</option>
-                    <option value="enterprise">Enterprise</option>
-                    <option value="self_hosted">Self-Hosted (legacy)</option>
-                </select>
-                <select
-                    value={reason}
-                    onChange={(e) => setReason(e.target.value)}
-                    className="rounded border border-rule bg-panel-2 px-2.5 py-2"
-                    aria-label="Filter by reason"
-                >
-                    <option value="">All reasons</option>
-                    <option value="new">New</option>
-                    <option value="renewal">Renewal</option>
-                    <option value="tier_change">Tier change</option>
-                    <option value="relink">Relink</option>
-                    <option value="manual">Manual</option>
-                </select>
-            </div>
-            <div className="overflow-x-auto rounded border border-rule bg-panel">
-                <table className="w-full border-collapse text-left">
-                    <thead>
-                        <tr className="border-b border-rule bg-panel-2 font-mono text-[0.72rem] uppercase tracking-[0.08em] text-ink-3">
-                            <th className="px-4 py-2.5">Issued</th>
-                            <th className="px-4 py-2.5">Instance</th>
-                            <th className="px-4 py-2.5">Tier</th>
-                            <th className="px-4 py-2.5">Reason</th>
-                            <th className="px-4 py-2.5">Expires</th>
-                            <th className="px-4 py-2.5">State</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        {rows.map((l) => (
-                            <tr
-                                key={l.license_id}
-                                className="border-b border-rule-soft last:border-0"
-                            >
-                                <td className="px-4 py-3 font-mono tabular-nums">
-                                    {formatDate(l.issued_at)}
-                                </td>
-                                <td className="px-4 py-3">
-                                    <Link
-                                        href={`/staff/instances/${l.instance_id}`}
-                                        className="font-mono text-[0.82rem] text-accent underline"
-                                    >
-                                        {l.instance_id.slice(0, 8)}
-                                    </Link>
-                                </td>
-                                <td className="px-4 py-3">{l.tier.replace("_", " ")}</td>
-                                <td className="px-4 py-3">{l.reason.replace("_", " ")}</td>
-                                <td className="px-4 py-3 font-mono tabular-nums">
-                                    {formatDate(l.expires_at)}
-                                </td>
-                                <td className="px-4 py-3 text-ink-3">
-                                    {l.superseded_by ? "superseded" : "current"}
-                                </td>
-                            </tr>
-                        ))}
-                    </tbody>
-                </table>
+
+            <Panel>
+                <div className="flex flex-wrap gap-3">
+                    <label className="grid gap-1.5">
+                        <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">Tier</span>
+                        <select value={tier} onChange={(e) => setTier(e.target.value as Tier | "")} className={SELECT} aria-label="Filter by tier">
+                            <option value="">All tiers</option>
+                            <option value="free">Free</option>
+                            <option value="professional">Professional</option>
+                            <option value="enterprise">Enterprise</option>
+                            <option value="self_hosted">Self-Hosted (legacy)</option>
+                        </select>
+                    </label>
+                    <label className="grid gap-1.5">
+                        <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">Reason</span>
+                        <select value={reason} onChange={(e) => setReason(e.target.value)} className={SELECT} aria-label="Filter by reason">
+                            <option value="">All reasons</option>
+                            <option value="new">New</option>
+                            <option value="renewal">Renewal</option>
+                            <option value="tier_change">Tier change</option>
+                            <option value="relink">Relink</option>
+                            <option value="manual">Manual</option>
+                        </select>
+                    </label>
+                </div>
+            </Panel>
+
+            <Panel bodyless>
+                <Table>
+                    <THead>
+                        <TR className="hover:bg-transparent">
+                            <TH>Issued</TH>
+                            <TH>Instance</TH>
+                            <TH>Tier</TH>
+                            <TH>Reason</TH>
+                            <TH>Term</TH>
+                            <TH>Expires</TH>
+                            <TH>State</TH>
+                        </TR>
+                    </THead>
+                    <TBody>
+                        {rows.map((l) => {
+                            const dead = Boolean(l.superseded_by);
+                            return (
+                                // A superseded row is overprinted rather than hidden:
+                                // it is the only record of why an instance stopped
+                                // working on a given date.
+                                <TR key={l.license_id} className={dead ? "text-ink-3" : undefined}>
+                                    <TD className="whitespace-nowrap font-mono tabular-nums">{formatDate(l.issued_at)}</TD>
+                                    <TD>
+                                        <Link href={`/staff/instances/${l.instance_id}`} className="font-mono text-[0.82rem] text-accent no-underline hover:underline">
+                                            {l.instance_id.slice(0, 8)}
+                                        </Link>
+                                        <Sub>
+                                            <span className="font-mono">{l.license_id.slice(0, 8)}</span>
+                                        </Sub>
+                                    </TD>
+                                    <TD>{l.tier.replace("_", " ")}</TD>
+                                    <TD className="text-ink-2">{l.reason.replace("_", " ")}</TD>
+                                    {/* A superseded row's term is not a countdown to
+                                        anything — it ended when its successor was
+                                        issued, so drawing a bar would invite a
+                                        comparison that means nothing. */}
+                                    <TD>
+                                        {dead ? (
+                                            <span className="font-mono text-[0.72rem] text-ink-3">—</span>
+                                        ) : (
+                                            <TermSpark issuedAt={l.issued_at} expiresAt={l.expires_at} state={licenceState(l.expires_at, true)} />
+                                        )}
+                                    </TD>
+                                    <TD className="whitespace-nowrap font-mono tabular-nums">{formatDate(l.expires_at)}</TD>
+                                    <TD>
+                                        <span className="font-mono text-[0.7rem] uppercase tracking-[0.1em] text-ink-3">{dead ? "superseded" : "current"}</span>
+                                    </TD>
+                                </TR>
+                            );
+                        })}
+                    </TBody>
+                </Table>
+
                 {rows.length === 0 && (
-                    <p className="px-4 py-6 text-ink-3">No licences match those filters.</p>
+                    <EmptyState
+                        title={filtered ? "No licences match those filters." : "No licences issued yet."}
+                        body={filtered ? "Clear a filter to widen the search." : "Every issue, renewal and relink writes a row here."}
+                    />
                 )}
-            </div>
+            </Panel>
         </div>
     );
 }

adminsite/app/(staff)/staff/page.tsx

@@ -7,6 +7,8 @@ import { NotConnectedPanel } from "@/components/NotConnected";
 import { Queue } from "@/components/Queue";
 import { PageFrame, RailCard, RailFacts } from "@/components/PageFrame";
 import { PageHeader } from "@/components/PageHeader";
+import { EmptyState, Panel } from "@/components/Panel";
+import { TBody, TD, TH, THead, TR, Table } from "@/components/Table";
 import { StatePill } from "@/components/StatePill";
 import { LinkButton } from "@/components/Button";
 import { daysRemaining, formatStamp } from "@/lib/format";
@@ -123,46 +125,37 @@ export default function StaffDashboard() {
                     </RailCard>
                 }
             >
-                <section className="overflow-hidden rounded border border-rule bg-panel">
-                    <header className="flex flex-wrap items-center justify-between gap-3 border-b border-rule-soft bg-panel-2 px-4 py-3">
-                        <div>
-                            <h2 className="text-[0.95rem]">Recent activity</h2>
-                            <p className="text-[0.8rem] text-ink-2">Every licence issued, relinked or reaped, newest first.</p>
-                        </div>
-                        <Link href="/staff/audit" className="text-[0.82rem] font-semibold text-accent underline">
-                            Full audit
+                <Panel
+                    title="Recent activity"
+                    actions={
+                        <Link href="/staff/audit" className="font-mono text-[0.7rem] uppercase tracking-[0.1em] text-accent no-underline hover:underline">
+                            Full audit &rarr;
                         </Link>
-                    </header>
-                    <div className="overflow-x-auto">
-                        <table className="w-full border-collapse text-left text-[0.86rem]">
-                            <thead>
-                                <tr className="border-b border-rule-soft font-mono text-[0.64rem] uppercase tracking-[0.11em] text-ink-3">
-                                    <th className="px-4 py-2 font-normal">Time</th>
-                                    <th className="px-4 py-2 font-normal">Action</th>
-                                    <th className="px-4 py-2 font-normal">Target</th>
-                                    <th className="px-4 py-2 font-normal">Actor</th>
-                                </tr>
-                            </thead>
-                            <tbody>
-                                {(audit.data ?? []).slice(0, 12).map((e, n) => (
-                                    <tr key={n} className="border-b border-rule-soft last:border-0">
-                                        <td className="px-4 py-2.5 font-mono tabular-nums text-ink-2">{new Date(e.created_at).toISOString().slice(11, 16)}</td>
-                                        <td className="px-4 py-2.5">{e.action}</td>
-                                        <td className="px-4 py-2.5 text-ink-2">{e.target ?? "—"}</td>
-                                        <td className="px-4 py-2.5 text-ink-3">{e.actor}</td>
-                                    </tr>
-                                ))}
-                                {audit.data?.length === 0 && (
-                                    <tr>
-                                        <td colSpan={4} className="px-4 py-6 text-ink-3">
-                                            Nothing yet today.
-                                        </td>
-                                    </tr>
-                                )}
-                            </tbody>
-                        </table>
-                    </div>
-                </section>
+                    }
+                    bodyless
+                >
+                    <Table>
+                        <THead>
+                            <TR className="hover:bg-transparent">
+                                <TH>Time</TH>
+                                <TH>Actor</TH>
+                                <TH>Action</TH>
+                                <TH>Target</TH>
+                            </TR>
+                        </THead>
+                        <TBody>
+                            {(audit.data ?? []).slice(0, 12).map((e, n) => (
+                                <TR key={n}>
+                                    <TD className="whitespace-nowrap font-mono tabular-nums text-ink-2">{new Date(e.created_at).toISOString().slice(11, 16)}</TD>
+                                    <TD className="text-ink-2">{e.actor}</TD>
+                                    <TD className="font-mono text-[0.8rem]">{e.action}</TD>
+                                    <TD className="text-ink-2">{e.target ?? "—"}</TD>
+                                </TR>
+                            ))}
+                        </TBody>
+                    </Table>
+                    {audit.data?.length === 0 && <EmptyState title="Nothing yet today." body="Every licence issued, relinked or reaped appears here as it happens." />}
+                </Panel>
             </PageFrame>
         </div>
     );

adminsite/app/(staff)/staff/plans/page.tsx

@@ -5,6 +5,7 @@ import { useState } from "react";
 import { api, type Deployment, type Plan, type Tier } from "@/lib/api";
 import { ConfirmPlanChange } from "@/components/ConfirmPlanChange";
 import { PageHeader } from "@/components/PageHeader";
+import { Panel } from "@/components/Panel";
 
 const SUPPORT_LEVELS = [
     { value: "community", label: "Community" },
@@ -31,7 +32,7 @@ function AllowanceForm({ plan, onSave, saving }: { plan: Plan; onSave: (next: Pl
     const dirty = JSON.stringify(draft) !== JSON.stringify(plan);
 
     return (
-        <div className="space-y-3">
+        <div className="grid gap-3">
             <div className="grid gap-2 sm:grid-cols-2 lg:grid-cols-3">
                 {LIMIT_FIELDS.map((f) => (
                     <label key={f.key} className="block">
@@ -48,7 +49,7 @@ function AllowanceForm({ plan, onSave, saving }: { plan: Plan; onSave: (next: Pl
                                     },
                                 })
                             }
-                            className="w-full rounded border border-rule bg-panel px-2 py-1.5 text-[0.85rem] text-ink"
+                            className="w-full rounded border border-rule bg-panel-2 px-2 py-1.5 text-[0.85rem] text-ink focus:border-accent focus:outline-none"
                         />
                         <span className="mt-0.5 block text-[0.72rem] text-ink-3">−1 is unlimited</span>
                     </label>
@@ -58,7 +59,7 @@ function AllowanceForm({ plan, onSave, saving }: { plan: Plan; onSave: (next: Pl
                     <select
                         value={draft.support_level}
                         onChange={(e) => setDraft({ ...draft, support_level: e.target.value })}
-                        className="w-full rounded border border-rule bg-panel px-2 py-1.5 text-[0.85rem] text-ink"
+                        className="w-full rounded border border-rule bg-panel-2 px-2 py-1.5 text-[0.85rem] text-ink focus:border-accent focus:outline-none"
                     >
                         {SUPPORT_LEVELS.map((s) => (
                             <option key={s.value} value={s.value}>
@@ -76,7 +77,12 @@ function AllowanceForm({ plan, onSave, saving }: { plan: Plan; onSave: (next: Pl
 
             <p className="text-[0.78rem] text-ink-3">Changes apply to licences issued from now on. Existing licences snapshotted their plan and are unaffected.</p>
 
-            <button type="button" disabled={!dirty || saving} onClick={() => onSave(draft)} className="rounded border border-accent/50 px-3 py-1.5 text-[0.85rem] text-accent disabled:opacity-40">
+            <button
+                type="button"
+                disabled={!dirty || saving}
+                onClick={() => onSave(draft)}
+                className="justify-self-start rounded border border-accent bg-accent px-3.5 py-2 text-[0.86rem] font-semibold text-accent-ink disabled:opacity-40"
+            >
                 {saving ? "Saving…" : "Save allowances"}
             </button>
         </div>
@@ -126,20 +132,19 @@ export default function PlansPage() {
             )}
 
             {(["cloud", "self_hosted"] as const).map((deployment: Deployment) => (
-                <section key={deployment} className="space-y-3">
-                    <h2 className="text-[0.95rem] font-medium text-ink">{deployment === "cloud" ? "Cloud" : "Self-Hosted"}</h2>
+                <section key={deployment} className="grid gap-3">
+                    <h2 className="font-mono text-[0.68rem] uppercase tracking-[0.14em] text-ink-3">{deployment === "cloud" ? "Cloud" : "Self-Hosted"}</h2>
                     {(plans.data ?? [])
                         .filter((p) => p.deployment === deployment)
                         .map((p) => (
-                            <article key={`${p.deployment}/${p.tier}`} className="rounded-lg border border-rule bg-panel p-4">
-                                <header className="mb-3 flex items-baseline justify-between gap-3">
-                                    <h3 className="text-[0.9rem] font-medium text-ink">{p.name}</h3>
-                                    <span className="font-mono text-[0.75rem] text-ink-3">
-                                        {p.deployment}/{p.tier}
-                                    </span>
-                                </header>
+                            <Panel
+                                key={`${p.deployment}/${p.tier}`}
+                                title={p.name}
+                                meta={`${p.deployment}/${p.tier}`}
+                                actions={!p.active ? <span className="font-mono text-[0.64rem] uppercase tracking-[0.12em] text-warn">Not offered</span> : undefined}
+                            >
                                 <AllowanceForm plan={p} saving={saving === `${p.deployment}/${p.tier}`} onSave={(next: Plan) => setDraft(next)} />
-                            </article>
+                            </Panel>
                         ))}
                 </section>
             ))}

adminsite/app/accept-invite/page.tsx

@@ -1,12 +1,12 @@
 "use client";
 
 import { useMutation } from "@tanstack/react-query";
-import Link from "next/link";
 import { useSearchParams } from "next/navigation";
 import { Suspense, useState } from "react";
 import { ApiError, api } from "@/lib/api";
 import { Button } from "@/components/Button";
 import { Field } from "@/components/Field";
+import { AuthMessage, AuthShell } from "@/components/AuthShell";
 
 function AcceptForm() {
     const token = useSearchParams().get("token") ?? "";
@@ -17,60 +17,65 @@ function AcceptForm() {
     const accept = useMutation({
         mutationFn: () => api.acceptInvite(token, password),
         onSuccess: () => setDone(true),
-        onError: (e) =>
-            setError(e instanceof ApiError ? e.message : "Something went wrong. Try again."),
+        onError: (e) => setError(e instanceof ApiError ? e.message : "Something went wrong. Try again."),
     });
 
-    if (!token) return <p className="text-ink-2">That link is missing its token.</p>;
+    if (!token)
+        return (
+            <AuthMessage
+                title="That link is incomplete"
+                body="It is missing its token. Use the link in the invitation exactly as sent — some mail clients cut long links in half."
+                action={{ href: "/login", label: "Go to sign in" }}
+            />
+        );
+
     if (done)
         return (
-            <div className="grid gap-3">
-                <h1 className="text-3xl">You&apos;re in</h1>
-                <p className="text-ink-2">Sign in with your email address and new password.</p>
-                <Link href="/login" className="font-semibold text-accent underline">
-                    Sign in
-                </Link>
-            </div>
+            <AuthMessage
+                title="You're in"
+                body="Sign in with your email address and the password you just set."
+                action={{ href: "/login", label: "Sign in" }}
+            />
         );
 
     return (
-        <form
-            className="grid max-w-md gap-4"
-            onSubmit={(e) => {
-                e.preventDefault();
-                setError(null);
-                accept.mutate();
-            }}
+        <AuthShell
+            title="Choose a password"
+            lede="You have been invited to a Vantage HQ account."
+            footnote="Nobody who invited you can see this password, and it is never sent to them."
         >
-            <h1 className="text-3xl">Choose a password</h1>
-            <p className="text-ink-2">
-                This password signs you into Vantage HQ and into every instance you are given
-                access to. Nobody who invited you can see it.
-            </p>
-            <Field
-                label="New password"
-                type="password"
-                autoComplete="new-password"
-                value={password}
-                onChange={(e) => setPassword(e.target.value)}
-                required
-                minLength={12}
-                hint="At least 12 characters."
-                error={error ?? undefined}
-            />
-            <Button type="submit" disabled={accept.isPending || password.length < 12}>
-                {accept.isPending ? "Setting…" : "Set password"}
-            </Button>
-        </form>
+            <form
+                className="grid gap-4"
+                onSubmit={(e) => {
+                    e.preventDefault();
+                    setError(null);
+                    accept.mutate();
+                }}
+            >
+                <p className="text-[0.86rem] text-ink-2">This password signs you into Vantage HQ and into every instance you are given access to.</p>
+                <Field
+                    label="New password"
+                    type="password"
+                    autoComplete="new-password"
+                    value={password}
+                    onChange={(e) => setPassword(e.target.value)}
+                    required
+                    minLength={12}
+                    hint="At least 12 characters."
+                    error={error ?? undefined}
+                />
+                <Button type="submit" disabled={accept.isPending || password.length < 12} className="w-full justify-center">
+                    {accept.isPending ? "Setting…" : "Set password and continue"}
+                </Button>
+            </form>
+        </AuthShell>
     );
 }
 
 export default function AcceptInvitePage() {
     return (
-        <main className="mx-auto max-w-rail px-5 py-16">
-            <Suspense fallback={<p className="text-ink-3">Loading…</p>}>
-                <AcceptForm />
-            </Suspense>
-        </main>
+        <Suspense fallback={<AuthShell title="Choose a password" lede="One moment." />}>
+            <AcceptForm />
+        </Suspense>
     );
 }

adminsite/app/login/page.tsx

@@ -6,6 +6,7 @@ import { API_BASE, ApiError, NotConnected, api } from "@/lib/api";
 import { NotConnectedPanel } from "@/components/NotConnected";
 import { Button } from "@/components/Button";
 import { Field } from "@/components/Field";
+import { AuthShell } from "@/components/AuthShell";
 
 const SITE_URL = (process.env.NEXT_PUBLIC_SITE_URL ?? "").replace(/\/$/, "");
 
@@ -38,82 +39,56 @@ export default function LoginPage() {
 
     if (offline)
         return (
-            <Main>
+            <AuthShell title="Sign in">
                 <NotConnectedPanel url={API_BASE} />
-            </Main>
+            </AuthShell>
         );
 
     return (
-        <Main>
-            {/* The masthead's lockup, unlinked: there is nowhere to go yet. */}
-            <div className="mb-7 flex flex-col items-center gap-2 text-center">
-                <span className="flex items-baseline gap-2 text-[1.5rem] font-extrabold tracking-[-0.02em]">
-                    Vantage
-                    <span className="font-mono text-[0.78rem] font-normal uppercase tracking-[0.14em] text-ink-3">
-                        HQ
-                    </span>
-                </span>
-                <h1 className="text-[1.16rem]">Sign in</h1>
-                <p className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
-                    Licences · instances · billing
-                </p>
-            </div>
+        <AuthShell
+            title="Sign in"
+            lede="Licences, instances and billing for your account."
+            /*
+             * HQ and the Vantage console are separate sign-ins on separate
+             * hosts, and the two get confused — someone lands here with their
+             * console password and reads the generic failure as a broken
+             * account. Saying which door this is costs one line.
+             */
+            footnote="This is the portal for your licence and billing. Your servers are managed inside your Vantage instance, which signs in separately."
+        >
+            <form onSubmit={submit} className="grid gap-4">
+                <Field label="Email" type="email" autoComplete="username" required value={email} onChange={(e) => setEmail(e.target.value)} />
+                <Field
+                    label="Password"
+                    type="password"
+                    autoComplete="current-password"
+                    required
+                    value={password}
+                    onChange={(e) => setPassword(e.target.value)}
+                    error={error ?? undefined}
+                />
+                <label className="flex items-center gap-2 text-[0.82rem] text-ink-2">
+                    <input type="checkbox" checked={staff} onChange={(e) => setStaff(e.target.checked)} className="accent-[var(--accent)]" />
+                    I work at Vantage
+                </label>
+                <Button type="submit" disabled={busy} className="w-full justify-center">
+                    {busy ? "Signing in…" : "Sign in"}
+                </Button>
+            </form>
 
-            <div className="rounded border border-rule bg-panel p-6 shadow-[var(--shadow)]">
-                <form onSubmit={submit} className="grid gap-4">
-                    <Field
-                        label="Email"
-                        type="email"
-                        autoComplete="username"
-                        required
-                        value={email}
-                        onChange={(e) => setEmail(e.target.value)}
-                    />
-                    <Field
-                        label="Password"
-                        type="password"
-                        autoComplete="current-password"
-                        required
-                        value={password}
-                        onChange={(e) => setPassword(e.target.value)}
-                        error={error ?? undefined}
-                    />
-                    <label className="flex items-center gap-2 text-[0.82rem] text-ink-2">
-                        <input
-                            type="checkbox"
-                            checked={staff}
-                            onChange={(e) => setStaff(e.target.checked)}
-                            className="accent-[var(--accent)]"
-                        />
-                        I work at Vantage
-                    </label>
-                    <Button type="submit" disabled={busy} className="w-full justify-center">
-                        {busy ? "Signing in…" : "Sign in"}
-                    </Button>
-                </form>
+            {SITE_URL && (
+                <>
+                    <div className="h-px bg-rule-soft" />
 
-                {SITE_URL && (
-                    <>
-                        <div className="my-5 h-px bg-rule-soft" />
-
-                        {/* Signup lives on the marketing site's /start, not here. */}
-                        <p className="text-center text-[0.82rem] text-ink-3">
-                            No account?{" "}
-                            <a href={`${SITE_URL}/start`} className="text-accent underline">
-                                Create one
-                            </a>
-                        </p>
-                    </>
-                )}
-            </div>
-        </Main>
-    );
-}
-
-function Main({ children }: { children: React.ReactNode }) {
-    return (
-        <main className="mx-auto flex min-h-screen w-full max-w-[26rem] flex-col justify-center px-5 py-12">
-            {children}
-        </main>
+                    {/* Signup lives on the marketing site's /start, not here. */}
+                    <p className="text-center text-[0.82rem] text-ink-3">
+                        No account?{" "}
+                        <a href={`${SITE_URL}/start`} className="text-accent underline">
+                            Create one
+                        </a>
+                    </p>
+                </>
+            )}
+        </AuthShell>
     );
 }

adminsite/app/verify/page.tsx

@@ -2,9 +2,11 @@
 
 import { useQuery } from "@tanstack/react-query";
 import { useRouter, useSearchParams } from "next/navigation";
-import Link from "next/link";
 import { Suspense, useEffect } from "react";
 import { api } from "@/lib/api";
+import { AuthMessage, AuthShell } from "@/components/AuthShell";
+
+const SITE_URL = (process.env.NEXT_PUBLIC_SITE_URL ?? "").replace(/\/$/, "");
 
 function Verify() {
     const router = useRouter();
@@ -25,50 +27,59 @@ function Verify() {
             router.replace(`/accept-invite?token=${encodeURIComponent(token)}`);
         }
     }, [needsPassword, token, router]);
-    if (needsPassword) return <Message title="One moment…" body="Taking you to set a password." />;
+    if (needsPassword) return <AuthShell title="One moment…" lede="Taking you to set a password." />;
 
     if (!token)
         return (
-            <Message
+            <AuthMessage
                 title="That link is incomplete"
-                body="It is missing its token. Use the link in the email exactly as sent."
+                body="It is missing its token. Use the link in the email exactly as sent — some mail clients cut long links in half."
+                action={{ href: "/login", label: "Go to sign in" }}
             />
         );
-    if (isLoading) return <Message title="Verifying…" body="One moment." />;
+
+    if (isLoading) return <AuthShell title="Verifying…" lede="One moment." />;
+
     if (error || !data?.verified)
         return (
-            <Message
+            <AuthMessage
                 title="That link is invalid or has expired"
-                body="Links last 24 hours and can only be used once. Sign up again to get a fresh one."
+                body="Links last 24 hours and can only be used once. Signing in will send you a fresh one."
+                action={{ href: "/login", label: "Go to sign in" }}
             />
         );
 
     return (
-        <div className="grid max-w-xl gap-3">
-            <h1 className="text-3xl">Email verified</h1>
-            <p className="text-ink-2">Your account is ready.</p>
-            <Link href="/login" className="justify-self-start text-accent underline">
+        <AuthShell
+            title="Email verified"
+            lede="Your account is ready."
+            footnote={
+                SITE_URL ? (
+                    <>
+                        New to Vantage? The{" "}
+                        <a href={`${SITE_URL}/docs`} className="text-accent underline">
+                            getting started guide
+                        </a>{" "}
+                        walks through your first instance.
+                    </>
+                ) : undefined
+            }
+        >
+            <p className="text-[0.9rem] text-ink-2">Sign in to create your first instance. The Free tier covers 5 servers and needs no card.</p>
+            <a
+                href="/login"
+                className="inline-flex items-center justify-center gap-2 rounded border border-accent bg-accent px-3.5 py-2 text-[0.86rem] font-semibold text-accent-ink no-underline"
+            >
                 Sign in
-            </Link>
-        </div>
-    );
-}
-
-function Message({ title, body }: { title: string; body: string }) {
-    return (
-        <div className="grid max-w-xl gap-3">
-            <h1 className="text-3xl">{title}</h1>
-            <p className="text-ink-2">{body}</p>
-        </div>
+            </a>
+        </AuthShell>
     );
 }
 
 export default function VerifyPage() {
     return (
-        <main className="mx-auto max-w-rail px-5 py-12">
-            <Suspense fallback={null}>
-                <Verify />
-            </Suspense>
-        </main>
+        <Suspense fallback={<AuthShell title="Verifying…" lede="One moment." />}>
+            <Verify />
+        </Suspense>
     );
 }

adminsite/components/AuthShell.tsx

@@ -0,0 +1,67 @@
+import Link from "next/link";
+
+/*
+ * The frame for every screen you can reach without a session: sign in, email
+ * verification, and accepting an invitation.
+ *
+ * These three had drifted into three different layouts. Sign in was a centred
+ * 26rem card with the lockup above it; verify and accept-invite were bare
+ * left-aligned text on the full 1200px rail, with no masthead, no panel and no
+ * brand anywhere on the page. Those two are the first screens a new customer
+ * ever sees — arriving from an email, on a domain they have not visited before
+ * — and they were the two that did not say whose product this is.
+ *
+ * There is no AppBar here on purpose: it carries navigation and an account
+ * menu, and none of it works without a session.
+ */
+export function AuthShell({
+    title,
+    lede,
+    children,
+    footnote,
+}: {
+    title: string;
+    lede?: React.ReactNode;
+    children?: React.ReactNode;
+    /** Sits outside the panel: orientation, not part of the task. */
+    footnote?: React.ReactNode;
+}) {
+    return (
+        <main className="mx-auto flex min-h-screen w-full max-w-[26rem] flex-col justify-center px-5 py-12">
+            {/* The masthead's lockup, unlinked: there is nowhere to go yet. */}
+            <div className="mb-7 flex flex-col items-center gap-2 text-center">
+                <span className="flex items-baseline gap-2 text-[1.5rem] font-extrabold tracking-[-0.02em]">
+                    Vantage
+                    <span className="font-mono text-[0.78rem] font-normal uppercase tracking-[0.14em] text-ink-3">HQ</span>
+                </span>
+                <h1 className="text-[1.16rem]">{title}</h1>
+                {lede && <p className="text-[0.86rem] text-ink-2">{lede}</p>}
+            </div>
+
+            {children && <div className="grid gap-4 rounded border border-rule bg-panel p-6 shadow-[var(--shadow)]">{children}</div>}
+
+            {footnote && <div className="mt-5 text-center text-[0.8rem] text-ink-3">{footnote}</div>}
+        </main>
+    );
+}
+
+/*
+ * A terminal state — verified, expired, already used, invalid. Always says what
+ * happened and what to do next: a dead end that only reports the failure leaves
+ * someone holding an email they cannot act on.
+ */
+export function AuthMessage({ title, body, action }: { title: string; body: React.ReactNode; action?: { href: string; label: string } }) {
+    return (
+        <AuthShell title={title}>
+            <p className="text-[0.9rem] text-ink-2">{body}</p>
+            {action && (
+                <Link
+                    href={action.href}
+                    className="inline-flex items-center justify-center gap-2 rounded border border-accent bg-accent px-3.5 py-2 text-[0.86rem] font-semibold text-accent-ink no-underline"
+                >
+                    {action.label}
+                </Link>
+            )}
+        </AuthShell>
+    );
+}

adminsite/components/Button.tsx

@@ -8,9 +8,34 @@ type Variant = "solid" | "line";
  * border on the secondary variant. site/ does not have an accent-outlined
  * button and this app should not invent one.
  */
+/*
+ * The height every form control resolves to, buttons included.
+ *
+ * Padding alone cannot align them: a select is mono at 0.84rem and a button is
+ * sans at 0.94rem, so identical padding still leaves them ~7px apart and a
+ * filter row looks assembled from two different kits. It is the height the
+ * button's own padding already computed to, so buttons do not move — everything
+ * else comes up to meet them.
+ */
+export const CONTROL_HEIGHT = "h-11";
+
+/*
+ * An input or select that sits on a form row with a button. Mono, because in
+ * this product the values typed into these are addresses, UUIDs and price IDs.
+ */
+export function controlClass(className?: string) {
+    return clsx(
+        CONTROL_HEIGHT,
+        "w-full rounded border border-rule bg-panel-2 px-2.5 font-mono text-[0.88rem] text-ink",
+        "focus:border-accent focus:outline-none",
+        className,
+    );
+}
+
 export function buttonClass(variant: Variant = "solid", disabled = false, className?: string) {
     return clsx(
-        "inline-flex items-center gap-2 rounded border px-4 py-2.5 text-[0.94rem] font-semibold",
+        "inline-flex items-center gap-2 rounded border px-4 text-[0.94rem] font-semibold",
+        CONTROL_HEIGHT,
         "transition-[filter,border-color] duration-150 hover:brightness-110",
         variant === "solid" ? "border-accent bg-accent text-accent-ink" : "border-rule bg-panel text-ink hover:border-ink-3",
         disabled && "cursor-not-allowed border-rule bg-panel text-ink-3 hover:brightness-100",

adminsite/components/Field.tsx

@@ -1,7 +1,10 @@
+import { controlClass } from "./Button";
+
 export function Field({
     label,
     hint,
     error,
+    className,
     ...input
 }: React.InputHTMLAttributes<HTMLInputElement> & {
     label: string;
@@ -10,18 +13,15 @@ export function Field({
 }) {
     return (
         <label className="grid max-w-md gap-1.5">
-            <span className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
-                {label}
-            </span>
-            <input
-                {...input}
-                className="rounded border border-rule bg-panel-2 px-2.5 py-2 font-mono text-ink"
-            />
-            {error ? (
-                <span className="text-[0.82rem] text-expired">{error}</span>
-            ) : hint ? (
-                <span className="text-[0.82rem] text-ink-3">{hint}</span>
-            ) : null}
+            <span className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">{label}</span>
+            {/*
+             * className is pulled out of the spread rather than left in it: it
+             * used to be spread onto the input and then overwritten by the
+             * hardcoded one below, so a caller passing className got nothing and
+             * no warning.
+             */}
+            <input {...input} className={controlClass(className)} aria-invalid={error ? true : undefined} />
+            {error ? <span className="text-[0.82rem] text-expired">{error}</span> : hint ? <span className="text-[0.82rem] text-ink-3">{hint}</span> : null}
         </label>
     );
 }

adminsite/components/InstanceRecord.tsx

@@ -7,6 +7,7 @@ import { useEffect, useState } from "react";
 import { api, type Instance, type License } from "@/lib/api";
 import { daysRemaining, formatDate, licenceState, limitLabel } from "@/lib/format";
 import { StatePill } from "./StatePill";
+import { TermBar } from "./TermBar";
 import { Button, LinkButton } from "./Button";
 
 const STRIPE = {
@@ -35,7 +36,6 @@ export function InstanceRecord({ instance, license, reapAfterDays, defaultOpen =
     const state = licenceState(license?.expires_at, Boolean(license));
     const days = license ? daysRemaining(license.expires_at) : 0;
     const cloud = instance.deployment === "cloud";
-    const termDays = instance.tier === "free" ? 30 : 365;
     const deleteInDays = license && reapAfterDays ? daysRemaining(license.expires_at) + reapAfterDays : null;
 
     const [open, setOpen] = useState(defaultOpen);
@@ -102,22 +102,10 @@ export function InstanceRecord({ instance, license, reapAfterDays, defaultOpen =
                 </div>
             </div>
 
-            {license && state !== "expired" && (
-                <div className="grid max-w-md gap-1.5">
-                    <div className="flex justify-between font-mono text-[0.78rem] tabular-nums text-ink-2">
-                        <span>{days} days remaining</span>
-                        <span>Renews {formatDate(license.expires_at)}</span>
-                    </div>
-                    <div className="h-1 overflow-hidden rounded-sm bg-rule-soft">
-                        <div
-                            className={clsx("h-full", state === "warn" ? "bg-warn" : "bg-valid")}
-                            style={{
-                                width: `${Math.max(2, Math.min(100, (days / termDays) * 100))}%`,
-                            }}
-                        />
-                    </div>
-                </div>
-            )}
+            {/* The term is drawn for an expired licence too. The old bar hid
+                itself once it lapsed, which removed the measurement at exactly
+                the moment it started mattering. */}
+            {license && <TermBar issuedAt={license.issued_at} expiresAt={license.expires_at} state={state} className="max-w-md" />}
 
             {state === "expired" && (
                 <div className="grid gap-1">
@@ -168,14 +156,10 @@ export function InstanceRecord({ instance, license, reapAfterDays, defaultOpen =
 
                 <div className="flex flex-wrap items-center gap-2.5">
                     {state === "none" ? (
-                        // A paid placeholder (awaiting_link) claims its real install
-                        // UUID in place. Anything else without a licence gets one from
-                        // the purchase page (self-hosted Free is created there).
-                        instance.status === "awaiting_link" ? (
-                            <LinkButton href={`/instances/link?claim=${instance.instance_id}`}>Link an install</LinkButton>
-                        ) : (
-                            <LinkButton href="/purchase">Get a licence</LinkButton>
-                        )
+                        // Every unlicensed instance is answered from the purchase
+                        // page — self-hosted Free and paid both start there, and
+                        // both name the install's own UUID.
+                        <LinkButton href="/purchase">Get a licence</LinkButton>
                     ) : cloud && instance.slug ? (
                         <>
                             <LinkButton external href={`https://${instance.slug}.vantage.hostxtra.co.uk`}>

adminsite/components/LicenceDelivery.tsx

@@ -1,56 +1,86 @@
 "use client";
 
 import { useState } from "react";
-import { Button } from "./Button";
+import { Panel } from "./Panel";
 
 /*
- * A licence blob is signed public data, not a secret it is useless on any
+ * A licence blob is signed public data, not a secret — it is useless on any
  * instance other than the one it names. So it is safe to show inline, and
  * showing it is what stops a blocked download from blocking a paying customer.
+ * That is also why it is never collapsed behind a toggle: someone whose
+ * clipboard and download are both blocked has to be able to select it by hand.
+ *
+ * It is evidence rather than content, so it is set in a well with a keyed strip
+ * saying what it is and how much of it there is, and given a fixed height. It
+ * used to run to 250px of base64 and was the largest thing on the page, which
+ * is a strange amount of room to give a string nobody reads.
+ *
+ * The download lives in the page header beside Renew, not here — it was in both
+ * places, which is one button too many for one file.
  */
-export function LicenceDelivery({ instanceId, blob, downloadUrl }: { instanceId: string; blob: string; downloadUrl: string }) {
+export function LicenceDelivery({ blob }: { instanceId: string; blob: string; downloadUrl: string }) {
     const [copied, setCopied] = useState(false);
 
     async function copy() {
-        await navigator.clipboard.writeText(blob);
-        setCopied(true);
-        setTimeout(() => setCopied(false), 2000);
+        try {
+            await navigator.clipboard.writeText(blob);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 2000);
+        } catch {
+            // Clipboard is refused without a secure context or a gesture the
+            // browser trusts. The blob is on screen and selectable either way,
+            // so this needs no error state.
+        }
     }
 
     const steps = [
         <>
-            Open <code className="rounded-sm bg-accent-wash px-1">Settings → Licence</code> on your install.
+            Open <Code>Settings → Licence</Code> on your install.
         </>,
         <>Paste the licence into the box and save.</>,
         <>
-            The page reports <code className="rounded-sm bg-accent-wash px-1">Valid</code> straight away no restart.
+            The page reports <Code>Valid</Code> straight away — no restart.
         </>,
     ];
 
     return (
-        <section className="grid gap-3">
-            <h2 className="text-xl">Your licence</h2>
-            <div className="flex flex-wrap items-center gap-3">
-                <a
-                    href={downloadUrl}
-                    download={`vantage-${instanceId}.lic`}
-                    className="inline-flex items-center gap-2 rounded border border-accent bg-accent px-4 py-2.5 text-[0.94rem] font-semibold text-accent-ink"
-                >
-                    Download licence
-                </a>
-                <Button variant="line" type="button" onClick={copy}>
-                    {copied ? "Copied" : "Copy to clipboard"}
-                </Button>
+        <Panel title="Your licence" meta="Paste into your install">
+            <div className="grid gap-2">
+                <div className="flex flex-wrap items-baseline justify-between gap-3">
+                    <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">Licence key</span>
+                    <span className="font-mono text-[0.64rem] uppercase tracking-[0.12em] text-ink-3">{blob.length.toLocaleString()} characters</span>
+                </div>
+
+                <div className="relative">
+                    {/* Dashed, because this is data to be carried somewhere else
+                        rather than a surface to read. */}
+                    <pre className="max-h-32 overflow-y-auto whitespace-pre-wrap break-all rounded border border-dashed border-rule bg-panel-2 p-3 pr-24 font-mono text-[0.7rem] leading-relaxed text-ink-2">
+                        {blob}
+                    </pre>
+                    <button
+                        type="button"
+                        onClick={copy}
+                        className="absolute right-2 top-2 rounded border border-rule bg-panel px-2.5 py-1 font-mono text-[0.66rem] uppercase tracking-[0.1em] text-ink-2 hover:border-accent hover:text-accent"
+                    >
+                        {copied ? "Copied" : "Copy"}
+                    </button>
+                </div>
             </div>
-            <pre className="max-h-48 overflow-y-auto whitespace-pre-wrap break-all rounded border border-dashed border-rule bg-panel-2 p-3 font-mono text-[0.72rem] text-ink-2">{blob}</pre>
+
+            {/* Numbered because this is an actual sequence — each step is only
+                possible once the one before it is done. */}
             <ol className="grid gap-2">
                 {steps.map((body, i) => (
-                    <li key={i} className="grid grid-cols-[1.6rem_1fr] gap-3 text-[0.82rem] text-ink-2">
-                        <span className="h-6 rounded-sm border border-rule text-center font-mono text-[0.72rem] leading-6 text-accent">{i + 1}</span>
-                        <span>{body}</span>
+                    <li key={i} className="grid grid-cols-[1.5rem_1fr] items-start gap-3 text-[0.84rem] text-ink-2">
+                        <span className="grid h-[1.4rem] place-items-center rounded-sm border border-rule font-mono text-[0.68rem] text-accent">{i + 1}</span>
+                        <span className="leading-[1.4rem]">{body}</span>
                     </li>
                 ))}
             </ol>
-        </section>
+        </Panel>
     );
 }
+
+function Code({ children }: { children: React.ReactNode }) {
+    return <code className="rounded-sm bg-accent-wash px-1 font-mono text-[0.8rem] text-ink">{children}</code>;
+}

adminsite/components/MembersPanel.tsx

@@ -4,13 +4,43 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useState } from "react";
 import { ApiError, api, type InstanceRole } from "@/lib/api";
 import { useSession } from "@/lib/session";
-import { Button } from "@/components/Button";
+import { Button, controlClass } from "@/components/Button";
+import { EmptyState, Panel } from "@/components/Panel";
 
 const ROLES: InstanceRole[] = ["owner", "admin", "member"];
 
 /*
- * Absent entirely for self-hosted instances the backend refuses those, and a
+ * What each rank actually lets someone do, in the instance rather than in the
+ * portal. The select used to offer three words with no statement of what they
+ * bought — which is a permissions control that declines to explain permissions.
+ */
+const ROLE_GRANTS: Record<InstanceRole, string> = {
+    owner: "Everything, including billing and deleting the instance.",
+    admin: "Manage servers, workflows, secrets and settings.",
+    member: "Use the instance. Cannot change settings or members.",
+};
+
+const SELECT_QUIET =
+    "rounded border border-transparent bg-transparent px-2 py-1 font-mono text-[0.78rem] uppercase tracking-[0.08em] text-ink-2 hover:border-rule focus:border-accent focus:text-ink focus:outline-none";
+
+/* Same height as the Grant access button beside it — see controlClass. */
+const SELECT = controlClass("bg-panel");
+
+/*
+ * The access roster for one instance.
+ *
+ * Absent entirely for self-hosted instances — the backend refuses those, and a
  * panel that renders controls the server will reject is a panel that lies.
+ *
+ * The row is a monogram and an address set in mono, because in this product an
+ * identity IS an address, and every other identifier on the screen — the
+ * instance UUID, the licence reference — is mono too. The role is a fact most
+ * of the time and a control occasionally, so it is drawn as text and only grows
+ * a border on hover or focus: the old row made the dropdown the loudest thing
+ * in it, which is backwards for a list people mostly read.
+ *
+ * Granting sits in its own strip on --panel-2 rather than as a fourth row of
+ * naked controls, so the roster reads as the record and the strip as the action.
  */
 export function MembersPanel({ instanceId }: { instanceId: string }) {
     const qc = useQueryClient();
@@ -18,6 +48,7 @@ export function MembersPanel({ instanceId }: { instanceId: string }) {
     const [selected, setSelected] = useState("");
     const [role, setRole] = useState<InstanceRole>("member");
     const [error, setError] = useState<string | null>(null);
+    const [confirming, setConfirming] = useState<string | null>(null);
 
     const members = useQuery({
         queryKey: ["members", instanceId],
@@ -44,109 +75,175 @@ export function MembersPanel({ instanceId }: { instanceId: string }) {
     });
     const revoke = useMutation({
         mutationFn: (uid: string) => api.revokeMember(instanceId, uid),
-        onSuccess: refresh,
-        onError: fail,
+        onSuccess: () => {
+            setConfirming(null);
+            refresh();
+        },
+        onError: (e) => {
+            setConfirming(null);
+            fail(e);
+        },
     });
 
     const myRole = session?.account_role;
     const canManage = myRole === "owner" || myRole === "admin";
 
-    const granted = new Set((members.data ?? []).map((m) => m.customer_user_id));
+    const rows = members.data ?? [];
+    const granted = new Set(rows.map((m) => m.customer_user_id));
     const candidates = (people.data ?? []).filter((p) => !granted.has(p.user_id) && p.verified_at);
     const pending = (people.data ?? []).filter((p) => !p.verified_at).length;
 
     return (
-        <section className="grid gap-4 rounded border border-rule bg-panel p-5">
-            <div className="grid gap-1">
-                <h2 className="text-xl">Who can sign in</h2>
-                <p className="text-[0.82rem] text-ink-2">Each person here has a real user inside this instance and signs in with their Vantage HQ password.</p>
+        <Panel title="Who can sign in" meta={rows.length ? `${rows.length} ${rows.length === 1 ? "person" : "people"}` : undefined} bodyless>
+            <div className="grid gap-3 px-4 pb-4 pt-3.5">
+                <p className="text-[0.84rem] text-ink-2">Each person here has a real user inside this instance and signs in with their Vantage HQ password.</p>
+                {error && (
+                    <p role="alert" className="rounded border border-rule border-l-[3px] border-l-expired bg-panel-2 px-3.5 py-2.5 text-[0.84rem] text-ink-2">
+                        {error}
+                    </p>
+                )}
             </div>
 
-            {error && <p className="text-[0.9rem] text-expired">{error}</p>}
+            {rows.length === 0 ? (
+                <EmptyState
+                    title="Nobody else can sign in yet."
+                    body={canManage ? "Add someone from your account below and a user is created for them inside this instance." : "An owner or admin can grant access."}
+                />
+            ) : (
+                <ul className="grid border-t border-rule-soft">
+                    {/*
+                     * Two columns on a phone — monogram and address — with the
+                     * controls dropping to their own full-width row beneath;
+                     * three columns from sm up, controls right-aligned. As one
+                     * wrapping flex row the address competed with a select and
+                     * two buttons for 320px and lost, and the confirm step put
+                     * three more elements into the same row.
+                     */}
+                    {rows.map((m) => (
+                        <li
+                            key={m.member_id}
+                            className="grid grid-cols-[auto_1fr] items-center gap-x-3 gap-y-2 border-b border-rule-soft px-4 py-3 last:border-b-0 sm:grid-cols-[auto_1fr_auto]"
+                        >
+                            <span aria-hidden className="grid h-7 w-7 shrink-0 place-items-center rounded-full bg-accent font-mono text-[0.62rem] font-bold text-accent-ink">
+                                {m.email.slice(0, 2).toUpperCase()}
+                            </span>
+                            <span className="min-w-0 break-all font-mono text-[0.84rem] sm:truncate sm:break-normal">{m.email}</span>
 
-            <ul className="grid gap-2">
-                {(members.data ?? []).map((m) => (
-                    <li key={m.member_id} className="flex flex-wrap items-center justify-between gap-3 border-b border-rule-soft pb-2">
-                        <span>{m.email}</span>
-                        <span className="flex items-center gap-3">
-                            {canManage ? (
-                                <select
-                                    value={m.role}
-                                    onChange={(e) =>
-                                        changeRole.mutate({
-                                            uid: m.customer_user_id,
-                                            role: e.target.value as InstanceRole,
-                                        })
-                                    }
-                                    className="rounded border border-rule bg-panel-2 px-2 py-1 font-mono text-[0.82rem] text-ink"
-                                >
-                                    {ROLES.map((r) => (
-                                        <option key={r} value={r}>
-                                            {r}
-                                        </option>
-                                    ))}
-                                </select>
-                            ) : (
-                                <span className="font-mono text-[0.82rem]">{m.role}</span>
-                            )}
-                            {canManage && (
-                                <button
-                                    type="button"
-                                    className="text-[0.82rem] font-semibold text-expired underline"
-                                    onClick={() => {
-                                        if (confirm(`Remove ${m.email} from this instance?`)) revoke.mutate(m.customer_user_id);
-                                    }}
-                                >
-                                    Remove
-                                </button>
-                            )}
-                        </span>
-                    </li>
-                ))}
-                {members.data?.length === 0 && <li className="text-ink-2">Nobody has been added yet.</li>}
-            </ul>
+                            <div className="col-span-2 flex flex-wrap items-center gap-2 sm:col-span-1 sm:flex-nowrap sm:justify-end">
+                                {canManage ? (
+                                    <label className="shrink-0">
+                                        <span className="sr-only">Role for {m.email}</span>
+                                        <select
+                                            value={m.role}
+                                            title={ROLE_GRANTS[m.role]}
+                                            onChange={(e) => changeRole.mutate({ uid: m.customer_user_id, role: e.target.value as InstanceRole })}
+                                            className={SELECT_QUIET}
+                                        >
+                                            {ROLES.map((r) => (
+                                                <option key={r} value={r}>
+                                                    {r}
+                                                </option>
+                                            ))}
+                                        </select>
+                                    </label>
+                                ) : (
+                                    <span className="shrink-0 font-mono text-[0.78rem] uppercase tracking-[0.08em] text-ink-3">{m.role}</span>
+                                )}
+
+                                {canManage &&
+                                /*
+                                 * Confirming inline rather than through
+                                 * window.confirm(), and in the row itself rather
+                                 * than a dialog: it can say what revoking does,
+                                 * where the eye already is.
+                                 */
+                                (confirming === m.customer_user_id ? (
+                                    <span className="flex flex-wrap items-center gap-x-2.5 gap-y-1">
+                                        <span className="text-[0.8rem] text-ink-2">Revoke access?</span>
+                                        <button
+                                            type="button"
+                                            className="rounded border border-expired px-2 py-0.5 font-mono text-[0.7rem] uppercase tracking-[0.08em] text-expired hover:bg-expired hover:text-panel disabled:opacity-50"
+                                            disabled={revoke.isPending}
+                                            onClick={() => revoke.mutate(m.customer_user_id)}
+                                        >
+                                            {revoke.isPending ? "Revoking…" : "Revoke"}
+                                        </button>
+                                        <button type="button" className="font-mono text-[0.7rem] uppercase tracking-[0.08em] text-ink-3 hover:text-ink" onClick={() => setConfirming(null)}>
+                                            Keep
+                                        </button>
+                                    </span>
+                                ) : (
+                                    /* Quiet until intent: a row that is mostly read
+                                       should not carry a permanently red control. */
+                                    <button
+                                        type="button"
+                                        className="shrink-0 rounded border border-transparent px-2 py-0.5 font-mono text-[0.7rem] uppercase tracking-[0.08em] text-ink-3 hover:border-expired hover:text-expired"
+                                        onClick={() => {
+                                            setError(null);
+                                            setConfirming(m.customer_user_id);
+                                        }}
+                                    >
+                                        Revoke<span className="sr-only"> access for {m.email}</span>
+                                    </button>
+                                ))}
+                            </div>
+                        </li>
+                    ))}
+                </ul>
+            )}
 
             {canManage && (
-                <form
-                    className="flex flex-wrap items-end gap-3"
-                    onSubmit={(e) => {
-                        e.preventDefault();
-                        setError(null);
-                        if (selected) grant.mutate();
-                    }}
-                >
-                    <label className="grid gap-1.5">
-                        <span className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">Add someone</span>
-                        <select value={selected} onChange={(e) => setSelected(e.target.value)} className="rounded border border-rule bg-panel-2 px-2.5 py-2 font-mono text-ink">
-                            <option value="">Choose a person…</option>
-                            {candidates.map((p) => (
-                                <option key={p.user_id} value={p.user_id}>
-                                    {p.email}
-                                </option>
-                            ))}
-                        </select>
-                    </label>
-                    <label className="grid gap-1.5">
-                        <span className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">Role here</span>
-                        <select value={role} onChange={(e) => setRole(e.target.value as InstanceRole)} className="rounded border border-rule bg-panel-2 px-2.5 py-2 font-mono text-ink">
-                            {ROLES.map((r) => (
-                                <option key={r} value={r}>
-                                    {r}
-                                </option>
-                            ))}
-                        </select>
-                    </label>
-                    <Button type="submit" disabled={!selected || grant.isPending}>
-                        {grant.isPending ? "Adding…" : "Add"}
-                    </Button>
-                </form>
-            )}
+                <div className="grid gap-3 border-t border-rule bg-panel-2 px-4 py-3.5">
+                    {/* Stacked and full width on a phone; one row from sm up.
+                        Three controls side by side left the person select about
+                        90px wide, which is not enough to read an address in. */}
+                    <form
+                        className="grid gap-3 sm:flex sm:flex-wrap sm:items-end"
+                        onSubmit={(e) => {
+                            e.preventDefault();
+                            setError(null);
+                            if (selected) grant.mutate();
+                        }}
+                    >
+                        <label className="grid min-w-0 gap-1.5 sm:flex-1">
+                            <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">Grant access to</span>
+                            <select value={selected} onChange={(e) => setSelected(e.target.value)} className={SELECT} disabled={candidates.length === 0}>
+                                <option value="">{candidates.length === 0 ? "Everyone already has access" : "Choose a person…"}</option>
+                                {candidates.map((p) => (
+                                    <option key={p.user_id} value={p.user_id}>
+                                        {p.email}
+                                    </option>
+                                ))}
+                            </select>
+                        </label>
+                        <label className="grid gap-1.5">
+                            <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">As</span>
+                            <select value={role} onChange={(e) => setRole(e.target.value as InstanceRole)} className={SELECT}>
+                                {ROLES.map((r) => (
+                                    <option key={r} value={r}>
+                                        {r}
+                                    </option>
+                                ))}
+                            </select>
+                        </label>
+                        <Button type="submit" disabled={!selected || grant.isPending} className="w-full justify-center sm:w-auto">
+                            {grant.isPending ? "Granting…" : "Grant access"}
+                        </Button>
+                    </form>
 
-            {canManage && pending > 0 && (
-                <p className="text-[0.82rem] text-ink-3">
-                    {pending} invited {pending === 1 ? "person has" : "people have"} not accepted yet and cannot be added until they do.
-                </p>
+                    {/* The chosen rank explains itself, rather than leaving three
+                        words to be guessed at. */}
+                    <p className="text-[0.8rem] text-ink-3">
+                        <span className="font-mono uppercase tracking-[0.08em]">{role}</span> — {ROLE_GRANTS[role]}
+                    </p>
+
+                    {pending > 0 && (
+                        <p className="text-[0.8rem] text-ink-3">
+                            {pending} invited {pending === 1 ? "person has" : "people have"} not accepted yet, and cannot be granted access until they do.
+                        </p>
+                    )}
+                </div>
             )}
-        </section>
+        </Panel>
     );
 }

adminsite/components/PageHeader.tsx

@@ -15,6 +15,8 @@ function CopyButton({ value }: { value: string }) {
     return (
         <button
             type="button"
+            // Never the thing that wraps: it is 5 characters and the value
+            // beside it may be 36.
             onClick={async () => {
                 try {
                     await navigator.clipboard.writeText(value);
@@ -26,7 +28,7 @@ function CopyButton({ value }: { value: string }) {
                     // selectable either way, so this needs no error state.
                 }
             }}
-            className="rounded-sm border border-rule px-1.5 py-px font-mono text-[0.62rem] uppercase tracking-[0.1em] text-ink-3 hover:border-accent hover:text-accent"
+            className="shrink-0 rounded-sm border border-rule px-1.5 py-px font-mono text-[0.62rem] uppercase tracking-[0.1em] text-ink-3 hover:border-accent hover:text-accent"
         >
             {done ? "Copied" : "Copy"}
         </button>
@@ -76,9 +78,13 @@ export function PageHeader({
             {(record?.length || status) && (
                 <div className="flex flex-wrap items-center gap-x-5 gap-y-2.5 border-t border-rule pt-2.5">
                     {record?.map((f) => (
-                        <span key={f.key} className="flex items-center gap-2">
-                            <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">{f.key}</span>
-                            <span className="font-mono text-[0.78rem] tabular-nums text-ink-2">{f.value}</span>
+                        // min-w-0 and break-all because the commonest value here
+                        // is a 36-character UUID with a Copy button beside it,
+                        // which does not fit a 320px screen as one unbreakable
+                        // token and pushed the whole page sideways.
+                        <span key={f.key} className="flex min-w-0 items-center gap-2">
+                            <span className="shrink-0 font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">{f.key}</span>
+                            <span className="min-w-0 break-all font-mono text-[0.78rem] tabular-nums text-ink-2">{f.value}</span>
                             {f.copy && <CopyButton value={f.value} />}
                         </span>
                     ))}

adminsite/components/Panel.tsx

@@ -0,0 +1,91 @@
+import clsx from "clsx";
+
+/*
+ * The surface every screen is built from.
+ *
+ * Before this there were four panel treatments in the app: `rounded border
+ * border-rule bg-panel p-5` with an `<h2 className="text-xl">`, the same thing
+ * with `text-[0.95rem] font-medium`, a bare `<section className="space-y-2">`
+ * with no border at all, and a table wrapper that was a panel in everything but
+ * name. They were all trying to be the same object.
+ *
+ * The header is title-left, meta-right. Meta is the keyed idiom — mono, small,
+ * tracked, dimmed — because it is always a count, a scope or an identifier,
+ * never prose.
+ */
+export function Panel({
+    title,
+    meta,
+    actions,
+    tone,
+    children,
+    bodyless,
+    className,
+}: {
+    title?: string;
+    meta?: React.ReactNode;
+    actions?: React.ReactNode;
+    /** Draws the panel's own border in a state colour. For a panel that IS the warning. */
+    tone?: "warn" | "expired";
+    children: React.ReactNode;
+    /** Skip the padded body — for a panel whose content is a full-bleed table. */
+    bodyless?: boolean;
+    className?: string;
+}) {
+    const head = title || meta || actions;
+
+    return (
+        <section
+            className={clsx(
+                "grid overflow-hidden rounded border bg-panel",
+                tone === "warn" ? "border-warn" : tone === "expired" ? "border-expired" : "border-rule",
+                className,
+            )}
+        >
+            {head && (
+                <header className="flex flex-wrap items-center justify-between gap-3 border-b border-rule-soft px-4 py-3">
+                    {title && <h2 className="text-[0.95rem] font-bold tracking-[-0.01em]">{title}</h2>}
+                    <div className="flex items-center gap-3">
+                        {meta && <span className="font-mono text-[0.64rem] uppercase tracking-[0.14em] text-ink-3">{meta}</span>}
+                        {actions}
+                    </div>
+                </header>
+            )}
+            {bodyless ? children : <div className="grid gap-3.5 p-4">{children}</div>}
+        </section>
+    );
+}
+
+/*
+ * An aside that is part of the argument rather than beside it: the consequence
+ * of the action on screen, or the constraint the reader is about to hit. The
+ * left rule carries the tone, so the note reads as annotation and never as a
+ * second panel competing with the one it sits in.
+ */
+export function Note({ tone = "accent", children }: { tone?: "accent" | "warn" | "expired"; children: React.ReactNode }) {
+    return (
+        <p
+            className={clsx(
+                "rounded border border-rule border-l-[3px] bg-panel-2 px-3.5 py-2.5 text-[0.84rem] text-ink-2",
+                tone === "warn" ? "border-l-warn" : tone === "expired" ? "border-l-expired" : "border-l-accent",
+            )}
+        >
+            {children}
+        </p>
+    );
+}
+
+/*
+ * An empty screen is an invitation to act. Every one of these says what the
+ * thing is before offering to make one — "No licences match those filters" on
+ * its own tells someone the filter worked, not what to do about it.
+ */
+export function EmptyState({ title, body, action }: { title: string; body?: React.ReactNode; action?: React.ReactNode }) {
+    return (
+        <div className="grid justify-items-center gap-2 px-5 py-12 text-center">
+            <p className="text-[1rem] font-bold">{title}</p>
+            {body && <p className="max-w-[46ch] text-[0.86rem] text-ink-2">{body}</p>}
+            {action && <div className="mt-2">{action}</div>}
+        </div>
+    );
+}

adminsite/components/Queue.tsx

@@ -1,5 +1,6 @@
 import Link from "next/link";
 import clsx from "clsx";
+import type { ReactNode } from "react";
 
 const TONE = {
     expired: "border-l-expired text-expired",
@@ -16,7 +17,11 @@ export function Queue({
     title: string;
     count: number;
     tone: keyof typeof TONE;
-    items: { label: string; href: string; meta: string }[];
+    /* `meta` is a node rather than a string so a queue about time can carry the
+     * term measurement itself. A tier name told the reader what the instance
+     * was; the queue is sorted by how soon it lapses, and that was the one
+     * figure the row did not show. */
+    items: { label: string; href: string; meta: ReactNode }[];
 }) {
     return (
         <section
@@ -38,12 +43,12 @@ export function Queue({
                     {items.map((i) => (
                         <li
                             key={i.href}
-                            className="flex justify-between gap-2 font-mono text-[0.72rem] text-ink-2"
+                            className="flex items-center justify-between gap-2 font-mono text-[0.72rem] text-ink-2"
                         >
-                            <Link href={i.href} className="text-accent underline">
+                            <Link href={i.href} className="truncate text-accent underline">
                                 {i.label}
                             </Link>
-                            <span className="tabular-nums">{i.meta}</span>
+                            <span className="shrink-0 tabular-nums">{i.meta}</span>
                         </li>
                     ))}
                 </ul>

adminsite/components/RelinkPanel.tsx

@@ -6,6 +6,18 @@ import { Field } from "./Field";
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+/*
+ * The relink control, and only the control.
+ *
+ * It used to carry its own heading and its own "N of M relinks left this term"
+ * line. It now sits inside the Moves panel, which already says both — a panel
+ * titled Moves with "2 of 3 used" in its header, wrapping a section headed
+ * "Moved to a new server?" that says "1 of 3 relinks left", is the same fact
+ * told twice in two different directions.
+ *
+ * The exhausted case still lives here rather than in the caller: it is the
+ * reason the button is disabled, so it belongs beside the button.
+ */
 export function RelinkPanel({ used, max, onRelink, error }: { instanceId: string; used: number; max: number; onRelink: (newId: string) => void; error?: string }) {
     const [open, setOpen] = useState(false);
     const [value, setValue] = useState("");
@@ -13,18 +25,25 @@ export function RelinkPanel({ used, max, onRelink, error }: { instanceId: string
     const exhausted = remaining === 0;
 
     return (
-        <section className="grid gap-3 border-t border-rule-soft pt-5">
-            <h2 className="text-xl">Moved to a new server?</h2>
-            <p className="text-[0.82rem] text-ink-2">Relinking issues a replacement licence for the new install, covering the rest of your current term.</p>
-            {open && !exhausted && <Field label="New instance ID" value={value} onChange={(e) => setValue(e.target.value)} error={error} hint="From Settings → Licence on the new install." />}
+        <div className="grid gap-3">
+            {open && !exhausted && (
+                <Field label="New instance ID" value={value} onChange={(e) => setValue(e.target.value)} error={error} hint="From Settings → Licence on the new install." />
+            )}
             <div className="flex flex-wrap items-center gap-3">
-                <Button type="button" variant="line" disabled={exhausted || (open && !UUID_RE.test(value.trim()))} onClick={() => (open ? onRelink(value.trim()) : setOpen(true))}>
-                    Relink to a new install
+                <Button
+                    type="button"
+                    variant="line"
+                    disabled={exhausted || (open && !UUID_RE.test(value.trim()))}
+                    onClick={() => (open ? onRelink(value.trim()) : setOpen(true))}
+                >
+                    Move to another install
                 </Button>
-                <span className="text-[0.82rem] text-ink-3">
-                    {exhausted ? "You have used every relink for this term contact support and we will sort it out." : `${remaining} of ${max} relinks left this term`}
-                </span>
+                {exhausted ? (
+                    <span className="text-[0.82rem] text-ink-3">You have used every move for this term — contact support and we will sort it out.</span>
+                ) : (
+                    open && <span className="text-[0.82rem] text-ink-3">Relinking issues a replacement licence covering the rest of your current term.</span>
+                )}
             </div>
-        </section>
+        </div>
     );
 }

adminsite/components/RenamePanel.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "./Button";
+import { Field } from "./Field";
+import { Note } from "./Panel";
+import { ApiError, type RenameResult } from "@/lib/api";
+import { baseSlug, hostFor, slugError } from "@/lib/slug";
+
+/*
+ * The rename control, and only the control — the same shape as RelinkPanel: an
+ * input that expands in place rather than a modal, because this app has no modal
+ * and one action with one field does not need one.
+ *
+ * The host preview is drawn from lib/slug.ts, a mirror of the Go rules. It can
+ * disagree with the server; the 409 that comes back is the answer that counts.
+ *
+ * movesHost is what separates a rename that moves a DNS host from one that only
+ * changes a label. Self-hosted instances and unprovisioned cloud placeholders
+ * have no address, so every word about old links breaking and signing in again
+ * is false for them — and a preview host they will never live at is worse than
+ * no preview at all.
+ */
+export function RenamePanel({
+    currentName,
+    currentSlug,
+    movesHost,
+    onRename,
+}: {
+    currentName: string;
+    currentSlug: string;
+    movesHost: boolean;
+    onRename: (name: string) => Promise<RenameResult>;
+}) {
+    const [open, setOpen] = useState(false);
+    const [value, setValue] = useState(currentName);
+    const [error, setError] = useState<string | undefined>();
+    const [busy, setBusy] = useState(false);
+    const [done, setDone] = useState<RenameResult | undefined>();
+
+    const name = value.trim();
+    const derived = baseSlug(name);
+    const invalid = slugError(name);
+    // A cosmetic edit that lands on the same slug is still a rename worth doing —
+    // the name is what the customer reads. Only an empty or unchanged name is
+    // nothing to submit.
+    const unchanged = name === currentName.trim();
+
+    async function submit() {
+        setError(undefined);
+        setBusy(true);
+        try {
+            const res = await onRename(name);
+            setDone(res);
+            setOpen(false);
+            // The input is prefilled with the current name, and the current name
+            // is now this one. Leaving the old text in would make the next open
+            // look like an edit already in progress.
+            setValue(res.name);
+        } catch (err) {
+            setError(err instanceof ApiError ? err.message : "Rename failed. Try again.");
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    // The note sits ABOVE the control rather than replacing it. A rename is not
+    // a one-shot action — a customer who mistypes the new name needs the panel
+    // back, and returning early here left them with a success message and no way
+    // to correct it short of a reload.
+    return (
+        <div className="grid gap-3">
+            {done &&
+                (movesHost ? (
+                    <Note tone="warn">
+                        <span className="grid gap-2">
+                            <span>
+                                This instance is now <strong>{done.name}</strong>, at{" "}
+                                <span className="font-mono">{hostFor(done.slug)}</span>. The old address has stopped working, and
+                                your sign-in does not follow it — you will need to sign in again there.
+                            </span>
+                            <a
+                                href={done.login_url || `https://${hostFor(done.slug)}`}
+                                className="justify-self-start font-mono text-[0.78rem] text-accent underline"
+                            >
+                                Open {hostFor(done.slug)} &rarr;
+                            </a>
+                        </span>
+                    </Note>
+                ) : (
+                    <Note tone="warn">
+                        This instance is now <strong>{done.name}</strong>.
+                    </Note>
+                ))}
+            {open && (
+                <Field
+                    label="Instance name"
+                    value={value}
+                    onChange={(e) => setValue(e.target.value)}
+                    error={error ?? (name ? invalid : undefined)}
+                    hint={
+                        movesHost && name && !invalid ? (
+                            <>
+                                Moves to <span className="font-mono">{hostFor(derived)}</span>
+                                {derived === currentSlug && " — the address does not change"}
+                            </>
+                        ) : (
+                            "Letters and digits; everything else becomes a hyphen."
+                        )
+                    }
+                />
+            )}
+            <div className="flex flex-wrap items-center gap-3">
+                <Button
+                    type="button"
+                    variant="line"
+                    disabled={busy || (open && (!name || Boolean(invalid) || unchanged))}
+                    onClick={() => (open ? submit() : setOpen(true))}
+                >
+                    {busy ? "Renaming…" : "Rename instance"}
+                </Button>
+                {open && movesHost && (
+                    <span className="text-[0.82rem] text-ink-3">
+                        Anyone signed in will need to sign in again at the new address, and links to the old one stop working.
+                    </span>
+                )}
+            </div>
+        </div>
+    );
+}

adminsite/components/Table.tsx

@@ -0,0 +1,122 @@
+import clsx from "clsx";
+import type { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from "react";
+
+/*
+ * One table treatment for the whole console.
+ *
+ * There were four: billing, licences, accounts and catalogue each wrote their
+ * own thead, and they disagreed about the head's type size, its tracking,
+ * whether it sat on --panel-2, and whether numbers were tabular. Catalogue's
+ * heads were sentence-case body text. A registry whose columns are set four
+ * ways does not read as one product.
+ *
+ * The head is the keyed idiom — mono, small, uppercase, widely tracked — which
+ * is what a column head is: a key above a value, exactly as the record line is
+ * a key beside one.
+ *
+ * MOBILE. `stack` collapses the table into one card per row below sm, each cell
+ * becoming a label/value pair drawn from TD's `label`. The variants below hang
+ * off a `stacked` class on the <table>, so a table that does not opt in is
+ * untouched at every width.
+ *
+ * It is opt-in rather than automatic because a stacked row whose cells have no
+ * labels is worse than a scrolling one — the values lose the only thing naming
+ * them. Customer screens stack; the staff console's wide registry tables scroll
+ * sideways instead, which is the right trade for eight columns read at a desk.
+ */
+
+const STACK = "max-sm:[.stacked_&]:block";
+
+export function Table({ stack, className, children, ...props }: HTMLAttributes<HTMLTableElement> & { stack?: boolean }) {
+    return (
+        <div className="overflow-x-auto">
+            <table className={clsx("w-full border-collapse text-left text-[0.86rem]", stack && "stacked max-sm:block", className)} {...props}>
+                {children}
+            </table>
+        </div>
+    );
+}
+
+export function THead({ className, children, ...props }: HTMLAttributes<HTMLTableSectionElement>) {
+    return (
+        <thead className={clsx("border-b border-rule", "max-sm:[.stacked_&]:hidden", className)} {...props}>
+            {children}
+        </thead>
+    );
+}
+
+export function TBody({ className, children, ...props }: HTMLAttributes<HTMLTableSectionElement>) {
+    return (
+        <tbody className={clsx(STACK, "max-sm:[.stacked_&]:space-y-3 max-sm:[.stacked_&]:p-3", className)} {...props}>
+            {children}
+        </tbody>
+    );
+}
+
+export function TR({ className, children, ...props }: HTMLAttributes<HTMLTableRowElement>) {
+    return (
+        <tr
+            className={clsx(
+                "border-b border-rule-soft last:border-0 hover:bg-panel-2",
+                STACK,
+                // Plain bg-panel-2, not an opacity modifier: this app's tokens
+                // are whole colours rather than RGB channels, so `/40` has
+                // nothing to drop an alpha into. web/ stores channels precisely
+                // because it leans on those modifiers; this one must not.
+                "max-sm:[.stacked_&]:rounded max-sm:[.stacked_&]:border max-sm:[.stacked_&]:border-rule max-sm:[.stacked_&]:bg-panel-2 max-sm:[.stacked_&]:p-3",
+                className,
+            )}
+            {...props}
+        >
+            {children}
+        </tr>
+    );
+}
+
+interface CellProps {
+    /** Right-aligns the cell. For quantities and money, which read down the column. */
+    numeric?: boolean;
+}
+
+export function TH({ className, numeric, children, ...props }: ThHTMLAttributes<HTMLTableCellElement> & CellProps) {
+    return (
+        <th
+            className={clsx(
+                "whitespace-nowrap px-4 py-2.5 font-mono text-[0.62rem] font-normal uppercase tracking-[0.13em] text-ink-3",
+                numeric && "text-right",
+                className,
+            )}
+            {...props}
+        >
+            {children}
+        </th>
+    );
+}
+
+export function TD({ className, numeric, label, children, ...props }: TdHTMLAttributes<HTMLTableCellElement> & CellProps & { label?: string }) {
+    return (
+        <td
+            className={clsx(
+                "px-4 py-3 align-middle",
+                numeric && "text-right tabular-nums",
+                // Stacked, a cell is a label above its value and the right
+                // alignment that made a money column read down the page is
+                // meaningless, so it is dropped.
+                STACK,
+                "max-sm:[.stacked_&]:px-0 max-sm:[.stacked_&]:py-1 max-sm:[.stacked_&]:text-left",
+                className,
+            )}
+            {...props}
+        >
+            {label && (
+                <span className="mb-0.5 hidden font-mono text-[0.6rem] uppercase tracking-[0.13em] text-ink-3 max-sm:[.stacked_&]:block">{label}</span>
+            )}
+            {children}
+        </td>
+    );
+}
+
+/** The secondary line under a cell's main value — an ID, a deployment, a date. */
+export function Sub({ children }: { children: React.ReactNode }) {
+    return <div className="text-[0.78rem] text-ink-3">{children}</div>;
+}

adminsite/components/TermBar.tsx

@@ -0,0 +1,104 @@
+import clsx from "clsx";
+import { daysRemaining, formatDate, type LicenceState } from "@/lib/format";
+
+/*
+ * A licence's life as a measured line: issued at the left, expiry at the right,
+ * today as a notch, the part you have not got yet hatched.
+ *
+ * This replaces a 1px progress rule and a "Renews 19 Aug 2026" caption. The
+ * date is still there, but a date alone makes the reader do the arithmetic that
+ * is the only question this product is ever asked — when does this stop
+ * working. The bar answers it before they read a word.
+ *
+ * The fill takes the state's colour, so the same vocabulary the pill uses
+ * carries through. State is never colour alone here either: the remaining span
+ * is hatched rather than tinted, the notch is a hard edge, and the days-left
+ * figure is written out.
+ */
+
+const TONE: Record<LicenceState, string> = {
+    valid: "text-valid",
+    warn: "text-warn",
+    expired: "text-expired",
+    none: "text-accent",
+};
+
+function span(issuedAt: string, expiresAt: string) {
+    const start = new Date(issuedAt).getTime();
+    const end = new Date(expiresAt).getTime();
+    const total = end - start;
+    // A licence issued and expiring at the same instant is not a real record,
+    // but it must not divide by zero on the way to being rendered.
+    if (!Number.isFinite(total) || total <= 0) return 100;
+    const elapsed = Date.now() - start;
+    return Math.max(0, Math.min(100, (elapsed / total) * 100));
+}
+
+export function TermBar({
+    issuedAt,
+    expiresAt,
+    state,
+    className,
+}: {
+    issuedAt: string;
+    expiresAt: string;
+    state: LicenceState;
+    className?: string;
+}) {
+    const pct = span(issuedAt, expiresAt);
+    const days = daysRemaining(expiresAt);
+    const expired = days <= 0;
+
+    const remaining = expired
+        ? `Expired ${Math.abs(days)} ${Math.abs(days) === 1 ? "day" : "days"} ago`
+        : `${days} ${days === 1 ? "day" : "days"} left`;
+
+    return (
+        <div className={clsx("grid gap-2", TONE[state], className)}>
+            <div className="relative h-[26px] overflow-hidden rounded-sm border border-rule bg-panel-2">
+                <span className="absolute inset-y-0 left-0 bg-current opacity-[0.16]" style={{ width: `${pct}%` }} />
+                {/* The span still to come, drawn as absence rather than as a
+                    second colour: it is the thing being bought. */}
+                <span
+                    className="absolute inset-y-0 right-0 bg-[repeating-linear-gradient(45deg,transparent_0_5px,var(--rule-soft)_5px_6px)]"
+                    style={{ width: `${100 - pct}%` }}
+                />
+                <span className="absolute -inset-y-px w-0.5 bg-current" style={{ left: `${pct}%` }} />
+            </div>
+
+            {/*
+             * On a phone the three ends stack, and the figure someone actually
+             * came for goes first — wrapping a justify-between row left "9 days
+             * left" marooned between two dates in the middle of the stack.
+             */}
+            <div className="grid gap-1 sm:flex sm:flex-wrap sm:items-baseline sm:justify-between sm:gap-x-4">
+                <span className="order-1 font-mono text-[0.74rem] font-bold tabular-nums sm:order-2">{remaining}</span>
+                <span className="order-2 font-mono text-[0.64rem] uppercase tracking-[0.12em] text-ink-3 sm:order-1">Issued {formatDate(issuedAt)}</span>
+                <span className="order-3 font-mono text-[0.64rem] uppercase tracking-[0.12em] text-ink-3">Expires {formatDate(expiresAt)}</span>
+            </div>
+        </div>
+    );
+}
+
+/*
+ * The same measurement at 56px, for a row in a ledger. Licences, Billing and
+ * the staff expiry queue are all lists of terms, and a list of dates cannot be
+ * scanned for "which of these is nearly out" — a list of bars can.
+ *
+ * It carries a text alternative rather than a title: the row it sits in is
+ * being read, not hovered.
+ */
+export function TermSpark({ issuedAt, expiresAt, state }: { issuedAt: string; expiresAt: string; state: LicenceState }) {
+    const pct = span(issuedAt, expiresAt);
+    const days = daysRemaining(expiresAt);
+
+    return (
+        <span className={clsx("inline-flex items-center gap-2", TONE[state])}>
+            <span aria-hidden className="relative inline-block h-[9px] w-14 overflow-hidden rounded-sm border border-rule bg-panel-2 align-middle">
+                <span className="absolute inset-y-0 left-0 bg-current opacity-[0.45]" style={{ width: `${pct}%` }} />
+                <span className="absolute inset-y-0 w-px bg-current" style={{ left: `${pct}%` }} />
+            </span>
+            <span className="font-mono text-[0.72rem] tabular-nums">{days <= 0 ? `−${Math.abs(days)}d` : `${days}d`}</span>
+        </span>
+    );
+}

adminsite/lib/api.ts

@@ -129,6 +129,9 @@ export interface Instance {
     status: InstanceStatus;
     current_license?: string;
     relink_count: number;
+    /** Cloud only, and only until the paid checkout provisions the real row. */
+    placeholder?: boolean;
+    renamed_at?: string;
     inject_failed_at?: string | null;
     notices_sent?: string[];
     created_at: string;
@@ -247,13 +250,13 @@ export interface Entitlement {
     updated_at: string;
 }
 
-export interface CustomerUser {
-    user_id: string;
-    account_id: string;
-    email: string;
-    verified_at?: string | null;
-    created_at: string;
-}
+/*
+ * Staff and customer screens read the SAME customer_users row, so they share one
+ * type. There used to be a second, narrower CustomerUser for the staff side; it
+ * silently stopped matching the moment account_role was added to the model, and
+ * a subset type cannot warn about a field it never claimed to have.
+ */
+export type CustomerUser = AccountUser;
 
 export interface AuditEntry {
     actor: string;
@@ -288,6 +291,14 @@ export interface StaffInstanceResponse {
     injection: { applicable: boolean; state?: InjectionState; failed_at?: string | null };
 }
 
+export interface RenameResult {
+    instance_id: string;
+    name: string;
+    slug: string;
+    /** Empty when APP_LOGIN_URL is unset on the server. */
+    login_url?: string;
+}
+
 // --- calls ---------------------------------------------------------------
 
 export const api = {
@@ -306,6 +317,8 @@ export const api = {
         post<Instance>("/api/instances/link", { instance_id, name }),
     createInstance: (name: string) => post<Instance>("/api/instances", { name }),
     renewInstance: (id: string) => post<License>(`/api/instances/${id}/renew`, {}),
+    renameInstance: (id: string, name: string) =>
+        put<RenameResult>(`/api/instances/${id}/name`, { name }),
     // Self-hosted Free: issue the licence on an already-linked instance.
     claimFree: (id: string) => post<License>(`/api/instances/${id}/claim-free`, {}),
     relink: (id: string, instance_id: string) =>
@@ -317,8 +330,10 @@ export const api = {
     entitlement: (id: string) =>
         req<{ entitlement: Entitlement; pending: boolean }>(`/api/instances/${id}/entitlement`),
     checkoutOptions: () => req<CheckoutOptions>("/api/checkout/options"),
-    createSelfHosted: (name: string) =>
-        post<{ instance_id: string }>("/api/instances/self-hosted", { name }),
+    // Paid self-hosted: links (or reuses) the install's real UUID, which the
+    // checkout then names. There is no placeholder to claim afterwards.
+    createSelfHostedCheckout: (instance_id: string, name: string) =>
+        post<{ instance_id: string }>("/api/instances/self-hosted", { instance_id, name }),
     // Paid cloud: provisions the real instance the paid webhook then licenses.
     createCloudCheckout: (name: string) =>
         post<{ instance_id: string }>("/api/instances/cloud", { name }),
@@ -326,9 +341,6 @@ export const api = {
         id: string,
         body: { tier: Tier; term: Term; servers: number; features: string[] },
     ) => put<{ entitlement: Entitlement; pending: boolean }>(`/api/instances/${id}/entitlement`, body),
-    claimLink: (placeholderId: string, instance_id: string) =>
-        post<{ instance_id: string; warning?: string }>(
-            `/api/instances/${placeholderId}/claim-link`, { instance_id }),
     billingPortal: () => post<{ url: string }>("/api/billing/portal"),
 
     accountUsers: () => req<AccountUser[]>("/api/account/users"),
@@ -368,6 +380,8 @@ export const api = {
             post<License>(`/api/staff/instances/${id}/issue`, payload),
         relink: (id: string, instance_id: string) =>
             post<License>(`/api/staff/instances/${id}/relink`, { instance_id }),
+        renameInstance: (id: string, name: string) =>
+            put<RenameResult>(`/api/staff/instances/${id}/name`, { name }),
         licenses: (params?: Record<string, string>) =>
             req<License[]>(`/api/staff/licenses${params ? `?${new URLSearchParams(params)}` : ""}`),
         plans: () => req<Plan[]>("/api/staff/plans"),

adminsite/lib/slug.ts

@@ -0,0 +1,56 @@
+/*
+ * A TypeScript mirror of shared/provision's slug rules, used ONLY to preview the
+ * host a rename would move an instance to while the customer types.
+ *
+ * It is a second implementation of Slugify, BaseSlug and ReservedSlugs, and it
+ * must change in the same commit as the Go one — the same hazard as
+ * web/lib/targets.ts. The preview is a courtesy; the server's 409 is the
+ * boundary, and the two are allowed to disagree without anything breaking.
+ */
+
+/** Mirrors provision.MinSlugLength / MaxSlugLength. */
+export const MIN_SLUG_LENGTH = 3;
+export const MAX_SLUG_LENGTH = 40;
+
+/** Mirrors provision.ReservedSlugs. */
+const RESERVED = new Set([
+    "www", "api", "app", "admin", "auth",
+    "install", "static", "_next", "default",
+]);
+
+/*
+ * The tenant subdomain namespace. Also hardcoded in InstanceRecord.tsx and the
+ * customer instance page; those predate this file and are left alone rather than
+ * refactored under a rename change.
+ */
+export const INSTANCE_DOMAIN = "vantage.hostxtra.co.uk";
+
+/** Mirrors provision.Slugify. */
+export function slugify(name: string): string {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+
+/** Mirrors provision.BaseSlug's truncation. */
+export function baseSlug(name: string): string {
+    return slugify(name).slice(0, MAX_SLUG_LENGTH);
+}
+
+/** The reason a name cannot become a slug, or undefined when it can. */
+export function slugError(name: string): string | undefined {
+    const base = slugify(name);
+    if (base.length < MIN_SLUG_LENGTH) {
+        return `Needs at least ${MIN_SLUG_LENGTH} letters or digits.`;
+    }
+    if (RESERVED.has(base.slice(0, MAX_SLUG_LENGTH))) {
+        return "That name is reserved.";
+    }
+    return undefined;
+}
+
+/** The host an instance on this slug is reached at. */
+export function hostFor(slug: string): string {
+    return `${slug}.${INSTANCE_DOMAIN}`;
+}

agent/internal/packages/packages.go

@@ -33,7 +33,7 @@ func Collect() (OSRelease, []Package, error) {
 	switch {
 	case have("dpkg-query"):
 		out, err := run(ctx, "dpkg-query", "-W", "-f",
-			`${Package}\t${Version}\t${Architecture}\t${source:Package}\n`)
+			`${Package}\t${Version}\t${Architecture}\t${source:Package}\t${db:Status-Status}\n`)
 		if err != nil {
 			return osrel, nil, err
 		}

agent/internal/packages/parse.go

@@ -20,12 +20,20 @@ type Package struct {
 }
 
 // ParseDpkg reads tab-separated output of
-// dpkg-query -W -f '${Package}\t${Version}\t${Architecture}\t${source:Package}\n'
+// dpkg-query -W -f '${Package}\t${Version}\t${Architecture}\t${source:Package}\t${db:Status-Status}\n'
 //
 // SourceName is why the fourth column is requested at all: Debian and Ubuntu
 // advisories are keyed on the SOURCE package, so one CVE against "openssl"
 // covers the binaries libssl3, openssl and libssl-dev. Matching on binary name
 // alone finds one of the three.
+//
+// The fifth column is why "rc" packages do not appear. dpkg-query -W lists
+// every package dpkg knows about, including ones removed with their config
+// files left behind — a host that has upgraded its kernel a dozen times reports
+// a dozen old linux-modules versions that are not on disk, and the oldest of
+// them sorts first and reads as the installed version. Only "installed" is
+// installed. An empty status means dpkg did not understand the field, in which
+// case the line is kept rather than the whole inventory silently vanishing.
 func ParseDpkg(out string) []Package {
 	var pkgs []Package
 	for _, line := range strings.Split(out, "\n") {
@@ -36,6 +44,11 @@ func ParseDpkg(out string) []Package {
 		if len(f) < 3 {
 			continue
 		}
+		if len(f) > 4 {
+			if s := strings.TrimSpace(f[4]); s != "" && s != "installed" {
+				continue
+			}
+		}
 		p := Package{Name: f[0], Version: f[1], Arch: f[2]}
 		if len(f) > 3 && f[3] != "" {
 			p.SourceName = f[3]

deploy/chart/vantage/Chart.yaml

@@ -2,5 +2,5 @@ apiVersion: v2
 name: vantage
 description: Helm chart for the Vantage stack (Redis, MongoDB, guacd, server, web)
 type: application
-version: 1.0.7
-appVersion: "1.0.7"
+version: 1.0.8
+appVersion: "1.0.8"

deploy/chart/vantage/values.yaml

@@ -92,8 +92,8 @@ ingress:
     api:
         enabled: false
         paths:
-            - /api
-            - /auth
+            - /api/
+            - /auth/
             - /update
             - /install
             - /update.ps1

docs/superpowers/plans/2026-08-12-instance-rename.md

@@ -0,0 +1,938 @@
+# Instance Rename in Vantage HQ — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let an HQ customer (owner or admin) rename a cloud instance, which re-derives its slug and moves it to a new DNS host, with staff able to do the same without the cooldown.
+
+**Architecture:** Slug derivation stays in `shared/provision`, beside the create path that already owns it. Admin reaches the control plane only through `cloudprov`, writing `instances` — a collection it already writes. Admin's own row (`admin_instances`) is updated second and carries the 24h cooldown timestamp, because the cooldown is admin's policy and the control plane has no opinion about it. The portal shows the new host and asks the customer to click through; it does not redirect.
+
+**Note:** This repo has no automated test suite and the user has ruled out adding test files. Every task verifies by build, vet and (Task 8) manual exercise.
+
+**Tech Stack:** Go 1.x (gin, mongo-driver v2), Next.js 16 App Router + TanStack Query + Tailwind 3 (`adminsite`).
+
+**Spec:** `docs/superpowers/specs/2026-08-12-instance-rename-design.md`
+
+## Global Constraints
+
+- A licence binds an instance **UUID**, not a slug. A rename must not issue a licence, call Paddle, or touch `licenses`, `subscriptions` or `entitlements`.
+- Admin's control-plane write boundary is unchanged: `cloudprov` writes `instances` and `users` only. Do not add a write to any other control-plane collection.
+- Customer rename is **cloud only**. Self-hosted is refused with the existing `selfHostedRefusal` constant and HTTP **400**, matching `members.go`.
+- Cooldown for customers is **24 hours**, tracked by `admin_instances.renamed_at`. Staff bypass it and must **not** write `renamed_at`.
+- No `-2` suffix loop on rename. A taken slug is a refusal (`ErrSlugTaken` → HTTP 409).
+- No component in `adminsite` may carry a hex colour; use the existing token classes (`text-ink-2`, `text-ink-3`, `border-rule`, `text-accent`, `text-expired`, `bg-panel-2`).
+- The host domain used for display is `vantage.hostxtra.co.uk`, already hardcoded in `adminsite/components/InstanceRecord.tsx` and the customer instance page.
+- Commit messages follow the repo's existing style: `feat: Sentence case summary` / `fix: …` / `docs: …`.
+
+---
+
+### Task 1: Slug derivation and the control-plane rename
+
+**Files:**
+- Modify: `shared/provision/instance.go`
+**Interfaces:**
+- Consumes: `BaseSlug(name string) (string, error)`, `ErrNameRejected` — both already in `shared/provision`.
+- Produces:
+  - `provision.ErrSlugTaken` (`error`)
+  - `provision.RenameSlug(name, currentSlug string) (string, error)`
+  - `provision.RenameInstance(ctx context.Context, db *mongo.Database, instanceID, name string) (*models.Instance, error)`
+  - `provision.RestoreInstanceIdentity(ctx context.Context, db *mongo.Database, instanceID, name, slug string) error`
+
+Behaviour `RenameSlug` must have, verified by reading rather than by test (this
+repo has no Go test suite and the user has ruled out adding one):
+
+| Input name | Current slug | Result |
+|---|---|---|
+| `Acme Ltd` | `acme` | `acme-ltd` |
+| `ACME!` | `acme` | `acme` — still derives to the current slug, so not a move |
+| `Acme` | `acme-2` | `acme` — a creation-time collision suffix derives from no name, so moving off it is a real move |
+| `ab` | any | `ErrNameRejected` |
+| `Admin` | any | `ErrNameRejected` (reserved) |
+| `!!!` | any | `ErrNameRejected` |
+| 50 `a`s | any | truncated to `MaxSlugLength`, exactly as `BaseSlug` truncates on create |
+
+- [ ] **Step 1: Write the implementation**
+
+Append to `shared/provision/instance.go`:
+
+```go
+// ErrSlugTaken means the slug a new name derives to already belongs to another
+// instance.
+//
+// Rename refuses rather than appending a counter the way creation does. Creation
+// appends because the customer is waiting on an instance and any free slug will
+// do; a rename is a request for one specific host, and silently landing them on
+// "acme-2" answers a question they did not ask.
+var ErrSlugTaken = errors.New("slug taken")
+
+// RenameSlug derives the slug a rename to name would move an instance to, given
+// the slug it holds now.
+//
+// It returns the current slug unchanged when the name still derives to it, so a
+// cosmetic edit — capitalisation, punctuation, a trailing "Ltd." — is not a move
+// and cannot collide with the instance's own slug.
+func RenameSlug(name, currentSlug string) (string, error) {
+	base, err := BaseSlug(name)
+	if err != nil {
+		return "", fmt.Errorf("%w: %s", ErrNameRejected, err.Error())
+	}
+	if base == currentSlug {
+		return currentSlug, nil
+	}
+	return base, nil
+}
+
+// RenameInstance changes an instance's name and re-derives its slug from it.
+//
+// The count-then-update is racy on its own, and is safe for the same reason
+// CreateInstanceWithID's loop is: instances.slug carries a unique index, so a
+// lost race surfaces as a duplicate-key error. Unlike creation there is nothing
+// to retry with — the caller asked for one specific name — so it becomes
+// ErrSlugTaken. Do not remove the duplicate-key branch, and do not remove the
+// index.
+func RenameInstance(ctx context.Context, db *mongo.Database, instanceID, name string) (*models.Instance, error) {
+	var inst models.Instance
+	if err := db.Collection("instances").FindOne(ctx,
+		bson.M{"instance_id": instanceID}).Decode(&inst); err != nil {
+		return nil, err
+	}
+
+	slug, err := RenameSlug(name, inst.Slug)
+	if err != nil {
+		return nil, err
+	}
+
+	if slug != inst.Slug {
+		n, err := db.Collection("instances").CountDocuments(ctx, bson.M{
+			"slug":        slug,
+			"instance_id": bson.M{"$ne": instanceID},
+		})
+		if err != nil {
+			return nil, err
+		}
+		if n > 0 {
+			return nil, fmt.Errorf("%w: %s", ErrSlugTaken, slug)
+		}
+	}
+
+	if _, err := db.Collection("instances").UpdateOne(ctx,
+		bson.M{"instance_id": instanceID},
+		bson.M{"$set": bson.M{"name": name, "slug": slug}}); err != nil {
+		if mongo.IsDuplicateKeyError(err) {
+			return nil, fmt.Errorf("%w: %s", ErrSlugTaken, slug)
+		}
+		return nil, err
+	}
+
+	inst.Name = name
+	inst.Slug = slug
+	return &inst, nil
+}
+
+// RestoreInstanceIdentity writes an exact name and slug back, unwinding a rename
+// whose caller-side bookkeeping then failed.
+//
+// It derives nothing. The values being restored may include a creation-time
+// collision suffix that no name derives to, so re-running RenameInstance with the
+// old name would not reproduce them.
+func RestoreInstanceIdentity(ctx context.Context, db *mongo.Database, instanceID, name, slug string) error {
+	_, err := db.Collection("instances").UpdateOne(ctx,
+		bson.M{"instance_id": instanceID},
+		bson.M{"$set": bson.M{"name": name, "slug": slug}})
+	return err
+}
+```
+
+- [ ] **Step 2: Build and vet**
+
+Run: `cd /go-projects/vantage && go build ./shared/... && go vet ./shared/provision/`
+Expected: clean.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add shared/provision/instance.go
+git commit -m "feat: Add instance rename to shared provisioning"
+```
+
+---
+
+### Task 2: Admin's row and the cloudprov wrappers
+
+**Files:**
+- Modify: `admin/internal/models/models.go` (the `Instance` struct, ~line 129; constants block near `RenewWindow`, ~line 105)
+- Modify: `admin/internal/cloudprov/cloudprov.go`
+
+**Interfaces:**
+- Consumes: `provision.RenameInstance`, `provision.RestoreInstanceIdentity` (Task 1).
+- Produces:
+  - `models.RenameCooldown` (`time.Duration`)
+  - `models.Instance.RenamedAt *time.Time` (bson `renamed_at`, json `renamed_at`)
+  - `cloudprov.RenameInstance(ctx context.Context, instanceID, name string) (*sharedmodels.Instance, error)`
+  - `cloudprov.RestoreInstanceIdentity(ctx context.Context, instanceID, name, slug string) error`
+
+- [ ] **Step 1: Add the cooldown constant**
+
+In `admin/internal/models/models.go`, directly beneath the `RenewWindow` block:
+
+```go
+// RenameCooldown is how long a customer must wait between renames of one
+// instance.
+//
+// A rename moves the instance's DNS host and invalidates every saved link to it,
+// so this exists to make that a considered act rather than a slider. Staff are
+// not subject to it: a support conversation about a name is already a human
+// deciding.
+const RenameCooldown = 24 * time.Hour
+```
+
+- [ ] **Step 2: Add the field to `Instance`**
+
+In the same file, inside the `Instance` struct, after `RelinkCount`:
+
+```go
+	// RenamedAt is when this instance last changed name, and backs the customer
+	// rename cooldown. It is a pointer because absent means "never renamed"; a
+	// zero time.Time would read as year 1 — an inert cooldown, but only by
+	// accident. Staff renames deliberately leave it alone.
+	RenamedAt *time.Time `bson:"renamed_at,omitempty" json:"renamed_at,omitempty"`
+```
+
+- [ ] **Step 3: Add the cloudprov wrappers**
+
+Append to `admin/internal/cloudprov/cloudprov.go`:
+
+```go
+// RenameInstance changes a cloud instance's name and moves it to the slug that
+// name derives to.
+//
+// It writes `instances` and nothing else, so admin's control-plane write
+// boundary is unchanged. It issues no licence: a licence binds the instance
+// UUID, which a rename never touches.
+func RenameInstance(ctx context.Context, instanceID, name string) (*sharedmodels.Instance, error) {
+	return provision.RenameInstance(ctx, db.ControlDB(), instanceID, name)
+}
+
+// RestoreInstanceIdentity puts an instance's previous name and slug back, for a
+// caller unwinding a rename whose admin-side write failed. Leaving the two
+// databases disagreeing would have HQ print a host that is not the host.
+func RestoreInstanceIdentity(ctx context.Context, instanceID, name, slug string) error {
+	return provision.RestoreInstanceIdentity(ctx, db.ControlDB(), instanceID, name, slug)
+}
+```
+
+- [ ] **Step 4: Build**
+
+Run: `cd /go-projects/vantage && go build ./admin/... ./shared/...`
+Expected: clean build, no output.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add admin/internal/models/models.go admin/internal/cloudprov/cloudprov.go
+git commit -m "feat: Add rename cooldown field and cloudprov rename"
+```
+
+---
+
+### Task 3: Customer rename endpoint
+
+**Files:**
+- Modify: `admin/internal/api/customer.go` (add handler; `loginURLFor` at ~line 442 is already in this file)
+- Modify: `admin/internal/api/routes.go` (~line 77, beside the other `/instances/:id/*` customer routes)
+
+**Interfaces:**
+- Consumes: `ownedInstance(c, id) (*models.Instance, bool)`, `selfHostedRefusal` (`members.go`), `loginURLFor(slug) string`, `cloudprov.RenameInstance`, `cloudprov.RestoreInstanceIdentity`, `models.RenameCooldown`, `provision.ErrSlugTaken`, `provision.ErrNameRejected`.
+- Produces: `PUT /api/instances/:id/name` returning `{instance_id, name, slug, login_url}`.
+
+- [ ] **Step 1: Write the handler**
+
+Append to `admin/internal/api/customer.go`:
+
+```go
+// renameInstance changes a cloud instance's name and moves it to the slug that
+// name derives to.
+//
+// The control plane is written FIRST, because instances.slug carries the unique
+// index and that index is what actually settles a race between two accounts
+// reaching for the same name. Admin's own row follows; if that write fails the
+// control plane is put back, because HQ printing a host that is not the host is
+// worse than a failed rename.
+//
+// No licence is issued and Paddle is not called: a licence binds the instance
+// UUID, and a rename does not change it.
+func renameInstance(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	if inst.Deployment != license.DeploymentCloud {
+		c.JSON(http.StatusBadRequest, gin.H{"error": selfHostedRefusal})
+		return
+	}
+	if inst.Placeholder {
+		c.JSON(http.StatusConflict, gin.H{"error": "this instance is not provisioned yet"})
+		return
+	}
+
+	var body struct {
+		Name string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+	name := strings.TrimSpace(body.Name)
+	if name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+
+	if inst.RenamedAt != nil {
+		if until := inst.RenamedAt.Add(models.RenameCooldown); time.Now().UTC().Before(until) {
+			c.JSON(http.StatusTooManyRequests, gin.H{
+				"error":       fmt.Sprintf("this instance was renamed recently; it can be renamed again after %s UTC", until.Format("2 Jan 2006 15:04")),
+				"retry_after": until,
+			})
+			return
+		}
+	}
+
+	ctx := c.Request.Context()
+	renamed, err := cloudprov.RenameInstance(ctx, inst.InstanceID, name)
+	switch {
+	case errors.Is(err, provision.ErrSlugTaken):
+		c.JSON(http.StatusConflict, gin.H{"error": "that name is already in use — try another"})
+		return
+	case errors.Is(err, provision.ErrNameRejected):
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": err.Error()})
+		return
+	case err != nil:
+		log.Printf("renameInstance: control plane rename of %s: %v", inst.InstanceID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not rename the instance"})
+		return
+	}
+
+	if _, err := db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": inst.InstanceID},
+		bson.M{"$set": bson.M{
+			"name":       renamed.Name,
+			"slug":       renamed.Slug,
+			"renamed_at": time.Now().UTC(),
+		}}); err != nil {
+		if rbErr := cloudprov.RestoreInstanceIdentity(ctx, inst.InstanceID, inst.Name, inst.Slug); rbErr != nil {
+			log.Printf("renameInstance: rollback of %s failed: %v", inst.InstanceID, rbErr)
+		}
+		log.Printf("renameInstance: record rename of %s: %v", inst.InstanceID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not rename the instance"})
+		return
+	}
+
+	s := auth.Current(c)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance.renamed", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: inst.Slug + " -> " + renamed.Slug, IP: c.ClientIP()})
+
+	c.JSON(http.StatusOK, gin.H{
+		"instance_id": inst.InstanceID,
+		"name":        renamed.Name,
+		"slug":        renamed.Slug,
+		// The same builder the licence emails use, rather than a second opinion
+		// about how a tenant host is spelled. Empty when APP_LOGIN_URL is unset.
+		"login_url": loginURLFor(renamed.Slug),
+	})
+}
+```
+
+- [ ] **Step 2: Check the imports**
+
+`customer.go` must import `errors`, `fmt`, `log`, `net/http`, `strings`, `time`, `audit`, `auth`, `cloudprov`, `db`, `models`, `license`, `provision`, `gin`, `bson`. Most are already there — add only what the compiler asks for. `provision` is `gitea.hostxtra.co.uk/mrhid6/vantage/shared/provision`; `license` is `gitea.hostxtra.co.uk/mrhid6/vantage/shared/license`.
+
+- [ ] **Step 3: Mount the route**
+
+In `admin/internal/api/routes.go`, in the `cust` group beside the other instance routes (after `cust.POST("/instances/:id/claim-free", …)`):
+
+```go
+		// Renaming moves the instance's DNS host, so it is owner-or-admin like
+		// every other instance mutation. Cloud only; the handler refuses the rest.
+		cust.PUT("/instances/:id/name",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			renameInstance)
+```
+
+- [ ] **Step 4: Build**
+
+Run: `cd /go-projects/vantage && go build ./admin/... && go vet ./admin/internal/api/`
+Expected: clean.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add admin/internal/api/customer.go admin/internal/api/routes.go
+git commit -m "feat: Add customer instance rename endpoint"
+```
+
+---
+
+### Task 4: Staff rename endpoint
+
+**Files:**
+- Modify: `admin/internal/api/staff.go`
+- Modify: `admin/internal/api/routes.go` (the `staff` group, beside `staff.POST("/instances/:id/relink", …)`)
+
+**Interfaces:**
+- Consumes: everything Task 3 consumes, plus `db.Admin`.
+- Produces: `PUT /api/staff/instances/:id/name` returning `{instance_id, name, slug}`.
+
+- [ ] **Step 1: Write the handler**
+
+Append to `admin/internal/api/staff.go`:
+
+```go
+// staffRenameInstance renames any instance, with no cooldown.
+//
+// It does NOT write renamed_at: a staff rename must not start the customer's
+// 24h clock, or fixing a name for someone locks them out of fixing it further.
+//
+// On self-hosted it changes admin's label only. There is no control-plane row to
+// write — the install is the customer's — and no slug, because self-hosted has
+// no tenant subdomain.
+func staffRenameInstance(c *gin.Context) {
+	var body struct {
+		Name string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+	name := strings.TrimSpace(body.Name)
+	if name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+
+	ctx := c.Request.Context()
+	var inst models.Instance
+	if err := db.Admin("admin_instances").FindOne(ctx,
+		bson.M{"instance_id": c.Param("id")}).Decode(&inst); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return
+	}
+
+	set := bson.M{"name": name}
+	slug := inst.Slug
+
+	if inst.Deployment == license.DeploymentCloud && !inst.Placeholder {
+		renamed, err := cloudprov.RenameInstance(ctx, inst.InstanceID, name)
+		switch {
+		case errors.Is(err, provision.ErrSlugTaken):
+			c.JSON(http.StatusConflict, gin.H{"error": "that name is already in use"})
+			return
+		case errors.Is(err, provision.ErrNameRejected):
+			c.JSON(http.StatusUnprocessableEntity, gin.H{"error": err.Error()})
+			return
+		case err != nil:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		slug = renamed.Slug
+		set["slug"] = renamed.Slug
+	}
+
+	if _, err := db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": inst.InstanceID}, bson.M{"$set": set}); err != nil {
+		if inst.Deployment == license.DeploymentCloud && !inst.Placeholder {
+			if rbErr := cloudprov.RestoreInstanceIdentity(ctx, inst.InstanceID, inst.Name, inst.Slug); rbErr != nil {
+				log.Printf("staffRenameInstance: rollback of %s failed: %v", inst.InstanceID, rbErr)
+			}
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: auth.Current(c).Email, Action: "instance.renamed", AccountID: inst.AccountID,
+		Target: inst.InstanceID, Detail: inst.Slug + " -> " + slug, IP: c.ClientIP()})
+
+	c.JSON(http.StatusOK, gin.H{"instance_id": inst.InstanceID, "name": name, "slug": slug})
+}
+```
+
+`staff.go` will need `errors`, `log`, `cloudprov` and `provision` added to its imports; `fmt`, `net/http`, `strings`, `time`, `audit`, `auth`, `db`, `models`, `license`, `bson` are already there.
+
+- [ ] **Step 2: Mount the route**
+
+In `routes.go`, in the `staff` group after `staff.POST("/instances/:id/relink", staffRelink)`:
+
+```go
+		staff.PUT("/instances/:id/name", staffRenameInstance)
+```
+
+- [ ] **Step 3: Build**
+
+Run: `cd /go-projects/vantage && go build ./admin/... && go vet ./admin/internal/api/`
+Expected: clean.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add admin/internal/api/staff.go admin/internal/api/routes.go
+git commit -m "feat: Add staff instance rename endpoint"
+```
+
+---
+
+### Task 5: `adminsite` API client and slug preview
+
+**Files:**
+- Create: `adminsite/lib/slug.ts`
+- Modify: `adminsite/lib/api.ts` (the `Instance` interface ~line 123; the `api` object's instance calls ~line 305; `api.staff` ~line 360)
+
+**Interfaces:**
+- Consumes: `PUT /api/instances/:id/name`, `PUT /api/staff/instances/:id/name` (Tasks 3 and 4).
+- Produces:
+  - `INSTANCE_DOMAIN`, `slugify(name: string): string`, `slugError(name: string): string | undefined` from `@/lib/slug`
+  - `RenameResult` interface, `api.renameInstance(id, name): Promise<RenameResult>`, `api.staff.renameInstance(id, name): Promise<RenameResult>`
+  - `Instance.renamed_at?: string`
+
+- [ ] **Step 1: Create the slug mirror**
+
+Create `adminsite/lib/slug.ts`:
+
+```ts
+/*
+ * A TypeScript mirror of shared/provision's slug rules, used ONLY to preview the
+ * host a rename would move an instance to while the customer types.
+ *
+ * It is a second implementation of Slugify, BaseSlug and ReservedSlugs, and it
+ * must change in the same commit as the Go one — the same hazard as
+ * web/lib/targets.ts. The preview is a courtesy; the server's 409 is the
+ * boundary, and the two are allowed to disagree without anything breaking.
+ */
+
+/** Mirrors provision.MinSlugLength / MaxSlugLength. */
+export const MIN_SLUG_LENGTH = 3;
+export const MAX_SLUG_LENGTH = 40;
+
+/** Mirrors provision.ReservedSlugs. */
+const RESERVED = new Set([
+    "www", "api", "app", "admin", "auth",
+    "install", "static", "_next", "default",
+]);
+
+/*
+ * The tenant subdomain namespace. Also hardcoded in InstanceRecord.tsx and the
+ * customer instance page; those predate this file and are left alone rather than
+ * refactored under a rename change.
+ */
+export const INSTANCE_DOMAIN = "vantage.hostxtra.co.uk";
+
+/** Mirrors provision.Slugify. */
+export function slugify(name: string): string {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+
+/** Mirrors provision.BaseSlug's truncation. */
+export function baseSlug(name: string): string {
+    return slugify(name).slice(0, MAX_SLUG_LENGTH);
+}
+
+/** The reason a name cannot become a slug, or undefined when it can. */
+export function slugError(name: string): string | undefined {
+    const base = slugify(name);
+    if (base.length < MIN_SLUG_LENGTH) {
+        return `Needs at least ${MIN_SLUG_LENGTH} letters or digits.`;
+    }
+    if (RESERVED.has(base.slice(0, MAX_SLUG_LENGTH))) {
+        return "That name is reserved.";
+    }
+    return undefined;
+}
+
+/** The host an instance on this slug is reached at. */
+export function hostFor(slug: string): string {
+    return `${slug}.${INSTANCE_DOMAIN}`;
+}
+```
+
+- [ ] **Step 2: Extend the API client**
+
+In `adminsite/lib/api.ts`, add `renamed_at` to `Instance` (after `relink_count`):
+
+```ts
+    renamed_at?: string;
+```
+
+Add the response type beside the other interfaces:
+
+```ts
+export interface RenameResult {
+    instance_id: string;
+    name: string;
+    slug: string;
+    /** Empty when APP_LOGIN_URL is unset on the server. */
+    login_url?: string;
+}
+```
+
+Add the call to the `api` object, after `renewInstance`:
+
+```ts
+    renameInstance: (id: string, name: string) =>
+        put<RenameResult>(`/api/instances/${id}/name`, { name }),
+```
+
+And to `api.staff`, after `relink`:
+
+```ts
+        renameInstance: (id: string, name: string) =>
+            put<RenameResult>(`/api/staff/instances/${id}/name`, { name }),
+```
+
+- [ ] **Step 3: Type-check**
+
+Run: `cd /go-projects/vantage/adminsite && npx tsc --noEmit`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add adminsite/lib/slug.ts adminsite/lib/api.ts
+git commit -m "feat: Add rename calls and slug preview to the HQ client"
+```
+
+---
+
+### Task 6: The rename panel and the customer instance page
+
+**Files:**
+- Create: `adminsite/components/RenamePanel.tsx`
+- Modify: `adminsite/app/(customer)/instances/[id]/page.tsx`
+
+**Interfaces:**
+- Consumes: `api.renameInstance` / `api.staff.renameInstance`, `RenameResult` (Task 5); `slugError`, `baseSlug`, `hostFor` (Task 5); `Panel`, `Note` (`@/components/Panel`), `Button` (`@/components/Button`), `Field` (`@/components/Field`), `ApiError` (`@/lib/api`).
+- Produces: `RenamePanel({ currentName, currentSlug, onRename })` — a default-collapsed control; `onRename` is `(name: string) => Promise<RenameResult>`.
+
+- [ ] **Step 1: Create the component**
+
+Create `adminsite/components/RenamePanel.tsx`:
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { Button } from "./Button";
+import { Field } from "./Field";
+import { Note } from "./Panel";
+import { ApiError, type RenameResult } from "@/lib/api";
+import { baseSlug, hostFor, slugError } from "@/lib/slug";
+
+/*
+ * The rename control, and only the control — the same shape as RelinkPanel: an
+ * input that expands in place rather than a modal, because this app has no modal
+ * and one action with one field does not need one.
+ *
+ * The host preview is drawn from lib/slug.ts, a mirror of the Go rules. It can
+ * disagree with the server; the 409 that comes back is the answer that counts.
+ */
+export function RenamePanel({
+    currentName,
+    currentSlug,
+    onRename,
+}: {
+    currentName: string;
+    currentSlug: string;
+    onRename: (name: string) => Promise<RenameResult>;
+}) {
+    const [open, setOpen] = useState(false);
+    const [value, setValue] = useState(currentName);
+    const [error, setError] = useState<string | undefined>();
+    const [busy, setBusy] = useState(false);
+    const [done, setDone] = useState<RenameResult | undefined>();
+
+    const name = value.trim();
+    const derived = baseSlug(name);
+    const invalid = slugError(name);
+    // A cosmetic edit that lands on the same slug is still a rename worth doing —
+    // the name is what the customer reads. Only an empty or unchanged name is
+    // nothing to submit.
+    const unchanged = name === currentName.trim();
+
+    async function submit() {
+        setError(undefined);
+        setBusy(true);
+        try {
+            const res = await onRename(name);
+            setDone(res);
+            setOpen(false);
+        } catch (err) {
+            setError(err instanceof ApiError ? err.message : "Rename failed. Try again.");
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    if (done) {
+        const host = done.login_url || `https://${hostFor(done.slug)}`;
+        return (
+            <Note tone="warn">
+                <span className="grid gap-2">
+                    <span>
+                        This instance is now <strong>{done.name}</strong>, at{" "}
+                        <span className="font-mono">{hostFor(done.slug)}</span>. The old address has stopped working, and your
+                        sign-in does not follow it — you will need to sign in again there.
+                    </span>
+                    <a href={host} className="justify-self-start font-mono text-[0.78rem] text-accent underline">
+                        Open {hostFor(done.slug)} &rarr;
+                    </a>
+                </span>
+            </Note>
+        );
+    }
+
+    return (
+        <div className="grid gap-3">
+            {open && (
+                <Field
+                    label="Instance name"
+                    value={value}
+                    onChange={(e) => setValue(e.target.value)}
+                    error={error ?? (name ? invalid : undefined)}
+                    hint={
+                        name && !invalid ? (
+                            <>
+                                Moves to <span className="font-mono">{hostFor(derived)}</span>
+                                {derived === currentSlug && " — the address does not change"}
+                            </>
+                        ) : (
+                            "Letters and digits; everything else becomes a hyphen."
+                        )
+                    }
+                />
+            )}
+            <div className="flex flex-wrap items-center gap-3">
+                <Button
+                    type="button"
+                    variant="line"
+                    disabled={busy || (open && (!name || Boolean(invalid) || unchanged))}
+                    onClick={() => (open ? submit() : setOpen(true))}
+                >
+                    {busy ? "Renaming…" : "Rename instance"}
+                </Button>
+                {open && (
+                    <span className="text-[0.82rem] text-ink-3">
+                        Anyone signed in will need to sign in again at the new address, and links to the old one stop working.
+                    </span>
+                )}
+            </div>
+        </div>
+    );
+}
+```
+
+`Note` is `({ tone = "accent" | "warn" | "expired", children })` and renders a `<p>`, which is why the success state wraps its two lines in a `<span className="grid gap-2">` rather than block elements.
+
+- [ ] **Step 2: Mount it on the customer instance page**
+
+In `adminsite/app/(customer)/instances/[id]/page.tsx`:
+
+Add the imports:
+
+```tsx
+import { RenamePanel } from "@/components/RenamePanel";
+```
+
+and
+
+```tsx
+import { useSession } from "@/lib/session";
+```
+
+Inside `InstancePage`, with the other hooks (hooks must precede the early returns already in this component):
+
+```tsx
+    // useSession is the app's one way to ask who the caller is — it shares the
+    // ["me"] query, so this adds no request.
+    const { session } = useSession();
+```
+
+and after the `cloud` const:
+
+```tsx
+    const mayRename = session?.account_role === "owner" || session?.account_role === "admin";
+```
+
+Then add the panel to `PageFrame`'s children, directly after the `MembersPanel` line:
+
+```tsx
+                {/*
+                 * Address rather than "Rename": the panel is about where this
+                 * instance lives, and the rename is how you change it. Cloud
+                 * only — a self-hosted install has no tenant subdomain for us to
+                 * move.
+                 */}
+                {cloud && mayRename && (
+                    <Panel title="Address" meta={host ?? undefined}>
+                        <p className="text-[0.86rem] text-ink-2">
+                            The instance name is where its address comes from. Renaming moves it to a new address and releases the old
+                            one, so saved links and bookmarks to it stop working.
+                        </p>
+                        <RenamePanel
+                            currentName={instance.name}
+                            currentSlug={instance.slug ?? ""}
+                            onRename={async (name) => {
+                                const res = await api.renameInstance(instance.instance_id, name);
+                                qc.invalidateQueries({ queryKey: ["account"] });
+                                return res;
+                            }}
+                        />
+                    </Panel>
+                )}
+```
+
+- [ ] **Step 3: Build**
+
+Run: `cd /go-projects/vantage/adminsite && npm run build`
+Expected: build succeeds.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add adminsite/components/RenamePanel.tsx "adminsite/app/(customer)/instances/[id]/page.tsx"
+git commit -m "feat: Let a customer rename a cloud instance from HQ"
+```
+
+---
+
+### Task 7: Staff instance page rename
+
+**Files:**
+- Modify: `adminsite/app/(staff)/staff/instances/[id]/page.tsx`
+
+**Interfaces:**
+- Consumes: `RenamePanel` (Task 6), `api.staff.renameInstance` (Task 5).
+- Produces: nothing later tasks depend on.
+
+- [ ] **Step 1: Add the panel**
+
+In `adminsite/app/(staff)/staff/instances/[id]/page.tsx`, add the imports:
+
+```tsx
+import { RenamePanel } from "@/components/RenamePanel";
+```
+
+and, inside `StaffInstancePage`, add `const qc = useQueryClient();` at the top of the component if it is not already there (`useQueryClient` is already imported for `EntitlementSection`).
+
+Add this panel after the "Licence history" panel:
+
+```tsx
+            {/*
+             * Staff rename has no cooldown and does not start the customer's:
+             * fixing a name on someone's behalf must not spend their next 24
+             * hours.
+             */}
+            <Panel title="Name" meta={data.instance.deployment === "cloud" ? "Moves the address" : "Label only"}>
+                <RenamePanel
+                    currentName={data.instance.name}
+                    currentSlug={data.instance.slug ?? ""}
+                    onRename={async (name) => {
+                        const res = await api.staff.renameInstance(data.instance.instance_id, name);
+                        qc.invalidateQueries({ queryKey: ["staff-instance", id] });
+                        return res;
+                    }}
+                />
+            </Panel>
+```
+
+- [ ] **Step 2: Build**
+
+Run: `cd /go-projects/vantage/adminsite && npm run build`
+Expected: build succeeds.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add "adminsite/app/(staff)/staff/instances/[id]/page.tsx"
+git commit -m "feat: Let staff rename an instance"
+```
+
+---
+
+### Task 8: Documentation and end-to-end verification
+
+**Files:**
+- Modify: `CLAUDE.md` (the Admin REST API route list, and the `admin_instances` note under MongoDB Collections)
+
+**Interfaces:**
+- Consumes: everything above.
+- Produces: nothing.
+
+- [ ] **Step 1: Update the Admin REST API route list**
+
+In `CLAUDE.md`, in the customer-session block, after the `POST /instances/:id/claim-free` line:
+
+```
+PUT  /instances/:id/name                       # rename a cloud instance; moves its slug (owner|admin, 24h cooldown)
+```
+
+and in the staff-session block, after `POST /instances/:id/issue · /instances/:id/relink`:
+
+```
+PUT  /instances/:id/name                       # rename any instance, no cooldown
+```
+
+- [ ] **Step 2: Add the design note**
+
+In `CLAUDE.md`, under "Grants project, they do not federate" (admin's control-plane write boundary is described nearby), add a short paragraph:
+
+```markdown
+**A rename moves the host, and the licence does not care.** `PUT
+/api/instances/:id/name` re-derives the slug from the new name through
+`provision.RenameSlug` — the same rules that named the instance at creation —
+and writes the control plane first, because `instances.slug`'s unique index is
+what settles a race between two accounts reaching for one name. A taken slug is
+a refusal, not an `acme-2`: creation appends a counter because any free slug
+will do, and a rename is a request for one specific host. A licence binds the
+instance UUID, so nothing is reissued and Paddle is not called. The old host
+keeps resolving for up to 60s (`instancehost.go`'s cache, which admin cannot
+reach into), and `km_session` is host-only, so the customer signs in again on
+the new address — the portal says so rather than redirecting them into a login
+screen with no explanation. The 24h cooldown lives on `admin_instances.renamed_at`
+because it is admin's policy; staff bypass it and must not write the field.
+```
+
+- [ ] **Step 3: Full build**
+
+Run:
+```bash
+cd /go-projects/vantage && go build ./... && go vet ./admin/... ./shared/... && (cd adminsite && npm run build)
+```
+Expected: all clean.
+
+- [ ] **Step 4: Manual verification against a running stack**
+
+Work through each and record the result:
+
+1. Rename a cloud instance from `/instances/<id>` as an owner. Panel reports the new host.
+2. In Mongo: `db.instances.findOne({instance_id})` and `db.admin_instances.findOne({instance_id})` agree on `name` and `slug`; `admin_instances.renamed_at` is set.
+3. The new host serves a login page. The old host stops resolving to the instance within ~60 seconds.
+4. A second rename inside 24 hours answers `429` with the unlock time.
+5. Renaming onto a slug another instance holds answers `409` and changes neither database.
+6. `PUT /api/instances/:id/name` on a self-hosted instance answers `400` with the `selfHostedRefusal` message.
+7. `GET /api/staff/audit` shows `instance.renamed` with `old-slug -> new-slug`.
+8. Staff rename of the same instance succeeds immediately and leaves `renamed_at` unchanged.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs: Document instance rename in HQ"
+```
+
+- [ ] **Step 6: Refresh the knowledge graph**
+
+```bash
+graphify update .
+```

docs/superpowers/specs/2026-08-12-api-tokens-openapi-design.md

@@ -0,0 +1,297 @@
+# API tokens and OpenAPI reference
+
+Date: 2026-08-12
+Status: approved, ready for implementation planning
+
+## Problem
+
+The only programmatic credential the control plane issues is the ESO secrets-read
+bearer token, which reaches exactly one endpoint. Everything else requires a
+browser session cookie. There is therefore no supported way to drive Vantage from
+CI, a script, or infrastructure-as-code, and no machine-readable description of
+the REST API for anyone who wants to try.
+
+This spec covers two deliverables that ship together: scoped API tokens, and an
+OpenAPI 3.1 document rendered as a live reference page. A Terraform provider is
+the intended follow-on and is explicitly out of scope here — it depends on both
+of these being settled, and it is a separate Go module with its own release
+cycle.
+
+## Goals
+
+- A person can mint a scoped, optionally expiring token and use it against the
+  existing REST API with no new endpoints to learn.
+- A leaked token is bounded by role, by scope, and by expiry policy.
+- Offboarding a person removes their tokens as a side effect of removing them.
+- The API has a machine-readable description that cannot silently drift from the
+  handlers it describes.
+- The reference page works on an air-gapped self-hosted install.
+
+## Non-goals
+
+- Token editing. Role and scopes are immutable; rotation replaces amendment.
+- OAuth device flow or any browser-based authorisation grant.
+- Per-server or per-tag restrictions on a token.
+- Instance-owned service tokens that outlive their creator.
+- The Terraform provider.
+- General API rate limiting beyond the per-token limit described below.
+
+## Part 1 — API tokens
+
+### Token format and storage
+
+A token is `vt_` followed by 32 random bytes, hex encoded. It is displayed once,
+at creation, and never again.
+
+Only the SHA-256 hash is stored, in a unique index. This follows the precedent
+already set by `servers.agent_token_hash` and the ESO read token. bcrypt is
+deliberately not used: the value is full-entropy random rather than a
+user-chosen password, so a fast hash is sufficient, and a per-token salt would
+force a collection scan where an indexed lookup is wanted.
+
+The first eight characters are stored in clear as `hint`, so the list can
+identify a token without revealing it.
+
+### Authentication path
+
+`auth.Middleware()` gains a fallback. When there is no `km_session` cookie it
+looks for `Authorization: Bearer vt_…`. Both paths end by placing a `*Session` in
+the gin context, so every handler, `auth.RequireRole`, `RequireActiveLicense`,
+`RequireFeature` and `actorFromCtx` continue to work unmodified.
+
+```
+Session{
+  UserID:     token.UserID
+  InstanceID: token.InstanceID
+  Role:       min(user.Role, token.Role)   // owner > admin > member
+  Email:      user.Email
+  TokenID:    token.TokenID                // "" for cookie sessions
+  Scopes:     token.Scopes                 // nil for cookie sessions
+}
+```
+
+The effective role is recomputed on every request rather than frozen at
+creation. Demoting the user demotes the token with them. No caching is required
+because the user document is already read to confirm the user still exists.
+
+The existing host guard applies identically. A token carries an `instance_id`,
+and a request arriving at a different instance's host is rejected exactly as a
+mismatched cookie session is. The tenant boundary must not have a token-shaped
+hole in it.
+
+`last_used_at` is written best-effort and only when the stored value is more
+than 60 seconds old, so it does not become a Mongo write per request.
+
+Rejections:
+
+| Condition            | Status | Body                                   |
+| -------------------- | ------ | -------------------------------------- |
+| No credential at all | 401    | `not authenticated`                    |
+| Unknown token        | 401    | `invalid token`                        |
+| Expired token        | 401    | `code: token_expired`                  |
+| Owning user deleted  | 401    | `invalid token`                        |
+| Missing scope        | 403    | names the required scope               |
+| Wrong instance host  | 403    | `instance host mismatch`               |
+
+### Data model
+
+New collection `api_tokens`, added to `services.ScopedCollections` so instance
+purge reaches it.
+
+```
+instance_id     string
+token_id        string
+user_id         string
+name            string    1-64 chars, unique per user
+hint            string    first 8 chars of the plaintext
+token_hash      string    sha256
+role            string    owner|admin|member
+scopes          []string
+expires_at      *time.Time  nil means never
+created_at      time.Time
+last_used_at    *time.Time
+created_by_ip   string
+```
+
+Indexes: unique on `token_hash`; compound on `(instance_id, user_id)`.
+
+Deleting a user deletes their tokens as part of the same service call as
+`DeleteInstanceUser`, so offboarding is one action rather than two.
+
+### Expiry policy
+
+Expiry is optional by default: a token may be created with no expiry at all.
+Instance settings gain `api_token_max_days *int`, editable by owner and admin:
+
+- `nil` — no cap; never-expire is allowed. This is the default, so an upgrade
+  changes nothing.
+- `n > 0` — a new token must expire within `n` days, and a never-expire token is
+  refused.
+
+Changing the setting does not retroactively invalidate existing tokens; it is a
+policy on issuance. Tokens already outside the new cap are flagged in the UI so
+that someone can rotate them deliberately, rather than discovering the change
+when a pipeline breaks.
+
+### Scopes
+
+Eight resources, each with `:read` and `:write`. Write implies read on the same
+resource.
+
+```
+servers    keys     secrets    workflows
+monitors   vulns    workloads  settings
+```
+
+Scope enforcement is a single middleware, `RequireScopes()`, mounted once in the
+`/api` stack. It derives the required resource from the matched gin route
+pattern using a map, rather than from a per-route decorator: a route registered
+without a decorator would otherwise be unguarded, and this repo already prefers
+guards that come from where a route is mounted rather than from someone
+remembering.
+
+- Cookie sessions skip the check entirely.
+- A token-authenticated request whose route pattern is absent from the map is
+  denied with 403. Fail closed.
+- A startup check fails boot if any registered `/api` route pattern is missing
+  from the map, so the failure surfaces at deploy rather than at the first call.
+
+Deliberate placements:
+
+- `keys:read` covers `GET /keys/:id/private-key`. Reading a private key is
+  reading a key.
+- `secrets:read` does not cover `GET /api/secrets/:group/values`. That endpoint
+  keeps its separate ESO bearer path and is unaffected by this work.
+- `workloads:write` covers both container control actions and log reads, which
+  are already restricted to owner and admin.
+- The token endpoints themselves map to the `settings` resource: `GET
+  /api/tokens` requires `settings:read`, and `POST` and `DELETE` require
+  `settings:write`. A token can therefore mint or revoke tokens only when
+  explicitly granted that scope, and never above its own role.
+
+### Endpoints
+
+```
+GET    /api/tokens        list; a member sees their own, owner|admin see all
+POST   /api/tokens        create; returns the plaintext once
+DELETE /api/tokens/:id    revoke; own always, owner|admin any
+```
+
+There is no `PUT`. Editing a token's role or scopes changes what a credential
+already deployed in a CI system can do, with no record of what it could do
+before. Rotation replaces amendment.
+
+`POST` body: `name`, `role`, `scopes[]`, `expires_in_days` (omitted means never,
+and is refused when `api_token_max_days` is set).
+
+Refusals: 400 for an unknown scope, 409 for a duplicate name for that user, 403
+for a role above the creator's own, 422 for an expiry beyond policy.
+
+### Web UI
+
+A new "API tokens" card in the Access group of `/settings`, alongside Members
+and single sign-on. Not a new nav entry — `/settings/instance` was folded back
+into `/settings` for precisely this reason, and the card lives in
+`web/components/settings/` with the others, reusing the shared `Field` and
+`inputClass`.
+
+The card lists name, hint, role, scope chips, last used, and expiry with a
+distinct state for expired and for over-policy. Revoke is per row and confirms.
+
+Create opens a modal. The plaintext is shown once in a `--well` block with
+copy-to-clipboard and an explicit line saying it will not be shown again.
+
+Members see only their own rows. Owner and admin get an "All tokens" toggle.
+
+`api_token_max_days` is a field on the same card, visible to owner and admin
+only.
+
+### Audit
+
+New events:
+
+- `token.created`
+- `token.revoked`
+- `token.expired_use` — a rejected expired token, which is how a forgotten CI
+  job becomes visible
+- `settings.token_policy_updated`
+
+The actor is the human's email throughout, so `actorFromCtx` needs no change.
+Every existing audit event written during a token-authenticated request gains
+`via: "token:<name>"` in its detail, so the log distinguishes a person clicking
+from their credential acting.
+
+### Rate limiting
+
+Token-authenticated requests are limited per token in Redis at 600 per minute,
+answering 429 with `Retry-After`. Cookie sessions are untouched. This is narrow
+on purpose: it is not the general API rate-limiting project, only enough that a
+runaway script cannot take an instance down.
+
+## Part 2 — OpenAPI and the reference page
+
+### Generation
+
+`swaggo/swag` v2, pinned, emitting OpenAPI 3.1. v1 emits Swagger 2.0, which
+Scalar renders poorly.
+
+Handlers in `server/internal/api/*.go` gain annotation comments. Request and
+response bodies that are currently anonymous inline structs become named
+structs. This is real churn across roughly fifteen files and is the honest cost
+of choosing generation over a hand-written document.
+
+The generated `server/internal/api/docs/openapi.json` is committed and embedded
+with `go:embed`, not generated during the image build: `server/Dockerfile`
+produces a `scratch` runtime from a Go build stage, and adding codegen there
+means putting the toolchain in the build image.
+
+`server-deploy.yml` gains a check that regenerates the spec and runs
+`git diff --exit-code`. An annotation edited without regenerating fails the
+build. Without this check the annotations are worth less than a hand-written
+document, because they would drift while appearing authoritative.
+
+### Serving
+
+```
+GET /api/openapi.json    the spec, session or token authenticated
+GET /api/docs            HTML page loading a vendored Scalar bundle
+```
+
+The Scalar standalone bundle is vendored under `server/internal/api/docs/`, with
+its version recorded in a comment beside it and refreshed by hand. No CDN:
+air-gapped self-hosted installs are supported, and a reference page that fails
+closed on an offline site is a support ticket.
+
+Because the page is served by the instance itself, "Try it" acts against the
+reader's own API with their own session.
+
+### Documented auth schemes
+
+Three, kept distinct:
+
+- `cookieAuth` — the `km_session` cookie.
+- `bearerAuth` — a `vt_…` API token.
+- The ESO secrets endpoint is marked as its own separate scheme, so nobody wires
+  a personal access token into External Secrets Operator.
+
+## Documentation
+
+- `docsite/docs/reference/api-tokens.md`: creating a token, the scope table,
+  curl examples, rotation, and the maximum-lifetime policy.
+- `CLAUDE.md`: the three token routes under REST API, the `api_tokens`
+  collection, and a note that `openapi.json` is generated and CI-verified.
+
+## Risks
+
+- The anonymous-struct-to-named-struct conversion is the bulk of the work and
+  touches handler code this feature otherwise has no business in.
+- The vendored Scalar bundle is a manual refresh that nobody will remember. The
+  version comment is the only mitigation.
+- A scope map keyed on gin route patterns breaks if a route path is renamed. The
+  boot-time completeness check is what turns that into a startup failure rather
+  than a silent 403 in production.
+
+## Follow-on work
+
+A Terraform provider, as its own spec and plan, consuming the tokens and the
+OpenAPI document produced here.

docs/superpowers/specs/2026-08-12-instance-rename-design.md

@@ -0,0 +1,236 @@
+# Instance rename in Vantage HQ
+
+**Date:** 2026-08-12
+**Status:** approved, not yet implemented
+
+## Problem
+
+A cloud instance is named once, at creation, and never again. The name is
+chosen in the first thirty seconds of a customer's relationship with the
+product — before they have decided whether this is "Acme" or "Acme
+Production" — and it is the name that becomes their DNS host, appears in every
+sign-in link and heads every page of their control plane. Today the only way to
+change it is to create a second instance and move, or to open a support ticket
+that has no tooling behind it.
+
+## What a rename is
+
+One customer-initiated action on a **cloud** instance: a new name, from which a
+new slug is derived, which moves the instance to a new DNS host.
+
+Name and slug move together. The slug is re-derived through
+`provision.BaseSlug`, so the rules that named the instance at creation are the
+rules that rename it — the same reserved-label list, the same 3–40 character
+bound, the same `Slugify` collapse of non-alphanumeric runs. There is no
+separate slug field for the customer to edit, because two fields invite the
+state where the name says one thing and the host says another, and that
+divergence is exactly what a rename exists to fix.
+
+A licence binds an instance **UUID**, not a slug. A rename therefore issues no
+licence, calls Paddle not at all, and consumes no relink. This is the property
+that makes the whole feature cheap, and it should be stated in any future change
+that tempts someone to touch the licence from this path.
+
+### What breaks, deliberately
+
+- **The old host stops working.** The old slug is released the moment the rename
+  commits; another account may take it. Bookmarks, saved sign-in links and any
+  agent install one-liner that named the web host are stale. Agents themselves
+  are unaffected — they dial `GRPC_HOST`, which is not per-tenant.
+- **The old host keeps working for up to 60 seconds.** `server/internal/auth/instancehost.go`
+  caches slug-to-instance lookups for 60s, and admin has no path to invalidate
+  another process's memory. The released slug can be claimed by another account
+  inside that window, so for up to a minute a replica still maps that host to the
+  previous tenant. No data is exposed — the host/session guard rejects a session
+  belonging to a different instance — but the new owner's users can briefly reach
+  the old tenant's instance on their own host, and see its login page rather than
+  theirs. Adding a cross-service invalidation channel for a 60-second window is
+  not worth the coupling.
+- **The customer must sign in again.** `km_session` is set with no `Domain`
+  attribute, so it is host-only and does not follow the instance to its new
+  subdomain. The UI says so rather than letting the customer discover it.
+
+## Scope
+
+| | Customer (owner or admin) | Staff |
+|---|---|---|
+| Cloud instance | rename, 24h cooldown | rename, no cooldown |
+| Self-hosted instance | refused, 400 | name only; there is no slug |
+| Cloud placeholder | refused, 409 | refused, 409 |
+
+Self-hosted is refused on the customer side for the same reason the member
+endpoints refuse it: there is no control-plane row to write. The install is the
+customer's, on their own database, and admin cannot reach it. Staff may still
+correct the label on admin's own row, because that label is what staff search
+by.
+
+## Data flow
+
+Two writes, in this order:
+
+1. **Control plane `instances`** — `{name, slug}`.
+2. **Admin `admin_instances`** — `{name, slug, renamed_at}`.
+
+The control plane goes first because `instances.slug` carries the unique index,
+and that index is what actually decides a race between two accounts reaching for
+the same name. Deciding it anywhere else would be guessing.
+
+If the second write fails, the first is rolled back best-effort — restoring the
+previous name and slug — and the request answers 500. Leaving them divergent
+would have HQ print a host that is not the host, which is worse than a failed
+rename.
+
+## Backend
+
+### `shared/provision/instance.go`
+
+```go
+// ErrSlugTaken means the derived slug belongs to another instance.
+var ErrSlugTaken = errors.New("slug taken")
+
+// RenameInstance changes an instance's name and re-derives its slug.
+func RenameInstance(ctx context.Context, db *mongo.Database, instanceID, name string) (*models.Instance, error)
+```
+
+It lives beside `CreateInstanceWithID` so slug derivation keeps one home, and it
+behaves as that function's rules imply:
+
+- `BaseSlug(name)` failures wrap `ErrNameRejected` — too short, too long,
+  reserved.
+- The derived slug is compared against the instance's current one. If they are
+  equal, only the name is written; a cosmetic capitalisation change is not a
+  move, and must not fail on its own slug.
+- **No `-2` suffix loop.** Creation appends a counter because the customer is
+  waiting on an instance and any free slug will do. A rename is a request for a
+  specific host, and silently landing the customer on `acme-2` is a worse answer
+  than refusing.
+- A duplicate-key error on the update surfaces as `ErrSlugTaken`, exactly as the
+  create path treats it as "that slug is taken". The pre-check is a courtesy;
+  the index is the boundary.
+
+### `admin/internal/cloudprov`
+
+```go
+func RenameInstance(ctx context.Context, instanceID, name string) (*sharedmodels.Instance, error)
+```
+
+A thin wrapper over `provision.RenameInstance` on `db.ControlDB()`. It writes
+`instances` and nothing else, so admin's documented control-plane write boundary
+— `instances` and `users`, from `cloudprov` and `inject` only — is unchanged.
+
+### `admin/internal/models`
+
+`Instance` gains:
+
+```go
+// RenamedAt is when this instance last changed name, and backs the 24h
+// customer cooldown. The cooldown is admin's policy, so it lives on admin's
+// row rather than in the control plane, which has no opinion about how often
+// a customer may move.
+RenamedAt *time.Time `bson:"renamed_at,omitempty" json:"renamed_at,omitempty"`
+```
+
+A pointer because absent means "never renamed", and a zero `time.Time` would
+read as 1 January year 1 — far enough in the past that the cooldown is inert,
+but only by accident.
+
+### `PUT /api/instances/:id/name` (customer)
+
+Mounted in the `cust` group behind `auth.RequireAccountRole(owner, admin)`, and
+resolving the instance through `ownedInstance` like every other instance route,
+so another account's instance answers 404 rather than 403.
+
+Body: `{"name": "..."}`, trimmed before use.
+
+Refusals, in the order checked:
+
+| Condition | Status | Body |
+|---|---|---|
+| `deployment != cloud` | 400 | `selfHostedRefusal`, the same constant and status the member endpoints already answer with |
+| `placeholder` | 409 | instance is not provisioned yet |
+| within 24h of `renamed_at` | 429 | includes the UTC time it unlocks |
+| `provision.ErrNameRejected` | 422 | the wrapped reason, verbatim |
+| `provision.ErrSlugTaken` | 409 | that name is already in use |
+
+Success returns `{"instance_id", "name", "slug", "login_url"}` and writes an
+audit entry `instance.renamed` with detail `<old-slug> -> <new-slug>`, so the
+history of a host is answerable from the audit log alone.
+
+`login_url` comes from the existing `loginURLFor(slug)`, which fills `{slug}`
+into `APP_LOGIN_URL` — the same builder the licence emails already use, rather
+than a second opinion about how a tenant host is spelled. It is empty when
+`APP_LOGIN_URL` is unset, and the portal then falls back to the host string it
+already composes from the slug in `InstanceRecord` and the instance page.
+
+### `PUT /api/staff/instances/:id/name`
+
+The same core, without the cooldown, actor recorded as the staff user. On a
+self-hosted instance it updates `admin_instances.name` only and does not call
+`cloudprov`.
+
+## Frontend (`adminsite`)
+
+### `lib/slug.ts`
+
+A TypeScript mirror of `provision.Slugify` and the length/reserved checks, used
+only to preview the resulting host while the customer types. It carries the same
+warning as `web/lib/targets.ts`: it is a second implementation and must change in
+the same commit as the Go one. The preview can disagree with the server — the
+409 is the answer that counts.
+
+### `components/RenamePanel.tsx`
+
+An inline panel, not a modal — `adminsite` has no modal component, and the
+codebase's idiom for a destructive-ish action with one input is `RelinkPanel`:
+a control that expands in place inside a `Panel`.
+
+Prefilled with the current name. Below the input, a live line reading
+`acme-ltd.vantage.hostxtra.co.uk` as the customer types, and a note that they
+will need to sign in again on the new host. Submit is disabled while the derived
+slug is unchanged or invalid.
+
+It lives in an "Address" panel on `app/(customer)/instances/[id]/page.tsx`,
+rendered only when the instance is cloud and `account_role` is `owner` or
+`admin`. The staff instance page mounts the same component against the staff
+route.
+
+`InstanceRecord` on the Overview page is not touched: it stays a summary, and
+the rename is a decision that deserves the detail page.
+
+### After a successful rename
+
+Invalidate `["account"]`, collapse the panel, and let the page redraw with the new
+name and host. The Console rail card shows the new host, with a note:
+
+> This instance now lives at `acme-ltd.vantage.hostxtra.co.uk`. You will need to
+> sign in again there.
+
+**No automatic redirect.** Sending the browser to the new host lands the customer
+on a login screen with no explanation, having just lost the HQ page they were
+standing on. The link is right there; they click it when they are ready.
+
+## Verification
+
+The repository has no Go test suite, so verification is build plus manual
+exercise, matching existing practice:
+
+- `go build ./...` in `shared` and `admin`; `npm run build` in `adminsite`.
+- Rename a cloud instance; confirm `instances` and `admin_instances` agree on
+  name and slug.
+- The new host serves a login page; the old host stops resolving to the instance
+  within ~60 seconds.
+- A second rename within 24 hours answers 429.
+- A rename onto an occupied slug answers 409 and changes nothing.
+- A rename attempt on a self-hosted instance from the customer portal answers
+  400, the same status and constant the member endpoints already answer with.
+- The audit log carries `instance.renamed` with both slugs.
+
+## Out of scope
+
+- Slug aliases or redirects from the old host. The control plane resolves one
+  slug per instance, and an alias table is a second identity to keep correct for
+  the sake of stale bookmarks.
+- Renaming from inside the control plane's own `/settings`. HQ owns instance
+  identity, the same way it owns licences and `hq`-sourced users; a second
+  writer would need the same collision handling and the same cooldown.
+- Any change to the licence, subscription or Paddle line items.

docsite/docs/getting-started/claim-free-licence.md

@@ -4,64 +4,73 @@ title: Claim a Free licence
 sidebar_label: Claim a Free licence
 ---
 
-A self-hosted install runs unlicensed until you give it a licence. Free is a
-real tier in both deployments, and you can claim one for your install from the
-HQ portal.
+A self-hosted install stays read-only until you give it a licence. You claim a
+Free one from Vantage HQ, and it takes a couple of minutes.
+
+:::warning An unlicensed install is read-only
+You can sign in and look around, but adding servers, keys, workflows and
+everything else is refused until a licence is installed. Do this before
+[adding your first server](./first-server.md).
+:::
 
 ## What a licence is
 
-A signed file. It carries the instance ID it belongs to, the tier, the server
-allowance, feature toggles and an expiry. The control plane verifies the
-signature locally.
+A signed file that names your instance, its tier, how many servers you may
+manage, which features are enabled and when it expires. Your install checks the
+signature itself, so it never has to reach Vantage HQ to work.
 
-A running instance does not need HQ to be reachable.
-
-:::info One Free per account, per deployment.
-The limit is enforced per account **and** deployment, so a Free cloud instance does not stop you claiming Free on a self-hosted install.
+:::info One Free licence per account, per deployment
+A Free cloud instance does not use up your Free self-hosted one. They are
+separate.
 :::
 
 ## 1. Find your instance ID
 
-In the control plane, go to **Settings → Licence**. The instance ID is shown there.
+Open the **Licence** page from the sidebar of your install. The instance ID is
+shown at the top, and it is the value Vantage HQ asks for.
 
-## 2. Create a free license
+## 2. Create the instance in Vantage HQ
 
 1. Sign in at [Vantage HQ](https://vantage-hq.hostxtra.co.uk). If you have no
-   account, see [Accounts and signup](../hq/accounts-and-signup.md).
-2. Click on the **Buy A Plan** button.
-3. Click on **Self Hosted** then click on the **Free** plan, then finally Paste the instance ID and give it a name you will recognise.
+   account yet, see [Accounts and signup](../hq/accounts-and-signup.md).
+2. On **Overview**, choose **License my own install**. Once you already have an
+   instance, the same page offers **Buy a plan** instead.
+3. Choose **Self-hosted**, then the **Free** plan.
+4. Paste your instance ID, give the instance a name you will recognise, and
+   click **Create licence**.
 
-You will then see the new instance on the **Overview** page.
+The new instance now appears on the **Overview** page.
 
-## 3. Downloading the free license
+## 3. Download the licence
 
-With the instance created go to the **Overview** page and expand the new instance.
-
-Click on the **View Instance Settings** button. You can then click on the **Download License** or the **Copy to clipboard** button.
+Expand the new instance on **Overview** and click **View Instance Settings**.
+From there, use **Download licence** or **Copy to clipboard**.
 
 ## 4. Install the licence
 
-Download the licence from HQ and paste it in the control plane at
-**Settings → Licence**.
+Back in your install, open the **Licence** page, paste the licence and save.
+Your instance confirms the licence was issued to it, then shows your tier,
+server allowance and expiry date.
 
-The instance validates the signature, checks the ID matches its own, and
-starts reporting the tier, allowance and expiry.
-
-:::info Cloud instances do **not** require installing the license as this is done automatically.
+:::info Cloud instances need none of this
+A cloud instance is licensed automatically when it is created. These steps are
+for self-hosted installs only.
 :::
 
 ## Renewing
 
-Free licences are renewable from HQ within a renewal window near expiry;
-outside that window you cannot renew early. See [Free tier](../hq/free-tier.md).
+Free licences run for a year. The renew button appears in Vantage HQ seven days
+before expiry and stays available after it, so a lapsed instance can still be
+rescued. See [Free tier](../hq/free-tier.md).
 
 ## Moving the install to new hardware
 
-Rebuilding produces a new instance ID, and a licence binds to a ID. Use
-**Relink** in HQ to move the licence across. The number of relinks per term is
-capped; the portal shows how many you have left.
+A rebuilt install gets a new instance ID, and a licence only works for the ID it
+was issued to. Use **Relink** in Vantage HQ to move the licence across. You get
+three relinks per term, and the portal shows how many are left.
 
 ## Next
 
+- [Add your first server](./first-server.md)
 - [Licensing and entitlements](../hq/licensing-and-entitlements.md)
 - [Buying a paid self-hosted licence](../hq/self-hosted-instances.md)

docsite/docs/getting-started/cloud-vs-self-hosted.md

@@ -4,64 +4,62 @@ title: Cloud or self-hosted
 sidebar_label: Cloud or self-hosted
 ---
 
-Vantage runs in two deployments. They are the same software; what differs is
-who operates it and how licensing, users and data lifecycle work.
+Vantage runs in two ways. It is the same software; what differs is who runs it,
+and how licensing and user accounts work.
 
 ## At a glance
 
-|                       | Cloud                                               | Self-hosted                    |
-| --------------------- | --------------------------------------------------- | ------------------------------ |
-| Who runs it           | We do                                               | You do                         |
-| Where you sign in     | `<your-slug>.vantage.hostxtra.co.uk`                | Your own hostname              |
-| Database and backups  | Ours                                                | Yours                          |
-| Licence               | Written for you when you buy or create the instance | Pasted in, or claimed from HQ  |
-| Team members          | Granted from HQ; the instance holds a projection    | Created in the instance itself |
-| Free tier             | Yes, one per account                                | Yes, one per account           |
-| Expired Free instance | Eventually deleted, after warning                   | Never deleted                  |
+|                       | Cloud                                       | Self-hosted                    |
+| --------------------- | ------------------------------------------- | ------------------------------ |
+| Who runs it           | We do                                       | You do                         |
+| Where you sign in     | `<your-slug>.vantage.hostxtra.co.uk`        | Your own hostname              |
+| Database and backups  | Ours                                        | Yours                          |
+| Licence               | Installed for you                           | You paste it in                |
+| Team members          | Granted from Vantage HQ                     | Created in the instance itself |
+| Free tier             | Yes, one per account                        | Yes, one per account           |
+| Expired Free instance | Eventually deleted, after warning emails    | Never deleted                  |
 
 ## Cloud
 
-You create an instance from the HQ portal and it exists a few seconds later,
-already licensed. People you grant access to get a real user inside that
-instance see [People and roles](../hq/people-and-roles.md) but HQ owns their
-password, role and existence.
+You create an instance from the Vantage HQ portal and it is ready seconds later,
+already licensed. People you grant access to get a real account inside that
+instance, but Vantage HQ owns their password and role. See
+[People and roles](../hq/people-and-roles.md).
 
-:::info The instance does not phone home
-A grant writes a user row into the control plane once. After that the instance
-authenticates that person entirely on its own. HQ being down does not stop
-anyone signing in to a running instance.
-:::
+Your instance keeps working whether or not Vantage HQ is reachable. Signing in
+and managing servers never depend on it.
 
-Cloud instances on the Free tier are reaped after their licence expires, with
-warning emails first. See [Free tier](../hq/free-tier.md).
+Cloud instances on the Free tier are deleted some time after their licence
+expires, with warning emails first. See [Free tier](../hq/free-tier.md).
 
 ## Self-hosted
 
-You run the Docker Compose stack on your own infrastructure. Nothing about the
-control plane requires an internet connection to HQ at runtime a licence is a
-signed file, verified locally.
+You run Vantage with Docker Compose on your own infrastructure. It needs no
+connection to us at runtime, because a licence is a signed file your install
+checks for itself.
 
 Two ways to get one:
 
-1. **Free** link the install to an HQ account and claim it
-   ([Claim a Free licence](./claim-free-licence.md)).
-2. **Paid** buy from HQ, which creates a placeholder, then paste the install's
-   real instance UUID to bind and issue
-   ([Self-hosted instances](../hq/self-hosted-instances.md)).
+1. **Free.** Link the install to a Vantage HQ account and claim it. See
+   [Claim a Free licence](./claim-free-licence.md).
+2. **Paid.** Buy from Vantage HQ, then paste your install's instance ID to have
+   the licence issued. See
+   [Self-hosted instances](../hq/self-hosted-instances.md).
 
-Self-hosted users are local (or OIDC). There is no projection from HQ, and the
-three member endpoints in HQ refuse to touch a self-hosted instance at all.
+People who sign in to a self-hosted install are created in the install itself,
+either with a password or through single sign-on. Vantage HQ cannot add them for
+you.
 
 ## Which should you pick
 
-Pick cloud if you want the thing running now and do not want to own a MongoDB.
+Pick cloud if you want it running today and would rather not run a database.
 Pick self-hosted if your policy requires the control plane inside your own
-network, or the servers you manage cannot reach the public internet.
+network, or the servers you manage cannot reach the internet.
 
-Moving between them is a migration, not a switch instances are bound to a
-deployment at creation, and a licence binds to an instance UUID.
+Moving between the two means migrating your data, and a new licence, since a
+licence is tied to one instance.
 
 ## Next
 
 - [Self-hosted install](./self-hosted-install.md)
-- [Accounts and signup](../hq/accounts-and-signup.md) if you are going cloud
+- [Accounts and signup](../hq/accounts-and-signup.md), if you are going cloud

docsite/docs/getting-started/first-login.md

@@ -6,67 +6,82 @@ sidebar_label: First login
 
 A fresh install has no users and no instance. The first visit creates both.
 
-## 1. Bootstrap
+## 1. Create the first account
 
-Open the control plane in a browser. Because no user exists, you land on
-`/setup`.
+Open your Vantage address in a browser. Because no user exists yet, you land on
+the setup page.
 
 Fill in:
 
-| Field         | Notes                                 |
-| ------------- | ------------------------------------- |
-| Instance name | Display name. Shown throughout the UI |
-| Email         | Becomes your sign-in identity         |
-| Password      | Stored bcrypt-hashed                  |
+| Field            | Notes                                                     |
+| ---------------- | --------------------------------------------------------- |
+| Instance name    | Also used to derive your instance's own subdomain          |
+| Owner email      | Becomes your sign-in identity                              |
+| Password         | At least 8 characters                                      |
+| Confirm password | Must match                                                 |
 
-Submitting creates the instance and its **owner** you.
+**Setup Instance** creates the instance and makes you its **owner**.
 
-:::warning Bootstrap works exactly once
-The endpoint is open only while the database has no users. As soon as the first
-one exists, There is no second chance to create the first owner, so record the
-credentials before you continue.
+:::warning Your instance gets its own address
+If you installed on a name like `vantage.example.com`, an instance called Acme
+signs in at `acme.vantage.example.com`, and each instance keeps its own sign-in.
+Make sure DNS and your reverse proxy cover that subdomain, or use a wildcard.
 :::
 
-## 2. Copy the Instance ID
+:::warning Setup runs exactly once
+It is only available while the database has no users. Once yours exists, the
+page closes for good, so record the email and password before you continue.
+:::
 
-Once you have finished setup you will see the successfully created page.
+## 2. Copy the instance ID
 
-This will show the Instance ID. You will need this ID when creating a license in the HQ.
+The confirmation page, headed **Instance created**, shows your instance ID and
+your sign-in address. You need that ID to claim a licence in Vantage HQ, and it
+is the reference support works from. You can find it again later on the
+**Licence** page in the sidebar.
 
 ## 3. Sign in
 
-Click the continue to sign in button on the successful setup page.
-
-You will be taken to `/login`. Sign in with the email and password you just set.
+Click **Go to sign in**, then sign in with the email and password you just set.
 
 ## 4. Look around
 
-You land on the servers dashboard, which is empty. The sidebar is the whole
-product:
+You land on the servers page, which is empty. The sidebar is the whole product:
 
-| Section   | What it does                               |
-| --------- | ------------------------------------------ |
-| Servers   | The server enrol, inspect, console, update |
-| Keys      | SSH public keys and their assignments      |
-| Workflows | Compose and run scripted work              |
-| Steps     | The reusable step library                  |
-| Monitors  | HTTP, TCP, ICMP and TLS checks             |
-| Secrets   | The encrypted vault                        |
-| Audit     | Every mutating action                      |
-| Settings  | Members, SSO, alerts, retention, licence   |
+| Section         | What it does                                     |
+| --------------- | ------------------------------------------------ |
+| Servers         | Your fleet: enrol, inspect, console, update      |
+| Monitors        | HTTP, TCP, ping and certificate checks           |
+| Vulnerabilities | Known security issues in installed packages      |
+| Workloads       | Containers and services running on your servers  |
+| SSH Keys        | Public keys and which servers they are on        |
+| Secrets         | The encrypted vault                              |
+| Workflows       | Compose and run scripted work                    |
+| Steps           | The reusable step library                        |
+| Audit Log       | A record of everything that changed              |
+| Licence         | Your tier, allowance and expiry                  |
+| Settings        | People, sign-in, alerts and integrations         |
 
-## 5. Add the rest of your team
+**Licence** and **Settings** are shown only to owners and admins.
 
-Go to **Settings → Access**. Add members with a role:
+## 5. Install your licence
 
-| Role     | Can                                                |
-| -------- | -------------------------------------------------- |
-| `owner`  | Everything, including billing-adjacent settings    |
-| `admin`  | Everything except owner-only settings              |
-| `member` | Day-to-day work servers, keys, workflows, monitors |
+Until a licence is installed, the instance is read-only: you can look, but you
+cannot add servers or anything else. Continue with
+[Claim a Free licence](./claim-free-licence.md).
 
-Settings and organisation management require `owner` or `admin`.
+## 6. Add the rest of your team
 
-If you would rather not manage passwords, configure single sign-on instead: see [Settings](../vantage/settings.md#single-sign-on).
+Go to **Settings → Access** and add people with a role:
 
-You can add more than one identity provider; each gets its own button on the login page, and no buttons appear at all until at least one provider is configured.
+| Role     | Can                                                  |
+| -------- | ---------------------------------------------------- |
+| `owner`  | Everything                                           |
+| `admin`  | Everything except owner-only settings                |
+| `member` | Day-to-day work: servers, keys, workflows, monitors  |
+
+Changing settings, and adding or removing people, needs `owner` or `admin`.
+
+If you would rather not manage passwords, you can use single sign-on instead,
+which is available on paid plans. See
+[Settings](../vantage/settings.md#single-sign-on).

docsite/docs/getting-started/first-server.md

@@ -4,64 +4,67 @@ title: Add your first server
 sidebar_label: Add your first server
 ---
 
-Enrolling a server means running one command on it. The control plane issues a
-short-lived token, the install script fetches the agent and writes a config, and
-the machine registers itself.
+Enrolling a server means running one command on it. Vantage issues a short-lived
+token, the install script fetches the agent and writes a config file, and the
+machine registers itself.
+
+:::info You need a licence first
+An unlicensed install is read-only, so **Add server** will be refused until a
+licence is in place. If you have not done that yet, start with
+[Claim a Free licence](./claim-free-licence.md).
+:::
 
 ## 1. Create the enrolment
 
-In the UI, go to **Servers → Add server** Then click the **Generate Install Command** button.
-This generates a server ID and a pre-registration token
+Go to **Servers → Add server**, then click **Generate install command**. Vantage
+creates a server record and an enrolment token for it.
 
-:::warning The token is single-use and lives one hour
-It is the only credential in the flow, and it is spent the moment the agent registers.
+:::warning The token is single-use and lasts one hour
+It is the only credential in the flow, and it is spent the moment the agent
+registers. If it expires, generate a new command rather than reusing the old one.
 :::
 
 ## 2. Run the one-liner
 
 ### Linux
 
-Run the generated install script as root.
-
-Here is an example of the install script:
+Run the generated command as root. It looks like this:
 
 ```bash
 curl -fsSL "https://vantage.example.com/install?server_id=<id>&token=<token>" | bash
 ```
 
-What the script does:
+The script:
 
-1. Detects architecture `x86_64` and `aarch64` only; anything else exits.
-2. Downloads the binary and `checksums.txt`, and **verifies the SHA-256**, aborting on a mismatch.
-3. Installs to `/usr/local/bin/vantage-agent`, mode `0755`.
-4. Writes the config file at `/etc/vantage/config.yaml`
-    1. This contains the server ID, the pre-registration token and the gRPC host.
-5. Writes the systemd service file `/etc/systemd/system/vantage-agent.service` and starts the agent.
+1. Checks the architecture. Only `x86_64` and `aarch64` are supported.
+2. Downloads the agent and verifies its SHA-256 checksum, stopping on a mismatch.
+3. Installs the agent to `/usr/local/bin/vantage-agent`.
+4. Writes `/etc/vantage/config.yaml` with the server ID, the enrolment token and
+   the address the agent connects to.
+5. Installs and starts the `vantage-agent` systemd service.
 
 ### Windows
 
+Run this from an elevated PowerShell prompt:
+
 ```powershell
 irm "https://vantage.example.com/install.ps1?server_id=<id>&token=<token>" | iex
 ```
 
-Run from an elevated PowerShell.
+It writes the config to `%ProgramData%\vantage\config.yaml`, installs the agent
+as a Windows service and starts it.
 
-What the script does:
-
-1. Creates the config at `%ProgramData%\vantage\config.yaml`.
-    1. This contains the server ID, the pre-registration token and the gRPC host.
-2. Downloads the agent MSI from Gitea.
-3. Installs the MSI and creates the Windows service.
-4. Starts the agent.
-
-:::info Windows agents do **not** manage `authorized_keys` as this is a Linux-only function.
+:::info Windows servers do not get SSH key management
+Windows agents register, report inventory and run workflow steps. Managing
+`authorized_keys` is a Linux-only feature.
 :::
 
 ## 3. Watch it come up
 
-The server appears immediately as `pending`. Within one poll interval, 30 seconds it becomes `active`.
+The server appears as `pending` straight away, and becomes `active` within about
+30 seconds.
 
-Check the systemd logs using the following commands:
+On Linux you can watch the agent itself:
 
 ```bash
 systemctl status vantage-agent
@@ -70,28 +73,30 @@ journalctl -u vantage-agent -f
 
 ## 4. Confirm it works
 
-Open the server's detail page. Within a minute or two you should see:
+Open the server's page. Within a minute or two you should see:
 
-- Status `active`, with a recent last-seen timestamp.
-- Inventory CPU, memory, swap, partitions, kernel. Metrics refresh every 30
-  seconds; the full static snapshot every 15 minutes.
-- Pending OS updates, checked hourly.
+- Status `active`, with a recent last-seen time.
+- Inventory: CPU, memory, swap, partitions and kernel. Metrics refresh every 30
+  seconds, and the fuller snapshot every 15 minutes.
+- Any pending OS updates, which the agent checks for hourly.
 
 ## If it does not appear
 
-| Symptom                                    | Cause                                                                                                                             |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| Script exits at "Unsupported architecture" | Not amd64 or arm64                                                                                                                |
-| "Checksum mismatch!"                       | Interrupted download, or a proxy rewriting the body. Re-run                                                                       |
-| "Could not determine latest agent version" | The host cannot reach `gitea.hostxtra.co.uk`, or no `agent/v*` release exists                                                     |
-| Service runs, server stays `pending`       | The machine cannot reach `GRPC_HOST`. Test it from that machine                                                                   |
-| Registers once then goes `offline`         | Reachable for `Register` but not for the poll usually a firewall that permits the initial connection but drops the long-lived one |
+| Symptom                                    | What to check                                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| Script stops at "Unsupported architecture" | The machine is not 64-bit x86 or ARM                                                                    |
+| "Checksum mismatch!"                       | An interrupted download, or a proxy rewriting the response. Run it again                                |
+| "Could not determine latest agent version" | The machine cannot reach the release host, or `GITEA_HOST` is not set on your control plane             |
+| Service runs, server stays `pending`       | The machine cannot reach the agent port. Test it from that machine, not from the control plane          |
+| Registers, then goes `offline`             | A firewall or proxy allows the first connection but drops the long-lived one                            |
+| "Server limit reached"                     | Your licence allowance is full. Raise it in Vantage HQ, or remove a server you no longer manage         |
 
-A server is marked `offline` when its last-seen time passes the threshold; that
-sweep runs every two minutes, so allow for it before concluding anything.
+A server is marked `offline` once it has not been seen for a while, and that
+check runs every couple of minutes, so give it a moment before concluding
+anything.
 
-## Next Steps
+## Next steps
 
 - [Assign an SSH key](../vantage/ssh-keys.md)
 - [Run a workflow](../vantage/workflows.md)
-- [Claim a Free licence](./claim-free-licence.md)
+- [Watch something with a monitor](../vantage/monitors.md)

docsite/docs/getting-started/self-hosted-install.md

@@ -4,52 +4,46 @@ title: Install Vantage (self-hosted)
 sidebar_label: Self-hosted install
 ---
 
-This installs the control plane on a host you own. Budget about fifteen minutes.
+This puts the control plane on a host you own. Budget about fifteen minutes.
 
 ## Before you start
 
 You need:
 
 - A Linux host with **Docker** and the **Compose plugin**.
-- A DNS name pointing at it. You will use it for both the web UI and, with a
-  port, for agents.
-- A reverse proxy terminating TLS in front of the web UI. gRPC on `:9090` is
-  reached directly by agents.
-- Two ports reachable from every machine you intend to manage: the web port for
-  people, and **9090** for agents.
-- Outbound access from the control plane, and from every managed machine, to
-  `gitea.hostxtra.co.uk`, which serves the agent releases.
+- A DNS name pointing at that host. People use it for the web UI, and your
+  agents use it too.
+- A reverse proxy in front of Vantage that terminates TLS. It needs to handle
+  both the web UI and the agent port, `9090`, which speaks HTTP/2.
+- Those two ports reachable: the web port from wherever your people are, and
+  `9090` from every machine you intend to manage.
+- Outbound access from the control plane, and from each managed machine, to
+  `gitea.hostxtra.co.uk`, which serves the agent downloads.
 
-The stack itself brings MongoDB, Redis and guacd with it. You do not need to
-provide a database.
+The stack brings MongoDB, Redis and the console daemon with it, so there is no
+database to provide.
 
-## 1. Get the compose file
-
-Put `deploy/docker-compose.yml` from the repository in a working directory, for
-example `/opt/vantage`.
+## 1. Get the Compose file
 
 ```bash
-mkdir -p /opt/vantage/data && cd /opt/vantage
-# copy docker-compose.yml here
+mkdir -p /opt/vantage && cd /opt/vantage
+curl -fsSLO https://gitea.hostxtra.co.uk/mrhid6/vantage/raw/branch/main/deploy/docker/docker-compose.yml
 ```
 
-The `server` service bind-mounts `./data`, which is where workflow run logs are
-written. Create it before first boot so it is not owned by root-in-container in
-a way you did not intend.
-
 ## 2. Write the environment file
 
 Create `/opt/vantage/.env`:
 
 ```bash
-# The host:port agents dial. NOT the web URL this port speaks gRPC.
+# The host:port your agents connect to. This is not the web URL;
+# this port speaks gRPC.
 GRPC_HOST=vantage.example.com:9090
 
-
-# 32 bytes as 64 hex characters. Generate with the command below.
+# 32 bytes as 64 hex characters. Generate it with the command below.
 KEY_ENCRYPTION_KEY=
 
-# Optional: where workflow run logs are written inside the container.
+# The host serving agent downloads.
+GITEA_HOST=gitea.hostxtra.co.uk
 ```
 
 Generate the encryption key:
@@ -58,17 +52,27 @@ Generate the encryption key:
 openssl rand -hex 32
 ```
 
-:::danger Keep the encryption key
-`KEY_ENCRYPTION_KEY` encrypts SSH private keys, vault secrets, OIDC client
-secrets and console credentials with AES-256-GCM. Lose it and every one of those
-becomes unreadable there is no recovery path. Back it up somewhere other than
-the server it protects, and never rotate it without a planned re-encryption.
+Then make sure the `server` service passes `GITEA_HOST` through, by adding this
+line to its `environment:` block in `docker-compose.yml`:
+
+```yaml
+GITEA_HOST: ${GITEA_HOST}
+```
+
+Without it, the install command you hand to a new server cannot work out which
+agent to download.
+
+:::danger Keep the encryption key safe
+`KEY_ENCRYPTION_KEY` encrypts SSH private keys, vault secrets, single sign-on
+client secrets and console credentials. If you lose it, all of those become
+unreadable and there is no way to recover them. Back it up somewhere other than
+the server it protects, and do not change it once the install is in use.
 :::
 
 :::warning `GRPC_HOST` has no default
-The server refuses to boot without it. There is deliberately no fallback to the
-web host: that would hand every agent a port that does not speak gRPC, and the
-failure would only surface later, on each agent, as a connection error.
+The server will not start without it. There is deliberately no fallback to your
+web address, because that port does not speak the protocol agents use, and the
+mistake would only show up later as every agent failing to connect.
 :::
 
 ## 3. Start the stack
@@ -78,31 +82,37 @@ docker compose up -d
 docker compose ps
 ```
 
-Five services come up: `mongo`, `redis`, `guacd`, `server` and `web`.
+Five services start: `mongo`, `redis`, `guacd`, `server` and `web`.
 
-Check the server got through boot:
+Check the server got through startup:
 
 ```bash
 docker compose logs -f server
 ```
 
-Boot runs database migrations, builds indexes and seeds the default workflow
-step library. Index builders for auth and settings are **fatal on failure** —
-they enforce tenant isolation, so the server would rather not start than start
-without them.
+On first boot it prepares the database and loads the built-in workflow step
+library. If it stops during that, it will say why, and it is meant to stop
+rather than run in a half-prepared state.
 
 ## 4. Put a proxy in front
 
 Point your reverse proxy at `web` on port `3000` and terminate TLS there. The
-web app calls the REST API through a Next rewrite, so you do not need to expose
-`8080` publicly.
+web app reaches the API internally, so there is no need to publish port `8080`.
 
-Do **not** proxy `9090`. Agents connect to it directly over TLS.
+Agents connect to port `9090`. Vantage does not terminate TLS itself, so put
+that port behind your proxy too, with a certificate valid for the name in
+`GRPC_HOST`. The proxy must speak HTTP/2 through to Vantage. Many do not do so
+by default, and the symptom is agents that register once and then stop
+responding.
+
+For a private network where TLS is not required, you can instead set
+`tls: false` in each [agent's config](../reference/agent-config.md) and let
+agents reach the port directly.
 
 ## 5. First sign-in
 
-Open your hostname in a browser. With no users in the database, you are sent to
-`/setup`.
+Open your hostname in a browser. With no users in the database yet, you are sent
+to the setup page.
 
 Continue with [First login](./first-login.md).
 
@@ -113,23 +123,24 @@ Continue with [First login](./first-login.md).
 | `docker compose ps`                            | five services `running`         |
 | `curl -s localhost:8080/auth/bootstrap-status` | JSON saying bootstrap is needed |
 | `nc -z your-host 9090`                         | open                            |
-| `docker compose logs server \| grep -i fatal`  | nothing                         |
+| `docker compose logs server`                   | no fatal errors                 |
 
 ## Common install problems
 
-**Server exits immediately.** Almost always a missing `GRPC_HOST`. The log line
+**The server exits immediately.** Almost always a missing `GRPC_HOST`. The log
 names it.
 
-**Agents register but never go active.** They reached `:9090` for `Register` but
-cannot sustain the poll, or `GRPC_HOST` names a host they resolve differently.
-Check from the managed machine, not from the control plane host.
+**Agents register but never go active.** They reached port `9090` once but
+cannot hold the connection, or your proxy is not passing HTTP/2 through. Test
+from the managed machine, not from the control plane host.
 
-**Secrets pages error.** `KEY_ENCRYPTION_KEY` is empty or not 64 hex characters.
+**Secrets pages show an error.** `KEY_ENCRYPTION_KEY` is empty or is not 64 hex
+characters.
 
 More in [Troubleshooting](../reference/troubleshooting.md).
 
-## What this install does not include
+## What is not included
 
-The website, the HQ portal and this documentation site are hosted by us and are
-not part of a self-hosted install. It deliberately runs none of them, and in
-particular never holds the licence signing key.
+The marketing site, the Vantage HQ portal and this documentation site are hosted
+by us. A self-hosted install runs none of them, and it never holds the key that
+signs licences.

docsite/docs/getting-started/what-is-vantage.md

@@ -5,59 +5,52 @@ sidebar_label: What is Vantage
 ---
 
 Vantage manages a fleet of servers from one place. It began as SSH key
-management and grew outwards: key assignment, scripted workflow execution,
-service monitoring, a secrets vault, a browser-based console and OS update
-management.
+management and grew outwards: key assignment, scripted workflows, service
+monitoring, a secrets vault, a browser console and OS update management.
 
 ## The pieces
 
 ```mermaid
 flowchart TD
     W["Web UI<br/>servers · keys · workflows · monitors<br/>secrets · audit · console · settings"]
-    S["Server<br/>REST :8080 · gRPC :9090<br/>MongoDB · Redis · guacd"]
+    S["Vantage server<br/>the control plane"]
     A["Agent<br/>one per managed server<br/>Linux and Windows"]
-    W -->|REST, cookie session| S
-    S -->|gRPC over TLS| A
-    A -.->|outbound only| S
+    W -->|you sign in here| S
+    S -->|sends work| A
+    A -.->|connects outbound| S
 ```
 
-**The server** holds all state and does all decision-making. It exposes a REST
-API on `:8080` for the web UI and a gRPC API on `:9090` for agents. MongoDB
-stores everything durable; Redis stores sessions and nothing else.
+**The server** is the control plane. It holds all your data and makes all the
+decisions.
 
-**The agent** is a single Go binary running as root on each managed server. It
-polls the control plane every 30 seconds for desired key state, and holds a
-bidirectional command stream so the server can push work run a workflow step,
-generate a key, apply updates without waiting for the next poll.
+**The agent** is a single small program running on each managed server. It asks
+the control plane what it should be doing, and holds an open connection so
+Vantage can send it work without waiting.
 
-**The web UI** is the operator interface. Everything it does goes through the
-REST API, which is the actual security boundary; the UI only ever makes things
-convenient.
+**The web UI** is what you use. Everything it can do goes through the same API
+that enforces your permissions, so nothing is possible in the UI that would not
+be permitted elsewhere.
 
 ## How agents connect
 
-The agent dials **out** to the control plane. There is no inbound listener on a
-managed server, no port to open and no NAT traversal to arrange. If the machine
-can reach your Vantage host on the gRPC port, it can be managed.
+The agent always connects **outbound**. There is no listener on a managed
+server, no port to open and no NAT to work around. If the machine can reach your
+Vantage address, it can be managed.
 
-That direction is why `GRPC_HOST` exists as an explicit setting: the agent has
-to be told a `host:port` it can reach, and there is no safe default the server
-could guess on its behalf.
+That is why you tell Vantage its own agent address (`GRPC_HOST`) when you install
+it: the agent has to be given an address it can reach, and Vantage cannot guess
+one for you.
 
-## Two request patterns
+## Keeping things current
 
-| Pattern                       | Used for                                                   | Why                                                                                              |
-| ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| Poll, every 30s               | desired SSH key state                                      | Key changes are not urgent, and polling survives a dropped connection with no reconnection logic |
-| Push, over the command stream | workflow steps, key generation, updates, agent self-update | Clicking Run should not wait up to 30 seconds                                                    |
-
-## Multi-tenancy
-
-Every document in the database carries an instance ID, and every query is scoped
-by it. One deployment can therefore host many independent tenants. On a
-self-hosted install that mechanism is still there you simply have one tenant.
+| What                      | How it works                                                              |
+| ------------------------- | ------------------------------------------------------------------------- |
+| SSH keys on a server      | The agent checks every 30 seconds and only writes when something changed   |
+| Workflow steps, updates   | Sent to the agent straight away, so clicking Run does not wait for a check |
+| Inventory                 | Reported every 30 seconds, with a fuller snapshot every 15 minutes         |
+| Pending OS updates        | Checked hourly                                                            |
 
 ## Next
 
-- [Cloud or self-hosted](./cloud-vs-self-hosted.md) which one you want
-- [Self-hosted install](./self-hosted-install.md) stand it up
+- [Cloud or self-hosted](./cloud-vs-self-hosted.md), to pick which one you want
+- [Self-hosted install](./self-hosted-install.md), to stand it up

docsite/docs/hq/accounts-and-signup.md

@@ -20,9 +20,9 @@ role:
 Reading is open to any signed-in member. Every mutation except changing your own
 password requires `owner` or `admin`. Billing is owner-only.
 
-The three words are the same as the control plane's roles, on purpose but they
-are separate things. Your account role governs the portal; your role _inside_ an
-instance governs that instance.
+These are the same three words your instances use, but they are separate things.
+Your account role controls what you can do in the portal. Your role inside an
+instance controls what you can do there.
 
 ## Signing up
 
@@ -38,14 +38,19 @@ Verification links are valid for **24 hours**.
 
 ## Signing in
 
-Use the Email and password used in the signup form to login to the HQ, signing in to HQ does not sign you in to an instance, and vice versa.
+Sign in at [Vantage HQ](https://vantage-hq.hostxtra.co.uk) with the email and
+password from the signup form.
+
+HQ and your Vantage instances have separate sessions: signing in to HQ does not
+sign you in to an instance, and signing in to an instance does not sign you in
+to HQ.
 
 ## What comes next
 
 | You want                       | Go to                                                         |
 | ------------------------------ | ------------------------------------------------------------- |
 | A Vantage instance we run      | [Cloud instances](./cloud-instances.md)                       |
-| To license an install you run  | [Self-hosted instances](./self-hosted-instances.md)           |
+| To licence an install you run  | [Self-hosted instances](./self-hosted-instances.md)           |
 | To add colleagues              | [People and roles](./people-and-roles.md)                     |
 | To understand tiers and limits | [Licensing and entitlements](./licensing-and-entitlements.md) |
 
@@ -55,4 +60,4 @@ Three destinations: **Overview**, **People**, **Billing**.
 
 - Overview lists your instances.
 - People shows all the account members and their roles.
-- Billing show the current subscriptions and subscription management.
+- Billing shows your current subscriptions and lets you manage them.

docsite/docs/hq/billing.md

@@ -12,25 +12,31 @@ customer reference and nothing sensitive.
 The Billing page requires the **owner-only** account role.
 :::
 
-## Buying A Plan
+## Buying a plan
 
-Buying a plan license can be found in Vantage HQ by clicking on the **Buy a Plan** button on the **Overview** page.
+In Vantage HQ, click **Buy a plan** on the **Overview** page.
 
 ### Cloud
 
-On the **Buy A Plan** page you will need to select the **Deployment** to **Cloud** then chose your **Billing** cycle (Monthly or Annually).
+1. Set **Deployment** to **Cloud**.
+2. Choose a **Billing** cycle, monthly or annual.
+3. Choose a **Plan** and configure its features and server allowance.
+4. Enter an **Instance name** and click **Continue to payment**.
 
-Then select your desired **Plan** and configure the features.
-
-Finally specify the **Instance Name** and click the **Continue to payment** button.
+The instance is created and licensed as soon as payment confirms.
 
 ### Self-hosted
 
-On the **Buy A Plan** page you will need to select the **Deployment** to **Self-Hosted** then chose your **Billing** cycle (Monthly or Annually).
+Install your control plane first — a licence binds to its instance ID.
 
-Then select your desired **Plan** and configure the features.
+1. Set **Deployment** to **Self-hosted**.
+2. Choose a **Plan** and configure its features and server allowance.
+3. Under **Your install**, paste the instance ID from your install's **Licence**
+   page. An ID you already hold is upgraded in place.
+4. Enter an **Instance name** and click **Continue to payment**.
 
-Finally specify the **Instance Name** and click the **Continue to payment** button.
+The licence is issued as soon as payment confirms; download it and paste it into
+your install. See [Self-hosted instances](./self-hosted-instances.md).
 
 ## Cancelling and failed payments
 
@@ -38,7 +44,7 @@ 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
+For a cloud Free instance, lapsing eventually leads to deletion. See
 [Free tier](./free-tier.md). Paid instances are not deleted.
 
 ## Renewals
@@ -47,4 +53,4 @@ 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: the license is automatically linked to the instance.
+- Cloud customers: nothing to do. The licence is written to the instance for you.

docsite/docs/hq/cloud-instances.md

@@ -9,18 +9,19 @@ A cloud instance is a Vantage control plane we run for you, reachable at
 
 ## Creating one
 
-1. **Overview → New instance**.
-2. Choose a name and a slug.
-3. Create.
+1. On **Overview**, choose **Create a cloud instance**. Once you already have an
+   instance, the same page offers **Buy a plan** instead.
+2. Choose **Cloud**, then the plan you want.
+3. Give the instance a name and confirm.
 
 The instance is provisioned with you as its owner, and a Free licence is issued
-immediately. The owner user inside it gets your HQ password hash **copied**, not
-shared see [People and roles](./people-and-roles.md).
+immediately. Your Vantage HQ password gets you into it, though the two are kept
+in step rather than shared. See [People and roles](./people-and-roles.md).
 
 ### Slugs
 
-The slug becomes your hostname label, so it is lowercase, and some names are
-reserved. Pick something you can say on a phone call.
+Your instance's address comes from the name you choose, lowercased, with some
+names reserved. Pick something short that you can say on a phone call.
 
 :::warning One Free instance per account, per deployment
 Creating a second Free cloud instance is refused. If you want another, it needs
@@ -41,9 +42,9 @@ affect anyone signing in or any agent syncing.
 
 Each instance on Overview is one record. Closed, it is a row. Open, it shows:
 
-- **Licence contents** tier, server allowance, features, expiry.
-- **Members** who has access and with what instance role.
-- **Actions** grant access, change configuration, renew.
+- **Licence contents**: tier, server allowance, features and expiry.
+- **Members**: who has access, and with what role.
+- **Actions**: grant access, change configuration, renew.
 
 ## Members
 
@@ -53,14 +54,15 @@ Granting access writes a real user into the instance. Covered fully in
 ## Changing what it can do
 
 Server allowance and per-instance features (browser console, single sign-on) are
-part of the instance's **entitlement**. Changing it goes through billing see
+part of the instance's **entitlement**, the configuration your licence is cut
+from. Changing it goes through billing. See
 [Licensing and entitlements](./licensing-and-entitlements.md) and
 [Billing](./billing.md).
 
 ## Renaming
 
-The display name is free to change. The slug is the hostname and is not
-casually changed ask support if you need it.
+The display name is free to change. The slug is part of your hostname, so ask
+support if you need that changed.
 
 ## What happens if the licence lapses
 
@@ -73,6 +75,4 @@ runs to its grace-padded expiry and then lapses.
 
 ## Deleting
 
-Ask support. Deletion is performed by the control plane, not by HQ the control
-plane is the only service that knows which collections carry the instance ID,
-and duplicating that list into HQ would be a list that drifts.
+Ask support.

docsite/docs/hq/free-tier.md

@@ -4,7 +4,8 @@ title: Free tier
 sidebar_label: Free tier
 ---
 
-Free is a real tier in both deployments not a trial that turns into nothing.
+Free is a permanent tier. It is available whether we host Vantage for you or you
+host it yourself.
 
 ## What you get
 
@@ -23,16 +24,15 @@ features on a paid plan.
 ## One per account, per deployment
 
 The limit is enforced per account **and** deployment. A Free cloud instance does
-not prevent a Free self-hosted one they are separate slots.
+not prevent a Free self-hosted one; they are separate slots.
 
 ## Renewing
 
-Free licences have a term and must be renewed from the portal.
+Free licences run for a year and are renewed from the portal.
 
 - The renew button appears **7 days before expiry**.
-- It stays available **after** expiry, right up until the instance is reaped —
-  so the same button rescues a lapsed instance rather than needing a second
-  mechanism.
+- It stays available **after** expiry, right up until a lapsed cloud instance is
+  deleted, so the same button rescues one.
 - Renewing outside that window is refused, and the message names the date it
   opens.
 
@@ -55,19 +55,13 @@ There is no restore. If a cloud Free instance is approaching that date and you
 want to keep it, renew it, or move it to a paid plan.
 :::
 
-Deletion is carried out by the control plane rather than by HQ. HQ sends the
-warnings because it knows the billing address; the control plane performs the
-delete because it is the only service that knows which collections carry the
-instance ID.
-
 ## Moving off Free
 
 Change the instance's configuration to a paid tier and check out. Your data
-stays where it is a tier change reissues a licence, it does not rebuild
+stays where it is: a tier change reissues a licence, it does not rebuild
 anything.
 
 ## Relinks
 
-Free instances get the same relink allowance as paid ones: three per term. That
-cap exists to put a human in front of a fourth attempt, not to obstruct a
-genuine rebuild.
+Free instances get the same allowance as paid ones: three relinks per term. If
+you genuinely need more, ask support.

docsite/docs/hq/licensing-and-entitlements.md

@@ -10,7 +10,7 @@ A **licence** is a signed statement of what one instance may do. An
 ## 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.
+self-hosted; what differs is the term on offer, not what you get.
 
 |                       | Free      | Professional | Enterprise            |
 | --------------------- | --------- | ------------ | --------------------- |
@@ -23,17 +23,18 @@ self-hosted what differs is the term on offer, not what you get.
 
 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
+rather than "unlimited": the number you actually have is the one in your
 entitlement.
 
 ## Features
 
-Two are per-instance toggles rather than tier bundles:
+Three features are enabled per instance rather than bundled into a tier:
 
 | Feature   | What it enables                                                      |
 | --------- | -------------------------------------------------------------------- |
-| `console` | The [browser console](../vantage/browser-console.md)                 |
-| `oidc`    | Per-instance [single sign-on](../vantage/settings.md#single-sign-on) |
+| Browser console       | The [browser console](../vantage/browser-console.md)               |
+| Single sign-on        | [Sign-in through your identity provider](../vantage/settings.md#single-sign-on) |
+| Vulnerability scanning| [Package vulnerability scanning](../vantage/vulnerabilities.md)     |
 
 No tier includes them by default; you enable them on the instances that need
 them.
@@ -62,26 +63,35 @@ happens at renewal.
 
 ## What a licence carries
 
-Instance UUID, deployment, tier, resolved limits, features, term and expiry —
-all signed.
+Your instance ID, whether it is cloud or self-hosted, the tier, your limits,
+which features are enabled, and when it expires. All of it is 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.
+- **A licence works for one instance only.** Moving it to a rebuilt install
+  takes a [relink](./self-hosted-instances.md#relinking).
+- **A licence is a snapshot.** Changing a plan later does not rewrite a licence
+  already issued.
 
 Verification is local. Your instance does not call HQ to check a licence, and
 signing happens only in HQ.
 
-## Expiry and grace
+## Expiry, grace and degraded mode
 
-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.
+Expiry is padded with a few days' grace. Past that, an instance goes into
+**degraded mode**, which means:
 
-The way out is a current licence renew or purchase, then paste it (self-hosted)
-or let it be written for you (cloud).
+- It keeps running, and all of your data stays exactly where it is.
+- You can still sign in and read everything.
+- Adding or changing anything is refused.
+- Deleting things still works, so you can get back under a reduced allowance.
+- Applying OS updates still works, because security patching is never blocked.
+
+A brand-new self-hosted install behaves the same way until you install its first
+licence.
+
+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
 

docsite/docs/hq/people-and-roles.md

@@ -26,14 +26,11 @@ Owners and admins invite; billing is owner-only.
 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.
+An invited person cannot sign in at all until they set their own password. If
+you chose it for them, it would be a shared password to every instance they are
+later given 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.
+Their invitation link stays valid until they use it to set that password.
 :::
 
 ### Removing someone
@@ -43,26 +40,26 @@ 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"`.
+Granting access to a **cloud** instance creates a real account inside that
+instance, marked as managed by Vantage 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"]
+    P["Person in your Vantage HQ account"] -->|you grant access| U["Account inside the instance"]
+    U --> I["They sign in at the instance,<br/>like anyone else"]
 ```
 
-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.
+They then sign in at the instance itself, and that keeps working whether or not
+Vantage HQ is reachable. Revoking removes the account outright, so access ends
+immediately.
 
 ### 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.
+One person gets one account per instance, so granting twice is refused rather
+than quietly creating a second.
 
 ### Roles inside an instance
 
@@ -71,28 +68,24 @@ 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.
+Removes their access immediately, and ends any session they have open.
 
 :::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**.
+Vantage HQ cannot add or remove people in a self-hosted install. Manage them in
+the install 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.
+One Vantage HQ password covers you and every cloud instance you have been given
+access to. Change it in the portal and it changes everywhere, within about 15
+minutes at worst if an instance is briefly unreachable.
 
-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.
+Those people cannot change that password inside an instance, so there is only
+ever one place it is set.
 
 :::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.
+Changing the role of, or removing, someone managed by Vantage HQ has to be done
+from the portal. Inside the instance those rows are read-only, with a link back
+here.
 :::

docsite/docs/hq/self-hosted-instances.md

@@ -14,59 +14,56 @@ Install first, then link and claim. Step by step in
 
 ## Paid
 
-Buying happens **before** the install has to exist, because you may well be
-buying in order to build it.
+**Install first.** A licence is issued to one instance, so your control plane
+has to exist and report an instance ID before you can buy for it — the same
+precondition Free has.
 
 ```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["Install Vantage<br/>find its instance ID"] --> B["Buy in Vantage HQ<br/>paste that ID"]
+    B --> C["Payment confirms"]
+    C --> D["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.
-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.
+1. [Install Vantage](../getting-started/self-hosted-install.md) and find its
+   instance ID on the **Licence** page.
+2. On **Overview**, choose **Buy a plan**. Pick **Self-hosted**, then your tier
+   and configuration.
+3. Under **Your install**, paste the instance ID. Enter an **Instance name** and
+   click **Continue to payment**.
+4. The licence is issued as soon as payment confirms. 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.
-:::
+## Upgrading an instance you already have
 
-## Linking an existing install
+Paste the same instance ID you already hold — an install on Free moves to the
+paid plan in place, keeping its ID and its history. An ID belonging to another
+account is refused.
 
-If the install already exists, **Link an instance** takes the UUID directly. A
-UUID already claimed by another account is refused with a conflict.
+For a Free licence, 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,

docsite/docs/index.md

@@ -7,9 +7,9 @@ slug: /
 
 # Vantage documentation
 
-Vantage is a self-hosted, multi-tenant infrastructure control plane. It manages
-SSH keys, runs scripted workflows, watches services, stores secrets, opens
-browser consoles and applies OS updates across a fleet of servers.
+Vantage manages a fleet of servers from one place: SSH keys, scripted workflows,
+service monitoring, a secrets vault, browser consoles and OS updates. Run it
+yourself, or let us run it for you.
 
 A central server drives a lightweight agent installed on each managed machine.
 The agent connects **outbound only**, so managed servers need no inbound
@@ -20,14 +20,16 @@ firewall holes.
 | If you want to                          | Read                                                            |
 | --------------------------------------- | --------------------------------------------------------------- |
 | Understand what the pieces are          | [What is Vantage](./getting-started/what-is-vantage.md)         |
+| Decide who should run it                | [Cloud or self-hosted](./getting-started/cloud-vs-self-hosted.md) |
 | Run it on your own hardware             | [Self-hosted install](./getting-started/self-hosted-install.md) |
+| Licence a self-hosted install           | [Claim a Free licence](./getting-started/claim-free-licence.md) |
 | Enrol your first machine                | [Add your first server](./getting-started/first-server.md)      |
 | Manage your account, licence or billing | [Vantage HQ](./hq/accounts-and-signup.md)                       |
 | Look something up                       | [Reference](./reference/environment-variables.md)               |
 
 ## The two products
 
-**Vantage** is the control plane the thing you sign in to in order to manage
+**Vantage** is the control plane, the thing you sign in to in order to manage
 servers. It runs either on your own infrastructure or as a cloud instance we
 run for you.
 

docsite/docs/operations/agent-updates.md

@@ -13,8 +13,7 @@ Each server's detail page shows the version it reported at its last sync.
 
 ## Updating from the UI
 
-**Servers → _a server_ → Update agent** pushes `UpdateAgentCmd` with a target
-version. The agent then:
+Open a server and choose **Update agent**. The agent then:
 
 1. Downloads the binary for its platform from the release.
 2. Verifies the SHA-256 against `checksums.txt`.
@@ -35,8 +34,8 @@ irm https://vantage.example.com/update.ps1 | iex
 ```
 
 It does the same download, checksum and replace, then restarts the service. Use
-this when the control plane cannot push for example, when the machine is
-reachable but its command stream is not.
+this when Vantage cannot reach the agent to push the update, but you can still
+reach the machine.
 
 ## Rolling out across a fleet
 
@@ -54,9 +53,8 @@ Do one, confirm it returns to `active`, then do the rest.
 
 ## Version compatibility
 
-The agent API is versioned to tolerate an agent older than the control plane. The
-reverse an agent newer than the control plane is not a case anyone tests.
-Upgrade the control plane first.
+An agent older than your control plane is supported. An agent newer than it is
+not, so upgrade the control plane first.
 
 Agents report their version on every poll, so a fleet running mixed
 versions is visible in the server list rather than something you have to go

docsite/docs/operations/backups.md

@@ -11,9 +11,8 @@ either one restores to something unusable.
 
 | Store                | Contents                                                                                                      | Back up                                           |
 | -------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| MongoDB              | Everything durable servers, keys, assignments, workflows, runs, monitors, incidents, secrets, settings, audit | **Yes**                                           |
+| MongoDB              | Everything durable: servers, keys, assignments, workflows, runs and their logs, monitors, incidents, secrets, settings, audit | **Yes**                          |
 | Redis                | Sessions only                                                                                                 | No. Losing it signs everyone out and nothing else |
-| `./data` bind mount  | Workflow run logs                                                                                             | Optional                                          |
 | `KEY_ENCRYPTION_KEY` | Not stored anywhere by the app                                                                                | **Yes, separately**                               |
 
 :::danger The database alone is not a backup
@@ -50,7 +49,7 @@ nothing writes during the restore.
 cp /opt/vantage/.env /secure-location/vantage.env
 ```
 
-Treat it as a credential in its own right it holds the encryption key.
+Treat it as a credential in its own right, since it holds the encryption key.
 
 ## What a restore gives you
 
@@ -62,7 +61,7 @@ What it does **not** do is reconcile the world. After a restore:
 - Agents reconnect with their existing tokens, since the token hashes are in the
   database.
 - If the restore is older than an enrolment, that server's token hash is missing
-  and the agent will fail to authenticate re-enrol it.
+  and the agent will fail to authenticate. Re-enrol it.
 - The next agent poll rewrites `authorized_keys` to match the restored desired
   state, which may remove keys added since the backup.
 
@@ -74,8 +73,8 @@ What it does **not** do is reconcile the world. After a restore:
 | Environment file  | On change, held in a password manager or secret store |
 | Restore rehearsal | Occasionally, into a throwaway host                   |
 
-The rehearsal is the part that gets skipped and the part that finds the
-problems.
+Rehearse a restore now and again. It is the step most often skipped, and the one
+that finds the problems.
 
 ## Cloud instances
 

docsite/docs/operations/upgrading.md

@@ -5,7 +5,7 @@ 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).
+upgraded separately. See [Agent updates](./agent-updates.md).
 
 :::info Cloud instances upgrade themselves
 This page is for self-hosted installs. If your instance is hosted by us, there
@@ -26,11 +26,11 @@ 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.
+1. The database is brought up to date. Each change runs once.
+2. The built-in workflow steps are reinstalled, which is why those steps cannot
+   be edited.
+
+If Vantage cannot complete either safely, it stops rather than run half-prepared.
 
 Watch it:
 
@@ -46,6 +46,16 @@ docker compose logs -f server
 - **Check your `.env`** still supplies everything required. A newly required
   variable stops the boot rather than defaulting to something unsafe.
 
+## Single sign-on after an upgrade
+
+Each identity provider now has its own callback URL. If you configured single
+sign-on on an older version it was carried over, but its callback URL changed,
+and sign-in through it fails until you copy the new one from its card in
+**Settings** and register it with your identity provider. The card shows a
+reminder until you dismiss it.
+
+Password sign-in is unaffected, so you can always sign in locally to fix this.
+
 ## Downgrading
 
 There is no automatic downgrade. Migrations do not roll back, so returning to an
@@ -57,7 +67,7 @@ is the reason the backup is not optional.
 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.
+- Agents reconnect on their own.
 - 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.**
@@ -67,5 +77,4 @@ container, which is a short interruption:
 
 - 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.
+- Open a secret group, to confirm `KEY_ENCRYPTION_KEY` came through.

docsite/docs/reference/agent-config.md

@@ -20,15 +20,15 @@ Directory `0700`, file `0600`. The install script sets both.
 ```yaml
 server_url: "vantage.yourdomain.com:9090"
 server_id: "<uuid>"
-pre_reg_token: "<token>" # removed after the first successful Register()
-agent_token: "" # written by the agent after Register()
+pre_reg_token: "<token>" # cleared once the agent has registered
+agent_token: "" # written by the agent when it registers
 poll_interval: 30s
 tls: true
 ```
 
 | Field           | Meaning                                                               |
 | --------------- | --------------------------------------------------------------------- |
-| `server_url`    | `host:port` of the gRPC endpoint. Comes from the server's `GRPC_HOST` |
+| `server_url`    | The `host:port` the agent connects to. Comes from your `GRPC_HOST`    |
 | `server_id`     | The identity issued when the enrolment was created                    |
 | `pre_reg_token` | Single-use, one hour. Cleared once registration succeeds              |
 | `agent_token`   | The permanent credential, written by the agent itself                 |
@@ -36,8 +36,8 @@ tls: true
 | `tls`           | Whether to use TLS. Leave `true`                                      |
 
 :::danger This file is the credential
-`agent_token` is plaintext here and nowhere else the control plane holds only
-its SHA-256. Anyone who can read this file can act as this agent.
+`agent_token` exists in full only in this file. Anyone who can read it can act
+as this agent.
 :::
 
 ## Service management
@@ -77,5 +77,5 @@ rm -rf /etc/vantage
 systemctl daemon-reload
 ```
 
-Keys already written to `authorized_keys` remain on disk the agent is no
-longer running to remove them. Revoke first if that matters.
+Keys already written to `authorized_keys` remain on disk, because the agent is
+no longer running to remove them. Revoke first if that matters.

docsite/docs/reference/api-tokens.md

@@ -0,0 +1,110 @@
+---
+id: api-tokens
+title: API tokens
+sidebar_label: API tokens
+---
+
+A session cookie is fine for a browser. A script, a CI job or a cron task
+needs something it can hold onto instead — an API token.
+
+## Creating one
+
+**API Keys**, in the Access group of the sidebar. The page is reachable at
+every role: any member may create and revoke their own keys, and owner and
+admin additionally see every key in the instance. Give it a name, a role
+(owner, admin or member) and one or more scopes, and optionally an expiry. The value is shown
+once, in full, immediately after creation:
+
+```
+vt_8f2c1a9e4b6d0735a1c8e29f4b0d6e17...
+```
+
+That is the only time you will see it. Vantage stores a hash of the token,
+never the value itself, so if you lose it there is no support ticket that gets
+it back — create a new token and revoke the old one.
+
+## Scopes
+
+A token can reach only what its scopes name. There are eight resources, each
+with a `:read` and a `:write` scope, and holding `:write` on a resource also
+satisfies a `:read` requirement for it — you do not need to tick both.
+
+| Resource    | Covers                                             |
+| ----------- | --------------------------------------------------- |
+| `servers`   | Fleet list, server detail, agent commands, tags     |
+| `keys`      | SSH key library and assignment                      |
+| `secrets`   | The vault                                            |
+| `workflows` | Steps, workflows, runs and their logs               |
+| `monitors`  | Monitors, incidents, uptime and notification channels |
+| `vulns`     | Vulnerability findings, packages and scan rules      |
+| `workloads` | Containers and systemd units, including control actions and logs |
+| `settings`  | Instance settings, members, single sign-on, licence, and token management itself |
+
+A token created with only `servers:read` can list and inspect servers but
+cannot run a workflow against them, touch a key, or read a secret — each of
+those needs its own scope.
+
+## A token never outranks its owner
+
+A token's role can be at most the role of the person who created it, and its
+effective role is **recomputed on every request** as the lower of the two —
+not fixed at creation. Demote the person from owner to member and every token
+they hold drops to member from that request onward. Remove the person and
+every token they hold stops working immediately: a token has no existence
+independent of its owner.
+
+## Expiry
+
+An expiry is optional on a token you create. An instance can set a
+**maximum key lifetime** (Settings → Integrations) that caps how far out a new
+token's expiry may be set; when that cap is in place, a token with no expiry
+at all is refused, so there is no way to route around the policy by leaving
+the field blank.
+
+Changing the maximum lifetime only affects tokens created afterwards. It does
+not shorten, extend or invalidate a token that already exists.
+
+## Using a token
+
+Send it as a bearer token:
+
+```bash
+curl -H "Authorization: Bearer vt_…" https://acme.vantage.example.com/api/servers
+```
+
+Everything else about the [REST API](./rest-api.md) applies the same way it
+does to a session — JSON errors, audit logging, licence gating on writes —
+except that authority comes from the token's role and scopes rather than a
+signed-in person's role.
+
+## Rate limit
+
+A token is limited to **600 requests per minute**. Going over it gets a `429`
+with a `Retry-After` header naming how many seconds to wait. Cookie sessions
+are not subject to this limit; it exists so a runaway script cannot take an
+instance down, not as a general throttle.
+
+## Rotating a token
+
+1. Create the replacement token first, with the scopes and role you need.
+2. Deploy it wherever the old one was used, and confirm it works.
+3. Revoke the old one.
+
+Doing it in that order means there is no gap where the credential in use has
+already been deleted.
+
+## The full reference
+
+This page covers the token model. Every route, request and response shape is
+in the generated OpenAPI reference, served by **your own instance** at
+`/api/docs` — not this documentation site, since the routes and their shapes
+are specific to your install. The raw document is at `/api/openapi.json`.
+
+:::danger Not the External Secrets token
+The bearer token read by `GET /api/secrets/:group/values` for the Kubernetes
+External Secrets Operator is a **separate credential** — a single instance-wide
+value, rotated from Settings, that reaches only that one endpoint. It is not an
+API token and an API token cannot be used in its place: the two are checked by
+different code, and neither substitutes for the other. See
+[Secrets](../vantage/secrets.md#kubernetes-external-secrets-operator).
+:::

docsite/docs/reference/environment-variables.md

@@ -13,16 +13,18 @@ it is absent.
 | -------------------------- | --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `GRPC_HOST`                | **yes**         |                             | The `host:port` agents dial. Boot fails without it. There is deliberately no fallback to the web host: that would hand every agent a port that does not speak gRPC |
 | `MONGO_URI`                | no              | `mongodb://localhost:27017` | The database name is taken from the URI path, falling back to `vantage`. There is no separate `MONGO_DB`                                                           |
-| `REDIS_ADDR`               | no              | `localhost:6379`            | Sessions, and the bus that routes agent commands between server replicas. Every replica must point at the **same** Redis                                            |
+| `REDIS_ADDR`               | no              | `localhost:6379`            | Where sessions are held. If you run more than one copy of Vantage, they must all point at the same Redis                                                            |
 | `REDIS_USERNAME`           | no              |                             | Redis 6+ ACL user. Leave empty against a legacy `requirepass` instance, which authenticates with the password alone                                                |
 | `REDIS_PASSWORD`           | no              |                             | Leave empty for an unauthenticated Redis. Both of these exist so an install can use a managed Redis rather than the bundled one                                    |
 | `KEY_ENCRYPTION_KEY`       | yes in practice |                             | 64 hex characters (32 bytes) for AES-256-GCM. Required for private keys, vault secrets, OIDC client secrets and console credentials                                |
-| `GITEA_HOST`               | yes             | `gitea.example.com`         | Used to build the install scripts and agent download URLs. The default is a placeholder that will not resolve                                                      |
+| `GITEA_HOST`               | yes in practice | `gitea.example.com`         | Host serving agent releases; used to build the install scripts and download URLs. The default is a placeholder that will not resolve, so set it to `gitea.hostxtra.co.uk` |
 | `GUACD_ADDR`               | no              | `guacd:4822`                | The [browser console](../vantage/browser-console.md) daemon                                                                                                        |
 | `PROXY_ADVERTISE_HOST`     | no              | `server`                    | The hostname **guacd** uses to reach the control plane's console relay. Wrong here and every console session fails at connect with guacd unable to resolve the relay |
 | `PROXY_LISTEN_HOST`        | no              | `0.0.0.0`                   | Interface the ephemeral relay listeners bind. Narrow it only if guacd shares a known interface                                                                     |
-| `POD_IP`                   | no              |                             | Kubernetes only, set by the Helm chart from the downward API. Overrides `PROXY_ADVERTISE_HOST`, because a console relay belongs to one replica and a Service address names all of them |
-| `APP_ROOT_LABEL`           | no              | `vantage`                   | The app root label for the host and session organisation guard                                                                                                     |
+| `APP_ROOT_LABEL`           | no              | `vantage`                   | The label Vantage expects in its own hostname, used to match a browser session to the right instance                                                                |
+| `VANTAGE_LICENSE`          | no              |                             | A licence supplied at startup, so an automated install does not have to paste one in                                                                                |
+| `VANTAGE_TRIVY_DB_REF`     | no              | `ghcr.io/aquasecurity/trivy-db:2` | Where the vulnerability database is pulled from. Point it at a mirror for an air-gapped install                                                              |
+| `VANTAGE_VULNDB_DISABLED`  | no              |                             | `true` switches [vulnerability scanning](../vantage/vulnerabilities.md) off entirely. Findings already stored are still served, and still shown as stale        |
 
 :::danger `KEY_ENCRYPTION_KEY` has no recovery path
 It encrypts SSH private keys, vault secrets, OIDC client secrets and console
@@ -38,8 +40,8 @@ protecting anything.
 ### Not configurable
 
 The HTTP port (`8080`) and the gRPC port (`9090`) are fixed in the server. The
-`HTTP_PORT` and `GRPC_PORT` entries in the shipped Compose file are inert —
-remap with Docker's port publishing instead.
+`HTTP_PORT` and `GRPC_PORT` entries in the shipped Compose file have no effect.
+Remap the ports with Docker instead.
 
 ## Agent
 

docsite/docs/reference/ports-and-networking.md

@@ -9,9 +9,9 @@ sidebar_label: Ports and networking
 | Port    | Service     | Who connects                     | Expose publicly |
 | ------- | ----------- | -------------------------------- | --------------- |
 | `3000`  | web         | Browsers, via your reverse proxy | Yes, behind TLS |
-| `8080`  | server REST | The web app                      | No              |
+| `8080`  | server API  | The web app                      | No, firewall it |
 | `9090`  | server gRPC | Agents                           | **Yes**         |
-| `4822`  | guacd       | The server                       | No              |
+| `4822`  | guacd       | The server                       | No, firewall it |
 | `27017` | MongoDB     | The server                       | No              |
 | `6379`  | Redis       | The server                       | No              |
 
@@ -35,11 +35,10 @@ NAT is not an obstacle. The only requirement is that the machine can reach
 `GRPC_HOST`.
 
 **The console rides the agent's connection too.** guacd never dials the target
-directly; the server pushes a command down the agent's existing outbound gRPC
-stream on `9090`, and the agent relays the protocol traffic from its own
-loopback. No route from the control plane to the target's address is needed,
-and no new inbound port opens on the target — the same connection that carries
-key sync carries console traffic. This is what makes the console work for a
+directly. Vantage sends the request down the connection the agent already holds
+on port `9090`, and the agent connects to the service locally on that machine. No route from the control plane to the target's address is needed,
+and no new inbound port opens on the target. The same connection that keeps keys
+in sync carries console traffic, which is what makes the console work for a
 machine behind NAT on a private subnet, as long as its agent is online.
 
 ## What to open
@@ -55,8 +54,8 @@ machine behind NAT on a private subnet, as long as its agent is online.
 - Anything a server-run [monitor](../vantage/monitors.md) checks.
 - SMTP, if you use an SMTP notification channel.
 
-No route to the machines you intend to console is needed — that traffic rides
-the agent's existing outbound `9090` connection instead.
+No route to the machines you intend to console is needed. That traffic uses the
+connection the agent already holds.
 
 ### Outbound from a managed machine
 
@@ -68,14 +67,17 @@ the agent's existing outbound `9090` connection instead.
 
 Terminate TLS for the web UI at your reverse proxy.
 
-gRPC on `9090` is reached directly by agents with `tls: true`, so that port needs
-a valid certificate for the name in `GRPC_HOST`. If you proxy it, the proxy must
-speak HTTP/2 end to end many do not by default, and the symptom is agents that
-register and then fail to hold the command stream.
+Vantage does not terminate TLS itself, so port `9090` needs the same treatment:
+put it behind your proxy with a certificate valid for the name in `GRPC_HOST`.
+The proxy has to pass HTTP/2 through to Vantage. Many do not do that by default,
+and the symptom is agents that register once and then stop responding.
+
+On a private network you can skip TLS instead, by setting `tls: false` in each
+[agent's config](./agent-config.md).
 
 ## Reverse proxy notes
 
-- Point the proxy at `web:3000`. The web app reaches the REST API internally, so
+- Point the proxy at `web:3000`. The web app reaches the API internally, so
   `8080` does not need publishing.
 - The console uses a **WebSocket** at `/api/console/tunnel`. A proxy that does
   not forward upgrade headers breaks the console and nothing else.
@@ -85,8 +87,8 @@ register and then fail to hold the command stream.
 ## Air-gapped and restricted networks
 
 The control plane needs outbound access to fetch agent releases. Managed
-machines need it too, unless you distribute the agent binary yourself and write
-the config by hand the install script's only job is to do those two things.
+machines need it too, unless you distribute the agent yourself and write its
+config by hand, which is all the install script does.
 
 Licence verification is entirely local, so a licensed install works with no
 outbound access to HQ at all.

docsite/docs/reference/rest-api.md

@@ -1,154 +1,59 @@
 ---
 id: rest-api
-title: REST API
-sidebar_label: REST API
+title: Automating Vantage
+sidebar_label: Automating Vantage
 ---
 
-The control plane's HTTP API, on port `8080`. The web UI is a client of it and
-has no privileges it does not.
+Everything the web UI does, it does through Vantage's own API, so anything you
+can do on screen you can also do from a script.
 
-## Authentication
+The routes mirror the product: `/api/servers`, `/api/keys`, `/api/workflows`,
+`/api/monitors`, `/api/secrets`, `/api/audit`, and so on.
 
-Most endpoints take a session: an opaque 32-byte token in the `km_session`
-cookie, with the body in Redis for 24 hours.
+## Where it is
 
-One endpoint takes a bearer token instead the External Secrets Operator read
-path.
+On a self-hosted install the API is served on port `8080`, behind the same
+reverse proxy as the web UI, under `/api` and `/auth`. On a cloud instance it is
+your instance hostname.
 
-## Unauthenticated
+## Signing in
 
-```
-GET  /install            /install.ps1        # dynamic agent install scripts
-GET  /update             /update.ps1
-GET  /auth/bootstrap-status
-POST /auth/bootstrap     /auth/login  /auth/logout
-GET  /auth/me
-GET  /auth/providers                          # {local_enabled, providers:[{id,name,preset}]} — no issuer, client ID or secret
-GET  /auth/oidc/:providerId/start · /auth/oidc/:providerId/callback
-GET  /api/secrets/:group/values               # bearer token (ESO)
+Most calls use a session, exactly as the browser does:
+
+```bash
+curl -c cookies.txt -X POST https://vantage.example.com/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"you@example.com","password":"..."}'
+
+curl -b cookies.txt https://vantage.example.com/api/servers
 ```
 
-`/install` and `/install.ps1` take `server_id` and `token` as query parameters
-and return a shell script with the newest agent version substituted in.
+Sessions last 24 hours. Your role applies exactly as it does in the UI: a
+`member` calling an owner-only route is refused.
 
-`POST /auth/bootstrap` works only while the database has no users.
+## The one exception
 
-## Session-authenticated, under `/api`
+Kubernetes reads secret groups with a token instead of a session, so that it
+does not need an account. See
+[Secrets](../vantage/secrets.md#kubernetes-external-secrets-operator).
 
-### Servers
+## Things worth knowing
 
-```
-GET,POST   /servers
-GET,POST   /servers/new
-GET,DELETE /servers/:id
-POST       /servers/:id/generate-key
-POST       /servers/:id/update-agent
-POST       /servers/:id/apply-updates
-```
+- **Reads always work. Changes need a valid licence.** Without one, the instance
+  is read-only and any call that changes something is refused. Deleting things,
+  applying OS updates and installing a licence are always allowed, so you can
+  always get back under your allowance or out of read-only mode.
+- **Some features are licensed.** The browser console, single sign-on and
+  vulnerability scanning are refused if your licence does not include them.
+- **Some things cannot be changed here.** A cloud instance refuses a pasted
+  licence, and people managed by Vantage HQ cannot be re-roled or deleted inside
+  the instance.
+- **Errors are JSON**, with an `error` field naming the reason.
+- **Everything that changes something is audited**, whether it came from the UI
+  or from a script. See [Audit log](../vantage/audit-log.md).
 
-### Keys
+## Vantage HQ
 
-```
-GET,POST   /keys
-GET,DELETE /keys/:id
-GET        /keys/:id/private-key
-POST       /keys/:id/assign
-DELETE     /keys/:id/assign/:serverId
-```
-
-### Workflows and steps
-
-```
-GET,POST       /steps
-PUT,DELETE     /steps/:id
-GET            /steps/:id/export
-POST           /steps/import · /steps/seed-defaults · /steps/parse
-GET            /steps/usage
-GET,POST       /workflows
-GET,PUT,DELETE /workflows/:id
-POST           /workflows/:id/run
-GET            /workflows/:id/runs
-GET            /runs/:runId
-POST           /runs/:runId/cancel
-GET            /runs/:runId/servers/:serverId/logs
-GET            /runs/:runId/servers/:serverId/logs/stream
-```
-
-`PUT` and `DELETE` on a step whose source is `default` answer `409`. See
-[Workflows](../vantage/workflows.md#default-steps).
-
-### Monitors and channels
-
-```
-GET,POST       /monitors
-GET,PUT,DELETE /monitors/:id
-GET            /monitors/:id/incidents · /monitors/:id/uptime
-GET,POST       /channels
-PUT,DELETE     /channels/:id
-POST           /channels/:id/test
-```
-
-### Secrets
-
-```
-GET,POST       /secrets
-GET,PUT,DELETE /secrets/:group
-POST           /secrets/:group/reveal
-DELETE         /secrets/:group/:key
-```
-
-### Console
-
-```
-POST /console/connect
-GET  /console/tunnel        # websocket
-```
-
-### Other
-
-```
-GET  /audit
-GET  /agent/latest-version
-GET,PUT /settings                            (owner|admin)
-POST /settings/secrets-token                 (owner|admin)
-GET  /license
-POST /license                                (self-hosted only)
-GET,POST   /org/users
-PUT        /org/users/:id/role
-DELETE     /org/users/:id
-GET,POST       /auth/providers                        (owner|admin)
-PUT,DELETE     /auth/providers/:id                     (owner|admin)
-POST           /auth/providers/:id/test · /auth/providers/:id/ack-notice   (owner|admin)
-GET             /auth/presets                          (owner|admin)
-```
-
-## Notable refusals
-
-| Endpoint                                           | Condition                      | Status              |
-| -------------------------------------------------- | ------------------------------ | ------------------- |
-| `POST /license`                                    | deployment is `cloud`          | `409 cloud_managed` |
-| `PUT,DELETE /steps/:id`                            | the step's source is `default` | `409`               |
-| `PUT /org/users/:id/role`, `DELETE /org/users/:id` | the user's auth source is `hq` | `409`               |
-
-`POST /license` is exempt from the licence check, so pasting a valid licence
-works while the current one is expired that is the way out of degraded mode.
-
-## Multi-tenancy
-
-Every request is scoped to the instance resolved from the session. On a
-multi-tenant deployment, a request arriving at `<slug>.vantage.<tld>` also has
-its host checked against the session's instance, and a mismatch is rejected.
-
-## Errors
-
-Errors are JSON with an `error` field. Customer-facing endpoints in the HQ API
-answer `404` rather than `403` for another account's resource, because a `403`
-confirms the resource exists; the control plane's own API is single-tenant per
-session and does not need that distinction.
-
-## Admin API
-
-Vantage HQ is a separate hosted service with its own API and its own session.
-Its behaviour is described in the [Vantage HQ](../hq/accounts-and-signup.md)
-section rather than here; the two services share no session and no
-authentication.
+The portal is a separate service with its own sign-in, described in the
+[Vantage HQ](../hq/accounts-and-signup.md) section. A Vantage session does not
+work there, and an HQ session does not work in your instance.

docsite/docs/reference/troubleshooting.md

@@ -8,13 +8,12 @@ Symptoms, in the order people hit them.
 
 ## The server will not start
 
-**Exits immediately on boot.** Almost always a missing `GRPC_HOST` the server
+**Exits immediately on boot.** Almost always a missing `GRPC_HOST`. The server
 refuses to start rather than guess a value that would break every agent later.
 
-**Fails during index creation.** The auth and settings index builders are fatal
-on failure by design: those unique indexes are what enforce tenant isolation,
-so starting without them is worse than not starting. Check the MongoDB user's
-permissions and whether a conflicting index already exists.
+**Fails while preparing the database.** Vantage stops rather than run without
+the safeguards it sets up at startup. Check the MongoDB user's permissions and
+whether an old, conflicting index is already there.
 
 **Starts, but every secret operation errors.** `KEY_ENCRYPTION_KEY` is missing
 or is not 64 hex characters.
@@ -22,15 +21,15 @@ or is not 64 hex characters.
 ## Nobody can sign in
 
 **`/setup` appears when users already exist.** The server is pointed at a
-different database than you think. Check the database name in `MONGO_URI` —
-it comes from the URI path, not a separate variable.
+different database than you think. Check the database name in `MONGO_URI`,
+which is taken from the end of the URI.
 
 **Sessions do not stick.** Redis is unreachable, or the cookie is being dropped
 because the site is served over plain HTTP.
 
-**"Wrong organisation" style rejections.** The host and session guard is
-comparing the request host's label against the session's organisation. Check
-`APP_ROOT_LABEL`.
+**"Wrong organisation" style rejections.** Vantage compares the address you
+browsed to against the instance your session belongs to. On a custom domain,
+check `APP_ROOT_LABEL`.
 
 **OIDC redirects and then fails.** The callback URL registered with the provider
 must match exactly. Keep one local owner account so a broken provider is not a
@@ -44,12 +43,12 @@ Work through it in this order:
 2. What does it say? `journalctl -u vantage-agent -f`.
 3. Can that machine reach the endpoint? Test `GRPC_HOST` **from the machine**,
    not from the control plane host.
-4. Was the token already used or expired? It is single-use and lives one hour —
-   create a fresh enrolment rather than reusing the old command.
+4. Was the token already used, or older than an hour? Generate a fresh install
+   command rather than reusing the old one.
 
 | Symptom                                       | Cause                                                                                                                  |
 | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Registers, then goes `offline` within minutes | Something permits the short `Register` call but drops the long-lived stream. Usually a proxy or idle-timeout middlebox |
+| Registers, then goes `offline` within minutes | The short registration call gets through but the long-lived connection is dropped, usually by a proxy or an idle timeout |
 | Stays `pending` forever                       | Registration never happened. Token spent, or the endpoint unreachable                                                  |
 | Flaps between `active` and `offline`          | Intermittent path, or a poll interval longer than the offline threshold                                                |
 
@@ -67,15 +66,15 @@ instantaneous.
 
 ## A workflow run fails or hangs
 
-- **Hangs at dispatch.** The target's command stream is not connected the
+- **Hangs at dispatch.** The target's command stream is not connected; the
   server may be `offline`.
 - **Fails immediately with an interpreter error.** A bash step on a Windows
   target, or PowerShell on Linux.
 - **A value does not reach the next step.** Values pass through the file at
-  `$WORKFLOW_ENV`, one `KEY=value` per line. Declaring an output does not export
-  it.
-- **A secret is empty.** The group is not in the step's `secret_refs`, or the
-  key name differs from the environment variable you are reading.
+  `$WORKFLOW_ENV`, one `KEY=value` per line. Listing an output does not pass it
+  on by itself.
+- **A secret is empty.** The group is not attached to that step, or the key name
+  differs from the variable you are reading.
 - **Logs stop mid-run.** A reverse proxy read timeout cut the stream. The run
   itself continues; reload the page.
 
@@ -85,8 +84,8 @@ instantaneous.
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
 | Connects, then closes at once | guacd unreachable. Check `GUACD_ADDR` and that the container is running                                         |
 | SSH rejects the key           | The stored key has no private half, or is not on the target                                                     |
-| RDP fails on retry            | Credentials are single-use and consumed at tunnel open enter them again                                         |
-| Hangs, then disconnects        | The agent never claimed the relay, nothing is listening on the protocol port on the target's own loopback address, or guacd never dialled in time. Check the audit log for `console.proxy_failed` — its reason (`agent_timeout`, `dial_refused`, `guacd_timeout`, `rejected`) names which |
+| RDP fails on retry            | Credentials are single-use and consumed at tunnel open. Enter them again                                        |
+| Hangs, then disconnects       | The agent could not reach the service on that machine, or setting up the session timed out. The audit log records which |
 | Fails only in production      | The reverse proxy is not forwarding WebSocket upgrade headers                                                   |
 
 ## Monitors report down when the service is up
@@ -98,7 +97,7 @@ instantaneous.
 
 ## Notifications are not arriving
 
-Use the channel **Test** button it goes through the real delivery path, so a
+Use the channel **Test** button. It goes through the real delivery path, so a
 test that arrives proves credentials, network path and destination.
 
 If the test fails: a webhook returning 300 or above counts as a failure, SMTP
@@ -109,9 +108,9 @@ needs `host`, `port`, `from` and `to`, and Telegram needs both `token` and
 
 | Symptom                                           | Cause                                                                                                          |
 | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `409 cloud_managed` when pasting                  | It is a cloud instance. Licences are written by HQ; there is nothing to paste                                  |
-| Licence rejected as not matching                  | It is bound to a different instance UUID. Relink in HQ                                                         |
-| Instance degraded despite a valid-looking licence | It has expired past its grace period. Pasting still works that endpoint stays available specifically so it can |
+| "Managed by Vantage HQ" when pasting              | It is a cloud instance, which is licensed for you. There is nothing to paste                                   |
+| Licence rejected as not matching                  | It was issued to a different instance ID. Relink it in Vantage HQ                                              |
+| Instance degraded despite a valid-looking licence | It expired more than a few days ago. Pasting a new one still works, which is how you recover |
 | Cannot enrol another server                       | The server allowance is reached. Raise it in HQ or remove one                                                  |
 
 ## HQ portal problems
@@ -129,5 +128,5 @@ docker compose logs --tail=200 server
 journalctl -u vantage-agent --no-pager -n 200   # on the affected machine
 ```
 
-Include your instance UUID from **Settings → Licence** it is the reference
+Include your instance ID from the **Licence** page, which is the reference
 support works from.

docsite/docs/vantage/audit-log.md

@@ -4,7 +4,8 @@ title: Audit log
 sidebar_label: Audit log
 ---
 
-Every mutating API path writes an audit event. The log is at **Audit**.
+Anything that changes something is recorded, whether it was done in the UI or by
+a script. The log is at **Audit Log**.
 
 ## What an event carries
 
@@ -23,21 +24,24 @@ keys and assignments, workflow and step changes, runs triggered, monitors and
 channels, secret groups and reveals, console sessions opened, settings and
 member changes, licence installs.
 
-Reads are not recorded, with one deliberate exception: **revealing a secret**
-writes an event, because reading that particular thing is an act rather than a
-lookup.
+Simply looking at something is not recorded, with one exception: **revealing a
+secret** is.
 
 ## What is not recorded
 
-- Sign-ins and sign-out.
+- Sign-ins and sign-outs.
 - Anything inside a console session.
 - Step output. That lives in the run log, kept under the workflow retention
   setting rather than with the audit log.
 
 ## Retention
 
-Audit events are not swept by the workflow log retention setting that setting
-governs run logs only. Audit history stays until the instance does.
+How long audit events are kept comes from your licence: 30 days on Free, a year
+on Professional, and unlimited on Enterprise. See
+[Licensing and entitlements](../hq/licensing-and-entitlements.md).
+
+This is separate from the workflow log retention setting, which covers run logs
+only.
 
 :::warning It is a log, not a control
 The audit log tells you what happened. It does not restrict what can happen, and
@@ -45,7 +49,11 @@ an admin can do anything an admin can do. Use roles for restriction and the log
 for accountability.
 :::
 
-## Getting events out
+## Searching and exporting
 
-`GET /api/audit` returns recent events as JSON and accepts a `limit`. There is
-no streaming or push export; if you need events in a SIEM, poll that endpoint.
+The page searches by actor, detail and event type, and filters by category, such
+as `workflow`, `key` or `server`. The count shown is the number of matching
+events, not the number on screen.
+
+The same events are available from the API if you want them in a log system of
+your own. See [Automating Vantage](../reference/rest-api.md).

docsite/docs/vantage/browser-console.md

@@ -4,70 +4,59 @@ title: Browser console
 sidebar_label: Browser console
 ---
 
-An SSH, RDP or VNC session in a browser tab, with no client software and no
-inbound port on the target beyond the one the protocol already uses.
+An SSH, RDP or VNC session in a browser tab, with no client software to install
+and no new port to open on the target machine.
 
-Protocol handling is Apache Guacamole's the control plane proxies a WebSocket
-to a **guacd** daemon and manages credentials around it.
+:::info Requires the console feature on your licence
+The console is a per-instance feature you enable on a paid plan. Without it, the
+Console button is unavailable. See
+[Licensing and entitlements](../hq/licensing-and-entitlements.md).
+:::
 
-## Requirements
+## What you need
 
-- `guacd` running and reachable from the server. The bundled Compose stack
-  includes it; `GUACD_ADDR` defaults to `guacd:4822`.
-- `KEY_ENCRYPTION_KEY` set, since every credential involved is stored encrypted.
-- The target's **agent must be online**. Console traffic is relayed over the
-  agent's existing outbound connection, so the control plane never needs a route
-  to the server's address — but it does need the agent.
-- No inbound port on the target, beyond what the protocol already listens on
-  locally. A service bound only to `127.0.0.1` works, because the agent dials
-  loopback on the target itself.
+- The target server's **agent must be online**. Console traffic travels over the
+  connection the agent already holds, so an offline agent means no session.
+- `KEY_ENCRYPTION_KEY` set on a self-hosted install, since every credential
+  involved is stored encrypted.
+- The service you are connecting to listening on the machine itself. It does not
+  have to be reachable from anywhere else, because the agent connects to it
+  locally.
 
 ## Opening a session
 
-From a server's page, choose **Console**. Then:
-
-1. The UI calls `POST /api/console/connect`, which mints a **one-time** session
-   token. If the target's agent is not connected, this fails immediately with
-   `409 agent_offline` rather than hanging.
-2. The browser opens a WebSocket to `GET /api/console/tunnel` with that token.
-3. The server marks the token consumed atomically, so a second use cannot
-   race and proxies the connection to guacd.
+From a server's page, choose **Console**, pick the protocol and connect. Vantage
+issues a one-time ticket for that session, and the connection is refused rather
+than left hanging if the agent is not online.
 
 ## Credentials
 
 ### SSH
 
-Authenticates with a private key stored in the [key library](./ssh-keys.md). The
-key must have its private half uploaded; a public-only key cannot open a
-session.
+Uses a private key from your [key library](./ssh-keys.md). The key must have had
+its private half uploaded; a public key alone cannot open a session.
 
 ### RDP and VNC
 
-You supply credentials when connecting. They are encrypted, **single-use**, and
-consumed when the tunnel opens. They are not retained for the next session.
+You type the credentials when you connect. They are encrypted, used once and
+discarded, so the next session asks again.
 
-:::info Why single-use
-A stored console credential is a standing grant to that machine for anyone who
-can reach the endpoint. Consuming it at tunnel-open means a leaked session token
-is worth one connection at most, and only until it is used.
-:::
+## During and after a session
 
-## Session behaviour
+Closing the tab ends the session. There is no reconnect: opening it again starts
+a fresh session.
 
-Closing the tab ends the session. There is no reconnect and no session
-persistence reopening mints a new token and a new connection.
-
-## Auditing
-
-Opening a console is an audited action, with actor, server and time. What
-happens _inside_ the session is not recorded: there is no session capture or
-keystroke log. If you need that, it has to come from the target machine.
+Opening a console is recorded in the [audit log](./audit-log.md), with who did
+it, which server and when. What happens inside the session is not recorded.
+There is no session replay or keystroke capture, so if you need that, it has to
+come from the target machine itself.
 
 ## When it does not work
 
-| Symptom                          | Cause                                                                           |
-| -------------------------------- | ------------------------------------------------------------------------------- |
-| Connects then closes immediately | guacd unreachable check `GUACD_ADDR` and that the container is up               |
-| SSH refuses the key              | The stored key has no private half, or is not in the target's `authorized_keys` |
-| RDP fails on a fresh credential  | Credentials are consumed on open; a retry needs them entered again              |
-| Hangs, then disconnects           | The agent never claimed the relay, nothing is listening on the protocol port on the target's own loopback address, or guacd never dialled in time. Check the audit log for `console.proxy_failed` — its reason (`agent_timeout`, `dial_refused`, `guacd_timeout`, `rejected`) names which |
+| Symptom                          | What to check                                                                            |
+| -------------------------------- | ------------------------------------------------------------------------------------------ |
+| Connects, then closes at once    | The console daemon is unreachable. On a self-hosted install, check that `guacd` is running |
+| SSH refuses the key              | The stored key has no private half, or is not assigned to that server                      |
+| RDP fails when you retry         | Credentials are used once. Enter them again                                                |
+| Hangs, then disconnects          | The agent could not reach the service on the machine, or the session timed out setting up. The audit log records the reason |
+| Works locally, fails in production | Your reverse proxy is not forwarding WebSocket connections                               |

docsite/docs/vantage/monitors.md

@@ -28,22 +28,22 @@ Every monitor has a **runner**:
 | `server`    | The control plane's scheduler performs the check               |
 | a server ID | That server's agent performs it locally and reports the result |
 
-Use `server` for anything reachable from the control plane public endpoints,
-your own front door. Use an agent for anything only reachable from inside the
+Use `server` for anything Vantage itself can reach, such as your public website
+or API. Use an agent for anything only reachable from inside the
 target network: a database on a private subnet, a service bound to localhost, a
 device on a management VLAN.
 
-:::tip Agent-run monitors measure what your users can't
-A check run from the control plane tells you the service is reachable from
-there. A check run on the machine tells you the process is alive. Those are
-different questions, and outages usually live in the gap.
+:::tip The two answer different questions
+A check from Vantage tells you the service is reachable over the network. A
+check on the machine tells you the process is running. Watch both where it
+matters.
 :::
 
 ## Interval, retries and state
 
-- **Interval** how often to check.
-- **Retries** how many consecutive failures are tolerated before the state
-  flips.
+- **Interval** is how often to check.
+- **Retries** is how many failures in a row are tolerated before the state
+  changes.
 
 A monitor sits in `pending` until its first result. Failures accumulate; once
 they exceed `retries`, the monitor goes `down`, an **incident** opens and the
@@ -58,21 +58,20 @@ Attach one or more [notification channels](./notification-channels.md) to a
 monitor. Channels are shared, so one Slack destination can serve every monitor
 you have.
 
-Notification state is tracked per monitor, so a service that is down for six
-hours does not send a message per interval.
+You get a message when a monitor goes down and another when it recovers, not one
+per check while it stays down.
 
 ## Uptime and incidents
 
 The monitor detail page shows:
 
-- **Uptime**, from hourly rollup records checks performed, how many were up,
-  and mean latency per hour. Rollups are what make the graph cheap to draw over
-  long windows.
+- **Uptime**, summarised per hour: how many checks ran, how many passed and the
+  average response time.
 - **Incidents**, each with a start, a resolution and the cause recorded at the
   moment it opened.
 
 ## Disabling versus deleting
 
 Disabling stops the checks and keeps the history. Deleting removes the monitor.
-Prefer disabling for anything seasonal the uptime record is usually the part
-you wanted.
+Disable anything seasonal rather than deleting it, since the uptime record is
+usually the part worth keeping.

docsite/docs/vantage/notification-channels.md

@@ -4,8 +4,8 @@ title: Notification channels
 sidebar_label: Notification channels
 ---
 
-A channel is a destination for alerts. [Monitors](./monitors.md) reference
-channels by ID, so one destination serves as many monitors as you like.
+A channel is a destination for alerts. One channel serves as many
+[monitors](./monitors.md) as you like.
 
 Manage them at **Settings → Notifications**.
 
@@ -64,9 +64,7 @@ Posts the alert as message content.
 
 Port `465` uses implicit TLS; anything else uses STARTTLS.
 
-Alert emails are rendered by the same email system that sends licence and
-account mail, so a monitor alert and an account email look like the same
-product.
+Alert emails look like the rest of the mail Vantage sends you.
 
 ## The message
 
@@ -83,9 +81,9 @@ something that needs to branch on status.
 ## Testing
 
 Every channel has a **Test** button. It dispatches a fabricated down event for a
-monitor called "Test monitor", through the real delivery path so a test that
-arrives proves the credentials, the network path and the destination, not just
-the configuration form.
+monitor called "Test monitor" and sends it the same way a real alert goes out, so
+a test that arrives proves the credentials, the network path and the destination
+as well as the form.
 
 :::tip Test after every change
 Channel settings are only exercised when something breaks, which is the worst

docsite/docs/vantage/secrets.md

@@ -10,54 +10,53 @@ External Secrets Operator.
 
 ## Groups and values
 
-A **group** is a named bundle `prod-db`, `registry`, `acme-api`. Inside it are
-key/value pairs.
+A **group** is a named bundle, such as `prod-db`, `registry` or `acme-api`.
+Inside it are key/value pairs.
 
-Group by consumer, not by type. A group is the unit a workflow step references
-and the unit ESO reads, so a group that matches one consumer is one reference;
-a group holding everything is over-sharing to every step that needs any of it.
+Group by who uses them rather than by what they are. A workflow step references
+a whole group, so a group that matches one job stays tidy, while a group holding
+everything hands all of it to every step that needs any of it.
 
 ## Managing them
 
 **Secrets → New group**, then add keys.
 
-Values are write-then-hidden. The list shows keys, never values. **Reveal** is a
-separate action on a separate endpoint, and it writes an audit event so
-looking at a secret is a recorded act.
+Once saved, a value is hidden. The list shows key names only. **Reveal** is a
+separate action, and it is written to the audit log.
 
 Deleting a single key and deleting the whole group are separate operations.
 
 ## Using secrets in workflows
 
-Add the group name to a step's `secret_refs`. At execution the group's pairs are
-injected into the step's environment:
+Add the group to a step's secret references. When the step runs, the group's
+pairs are available to it as environment variables:
 
 ```bash
-# secret_refs: ["registry"]
+# with the "registry" group attached to this step
 echo "$REGISTRY_PASSWORD" | docker login registry.example.com -u "$REGISTRY_USER" --password-stdin
 ```
 
-A workflow can also override `secret_refs` per step, without changing the
-library entry.
+A workflow can change which groups a step uses without changing the step in the
+library.
 
 :::warning A step can print its own secrets
-Injection puts values in the environment. If your script echoes them, or runs
-with `set -x`, they land in the run log which is stored on disk and readable
-in the UI. Vantage does not scrub step output.
+Values arrive as environment variables. If your script prints them, or runs with
+`set -x`, they end up in the run log, which anyone who can see the run can read.
+Vantage does not filter step output.
 :::
 
 ## Kubernetes External Secrets Operator
 
-`GET /api/secrets/:group/values` returns a group's pairs for ESO, authenticated
-with a **bearer token** rather than a session.
+Kubernetes can read a secret group directly, using a token rather than a
+sign-in.
 
-1. Generate the token at **Settings → Integrations**. It is shown once; only its
-   SHA-256 is stored.
+1. Generate the token at **Settings → Integrations**. It is shown once, and
+   Vantage stores only a fingerprint of it.
 2. Put it in a Kubernetes secret.
-3. Point an ESO `SecretStore` at the endpoint with that bearer token.
+3. Point an External Secrets Operator `SecretStore` at your Vantage address with
+   that token.
 
-The token is rotatable: generating a new one replaces the stored hash and
-invalidates the old one immediately.
+Generating a new token replaces the old one immediately.
 
 :::danger This token reads every group
 It is instance-wide, not scoped to one group. Treat it as a credential to the

docsite/docs/vantage/servers.md

@@ -5,8 +5,8 @@ sidebar_label: Servers
 ---
 
 The fleet. Every managed machine runs an agent that connects outbound to the
-control plane, and everything else in Vantage keys, workflows, monitors,
-consoles targets these records.
+control plane. Keys, workflows, monitors and consoles all point at these
+records.
 
 ## Enrolling a server
 
@@ -23,18 +23,17 @@ a one-liner to run as root on the target machine.
 | `offline` | Last-seen passed the threshold                      |
 
 The offline sweep runs every two minutes, so a machine that has just gone away
-takes a little while to be marked as such. That delay is intentional a single
-missed poll is not an outage.
+takes a little while to be marked as such.
 
 ## Tags
 
 A tag is a `key:value` label you put on a server. Tags are how you say what a
-machine **is** `env:prod`, `role:web`, `team:core-infra` so that you can find
-it later, and so that a [workflow](./workflows.md) can target it without you
+machine is, such as `env:prod`, `role:web` or `team:core-infra`, so that you can
+find it later and so a [workflow](./workflows.md) can target it without you
 naming it by hand.
 
-There is no tag library to manage first. A tag exists because a server carries
-it, and it stops existing when the last server carrying it drops it.
+There is no tag library to set up first. A tag exists as soon as a server
+carries it, and disappears when the last server carrying it drops it.
 
 ### The rules
 
@@ -45,25 +44,22 @@ it, and it stops existing when the last server carrying it drops it.
 | Value length | up to 64 characters                             |
 | Per server | up to 20 tags                                     |
 
-Neither half may be empty, and keys beginning `sys:` are reserved for tags
-Vantage may derive from inventory later, so a tag you write today can never
-collide with one invented for you tomorrow.
+Neither half may be empty, and keys beginning `sys:` are reserved for Vantage's
+own use.
 
-Anything outside those rules is refused with a message naming the rule, rather
-than quietly saved in a shape you did not intend. Uppercase is not folded to
-lowercase for you `Env` is a mistake, not a synonym for `env`.
+Anything outside those rules is refused, with a message naming the rule.
+Uppercase is not corrected for you, so `Env` and `env` are different tags.
 
 ### Editing a server's tags
 
-On the server detail page, **Edit** beside the tag chips. Saving replaces the
-whole set: what you see in the editor is exactly what the server will have.
-There is no per-tag merge, so if two people edit the same server at once, the
-last save wins outright rather than producing a blend of the two.
+On the server's page, click **Edit** beside the tags. Saving replaces the whole
+set, so what you see in the editor is exactly what the server ends up with. If
+two people edit the same server at once, the last save wins.
 
 ### Filtering the fleet
 
 The **Servers** list has a picker per tag key in use. Choosing values from more
-than one key narrows the list a server must match **all** of them, not any.
+than one key narrows the list, because a server must match **all** of them.
 Untagged servers appear only when no filter is set.
 
 :::tip A filtered fleet view is a link
@@ -96,16 +92,13 @@ metrics is normal rather than a fault.
 Agents check for pending package updates hourly and report the count. From the
 server page you can:
 
-- **Apply updates** pushes `ApplyUpdatesCmd` down the command stream. The
-  agent runs the platform's package manager and reports back.
-- **Update agent** pushes `UpdateAgentCmd` with a target version; the agent
-  downloads the release, verifies it and replaces itself. See
+- **Apply updates** runs the machine's own package manager and reports back.
+- **Update agent** upgrades the Vantage agent on that machine. See
   [Agent updates](../operations/agent-updates.md).
 
 :::warning Applying updates is not scheduled or staged
-It runs now, on that machine. If you need ordering, health gates or a canary,
-build it as a [workflow](./workflows.md) instead that is what workflows exist
-for.
+It runs immediately, on that machine. If you need ordering, health checks or a
+test machine first, build it as a [workflow](./workflows.md) instead.
 :::
 
 ### Console
@@ -114,10 +107,8 @@ Opens a browser SSH, RDP or VNC session. See [Browser console](./browser-console
 
 ## Windows servers
 
-Windows agents register, heartbeat, run workflow steps and report inventory.
-They do not manage `authorized_keys` the poll loop stops after the heartbeat
-on any non-Linux host. This is a deliberate scope decision, not a gap being
-worked on.
+Windows agents register, run workflow steps and report inventory. They do not
+manage `authorized_keys`.
 
 ## Removing a server
 
@@ -138,7 +129,6 @@ no longer running to remove them. Revoke and let the agent apply the change
 
 ## Agent tokens
 
-Each server has its own token. The control plane stores only its SHA-256; the
-plaintext exists in the agent's `0600` config and nowhere else. There is no way
-to read a token back out of the control plane if one is lost, re-enrol the
-machine.
+Each server has its own token, which exists in full only in the agent's config
+file on that machine. Vantage stores a fingerprint of it and cannot show it to
+you again. If a token is lost, enrol the machine again.

docsite/docs/vantage/settings.md

@@ -4,31 +4,14 @@ title: Settings
 sidebar_label: Settings
 ---
 
-One page, three groups: **Access**, **Monitoring** and **Integrations**. Plus
-the licence, which has its own page.
+One page, three groups: **Access**, **Monitoring** and **Integrations**. Your
+licence has its own page.
 
-Settings require the `owner` or `admin` role.
-
-:::info Where instance settings went
-Members and single sign-on used to live at `/settings/instance`. They are now
-the Access group at the top of this page splitting "who can sign in" from "how
-this instance behaves" produced two half-pages and a nav entry nobody could
-distinguish from Settings. The old path still redirects.
-:::
-
-:::danger Upgrading breaks existing single sign-on until you re-register the callback URL
-Callback URLs are now per provider instead of one shared URL for the whole
-instance. If you already had single sign-on configured, it was carried
-forward automatically, but its callback URL changed and **sign-in through it
-will fail until you copy the new callback URL from its settings card and
-register it with your identity provider**. The migrated provider's card shows
-a dismissable warning as a reminder. Password sign-in is not affected by this
-change, so an administrator can always sign in locally to make the update.
-:::
+Settings need the `owner` or `admin` role.
 
 ## Access
 
-### Members
+### People
 
 Add, remove and re-role the people who can sign in.
 
@@ -38,112 +21,103 @@ Add, remove and re-role the people who can sign in.
 | `admin`  | Everything except owner-only settings                |
 | `member` | Servers, keys, workflows, monitors, secrets, console |
 
-Local members authenticate with email and a bcrypt-hashed password.
+Local members sign in with an email address and a password.
 
-#### Members managed by Vantage HQ
+#### People managed by Vantage HQ
 
-On a cloud instance, people granted access from the HQ portal appear here as
-read-only rows with a link to the portal.
+On a cloud instance, anyone granted access from the Vantage HQ portal appears
+here as a read-only row with a link back to the portal.
 
-:::warning HQ-managed users cannot be edited locally
-Changing the role of, or deleting, an `hq`-sourced user is refused with `409`.
-HQ owns their role, their password and whether they exist at all a local
-change would be overwritten by the next sync and would leave two writers for one
-password hash. Manage them from [People and roles](../hq/people-and-roles.md).
+:::warning You cannot edit those people here
+Their role, password and access are owned by Vantage HQ, so changing or removing
+them has to be done there. See
+[People and roles](../hq/people-and-roles.md).
 :::
 
 ### Single sign-on
 
-Add as many identity providers as you need: one instance can have several at
-once, each with its own name, its own button on the login page and its own
-callback URL.
+:::info Requires the single sign-on feature on your licence
+It is a per-instance feature you enable on a paid plan.
+:::
 
-Pick a provider from the list of presets:
+Add as many identity providers as you need. Each has its own name, its own
+button on the login page and its own callback URL.
 
-| Preset                 | You provide                                |
-| ---------------------- | ------------------------------------------- |
-| Microsoft Entra ID     | Directory (tenant) ID                       |
-| Google Workspace       | nothing further, the issuer is fixed        |
-| Okta                   | Your Okta org domain                        |
-| GitHub                 | Client ID and client secret only            |
-| Other (OpenID Connect) | The issuer URL of your identity provider    |
+If you configured single sign-on on an older version, see
+[Upgrading](../operations/upgrading.md#single-sign-on-after-an-upgrade).
 
-Every provider also needs a **Client ID** and **Client secret**; the secret is
-stored AES-256-GCM encrypted and never shown again after you save it.
+Start from a preset:
 
-:::info GitHub requires a verified primary email
-Vantage signs a person in by their email address. GitHub is asked for the
-account's addresses and only accepts one that is **both** the account's
-primary address **and** marked verified: an address GitHub has not confirmed
-is not proof anyone controls it.
+| Preset                 | You provide                              |
+| ---------------------- | ---------------------------------------- |
+| Microsoft Entra ID     | Directory (tenant) ID                    |
+| Google Workspace       | Nothing further                          |
+| Okta                   | Your Okta org domain                     |
+| GitHub                 | Client ID and client secret only         |
+| Other (OpenID Connect) | The issuer URL of your provider          |
+
+Every provider also needs a **Client ID** and **Client secret**. The secret is
+stored encrypted and is never shown again after you save it.
+
+:::info GitHub needs a verified primary email
+Vantage identifies people by email address, and it only accepts a GitHub address
+that is both the account's primary address and confirmed by GitHub.
 :::
 
 #### Callback URL
 
-Each provider gets its own callback URL, shown on its settings card with a
-copy button. This is the address you register with the identity provider when
-you set up the application on their side: each provider is registered
-separately, even if you have several with the same identity provider.
+Each provider's card shows its callback URL with a copy button. That is the
+address you register with the identity provider when you set up the application
+on their side. Register each provider separately, even where several use the
+same identity provider.
 
 #### Turning off password sign-in
 
-You can disable local (email and password) sign-in once at least one provider
-is enabled. Vantage refuses to save a change that would leave nobody able to
-sign in, whether that change comes from the local login toggle or from
-disabling the last enabled provider. Keep at least one option open until every
-person who needs access can reach the new one.
+Once at least one provider is enabled you can turn off email and password
+sign-in. Vantage refuses any change that would leave nobody able to sign in,
+whether that is switching off passwords or disabling your last provider. Keep
+one route open until everyone who needs access can use the new one.
 
 ## Monitoring
 
-- **Alert defaults** for monitors.
-- **Notification channels** their own page. See
-  [Notification channels](./notification-channels.md).
-
-## Integrations
-
-### Workflow log retention
-
-How long run logs are kept.
+- **Offline threshold**, how long a server may go unheard from before it is
+  marked offline. The default is 5 minutes.
+- **Offline alerts**, the [notification channels](./notification-channels.md) to
+  tell when that happens.
+- **Notification channels** have [their own page](./notification-channels.md).
+- **Workflow log retention**, how long run logs are kept.
 
 | Value    | Meaning        |
 | -------- | -------------- |
 | unset    | 30 days        |
 | a number | that many days |
-| `0`      | forever        |
+| `0`      | keep forever   |
 
-### ESO read token
+## Integrations
 
-The bearer token External Secrets Operator uses to read secret groups. Shown
-once, stored as a SHA-256 hash, rotatable. See
+### External Secrets Operator token
+
+The token Kubernetes uses to read your secret groups. It is shown once, stored
+only as a fingerprint, and can be replaced at any time. See
 [Secrets](./secrets.md#kubernetes-external-secrets-operator).
 
 ## Licence
 
-`/settings/license` shows the deployment, tier, server allowance, enabled
-features and expiry.
+The **Licence** page, in the sidebar, shows your instance ID, whether you are
+cloud or self-hosted, your tier, server allowance, enabled features and expiry
+date.
 
-On **self-hosted**, paste a licence here. This works even while the current
-licence is expired that is the way out of degraded mode.
+On a **self-hosted** install you paste your licence here. This works even while
+your current licence has expired, which is how you get an instance out of
+read-only mode.
 
-On **cloud**, there is no paste form. The endpoint answers `409 cloud_managed`,
-because a cloud licence is written by HQ directly. The page links to the portal
-instead.
+On a **cloud** instance there is nothing to paste. Licences are installed for
+you, and the page links to the portal instead.
 
 See [Licensing and entitlements](../hq/licensing-and-entitlements.md).
 
 ## Sessions
 
-Sessions are an opaque token in the `km_session` cookie, held in Redis with a
-24-hour TTL. There is no per-session management UI; restarting Redis signs
-everyone out and affects nothing else.
-
-## Host and organisation guard
-
-On a multi-tenant deployment, a request to `<slug>.vantage.<tld>` resolves the
-organisation from the slug and rejects a session belonging to a different one.
-The label it looks for comes from `APP_ROOT_LABEL`.
-
-:::warning A wrong `APP_ROOT_LABEL` disables the guard
-It does not fail loudly it simply stops matching, and the host check stops
-protecting anything. If you serve the UI on a custom domain, set it to match.
-:::
+Signing in gives you a session that lasts 24 hours. There is no session list to
+manage. On a self-hosted install, restarting Redis signs everyone out and affects
+nothing else.

docsite/docs/vantage/ssh-keys.md

@@ -22,14 +22,12 @@ fingerprint, and never needs the private half for this path.
 
 ### Generate one on a server
 
-Vantage can have an agent generate a keypair on a managed machine
-(`GenerateKeyCmd` over the command stream). The public half comes back to the
-library. You may optionally upload the private half too, in which case it is
+Vantage can have a managed machine generate a keypair for you. The public half
+comes back to the library. You may optionally upload the private half too, in which case it is
 stored **AES-256-GCM encrypted** under `KEY_ENCRYPTION_KEY`.
 
-The JSON representation of a key exposes only `has_private_key` and
-`has_passphrase` never the material. Retrieving a stored private key is its
-own endpoint and its own audit event.
+Vantage never displays stored private key material in a list. Retrieving one is
+a separate, deliberate action, and it is written to the audit log.
 
 :::tip Why store a private key at all
 The [browser console](./browser-console.md) needs one to open an SSH session. If
@@ -38,13 +36,13 @@ you are not using the console, do not upload private halves.
 
 ## Assigning
 
-Assign a key to one or more servers. Within one poll interval 30 seconds the
-agent picks up the change.
+Assign a key to one or more servers. The agent picks up the change within about
+30 seconds.
 
 ## Revoking
 
-Revocation is **soft**: the assignment gets a `revoked_at` timestamp rather than
-being deleted, so the history of who had access to what, and when, survives.
+Revoking marks the assignment revoked, with a timestamp, rather than erasing it,
+so the record of who had access to what, and when, survives.
 
 The agent treats a revoked assignment as "not desired" and removes the line from
 `authorized_keys` on its next sync.
@@ -60,13 +58,12 @@ Each poll:
 
 1. The control plane returns the desired set of public keys for that server.
 2. The agent reads `/root/.ssh/authorized_keys` and computes fingerprints.
-3. **If the sets match, it writes nothing.** No disk churn on unchanged state,
-   which is most polls.
-4. If they differ, it writes a temporary file, then `os.Rename()`s it over the
-   real one and sets mode `0600`.
+3. **If they match, it writes nothing.** That is true of almost every check.
+4. If they differ, it writes the new file alongside the old one and swaps it in
+   one step.
 
-The rename is atomic, so a machine that dies mid-write keeps the old file
-intact. There is no window in which `authorized_keys` is truncated or partial.
+The swap cannot be interrupted halfway, so a machine that loses power mid-change
+keeps its old, working file.
 
 :::danger Vantage owns the whole file
 The agent rewrites `authorized_keys` to match the desired set. Keys added by
@@ -77,5 +74,5 @@ it in Vantage.
 ## Recovering from a lockout
 
 If you have removed every key from a machine and cannot get in, you still have
-the console provided a private key is stored or out-of-band access from your
-hosting provider. Vantage has no backdoor and does not keep a break-glass key.
+the console, provided a private key is stored, or whatever out-of-band access
+your hosting provider offers. Vantage has no backdoor and does not keep a break-glass key.

docsite/docs/vantage/vulnerabilities.md

@@ -9,8 +9,8 @@ against the security advisories published by that server's own distribution and
 raises a finding for anything not yet patched.
 
 Requires the **vulnerability scanning** feature on your licence. Without it,
-agents collect nothing at all — there is no inventory stored and no findings
-page to read.
+nothing is collected and there is no findings page. See
+[Licensing and entitlements](../hq/licensing-and-entitlements.md).
 
 ## What gets scanned
 
@@ -20,10 +20,9 @@ report.
 
 Windows servers are not scanned.
 
-Some distributions publish no machine-readable advisory feed. Those servers
-show **unsupported** on their own page rather than appearing as having no
-vulnerabilities — the two are very different answers, and only one of them is
-good news.
+Some distributions publish no security advisories Vantage can read. Those
+servers are shown as **unsupported**, rather than as having no vulnerabilities.
+Those are very different answers, and only one of them is good news.
 
 ## Why versions look "wrong"
 
@@ -43,9 +42,9 @@ the accurate one for the package you are actually running.
 
 ## The board
 
-`/vulnerabilities` groups findings by CVE. One row per CVE with the number of
-affected servers, expandable to the individual servers — the same CVE across
-forty machines is one decision, not forty.
+The **Vulnerabilities** page groups findings by CVE, one row each, with the
+number of servers affected. Expand a row to see them. The same CVE across forty
+machines is usually one decision, not forty.
 
 Severity counts at the top filter the list when clicked. The state tabs switch
 between **open**, **accepted** and **fixed**.
@@ -60,8 +59,8 @@ A finding with a known fixed version gets an **Apply updates** button, which
 runs the same OS update the server page offers. There is no separate patching
 mechanism.
 
-Vantage never patches automatically. An unattended upgrade triggered by a third
-party's data feed is a fleet-wide change nobody chose.
+Vantage never patches automatically. Applying updates is always something you
+ask for.
 
 ## Accepting a finding
 
@@ -72,23 +71,21 @@ or one with no vendor fix published at all.
 a reason that is recorded in the audit log along with your name. On that date it
 reopens by itself.
 
-The expiry is required. A dismissal with no end date is how a finding gets
-forgotten, and it is exactly what an auditor will ask to see.
+An expiry date is required, so nothing is dismissed permanently by accident.
 
 ## Alerts
 
-Alert rules live with your notification channels, under
-**Settings → Notification Channels**. A rule has a minimum severity, an optional
-server tag filter, and one or more channels.
+Alert rules live with your
+[notification channels](./notification-channels.md). A rule has a minimum
+severity, an optional server tag filter, and the channels to notify.
 
-A rule sends **one digest per scan** summarising what newly opened — never one
-message per finding. A database refresh can open several hundred findings at
-once, and a message each would flood the channel.
+A rule sends **one summary per scan** covering everything newly found, rather
+than one message per finding. A single update to the security data can raise
+hundreds at once.
 
 Findings that were already open do not re-alert.
 
 ## Fleet-wide package search
 
-`GET /api/packages/search?name=openssl` answers which servers run a given
-package and at what version, across the whole fleet. Useful during an incident
-before a finding exists for it.
+Search your whole fleet for a package by name to see which servers have it and
+at what version. Useful during an incident, before there is a finding for it.

docsite/docs/vantage/workflows.md

@@ -4,10 +4,9 @@ title: Workflows and steps
 sidebar_label: Workflows
 ---
 
-A **step** is a reusable script with declared inputs, outputs and secret
-references. A **workflow** composes steps in order and targets a set of servers.
-Running one dispatches the steps to each target's agent and streams the output
-back live.
+A **step** is a reusable script with its own inputs, outputs and secrets. A
+**workflow** puts steps in order and aims them at a set of servers. Running one
+sends the steps to each server and streams the output back as it happens.
 
 ## Steps
 
@@ -15,12 +14,12 @@ A step has:
 
 | Field                 | Meaning                                         |
 | --------------------- | ----------------------------------------------- |
-| `name`, `description` | Library identity                                |
-| `interpreter`         | `bash` or `powershell`                          |
-| `script`              | The body                                        |
-| `declared_inputs`     | Named parameters with defaults and descriptions |
-| `declared_outputs`    | Names this step promises to export              |
-| `secret_refs`         | Vault entries injected as environment variables |
+| Name and description  | How you recognise it in the library             |
+| Interpreter           | `bash` or `powershell`                          |
+| Script                | What it runs                                    |
+| Inputs                | Named parameters, with defaults                 |
+| Outputs               | Values this step passes on                      |
+| Secrets               | Vault groups made available to it               |
 
 ### Passing values between steps
 
@@ -34,42 +33,36 @@ echo "$HOSTNAME"
 echo "HOSTNAME=$HOSTNAME" >> $WORKFLOW_ENV
 ```
 
-That is the whole mechanism. `declared_outputs` documents what a step exports so
-the designer can show it; the file is what actually carries the value.
+That is the whole mechanism. Listing a step's outputs documents them for the
+designer, but writing to that file is what actually passes a value on.
 
 ### Secrets
 
-List a vault group in `secret_refs` and its key/value pairs are injected as
-environment variables when the step runs. They are not written to the run log
-unless your own script echoes them. See [Secrets](./secrets.md).
+Add a vault group to a step and its pairs are available as environment variables
+while it runs. They do not appear in the run log unless your own script prints
+them. See [Secrets](./secrets.md).
 
 ### The workspace
 
-Every run gets a per-run working directory on each target. Steps share it, so
-one step can leave a file for the next. The agent removes it at the end of the
-run (`CleanupWorkspaceCmd`).
+Every run gets its own working directory on each server. Steps share it, so one
+step can leave a file for the next. It is deleted when the run finishes.
 
 Do not use it for anything that must outlive the run.
 
 ## Default steps
 
-A small library is seeded into every organisation at boot from the image, so a
-new install is not staring at an empty page.
+Vantage ships a small library of ready-made steps, so a new install is not
+staring at an empty page.
 
 :::warning Default steps are read-only
-Editing or deleting one is refused with `409`. Seeding rewrites them on every
-boot, so an edit would silently revert and a delete would come back at the next
-restart refusing is the honest answer.
+They are reinstalled every time Vantage restarts, so any edit or deletion would
+come back anyway. Vantage refuses the change rather than letting it quietly
+revert.
 
-To customise one, use the per-step **script override** in the workflow designer,
-which belongs to that workflow and is not touched by seeding. To add to the
-shared library permanently, a file has to be committed to the repository and the
-server image rebuilt.
+To adapt one, override its script inside the workflow that uses it. That change
+belongs to the workflow and is left alone.
 :::
 
-The UI mirrors this the step modal opens read-only and Delete is hidden but
-the API is the boundary; the UI is the courtesy.
-
 ## Building a workflow
 
 1. **Workflows → New**.
@@ -81,11 +74,11 @@ the API is the boundary; the UI is the courtesy.
 
 ### Failure behaviour
 
-| `on_failure` | Effect                                                          |
-| ------------ | --------------------------------------------------------------- |
-| `stop`       | Abort this server's run. Other servers continue                 |
-| `continue`   | Record the failure, run the next step anyway                    |
-| `retry`      | Re-run the step up to `max_retries`, then treat it as a failure |
+| On failure | Effect                                                        |
+| ---------- | ------------------------------------------------------------- |
+| Stop       | Stop this server's run. Other servers carry on                 |
+| Continue   | Record the failure and run the next step anyway                |
+| Retry      | Try again up to the limit you set, then count it as a failure  |
 
 ### Per-step overrides
 
@@ -97,27 +90,21 @@ scoped to that workflow.
 
 A workflow names servers two ways, and it can use both at once:
 
-- **Target servers** an explicit list you pick from the fleet.
-- **Target tags** a `key:value` selector matched against
-  [server tags](./servers.md#tags). More than one key ANDs: a server must carry
-  every pair to match.
+- **Target servers**, a list you pick by hand.
+- **Target tags**, matched against [server tags](./servers.md#tags). Give more
+  than one tag and a server must carry all of them to match.
 
-A run goes to the **union** of the two, with duplicates removed. A server that is
-both named explicitly and matched by the selector runs once, not twice. This is
-what lets a workflow say "every production web server, plus this one box I am
-watching" without maintaining a list.
+A run goes to both sets combined. A server that is named by hand and also matched
+by a tag runs once. That is how a workflow can say "every production web server,
+plus this one machine I am watching" without you keeping a list up to date.
 
 The designer shows the resolved count as you edit, so you can see how many
 machines a change to the selector just added or removed before you save.
 
 :::warning An empty selector matches nothing
-Clearing the tag selector does not mean "all servers". A workflow with no named
-servers and no tags matches nothing and is refused at run time rather than
-reported as a success over zero machines.
-
-The alternative reading, where an empty field means the whole fleet, turns a
-cleared box into a fleet-wide run. That is not a mistake anyone should be able to
-make by deleting text.
+Clearing the tags does not mean "all servers". A workflow with no servers and no
+tags matches nothing, and running it is refused rather than reported as a
+success over zero machines.
 :::
 
 Tags are read **at run time**, not when you save. Tag a new machine `env:prod`
@@ -127,31 +114,29 @@ machine from every workflow that selected on it.
 
 ### Offline servers are still targeted
 
-A server matched by tag is dispatched to even if its agent is offline, and that
-step fails visibly on that machine. Vantage does not quietly shrink your target
-list to the machines that happened to be reachable a patch run that skipped
-three servers and reported success is worse than one that failed on three and
-said so.
+A server is still targeted when its agent is offline, and the run fails visibly
+on that machine. Vantage does not quietly drop unreachable servers from a run,
+because a patch run that skipped three servers and called itself a success is
+harder to spot than one that failed.
 
 Re-run the workflow once they are back, or fix the agent first.
 
 ## Running
 
-**Run** snapshots the resolved steps into the run record and dispatches each step
-to the target's agent over the command stream no waiting for the next poll.
+**Run** records the exact steps being run, then sends them to each server
+straight away.
 
 :::info Runs freeze their steps
-The snapshot is why editing a step tomorrow never rewrites what happened today.
-A run shows the script that actually executed, not the current library version.
+Editing a step tomorrow never changes what a past run shows. A run always
+displays the script that actually ran.
 :::
 
 Targets run **in parallel**; steps within one server run **in order**.
 
 ## Schedules
 
-A workflow can carry a schedule, and Vantage will start it the same way a person
-would — the same dispatch, the same snapshot, the same run page. A scheduled run
-is an ordinary run with `schedule` recorded as who triggered it.
+A workflow can run on a schedule. A scheduled run is an ordinary run, on the
+same run page, with the schedule recorded as what started it.
 
 Open a workflow, choose **Edit**, and tick **Run on a schedule**. The expression
 is standard five-field cron:
@@ -175,10 +160,10 @@ than the browser, so what you see is exactly what will fire.
 
 ### Timezones
 
-A schedule stores an IANA timezone by name — `Europe/London`, not an offset.
-That is what makes a 02:00 job stay at 02:00 across a daylight-saving change
-instead of drifting an hour for half the year. An unknown zone is refused when
-you save it, not at 2am.
+A schedule stores a timezone by name, such as `Europe/London`, rather than an
+offset. That keeps a 02:00 job at 02:00 across daylight-saving changes instead
+of drifting by an hour for half the year. A timezone Vantage does not recognise
+is refused when you save it.
 
 ### Overlaps are skipped, not queued
 
@@ -189,28 +174,27 @@ should fall behind visibly rather than pile up.
 
 ### Missed occurrences
 
-If the control plane was not running when an occurrence was due, it still fires
-when the control plane comes back — but only within **one hour** of the due
-time. Anything older is recorded as missed and dropped. A job missed by ten
-minutes during an upgrade should still run; one missed by two days should not
-suddenly fire at lunchtime.
+If Vantage was not running when a scheduled run was due, it still runs when
+Vantage comes back, as long as that is within **one hour** of the due time.
+Anything older is recorded as missed and skipped, so a job missed during a short
+upgrade catches up, while one missed for two days does not suddenly start at
+lunchtime.
 
 Either kind of skip is shown on the workflow's schedule panel, with the time it
 was due and why it did not run.
 
 ## Watching a run
 
-Step stdout and stderr stream back as chunks, are appended to a log file on the
-server, and the UI follows them live. Each step records status, attempts, exit
-code and its exported environment.
+Output streams back as it happens and the page follows it live. Each step
+records its status, how many attempts it took, its exit code and any values it
+passed on.
 
 **Cancel** stops a run in progress. Steps already running on an agent finish;
 nothing further is dispatched.
 
 ## Log retention
 
-Run logs are swept on a schedule set by `workflow_log_retention_days` in
-Settings:
+How long run logs are kept is set under **Settings → Monitoring**:
 
 | Value    | Meaning        |
 | -------- | -------------- |
@@ -220,16 +204,15 @@ Settings:
 
 ## Import and export
 
-Steps export to a JSON file (`vantage.step/v1`) and import back, which is how
-you move a step between instances or keep one in version control. There is also
-a parse endpoint that turns a pasted script into a draft step by reading its
-declared inputs and outputs.
+A step exports to a file and imports back, which is how you move one between
+instances or keep it in version control. You can also paste a script and have
+Vantage turn it into a draft step for you.
 
 ## Practical notes
 
 - A step is a script. It runs as root, on the target, with no sandbox. Review
   what you import.
-- Keep steps small and single-purpose; compose them in the workflow. That is
-  what makes the library reusable rather than a folder of near-duplicates.
+- Keep steps small and single-purpose, and combine them in the workflow. A
+  library of small steps stays reusable.
 - PowerShell steps only make sense on Windows targets and bash steps on Linux
   ones. Nothing stops you targeting the wrong one; the step simply fails.

docsite/docs/vantage/workloads.md

@@ -4,30 +4,27 @@ title: Workloads
 sidebar_label: Workloads
 ---
 
-A **workload** is one Docker container or one systemd service. Each Linux
-server reports what it runs, and you can start, stop and restart those
-workloads — and read a snapshot of their logs — without opening a console.
+A **workload** is one Docker container or one systemd service. Each Linux server
+reports what it is running, and you can start, stop and restart those workloads,
+and read their recent logs, without opening a console.
 
 Available on every instance. No licence feature is required.
 
 ## What gets reported
 
-Linux servers only. Agents report every 60 seconds, and an unchanged list costs
-a single small message rather than the whole thing again.
+Linux servers only, reported every 60 seconds.
 
-- **Containers** — every container, running or not, with its image, published
+- **Containers**: every container, running or not, with its image, published
   ports, health, restart count and the compose stack it belongs to.
-- **Services** — systemd units that are running or failed, plus units that are
-  enabled but currently stopped. The platform's own units (`systemd-*`,
-  `user@*`, `session-*`) are filtered out; a typical host has 300 of them and
-  they bury the ten you care about.
+- **Services**: systemd units that are running, failed, or enabled but stopped.
+  The operating system's own units are hidden, since a typical host has hundreds
+  of them and they bury the ones you care about.
 
 Windows servers report no workloads at all.
 
 ## Docker not in use is not an error
 
-Three different things look identical if you are careless, and only one of them
-is a problem:
+Three states look similar, and only one of them is a problem:
 
 | What you see | What it means |
 | ------------ | ------------- |
@@ -37,54 +34,47 @@ is a problem:
 
 ## Stacks are grouped
 
-Compose stacks appear first, grouped under the stack name, then loose
-containers, then services. A stack is one thing even when it is six containers,
-and a flat list turns one decision into six rows.
+Compose stacks appear first, grouped under the stack name, then individual
+containers, then services.
 
-The stack name comes from Docker's own `com.docker.compose.project` label. No
-compose file is read from disk — a file on disk may not be what is running.
+The stack name comes from Docker itself, so it reflects what is actually
+running.
 
 ## Controlling a workload
 
 Start, stop and restart are **owner or admin only**, and every action is
 written to the audit log naming you, the server and the target.
 
-The agent refuses to act on itself. `vantage-agent.service` is shown with its
-buttons disabled: a server that stops its own agent goes offline, and the only
-way back is SSH or physical access — which is exactly what this page exists to
-avoid needing.
+The Vantage agent will not act on itself, and its buttons are disabled. A server
+that stopped its own agent would go offline, and getting it back would need SSH
+or physical access.
 
-A stop that never finishes is not reported as success. Both `docker stop` and
-`systemctl stop` run under a 90-second limit, and a timeout comes back as a
-real error.
+A stop that never finishes is not reported as a success. Vantage waits up to 90
+seconds and then reports the failure.
 
 ## Reading logs
 
-Logs are **owner or admin only** and every read is audited. Unlike workflow
-logs, a container's output cannot be masked: it is arbitrary, and a startup
-banner or a stack trace may contain credentials nobody declared.
+Reading logs is **owner or admin only**, and every read is audited. A
+container's output cannot be filtered the way a workflow's can, and a startup
+banner or stack trace may contain credentials nobody expected.
 
-A log read returns a snapshot of at most **500 lines or 256KB**, whichever
-limit is reached first, with the most recent output kept. When either limit
-binds, the dialog says so — a truncated log must never be read as a complete
-one.
+You get the most recent output, up to **500 lines or 256KB**, whichever comes
+first. If it was cut short, the dialog says so.
 
-There is no live following. The [browser console](./browser-console.md) already
-gives you a real terminal on the same server, where `docker logs -f` works
-properly with its own scrollback.
+There is no live tail here. For that, use the
+[browser console](./browser-console.md), which gives you a real terminal on the
+same server.
 
 ## Refreshing
 
-Opening a server's Workloads panel asks its agent to report immediately, so
-what is on screen is current rather than up to a minute old. That matters
-because the panel has a Restart button on it: a stale row is not just a wrong
-impression, it is a wrong action aimed at something that already died.
+Opening a server's Workloads panel asks its agent to report straight away, so
+what you see is current rather than up to a minute old. That matters when the
+next thing you click is Restart.
 
-If the agent is offline the refresh fails visibly rather than queueing. A
-command whose target cannot be reached must say so.
+If the agent is offline, the refresh reports a failure rather than waiting.
 
 ## Fleet view
 
-**Workloads** in the sidebar searches the whole fleet by image, stack or state
-— "which of these servers is still on the old image" — and links each result
-back to its server.
+**Workloads** in the sidebar searches your whole fleet by image, stack or state,
+which is how you answer questions like "which servers are still on the old
+image". Each result links back to its server.

docsite/sidebars.ts

@@ -14,8 +14,8 @@ const sidebars: SidebarsConfig = {
                 "getting-started/cloud-vs-self-hosted",
                 "getting-started/self-hosted-install",
                 "getting-started/first-login",
-                "getting-started/first-server",
                 "getting-started/claim-free-licence",
+                "getting-started/first-server",
             ],
         },
         {
@@ -43,7 +43,7 @@ const sidebars: SidebarsConfig = {
         {
             type: "category",
             label: "Reference",
-            items: ["reference/environment-variables", "reference/rest-api", "reference/agent-config", "reference/ports-and-networking", "reference/troubleshooting"],
+            items: ["reference/environment-variables", "reference/rest-api", "reference/api-tokens", "reference/agent-config", "reference/ports-and-networking", "reference/troubleshooting"],
         },
         {
             type: "category",

server/cmd/main.go

@@ -29,6 +29,32 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+//	@title			Vantage API
+//	@version		1.0
+//	@description	The Vantage control plane REST API. Authenticate with a browser session cookie, or with an API token created under Settings → API tokens.
+//	@BasePath		/api
+
+// Each @securityDefinitions.apikey block below is deliberately its own
+// comment group, separated by a real blank line rather than a bare "//": Go's
+// parser only splits ast.CommentGroups on an actual blank line, and
+// swag v2.0.0-rc5's parseSecAttributesV3 resolves a scheme's map key by
+// scanning from the start of whatever comment group it was handed — so three
+// stacked blocks sharing one group all collapse onto the first block's name.
+// Three groups means three independent scans, each finding its own name.
+
+//	@securityDefinitions.apikey	cookieAuth
+//	@in								cookie
+//	@name							km_session
+
+//	@securityDefinitions.apikey	bearerAuth
+//	@in								header
+//	@name							Authorization
+//	@description					An API token, sent as "Bearer vt_…". Scoped and optionally expiring.
+
+//	@securityDefinitions.apikey	esoAuth
+//	@in								header
+//	@name							Authorization
+//	@description					The External Secrets read token, rotated under Settings. It reaches /api/secrets/{group}/values and nothing else. It is a different credential from an API token, and the two must never be substituted for one another.
 func main() {
 	mongoURI := getEnv("MONGO_URI", "mongodb://localhost:27017")
 
@@ -109,6 +135,10 @@ func runSchemaSetup() {
 		log.Fatalf("failed to ensure auth indexes: %v", err)
 	}
 
+	if err := services.EnsureAPITokenIndexes(); err != nil {
+		log.Fatalf("api token indexes: %v", err)
+	}
+
 	// 0005 runs AFTER EnsureAuthIndexes: the unique (instance_id, provider_id)
 	// index must exist before anything inserts providers, or a concurrent
 	// re-run could double-insert before the index is there to refuse it.
@@ -140,6 +170,10 @@ func runSchemaSetup() {
 		log.Printf("warning: failed to ensure workload indexes: %v", err)
 	}
 
+	if err := services.EnsureAuditIndexes(); err != nil {
+		log.Printf("warning: failed to ensure audit indexes: %v", err)
+	}
+
 	if instanceIDs, err := services.ListInstanceIDs(); err != nil {
 		log.Printf("warning: failed to list instances for default step seeding: %v", err)
 	} else {
@@ -226,6 +260,10 @@ func serve() {
 	r.Use(corsMiddleware())
 	api.RegisterRoutes(r)
 
+	if err := api.AssertScopeMapComplete(r); err != nil {
+		log.Fatalf("api scope map: %v", err)
+	}
+
 	srv := &http.Server{Addr: ":8080", Handler: r}
 	go func() {
 		log.Println("REST server listening on :8080")

server/internal/api/auth_providers.go

@@ -26,10 +26,30 @@ func viewOf(c *gin.Context, p models.AuthProvider) authProviderView {
 	}
 }
 
+// listAuthPresets godoc
+//
+//	@Summary		List SSO presets
+//	@Description	Preset providers (Entra, Google, Okta, GitHub) that expand to a real issuer on save.
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Success		200	{array}		auth.Preset
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/presets [get]
 func listAuthPresets(c *gin.Context) {
 	c.JSON(http.StatusOK, auth.Presets())
 }
 
+// listAuthProviders godoc
+//
+//	@Summary		List SSO providers
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Success		200	{array}		authProviderView
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers [get]
 func listAuthProviders(c *gin.Context) {
 	providers, err := services.ListAuthProviders(auth.InstanceID(c))
 	if err != nil {
@@ -43,6 +63,18 @@ func listAuthProviders(c *gin.Context) {
 	c.JSON(http.StatusOK, out)
 }
 
+// createAuthProvider godoc
+//
+//	@Summary		Create an SSO provider
+//	@Tags			auth-providers
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{name=string,preset=string,issuer_input=string,client_id=string,client_secret=string,enabled=bool}	true	"Provider parameters"
+//	@Success		201	{object}	authProviderView
+//	@Failure		400	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers [post]
 func createAuthProvider(c *gin.Context) {
 	var body struct {
 		Name         string `json:"name"`
@@ -80,6 +112,22 @@ func createAuthProvider(c *gin.Context) {
 	c.JSON(http.StatusCreated, viewOf(c, *p))
 }
 
+// updateAuthProvider godoc
+//
+//	@Summary		Update an SSO provider
+//	@Tags			auth-providers
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string	true	"Provider ID"
+//	@Param			body	body		object{name=string,issuer_input=string,client_id=string,client_secret=string,enabled=bool,order=int}	true	"Fields to update"
+//	@Success		200	{object}	SavedResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id} [put]
 func updateAuthProvider(c *gin.Context) {
 	var body struct {
 		Name         *string `json:"name"`
@@ -135,9 +183,23 @@ func updateAuthProvider(c *gin.Context) {
 	// document was built from the old ones.
 	auth.EvictProvider(providerID)
 	services.LogEvent(instanceID, "auth_provider.update", actorFromCtx(c), "", "", existing.Name)
-	c.JSON(http.StatusOK, gin.H{"saved": true})
+	c.JSON(http.StatusOK, SavedResponse{Saved: true})
 }
 
+// deleteAuthProvider godoc
+//
+//	@Summary		Delete an SSO provider
+//	@Description	Refused when the instance would be left with no way in (no local login and no other enabled provider).
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Param			id	path		string	true	"Provider ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id} [delete]
 func deleteAuthProvider(c *gin.Context) {
 	instanceID := auth.InstanceID(c)
 	providerID := c.Param("id")
@@ -161,7 +223,7 @@ func deleteAuthProvider(c *gin.Context) {
 	}
 	auth.EvictProvider(providerID)
 	services.LogEvent(instanceID, "auth_provider.delete", actorFromCtx(c), "", "", existing.Name)
-	c.JSON(http.StatusOK, gin.H{"deleted": true})
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
 }
 
 // guardProviderChange asks whether the instance would still have a way in.
@@ -178,6 +240,18 @@ func guardProviderChange(instanceID string, existing *models.AuthProvider, enabl
 	return services.CheckLockout(services.IsLocalLoginEnabled(instanceID), n-1)
 }
 
+// ackAuthProviderNotice godoc
+//
+//	@Summary		Acknowledge a provider migration notice
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Param			id	path		string	true	"Provider ID"
+//	@Success		200	{object}	AcknowledgedResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id}/ack-notice [post]
 func ackAuthProviderNotice(c *gin.Context) {
 	instanceID := auth.InstanceID(c)
 	providerID := c.Param("id")
@@ -191,10 +265,21 @@ func ackAuthProviderNotice(c *gin.Context) {
 		return
 	}
 	services.LogEvent(instanceID, "auth_provider.ack_notice", actorFromCtx(c), "", "", existing.Name)
-	c.JSON(http.StatusOK, gin.H{"acknowledged": true})
+	c.JSON(http.StatusOK, AcknowledgedResponse{Acknowledged: true})
 }
 
-// testAuthProvider proves the configuration is reachable. It signs nobody in.
+// testAuthProvider godoc
+//
+//	@Summary		Test an SSO provider's reachability
+//	@Description	Proves the configuration is reachable. It signs nobody in.
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Param			id	path		string	true	"Provider ID"
+//	@Success		200	{object}	TestProviderResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id}/test [post]
 func testAuthProvider(c *gin.Context) {
 	instanceID := auth.InstanceID(c)
 	p, err := services.GetAuthProvider(instanceID, c.Param("id"))
@@ -206,15 +291,15 @@ func testAuthProvider(c *gin.Context) {
 		// GitHub has no discovery document. The only meaningful check without
 		// a user token is that credentials are present.
 		if p.ClientID == "" || p.ClientSecretEnc == "" {
-			c.JSON(http.StatusOK, gin.H{"ok": false, "message": "client ID and secret are required"})
+			c.JSON(http.StatusOK, TestProviderResponse{OK: false, Message: "client ID and secret are required"})
 			return
 		}
-		c.JSON(http.StatusOK, gin.H{"ok": true, "message": "credentials are configured"})
+		c.JSON(http.StatusOK, TestProviderResponse{OK: true, Message: "credentials are configured"})
 		return
 	}
 	if _, err := oidc.NewProvider(c.Request.Context(), p.Issuer); err != nil {
-		c.JSON(http.StatusOK, gin.H{"ok": false, "message": err.Error()})
+		c.JSON(http.StatusOK, TestProviderResponse{OK: false, Message: err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"ok": true, "message": "discovery document fetched"})
+	c.JSON(http.StatusOK, TestProviderResponse{OK: true, Message: "discovery document fetched"})
 }

server/internal/api/channels.go

@@ -18,6 +18,16 @@ func registerChannelRoutes(g *gin.RouterGroup) {
 	g.POST("/channels/:id/test", testChannel)
 }
 
+// listChannels godoc
+//
+//	@Summary		List notification channels
+//	@Tags			channels
+//	@Produce		json
+//	@Success		200	{array}		models.NotificationChannel
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels [get]
 func listChannels(c *gin.Context) {
 	channels, err := services.ListChannels(auth.InstanceID(c))
 	if err != nil {
@@ -27,6 +37,20 @@ func listChannels(c *gin.Context) {
 	c.JSON(http.StatusOK, channels)
 }
 
+// createChannel godoc
+//
+//	@Summary		Create a notification channel
+//	@Tags			channels
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		models.NotificationChannel	true	"Channel to create"
+//	@Success		201	{object}	models.NotificationChannel
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		403	{object}	LimitExceededResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels [post]
 func createChannel(c *gin.Context) {
 	var ch models.NotificationChannel
 	if err := c.ShouldBindJSON(&ch); err != nil {
@@ -48,6 +72,20 @@ func createChannel(c *gin.Context) {
 	c.JSON(http.StatusCreated, created)
 }
 
+// updateChannel godoc
+//
+//	@Summary		Update a notification channel
+//	@Tags			channels
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path	string											true	"Channel ID"
+//	@Param			body	body	object{name=string,type=string,config=map[string]string,enabled=bool}	true	"Fields to update"
+//	@Success		204
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels/{id} [put]
 func updateChannel(c *gin.Context) {
 	var body struct {
 		Name    *string            `json:"name"`
@@ -83,6 +121,16 @@ func updateChannel(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }
 
+// deleteChannel godoc
+//
+//	@Summary		Delete a notification channel
+//	@Tags			channels
+//	@Param			id	path	string	true	"Channel ID"
+//	@Success		204
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels/{id} [delete]
 func deleteChannel(c *gin.Context) {
 	if err := services.DeleteChannel(auth.InstanceID(c), c.Param("id")); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
@@ -91,10 +139,21 @@ func deleteChannel(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }
 
+// testChannel godoc
+//
+//	@Summary		Send a test notification
+//	@Tags			channels
+//	@Produce		json
+//	@Param			id	path		string	true	"Channel ID"
+//	@Success		200	{object}	StatusResponse
+//	@Failure		502	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels/{id}/test [post]
 func testChannel(c *gin.Context) {
 	if err := services.TestChannel(auth.InstanceID(c), c.Param("id")); err != nil {
 		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"status": "sent"})
+	c.JSON(http.StatusOK, StatusResponse{Status: "sent"})
 }

server/internal/api/console.go

@@ -16,6 +16,22 @@ import (
 	"github.com/wwt/guac"
 )
 
+// consoleConnect godoc
+//
+//	@Summary		Open a browser console session
+//	@Description	Mints a one-time session token for the /console/tunnel websocket. Requires a live agent — answers 409 agent_offline otherwise.
+//	@Tags			console
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{server_id=string,protocol=string,key_id=string,rdp_username=string,rdp_password=string,ssh_username=string}	true	"Session parameters"
+//	@Success		200	{object}	ConsoleConnectResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/console/connect [post]
 func consoleConnect(c *gin.Context) {
 	var body struct {
 		ServerID    string `json:"server_id" binding:"required"`
@@ -73,10 +89,10 @@ func consoleConnect(c *gin.Context) {
 	services.LogEvent(auth.InstanceID(c), "console.opened", actorFromCtx(c), srv.ServerID, "",
 		"console session opened ("+body.Protocol+", agent-relayed)")
 
-	c.JSON(http.StatusOK, gin.H{
-		"session_id": sess.SessionID,
-		"token":      token,
-		"ws_path":    "/api/console/tunnel",
+	c.JSON(http.StatusOK, ConsoleConnectResponse{
+		SessionID: sess.SessionID,
+		Token:     token,
+		WSPath:    "/api/console/tunnel",
 	})
 }
 
@@ -100,6 +116,21 @@ func queryIntDefault(r *http.Request, key string, def int) int {
 //
 // Lines are prefixed with the session ID so one attempt can be followed across
 // pods, and the pod's own hostname so it is obvious which one served it.
+// consoleTunnel godoc
+//
+//	@Summary		Console websocket tunnel
+//	@Description	Upgrades the browser's connection to a websocket and joins it to guacd, relayed through the agent. Consumes the one-time session token from /console/connect.
+//	@Tags			console
+//	@Param			token	query	string	true	"One-time session token"
+//	@Success		101
+//	@Failure		401	{object}	ErrorResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/console/tunnel [get]
 func consoleTunnel(c *gin.Context) {
 	host, _ := os.Hostname()
 

server/internal/api/docs/doc.go

@@ -0,0 +1,23 @@
+// Package docs holds the generated OpenAPI document and the vendored Scalar
+// bundle that renders it.
+//
+// openapi.json is generated by `swag init` and committed rather than built into
+// the image: server/Dockerfile produces a scratch runtime from a Go build
+// stage, and adding codegen there means putting the toolchain in the image.
+// server-deploy.yml regenerates and diffs it, so an annotation edited without
+// regenerating fails the build.
+//
+// scalar.standalone.js is vendored from
+// https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest/dist/browser/standalone.js
+// and refreshed by hand. Fetched at build time it would break an air-gapped
+// install; fetched at page load it would break an air-gapped install more
+// visibly.
+package docs
+
+import _ "embed"
+
+//go:embed openapi.json
+var OpenAPI []byte
+
+//go:embed scalar.standalone.js
+var ScalarJS []byte

server/internal/api/handlers.go

@@ -14,10 +14,17 @@ import (
 )
 
 func actorFromCtx(c *gin.Context) string {
-	if sess := auth.GetSessionFromContext(c); sess != nil && sess.Email != "" {
-		return sess.Email
+	sess := auth.GetSessionFromContext(c)
+	if sess == nil || sess.Email == "" {
+		return "admin"
 	}
-	return "admin"
+	// The actor stays the human, because a token acts on their behalf and the
+	// log has to name somebody. The credential is appended so a person clicking
+	// and their CI job are told apart.
+	if sess.TokenID != "" {
+		return fmt.Sprintf("%s (via token:%s)", sess.Email, sess.TokenName)
+	}
+	return sess.Email
 }
 
 func RegisterRoutes(r *gin.Engine) {
@@ -42,6 +49,11 @@ func RegisterRoutes(r *gin.Engine) {
 
 	apiGroup := r.Group("/api")
 	apiGroup.Use(auth.Middleware())
+	// Scope enforcement sits between authentication and the licence gate, and
+	// no-ops for cookie sessions. It is mounted here rather than per route so
+	// a route added later is covered by where it lives, not by memory.
+	apiGroup.Use(RequireScopes())
+	apiGroup.Use(RateLimitTokens())
 	// Deny by default: every non-GET route under /api is gated unless it is on
 	// the exemption list in licence.go. A route added later is covered because
 	// of where it is mounted, not because someone remembered.
@@ -68,6 +80,15 @@ func RegisterRoutes(r *gin.Engine) {
 
 		apiGroup.GET("/audit", listAuditEvents)
 
+		apiGroup.GET("/tokens", listTokens)
+		apiGroup.GET("/tokens/scopes", listTokenScopes)
+		apiGroup.POST("/tokens", createToken)
+		apiGroup.DELETE("/tokens/:id", revokeToken)
+
+		apiGroup.GET("/openapi.json", getOpenAPI)
+		apiGroup.GET("/docs", getAPIDocs)
+		apiGroup.GET("/docs/scalar.js", getScalarJS)
+
 		settings := apiGroup.Group("/settings")
 		settings.Use(auth.RequireRole("owner", "admin"))
 		{
@@ -144,6 +165,19 @@ func RegisterRoutes(r *gin.Engine) {
 	}
 }
 
+// listServers godoc
+//
+//	@Summary		List servers
+//	@Description	Returns every server in the instance, optionally filtered by tag (repeatable, key:value).
+//	@Tags			servers
+//	@Produce		json
+//	@Param			tag	query		[]string	false	"Filter by tag as key:value, repeatable"
+//	@Success		200	{array}		models.Server
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers [get]
 func listServers(c *gin.Context) {
 	sel, err := services.ParseTagFilters(c.QueryArray("tag"))
 	if err != nil {
@@ -158,6 +192,17 @@ func listServers(c *gin.Context) {
 	c.JSON(http.StatusOK, servers)
 }
 
+// listKnownTags godoc
+//
+//	@Summary		List known tags
+//	@Description	Returns every tag key currently used by any server, with the values seen for each.
+//	@Tags			servers
+//	@Produce		json
+//	@Success		200	{object}	map[string][]string
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/tags [get]
 func listKnownTags(c *gin.Context) {
 	tags, err := services.KnownTags(auth.InstanceID(c))
 	if err != nil {
@@ -167,6 +212,22 @@ func listKnownTags(c *gin.Context) {
 	c.JSON(http.StatusOK, tags)
 }
 
+// putServerTags godoc
+//
+//	@Summary		Replace a server's tags
+//	@Description	Replaces the whole tag map for a server. Last write wins.
+//	@Tags			servers
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string				true	"Server ID"
+//	@Param			body	body		object{tags=map[string]string}	true	"New tag map"
+//	@Success		200	{object}	TagsResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/tags [put]
 func putServerTags(c *gin.Context) {
 	var body struct {
 		Tags map[string]string `json:"tags"`
@@ -196,9 +257,21 @@ func putServerTags(c *gin.Context) {
 
 	services.LogEvent(instanceID, "server.tags_updated", actorFromCtx(c), serverID, "",
 		fmt.Sprintf("tags %v -> %v", before.Tags, body.Tags))
-	c.JSON(http.StatusOK, gin.H{"tags": body.Tags})
+	c.JSON(http.StatusOK, TagsResponse{Tags: body.Tags})
 }
 
+// createServer godoc
+//
+//	@Summary		Add a server
+//	@Description	Creates a server record and a single-use pre-registration token (TTL 1 hour).
+//	@Tags			servers
+//	@Produce		json
+//	@Success		201	{object}	CreateServerResponse
+//	@Failure		403	{object}	LimitExceededResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers [post]
 func createServer(c *gin.Context) {
 	s, token, err := services.CreateServer(auth.InstanceID(c))
 	if err != nil {
@@ -208,13 +281,26 @@ func createServer(c *gin.Context) {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusCreated, gin.H{
-		"server":    s,
-		"token":     token,
-		"server_id": s.ServerID,
+	c.JSON(http.StatusCreated, CreateServerResponse{
+		Server:   s,
+		Token:    token,
+		ServerID: s.ServerID,
 	})
 }
 
+// newServer godoc
+//
+//	@Summary		Add a server (install page)
+//	@Description	Identical to POST /servers; also reachable by GET for the install page. Mints a new pre-registration token.
+//	@Tags			servers
+//	@Produce		json
+//	@Success		200	{object}	NewServerResponse
+//	@Failure		403	{object}	LimitExceededResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/new [get]
+//	@Router			/servers/new [post]
 func newServer(c *gin.Context) {
 	s, token, err := services.CreateServer(auth.InstanceID(c))
 	if err != nil {
@@ -238,14 +324,26 @@ func newServer(c *gin.Context) {
 		host, s.ServerID, token,
 	)
 
-	c.JSON(http.StatusOK, gin.H{
-		"server_id":          s.ServerID,
-		"pre_reg_token":      token,
-		"install_command":    installCmd,
-		"install_command_ps": installCmdPS,
+	c.JSON(http.StatusOK, NewServerResponse{
+		ServerID:         s.ServerID,
+		PreRegToken:      token,
+		InstallCommand:   installCmd,
+		InstallCommandPS: installCmdPS,
 	})
 }
 
+// getServer godoc
+//
+//	@Summary		Get a server
+//	@Description	Returns a server together with its resolved key assignments.
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		200	{object}	ServerDetailResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id} [get]
 func getServer(c *gin.Context) {
 	id := c.Param("id")
 	s, err := services.GetServer(auth.InstanceID(c), id)
@@ -256,16 +354,23 @@ func getServer(c *gin.Context) {
 
 	assignments, _ := services.GetAssignmentsWithKeysForServer(auth.InstanceID(c), id)
 
-	type serverResponse struct {
-		*models.Server
-		Keys interface{} `json:"keys"`
-	}
-	c.JSON(http.StatusOK, serverResponse{
+	c.JSON(http.StatusOK, ServerDetailResponse{
 		Server: s,
 		Keys:   assignments,
 	})
 }
 
+// deleteServer godoc
+//
+//	@Summary		Delete a server
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id} [delete]
 func deleteServer(c *gin.Context) {
 	id := c.Param("id")
 	s, _ := services.GetServer(auth.InstanceID(c), id)
@@ -278,9 +383,24 @@ func deleteServer(c *gin.Context) {
 		hostname = s.Hostname
 	}
 	services.LogEvent(auth.InstanceID(c), "server.deleted", actorFromCtx(c), id, "", fmt.Sprintf("server %s deleted", hostname))
-	c.JSON(http.StatusOK, gin.H{"deleted": true})
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
 }
 
+// generateKey godoc
+//
+//	@Summary		Generate a key on a server
+//	@Description	Dispatches an agent command that generates a keypair on the target server and reports it back.
+//	@Tags			keys
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string					true	"Server ID"
+//	@Param			body	body		object{label=string,key_type=string,key_size=int,passphrase=string,comment=string}	false	"Key generation parameters"
+//	@Success		202	{object}	GenerateKeyResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/generate-key [post]
 func generateKey(c *gin.Context) {
 	id := c.Param("id")
 
@@ -315,13 +435,23 @@ func generateKey(c *gin.Context) {
 	}
 
 	services.LogEvent(auth.InstanceID(c), "key.generation_dispatched", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("key generation dispatched (label=%s type=%s)", body.Label, body.KeyType))
-	c.JSON(http.StatusAccepted, gin.H{
-		"message":    "key generation command sent to agent",
-		"command_id": cmdID,
-		"server_id":  s.ServerID,
+	c.JSON(http.StatusAccepted, GenerateKeyResponse{
+		Message:   "key generation command sent to agent",
+		CommandID: cmdID,
+		ServerID:  s.ServerID,
 	})
 }
 
+// listKeys godoc
+//
+//	@Summary		List keys
+//	@Tags			keys
+//	@Produce		json
+//	@Success		200	{array}		models.Key
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys [get]
 func listKeys(c *gin.Context) {
 	keys, err := services.ListKeys(auth.InstanceID(c))
 	if err != nil {
@@ -331,6 +461,19 @@ func listKeys(c *gin.Context) {
 	c.JSON(http.StatusOK, keys)
 }
 
+// createKey godoc
+//
+//	@Summary		Upload a key
+//	@Tags			keys
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{label=string,public_key=string,private_key=string,passphrase=string}	true	"Key material"
+//	@Success		201	{object}	models.Key
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys [post]
 func createKey(c *gin.Context) {
 	var body struct {
 		Label      string `json:"label" binding:"required"`
@@ -352,6 +495,18 @@ func createKey(c *gin.Context) {
 	c.JSON(http.StatusCreated, key)
 }
 
+// getPrivateKey godoc
+//
+//	@Summary		Get a key's private material
+//	@Description	Returns the decrypted private key. Reading is a keys:read action even though the material is sensitive.
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id	path		string	true	"Key ID"
+//	@Success		200	{object}	PrivateKeyResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id}/private-key [get]
 func getPrivateKey(c *gin.Context) {
 	id := c.Param("id")
 	plaintext, err := services.GetPrivateKey(auth.InstanceID(c), id)
@@ -359,9 +514,21 @@ func getPrivateKey(c *gin.Context) {
 		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"private_key": plaintext})
+	c.JSON(http.StatusOK, PrivateKeyResponse{PrivateKey: plaintext})
 }
 
+// getKey godoc
+//
+//	@Summary		Get a key
+//	@Description	Returns a key together with the servers it is assigned to.
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id	path		string	true	"Key ID"
+//	@Success		200	{object}	KeyDetailResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id} [get]
 func getKey(c *gin.Context) {
 	id := c.Param("id")
 	key, err := services.GetKey(auth.InstanceID(c), id)
@@ -372,16 +539,23 @@ func getKey(c *gin.Context) {
 
 	assignments, _ := services.GetAssignmentsWithServers(auth.InstanceID(c), id)
 
-	type keyResponse struct {
-		*models.Key
-		Assignments any `json:"assignments"`
-	}
-	c.JSON(http.StatusOK, keyResponse{
+	c.JSON(http.StatusOK, KeyDetailResponse{
 		Key:         key,
 		Assignments: assignments,
 	})
 }
 
+// deleteKey godoc
+//
+//	@Summary		Delete a key
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id	path		string	true	"Key ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id} [delete]
 func deleteKey(c *gin.Context) {
 	id := c.Param("id")
 	k, _ := services.GetKey(auth.InstanceID(c), id)
@@ -394,9 +568,23 @@ func deleteKey(c *gin.Context) {
 		label = k.Label
 	}
 	services.LogEvent(auth.InstanceID(c), "key.deleted", actorFromCtx(c), "", id, fmt.Sprintf("key '%s' deleted", label))
-	c.JSON(http.StatusOK, gin.H{"deleted": true})
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
 }
 
+// assignKey godoc
+//
+//	@Summary		Assign a key to a server
+//	@Tags			keys
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string							true	"Key ID"
+//	@Param			body	body		object{server_id=string}	true	"Target server"
+//	@Success		201	{object}	models.Assignment
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id}/assign [post]
 func assignKey(c *gin.Context) {
 	keyID := c.Param("id")
 	var body struct {
@@ -416,6 +604,19 @@ func assignKey(c *gin.Context) {
 	c.JSON(http.StatusCreated, a)
 }
 
+// revokeAssignment godoc
+//
+//	@Summary		Revoke a key assignment
+//	@Description	Soft revocation: sets revoked_at rather than deleting, preserving audit history.
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id			path		string	true	"Key ID"
+//	@Param			serverId	path		string	true	"Server ID"
+//	@Success		200	{object}	RevokedResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id}/assign/{serverId} [delete]
 func revokeAssignment(c *gin.Context) {
 	keyID := c.Param("id")
 	serverID := c.Param("serverId")
@@ -425,18 +626,42 @@ func revokeAssignment(c *gin.Context) {
 		return
 	}
 	services.LogEvent(auth.InstanceID(c), "key.revoked", actorFromCtx(c), serverID, keyID, fmt.Sprintf("key %s revoked from server %s", keyID, serverID))
-	c.JSON(http.StatusOK, gin.H{"revoked": true})
+	c.JSON(http.StatusOK, RevokedResponse{Revoked: true})
 }
 
+// getLatestAgentVersion godoc
+//
+//	@Summary		Get the latest agent version
+//	@Description	Reads the latest agent/v* tag from the Gitea release API.
+//	@Tags			servers
+//	@Produce		json
+//	@Success		200	{object}	AgentVersionResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/agent/latest-version [get]
 func getLatestAgentVersion(c *gin.Context) {
 	version, err := services.GetLatestAgentVersion()
 	if err != nil {
 		c.JSON(http.StatusServiceUnavailable, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"version": version})
+	c.JSON(http.StatusOK, AgentVersionResponse{Version: version})
 }
 
+// updateAgent godoc
+//
+//	@Summary		Update a server's agent
+//	@Description	Dispatches UpdateAgentCmd to the agent, telling it to download and replace itself.
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		202	{object}	UpdateAgentResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/update-agent [post]
 func updateAgent(c *gin.Context) {
 	id := c.Param("id")
 	s, err := services.GetServer(auth.InstanceID(c), id)
@@ -451,12 +676,25 @@ func updateAgent(c *gin.Context) {
 		return
 	}
 	services.LogEvent(auth.InstanceID(c), "agent.update_dispatched", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("agent update dispatched to %s (version %s)", s.Hostname, version))
-	c.JSON(http.StatusAccepted, gin.H{
-		"message": "update command sent to agent",
-		"version": version,
+	c.JSON(http.StatusAccepted, UpdateAgentResponse{
+		Message: "update command sent to agent",
+		Version: version,
 	})
 }
 
+// applyUpdates godoc
+//
+//	@Summary		Apply pending OS updates on a server
+//	@Description	Dispatches ApplyUpdatesCmd. Exempt from the licence gate: security patching is never paywalled.
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		202	{object}	MessageResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/apply-updates [post]
 func applyUpdates(c *gin.Context) {
 	id := c.Param("id")
 	s, err := services.GetServer(auth.InstanceID(c), id)
@@ -470,9 +708,16 @@ func applyUpdates(c *gin.Context) {
 		return
 	}
 	services.LogEvent(auth.InstanceID(c), "updates.applied", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("package update command dispatched to %s", s.Hostname))
-	c.JSON(http.StatusAccepted, gin.H{"message": "apply updates command sent to agent"})
+	c.JSON(http.StatusAccepted, MessageResponse{Message: "apply updates command sent to agent"})
 }
 
+// handleUpdateScript serves a dynamically generated shell script that
+// downloads and installs the latest agent. Deliberately not in the generated
+// OpenAPI document: it is registered on the bare engine, not under the /api
+// group the document's BasePath assumes, so a @Router annotation here would
+// publish /api/update — a path that 404s — rather than the real top-level
+// /update. It serves a shell script, not JSON, so there is nothing lost by
+// leaving it out of a JSON API reference.
 func handleUpdateScript(c *gin.Context) {
 	giteaHost := "gitea.hostxtra.co.uk"
 
@@ -526,21 +771,57 @@ echo "vantage-agent updated to ${VERSION} and restarted."
 	c.String(http.StatusOK, script)
 }
 
+// listAuditEvents godoc
+//
+//	@Summary		List audit events
+//	@Description	Every mutating API path writes an audit event. Paginated with a total, since a short page is not proof of the end of the log.
+//	@Tags			audit
+//	@Produce		json
+//	@Param			q			query		string	false	"Free-text search"
+//	@Param			category	query		string	false	"Filter by category"
+//	@Param			limit		query		int		false	"Max events to return"
+//	@Param			skip		query		int		false	"Events to skip"
+//	@Success		200	{object}	AuditEventsResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/audit [get]
 func listAuditEvents(c *gin.Context) {
-	limit := int64(100)
+	f := services.AuditFilter{
+		Search:   c.Query("q"),
+		Category: c.Query("category"),
+	}
 	if l := c.Query("limit"); l != "" {
 		if n, err := strconv.ParseInt(l, 10, 64); err == nil && n > 0 {
-			limit = n
+			f.Limit = n
 		}
 	}
-	events, err := services.ListAuditEvents(auth.InstanceID(c), limit)
+	if s := c.Query("skip"); s != "" {
+		if n, err := strconv.ParseInt(s, 10, 64); err == nil && n >= 0 {
+			f.Skip = n
+		}
+	}
+
+	events, total, err := services.ListAuditEvents(auth.InstanceID(c), f)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, events)
+	// An object rather than a bare array: a page is meaningless without the
+	// total it came from, and a short page is not proof of the end of the log.
+	c.JSON(http.StatusOK, AuditEventsResponse{Events: events, Total: total})
 }
 
+// getSettings godoc
+//
+//	@Summary		Get instance settings
+//	@Tags			settings
+//	@Produce		json
+//	@Success		200	{object}	models.Settings
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/settings [get]
 func getSettings(c *gin.Context) {
 	s, err := services.GetSettings(auth.InstanceID(c))
 	if err != nil {
@@ -550,17 +831,37 @@ func getSettings(c *gin.Context) {
 	c.JSON(http.StatusOK, s)
 }
 
+// saveSettings godoc
+//
+//	@Summary		Save instance settings
+//	@Description	Owner and admin only. Refuses a change that would leave neither local login nor an enabled auth provider.
+//	@Tags			settings
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{alerts=models.AlertSettings,workflow_log_retention_days=int,local_login_enabled=bool,api_token_max_days=int}	true	"Settings to save"
+//	@Success		200	{object}	SavedResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/settings [put]
 func saveSettings(c *gin.Context) {
 	var body struct {
 		Alerts                   models.AlertSettings `json:"alerts"`
 		WorkflowLogRetentionDays *int                 `json:"workflow_log_retention_days"`
 		LocalLoginEnabled        *bool                `json:"local_login_enabled"`
+		APITokenMaxDays          *int                 `json:"api_token_max_days"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	if err := services.SaveSettings(auth.InstanceID(c), body.Alerts, body.WorkflowLogRetentionDays, body.LocalLoginEnabled); err != nil {
+	if body.APITokenMaxDays != nil && *body.APITokenMaxDays < 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "api_token_max_days cannot be negative"})
+		return
+	}
+	if err := services.SaveSettings(auth.InstanceID(c), body.Alerts, body.WorkflowLogRetentionDays, body.LocalLoginEnabled, body.APITokenMaxDays); err != nil {
 		if errors.Is(err, services.ErrLockout) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error(), "code": "local_login_required"})
 			return
@@ -569,9 +870,19 @@ func saveSettings(c *gin.Context) {
 		return
 	}
 	services.LogEvent(auth.InstanceID(c), "settings.updated", actorFromCtx(c), "", "", "alert settings updated")
-	c.JSON(http.StatusOK, gin.H{"saved": true})
+	if body.APITokenMaxDays != nil {
+		services.LogEvent(auth.InstanceID(c), "settings.token_policy_updated", actorFromCtx(c), "", "",
+			fmt.Sprintf("API token maximum lifetime set to %d day(s); 0 means no cap", *body.APITokenMaxDays))
+	}
+	c.JSON(http.StatusOK, SavedResponse{Saved: true})
 }
 
+// handleInstallScript serves a dynamically generated shell script that
+// downloads, verifies and installs the agent, seeded with a pre-registration
+// token. Deliberately not in the generated OpenAPI document, for the same
+// reason as handleUpdateScript: it is registered on the bare engine, outside
+// the /api group the document's BasePath assumes, so a @Router annotation
+// would publish a /api/install path that 404s.
 func handleInstallScript(c *gin.Context) {
 	serverID := c.Query("server_id")
 	token := c.Query("token")

server/internal/api/instance.go

@@ -10,6 +10,16 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// listInstanceUsers godoc
+//
+//	@Summary		List instance members
+//	@Tags			instance-users
+//	@Produce		json
+//	@Success		200	{array}		models.User
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users [get]
 func listInstanceUsers(c *gin.Context) {
 	users, err := services.ListUsers(auth.InstanceID(c))
 	if err != nil {
@@ -23,6 +33,20 @@ func actorMayGrantOwner(c *gin.Context) bool {
 	return auth.Role(c) == models.RoleOwner
 }
 
+// createInstanceUser godoc
+//
+//	@Summary		Create an instance member
+//	@Description	Only an owner can create another owner.
+//	@Tags			instance-users
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{email=string,password=string,role=string}	true	"New member"
+//	@Success		201	{object}	models.User
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users [post]
 func createInstanceUser(c *gin.Context) {
 	var body struct {
 		Email    string `json:"email"`
@@ -52,6 +76,24 @@ func createInstanceUser(c *gin.Context) {
 	c.JSON(http.StatusCreated, u)
 }
 
+// updateInstanceUserRole godoc
+//
+//	@Summary		Change an instance member's role
+//	@Description	A caller cannot change their own role. Only an owner can change owner roles.
+//	@Tags			instance-users
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string					true	"User ID"
+//	@Param			body	body		object{role=string}	true	"New role"
+//	@Success		200	{object}	OKResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users/{id}/role [put]
 func updateInstanceUserRole(c *gin.Context) {
 	var body struct {
 		Role string `json:"role"`
@@ -84,9 +126,24 @@ func updateInstanceUserRole(c *gin.Context) {
 		c.JSON(orgUserErrStatus(err), gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"ok": true})
+	c.JSON(http.StatusOK, OKResponse{OK: true})
 }
 
+// deleteInstanceUser godoc
+//
+//	@Summary		Remove an instance member
+//	@Description	A caller cannot remove their own account. Only an owner can remove another owner.
+//	@Tags			instance-users
+//	@Produce		json
+//	@Param			id	path		string	true	"User ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users/{id} [delete]
 func deleteInstanceUser(c *gin.Context) {
 	instanceID, targetID := auth.InstanceID(c), c.Param("id")
 	if targetID == auth.UserID(c) {
@@ -107,7 +164,7 @@ func deleteInstanceUser(c *gin.Context) {
 		c.JSON(orgUserErrStatus(err), gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"deleted": true})
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
 }
 
 func orgUserErrStatus(err error) int {

server/internal/api/licence.go

@@ -116,6 +116,15 @@ type licenceUsageResponse struct {
 	Channels     int `json:"channels"`
 }
 
+// getLicence godoc
+//
+//	@Summary		Get this instance's licence state
+//	@Tags			licence
+//	@Produce		json
+//	@Success		200	{object}	licenceResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/license [get]
 func getLicence(c *gin.Context) {
 	instanceID := auth.InstanceID(c)
 	st := services.GetLicenseState(instanceID)
@@ -169,6 +178,21 @@ func licencePostAllowed(instanceID string) bool {
 	return true
 }
 
+// postLicence godoc
+//
+//	@Summary		Set this instance's licence
+//	@Description	Self-hosted only; a cloud instance's licence is injected by admin and this endpoint answers 409 cloud_managed. Exempt from the licence gate, since pasting a valid licence is the way out of degraded mode. Rate limited to 10 attempts per instance per hour.
+//	@Tags			licence
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{blob=string}	true	"Licence key blob"
+//	@Success		200	{object}	LicencePostResponse
+//	@Failure		400	{object}	LicenceErrorResponse
+//	@Failure		409	{object}	LicenceErrorResponse
+//	@Failure		429	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/license [post]
 func postLicence(c *gin.Context) {
 	instanceID := auth.InstanceID(c)
 
@@ -210,7 +234,7 @@ func postLicence(c *gin.Context) {
 
 	services.LogEvent(instanceID, "license.updated", actorFromCtx(c), "", "",
 		"licence accepted (tier "+st.Tier+")")
-	c.JSON(http.StatusOK, gin.H{"state": st.Status, "tier": st.Tier, "expires_at": st.ExpiresAt})
+	c.JSON(http.StatusOK, LicencePostResponse{State: st.Status, Tier: st.Tier, ExpiresAt: st.ExpiresAt})
 }
 
 // licenceRejectionMessage turns a machine reason into something a person can act
@@ -238,11 +262,11 @@ func limitStatus(c *gin.Context, err error) bool {
 	if !errors.As(err, &le) {
 		return false
 	}
-	c.JSON(http.StatusForbidden, gin.H{
-		"error":   "limit_exceeded",
-		"limit":   le.Limit,
-		"current": le.Current,
-		"max":     le.Max,
+	c.JSON(http.StatusForbidden, LimitExceededResponse{
+		Error:   "limit_exceeded",
+		Limit:   le.Limit,
+		Current: le.Current,
+		Max:     le.Max,
 	})
 	return true
 }