feat(adminsite): one masthead, a shared page frame, collapsible instance records

The console had components but no shell: a brand bar and a nav strip stacked
into 100px carrying eight words, no sign-out, no account identity, and an
Overview link hardcoded to text-accent so it read as the current page on
every screen. Nine pages each hand-rolled their own header.

AppBar replaces both bars and derives its active state from usePathname.
Settings moves into AccountMenu — it is your password, not a destination —
taking appearance with it, which finally sets the data-theme attribute the
token blocks have supported in both directions since they were written.
That leaves three customer destinations: Overview, People, Billing.

PageFrame adds a support rail so a page has a floor, and InstanceRecord
replaces InstanceCard with one component that opens and closes: an account
with a single instance used to render a third of a row of summary with its
substance a click away. It defaults open when the instance is the only one
or needs attention.

No plan card in the rail: tier, limits and expiry belong to a licence and a
licence belongs to one instance, so an account holding a Free cloud instance
and a Professional self-hosted one has no single plan. The rail carries only
what is account-wide.

Tokens and globals.css are untouched — they stay verbatim shared with site/.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitea/workflows/agent-release.yml

@@ -86,22 +86,6 @@ jobs:
                   $env:GOOS = "windows"; $env:GOARCH = "amd64"
                   go build -ldflags="-s -w -X main.Version=$env:VERSION" -o ../installer/vantage-agent-windows-amd64.exe ./cmd
 
-            - name: Cache nssm
-              id: cache-nssm
-              uses: actions/cache@v4
-              with:
-                  path: installer/nssm.exe
-                  key: nssm-2.24-win64
-
-            - name: Fetch nssm
-              if: steps.cache-nssm.outputs.cache-hit != 'true'
-              working-directory: installer
-              shell: pwsh
-              run: |
-                  Invoke-WebRequest -Uri https://nssm.cc/release/nssm-2.24.zip -OutFile nssm.zip
-                  Expand-Archive -Path nssm.zip -DestinationPath nssm-extract -Force
-                  Copy-Item nssm-extract/nssm-2.24/win64/nssm.exe -Destination nssm.exe
-
             - name: Install WiX
               shell: pwsh
               run: dotnet tool install --global wix --version 5.*

.gitea/workflows/server-deploy.yml

@@ -24,7 +24,8 @@ jobs:
             - name: Build and push server image
               run: |
                   IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/server:latest"
-                  docker build -t "$IMAGE" -f server/Dockerfile server/
+                  # Root context: server depends on the shared module.
+                  docker build -t "$IMAGE" -f server/Dockerfile .
                   docker push "$IMAGE"
 
             - name: Build and push web image
@@ -32,6 +33,42 @@ jobs:
                   IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/web:latest"
                   docker build \
                     --build-arg NEXT_PUBLIC_API_URL="${{ vars.API_URL }}" \
+                    --build-arg NEXT_PUBLIC_HQ_URL="${{ vars.HQ_URL }}" \
                     -t "$IMAGE" \
                     -f web/Dockerfile web/
                   docker push "$IMAGE"
+
+            - name: Build and push site image
+              run: |
+                  IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/site:latest"
+                  docker build \
+                    --build-arg NEXT_PUBLIC_SITE_API="${{ vars.SITE_API_URL }}" \
+                    --build-arg NEXT_PUBLIC_CONTACT_EMAIL="support@hostxtra.co.uk" \
+                    --build-arg NEXT_PUBLIC_ADMIN_API_URL="${{ vars.ADMIN_API_URL }}" \
+                    -t "$IMAGE" \
+                    -f site/Dockerfile site/
+                  docker push "$IMAGE"
+
+            - name: Build and push sitesvc image
+              run: |
+                  IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/sitesvc:latest"
+                  # Root context: sitesvc depends on the shared module.
+                  docker build -t "$IMAGE" -f sitesvc/Dockerfile .
+                  docker push "$IMAGE"
+
+            - name: Build and push admin image
+              run: |
+                  IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/admin:latest"
+                  # Root context: admin depends on the shared module.
+                  docker build -t "$IMAGE" -f admin/Dockerfile .
+                  docker push "$IMAGE"
+
+            - name: Build and push adminsite image
+              run: |
+                  IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/adminsite:latest"
+                  docker build \
+                    --build-arg NEXT_PUBLIC_ADMIN_API_URL="${{ vars.ADMIN_API_URL }}" \
+                    --build-arg NEXT_PUBLIC_ADMIN_ENV="${{ vars.ADMIN_ENV }}" \
+                    -t "$IMAGE" \
+                    -f adminsite/Dockerfile adminsite/
+                  docker push "$IMAGE"

.gitignore

@@ -2,10 +2,12 @@ node_modules
 dist
 build
 .env
-docs
+docs/*
+!docs/superpowers/
 .superpowers
-installer/*.exe
+installer/vantage-agent-windows-amd64.exe
 installer/*.msi
 installer/nssm.zip
 installer/checksums-msi.txt
-.next
+.next
+*.tsbuildinfo

admin/.dockerignore

@@ -0,0 +1,2 @@
+.env
+*.lic

admin/Dockerfile

@@ -0,0 +1,30 @@
+# Context is the repository root; admin depends on the shared module.
+FROM golang:1.26-alpine AS builder
+
+WORKDIR /src
+
+COPY shared/go.mod shared/go.sum ./shared/
+COPY admin/go.mod admin/go.sum ./admin/
+RUN cd admin && go mod download
+
+COPY shared/ ./shared/
+COPY admin/ ./admin/
+
+RUN cd admin && CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /out/admin ./cmd
+RUN cd admin && CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /out/adminctl ./cmd/adminctl
+
+FROM alpine:3.20 AS runner
+
+RUN apk add --no-cache ca-certificates && \
+    addgroup --system --gid 1001 admin && \
+    adduser --system --uid 1001 --ingroup admin admin
+
+COPY --from=builder /out/admin /usr/local/bin/admin
+COPY --from=builder /out/adminctl /usr/local/bin/adminctl
+
+USER admin
+
+EXPOSE 8083
+ENV PORT=8083
+
+CMD ["/usr/local/bin/admin"]

admin/cmd/adminctl/main.go

@@ -0,0 +1,84 @@
+// Command adminctl performs the operations that deliberately have no HTTP
+// surface.
+//
+//	adminctl staff-add --email=you@example.com --name="You" --password=...
+//
+// There is no staff signup endpoint. A licensing authority that can be joined
+// over the internet is not one.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/joho/godotenv"
+	"github.com/mrhid6/vantage/admin/internal/config"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"golang.org/x/crypto/bcrypt"
+)
+
+func main() {
+	godotenv.Load()
+	if len(os.Args) < 2 {
+		fmt.Fprintln(os.Stderr, "usage: adminctl staff-add")
+		os.Exit(2)
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		fatal("configuration: %v", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	if err := db.Connect(ctx, cfg); err != nil {
+		fatal("database: %v", err)
+	}
+
+	switch os.Args[1] {
+	case "staff-add":
+		staffAdd(ctx, os.Args[2:])
+	default:
+		fmt.Fprintln(os.Stderr, "usage: adminctl staff-add")
+		os.Exit(2)
+	}
+}
+
+func staffAdd(ctx context.Context, args []string) {
+	fs := flag.NewFlagSet("staff-add", flag.ExitOnError)
+	email := fs.String("email", "", "staff email (required)")
+	name := fs.String("name", "", "display name")
+	password := fs.String("password", "", "password, at least 12 characters (required)")
+	fs.Parse(args)
+
+	if *email == "" || len(*password) < 12 {
+		fatal("--email and a --password of at least 12 characters are required")
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte(*password), 12)
+	if err != nil {
+		fatal("hash: %v", err)
+	}
+
+	u := models.StaffUser{
+		UserID:       uuid.NewString(),
+		Email:        strings.ToLower(strings.TrimSpace(*email)),
+		PasswordHash: string(hash),
+		Name:         *name,
+		CreatedAt:    time.Now().UTC(),
+	}
+	if _, err := db.Admin("staff_users").InsertOne(ctx, u); err != nil {
+		fatal("create staff user: %v", err)
+	}
+	fmt.Printf("created staff user %s\n", u.Email)
+}
+
+func fatal(format string, a ...any) {
+	fmt.Fprintf(os.Stderr, format+"\n", a...)
+	os.Exit(1)
+}

admin/cmd/main.go

@@ -0,0 +1,110 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/joho/godotenv"
+	"github.com/mrhid6/vantage/admin/internal/api"
+	"github.com/mrhid6/vantage/admin/internal/auth"
+	"github.com/mrhid6/vantage/admin/internal/config"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/hqsync"
+	"github.com/mrhid6/vantage/admin/internal/inject"
+	"github.com/mrhid6/vantage/admin/internal/licensing"
+	"github.com/mrhid6/vantage/admin/internal/lifecycle"
+	"github.com/mrhid6/vantage/admin/internal/mail"
+	"github.com/mrhid6/vantage/admin/internal/models"
+)
+
+func main() {
+	godotenv.Load()
+
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("configuration error: %v", err)
+	}
+
+	licensing.SetSigningKey(cfg.SigningKey)
+	api.SetAppLoginURL(cfg.AppLoginURL)
+
+	mail.Init(mail.Config{
+		Host: cfg.SMTPHost, Port: cfg.SMTPPort, From: cfg.SMTPFrom,
+		Username: cfg.SMTPUsername, Password: cfg.SMTPPassword,
+		PublicURL: cfg.PublicURL,
+	})
+	if !mail.Enabled() {
+		log.Println("warning: SMTP not configured; verification and licence emails will fail")
+	}
+
+	auth.InitRedis(cfg.RedisAddr, cfg.RedisUsername, cfg.RedisPassword)
+	pingCtx, pingCancel := context.WithTimeout(context.Background(), 10*time.Second)
+	if err := auth.Ping(pingCtx); err != nil {
+		pingCancel()
+		log.Fatalf("redis: %v", err)
+	}
+	pingCancel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	if err := db.Connect(ctx, cfg); err != nil {
+		cancel()
+		log.Fatalf("database: %v", err)
+	}
+	cancel()
+	log.Printf("connected: admin=%s control=%s", cfg.AdminDBName, cfg.ControlDBName)
+
+	idxCtx, idxCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	if err := db.EnsureIndexes(idxCtx); err != nil {
+		idxCancel()
+		log.Fatalf("indexes: %v", err)
+	}
+	if err := models.SeedPlans(idxCtx); err != nil {
+		idxCancel()
+		log.Fatalf("plan seed: %v", err)
+	}
+	if err := models.Backfill(idxCtx); err != nil {
+		idxCancel()
+		log.Fatalf("backfill: %v", err)
+	}
+	idxCancel()
+
+	reconcileCtx, stopReconcile := context.WithCancel(context.Background())
+	defer stopReconcile()
+	inject.StartReconciler(reconcileCtx)
+	hqsync.Start(reconcileCtx)
+
+	lifecycle.SetPortalURL(cfg.PublicURL)
+	lifecycle.Start(reconcileCtx, cfg.ReapAfter)
+
+	srv := &http.Server{
+		Addr:              cfg.Addr,
+		Handler:           api.Routes(cfg),
+		ReadHeaderTimeout: 10 * time.Second,
+		ReadTimeout:       20 * time.Second,
+		WriteTimeout:      30 * time.Second,
+		IdleTimeout:       60 * time.Second,
+	}
+
+	go func() {
+		log.Printf("admin listening on %s", cfg.Addr)
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.Fatalf("server error: %v", err)
+		}
+	}()
+
+	stopCtx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+	<-stopCtx.Done()
+
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer shutdownCancel()
+	_ = srv.Shutdown(shutdownCtx)
+	log.Println("admin stopped")
+	os.Exit(0)
+}

admin/go.mod

@@ -0,0 +1,55 @@
+module github.com/mrhid6/vantage/admin
+
+go 1.26
+
+require (
+	github.com/gin-gonic/gin v1.10.0
+	github.com/google/uuid v1.6.0
+	github.com/joho/godotenv v1.5.1
+	github.com/mrhid6/vantage/shared v0.0.0-00010101000000-000000000000
+	github.com/redis/go-redis/v9 v9.20.1
+	go.mongodb.org/mongo-driver/v2 v2.8.0
+	golang.org/x/crypto v0.54.0
+)
+
+require (
+	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.15.0 // indirect
+	github.com/bytedance/sonic/loader v0.5.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
+	github.com/gin-contrib/sse v1.1.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.30.1 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/hyperboloide/lk v0.0.0-20251220053519-b291812e3216 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/compress v1.17.6 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/rogpeppe/go-internal v1.10.0 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.3.1 // indirect
+	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
+	github.com/xdg-go/scram v1.2.0 // indirect
+	github.com/xdg-go/stringprep v1.0.4 // indirect
+	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	golang.org/x/arch v0.22.0 // indirect
+	golang.org/x/net v0.56.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/mrhid6/vantage/shared => ../shared

admin/go.sum

@@ -0,0 +1,149 @@
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
+github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
+github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
+github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
+github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
+github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
+github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
+github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
+github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
+github.com/gin-gonic/gin v1.10.0 h1:nTuyha1TYqgedzytsKYqna+DfLos46nTv2ygFy86HFU=
+github.com/gin-gonic/gin v1.10.0/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
+github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hyperboloide/lk v0.0.0-20251220053519-b291812e3216 h1:Luh+sE/W2M+V0Y+jlZN7nJefLNHc4/y93xxl+rFD7k0=
+github.com/hyperboloide/lk v0.0.0-20251220053519-b291812e3216/go.mod h1:/OLW9HZj6qtQ7gWTGwuO3JrUZ+MC7I7TLRuNl14TYuo=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/compress v1.17.6 h1:60eq2E/jlfwQXtvZEeBUYADs+BwKBWURIY+Gj2eRGjI=
+github.com/klauspost/compress v1.17.6/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/redis/go-redis/v9 v9.20.1 h1:sfCU6A8P3dXbKyWes02uxA2baehGux9dZHfEKtsTB1w=
+github.com/redis/go-redis/v9 v9.20.1/go.mod h1:v/M13XI1PVCDcm01VtPFOADfZtHf8YW3baQf57KlIkA=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
+github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
+github.com/xdg-go/pbkdf2 v1.0.0 h1:Su7DPu48wXMwC3bs7MCNG+z4FhcyEuz5dlvchbq0B0c=
+github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
+github.com/xdg-go/scram v1.2.0 h1:bYKF2AEwG5rqd1BumT4gAnvwU/M9nBp2pTSxeZw7Wvs=
+github.com/xdg-go/scram v1.2.0/go.mod h1:3dlrS0iBaWKYVt2ZfA4cj48umJZ+cAEbR6/SjLA88I8=
+github.com/xdg-go/stringprep v1.0.4 h1:XLI/Ng3O1Atzq0oBs3TWm+5ZVgkq2aqdlvP9JtoZ6c8=
+github.com/xdg-go/stringprep v1.0.4/go.mod h1:mPGuuIYwz7CmR2bT9j4GbQqutWS1zV24gijq1dTyGkM=
+github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
+github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
+go.mongodb.org/mongo-driver/v2 v2.8.0 h1:CxWDGQYY8QQwNjAl/aq2sfWakdnWZynnqJ9F4DhHbP8=
+go.mongodb.org/mongo-driver/v2 v2.8.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
+golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
+google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

admin/internal/api/customer.go

@@ -0,0 +1,431 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/auth"
+	"github.com/mrhid6/vantage/admin/internal/cloudprov"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/inject"
+	"github.com/mrhid6/vantage/admin/internal/licensing"
+	"github.com/mrhid6/vantage/admin/internal/mail"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+	sharedmodels "github.com/mrhid6/vantage/shared/models"
+	"github.com/mrhid6/vantage/shared/provision"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// ownedInstance resolves an instance and confirms the session's account owns it.
+//
+// EVERY customer handler that names an instance must go through this. It returns
+// 404 for another account's instance rather than 403: a 403 confirms the
+// instance exists, which is an existence oracle over customer data.
+func ownedInstance(c *gin.Context, instanceID string) (*models.Instance, bool) {
+	s := auth.Current(c)
+	if s == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "sign in required"})
+		return nil, false
+	}
+	var inst models.Instance
+	err := db.Admin("admin_instances").FindOne(c.Request.Context(),
+		bson.M{"instance_id": instanceID, "account_id": s.AccountID}).Decode(&inst)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return nil, false
+	}
+	return &inst, true
+}
+
+// getMe reports who the caller is, for route guards in the UI.
+//
+// It is deliberately outside RequireCustomer/RequireStaff: the UI needs a
+// truthful 401 to redirect on, not an error page. It reveals nothing a caller
+// does not already possess, because it only ever describes their own cookie.
+func getMe(c *gin.Context) {
+	s := auth.Load(c)
+	if s == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "not signed in"})
+		return
+	}
+	out := gin.H{"kind": s.Kind, "email": s.Email, "account_id": s.AccountID}
+	if s.Kind == auth.KindCustomer {
+		var u models.CustomerUser
+		if err := db.Admin("customer_users").FindOne(c.Request.Context(),
+			bson.M{"user_id": s.UserID}).Decode(&u); err == nil {
+			out["account_role"] = u.AccountRole
+		}
+	}
+	c.JSON(http.StatusOK, out)
+}
+
+func getAccount(c *gin.Context) {
+	s := auth.Current(c)
+	ctx := c.Request.Context()
+
+	var acct models.Account
+	if err := db.Admin("accounts").FindOne(ctx, bson.M{"account_id": s.AccountID}).Decode(&acct); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return
+	}
+
+	cur, err := db.Admin("admin_instances").Find(ctx, bson.M{"account_id": s.AccountID})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	instances := []models.Instance{}
+	if err := cur.All(ctx, &instances); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"account":   acct,
+		"instances": instances,
+		// Sent rather than mirrored in the UI: a hardcoded 3 in TypeScript is a
+		// second source of truth for a rule the backend enforces.
+		"max_relinks": models.MaxRelinksPerTerm,
+	})
+}
+
+func linkInstance(c *gin.Context) {
+	var body struct {
+		InstanceID string `json:"instance_id"`
+		Name       string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "instance_id is required"})
+		return
+	}
+
+	s := auth.Current(c)
+	inst, err := licensing.LinkInstance(c.Request.Context(), s.AccountID, body.InstanceID, body.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
+	}
+	c.JSON(http.StatusCreated, inst)
+}
+
+func relinkInstance(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	var body struct {
+		InstanceID string `json:"instance_id"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "instance_id is required"})
+		return
+	}
+
+	s := auth.Current(c)
+	lic, err := licensing.Relink(c.Request.Context(), s.AccountID, inst.InstanceID, body.InstanceID, false)
+	if err != nil {
+		status := http.StatusBadRequest
+		if errors.Is(err, licensing.ErrRelinkLimit) {
+			status = http.StatusForbidden
+		}
+		c.JSON(status, gin.H{"error": err.Error()})
+		return
+	}
+	deliver(c, inst, lic)
+	c.JSON(http.StatusOK, lic)
+}
+
+func getInstanceLicense(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	var lic models.License
+	if err := db.Admin("licenses").FindOne(c.Request.Context(),
+		bson.M{"license_id": inst.CurrentLicense}).Decode(&lic); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no licence issued yet"})
+		return
+	}
+	// The owner gets the blob itself: it is signed public data bound to their
+	// own instance, and the download endpoint hands over the same bytes. The
+	// struct tag hides it, so the fields are listed explicitly.
+	c.JSON(http.StatusOK, gin.H{
+		"license_id": lic.LicenseID, "instance_id": lic.InstanceID, "tier": lic.Tier,
+		"deployment": lic.Deployment, "limits": lic.Limits, "features": lic.Features,
+		"issued_at": lic.IssuedAt, "expires_at": lic.ExpiresAt, "reason": lic.Reason,
+		"issued_by": lic.IssuedBy, "blob": lic.Blob,
+	})
+}
+
+func downloadInstanceLicense(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	var lic models.License
+	if err := db.Admin("licenses").FindOne(c.Request.Context(),
+		bson.M{"license_id": inst.CurrentLicense}).Decode(&lic); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no licence issued yet"})
+		return
+	}
+	c.Header("Content-Disposition", fmt.Sprintf(`attachment; filename="vantage-%s.lic"`, inst.InstanceID))
+	c.Data(http.StatusOK, "application/octet-stream", []byte(lic.Blob+"\n"))
+}
+
+func listSubscriptions(c *gin.Context) {
+	s := auth.Current(c)
+	cur, err := db.Admin("subscriptions").Find(c.Request.Context(), bson.M{"account_id": s.AccountID})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	subs := []models.Subscription{}
+	if err := cur.All(c.Request.Context(), &subs); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, subs)
+}
+
+// createInstance provisions a Free cloud instance for the calling account.
+//
+// The ordering matters and each step unwinds the previous one. Licence issuance
+// and email are deliberately NOT allowed to fail the request: the instance
+// exists and the customer can sign in, they see the licence banner, and staff
+// can issue by hand. Rolling back an instance the customer can already see would
+// be worse than shipping it unlicensed.
+func createInstance(c *gin.Context) {
+	var body struct {
+		Name string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || strings.TrimSpace(body.Name) == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+	name := strings.TrimSpace(body.Name)
+	ctx := c.Request.Context()
+	s := auth.Current(c)
+
+	// Pre-check the Free rule so we never create an instance we then cannot
+	// licence. licensing.Issue enforces it too; this is the friendly refusal.
+	n, err := db.Admin("admin_instances").CountDocuments(ctx, bson.M{
+		"account_id": s.AccountID,
+		"tier":       license.TierFree,
+		"status":     bson.M{"$ne": models.StatusCancelled},
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not check your account"})
+		return
+	}
+	if n > 0 {
+		c.JSON(http.StatusConflict, gin.H{
+			"error": "this account already has a Free instance"})
+		return
+	}
+
+	var cu models.CustomerUser
+	if err := db.Admin("customer_users").FindOne(ctx,
+		bson.M{"user_id": s.UserID}).Decode(&cu); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not read your account"})
+		return
+	}
+
+	inst, err := cloudprov.CreateInstance(ctx, name, cu.Email, cu.PasswordHash, cu.UserID)
+	if err != nil {
+		if errors.Is(err, provision.ErrEmailTaken) {
+			// users.email is unique per instance, so this means the address
+			// already owns a user in an instance we are not creating — a legacy
+			// cloud tenant. Staff have to attach that one by hand.
+			c.JSON(http.StatusConflict, gin.H{
+				"error": "that email address already belongs to an existing Vantage instance; contact support@hostxtra.co.uk and we will link it to your account"})
+			return
+		}
+		if errors.Is(err, provision.ErrNameRejected) {
+			c.JSON(http.StatusUnprocessableEntity, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not create the instance"})
+		return
+	}
+
+	rec := models.Instance{
+		InstanceID: inst.InstanceID,
+		AccountID:  s.AccountID,
+		Name:       inst.Name,
+		Slug:       inst.Slug,
+		Deployment: license.DeploymentCloud,
+		Status:     models.StatusActive,
+		CreatedAt:  time.Now().UTC(),
+	}
+	if _, err := db.Admin("admin_instances").InsertOne(ctx, rec); err != nil {
+		// Unwind in reverse: the owner first, because RollbackInstance refuses
+		// an instance that still has users.
+		if uid, e := cloudprov.OwnerUserID(ctx, inst.InstanceID); e == nil {
+			_ = cloudprov.DeleteUser(ctx, inst.InstanceID, uid)
+		}
+		if e := cloudprov.RollbackInstance(ctx, inst.InstanceID); e != nil {
+			log.Printf("createInstance: rollback of %s failed: %v", inst.InstanceID, e)
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not create the instance"})
+		return
+	}
+
+	// Record the owner's membership. Best-effort: the projected user already
+	// exists and is what actually grants access, so a missing row here costs a
+	// line in the members panel, not access — and the boot backfill rebuilds it.
+	ownerID, err := cloudprov.OwnerUserID(ctx, inst.InstanceID)
+	if err != nil {
+		log.Printf("createInstance: owner lookup for %s: %v", inst.InstanceID, err)
+	} else if _, err := db.Admin("instance_members").InsertOne(ctx, models.InstanceMember{
+		MemberID:       uuid.NewString(),
+		AccountID:      s.AccountID,
+		InstanceID:     inst.InstanceID,
+		CustomerUserID: cu.UserID,
+		ControlUserID:  ownerID,
+		Role:           sharedmodels.RoleOwner,
+		Email:          cu.Email,
+		CreatedAt:      time.Now().UTC(),
+	}); err != nil {
+		log.Printf("createInstance: record owner membership for %s: %v", inst.InstanceID, err)
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance.created", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: "slug=" + inst.Slug, IP: c.ClientIP()})
+
+	// Past this point nothing fails the request.
+	lic, err := licensing.Issue(ctx, licensing.IssueInput{
+		InstanceID: inst.InstanceID,
+		Tier:       license.TierFree,
+		Term:       "monthly",
+		Reason:     models.ReasonNew,
+		IssuedBy:   "self-serve",
+	})
+	if err != nil {
+		log.Printf("ISSUE FAILED for new instance %s: %v", inst.InstanceID, err)
+		c.JSON(http.StatusCreated, rec)
+		return
+	}
+	inject.Deliver(ctx, lic)
+
+	if mail.Enabled() {
+		if err := mail.SendInstanceReady(s.Email, inst.Name,
+			loginURLFor(inst.Slug), lic.ExpiresAt); err != nil {
+			log.Printf("createInstance: instance-ready email to %s: %v", s.Email, err)
+		}
+	}
+
+	rec.Tier = lic.Tier
+	rec.CurrentLicense = lic.LicenseID
+	c.JSON(http.StatusCreated, rec)
+}
+
+// renewInstance extends a Free licence by another term.
+//
+// Renewal is manual on purpose: it is the entire reclaim signal. An instance
+// nobody renews is an instance nobody is using, and that is what makes the
+// reaper safe to run at all.
+func renewInstance(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	if inst.Tier != license.TierFree {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "only Free instances renew here; paid plans renew through billing"})
+		return
+	}
+
+	ctx := c.Request.Context()
+
+	var current models.License
+	if err := db.Admin("licenses").FindOne(ctx,
+		bson.M{"license_id": inst.CurrentLicense}).Decode(&current); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no licence issued yet"})
+		return
+	}
+	if time.Now().UTC().Before(current.ExpiresAt.Add(-models.RenewWindow)) {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": fmt.Sprintf("this licence is not due yet; you can renew from %s",
+				current.ExpiresAt.Add(-models.RenewWindow).Format("2 January 2006"))})
+		return
+	}
+
+	lic, err := licensing.Issue(ctx, licensing.IssueInput{
+		InstanceID: inst.InstanceID,
+		Tier:       license.TierFree,
+		Term:       "monthly",
+		Reason:     models.ReasonRenewal,
+		IssuedBy:   "self-serve",
+	})
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	inject.Deliver(ctx, lic)
+
+	// Clear the notice log so the next term starts the sequence again. Issue has
+	// already set status back to active.
+	if _, err := db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": inst.InstanceID},
+		bson.M{"$unset": bson.M{"notices_sent": ""}}); err != nil {
+		log.Printf("renewInstance: clear notices for %s: %v", inst.InstanceID, err)
+	}
+
+	s := auth.Current(c)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance.renewed", AccountID: s.AccountID,
+		Target: inst.InstanceID, IP: c.ClientIP()})
+
+	if mail.Enabled() {
+		if err := mail.SendRenewed(s.Email, inst.Name, lic.ExpiresAt); err != nil {
+			log.Printf("renewInstance: renewed email to %s: %v", s.Email, err)
+		}
+	}
+
+	c.JSON(http.StatusOK, lic)
+}
+
+// loginURLFor fills the {slug} template in APP_LOGIN_URL. An empty template
+// yields an empty string, and the email simply omits the link.
+func loginURLFor(slug string) string {
+	if appLoginURL == "" {
+		return ""
+	}
+	return strings.ReplaceAll(appLoginURL, "{slug}", url.PathEscape(slug))
+}
+
+// appLoginURL is set once at boot from config.
+var appLoginURL string
+
+// SetAppLoginURL is called from main.
+func SetAppLoginURL(v string) { appLoginURL = v }
+
+// deliver sends a freshly issued licence where it needs to go. Cloud instances
+// are injected; self-hosted customers are emailed and can download.
+//
+// Delivery failures are logged, never returned: the licence is already recorded,
+// which is the part that must not be lost.
+func deliver(c *gin.Context, inst *models.Instance, lic *models.License) {
+	if inst.Deployment == license.DeploymentCloud {
+		inject.Deliver(c.Request.Context(), lic)
+		return
+	}
+	s := auth.Current(c)
+	if s != nil && mail.Enabled() {
+		_ = mail.SendLicense(s.Email, inst.Name, lic.Blob)
+	}
+}

admin/internal/api/members.go

@@ -0,0 +1,237 @@
+package api
+
+import (
+	"errors"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/auth"
+	"github.com/mrhid6/vantage/admin/internal/cloudprov"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+	sharedmodels "github.com/mrhid6/vantage/shared/models"
+	"github.com/mrhid6/vantage/shared/provision"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// selfHostedRefusal is the one message every membership endpoint gives for a
+// self-hosted instance. Their users live in their own deployment, which we
+// cannot see and must not write to.
+const selfHostedRefusal = "this install manages its own users; add them in Settings → Instance inside your Vantage install"
+
+func listInstanceMembers(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	ctx := c.Request.Context()
+	cur, err := db.Admin("instance_members").Find(ctx,
+		bson.M{"instance_id": inst.InstanceID})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	members := []models.InstanceMember{}
+	if err := cur.All(ctx, &members); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, members)
+}
+
+// grantInstanceMember projects an account person into a cloud instance.
+func grantInstanceMember(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
+	}
+
+	var body struct {
+		UserID string `json:"user_id"`
+		Role   string `json:"role"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.UserID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "user_id is required"})
+		return
+	}
+	if body.Role == "" {
+		body.Role = sharedmodels.RoleMember
+	}
+	if !sharedmodels.ValidRole(body.Role) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "role must be one of owner, admin, or member"})
+		return
+	}
+
+	target, ok := accountUser(c, body.UserID)
+	if !ok {
+		return
+	}
+	if target.VerifiedAt == nil || target.PasswordHash == "" {
+		// The projection copies a hash. An unverified invitee has no hash, so
+		// the row would exist and be unusable — and an address nobody has
+		// proven they control would hold a login inside a real instance.
+		c.JSON(http.StatusConflict, gin.H{
+			"error": "they have not accepted their invitation yet"})
+		return
+	}
+
+	ctx := c.Request.Context()
+	s := auth.Current(c)
+
+	u, err := cloudprov.GrantUser(ctx, inst.InstanceID, target.Email,
+		target.PasswordHash, body.Role, target.UserID)
+	if err != nil {
+		if errors.Is(err, provision.ErrEmailTaken) {
+			c.JSON(http.StatusConflict, gin.H{
+				"error": "that address already has a user inside this instance"})
+			return
+		}
+		log.Printf("grant %s to %s: %v", target.Email, inst.InstanceID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not grant access"})
+		return
+	}
+
+	m := models.InstanceMember{
+		MemberID:       uuid.NewString(),
+		AccountID:      inst.AccountID,
+		InstanceID:     inst.InstanceID,
+		CustomerUserID: target.UserID,
+		ControlUserID:  u.UserID,
+		Role:           body.Role,
+		Email:          target.Email,
+		CreatedAt:      time.Now().UTC(),
+	}
+	if _, err := db.Admin("instance_members").InsertOne(ctx, m); err != nil {
+		// Unwind the projection: a control-plane login nobody on this side
+		// records is a login nobody can revoke through the portal.
+		if rErr := cloudprov.RevokeUser(ctx, inst.InstanceID, target.UserID); rErr != nil {
+			log.Printf("grant: FAILED to unwind projection of %s in %s: %v",
+				target.Email, inst.InstanceID, rErr)
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not grant access"})
+		return
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance_member.granted", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: target.Email + " role=" + body.Role, IP: c.ClientIP()})
+	c.JSON(http.StatusCreated, m)
+}
+
+// memberRow loads one membership on an instance the caller owns.
+func memberRow(c *gin.Context, instanceID, customerUserID string) (*models.InstanceMember, bool) {
+	var m models.InstanceMember
+	if err := db.Admin("instance_members").FindOne(c.Request.Context(), bson.M{
+		"instance_id":      instanceID,
+		"customer_user_id": customerUserID,
+	}).Decode(&m); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return nil, false
+	}
+	return &m, true
+}
+
+func updateInstanceMemberRole(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
+	}
+	var body struct {
+		Role string `json:"role"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || !sharedmodels.ValidRole(body.Role) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "role must be one of owner, admin, or member"})
+		return
+	}
+	m, ok := memberRow(c, inst.InstanceID, c.Param("uid"))
+	if !ok {
+		return
+	}
+
+	ctx := c.Request.Context()
+	if m.Role == sharedmodels.RoleOwner && body.Role != sharedmodels.RoleOwner {
+		others, err := cloudprov.CountOtherOwners(ctx, inst.InstanceID, m.CustomerUserID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if others == 0 {
+			c.JSON(http.StatusConflict, gin.H{
+				"error": "this is the instance's last owner; make someone else an owner first"})
+			return
+		}
+	}
+
+	if err := cloudprov.SetMemberRole(ctx, inst.InstanceID, m.CustomerUserID, body.Role); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not change their role"})
+		return
+	}
+	if _, err := db.Admin("instance_members").UpdateOne(ctx,
+		bson.M{"member_id": m.MemberID},
+		bson.M{"$set": bson.M{"role": body.Role}}); err != nil {
+		log.Printf("member role: control plane updated but member row %s did not: %v", m.MemberID, err)
+	}
+
+	s := auth.Current(c)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance_member.role_changed", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: m.Email + " role=" + body.Role, IP: c.ClientIP()})
+	c.JSON(http.StatusOK, gin.H{"ok": true})
+}
+
+func revokeInstanceMember(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
+	}
+	m, ok := memberRow(c, inst.InstanceID, c.Param("uid"))
+	if !ok {
+		return
+	}
+
+	ctx := c.Request.Context()
+	if m.Role == sharedmodels.RoleOwner {
+		others, err := cloudprov.CountOtherOwners(ctx, inst.InstanceID, m.CustomerUserID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if others == 0 {
+			c.JSON(http.StatusConflict, gin.H{
+				"error": "this is the instance's last owner; make someone else an owner first"})
+			return
+		}
+	}
+
+	if err := cloudprov.RevokeUser(ctx, inst.InstanceID, m.CustomerUserID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not revoke access"})
+		return
+	}
+	if _, err := db.Admin("instance_members").DeleteOne(ctx,
+		bson.M{"member_id": m.MemberID}); err != nil {
+		log.Printf("revoke: control-plane user deleted but member row %s remains: %v", m.MemberID, err)
+	}
+
+	s := auth.Current(c)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance_member.revoked", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: m.Email, IP: c.ClientIP()})
+	c.JSON(http.StatusOK, gin.H{"revoked": true})
+}

admin/internal/api/people.go

@@ -0,0 +1,338 @@
+package api
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/auth"
+	"github.com/mrhid6/vantage/admin/internal/cloudprov"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	sharedmodels "github.com/mrhid6/vantage/shared/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"golang.org/x/crypto/bcrypt"
+)
+
+// listAccountUsers returns the account's people, newest last.
+//
+// Any signed-in member may read this. Knowing who your colleagues are is not
+// privileged, and hiding it would make the members panel unusable for the
+// people it is meant to inform.
+func listAccountUsers(c *gin.Context) {
+	s := auth.Current(c)
+	ctx := c.Request.Context()
+	cur, err := db.Admin("customer_users").Find(ctx, bson.M{"account_id": s.AccountID})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	users := []models.CustomerUser{}
+	if err := cur.All(ctx, &users); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, users)
+}
+
+// inviteAccountUser adds a person to the account.
+//
+// It never sets a password: see CreateInvitedUser. Only an owner may invite
+// another owner, mirroring the control plane's own rule that an admin cannot
+// mint someone with more power than themselves.
+func inviteAccountUser(c *gin.Context) {
+	var body struct {
+		Email string `json:"email"`
+		Role  string `json:"role"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "email is required"})
+		return
+	}
+	email := strings.ToLower(strings.TrimSpace(body.Email))
+	if email == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "email is required"})
+		return
+	}
+	if body.Role == "" {
+		body.Role = models.AccountRoleMember
+	}
+	if !models.ValidAccountRole(body.Role) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "role must be one of owner, admin, or member"})
+		return
+	}
+	me := auth.CurrentUser(c)
+	if body.Role == models.AccountRoleOwner && me.AccountRole != models.AccountRoleOwner {
+		c.JSON(http.StatusForbidden, gin.H{"error": "only an owner can invite another owner"})
+		return
+	}
+
+	ctx := c.Request.Context()
+	s := auth.Current(c)
+
+	// customer_users.email is globally unique, so an address already in use
+	// anywhere cannot be invited here. Say so plainly: unlike signup there is
+	// nothing to conceal, because the inviter already knows this address.
+	if n, _ := db.Admin("customer_users").CountDocuments(ctx, bson.M{"email": email}); n > 0 {
+		c.JSON(http.StatusConflict, gin.H{
+			"error": "that address already has a Vantage HQ account"})
+		return
+	}
+
+	var acct models.Account
+	if err := db.Admin("accounts").FindOne(ctx,
+		bson.M{"account_id": s.AccountID}).Decode(&acct); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not read your account"})
+		return
+	}
+
+	if err := auth.CreateInvitedUser(ctx, s.AccountID, acct.Name, email, body.Role); err != nil {
+		log.Printf("invite %s to %s: %v", email, s.AccountID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not send the invitation"})
+		return
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "account_user.invited", AccountID: s.AccountID,
+		Target: email, Detail: "role=" + body.Role, IP: c.ClientIP()})
+	c.JSON(http.StatusCreated, gin.H{"invited": true})
+}
+
+// accountUser loads one person and confirms they are on the caller's account.
+func accountUser(c *gin.Context, userID string) (*models.CustomerUser, bool) {
+	s := auth.Current(c)
+	var u models.CustomerUser
+	if err := db.Admin("customer_users").FindOne(c.Request.Context(),
+		bson.M{"user_id": userID, "account_id": s.AccountID}).Decode(&u); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return nil, false
+	}
+	return &u, true
+}
+
+// countOtherAccountOwners counts owners of an account other than one person.
+func countOtherAccountOwners(c *gin.Context, exceptUserID string) (int64, error) {
+	s := auth.Current(c)
+	return db.Admin("customer_users").CountDocuments(c.Request.Context(), bson.M{
+		"account_id":   s.AccountID,
+		"account_role": models.AccountRoleOwner,
+		"user_id":      bson.M{"$ne": exceptUserID},
+	})
+}
+
+func updateAccountUserRole(c *gin.Context) {
+	var body struct {
+		Role string `json:"role"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || !models.ValidAccountRole(body.Role) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "role must be one of owner, admin, or member"})
+		return
+	}
+	target, ok := accountUser(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	me := auth.CurrentUser(c)
+	if target.UserID == me.UserID {
+		c.JSON(http.StatusForbidden, gin.H{"error": "you cannot change your own role"})
+		return
+	}
+	if (body.Role == models.AccountRoleOwner || target.AccountRole == models.AccountRoleOwner) &&
+		me.AccountRole != models.AccountRoleOwner {
+		c.JSON(http.StatusForbidden, gin.H{"error": "only an owner can change owner roles"})
+		return
+	}
+	if target.AccountRole == models.AccountRoleOwner && body.Role != models.AccountRoleOwner {
+		others, err := countOtherAccountOwners(c, target.UserID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if others == 0 {
+			c.JSON(http.StatusConflict, gin.H{
+				"error": "this is the account's last owner; promote someone else first"})
+			return
+		}
+	}
+
+	ctx := c.Request.Context()
+	if _, err := db.Admin("customer_users").UpdateOne(ctx,
+		bson.M{"user_id": target.UserID},
+		bson.M{"$set": bson.M{"account_role": body.Role}}); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	s := auth.Current(c)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "account_user.role_changed", AccountID: s.AccountID,
+		Target: target.Email, Detail: "role=" + body.Role, IP: c.ClientIP()})
+	c.JSON(http.StatusOK, gin.H{"ok": true})
+}
+
+// deleteAccountUser removes a person and every instance they hold.
+//
+// Grants go first, and the whole request is refused if any of them would strand
+// an instance with no owner. Removing the person but leaving their projected
+// rows behind would leave working logins for someone the account has removed —
+// the exact failure this endpoint exists to prevent.
+func deleteAccountUser(c *gin.Context) {
+	target, ok := accountUser(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	me := auth.CurrentUser(c)
+	if target.UserID == me.UserID {
+		c.JSON(http.StatusForbidden, gin.H{"error": "you cannot remove your own account"})
+		return
+	}
+	if target.AccountRole == models.AccountRoleOwner && me.AccountRole != models.AccountRoleOwner {
+		c.JSON(http.StatusForbidden, gin.H{"error": "only an owner can remove another owner"})
+		return
+	}
+	if target.AccountRole == models.AccountRoleOwner {
+		others, err := countOtherAccountOwners(c, target.UserID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if others == 0 {
+			c.JSON(http.StatusConflict, gin.H{
+				"error": "this is the account's last owner; promote someone else first"})
+			return
+		}
+	}
+
+	ctx := c.Request.Context()
+	s := auth.Current(c)
+
+	cur, err := db.Admin("instance_members").Find(ctx,
+		bson.M{"customer_user_id": target.UserID})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	members := []models.InstanceMember{}
+	if err := cur.All(ctx, &members); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Check every instance BEFORE deleting anything, so a refusal leaves the
+	// person exactly as they were rather than half-revoked.
+	for _, m := range members {
+		if m.Role != sharedmodels.RoleOwner {
+			continue
+		}
+		others, err := cloudprov.CountOtherOwners(ctx, m.InstanceID, target.UserID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if others == 0 {
+			c.JSON(http.StatusConflict, gin.H{
+				"error": "they are the last owner of an instance; give someone else that instance's owner role first"})
+			return
+		}
+	}
+
+	for _, m := range members {
+		if err := cloudprov.RevokeUser(ctx, m.InstanceID, target.UserID); err != nil {
+			log.Printf("deleteAccountUser: revoke %s from %s: %v", target.Email, m.InstanceID, err)
+			c.JSON(http.StatusInternalServerError, gin.H{
+				"error": "could not remove their instance access; nothing was deleted"})
+			return
+		}
+		if _, err := db.Admin("instance_members").DeleteOne(ctx,
+			bson.M{"member_id": m.MemberID}); err != nil {
+			log.Printf("deleteAccountUser: drop member row %s: %v", m.MemberID, err)
+		}
+	}
+
+	if _, err := db.Admin("customer_users").DeleteOne(ctx,
+		bson.M{"user_id": target.UserID}); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "account_user.removed", AccountID: s.AccountID,
+		Target: target.Email, Detail: fmt.Sprintf("revoked %d instance(s)", len(members)),
+		IP: c.ClientIP()})
+	c.JSON(http.StatusOK, gin.H{"deleted": true})
+}
+
+// changeAccountPassword sets one password and pushes it everywhere.
+//
+// HQ's hash is the single source of truth for every hq-sourced row, and the
+// control plane has no local password-change path for them, so there is no
+// competing writer.
+//
+// Propagation is best-effort ON PURPOSE. Failing the password change because
+// one of three instances was briefly unreachable would leave the customer with
+// the password they were trying to get rid of; hqsync repairs a stale instance
+// within fifteen minutes, which is recoverable.
+func changeAccountPassword(c *gin.Context) {
+	var body struct {
+		CurrentPassword string `json:"current_password"`
+		NewPassword     string `json:"new_password"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "current and new password are required"})
+		return
+	}
+	if len(body.NewPassword) < 12 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "choose a password of at least 12 characters"})
+		return
+	}
+
+	s := auth.Current(c)
+	ctx := c.Request.Context()
+
+	var me models.CustomerUser
+	if err := db.Admin("customer_users").FindOne(ctx,
+		bson.M{"user_id": s.UserID}).Decode(&me); err != nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "sign in required"})
+		return
+	}
+	if bcrypt.CompareHashAndPassword([]byte(me.PasswordHash), []byte(body.CurrentPassword)) != nil {
+		c.JSON(http.StatusForbidden, gin.H{"error": "that is not your current password"})
+		return
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte(body.NewPassword), auth.BcryptCost)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not set the password"})
+		return
+	}
+	if _, err := db.Admin("customer_users").UpdateOne(ctx,
+		bson.M{"user_id": me.UserID},
+		bson.M{"$set": bson.M{"password_hash": string(hash)}}); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not set the password"})
+		return
+	}
+
+	pending := false
+	if n, err := cloudprov.SetPasswordHash(ctx, me.UserID, string(hash)); err != nil {
+		pending = true
+		now := time.Now().UTC()
+		log.Printf("password: propagation for %s failed, hqsync will repair: %v", me.Email, err)
+		_, _ = db.Admin("customer_users").UpdateOne(ctx,
+			bson.M{"user_id": me.UserID},
+			bson.M{"$set": bson.M{"hq_sync_failed_at": now}})
+	} else {
+		log.Printf("password: %s propagated to %d instance user(s)", me.Email, n)
+		_, _ = db.Admin("customer_users").UpdateOne(ctx,
+			bson.M{"user_id": me.UserID},
+			bson.M{"$unset": bson.M{"hq_sync_failed_at": ""}})
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: me.Email, Action: "account_user.password_changed", AccountID: s.AccountID,
+		Target: me.Email, IP: c.ClientIP()})
+	c.JSON(http.StatusOK, gin.H{"updated": true, "propagation_pending": pending})
+}

admin/internal/api/routes.go

@@ -0,0 +1,124 @@
+// Package api mounts admin's HTTP surface.
+//
+// The route table is the single place scoping is guaranteed. Customer routes
+// live behind RequireCustomer and every handler that names an instance calls
+// ownedInstance. A new customer route that skips that helper is a scoping bug,
+// so keep them together and review them together.
+package api
+
+import (
+	"net/http"
+	"slices"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mrhid6/vantage/admin/internal/auth"
+	"github.com/mrhid6/vantage/admin/internal/config"
+	"github.com/mrhid6/vantage/admin/internal/models"
+)
+
+func Routes(cfg config.Config) http.Handler {
+	r := gin.New()
+	r.Use(gin.Logger(), gin.Recovery())
+	r.Use(cors(cfg.AllowedOrigins))
+
+	if cfg.TrustProxy {
+		_ = r.SetTrustedProxies(nil)
+	}
+
+	r.GET("/healthz", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"ok": true}) })
+
+	r.POST("/auth/staff/login", auth.HandleStaffLogin)
+	// Every customer authenticates against admin's own customer_users. There is
+	// deliberately no path that looks a customer up in the control plane by
+	// email alone: HQ sign-in names no instance, so such a lookup could not be
+	// scoped, and users.email is no longer globally unique.
+	r.POST("/auth/login", auth.HandleCustomerLogin)
+	r.POST("/auth/logout", auth.HandleLogout)
+	r.GET("/auth/verify", auth.HandleVerify)
+	r.GET("/auth/me", getMe)
+	r.POST("/auth/signup", auth.HandleSignup)
+	r.POST("/auth/accept-invite", auth.HandleAcceptInvite)
+
+	cust := r.Group("/api")
+	cust.Use(auth.RequireCustomer())
+	{
+		cust.GET("/account", getAccount)
+
+		// People. Reading is open to any member; changing anything is
+		// owner-or-admin, enforced per route rather than by splitting the group,
+		// so the guard is visible next to the route it guards.
+		cust.GET("/account/users", listAccountUsers)
+		cust.POST("/account/users",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			inviteAccountUser)
+		cust.PUT("/account/users/:id/role",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			updateAccountUserRole)
+		cust.DELETE("/account/users/:id",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			deleteAccountUser)
+
+		// Any member may change their own password — it is theirs. There is no
+		// endpoint for changing anyone else's.
+		cust.PUT("/account/password", changeAccountPassword)
+
+		cust.POST("/instances",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			createInstance)
+		cust.POST("/instances/link", linkInstance)
+		cust.POST("/instances/:id/relink", relinkInstance)
+		cust.POST("/instances/:id/renew", renewInstance)
+		cust.GET("/instances/:id/license", getInstanceLicense)
+		cust.GET("/instances/:id/license/download", downloadInstanceLicense)
+		cust.GET("/instances/:id/members", listInstanceMembers)
+		cust.POST("/instances/:id/members",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			grantInstanceMember)
+		cust.PUT("/instances/:id/members/:uid/role",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			updateInstanceMemberRole)
+		cust.DELETE("/instances/:id/members/:uid",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			revokeInstanceMember)
+		cust.GET("/subscriptions", listSubscriptions)
+	}
+
+	staff := r.Group("/api/staff")
+	staff.Use(auth.RequireStaff())
+	{
+		staff.GET("/accounts", staffListAccounts)
+		staff.POST("/accounts", staffCreateAccount)
+		staff.GET("/accounts/:id", staffGetAccount)
+		staff.POST("/accounts/:id/users", staffCreateAccountUser)
+		staff.GET("/instances", staffListInstances)
+		staff.POST("/instances", staffCreateInstance)
+		staff.GET("/instances/:id", staffGetInstance)
+		staff.GET("/subscriptions", staffListSubscriptions)
+		staff.POST("/instances/:id/issue", staffIssue)
+		staff.POST("/instances/:id/relink", staffRelink)
+		staff.GET("/licenses", staffListLicenses)
+		staff.GET("/plans", staffListPlans)
+		staff.PUT("/plans/:tier", staffUpdatePlan)
+		staff.GET("/audit", staffAudit)
+		staff.GET("/health/injection", staffInjectionHealth)
+	}
+
+	return r
+}
+
+func cors(allowed []string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		origin := c.GetHeader("Origin")
+		if origin != "" && slices.Contains(allowed, origin) {
+			c.Header("Access-Control-Allow-Origin", origin)
+			c.Header("Access-Control-Allow-Credentials", "true")
+			c.Header("Access-Control-Allow-Headers", "Content-Type")
+			c.Header("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS")
+		}
+		if c.Request.Method == http.MethodOptions {
+			c.AbortWithStatus(http.StatusNoContent)
+			return
+		}
+		c.Next()
+	}
+}

admin/internal/api/staff.go

@@ -0,0 +1,490 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/auth"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/licensing"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+	sharedmodels "github.com/mrhid6/vantage/shared/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func staffListAccounts(c *gin.Context) {
+	filter := bson.M{}
+	if q := c.Query("q"); q != "" {
+		or := []bson.M{
+			{"name": bson.M{"$regex": q, "$options": "i"}},
+			{"billing_email": bson.M{"$regex": q, "$options": "i"}},
+			{"paddle_customer_id": q},
+		}
+		// A support email often contains an instance UUID and nothing else, so
+		// resolve that to its owning account rather than returning nothing.
+		var inst models.Instance
+		if err := db.Admin("admin_instances").FindOne(c.Request.Context(),
+			bson.M{"instance_id": q}).Decode(&inst); err == nil {
+			or = append(or, bson.M{"account_id": inst.AccountID})
+		}
+		filter["$or"] = or
+	}
+	cur, err := db.Admin("accounts").Find(c.Request.Context(), filter,
+		options.Find().SetLimit(200).SetSort(bson.D{{Key: "created_at", Value: -1}}))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	accounts := []models.Account{}
+	if err := cur.All(c.Request.Context(), &accounts); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, accounts)
+}
+
+func staffCreateAccount(c *gin.Context) {
+	var body struct {
+		Name         string `json:"name"`
+		BillingEmail string `json:"billing_email"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Name == "" || body.BillingEmail == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name and billing_email are required"})
+		return
+	}
+	acct := models.Account{
+		AccountID:    uuid.NewString(),
+		Name:         body.Name,
+		BillingEmail: body.BillingEmail,
+		Status:       models.AccountActive,
+		CreatedAt:    time.Now().UTC(),
+	}
+	if _, err := db.Admin("accounts").InsertOne(c.Request.Context(), acct); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, acct)
+}
+
+func staffGetAccount(c *gin.Context) {
+	ctx := c.Request.Context()
+	var acct models.Account
+	if err := db.Admin("accounts").FindOne(ctx, bson.M{"account_id": c.Param("id")}).Decode(&acct); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return
+	}
+	instances := []models.Instance{}
+	if cur, err := db.Admin("admin_instances").Find(ctx, bson.M{"account_id": acct.AccountID}); err == nil {
+		_ = cur.All(ctx, &instances)
+	}
+	subs := []models.Subscription{}
+	if cur, err := db.Admin("subscriptions").Find(ctx, bson.M{"account_id": acct.AccountID}); err == nil {
+		_ = cur.All(ctx, &subs)
+	}
+	users := []models.CustomerUser{}
+	if cur, err := db.Admin("customer_users").Find(ctx, bson.M{"account_id": acct.AccountID}); err == nil {
+		_ = cur.All(ctx, &users)
+	}
+	entries := []models.AuditEntry{}
+	if cur, err := db.Admin("admin_audit").Find(ctx, bson.M{"account_id": acct.AccountID},
+		options.Find().SetLimit(100).SetSort(bson.D{{Key: "created_at", Value: -1}})); err == nil {
+		_ = cur.All(ctx, &entries)
+	}
+
+	// CustomerUser's password hash and both verify-token fields are json:"-",
+	// so no secret leaves here.
+	c.JSON(http.StatusOK, gin.H{
+		"account":       acct,
+		"instances":     instances,
+		"subscriptions": subs,
+		"users":         users,
+		"audit":         entries,
+	})
+}
+
+func staffListInstances(c *gin.Context) {
+	filter := bson.M{}
+	for param, field := range map[string]string{
+		"account_id": "account_id",
+		"deployment": "deployment",
+		"status":     "status",
+	} {
+		if v := c.Query(param); v != "" {
+			filter[field] = v
+		}
+	}
+	if c.Query("expiring") == "true" {
+		// Instances whose licence expires within 14 days, for renewal chasing.
+		var ids []string
+		cur, err := db.Admin("licenses").Find(c.Request.Context(), bson.M{
+			"superseded_by": bson.M{"$exists": false},
+			"expires_at":    bson.M{"$lt": time.Now().UTC().Add(14 * 24 * time.Hour)},
+		})
+		if err == nil {
+			var lics []models.License
+			if cur.All(c.Request.Context(), &lics) == nil {
+				for _, l := range lics {
+					ids = append(ids, l.InstanceID)
+				}
+			}
+		}
+		filter["instance_id"] = bson.M{"$in": ids}
+	}
+
+	cur, err := db.Admin("admin_instances").Find(c.Request.Context(), filter,
+		options.Find().SetLimit(500))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	instances := []models.Instance{}
+	if err := cur.All(c.Request.Context(), &instances); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, instances)
+}
+
+// staffCreateInstance attaches an instance to an account.
+//
+// For cloud, this ADOPTS an instance that already exists in the control plane —
+// the control-plane row is the source of truth for its name and slug, and this
+// refuses if no such instance exists, because an admin row pointing at nothing
+// would issue licences nobody can use.
+//
+// For self-hosted it does the same job as the customer-facing link endpoint, so
+// staff can link on a customer's behalf during support.
+//
+// This is how existing cloud instances get licensed: adopt, then issue.
+func staffCreateInstance(c *gin.Context) {
+	var body struct {
+		InstanceID string `json:"instance_id"`
+		AccountID  string `json:"account_id"`
+		Deployment string `json:"deployment"`
+		Name       string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.InstanceID == "" || body.AccountID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "instance_id and account_id are required"})
+		return
+	}
+	ctx := c.Request.Context()
+
+	if n, err := db.Admin("accounts").CountDocuments(ctx, bson.M{"account_id": body.AccountID}); err != nil || n == 0 {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no such account"})
+		return
+	}
+
+	inst := models.Instance{
+		InstanceID: body.InstanceID,
+		AccountID:  body.AccountID,
+		Name:       body.Name,
+		Deployment: body.Deployment,
+		Status:     models.StatusActive,
+		CreatedAt:  time.Now().UTC(),
+	}
+
+	if body.Deployment == license.DeploymentCloud {
+		var remote sharedmodels.Instance
+		if err := db.Control("instances").FindOne(ctx,
+			bson.M{"instance_id": body.InstanceID}).Decode(&remote); err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "no such cloud instance in the control plane"})
+			return
+		}
+		inst.Name = remote.Name
+		inst.Slug = remote.Slug
+	}
+
+	if _, err := db.Admin("admin_instances").InsertOne(ctx, inst); err != nil {
+		if mongo.IsDuplicateKeyError(err) {
+			c.JSON(http.StatusConflict, gin.H{"error": "that instance is already attached to an account"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	s := auth.Current(c)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance.attached", AccountID: body.AccountID, Target: body.InstanceID})
+	c.JSON(http.StatusCreated, inst)
+}
+
+// staffGetInstance is the "why did this stop working" screen's data: one
+// instance, its account, its whole licence history newest first, and whether
+// the control plane currently holds what we think it holds.
+func staffGetInstance(c *gin.Context) {
+	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
+	}
+
+	var acct models.Account
+	_ = db.Admin("accounts").FindOne(ctx, bson.M{"account_id": inst.AccountID}).Decode(&acct)
+
+	lics := []models.License{}
+	if cur, err := db.Admin("licenses").Find(ctx, bson.M{"instance_id": inst.InstanceID},
+		options.Find().SetSort(bson.D{{Key: "issued_at", Value: -1}})); err == nil {
+		_ = cur.All(ctx, &lics)
+	}
+
+	// Injection state is only meaningful for cloud. For self-hosted the
+	// customer holds the blob and there is nothing for us to have written.
+	injection := gin.H{"applicable": inst.Deployment == license.DeploymentCloud}
+	if inst.Deployment == license.DeploymentCloud {
+		var remote sharedmodels.Instance
+		err := db.Control("instances").FindOne(ctx,
+			bson.M{"instance_id": inst.InstanceID}).Decode(&remote)
+		switch {
+		case err != nil:
+			injection["state"] = "missing"
+		case inst.CurrentLicense == "":
+			injection["state"] = "none_issued"
+		default:
+			var current models.License
+			if db.Admin("licenses").FindOne(ctx,
+				bson.M{"license_id": inst.CurrentLicense}).Decode(&current) == nil &&
+				remote.LicenseBlob == current.Blob {
+				injection["state"] = "current"
+			} else {
+				injection["state"] = "stale"
+			}
+		}
+		injection["failed_at"] = inst.InjectFailedAt
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"instance": inst, "account": acct, "licenses": lics, "injection": injection,
+	})
+}
+
+// staffListSubscriptions backs the past-due queue on the dashboard.
+func staffListSubscriptions(c *gin.Context) {
+	filter := bson.M{}
+	if v := c.Query("status"); v != "" {
+		filter["status"] = v
+	}
+	if v := c.Query("account_id"); v != "" {
+		filter["account_id"] = v
+	}
+	cur, err := db.Admin("subscriptions").Find(c.Request.Context(), filter,
+		options.Find().SetLimit(500))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	subs := []models.Subscription{}
+	if err := cur.All(c.Request.Context(), &subs); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, subs)
+}
+
+func staffIssue(c *gin.Context) {
+	var body struct {
+		Tier   string `json:"tier"`
+		Term   string `json:"term"`
+		Reason string `json:"reason"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Tier == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "tier is required"})
+		return
+	}
+	if body.Reason == "" {
+		body.Reason = models.ReasonManual
+	}
+
+	s := auth.Current(c)
+	lic, err := licensing.Issue(c.Request.Context(), licensing.IssueInput{
+		InstanceID: c.Param("id"),
+		Tier:       body.Tier,
+		Term:       body.Term,
+		Reason:     body.Reason,
+		IssuedBy:   s.Email,
+	})
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	var inst models.Instance
+	if db.Admin("admin_instances").FindOne(c.Request.Context(),
+		bson.M{"instance_id": lic.InstanceID}).Decode(&inst) == nil {
+		deliver(c, &inst, lic)
+	}
+	c.JSON(http.StatusCreated, lic)
+}
+
+// staffRelink has no attempt cap. The customer-facing limit exists to put a
+// human in front of the fourth attempt; this is that human.
+func staffRelink(c *gin.Context) {
+	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()
+
+	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
+	}
+
+	lic, err := licensing.Relink(ctx, inst.AccountID, inst.InstanceID, body.InstanceID, true)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, lic)
+}
+
+func staffListLicenses(c *gin.Context) {
+	filter := bson.M{}
+	if v := c.Query("instance_id"); v != "" {
+		filter["instance_id"] = v
+	}
+	if v := c.Query("account_id"); v != "" {
+		filter["account_id"] = v
+	}
+	cur, err := db.Admin("licenses").Find(c.Request.Context(), filter,
+		options.Find().SetLimit(500).SetSort(bson.D{{Key: "issued_at", Value: -1}}))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	lics := []models.License{}
+	if err := cur.All(c.Request.Context(), &lics); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, lics)
+}
+
+func staffListPlans(c *gin.Context) {
+	cur, err := db.Admin("plans").Find(c.Request.Context(), bson.M{})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	plans := []models.Plan{}
+	if err := cur.All(c.Request.Context(), &plans); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, plans)
+}
+
+// staffUpdatePlan changes what a tier grants FROM NOW ON. Existing licences
+// snapshotted their plan at issue time and are unaffected — the same rule as
+// workflow_runs.steps_snapshot.
+func staffUpdatePlan(c *gin.Context) {
+	var body models.Plan
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid plan"})
+		return
+	}
+	set := bson.M{
+		"name":              body.Name,
+		"limits":            body.Limits,
+		"features":          body.Features,
+		"paddle_product_id": body.PaddleProductID,
+		"paddle_price_ids":  body.PaddlePriceIDs,
+		"active":            body.Active,
+	}
+	if _, err := db.Admin("plans").UpdateOne(c.Request.Context(),
+		bson.M{"tier": c.Param("tier")}, bson.M{"$set": set}); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"updated": true})
+}
+
+func staffAudit(c *gin.Context) {
+	filter := bson.M{}
+	if v := c.Query("account_id"); v != "" {
+		filter["account_id"] = v
+	}
+	cur, err := db.Admin("admin_audit").Find(c.Request.Context(), filter,
+		options.Find().SetLimit(500).SetSort(bson.D{{Key: "created_at", Value: -1}}))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	entries := []models.AuditEntry{}
+	if err := cur.All(c.Request.Context(), &entries); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, entries)
+}
+
+// staffInjectionHealth lists instances whose last injection failed. This is the
+// page to look at when a customer says their cloud instance is read-only.
+func staffInjectionHealth(c *gin.Context) {
+	cur, err := db.Admin("admin_instances").Find(c.Request.Context(),
+		bson.M{"inject_failed_at": bson.M{"$exists": true}})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	failed := []models.Instance{}
+	if err := cur.All(c.Request.Context(), &failed); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"failed": failed, "count": len(failed)})
+}
+
+// staffCreateAccountUser gives an account an HQ login.
+//
+// This is how a legacy cloud customer — one whose instance predates HQ accounts
+// — gets into the portal, alongside the manual instance attach the spec README
+// describes. It reuses CreateCustomerUser, so the row is unverified until the
+// emailed link is opened and is rolled back if that email cannot be sent.
+func staffCreateAccountUser(c *gin.Context) {
+	var body struct {
+		Email    string `json:"email"`
+		Password string `json:"password"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Email == "" || len(body.Password) < 12 {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "email and a password of at least 12 characters are required"})
+		return
+	}
+	ctx := c.Request.Context()
+	accountID := c.Param("id")
+
+	if n, err := db.Admin("accounts").CountDocuments(ctx,
+		bson.M{"account_id": accountID}); err != nil || n == 0 {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no such account"})
+		return
+	}
+
+	email := strings.ToLower(strings.TrimSpace(body.Email))
+	// Staff attaching a legacy customer are attaching the person who runs that
+	// account, so they get owner.
+	if err := auth.CreateCustomerUser(ctx, accountID, email, body.Password, models.AccountRoleOwner); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	s := auth.Current(c)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "customer_user.created", AccountID: accountID, Target: email})
+	c.JSON(http.StatusCreated, gin.H{"pending": true})
+}

admin/internal/audit/audit.go

@@ -0,0 +1,21 @@
+// Package audit records who did what. Every issuance, link, relink and sign-in
+// attempt lands here.
+package audit
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+)
+
+// Write never returns an error: an audit failure must not roll back the action
+// it describes. It logs instead, loudly enough to notice.
+func Write(ctx context.Context, e models.AuditEntry) {
+	e.CreatedAt = time.Now().UTC()
+	if _, err := db.Admin("admin_audit").InsertOne(ctx, e); err != nil {
+		log.Printf("AUDIT WRITE FAILED action=%s target=%s: %v", e.Action, e.Target, err)
+	}
+}

admin/internal/auth/customer.go

@@ -0,0 +1,341 @@
+package auth
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/mail"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"golang.org/x/crypto/bcrypt"
+)
+
+// BcryptCost matches the control plane and sitesvc. Changing it here alone would
+// make hashes inconsistent across services that may one day compare them.
+const BcryptCost = 12
+
+// VerifyWindow mirrors sitesvc's proven pattern: 32 random bytes, only the
+// SHA-256 hash stored, 24-hour expiry.
+const VerifyWindow = 24 * time.Hour
+
+// CreateCustomerUser creates an unverified HQ login with a chosen password and
+// emails the verification link. Used by signup and by staff.
+func CreateCustomerUser(ctx context.Context, accountID, email, password, accountRole string) error {
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), BcryptCost)
+	if err != nil {
+		return err
+	}
+
+	raw := make([]byte, 32)
+	if _, err := rand.Read(raw); err != nil {
+		return err
+	}
+	token := hex.EncodeToString(raw)
+	sum := sha256.Sum256([]byte(token))
+	expiry := time.Now().UTC().Add(VerifyWindow)
+
+	u := models.CustomerUser{
+		UserID:            uuid.NewString(),
+		AccountID:         accountID,
+		Email:             strings.ToLower(strings.TrimSpace(email)),
+		PasswordHash:      string(hash),
+		AccountRole:       accountRole,
+		VerifyTokenHash:   hex.EncodeToString(sum[:]),
+		VerifyTokenExpiry: &expiry,
+		CreatedAt:         time.Now().UTC(),
+	}
+	if _, err := db.Admin("customer_users").InsertOne(ctx, u); err != nil {
+		return err
+	}
+
+	if err := mail.SendVerification(u.Email, token); err != nil {
+		// Undo the insert. A row whose verification link was never delivered is
+		// worse than no row: it can never be signed in to, and it holds the
+		// unique index on email, so the customer cannot sign up again with the
+		// address they just used.
+		//
+		// Deliberately NOT on ctx. ctx is the HTTP request's, and the most likely
+		// reason we are here is that the mail server stalled until the browser
+		// gave up — which cancels ctx and makes this delete a silent no-op,
+		// stranding exactly the row it exists to remove. That happened in
+		// production against a port-465 server.
+		rbCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
+		defer cancel()
+		if _, dErr := db.Admin("customer_users").DeleteOne(rbCtx, bson.M{"user_id": u.UserID}); dErr != nil {
+			log.Printf("signup: FAILED to roll back customer_user %s (%s) after mail error: %v",
+				u.UserID, u.Email, dErr)
+		}
+		return err
+	}
+	return nil
+}
+
+// CreateInvitedUser creates a passwordless, unverified member of an existing
+// account and emails them a link to set a password.
+//
+// The empty hash is load-bearing: bcrypt.CompareHashAndPassword against "" can
+// never succeed, so the row cannot sign in and cannot usefully be projected
+// into an instance until the invitee has been through /accept-invite. That is
+// also why a grant refuses an unverified user.
+func CreateInvitedUser(ctx context.Context, accountID, accountName, email, accountRole string) error {
+	raw := make([]byte, 32)
+	if _, err := rand.Read(raw); err != nil {
+		return err
+	}
+	token := hex.EncodeToString(raw)
+	sum := sha256.Sum256([]byte(token))
+	expiry := time.Now().UTC().Add(VerifyWindow)
+
+	u := models.CustomerUser{
+		UserID:            uuid.NewString(),
+		AccountID:         accountID,
+		Email:             strings.ToLower(strings.TrimSpace(email)),
+		AccountRole:       accountRole,
+		VerifyTokenHash:   hex.EncodeToString(sum[:]),
+		VerifyTokenExpiry: &expiry,
+		CreatedAt:         time.Now().UTC(),
+	}
+	if _, err := db.Admin("customer_users").InsertOne(ctx, u); err != nil {
+		return err
+	}
+
+	if err := mail.SendInvite(u.Email, accountName, token); err != nil {
+		// Same rollback rule, and the same detached context, as signup: a row
+		// whose link was never delivered can never be signed in to and holds
+		// the unique index on email against the person it was meant for.
+		rbCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
+		defer cancel()
+		if _, dErr := db.Admin("customer_users").DeleteOne(rbCtx, bson.M{"user_id": u.UserID}); dErr != nil {
+			log.Printf("invite: FAILED to roll back customer_user %s (%s) after mail error: %v",
+				u.UserID, u.Email, dErr)
+		}
+		return err
+	}
+	return nil
+}
+
+// HandleAcceptInvite consumes an invitation token and sets the password.
+//
+// Verification and password-setting are one step for an invitee, because the
+// link IS the proof of address and there is nothing to verify separately.
+func HandleAcceptInvite(c *gin.Context) {
+	var body struct {
+		Token    string `json:"token"`
+		Password string `json:"password"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Token == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "missing token"})
+		return
+	}
+	if len(body.Password) < 12 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "choose a password of at least 12 characters"})
+		return
+	}
+	hash, err := bcrypt.GenerateFromPassword([]byte(body.Password), BcryptCost)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not set the password"})
+		return
+	}
+
+	sum := sha256.Sum256([]byte(body.Token))
+	now := time.Now().UTC()
+	res, err := db.Admin("customer_users").UpdateOne(c.Request.Context(),
+		bson.M{
+			"verify_token_hash":   hex.EncodeToString(sum[:]),
+			"verify_token_expiry": bson.M{"$gt": now},
+		},
+		bson.M{
+			"$set":   bson.M{"verified_at": now, "password_hash": string(hash)},
+			"$unset": bson.M{"verify_token_hash": "", "verify_token_expiry": ""},
+		})
+	if err != nil || res.MatchedCount == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "that link is invalid or has expired"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"accepted": true})
+}
+
+// HandleSignup creates a self-hosted customer: an account, an unverified user,
+// and a verification email.
+//
+// Nothing is usable until the emailed link is opened, the same rule sitesvc
+// already proves — so an address nobody controls cannot occupy an email or
+// produce an account that can sign in.
+func HandleSignup(c *gin.Context) {
+	var body struct {
+		Name     string `json:"name"`
+		Email    string `json:"email"`
+		Password string `json:"password"`
+		Website  string `json:"website"` // honeypot; real users never fill it
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name, email and password are required"})
+		return
+	}
+
+	// Honeypot: answer exactly as success so a bot learns nothing.
+	if strings.TrimSpace(body.Website) != "" {
+		c.JSON(http.StatusCreated, gin.H{"pending": true})
+		return
+	}
+
+	email := strings.ToLower(strings.TrimSpace(body.Email))
+	ctx := c.Request.Context()
+
+	if email == "" || len(body.Password) < 12 || strings.TrimSpace(body.Name) == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name, email and a password of at least 12 characters are required"})
+		return
+	}
+	if !allowAttempt("signup:"+email, c.ClientIP()) {
+		c.JSON(http.StatusTooManyRequests, gin.H{"error": "too many attempts, try again later"})
+		return
+	}
+
+	if n, _ := db.Admin("customer_users").CountDocuments(ctx, bson.M{"email": email}); n > 0 {
+		// Same response as success. Telling a stranger the address is taken
+		// confirms who has an account here.
+		c.JSON(http.StatusCreated, gin.H{"pending": true})
+		return
+	}
+
+	acct := models.Account{
+		AccountID:    uuid.NewString(),
+		Name:         strings.TrimSpace(body.Name),
+		BillingEmail: email,
+		Status:       models.AccountActive,
+		CreatedAt:    time.Now().UTC(),
+	}
+	if _, err := db.Admin("accounts").InsertOne(ctx, acct); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not create the account"})
+		return
+	}
+
+	if err := CreateCustomerUser(ctx, acct.AccountID, email, body.Password, models.AccountRoleOwner); err != nil {
+		// Roll the account back rather than strand one with no owner. Detached
+		// from ctx for the same reason as the user rollback above: a stalled mail
+		// server cancels the request, and a rollback that needs the request to
+		// still be alive is a rollback that fails exactly when it is needed.
+		log.Printf("signup: %s failed, rolling back account %s: %v", email, acct.AccountID, err)
+		rbCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
+		defer cancel()
+		if _, dErr := db.Admin("accounts").DeleteOne(rbCtx, bson.M{"account_id": acct.AccountID}); dErr != nil {
+			log.Printf("signup: FAILED to roll back account %s: %v", acct.AccountID, dErr)
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not send the verification email"})
+		return
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: email, Action: "customer.signup", AccountID: acct.AccountID, IP: c.ClientIP()})
+	c.JSON(http.StatusCreated, gin.H{"pending": true})
+}
+
+// HandleVerify consumes a verification token.
+func HandleVerify(c *gin.Context) {
+	token := c.Query("token")
+	if token == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "missing token"})
+		return
+	}
+	sum := sha256.Sum256([]byte(token))
+	now := time.Now().UTC()
+	ctx := c.Request.Context()
+	hashed := hex.EncodeToString(sum[:])
+
+	// Peek first. An invited row has no password yet, so consuming its token
+	// here would verify an account nobody can sign in to and burn the only
+	// link that could fix it.
+	var u models.CustomerUser
+	if err := db.Admin("customer_users").FindOne(ctx, bson.M{
+		"verify_token_hash":   hashed,
+		"verify_token_expiry": bson.M{"$gt": now},
+	}).Decode(&u); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "that link is invalid or has expired"})
+		return
+	}
+	if u.PasswordHash == "" {
+		c.JSON(http.StatusOK, gin.H{"verified": false, "needs_password": true})
+		return
+	}
+
+	res, err := db.Admin("customer_users").UpdateOne(ctx,
+		bson.M{
+			"verify_token_hash":   hashed,
+			"verify_token_expiry": bson.M{"$gt": now},
+		},
+		bson.M{
+			"$set":   bson.M{"verified_at": now},
+			"$unset": bson.M{"verify_token_hash": "", "verify_token_expiry": ""},
+		})
+	if err != nil || res.MatchedCount == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "that link is invalid or has expired"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"verified": true})
+}
+
+// HandleCustomerLogin authenticates a self-hosted customer.
+func HandleCustomerLogin(c *gin.Context) {
+	var body struct {
+		Email    string `json:"email"`
+		Password string `json:"password"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "email and password are required"})
+		return
+	}
+	email := strings.ToLower(strings.TrimSpace(body.Email))
+	ctx := c.Request.Context()
+
+	if !allowAttempt(email, c.ClientIP()) {
+		c.JSON(http.StatusTooManyRequests, gin.H{"error": "too many attempts, try again later"})
+		return
+	}
+
+	reject := func(reason string) {
+		audit.Write(ctx, models.AuditEntry{
+			Actor: email, Action: "customer.login_failed", IP: c.ClientIP(), Detail: reason})
+		c.JSON(http.StatusUnauthorized, gin.H{"error": genericAuthError})
+	}
+
+	var u models.CustomerUser
+	if err := db.Admin("customer_users").FindOne(ctx, bson.M{"email": email}).Decode(&u); err != nil {
+		bcrypt.CompareHashAndPassword([]byte(dummyHash), []byte(body.Password))
+		reject("unknown email")
+		return
+	}
+	if bcrypt.CompareHashAndPassword([]byte(u.PasswordHash), []byte(body.Password)) != nil {
+		reject("bad password")
+		return
+	}
+	if u.VerifiedAt == nil {
+		// Distinct from genericAuthError on purpose: the address is already
+		// known to be theirs, so there is nothing to disclose, and "check your
+		// email" is the only useful thing to say.
+		c.JSON(http.StatusForbidden, gin.H{"error": "verify your email address first"})
+		return
+	}
+
+	id, err := Save(ctx, Session{
+		UserID: u.UserID, Kind: KindCustomer, Email: u.Email, AccountID: u.AccountID,
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "session failed"})
+		return
+	}
+	SetCookie(c, id)
+	clearAttempts(email)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: email, Action: "customer.login", AccountID: u.AccountID, IP: c.ClientIP()})
+	c.JSON(http.StatusOK, gin.H{"kind": KindCustomer, "email": u.Email})
+}

admin/internal/auth/middleware.go

@@ -0,0 +1,111 @@
+package auth
+
+import (
+	"net/http"
+	"slices"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+const ctxSession = "admin_session_obj"
+
+// Load returns the caller's session, or nil. Exported because the session probe
+// in api/ needs to read a session without requiring one.
+func Load(c *gin.Context) *Session {
+	id, err := c.Cookie(CookieName)
+	if err != nil || id == "" {
+		return nil
+	}
+	s, err := Get(c.Request.Context(), id)
+	if err != nil {
+		return nil
+	}
+	return s
+}
+
+// Current returns the session, or nil.
+func Current(c *gin.Context) *Session {
+	if v, ok := c.Get(ctxSession); ok {
+		if s, ok := v.(*Session); ok {
+			return s
+		}
+	}
+	return nil
+}
+
+func RequireStaff() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		s := Load(c)
+		if s == nil || s.Kind != KindStaff {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "sign in required"})
+			return
+		}
+		c.Set(ctxSession, s)
+		c.Next()
+	}
+}
+
+// RequireCustomer admits both cloud and self-hosted customers. Every handler
+// behind it scopes by AccountID via the helper in api/customer.go — never by
+// remembering to filter.
+func RequireCustomer() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		s := Load(c)
+		if s == nil || s.Kind != KindCustomer || s.AccountID == "" {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "sign in required"})
+			return
+		}
+		c.Set(ctxSession, s)
+		c.Next()
+	}
+}
+
+const ctxCustomerUser = "admin_customer_user"
+
+// CurrentUser returns the calling customer's own row, loaded once per request
+// by RequireAccountRole.
+//
+// It is nil behind RequireCustomer alone. A handler that needs the role must
+// sit behind RequireAccountRole, which is the only thing that loads it.
+func CurrentUser(c *gin.Context) *models.CustomerUser {
+	if v, ok := c.Get(ctxCustomerUser); ok {
+		if u, ok := v.(*models.CustomerUser); ok {
+			return u
+		}
+	}
+	return nil
+}
+
+// RequireAccountRole admits a customer holding one of the given account roles.
+//
+// The role is read from the database on every request rather than carried in
+// the session. A session lives 24 hours; a demotion that only takes effect
+// when someone signs out again is not a demotion.
+func RequireAccountRole(roles ...string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		s := Current(c)
+		if s == nil {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "sign in required"})
+			return
+		}
+		var u models.CustomerUser
+		if err := db.Admin("customer_users").FindOne(c.Request.Context(),
+			bson.M{"user_id": s.UserID}).Decode(&u); err != nil {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "sign in required"})
+			return
+		}
+		if !slices.Contains(roles, u.AccountRole) {
+			// 403 rather than 404 here: this is the caller's OWN account, so
+			// there is no existence to disclose — the 404 rule protects other
+			// accounts' resources, not the caller's view of their own.
+			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
+				"error": "your account role does not allow this"})
+			return
+		}
+		c.Set(ctxCustomerUser, &u)
+		c.Next()
+	}
+}

admin/internal/auth/ratelimit.go

@@ -0,0 +1,55 @@
+package auth
+
+import (
+	"sync"
+	"time"
+)
+
+// Thresholds from spec 3: 5 attempts per email per 15 minutes, 20 per IP per
+// hour. The email limit stops a targeted attack on one account; the IP limit
+// stops a spray across many.
+const (
+	emailLimit  = 5
+	emailWindow = 15 * time.Minute
+	ipLimit     = 20
+	ipWindow    = time.Hour
+)
+
+var (
+	attemptMu sync.Mutex
+	byEmail   = map[string][]time.Time{}
+	byIP      = map[string][]time.Time{}
+)
+
+func prune(in []time.Time, cutoff time.Time) []time.Time {
+	out := in[:0]
+	for _, t := range in {
+		if t.After(cutoff) {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+func allowAttempt(email, ip string) bool {
+	now := time.Now()
+
+	attemptMu.Lock()
+	defer attemptMu.Unlock()
+
+	byEmail[email] = prune(byEmail[email], now.Add(-emailWindow))
+	byIP[ip] = prune(byIP[ip], now.Add(-ipWindow))
+
+	if len(byEmail[email]) >= emailLimit || len(byIP[ip]) >= ipLimit {
+		return false
+	}
+	byEmail[email] = append(byEmail[email], now)
+	byIP[ip] = append(byIP[ip], now)
+	return true
+}
+
+func clearAttempts(email string) {
+	attemptMu.Lock()
+	delete(byEmail, email)
+	attemptMu.Unlock()
+}

admin/internal/auth/session.go

@@ -0,0 +1,101 @@
+// Package auth holds admin's three identities: staff, cloud customers and
+// self-hosted customers. All three share one session store and one cookie.
+package auth
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	CookieName   = "admin_session"
+	SessionTTL   = 24 * time.Hour
+	KindStaff    = "staff"
+	KindCustomer = "customer"
+)
+
+type Session struct {
+	UserID    string `json:"user_id"`
+	Kind      string `json:"kind"`
+	Email     string `json:"email"`
+	AccountID string `json:"account_id,omitempty"` // customers only
+}
+
+var rdb *redis.Client
+
+// InitRedis connects the session store.
+//
+// Username and password may both be empty for an unauthenticated instance. For
+// a legacy `requirepass` Redis, pass the password with an empty username —
+// go-redis then sends AUTH with one argument instead of two.
+func InitRedis(addr, username, password string) {
+	rdb = redis.NewClient(&redis.Options{
+		Addr:     addr,
+		Username: username,
+		Password: password,
+	})
+}
+
+func Ping(ctx context.Context) error { return rdb.Ping(ctx).Err() }
+
+func newID() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}
+
+func Save(ctx context.Context, s Session) (string, error) {
+	id, err := newID()
+	if err != nil {
+		return "", err
+	}
+	body, err := json.Marshal(s)
+	if err != nil {
+		return "", err
+	}
+	if err := rdb.Set(ctx, "admin_session:"+id, body, SessionTTL).Err(); err != nil {
+		return "", err
+	}
+	return id, nil
+}
+
+func Get(ctx context.Context, id string) (*Session, error) {
+	body, err := rdb.Get(ctx, "admin_session:"+id).Bytes()
+	if err != nil {
+		return nil, err
+	}
+	var s Session
+	if err := json.Unmarshal(body, &s); err != nil {
+		return nil, err
+	}
+	return &s, nil
+}
+
+func Destroy(ctx context.Context, id string) { rdb.Del(ctx, "admin_session:"+id) }
+
+func SetCookie(c *gin.Context, id string) {
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     CookieName,
+		Value:    id,
+		Path:     "/",
+		HttpOnly: true,
+		Secure:   true,
+		SameSite: http.SameSiteLaxMode,
+		MaxAge:   int(SessionTTL.Seconds()),
+	})
+}
+
+func ClearCookie(c *gin.Context) {
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name: CookieName, Value: "", Path: "/", HttpOnly: true, Secure: true, MaxAge: -1,
+	})
+}

admin/internal/auth/staff.go

@@ -0,0 +1,77 @@
+package auth
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"golang.org/x/crypto/bcrypt"
+)
+
+// genericAuthError is returned for every failure mode — unknown email, wrong
+// password, wrong role. Distinguishing them would confirm which addresses have
+// accounts.
+const genericAuthError = "email or password is incorrect"
+
+func HandleStaffLogin(c *gin.Context) {
+	var body struct {
+		Email    string `json:"email"`
+		Password string `json:"password"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "email and password are required"})
+		return
+	}
+	email := strings.ToLower(strings.TrimSpace(body.Email))
+
+	if !allowAttempt(email, c.ClientIP()) {
+		c.JSON(http.StatusTooManyRequests, gin.H{"error": "too many attempts, try again later"})
+		return
+	}
+
+	var u models.StaffUser
+	err := db.Admin("staff_users").FindOne(c.Request.Context(), bson.M{"email": email}).Decode(&u)
+	if err != nil {
+		// Spend the same work as a real comparison so timing does not
+		// distinguish "no such user" from "wrong password".
+		bcrypt.CompareHashAndPassword([]byte(dummyHash), []byte(body.Password))
+		audit.Write(c.Request.Context(), models.AuditEntry{
+			Actor: email, Action: "staff.login_failed", IP: c.ClientIP(), Detail: "unknown email"})
+		c.JSON(http.StatusUnauthorized, gin.H{"error": genericAuthError})
+		return
+	}
+
+	if bcrypt.CompareHashAndPassword([]byte(u.PasswordHash), []byte(body.Password)) != nil {
+		audit.Write(c.Request.Context(), models.AuditEntry{
+			Actor: email, Action: "staff.login_failed", IP: c.ClientIP(), Detail: "bad password"})
+		c.JSON(http.StatusUnauthorized, gin.H{"error": genericAuthError})
+		return
+	}
+
+	id, err := Save(c.Request.Context(), Session{UserID: u.UserID, Kind: KindStaff, Email: u.Email})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "session failed"})
+		return
+	}
+	SetCookie(c, id)
+	clearAttempts(email)
+	audit.Write(c.Request.Context(), models.AuditEntry{
+		Actor: email, Action: "staff.login", IP: c.ClientIP()})
+	c.JSON(http.StatusOK, gin.H{"kind": KindStaff, "email": u.Email, "name": u.Name})
+}
+
+// dummyHash is a valid bcrypt hash of a random value, compared against when no
+// user exists so the timing profile matches.
+const dummyHash = "$2a$12$C6UzMDM.H6dfI/f/IKcEe.6qGZoAZQFtQmOoLmC5PbfW1uMh1Sv2u"
+
+func HandleLogout(c *gin.Context) {
+	if id, err := c.Cookie(CookieName); err == nil && id != "" {
+		Destroy(c.Request.Context(), id)
+	}
+	ClearCookie(c)
+	c.JSON(http.StatusOK, gin.H{"ok": true})
+}

admin/internal/cloudprov/cloudprov.go

@@ -0,0 +1,185 @@
+// Package cloudprov provisions cloud instances in the control plane.
+//
+// This is admin's second and final write path into the control-plane database,
+// alongside inject. It writes `instances` and `users` and nothing else. A third
+// write target, or a write to any other collection from here, is a design change
+// and not a refactor — see the spec's "Admin's control-plane write boundary".
+//
+// Every function here is called from a customer request, so each one leaves the
+// control plane in a consistent state or not at all: the caller unwinds in
+// reverse order on failure, and RollbackInstance refuses to delete an instance
+// that has users.
+package cloudprov
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/mrhid6/vantage/admin/internal/db"
+	sharedmodels "github.com/mrhid6/vantage/shared/models"
+	"github.com/mrhid6/vantage/shared/provision"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// CreateInstance creates a control-plane instance and its owner.
+//
+// The owner's password hash is COPIED from the HQ account rather than shared.
+// HQ remains the single source of truth: a password change there copies the new
+// hash to every projected row (see SetPasswordHash), and hqsync repairs any that
+// a failed write left stale. The control plane has no local password-change path
+// for an hq-sourced row, so there is no competing writer.
+//
+// On owner-insert failure the instance is rolled back, so a failed provision
+// never leaves a slug permanently occupied by an instance nobody owns.
+func CreateInstance(ctx context.Context, name, ownerEmail, ownerPasswordHash, hqUserID string) (*sharedmodels.Instance, error) {
+	inst, err := provision.CreateInstance(ctx, db.ControlDB(), name)
+	if err != nil {
+		return nil, err
+	}
+
+	u, err := provision.CreateUserWithHash(ctx, db.ControlDB(), inst.InstanceID,
+		ownerEmail, ownerPasswordHash, sharedmodels.RoleOwner, sharedmodels.AuthHQ)
+	if err != nil {
+		if rbErr := provision.RollbackInstance(ctx, db.ControlDB(), inst.InstanceID); rbErr != nil {
+			return nil, fmt.Errorf("create owner: %w (and rollback failed: %v)", err, rbErr)
+		}
+		return nil, err
+	}
+
+	// hq_user_id is what phase 3 uses to find every row projected from one HQ
+	// user when its password changes. Set at creation so the owner is not a
+	// special case later.
+	if _, err := db.Control("users").UpdateOne(ctx,
+		bson.M{"user_id": u.UserID},
+		bson.M{"$set": bson.M{"hq_user_id": hqUserID}}); err != nil {
+		return nil, fmt.Errorf("set hq_user_id: %w", err)
+	}
+
+	return inst, nil
+}
+
+// DeleteUser removes one control-plane user. Used only to unwind a failed
+// provision.
+func DeleteUser(ctx context.Context, instanceID, userID string) error {
+	_, err := db.Control("users").DeleteOne(ctx,
+		bson.M{"instance_id": instanceID, "user_id": userID})
+	return err
+}
+
+// RollbackInstance deletes an instance that has no users.
+func RollbackInstance(ctx context.Context, instanceID string) error {
+	return provision.RollbackInstance(ctx, db.ControlDB(), instanceID)
+}
+
+// OwnerUserID returns the control-plane user_id of an instance's owner, so a
+// caller can unwind a partial provision without re-deriving it.
+func OwnerUserID(ctx context.Context, instanceID string) (string, error) {
+	var u sharedmodels.User
+	err := db.Control("users").FindOne(ctx, bson.M{
+		"instance_id": instanceID,
+		"role":        sharedmodels.RoleOwner,
+	}).Decode(&u)
+	if err != nil {
+		return "", err
+	}
+	return u.UserID, nil
+}
+
+// GrantUser projects an HQ person into a control-plane instance.
+//
+// The password hash is copied from customer_users rather than re-derived: HQ
+// owns the password, and a grant that asked for a password again would create
+// a second credential for one person.
+//
+// The row is written with auth_source "hq" and hq_user_id set, which is what
+// makes the control plane refuse to edit it locally and what lets a password
+// change find it later.
+func GrantUser(ctx context.Context, instanceID, email, passwordHash, role, hqUserID string) (*sharedmodels.User, error) {
+	u, err := provision.CreateUserWithHash(ctx, db.ControlDB(), instanceID,
+		email, passwordHash, role, sharedmodels.AuthHQ)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := db.Control("users").UpdateOne(ctx,
+		bson.M{"user_id": u.UserID},
+		bson.M{"$set": bson.M{"hq_user_id": hqUserID}}); err != nil {
+		// Unwind: a projected row with no hq_user_id is invisible to revoke and
+		// to password propagation, which is worse than no row at all.
+		_, _ = db.Control("users").DeleteOne(ctx, bson.M{"user_id": u.UserID})
+		return nil, fmt.Errorf("set hq_user_id: %w", err)
+	}
+	u.HQUserID = hqUserID
+	return u, nil
+}
+
+// RevokeUser deletes the projected row for one person in one instance.
+//
+// Deleting rather than disabling is deliberate: the control plane has no
+// concept of a disabled user, and a row that still exists is a row that can
+// still sign in.
+func RevokeUser(ctx context.Context, instanceID, hqUserID string) error {
+	_, err := db.Control("users").DeleteOne(ctx, bson.M{
+		"instance_id": instanceID,
+		"hq_user_id":  hqUserID,
+	})
+	return err
+}
+
+// SetMemberRole changes a projected user's role inside one instance.
+func SetMemberRole(ctx context.Context, instanceID, hqUserID, role string) error {
+	if !sharedmodels.ValidRole(role) {
+		return fmt.Errorf("invalid role %q", role)
+	}
+	res, err := db.Control("users").UpdateOne(ctx,
+		bson.M{"instance_id": instanceID, "hq_user_id": hqUserID},
+		bson.M{"$set": bson.M{"role": role}})
+	if err != nil {
+		return err
+	}
+	if res.MatchedCount == 0 {
+		return fmt.Errorf("no projected user in instance %s", instanceID)
+	}
+	return nil
+}
+
+// CountOtherOwners counts owners of an instance other than one HQ person.
+//
+// It counts CONTROL-PLANE owners, so an owner created locally inside the
+// instance counts too. That matters: refusing to revoke the last HQ owner of
+// an instance that has three local owners would be a refusal with no cause.
+//
+// $ne matches documents where the field is absent, which is exactly how a
+// locally-created owner is stored.
+func CountOtherOwners(ctx context.Context, instanceID, exceptHQUserID string) (int64, error) {
+	return db.Control("users").CountDocuments(ctx, bson.M{
+		"instance_id": instanceID,
+		"role":        sharedmodels.RoleOwner,
+		"hq_user_id":  bson.M{"$ne": exceptHQUserID},
+	})
+}
+
+// SetPasswordHash writes one hash to every row projected from one HQ person,
+// across every instance, and reports how many it changed.
+func SetPasswordHash(ctx context.Context, hqUserID, hash string) (int64, error) {
+	res, err := db.Control("users").UpdateMany(ctx,
+		bson.M{"hq_user_id": hqUserID},
+		bson.M{"$set": bson.M{"password_hash": hash}})
+	if err != nil {
+		return 0, err
+	}
+	return res.ModifiedCount, nil
+}
+
+// ProjectedUsers returns every control-plane row projected from one HQ person.
+// hqsync uses it to compare hashes.
+func ProjectedUsers(ctx context.Context, hqUserID string) ([]sharedmodels.User, error) {
+	cur, err := db.Control("users").Find(ctx, bson.M{"hq_user_id": hqUserID})
+	if err != nil {
+		return nil, err
+	}
+	var users []sharedmodels.User
+	if err := cur.All(ctx, &users); err != nil {
+		return nil, err
+	}
+	return users, nil
+}

admin/internal/config/config.go

@@ -0,0 +1,133 @@
+// Package config parses and validates admin's environment.
+//
+// Everything required is checked at boot and the process refuses to start
+// without it. A licensing service that cannot sign is worse than one that is
+// down, because it looks healthy.
+package config
+
+import (
+	"fmt"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+type Config struct {
+	AdminMongoURI   string
+	AdminDBName     string
+	ControlMongoURI string
+	ControlDBName   string
+	RedisAddr       string
+	RedisUsername   string
+	RedisPassword   string
+	SigningKey      string
+	PublicURL       string
+	AppLoginURL     string
+	AllowedOrigins  []string
+	TrustProxy      bool
+	Addr            string
+	ReapAfter       time.Duration
+
+	SMTPHost     string
+	SMTPPort     string
+	SMTPFrom     string
+	SMTPUsername string
+	SMTPPassword string
+}
+
+// dbNameFromURI reads the database from a Mongo URI path.
+//
+// Both URIs must name their database inline rather than through a separate
+// variable. Admin talks to two databases; a bare MONGO_DB would be ambiguous
+// about which, and guessing wrong means writing licence fields into the wrong
+// place.
+func dbNameFromURI(raw, which string) (string, error) {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return "", fmt.Errorf("%s is not a valid URI: %w", which, err)
+	}
+	name := strings.TrimPrefix(u.Path, "/")
+	if name == "" {
+		return "", fmt.Errorf("%s must name a database in its path, e.g. mongodb://host:27017/vantage_admin", which)
+	}
+	return name, nil
+}
+
+func Load() (Config, error) {
+	c := Config{
+		AdminMongoURI:   os.Getenv("ADMIN_MONGO_URI"),
+		ControlMongoURI: os.Getenv("CONTROL_MONGO_URI"),
+		RedisAddr:       os.Getenv("REDIS_ADDR"),
+		// Optional: an unauthenticated Redis needs neither. Redis 6+ ACL auth
+		// takes both; a legacy `requirepass` instance takes the password alone
+		// and must leave the username empty.
+		RedisUsername: os.Getenv("REDIS_USERNAME"),
+		RedisPassword: os.Getenv("REDIS_PASSWORD"),
+		SigningKey:    os.Getenv("LICENSE_SIGNING_KEY"),
+		PublicURL:     strings.TrimSuffix(os.Getenv("PUBLIC_URL"), "/"),
+		AppLoginURL:   os.Getenv("APP_LOGIN_URL"),
+		TrustProxy:    strings.EqualFold(os.Getenv("TRUST_PROXY"), "true"),
+		Addr:          ":" + envOr("PORT", "8083"),
+
+		SMTPHost:     os.Getenv("SMTP_HOST"),
+		SMTPPort:     envOr("SMTP_PORT", "587"),
+		SMTPFrom:     os.Getenv("SMTP_FROM"),
+		SMTPUsername: os.Getenv("SMTP_USERNAME"),
+		SMTPPassword: os.Getenv("SMTP_PASSWORD"),
+	}
+
+	var missing []string
+	for name, v := range map[string]string{
+		"ADMIN_MONGO_URI":     c.AdminMongoURI,
+		"CONTROL_MONGO_URI":   c.ControlMongoURI,
+		"REDIS_ADDR":          c.RedisAddr,
+		"LICENSE_SIGNING_KEY": c.SigningKey,
+		"PUBLIC_URL":          c.PublicURL,
+		"ADMIN_ORIGIN":        os.Getenv("ADMIN_ORIGIN"),
+	} {
+		if v == "" {
+			missing = append(missing, name)
+		}
+	}
+	if len(missing) > 0 {
+		return Config{}, fmt.Errorf("missing required environment: %s", strings.Join(missing, ", "))
+	}
+
+	var err error
+	if c.AdminDBName, err = dbNameFromURI(c.AdminMongoURI, "ADMIN_MONGO_URI"); err != nil {
+		return Config{}, err
+	}
+	if c.ControlDBName, err = dbNameFromURI(c.ControlMongoURI, "CONTROL_MONGO_URI"); err != nil {
+		return Config{}, err
+	}
+	if c.AdminMongoURI == c.ControlMongoURI {
+		return Config{}, fmt.Errorf("ADMIN_MONGO_URI and CONTROL_MONGO_URI must not be the same database")
+	}
+
+	for _, o := range strings.Split(os.Getenv("ADMIN_ORIGIN"), ",") {
+		if o = strings.TrimSpace(o); o != "" {
+			c.AllowedOrigins = append(c.AllowedOrigins, o)
+		}
+	}
+
+	// Mirrors the control plane's FREE_INSTANCE_REAP_AFTER so notice emails can
+	// name the real deletion date. An unparseable value is refused rather than
+	// silently treated as "off": a typo here would quietly stop every deletion
+	// warning while the control plane still deletes.
+	if v := os.Getenv("FREE_INSTANCE_REAP_AFTER"); v != "" {
+		d, err := time.ParseDuration(v)
+		if err != nil {
+			return Config{}, fmt.Errorf("FREE_INSTANCE_REAP_AFTER %q: %w", v, err)
+		}
+		c.ReapAfter = d
+	}
+	return c, nil
+}
+
+func envOr(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}

admin/internal/db/db.go

@@ -0,0 +1,142 @@
+// Package db holds admin's two MongoDB connections.
+//
+// Admin() is its own database and it owns every collection there. Control() is
+// the control plane's database. Admin's access to it is narrow and lives in
+// exactly two packages: inject writes three licence fields on `instances`, and
+// cloudprov creates and rolls back `instances` and `users` when a customer
+// provisions a cloud instance. Nothing else may write there, and a third write
+// path is a design change rather than a refactor.
+package db
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/mrhid6/vantage/admin/internal/config"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+var (
+	adminDB   *mongo.Database
+	controlDB *mongo.Database
+)
+
+func Connect(ctx context.Context, cfg config.Config) error {
+	ac, err := mongo.Connect(options.Client().ApplyURI(cfg.AdminMongoURI))
+	if err != nil {
+		return fmt.Errorf("connect admin mongo: %w", err)
+	}
+	if err := ac.Ping(ctx, nil); err != nil {
+		return fmt.Errorf("ping admin mongo: %w", err)
+	}
+	adminDB = ac.Database(cfg.AdminDBName)
+
+	cc, err := mongo.Connect(options.Client().ApplyURI(cfg.ControlMongoURI))
+	if err != nil {
+		return fmt.Errorf("connect control mongo: %w", err)
+	}
+	if err := cc.Ping(ctx, nil); err != nil {
+		return fmt.Errorf("ping control mongo: %w", err)
+	}
+	controlDB = cc.Database(cfg.ControlDBName)
+
+	// The control plane must already be deployed and migrated. Without the
+	// instances collection, injection would silently create it and write
+	// licence fields into a collection nothing reads.
+	names, err := controlDB.ListCollectionNames(ctx, map[string]any{"name": "instances"})
+	if err != nil {
+		return fmt.Errorf("inspect control database: %w", err)
+	}
+	if len(names) == 0 {
+		return fmt.Errorf("control database %q has no instances collection; deploy and migrate the control plane first", cfg.ControlDBName)
+	}
+	return nil
+}
+
+func Admin(name string) *mongo.Collection   { return adminDB.Collection(name) }
+func Control(name string) *mongo.Collection { return controlDB.Collection(name) }
+
+// ControlDB exposes the control-plane database itself, because shared/provision
+// takes a database rather than a collection.
+//
+// It is used by cloudprov and nothing else. Reach for Control(name) unless you
+// are calling into shared/provision.
+func ControlDB() *mongo.Database { return controlDB }
+
+func Ctx() (context.Context, context.CancelFunc) {
+	return context.WithTimeout(context.Background(), 10*time.Second)
+}
+
+// EnsureIndexes creates admin's unique indexes.
+//
+// These are a correctness property, not an optimisation. In particular
+// admin_instances.instance_id unique is what stops the same self-hosted UUID
+// being linked to two accounts — without it, two customers could both claim one
+// instance and both be issued licences for it.
+func EnsureIndexes(ctx context.Context) error {
+	unique := []struct {
+		coll  string
+		field string
+	}{
+		{"accounts", "account_id"},
+		{"admin_instances", "instance_id"},
+		{"licenses", "license_id"},
+		{"plans", "tier"},
+		{"staff_users", "email"},
+		{"customer_users", "email"},
+	}
+	for _, u := range unique {
+		if _, err := Admin(u.coll).Indexes().CreateOne(ctx, mongo.IndexModel{
+			Keys:    bson.D{{Key: u.field, Value: 1}},
+			Options: options.Index().SetUnique(true).SetName(u.field + "_unique"),
+		}); err != nil {
+			return fmt.Errorf("index %s.%s: %w", u.coll, u.field, err)
+		}
+	}
+
+	// Sparse: a subscription exists before Paddle assigns an ID, so empty must
+	// not collide with empty.
+	if _, err := Admin("subscriptions").Indexes().CreateOne(ctx, mongo.IndexModel{
+		Keys:    bson.D{{Key: "paddle_subscription_id", Value: 1}},
+		Options: options.Index().SetUnique(true).SetSparse(true).SetName("paddle_subscription_id_unique"),
+	}); err != nil {
+		return fmt.Errorf("index subscriptions.paddle_subscription_id: %w", err)
+	}
+
+	for _, idx := range []struct {
+		coll string
+		keys bson.D
+	}{
+		{"licenses", bson.D{{Key: "instance_id", Value: 1}, {Key: "issued_at", Value: -1}}},
+		{"admin_instances", bson.D{{Key: "account_id", Value: 1}}},
+		{"admin_audit", bson.D{{Key: "created_at", Value: -1}}},
+	} {
+		if _, err := Admin(idx.coll).Indexes().CreateOne(ctx, mongo.IndexModel{Keys: idx.keys}); err != nil {
+			return fmt.Errorf("index %s: %w", idx.coll, err)
+		}
+	}
+
+	// One person holds at most one user in one instance. This is the property
+	// that makes a grant idempotent-by-refusal rather than silently doubling a
+	// projection, and it mirrors users' own (instance_id, email) uniqueness.
+	if _, err := Admin("instance_members").Indexes().CreateOne(ctx, mongo.IndexModel{
+		Keys: bson.D{{Key: "instance_id", Value: 1}, {Key: "customer_user_id", Value: 1}},
+		Options: options.Index().SetUnique(true).
+			SetName("instance_customer_user_unique"),
+	}); err != nil {
+		return fmt.Errorf("index instance_members.(instance_id,customer_user_id): %w", err)
+	}
+	for _, keys := range []bson.D{
+		{{Key: "account_id", Value: 1}},
+		{{Key: "customer_user_id", Value: 1}},
+	} {
+		if _, err := Admin("instance_members").Indexes().CreateOne(ctx,
+			mongo.IndexModel{Keys: keys}); err != nil {
+			return fmt.Errorf("index instance_members: %w", err)
+		}
+	}
+	return nil
+}

admin/internal/hqsync/hqsync.go

@@ -0,0 +1,116 @@
+// Package hqsync keeps projected control-plane users consistent with the HQ
+// people they were projected from.
+//
+// It is separate from inject on purpose. inject writes exactly three licence
+// fields on `instances` and that narrowness is the reason admin's reach into
+// the control plane is reviewable at all; a password repair pass bolted onto it
+// would quietly turn it into "the package that writes whatever admin wants".
+// This one goes through cloudprov, which is the sanctioned user write path.
+package hqsync
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/mrhid6/vantage/admin/internal/cloudprov"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// Interval matches inject's reconciler. Fifteen minutes is the worst-case
+// staleness a password change can suffer, which the spec accepts as
+// recoverable.
+const Interval = 15 * time.Minute
+
+// Reconcile compares every projected user's stored hash against the HQ hash it
+// came from, and repairs mismatches.
+//
+// The comparison is on the hash string, not the password: two bcrypt hashes of
+// one password differ by salt, so this repairs by COPYING HQ's hash rather than
+// re-hashing. That is also why propagation copies rather than re-derives.
+func Reconcile(ctx context.Context) (checked, repaired int, err error) {
+	cur, err := db.Admin("customer_users").Find(ctx,
+		bson.M{"password_hash": bson.M{"$nin": bson.A{nil, ""}}})
+	if err != nil {
+		return 0, 0, err
+	}
+	var people []models.CustomerUser
+	if err := cur.All(ctx, &people); err != nil {
+		return 0, 0, err
+	}
+
+	for _, p := range people {
+		projected, err := cloudprov.ProjectedUsers(ctx, p.UserID)
+		if err != nil {
+			log.Printf("hqsync: read projections of %s: %v", p.Email, err)
+			continue
+		}
+		stale := false
+		for _, u := range projected {
+			checked++
+			if u.PasswordHash != p.PasswordHash {
+				stale = true
+			}
+		}
+		if !stale {
+			// Clear a stale failure flag: the instances agree, whatever the
+			// flag says. Nothing reads the flag to decide what to repair.
+			if p.HQSyncFailedAt != nil {
+				_, _ = db.Admin("customer_users").UpdateOne(ctx,
+					bson.M{"user_id": p.UserID},
+					bson.M{"$unset": bson.M{"hq_sync_failed_at": ""}})
+			}
+			continue
+		}
+
+		n, err := cloudprov.SetPasswordHash(ctx, p.UserID, p.PasswordHash)
+		if err != nil {
+			log.Printf("hqsync: repair %s: %v", p.Email, err)
+			continue
+		}
+		repaired += int(n)
+		log.Printf("hqsync: repaired %d projected user(s) for %s", n, p.Email)
+		_, _ = db.Admin("customer_users").UpdateOne(ctx,
+			bson.M{"user_id": p.UserID},
+			bson.M{"$unset": bson.M{"hq_sync_failed_at": ""}})
+	}
+	return checked, repaired, nil
+}
+
+// Start runs once at boot, then on a ticker until ctx is cancelled.
+//
+// The boot pass is for the same reason inject's is: the likeliest moment for a
+// half-applied write is a deploy or a crash, and waiting a full interval to
+// notice means a customer's new password does not work somewhere for fifteen
+// minutes after we already know how to fix it.
+func Start(ctx context.Context) {
+	go func() {
+		runOnce(ctx)
+		t := time.NewTicker(Interval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				runOnce(ctx)
+			}
+		}
+	}()
+}
+
+func runOnce(ctx context.Context) {
+	runCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+	defer cancel()
+
+	checked, repaired, err := Reconcile(runCtx)
+	if err != nil {
+		log.Printf("hqsync: %v", err)
+		return
+	}
+	if repaired > 0 {
+		log.Printf("hqsync: checked %d projected user(s), repaired %d", checked, repaired)
+	}
+}

admin/internal/inject/inject.go

@@ -0,0 +1,178 @@
+// Package inject writes licences onto control-plane instance documents.
+//
+// This is admin's ONLY write path into the control plane, and it touches exactly
+// three fields on one collection. If this package ever grows a second write
+// target, that is a design change and not a refactor.
+package inject
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"time"
+
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+	sharedmodels "github.com/mrhid6/vantage/shared/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+// ReconcileInterval is how often every cloud instance is compared against what
+// admin believes it should hold.
+//
+// This job, not the issuance path, is what guarantees eventual consistency.
+// Injection at issue time is best-effort; this is the backstop.
+const ReconcileInterval = 15 * time.Minute
+
+// Cloud writes the licence onto the control-plane instance document.
+//
+// Idempotent and safe to re-run: it is a single UpdateOne of three fields with
+// no read-modify-write. Retries three times with backoff.
+//
+// The control plane caches licence state for 60 seconds, so this takes effect
+// within a minute with no restart.
+func Cloud(ctx context.Context, lic *models.License) error {
+	set := bson.M{"$set": bson.M{
+		"license_blob":   lic.Blob,
+		"license_tier":   lic.Tier,
+		"license_expiry": lic.ExpiresAt,
+	}}
+
+	var lastErr error
+	for attempt := 1; attempt <= 3; attempt++ {
+		res, err := db.Control("instances").UpdateOne(ctx,
+			bson.M{"instance_id": lic.InstanceID}, set)
+		if err == nil {
+			if res.MatchedCount == 0 {
+				return fmt.Errorf("no control-plane instance %s", lic.InstanceID)
+			}
+			return nil
+		}
+		lastErr = err
+		time.Sleep(time.Duration(attempt) * 2 * time.Second)
+	}
+	return fmt.Errorf("inject after 3 attempts: %w", lastErr)
+}
+
+// Deliver injects and records the outcome without ever failing the caller.
+//
+// A licence that is recorded but not injected is recoverable — the reconciler
+// will fix it within 15 minutes, and staff can see it on the health endpoint.
+// Failing the purchase because one write failed would be worse.
+func Deliver(ctx context.Context, lic *models.License) {
+	if err := Cloud(ctx, lic); err != nil {
+		log.Printf("INJECTION FAILED instance=%s licence=%s: %v", lic.InstanceID, lic.LicenseID, err)
+		now := time.Now().UTC()
+		_, _ = db.Admin("admin_instances").UpdateOne(ctx,
+			bson.M{"instance_id": lic.InstanceID},
+			bson.M{"$set": bson.M{"inject_failed_at": now}})
+		return
+	}
+	_, _ = db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": lic.InstanceID},
+		bson.M{"$unset": bson.M{"inject_failed_at": ""}})
+}
+
+// Reconcile compares every active cloud instance's current licence against the
+// blob actually stored in the control plane, and re-injects on mismatch.
+func Reconcile(ctx context.Context) (checked, repaired int, err error) {
+	cur, err := db.Admin("admin_instances").Find(ctx, bson.M{
+		"deployment":      license.DeploymentCloud,
+		"status":          models.StatusActive,
+		"current_license": bson.M{"$ne": ""},
+	})
+	if err != nil {
+		return 0, 0, err
+	}
+	var instances []models.Instance
+	if err := cur.All(ctx, &instances); err != nil {
+		return 0, 0, err
+	}
+
+	for _, inst := range instances {
+		checked++
+
+		var lic models.License
+		if err := db.Admin("licenses").FindOne(ctx,
+			bson.M{"license_id": inst.CurrentLicense}).Decode(&lic); err != nil {
+			log.Printf("reconcile: instance %s references unknown licence %s", inst.InstanceID, inst.CurrentLicense)
+			continue
+		}
+
+		var remote sharedmodels.Instance
+		if err := db.Control("instances").FindOne(ctx,
+			bson.M{"instance_id": inst.InstanceID}).Decode(&remote); err != nil {
+			// The control plane's reaper deletes lapsed Free instances. Record
+			// that here rather than re-logging it every fifteen minutes forever,
+			// and so the lifecycle sweep stops emailing about it.
+			if errors.Is(err, mongo.ErrNoDocuments) {
+				if _, uErr := db.Admin("admin_instances").UpdateOne(ctx,
+					bson.M{"instance_id": inst.InstanceID},
+					bson.M{"$set": bson.M{"status": models.StatusDeleted}}); uErr != nil {
+					log.Printf("reconcile: mark %s deleted: %v", inst.InstanceID, uErr)
+				} else {
+					log.Printf("reconcile: instance %s is gone from the control plane; marked deleted", inst.InstanceID)
+				}
+				continue
+			}
+			log.Printf("reconcile: no control-plane instance %s: %v", inst.InstanceID, err)
+			continue
+		}
+
+		if remote.LicenseBlob == lic.Blob {
+			continue
+		}
+
+		log.Printf("reconcile: repairing instance %s (licence %s)", inst.InstanceID, lic.LicenseID)
+		if err := Cloud(ctx, &lic); err != nil {
+			log.Printf("reconcile: repair failed for %s: %v", inst.InstanceID, err)
+			continue
+		}
+		repaired++
+		_, _ = db.Admin("admin_instances").UpdateOne(ctx,
+			bson.M{"instance_id": inst.InstanceID},
+			bson.M{"$unset": bson.M{"inject_failed_at": ""}})
+	}
+	return checked, repaired, nil
+}
+
+// StartReconciler reconciles once at boot, then on a ticker until ctx is
+// cancelled.
+//
+// The pass at boot matters: injection failures are most likely around a deploy
+// or a crash, and waiting a full interval to notice would leave a paying
+// customer read-only for that long. It also means a restart is a supported way
+// to force reconciliation.
+func StartReconciler(ctx context.Context) {
+	go func() {
+		runOnce(ctx)
+
+		t := time.NewTicker(ReconcileInterval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				runOnce(ctx)
+			}
+		}
+	}()
+}
+
+func runOnce(ctx context.Context) {
+	runCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+	defer cancel()
+
+	checked, repaired, err := Reconcile(runCtx)
+	if err != nil {
+		log.Printf("reconcile: %v", err)
+		return
+	}
+	if repaired > 0 {
+		log.Printf("reconcile: checked %d, repaired %d", checked, repaired)
+	}
+}

admin/internal/licensing/issue.go

@@ -0,0 +1,178 @@
+// Package licensing issues licences. It is the only place that signs.
+package licensing
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+var (
+	ErrUnknownTier        = errors.New("unknown tier")
+	ErrDeploymentMismatch = errors.New("that plan is not available for this deployment type")
+	ErrFreeLimit          = errors.New("this account already has a Free instance")
+	ErrUnknownInstance    = errors.New("instance not found")
+)
+
+type IssueInput struct {
+	InstanceID string
+	Tier       string
+	Term       string    // "monthly" or "annual"; ignored when ExpiresAt is set
+	ExpiresAt  time.Time // explicit expiry, used by relink to preserve the remaining term
+	Reason     string
+	IssuedBy   string // staff email, "system", or "paddle:<event id>"
+}
+
+// signingKey is set once at boot from LICENSE_SIGNING_KEY.
+var signingKey string
+
+func SetSigningKey(k string) { signingKey = k }
+
+// Issue signs a licence, records it, supersedes its predecessor and updates the
+// instance.
+//
+// It does NOT deliver. Recording and delivery are deliberately separate and
+// ordered: a licence recorded but not delivered is recoverable, because the
+// customer can download it. A licence delivered but not recorded is a support
+// mystery with no paper trail. Callers deliver after this returns.
+func Issue(ctx context.Context, in IssueInput) (*models.License, error) {
+	if signingKey == "" {
+		return nil, errors.New("no signing key configured")
+	}
+
+	var inst models.Instance
+	if err := db.Admin("admin_instances").FindOne(ctx,
+		bson.M{"instance_id": in.InstanceID}).Decode(&inst); err != nil {
+		return nil, ErrUnknownInstance
+	}
+
+	plan, err := models.GetPlan(ctx, in.Tier)
+	if err != nil {
+		return nil, ErrUnknownTier
+	}
+
+	// This single comparison is what makes Free cloud-only. Free's plan is
+	// deployment "cloud", so it can never be issued against a self-hosted
+	// instance, and verification on the instance would reject it anyway.
+	if plan.Deployment != inst.Deployment {
+		return nil, fmt.Errorf("%w: %s is %s only", ErrDeploymentMismatch, plan.Name, plan.Deployment)
+	}
+
+	if plan.Tier == license.TierFree {
+		if err := checkFreeLimit(ctx, inst.AccountID, inst.InstanceID); err != nil {
+			return nil, err
+		}
+	}
+
+	now := time.Now().UTC()
+	expires := in.ExpiresAt
+	if expires.IsZero() {
+		switch in.Term {
+		case "monthly":
+			expires = now.AddDate(0, 1, 0).Add(models.GracePeriod)
+		case "annual", "":
+			expires = now.AddDate(1, 0, 0).Add(models.GracePeriod)
+		default:
+			return nil, fmt.Errorf("unknown term %q", in.Term)
+		}
+	}
+
+	payload := license.License{
+		ID:           uuid.NewString(),
+		InstanceID:   inst.InstanceID,
+		AccountID:    inst.AccountID,
+		InstanceName: inst.Name,
+		Tier:         plan.Tier,
+		Deployment:   plan.Deployment,
+		IssuedAt:     now,
+		ExpiresAt:    expires,
+		// Snapshotted, not referenced: editing a plan tomorrow must not change
+		// what this licence grants.
+		Limits:   plan.Limits,
+		Features: plan.Features,
+	}
+
+	blob, err := license.Sign(payload, signingKey)
+	if err != nil {
+		return nil, fmt.Errorf("sign: %w", err)
+	}
+
+	rec := models.License{
+		LicenseID:  payload.ID,
+		InstanceID: inst.InstanceID,
+		AccountID:  inst.AccountID,
+		Tier:       plan.Tier,
+		Deployment: plan.Deployment,
+		Limits:     plan.Limits,
+		Features:   plan.Features,
+		IssuedAt:   now,
+		ExpiresAt:  expires,
+		Blob:       blob,
+		IssuedBy:   in.IssuedBy,
+		Reason:     in.Reason,
+	}
+	if _, err := db.Admin("licenses").InsertOne(ctx, rec); err != nil {
+		return nil, fmt.Errorf("record licence: %w", err)
+	}
+
+	// Supersede rather than delete. The history is the support tool.
+	if inst.CurrentLicense != "" {
+		if _, err := db.Admin("licenses").UpdateOne(ctx,
+			bson.M{"license_id": inst.CurrentLicense},
+			bson.M{"$set": bson.M{"superseded_by": rec.LicenseID}}); err != nil {
+			return nil, fmt.Errorf("supersede previous licence: %w", err)
+		}
+	}
+
+	set := bson.M{
+		"current_license": rec.LicenseID,
+		"tier":            plan.Tier,
+		"status":          models.StatusActive,
+	}
+	if in.Reason == models.ReasonRenewal {
+		set["relink_count"] = 0 // the cap is per term
+	}
+	if _, err := db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": inst.InstanceID}, bson.M{"$set": set}); err != nil {
+		return nil, fmt.Errorf("update instance: %w", err)
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor:     in.IssuedBy,
+		Action:    "license.issued",
+		AccountID: inst.AccountID,
+		Target:    inst.InstanceID,
+		Detail: fmt.Sprintf("tier=%s reason=%s expires=%s licence=%s",
+			plan.Tier, in.Reason, expires.Format(time.RFC3339), rec.LicenseID),
+	})
+
+	return &rec, nil
+}
+
+// checkFreeLimit enforces one Free instance per account.
+//
+// Cancelled instances do not count: a customer who cancelled their Free instance
+// is allowed another one.
+func checkFreeLimit(ctx context.Context, accountID, exceptInstanceID string) error {
+	n, err := db.Admin("admin_instances").CountDocuments(ctx, bson.M{
+		"account_id":  accountID,
+		"tier":        license.TierFree,
+		"status":      bson.M{"$ne": models.StatusCancelled},
+		"instance_id": bson.M{"$ne": exceptInstanceID},
+	})
+	if err != nil {
+		return err
+	}
+	if n > 0 {
+		return ErrFreeLimit
+	}
+	return nil
+}

admin/internal/licensing/link.go

@@ -0,0 +1,121 @@
+package licensing
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+var (
+	ErrBadUUID       = errors.New("that does not look like an instance ID")
+	ErrAlreadyLinked = errors.New("that instance ID is already linked to an account")
+	ErrRelinkLimit   = errors.New("relink limit reached for this term; contact support")
+)
+
+// LinkInstance attaches a self-hosted instance UUID to an account.
+//
+// The duplicate error deliberately does not say WHICH account holds it. It is a
+// small enumeration surface, but there is no reason to leave it open.
+func LinkInstance(ctx context.Context, accountID, instanceID, name string) (*models.Instance, error) {
+	if _, err := uuid.Parse(instanceID); err != nil {
+		return nil, ErrBadUUID
+	}
+
+	// A self-hosted UUID must not collide with a cloud instance either.
+	if n, err := db.Control("instances").CountDocuments(ctx, bson.M{"instance_id": instanceID}); err == nil && n > 0 {
+		return nil, ErrAlreadyLinked
+	}
+
+	inst := models.Instance{
+		InstanceID: instanceID,
+		AccountID:  accountID,
+		Name:       name,
+		Deployment: license.DeploymentSelfHosted,
+		Status:     models.StatusActive,
+		CreatedAt:  time.Now().UTC(),
+	}
+	if _, err := db.Admin("admin_instances").InsertOne(ctx, inst); err != nil {
+		if mongo.IsDuplicateKeyError(err) {
+			// The unique index is what actually prevents two accounts owning
+			// one instance. The check above is a nicety; this is the guarantee.
+			return nil, ErrAlreadyLinked
+		}
+		return nil, err
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor: accountID, Action: "instance.linked", AccountID: accountID, Target: instanceID})
+	return &inst, nil
+}
+
+// Relink moves a licence to a rebuilt server's new UUID.
+//
+// The replacement covers the REMAINING term, not a fresh one — relinking is not
+// a way to extend a subscription.
+//
+// The old licence is not revoked, because offline verification has no
+// revocation. It simply no longer matches any UUID the customer controls, and
+// its binding stops it working on another machine anyway.
+func Relink(ctx context.Context, accountID, oldID, newID string, staff bool) (*models.License, error) {
+	if _, err := uuid.Parse(newID); err != nil {
+		return nil, ErrBadUUID
+	}
+
+	var inst models.Instance
+	if err := db.Admin("admin_instances").FindOne(ctx,
+		bson.M{"instance_id": oldID, "account_id": accountID}).Decode(&inst); err != nil {
+		return nil, ErrUnknownInstance
+	}
+
+	// The cap is a signal, not a defence. Its job is to put a human in front of
+	// the fourth attempt, so staff bypass it.
+	if !staff && inst.RelinkCount >= models.MaxRelinksPerTerm {
+		return nil, ErrRelinkLimit
+	}
+
+	if n, err := db.Admin("admin_instances").CountDocuments(ctx, bson.M{"instance_id": newID}); err == nil && n > 0 {
+		return nil, ErrAlreadyLinked
+	}
+
+	// Preserve the remaining term from the current licence.
+	remaining := time.Now().UTC().Add(models.GracePeriod)
+	var current models.License
+	if err := db.Admin("licenses").FindOne(ctx,
+		bson.M{"license_id": inst.CurrentLicense}).Decode(&current); err == nil {
+		remaining = current.ExpiresAt
+	}
+
+	if _, err := db.Admin("admin_instances").UpdateOne(ctx,
+		bson.M{"instance_id": oldID},
+		bson.M{"$set": bson.M{"instance_id": newID}, "$inc": bson.M{"relink_count": 1}}); err != nil {
+		if mongo.IsDuplicateKeyError(err) {
+			return nil, ErrAlreadyLinked
+		}
+		return nil, fmt.Errorf("relink: %w", err)
+	}
+
+	actor := accountID
+	if staff {
+		actor = "staff"
+	}
+	audit.Write(ctx, models.AuditEntry{
+		Actor: actor, Action: "instance.relinked", AccountID: accountID,
+		Target: newID, Detail: "was " + oldID})
+
+	return Issue(ctx, IssueInput{
+		InstanceID: newID,
+		Tier:       inst.Tier,
+		ExpiresAt:  remaining,
+		Reason:     models.ReasonRelink,
+		IssuedBy:   actor,
+	})
+}

admin/internal/lifecycle/lifecycle.go

@@ -0,0 +1,175 @@
+// Package lifecycle marks lapsed Free instances and sends the renewal notices.
+//
+// It sends; it never deletes. Deletion belongs to the control plane, which is
+// the only service that knows what an instance is made of. The two are kept
+// apart on purpose: a bug here sends a wrong email, a bug there loses data.
+package lifecycle
+
+import (
+	"context"
+	"log"
+	"slices"
+	"time"
+
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/mail"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// Interval is how often the sweep runs. Hourly is far finer than the daily
+// granularity of the notices, which means a notice goes out within an hour of
+// becoming due rather than up to a day late.
+const Interval = time.Hour
+
+// Notice keys, recorded on the instance so a restart cannot re-send one.
+const (
+	noticeExpiring = "expiring"
+	noticeExpired  = "expired"
+	noticeDelete7  = "delete_7"
+	noticeDelete1  = "delete_1"
+)
+
+// portalURL is the customer portal address used in notice emails.
+var portalURL string
+
+// SetPortalURL is called once at boot.
+func SetPortalURL(v string) { portalURL = v }
+
+// reapAfter mirrors the control plane's FREE_INSTANCE_REAP_AFTER so the emails
+// can name the real deletion date. Zero means the reaper is off, and the
+// deletion notices are then suppressed — promising a deletion that will never
+// happen would be a lie, and a scarier one than saying nothing.
+var reapAfter time.Duration
+
+// Run performs one sweep: mark lapsed instances, then send whatever notices are
+// due. Errors on one instance never stop the others.
+func Run(ctx context.Context) error {
+	now := time.Now().UTC()
+
+	cur, err := db.Admin("admin_instances").Find(ctx, bson.M{
+		"deployment": license.DeploymentCloud,
+		"tier":       license.TierFree,
+		"status":     bson.M{"$in": []string{models.StatusActive, models.StatusLapsed}},
+	})
+	if err != nil {
+		return err
+	}
+	var instances []models.Instance
+	if err := cur.All(ctx, &instances); err != nil {
+		return err
+	}
+
+	for _, inst := range instances {
+		var lic models.License
+		if err := db.Admin("licenses").FindOne(ctx,
+			bson.M{"license_id": inst.CurrentLicense}).Decode(&lic); err != nil {
+			continue // no licence yet; nothing to expire
+		}
+
+		// Flip active -> lapsed once the licence is past its expiry.
+		if now.After(lic.ExpiresAt) && inst.Status == models.StatusActive {
+			if _, err := db.Admin("admin_instances").UpdateOne(ctx,
+				bson.M{"instance_id": inst.InstanceID},
+				bson.M{"$set": bson.M{"status": models.StatusLapsed}}); err != nil {
+				log.Printf("lifecycle: mark %s lapsed: %v", inst.InstanceID, err)
+			}
+		}
+
+		due := dueNotice(now, lic.ExpiresAt, inst.NoticesSent)
+		if due == "" {
+			continue
+		}
+		if err := sendNotice(ctx, inst, lic, due); err != nil {
+			log.Printf("lifecycle: notice %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 notice %s for %s: %v", due, inst.InstanceID, err)
+		}
+	}
+	return nil
+}
+
+// dueNotice returns the most urgent unsent notice, or "".
+//
+// Most urgent first, so an instance that was missed for a week — because admin
+// was down — sends the one that matters now rather than working through a
+// backlog of stale warnings.
+func dueNotice(now, expires time.Time, sent []string) string {
+	deleteOn := expires.Add(reapAfter)
+
+	if reapAfter > 0 {
+		if now.After(deleteOn.Add(-24*time.Hour)) && !slices.Contains(sent, noticeDelete1) {
+			return noticeDelete1
+		}
+		if now.After(deleteOn.Add(-7*24*time.Hour)) && !slices.Contains(sent, noticeDelete7) {
+			return noticeDelete7
+		}
+	}
+	if now.After(expires) && !slices.Contains(sent, noticeExpired) {
+		return noticeExpired
+	}
+	if now.After(expires.Add(-models.RenewWindow)) && !slices.Contains(sent, noticeExpiring) {
+		return noticeExpiring
+	}
+	return ""
+}
+
+func sendNotice(ctx context.Context, inst models.Instance, lic models.License, key string) error {
+	if !mail.Enabled() {
+		return nil
+	}
+	var acct models.Account
+	if err := db.Admin("accounts").FindOne(ctx,
+		bson.M{"account_id": inst.AccountID}).Decode(&acct); err != nil {
+		return err
+	}
+	to := acct.BillingEmail
+	deleteOn := lic.ExpiresAt.Add(reapAfter)
+
+	switch key {
+	case noticeExpiring:
+		return mail.SendExpiring(to, inst.Name, portalURL, lic.ExpiresAt)
+	case noticeExpired:
+		return mail.SendExpired(to, inst.Name, portalURL, deleteOn)
+	case noticeDelete7:
+		return mail.SendDeletionWarning(to, inst.Name, portalURL, deleteOn, 7)
+	case noticeDelete1:
+		return mail.SendDeletionWarning(to, inst.Name, portalURL, deleteOn, 1)
+	}
+	return nil
+}
+
+// Start runs the sweep on a ticker until ctx is cancelled.
+//
+// reapAfterDur must match the control plane's FREE_INSTANCE_REAP_AFTER. If they
+// disagree, the emails name a date the reaper does not honour — so they are
+// documented as a pair in CLAUDE.md and set together in the compose file.
+func Start(ctx context.Context, reapAfterDur time.Duration) {
+	reapAfter = reapAfterDur
+	go func() {
+		runOnce(ctx)
+		t := time.NewTicker(Interval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				runOnce(ctx)
+			}
+		}
+	}()
+}
+
+func runOnce(ctx context.Context) {
+	runCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+	defer cancel()
+	if err := Run(runCtx); err != nil {
+		log.Printf("lifecycle: %v", err)
+	}
+}

admin/internal/mail/mail.go

@@ -0,0 +1,226 @@
+// Package mail delivers verification links and licence files.
+package mail
+
+import (
+	"crypto/rand"
+	"crypto/tls"
+	"encoding/hex"
+	"fmt"
+	"mime"
+	"net"
+	"net/smtp"
+	"strings"
+	"time"
+)
+
+// timeout bounds the whole SMTP conversation. Without it a mail server that
+// accepts the connection and then stalls holds an HTTP request open until the
+// client gives up — and signup's rollback runs on that request's context.
+const timeout = 15 * time.Second
+
+type Config struct {
+	Host, Port, From, Username, Password string
+	PublicURL                            string
+}
+
+var cfg Config
+
+func Init(c Config) { cfg = c }
+
+func Enabled() bool { return cfg.Host != "" && cfg.From != "" }
+
+// send delivers one message.
+//
+// Port 465 is implicit TLS: the server expects a TLS handshake immediately, so
+// the connection is wrapped BEFORE any SMTP is spoken. Every other port gets
+// plaintext then STARTTLS if offered. `net/smtp.SendMail` only does the latter,
+// which is why it fails against a 465 mail server — this exact bug silently
+// stopped every admin email from being delivered.
+//
+// This mirrors sitesvc/internal/mail, which solved the same problem first. The
+// two are duplicated rather than shared; if you change the transport here,
+// change it there too, or consolidate both into shared/.
+func send(to, subject, body string) error {
+	if !Enabled() {
+		return fmt.Errorf("SMTP is not configured")
+	}
+	if strings.TrimSpace(to) == "" {
+		return fmt.Errorf("smtp: no recipient")
+	}
+
+	addr := net.JoinHostPort(cfg.Host, cfg.Port)
+	conn, err := net.DialTimeout("tcp", addr, timeout)
+	if err != nil {
+		return fmt.Errorf("smtp: dial %s: %w", addr, err)
+	}
+	_ = conn.SetDeadline(time.Now().Add(timeout))
+
+	if cfg.Port == "465" {
+		conn = tls.Client(conn, &tls.Config{ServerName: cfg.Host})
+	}
+
+	client, err := smtp.NewClient(conn, cfg.Host)
+	if err != nil {
+		conn.Close()
+		return fmt.Errorf("smtp: client: %w", err)
+	}
+	defer client.Close()
+
+	if cfg.Port != "465" {
+		if ok, _ := client.Extension("STARTTLS"); ok {
+			if err := client.StartTLS(&tls.Config{ServerName: cfg.Host}); err != nil {
+				return fmt.Errorf("smtp: starttls: %w", err)
+			}
+		}
+	}
+
+	if cfg.Username != "" {
+		if err := client.Auth(smtp.PlainAuth("", cfg.Username, cfg.Password, cfg.Host)); err != nil {
+			return fmt.Errorf("smtp: auth: %w", err)
+		}
+	}
+
+	if err := client.Mail(cfg.From); err != nil {
+		return fmt.Errorf("smtp: mail from: %w", err)
+	}
+	if err := client.Rcpt(to); err != nil {
+		return fmt.Errorf("smtp: rcpt %s: %w", to, err)
+	}
+
+	w, err := client.Data()
+	if err != nil {
+		return fmt.Errorf("smtp: data: %w", err)
+	}
+	if _, err := w.Write(message(to, subject, body)); err != nil {
+		return fmt.Errorf("smtp: write: %w", err)
+	}
+	if err := w.Close(); err != nil {
+		return fmt.Errorf("smtp: close data: %w", err)
+	}
+	return client.Quit()
+}
+
+// message builds the RFC 5322 envelope.
+//
+// Date and Message-ID are not decoration: a message without them is scored as
+// spam by most filters, which is its own way of "the email never arrived".
+// Header values are stripped of CR and LF so a crafted instance name cannot
+// inject extra headers.
+func message(to, subject, body string) []byte {
+	var b strings.Builder
+	b.WriteString("From: " + sanitizeHeader(cfg.From) + "\r\n")
+	b.WriteString("To: " + sanitizeHeader(to) + "\r\n")
+	b.WriteString("Date: " + time.Now().Format(time.RFC1123Z) + "\r\n")
+	b.WriteString("Message-ID: " + messageID(cfg.From) + "\r\n")
+	b.WriteString("Subject: " + mime.QEncoding.Encode("utf-8", sanitizeHeader(subject)) + "\r\n")
+	b.WriteString("MIME-Version: 1.0\r\n")
+	b.WriteString("Content-Type: text/plain; charset=utf-8\r\n")
+	b.WriteString("\r\n")
+	b.WriteString(body)
+	return []byte(b.String())
+}
+
+func messageID(from string) string {
+	domain := "vantage.local"
+	if at := strings.LastIndex(from, "@"); at >= 0 && at < len(from)-1 {
+		domain = strings.Trim(from[at+1:], "<> ")
+	}
+	var buf [16]byte
+	if _, err := rand.Read(buf[:]); err != nil {
+		return fmt.Sprintf("<%d@%s>", time.Now().UnixNano(), domain)
+	}
+	return fmt.Sprintf("<%s@%s>", hex.EncodeToString(buf[:]), domain)
+}
+
+func sanitizeHeader(v string) string {
+	return strings.NewReplacer("\r", " ", "\n", " ").Replace(v)
+}
+
+func SendVerification(to, token string) error {
+	link := fmt.Sprintf("%s/verify?token=%s", cfg.PublicURL, token)
+	return send(to, "Verify your Vantage account",
+		"Confirm your email address to finish setting up your Vantage account:\n\n"+
+			link+"\n\nThis link expires in 24 hours.\n")
+}
+
+// SendInvite asks someone to join an existing account and set their own
+// password. It names the account, because an unexpected invitation from a
+// service you have never used is otherwise indistinguishable from spam.
+func SendInvite(to, accountName, token string) error {
+	link := fmt.Sprintf("%s/accept-invite?token=%s", cfg.PublicURL, token)
+	return send(to, "You have been invited to "+sanitizeHeader(accountName)+" on Vantage",
+		fmt.Sprintf("You have been invited to join %s on Vantage.\n\n"+
+			"Set your password and finish joining:\n\n%s\n\n"+
+			"This link expires in 24 hours. If you were not expecting this, ignore it — "+
+			"nothing happens until you open the link.\n", accountName, link))
+}
+
+// SendLicense delivers the blob inline. It is signed public data, not a secret —
+// it is useless on any instance other than the one it names.
+func SendLicense(to, instanceName, blob string) error {
+	return send(to, "Your Vantage licence key",
+		fmt.Sprintf("Your licence for %s is below.\n\n"+
+			"Paste it into Settings → Licence on your Vantage install:\n\n%s\n",
+			instanceName, blob))
+}
+
+// SendInstanceReady tells a customer their cloud instance exists, where it is,
+// and when its licence runs out.
+//
+// The expiry is stated here rather than only in a later reminder: a Free licence
+// that quietly expires in a month is a surprise, and the first email is the one
+// people keep.
+func SendInstanceReady(to, instanceName, loginURL string, expires time.Time) error {
+	body := fmt.Sprintf("%s is ready.\n\n", instanceName)
+	if loginURL != "" {
+		body += "Sign in here:\n\n" + loginURL + "\n\n"
+	}
+	body += fmt.Sprintf(
+		"Your Free licence runs until %s. We will email you before then so you can renew it in one click.\n\n"+
+			"Sign in with the same email address and password you use for your Vantage account. "+
+			"Changing your Vantage HQ password changes it here too.\n",
+		expires.Format("2 January 2006"))
+	return send(to, instanceName+" is ready", body)
+}
+
+// SendRenewed confirms a renewal and states the new date.
+func SendRenewed(to, instanceName string, expires time.Time) error {
+	return send(to, instanceName+" renewed",
+		fmt.Sprintf("%s is renewed.\n\nYour Free licence now runs until %s.\n",
+			instanceName, expires.Format("2 January 2006")))
+}
+
+// SendExpiring is the renew-now nudge, seven days out.
+func SendExpiring(to, instanceName, portalURL string, expires time.Time) error {
+	return send(to, instanceName+" expires on "+expires.Format("2 January"),
+		fmt.Sprintf("%s's Free licence runs out on %s.\n\n"+
+			"Renew it in one click:\n\n%s\n\n"+
+			"If you do nothing, the instance keeps running but stops accepting changes.\n",
+			instanceName, expires.Format("2 January 2006"), portalURL))
+}
+
+// SendExpired states plainly what has stopped and what happens next.
+//
+// It names the deletion date rather than a vague warning: the whole point of the
+// sequence is that nobody loses an instance without having been told a date.
+func SendExpired(to, instanceName, portalURL string, deleteOn time.Time) error {
+	return send(to, instanceName+" is now read-only",
+		fmt.Sprintf("%s's Free licence has expired.\n\n"+
+			"Your servers and monitors keep running and your agents keep their keys, "+
+			"but changes are disabled.\n\n"+
+			"Renew it here:\n\n%s\n\n"+
+			"If it is not renewed, the instance and everything in it will be deleted on %s.\n",
+			instanceName, portalURL, deleteOn.Format("2 January 2006")))
+}
+
+// SendDeletionWarning is the final countdown, sent at seven days and one day.
+func SendDeletionWarning(to, instanceName, portalURL string, deleteOn time.Time, daysLeft int) error {
+	when := fmt.Sprintf("in %d days", daysLeft)
+	if daysLeft <= 1 {
+		when = "tomorrow"
+	}
+	return send(to, instanceName+" will be deleted "+when,
+		fmt.Sprintf("%s and everything in it will be deleted %s, on %s.\n\n"+
+			"This cannot be undone. Renew it here to keep it:\n\n%s\n",
+			instanceName, when, deleteOn.Format("2 January 2006"), portalURL))
+}

admin/internal/models/backfill.go

@@ -0,0 +1,101 @@
+package models
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/shared/license"
+	sharedmodels "github.com/mrhid6/vantage/shared/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+// Backfill brings pre-phase-3 data up to the membership model.
+//
+// It runs on every boot and is idempotent by construction: both passes filter
+// on the absence of what they write. There is no migrations collection in
+// admin, and adding one for two `$exists: false` queries would be more
+// machinery than the job deserves.
+//
+// It lives in models rather than db for the same reason SeedPlans does: db is
+// the connection layer and importing models there is an import cycle.
+func Backfill(ctx context.Context) error {
+	// Pass 1: every existing customer_user created their own account, so they
+	// are all owners. A row with no account_role would otherwise be able to do
+	// nothing at all once the guards land — including managing the account it
+	// created.
+	res, err := db.Admin("customer_users").UpdateMany(ctx,
+		bson.M{"account_role": bson.M{"$exists": false}},
+		bson.M{"$set": bson.M{"account_role": AccountRoleOwner}})
+	if err != nil {
+		return err
+	}
+	if res.ModifiedCount > 0 {
+		log.Printf("backfill: set account_role=owner on %d customer_users", res.ModifiedCount)
+	}
+
+	// Pass 2: phase 2 created cloud instances and their owners without an
+	// instance_members row, because the collection did not exist. Reconstruct
+	// one per instance from the control-plane owner it actually created.
+	cur, err := db.Admin("admin_instances").Find(ctx, bson.M{
+		"deployment": license.DeploymentCloud,
+		"status":     bson.M{"$ne": StatusDeleted},
+	})
+	if err != nil {
+		return err
+	}
+	var instances []Instance
+	if err := cur.All(ctx, &instances); err != nil {
+		return err
+	}
+
+	created := 0
+	for _, inst := range instances {
+		n, err := db.Admin("instance_members").CountDocuments(ctx,
+			bson.M{"instance_id": inst.InstanceID})
+		if err != nil {
+			return err
+		}
+		if n > 0 {
+			continue
+		}
+
+		// Only an hq-sourced owner can be reconstructed: a control-plane owner
+		// with no hq_user_id was created inside the instance and belongs to
+		// nobody on this side. Leaving it unrecorded is correct.
+		var owner sharedmodels.User
+		err = db.Control("users").FindOne(ctx, bson.M{
+			"instance_id": inst.InstanceID,
+			"role":        sharedmodels.RoleOwner,
+			"hq_user_id":  bson.M{"$nin": bson.A{nil, ""}},
+		}).Decode(&owner)
+		if err != nil {
+			if err != mongo.ErrNoDocuments {
+				return err
+			}
+			log.Printf("backfill: instance %s has no hq-sourced owner; left unrecorded", inst.InstanceID)
+			continue
+		}
+
+		if _, err := db.Admin("instance_members").InsertOne(ctx, InstanceMember{
+			MemberID:       uuid.NewString(),
+			AccountID:      inst.AccountID,
+			InstanceID:     inst.InstanceID,
+			CustomerUserID: owner.HQUserID,
+			ControlUserID:  owner.UserID,
+			Role:           sharedmodels.RoleOwner,
+			Email:          owner.Email,
+			CreatedAt:      time.Now().UTC(),
+		}); err != nil {
+			return err
+		}
+		created++
+	}
+	if created > 0 {
+		log.Printf("backfill: recorded %d pre-existing instance owners", created)
+	}
+	return nil
+}

admin/internal/models/members.go

@@ -0,0 +1,60 @@
+package models
+
+import (
+	"time"
+
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// Account roles.
+//
+// Deliberately the same three words as the control plane's own roles rather
+// than a second vocabulary: a customer who reads "admin" in the portal and
+// "admin" in their instance should not have to learn that they mean different
+// things. They govern different scopes — this one governs the HQ account —
+// but they mean the same thing about power.
+//
+// Billing stays owner-only. Owners and admins may invite people, create
+// instances and grant instance access.
+const (
+	AccountRoleOwner  = "owner"
+	AccountRoleAdmin  = "admin"
+	AccountRoleMember = "member"
+)
+
+func ValidAccountRole(r string) bool {
+	switch r {
+	case AccountRoleOwner, AccountRoleAdmin, AccountRoleMember:
+		return true
+	}
+	return false
+}
+
+// AccountRoleAtLeastAdmin is the single definition of "may manage people and
+// instances". Every guard calls this rather than comparing strings, so widening
+// the rule is one edit.
+func AccountRoleAtLeastAdmin(r string) bool {
+	return r == AccountRoleOwner || r == AccountRoleAdmin
+}
+
+// InstanceMember records that one HQ person holds a projected user inside one
+// cloud instance.
+//
+// It is admin's index of the projection, not the authority: the control-plane
+// `users` row IS the access. This row exists so the portal can list who is on
+// an instance without reading the control plane, and so a password change can
+// find every row to update without scanning every instance.
+//
+// ControlUserID is the projected users.user_id. Role is the role that user
+// holds INSIDE the instance, which is not the person's account role.
+type InstanceMember struct {
+	ID             bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	MemberID       string        `bson:"member_id" json:"member_id"`
+	AccountID      string        `bson:"account_id" json:"account_id"`
+	InstanceID     string        `bson:"instance_id" json:"instance_id"`
+	CustomerUserID string        `bson:"customer_user_id" json:"customer_user_id"`
+	ControlUserID  string        `bson:"control_user_id" json:"control_user_id"`
+	Role           string        `bson:"role" json:"role"`
+	Email          string        `bson:"email" json:"email"`
+	CreatedAt      time.Time     `bson:"created_at" json:"created_at"`
+}

admin/internal/models/models.go

@@ -0,0 +1,189 @@
+// Package models holds admin's own documents.
+//
+// These are admin-owned and never shared with the control plane. The two
+// structs that ARE shared — Instance and User on the control-plane side — come
+// from shared/models, so there is no second copy of those shapes to drift.
+package models
+
+import (
+	"time"
+
+	"github.com/mrhid6/vantage/shared/license"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// Instance statuses.
+const (
+	StatusAwaitingLink = "awaiting_link"
+	StatusActive       = "active"
+	StatusLapsed       = "lapsed"
+	StatusCancelled    = "cancelled"
+
+	// StatusDeleted marks an instance the control plane has reaped. The row is
+	// kept because the licence history references it and support questions
+	// outlive the instance.
+	StatusDeleted = "deleted"
+)
+
+// Account statuses.
+const (
+	AccountActive    = "active"
+	AccountSuspended = "suspended"
+)
+
+// Licence issuance reasons. These end up in support conversations, so they are
+// stable identifiers rather than prose.
+const (
+	ReasonNew        = "new"
+	ReasonRenewal    = "renewal"
+	ReasonTierChange = "tier_change"
+	ReasonRelink     = "relink"
+	ReasonManual     = "manual"
+)
+
+// MaxRelinksPerTerm is the customer-facing relink cap.
+//
+// This is an abuse SIGNAL, not abuse prevention — offline licences cannot be
+// revoked, so a determined customer is not stopped by a counter. Its real job is
+// to put a human in front of the fourth attempt.
+const MaxRelinksPerTerm = 3
+
+// GracePeriod is added to every licence expiry beyond the billing period end,
+// so a renewal webhook arriving slightly late does not create a gap in which a
+// paying customer's instance goes read-only.
+const GracePeriod = 3 * 24 * time.Hour
+
+// RenewWindow is how long before expiry a Free instance may be renewed.
+//
+// Renewal stays available after expiry too, right up until the reaper takes the
+// instance, so the same button rescues a lapsed instance instead of needing a
+// second mechanism.
+const RenewWindow = 7 * 24 * time.Hour
+
+type Account struct {
+	ID               bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	AccountID        string        `bson:"account_id" json:"account_id"`
+	Name             string        `bson:"name" json:"name"`
+	BillingEmail     string        `bson:"billing_email" json:"billing_email"`
+	PaddleCustomerID string        `bson:"paddle_customer_id,omitempty" json:"paddle_customer_id,omitempty"`
+	Status           string        `bson:"status" json:"status"`
+	CreatedAt        time.Time     `bson:"created_at" json:"created_at"`
+}
+
+// Instance is admin's record of one deployment.
+//
+// For cloud, InstanceID equals the control-plane instance_id. For self-hosted it
+// is the UUID the customer pasted — their database is theirs, and we cannot see
+// it, so this row is the only thing that exists on our side.
+type Instance struct {
+	ID             bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	InstanceID     string        `bson:"instance_id" json:"instance_id"`
+	AccountID      string        `bson:"account_id" json:"account_id"`
+	Name           string        `bson:"name" json:"name"`
+	Slug           string        `bson:"slug,omitempty" json:"slug,omitempty"`
+	Deployment     string        `bson:"deployment" json:"deployment"`
+	Tier           string        `bson:"tier,omitempty" json:"tier,omitempty"`
+	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"`
+	// 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"`
+	CreatedAt   time.Time `bson:"created_at" json:"created_at"`
+}
+
+// License is append-only. A renewal writes a new row and sets SupersededBy on
+// the old one. Nothing here is ever edited or deleted: when a support question
+// arrives about why an instance stopped working on a given date, the answer has
+// to still be in the table.
+type License struct {
+	ID           bson.ObjectID  `bson:"_id,omitempty" json:"-"`
+	LicenseID    string         `bson:"license_id" json:"license_id"`
+	InstanceID   string         `bson:"instance_id" json:"instance_id"`
+	AccountID    string         `bson:"account_id" json:"account_id"`
+	Tier         string         `bson:"tier" json:"tier"`
+	Deployment   string         `bson:"deployment" json:"deployment"`
+	Limits       license.Limits `bson:"limits" json:"limits"`
+	Features     []string       `bson:"features" json:"features"`
+	IssuedAt     time.Time      `bson:"issued_at" json:"issued_at"`
+	ExpiresAt    time.Time      `bson:"expires_at" json:"expires_at"`
+	Blob         string         `bson:"blob" json:"-"`
+	SupersededBy string         `bson:"superseded_by,omitempty" json:"superseded_by,omitempty"`
+	IssuedBy     string         `bson:"issued_by" json:"issued_by"`
+	Reason       string         `bson:"reason" json:"reason"`
+}
+
+type Subscription struct {
+	ID                   bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	SubscriptionID       string        `bson:"subscription_id" json:"subscription_id"`
+	AccountID            string        `bson:"account_id" json:"account_id"`
+	InstanceID           string        `bson:"instance_id,omitempty" json:"instance_id,omitempty"`
+	PaddleSubscriptionID string        `bson:"paddle_subscription_id,omitempty" json:"paddle_subscription_id,omitempty"`
+	PaddlePriceID        string        `bson:"paddle_price_id,omitempty" json:"paddle_price_id,omitempty"`
+	Tier                 string        `bson:"tier" json:"tier"`
+	Term                 string        `bson:"term" json:"term"`
+	Status               string        `bson:"status" json:"status"`
+	CurrentPeriodEnd     time.Time     `bson:"current_period_end" json:"current_period_end"`
+}
+
+// Plan is the authoritative tier definition, seeded from shared/license.
+//
+// It lives in the database so tier contents change without a deploy. Every
+// issued licence snapshots it, so editing a plan never rewrites an existing
+// licence — the same rule as workflow_runs.steps_snapshot.
+type Plan struct {
+	ID              bson.ObjectID     `bson:"_id,omitempty" json:"-"`
+	Tier            string            `bson:"tier" json:"tier"`
+	Name            string            `bson:"name" json:"name"`
+	Deployment      string            `bson:"deployment" json:"deployment"`
+	Limits          license.Limits    `bson:"limits" json:"limits"`
+	Features        []string          `bson:"features" json:"features"`
+	PaddleProductID string            `bson:"paddle_product_id,omitempty" json:"paddle_product_id,omitempty"`
+	PaddlePriceIDs  map[string]string `bson:"paddle_price_ids,omitempty" json:"paddle_price_ids,omitempty"`
+	Active          bool              `bson:"active" json:"active"`
+}
+
+type StaffUser struct {
+	ID           bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	UserID       string        `bson:"user_id" json:"user_id"`
+	Email        string        `bson:"email" json:"email"`
+	PasswordHash string        `bson:"password_hash" json:"-"`
+	Name         string        `bson:"name" json:"name"`
+	CreatedAt    time.Time     `bson:"created_at" json:"created_at"`
+}
+
+// CustomerUser is one person on an HQ account.
+//
+// AccountRole governs what they may do to the ACCOUNT — invite people, create
+// instances, grant access. It says nothing about what they may do inside any
+// instance; that is the role on their InstanceMember row.
+type CustomerUser struct {
+	ID                bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	UserID            string        `bson:"user_id" json:"user_id"`
+	AccountID         string        `bson:"account_id" json:"account_id"`
+	Email             string        `bson:"email" json:"email"`
+	PasswordHash      string        `bson:"password_hash" json:"-"`
+	AccountRole       string        `bson:"account_role" json:"account_role"`
+	VerifiedAt        *time.Time    `bson:"verified_at,omitempty" json:"verified_at,omitempty"`
+	VerifyTokenHash   string        `bson:"verify_token_hash,omitempty" json:"-"`
+	VerifyTokenExpiry *time.Time    `bson:"verify_token_expiry,omitempty" json:"-"`
+	// HQSyncFailedAt is set when a password change could not be written to
+	// every projected control-plane row. It is visibility only — hqsync repairs
+	// by comparing hashes, not by reading this field.
+	HQSyncFailedAt *time.Time `bson:"hq_sync_failed_at,omitempty" json:"hq_sync_failed_at,omitempty"`
+	CreatedAt      time.Time  `bson:"created_at" json:"created_at"`
+}
+
+type AuditEntry struct {
+	ID        bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	Actor     string        `bson:"actor" json:"actor"`
+	Action    string        `bson:"action" json:"action"`
+	AccountID string        `bson:"account_id,omitempty" json:"account_id,omitempty"`
+	Target    string        `bson:"target,omitempty" json:"target,omitempty"`
+	Detail    string        `bson:"detail,omitempty" json:"detail,omitempty"`
+	IP        string        `bson:"ip,omitempty" json:"ip,omitempty"`
+	CreatedAt time.Time     `bson:"created_at" json:"created_at"`
+}

admin/internal/models/plans.go

@@ -0,0 +1,50 @@
+package models
+
+import (
+	"context"
+	"time"
+
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/shared/license"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+// SeedPlans inserts the tier table from shared/license on first boot.
+//
+// It uses $setOnInsert only: once a plan exists, staff edits to limits, features
+// and Paddle IDs are authoritative and a redeploy must not stamp over them.
+func SeedPlans(ctx context.Context) error {
+	for _, tier := range []string{license.TierFree, license.TierProfessional, license.TierSelfHosted} {
+		p, ok := license.PlanFor(tier)
+		if !ok {
+			continue
+		}
+		_, err := db.Admin("plans").UpdateOne(ctx,
+			bson.M{"tier": tier},
+			bson.M{"$setOnInsert": bson.M{
+				"tier":       p.Tier,
+				"name":       p.Name,
+				"deployment": p.Deployment,
+				"limits":     p.Limits,
+				"features":   p.Features,
+				"active":     true,
+			}},
+			options.UpdateOne().SetUpsert(true))
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// GetPlan reads a tier's authoritative definition.
+func GetPlan(ctx context.Context, tier string) (*Plan, error) {
+	var p Plan
+	if err := db.Admin("plans").FindOne(ctx, bson.M{"tier": tier}).Decode(&p); err != nil {
+		return nil, err
+	}
+	return &p, nil
+}
+
+func now() time.Time { return time.Now().UTC() }

adminsite/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+.next
+.env
+*.lic

adminsite/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+.next
+next-env.d.ts
+.env
+*.lic

adminsite/Dockerfile

@@ -0,0 +1,43 @@
+FROM node:26-alpine AS deps
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm install
+
+FROM node:26-alpine AS builder
+
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Baked in at build time and must be reachable from the BROWSER, and present in
+# admin's ADMIN_ORIGIN. Wrong here means every request fails at runtime.
+ARG NEXT_PUBLIC_ADMIN_API_URL=http://localhost:8083
+ENV NEXT_PUBLIC_ADMIN_API_URL=$NEXT_PUBLIC_ADMIN_API_URL
+ARG NEXT_PUBLIC_ADMIN_ENV=production
+ENV NEXT_PUBLIC_ADMIN_ENV=$NEXT_PUBLIC_ADMIN_ENV
+
+RUN npm run build
+
+FROM node:26-alpine AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]

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

@@ -0,0 +1,111 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { API_BASE, NotConnected, api } from "@/lib/api";
+import { NotConnectedPanel } from "@/components/NotConnected";
+import { PageFrame, RailCard, RailFacts } from "@/components/PageFrame";
+import { PageHeader } from "@/components/PageHeader";
+import { formatDate } from "@/lib/format";
+
+export default function BillingPage() {
+    const subs = useQuery({ queryKey: ["subscriptions"], queryFn: api.subscriptions });
+    const account = useQuery({ queryKey: ["account"], queryFn: api.account });
+
+    if (subs.error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
+    if (subs.isLoading) return <p className="text-ink-3">Loading…</p>;
+
+    const rows = subs.data ?? [];
+
+    // Each subscription names the instance it pays for, because tier and term
+    // are per-licence rather than per-account. Resolving the name here is the
+    // difference between "professional · annual" and knowing which install that is.
+    const nameFor = (instanceId?: string) =>
+        account.data?.instances.find((i) => i.instance_id === instanceId)?.name;
+
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="Billing"
+                subtitle="One subscription per instance — each carries its own tier and term."
+                record={
+                    account.data
+                        ? [{ key: "Billing", value: account.data.account.billing_email }]
+                        : undefined
+                }
+            />
+
+            <PageFrame
+                aside={
+                    <>
+                        <RailCard title="Account">
+                            <RailFacts
+                                rows={[
+                                    {
+                                        label: "Billing contact",
+                                        value: account.data?.account.billing_email ?? "—",
+                                    },
+                                    { label: "Status", value: account.data?.account.status ?? "—" },
+                                    { label: "Subscriptions", value: rows.length },
+                                ]}
+                            />
+                        </RailCard>
+                        <RailCard title="Need a change?">
+                            <p className="text-[0.82rem] text-ink-2">
+                                To change a card, download an invoice or cancel, email support and
+                                we will send you a billing link. Self-service billing arrives with
+                                card payments.
+                            </p>
+                            <a
+                                href="mailto:support@hostxtra.co.uk"
+                                className="text-[0.82rem] font-semibold text-accent underline"
+                            >
+                                support@hostxtra.co.uk
+                            </a>
+                        </RailCard>
+                    </>
+                }
+            >
+                {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>
+                )}
+            </PageFrame>
+        </div>
+    );
+}

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

@@ -0,0 +1,168 @@
+"use client";
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useParams, useRouter } from "next/navigation";
+import { useState } from "react";
+import { API_BASE, ApiError, NotConnected, api } from "@/lib/api";
+import { NotConnectedPanel } from "@/components/NotConnected";
+import { LicenceDelivery } from "@/components/LicenceDelivery";
+import { MembersPanel } from "@/components/MembersPanel";
+import { RelinkPanel } from "@/components/RelinkPanel";
+import { StatePill } from "@/components/StatePill";
+import { PageFrame, RailCard, RailFacts } from "@/components/PageFrame";
+import { PageHeader } from "@/components/PageHeader";
+import { formatDate, licenceState, limitLabel } from "@/lib/format";
+
+export default function InstancePage() {
+    const id = String(useParams().id);
+    const router = useRouter();
+    const qc = useQueryClient();
+    const [relinkError, setRelinkError] = useState<string | undefined>();
+
+    const account = useQuery({ queryKey: ["account"], queryFn: api.account });
+    const licence = useQuery({
+        queryKey: ["license", id],
+        queryFn: () => api.license(id),
+        retry: false,
+    });
+
+    const relink = useMutation({
+        mutationFn: (newId: string) => api.relink(id, newId),
+        onSuccess: (lic) => {
+            qc.invalidateQueries({ queryKey: ["account"] });
+            router.replace(`/instances/${lic.instance_id}`);
+        },
+        onError: (err) =>
+            setRelinkError(err instanceof ApiError ? err.message : "Relink failed. Try again."),
+    });
+
+    if (account.error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
+
+    const instance = account.data?.instances.find((i) => i.instance_id === id);
+    if (account.isLoading) return <p className="text-ink-3">Loading…</p>;
+    if (!instance) {
+        // Says "not on your account" rather than "does not exist": the backend
+        // answers 404 for another account's instance, and confirming existence
+        // here would undo that.
+        return <p className="text-ink-2">That instance is not on your account.</p>;
+    }
+
+    const lic = licence.data;
+    const state = licenceState(lic?.expires_at, Boolean(lic));
+    const cloud = instance.deployment === "cloud";
+
+    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 }] : []),
+                ]}
+                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>
+                            )}
+                        </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",
+                                            value: lic.features.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>
+                        )}
+                    </>
+                }
+            >
+                {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>
+                )}
+
+                {lic && !cloud && (
+                    <>
+                        <LicenceDelivery
+                            instanceId={instance.instance_id}
+                            blob={lic.blob ?? ""}
+                            downloadUrl={api.licenseBlobUrl(instance.instance_id)}
+                        />
+                        <RelinkPanel
+                            instanceId={instance.instance_id}
+                            used={instance.relink_count}
+                            max={account.data?.max_relinks ?? 3}
+                            error={relinkError}
+                            onRelink={(newId) => relink.mutate(newId)}
+                        />
+                    </>
+                )}
+
+                {!lic && (
+                    <p className="rounded border border-rule bg-panel p-5 text-ink-2">
+                        No licence has been issued for this instance yet.
+                    </p>
+                )}
+            </PageFrame>
+        </div>
+    );
+}

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

@@ -0,0 +1,72 @@
+"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 }: { onLinked: (instanceId: string) => void }) {
+    const [id, setId] = useState("");
+    const [name, setName] = 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.link(value, name.trim());
+            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>.
+                    </>
+                }
+            />
+            <Field
+                label="Name it (optional)"
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                hint="So you can tell it apart from your other installs."
+            />
+            <Button type="submit" disabled={busy} className="justify-self-start">
+                {busy ? "Linking…" : "Link and issue licence"}
+            </Button>
+        </form>
+    );
+}

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

@@ -0,0 +1,29 @@
+"use client";
+
+import { useRouter } 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();
+
+    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
+                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)/instances/new/CreateForm.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { ApiError, api } from "@/lib/api";
+import { Button } from "@/components/Button";
+import { Field } from "@/components/Field";
+
+function slugify(value: string) {
+    return value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+
+export function CreateForm() {
+    const [name, setName] = useState("");
+    const [error, setError] = useState<string | null>(null);
+    const router = useRouter();
+    const qc = useQueryClient();
+
+    const create = useMutation({
+        mutationFn: () => api.createInstance(name.trim()),
+        onSuccess: async () => {
+            await qc.invalidateQueries({ queryKey: ["account"] });
+            router.push("/");
+        },
+        onError: (e) =>
+            setError(e instanceof ApiError ? e.message : "Something went wrong. Try again."),
+    });
+
+    const slug = slugify(name);
+
+    return (
+        <form
+            className="grid max-w-md gap-4"
+            onSubmit={(e) => {
+                e.preventDefault();
+                setError(null);
+                if (name.trim()) create.mutate();
+            }}
+        >
+            <Field
+                label="Instance name"
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                placeholder="Northgate Systems"
+                required
+                error={error ?? undefined}
+                hint={`${slug || "your-instance"}.vantage.hostxtra.co.uk`}
+            />
+
+            <p className="text-[0.82rem] text-ink-2">
+                You sign in to it with this same email address and password. Changing your Vantage
+                HQ password changes it here too.
+            </p>
+
+            <Button type="submit" disabled={create.isPending || !name.trim()}>
+                {create.isPending ? "Creating…" : "Create instance"}
+            </Button>
+        </form>
+    );
+}

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

@@ -0,0 +1,18 @@
+import type { Metadata } from "next";
+import { CreateForm } from "./CreateForm";
+import { PageHeader } from "@/components/PageHeader";
+
+export const metadata: Metadata = { title: "New instance" };
+
+export default function NewInstancePage() {
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                back={{ href: "/", label: "Overview" }}
+                title="Create a free instance"
+                subtitle="An instance owns its servers, keys, workflows, monitors and secrets. Nothing inside it is visible to any other instance. Free covers three servers, and the licence runs for a month at a time — we email you before it needs renewing."
+            />
+            <CreateForm />
+        </div>
+    );
+}

adminsite/app/(customer)/layout.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { api } from "@/lib/api";
+import { RequireKind } from "@/lib/session";
+import { AppBar, type NavLink } from "@/components/AppBar";
+
+/*
+ * Three destinations, not five. Settings moved into the account menu — it is
+ * your password, not a place — and Instances went with it, because Overview
+ * already lists them and a second door to the same room is just a second thing
+ * to keep in sync. Linking an install is an action, so it is a button on
+ * Overview rather than a permanent nav entry.
+ */
+const LINKS: NavLink[] = [
+    { href: "/", label: "Overview" },
+    { href: "/users", label: "People" },
+    { href: "/billing", label: "Billing" },
+];
+
+function AccountName() {
+    // Shares the ["account"] key with Overview, so this costs no extra request.
+    const { data } = useQuery({ queryKey: ["account"], queryFn: api.account });
+    if (!data) return null;
+    return (
+        <span className="block truncate text-[0.92rem] font-bold tracking-[-0.01em]">
+            {data.account.name}
+        </span>
+    );
+}
+
+export default function CustomerLayout({ children }: { children: React.ReactNode }) {
+    return (
+        <RequireKind kind="customer">
+            <AppBar links={LINKS} context={<AccountName />} />
+            <main className="mx-auto max-w-rail px-5 py-7">{children}</main>
+        </RequireKind>
+    );
+}

adminsite/app/(customer)/page.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import { useQueries, useQuery } from "@tanstack/react-query";
+import Link from "next/link";
+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 { PageHeader } from "@/components/PageHeader";
+import { LinkButton } from "@/components/Button";
+import { StatePill } from "@/components/StatePill";
+import { daysRemaining, formatDate, licenceState } from "@/lib/format";
+
+export default function OverviewPage() {
+    const { data, error, isLoading } = useQuery({ queryKey: ["account"], queryFn: api.account });
+    const people = useQuery({ queryKey: ["account-users"], queryFn: api.accountUsers });
+
+    const licences = useQueries({
+        queries: (data?.instances ?? [])
+            .filter((i) => i.current_license)
+            .map((i) => ({
+                queryKey: ["license", i.instance_id],
+                queryFn: () => api.license(i.instance_id),
+            })),
+    });
+
+    if (error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
+    if (isLoading || !data) return <p className="text-ink-3">Loading your account…</p>;
+
+    const byInstance = new Map<string, License>();
+    licences.forEach((q) => {
+        if (q.data) byInstance.set(q.data.instance_id, q.data);
+    });
+
+    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.
+    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")
+            return [
+                {
+                    id: i.instance_id,
+                    text: `${i.name} expires`,
+                    note: `${daysRemaining(lic!.expires_at)}d`,
+                },
+            ];
+        return [];
+    });
+
+    const pending = (people.data ?? []).filter((p) => !p.verified_at).length;
+    const hasFree = live.some((i) => i.tier === "free" && i.status !== "cancelled");
+
+    const subtitle =
+        live.length === 0
+            ? "Nothing here yet."
+            : `${live.length} ${live.length === 1 ? "instance" : "instances"}${
+                  attention.length ? ` · ${attention.length} needing attention` : " · all licensed"
+              }`;
+
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="Overview"
+                subtitle={subtitle}
+                actions={
+                    !hasFree && live.length > 0 ? (
+                        <LinkButton variant="line" href="/instances/new">
+                            Create a free instance
+                        </LinkButton>
+                    ) : undefined
+                }
+                record={[
+                    { key: "Account", value: data.account.account_id, copy: true },
+                    { key: "Billing", value: data.account.billing_email },
+                ]}
+                status={
+                    attention.length === 0 && live.length > 0 ? (
+                        <StatePill state="valid" />
+                    ) : undefined
+                }
+            />
+
+            {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 buy a self-hosted licence, install Vantage on your own
+                        server, and link it here to get your licence file.
+                    </p>
+                    <div className="flex flex-wrap gap-2.5">
+                        <LinkButton href="/instances/new">Create a free instance</LinkButton>
+                        <LinkButton variant="line" href="/instances/link">
+                            Link an install
+                        </LinkButton>
+                    </div>
+                </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) => (
+                                        <li
+                                            key={p.user_id}
+                                            className="flex items-center justify-between gap-2.5 text-[0.82rem] text-ink-2"
+                                        >
+                                            <span className="truncate">{p.email}</span>
+                                            <span className="shrink-0 font-mono text-[0.64rem] uppercase tracking-[0.08em] text-ink-3">
+                                                {p.account_role}
+                                            </span>
+                                        </li>
+                                    ))}
+                                </ul>
+                                {pending > 0 && (
+                                    <p className="border-t border-rule-soft pt-2 text-[0.78rem] text-warn">
+                                        {pending} {pending === 1 ? "invitation" : "invitations"} not
+                                        accepted yet
+                                    </p>
+                                )}
+                                <Link
+                                    href="/users"
+                                    className="text-[0.82rem] font-semibold text-accent underline"
+                                >
+                                    Manage people
+                                </Link>
+                            </RailCard>
+
+                            {/*
+                             * Account-level facts only. Tier, limits and renewal date
+                             * belong to a licence, and a licence belongs to one
+                             * instance — an account holding a Free cloud instance and
+                             * a Professional self-hosted one has no single plan.
+                             */}
+                            <RailCard title="Account">
+                                <RailFacts
+                                    rows={[
+                                        { label: "Billing contact", value: data.account.billing_email },
+                                        { label: "Status", value: data.account.status },
+                                        {
+                                            label: "Customer since",
+                                            value: formatDate(data.account.created_at),
+                                        },
+                                    ]}
+                                />
+                                <Link
+                                    href="/billing"
+                                    className="text-[0.82rem] font-semibold text-accent underline"
+                                >
+                                    Billing history
+                                </Link>
+                            </RailCard>
+
+                            <RailCard title="Running Vantage yourself?">
+                                <p className="text-[0.82rem] text-ink-2">
+                                    Link your own install to get its licence file. It keeps its own
+                                    users.
+                                </p>
+                                <Link
+                                    href="/instances/link"
+                                    className="text-[0.82rem] font-semibold text-accent underline"
+                                >
+                                    Link an install
+                                </Link>
+                            </RailCard>
+                        </>
+                    }
+                >
+                    {live.map((i, n) => {
+                        const lic = byInstance.get(i.instance_id);
+                        const state = licenceState(lic?.expires_at, Boolean(lic));
+                        return (
+                            <InstanceRecord
+                                key={i.instance_id}
+                                instance={i}
+                                license={lic}
+                                // Open when it is the only one, or when it is the
+                                // first thing that needs a decision. A saved toggle
+                                // beats this from then on.
+                                defaultOpen={
+                                    live.length === 1 ||
+                                    (state !== "valid" &&
+                                        attention[0]?.id === i.instance_id) ||
+                                    (attention.length === 0 && n === 0)
+                                }
+                            />
+                        );
+                    })}
+                </PageFrame>
+            )}
+        </div>
+    );
+}

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

@@ -0,0 +1,74 @@
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useState } from "react";
+import { ApiError, api } from "@/lib/api";
+import { Button } from "@/components/Button";
+import { Field } from "@/components/Field";
+import { PageHeader } from "@/components/PageHeader";
+
+export default function SettingsPage() {
+    const [current, setCurrent] = useState("");
+    const [next, setNext] = useState("");
+    const [error, setError] = useState<string | null>(null);
+    const [done, setDone] = useState<string | null>(null);
+
+    const change = useMutation({
+        mutationFn: () => api.changePassword(current, next),
+        onSuccess: (res) => {
+            setCurrent("");
+            setNext("");
+            setDone(
+                res.propagation_pending
+                    ? "Password changed. One of your instances could not be updated just now; it will catch up within fifteen minutes."
+                    : "Password changed everywhere.",
+            );
+        },
+        onError: (e) =>
+            setError(e instanceof ApiError ? e.message : "Something went wrong. Try again."),
+    });
+
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                back={{ href: "/", label: "Overview" }}
+                title="Settings"
+                subtitle="Your password signs you in here and into every Vantage instance you belong to. Changing it changes all of them."
+            />
+
+            <form
+                className="grid max-w-md gap-4 rounded border border-rule bg-panel p-5"
+                onSubmit={(e) => {
+                    e.preventDefault();
+                    setError(null);
+                    setDone(null);
+                    change.mutate();
+                }}
+            >
+                <Field
+                    label="Current password"
+                    type="password"
+                    autoComplete="current-password"
+                    value={current}
+                    onChange={(e) => setCurrent(e.target.value)}
+                    required
+                />
+                <Field
+                    label="New password"
+                    type="password"
+                    autoComplete="new-password"
+                    value={next}
+                    onChange={(e) => setNext(e.target.value)}
+                    required
+                    minLength={12}
+                    hint="At least 12 characters."
+                    error={error ?? undefined}
+                />
+                {done && <p className="text-[0.9rem] text-valid">{done}</p>}
+                <Button type="submit" disabled={change.isPending || next.length < 12}>
+                    {change.isPending ? "Changing…" : "Change password"}
+                </Button>
+            </form>
+        </div>
+    );
+}

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

@@ -0,0 +1,210 @@
+"use client";
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+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 { Field } from "@/components/Field";
+import { PageFrame, RailCard } from "@/components/PageFrame";
+import { formatDate } from "@/lib/format";
+
+const ROLES: AccountRole[] = ["owner", "admin", "member"];
+
+const WHAT_ROLES_DO: [AccountRole, string][] = [
+    ["owner", "Everything, including billing."],
+    ["admin", "Invite people, create instances, grant access. No billing."],
+    ["member", "Sign in to the instances they are given."],
+];
+
+export function InvitePanel() {
+    const qc = useQueryClient();
+    const { session } = useSession();
+    const [email, setEmail] = useState("");
+    const [role, setRole] = useState<AccountRole>("member");
+    const [error, setError] = useState<string | null>(null);
+
+    const users = useQuery({ queryKey: ["account-users"], queryFn: api.accountUsers });
+    const refresh = () => qc.invalidateQueries({ queryKey: ["account-users"] });
+    const fail = (e: unknown) =>
+        setError(e instanceof ApiError ? e.message : "Something went wrong. Try again.");
+
+    const invite = useMutation({
+        mutationFn: () => api.invite(email.trim().toLowerCase(), role),
+        onSuccess: () => {
+            setEmail("");
+            setRole("member");
+            refresh();
+        },
+        onError: fail,
+    });
+    const setRoleFor = useMutation({
+        mutationFn: (v: { id: string; role: AccountRole }) => api.setAccountRole(v.id, v.role),
+        onSuccess: refresh,
+        onError: fail,
+    });
+    const remove = useMutation({
+        mutationFn: (id: string) => api.removeAccountUser(id),
+        onSuccess: refresh,
+        onError: fail,
+    });
+
+    if (users.error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
+
+    const myRole = session?.account_role;
+    const canManage = myRole === "owner" || myRole === "admin";
+    const assignable = myRole === "owner" ? ROLES : ROLES.filter((r) => r !== "owner");
+
+    return (
+        <PageFrame
+            aside={
+                <>
+                    {canManage && (
+                        <RailCard title="Invite someone">
+                            <form
+                                className="grid gap-3"
+                                onSubmit={(e) => {
+                                    e.preventDefault();
+                                    setError(null);
+                                    if (email.trim()) invite.mutate();
+                                }}
+                            >
+                                <Field
+                                    label="Email"
+                                    type="email"
+                                    value={email}
+                                    onChange={(e) => setEmail(e.target.value)}
+                                    required
+                                    hint="They choose their own password from the emailed link. Nothing happens until they open it."
+                                />
+                                <label className="grid gap-1.5">
+                                    <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"
+                                    >
+                                        {assignable.map((r) => (
+                                            <option key={r} value={r}>
+                                                {r}
+                                            </option>
+                                        ))}
+                                    </select>
+                                </label>
+                                <Button type="submit" disabled={invite.isPending || !email.trim()}>
+                                    {invite.isPending ? "Sending…" : "Send invitation"}
+                                </Button>
+                            </form>
+                        </RailCard>
+                    )}
+
+                    <RailCard title="What the roles do">
+                        <dl className="grid gap-2">
+                            {WHAT_ROLES_DO.map(([r, what]) => (
+                                <div key={r} className="grid gap-0.5">
+                                    <dt className="font-mono text-[0.68rem] uppercase tracking-[0.08em] text-ink">
+                                        {r}
+                                    </dt>
+                                    <dd className="m-0 text-[0.8rem] text-ink-2">{what}</dd>
+                                </div>
+                            ))}
+                        </dl>
+                        <p className="border-t border-rule-soft pt-2 text-[0.8rem] text-ink-2">
+                            An account role is not access to an instance. Give someone that on the
+                            instance itself.
+                        </p>
+                    </RailCard>
+                </>
+            }
+        >
+            {error && (
+                <p className="rounded border border-expired bg-panel p-3 text-[0.9rem] text-expired">
+                    {error}
+                </p>
+            )}
+
+            <div className="overflow-x-auto rounded border border-rule bg-panel">
+                <table className="w-full border-collapse text-left text-[0.9rem]">
+                    <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">Email</th>
+                            <th className="px-4 py-2.5 font-normal">Account role</th>
+                            <th className="px-4 py-2.5 font-normal">Status</th>
+                            <th className="px-4 py-2.5" />
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {(users.data ?? []).map((u) => {
+                            const isSelf = u.email === session?.email;
+                            return (
+                                <tr key={u.user_id} className="border-b border-rule-soft last:border-0">
+                                    <td className="px-4 py-3">
+                                        {u.email}
+                                        {isSelf && <span className="ml-2 text-ink-3">(you)</span>}
+                                    </td>
+                                    <td className="px-4 py-3">
+                                        {canManage && !isSelf ? (
+                                            <select
+                                                value={u.account_role}
+                                                onChange={(e) =>
+                                                    setRoleFor.mutate({
+                                                        id: u.user_id,
+                                                        role: e.target.value as AccountRole,
+                                                    })
+                                                }
+                                                className="rounded border border-rule bg-panel-2 px-2 py-1 font-mono text-[0.82rem] text-ink"
+                                            >
+                                                {assignable.map((r) => (
+                                                    <option key={r} value={r}>
+                                                        {r}
+                                                    </option>
+                                                ))}
+                                            </select>
+                                        ) : (
+                                            <span className="font-mono text-[0.82rem]">
+                                                {u.account_role}
+                                            </span>
+                                        )}
+                                    </td>
+                                    <td className="px-4 py-3 text-ink-2">
+                                        {u.verified_at
+                                            ? `Active since ${formatDate(u.verified_at)}`
+                                            : "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>
+                                        )}
+                                    </td>
+                                </tr>
+                            );
+                        })}
+                        {users.data?.length === 0 && (
+                            <tr>
+                                <td colSpan={4} className="px-4 py-6 text-ink-3">
+                                    Nobody yet.
+                                </td>
+                            </tr>
+                        )}
+                    </tbody>
+                </table>
+            </div>
+        </PageFrame>
+    );
+}

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

@@ -0,0 +1,16 @@
+"use client";
+
+import { InvitePanel } from "./InvitePanel";
+import { PageHeader } from "@/components/PageHeader";
+
+export default function UsersPage() {
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="People"
+                subtitle="Everyone on this account. Owners and admins can invite people and grant them access to instances; billing stays with owners."
+            />
+            <InvitePanel />
+        </div>
+    );
+}

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

@@ -0,0 +1,69 @@
+"use client";
+
+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";
+
+export function AccountSearch() {
+    const [q, setQ] = useState("");
+    const { data, isFetching } = useQuery({
+        queryKey: ["staff-accounts", q],
+        queryFn: () => api.staff.accounts(q || undefined),
+    });
+
+    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"
+                                    >
+                                        {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>
+                        ))}
+                    </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>
+                )}
+            </div>
+        </div>
+    );
+}

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

@@ -0,0 +1,116 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { useParams } from "next/navigation";
+import Link from "next/link";
+import { api } from "@/lib/api";
+import { formatDate } from "@/lib/format";
+import { PageHeader } from "@/components/PageHeader";
+
+export default function AccountDetailPage() {
+    const id = String(useParams().id);
+    const { data, isLoading } = useQuery({
+        queryKey: ["staff-account", id],
+        queryFn: () => api.staff.account(id),
+    });
+
+    if (isLoading || !data) return <p className="text-ink-3">Loading…</p>;
+
+    return (
+        <div className="grid gap-8">
+            <PageHeader
+                back={{ href: "/staff/accounts", label: "Accounts" }}
+                title={data.account.name}
+                subtitle={data.account.billing_email}
+                record={[
+                    { key: "Account", value: data.account.account_id, copy: true },
+                    { key: "Status", value: data.account.status },
+                    ...(data.account.paddle_customer_id
+                        ? [{ key: "Paddle", value: data.account.paddle_customer_id, copy: true }]
+                        : []),
+                ]}
+            />
+
+            <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>
+            </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>
+
+            <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>
+
+            <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>
+        </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/accounts/page.tsx

@@ -0,0 +1,14 @@
+import { AccountSearch } from "./AccountSearch";
+import { PageHeader } from "@/components/PageHeader";
+
+export default function AccountsPage() {
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="Accounts"
+                subtitle="Search by name, email, Paddle ID or instance UUID."
+            />
+            <AccountSearch />
+        </div>
+    );
+}

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

@@ -0,0 +1,53 @@
+"use client";
+
+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";
+
+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,
+    );
+
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="Audit"
+                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>
+        </div>
+    );
+}

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

@@ -0,0 +1,91 @@
+"use client";
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { ApiError, api, type Tier } from "@/lib/api";
+import { Button } from "@/components/Button";
+import { Field } from "@/components/Field";
+
+export function IssuePanel({
+    instanceId,
+    deployment,
+}: {
+    instanceId: string;
+    deployment: string;
+}) {
+    const qc = useQueryClient();
+    const [tier, setTier] = useState<Tier>(deployment === "cloud" ? "professional" : "self_hosted");
+    const [term, setTerm] = useState("annual");
+    const [newId, setNewId] = useState("");
+    const [error, setError] = useState<string | undefined>();
+
+    const invalidate = () => qc.invalidateQueries({ queryKey: ["staff-instance", instanceId] });
+
+    const issue = useMutation({
+        mutationFn: () => api.staff.issue(instanceId, { tier, term, reason: "manual" }),
+        onSuccess: invalidate,
+        onError: (e) => setError(e instanceof ApiError ? e.message : "Issue failed."),
+    });
+
+    const relink = useMutation({
+        mutationFn: () => api.staff.relink(instanceId, newId.trim()),
+        onSuccess: invalidate,
+        onError: (e) => setError(e instanceof ApiError ? e.message : "Relink failed."),
+    });
+
+    return (
+        <section className="grid gap-4 border-t border-rule-soft pt-5">
+            <div className="flex flex-wrap items-end gap-3">
+                <label className="grid gap-1.5">
+                    <span className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
+                        Tier
+                    </span>
+                    <select
+                        value={tier}
+                        onChange={(e) => setTier(e.target.value as Tier)}
+                        className="rounded border border-rule bg-panel-2 px-2.5 py-2"
+                    >
+                        <option value="free">Free</option>
+                        <option value="professional">Professional</option>
+                        <option value="self_hosted">Self Hosted</option>
+                    </select>
+                </label>
+                <label className="grid gap-1.5">
+                    <span className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
+                        Term
+                    </span>
+                    <select
+                        value={term}
+                        onChange={(e) => setTerm(e.target.value)}
+                        className="rounded border border-rule bg-panel-2 px-2.5 py-2"
+                    >
+                        <option value="annual">Annual</option>
+                        <option value="monthly">Monthly</option>
+                    </select>
+                </label>
+                <Button type="button" onClick={() => issue.mutate()} disabled={issue.isPending}>
+                    {issue.isPending ? "Issuing…" : "Issue licence"}
+                </Button>
+            </div>
+
+            <div className="flex flex-wrap items-end gap-3">
+                <Field
+                    label="Relink to instance ID"
+                    value={newId}
+                    onChange={(e) => setNewId(e.target.value)}
+                    hint="Staff relinks are not capped — the customer cap exists to put you in the loop."
+                />
+                <Button
+                    type="button"
+                    variant="line"
+                    onClick={() => relink.mutate()}
+                    disabled={!newId.trim()}
+                >
+                    Relink
+                </Button>
+            </div>
+
+            {error && <p className="text-[0.82rem] text-expired">{error}</p>}
+        </section>
+    );
+}

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

@@ -0,0 +1,81 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { useParams } from "next/navigation";
+import Link from "next/link";
+import clsx from "clsx";
+import { api, type InjectionState } from "@/lib/api";
+import { Ledger } from "@/components/Ledger";
+import { PageHeader } from "@/components/PageHeader";
+import { IssuePanel } from "./IssuePanel";
+
+const INJECTION: Record<InjectionState, { label: string; tone: string }> = {
+    current: { label: "Control plane holds the current licence", tone: "text-valid" },
+    stale: {
+        label: "Control plane holds an older blob — the reconciler will repair it",
+        tone: "text-warn",
+    },
+    missing: { label: "No matching instance in the control plane", tone: "text-expired" },
+    none_issued: { label: "Nothing issued yet, so nothing to inject", tone: "text-ink-3" },
+};
+
+export default function StaffInstancePage() {
+    const id = String(useParams().id);
+    const { data, isLoading } = useQuery({
+        queryKey: ["staff-instance", id],
+        queryFn: () => api.staff.instance(id),
+        refetchInterval: 30_000,
+    });
+
+    if (isLoading || !data) return <p className="text-ink-3">Loading…</p>;
+
+    const inj = data.injection.state ? INJECTION[data.injection.state] : undefined;
+
+    return (
+        <div className="grid gap-8">
+            <div className="grid gap-3">
+                <PageHeader
+                    back={{
+                        href: `/staff/accounts/${data.account.account_id}`,
+                        label: data.account.name || "Account",
+                    }}
+                    title={data.instance.name || data.instance.instance_id}
+                    subtitle={
+                        <>
+                            <Link
+                                href={`/staff/accounts/${data.account.account_id}`}
+                                className="text-accent underline"
+                            >
+                                {data.account.name || data.account.account_id}
+                            </Link>
+                            <span className="text-ink-3">
+                                {" "}
+                                · {data.instance.deployment} · {data.instance.status}
+                                {data.instance.relink_count > 0 &&
+                                    ` · ${data.instance.relink_count} relinks this term`}
+                            </span>
+                        </>
+                    }
+                    record={[
+                        { key: "Instance", value: data.instance.instance_id, copy: true },
+                        ...(data.instance.slug
+                            ? [{ key: "Slug", value: data.instance.slug }]
+                            : []),
+                    ]}
+                />
+                {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>
+                <Ledger licenses={data.licenses} />
+                <IssuePanel
+                    instanceId={data.instance.instance_id}
+                    deployment={data.instance.deployment}
+                />
+            </section>
+        </div>
+    );
+}

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

@@ -0,0 +1,29 @@
+"use client";
+
+import { RequireKind } from "@/lib/session";
+import { AppBar, type NavLink } from "@/components/AppBar";
+
+const LINKS: NavLink[] = [
+    { href: "/staff", label: "Operations" },
+    { href: "/staff/accounts", label: "Accounts" },
+    { href: "/staff/licenses", label: "Licences" },
+    { href: "/staff/plans", label: "Plans" },
+    { href: "/staff/audit", label: "Audit" },
+];
+
+export default function StaffLayout({ children }: { children: React.ReactNode }) {
+    return (
+        <RequireKind kind="staff">
+            <AppBar
+                links={LINKS}
+                staff
+                context={
+                    <span className="rounded-sm border border-accent px-1.5 py-0.5 font-mono text-[0.64rem] uppercase tracking-[0.12em] text-accent">
+                        Staff
+                    </span>
+                }
+            />
+            <main className="mx-auto max-w-rail px-5 py-7">{children}</main>
+        </RequireKind>
+    );
+}

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

@@ -0,0 +1,101 @@
+"use client";
+
+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 { PageHeader } from "@/components/PageHeader";
+
+export default function LicensesPage() {
+    const [tier, setTier] = useState<"" | Tier>("");
+    const [reason, setReason] = useState("");
+    const { data } = useQuery({ queryKey: ["staff-licenses"], queryFn: () => api.staff.licenses() });
+
+    // 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),
+    );
+
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="Licences"
+                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="self_hosted">Self Hosted</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>
+                {rows.length === 0 && (
+                    <p className="px-4 py-6 text-ink-3">No licences match those filters.</p>
+                )}
+            </div>
+        </div>
+    );
+}

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

@@ -0,0 +1,188 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import Link from "next/link";
+import { API_BASE, NotConnected, api } from "@/lib/api";
+import { NotConnectedPanel } from "@/components/NotConnected";
+import { Queue } from "@/components/Queue";
+import { PageFrame, RailCard, RailFacts } from "@/components/PageFrame";
+import { PageHeader } from "@/components/PageHeader";
+import { StatePill } from "@/components/StatePill";
+import { LinkButton } from "@/components/Button";
+import { daysRemaining, formatStamp } from "@/lib/format";
+
+const HOURS_48 = 48 * 3600_000;
+
+export default function StaffDashboard() {
+    const injection = useQuery({ queryKey: ["injection"], queryFn: api.staff.injectionHealth });
+    const expiring = useQuery({
+        queryKey: ["instances", "expiring"],
+        queryFn: () => api.staff.instances({ expiring: "true" }),
+    });
+    const pastDue = useQuery({
+        queryKey: ["subs", "past_due"],
+        queryFn: () => api.staff.subscriptions("past_due"),
+    });
+    const unlinked = useQuery({
+        queryKey: ["instances", "awaiting_link"],
+        queryFn: () => api.staff.instances({ status: "awaiting_link" }),
+    });
+    const audit = useQuery({ queryKey: ["staff-audit"], queryFn: () => api.staff.audit() });
+    const allInstances = useQuery({
+        queryKey: ["instances", "all"],
+        queryFn: () => api.staff.instances(),
+    });
+
+    if (injection.error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
+
+    const stale = (unlinked.data ?? []).filter(
+        (i) => Date.now() - new Date(i.created_at).getTime() > HOURS_48,
+    );
+
+    const failed = injection.data?.count ?? 0;
+    const instances = allInstances.data ?? [];
+
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="Operations"
+                subtitle={
+                    failed > 0
+                        ? "Injection failures come first — those instances are paying for a licence they have not received."
+                        : "Nothing failing. Queues below are routine chasing."
+                }
+                actions={
+                    <LinkButton variant="line" href="/staff/accounts">
+                        Find an account
+                    </LinkButton>
+                }
+                record={[{ key: "Checked", value: formatStamp(new Date().toISOString()) }]}
+                status={failed > 0 ? <StatePill state="expired" /> : <StatePill state="valid" />}
+            />
+
+            <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+                <Queue
+                    title="Failed injections"
+                    tone="expired"
+                    count={failed}
+                    items={(injection.data?.failed ?? []).slice(0, 4).map((i) => ({
+                        label: i.name || i.instance_id,
+                        href: `/staff/instances/${i.instance_id}`,
+                        meta: i.inject_failed_at
+                            ? new Date(i.inject_failed_at).toISOString().slice(11, 16)
+                            : "",
+                    }))}
+                />
+                <Queue
+                    title="Expiring ≤ 14 days"
+                    tone="warn"
+                    count={expiring.data?.length ?? 0}
+                    items={(expiring.data ?? []).slice(0, 4).map((i) => ({
+                        label: i.name || i.instance_id,
+                        href: `/staff/instances/${i.instance_id}`,
+                        meta: i.tier ?? "",
+                    }))}
+                />
+                <Queue
+                    title="Past due"
+                    tone="expired"
+                    count={pastDue.data?.length ?? 0}
+                    items={(pastDue.data ?? []).slice(0, 4).map((s) => ({
+                        label: s.instance_id || s.account_id,
+                        href: `/staff/accounts/${s.account_id}`,
+                        meta: `${daysRemaining(s.current_period_end)}d`,
+                    }))}
+                />
+                <Queue
+                    title="Unlinked > 48h"
+                    tone="accent"
+                    count={stale.length}
+                    items={stale.slice(0, 4).map((i) => ({
+                        label: i.name || i.instance_id,
+                        href: `/staff/accounts/${i.account_id}`,
+                        meta: `${Math.floor((Date.now() - new Date(i.created_at).getTime()) / 86_400_000)}d`,
+                    }))}
+                />
+            </div>
+
+            <PageFrame
+                aside={
+                    <RailCard title="Fleet">
+                        <RailFacts
+                            rows={[
+                                { label: "Instances", value: instances.length },
+                                {
+                                    label: "Cloud",
+                                    value: instances.filter((i) => i.deployment === "cloud").length,
+                                },
+                                {
+                                    label: "Self-hosted",
+                                    value: instances.filter((i) => i.deployment === "self_hosted")
+                                        .length,
+                                },
+                                {
+                                    label: "Awaiting link",
+                                    value: (unlinked.data ?? []).length,
+                                },
+                            ]}
+                        />
+                        <Link
+                            href="/staff/licenses"
+                            className="text-[0.82rem] font-semibold text-accent underline"
+                        >
+                            All licences
+                        </Link>
+                    </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
+                        </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>
+            </PageFrame>
+        </div>
+    );
+}

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

@@ -0,0 +1,131 @@
+"use client";
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { api, type Plan } from "@/lib/api";
+import { Button } from "@/components/Button";
+import { ConfirmPlanChange } from "@/components/ConfirmPlanChange";
+import { limitLabel } from "@/lib/format";
+import { PageHeader } from "@/components/PageHeader";
+
+export default function PlansPage() {
+    const qc = useQueryClient();
+    const plans = useQuery({ queryKey: ["plans"], queryFn: api.staff.plans });
+    const licenses = useQuery({
+        queryKey: ["staff-licenses"],
+        queryFn: () => api.staff.licenses(),
+    });
+    const [draft, setDraft] = useState<Plan | null>(null);
+
+    const save = useMutation({
+        mutationFn: (p: Plan) =>
+            api.staff.updatePlan(p.tier, {
+                name: p.name,
+                limits: p.limits,
+                features: p.features,
+                paddle_product_id: p.paddle_product_id,
+                paddle_price_ids: p.paddle_price_ids,
+                active: p.active,
+            }),
+        onSuccess: () => {
+            qc.invalidateQueries({ queryKey: ["plans"] });
+            setDraft(null);
+        },
+    });
+
+    const original = plans.data?.find((p) => p.tier === draft?.tier);
+
+    return (
+        <div className="grid gap-6">
+            <PageHeader
+                title="Plans"
+                subtitle="The authoritative tier table. Every issued licence snapshots the plan it was cut from, so editing one never rewrites an existing licence."
+            />
+
+            {draft && original && (
+                <ConfirmPlanChange
+                    plan={original}
+                    next={draft}
+                    issuedCount={
+                        (licenses.data ?? []).filter(
+                            (l) => l.tier === draft.tier,
+                        ).length
+                    }
+                    onConfirm={() => save.mutate(draft)}
+                    onCancel={() => setDraft(null)}
+                />
+            )}
+
+            <div className="grid gap-4 lg:grid-cols-3">
+                {(plans.data ?? []).map((p) => (
+                    <section
+                        key={p.tier}
+                        className="grid gap-3 rounded border border-rule bg-panel p-5"
+                    >
+                        <h2 className="text-xl">{p.name}</h2>
+                        <dl className="grid gap-1 font-mono text-[0.82rem] tabular-nums text-ink-2">
+                            <div className="flex justify-between gap-2">
+                                <dt>servers</dt>
+                                <dd>{limitLabel(p.limits.max_servers)}</dd>
+                            </div>
+                            <div className="flex justify-between gap-2">
+                                <dt>secret groups</dt>
+                                <dd>
+                                    {limitLabel(p.limits.max_secret_groups)}
+                                </dd>
+                            </div>
+                            <div className="flex justify-between gap-2">
+                                <dt>channels</dt>
+                                <dd>{limitLabel(p.limits.max_channels)}</dd>
+                            </div>
+                            <div className="flex justify-between gap-2">
+                                <dt>features</dt>
+                                <dd>{p.features?.join(", ") || "none"}</dd>
+                            </div>
+                        </dl>
+
+                        {/* Guard rail two: deployment is shown, never edited. */}
+                        <p className="flex items-center gap-2 rounded border border-rule bg-panel-2 px-2.5 py-2 text-[0.82rem] text-ink-3">
+                            <span aria-hidden="true">🔒</span>
+                            <span>
+                                Deployment is fixed at{" "}
+                                <b className="font-mono">{p.deployment}</b>.
+                                Moving a tier between cloud and self-hosted is a
+                                code change, not a form field.
+                            </span>
+                        </p>
+
+                        <div className="flex flex-wrap gap-2">
+                            <Button
+                                type="button"
+                                variant="line"
+                                onClick={() =>
+                                    setDraft({
+                                        ...p,
+                                        limits: { ...p.limits, max_servers: 7 },
+                                    })
+                                }
+                            >
+                                Cap servers at 7
+                            </Button>
+                            <Button
+                                type="button"
+                                variant="line"
+                                onClick={() =>
+                                    setDraft({
+                                        ...p,
+                                        features: p.features.filter(
+                                            (f) => f !== "oidc",
+                                        ),
+                                    })
+                                }
+                            >
+                                Remove OIDC
+                            </Button>
+                        </div>
+                    </section>
+                ))}
+            </div>
+        </div>
+    );
+}

adminsite/app/accept-invite/page.tsx

@@ -0,0 +1,76 @@
+"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";
+
+function AcceptForm() {
+    const token = useSearchParams().get("token") ?? "";
+    const [password, setPassword] = useState("");
+    const [error, setError] = useState<string | null>(null);
+    const [done, setDone] = useState(false);
+
+    const accept = useMutation({
+        mutationFn: () => api.acceptInvite(token, password),
+        onSuccess: () => setDone(true),
+        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 (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>
+        );
+
+    return (
+        <form
+            className="grid max-w-md gap-4"
+            onSubmit={(e) => {
+                e.preventDefault();
+                setError(null);
+                accept.mutate();
+            }}
+        >
+            <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>
+    );
+}
+
+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>
+    );
+}

adminsite/app/globals.css

@@ -0,0 +1,178 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ==========================================================================
+   Vantage admin console design tokens.
+
+   Lines 8-97 below are site/app/globals.css's token blocks, copied verbatim:
+   the marketing site and this console are one visual system. Change them in
+   both apps in the same commit — nothing enforces the match automatically.
+
+   Light is the default because web/ is locked to dark, and telling the two
+   apart at a glance is what stops a Reissue landing in the wrong tab. In dark
+   mode the accent lifts to #5b9be8, which is nearer web/'s indigo, so the
+   distinction leans on the ground rather than the hue.
+   ========================================================================== */
+
+:root {
+    color-scheme: light dark;
+
+    --ground: #eaedf3;
+    --panel: #ffffff;
+    --panel-2: #f4f6fa;
+    --ink: #0a1b33;
+    --ink-2: #41556f;
+    --ink-3: #6c7f96;
+    --rule: #cdd6e2;
+    --rule-soft: #e0e6ef;
+    --accent: #0b2a58;
+    --accent-ink: #ffffff;
+    --up: #2f8a60;
+    --down: #c6462f;
+    --pend: #b0801f;
+    --shadow: 0 1px 0 rgba(10, 27, 51, 0.05), 0 18px 40px -26px rgba(10, 27, 51, 0.45);
+    --logo: #0b2a58;
+
+    --sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --mono: ui-monospace, "Cascadia Mono", "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace;
+
+    --s--1: clamp(0.76rem, 0.74rem + 0.1vw, 0.81rem);
+    --s-0: clamp(1rem, 0.97rem + 0.14vw, 1.05rem);
+    --s-1: clamp(1.16rem, 1.09rem + 0.32vw, 1.36rem);
+    --s-2: clamp(1.5rem, 1.34rem + 0.74vw, 2rem);
+    --s-3: clamp(2rem, 1.66rem + 1.6vw, 3.1rem);
+    --s-4: clamp(2.6rem, 1.9rem + 3.3vw, 4.9rem);
+
+    --rail: 1200px;
+}
+
+/* Dark tokens are defined once and applied through three selectors: the OS
+   preference, and both explicit values of data-theme so the in-page toggle
+   wins in either direction. */
+@media (prefers-color-scheme: dark) {
+    :root {
+        --ground: #071628;
+        --panel: #0d2138;
+        --panel-2: #102842;
+        --ink: #e4ecf6;
+        --ink-2: #9fb3ca;
+        --ink-3: #71879f;
+        --rule: #1e3855;
+        --rule-soft: #172c44;
+        --accent: #5b9be8;
+        --accent-ink: #04101f;
+        --up: #4fb484;
+        --down: #e2705a;
+        --pend: #d6a63f;
+        --shadow: 0 1px 0 rgba(0, 0, 0, 0.35), 0 20px 44px -26px rgba(0, 0, 0, 0.85);
+        --logo: #7fb2f0;
+    }
+}
+
+:root[data-theme="dark"] {
+    --ground: #071628;
+    --panel: #0d2138;
+    --panel-2: #102842;
+    --ink: #e4ecf6;
+    --ink-2: #9fb3ca;
+    --ink-3: #71879f;
+    --rule: #1e3855;
+    --rule-soft: #172c44;
+    --accent: #5b9be8;
+    --accent-ink: #04101f;
+    --up: #4fb484;
+    --down: #e2705a;
+    --pend: #d6a63f;
+    --shadow: 0 1px 0 rgba(0, 0, 0, 0.35), 0 20px 44px -26px rgba(0, 0, 0, 0.85);
+    --logo: #7fb2f0;
+}
+
+:root[data-theme="light"] {
+    --ground: #eaedf3;
+    --panel: #ffffff;
+    --panel-2: #f4f6fa;
+    --ink: #0a1b33;
+    --ink-2: #41556f;
+    --ink-3: #6c7f96;
+    --rule: #cdd6e2;
+    --rule-soft: #e0e6ef;
+    --accent: #0b2a58;
+    --accent-ink: #ffffff;
+    --up: #2f8a60;
+    --down: #c6462f;
+    --pend: #b0801f;
+    --shadow: 0 1px 0 rgba(10, 27, 51, 0.05), 0 18px 40px -26px rgba(10, 27, 51, 0.45);
+    --logo: #0b2a58;
+}
+
+/* Not in site/: the hatched sandbox badge and hover washes need a tinted fill,
+   and deriving it at each use would drift. */
+:root {
+    --accent-wash: rgba(11, 42, 88, 0.07);
+}
+
+@media (prefers-color-scheme: dark) {
+    :root {
+        --accent-wash: rgba(91, 155, 232, 0.1);
+    }
+}
+
+:root[data-theme="dark"] {
+    --accent-wash: rgba(91, 155, 232, 0.1);
+}
+
+:root[data-theme="light"] {
+    --accent-wash: rgba(11, 42, 88, 0.07);
+}
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    background: var(--ground);
+    color: var(--ink);
+    font-family: var(--sans);
+    font-size: var(--s-0);
+    line-height: 1.6;
+    -webkit-font-smoothing: antialiased;
+}
+
+/* site/'s heading treatment, which is what replaces a display face. */
+h1,
+h2,
+h3 {
+    margin: 0;
+    font-weight: 800;
+    line-height: 1.03;
+    letter-spacing: -0.03em;
+    text-wrap: balance;
+}
+
+p {
+    margin: 0;
+}
+
+code {
+    font-family: var(--mono);
+    font-size: 0.92em;
+}
+
+:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 3px;
+    border-radius: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+        animation-duration: 0.001ms !important;
+        transition-duration: 0.001ms !important;
+    }
+}

adminsite/app/layout.tsx

@@ -0,0 +1,28 @@
+import type { Metadata } from "next";
+import "./globals.css";
+import { Providers } from "@/components/Providers";
+import { THEME_BOOT_SCRIPT } from "@/lib/theme";
+
+export const metadata: Metadata = {
+    title: "Vantage HQ",
+    description: "Licences, instances and billing for Vantage.",
+};
+
+/*
+ * The masthead deliberately does NOT live here. It belongs to the authenticated
+ * layouts, so /login, /signup, /verify and /accept-invite stop rendering a bar
+ * whose navigation and account menu they cannot use.
+ */
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+    return (
+        <html lang="en">
+            <head>
+                {/* Runs before first paint, so a dark-preferring viewer never sees white. */}
+                <script dangerouslySetInnerHTML={{ __html: THEME_BOOT_SCRIPT }} />
+            </head>
+            <body>
+                <Providers>{children}</Providers>
+            </body>
+        </html>
+    );
+}

adminsite/app/login/page.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+import Link from "next/link";
+import { API_BASE, ApiError, NotConnected, api } from "@/lib/api";
+import { NotConnectedPanel } from "@/components/NotConnected";
+import { Button } from "@/components/Button";
+import { Field } from "@/components/Field";
+
+export default function LoginPage() {
+    const router = useRouter();
+    const [email, setEmail] = useState("");
+    const [password, setPassword] = useState("");
+    const [staff, setStaff] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    const [offline, setOffline] = useState(false);
+    const [busy, setBusy] = useState(false);
+
+    async function submit(e: React.FormEvent) {
+        e.preventDefault();
+        setBusy(true);
+        setError(null);
+        try {
+            const s = staff
+                ? await api.staffLogin(email, password)
+                : await api.login(email, password);
+            router.replace(s.kind === "staff" ? "/staff" : "/");
+        } catch (err) {
+            if (err instanceof NotConnected) setOffline(true);
+            else if (err instanceof ApiError) setError(err.message);
+            else setError("Sign in failed. Try again.");
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    if (offline)
+        return (
+            <Main>
+                <NotConnectedPanel url={API_BASE} />
+            </Main>
+        );
+
+    return (
+        <Main>
+            <h1 className="text-3xl">Sign in</h1>
+            <form onSubmit={submit} className="mt-6 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)}
+                    />
+                    I work at Vantage
+                </label>
+                <div className="flex flex-wrap items-center gap-3">
+                    <Button type="submit" disabled={busy}>
+                        {busy ? "Signing in…" : "Sign in"}
+                    </Button>
+                    <Link href="/signup" className="text-[0.82rem] text-accent underline">
+                        Create an account for a self-hosted licence
+                    </Link>
+                </div>
+            </form>
+        </Main>
+    );
+}
+
+function Main({ children }: { children: React.ReactNode }) {
+    return <main className="mx-auto max-w-rail px-5 py-12">{children}</main>;
+}

adminsite/app/not-found.tsx

@@ -0,0 +1,15 @@
+import Link from "next/link";
+
+export default function NotFound() {
+    return (
+        <main className="mx-auto max-w-rail px-5 py-12">
+            <h1 className="text-3xl">Nothing here</h1>
+            <p className="mt-2 text-ink-2">
+                That page does not exist, or it belongs to an account you are not signed in to.
+            </p>
+            <Link href="/" className="mt-4 inline-block text-accent underline">
+                Back to your account
+            </Link>
+        </main>
+    );
+}

adminsite/app/signup/page.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { useState } from "react";
+import { ApiError, NotConnected, api } from "@/lib/api";
+import { Button } from "@/components/Button";
+import { Field } from "@/components/Field";
+
+export default function SignupPage() {
+    const [form, setForm] = useState({ name: "", email: "", password: "", website: "" });
+    const [state, setState] = useState<"idle" | "busy" | "sent">("idle");
+    const [error, setError] = useState<string | null>(null);
+
+    async function submit(e: React.FormEvent) {
+        e.preventDefault();
+        setState("busy");
+        setError(null);
+        try {
+            await api.signup(form);
+            setState("sent");
+        } catch (err) {
+            setState("idle");
+            setError(
+                err instanceof NotConnected
+                    ? "The licensing service is not reachable from this page."
+                    : err instanceof ApiError
+                      ? err.message
+                      : "Could not create the account. Try again.",
+            );
+        }
+    }
+
+    return (
+        <main className="mx-auto max-w-rail px-5 py-12">
+            {state === "sent" ? (
+                <div className="grid max-w-xl gap-3">
+                    <h1 className="text-3xl">Check your email</h1>
+                    <p className="text-ink-2">
+                        We sent a link to {form.email}. Open it to finish setting up your account —
+                        it expires in 24 hours. Nothing is created until you do.
+                    </p>
+                </div>
+            ) : (
+                <>
+                    <h1 className="text-3xl">Create an account</h1>
+                    <p className="mt-2 max-w-xl text-ink-2">
+                        For self-hosted licences. If you run on our cloud, sign in with the same
+                        details you use for your Vantage instance.
+                    </p>
+                    <form onSubmit={submit} className="mt-6 grid gap-4">
+                        <Field
+                            label="Organisation"
+                            required
+                            value={form.name}
+                            onChange={(e) => setForm({ ...form, name: e.target.value })}
+                        />
+                        <Field
+                            label="Email"
+                            type="email"
+                            required
+                            value={form.email}
+                            onChange={(e) => setForm({ ...form, email: e.target.value })}
+                        />
+                        <Field
+                            label="Password"
+                            type="password"
+                            required
+                            minLength={12}
+                            hint="At least 12 characters."
+                            value={form.password}
+                            onChange={(e) => setForm({ ...form, password: e.target.value })}
+                            error={error ?? undefined}
+                        />
+                        {/* Honeypot: off-screen, unlabelled for humans, irresistible to bots. */}
+                        <input
+                            type="text"
+                            name="website"
+                            tabIndex={-1}
+                            autoComplete="off"
+                            aria-hidden="true"
+                            value={form.website}
+                            onChange={(e) => setForm({ ...form, website: e.target.value })}
+                            className="absolute left-[-9999px] h-0 w-0"
+                        />
+                        <Button type="submit" disabled={state === "busy"}>
+                            {state === "busy" ? "Creating…" : "Create account"}
+                        </Button>
+                    </form>
+                </>
+            )}
+        </main>
+    );
+}

adminsite/app/verify/page.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+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";
+
+function Verify() {
+    const router = useRouter();
+    const token = useSearchParams().get("token") ?? "";
+    const { data, error, isLoading } = useQuery({
+        queryKey: ["verify", token],
+        queryFn: () => api.verify(token),
+        enabled: token !== "",
+        retry: false,
+    });
+
+    // An invitation and a verification link are the same shape, and someone will
+    // paste one into the other. The backend leaves an invite token unspent and
+    // says so; send them where they can actually finish.
+    const needsPassword = data?.needs_password === true;
+    useEffect(() => {
+        if (needsPassword) {
+            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 (!token)
+        return (
+            <Message
+                title="That link is incomplete"
+                body="It is missing its token. Use the link in the email exactly as sent."
+            />
+        );
+    if (isLoading) return <Message title="Verifying…" body="One moment." />;
+    if (error || !data?.verified)
+        return (
+            <Message
+                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."
+            />
+        );
+
+    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">
+                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>
+    );
+}
+
+export default function VerifyPage() {
+    return (
+        <main className="mx-auto max-w-rail px-5 py-12">
+            <Suspense fallback={null}>
+                <Verify />
+            </Suspense>
+        </main>
+    );
+}

adminsite/components/AccountMenu.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
+import { api } from "@/lib/api";
+import { useSession } from "@/lib/session";
+import { useTheme, type ThemePref } from "@/lib/theme";
+
+const APPEARANCE: { value: ThemePref; label: string }[] = [
+    { value: "light", label: "Light" },
+    { value: "dark", label: "Dark" },
+    { value: "system", label: "System" },
+];
+
+/*
+ * Everything here is about YOU rather than about the account: your settings,
+ * your password, how you want the app to look, and leaving. None of it is a
+ * destination worth a slot in the primary nav, which is why Settings moved off
+ * the bar and into this menu.
+ */
+export function AccountMenu({ staff = false }: { staff?: boolean }) {
+    const { session } = useSession();
+    const [open, setOpen] = useState(false);
+    const [pref, setPref] = useTheme();
+    const wrap = useRef<HTMLDivElement>(null);
+    const router = useRouter();
+    const qc = useQueryClient();
+
+    useEffect(() => {
+        if (!open) return;
+        const onDown = (e: MouseEvent) => {
+            if (wrap.current && !wrap.current.contains(e.target as Node)) setOpen(false);
+        };
+        const onKey = (e: KeyboardEvent) => {
+            if (e.key === "Escape") setOpen(false);
+        };
+        document.addEventListener("mousedown", onDown);
+        document.addEventListener("keydown", onKey);
+        return () => {
+            document.removeEventListener("mousedown", onDown);
+            document.removeEventListener("keydown", onKey);
+        };
+    }, [open]);
+
+    const signOut = useMutation({
+        mutationFn: api.logout,
+        // Clear the cache before leaving: a cached account response outliving
+        // the session would show the next person who signs in on this browser
+        // the previous account's name for a beat.
+        onSettled: () => {
+            qc.clear();
+            router.replace("/login");
+        },
+    });
+
+    const email = session?.email ?? "";
+    const initials =
+        email
+            .split("@")[0]
+            .split(/[.\-_]/)
+            .slice(0, 2)
+            .map((p) => p[0]?.toUpperCase() ?? "")
+            .join("") || "?";
+
+    return (
+        <div className="relative" ref={wrap}>
+            <button
+                type="button"
+                onClick={() => setOpen((v) => !v)}
+                aria-expanded={open}
+                aria-haspopup="menu"
+                className={`flex items-center gap-2 rounded-sm border px-2 py-1 text-[0.8rem] ${
+                    open ? "border-accent text-ink" : "border-rule text-ink-2"
+                } bg-panel hover:border-ink-3`}
+            >
+                <span className="grid h-[18px] w-[18px] shrink-0 place-items-center rounded-full bg-accent font-mono text-[0.56rem] font-bold text-accent-ink">
+                    {initials}
+                </span>
+                <span className="hidden max-w-[16ch] truncate sm:inline">{email}</span>
+                <span aria-hidden className="text-[0.6rem] text-ink-3">
+                    ▾
+                </span>
+            </button>
+
+            {open && (
+                <div
+                    role="menu"
+                    // --shadow rather than a literal: globals.css defines it per
+                    // theme, and a hardcoded rgba would be a colour value living
+                    // in a component, which this app's tokens rule forbids.
+                    className="absolute right-0 top-[calc(100%+8px)] z-50 grid w-64 overflow-hidden rounded border border-rule bg-panel shadow-[var(--shadow)]"
+                >
+                    <div className="grid gap-0.5 border-b border-rule-soft px-3 py-2.5">
+                        <strong className="truncate text-[0.86rem]">{email}</strong>
+                        <span className="font-mono text-[0.66rem] uppercase tracking-[0.1em] text-ink-3">
+                            {staff ? "Vantage staff" : (session?.account_role ?? "member")}
+                        </span>
+                    </div>
+
+                    {!staff && (
+                        <Link
+                            href="/settings"
+                            role="menuitem"
+                            onClick={() => setOpen(false)}
+                            className="px-3 py-2 text-[0.86rem] text-ink hover:bg-accent-wash"
+                        >
+                            Settings
+                        </Link>
+                    )}
+
+                    <div className="grid gap-1.5 border-y border-rule-soft px-3 py-2.5">
+                        <span className="font-mono text-[0.66rem] uppercase tracking-[0.12em] text-ink-3">
+                            Appearance
+                        </span>
+                        <div className="flex overflow-hidden rounded-sm border border-rule">
+                            {APPEARANCE.map((a) => (
+                                <button
+                                    key={a.value}
+                                    type="button"
+                                    onClick={() => setPref(a.value)}
+                                    aria-pressed={pref === a.value}
+                                    className={`flex-1 px-0 py-1 font-mono text-[0.62rem] uppercase tracking-[0.08em] ${
+                                        pref === a.value
+                                            ? "bg-accent text-accent-ink"
+                                            : "bg-panel text-ink-3 hover:text-ink-2"
+                                    }`}
+                                >
+                                    {a.label}
+                                </button>
+                            ))}
+                        </div>
+                    </div>
+
+                    <button
+                        type="button"
+                        role="menuitem"
+                        onClick={() => signOut.mutate()}
+                        disabled={signOut.isPending}
+                        className="px-3 py-2 text-left text-[0.86rem] text-expired hover:bg-accent-wash"
+                    >
+                        {signOut.isPending ? "Signing out…" : "Sign out"}
+                    </button>
+                </div>
+            )}
+        </div>
+    );
+}

adminsite/components/AppBar.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { AccountMenu } from "@/components/AccountMenu";
+import { EnvBadge } from "@/components/EnvBadge";
+
+export type NavLink = { href: string; label: string };
+
+/*
+ * One masthead in three zones: who you are acting as, where you can go, and
+ * which environment you are in.
+ *
+ * It replaces a brand bar and a separate nav strip. The nav's active state is
+ * derived from the pathname rather than hardcoded — the previous customer nav
+ * marked Overview as current on every page, including the ones that weren't it.
+ *
+ * Staff sit on --panel-2 with a chip where the account name goes. web/ is locked
+ * to dark so this app defaults to light for the same reason CLAUDE.md gives:
+ * telling two consoles apart before you click Reissue. Staff and customer need
+ * that distinction from each other too, and one shade plus one chip buys it
+ * without a second palette.
+ */
+export function AppBar({
+    links,
+    context,
+    staff = false,
+}: {
+    links: NavLink[];
+    context?: React.ReactNode;
+    staff?: boolean;
+}) {
+    const pathname = usePathname();
+
+    const isCurrent = (href: string) =>
+        // The section root matches only exactly; deeper routes match by prefix,
+        // so /staff/accounts/:id still lights Accounts while /staff/accounts
+        // does not light Operations.
+        href === "/" || href === "/staff"
+            ? pathname === href
+            : pathname === href || pathname.startsWith(`${href}/`);
+
+    return (
+        <header className={`border-b border-rule ${staff ? "bg-panel-2" : "bg-panel"}`}>
+            <div className="mx-auto grid max-w-rail grid-cols-[auto_1fr_auto] items-center gap-4 px-5 md:gap-7">
+                <div className="col-start-1 row-start-1 flex min-w-0 items-center gap-3 py-2.5">
+                    <span className="flex items-baseline gap-2 text-[1.16rem] font-extrabold tracking-[-0.02em]">
+                        Vantage
+                        <span className="font-mono text-[0.72rem] font-normal uppercase tracking-[0.14em] text-ink-3">
+                            HQ
+                        </span>
+                    </span>
+                    {context && (
+                        <>
+                            <span aria-hidden className="hidden h-[22px] w-px bg-rule sm:block" />
+                            <span className="hidden min-w-0 sm:block">{context}</span>
+                        </>
+                    )}
+                </div>
+
+                <nav
+                    aria-label={staff ? "Staff" : "Account"}
+                    className="col-span-3 col-start-1 row-start-2 flex items-stretch gap-1 overflow-x-auto border-t border-rule-soft md:col-span-1 md:col-start-2 md:row-start-1 md:border-t-0"
+                >
+                    {links.map((l) => {
+                        const on = isCurrent(l.href);
+                        return (
+                            <Link
+                                key={l.href}
+                                href={l.href}
+                                aria-current={on ? "page" : undefined}
+                                className={`relative inline-flex shrink-0 items-center px-3 py-2.5 font-mono text-[0.72rem] uppercase tracking-[0.08em] md:py-0 ${
+                                    on
+                                        ? "font-bold text-accent after:absolute after:inset-x-3 after:bottom-0 after:h-0.5 after:bg-accent after:content-['']"
+                                        : "text-ink-3 hover:text-ink-2"
+                                }`}
+                            >
+                                {l.label}
+                            </Link>
+                        );
+                    })}
+                </nav>
+
+                <div className="col-start-3 row-start-1 flex items-center justify-end gap-2.5 py-2.5">
+                    <span className="hidden sm:block">
+                        <EnvBadge />
+                    </span>
+                    <AccountMenu staff={staff} />
+                </div>
+            </div>
+        </header>
+    );
+}

adminsite/components/Button.tsx

@@ -0,0 +1,57 @@
+import clsx from "clsx";
+import Link from "next/link";
+
+type Variant = "solid" | "line";
+
+/*
+ * Matches site/'s .btn--solid and .btn--line exactly, including the neutral
+ * border on the secondary variant. site/ does not have an accent-outlined
+ * button and this app should not invent one.
+ */
+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",
+        "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",
+        className,
+    );
+}
+
+type Props = React.ButtonHTMLAttributes<HTMLButtonElement> & { variant?: Variant };
+
+export function Button({ variant = "solid", className, ...rest }: Props) {
+    return <button {...rest} className={buttonClass(variant, rest.disabled, className)} />;
+}
+
+/*
+ * A link that looks like a button. It exists so a navigation action never has to
+ * be an <a> wrapped around a <button> — invalid markup, and it gives screen
+ * readers two nested controls where the page means one.
+ */
+export function LinkButton({
+    href,
+    variant = "solid",
+    external,
+    className,
+    children,
+}: {
+    href: string;
+    variant?: Variant;
+    external?: boolean;
+    className?: string;
+    children: React.ReactNode;
+}) {
+    const cls = buttonClass(variant, false, className);
+    return external ? (
+        <a href={href} className={cls}>
+            {children}
+        </a>
+    ) : (
+        <Link href={href} className={cls}>
+            {children}
+        </Link>
+    );
+}

adminsite/components/ConfirmPlanChange.tsx

@@ -0,0 +1,77 @@
+import type { Plan } from "@/lib/api";
+import { limitLabel } from "@/lib/format";
+import { Button } from "./Button";
+
+/*
+ * Editing a plan changes what every future customer gets, so the confirmation
+ * names each field rather than asking "are you sure". Existing licences
+ * snapshotted their plan at issue time and are genuinely unaffected — saying so
+ * is what stops a well-meaning edit being followed by a panicked reissue.
+ */
+export function ConfirmPlanChange({
+    plan,
+    next,
+    issuedCount,
+    onConfirm,
+    onCancel,
+}: {
+    plan: Plan;
+    next: Plan;
+    issuedCount: number;
+    onConfirm: () => void;
+    onCancel: () => void;
+}) {
+    const rows: { field: string; was: string; now: string }[] = [];
+    if (plan.limits.max_servers !== next.limits.max_servers)
+        rows.push({
+            field: "max_servers",
+            was: limitLabel(plan.limits.max_servers),
+            now: limitLabel(next.limits.max_servers),
+        });
+    if (plan.limits.max_secret_groups !== next.limits.max_secret_groups)
+        rows.push({
+            field: "max_secret_groups",
+            was: limitLabel(plan.limits.max_secret_groups),
+            now: limitLabel(next.limits.max_secret_groups),
+        });
+    if (plan.limits.max_channels !== next.limits.max_channels)
+        rows.push({
+            field: "max_channels",
+            was: limitLabel(plan.limits.max_channels),
+            now: limitLabel(next.limits.max_channels),
+        });
+    if (plan.features.join(",") !== next.features.join(","))
+        rows.push({
+            field: "features",
+            was: plan.features.join(", ") || "none",
+            now: next.features.join(", ") || "none",
+        });
+
+    return (
+        <div className="grid max-w-xl gap-3 rounded border border-warn bg-panel p-5">
+            <h2 className="text-xl">Change what {plan.name} grants?</h2>
+            <ul className="grid gap-1 font-mono text-[0.82rem]">
+                {rows.map((r) => (
+                    <li key={r.field} className="flex flex-wrap gap-2">
+                        <span className="text-ink-3">{r.field}</span>
+                        <span className="text-ink-3 line-through">{r.was}</span>
+                        <span className="font-semibold text-ink">→ {r.now}</span>
+                    </li>
+                ))}
+                {rows.length === 0 && <li className="text-ink-3">Nothing would change.</li>}
+            </ul>
+            <p className="text-[0.82rem] text-ink-3">
+                This applies to licences issued from now on. The {issuedCount} licences already
+                issued keep what they were signed with until each is reissued.
+            </p>
+            <div className="flex flex-wrap gap-3">
+                <Button type="button" onClick={onConfirm}>
+                    Change plan
+                </Button>
+                <Button type="button" variant="line" onClick={onCancel}>
+                    Keep as is
+                </Button>
+            </div>
+        </div>
+    );
+}

adminsite/components/EnvBadge.tsx

@@ -0,0 +1,22 @@
+/*
+ * Sandbox is hatched as well as coloured, so it survives a colourblind reader
+ * and a glance. It sits in the same place on every screen: issuing against the
+ * wrong environment should feel wrong before you click.
+ */
+const ENV = process.env.NEXT_PUBLIC_ADMIN_ENV === "sandbox" ? "sandbox" : "production";
+
+export function EnvBadge() {
+    const sandbox = ENV === "sandbox";
+    return (
+        <span
+            className={
+                sandbox
+                    ? "inline-flex items-center gap-2 rounded-sm border border-warn px-2 py-1 font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink [background-image:repeating-linear-gradient(-45deg,var(--accent-wash)_0_6px,transparent_6px_12px)]"
+                    : "inline-flex items-center gap-2 rounded-sm bg-accent px-2 py-1 font-mono text-[0.72rem] uppercase tracking-[0.1em] text-accent-ink"
+            }
+        >
+            <i className="h-1.5 w-1.5 shrink-0 rounded-full bg-current" />
+            {sandbox ? "Sandbox" : "Production"}
+        </span>
+    );
+}

adminsite/components/Field.tsx

@@ -0,0 +1,27 @@
+export function Field({
+    label,
+    hint,
+    error,
+    ...input
+}: React.InputHTMLAttributes<HTMLInputElement> & {
+    label: string;
+    hint?: React.ReactNode;
+    error?: string;
+}) {
+    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}
+        </label>
+    );
+}

adminsite/components/InstanceRecord.tsx

@@ -0,0 +1,279 @@
+"use client";
+
+import Link from "next/link";
+import clsx from "clsx";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+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 { Button, LinkButton } from "./Button";
+
+const STRIPE = {
+    valid: "before:bg-valid",
+    warn: "before:bg-warn",
+    expired: "before:bg-expired",
+    none: "before:bg-accent",
+} as const;
+
+const KEY = (id: string) => `vantage-hq-record-open:${id}`;
+
+/*
+ * One instance, open or closed.
+ *
+ * Closed it is a row — name, tier, host, term bar, state. Open it adds what the
+ * licence includes, who can sign in, and the actions. Deliberately ONE component
+ * rather than a card and a detail panel: two components meant a single-instance
+ * account got a third of a row of summary with its substance a click away, and
+ * a six-instance account got a grid of summaries with no way to look closer.
+ *
+ * It defaults open when it is the only instance or when it needs attention,
+ * because the thing that needs you is the thing that should be open. A manual
+ * toggle is remembered per instance and beats the default from then on.
+ */
+export function InstanceRecord({
+    instance,
+    license,
+    reapAfterDays,
+    defaultOpen = false,
+}: {
+    instance: Instance;
+    license?: License;
+    reapAfterDays?: number;
+    defaultOpen?: boolean;
+}) {
+    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);
+    useEffect(() => {
+        const saved = localStorage.getItem(KEY(instance.instance_id));
+        if (saved !== null) setOpen(saved === "1");
+    }, [instance.instance_id]);
+
+    const toggle = () => {
+        setOpen((v) => {
+            localStorage.setItem(KEY(instance.instance_id), v ? "0" : "1");
+            return !v;
+        });
+    };
+
+    const qc = useQueryClient();
+    const renew = useMutation({
+        mutationFn: () => api.renewInstance(instance.instance_id),
+        onSuccess: () => qc.invalidateQueries({ queryKey: ["account"] }),
+    });
+    const canRenew = instance.tier === "free" && license !== undefined && days <= 7;
+
+    // Only fetched once the record is open, and only for cloud: a self-hosted
+    // install manages its own users and the endpoint refuses it.
+    const members = useQuery({
+        queryKey: ["members", instance.instance_id],
+        queryFn: () => api.members(instance.instance_id),
+        enabled: open && cloud,
+    });
+
+    const panelId = `record-${instance.instance_id}`;
+
+    return (
+        <article
+            className={clsx(
+                "relative grid gap-3.5 rounded border border-rule bg-panel p-4 pl-5",
+                "before:absolute before:inset-y-0 before:left-0 before:w-1 before:content-['']",
+                STRIPE[state],
+            )}
+        >
+            <div className="flex flex-wrap items-start justify-between gap-3">
+                <div className="min-w-0">
+                    <h2 className="text-[1.22rem]">{instance.name || "Unnamed instance"}</h2>
+                    <p className="mt-1 font-mono text-[0.68rem] uppercase tracking-[0.1em] text-ink-3">
+                        {cloud ? "Cloud" : "Self-hosted"}
+                        {instance.tier ? ` · ${instance.tier.replace("_", " ")}` : ""}
+                        {` · created ${formatDate(instance.created_at)}`}
+                    </p>
+                    {cloud && instance.slug && (
+                        <a
+                            href={`https://${instance.slug}.vantage.hostxtra.co.uk`}
+                            className="mt-1.5 inline-block font-mono text-[0.78rem] text-accent underline"
+                        >
+                            {instance.slug}.vantage.hostxtra.co.uk &rarr;
+                        </a>
+                    )}
+                </div>
+
+                <div className="flex shrink-0 items-center gap-2.5">
+                    <StatePill state={state} />
+                    <button
+                        type="button"
+                        onClick={toggle}
+                        aria-expanded={open}
+                        aria-controls={panelId}
+                        aria-label={open ? "Hide details" : "Show details"}
+                        className="grid h-[26px] w-[26px] place-items-center rounded-sm border border-rule bg-panel text-[0.6rem] text-ink-3 hover:border-accent hover:text-accent"
+                    >
+                        <span
+                            aria-hidden
+                            className={clsx("block transition-transform", open && "rotate-180")}
+                        >
+                            ▲
+                        </span>
+                    </button>
+                </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>
+            )}
+
+            {state === "expired" && (
+                <div className="grid gap-1">
+                    <p className="text-[0.82rem] text-ink-2">
+                        Servers and monitors are still running, and your agents keep their keys.
+                        Changes are disabled until you renew.
+                    </p>
+                    {deleteInDays !== null && (
+                        <p className="text-[0.82rem] font-semibold text-expired">
+                            {deleteInDays <= 0
+                                ? "Scheduled for deletion."
+                                : `Deleted in ${deleteInDays} ${deleteInDays === 1 ? "day" : "days"} unless renewed.`}
+                        </p>
+                    )}
+                </div>
+            )}
+
+            {state === "none" && (
+                <p className="text-[0.82rem] text-ink-2">
+                    You have paid for this but it is not attached to an install yet, so no licence
+                    has been issued. Linking takes a minute.
+                </p>
+            )}
+
+            <div id={panelId} hidden={!open} className="grid gap-3.5">
+                {license && (
+                    <div className="grid gap-2 border-t border-rule-soft pt-3">
+                        <p className="font-mono text-[0.68rem] uppercase tracking-[0.12em] text-ink-3">
+                            Included in {instance.tier?.replace("_", " ") ?? "this licence"}
+                        </p>
+                        <div className="flex flex-wrap gap-x-7 gap-y-2.5">
+                            <Stat n={limitLabel(license.limits.max_servers)} label="Servers" />
+                            <Stat
+                                n={limitLabel(license.limits.max_secret_groups)}
+                                label="Secret groups"
+                            />
+                            <Stat n={limitLabel(license.limits.max_channels)} label="Channels" />
+                            <Stat
+                                n={license.features.length ? license.features.join(" · ") : "None"}
+                                label="Features"
+                                quiet={license.features.length === 0}
+                            />
+                        </div>
+                    </div>
+                )}
+
+                {cloud && (
+                    <div className="grid gap-2 border-t border-rule-soft pt-3">
+                        <p className="font-mono text-[0.68rem] uppercase tracking-[0.12em] text-ink-3">
+                            Who can sign in
+                        </p>
+                        <div className="flex flex-wrap items-center gap-2">
+                            {(members.data ?? []).map((m) => (
+                                <span
+                                    key={m.member_id}
+                                    className="inline-flex items-center gap-1.5 rounded-full border border-rule-soft py-0.5 pl-0.5 pr-2.5 text-[0.78rem] text-ink-2"
+                                >
+                                    <span className="grid h-[18px] w-[18px] place-items-center rounded-full bg-accent font-mono text-[0.56rem] font-bold text-accent-ink">
+                                        {m.email.slice(0, 2).toUpperCase()}
+                                    </span>
+                                    {m.email}
+                                </span>
+                            ))}
+                            {members.isLoading && <span className="text-[0.82rem] text-ink-3">Loading…</span>}
+                            {members.data?.length === 0 && (
+                                <span className="text-[0.82rem] text-ink-3">Nobody yet.</span>
+                            )}
+                            <Link
+                                href={`/instances/${instance.instance_id}`}
+                                className="text-[0.82rem] font-semibold text-accent underline"
+                            >
+                                Manage access
+                            </Link>
+                        </div>
+                    </div>
+                )}
+
+                <div className="flex flex-wrap items-center gap-2.5">
+                    {state === "none" ? (
+                        <LinkButton href="/instances/link">Link an install</LinkButton>
+                    ) : cloud && instance.slug ? (
+                        <>
+                            <LinkButton
+                                external
+                                href={`https://${instance.slug}.vantage.hostxtra.co.uk`}
+                            >
+                                Open instance
+                            </LinkButton>
+                            <LinkButton
+                                variant="line"
+                                href={`/instances/${instance.instance_id}`}
+                            >
+                                Instance settings
+                            </LinkButton>
+                        </>
+                    ) : (
+                        <LinkButton href={`/instances/${instance.instance_id}`}>
+                            {state === "expired" ? "Renew and download" : "Licence and download"}
+                        </LinkButton>
+                    )}
+
+                    {canRenew && (
+                        <Button
+                            type="button"
+                            variant="line"
+                            onClick={() => renew.mutate()}
+                            disabled={renew.isPending}
+                        >
+                            {renew.isPending ? "Renewing…" : "Renew"}
+                        </Button>
+                    )}
+                </div>
+            </div>
+        </article>
+    );
+}
+
+function Stat({ n, label, quiet }: { n: string; label: string; quiet?: boolean }) {
+    return (
+        <div className="grid gap-px">
+            <b
+                className={clsx(
+                    "tabular-nums tracking-[-0.02em]",
+                    quiet
+                        ? "text-[0.95rem] font-semibold text-ink-3"
+                        : "text-[1.18rem] font-extrabold",
+                )}
+            >
+                {n}
+            </b>
+            <span className="font-mono text-[0.64rem] uppercase tracking-[0.1em] text-ink-3">
+                {label}
+            </span>
+        </div>
+    );
+}

adminsite/components/Ledger.tsx

@@ -0,0 +1,82 @@
+import clsx from "clsx";
+import type { License } from "@/lib/api";
+import { formatDate, formatStamp, limitLabel } from "@/lib/format";
+
+const REASON: Record<License["reason"], string> = {
+    new: "New",
+    renewal: "Renewal",
+    tier_change: "Tier change",
+    relink: "Relink",
+    manual: "Manual",
+};
+
+/*
+ * Licences are append-only: a renewal supersedes its predecessor rather than
+ * replacing it. So this is a ledger, not a table. Superseded rows stay visible
+ * and are overprinted the way a cancelled instrument is — hiding them would
+ * destroy the only record of why an instance stopped working on a given date.
+ */
+export function Ledger({ licenses }: { licenses: License[] }) {
+    if (licenses.length === 0) {
+        return (
+            <p className="text-ink-2">
+                No licence has ever been issued for this instance, so it is read-only.
+            </p>
+        );
+    }
+
+    return (
+        <ul className="grid">
+            {licenses.map((l) => {
+                const dead = Boolean(l.superseded_by);
+                return (
+                    <li
+                        key={l.license_id}
+                        className={clsx(
+                            "grid gap-4 border-b border-rule-soft py-4 last:border-0 sm:grid-cols-[9.5rem_1fr]",
+                            dead && "text-ink-3",
+                        )}
+                    >
+                        <div className="font-mono text-[0.72rem] tabular-nums text-ink-3">
+                            <b
+                                className={clsx(
+                                    "block text-[0.82rem] font-semibold",
+                                    dead ? "text-ink-3" : "text-ink",
+                                )}
+                            >
+                                {formatDate(l.issued_at)}
+                            </b>
+                            {formatStamp(l.issued_at)}
+                        </div>
+                        <div className="grid justify-items-start gap-1.5">
+                            {dead && (
+                                <span className="-rotate-2 rounded-sm border-2 border-archival px-1.5 py-0.5 font-mono text-[0.72rem] uppercase tracking-[0.18em] text-archival opacity-75">
+                                    Superseded
+                                </span>
+                            )}
+                            <p className="flex flex-wrap items-center gap-2 font-semibold">
+                                {l.tier.replace("_", " ")}
+                                <span className="rounded-sm border border-rule px-1.5 py-0.5 font-mono text-[0.72rem] font-normal uppercase tracking-[0.09em] text-accent">
+                                    {REASON[l.reason]}
+                                </span>
+                            </p>
+                            <p className="font-mono text-[0.72rem] tabular-nums text-ink-3">
+                                {l.license_id.slice(0, 8)} · expires {formatDate(l.expires_at)} ·{" "}
+                                {limitLabel(l.limits.max_servers)} servers · issued by {l.issued_by}
+                                {l.superseded_by && (
+                                    <>
+                                        {" "}
+                                        · replaced by{" "}
+                                        <span className="text-accent underline">
+                                            {l.superseded_by.slice(0, 8)}
+                                        </span>
+                                    </>
+                                )}
+                            </p>
+                        </div>
+                    </li>
+                );
+            })}
+        </ul>
+    );
+}

adminsite/components/LicenceDelivery.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "./Button";
+
+/*
+ * 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.
+ */
+export function LicenceDelivery({
+    instanceId,
+    blob,
+    downloadUrl,
+}: {
+    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);
+    }
+
+    const steps = [
+        <>
+            Open <code className="rounded-sm bg-accent-wash px-1">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.
+        </>,
+    ];
+
+    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>
+            </div>
+            <pre className="overflow-x-auto rounded border border-dashed border-rule bg-panel-2 p-3 font-mono text-[0.72rem] text-ink-2">
+                {blob}
+            </pre>
+            <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>
+                ))}
+            </ol>
+        </section>
+    );
+}

adminsite/components/MembersPanel.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+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";
+
+const ROLES: InstanceRole[] = ["owner", "admin", "member"];
+
+/*
+ * 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.
+ */
+export function MembersPanel({ instanceId }: { instanceId: string }) {
+    const qc = useQueryClient();
+    const { session } = useSession();
+    const [selected, setSelected] = useState("");
+    const [role, setRole] = useState<InstanceRole>("member");
+    const [error, setError] = useState<string | null>(null);
+
+    const members = useQuery({
+        queryKey: ["members", instanceId],
+        queryFn: () => api.members(instanceId),
+    });
+    const people = useQuery({ queryKey: ["account-users"], queryFn: api.accountUsers });
+
+    const refresh = () => qc.invalidateQueries({ queryKey: ["members", instanceId] });
+    const fail = (e: unknown) =>
+        setError(e instanceof ApiError ? e.message : "Something went wrong. Try again.");
+
+    const grant = useMutation({
+        mutationFn: () => api.grantMember(instanceId, selected, role),
+        onSuccess: () => {
+            setSelected("");
+            setRole("member");
+            refresh();
+        },
+        onError: fail,
+    });
+    const changeRole = useMutation({
+        mutationFn: (v: { uid: string; role: InstanceRole }) =>
+            api.setMemberRole(instanceId, v.uid, v.role),
+        onSuccess: refresh,
+        onError: fail,
+    });
+    const revoke = useMutation({
+        mutationFn: (uid: string) => api.revokeMember(instanceId, uid),
+        onSuccess: refresh,
+        onError: fail,
+    });
+
+    const myRole = session?.account_role;
+    const canManage = myRole === "owner" || myRole === "admin";
+
+    const granted = new Set((members.data ?? []).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>
+            </div>
+
+            {error && <p className="text-[0.9rem] text-expired">{error}</p>}
+
+            <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>
+
+            {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>
+            )}
+
+            {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>
+            )}
+        </section>
+    );
+}

adminsite/components/NotConnected.tsx

@@ -0,0 +1,28 @@
+/*
+ * The deployment failure this repo makes most often, made legible. It names the
+ * variable, the value baked in, and both reasons it fails — unreachable from
+ * the browser, or missing from admin's ADMIN_ORIGIN.
+ */
+export function NotConnectedPanel({ url }: { url: string }) {
+    return (
+        <div className="grid max-w-2xl gap-3 rounded border border-expired bg-panel p-5">
+            <h2 className="text-xl text-expired">Not connected to the licensing service</h2>
+            {url ? (
+                <p className="text-ink-2">
+                    This build points at <code className="text-ink">ADMIN_API_URL</code> ={" "}
+                    <code className="text-ink">{url}</code>, which did not respond.
+                </p>
+            ) : (
+                <p className="text-ink-2">
+                    <code className="text-ink">ADMIN_API_URL</code> was not set when this app was
+                    built, so there is nowhere to send requests.
+                </p>
+            )}
+            <p className="text-[0.82rem] text-ink-3">
+                The value is baked in when the image is built and has to be reachable from your
+                browser, not just from the server. It also has to appear in the licensing
+                service&rsquo;s <code>ADMIN_ORIGIN</code>, or the browser blocks every request.
+            </p>
+        </div>
+    );
+}

adminsite/components/PageFrame.tsx

@@ -0,0 +1,69 @@
+/*
+ * Main column plus a fixed support rail.
+ *
+ * The rail is what stops a page being empty and the main column is what stops
+ * it being thin: an account with one instance used to render a third of a row
+ * of summary and nothing else. The rail carries what is true regardless of how
+ * many instances exist, so the page has a floor.
+ *
+ * It collapses below lg in source order, which puts the main column first on a
+ * phone. Nothing is hidden at any width — if content only fits on a desktop it
+ * does not belong in the rail.
+ */
+export function PageFrame({
+    children,
+    aside,
+}: {
+    children: React.ReactNode;
+    aside?: React.ReactNode;
+}) {
+    if (!aside) return <div className="grid gap-5">{children}</div>;
+
+    return (
+        <div className="grid items-start gap-5 lg:grid-cols-[minmax(0,1fr)_320px]">
+            <div className="grid min-w-0 gap-4">{children}</div>
+            <aside className="grid gap-3.5">{aside}</aside>
+        </div>
+    );
+}
+
+/** One card in the rail. Title is a label, not a heading you read for pleasure. */
+export function RailCard({
+    title,
+    count,
+    children,
+}: {
+    title: string;
+    count?: number | string;
+    children: React.ReactNode;
+}) {
+    return (
+        <section className="grid gap-2.5 rounded border border-rule bg-panel p-3.5">
+            <header className="flex items-baseline justify-between gap-2.5">
+                <h2 className="font-mono text-[0.66rem] font-normal uppercase tracking-[0.12em] text-ink-3">
+                    {title}
+                </h2>
+                {count !== undefined && (
+                    <b className="text-[0.95rem] font-extrabold tabular-nums">{count}</b>
+                )}
+            </header>
+            {children}
+        </section>
+    );
+}
+
+/** Key/value rows for the rail. Values are mono so numbers line up. */
+export function RailFacts({ rows }: { rows: { label: string; value: React.ReactNode }[] }) {
+    return (
+        <dl className="grid gap-1.5">
+            {rows.map((r) => (
+                <div key={r.label} className="flex justify-between gap-2.5 text-[0.82rem]">
+                    <dt className="text-ink-3">{r.label}</dt>
+                    <dd className="m-0 truncate font-mono text-[0.78rem] tabular-nums text-ink">
+                        {r.value}
+                    </dd>
+                </div>
+            ))}
+        </dl>
+    );
+}

adminsite/components/PageHeader.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import Link from "next/link";
+import { useState } from "react";
+
+/*
+ * One record-line entry. `copy` marks the value as worth lifting to the
+ * clipboard — an instance UUID or a licence ID, the strings people paste into
+ * support tickets.
+ */
+export type RecordField = { key: string; value: string; copy?: boolean };
+
+function CopyButton({ value }: { value: string }) {
+    const [done, setDone] = useState(false);
+    return (
+        <button
+            type="button"
+            onClick={async () => {
+                try {
+                    await navigator.clipboard.writeText(value);
+                    setDone(true);
+                    setTimeout(() => setDone(false), 1200);
+                } catch {
+                    // Clipboard is refused without a secure context or a user
+                    // gesture the browser trusts. The value is on screen and
+                    // 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"
+        >
+            {done ? "Copied" : "Copy"}
+        </button>
+    );
+}
+
+/*
+ * The page frame every screen starts with, replacing nine hand-rolled header
+ * blocks that each picked their own gaps and their own place for actions.
+ *
+ * The record line is the one new idea: Vantage HQ is a registry, so every screen
+ * is a record and records have reference numbers. Giving the reference a fixed
+ * slot, in mono, above the fold, means "where is the ID" stops being a per-page
+ * question. It costs one hairline rule.
+ */
+export function PageHeader({
+    back,
+    title,
+    subtitle,
+    actions,
+    record,
+    status,
+}: {
+    back?: { href: string; label: string };
+    title: string;
+    subtitle?: React.ReactNode;
+    actions?: React.ReactNode;
+    record?: RecordField[];
+    status?: React.ReactNode;
+}) {
+    return (
+        <header className="grid gap-3">
+            {back && (
+                <Link
+                    href={back.href}
+                    className="justify-self-start font-mono text-[0.7rem] uppercase tracking-[0.1em] text-ink-3 hover:text-accent"
+                >
+                    &larr; {back.label}
+                </Link>
+            )}
+
+            <div className="flex flex-wrap items-start justify-between gap-4">
+                <div className="min-w-0">
+                    <h1 className="text-[1.9rem]">{title}</h1>
+                    {subtitle && <p className="mt-1 text-[0.92rem] text-ink-2">{subtitle}</p>}
+                </div>
+                {actions && <div className="flex flex-wrap items-center gap-2">{actions}</div>}
+            </div>
+
+            {(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>
+                            {f.copy && <CopyButton value={f.value} />}
+                        </span>
+                    ))}
+                    {status && <span className="ml-auto">{status}</span>}
+                </div>
+            )}
+        </header>
+    );
+}

adminsite/components/Providers.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { QueryClientProvider } from "@tanstack/react-query";
+import { queryClient } from "@/lib/query-client";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}

adminsite/components/Queue.tsx

@@ -0,0 +1,53 @@
+import Link from "next/link";
+import clsx from "clsx";
+
+const TONE = {
+    expired: "border-l-expired text-expired",
+    warn: "border-l-warn text-warn",
+    accent: "border-l-accent text-accent",
+} as const;
+
+export function Queue({
+    title,
+    count,
+    tone,
+    items,
+}: {
+    title: string;
+    count: number;
+    tone: keyof typeof TONE;
+    items: { label: string; href: string; meta: string }[];
+}) {
+    return (
+        <section
+            className={clsx(
+                "grid gap-2 rounded border border-l-4 border-rule bg-panel p-4",
+                TONE[tone],
+            )}
+        >
+            <h2 className="font-mono text-[0.72rem] font-normal uppercase tracking-[0.1em] text-ink-3">
+                {title}
+            </h2>
+            <p className="text-3xl font-extrabold leading-none tabular-nums tracking-[-0.03em]">
+                {count}
+            </p>
+            {items.length === 0 ? (
+                <p className="text-[0.72rem] text-ink-3">Nothing to do here.</p>
+            ) : (
+                <ul className="grid gap-1">
+                    {items.map((i) => (
+                        <li
+                            key={i.href}
+                            className="flex justify-between gap-2 font-mono text-[0.72rem] text-ink-2"
+                        >
+                            <Link href={i.href} className="text-accent underline">
+                                {i.label}
+                            </Link>
+                            <span className="tabular-nums">{i.meta}</span>
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </section>
+    );
+}

adminsite/components/RelinkPanel.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "./Button";
+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;
+
+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("");
+    const remaining = Math.max(0, max - used);
+    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="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>
+                <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>
+            </div>
+        </section>
+    );
+}

adminsite/components/StatePill.tsx

@@ -0,0 +1,42 @@
+import clsx from "clsx";
+import type { LicenceState } from "@/lib/format";
+
+const LABEL: Record<LicenceState, string> = {
+    valid: "Valid",
+    warn: "Expiring",
+    expired: "Expired",
+    none: "Awaiting link",
+};
+
+/*
+ * State reads three ways: this pill's colour, the pill's SHAPE, and the label.
+ * Colour alone would fail a colourblind reader on the one screen where getting
+ * it wrong costs money.
+ */
+const SHAPE: Record<LicenceState, string> = {
+    valid: "rounded-full",
+    warn: "[clip-path:polygon(50%_0,100%_100%,0_100%)]",
+    expired: "[clip-path:polygon(20%_0,80%_0,100%_20%,100%_80%,80%_100%,20%_100%,0_80%,0_20%)]",
+    none: "rounded-none",
+};
+
+const TONE: Record<LicenceState, string> = {
+    valid: "border-valid text-valid",
+    warn: "border-warn text-warn",
+    expired: "border-expired text-expired",
+    none: "border-accent text-accent",
+};
+
+export function StatePill({ state }: { state: LicenceState }) {
+    return (
+        <span
+            className={clsx(
+                "inline-flex shrink-0 items-center gap-1.5 rounded-sm border bg-panel px-2 py-0.5 font-mono text-[0.72rem] uppercase tracking-[0.08em]",
+                TONE[state],
+            )}
+        >
+            <i className={clsx("h-1.5 w-1.5 shrink-0 bg-current", SHAPE[state])} />
+            {LABEL[state]}
+        </span>
+    );
+}

adminsite/lib/api.ts

@@ -0,0 +1,289 @@
+/*
+ * The typed client for the licensing service.
+ *
+ * The browser calls admin directly, so every request carries credentials and
+ * every failure mode is one of three: the API is unreachable (NotConnected),
+ * the caller is not signed in (ApiError 401, which layouts redirect on), or the
+ * request was refused (ApiError with the backend's own message, which is
+ * customer-facing and should be shown verbatim).
+ */
+
+export const API_BASE = (process.env.NEXT_PUBLIC_ADMIN_API_URL ?? "").replace(/\/$/, "");
+
+export class NotConnected extends Error {
+    constructor() {
+        super("not connected");
+        this.name = "NotConnected";
+    }
+}
+
+export class ApiError extends Error {
+    status: number;
+    constructor(status: number, message: string) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+    }
+}
+
+async function req<T>(path: string, init?: RequestInit): Promise<T> {
+    if (!API_BASE) throw new NotConnected();
+
+    let res: Response;
+    try {
+        res = await fetch(`${API_BASE}${path}`, {
+            ...init,
+            credentials: "include",
+            headers: { "Content-Type": "application/json", ...(init?.headers ?? {}) },
+        });
+    } catch {
+        // Network-level failure, DNS, or a CORS preflight the browser refused.
+        throw new NotConnected();
+    }
+
+    if (res.status === 204) return undefined as T;
+
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+        throw new ApiError(res.status, body?.error ?? `request failed (${res.status})`);
+    }
+    return body as T;
+}
+
+const post = <T,>(path: string, payload?: unknown) =>
+    req<T>(path, { method: "POST", body: payload ? JSON.stringify(payload) : undefined });
+
+const put = <T,>(path: string, payload?: unknown) =>
+    req<T>(path, { method: "PUT", body: payload ? JSON.stringify(payload) : undefined });
+
+const del = <T,>(path: string) => req<T>(path, { method: "DELETE" });
+
+// --- types ---------------------------------------------------------------
+
+export type Deployment = "cloud" | "self_hosted";
+export type Tier = "free" | "professional" | "self_hosted";
+export type InstanceStatus = "awaiting_link" | "active" | "lapsed" | "cancelled" | "deleted";
+
+/*
+ * Two role vocabularies, same three words. AccountRole governs the HQ account:
+ * who may invite, create instances and grant access. InstanceRole is the role a
+ * projected user holds INSIDE one instance. A person can be an account member
+ * and an instance owner at once — that is normal, not a mistake.
+ */
+export type AccountRole = "owner" | "admin" | "member";
+export type InstanceRole = "owner" | "admin" | "member";
+
+export interface Session {
+    kind: "staff" | "customer";
+    email: string;
+    account_id?: string;
+    account_role?: AccountRole;
+}
+
+export interface AccountUser {
+    user_id: string;
+    account_id: string;
+    email: string;
+    account_role: AccountRole;
+    verified_at?: string | null;
+    hq_sync_failed_at?: string | null;
+    created_at: string;
+}
+
+export interface InstanceMember {
+    member_id: string;
+    account_id: string;
+    instance_id: string;
+    customer_user_id: string;
+    control_user_id: string;
+    role: InstanceRole;
+    email: string;
+    created_at: string;
+}
+
+export interface Limits {
+    max_servers: number;
+    max_secret_groups: number;
+    max_channels: number;
+}
+
+export interface Account {
+    account_id: string;
+    name: string;
+    billing_email: string;
+    paddle_customer_id?: string;
+    status: "active" | "suspended";
+    created_at: string;
+}
+
+export interface Instance {
+    instance_id: string;
+    account_id: string;
+    name: string;
+    slug?: string;
+    deployment: Deployment;
+    tier?: Tier;
+    status: InstanceStatus;
+    current_license?: string;
+    relink_count: number;
+    inject_failed_at?: string | null;
+    notices_sent?: string[];
+    created_at: string;
+}
+
+export interface License {
+    license_id: string;
+    instance_id: string;
+    account_id: string;
+    tier: Tier;
+    deployment: Deployment;
+    limits: Limits;
+    features: string[];
+    issued_at: string;
+    expires_at: string;
+    superseded_by?: string;
+    issued_by: string;
+    reason: "new" | "renewal" | "tier_change" | "relink" | "manual";
+}
+
+export interface Subscription {
+    subscription_id: string;
+    account_id: string;
+    instance_id?: string;
+    tier: Tier;
+    term: string;
+    status: string;
+    current_period_end: string;
+}
+
+export interface Plan {
+    tier: Tier;
+    name: string;
+    deployment: Deployment;
+    limits: Limits;
+    features: string[];
+    paddle_product_id?: string;
+    paddle_price_ids?: Record<string, string>;
+    active: boolean;
+}
+
+export interface CustomerUser {
+    user_id: string;
+    account_id: string;
+    email: string;
+    verified_at?: string | null;
+    created_at: string;
+}
+
+export interface AuditEntry {
+    actor: string;
+    action: string;
+    account_id?: string;
+    target?: string;
+    detail?: string;
+    ip?: string;
+    created_at: string;
+}
+
+export interface AccountResponse {
+    account: Account;
+    instances: Instance[];
+    max_relinks: number;
+}
+
+export interface StaffAccountResponse {
+    account: Account;
+    instances: Instance[];
+    subscriptions: Subscription[];
+    users: CustomerUser[];
+    audit: AuditEntry[];
+}
+
+export type InjectionState = "current" | "stale" | "missing" | "none_issued";
+
+export interface StaffInstanceResponse {
+    instance: Instance;
+    account: Account;
+    licenses: License[];
+    injection: { applicable: boolean; state?: InjectionState; failed_at?: string | null };
+}
+
+// --- calls ---------------------------------------------------------------
+
+export const api = {
+    me: () => req<Session>("/auth/me"),
+    login: (email: string, password: string) => post<Session>("/auth/login", { email, password }),
+    staffLogin: (email: string, password: string) =>
+        post<Session>("/auth/staff/login", { email, password }),
+    logout: () => post<{ ok: boolean }>("/auth/logout"),
+    signup: (payload: { name: string; email: string; password: string; website?: string }) =>
+        post<{ pending: boolean }>("/auth/signup", payload),
+    verify: (token: string) =>
+        req<{ verified: boolean; needs_password?: boolean }>(
+            `/auth/verify?token=${encodeURIComponent(token)}`,
+        ),
+
+    account: () => req<AccountResponse>("/api/account"),
+    link: (instance_id: string, name: string) =>
+        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`, {}),
+    relink: (id: string, instance_id: string) =>
+        post<License>(`/api/instances/${id}/relink`, { instance_id }),
+    license: (id: string) => req<License & { blob?: string }>(`/api/instances/${id}/license`),
+    licenseBlobUrl: (id: string) => `${API_BASE}/api/instances/${id}/license/download`,
+    subscriptions: () => req<Subscription[]>("/api/subscriptions"),
+
+    accountUsers: () => req<AccountUser[]>("/api/account/users"),
+    invite: (email: string, role: AccountRole) =>
+        post<{ invited: boolean }>("/api/account/users", { email, role }),
+    setAccountRole: (userId: string, role: AccountRole) =>
+        put<{ ok: boolean }>(`/api/account/users/${userId}/role`, { role }),
+    removeAccountUser: (userId: string) =>
+        del<{ deleted: boolean }>(`/api/account/users/${userId}`),
+    changePassword: (current_password: string, new_password: string) =>
+        put<{ updated: boolean; propagation_pending: boolean }>("/api/account/password", {
+            current_password,
+            new_password,
+        }),
+    acceptInvite: (token: string, password: string) =>
+        post<{ accepted: boolean }>("/auth/accept-invite", { token, password }),
+
+    members: (instanceId: string) =>
+        req<InstanceMember[]>(`/api/instances/${instanceId}/members`),
+    grantMember: (instanceId: string, user_id: string, role: InstanceRole) =>
+        post<InstanceMember>(`/api/instances/${instanceId}/members`, { user_id, role }),
+    setMemberRole: (instanceId: string, userId: string, role: InstanceRole) =>
+        put<{ ok: boolean }>(`/api/instances/${instanceId}/members/${userId}/role`, { role }),
+    revokeMember: (instanceId: string, userId: string) =>
+        del<{ revoked: boolean }>(`/api/instances/${instanceId}/members/${userId}`),
+
+    staff: {
+        accounts: (q?: string) =>
+            req<Account[]>(`/api/staff/accounts${q ? `?q=${encodeURIComponent(q)}` : ""}`),
+        account: (id: string) => req<StaffAccountResponse>(`/api/staff/accounts/${id}`),
+        instances: (params?: Record<string, string>) =>
+            req<Instance[]>(
+                `/api/staff/instances${params ? `?${new URLSearchParams(params)}` : ""}`,
+            ),
+        instance: (id: string) => req<StaffInstanceResponse>(`/api/staff/instances/${id}`),
+        issue: (id: string, payload: { tier: Tier; term?: string; reason?: string }) =>
+            post<License>(`/api/staff/instances/${id}/issue`, payload),
+        relink: (id: string, instance_id: string) =>
+            post<License>(`/api/staff/instances/${id}/relink`, { instance_id }),
+        licenses: (params?: Record<string, string>) =>
+            req<License[]>(`/api/staff/licenses${params ? `?${new URLSearchParams(params)}` : ""}`),
+        plans: () => req<Plan[]>("/api/staff/plans"),
+        updatePlan: (tier: Tier, plan: Omit<Plan, "tier" | "deployment">) =>
+            req<{ updated: boolean }>(`/api/staff/plans/${tier}`, {
+                method: "PUT",
+                body: JSON.stringify(plan),
+            }),
+        audit: (accountId?: string) =>
+            req<AuditEntry[]>(`/api/staff/audit${accountId ? `?account_id=${accountId}` : ""}`),
+        injectionHealth: () =>
+            req<{ failed: Instance[]; count: number }>("/api/staff/health/injection"),
+        subscriptions: (status?: string) =>
+            req<Subscription[]>(`/api/staff/subscriptions${status ? `?status=${status}` : ""}`),
+    },
+};

adminsite/lib/format.ts

@@ -0,0 +1,33 @@
+export type LicenceState = "valid" | "warn" | "expired" | "none";
+
+/** Amber inside 14 days, matching the window staff chase renewals on. */
+export const EXPIRY_WARNING_DAYS = 14;
+
+export function daysRemaining(iso: string): number {
+    const ms = new Date(iso).getTime() - Date.now();
+    return Math.ceil(ms / 86_400_000);
+}
+
+export function licenceState(expiresAt: string | undefined, hasLicence: boolean): LicenceState {
+    if (!hasLicence || !expiresAt) return "none";
+    const days = daysRemaining(expiresAt);
+    if (days <= 0) return "expired";
+    if (days <= EXPIRY_WARNING_DAYS) return "warn";
+    return "valid";
+}
+
+export function formatDate(iso: string): string {
+    return new Date(iso).toLocaleDateString("en-GB", {
+        day: "numeric",
+        month: "short",
+        year: "numeric",
+    });
+}
+
+export function formatStamp(iso: string): string {
+    return `${new Date(iso).toISOString().slice(11, 19)} UTC`;
+}
+
+export function limitLabel(n: number): string {
+    return n === -1 ? "unlimited" : String(n);
+}

adminsite/lib/query-client.ts

@@ -0,0 +1,16 @@
+"use client";
+
+import { QueryClient } from "@tanstack/react-query";
+import { ApiError, NotConnected } from "./api";
+
+export const queryClient = new QueryClient({
+    defaultOptions: {
+        queries: {
+            staleTime: 30_000,
+            // Retrying a 401 or a missing API URL just delays the redirect and
+            // the not-connected panel.
+            retry: (count, error) =>
+                error instanceof NotConnected || error instanceof ApiError ? false : count < 1,
+        },
+    },
+});

adminsite/lib/session.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+import { API_BASE, ApiError, NotConnected, api, type Session } from "./api";
+import { NotConnectedPanel } from "@/components/NotConnected";
+
+export function useSession() {
+    const { data, error, isLoading } = useQuery<Session>({
+        queryKey: ["me"],
+        queryFn: api.me,
+        staleTime: 60_000,
+    });
+    return { session: data, error, isLoading };
+}
+
+/*
+ * The route-group guard. This is UX, not security: admin enforces the same
+ * boundary with RequireStaff/RequireCustomer and returns 404 rather than 403
+ * for another account's data. A customer hitting a staff route is redirected
+ * rather than shown a refusal, because there is nothing to tell them about.
+ */
+export function RequireKind({
+    kind,
+    children,
+}: {
+    kind: Session["kind"];
+    children: React.ReactNode;
+}) {
+    const router = useRouter();
+    const { session, error, isLoading } = useSession();
+
+    useEffect(() => {
+        if (error instanceof ApiError && error.status === 401) {
+            router.replace("/login");
+            return;
+        }
+        if (session && session.kind !== kind) {
+            router.replace(session.kind === "staff" ? "/staff" : "/");
+        }
+    }, [error, session, kind, router]);
+
+    if (error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
+    if (isLoading || !session || session.kind !== kind) return null;
+    return <>{children}</>;
+}

adminsite/lib/theme.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export type ThemePref = "light" | "dark" | "system";
+
+const KEY = "vantage-hq-theme";
+
+/*
+ * globals.css has always defined the dark tokens under BOTH
+ * :root[data-theme="dark"] and :root[data-theme="light"], specifically so an
+ * in-page control can win over the OS preference in either direction. Nothing
+ * ever set the attribute. This is that missing half.
+ *
+ * "system" removes the attribute rather than writing a value, which hands the
+ * decision back to the prefers-color-scheme block.
+ */
+export function applyTheme(pref: ThemePref) {
+    const root = document.documentElement;
+    if (pref === "system") root.removeAttribute("data-theme");
+    else root.setAttribute("data-theme", pref);
+}
+
+export function readTheme(): ThemePref {
+    if (typeof localStorage === "undefined") return "system";
+    const v = localStorage.getItem(KEY);
+    return v === "light" || v === "dark" ? v : "system";
+}
+
+export function useTheme(): [ThemePref, (p: ThemePref) => void] {
+    // Starts at "system" on both server and first client render so hydration
+    // matches; the real value lands in the effect below. The inline script in
+    // app/layout.tsx has already painted the correct colours by then, so there
+    // is no flash — only this control's own highlight settles a tick late.
+    const [pref, setPref] = useState<ThemePref>("system");
+
+    useEffect(() => setPref(readTheme()), []);
+
+    return [
+        pref,
+        (next: ThemePref) => {
+            setPref(next);
+            if (next === "system") localStorage.removeItem(KEY);
+            else localStorage.setItem(KEY, next);
+            applyTheme(next);
+        },
+    ];
+}
+
+/*
+ * Runs before first paint, so a dark-preferring user never sees a white flash.
+ * Inlined as a string because it has to execute ahead of React.
+ */
+export const THEME_BOOT_SCRIPT = `try{var t=localStorage.getItem(${JSON.stringify(
+    KEY,
+)});if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t)}catch(e){}`;

adminsite/next.config.ts

@@ -0,0 +1,13 @@
+import type { NextConfig } from "next";
+
+/*
+ * Unlike web/, this app does NOT proxy /api through a rewrite. The browser
+ * calls admin directly, so NEXT_PUBLIC_ADMIN_API_URL must be reachable from the
+ * browser and must appear in admin's ADMIN_ORIGIN. lib/api.ts renders an
+ * explicit not-connected state when it is not.
+ */
+const nextConfig: NextConfig = {
+    output: "standalone",
+};
+
+export default nextConfig;

adminsite/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "vantage-adminsite",
+    "version": "0.1.0",
+    "private": true,
+    "scripts": {
+        "dev": "next dev",
+        "build": "next build",
+        "start": "next start",
+        "lint": "next lint"
+    },
+    "dependencies": {
+        "next": "16.2.9",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
+        "@tanstack/react-query": "^5.51.1",
+        "clsx": "^2.1.1"
+    },
+    "devDependencies": {
+        "@types/node": "^20.14.11",
+        "@types/react": "^18.3.3",
+        "@types/react-dom": "^18.3.0",
+        "autoprefixer": "^10.4.19",
+        "eslint": "^9.0.0",
+        "eslint-config-next": "16.2.9",
+        "postcss": "^8.4.39",
+        "tailwindcss": "^3.4.6",
+        "typescript": "^5.5.3"
+    }
+}

adminsite/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+    plugins: {
+        tailwindcss: {},
+        autoprefixer: {},
+    },
+};

adminsite/tailwind.config.ts

@@ -0,0 +1,46 @@
+import type { Config } from "tailwindcss";
+
+/*
+ * Tokens are shared with site/ — same names, same values, copied verbatim into
+ * app/globals.css. Nothing here may hold a hex value: if a colour needs to
+ * change it changes in globals.css, in both apps, in one commit.
+ *
+ * The semantic three are aliased rather than renamed. site/ calls them up,
+ * down and pend because it shows monitor state; this app calls them valid,
+ * expired and warn because it shows licence state. Same colours, honest names
+ * on both sides.
+ */
+const config: Config = {
+    content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
+    theme: {
+        extend: {
+            colors: {
+                ground: "var(--ground)",
+                panel: "var(--panel)",
+                "panel-2": "var(--panel-2)",
+                ink: "var(--ink)",
+                "ink-2": "var(--ink-2)",
+                "ink-3": "var(--ink-3)",
+                rule: "var(--rule)",
+                "rule-soft": "var(--rule-soft)",
+                accent: "var(--accent)",
+                "accent-ink": "var(--accent-ink)",
+                "accent-wash": "var(--accent-wash)",
+                valid: "var(--up)",
+                warn: "var(--pend)",
+                expired: "var(--down)",
+                archival: "var(--ink-3)",
+            },
+            fontFamily: {
+                sans: ["ui-sans-serif", "system-ui", "-apple-system", "Segoe UI", "Roboto", "Helvetica Neue", "Arial", "sans-serif"],
+                mono: ["ui-monospace", "Cascadia Mono", "SF Mono", "JetBrains Mono", "Menlo", "Consolas", "monospace"],
+            },
+            // site/ uses 4px on panels and buttons, 2px on focus rings.
+            borderRadius: { DEFAULT: "4px" },
+            maxWidth: { rail: "1200px" },
+        },
+    },
+    plugins: [],
+};
+
+export default config;

adminsite/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

agent/internal/checker/checker.go

@@ -0,0 +1,222 @@
+package checker
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+
+const (
+	TypeHTTP = "http"
+	TypeTCP  = "tcp"
+	TypeICMP = "icmp"
+	TypeTLS  = "tls"
+)
+
+
+type Spec struct {
+	Type           string
+	URL            string
+	Host           string
+	Port           int
+	Method         string
+	ExpectedStatus int
+	Keyword        string
+	TLSWarnDays    int
+	Insecure       bool 
+	TimeoutSec     int
+}
+
+
+type Result struct {
+	Up         bool
+	LatencyMs  int
+	Message    string
+	CertExpiry *time.Time
+}
+
+func (s Spec) timeout() time.Duration {
+	t := s.TimeoutSec
+	if t <= 0 || t > 10 {
+		t = 10
+	}
+	return time.Duration(t) * time.Second
+}
+
+
+func Run(ctx context.Context, s Spec) Result {
+	switch s.Type {
+	case TypeHTTP:
+		return runHTTP(ctx, s)
+	case TypeTCP:
+		return runTCP(ctx, s)
+	case TypeICMP:
+		return runICMP(ctx, s)
+	case TypeTLS:
+		return runTLS(ctx, s)
+	default:
+		return Result{Message: "unknown check type: " + s.Type}
+	}
+}
+
+func runHTTP(ctx context.Context, s Spec) Result {
+	method := s.Method
+	if method == "" {
+		method = http.MethodGet
+	}
+	expect := s.ExpectedStatus
+	if expect == 0 {
+		expect = 200
+	}
+	client := &http.Client{Timeout: s.timeout()}
+	if s.Insecure {
+		client.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}} 
+	}
+	start := time.Now()
+	req, err := http.NewRequestWithContext(ctx, method, s.URL, nil)
+	if err != nil {
+		return Result{Message: err.Error()}
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return Result{LatencyMs: msSince(start), Message: err.Error()}
+	}
+	defer resp.Body.Close()
+	res := Result{LatencyMs: msSince(start), Up: true}
+	if resp.TLS != nil && len(resp.TLS.PeerCertificates) > 0 {
+		exp := resp.TLS.PeerCertificates[0].NotAfter
+		res.CertExpiry = &exp
+	}
+	if resp.StatusCode != expect {
+		return Result{LatencyMs: res.LatencyMs, CertExpiry: res.CertExpiry, Message: fmt.Sprintf("status %d (want %d)", resp.StatusCode, expect)}
+	}
+	if s.Keyword != "" {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+		if !strings.Contains(string(body), s.Keyword) {
+			return Result{LatencyMs: res.LatencyMs, CertExpiry: res.CertExpiry, Message: "keyword not found"}
+		}
+	}
+	return res
+}
+
+func runTCP(ctx context.Context, s Spec) Result {
+	addr := net.JoinHostPort(s.Host, fmt.Sprint(s.Port))
+	start := time.Now()
+	d := net.Dialer{Timeout: s.timeout()}
+	conn, err := d.DialContext(ctx, "tcp", addr)
+	if err != nil {
+		return Result{LatencyMs: msSince(start), Message: err.Error()}
+	}
+	conn.Close()
+	return Result{Up: true, LatencyMs: msSince(start)}
+}
+
+func runTLS(ctx context.Context, s Spec) Result {
+	port := s.Port
+	if port == 0 {
+		port = 443
+	}
+	addr := net.JoinHostPort(s.Host, fmt.Sprint(port))
+	start := time.Now()
+	d := net.Dialer{Timeout: s.timeout()}
+	conn, err := tls.DialWithDialer(&d, "tcp", addr, &tls.Config{ServerName: s.Host})
+	if err != nil {
+		return Result{LatencyMs: msSince(start), Message: err.Error()}
+	}
+	defer conn.Close()
+	certs := conn.ConnectionState().PeerCertificates
+	if len(certs) == 0 {
+		return Result{LatencyMs: msSince(start), Message: "no peer certificate"}
+	}
+	exp := certs[0].NotAfter
+	res := Result{LatencyMs: msSince(start), CertExpiry: &exp}
+	warn := s.TLSWarnDays
+	if warn <= 0 {
+		warn = 14
+	}
+	remaining := time.Until(exp)
+	if remaining <= 0 {
+		res.Message = "certificate expired"
+		return res
+	}
+	if remaining <= time.Duration(warn)*24*time.Hour {
+		res.Message = fmt.Sprintf("certificate expires in %d days", int(remaining.Hours()/24))
+		return res
+	}
+	res.Up = true
+	return res
+}
+
+func msSince(t time.Time) int { return int(time.Since(t).Milliseconds()) }
+
+
+
+
+func runICMP(ctx context.Context, s Spec) Result {
+	dst, err := net.ResolveIPAddr("ip4", s.Host)
+	if err != nil {
+		return Result{Message: err.Error()}
+	}
+	conn, err := net.ListenPacket("ip4:icmp", "0.0.0.0")
+	if err != nil {
+		return Result{Message: "icmp socket: " + err.Error()}
+	}
+	defer conn.Close()
+
+	id := os.Getpid() & 0xffff
+	pkt := icmpEcho(id, 1)
+	deadline := time.Now().Add(s.timeout())
+	if d, ok := ctx.Deadline(); ok && d.Before(deadline) {
+		deadline = d
+	}
+	_ = conn.SetDeadline(deadline)
+
+	start := time.Now()
+	if _, err := conn.WriteTo(pkt, dst); err != nil {
+		return Result{Message: err.Error()}
+	}
+	reply := make([]byte, 1500)
+	for {
+		n, peer, err := conn.ReadFrom(reply)
+		if err != nil {
+			return Result{LatencyMs: msSince(start), Message: "no reply"}
+		}
+		
+		if n < 28 || peer.String() != dst.String() {
+			continue
+		}
+		if reply[20] == 0 { 
+			return Result{Up: true, LatencyMs: msSince(start)}
+		}
+	}
+}
+
+func icmpEcho(id, seq int) []byte {
+	
+	b := []byte{8, 0, 0, 0, byte(id >> 8), byte(id), byte(seq >> 8), byte(seq)}
+	cs := icmpChecksum(b)
+	b[2] = byte(cs >> 8)
+	b[3] = byte(cs)
+	return b
+}
+
+func icmpChecksum(b []byte) uint16 {
+	var sum uint32
+	for i := 0; i < len(b)-1; i += 2 {
+		sum += uint32(b[i])<<8 | uint32(b[i+1])
+	}
+	if len(b)%2 == 1 {
+		sum += uint32(b[len(b)-1]) << 8
+	}
+	for sum>>16 != 0 {
+		sum = (sum & 0xffff) + (sum >> 16)
+	}
+	return ^uint16(sum)
+}

agent/internal/config/config.go

@@ -9,7 +9,7 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
-// ConfigDir returns the platform-specific config directory.
+
 func ConfigDir() string {
 	if runtime.GOOS == "windows" {
 		base := os.Getenv("ProgramData")

agent/internal/exec/exec.go

@@ -0,0 +1,164 @@
+package exec
+
+import (
+	"bufio"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
+)
+
+
+
+
+type streamWriter struct {
+	mu   sync.Mutex
+	seq  uint64
+	emit func(seq uint64, data []byte)
+}
+
+func (w *streamWriter) Write(p []byte) (int, error) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.emit != nil {
+		buf := make([]byte, len(p))
+		copy(buf, p)
+		w.emit(w.seq, buf)
+		w.seq++
+	}
+	return len(p), nil
+}
+
+
+
+func WorkspacePath(workspaceID string) string {
+	return filepath.Join(os.TempDir(), "vantage-run-"+workspaceID)
+}
+
+
+
+
+
+
+
+
+
+
+func RunStep(cmd *pb.RunStepCmd, emit func(seq uint64, data []byte)) *pb.StepResult {
+	res := &pb.StepResult{CommandId: "", OutputEnv: map[string]string{}}
+
+	dir, err := os.MkdirTemp("", "vantage-step-")
+	if err != nil {
+		res.ExitCode = 1
+		res.Stderr = "create temp dir: " + err.Error()
+		return res
+	}
+	defer os.RemoveAll(dir)
+
+	workDir := ""
+	if cmd.WorkspaceId != "" {
+		workDir = WorkspacePath(cmd.WorkspaceId)
+		if err := os.MkdirAll(workDir, 0700); err != nil {
+			res.ExitCode = 1
+			res.Stderr = "create workspace: " + err.Error()
+			return res
+		}
+	}
+
+	envFile := filepath.Join(dir, "workflow_env")
+	if err := os.WriteFile(envFile, nil, 0600); err != nil {
+		res.ExitCode = 1
+		res.Stderr = "create env file: " + err.Error()
+		return res
+	}
+
+	var scriptPath string
+	var c *exec.Cmd
+	timeout := time.Duration(cmd.TimeoutSeconds) * time.Second
+	if timeout <= 0 {
+		timeout = 30 * time.Minute
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+
+	switch cmd.Interpreter {
+	case "powershell":
+		scriptPath = filepath.Join(dir, "step.ps1")
+		if err := os.WriteFile(scriptPath, []byte(cmd.Script), 0600); err != nil {
+			res.ExitCode = 1
+			res.Stderr = err.Error()
+			return res
+		}
+		shell := "pwsh"
+		if runtime.GOOS == "windows" {
+			if _, err := exec.LookPath("pwsh"); err != nil {
+				shell = "powershell.exe"
+			}
+		}
+		c = exec.CommandContext(ctx, shell, "-NoProfile", "-NonInteractive", "-File", scriptPath)
+	default: 
+		scriptPath = filepath.Join(dir, "step.sh")
+		if err := os.WriteFile(scriptPath, []byte(cmd.Script), 0700); err != nil {
+			res.ExitCode = 1
+			res.Stderr = err.Error()
+			return res
+		}
+		c = exec.CommandContext(ctx, "bash", scriptPath)
+	}
+
+	if workDir != "" {
+		c.Dir = workDir
+	}
+
+	c.Env = append(os.Environ(), "WORKFLOW_ENV="+envFile)
+	for k, v := range cmd.Env {
+		c.Env = append(c.Env, k+"="+v)
+	}
+
+	sw := &streamWriter{emit: emit}
+	c.Stdout = sw
+	c.Stderr = sw
+	runErr := c.Run()
+
+	
+	if ctx.Err() == context.DeadlineExceeded {
+		res.ExitCode = 124
+		res.Stderr = "[vantage] step timed out"
+	} else if ee, ok := runErr.(*exec.ExitError); ok {
+		res.ExitCode = ee.ExitCode()
+	} else if runErr != nil {
+		res.ExitCode = 1
+		res.Stderr = "[vantage] " + runErr.Error()
+	}
+
+	res.OutputEnv = parseEnvFile(envFile)
+	return res
+}
+
+
+
+func parseEnvFile(path string) map[string]string {
+	out := map[string]string{}
+	f, err := os.Open(path)
+	if err != nil {
+		return out
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for sc.Scan() {
+		line := sc.Text()
+		i := strings.IndexByte(line, '=')
+		if i <= 0 {
+			continue
+		}
+		out[line[:i]] = line[i+1:]
+	}
+	return out
+}

agent/internal/grpc/client.go

@@ -27,8 +27,8 @@ func New(serverURL string, useTLS bool) (*Client, error) {
 	serverURL = strings.TrimPrefix(serverURL, "https://")
 	serverURL = strings.TrimPrefix(serverURL, "http://")
 
-	// Send a ping every 30s so proxies with a 60s idle timeout don't kill the
-	// long-lived CommandStream when no commands are flowing.
+	
+	
 	dialOpts := []grpc.DialOption{
 		grpc.WithKeepaliveParams(keepalive.ClientParameters{
 			Time:                30 * time.Second,
@@ -126,8 +126,32 @@ func (c *Client) ReportUpdates(serverID, agentToken string, updates []pb.Package
 	return err
 }
 
-// CommandStream opens a long-lived bidirectional stream for server-pushed commands.
-// The caller controls the stream lifetime via ctx.
+func (c *Client) ReportInventory(report *pb.InventoryReport) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	_, err := c.client.ReportInventory(ctx, report)
+	return err
+}
+
+func (c *Client) SyncMonitors(serverID, agentToken string) ([]pb.MonitorSpec, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	resp, err := c.client.SyncMonitors(ctx, &pb.SyncMonitorsRequest{ServerId: serverID, AgentToken: agentToken})
+	if err != nil {
+		return nil, err
+	}
+	return resp.Monitors, nil
+}
+
+func (c *Client) ReportChecks(serverID, agentToken string, results []pb.CheckResult) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	_, err := c.client.ReportChecks(ctx, &pb.ReportChecksRequest{ServerId: serverID, AgentToken: agentToken, Results: results})
+	return err
+}
+
+
+
 func (c *Client) CommandStream(ctx context.Context) (pb.Vantage_CommandStreamClient, error) {
 	return c.client.CommandStream(ctx)
 }

agent/internal/grpc/pb/vantage.pb.go

@@ -1,4 +1,4 @@
-// Hand-written gRPC bindings for vantage.proto (agent side, JSON codec).
+
 
 package pb
 
@@ -44,7 +44,7 @@ type UploadKeyResponse struct {
 	KeyId string `json:"key_id"`
 }
 
-// CommandStream message types
+
 
 type PackageUpdate struct {
 	Name           string `json:"name"`
@@ -60,14 +60,91 @@ type ReportUpdatesRequest struct {
 
 type ReportUpdatesResponse struct{}
 
+
+
+type CPUReport struct {
+	Model    string  `json:"model,omitempty"`
+	Cores    int     `json:"cores,omitempty"`
+	UsagePct float64 `json:"usage_pct"`
+	Load1    float64 `json:"load1,omitempty"`
+}
+type MemReport struct {
+	TotalBytes uint64 `json:"total_bytes"`
+	UsedBytes  uint64 `json:"used_bytes"`
+}
+type PartitionReport struct {
+	Device     string `json:"device"`
+	Mountpoint string `json:"mountpoint"`
+	Fstype     string `json:"fstype,omitempty"`
+	TotalBytes uint64 `json:"total_bytes"`
+	UsedBytes  uint64 `json:"used_bytes"`
+}
+type InventoryReport struct {
+	ServerId      string            `json:"server_id"`
+	AgentToken    string            `json:"agent_token"`
+	IncludeStatic bool              `json:"include_static"`
+	CPU           *CPUReport        `json:"cpu,omitempty"`
+	Memory        *MemReport        `json:"memory,omitempty"`
+	SwapTotal     uint64            `json:"swap_total"`
+	SwapUsed      uint64            `json:"swap_used"`
+	Partitions    []PartitionReport `json:"partitions,omitempty"`
+	Kernel        string            `json:"kernel,omitempty"`
+}
+type InventoryReportResponse struct{}
+
+
+
+type MonitorSpec struct {
+	MonitorId      string `json:"monitor_id"`
+	Type           string `json:"type"`
+	URL            string `json:"url,omitempty"`
+	Host           string `json:"host,omitempty"`
+	Port           int    `json:"port,omitempty"`
+	Method         string `json:"method,omitempty"`
+	ExpectedStatus int    `json:"expected_status,omitempty"`
+	Keyword        string `json:"keyword,omitempty"`
+	TLSWarnDays    int    `json:"tls_warn_days,omitempty"`
+	Insecure       bool   `json:"insecure,omitempty"`
+	IntervalSec    int    `json:"interval_sec"`
+	Retries        int    `json:"retries"`
+}
+type SyncMonitorsRequest struct {
+	ServerId   string `json:"server_id"`
+	AgentToken string `json:"agent_token"`
+}
+type SyncMonitorsResponse struct {
+	Monitors []MonitorSpec `json:"monitors,omitempty"`
+}
+type CheckResult struct {
+	MonitorId      string `json:"monitor_id"`
+	Up             bool   `json:"up"`
+	LatencyMs      int    `json:"latency_ms"`
+	Message        string `json:"message,omitempty"`
+	CertExpiryUnix int64  `json:"cert_expiry_unix,omitempty"`
+}
+type ReportChecksRequest struct {
+	ServerId   string        `json:"server_id"`
+	AgentToken string        `json:"agent_token"`
+	Results    []CheckResult `json:"results,omitempty"`
+}
+type ReportChecksResponse struct{}
+
 type ApplyUpdatesCmd struct{}
 
 type ServerCommand struct {
-	CommandId    string           `json:"command_id"`
-	GenerateKey  *GenerateKeyCmd  `json:"generate_key,omitempty"`
-	DeleteKey    *DeleteKeyCmd    `json:"delete_key,omitempty"`
-	UpdateAgent  *UpdateAgentCmd  `json:"update_agent,omitempty"`
-	ApplyUpdates *ApplyUpdatesCmd `json:"apply_updates,omitempty"`
+	CommandId        string               `json:"command_id"`
+	GenerateKey      *GenerateKeyCmd      `json:"generate_key,omitempty"`
+	DeleteKey        *DeleteKeyCmd        `json:"delete_key,omitempty"`
+	UpdateAgent      *UpdateAgentCmd      `json:"update_agent,omitempty"`
+	ApplyUpdates     *ApplyUpdatesCmd     `json:"apply_updates,omitempty"`
+	RunStep          *RunStepCmd          `json:"run_step,omitempty"`
+	CleanupWorkspace *CleanupWorkspaceCmd `json:"cleanup_workspace,omitempty"`
+}
+
+
+
+type CleanupWorkspaceCmd struct {
+	WorkspaceId string `json:"workspace_id"`
 }
 
 type DeleteKeyCmd struct {
@@ -88,10 +165,12 @@ type GenerateKeyCmd struct {
 }
 
 type AgentMessage struct {
-	ServerId   string         `json:"server_id"`
-	AgentToken string         `json:"agent_token"`
-	Ready      *AgentReady    `json:"ready,omitempty"`
-	Result     *CommandResult `json:"result,omitempty"`
+	ServerId   string            `json:"server_id"`
+	AgentToken string            `json:"agent_token"`
+	Ready      *AgentReady       `json:"ready,omitempty"`
+	Result     *CommandResult    `json:"result,omitempty"`
+	StepResult *StepResult       `json:"step_result,omitempty"`
+	StepOutput *StepOutputChunk  `json:"step_output,omitempty"`
 }
 
 type AgentReady struct{}
@@ -102,7 +181,32 @@ type CommandResult struct {
 	Message   string `json:"message"`
 }
 
-// CommandStream client-side interface
+type RunStepCmd struct {
+	Interpreter    string            `json:"interpreter"`
+	Script         string            `json:"script"`
+	Env            map[string]string `json:"env,omitempty"`
+	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
+	
+	
+	WorkspaceId string `json:"workspace_id,omitempty"`
+}
+
+type StepResult struct {
+	CommandId string            `json:"command_id"`
+	ExitCode  int               `json:"exit_code"`
+	Stdout    string            `json:"stdout,omitempty"`
+	Stderr    string            `json:"stderr,omitempty"`
+	OutputEnv map[string]string `json:"output_env,omitempty"`
+}
+
+type StepOutputChunk struct {
+	CommandId string `json:"command_id"`
+	Seq       uint64 `json:"seq"`
+	Data      []byte `json:"data,omitempty"`
+	Eof       bool   `json:"eof,omitempty"`
+}
+
+
 
 type Vantage_CommandStreamClient interface {
 	Send(*AgentMessage) error
@@ -126,7 +230,7 @@ func (c *vantageCommandStreamClient) Recv() (*ServerCommand, error) {
 	return m, nil
 }
 
-// CommandStream server-side interface (included for completeness)
+
 
 type Vantage_CommandStreamServer interface {
 	Send(*ServerCommand) error
@@ -155,6 +259,9 @@ type VantageClient interface {
 	SyncKeys(ctx context.Context, in *SyncRequest, opts ...grpc.CallOption) (*SyncResponse, error)
 	UploadGeneratedKey(ctx context.Context, in *UploadKeyRequest, opts ...grpc.CallOption) (*UploadKeyResponse, error)
 	ReportUpdates(ctx context.Context, in *ReportUpdatesRequest, opts ...grpc.CallOption) (*ReportUpdatesResponse, error)
+	ReportInventory(ctx context.Context, in *InventoryReport, opts ...grpc.CallOption) (*InventoryReportResponse, error)
+	SyncMonitors(ctx context.Context, in *SyncMonitorsRequest, opts ...grpc.CallOption) (*SyncMonitorsResponse, error)
+	ReportChecks(ctx context.Context, in *ReportChecksRequest, opts ...grpc.CallOption) (*ReportChecksResponse, error)
 	CommandStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_CommandStreamClient, error)
 }
 
@@ -210,6 +317,30 @@ func (c *keyManagerClient) ReportUpdates(ctx context.Context, in *ReportUpdatesR
 	return out, nil
 }
 
+func (c *keyManagerClient) ReportInventory(ctx context.Context, in *InventoryReport, opts ...grpc.CallOption) (*InventoryReportResponse, error) {
+	out := new(InventoryReportResponse)
+	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/ReportInventory", in, out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *keyManagerClient) SyncMonitors(ctx context.Context, in *SyncMonitorsRequest, opts ...grpc.CallOption) (*SyncMonitorsResponse, error) {
+	out := new(SyncMonitorsResponse)
+	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/SyncMonitors", in, out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *keyManagerClient) ReportChecks(ctx context.Context, in *ReportChecksRequest, opts ...grpc.CallOption) (*ReportChecksResponse, error) {
+	out := new(ReportChecksResponse)
+	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/ReportChecks", in, out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 func (c *keyManagerClient) CommandStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_CommandStreamClient, error) {
 	desc := &grpc.StreamDesc{StreamName: "CommandStream", ServerStreams: true, ClientStreams: true}
 	stream, err := c.cc.NewStream(ctx, desc, "/vantage.v1.Vantage/CommandStream", opts...)

agent/internal/inventory/collect_linux.go

@@ -0,0 +1,157 @@
+
+
+package inventory
+
+import (
+	"bufio"
+	"os"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
+)
+
+func collect(r *pb.InventoryReport, includeStatic bool) {
+	r.CPU.UsagePct = cpuUsage()
+	r.CPU.Load1 = load1()
+	memTotal, memAvail, swapTotal, swapFree := meminfo()
+	if memTotal > memAvail {
+		r.Memory.UsedBytes = memTotal - memAvail
+	}
+	if swapTotal > swapFree {
+		r.SwapUsed = swapTotal - swapFree
+	}
+	if includeStatic {
+		r.Memory.TotalBytes = memTotal
+		r.SwapTotal = swapTotal
+		r.CPU.Model, r.CPU.Cores = cpuStatic()
+		r.Kernel = kernel()
+		r.Partitions = partitions()
+	}
+}
+
+func readProc(path string) string { b, _ := os.ReadFile(path); return string(b) }
+
+func cpuSample() (idle, total uint64) {
+	f, err := os.Open("/proc/stat")
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	if sc.Scan() {
+		fields := strings.Fields(sc.Text()) 
+		for i, v := range fields[1:] {
+			n, _ := strconv.ParseUint(v, 10, 64)
+			total += n
+			if i == 3 { 
+				idle = n
+			}
+		}
+	}
+	return
+}
+
+func cpuUsage() float64 {
+	i1, t1 := cpuSample()
+	time.Sleep(100 * time.Millisecond)
+	i2, t2 := cpuSample()
+	dt := float64(t2 - t1)
+	if dt <= 0 {
+		return 0
+	}
+	return (1 - float64(i2-i1)/dt) * 100
+}
+
+func load1() float64 {
+	fields := strings.Fields(readProc("/proc/loadavg"))
+	if len(fields) > 0 {
+		v, _ := strconv.ParseFloat(fields[0], 64)
+		return v
+	}
+	return 0
+}
+
+func meminfo() (total, avail, swapTotal, swapFree uint64) {
+	f, err := os.Open("/proc/meminfo")
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		fields := strings.Fields(sc.Text())
+		if len(fields) < 2 {
+			continue
+		}
+		kb, _ := strconv.ParseUint(fields[1], 10, 64)
+		b := kb * 1024
+		switch strings.TrimSuffix(fields[0], ":") {
+		case "MemTotal":
+			total = b
+		case "MemAvailable":
+			avail = b
+		case "SwapTotal":
+			swapTotal = b
+		case "SwapFree":
+			swapFree = b
+		}
+	}
+	return
+}
+
+func cpuStatic() (model string, cores int) {
+	f, err := os.Open("/proc/cpuinfo")
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := sc.Text()
+		if strings.HasPrefix(line, "processor") {
+			cores++
+		} else if strings.HasPrefix(line, "model name") && model == "" {
+			if i := strings.Index(line, ":"); i >= 0 {
+				model = strings.TrimSpace(line[i+1:])
+			}
+		}
+	}
+	return
+}
+
+func kernel() string {
+	return strings.TrimSpace(readProc("/proc/sys/kernel/osrelease"))
+}
+
+func partitions() []pb.PartitionReport {
+	allowed := map[string]bool{"ext4": true, "xfs": true, "btrfs": true, "zfs": true, "vfat": true, "ntfs": true, "ext3": true}
+	f, err := os.Open("/proc/mounts")
+	if err != nil {
+		return nil
+	}
+	defer f.Close()
+	var out []pb.PartitionReport
+	seen := map[string]bool{}
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		fields := strings.Fields(sc.Text())
+		if len(fields) < 3 || !allowed[fields[2]] || seen[fields[1]] {
+			continue
+		}
+		seen[fields[1]] = true
+		var st syscall.Statfs_t
+		if syscall.Statfs(fields[1], &st) != nil {
+			continue
+		}
+		total := st.Blocks * uint64(st.Bsize)
+		free := st.Bavail * uint64(st.Bsize)
+		out = append(out, pb.PartitionReport{
+			Device: fields[0], Mountpoint: fields[1], Fstype: fields[2],
+			TotalBytes: total, UsedBytes: total - free,
+		})
+	}
+	return out
+}

agent/internal/inventory/collect_other.go

@@ -0,0 +1,12 @@
+//go:build !linux
+
+// Inventory collection is Linux-only. This no-op stands in everywhere else.
+//
+// The build constraint above is load-bearing: "_other" is not a GOOS suffix, so
+// without it this file compiles on Linux too and collides with collect_linux.go.
+package inventory
+
+import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
+
+
+func collect(r *pb.InventoryReport, includeStatic bool) {}

agent/internal/inventory/inventory.go

@@ -0,0 +1,11 @@
+package inventory
+
+import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
+
+
+
+func Collect(includeStatic bool) *pb.InventoryReport {
+	r := &pb.InventoryReport{IncludeStatic: includeStatic, CPU: &pb.CPUReport{}, Memory: &pb.MemReport{}}
+	collect(r, includeStatic)
+	return r
+}