fix: Fixed plans on admin site erroring

Two bugs, one symptom: signup created an account and a customer_user but
no verification email ever arrived.

net/smtp.SendMail only speaks STARTTLS. Against a port-465 server, which
expects a TLS handshake immediately, it never delivers. The transport now
wraps the connection before speaking SMTP on 465, exactly as
sitesvc/internal/mail already did — the two are duplicated, so change both
or consolidate into shared/. Also adds Date and Message-ID, whose absence
gets a message scored as spam, and a 15s deadline on the conversation.

The rollbacks ran on the HTTP request's context. A stalled mail server
holds the request until the browser gives up, which cancels that context
and turns both rollbacks into silent no-ops — stranding the exact rows
they exist to remove. They now run detached with their own timeout, and
log when they fail.

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

.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
@@ -35,3 +36,38 @@ jobs:
                     -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/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,104 @@
+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/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)
+	}
+	idxCancel()
+
+	reconcileCtx, stopReconcile := context.WithCancel(context.Background())
+	defer stopReconcile()
+	inject.StartReconciler(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,406 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"net/url"
+	"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/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"
+	"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
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"kind":       s.Kind,
+		"email":      s.Email,
+		"account_id": s.AccountID,
+	})
+}
+
+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
+	}
+
+	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/routes.go

@@ -0,0 +1,91 @@
+// 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"
+)
+
+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)
+
+	cust := r.Group("/api")
+	cust.Use(auth.RequireCustomer())
+	{
+		cust.GET("/account", getAccount)
+		cust.POST("/instances", 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("/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,488 @@
+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))
+	if err := auth.CreateCustomerUser(ctx, accountID, email, body.Password); 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,237 @@
+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 self-hosted customer login and emails
+// the verification link. Called during purchase (spec 5) and by staff.
+func CreateCustomerUser(ctx context.Context, accountID, email, password 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),
+		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
+}
+
+// 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); 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()
+
+	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},
+			"$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,60 @@
+package auth
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+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()
+	}
+}

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,85 @@
+// 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.
+// Changing the password on either side does not propagate, and they diverge from
+// that moment — accepted deliberately, because propagating a hash across two
+// services' databases is a worse problem than two passwords that started equal.
+//
+// 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
+}

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,122 @@
+// 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)
+		}
+	}
+	return nil
+}

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,214 @@
+// 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")
+}
+
+// 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 one does not change the other.\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/models.go

@@ -0,0 +1,182 @@
+// 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 a self-hosted customer's login. Cloud customers do not have
+// one — they authenticate against the control plane with credentials they
+// already hold.
+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:"-"`
+	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:"-"`
+	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,62 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { API_BASE, NotConnected, api } from "@/lib/api";
+import { NotConnectedPanel } from "@/components/NotConnected";
+import { formatDate } from "@/lib/format";
+
+export default function BillingPage() {
+    const { data, error, isLoading } = useQuery({
+        queryKey: ["subscriptions"],
+        queryFn: api.subscriptions,
+    });
+
+    if (error instanceof NotConnected) return <NotConnectedPanel url={API_BASE} />;
+    if (isLoading) return <p className="text-ink-3">Loading…</p>;
+
+    return (
+        <div className="grid gap-6">
+            <h1 className="text-3xl">Billing</h1>
+
+            {!data || data.length === 0 ? (
+                <p className="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.72rem] uppercase tracking-[0.08em] text-ink-3">
+                                <th className="px-4 py-2.5">Plan</th>
+                                <th className="px-4 py-2.5">Term</th>
+                                <th className="px-4 py-2.5">Status</th>
+                                <th className="px-4 py-2.5">Renews</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            {data.map((s) => (
+                                <tr
+                                    key={s.subscription_id}
+                                    className="border-b border-rule-soft last:border-0"
+                                >
+                                    <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>
+            )}
+
+            <p className="max-w-xl text-[0.82rem] text-ink-3">
+                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>
+        </div>
+    );
+}

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

@@ -0,0 +1,104 @@
+"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 { RelinkPanel } from "@/components/RelinkPanel";
+import { StatePill } from "@/components/StatePill";
+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));
+
+    return (
+        <div className="grid gap-8">
+            <header className="grid gap-3">
+                <div className="flex flex-wrap items-center gap-3">
+                    <h1 className="text-3xl">{instance.name}</h1>
+                    <StatePill state={state} />
+                </div>
+                <p className="font-mono text-[0.82rem] tabular-nums text-ink-3">
+                    {instance.instance_id}
+                </p>
+            </header>
+
+            {lic ? (
+                <>
+                    <dl className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+                        <Fact label="Tier" value={lic.tier.replace("_", " ")} />
+                        <Fact label="Expires" value={formatDate(lic.expires_at)} />
+                        <Fact label="Servers" value={limitLabel(lic.limits.max_servers)} />
+                        <Fact label="Features" value={lic.features.join(", ") || "none"} />
+                    </dl>
+
+                    {instance.deployment === "self_hosted" && (
+                        <>
+                            <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)}
+                            />
+                        </>
+                    )}
+                </>
+            ) : (
+                <p className="text-ink-2">No licence has been issued for this instance yet.</p>
+            )}
+        </div>
+    );
+}
+
+function Fact({ label, value }: { label: string; value: string }) {
+    return (
+        <div className="grid gap-1">
+            <dt className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
+                {label}
+            </dt>
+            <dd className="font-mono tabular-nums">{value}</dd>
+        </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,30 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useQueryClient } from "@tanstack/react-query";
+import { LinkForm } from "./LinkForm";
+
+export default function LinkPage() {
+    const router = useRouter();
+    const qc = useQueryClient();
+
+    return (
+        <div className="grid max-w-2xl gap-6">
+            <header className="grid gap-2">
+                <h1 className="text-3xl">Link an install</h1>
+                <p className="text-ink-2">
+                    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.
+                </p>
+            </header>
+            <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 one does not
+                change the other afterwards.
+            </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,20 @@
+import type { Metadata } from "next";
+import { CreateForm } from "./CreateForm";
+
+export const metadata: Metadata = { title: "New instance" };
+
+export default function NewInstancePage() {
+    return (
+        <div className="grid gap-6">
+            <header className="grid gap-2">
+                <h1 className="text-3xl">Create a free instance</h1>
+                <p className="max-w-prose text-ink-2">
+                    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.
+                </p>
+            </header>
+            <CreateForm />
+        </div>
+    );
+}

adminsite/app/(customer)/layout.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import Link from "next/link";
+import { RequireKind } from "@/lib/session";
+
+export default function CustomerLayout({ children }: { children: React.ReactNode }) {
+    return (
+        <RequireKind kind="customer">
+            <nav className="border-b border-rule-soft bg-panel-2">
+                <div className="mx-auto flex max-w-rail flex-wrap gap-5 px-5 py-2.5 font-mono text-[0.72rem] uppercase tracking-[0.06em]">
+                    <Link href="/" className="text-accent">
+                        Overview
+                    </Link>
+                    <Link href="/instances/link" className="text-ink-3">
+                        Link an install
+                    </Link>
+                    <Link href="/billing" className="text-ink-3">
+                        Billing
+                    </Link>
+                </div>
+            </nav>
+            <main className="mx-auto max-w-rail px-5 py-8">{children}</main>
+        </RequireKind>
+    );
+}

adminsite/app/(customer)/page.tsx

@@ -0,0 +1,97 @@
+"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 { InstanceCard } from "@/components/InstanceCard";
+
+export default function OverviewPage() {
+    const { data, error, isLoading } = useQuery({ queryKey: ["account"], queryFn: api.account });
+
+    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 unlinked = data.instances.filter((i) => i.status === "awaiting_link");
+
+    return (
+        <div className="grid gap-8">
+            <header className="grid gap-2">
+                <h1 className="text-3xl">{data.account.name}</h1>
+                <p className="text-ink-2">{data.account.billing_email}</p>
+            </header>
+
+            {unlinked.length > 0 && (
+                <div className="rounded border border-accent bg-accent-wash p-4">
+                    <h2 className="text-xl">Finish setting up your licence</h2>
+                    <p className="mt-1 text-[0.82rem] text-ink-2">
+                        {unlinked.length === 1
+                            ? "One purchase is"
+                            : `${unlinked.length} purchases are`}{" "}
+                        not attached to an install yet, so no licence has been issued for{" "}
+                        {unlinked.length === 1 ? "it" : "them"}.
+                    </p>
+                    <Link
+                        href="/instances/link"
+                        className="mt-2 inline-block text-[0.82rem] font-semibold text-accent underline"
+                    >
+                        Link an install
+                    </Link>
+                </div>
+            )}
+
+            {data.instances.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>
+                    <Link
+                        href="/instances/new"
+                        className="justify-self-start rounded bg-accent px-4 py-2 text-[0.9rem] font-semibold text-accent-ink"
+                    >
+                        Create a free instance
+                    </Link>
+                </div>
+            ) : (
+                <section className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+                    {data.instances.map((i) => (
+                        <InstanceCard
+                            key={i.instance_id}
+                            instance={i}
+                            license={byInstance.get(i.instance_id)}
+                        />
+                    ))}
+                </section>
+            )}
+
+            {data.instances.length > 0 &&
+                !data.instances.some(
+                    (i) => i.tier === "free" && i.status !== "cancelled" && i.status !== "deleted",
+                ) && (
+                    <Link
+                        href="/instances/new"
+                        className="justify-self-start text-[0.82rem] font-semibold text-accent underline"
+                    >
+                        Create a free instance
+                    </Link>
+                )}
+        </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,109 @@
+"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";
+
+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">
+            <header className="grid gap-1">
+                <h1 className="text-3xl">{data.account.name}</h1>
+                <p className="font-mono text-[0.82rem] text-ink-3">
+                    {data.account.billing_email} · {data.account.account_id}
+                </p>
+            </header>
+
+            <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,10 @@
+import { AccountSearch } from "./AccountSearch";
+
+export default function AccountsPage() {
+    return (
+        <div className="grid gap-6">
+            <h1 className="text-3xl">Accounts</h1>
+            <AccountSearch />
+        </div>
+    );
+}

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

@@ -0,0 +1,48 @@
+"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";
+
+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">
+            <h1 className="text-3xl">Audit</h1>
+            <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,69 @@
+"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 { 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">
+            <header className="grid gap-2">
+                <h1 className="text-3xl">{data.instance.name || data.instance.instance_id}</h1>
+                <p className="font-mono text-[0.82rem] tabular-nums text-ink-3">
+                    {data.instance.instance_id}
+                </p>
+                <p className="text-[0.82rem]">
+                    <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>
+                </p>
+                {data.injection.applicable && inj && (
+                    <p className={clsx("font-mono text-[0.72rem]", inj.tone)}>{inj.label}</p>
+                )}
+            </header>
+
+            <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 Link from "next/link";
+import { RequireKind } from "@/lib/session";
+
+const LINKS = [
+    ["/staff", "Operations"],
+    ["/staff/accounts", "Accounts"],
+    ["/staff/licenses", "Licences"],
+    ["/staff/plans", "Plans"],
+    ["/staff/audit", "Audit"],
+] as const;
+
+export default function StaffLayout({ children }: { children: React.ReactNode }) {
+    return (
+        <RequireKind kind="staff">
+            <nav className="border-b border-rule-soft bg-panel-2">
+                <div className="mx-auto flex max-w-rail flex-wrap gap-5 px-5 py-2.5 font-mono text-[0.72rem] uppercase tracking-[0.06em]">
+                    {LINKS.map(([href, label]) => (
+                        <Link key={href} href={href} className="text-ink-3 hover:text-accent">
+                            {label}
+                        </Link>
+                    ))}
+                </div>
+            </nav>
+            <main className="mx-auto max-w-rail px-5 py-8">{children}</main>
+        </RequireKind>
+    );
+}

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

@@ -0,0 +1,96 @@
+"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";
+
+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">
+            <h1 className="text-3xl">Licences</h1>
+            <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,81 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { API_BASE, NotConnected, api } from "@/lib/api";
+import { NotConnectedPanel } from "@/components/NotConnected";
+import { Queue } from "@/components/Queue";
+import { daysRemaining } 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" }),
+    });
+
+    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,
+    );
+
+    return (
+        <div className="grid gap-6">
+            <h1 className="text-3xl">Operations</h1>
+            <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+                <Queue
+                    title="Failed injections"
+                    tone="expired"
+                    count={injection.data?.count ?? 0}
+                    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>
+        </div>
+    );
+}

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

@@ -0,0 +1,127 @@
+"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";
+
+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">
+            <h1 className="text-3xl">Plans</h1>
+
+            {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/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,30 @@
+import type { Metadata } from "next";
+import "./globals.css";
+import { Providers } from "@/components/Providers";
+import { EnvBadge } from "@/components/EnvBadge";
+
+export const metadata: Metadata = {
+    title: "Vantage Licensing",
+    description: "Licences, instances and billing for Vantage.",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+    return (
+        <html lang="en">
+            <body>
+                <header className="border-b border-rule bg-panel">
+                    <div className="mx-auto flex max-w-rail flex-wrap items-center justify-between gap-4 px-5 py-4">
+                        <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">
+                                Licensing
+                            </span>
+                        </span>
+                        <EnvBadge />
+                    </div>
+                </header>
+                <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,62 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { useSearchParams } from "next/navigation";
+import Link from "next/link";
+import { Suspense } from "react";
+import { api } from "@/lib/api";
+
+function Verify() {
+    const token = useSearchParams().get("token") ?? "";
+    const { data, error, isLoading } = useQuery({
+        queryKey: ["verify", token],
+        queryFn: () => api.verify(token),
+        enabled: token !== "",
+        retry: false,
+    });
+
+    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/Button.tsx

@@ -0,0 +1,25 @@
+import clsx from "clsx";
+
+type Props = React.ButtonHTMLAttributes<HTMLButtonElement> & { 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 Button({ variant = "solid", className, ...rest }: Props) {
+    return (
+        <button
+            {...rest}
+            className={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",
+                rest.disabled && "cursor-not-allowed border-rule bg-panel text-ink-3 hover:brightness-100",
+                className,
+            )}
+        />
+    );
+}

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/InstanceCard.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+import Link from "next/link";
+import clsx from "clsx";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { api, type Instance, type License } from "@/lib/api";
+import { daysRemaining, formatDate, licenceState } from "@/lib/format";
+import { StatePill } from "./StatePill";
+
+const STRIPE = {
+    valid: "before:bg-valid",
+    warn: "before:bg-warn",
+    expired: "before:bg-expired",
+    none: "before:bg-accent",
+} as const;
+
+export function InstanceCard({
+    instance,
+    license,
+    reapAfterDays,
+}: {
+    instance: Instance;
+    license?: License;
+    reapAfterDays?: number;
+}) {
+    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 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;
+
+    return (
+        <article
+            className={clsx(
+                "relative grid gap-3 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 items-start justify-between gap-3">
+                <div>
+                    <h3 className="text-lg">{instance.name || "Unnamed instance"}</h3>
+                    <p className="font-mono text-[0.72rem] uppercase tracking-[0.1em] text-ink-3">
+                        {cloud ? "Cloud" : "Self-hosted"}
+                        {instance.tier ? ` · ${instance.tier.replace("_", " ")}` : ""}
+                    </p>
+                </div>
+                <StatePill state={state} />
+            </div>
+
+            {state === "expired" && (
+                <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>
+            )}
+
+            {state === "expired" && 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>
+            )}
+
+            {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>
+            )}
+
+            {license && state !== "expired" && (
+                <div className="grid gap-1 font-mono text-[0.82rem] tabular-nums text-ink-2">
+                    <span>{days} days remaining</span>
+                    <div className="h-[3px] 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>
+                    <span>Renews {formatDate(license.expires_at)}</span>
+                </div>
+            )}
+
+            <div className="flex flex-wrap items-center gap-3">
+                {state === "none" ? (
+                    <Link
+                        href="/instances/link"
+                        className="justify-self-start text-[0.82rem] font-semibold text-accent underline"
+                    >
+                        Link an install
+                    </Link>
+                ) : cloud && instance.slug ? (
+                    <a
+                        href={`https://${instance.slug}.vantage.hostxtra.co.uk`}
+                        className="justify-self-start text-[0.82rem] font-semibold text-accent underline"
+                    >
+                        Open {instance.slug}.vantage.hostxtra.co.uk
+                    </a>
+                ) : (
+                    <Link
+                        href={`/instances/${instance.instance_id}`}
+                        className="justify-self-start text-[0.82rem] font-semibold text-accent underline"
+                    >
+                        {state === "expired" ? "Renew and download" : "Licence and download"}
+                    </Link>
+                )}
+
+                {canRenew && (
+                    <button
+                        type="button"
+                        onClick={() => renew.mutate()}
+                        disabled={renew.isPending}
+                        className="justify-self-start rounded bg-accent px-3 py-1.5 text-[0.82rem] font-semibold text-accent-ink"
+                    >
+                        {renew.isPending ? "Renewing…" : "Renew"}
+                    </button>
+                )}
+            </div>
+        </article>
+    );
+}

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/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/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,227 @@
+/*
+ * 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 });
+
+// --- types ---------------------------------------------------------------
+
+export type Deployment = "cloud" | "self_hosted";
+export type Tier = "free" | "professional" | "self_hosted";
+export type InstanceStatus = "awaiting_link" | "active" | "lapsed" | "cancelled" | "deleted";
+
+export interface Session {
+    kind: "staff" | "customer";
+    email: string;
+    account_id?: 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 }>(`/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"),
+
+    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/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

@@ -1,7 +1,3 @@
-// Package checker runs service checks (http/tcp/icmp/tls) and returns a uniform
-// Result. It has no dependency on models or pb so it can be duplicated verbatim
-// into the agent module (agent-run monitors) — callers map their own monitor
-// representation onto Spec.
 package checker
 
 import (
@@ -16,7 +12,7 @@ import (
 	"time"
 )
 
-// Check types (mirror models.Monitor* constants).
+
 const (
 	TypeHTTP = "http"
 	TypeTCP  = "tcp"
@@ -24,7 +20,7 @@ const (
 	TypeTLS  = "tls"
 )
 
-// Spec is a self-contained description of a single check.
+
 type Spec struct {
 	Type           string
 	URL            string
@@ -34,11 +30,11 @@ type Spec struct {
 	ExpectedStatus int
 	Keyword        string
 	TLSWarnDays    int
-	Insecure       bool // skip TLS certificate verification (HTTP checks)
+	Insecure       bool 
 	TimeoutSec     int
 }
 
-// Result is the uniform outcome of running a check.
+
 type Result struct {
 	Up         bool
 	LatencyMs  int
@@ -54,7 +50,7 @@ func (s Spec) timeout() time.Duration {
 	return time.Duration(t) * time.Second
 }
 
-// Run executes the check described by s.
+
 func Run(ctx context.Context, s Spec) Result {
 	switch s.Type {
 	case TypeHTTP:
@@ -81,7 +77,7 @@ func runHTTP(ctx context.Context, s Spec) Result {
 	}
 	client := &http.Client{Timeout: s.timeout()}
 	if s.Insecure {
-		client.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}} //nolint:gosec // opt-in per monitor
+		client.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}} 
 	}
 	start := time.Now()
 	req, err := http.NewRequestWithContext(ctx, method, s.URL, nil)
@@ -160,9 +156,9 @@ func runTLS(ctx context.Context, s Spec) Result {
 
 func msSince(t time.Time) int { return int(time.Since(t).Milliseconds()) }
 
-// runICMP sends a single ICMP echo request and waits for the reply. Requires
-// raw-socket privileges (the agent and server run as root). Returns down with a
-// descriptive message when the socket cannot be opened or no reply arrives.
+
+
+
 func runICMP(ctx context.Context, s Spec) Result {
 	dst, err := net.ResolveIPAddr("ip4", s.Host)
 	if err != nil {
@@ -192,18 +188,18 @@ func runICMP(ctx context.Context, s Spec) Result {
 		if err != nil {
 			return Result{LatencyMs: msSince(start), Message: "no reply"}
 		}
-		// Skip the IPv4 header (20 bytes) to reach the ICMP message.
+		
 		if n < 28 || peer.String() != dst.String() {
 			continue
 		}
-		if reply[20] == 0 { // ICMP echo reply type
+		if reply[20] == 0 { 
 			return Result{Up: true, LatencyMs: msSince(start)}
 		}
 	}
 }
 
 func icmpEcho(id, seq int) []byte {
-	// Type(8)=echo request, Code=0, Checksum, ID, Seq, no payload.
+	
 	b := []byte{8, 0, 0, 0, byte(id >> 8), byte(id), byte(seq >> 8), byte(seq)}
 	cs := icmpChecksum(b)
 	b[2] = byte(cs >> 8)

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

@@ -14,9 +14,9 @@ import (
 	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
 )
 
-// streamWriter forwards every write to emit() as an ordered chunk. Used as both
-// Stdout and Stderr so output interleaves in real execution order. The mutex
-// ensures a single stdout/stderr write is not interleaved mid-slice with another.
+
+
+
 type streamWriter struct {
 	mu   sync.Mutex
 	seq  uint64
@@ -35,21 +35,21 @@ func (w *streamWriter) Write(p []byte) (int, error) {
 	return len(p), nil
 }
 
-// WorkspacePath returns the per-run working directory for a workspace id. The
-// same id always maps to the same path so RunStep and the cleanup command agree.
+
+
 func WorkspacePath(workspaceID string) string {
 	return filepath.Join(os.TempDir(), "vantage-run-"+workspaceID)
 }
 
-// RunStep writes the script to a temp file, provides a WORKFLOW_ENV file for
-// the script to append KEY=value output to, executes it under the requested
-// interpreter, and streams output via emit, returning the terminal result
-// with empty stdout/stderr but populated exit_code/output_env.
-//
-// When the command carries a WorkspaceId the step runs with that per-run working
-// directory as its cwd (created here if missing); the server removes it once the
-// run finishes. The script and env files always live in a private temp dir so
-// they never leak into the shared workspace.
+
+
+
+
+
+
+
+
+
 func RunStep(cmd *pb.RunStepCmd, emit func(seq uint64, data []byte)) *pb.StepResult {
 	res := &pb.StepResult{CommandId: "", OutputEnv: map[string]string{}}
 
@@ -102,7 +102,7 @@ func RunStep(cmd *pb.RunStepCmd, emit func(seq uint64, data []byte)) *pb.StepRes
 			}
 		}
 		c = exec.CommandContext(ctx, shell, "-NoProfile", "-NonInteractive", "-File", scriptPath)
-	default: // "bash"
+	default: 
 		scriptPath = filepath.Join(dir, "step.sh")
 		if err := os.WriteFile(scriptPath, []byte(cmd.Script), 0700); err != nil {
 			res.ExitCode = 1
@@ -126,7 +126,7 @@ func RunStep(cmd *pb.RunStepCmd, emit func(seq uint64, data []byte)) *pb.StepRes
 	c.Stderr = sw
 	runErr := c.Run()
 
-	// stdout/stderr are streamed via emit, not returned in the result.
+	
 	if ctx.Err() == context.DeadlineExceeded {
 		res.ExitCode = 124
 		res.Stderr = "[vantage] step timed out"
@@ -141,8 +141,8 @@ func RunStep(cmd *pb.RunStepCmd, emit func(seq uint64, data []byte)) *pb.StepRes
 	return res
 }
 
-// parseEnvFile reads KEY=value lines (last write wins). Blank lines and lines
-// without '=' are ignored.
+
+
 func parseEnvFile(path string) map[string]string {
 	out := map[string]string{}
 	f, err := os.Open(path)

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,
@@ -150,8 +150,8 @@ func (c *Client) ReportChecks(serverID, agentToken string, results []pb.CheckRes
 	return err
 }
 
-// CommandStream opens a long-lived bidirectional stream for server-pushed commands.
-// The caller controls the stream lifetime via ctx.
+
+
 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,7 +60,7 @@ type ReportUpdatesRequest struct {
 
 type ReportUpdatesResponse struct{}
 
-// Inventory report message types
+
 
 type CPUReport struct {
 	Model    string  `json:"model,omitempty"`
@@ -92,7 +92,7 @@ type InventoryReport struct {
 }
 type InventoryReportResponse struct{}
 
-// Monitor sync / check report message types
+
 
 type MonitorSpec struct {
 	MonitorId      string `json:"monitor_id"`
@@ -141,8 +141,8 @@ type ServerCommand struct {
 	CleanupWorkspace *CleanupWorkspaceCmd `json:"cleanup_workspace,omitempty"`
 }
 
-// CleanupWorkspaceCmd tells the agent to recursively remove the run's working
-// directory once all steps on that server have finished.
+
+
 type CleanupWorkspaceCmd struct {
 	WorkspaceId string `json:"workspace_id"`
 }
@@ -186,8 +186,8 @@ type RunStepCmd struct {
 	Script         string            `json:"script"`
 	Env            map[string]string `json:"env,omitempty"`
 	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
-	// WorkspaceId names the per-run working directory the agent creates and uses
-	// as the step's cwd. Empty means run in the agent's default directory.
+	
+	
 	WorkspaceId string `json:"workspace_id,omitempty"`
 }
 
@@ -206,7 +206,7 @@ type StepOutputChunk struct {
 	Eof       bool   `json:"eof,omitempty"`
 }
 
-// CommandStream client-side interface
+
 
 type Vantage_CommandStreamClient interface {
 	Send(*AgentMessage) error
@@ -230,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

agent/internal/inventory/collect_linux.go

@@ -1,4 +1,4 @@
-//go:build linux
+
 
 package inventory
 
@@ -42,11 +42,11 @@ func cpuSample() (idle, total uint64) {
 	defer f.Close()
 	sc := bufio.NewScanner(f)
 	if sc.Scan() {
-		fields := strings.Fields(sc.Text()) // cpu user nice system idle iowait ...
+		fields := strings.Fields(sc.Text()) 
 		for i, v := range fields[1:] {
 			n, _ := strconv.ParseUint(v, 10, 64)
 			total += n
-			if i == 3 { // idle
+			if i == 3 { 
 				idle = n
 			}
 		}

agent/internal/inventory/collect_other.go

@@ -1,8 +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"
 
-// collect is a no-op best-effort stub on non-Linux platforms.
+
 func collect(r *pb.InventoryReport, includeStatic bool) {}

agent/internal/inventory/inventory.go

@@ -2,8 +2,8 @@ package inventory
 
 import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
 
-// Collect gathers metrics always and static hardware info when includeStatic.
-// Platform specifics are provided by collect_linux.go / collect_other.go.
+
+
 func Collect(includeStatic bool) *pb.InventoryReport {
 	r := &pb.InventoryReport{IncludeStatic: includeStatic, CPU: &pb.CPUReport{}, Memory: &pb.MemReport{}}
 	collect(r, includeStatic)

agent/internal/keys/keys.go

@@ -96,16 +96,16 @@ func fingerprint(pubKey string) string {
 	return "MD5:" + strings.Join(pairs, ":")
 }
 
-// KeyGenOptions controls how ssh-keygen is invoked.
+
 type KeyGenOptions struct {
-	KeyType    string // ed25519 (default), rsa, ecdsa
-	KeySize    int    // bits; used for rsa and ecdsa
-	Passphrase string // empty = no passphrase
-	Comment    string // embedded in the public key
+	KeyType    string 
+	KeySize    int    
+	Passphrase string 
+	Comment    string 
 }
 
-// GenerateKeyPair generates an SSH keypair and returns the public key.
-// The private key is written to keyPath; keyPath+".pub" holds the public key.
+
+
 func GenerateKeyPair(keyPath string, opts KeyGenOptions) (string, error) {
 	if err := os.MkdirAll(filepath.Dir(keyPath), 0700); err != nil {
 		return "", err
@@ -139,8 +139,8 @@ func GenerateKeyPair(keyPath string, opts KeyGenOptions) (string, error) {
 	return strings.TrimSpace(string(pubData)), nil
 }
 
-// AddSSHIdentity writes an IdentityFile entry for keyPath into the managed
-// vantage.conf include file, and ensures ~/.ssh/config includes it.
+
+
 func AddSSHIdentity(keyPath string) error {
 	if err := os.MkdirAll(filepath.Dir(sshConfigPath), 0700); err != nil {
 		return fmt.Errorf("mkdir .ssh: %w", err)
@@ -150,7 +150,7 @@ func AddSSHIdentity(keyPath string) error {
 		return err
 	}
 
-	// Read existing managed config (it may not exist yet).
+	
 	var existing string
 	data, err := os.ReadFile(managedConfigPath)
 	if err != nil && !os.IsNotExist(err) {
@@ -161,7 +161,7 @@ func AddSSHIdentity(keyPath string) error {
 	line := "IdentityFile " + keyPath
 	for _, l := range strings.Split(existing, "\n") {
 		if strings.TrimSpace(l) == line {
-			return nil // already present
+			return nil 
 		}
 	}
 
@@ -176,7 +176,7 @@ func AddSSHIdentity(keyPath string) error {
 	return nil
 }
 
-// RemoveSSHIdentity removes the IdentityFile entry for keyPath from the managed config.
+
 func RemoveSSHIdentity(keyPath string) error {
 	data, err := os.ReadFile(managedConfigPath)
 	if os.IsNotExist(err) {
@@ -204,9 +204,9 @@ func RemoveSSHIdentity(keyPath string) error {
 	return nil
 }
 
-// ensureIncludeDirective adds "Include /root/.ssh/vantage.conf" to the top
-// of ~/.ssh/config if it is not already present. The Include must appear before
-// any Host stanzas to be effective for all connections.
+
+
+
 func ensureIncludeDirective() error {
 	data, err := os.ReadFile(sshConfigPath)
 	if err != nil && !os.IsNotExist(err) {
@@ -215,11 +215,11 @@ func ensureIncludeDirective() error {
 
 	for _, l := range strings.Split(string(data), "\n") {
 		if strings.TrimSpace(l) == includeDirective {
-			return nil // already present
+			return nil 
 		}
 	}
 
-	// Prepend the Include directive so it takes effect before any Host blocks.
+	
 	updated := includeDirective + "\n" + string(data)
 	if err := os.WriteFile(sshConfigPath, []byte(updated), 0600); err != nil {
 		return fmt.Errorf("write %s: %w", sshConfigPath, err)

agent/internal/monitors/monitors.go

@@ -1,6 +1,6 @@
-// Package monitors runs agent-side service checks. It polls the server for the
-// monitors assigned to this agent (SyncMonitors), runs each on its own interval
-// using the local checker package, and reports results back (ReportChecks).
+
+
+
 package monitors
 
 import (
@@ -15,7 +15,7 @@ import (
 	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
 )
 
-// syncInterval controls how often the agent re-fetches its assigned monitors.
+
 const syncInterval = 30 * time.Second
 
 type runner struct {
@@ -23,13 +23,13 @@ type runner struct {
 	cancel      context.CancelFunc
 }
 
-// Run starts the agent monitor loop and blocks until ctx is cancelled.
+
 func Run(ctx context.Context, cfg *config.Config) {
 	active := map[string]*runner{}
 	var mu sync.Mutex
 
-	// results is a shared channel every check writes to; a single reporter
-	// goroutine batches and ships them so we make one ReportChecks call per tick.
+	
+	
 	results := make(chan pb.CheckResult, 64)
 	go reporter(ctx, cfg, results)
 
@@ -128,7 +128,7 @@ func runSpec(ctx context.Context, s pb.MonitorSpec, out chan<- pb.CheckResult) {
 	}
 }
 
-// reporter batches results on a short interval and ships each batch in one call.
+
 func reporter(ctx context.Context, cfg *config.Config, in <-chan pb.CheckResult) {
 	t := time.NewTicker(5 * time.Second)
 	defer t.Stop()

agent/internal/sync/sync.go

@@ -34,7 +34,7 @@ func Run(ctx context.Context, cfg *config.Config, version string) error {
 	}
 	defer client.Close()
 
-	// Register if we have a pre-reg token
+	
 	if cfg.PreRegToken != "" {
 		log.Println("registering with server...")
 		hostname, _ := os.Hostname()
@@ -61,25 +61,25 @@ func Run(ctx context.Context, cfg *config.Config, version string) error {
 	}
 
 	if cfg.AgentToken == "" {
-		return fmt.Errorf("no agent token available — registration required")
+		return fmt.Errorf("no agent token available registration required")
 	}
 
-	// Start the command stream alongside the poll loop.
+	
 	go runCommandStream(ctx, cfg)
 
-	// Check for OS updates on startup and then hourly.
+	
 	go runUpdateCheck(ctx, cfg)
 
-	// Report host inventory: metrics every 30s, full static snapshot every 15 min.
+	
 	go runInventory(ctx, cfg)
 
-	// Run agent-side service monitors assigned to this server.
+	
 	go monitors.Run(ctx, cfg)
 
 	ticker := time.NewTicker(cfg.PollInterval)
 	defer ticker.Stop()
 
-	// Run immediately on startup
+	
 	if err := poll(client, cfg, version); err != nil {
 		log.Printf("poll error: %v", err)
 	}
@@ -102,7 +102,6 @@ func poll(client *grpcclient.Client, cfg *config.Config, version string) error {
 		return fmt.Errorf("SyncKeys: %w", err)
 	}
 
-	// Windows agents register and heartbeat only — no authorized_keys management.
 	if runtime.GOOS != "linux" {
 		return nil
 	}
@@ -124,8 +123,8 @@ func poll(client *grpcclient.Client, cfg *config.Config, version string) error {
 	return nil
 }
 
-// runCommandStream maintains a persistent bidirectional stream with the server
-// for instant command delivery. Reconnects with exponential backoff on failure.
+
+
 func runCommandStream(ctx context.Context, cfg *config.Config) {
 	backoff := time.Second
 	const maxBackoff = 2 * time.Minute
@@ -178,9 +177,9 @@ func connectAndHandleStream(ctx context.Context, cfg *config.Config) error {
 
 	log.Println("command stream connected")
 
-	// grpc streams are not safe for concurrent Send; RunStep results are sent
-	// from per-command goroutines, so all sends on this stream must go through
-	// this mutex-protected helper.
+	
+	
+	
 	var sendMu sync.Mutex
 	send := func(msg *pb.AgentMessage) error {
 		sendMu.Lock()
@@ -220,7 +219,7 @@ func connectAndHandleStream(ctx context.Context, cfg *config.Config) error {
 				}
 				res := agentexec.RunStep(rc, emit)
 				res.CommandId = cid
-				// Final eof marker so the server closes the log file.
+				
 				_ = send(&pb.AgentMessage{
 					ServerId:   cfg.ServerID,
 					AgentToken: cfg.AgentToken,
@@ -280,8 +279,8 @@ func runUpdateCheck(ctx context.Context, cfg *config.Config) {
 	}
 }
 
-// runInventory reports host metrics every 30s and a full static snapshot every
-// 15 min (and once immediately on startup so static fields populate without delay).
+
+
 func runInventory(ctx context.Context, cfg *config.Config) {
 	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
 	if err != nil {
@@ -299,7 +298,7 @@ func runInventory(ctx context.Context, cfg *config.Config) {
 		}
 	}
 
-	report(true) // full snapshot on startup
+	report(true) 
 	ticker := time.NewTicker(30 * time.Second)
 	defer ticker.Stop()
 	tick := 0
@@ -309,7 +308,7 @@ func runInventory(ctx context.Context, cfg *config.Config) {
 			return
 		case <-ticker.C:
 			tick++
-			report(tick%30 == 0) // every 30th tick = 15 min → include static
+			report(tick%30 == 0) 
 		}
 	}
 }
@@ -322,7 +321,7 @@ func handleApplyUpdates(cfg *config.Config, cmd *pb.ServerCommand) {
 	}
 	log.Printf("OS updates applied successfully (cmd=%s)", cmd.CommandId)
 
-	// Re-report the (now empty) update list so the server reflects the new state.
+	
 	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
 	if err != nil {
 		return
@@ -364,21 +363,21 @@ func handleUpdateAgent(cmd *pb.ServerCommand) {
 	}
 
 	u := cmd.UpdateAgent
-	arch := runtime.GOARCH // "amd64" or "arm64"
+	arch := runtime.GOARCH 
 	tag := "agent%2Fv" + u.Version
 	binaryURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/vantage-agent-linux-%s", u.GiteaBaseURL, tag, arch)
 	checksumURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/checksums.txt", u.GiteaBaseURL, tag)
 
 	log.Printf("updating agent to v%s from %s (cmd=%s)", u.Version, u.GiteaBaseURL, cmd.CommandId)
 
-	// Download binary
+	
 	tmpBin := "/tmp/vantage-agent-update"
 	if err := downloadFile(binaryURL, tmpBin); err != nil {
 		log.Printf("update download failed (cmd=%s): %v", cmd.CommandId, err)
 		return
 	}
 
-	// Download and verify checksum
+	
 	checksumData, err := httpGetBytes(checksumURL)
 	if err != nil {
 		log.Printf("update checksum fetch failed (cmd=%s): %v", cmd.CommandId, err)
@@ -403,11 +402,11 @@ func handleUpdateAgent(cmd *pb.ServerCommand) {
 	exec.Command("systemctl", "restart", "vantage-agent").Run()
 }
 
-// handleUpdateAgentWindows downloads the latest MSI and launches msiexec to
-// perform a MajorUpgrade. msiexec is started DETACHED (via "cmd /c start") so
-// that when the upgrade stops the VantageAgent service, nssm's process-tree
-// kill of this agent does not also kill the installer mid-flight. Config
-// (server_id, agent_token) is preserved by setup.ps1 on upgrade.
+
+
+
+
+
 func handleUpdateAgentWindows(cmd *pb.ServerCommand) {
 	u := cmd.UpdateAgent
 	tag := "agent%2Fv" + u.Version
@@ -435,8 +434,8 @@ func handleUpdateAgentWindows(cmd *pb.ServerCommand) {
 
 	logPath := filepath.Join(os.TempDir(), "vantage-agent-msi.log")
 	log.Printf("launching msiexec for upgrade to v%s (cmd=%s)", u.Version, cmd.CommandId)
-	// "start" detaches msiexec from this process tree so the service stop
-	// during the upgrade does not terminate the installer.
+	
+	
 	up := exec.Command("cmd", "/c", "start", "", "/wait", "msiexec", "/i", msiPath, "/qn", "/norestart", "/l*v", logPath)
 	if err := up.Start(); err != nil {
 		log.Printf("failed to launch msiexec (cmd=%s): %v", cmd.CommandId, err)
@@ -445,7 +444,7 @@ func handleUpdateAgentWindows(cmd *pb.ServerCommand) {
 }
 
 func downloadFile(url, dest string) error {
-	resp, err := http.Get(url) //nolint:gosec
+	resp, err := http.Get(url) 
 	if err != nil {
 		return err
 	}
@@ -463,7 +462,7 @@ func downloadFile(url, dest string) error {
 }
 
 func httpGetBytes(url string) ([]byte, error) {
-	resp, err := http.Get(url) //nolint:gosec
+	resp, err := http.Get(url) 
 	if err != nil {
 		return nil, err
 	}
@@ -555,7 +554,7 @@ func localIP() string {
 	return ""
 }
 
-// GenerateAndUpload generates an SSH keypair and uploads the public key to the server.
+
 func GenerateAndUpload(cfg *config.Config, label string) error {
 	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
 	if err != nil {

agent/internal/updates/updates.go

@@ -27,8 +27,8 @@ func detectPM() string {
 	return ""
 }
 
-// CheckAvailable returns the list of packages with available upgrades.
-// Returns nil, nil when no supported package manager is found.
+
+
 func CheckAvailable() ([]PackageUpdate, error) {
 	switch detectPM() {
 	case "apt":
@@ -48,11 +48,11 @@ func CheckAvailable() ([]PackageUpdate, error) {
 	}
 }
 
-// ApplyAll runs a full non-interactive upgrade using the detected package manager.
+
 func ApplyAll() error {
 	switch detectPM() {
 	case "apt":
-		// Refresh lists first, then upgrade.
+		
 		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
 		defer cancel()
 		if err := exec.CommandContext(ctx, "apt-get", "update", "-qq").Run(); err != nil {
@@ -77,8 +77,8 @@ func ApplyAll() error {
 func checkApt() ([]PackageUpdate, error) {
 	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
 	defer cancel()
-	// Best-effort refresh; ignore errors (cached data is fine).
-	exec.CommandContext(ctx, "apt-get", "update", "-qq").Run() //nolint:errcheck
+	
+	exec.CommandContext(ctx, "apt-get", "update", "-qq").Run() 
 
 	out, err := exec.Command("apt", "list", "--upgradable").Output()
 	if err != nil {
@@ -88,7 +88,7 @@ func checkApt() ([]PackageUpdate, error) {
 	scanner := bufio.NewScanner(bytes.NewReader(out))
 	for scanner.Scan() {
 		line := scanner.Text()
-		// Format: package/suite version arch [upgradable from: old-ver]
+		
 		if !strings.Contains(line, "[upgradable from:") {
 			continue
 		}
@@ -111,7 +111,6 @@ func checkApt() ([]PackageUpdate, error) {
 func checkDnfYum(pm string) ([]PackageUpdate, error) {
 	cmd := exec.Command(pm, "check-update")
 	out, err := cmd.Output()
-	// Exit code 100 means updates are available — not an error.
 	if exitErr, ok := err.(*exec.ExitError); ok && exitErr.ExitCode() == 100 {
 		err = nil
 	}
@@ -133,7 +132,7 @@ func checkDnfYum(pm string) ([]PackageUpdate, error) {
 		if len(parts) < 2 {
 			continue
 		}
-		// name.arch  new-version  repo
+		
 		name := strings.SplitN(parts[0], ".", 2)[0]
 		updates = append(updates, PackageUpdate{Name: name, NewVersion: parts[1]})
 	}
@@ -146,7 +145,7 @@ func checkPacman() ([]PackageUpdate, error) {
 	scanner := bufio.NewScanner(bytes.NewReader(out))
 	for scanner.Scan() {
 		parts := strings.Fields(scanner.Text())
-		// Format: package old-version -> new-version
+		
 		if len(parts) < 4 {
 			continue
 		}
@@ -164,7 +163,7 @@ func checkZypper() ([]PackageUpdate, error) {
 	scanner := bufio.NewScanner(bytes.NewReader(out))
 	for scanner.Scan() {
 		line := scanner.Text()
-		// Data rows start with "v |" (available) or "i |" (installed but updatable).
+		
 		if !strings.HasPrefix(line, "v |") && !strings.HasPrefix(line, "i |") {
 			continue
 		}

claude.md

@@ -1,34 +1,38 @@
 # Vantage
 
-A self-hosted SSH key management system. A central server (Go + Next.js + MongoDB) manages public key assignments across servers. A lightweight Go agent runs on each managed server, polls the central server via gRPC, and atomically rewrites `/root/.ssh/authorized_keys` to match the desired state.
+A self-hosted, multi-tenant infrastructure control plane. It started as SSH key management and has grown into fleet management: SSH key assignment, workflow/script execution, service monitoring, a secrets vault, a browser console (SSH/RDP/VNC), and OS update management.
+
+A central server (Go + Next.js + MongoDB + Redis) drives a lightweight Go agent installed on each managed server. Agents poll over gRPC and also hold a bidirectional command stream for push-style commands.
 
 ---
 
 ## Architecture Overview
 
 ```
-┌─────────────────────────────────┐
-│  Next.js Frontend               │
-│  - Upload/manage keys           │
-│  - Add servers (install script) │
-│  - Assign/revoke per server     │
-└────────────┬────────────────────┘
-             │ REST
-┌────────────▼────────────────────┐
-│  Go Backend                     │
-│  - REST API for frontend        │
-│  - gRPC server for agents       │
-│  - MongoDB                      │
-└────────────┬────────────────────┘
-             │ gRPC (TLS)
-┌────────────▼────────────────────┐
-│  Go Agent (per server)          │
-│  - Polls every 30s              │
-│  - Rewrites authorized_keys     │
-│  - Can generate SSH keypairs    │
-└─────────────────────────────────┘
+┌──────────────────────────────────────────────┐
+│  Next.js 16 Frontend (web, :3000)            │
+│  servers · keys · workflows · monitors       │
+│  secrets · audit · console · settings        │
+└───────────────┬──────────────────────────────┘
+                │ REST + cookie session
+┌───────────────▼──────────────────────────────┐
+│  Go Backend (server)                         │
+│  :8080 REST (gin)   :9090 gRPC (agents)      │
+│  MongoDB (state) · Redis (sessions)          │
+│  monitor scheduler · workflow runner         │
+│  guacd tunnel proxy for browser console      │
+└───────────────┬──────────────────────────────┘
+                │ gRPC (TLS) — outbound from agent only
+┌───────────────▼──────────────────────────────┐
+│  Go Agent (per server, Linux + Windows)      │
+│  polls SyncKeys · CommandStream              │
+│  rewrites authorized_keys (Linux only)       │
+│  runs workflow steps · monitors · inventory  │
+└──────────────────────────────────────────────┘
 ```
 
+Multi-tenancy: every domain document carries `org_id`, and every service query is scoped by it. Org is resolved from the session, and optionally cross-checked against the request host (`<slug>.vantage.<tld>`).
+
 ---
 
 ## Repository Structure
@@ -36,143 +40,303 @@ A self-hosted SSH key management system. A central server (Go + Next.js + MongoD
 ```
 vantage/
 ├── agent/
-│   ├── cmd/main.go
+│   ├── cmd/main.go                  # flags: -generate-key
 │   └── internal/
-│       ├── config/
-│       ├── grpc/
-│       ├── keys/
-│       └── sync/
+│       ├── checker/                 # monitor check execution
+│       ├── config/                  # config.yaml load/save
+│       ├── exec/                    # workflow step execution
+│       ├── grpc/                    # client + generated pb
+│       ├── inventory/               # CPU/mem/disk collection (linux/other)
+│       ├── keys/                    # authorized_keys read/diff/write
+│       ├── monitors/                # agent-run monitor loop
+│       ├── sync/                    # poll loop + command stream
+│       └── updates/                 # OS package update check/apply
 ├── server/
 │   ├── cmd/main.go
 │   └── internal/
-│       ├── api/          # REST handlers for Next.js
-│       ├── grpc/         # gRPC server implementation
-│       ├── models/       # MongoDB models
-│       └── services/
-│           ├── keys.go
-│           ├── servers.go
-│           └── sync.go   # builds desired state per server
-├── web/
-│   ├── app/
-│   └── components/
-├── proto/
-│   └── vantage/v1/vantage.proto
-├── deploy/
-│   ├── docker-compose.yml
-│   └── agent.service
-└── .gitea/
-    └── workflows/
-        ├── agent-release.yml
-        └── server-deploy.yml
+│       ├── api/                     # REST handlers
+│       ├── auth/                    # local, OIDC, session, middleware, orghost
+│       ├── checker/                 # server-run monitor checks
+│       ├── db/                      # mongo connect + Col()
+│       ├── grpc/                    # gRPC server + generated pb
+│       ├── models/                  # MongoDB documents
+│       ├── monitorsched/            # server-side monitor scheduler
+│       ├── notify/                  # smtp, http, templating, dispatch
+│       └── services/                # business logic + migrations
+├── web/                             # the application UI (authenticated)
+│   ├── app/(app)/                   # authed routes
+│   ├── app/login, app/setup         # unauthed routes
+│   ├── components/                  # ui/, workflows/, monitors/, Sidebar
+│   └── lib/                         # api client, guac console, query client
+├── site/                            # public marketing site
+│   ├── app/                         # one directory per route
+│   ├── components/                  # Nav, Footer, Logo, InstrumentPanel, forms
+│   ├── assets/                      # image sources, not served
+│   └── Dockerfile                   # same shape as web/: standalone, node, 3000
+├── sitesvc/                         # public form: contact mail only
+│   ├── cmd/main.go
+│   └── internal/
+│       ├── api/                     # contact
+│       ├── mail/                    # SMTP
+│       └── store/                   # Mongo connect helper
+├── admin/                           # licensing authority: the only signer
+│   ├── cmd/main.go                  # boot: two Mongo connections, reconciler, HTTP
+│   ├── cmd/adminctl/                # staff-add; deliberately has no HTTP surface
+│   └── internal/
+│       ├── api/                     # customer + staff handlers, route table
+│       ├── auth/                    # staff, HQ customer and cloud-owner sessions
+│       ├── inject/                  # licence write path into the control plane
+│       ├── cloudprov/               # instance write path: creates instances + owners
+│       ├── licensing/               # Issue, LinkInstance, Relink
+│       ├── mail/                    # verification and licence delivery
+│       └── models/                  # accounts, instances, licences, plans
+├── adminsite/                       # staff + customer console (vantage-hq)
+│   ├── app/(customer)/              # overview, instance, link, billing
+│   ├── app/(staff)/staff/           # operations, accounts, licences, plans, audit
+│   ├── components/                  # InstanceCard, Ledger, Queue, EnvBadge
+│   └── lib/                         # api client, session guards, formatters
+├── shared/                          # imported by server, sitesvc and admin
+│   ├── license/                     # payload, sign, verify, trusted keys, plans
+│   ├── models/                      # Instance, User, Settings
+│   └── cmd/lkctl/                   # issue and inspect licences by hand
+├── proto/vantage/v1/vantage.proto
+├── installer/                       # Windows: setup.ps1, nssm.exe, WiX .wxs
+├── deploy/                          # docker-compose.yml, agent.service
+└── .gitea/workflows/                # agent-release.yml, server-deploy.yml
 ```
 
 ---
 
+## Subsystems
+
+### SSH keys
+
+Upload a public key, assign it per server, revoke softly. The agent diffs desired vs on-disk state and rewrites `/root/.ssh/authorized_keys` atomically. Keys can also be generated _on_ a server by the agent; the private half can optionally be uploaded and is stored AES-256-GCM encrypted.
+
+### Workflows
+
+A library of reusable **steps** (bash or PowerShell scripts with declared inputs, outputs, and secret refs) composed into **workflows** targeting a set of servers. Running one snapshots the resolved steps into a `WorkflowRun`, then dispatches `RunStepCmd` over the agent command stream. Step stdout/stderr streams back as `StepOutputChunk` and is written to a log file on disk; the UI streams it live. Steps support `on_failure: stop|continue|retry`, per-run env passed between steps via `output_env`, and a per-run workspace directory the agent cleans up at the end.
+
+Default steps are seeded per org at boot (`SeedDefaultSteps`). Logs are swept by retention (`workflow_log_retention_days`; nil = 30 days, 0 = forever).
+
+### Monitors
+
+HTTP, TCP, ICMP and TLS checks. Each monitor has a `runner`: `"server"` (executed by the server-side scheduler) or a `server_id` (pushed to that agent, which runs it locally and reports results). Consecutive failures beyond `retries` flip state to `down`, open an `Incident`, and notify. Hourly `Rollup` documents back the uptime graphs.
+
+### Notification channels
+
+Per-org outbound destinations: `webhook`, `smtp`, `discord`, `slack`, `telegram`. Monitors reference channels by ID. Channels are testable from the UI.
+
+### Secrets vault
+
+Key/value pairs grouped by name, encrypted at rest with AES-256-GCM. Consumed two ways: referenced by workflow steps via `secret_refs` (injected as env at execution), and read by Kubernetes External Secrets Operator via `GET /api/secrets/:group/values` using a bearer token whose SHA-256 hash is stored in settings.
+
+### Browser console
+
+`POST /api/console/connect` mints a one-time session token; `GET /api/console/tunnel` upgrades to a WebSocket and proxies to **guacd** (Apache Guacamole daemon) using `github.com/wwt/guac`. SSH connections authenticate with a stored private key; RDP/VNC credentials are encrypted, single-use, and consumed when the tunnel opens.
+
+### Inventory and OS updates
+
+Agents report CPU/memory/swap/partitions/kernel — metrics every 30s, full static snapshot every 15 min. They also check for pending OS package updates hourly and can apply them on command (`ApplyUpdatesCmd`).
+
+### Agent self-update
+
+`UpdateAgentCmd` carries a target version and Gitea base URL; the agent downloads and replaces itself.
+
+### Marketing site and sitesvc
+
+`site/` is a separate Next.js app built exactly like `web/` — `output: "standalone"`, run by Node in a `node:26-alpine` image, listening on `3000` and published as `3003`. The contact form posts to `sitesvc`; account signup posts to `admin` (`NEXT_PUBLIC_ADMIN_API_URL`), which creates an HQ account, not an org — the control plane is not touched until the customer later creates a cloud instance from the portal.
+
+`adminsite/` is built the same way and published as `3004`, served at **`vantage-hq.hostxtra.co.uk`** — deliberately *outside* `*.vantage.hostxtra.co.uk`, because that namespace is per-tenant instance subdomains and `APP_ROOT_LABEL` resolves an org from the label before `vantage`. It shares `site/`'s design tokens verbatim (see Frontend below) and, unlike `web/`, does **not** proxy through a Next rewrite: the browser calls `admin` directly, so `ADMIN_API_URL` must be browser-reachable. Authenticated requests work cross-origin only because both hosts share the registrable domain `hostxtra.co.uk`, which keeps `admin_session`'s `SameSite=Lax` cookie in play.
+
+**`ADMIN_ORIGIN` must list every browser origin that calls admin — currently two**: `https://vantage-hq.hostxtra.co.uk` for the console, and `https://vantage.hostxtra.co.uk` because the marketing site's `/start` form posts account signups to admin directly. It is comma-separated. A missing origin does not produce a 403: `cors()` simply omits the `Access-Control-Allow-Origin` header and still answers the preflight `204`, so the browser blocks the request and **admin logs nothing at all**. Symptom is a CORS preflight failure on an endpoint that works fine under curl.
+
+`sitesvc/` (port `8082`) now owns only the contact flow:
+
+| Form    | Endpoint             | Effect                                                                  |
+| ------- | --------------------- | ----------------------------------------------------------------------- |
+| Contact | `POST /api/contact`   | Emails `support@hostxtra.co.uk`, `Reply-To` the sender. Nothing stored. |
+
+Account signup lives in `admin` instead (`POST /auth/signup`, `GET /auth/verify?token=…`) — see Signup and verification below.
+
+`site`, `sitesvc` and `admin` are deliberately **excluded from the self-hosted deployment**: `deploy/docker-compose.yml` mentions none of them, and they live in `deploy/docker-compose.site.yml` instead.
+
+```bash
+# self-hosted install — no marketing site, no sitesvc
+docker compose up -d
+
+# vantage.hostxtra.co.uk — control plane plus the public site
+docker compose -f docker-compose.yml -f docker-compose.site.yml up -d
+```
+
+### Signup and verification
+
+Signup is **account-first**: it creates an HQ account and an unverified `customer_user` in admin's own database, nothing in the control plane. Only after a customer later creates a cloud instance from the portal (`POST /api/instances`, see Admin REST API) does an org, or rather an `instance`, come to exist — provisioned by `cloudprov`, with the owner's password hash copied from the HQ user rather than shared. `site_pending_signups` is gone; sitesvc no longer has a signup flow at all.
+
+- The token is 32 random bytes; only its **SHA-256 hash** is stored, so a leaked database yields no working links.
+- Links expire after 24 hours (`VerifyWindow`).
+- An unverified sign-in gets a distinct "check your email" error rather than the generic auth failure, because the address is already known to be theirs.
+- If sending the verification email fails, the freshly inserted `customer_user` (and account, on first signup) is rolled back rather than left stranded holding the unique index on email.
+- Rate limited per client IP, plus a honeypot field.
+
+### Shared provisioning
+
+`shared/provision` (`instance.go`, `slug.go`, `user.go`) holds the slug rules, reserved names and instance/user creation logic that both `server` and `admin/internal/cloudprov` need, so there is no longer a second copy to drift: `cloudprov.CreateInstance` calls straight into it to create a control-plane instance and its owner from a customer request.
+
+---
+
+## Auth and Orgs
+
+- **Bootstrap** — first run has no users. `GET /auth/bootstrap-status` drives `/setup`, `POST /auth/bootstrap` creates the first org plus its owner.
+- **Local auth** — email + password (bcrypt), `POST /auth/login`.
+- **OIDC** — configured _per org_ (`org_oidc`), issuer + client ID + encrypted client secret. `/auth/oidc/start` → `/auth/oidc/callback`.
+- **Sessions** — opaque 32-byte hex ID in the `km_session` cookie, session body stored in Redis with a 24h TTL.
+- **Roles** — `owner`, `admin`, `member`. `/api/settings` and `/api/org/*` require owner or admin.
+- **Host/org guard** — `APP_ROOT_LABEL` (default `vantage`) defines the app root label. A request to `<slug>.vantage.<tld>` resolves that org from the slug and rejects sessions belonging to a different one. Org lookups are cached for 60s.
+
+Unique indexes are a **security property**, not an optimisation. `users` is
+unique on `(instance_id, email)` — one address is one user *within* an instance,
+and the same address may hold a user in several instances, because an account's
+people are projected into each instance they are granted. This is sufficient only
+because **every lookup by email is scoped by instance**; there is deliberately no
+unscoped lookup anywhere, and adding one would let the login path return an
+arbitrary one of several matching users. Instance slug, settings instance and ESO
+token hash remain globally unique.
+
+---
+
 ## gRPC API
 
 ```protobuf
-syntax = "proto3";
-package vantage.v1;
-
 service Vantage {
-  rpc Register(RegisterRequest)           returns (RegisterResponse);
-  rpc SyncKeys(SyncRequest)               returns (SyncResponse);
-  rpc UploadGeneratedKey(UploadKeyRequest) returns (UploadKeyResponse);
-}
-
-message RegisterRequest {
-  string server_id      = 1;
-  string pre_reg_token  = 2;
-  string hostname       = 3;
-  string ip_address     = 4;
-  string os_info        = 5;
-}
-message RegisterResponse {
-  string agent_token = 1;
-}
-
-message SyncRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-}
-message SyncResponse {
-  repeated string public_keys = 1; // full authorized_keys lines
-}
-
-message UploadKeyRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-  string public_key  = 3;
-  string label       = 4;
-}
-message UploadKeyResponse {
-  string key_id = 1;
+  rpc Register(RegisterRequest)              returns (RegisterResponse);
+  rpc SyncKeys(SyncRequest)                  returns (SyncResponse);
+  rpc UploadGeneratedKey(UploadKeyRequest)   returns (UploadKeyResponse);
+  rpc ReportUpdates(ReportUpdatesRequest)    returns (ReportUpdatesResponse);
+  rpc ReportInventory(InventoryReport)       returns (InventoryReportResponse);
+  rpc SyncMonitors(SyncMonitorsRequest)      returns (SyncMonitorsResponse);
+  rpc ReportChecks(ReportChecksRequest)      returns (ReportChecksResponse);
+  rpc CommandStream(stream AgentMessage)     returns (stream ServerCommand);
 }
 ```
 
-No streaming — polling only. Poll interval: **30 seconds**.
+`CommandStream` is the only streaming RPC: the agent authenticates once with `AgentReady`, then the server pushes `ServerCommand`s and the agent replies with `CommandResult`, `StepResult`, or `StepOutputChunk`.
+
+`ServerCommand` variants: `GenerateKeyCmd`, `DeleteKeyCmd`, `UpdateAgentCmd`, `ApplyUpdatesCmd`, `RunStepCmd`, `CleanupWorkspaceCmd`.
+
+Key-state polling stays on the 30s `SyncKeys` interval. Full message definitions live in `proto/vantage/v1/vantage.proto`.
 
 ---
 
+## REST API
+
+Unauthenticated:
+
+```
+GET  /install            /install.ps1        # dynamic agent install scripts
+GET  /update             /update.ps1
+GET  /auth/bootstrap-status
+POST /auth/bootstrap     /auth/login  /auth/logout
+GET  /auth/me            /auth/oidc/start    /auth/oidc/callback
+GET  /api/secrets/:group/values               # bearer token (ESO)
+```
+
+Session-authed under `/api`:
+
+```
+servers      GET,POST /servers · GET,POST /servers/new · GET,DELETE /servers/:id
+             POST /servers/:id/{generate-key,update-agent,apply-updates}
+keys         GET,POST /keys · GET,DELETE /keys/:id · GET /keys/:id/private-key
+             POST /keys/:id/assign · DELETE /keys/:id/assign/:serverId
+workflows    GET,POST /steps · PUT,DELETE /steps/:id · GET /steps/:id/export
+             POST /steps/{import,seed-defaults,parse} · GET /steps/usage
+             GET,POST /workflows · GET,PUT,DELETE /workflows/:id
+             POST /workflows/:id/run · GET /workflows/:id/runs
+             GET /runs/:runId · POST /runs/:runId/cancel
+             GET /runs/:runId/servers/:serverId/logs[/stream]
+monitors     GET,POST /monitors · GET,PUT,DELETE /monitors/:id
+             GET /monitors/:id/{incidents,uptime}
+channels     GET,POST /channels · PUT,DELETE /channels/:id · POST /channels/:id/test
+secrets      GET,POST /secrets · GET,PUT,DELETE /secrets/:group
+             POST /secrets/:group/reveal · DELETE /secrets/:group/:key
+console      POST /console/connect · GET /console/tunnel (websocket)
+audit        GET /audit
+agent        GET /agent/latest-version
+settings     GET,PUT /settings · POST /settings/secrets-token       (owner|admin)
+org          GET,POST /org/users · PUT /org/users/:id/role · DELETE /org/users/:id
+             GET,PUT /org/oidc                                       (owner|admin)
+```
+
+---
+
+## Admin REST API (`admin`, :8083)
+
+A separate service with its own session cookie (`admin_session`) and its own database. Unauthenticated:
+
+```
+GET  /healthz
+GET  /auth/me                                  # who am I; 401 drives the UI's redirects
+POST /auth/staff/login   /auth/login  /auth/logout
+POST /auth/signup                              # self-hosted only; honeypot + rate limited
+GET  /auth/verify?token=…
+```
+
+Customer-session (`/api`), every instance resolved through `ownedInstance`:
+
+```
+GET  /account                                  # account, instances, max_relinks
+POST /instances                                # create a cloud instance (Free tier, capped at one per account)
+POST /instances/:id/renew                      # Free renewal; refuses outside the renewal window
+POST /instances/link · /instances/:id/relink
+GET  /instances/:id/license · /instances/:id/license/download
+GET  /subscriptions
+```
+
+Staff-session (`/api/staff`):
+
+```
+GET,POST /accounts · GET /accounts/:id         # search by name, email, Paddle ID or instance UUID
+GET,POST /instances · GET /instances/:id       # instance + account + licence history + injection state
+POST /instances/:id/issue · /instances/:id/relink
+GET  /licenses · /subscriptions · /audit · /plans · PUT /plans/:tier
+GET  /health/injection
+```
+
+**Customer endpoints answer 404, never 403, for another account's resource** — a 403 confirms the resource exists. Route-group guards in `adminsite/` mirror this, but the backend is the layer that matters.
+
 ## MongoDB Collections
 
-### `servers`
+`servers` · `keys` · `assignments` · `orgs` · `users` · `org_oidc` · `settings` · `secrets` · `workflows` · `workflow_steps` · `workflow_runs` · `monitors` · `incidents` · `monitor_rollups` · `notification_channels` · `console_sessions` · `audit_logs` · `migrations`
 
-```json
-{
-    "_id": "ObjectId",
-    "server_id": "uuid",
-    "hostname": "proxmox-node-1",
-    "ip_address": "10.10.10.5",
-    "os_info": "Ubuntu 24.04",
-    "pre_reg_token": "abc123",
-    "pre_reg_expires": "ISODate",
-    "agent_token_hash": "sha256...",
-    "status": "pending|active|offline",
-    "last_seen": "ISODate",
-    "created_at": "ISODate"
-}
-```
+Every document except `migrations` carries `org_id`. Struct definitions are the source of truth — see `server/internal/models/`.
 
-- `pre_reg_token` is cleared after the agent successfully calls `Register()`
-- `agent_token_hash` stores SHA-256 of the token — never plaintext
-- `status` transitions: `pending` → `active` on first `Register()`, `offline` if last_seen exceeds threshold
+Notes that are not obvious from the structs:
 
-### `keys`
+- `servers.agent_token_hash` stores SHA-256 of the token, never plaintext. `pre_reg_token` is cleared after `Register()`. `status` is `pending` → `active` on register, `offline` when `last_seen` passes the threshold (swept every 2 min).
+- `servers.inventory` holds the latest metrics snapshot with separate `metrics_at` / `static_at` timestamps.
+- `keys.private_key_enc` and `passphrase_enc` are AES-256-GCM; the JSON form exposes only `has_private_key` / `has_passphrase`.
+- `assignments.revoked_at: null` means active. Revocation is soft, preserving audit history.
+- `workflow_runs.steps_snapshot` freezes the resolved steps so editing the library never rewrites history.
+- `console_sessions.token_consumed_at` is set atomically to enforce one-time use.
+- `users.auth_source` is `local`, `oidc` or `hq`. An `hq` user was projected from a Vantage HQ account and carries `hq_user_id`; HQ owns its role, password and existence.
 
-```json
-{
-    "_id": "ObjectId",
-    "key_id": "uuid",
-    "label": "dom-macbook",
-    "public_key": "ssh-ed25519 AAAA...",
-    "fingerprint": "SHA256:...",
-    "source": "uploaded|generated",
-    "generated_by_server_id": "uuid",
-    "created_at": "ISODate"
-}
-```
+### Migrations
 
-### `assignments`
+`services.RunMigrations()` runs at boot, recording markers in `migrations`:
 
-```json
-{
-    "_id": "ObjectId",
-    "key_id": "uuid",
-    "server_id": "uuid",
-    "assigned_at": "ISODate",
-    "revoked_at": "ISODate | null"
-}
-```
+- `0001_default_org_backfill`
+- `0002_settings_org_backfill` (must run before 0003 — 0003 can create a `default` org, which pushes 0002 into its ambiguous multi-org branch)
+- `0003_missed_org_scopes`
 
-- `revoked_at: null` = key is active on that server
-- Revocation is soft — set `revoked_at`, agent picks it up on next poll
+Index builders (`EnsureAuthIndexes`, `EnsureSettingsIndexes`) are fatal on failure; `EnsureSecretIndexes` and `EnsureWorkflowIndexes` only warn.
 
 ---
 
 ## Agent Lifecycle
 
-### Config file — `/etc/vantage/config.yaml`
+### Config file
+
+Linux `/etc/vantage/config.yaml`, Windows `%ProgramData%\vantage\config.yaml`. Directory `0700`, file `0600`.
 
 ```yaml
 server_url: "vantage.yourdomain.com:9090"
@@ -183,117 +347,132 @@ poll_interval: 30s
 tls: true
 ```
 
-Config file permissions: `0600`. Config directory: `0700`.
-
-### Startup flow
+### Startup
 
 ```
 1. Load config
-2. If pre_reg_token present:
-     → call Register(server_id, pre_reg_token, hostname, ip, os_info)
-     → save returned agent_token to config
-     → delete pre_reg_token from config
-3. Enter poll loop
+2. If pre_reg_token present → Register() → save agent_token, clear pre_reg_token, reconnect
+3. Start goroutines: command stream · update check (hourly) · inventory · monitors
+4. Enter SyncKeys poll loop (default 30s)
 ```
 
-### Poll loop (every 30s)
+### Poll loop
 
 ```
-1. Call SyncKeys(server_id, agent_token)
-2. Receive []public_keys
-3. Compute fingerprints of current /root/.ssh/authorized_keys
-4. If state unchanged → skip write
-5. If changed:
-     → write to /root/.ssh/authorized_keys.tmp
-     → os.Rename() to /root/.ssh/authorized_keys  (atomic)
-     → chmod 0600
+1. SyncKeys(server_id, agent_token, agent_version)
+2. Non-Linux hosts stop here — Windows agents register and heartbeat only
+3. Diff desired keys against /root/.ssh/authorized_keys; unchanged → no write
+4. Changed → write .tmp, os.Rename() over the real file, chmod 0600
 ```
 
-### Key generation (on demand)
+### Install
 
-- Triggered by a flag or API call from the server
-- Runs `ssh-keygen` via `exec.Command`
-- Uploads public key via `UploadGeneratedKey()`
-- Private key stays local on the machine
-
-### Systemd unit — `/etc/systemd/system/vantage-agent.service`
-
-```ini
-[Unit]
-Description=Vantage Agent
-After=network.target
-
-[Service]
-ExecStart=/usr/local/bin/vantage-agent
-Restart=always
-RestartSec=10
-User=root
-
-[Install]
-WantedBy=multi-user.target
-```
+Linux: systemd unit at `/etc/systemd/system/vantage-agent.service`, `Restart=always`, runs as root.
+Windows: MSI built by CI (WiX), or `installer/setup.ps1` registering the agent as a service via NSSM.
 
 ---
 
 ## Server Registration Flow
 
-1. Click **Add Server** in the UI
-2. Backend generates a short-lived pre-registration token (TTL: 1 hour) and a `server_id`
-3. UI displays a one-liner install command with copy button:
+1. **Add Server** in the UI calls `POST /api/servers/new`, which generates a `server_id` and a pre-registration token (TTL 1 hour, single-use).
+2. The UI shows a one-liner:
     ```bash
     curl -fsSL https://vantage.yourdomain.com/install | \
       bash -s -- --server-id=<id> --token=<token>
     ```
-4. Install script:
-    - Detects arch (`amd64` / `arm64`)
-    - Downloads agent binary from Gitea release
-    - Verifies SHA-256 checksum
-    - Writes `/etc/vantage/config.yaml`
-    - Installs and starts systemd unit
-5. On first `SyncKeys` call, server marks status as `active`
+    Windows gets the `/install.ps1` equivalent.
+3. The script detects arch, downloads the agent from the Gitea release, verifies the SHA-256 checksum, writes the config, installs and starts the service.
+4. The server flips to `active` on first sync.
 
-The backend serves `/install` dynamically, injecting the latest agent version by querying the Gitea API for the most recent `agent/v*` release tag.
+`/install` is served dynamically, injecting the latest agent version from the Gitea API.
+
+---
+
+## Environment Variables (server)
+
+| Name                       | Required        | Notes                                                                                                                                                      |
+| -------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GRPC_HOST`                | **yes**         | `host:port` agents dial. Boot fails without it — there is no safe default; falling back to the web host would hand agents a port that does not speak gRPC. |
+| `MONGO_URI`                | no              | default `mongodb://localhost:27017`                                                                                                                        |
+| `MONGO_DB`                 | no              | default `vantage`                                                                                                                                          |
+| `REDIS_ADDR`               | no              | default `localhost:6379`                                                                                                                                   |
+| `KEY_ENCRYPTION_KEY`       | yes in practice | 64-char hex (32 bytes) for AES-256-GCM. Required for private keys, secrets, OIDC secrets, RDP credentials.                                                 |
+| `GITEA_HOST`               | yes             | used to build install scripts and agent download URLs                                                                                                      |
+| `GUACD_ADDR`               | no              | default `guacd:4822`                                                                                                                                       |
+| `APP_ROOT_LABEL`           | no              | default `vantage`; wrong value disables the host/session org guard                                                                                         |
+| `VANTAGE_WORKFLOW_LOG_DIR` | no              | where run logs are written                                                                                                                                 |
+| `FREE_INSTANCE_REAP_AFTER` | no              | duration past a Free licence's expiry before the instance and all its data are deleted. **Empty disables the reaper, and empty is the default.** Set to `336h` in `docker-compose.site.yml` only — a self-hosted deployment must never reap. Must match admin's value, which only names the date in warning emails |
+
+**sitesvc** (`deploy/docker-compose.site.yml` only):
+
+| Name                              | Required        | Notes                                                                                                                                                                                                                                                                                                                                            |
+| --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MONGO_URI`                       | yes             | **must point at the control plane's database.** sitesvc no longer provisions orgs itself, but it still refuses to start (`RequireMigratedDatabase`) against a database that has not run migration `0004` (the `orgs` → `instances` rename), and it (re)declares the shared `users.email` / `instances.slug` indexes at boot. The database name is read from the URI path; a URI without one is refused rather than defaulted. Note this differs from the server, which takes `MONGO_DB` separately. |
+| `SMTP_HOST` / `SMTP_FROM`         | yes             | without them the contact form refuses (503) rather than silently dropping                                                                                                                                                                                                                                                                        |
+| `SMTP_TO`                         | no              | default `support@hostxtra.co.uk`; contact enquiries only                                                                                                                                                                                                                                                                                         |
+| `SMTP_PORT`                       | no              | default `587`; `465` uses implicit TLS                                                                                                                                                                                                                                                                                                           |
+| `SMTP_USERNAME` / `SMTP_PASSWORD` | no              | auth skipped when username is empty                                                                                                                                                                                                                                                                                                              |
+| `SITE_ORIGIN`                     | yes in practice | comma-separated allowed origins; unset refuses every cross-origin browser request                                                                                                                                                                                                                                                                |
+| `TRUST_PROXY`                     | no              | only `true` behind a proxy that overwrites `X-Forwarded-For`, or clients spoof past the rate limiter                                                                                                                                                                                                                                             |
+
+`deploy/docker-compose.yml` runs four services: `redis`, `guacd`, `server` (8080 + 9090), `web` (3000). MongoDB is external. `deploy/docker-compose.site.yml` adds four more — `site` (3003), `sitesvc` (8082), `admin` (8083) and `adminsite` (3004) — and is only used on vantage.hostxtra.co.uk.
+
+`LICENSE_SIGNING_KEY` appears in **exactly one service in exactly one compose file**: `admin` in `docker-compose.site.yml`. It must never be added to `server`, and the self-hosted `docker-compose.yml` must never mention `admin` or `adminsite` at all. Admin uses an external Redis via `REDIS_ADDR`/`REDIS_USERNAME`/`REDIS_PASSWORD`; the base compose hardcodes `redis:6379` for `server`, so those variables reach admin only.
 
 ---
 
 ## Security
 
-- gRPC over TLS (Let's Encrypt or self-signed with cert pinning on the agent)
-- Agent authenticates with a per-server token stored at `/etc/vantage/config.yaml` (`0600`)
-- Server stores `SHA-256(agent_token)` — never the plaintext token
-- Private keys generated by agents are encrypted at rest in MongoDB (AES-256)
-- `authorized_keys` written as `0600`, owned by root
-- Pre-registration tokens are short-lived (1 hour) and single-use
-- Agent runs as `root` (required for `/root/.ssh/authorized_keys` writes)
+- gRPC over TLS; agents connect outbound only, no inbound firewall holes on managed servers.
+- Per-server agent token stored as SHA-256 on the server, plaintext only in the agent's `0600` config.
+- Pre-registration tokens are short-lived (1 hour) and single-use.
+- AES-256-GCM at rest for private keys, key passphrases, vault secrets, OIDC client secrets, RDP/VNC credentials.
+- Console session tokens are one-time; RDP credentials are consumed on tunnel open.
+- ESO read token stored as a SHA-256 hash and rotatable.
+- Unique indexes on `(instance_id, email)`, instance slug, settings instance and the ESO token hash are load-bearing for tenant isolation. So is the absence of any unscoped lookup by email.
+- `authorized_keys` written `0600`, owned by root. The agent runs as root because it must.
+- Every mutating API path writes an audit event.
 
 ---
 
-## Frontend Routes
+## Frontend
 
-| Route           | Purpose                                                              |
-| --------------- | -------------------------------------------------------------------- |
-| `/servers`      | List all servers, online/offline status badge, last seen timestamp   |
-| `/servers/new`  | Displays the one-liner install script with copy button               |
-| `/servers/[id]` | Keys installed on this server, trigger key generation, remove server |
-| `/keys`         | All keys — label, fingerprint, source, assigned count                |
-| `/keys/[id]`    | Assign key to servers, revoke per server                             |
+Next.js 16 (App Router) + React 18, Tailwind 3, TanStack Query. Guacamole client bundled locally in `web/lib/guacamole-common.js`.
+
+There are **three separate visual identities**, and the split is deliberate:
+
+| App | Ground | Accent | Themes |
+| --- | --- | --- | --- |
+| `web/` | `#0f1117` | indigo `#6366f1` | dark only, locked |
+| `site/` | token-based | brand navy `#0b2a58` / `#5b9be8` | light + dark |
+| `adminsite/` | **the same tokens as `site/`** | brand navy | light + dark, light default |
+
+`adminsite/app/globals.css` holds `site/app/globals.css`'s token blocks **copied verbatim** — same names, same values. **Change them in both files in the same commit; nothing enforces the match automatically**, the same shape of hazard as sitesvc's mirrored slug rules. Tailwind in `adminsite/` maps `var(--…)` references only, so no component may carry a hex value. `site/` names the semantic three `--up`/`--pend`/`--down` for monitor state; `adminsite/` aliases them to `valid`/`warn`/`expired` for licence state — same colours.
+
+`adminsite/` defaults to **light** on purpose: `web/` is locked to dark, and a staff member with both open should never mistake one for the other before clicking Reissue. In dark mode the shared accent lifts to `#5b9be8`, closer to web/'s indigo, so that distinction rests on the ground — do not make dark the default. Licence state never reads by colour alone: every pill carries a distinct shape and a text label.
+
+| Route                                                           | Purpose                                                                 |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `/setup`                                                        | First-run bootstrap: create the first org and owner                     |
+| `/login`                                                        | Local or OIDC sign-in                                                   |
+| `/`                                                             | Fleet dashboard                                                         |
+| `/servers`, `/servers/new`, `/servers/[id]`                     | Fleet list, install one-liner, server detail (keys, inventory, updates) |
+| `/servers/[id]/console`                                         | Browser SSH/RDP/VNC session                                             |
+| `/keys`, `/keys/[id]`                                           | Key library; assign and revoke per server                               |
+| `/workflows`, `/workflows/[id]`, `/workflows/[id]/runs[/runId]` | Compose, run, and follow live logs                                      |
+| `/steps`                                                        | Reusable step library                                                   |
+| `/monitors`, `/monitors/new`, `/monitors/[id][/edit]`           | Checks, uptime, incidents                                               |
+| `/secrets`, `/secrets/[group]`                                  | Vault                                                                   |
+| `/audit`                                                        | Audit log                                                               |
+| `/settings`, `/settings/org`, `/settings/notifications`         | Alerts, members, OIDC, channels                                         |
 
 ---
 
 ## CI/CD — Gitea Actions
 
-### Agent release — `.gitea/workflows/agent-release.yml`
+### `agent-release.yml` — triggered by `agent/v*` tags
 
-Triggered by a `agent/v*` tag. Cross-compiles for `linux/amd64` and `linux/arm64`, creates a Gitea release with binaries and checksums.
-
-```yaml
-on:
-    push:
-        tags:
-            - "agent/v*"
-```
-
-Build command:
+Builds `linux/amd64`, `linux/arm64`, `windows/amd64`, writes `checksums.txt`, creates a Gitea release. A second `msi` job on `windows-2022` packages the WiX installer.
 
 ```bash
 GOOS=linux GOARCH=amd64 go build \
@@ -301,51 +480,54 @@ GOOS=linux GOARCH=amd64 go build \
   -o dist/vantage-agent-linux-amd64 ./cmd
 ```
 
-Release assets:
+### `server-deploy.yml` — triggered on every push to `main`
 
-- `vantage-agent-linux-amd64`
-- `vantage-agent-linux-arm64`
-- `checksums.txt`
+Builds and pushes six images to the Gitea container registry: `server`, `web`, `site`, `sitesvc`, `admin` and `adminsite`.
 
-### Server deploy — `.gitea/workflows/server-deploy.yml`
-
-Triggered on pushes to `main` touching `server/**`, `web/**`, or `proto/**`. Builds and pushes Docker images to the Gitea container registry, then deploys via SSH:
+Note that despite the name, **this workflow does not deploy** — it only builds and pushes. There is no SSH step and no path filter; every push to `main` rebuilds all three images. Rolling them out is a separate manual step on the host:
 
 ```bash
-cd /opt/vantage && docker compose pull && docker compose up -d --remove-orphans
+cd /opt/vantage && docker compose -f docker-compose.yml -f docker-compose.site.yml pull && \
+  docker compose -f docker-compose.yml -f docker-compose.site.yml up -d --remove-orphans
 ```
 
-### Tagging convention
+### Tagging
 
 ```bash
-# Release a new agent version
-git tag agent/v1.0.0 && git push origin agent/v1.0.0
-
-# Server + web deploy automatically on push to main
-git push origin main
+git tag agent/v1.0.0 && git push origin agent/v1.0.0   # agent release
+git push origin main                                    # server + web deploy
 ```
 
-### Required Gitea secrets / variables
+### Secrets / variables
 
-| Name                | Type     | Value                                      |
-| ------------------- | -------- | ------------------------------------------ |
-| `RELEASE_TOKEN`     | Secret   | Gitea API token with `write:release` scope |
-| `REGISTRY_USER`     | Secret   | Gitea username                             |
-| `REGISTRY_PASSWORD` | Secret   | Gitea token with `write:packages` scope    |
-| `DEPLOY_HOST`       | Secret   | IP/hostname of the server VM               |
-| `DEPLOY_USER`       | Secret   | SSH user for deploy                        |
-| `DEPLOY_SSH_KEY`    | Secret   | Private key for deploy SSH                 |
-| `GITEA_HOST`        | Variable | `gitea.hostxtra.co.uk`                     |
+| Name                 | Type     | Value                                                                                                                                                                               |
+| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RELEASE_TOKEN`      | Secret   | Gitea API token, `write:release`                                                                                                                                                    |
+| `REGISTRY_USER`      | Secret   | Gitea username                                                                                                                                                                      |
+| `REGISTRY_PASSWORD`  | Secret   | Gitea token, `write:packages`                                                                                                                                                       |
+| `GITEA_HOST`         | Variable | `gitea.hostxtra.co.uk`                                                                                                                                                              |
+| `DOCKER_HOST`        | Variable | registry host used for image tags                                                                                                                                                   |
+| `API_URL`            | Variable | baked into the `web` image at build time                                                                                                                                            |
+| `SITE_API_URL`       | Variable | **browser-reachable** sitesvc URL, baked into the `site` image. Required — if empty, both forms report "not connected" and submit nowhere. Must also be in sitesvc's `SITE_ORIGIN`. |
+| `SITE_CONTACT_EMAIL` | Variable | optional; address shown when a form is misconfigured                                                                                                                                |
+| `ADMIN_API_URL`      | Variable | **browser-reachable** admin URL, baked into **both** the `adminsite` and `site` images — `site/start` posts account signups straight to admin. Same footgun as `SITE_API_URL`: wrong here and every request fails at runtime with the not-connected panel. |
+| `ADMIN_ENV`          | Variable | `production` or `sandbox`; drives the persistent environment badge. Anything but `sandbox` reads as production.                                                                     |
 
 ---
 
 ## Design Decisions
 
-- **gRPC over REST for agent communication** — strong typing, easy versioning, bi-directional streaming available later if push-based updates are needed
-- **Poll-only, no streaming** — 30s interval is sufficient for a homelab; simplifies agent implementation
-- **Outbound-only agent connections** — no inbound firewall holes required on managed servers
-- **Atomic `authorized_keys` rewrite** — write to `.tmp` then `os.Rename()` prevents partial writes
-- **Fingerprint diffing before write** — avoids unnecessary disk writes on unchanged state
-- **Soft revocation** — `revoked_at` timestamp rather than hard deletes; preserves audit history
-- **root only** — manages `/root/.ssh/authorized_keys` only; no per-user key management
-- **Gitea releases for agent binaries** — slots into existing act_runner CI pipeline; install script queries Gitea API for latest version at serve time
+- **gRPC for agent traffic** — strong typing and cheap versioning; polling for state, one bidirectional stream for commands.
+- **Outbound-only agents** — no inbound ports on managed servers, works behind NAT.
+- **Poll for keys, push for commands** — a 30s key poll is fine, but running a workflow step should not wait up to 30s.
+- **Atomic `authorized_keys` rewrite** — temp file plus `os.Rename()`; a machine that dies mid-write keeps the old file.
+- **Fingerprint diffing before write** — no disk churn on unchanged state.
+- **Soft revocation** — `revoked_at` rather than deletes; preserves audit history.
+- **Run snapshots** — workflow runs freeze their resolved steps so editing a step never rewrites past runs.
+- **Monitors run in two places** — server-side for external endpoints, agent-side for anything only reachable from inside the target network.
+- **Redis for sessions only** — all durable state stays in MongoDB; losing Redis logs everyone out and nothing else.
+- **guacd for console** — protocol handling is Guacamole's problem, not ours; we proxy the WebSocket and manage credentials.
+- **`org_id` on every document** — isolation enforced at the query layer, not by separate databases.
+- **root only** — manages `/root/.ssh/authorized_keys`; no per-user key management.
+- **Windows agents are second-class by design** — register, heartbeat, run steps, report inventory; no `authorized_keys` management.
+- **Deletion lives in the control plane** — admin sends the warnings because it knows the billing address; the control plane performs the delete because it is the only service that knows which collections carry `instance_id`. Mirroring that list into admin would drift, and a drift there deletes the wrong rows.

cloud-instance-creation-process.md

@@ -0,0 +1,30 @@
+# Current cloud instance process
+
+The current processs for creating cloud instances is incorrect.
+
+At the moment the cloud instance process is the following:
+
+- Customer goes to `https://vantage.hostxtra.co.uk/start` then fills in the form.
+- Customer is then sent and email to verify
+- Customer clicks the link and the instance is created in the DB.
+- Customer can then access the instance.
+
+As the `/start` process is auto creating a new instance this should default to the free tier instance.
+
+The issue is that this doesn't create an `account` and `admin_instance` on the admin side.
+
+The Cloud instance creation / account creation needs to be restructured.
+
+for context when I say `hq` I mean `admin`
+
+- customer goes to `https://vantage.hostxtra.co.uk/start` and fills in the form.
+    - This is where the HQ account is created.
+- The customer is then sent and email to verify their email address.
+- The customer can then access the HQ customer portal.
+- The customer can then create a free new instance in the HQ portal.
+- The cloud instance is created in the DB.
+- The HQ `account` and `admin_instance` is created and populated in the DB.
+- A `Free` License is created and attached to the instance.
+- The customer is then sent an email letting them know the instance has been created and when the license expires.
+- The customer will need to renew the license after expiry, if they are on a Free license.
+    - This is so that unused instances can be cleaned up if no renew after a length of time has passed.

deploy/docker-compose.site.yml

@@ -0,0 +1,73 @@
+services:
+    # Adds to the base `server` service defined in docker-compose.yml —
+    # only the cloud deployment reaps abandoned Free instances.
+    server:
+        environment:
+            FREE_INSTANCE_REAP_AFTER: "336h"
+    site:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/site:latest
+        restart: unless-stopped
+        ports:
+            - 3003:3000
+        depends_on:
+            - sitesvc
+    sitesvc:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/sitesvc:latest
+        restart: unless-stopped
+        ports:
+            - 8082:8082
+        environment:
+            PORT: "8082"
+            MONGO_URI: ${MONGO_URI:-}
+            PUBLIC_URL: ${PUBLIC_URL:-}
+            SITE_ORIGIN: ${SITE_ORIGIN:-}
+            TRUST_PROXY: ${SITE_TRUST_PROXY:-false}
+            SMTP_HOST: ${SMTP_HOST:-}
+            SMTP_PORT: ${SMTP_PORT:-587}
+            SMTP_USERNAME: ${SMTP_USERNAME:-}
+            SMTP_PASSWORD: ${SMTP_PASSWORD:-}
+            SMTP_FROM: ${SMTP_FROM:-}
+            SMTP_TO: ${SMTP_TO:-support@hostxtra.co.uk}
+    admin:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/admin:latest
+        restart: unless-stopped
+        ports:
+            - 8083:8083
+        environment:
+            PORT: "8083"
+            ADMIN_MONGO_URI: ${ADMIN_MONGO_URI:-}
+            CONTROL_MONGO_URI: ${MONGO_URI:-}
+            REDIS_ADDR: ${REDIS_ADDR:-10.10.10.2:6379}
+            REDIS_USERNAME: ${REDIS_USERNAME:-}
+            REDIS_PASSWORD: ${REDIS_PASSWORD:-}
+            LICENSE_SIGNING_KEY: ${LICENSE_SIGNING_KEY:-}
+            PUBLIC_URL: ${ADMIN_PUBLIC_URL:-}
+            # Comma-separated, and it needs BOTH browser origins that call admin:
+            # vantage-hq (the console) and the marketing site, whose /start form
+            # posts account signups here. An origin missing from this list is not
+            # a 403 — admin omits the CORS header entirely and the browser blocks
+            # the preflight, so the form fails with nothing in admin's logs.
+            #   ADMIN_ORIGIN="https://vantage-hq.hostxtra.co.uk,https://vantage.hostxtra.co.uk"
+            ADMIN_ORIGIN: ${ADMIN_ORIGIN:-}
+            TRUST_PROXY: ${TRUST_PROXY:-true}
+            SMTP_HOST: ${SMTP_HOST:-}
+            SMTP_PORT: ${SMTP_PORT:-587}
+            SMTP_USERNAME: ${SMTP_USERNAME:-}
+            SMTP_PASSWORD: ${SMTP_PASSWORD:-}
+            SMTP_FROM: ${SMTP_FROM:-}
+            APP_LOGIN_URL: ${APP_LOGIN_URL:-}
+            FREE_INSTANCE_REAP_AFTER: "336h"
+
+    # The staff and customer console, served at vantage-hq.hostxtra.co.uk.
+    # ADMIN_API_URL is baked into the image at build time, not read here, so
+    # changing it needs a rebuild rather than a restart — and it must appear in
+    # admin's ADMIN_ORIGIN above or the browser blocks every request.
+    adminsite:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/adminsite:latest
+        restart: unless-stopped
+        ports:
+            # 3000 is web, 3003 is the marketing site; this takes 3004.
+            - 3004:3000
+        depends_on:
+            - admin
+networks: {}

deploy/docker-compose.yml

@@ -1,56 +1,52 @@
 services:
-  redis:
-    image: redis:8
-    restart: unless-stopped
-    volumes:
-      - redis_data:/data
-    healthcheck:
-      test:
-        - CMD
-        - redis-cli
-        - ping
-      interval: 10s
-      timeout: 5s
-      retries: 5
-  guacd:
-    image: docker.io/guacamole/guacd:1.6.0
-    restart: unless-stopped
-    ports:
-      - 4822:4822
-  server:
-    image: gitea.hostxtra.co.uk/mrhid6/vantage/server:latest
-    restart: unless-stopped
-    ports:
-      - 8080:8080
-      - 9090:9090
-    environment:
-      MONGO_URI: ${MONGO_URI:-}
-      REDIS_ADDR: redis:6379
-      GITEA_HOST: ${GITEA_HOST}
-      PUBLIC_HOST: ${PUBLIC_HOST}
-      GRPC_HOST: ${GRPC_HOST}
-      GRPC_PORT: "9090"
-      HTTP_PORT: "8080"
-      OIDC_ISSUER: ${OIDC_ISSUER:-}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID:-}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET:-}
-      OIDC_REDIRECT_URL: ${OIDC_REDIRECT_URL:-}
-      KEY_ENCRYPTION_KEY: ${KEY_ENCRYPTION_KEY:-}
-      VANTAGE_WORKFLOW_LOG_DIR: ${VANTAGE_WORKFLOW_LOG_DIR:-}
-      GUACD_ADDR: guacd:4822
-    depends_on:
-      redis:
-        condition: service_healthy
-    volumes:
-      - ./data:/data
-  web:
-    image: gitea.hostxtra.co.uk/mrhid6/vantage/web:latest
-    restart: unless-stopped
-    ports:
-      - 3000:3000
-    depends_on:
-      - server
+    redis:
+        image: redis:8
+        restart: unless-stopped
+        volumes:
+            - redis_data:/data
+        healthcheck:
+            test:
+                - CMD
+                - redis-cli
+                - ping
+            interval: 10s
+            timeout: 5s
+            retries: 5
+    guacd:
+        image: docker.io/guacamole/guacd:1.6.0
+        restart: unless-stopped
+        ports:
+            - 4822:4822
+    server:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/server:latest
+        restart: unless-stopped
+        ports:
+            - 8080:8080
+            - 9090:9090
+        environment:
+            MONGO_URI: ${MONGO_URI:-}
+            REDIS_ADDR: redis:6379
+            GITEA_HOST: ${GITEA_HOST}
+            GRPC_HOST: ${GRPC_HOST}
+            GRPC_PORT: "9090"
+            HTTP_PORT: "8080"
+            KEY_ENCRYPTION_KEY: ${KEY_ENCRYPTION_KEY:-}
+            VANTAGE_WORKFLOW_LOG_DIR: ${VANTAGE_WORKFLOW_LOG_DIR:-}
+            GUACD_ADDR: guacd:4822
+            APP_ROOT_LABEL: vantage
+        depends_on:
+            redis:
+                condition: service_healthy
+        volumes:
+            - ./data:/data
+    web:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/web:latest
+        restart: unless-stopped
+        ports:
+            - 3000:3000
+        depends_on:
+            - server
 volumes:
-  mongo_data: null
-  redis_data: null
+    mongo_data: null
+    redis_data: null
 networks: {}

docs/superpowers/plans/2026-07-20-fleet-inventory.md

@@ -1,866 +0,0 @@
-# Fleet Inventory Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Agents collect CPU/RAM/swap/disk/partition inventory and report it to the server via a new `ReportInventory` RPC; the server stores the latest snapshot per server and the UI displays it.
-
-**Architecture:** New unary gRPC `ReportInventory` (mirrors existing `ReportUpdates`). Agent runs a 30s metrics ticker (CPU/RAM/swap usage) and, every 15 min, a full static collection (disks, partitions, CPU model, kernel). Server upserts an embedded `inventory` sub-doc on the `servers` document with merge rules that preserve static fields between slow ticks.
-
-**Tech Stack:** Go (gin, mongo-driver v2, hand-written JSON-codec gRPC), `/proc` readers, Next.js 16 + react-query + Tailwind.
-
-## Global Constraints
-
-- **No tests this iteration.** Verify with `go build ./...`, `go vet ./...`, `npm run build`.
-- gRPC uses a JSON codec: edit **both** `server/internal/grpc/pb/vantage.pb.go` and `agent/internal/grpc/pb/vantage.pb.go` identically, plus `proto/vantage/v1/vantage.proto` as documentation. No codegen. Mirror the existing `ReportUpdates` RPC wiring exactly (service interface, `_Vantage_*_Handler`, client method, `Vantage_ServiceDesc`).
-- Mongo: `db.Col("servers")`, `context.WithTimeout`. Follow `server/internal/services/servers.go`.
-- Agent already runs as root; `/proc` is readable. Linux is primary; Windows collectors may return empty.
-- Module path `github.com/mrhid6/vantage`.
-- Do not add heavy dependencies; implement `/proc` parsing directly.
-
----
-
-## Task 1: Inventory model + gRPC messages
-
-**Files:**
-- Modify: `server/internal/models/server.go`
-- Modify: `proto/vantage/v1/vantage.proto`
-- Modify: `server/internal/grpc/pb/vantage.pb.go`
-- Modify: `agent/internal/grpc/pb/vantage.pb.go`
-
-**Interfaces:**
-- Produces: `models.Inventory` (+ `CPUInfo`, `MemInfo`, `Partition`) and `Server.Inventory *Inventory`. pb structs `InventoryReport`, `CPUReport`, `MemReport`, `PartitionReport`, `InventoryReportResponse`. Service method `ReportInventory` on both client and server interfaces.
-
-- [ ] **Step 1: Add model structs**
-
-In `server/internal/models/server.go` add (keep the existing `import "time"`):
-
-```go
-type CPUInfo struct {
-	Model    string  `bson:"model,omitempty" json:"model,omitempty"`
-	Cores    int     `bson:"cores,omitempty" json:"cores,omitempty"`
-	UsagePct float64 `bson:"usage_pct" json:"usage_pct"`
-	Load1    float64 `bson:"load1,omitempty" json:"load1,omitempty"`
-}
-
-type MemInfo struct {
-	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
-	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
-}
-
-type Partition struct {
-	Device     string `bson:"device" json:"device"`
-	Mountpoint string `bson:"mountpoint" json:"mountpoint"`
-	Fstype     string `bson:"fstype,omitempty" json:"fstype,omitempty"`
-	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
-	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
-}
-
-type Inventory struct {
-	CPU            CPUInfo     `bson:"cpu" json:"cpu"`
-	Memory         MemInfo     `bson:"memory" json:"memory"`
-	SwapTotalBytes uint64      `bson:"swap_total_bytes" json:"swap_total_bytes"`
-	SwapUsedBytes  uint64      `bson:"swap_used_bytes" json:"swap_used_bytes"`
-	Partitions     []Partition `bson:"partitions,omitempty" json:"partitions,omitempty"`
-	Kernel         string      `bson:"kernel,omitempty" json:"kernel,omitempty"`
-	MetricsAt      *time.Time  `bson:"metrics_at,omitempty" json:"metrics_at,omitempty"`
-	StaticAt       *time.Time  `bson:"static_at,omitempty" json:"static_at,omitempty"`
-}
-```
-
-Add to the `Server` struct: `Inventory *Inventory \`bson:"inventory,omitempty" json:"inventory,omitempty"\``.
-
-- [ ] **Step 2: Document RPC in proto**
-
-In `proto/vantage/v1/vantage.proto`, add to the service: `rpc ReportInventory(InventoryReport) returns (InventoryReportResponse);` and the messages `InventoryReport`, `CPUReport`, `MemReport`, `PartitionReport`, `InventoryReportResponse` per spec §4.
-
-- [ ] **Step 3: Add pb structs + RPC wiring (server pb)**
-
-In `server/internal/grpc/pb/vantage.pb.go` add the message structs:
-
-```go
-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{}
-```
-
-Then mirror the `ReportUpdates` RPC plumbing for `ReportInventory`. Locate every `ReportUpdates` reference in this file and add the parallel `ReportInventory`:
-- `VantageServer` interface: add `ReportInventory(context.Context, *InventoryReport) (*InventoryReportResponse, error)`.
-- `UnimplementedVantageServer`: add the stub returning `Unimplemented`.
-- `VantageClient` interface + `keyManagerClient`: add the client method `Invoke`-ing `/vantage.v1.Vantage/ReportInventory`.
-- `Vantage_ServiceDesc.Methods`: add `{MethodName: "ReportInventory", Handler: _Vantage_ReportInventory_Handler}`.
-- Add `_Vantage_ReportInventory_Handler` copied from `_Vantage_ReportUpdates_Handler` with types swapped.
-
-- [ ] **Step 4: Mirror pb structs + wiring (agent pb)**
-
-Apply the identical additions to `agent/internal/grpc/pb/vantage.pb.go`.
-
-- [ ] **Step 5: Verify build**
-
-Run: `cd server && go build ./... && cd ../agent && go build ./...`
-Expected: both succeed.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add server/internal/models/server.go proto/vantage/v1/vantage.proto server/internal/grpc/pb/vantage.pb.go agent/internal/grpc/pb/vantage.pb.go
-git commit -m "feat(proto): add ReportInventory RPC and inventory model"
-```
-
----
-
-## Task 2: Server handler + store service
-
-**Files:**
-- Create: `server/internal/services/inventory.go`
-- Modify: `server/internal/grpc/server.go`
-
-**Interfaces:**
-- Consumes: `pb.InventoryReport` (T1), `db.Col("servers")`.
-- Produces: `services.StoreInventory(serverID string, r *pb.InventoryReport) error`; gRPC method `(*vantageServer).ReportInventory`.
-
-- [ ] **Step 1: Write the store service**
-
-```go
-package services
-
-import (
-	"context"
-	"time"
-
-	"github.com/mrhid6/vantage/server/internal/db"
-	"github.com/mrhid6/vantage/server/internal/grpc/pb"
-	"go.mongodb.org/mongo-driver/v2/bson"
-)
-
-// StoreInventory upserts the latest inventory snapshot onto the server document.
-// Metrics fields update every call; static fields only when r.IncludeStatic.
-func StoreInventory(serverID string, r *pb.InventoryReport) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-
-	now := time.Now()
-	set := bson.M{"inventory.metrics_at": now}
-	if r.CPU != nil {
-		set["inventory.cpu.usage_pct"] = r.CPU.UsagePct
-		set["inventory.cpu.load1"] = r.CPU.Load1
-	}
-	if r.Memory != nil {
-		set["inventory.memory.used_bytes"] = r.Memory.UsedBytes
-	}
-	set["inventory.swap_used_bytes"] = r.SwapUsed
-
-	if r.IncludeStatic {
-		set["inventory.static_at"] = now
-		set["inventory.swap_total_bytes"] = r.SwapTotal
-		set["inventory.kernel"] = r.Kernel
-		if r.CPU != nil {
-			set["inventory.cpu.model"] = r.CPU.Model
-			set["inventory.cpu.cores"] = r.CPU.Cores
-		}
-		if r.Memory != nil {
-			set["inventory.memory.total_bytes"] = r.Memory.TotalBytes
-		}
-		parts := make([]bson.M, 0, len(r.Partitions))
-		for _, p := range r.Partitions {
-			parts = append(parts, bson.M{
-				"device": p.Device, "mountpoint": p.Mountpoint, "fstype": p.Fstype,
-				"total_bytes": p.TotalBytes, "used_bytes": p.UsedBytes,
-			})
-		}
-		set["inventory.partitions"] = parts
-	}
-
-	_, err := db.Col("servers").UpdateOne(ctx, bson.M{"server_id": serverID}, bson.M{"$set": set})
-	return err
-}
-```
-
-- [ ] **Step 2: Add the gRPC handler**
-
-In `server/internal/grpc/server.go`, add (mirroring the existing `ReportUpdates` handler that validates the agent token):
-
-```go
-func (s *vantageServer) ReportInventory(ctx context.Context, req *pb.InventoryReport) (*pb.InventoryReportResponse, error) {
-	srv, err := services.ValidateAgentToken(req.ServerId, req.AgentToken)
-	if err != nil {
-		return nil, status.Errorf(codes.Unauthenticated, "invalid agent token")
-	}
-	if err := services.StoreInventory(srv.ServerID, req); err != nil {
-		log.Printf("store inventory for %s: %v", srv.ServerID, err)
-	}
-	return &pb.InventoryReportResponse{}, nil
-}
-```
-
-Confirm `status`, `codes`, `log` are already imported in the file (they are, used by other handlers).
-
-- [ ] **Step 3: Verify build**
-
-Run: `cd server && go build ./... && go vet ./...`
-Expected: success.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add server/internal/services/inventory.go server/internal/grpc/server.go
-git commit -m "feat(server): store inventory and handle ReportInventory RPC"
-```
-
----
-
-## Task 3: Agent collectors
-
-**Files:**
-- Create: `agent/internal/inventory/collect_linux.go`
-- Create: `agent/internal/inventory/collect_other.go`
-- Create: `agent/internal/inventory/inventory.go`
-
-**Interfaces:**
-- Produces: `inventory.Collect(includeStatic bool) *pb.InventoryReport`.
-
-- [ ] **Step 1: Common entry (`inventory.go`)**
-
-```go
-package inventory
-
-import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
-
-// Collect gathers metrics always and static hardware info when includeStatic.
-// Platform specifics are provided by collect_linux.go / collect_other.go.
-func Collect(includeStatic bool) *pb.InventoryReport {
-	r := &pb.InventoryReport{IncludeStatic: includeStatic, CPU: &pb.CPUReport{}, Memory: &pb.MemReport{}}
-	collect(r, includeStatic)
-	return r
-}
-```
-
-- [ ] **Step 2: Linux collector (`collect_linux.go`)**
-
-Build-tagged `//go:build linux`. Implement `collect(r *pb.InventoryReport, includeStatic bool)`:
-- CPU usage: read `/proc/stat` first line twice ~100ms apart, compute `1 - idleDelta/totalDelta` × 100 → `r.CPU.UsagePct`.
-- Load: first field of `/proc/loadavg` → `r.CPU.Load1`.
-- Mem/swap: parse `/proc/meminfo` (`MemTotal`, `MemAvailable`, `SwapTotal`, `SwapFree`; used = total − available; swap used = swaptotal − swapfree) → `r.Memory.*`, `r.SwapUsed`, and on static `r.SwapTotal`.
-- Static only: `/proc/cpuinfo` (`model name`, count `processor` lines) → `r.CPU.Model/Cores`; `/proc/meminfo MemTotal` → `r.Memory.TotalBytes`; kernel via `syscall.Uname` or read `/proc/sys/kernel/osrelease` → `r.Kernel`; partitions from `/proc/mounts` filtered to fstypes in {ext4,xfs,btrfs,zfs,vfat,ntfs} then `syscall.Statfs` for total/used → `r.Partitions`.
-
-```go
-//go:build linux
-
-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()) // cpu user nice system idle iowait ...
-		for i, v := range fields[1:] {
-			n, _ := strconv.ParseUint(v, 10, 64)
-			total += n
-			if i == 3 { // idle
-				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
-}
-```
-
-- [ ] **Step 3: Non-linux stub (`collect_other.go`)**
-
-```go
-//go:build !linux
-
-package inventory
-
-import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
-
-// collect is a no-op best-effort stub on non-Linux platforms.
-func collect(r *pb.InventoryReport, includeStatic bool) {}
-```
-
-- [ ] **Step 4: Verify build**
-
-Run: `cd agent && go build ./... && go vet ./...`
-Expected: success (build both native and, if convenient, `GOOS=windows go build ./...`).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add agent/internal/inventory/
-git commit -m "feat(agent): /proc-based inventory collectors"
-```
-
----
-
-## Task 4: Agent client method + scheduler
-
-**Files:**
-- Modify: `agent/internal/grpc/client.go`
-- Modify: the agent main loop (`agent/cmd/main.go` or `agent/internal/sync/sync.go` — wherever the poll loop/tickers live).
-
-**Interfaces:**
-- Consumes: `inventory.Collect` (T3), pb (T1).
-- Produces: `(*Client).ReportInventory(report *pb.InventoryReport) error`; a running ticker that reports metrics every 30s and static every 15 min.
-
-- [ ] **Step 1: Add client method**
-
-In `agent/internal/grpc/client.go`, mirroring `ReportUpdates`:
-
-```go
-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
-}
-```
-
-The report already carries `ServerId`/`AgentToken`; ensure the caller sets them (see Step 2).
-
-- [ ] **Step 2: Add the scheduler to the agent loop**
-
-Find where the agent starts its poll loop (the goroutine that calls `SyncKeys`/`ReportUpdates`). Add a parallel inventory ticker. `serverID`, `agentToken`, and the `*Client` are in scope there:
-
-```go
-	go func() {
-		tick := 0
-		t := time.NewTicker(30 * time.Second)
-		defer t.Stop()
-		report := func(static bool) {
-			r := inventory.Collect(static)
-			r.ServerId = serverID
-			r.AgentToken = agentToken
-			if err := client.ReportInventory(r); err != nil {
-				log.Printf("report inventory: %v", err)
-			}
-		}
-		report(true) // send a full snapshot on startup
-		for range t.C {
-			tick++
-			report(tick%30 == 0) // every 30th tick = 15 min → include static
-		}
-	}()
-```
-
-Add imports `"github.com/mrhid6/vantage/agent/internal/inventory"`, `time`, `log` if missing. Match variable names to the actual loop (e.g. the client may be named `c`).
-
-- [ ] **Step 3: Verify build**
-
-Run: `cd agent && go build ./... && go vet ./...`
-Expected: success.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add agent/internal/grpc/client.go agent/
-git commit -m "feat(agent): schedule inventory reporting (30s metrics, 15m static)"
-```
-
----
-
-## Task 5: Frontend — inventory panel on server detail
-
-**Files:**
-- Modify: `web/lib/api.ts` (extend the `Server`/server-detail type with `inventory`)
-- Modify: `web/app/servers/[id]/page.tsx` (add panel; enable polling)
-
-**Interfaces:**
-- Consumes: server-detail query.
-
-- [ ] **Step 1: Add the inventory type**
-
-In `web/lib/api.ts`, add and attach to the server type used by the detail page:
-
-```ts
-export interface Inventory {
-  cpu: { model?: string; cores?: number; usage_pct: number; load1?: number };
-  memory: { total_bytes: number; used_bytes: number };
-  swap_total_bytes: number;
-  swap_used_bytes: number;
-  partitions?: { device: string; mountpoint: string; fstype?: string; total_bytes: number; used_bytes: number }[];
-  kernel?: string;
-  metrics_at?: string;
-  static_at?: string;
-}
-```
-
-Add `inventory?: Inventory;` to the server detail interface.
-
-- [ ] **Step 2: Add a `formatBytes` helper + Inventory panel**
-
-In `web/app/servers/[id]/page.tsx`, add a helper and a panel component. Enable polling on the server-detail `useQuery` with `refetchInterval: 30000`.
-
-```tsx
-function formatBytes(n: number): string {
-  if (!n) return "0 B";
-  const u = ["B", "KB", "MB", "GB", "TB"];
-  const i = Math.floor(Math.log(n) / Math.log(1024));
-  return `${(n / Math.pow(1024, i)).toFixed(1)} ${u[i]}`;
-}
-
-function UsageBar({ used, total }: { used: number; total: number }) {
-  const pct = total > 0 ? Math.min(100, (used / total) * 100) : 0;
-  return (
-    <div className="h-2 w-full overflow-hidden rounded-full bg-surface-2">
-      <div className={`h-full rounded-full ${pct > 90 ? "bg-danger" : "bg-accent"}`} style={{ width: `${pct}%` }} />
-    </div>
-  );
-}
-
-function InventoryPanel({ inv }: { inv: Inventory }) {
-  return (
-    <Card>
-      <h2 className="mb-4 text-lg font-semibold text-text-primary">Inventory</h2>
-      <div className="grid gap-4 sm:grid-cols-2">
-        <div>
-          <div className="mb-1 flex justify-between text-sm"><span className="text-text-secondary">CPU</span><span className="text-text-primary">{inv.cpu.usage_pct.toFixed(0)}%</span></div>
-          <UsageBar used={inv.cpu.usage_pct} total={100} />
-          <p className="mt-1 text-xs text-text-secondary">{inv.cpu.model} · {inv.cpu.cores} cores · load {inv.cpu.load1?.toFixed(2)}</p>
-        </div>
-        <div>
-          <div className="mb-1 flex justify-between text-sm"><span className="text-text-secondary">Memory</span><span className="text-text-primary">{formatBytes(inv.memory.used_bytes)} / {formatBytes(inv.memory.total_bytes)}</span></div>
-          <UsageBar used={inv.memory.used_bytes} total={inv.memory.total_bytes} />
-          <div className="mb-1 mt-3 flex justify-between text-sm"><span className="text-text-secondary">Swap</span><span className="text-text-primary">{formatBytes(inv.swap_used_bytes)} / {formatBytes(inv.swap_total_bytes)}</span></div>
-          <UsageBar used={inv.swap_used_bytes} total={inv.swap_total_bytes} />
-        </div>
-      </div>
-      {inv.partitions && inv.partitions.length > 0 && (
-        <div className="mt-5">
-          <h3 className="mb-2 text-sm font-medium text-text-secondary">Partitions</h3>
-          <div className="space-y-3">
-            {inv.partitions.map((p) => (
-              <div key={p.mountpoint}>
-                <div className="mb-1 flex justify-between text-xs">
-                  <span className="font-mono text-text-primary">{p.mountpoint}</span>
-                  <span className="text-text-secondary">{formatBytes(p.used_bytes)} / {formatBytes(p.total_bytes)} · {p.fstype}</span>
-                </div>
-                <UsageBar used={p.used_bytes} total={p.total_bytes} />
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
-      {inv.kernel && <p className="mt-4 text-xs text-text-secondary">Kernel {inv.kernel}</p>}
-    </Card>
-  );
-}
-```
-
-Render `{server.inventory && <InventoryPanel inv={server.inventory} />}` in the page body (ensure `Card`, `Inventory` are imported). Match how the page currently reads the server object.
-
-- [ ] **Step 3: Verify build**
-
-Run: `cd web && npm run build`
-Expected: success.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add web/lib/api.ts web/app/servers/[id]/page.tsx
-git commit -m "feat(web): inventory panel on server detail"
-```
-
----
-
-## Task 6: End-to-end manual verification
-
-- [ ] **Step 1: Build all**
-
-Run: `cd server && go build ./... && cd ../agent && go build ./... && cd ../web && npm run build`
-Expected: all succeed.
-
-- [ ] **Step 2: Smoke (if environment available)**
-
-With server + Mongo + a connected Linux agent: within ~30s the server detail page shows CPU %, RAM/swap bars; within 15 min (or on agent restart, which sends a full snapshot immediately) partitions, CPU model and kernel appear. Confirm metrics update roughly every 30s.
-
-- [ ] **Step 3: Commit any fixes**
-
-```bash
-git add -A
-git commit -m "fix: fleet inventory verification fixes"
-```
-
----
-
-# Service Monitoring (uptime-kuma replacement)
-
-Extends the fleet work: in-app service monitors replacing uptime-kuma. Monitors (HTTP/TCP/ICMP/TLS) run **server-side** (public endpoints) or **agent-side** (agent probes its own host). Both runners feed one server-side ingest pipeline: state → incidents → rollups → notifications.
-
-**Design:** validated in brainstorm 2026-07-21. Hybrid runners, all 4 check types, latest+incidents+rollups history, multi-channel notify (webhook/SMTP/Discord/Slack/Telegram), dedicated `SyncMonitors`/`ReportChecks` RPCs.
-
-**Build order — 3 phases, each shippable:**
-- **P1 (Tasks 7–10):** data model, checker pkg, server scheduler, ingest pipeline, `/monitors` UI. Server-run only. No agent, no notify.
-- **P2 (Tasks 11–12):** `SyncMonitors` + `ReportChecks` RPCs, agent checker + scheduler, agent-run monitors bound to a server.
-- **P3 (Tasks 13–14):** notification channels + dispatch + settings UI.
-
-## Monitoring Global Constraints
-
-- Same as fleet: no tests this iteration; verify with `go build ./...`, `go vet ./...`, `npm run build`. JSON-codec gRPC — edit both pb files identically, mirror `ReportUpdates` wiring. Separate Go modules, so the checker pkg is **duplicated** in `server/` and `agent/` (same convention as pb files).
-- Reuse existing patterns: REST handlers like `server/internal/api`, services like `server/internal/services/servers.go`, `db.Col(...)`, react-query + Tailwind UI like `web/app/servers`.
-
----
-
-## Task 7: Monitoring data model + checker package (server)
-
-**Files:**
-- Create: `server/internal/models/monitor.go`
-- Create: `server/internal/checker/checker.go` (+ `http.go`, `tcp.go`, `icmp.go`, `tls.go`)
-
-**Interfaces:**
-- Produces: `models.Monitor` (+ `MonitorState`, `MonitorTarget`), `models.Incident`, `models.Rollup`. `checker.Run(ctx, models.Monitor) checker.Result` where `Result{Up bool; LatencyMs int; Message string; CertExpiry *time.Time}`.
-
-- [ ] **Step 1: Model**
-
-```go
-type MonitorTarget struct {
-	URL            string `bson:"url,omitempty" json:"url,omitempty"`
-	Host           string `bson:"host,omitempty" json:"host,omitempty"`
-	Port           int    `bson:"port,omitempty" json:"port,omitempty"`
-	Method         string `bson:"method,omitempty" json:"method,omitempty"`
-	ExpectedStatus int    `bson:"expected_status,omitempty" json:"expected_status,omitempty"`
-	Keyword        string `bson:"keyword,omitempty" json:"keyword,omitempty"`
-	TLSWarnDays    int    `bson:"tls_warn_days,omitempty" json:"tls_warn_days,omitempty"`
-}
-type MonitorState struct {
-	Status       string     `bson:"status" json:"status"` // up|down|pending
-	LastCheckAt  *time.Time `bson:"last_check_at,omitempty" json:"last_check_at,omitempty"`
-	LatencyMs    int        `bson:"latency_ms" json:"latency_ms"`
-	Message      string     `bson:"message,omitempty" json:"message,omitempty"`
-	CertExpiryAt *time.Time `bson:"cert_expiry_at,omitempty" json:"cert_expiry_at,omitempty"`
-	Fails        int        `bson:"fails" json:"fails"` // consecutive failures
-}
-type Monitor struct {
-	MonitorID   string        `bson:"monitor_id" json:"monitor_id"`
-	Name        string        `bson:"name" json:"name"`
-	Type        string        `bson:"type" json:"type"` // http|tcp|icmp|tls
-	Target      MonitorTarget `bson:"target" json:"target"`
-	IntervalSec int           `bson:"interval_sec" json:"interval_sec"`
-	Runner      string        `bson:"runner" json:"runner"` // "server" or a server_id
-	Retries     int           `bson:"retries" json:"retries"` // consecutive fails before down
-	Enabled     bool          `bson:"enabled" json:"enabled"`
-	ChannelIDs  []string      `bson:"channel_ids,omitempty" json:"channel_ids,omitempty"`
-	State       MonitorState  `bson:"state" json:"state"`
-	CreatedAt   time.Time     `bson:"created_at" json:"created_at"`
-}
-type Incident struct {
-	IncidentID string     `bson:"incident_id" json:"incident_id"`
-	MonitorID  string     `bson:"monitor_id" json:"monitor_id"`
-	StartedAt  time.Time  `bson:"started_at" json:"started_at"`
-	ResolvedAt *time.Time `bson:"resolved_at,omitempty" json:"resolved_at,omitempty"`
-	Cause      string     `bson:"cause,omitempty" json:"cause,omitempty"`
-}
-type Rollup struct {
-	MonitorID   string    `bson:"monitor_id" json:"monitor_id"`
-	PeriodStart time.Time `bson:"period_start" json:"period_start"` // hour bucket
-	Checks      int       `bson:"checks" json:"checks"`
-	UpCount     int       `bson:"up_count" json:"up_count"`
-	SumLatency  int64     `bson:"sum_latency" json:"sum_latency"`
-}
-```
-
-- [ ] **Step 2: Checker package** — `Run(ctx, m)` switches on `m.Type`:
-  - **http**: `http.Client` GET/HEAD `m.Target.URL`, assert status == ExpectedStatus (default 200), optional `Keyword` body contains; capture TLS peer cert expiry when https.
-  - **tcp**: `net.DialTimeout("tcp", host:port)`, latency = dial time.
-  - **icmp**: raw ICMP echo (agent/server run as root). Fall back to `net.Dial("ip4:icmp")`; on permission error return down with message.
-  - **tls**: `tls.Dial`, read `ConnectionState().PeerCertificates[0].NotAfter` → `CertExpiry`; down if within `TLSWarnDays` or expired.
-  - All: wrap with per-check timeout (min(IntervalSec, 10s)); `Result.Message` = short reason on failure.
-
-- [ ] **Step 3: Verify build** — `cd server && go build ./... && go vet ./...`
-
-- [ ] **Step 4: Commit** — `feat(server): monitor model + checker package`
-
----
-
-## Task 8: Ingest pipeline + rollups service
-
-**Files:**
-- Create: `server/internal/services/monitors.go`
-
-**Interfaces:**
-- Produces: `IngestResult(monitorID string, res checker.Result) error` — the single entry both runners use. `ListMonitors`, `GetMonitor`, `CreateMonitor`, `UpdateMonitor`, `DeleteMonitor`, `ListIncidents(monitorID)`, `UptimeRollups(monitorID, since)`.
-
-- [ ] **Step 1: `IngestResult`** — load monitor; compute new status with `Retries` threshold (increment `state.Fails` on failure, flip to `down` only when `Fails >= Retries`; reset + flip `up` on success). On **transition**: open incident (`down`) or resolve open incident (`up`), and enqueue notification (P3 — leave a `// TODO(P3): dispatch` hook now). Always `$set` state fields. Upsert current-hour `Rollup` (`$inc` checks/up_count/sum_latency). Use `db.Col("monitors")`, `db.Col("incidents")`, `db.Col("monitor_rollups")`, `context.WithTimeout`.
-
-- [ ] **Step 2: CRUD + queries** — standard service funcs mirroring `services/servers.go`. `UptimeRollups` aggregates buckets since a cutoff → uptime % + avg latency series.
-
-- [ ] **Step 3: Verify build** — `go build ./... && go vet ./...`
-
-- [ ] **Step 4: Commit** — `feat(server): monitor ingest pipeline, incidents, rollups`
-
----
-
-## Task 9: Server scheduler + REST API
-
-**Files:**
-- Create: `server/internal/monitorsched/scheduler.go`
-- Create: `server/internal/api/monitors.go`
-- Modify: server bootstrap (wherever services/gRPC start) to launch the scheduler; router registration where `api` routes are mounted.
-
-**Interfaces:**
-- Produces: a scheduler that ticks enabled `runner=="server"` monitors on their `IntervalSec` and calls `checker.Run` → `services.IngestResult`. REST: `GET/POST /api/monitors`, `GET/PUT/DELETE /api/monitors/:id`, `GET /api/monitors/:id/incidents`, `GET /api/monitors/:id/uptime`.
-
-- [ ] **Step 1: Scheduler** — on boot load monitors; per-monitor goroutine or a min-heap wheel keyed on next-run. Only `runner=="server"`. Reload on CRUD (simplest: re-read every N sec, or a reload channel fired by the service). Skip disabled.
-
-- [ ] **Step 2: REST handlers** — mirror an existing `server/internal/api` handler file for style + auth middleware. JSON in/out of `models.Monitor`.
-
-- [ ] **Step 3: Verify build** — `go build ./... && go vet ./...`
-
-- [ ] **Step 4: Commit** — `feat(server): server-run monitor scheduler + REST API`
-
----
-
-## Task 10: Frontend — monitors UI (P1)
-
-**Files:**
-- Modify: `web/lib/api.ts` (Monitor types + bindings)
-- Create: `web/app/monitors/page.tsx` (list), `web/app/monitors/[id]/page.tsx` (detail), `web/app/monitors/new/page.tsx` (create/edit form)
-- Modify: main nav to add **Monitors** (same place Steps was added)
-
-**Interfaces:**
-- Consumes: `/api/monitors*` (T9).
-
-- [ ] **Step 1: Types + api bindings** — `Monitor`, `MonitorState`, `Incident`, uptime series; `api.monitors.list/get/create/update/remove/incidents/uptime`.
-- [ ] **Step 2: List page** — table: name, type, status badge (up/down/pending), uptime % (24h), latency, last check. `refetchInterval: 30000`.
-- [ ] **Step 3: Detail page** — status header, heartbeat/uptime bars (24h + 30d from rollups), latency chart, incident timeline, cert expiry, assigned channels (read-only until P3).
-- [ ] **Step 4: Create/edit form** — type-dependent fields (URL vs host/port), interval, retries, runner select (`server` or a registered server for agent-run — server option only wired in P2), enabled.
-- [ ] **Step 5: Verify build** — `cd web && npm run build`
-- [ ] **Step 6: Commit** — `feat(web): monitors list/detail/form UI`
-
----
-
-## Task 11: SyncMonitors + ReportChecks RPCs (P2)
-
-**Files:**
-- Modify: `proto/vantage/v1/vantage.proto`, `server/internal/grpc/pb/vantage.pb.go`, `agent/internal/grpc/pb/vantage.pb.go`, `server/internal/grpc/server.go`, `agent/internal/grpc/client.go`
-
-**Interfaces:**
-- Produces: `SyncMonitors(server_id, agent_token) -> repeated MonitorSpec`; `ReportChecks(server_id, agent_token, repeated CheckResult) -> ReportChecksResponse`. `MonitorSpec{monitor_id, type, target fields, interval_sec, retries}`. `CheckResult{monitor_id, up, latency_ms, message, cert_expiry_unix}`.
-
-- [ ] **Step 1: pb structs + proto** — add messages to both pb files + proto doc.
-- [ ] **Step 2: Wire both RPCs** — mirror `ReportUpdates` plumbing (interface, Unimplemented stub, client method, `Vantage_ServiceDesc.Methods`, `_Vantage_*_Handler`) in both pb files. Server handlers on `vantageServer` (after `ReportUpdates` at server.go:78): `SyncMonitors` returns monitors where `runner==req.ServerId && enabled`; `ReportChecks` validates token then loops `services.IngestResult`. Client methods on `*Client` in client.go (after `ReportUpdates` at client.go:117).
-- [ ] **Step 3: Verify build** — both modules `go build ./... && go vet ./...`
-- [ ] **Step 4: Commit** — `feat(proto): SyncMonitors + ReportChecks RPCs`
-
----
-
-## Task 12: Agent checker + scheduler (P2)
-
-**Files:**
-- Create: `agent/internal/checker/` (duplicate of server checker pkg)
-- Create: `agent/internal/monitors/monitors.go` (poll + run + report loop)
-- Modify: agent main loop to start it (alongside the sync loop in `agent/internal/sync` / the inventory ticker from Task 4)
-
-**Interfaces:**
-- Consumes: `client.SyncMonitors`, `client.ReportChecks`, agent `checker`.
-
-- [ ] **Step 1: Duplicate checker pkg** into agent module (identical logic; imports agent pb).
-- [ ] **Step 2: Monitor loop** — poll `SyncMonitors` every 30s for assigned specs; per-spec ticker on `IntervalSec` runs `checker.Run`; batch `CheckResult`s and `ReportChecks`. `serverID`/`agentToken`/`*Client` in scope from the existing loop.
-- [ ] **Step 3: Verify build** — `cd agent && go build ./... && go vet ./...` (+ `GOOS=windows go build ./...`; icmp may no-op on Windows).
-- [ ] **Step 4: Commit** — `feat(agent): agent-run monitor scheduler`
-
----
-
-## Task 13: Notification channels + dispatch (P3)
-
-**Files:**
-- Create: `server/internal/models/channel.go`, `server/internal/services/channels.go`, `server/internal/notify/` (`dispatch.go`, `webhook.go`, `smtp.go`, `discord.go`, `slack.go`, `telegram.go`), `server/internal/api/channels.go`
-- Modify: `server/internal/services/monitors.go` (replace the P2 `// TODO(P3): dispatch` hook)
-
-**Interfaces:**
-- Produces: `models.NotificationChannel{channel_id, name, type, config map, enabled}`. `notify.Dispatch(channel, event)` where `event` = monitor + old/new status + message. `notify.Test(channel)`.
-
-- [ ] **Step 1: Model + CRUD service + REST** (`/api/channels*`, incl. `POST /api/channels/:id/test`).
-- [ ] **Step 2: Dispatch abstraction** — webhook/discord/slack/telegram are HTTP POST with per-type JSON payload; SMTP via `net/smtp`. Per-monitor routing via `monitor.ChannelIDs`; resend interval so an ongoing `down` re-alerts at most every N min (track `last_notified_at` on monitor state).
-- [ ] **Step 3: Fire on transition** — in `IngestResult`, on up/down flip resolve channels and `notify.Dispatch` each (goroutine, best-effort, log failures).
-- [ ] **Step 4: Verify build** — `go build ./... && go vet ./...`
-- [ ] **Step 5: Commit** — `feat(server): multi-channel monitor notifications`
-
----
-
-## Task 14: Frontend — notification settings (P3)
-
-**Files:**
-- Modify: `web/lib/api.ts` (channel types + bindings), `web/app/settings/` (add notifications section/page)
-- Modify: monitor create/edit form (Task 10) to select channels
-
-**Interfaces:**
-- Consumes: `/api/channels*`.
-
-- [ ] **Step 1: Channel types + api bindings.**
-- [ ] **Step 2: Settings UI** — list/add/edit channels, type-dependent config fields, **Test** button hitting `/api/channels/:id/test`.
-- [ ] **Step 3: Wire channel multi-select** into the monitor form.
-- [ ] **Step 4: Verify build** — `cd web && npm run build`
-- [ ] **Step 5: Commit** — `feat(web): notification channel settings UI`
-
----
-
-## Self-Review Notes
-
-- **Spec coverage:** §3 model → T1; §4 RPC → T1; §5 collectors + scheduler → T3, T4; §6 handler/store → T2; §7 frontend → T5. Split cadence (30s metrics / 15m static) in T4 scheduler; merge rules preserving static in T2 `StoreInventory`. Tests omitted per Global Constraints.
-- **Startup snapshot:** agent sends `Collect(true)` immediately so static fields populate without waiting 15 min.
-- **Types consistent:** `InventoryReport` field names identical across proto, both pb files, store service, and TS interface (`usage_pct`, `used_bytes`, `total_bytes`, `swap_*`).
-- **Follow-ups (out of scope):** time-series history, usage alerting, Windows collectors, servers-list CPU/RAM badges.
-- **Monitoring (Tasks 7–14):** hybrid runner service-monitor replacing uptime-kuma, added 2026-07-21. 3 phases — P1 server-run engine+UI (T7–10), P2 agent-run RPCs (T11–12), P3 multi-channel notify (T13–14). Single `IngestResult` pipeline for both runners; checker pkg duplicated per module (pb convention). Design: brainstorm 2026-07-21. Follow-ups out of scope: status pages, maintenance windows, per-check auth headers, ICMP on Windows.