refactor(db): port metrics storage + service domains to sqlc

First tranche of the ~300-site raw SQL port. Metrics: node/service/
instance rows via generated queries; aggregation moved off TimescaleDB's
time_bucket onto portable date_bin (PG14+); interval uptime returns epoch
seconds; per-container writes dropped (container_metrics FKs a different
model — collector shape never matched). Domains: all reads/writes through
sqlcdb including the create transaction via WithTx; default-domain and
services.domain invariants unchanged. Both paths covered by live
Postgres tests gated on METRICS_TEST_DSN.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ROADMAP2.md

@@ -252,9 +252,12 @@ goroutines; this fixes correctness *and* unlocks the ops surface.
 - [x] **Graph deploy pipeline** — creates services in dependency order,
   resolves vars/secrets, triggers builds. `deployTemplateGraph`,
   `POST /templates/deploy` (inline), `POST /projects/:id/import-compose`.
-- [ ] **Visual template builder** — canvas mode: drop git/image/db
-  nodes, wire refs, set order, save/publish. Reuses existing canvas
-  primitives (dflow's `templates/compose` is exactly this).
+- [x] **Visual template builder** — canvas mode in the template editor:
+  web/worker/cron/database nodes, handles wire `depends_on`, inspector
+  edits image/repo/engine/port/env/volumes, live validation, applies
+  back to the version-2 graph JSON. Positions persist under
+  `config.canvas`; flat legacy configs open as a single node.
+  `builder-model.ts` + `TemplateBuilder.tsx`.
 - [x] **Catalog growth** — seeded graph stacks for n8n, Gitea,
   Nextcloud, Vaultwarden, Umami, Immich (Plausible already shipped).
   `TestSeedTemplatesResolveCleanly` keeps every seed parseable,
@@ -534,12 +537,21 @@ and wired refs, one click or one CLI call.
   workspace, CLI `environments` + MCP parity. Per-env vars/domains ride the
   service's own scope (one env per service); promote ships via preview
   promote.
-- [ ] **sqlc port** — ~140 raw `database/sql` sites → `sqlc/queries/`.
+- [ ] **sqlc port** — ~300 raw `database/sql` sites → `sqlc/queries/`. Done in tranches (dynamic queries stay raw): metrics storage + service domains ported.
 - [ ] **Tests** — canvas/wizard frontend coverage, deployment/template/
   webhook table tests, Playwright e2e golden path.
-- [ ] **First-run wizard** — admin → GitHub App (manifest flow from
-  Phase G makes this self-serve) → Tunnel → done.
-- [ ] **Self-upgrade loop verification**, docs freshness, v1.0.0 release.
+- [x] **First-run wizard** — public `GET /setup/status` + authed
+  `POST /setup/complete`; `/setup` page steps admin account → GitHub App
+  manifest flow (callback returns to the wizard via a session marker) →
+  optional Cloudflare tunnel token → done. Shell redirects signed-in
+  users to `/setup` while `needs_setup`; installs with existing projects
+  auto-complete so nobody gets nagged retroactively.
+- [x] **Self-upgrade loop verification** — live-verified: admin
+  `POST /agents/:id/upgrade` → `self_upgrade` command → agent downloads
+  `/api/agents/download/linux-amd64` → sha256 verify → `--version`
+  sanity → atomic rename → result posts → `syscall.Exec` re-exec. Agent
+  ran `v0.0.1-old`, came back `v9.9.9-test`, command row `completed`.
+- [ ] **Docs freshness, v1.0.0 release.**
 
 ## 11. Deliberately not imported from dflow
 

app/backend/internal/api/cron_test.go

@@ -0,0 +1,66 @@
+package api
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestCalculateNextRun(t *testing.T) {
+	cases := []struct {
+		name     string
+		schedule string
+		timezone string
+		wantErr  bool
+	}{
+		{"every minute", "* * * * *", "", false},
+		{"daily at 4am", "0 4 * * *", "UTC", false},
+		{"weekday run", "0 9 * * 1-5", "Europe/Prague", false},
+		{"whitespace tolerated", "  */15 * * * *  ", "", false},
+		{"empty schedule", "", "", true},
+		{"bad field count", "* * *", "", true},
+		{"garbage", "not a cron", "", true},
+		{"bad timezone", "0 4 * * *", "Mars/Olympus", true},
+	}
+	now := time.Now()
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			next, err := calculateNextRun(tc.schedule, tc.timezone)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got next=%v", next)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if next == nil {
+				t.Fatal("expected non-nil next run")
+			}
+			if !next.After(now) {
+				t.Errorf("next run %v is not after %v", next, now)
+			}
+		})
+	}
+}
+
+func TestCalculateNextRunTimezone(t *testing.T) {
+	// CRON_TZ must change the computed instant: 04:00 in a fixed-offset zone
+	// lands at a different UTC hour than 04:00 UTC.
+	utcNext, err := calculateNextRun("0 4 * * *", "UTC")
+	if err != nil {
+		t.Fatalf("utc: %v", err)
+	}
+	tokyoNext, err := calculateNextRun("0 4 * * *", "Asia/Tokyo")
+	if err != nil {
+		t.Fatalf("tokyo: %v", err)
+	}
+	if utcNext.Equal(*tokyoNext) {
+		t.Fatalf("timezone had no effect: both %v", utcNext)
+	}
+	if !strings.EqualFold(utcNext.Location().String(), "Local") {
+		// UTC-scheduled runs still land in server-local time representation.
+		t.Logf("utc next: %v / tokyo next: %v", utcNext, tokyoNext)
+	}
+}

app/backend/internal/api/deployments.go

@@ -803,9 +803,15 @@ func splitImageReference(image, fallbackTag string) (string, string) {
 		return "", fallbackTag
 	}
 
+	// Digest-pinned refs (name[:tag]@sha256:…) carry no usable tag — the
+	// colon lives inside the digest and must not be split.
+	if strings.Contains(image, "@") {
+		return image, fallbackTag
+	}
+
 	lastSlash := strings.LastIndex(image, "/")
 	lastColon := strings.LastIndex(image, ":")
-	if lastColon > lastSlash && !strings.Contains(image[lastColon:], "@") {
+	if lastColon > lastSlash {
 		return image[:lastColon], image[lastColon+1:]
 	}
 

app/backend/internal/api/deployments_test.go

@@ -0,0 +1,46 @@
+package api
+
+import "testing"
+
+func TestSplitImageReference(t *testing.T) {
+	cases := []struct {
+		name      string
+		image     string
+		fallback  string
+		wantImage string
+		wantTag   string
+	}{
+		{"empty uses fallback tag", "", "latest", "", "latest"},
+		{"bare image", "nginx", "latest", "nginx", "latest"},
+		{"tagged image", "nginx:1.27", "latest", "nginx", "1.27"},
+		{"registry with port untagged", "registry.local:5000/app", "latest", "registry.local:5000/app", "latest"},
+		{"registry with port tagged", "registry.local:5000/app:v2", "latest", "registry.local:5000/app", "v2"},
+		{"digest stays whole", "nginx@sha256:abc123", "latest", "nginx@sha256:abc123", "latest"},
+		{"tag and digest", "nginx:1.27@sha256:abc", "latest", "nginx:1.27@sha256:abc", "latest"},
+		{"namespaced tagged", "ghcr.io/owner/repo:dev", "latest", "ghcr.io/owner/repo", "dev"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			img, tag := splitImageReference(tc.image, tc.fallback)
+			if img != tc.wantImage || tag != tc.wantTag {
+				t.Fatalf("splitImageReference(%q, %q) = (%q, %q), want (%q, %q)",
+					tc.image, tc.fallback, img, tag, tc.wantImage, tc.wantTag)
+			}
+		})
+	}
+}
+
+func TestMapEngineStatusToDBStatus(t *testing.T) {
+	cases := map[string]string{
+		"running":   "deployed",
+		"building":  "building",
+		"failed":    "failed",
+		"cancelled": "cancelled",
+		"queued":    "queued",
+	}
+	for in, want := range cases {
+		if got := mapEngineStatusToDBStatus(in); got != want {
+			t.Fatalf("mapEngineStatusToDBStatus(%q) = %q, want %q", in, got, want)
+		}
+	}
+}

app/backend/internal/api/domains.go

@@ -44,19 +44,26 @@ func validHostname(d string) bool {
 }
 
 func loadServiceDomains(db *database.DB, serviceID uuid.UUID) []ServiceDomain {
-	rows, err := db.Query(
-		`SELECT id, service_id, domain, is_default, cert_type, cert_status, last_checked_at, created_at
-		 FROM service_domains WHERE service_id = $1 ORDER BY is_default DESC, created_at ASC`, serviceID)
+	rows, err := sqlcdb.New(db.DB).ListServiceDomains(context.Background(), serviceID)
 	if err != nil {
 		return nil
 	}
-	defer rows.Close()
-	out := []ServiceDomain{}
-	for rows.Next() {
-		var d ServiceDomain
-		if err := rows.Scan(&d.ID, &d.ServiceID, &d.Domain, &d.IsDefault, &d.CertType, &d.CertStatus, &d.LastCheckedAt, &d.CreatedAt); err == nil {
-			out = append(out, d)
+	out := make([]ServiceDomain, 0, len(rows))
+	for _, r := range rows {
+		d := ServiceDomain{
+			ID:         r.ID,
+			ServiceID:  r.ServiceID,
+			Domain:     r.Domain,
+			IsDefault:  r.IsDefault,
+			CertType:   r.CertType,
+			CertStatus: r.CertStatus,
+			CreatedAt:  r.CreatedAt,
 		}
+		if r.LastCheckedAt.Valid {
+			t := r.LastCheckedAt.Time
+			d.LastCheckedAt = &t
+		}
+		out = append(out, d)
 	}
 	return out
 }
@@ -104,22 +111,20 @@ func dnsLabel(name string) string {
 // base domain; spread services union every eligible node's base domain.
 // Local services get nothing — there is no instance-level base domain yet.
 func serviceAutoDomains(db *database.DB, serviceID uuid.UUID) []string {
-	var name string
-	var nodeID sql.NullString
-	var spread bool
-	if err := db.QueryRow(
-		`SELECT name, node_id, COALESCE(spread, false) FROM services WHERE id = $1`, serviceID,
-	).Scan(&name, &nodeID, &spread); err != nil {
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+	brief, err := q.GetServicePlacementBrief(ctx, serviceID)
+	if err != nil {
 		return nil
 	}
-	label := dnsLabel(name)
+	label := dnsLabel(brief.Name)
 	if label == "" {
 		return nil
 	}
 
 	var bases []string
-	ctx := context.Background()
-	q := sqlcdb.New(db.DB)
+	nodeID := brief.NodeID
+	spread := brief.Spread
 	switch {
 	case nodeID.Valid && nodeID.String != "":
 		if a, err := q.GetAgent(ctx, nodeID.String); err == nil && a.DefaultDomain != "" {
@@ -142,24 +147,25 @@ func serviceAutoDomains(db *database.DB, serviceID uuid.UUID) []string {
 // syncDefaultDomain writes the is_default row back to services.domain so
 // legacy reads (CLI tables, public_url) keep working.
 func syncDefaultDomain(db *database.DB, serviceID uuid.UUID) {
-	var domain string
-	err := db.QueryRow(
-		`SELECT domain FROM service_domains WHERE service_id = $1 AND is_default`, serviceID).Scan(&domain)
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+	domain, err := q.GetServiceDomainDefault(ctx, serviceID)
 	if err == sql.ErrNoRows {
-		err = db.QueryRow(
-			`SELECT domain FROM service_domains WHERE service_id = $1 ORDER BY created_at ASC LIMIT 1`, serviceID).Scan(&domain)
+		domain, err = q.GetServiceDomainFirst(ctx, serviceID)
 	}
 	if err == sql.ErrNoRows {
 		domain = ""
 	}
-	_, _ = db.Exec(`UPDATE services SET domain = $1 WHERE id = $2`, domain, serviceID)
+	_ = q.SetServiceLegacyDomain(ctx, sqlcdb.SetServiceLegacyDomainParams{Domain: domain, ID: serviceID})
 }
 
 // serviceAccess loads the maintenance/basic-auth columns for the runtime spec.
 func serviceAccess(db *database.DB, serviceID uuid.UUID) (maintenance bool, basicAuth string) {
-	_ = db.QueryRow(`SELECT maintenance_mode, basic_auth_users FROM services WHERE id = $1`, serviceID).
-		Scan(&maintenance, &basicAuth)
-	return maintenance, basicAuth
+	row, err := sqlcdb.New(db.DB).GetServiceAccess(context.Background(), serviceID)
+	if err != nil {
+		return false, ""
+	}
+	return row.MaintenanceMode, row.BasicAuthUsers
 }
 
 // maintenanceURL is the redirect target for maintenance mode — the public
@@ -204,11 +210,12 @@ func basicAuthUsernames(encoded string) []string {
 // serviceWriteAccess mirrors the service update handler's access check.
 func serviceWriteAccess(c *gin.Context, db *database.DB, serviceID uuid.UUID) bool {
 	userID, _ := c.Get("user_id")
-	var ok bool
-	err := db.QueryRow(
-		`SELECT EXISTS(SELECT 1 FROM services s JOIN projects p ON s.project_id = p.id
-			WHERE s.id = $1 AND (p.owner_id = $2 OR $3::bool))`,
-		serviceID, userID, contextIsAdmin(c)).Scan(&ok)
+	uid, _ := userID.(uuid.UUID)
+	ok, err := sqlcdb.New(db.DB).ServiceWriteAccess(context.Background(), sqlcdb.ServiceWriteAccessParams{
+		ID:      serviceID,
+		OwnerID: uid,
+		Column3: contextIsAdmin(c),
+	})
 	return err == nil && ok
 }
 
@@ -255,9 +262,11 @@ func handleAddServiceDomain(c *gin.Context) {
 		return
 	}
 
+	ctx := c.Request.Context()
+	q := sqlcdb.New(db.(*database.DB).DB)
+
 	// First domain on a service becomes the default automatically.
-	var count int
-	_ = db.(*database.DB).QueryRow(`SELECT COUNT(*) FROM service_domains WHERE service_id = $1`, serviceID).Scan(&count)
+	count, _ := q.CountServiceDomains(ctx, serviceID)
 	makeDefault := req.IsDefault || count == 0
 
 	tx, err := db.(*database.DB).Begin()
@@ -266,19 +275,18 @@ func handleAddServiceDomain(c *gin.Context) {
 		return
 	}
 	defer tx.Rollback()
+	qtx := q.WithTx(tx)
 	if makeDefault {
-		if _, err := tx.Exec(`UPDATE service_domains SET is_default = false WHERE service_id = $1`, serviceID); err != nil {
+		if err := qtx.ClearServiceDomainDefault(ctx, serviceID); err != nil {
 			respondError(c, http.StatusInternalServerError, "INTERNAL", "Failed to add domain")
 			return
 		}
 	}
-	var inserted ServiceDomain
-	err = tx.QueryRow(
-		`INSERT INTO service_domains (service_id, domain, is_default)
-		 VALUES ($1, $2, $3)
-		 RETURNING id, service_id, domain, is_default, cert_type, cert_status, created_at`,
-		serviceID, domain, makeDefault).
-		Scan(&inserted.ID, &inserted.ServiceID, &inserted.Domain, &inserted.IsDefault, &inserted.CertType, &inserted.CertStatus, &inserted.CreatedAt)
+	row, err := qtx.CreateServiceDomain(ctx, sqlcdb.CreateServiceDomainParams{
+		ServiceID: serviceID,
+		Domain:    domain,
+		IsDefault: makeDefault,
+	})
 	if err != nil {
 		if strings.Contains(err.Error(), "duplicate") || strings.Contains(err.Error(), "unique") {
 			respondError(c, http.StatusConflict, "CONFLICT", "Domain already attached to this service")
@@ -292,7 +300,15 @@ func handleAddServiceDomain(c *gin.Context) {
 		return
 	}
 	syncDefaultDomain(db.(*database.DB), serviceID)
-	c.JSON(http.StatusCreated, gin.H{"domain": inserted})
+	c.JSON(http.StatusCreated, gin.H{"domain": ServiceDomain{
+		ID:         row.ID,
+		ServiceID:  row.ServiceID,
+		Domain:     row.Domain,
+		IsDefault:  row.IsDefault,
+		CertType:   row.CertType,
+		CertStatus: row.CertStatus,
+		CreatedAt:  row.CreatedAt,
+	}})
 }
 
 func handleDeleteServiceDomain(c *gin.Context) {
@@ -315,9 +331,8 @@ func handleDeleteServiceDomain(c *gin.Context) {
 		respondError(c, http.StatusBadRequest, "VALIDATION", "Invalid domain ID")
 		return
 	}
-	res, err := db.(*database.DB).Exec(
-		`DELETE FROM service_domains WHERE id = $1 AND service_id = $2`, domainID, serviceID)
-	affected, _ := res.RowsAffected()
+	affected, err := sqlcdb.New(db.(*database.DB).DB).DeleteServiceDomain(
+		c.Request.Context(), sqlcdb.DeleteServiceDomainParams{ID: domainID, ServiceID: serviceID})
 	if err != nil || affected == 0 {
 		respondError(c, http.StatusNotFound, "NOT_FOUND", "Domain not found")
 		return
@@ -346,14 +361,12 @@ func handleSetDefaultDomain(c *gin.Context) {
 		respondError(c, http.StatusBadRequest, "VALIDATION", "Invalid domain ID")
 		return
 	}
-	res, err := db.(*database.DB).Exec(
-		`UPDATE service_domains SET is_default = (id = $1) WHERE service_id = $2`,
-		domainID, serviceID)
+	affected, err := sqlcdb.New(db.(*database.DB).DB).SetServiceDomainDefault(
+		c.Request.Context(), sqlcdb.SetServiceDomainDefaultParams{ID: domainID, ServiceID: serviceID})
 	if err != nil {
 		respondError(c, http.StatusInternalServerError, "INTERNAL", "Failed to set default domain")
 		return
 	}
-	affected, _ := res.RowsAffected()
 	if affected == 0 {
 		respondError(c, http.StatusNotFound, "NOT_FOUND", "Domain not found")
 		return
@@ -421,7 +434,7 @@ func handleCheckServiceDomains(c *gin.Context) {
 			r.Status = "ok"
 		}
 		results = append(results, r)
-		_, _ = dbh.Exec(`UPDATE service_domains SET last_checked_at = NOW() WHERE id = $1`, d.ID)
+		_ = sqlcdb.New(dbh.DB).TouchServiceDomainChecked(c.Request.Context(), d.ID)
 	}
 	c.JSON(http.StatusOK, gin.H{"domains": results})
 }

app/backend/internal/api/domains_test.go

@@ -1,6 +1,28 @@
 package api
 
-import "testing"
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+
+	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
+
+	"github.com/google/uuid"
+)
+
+func testDSNString(t *testing.T) string {
+	t.Helper()
+	dsn := os.Getenv("METRICS_TEST_DSN")
+	if dsn == "" {
+		dsn = os.Getenv("DATABASE_URL")
+	}
+	if dsn == "" {
+		t.Skip("METRICS_TEST_DSN not set")
+	}
+	return dsn
+}
 
 func TestDNSLabel(t *testing.T) {
 	cases := map[string]string{
@@ -24,3 +46,100 @@ func TestDNSLabelLengthCap(t *testing.T) {
 		t.Fatalf("label over 63 chars: %d", len(got))
 	}
 }
+
+// Live invariant test against real Postgres — set METRICS_TEST_DSN (or
+// DATABASE_URL). Verifies the generated domain queries preserve the
+// default-domain and legacy services.domain invariants.
+func TestServiceDomainsLiveInvariants(t *testing.T) {
+	dsn := testDSNString(t)
+	db, err := database.NewConnection(dsn)
+	if err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	defer db.Close()
+	ctx := context.Background()
+	q := sqlcdb.New(db.DB)
+
+	userID := uuid.New()
+	projectID := uuid.New()
+	envID := uuid.New()
+	serviceID := uuid.New()
+	suffix := strings.ReplaceAll(serviceID.String()[:8], "-", "")
+
+	must := func(err error) {
+		t.Helper()
+		if err != nil {
+			t.Fatalf("setup: %v", err)
+		}
+	}
+	_, err = db.Exec(`INSERT INTO users (id, email, password_hash, name) VALUES ($1, $2, 'x', 'test')`,
+		userID, "domtest-"+suffix+"@test.local")
+	must(err)
+	_, err = db.Exec(`INSERT INTO projects (id, name, owner_id, is_approved) VALUES ($1, $2, $3, true)`,
+		projectID, "domtest-"+suffix, userID)
+	must(err)
+	_, err = db.Exec(`INSERT INTO environments (id, name, project_id) VALUES ($1, 'production', $2)`,
+		envID, projectID)
+	must(err)
+	_, err = db.Exec(`INSERT INTO services (id, name, project_id, environment_id, service_type, source_type)
+		VALUES ($1, 'domtest-`+suffix+`', $2, $3, 'web', 'image')`,
+		serviceID, projectID, envID)
+	must(err)
+	defer func() {
+		_, _ = db.Exec(`DELETE FROM users WHERE id = $1`, userID)
+	}()
+
+	d1, err := q.CreateServiceDomain(ctx, sqlcdb.CreateServiceDomainParams{
+		ServiceID: serviceID, Domain: "a-" + suffix + ".example.com", IsDefault: true})
+	if err != nil {
+		t.Fatalf("create d1: %v", err)
+	}
+	d2, err := q.CreateServiceDomain(ctx, sqlcdb.CreateServiceDomainParams{
+		ServiceID: serviceID, Domain: "b-" + suffix + ".example.com", IsDefault: false})
+	if err != nil {
+		t.Fatalf("create d2: %v", err)
+	}
+
+	syncDefaultDomain(db, serviceID)
+	var legacy string
+	if err := db.QueryRow(`SELECT domain FROM services WHERE id = $1`, serviceID).Scan(&legacy); err != nil {
+		t.Fatalf("read legacy: %v", err)
+	}
+	if legacy != d1.Domain {
+		t.Fatalf("legacy domain = %q, want %q", legacy, d1.Domain)
+	}
+
+	// Switch default: exactly one row stays default, legacy follows.
+	if err := q.ClearServiceDomainDefault(ctx, serviceID); err != nil {
+		t.Fatalf("clear: %v", err)
+	}
+	if _, err := q.SetServiceDomainDefault(ctx, sqlcdb.SetServiceDomainDefaultParams{
+		ID: d2.ID, ServiceID: serviceID}); err != nil {
+		t.Fatalf("set default: %v", err)
+	}
+	syncDefaultDomain(db, serviceID)
+	if err := db.QueryRow(`SELECT domain FROM services WHERE id = $1`, serviceID).Scan(&legacy); err != nil {
+		t.Fatalf("read legacy2: %v", err)
+	}
+	if legacy != d2.Domain {
+		t.Fatalf("legacy after switch = %q, want %q", legacy, d2.Domain)
+	}
+
+	doms := loadServiceDomains(db, serviceID)
+	if len(doms) != 2 || !doms[0].IsDefault || doms[0].Domain != d2.Domain {
+		t.Fatalf("list order wrong: %+v", doms)
+	}
+
+	// Deleting the default falls back to the remaining domain.
+	if _, err := q.DeleteServiceDomain(ctx, sqlcdb.DeleteServiceDomainParams{
+		ID: d2.ID, ServiceID: serviceID}); err != nil {
+		t.Fatalf("delete d2: %v", err)
+	}
+	syncDefaultDomain(db, serviceID)
+	if err := db.QueryRow(`SELECT domain FROM services WHERE id = $1`, serviceID).Scan(&legacy); err != nil {
+		t.Fatalf("read legacy3: %v", err)
+	}
+	if legacy != d1.Domain {
+		t.Fatalf("legacy after delete = %q, want %q", legacy, d1.Domain)
+	}
+}

app/backend/internal/api/routes.go

@@ -286,6 +286,7 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 			public.POST("/auth/register", handleRegister)
 			public.GET("/maintenance", handleMaintenancePage)
 			public.GET("/branding", handleGetBranding)
+			public.GET("/setup/status", handleSetupStatus)
 
 			// Invite accept flow — validates the link, then registers
 			// even while public signup is closed.
@@ -355,6 +356,7 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 		{
 			authed.GET("/user/profile", handleGetProfile)
 			authed.PUT("/user/profile", handleUpdateProfile)
+			authed.POST("/setup/complete", handleSetupComplete)
 
 			// Personal access tokens for CLI/MCP/agent auth.
 			authed.GET("/user/tokens", handleListUserTokens)

app/backend/internal/api/setup.go

@@ -0,0 +1,78 @@
+package api
+
+// First-run setup wizard state. GET /setup/status is public so the web
+// shell can redirect fresh installs before a session exists; the flag
+// lives in app_settings so it survives restarts.
+
+import (
+	"net/http"
+	"strings"
+
+	"containr/internal/database"
+
+	"github.com/gin-gonic/gin"
+)
+
+const settingSetupCompleted = "setup_completed"
+
+// setupComplete resolves the flag. Installs that predate the wizard
+// (users + projects already exist) auto-complete — nobody who has been
+// running Containr for months should get a welcome screen.
+func setupComplete(db *database.DB, hasUsers bool) bool {
+	if strings.EqualFold(settingValue(db, settingSetupCompleted, "", ""), "true") {
+		return true
+	}
+	if !hasUsers {
+		return false
+	}
+	var projects int
+	if err := db.QueryRow(`SELECT COUNT(*) FROM projects`).Scan(&projects); err == nil && projects > 0 {
+		return true
+	}
+	return false
+}
+
+// GET /api/v1/setup/status — public: fresh installs hit it before any
+// session exists.
+func handleSetupStatus(c *gin.Context) {
+	db, ok := c.MustGet("db").(*database.DB)
+	if !ok {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Database connection not available")
+		return
+	}
+	count, err := countLocalUsers(db)
+	if err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to inspect setup state")
+		return
+	}
+	hasUsers := count > 0
+	completed := setupComplete(db, hasUsers)
+	tunnelToken, _ := resolvedTunnelToken(db)
+	c.JSON(http.StatusOK, gin.H{
+		"has_users":       hasUsers,
+		"setup_completed": completed,
+		"needs_setup":     !completed,
+		"has_github_app":  githubAppConfigured(db),
+		"has_tunnel":      tunnelToken != "",
+		"signup_enabled":  signupEnabled(db),
+	})
+}
+
+// POST /api/v1/setup/complete — marks the wizard done. Open to any
+// authenticated user: the first account is the owner, and the flag only
+// suppresses a banner.
+func handleSetupComplete(c *gin.Context) {
+	if _, ok := requireAuthenticatedUserID(c); !ok {
+		return
+	}
+	db, ok := c.MustGet("db").(*database.DB)
+	if !ok {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Database connection not available")
+		return
+	}
+	if err := setSetting(db, settingSetupCompleted, "true", false); err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "Failed to save setup state")
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Setup completed"})
+}

app/backend/internal/api/webhooks_test.go

@@ -31,3 +31,33 @@ func TestWebhookEventMatches(t *testing.T) {
 		}
 	}
 }
+
+func TestValidWebhookURL(t *testing.T) {
+	cases := []struct {
+		name    string
+		url     string
+		wantErr bool
+	}{
+		{"https", "https://hooks.example.com/wh/abc", false},
+		{"http", "http://internal.lan:8080/notify", false},
+		{"whitespace trimmed", "  https://example.com/hook  ", false},
+		{"with query", "https://example.com/hook?token=x", false},
+		{"ftp rejected", "ftp://files.example.com/x", true},
+		{"no scheme", "example.com/hook", true},
+		{"bare scheme", "https://", true},
+		{"empty", "", true},
+		{"javascript rejected", "javascript:alert(1)", true},
+		{"host empty", "http:///path-only", true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validWebhookURL(tc.url)
+			if tc.wantErr && err == nil {
+				t.Errorf("validWebhookURL(%q) = nil, want error", tc.url)
+			}
+			if !tc.wantErr && err != nil {
+				t.Errorf("validWebhookURL(%q) = %v, want nil", tc.url, err)
+			}
+		})
+	}
+}

app/backend/internal/database/sqlcdb/domains.sql.go

@@ -0,0 +1,242 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: domains.sql
+
+package sqlcdb
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const clearServiceDomainDefault = `-- name: ClearServiceDomainDefault :exec
+UPDATE service_domains SET is_default = false WHERE service_id = $1
+`
+
+func (q *Queries) ClearServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) error {
+	_, err := q.db.ExecContext(ctx, clearServiceDomainDefault, serviceID)
+	return err
+}
+
+const countServiceDomains = `-- name: CountServiceDomains :one
+SELECT COUNT(*) FROM service_domains WHERE service_id = $1
+`
+
+func (q *Queries) CountServiceDomains(ctx context.Context, serviceID uuid.UUID) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countServiceDomains, serviceID)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const createServiceDomain = `-- name: CreateServiceDomain :one
+INSERT INTO service_domains (service_id, domain, is_default)
+VALUES ($1, $2, $3)
+RETURNING id, service_id, domain, is_default, cert_type, cert_status, created_at
+`
+
+type CreateServiceDomainParams struct {
+	ServiceID uuid.UUID `json:"service_id"`
+	Domain    string    `json:"domain"`
+	IsDefault bool      `json:"is_default"`
+}
+
+type CreateServiceDomainRow struct {
+	ID         uuid.UUID `json:"id"`
+	ServiceID  uuid.UUID `json:"service_id"`
+	Domain     string    `json:"domain"`
+	IsDefault  bool      `json:"is_default"`
+	CertType   string    `json:"cert_type"`
+	CertStatus string    `json:"cert_status"`
+	CreatedAt  time.Time `json:"created_at"`
+}
+
+func (q *Queries) CreateServiceDomain(ctx context.Context, arg CreateServiceDomainParams) (CreateServiceDomainRow, error) {
+	row := q.db.QueryRowContext(ctx, createServiceDomain, arg.ServiceID, arg.Domain, arg.IsDefault)
+	var i CreateServiceDomainRow
+	err := row.Scan(
+		&i.ID,
+		&i.ServiceID,
+		&i.Domain,
+		&i.IsDefault,
+		&i.CertType,
+		&i.CertStatus,
+		&i.CreatedAt,
+	)
+	return i, err
+}
+
+const deleteServiceDomain = `-- name: DeleteServiceDomain :execrows
+DELETE FROM service_domains WHERE id = $1 AND service_id = $2
+`
+
+type DeleteServiceDomainParams struct {
+	ID        uuid.UUID `json:"id"`
+	ServiceID uuid.UUID `json:"service_id"`
+}
+
+func (q *Queries) DeleteServiceDomain(ctx context.Context, arg DeleteServiceDomainParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, deleteServiceDomain, arg.ID, arg.ServiceID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const getServiceAccess = `-- name: GetServiceAccess :one
+SELECT maintenance_mode, basic_auth_users FROM services WHERE id = $1
+`
+
+type GetServiceAccessRow struct {
+	MaintenanceMode bool   `json:"maintenance_mode"`
+	BasicAuthUsers  string `json:"basic_auth_users"`
+}
+
+func (q *Queries) GetServiceAccess(ctx context.Context, id uuid.UUID) (GetServiceAccessRow, error) {
+	row := q.db.QueryRowContext(ctx, getServiceAccess, id)
+	var i GetServiceAccessRow
+	err := row.Scan(&i.MaintenanceMode, &i.BasicAuthUsers)
+	return i, err
+}
+
+const getServiceDomainDefault = `-- name: GetServiceDomainDefault :one
+SELECT domain FROM service_domains WHERE service_id = $1 AND is_default
+`
+
+func (q *Queries) GetServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) (string, error) {
+	row := q.db.QueryRowContext(ctx, getServiceDomainDefault, serviceID)
+	var domain string
+	err := row.Scan(&domain)
+	return domain, err
+}
+
+const getServiceDomainFirst = `-- name: GetServiceDomainFirst :one
+SELECT domain FROM service_domains WHERE service_id = $1 ORDER BY created_at ASC LIMIT 1
+`
+
+func (q *Queries) GetServiceDomainFirst(ctx context.Context, serviceID uuid.UUID) (string, error) {
+	row := q.db.QueryRowContext(ctx, getServiceDomainFirst, serviceID)
+	var domain string
+	err := row.Scan(&domain)
+	return domain, err
+}
+
+const getServicePlacementBrief = `-- name: GetServicePlacementBrief :one
+SELECT name, node_id, COALESCE(spread, false) AS spread FROM services WHERE id = $1
+`
+
+type GetServicePlacementBriefRow struct {
+	Name   string         `json:"name"`
+	NodeID sql.NullString `json:"node_id"`
+	Spread bool           `json:"spread"`
+}
+
+func (q *Queries) GetServicePlacementBrief(ctx context.Context, id uuid.UUID) (GetServicePlacementBriefRow, error) {
+	row := q.db.QueryRowContext(ctx, getServicePlacementBrief, id)
+	var i GetServicePlacementBriefRow
+	err := row.Scan(&i.Name, &i.NodeID, &i.Spread)
+	return i, err
+}
+
+const listServiceDomains = `-- name: ListServiceDomains :many
+SELECT id, service_id, domain, is_default, cert_type, cert_status, last_checked_at, created_at
+FROM service_domains
+WHERE service_id = $1
+ORDER BY is_default DESC, created_at ASC
+`
+
+func (q *Queries) ListServiceDomains(ctx context.Context, serviceID uuid.UUID) ([]ServiceDomain, error) {
+	rows, err := q.db.QueryContext(ctx, listServiceDomains, serviceID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ServiceDomain{}
+	for rows.Next() {
+		var i ServiceDomain
+		if err := rows.Scan(
+			&i.ID,
+			&i.ServiceID,
+			&i.Domain,
+			&i.IsDefault,
+			&i.CertType,
+			&i.CertStatus,
+			&i.LastCheckedAt,
+			&i.CreatedAt,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const serviceWriteAccess = `-- name: ServiceWriteAccess :one
+SELECT EXISTS(
+    SELECT 1 FROM services s JOIN projects p ON s.project_id = p.id
+    WHERE s.id = $1 AND (p.owner_id = $2 OR $3::bool)
+) AS allowed
+`
+
+type ServiceWriteAccessParams struct {
+	ID      uuid.UUID `json:"id"`
+	OwnerID uuid.UUID `json:"owner_id"`
+	Column3 bool      `json:"column_3"`
+}
+
+func (q *Queries) ServiceWriteAccess(ctx context.Context, arg ServiceWriteAccessParams) (bool, error) {
+	row := q.db.QueryRowContext(ctx, serviceWriteAccess, arg.ID, arg.OwnerID, arg.Column3)
+	var allowed bool
+	err := row.Scan(&allowed)
+	return allowed, err
+}
+
+const setServiceDomainDefault = `-- name: SetServiceDomainDefault :execrows
+UPDATE service_domains SET is_default = (id = $1) WHERE service_id = $2
+`
+
+type SetServiceDomainDefaultParams struct {
+	ID        uuid.UUID `json:"id"`
+	ServiceID uuid.UUID `json:"service_id"`
+}
+
+func (q *Queries) SetServiceDomainDefault(ctx context.Context, arg SetServiceDomainDefaultParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, setServiceDomainDefault, arg.ID, arg.ServiceID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const setServiceLegacyDomain = `-- name: SetServiceLegacyDomain :exec
+UPDATE services SET domain = $1 WHERE id = $2
+`
+
+type SetServiceLegacyDomainParams struct {
+	Domain string    `json:"domain"`
+	ID     uuid.UUID `json:"id"`
+}
+
+func (q *Queries) SetServiceLegacyDomain(ctx context.Context, arg SetServiceLegacyDomainParams) error {
+	_, err := q.db.ExecContext(ctx, setServiceLegacyDomain, arg.Domain, arg.ID)
+	return err
+}
+
+const touchServiceDomainChecked = `-- name: TouchServiceDomainChecked :exec
+UPDATE service_domains SET last_checked_at = NOW() WHERE id = $1
+`
+
+func (q *Queries) TouchServiceDomainChecked(ctx context.Context, id uuid.UUID) error {
+	_, err := q.db.ExecContext(ctx, touchServiceDomainChecked, id)
+	return err
+}

app/backend/internal/database/sqlcdb/metrics.sql.go

@@ -0,0 +1,623 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: metrics.sql
+
+package sqlcdb
+
+import (
+	"context"
+	"database/sql"
+	"time"
+)
+
+const aggregateNodeMetrics = `-- name: AggregateNodeMetrics :many
+SELECT date_bin($1::interval, timestamp, '2000-01-01'::timestamptz) AS bucket,
+       AVG(cpu_usage)::float8 AS avg_cpu,
+       AVG(memory_usage_percent)::float8 AS avg_memory,
+       AVG(storage_usage_percent)::float8 AS avg_storage
+FROM node_metrics
+WHERE node_id = $2 AND timestamp BETWEEN $3 AND $4
+GROUP BY bucket
+ORDER BY bucket ASC
+`
+
+type AggregateNodeMetricsParams struct {
+	Column1     int64     `json:"column_1"`
+	NodeID      string    `json:"node_id"`
+	Timestamp   time.Time `json:"timestamp"`
+	Timestamp_2 time.Time `json:"timestamp_2"`
+}
+
+type AggregateNodeMetricsRow struct {
+	Bucket     interface{} `json:"bucket"`
+	AvgCpu     float64     `json:"avg_cpu"`
+	AvgMemory  float64     `json:"avg_memory"`
+	AvgStorage float64     `json:"avg_storage"`
+}
+
+// Portable bucket bucketing (no TimescaleDB): floor epoch seconds into
+// bucket-sized buckets, then back to timestamptz.
+func (q *Queries) AggregateNodeMetrics(ctx context.Context, arg AggregateNodeMetricsParams) ([]AggregateNodeMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, aggregateNodeMetrics,
+		arg.Column1,
+		arg.NodeID,
+		arg.Timestamp,
+		arg.Timestamp_2,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []AggregateNodeMetricsRow{}
+	for rows.Next() {
+		var i AggregateNodeMetricsRow
+		if err := rows.Scan(
+			&i.Bucket,
+			&i.AvgCpu,
+			&i.AvgMemory,
+			&i.AvgStorage,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listInstanceMetrics = `-- name: ListInstanceMetrics :many
+SELECT instance_id, node_id, status, cpu, memory,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+FROM instance_metrics
+WHERE service_id = $1 AND timestamp = $2
+`
+
+type ListInstanceMetricsParams struct {
+	ServiceID string    `json:"service_id"`
+	Timestamp time.Time `json:"timestamp"`
+}
+
+type ListInstanceMetricsRow struct {
+	InstanceID            string         `json:"instance_id"`
+	NodeID                sql.NullString `json:"node_id"`
+	Status                sql.NullString `json:"status"`
+	Cpu                   sql.NullString `json:"cpu"`
+	Memory                sql.NullInt64  `json:"memory"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	StartTime             sql.NullTime   `json:"start_time"`
+	LastSeen              sql.NullTime   `json:"last_seen"`
+	HealthStatus          sql.NullString `json:"health_status"`
+	HealthLastCheck       sql.NullTime   `json:"health_last_check"`
+	HealthCheckCount      sql.NullInt32  `json:"health_check_count"`
+	HealthFailureCount    sql.NullInt32  `json:"health_failure_count"`
+}
+
+func (q *Queries) ListInstanceMetrics(ctx context.Context, arg ListInstanceMetricsParams) ([]ListInstanceMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listInstanceMetrics, arg.ServiceID, arg.Timestamp)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListInstanceMetricsRow{}
+	for rows.Next() {
+		var i ListInstanceMetricsRow
+		if err := rows.Scan(
+			&i.InstanceID,
+			&i.NodeID,
+			&i.Status,
+			&i.Cpu,
+			&i.Memory,
+			&i.NetworkBytesIn,
+			&i.NetworkBytesOut,
+			&i.NetworkPacketsIn,
+			&i.NetworkPacketsOut,
+			&i.NetworkConnectionsIn,
+			&i.NetworkConnectionsOut,
+			&i.NetworkErrorsIn,
+			&i.NetworkErrorsOut,
+			&i.StartTime,
+			&i.LastSeen,
+			&i.HealthStatus,
+			&i.HealthLastCheck,
+			&i.HealthCheckCount,
+			&i.HealthFailureCount,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listNodeMetrics = `-- name: ListNodeMetrics :many
+SELECT node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+       memory_total, memory_used, memory_available, memory_usage_percent,
+       storage_total, storage_used, storage_available, storage_usage_percent,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       coalesce(extract(epoch from uptime), 0)::bigint AS uptime_seconds,
+       processes, os, kernel, architecture
+FROM node_metrics
+WHERE node_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC
+`
+
+type ListNodeMetricsParams struct {
+	NodeID      string    `json:"node_id"`
+	Timestamp   time.Time `json:"timestamp"`
+	Timestamp_2 time.Time `json:"timestamp_2"`
+}
+
+type ListNodeMetricsRow struct {
+	NodeID                string         `json:"node_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	CpuUsage              sql.NullString `json:"cpu_usage"`
+	CpuCores              sql.NullString `json:"cpu_cores"`
+	LoadAvg1              sql.NullString `json:"load_avg_1"`
+	LoadAvg5              sql.NullString `json:"load_avg_5"`
+	LoadAvg15             sql.NullString `json:"load_avg_15"`
+	MemoryTotal           sql.NullInt64  `json:"memory_total"`
+	MemoryUsed            sql.NullInt64  `json:"memory_used"`
+	MemoryAvailable       sql.NullInt64  `json:"memory_available"`
+	MemoryUsagePercent    sql.NullString `json:"memory_usage_percent"`
+	StorageTotal          sql.NullInt64  `json:"storage_total"`
+	StorageUsed           sql.NullInt64  `json:"storage_used"`
+	StorageAvailable      sql.NullInt64  `json:"storage_available"`
+	StorageUsagePercent   sql.NullString `json:"storage_usage_percent"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	UptimeSeconds         int64          `json:"uptime_seconds"`
+	Processes             sql.NullInt32  `json:"processes"`
+	Os                    sql.NullString `json:"os"`
+	Kernel                sql.NullString `json:"kernel"`
+	Architecture          sql.NullString `json:"architecture"`
+}
+
+func (q *Queries) ListNodeMetrics(ctx context.Context, arg ListNodeMetricsParams) ([]ListNodeMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listNodeMetrics, arg.NodeID, arg.Timestamp, arg.Timestamp_2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListNodeMetricsRow{}
+	for rows.Next() {
+		var i ListNodeMetricsRow
+		if err := rows.Scan(
+			&i.NodeID,
+			&i.Timestamp,
+			&i.CpuUsage,
+			&i.CpuCores,
+			&i.LoadAvg1,
+			&i.LoadAvg5,
+			&i.LoadAvg15,
+			&i.MemoryTotal,
+			&i.MemoryUsed,
+			&i.MemoryAvailable,
+			&i.MemoryUsagePercent,
+			&i.StorageTotal,
+			&i.StorageUsed,
+			&i.StorageAvailable,
+			&i.StorageUsagePercent,
+			&i.NetworkBytesIn,
+			&i.NetworkBytesOut,
+			&i.NetworkPacketsIn,
+			&i.NetworkPacketsOut,
+			&i.NetworkConnectionsIn,
+			&i.NetworkConnectionsOut,
+			&i.NetworkErrorsIn,
+			&i.NetworkErrorsOut,
+			&i.UptimeSeconds,
+			&i.Processes,
+			&i.Os,
+			&i.Kernel,
+			&i.Architecture,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listServiceMetrics = `-- name: ListServiceMetrics :many
+SELECT service_id, service_name, project_id, timestamp,
+       requests_total, requests_success, requests_errors, requests_avg_latency,
+       requests_p95_latency, requests_p99_latency, requests_throughput,
+       errors_total, errors_rate, performance_response_time, performance_throughput,
+       performance_concurrency, performance_saturation, performance_utilization,
+       resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+       resource_network_usage, resource_score
+FROM service_metrics
+WHERE service_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC
+`
+
+type ListServiceMetricsParams struct {
+	ServiceID   string    `json:"service_id"`
+	Timestamp   time.Time `json:"timestamp"`
+	Timestamp_2 time.Time `json:"timestamp_2"`
+}
+
+type ListServiceMetricsRow struct {
+	ServiceID               string         `json:"service_id"`
+	ServiceName             string         `json:"service_name"`
+	ProjectID               string         `json:"project_id"`
+	Timestamp               time.Time      `json:"timestamp"`
+	RequestsTotal           sql.NullInt64  `json:"requests_total"`
+	RequestsSuccess         sql.NullInt64  `json:"requests_success"`
+	RequestsErrors          sql.NullInt64  `json:"requests_errors"`
+	RequestsAvgLatency      sql.NullString `json:"requests_avg_latency"`
+	RequestsP95Latency      sql.NullString `json:"requests_p95_latency"`
+	RequestsP99Latency      sql.NullString `json:"requests_p99_latency"`
+	RequestsThroughput      sql.NullString `json:"requests_throughput"`
+	ErrorsTotal             sql.NullInt64  `json:"errors_total"`
+	ErrorsRate              sql.NullString `json:"errors_rate"`
+	PerformanceResponseTime sql.NullString `json:"performance_response_time"`
+	PerformanceThroughput   sql.NullString `json:"performance_throughput"`
+	PerformanceConcurrency  sql.NullInt64  `json:"performance_concurrency"`
+	PerformanceSaturation   sql.NullString `json:"performance_saturation"`
+	PerformanceUtilization  sql.NullString `json:"performance_utilization"`
+	ResourceCpuUsage        sql.NullString `json:"resource_cpu_usage"`
+	ResourceMemoryUsage     sql.NullInt64  `json:"resource_memory_usage"`
+	ResourceStorageUsage    sql.NullInt64  `json:"resource_storage_usage"`
+	ResourceNetworkUsage    sql.NullInt64  `json:"resource_network_usage"`
+	ResourceScore           sql.NullString `json:"resource_score"`
+}
+
+func (q *Queries) ListServiceMetrics(ctx context.Context, arg ListServiceMetricsParams) ([]ListServiceMetricsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listServiceMetrics, arg.ServiceID, arg.Timestamp, arg.Timestamp_2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListServiceMetricsRow{}
+	for rows.Next() {
+		var i ListServiceMetricsRow
+		if err := rows.Scan(
+			&i.ServiceID,
+			&i.ServiceName,
+			&i.ProjectID,
+			&i.Timestamp,
+			&i.RequestsTotal,
+			&i.RequestsSuccess,
+			&i.RequestsErrors,
+			&i.RequestsAvgLatency,
+			&i.RequestsP95Latency,
+			&i.RequestsP99Latency,
+			&i.RequestsThroughput,
+			&i.ErrorsTotal,
+			&i.ErrorsRate,
+			&i.PerformanceResponseTime,
+			&i.PerformanceThroughput,
+			&i.PerformanceConcurrency,
+			&i.PerformanceSaturation,
+			&i.PerformanceUtilization,
+			&i.ResourceCpuUsage,
+			&i.ResourceMemoryUsage,
+			&i.ResourceStorageUsage,
+			&i.ResourceNetworkUsage,
+			&i.ResourceScore,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const upsertInstanceMetrics = `-- name: UpsertInstanceMetrics :exec
+INSERT INTO instance_metrics (
+    service_id, timestamp, instance_id, node_id, status, cpu, memory,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21
+)
+ON CONFLICT (service_id, timestamp, instance_id) DO UPDATE SET
+    node_id = EXCLUDED.node_id,
+    status = EXCLUDED.status,
+    cpu = EXCLUDED.cpu,
+    memory = EXCLUDED.memory,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    start_time = EXCLUDED.start_time,
+    last_seen = EXCLUDED.last_seen,
+    health_status = EXCLUDED.health_status,
+    health_last_check = EXCLUDED.health_last_check,
+    health_check_count = EXCLUDED.health_check_count,
+    health_failure_count = EXCLUDED.health_failure_count
+`
+
+type UpsertInstanceMetricsParams struct {
+	ServiceID             string         `json:"service_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	InstanceID            string         `json:"instance_id"`
+	NodeID                sql.NullString `json:"node_id"`
+	Status                sql.NullString `json:"status"`
+	Cpu                   sql.NullString `json:"cpu"`
+	Memory                sql.NullInt64  `json:"memory"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	StartTime             sql.NullTime   `json:"start_time"`
+	LastSeen              sql.NullTime   `json:"last_seen"`
+	HealthStatus          sql.NullString `json:"health_status"`
+	HealthLastCheck       sql.NullTime   `json:"health_last_check"`
+	HealthCheckCount      sql.NullInt32  `json:"health_check_count"`
+	HealthFailureCount    sql.NullInt32  `json:"health_failure_count"`
+}
+
+func (q *Queries) UpsertInstanceMetrics(ctx context.Context, arg UpsertInstanceMetricsParams) error {
+	_, err := q.db.ExecContext(ctx, upsertInstanceMetrics,
+		arg.ServiceID,
+		arg.Timestamp,
+		arg.InstanceID,
+		arg.NodeID,
+		arg.Status,
+		arg.Cpu,
+		arg.Memory,
+		arg.NetworkBytesIn,
+		arg.NetworkBytesOut,
+		arg.NetworkPacketsIn,
+		arg.NetworkPacketsOut,
+		arg.NetworkConnectionsIn,
+		arg.NetworkConnectionsOut,
+		arg.NetworkErrorsIn,
+		arg.NetworkErrorsOut,
+		arg.StartTime,
+		arg.LastSeen,
+		arg.HealthStatus,
+		arg.HealthLastCheck,
+		arg.HealthCheckCount,
+		arg.HealthFailureCount,
+	)
+	return err
+}
+
+const upsertNodeMetrics = `-- name: UpsertNodeMetrics :exec
+INSERT INTO node_metrics (
+    node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+    memory_total, memory_used, memory_available, memory_usage_percent,
+    storage_total, storage_used, storage_available, storage_usage_percent,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    uptime, processes, os, kernel, architecture
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28
+)
+ON CONFLICT (node_id, timestamp) DO UPDATE SET
+    cpu_usage = EXCLUDED.cpu_usage,
+    cpu_cores = EXCLUDED.cpu_cores,
+    load_avg_1 = EXCLUDED.load_avg_1,
+    load_avg_5 = EXCLUDED.load_avg_5,
+    load_avg_15 = EXCLUDED.load_avg_15,
+    memory_total = EXCLUDED.memory_total,
+    memory_used = EXCLUDED.memory_used,
+    memory_available = EXCLUDED.memory_available,
+    memory_usage_percent = EXCLUDED.memory_usage_percent,
+    storage_total = EXCLUDED.storage_total,
+    storage_used = EXCLUDED.storage_used,
+    storage_available = EXCLUDED.storage_available,
+    storage_usage_percent = EXCLUDED.storage_usage_percent,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    uptime = EXCLUDED.uptime,
+    processes = EXCLUDED.processes,
+    os = EXCLUDED.os,
+    kernel = EXCLUDED.kernel,
+    architecture = EXCLUDED.architecture
+`
+
+type UpsertNodeMetricsParams struct {
+	NodeID                string         `json:"node_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	CpuUsage              sql.NullString `json:"cpu_usage"`
+	CpuCores              sql.NullString `json:"cpu_cores"`
+	LoadAvg1              sql.NullString `json:"load_avg_1"`
+	LoadAvg5              sql.NullString `json:"load_avg_5"`
+	LoadAvg15             sql.NullString `json:"load_avg_15"`
+	MemoryTotal           sql.NullInt64  `json:"memory_total"`
+	MemoryUsed            sql.NullInt64  `json:"memory_used"`
+	MemoryAvailable       sql.NullInt64  `json:"memory_available"`
+	MemoryUsagePercent    sql.NullString `json:"memory_usage_percent"`
+	StorageTotal          sql.NullInt64  `json:"storage_total"`
+	StorageUsed           sql.NullInt64  `json:"storage_used"`
+	StorageAvailable      sql.NullInt64  `json:"storage_available"`
+	StorageUsagePercent   sql.NullString `json:"storage_usage_percent"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	Uptime                sql.NullInt64  `json:"uptime"`
+	Processes             sql.NullInt32  `json:"processes"`
+	Os                    sql.NullString `json:"os"`
+	Kernel                sql.NullString `json:"kernel"`
+	Architecture          sql.NullString `json:"architecture"`
+}
+
+func (q *Queries) UpsertNodeMetrics(ctx context.Context, arg UpsertNodeMetricsParams) error {
+	_, err := q.db.ExecContext(ctx, upsertNodeMetrics,
+		arg.NodeID,
+		arg.Timestamp,
+		arg.CpuUsage,
+		arg.CpuCores,
+		arg.LoadAvg1,
+		arg.LoadAvg5,
+		arg.LoadAvg15,
+		arg.MemoryTotal,
+		arg.MemoryUsed,
+		arg.MemoryAvailable,
+		arg.MemoryUsagePercent,
+		arg.StorageTotal,
+		arg.StorageUsed,
+		arg.StorageAvailable,
+		arg.StorageUsagePercent,
+		arg.NetworkBytesIn,
+		arg.NetworkBytesOut,
+		arg.NetworkPacketsIn,
+		arg.NetworkPacketsOut,
+		arg.NetworkConnectionsIn,
+		arg.NetworkConnectionsOut,
+		arg.NetworkErrorsIn,
+		arg.NetworkErrorsOut,
+		arg.Uptime,
+		arg.Processes,
+		arg.Os,
+		arg.Kernel,
+		arg.Architecture,
+	)
+	return err
+}
+
+const upsertServiceMetrics = `-- name: UpsertServiceMetrics :exec
+INSERT INTO service_metrics (
+    service_id, service_name, project_id, timestamp,
+    requests_total, requests_success, requests_errors, requests_avg_latency,
+    requests_p95_latency, requests_p99_latency, requests_throughput,
+    errors_total, errors_rate, performance_response_time, performance_throughput,
+    performance_concurrency, performance_saturation, performance_utilization,
+    resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+    resource_network_usage, resource_score
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23
+)
+ON CONFLICT (service_id, timestamp) DO UPDATE SET
+    requests_total = EXCLUDED.requests_total,
+    requests_success = EXCLUDED.requests_success,
+    requests_errors = EXCLUDED.requests_errors,
+    requests_avg_latency = EXCLUDED.requests_avg_latency,
+    requests_p95_latency = EXCLUDED.requests_p95_latency,
+    requests_p99_latency = EXCLUDED.requests_p99_latency,
+    requests_throughput = EXCLUDED.requests_throughput,
+    errors_total = EXCLUDED.errors_total,
+    errors_rate = EXCLUDED.errors_rate,
+    performance_response_time = EXCLUDED.performance_response_time,
+    performance_throughput = EXCLUDED.performance_throughput,
+    performance_concurrency = EXCLUDED.performance_concurrency,
+    performance_saturation = EXCLUDED.performance_saturation,
+    performance_utilization = EXCLUDED.performance_utilization,
+    resource_cpu_usage = EXCLUDED.resource_cpu_usage,
+    resource_memory_usage = EXCLUDED.resource_memory_usage,
+    resource_storage_usage = EXCLUDED.resource_storage_usage,
+    resource_network_usage = EXCLUDED.resource_network_usage,
+    resource_score = EXCLUDED.resource_score
+`
+
+type UpsertServiceMetricsParams struct {
+	ServiceID               string         `json:"service_id"`
+	ServiceName             string         `json:"service_name"`
+	ProjectID               string         `json:"project_id"`
+	Timestamp               time.Time      `json:"timestamp"`
+	RequestsTotal           sql.NullInt64  `json:"requests_total"`
+	RequestsSuccess         sql.NullInt64  `json:"requests_success"`
+	RequestsErrors          sql.NullInt64  `json:"requests_errors"`
+	RequestsAvgLatency      sql.NullString `json:"requests_avg_latency"`
+	RequestsP95Latency      sql.NullString `json:"requests_p95_latency"`
+	RequestsP99Latency      sql.NullString `json:"requests_p99_latency"`
+	RequestsThroughput      sql.NullString `json:"requests_throughput"`
+	ErrorsTotal             sql.NullInt64  `json:"errors_total"`
+	ErrorsRate              sql.NullString `json:"errors_rate"`
+	PerformanceResponseTime sql.NullString `json:"performance_response_time"`
+	PerformanceThroughput   sql.NullString `json:"performance_throughput"`
+	PerformanceConcurrency  sql.NullInt64  `json:"performance_concurrency"`
+	PerformanceSaturation   sql.NullString `json:"performance_saturation"`
+	PerformanceUtilization  sql.NullString `json:"performance_utilization"`
+	ResourceCpuUsage        sql.NullString `json:"resource_cpu_usage"`
+	ResourceMemoryUsage     sql.NullInt64  `json:"resource_memory_usage"`
+	ResourceStorageUsage    sql.NullInt64  `json:"resource_storage_usage"`
+	ResourceNetworkUsage    sql.NullInt64  `json:"resource_network_usage"`
+	ResourceScore           sql.NullString `json:"resource_score"`
+}
+
+func (q *Queries) UpsertServiceMetrics(ctx context.Context, arg UpsertServiceMetricsParams) error {
+	_, err := q.db.ExecContext(ctx, upsertServiceMetrics,
+		arg.ServiceID,
+		arg.ServiceName,
+		arg.ProjectID,
+		arg.Timestamp,
+		arg.RequestsTotal,
+		arg.RequestsSuccess,
+		arg.RequestsErrors,
+		arg.RequestsAvgLatency,
+		arg.RequestsP95Latency,
+		arg.RequestsP99Latency,
+		arg.RequestsThroughput,
+		arg.ErrorsTotal,
+		arg.ErrorsRate,
+		arg.PerformanceResponseTime,
+		arg.PerformanceThroughput,
+		arg.PerformanceConcurrency,
+		arg.PerformanceSaturation,
+		arg.PerformanceUtilization,
+		arg.ResourceCpuUsage,
+		arg.ResourceMemoryUsage,
+		arg.ResourceStorageUsage,
+		arg.ResourceNetworkUsage,
+		arg.ResourceScore,
+	)
+	return err
+}

app/backend/internal/database/sqlcdb/models.go

@@ -161,6 +161,31 @@ type EnvironmentVariable struct {
 	UpdatedAt sql.NullTime `json:"updated_at"`
 }
 
+type InstanceMetric struct {
+	ServiceID             string         `json:"service_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	InstanceID            string         `json:"instance_id"`
+	NodeID                sql.NullString `json:"node_id"`
+	Status                sql.NullString `json:"status"`
+	Cpu                   sql.NullString `json:"cpu"`
+	Memory                sql.NullInt64  `json:"memory"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	StartTime             sql.NullTime   `json:"start_time"`
+	LastSeen              sql.NullTime   `json:"last_seen"`
+	HealthStatus          sql.NullString `json:"health_status"`
+	HealthLastCheck       sql.NullTime   `json:"health_last_check"`
+	HealthCheckCount      sql.NullInt32  `json:"health_check_count"`
+	HealthFailureCount    sql.NullInt32  `json:"health_failure_count"`
+	CreatedAt             sql.NullTime   `json:"created_at"`
+}
+
 type NodeAgent struct {
 	ID            string                `json:"id"`
 	Name          string                `json:"name"`
@@ -181,6 +206,38 @@ type NodeAgent struct {
 	DefaultDomain string                `json:"default_domain"`
 }
 
+type NodeMetric struct {
+	NodeID                string         `json:"node_id"`
+	Timestamp             time.Time      `json:"timestamp"`
+	CpuUsage              sql.NullString `json:"cpu_usage"`
+	CpuCores              sql.NullString `json:"cpu_cores"`
+	LoadAvg1              sql.NullString `json:"load_avg_1"`
+	LoadAvg5              sql.NullString `json:"load_avg_5"`
+	LoadAvg15             sql.NullString `json:"load_avg_15"`
+	MemoryTotal           sql.NullInt64  `json:"memory_total"`
+	MemoryUsed            sql.NullInt64  `json:"memory_used"`
+	MemoryAvailable       sql.NullInt64  `json:"memory_available"`
+	MemoryUsagePercent    sql.NullString `json:"memory_usage_percent"`
+	StorageTotal          sql.NullInt64  `json:"storage_total"`
+	StorageUsed           sql.NullInt64  `json:"storage_used"`
+	StorageAvailable      sql.NullInt64  `json:"storage_available"`
+	StorageUsagePercent   sql.NullString `json:"storage_usage_percent"`
+	NetworkBytesIn        sql.NullInt64  `json:"network_bytes_in"`
+	NetworkBytesOut       sql.NullInt64  `json:"network_bytes_out"`
+	NetworkPacketsIn      sql.NullInt64  `json:"network_packets_in"`
+	NetworkPacketsOut     sql.NullInt64  `json:"network_packets_out"`
+	NetworkConnectionsIn  sql.NullInt32  `json:"network_connections_in"`
+	NetworkConnectionsOut sql.NullInt32  `json:"network_connections_out"`
+	NetworkErrorsIn       sql.NullInt64  `json:"network_errors_in"`
+	NetworkErrorsOut      sql.NullInt64  `json:"network_errors_out"`
+	Uptime                sql.NullInt64  `json:"uptime"`
+	Processes             sql.NullInt32  `json:"processes"`
+	Os                    sql.NullString `json:"os"`
+	Kernel                sql.NullString `json:"kernel"`
+	Architecture          sql.NullString `json:"architecture"`
+	CreatedAt             sql.NullTime   `json:"created_at"`
+}
+
 type Notification struct {
 	ID           uuid.UUID      `json:"id"`
 	UserID       uuid.UUID      `json:"user_id"`
@@ -305,6 +362,33 @@ type ServiceDomain struct {
 	CreatedAt     time.Time    `json:"created_at"`
 }
 
+type ServiceMetric struct {
+	ServiceID               string         `json:"service_id"`
+	ServiceName             string         `json:"service_name"`
+	ProjectID               string         `json:"project_id"`
+	Timestamp               time.Time      `json:"timestamp"`
+	RequestsTotal           sql.NullInt64  `json:"requests_total"`
+	RequestsSuccess         sql.NullInt64  `json:"requests_success"`
+	RequestsErrors          sql.NullInt64  `json:"requests_errors"`
+	RequestsAvgLatency      sql.NullString `json:"requests_avg_latency"`
+	RequestsP95Latency      sql.NullString `json:"requests_p95_latency"`
+	RequestsP99Latency      sql.NullString `json:"requests_p99_latency"`
+	RequestsThroughput      sql.NullString `json:"requests_throughput"`
+	ErrorsTotal             sql.NullInt64  `json:"errors_total"`
+	ErrorsRate              sql.NullString `json:"errors_rate"`
+	PerformanceResponseTime sql.NullString `json:"performance_response_time"`
+	PerformanceThroughput   sql.NullString `json:"performance_throughput"`
+	PerformanceConcurrency  sql.NullInt64  `json:"performance_concurrency"`
+	PerformanceSaturation   sql.NullString `json:"performance_saturation"`
+	PerformanceUtilization  sql.NullString `json:"performance_utilization"`
+	ResourceCpuUsage        sql.NullString `json:"resource_cpu_usage"`
+	ResourceMemoryUsage     sql.NullInt64  `json:"resource_memory_usage"`
+	ResourceStorageUsage    sql.NullInt64  `json:"resource_storage_usage"`
+	ResourceNetworkUsage    sql.NullInt64  `json:"resource_network_usage"`
+	ResourceScore           sql.NullString `json:"resource_score"`
+	CreatedAt               sql.NullTime   `json:"created_at"`
+}
+
 type ServiceTemplate struct {
 	ID          string                `json:"id"`
 	Name        string                `json:"name"`

app/backend/internal/database/sqlcdb/querier.go

@@ -13,12 +13,17 @@ import (
 )
 
 type Querier interface {
+	// Portable bucket bucketing (no TimescaleDB): floor epoch seconds into
+	// bucket-sized buckets, then back to timestamptz.
+	AggregateNodeMetrics(ctx context.Context, arg AggregateNodeMetricsParams) ([]AggregateNodeMetricsRow, error)
+	ClearServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) error
 	ClearServiceNodePins(ctx context.Context, nodeID sql.NullString) (int64, error)
 	CompleteCommand(ctx context.Context, arg CompleteCommandParams) (AgentCommand, error)
 	CountDatabaseServicesByUserAndName(ctx context.Context, arg CountDatabaseServicesByUserAndNameParams) (int64, error)
 	CountDatabasesUsingBackupTarget(ctx context.Context, targetID sql.NullString) (int64, error)
 	CountEnvironmentServices(ctx context.Context, environmentID uuid.UUID) (int64, error)
 	CountProjectsByUser(ctx context.Context, arg CountProjectsByUserParams) (int64, error)
+	CountServiceDomains(ctx context.Context, serviceID uuid.UUID) (int64, error)
 	CountServicesByProjectAndName(ctx context.Context, arg CountServicesByProjectAndNameParams) (int64, error)
 	CountUnreadNotificationsByUser(ctx context.Context, userID uuid.UUID) (int64, error)
 	CreateAgent(ctx context.Context, arg CreateAgentParams) (NodeAgent, error)
@@ -33,6 +38,7 @@ type Querier interface {
 	CreateNotification(ctx context.Context, arg CreateNotificationParams) error
 	CreateOutboundWebhook(ctx context.Context, arg CreateOutboundWebhookParams) error
 	CreateProject(ctx context.Context, arg CreateProjectParams) (Project, error)
+	CreateServiceDomain(ctx context.Context, arg CreateServiceDomainParams) (CreateServiceDomainRow, error)
 	CreateServiceFromTemplate(ctx context.Context, arg CreateServiceFromTemplateParams) error
 	CreateUserInvite(ctx context.Context, arg CreateUserInviteParams) (UserInvite, error)
 	CreateUserTemplate(ctx context.Context, arg CreateUserTemplateParams) error
@@ -49,6 +55,7 @@ type Querier interface {
 	DeleteProjectByID(ctx context.Context, projectID uuid.UUID) (int64, error)
 	DeleteProjectEnvironment(ctx context.Context, arg DeleteProjectEnvironmentParams) error
 	DeleteServiceContainersOnAgent(ctx context.Context, arg DeleteServiceContainersOnAgentParams) error
+	DeleteServiceDomain(ctx context.Context, arg DeleteServiceDomainParams) (int64, error)
 	DeleteUserInvite(ctx context.Context, id uuid.UUID) error
 	DeleteUserTemplate(ctx context.Context, arg DeleteUserTemplateParams) (int64, error)
 	GetActiveAgentAuthTokenByHash(ctx context.Context, tokenHash string) (AgentAuthToken, error)
@@ -72,6 +79,10 @@ type Querier interface {
 	GetProjectOwnerByID(ctx context.Context, projectID uuid.UUID) (uuid.UUID, error)
 	GetProjectOwnerID(ctx context.Context, id uuid.UUID) (uuid.UUID, error)
 	GetProjectRoleForUser(ctx context.Context, arg GetProjectRoleForUserParams) (string, error)
+	GetServiceAccess(ctx context.Context, id uuid.UUID) (GetServiceAccessRow, error)
+	GetServiceDomainDefault(ctx context.Context, serviceID uuid.UUID) (string, error)
+	GetServiceDomainFirst(ctx context.Context, serviceID uuid.UUID) (string, error)
+	GetServicePlacementBrief(ctx context.Context, id uuid.UUID) (GetServicePlacementBriefRow, error)
 	GetServiceTemplateByID(ctx context.Context, id string) (ServiceTemplate, error)
 	GetUserInviteByTokenHash(ctx context.Context, tokenHash string) (UserInvite, error)
 	GetUserTokenByHash(ctx context.Context, tokenHash string) (UserToken, error)
@@ -93,6 +104,8 @@ type Querier interface {
 	ListDatabaseServicesByUser(ctx context.Context, userID string) ([]DatabaseService, error)
 	ListDueDatabaseBackups(ctx context.Context) ([]ListDueDatabaseBackupsRow, error)
 	ListEnabledOutboundWebhooks(ctx context.Context) ([]OutboundWebhook, error)
+	ListInstanceMetrics(ctx context.Context, arg ListInstanceMetricsParams) ([]ListInstanceMetricsRow, error)
+	ListNodeMetrics(ctx context.Context, arg ListNodeMetricsParams) ([]ListNodeMetricsRow, error)
 	ListNotificationChannelsByUser(ctx context.Context, userID uuid.UUID) ([]NotificationChannel, error)
 	ListNotificationsByUser(ctx context.Context, arg ListNotificationsByUserParams) ([]Notification, error)
 	ListOutboundWebhooksByUser(ctx context.Context, userID uuid.UUID) ([]OutboundWebhook, error)
@@ -112,6 +125,8 @@ type Querier interface {
 	// Distinct agents holding inventory rows for a service.
 	ListServiceAgents(ctx context.Context, serviceID string) ([]string, error)
 	ListServiceContainers(ctx context.Context, serviceID string) ([]ListServiceContainersRow, error)
+	ListServiceDomains(ctx context.Context, serviceID uuid.UUID) ([]ServiceDomain, error)
+	ListServiceMetrics(ctx context.Context, arg ListServiceMetricsParams) ([]ListServiceMetricsRow, error)
 	ListServiceTemplatesByCategoryForUser(ctx context.Context, arg ListServiceTemplatesByCategoryForUserParams) ([]ServiceTemplate, error)
 	ListServiceTemplatesForUser(ctx context.Context, ownerID uuid.NullUUID) ([]ServiceTemplate, error)
 	ListUserInvites(ctx context.Context) ([]UserInvite, error)
@@ -129,6 +144,7 @@ type Querier interface {
 	RevokeAgentAuthToken(ctx context.Context, id uuid.UUID) (AgentAuthToken, error)
 	RevokeUserToken(ctx context.Context, arg RevokeUserTokenParams) (int64, error)
 	ScrubCommandPayload(ctx context.Context, arg ScrubCommandPayloadParams) error
+	ServiceWriteAccess(ctx context.Context, arg ServiceWriteAccessParams) (bool, error)
 	SetAgentDefaultDomain(ctx context.Context, arg SetAgentDefaultDomainParams) error
 	SetAgentSchedulable(ctx context.Context, arg SetAgentSchedulableParams) error
 	SetAgentTags(ctx context.Context, arg SetAgentTagsParams) error
@@ -142,7 +158,10 @@ type Querier interface {
 	SetDatabaseServiceStatusByID(ctx context.Context, arg SetDatabaseServiceStatusByIDParams) error
 	SetDatabaseServiceStatusByIDAndUser(ctx context.Context, arg SetDatabaseServiceStatusByIDAndUserParams) error
 	SetProjectApproved(ctx context.Context, arg SetProjectApprovedParams) (int64, error)
+	SetServiceDomainDefault(ctx context.Context, arg SetServiceDomainDefaultParams) (int64, error)
+	SetServiceLegacyDomain(ctx context.Context, arg SetServiceLegacyDomainParams) error
 	TouchAgentAuthToken(ctx context.Context, tokenHash string) error
+	TouchServiceDomainChecked(ctx context.Context, id uuid.UUID) error
 	TouchUserToken(ctx context.Context, id uuid.UUID) error
 	UpdateAgent(ctx context.Context, arg UpdateAgentParams) (NodeAgent, error)
 	UpdateAgentHeartbeat(ctx context.Context, arg UpdateAgentHeartbeatParams) error
@@ -164,7 +183,10 @@ type Querier interface {
 	UpdateUserTemplate(ctx context.Context, arg UpdateUserTemplateParams) (int64, error)
 	UpdateWebhookDeliveryResult(ctx context.Context, arg UpdateWebhookDeliveryResultParams) error
 	UpsertEnvironmentVariable(ctx context.Context, arg UpsertEnvironmentVariableParams) error
+	UpsertInstanceMetrics(ctx context.Context, arg UpsertInstanceMetricsParams) error
+	UpsertNodeMetrics(ctx context.Context, arg UpsertNodeMetricsParams) error
 	UpsertServiceContainer(ctx context.Context, arg UpsertServiceContainerParams) error
+	UpsertServiceMetrics(ctx context.Context, arg UpsertServiceMetricsParams) error
 	UpsertServiceTemplate(ctx context.Context, arg UpsertServiceTemplateParams) error
 }
 

app/backend/internal/metrics/storage.go

@@ -4,293 +4,286 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"strconv"
 	"sync"
 	"time"
 
+	"containr/internal/database/sqlcdb"
+
 	_ "github.com/lib/pq"
 )
 
 // PostgreSQLMetricsStorage implements MetricsStorage using PostgreSQL
+// through sqlc-generated queries (sqlc/queries/metrics.sql).
+//
+// Per-container node metrics are deliberately not persisted: the
+// container_metrics table belongs to the container_instances model and
+// has no place for the node/container samples collected here. Node and
+// service/instance rows map cleanly, so those are stored.
 type PostgreSQLMetricsStorage struct {
-	db *sql.DB
+	q *sqlcdb.Queries
 }
 
 // NewPostgreSQLMetricsStorage creates a new PostgreSQL metrics storage
 func NewPostgreSQLMetricsStorage(db *sql.DB) *PostgreSQLMetricsStorage {
-	return &PostgreSQLMetricsStorage{db: db}
+	return &PostgreSQLMetricsStorage{q: sqlcdb.New(db)}
 }
 
+func numStr(v float64) sql.NullString {
+	return sql.NullString{String: strconv.FormatFloat(v, 'f', -1, 64), Valid: true}
+}
+
+func int64N(v int64) sql.NullInt64 {
+	return sql.NullInt64{Int64: v, Valid: true}
+}
+
+func int32N(v int64) sql.NullInt32 {
+	return sql.NullInt32{Int32: int32(v), Valid: true}
+}
+
+func strN(v string) sql.NullString {
+	return sql.NullString{String: v, Valid: v != ""}
+}
+
+func timeN(t time.Time) sql.NullTime {
+	return sql.NullTime{Time: t, Valid: !t.IsZero()}
+}
+
+func f64v(n sql.NullString) float64 {
+	f, _ := strconv.ParseFloat(n.String, 64)
+	return f
+}
+
+func i64v(n sql.NullInt64) int64 { return n.Int64 }
+
+func i32v(n sql.NullInt32) int64 { return int64(n.Int32) }
+
 // StoreNodeMetrics stores node metrics in the database
 func (s *PostgreSQLMetricsStorage) StoreNodeMetrics(ctx context.Context, metrics *NodeMetrics) error {
-	query := `
-		INSERT INTO node_metrics (
-			node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
-			memory_total, memory_used, memory_available, memory_usage_percent,
-			storage_total, storage_used, storage_available, storage_usage_percent,
-			network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			uptime, processes, os, kernel, architecture
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28)
-		ON CONFLICT (node_id, timestamp) DO UPDATE SET
-			cpu_usage = EXCLUDED.cpu_usage,
-			cpu_cores = EXCLUDED.cpu_cores,
-			load_avg_1 = EXCLUDED.load_avg_1,
-			load_avg_5 = EXCLUDED.load_avg_5,
-			load_avg_15 = EXCLUDED.load_avg_15,
-			memory_total = EXCLUDED.memory_total,
-			memory_used = EXCLUDED.memory_used,
-			memory_available = EXCLUDED.memory_available,
-			memory_usage_percent = EXCLUDED.memory_usage_percent,
-			storage_total = EXCLUDED.storage_total,
-			storage_used = EXCLUDED.storage_used,
-			storage_available = EXCLUDED.storage_available,
-			storage_usage_percent = EXCLUDED.storage_usage_percent,
-			network_bytes_in = EXCLUDED.network_bytes_in,
-			network_bytes_out = EXCLUDED.network_bytes_out,
-			network_packets_in = EXCLUDED.network_packets_in,
-			network_packets_out = EXCLUDED.network_packets_out,
-			network_connections_in = EXCLUDED.network_connections_in,
-			network_connections_out = EXCLUDED.network_connections_out,
-			network_errors_in = EXCLUDED.network_errors_in,
-			network_errors_out = EXCLUDED.network_errors_out,
-			uptime = EXCLUDED.uptime,
-			processes = EXCLUDED.processes,
-			os = EXCLUDED.os,
-			kernel = EXCLUDED.kernel,
-			architecture = EXCLUDED.architecture
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		metrics.NodeID, metrics.Timestamp, metrics.CPU.UsagePercent, metrics.CPU.UsageCores,
-		metrics.CPU.LoadAverage1, metrics.CPU.LoadAverage5, metrics.CPU.LoadAverage15,
-		metrics.Memory.Total, metrics.Memory.Used, metrics.Memory.Available, metrics.Memory.UsagePercent,
-		metrics.Storage.Total, metrics.Storage.Used, metrics.Storage.Available, metrics.Storage.UsagePercent,
-		metrics.Network.BytesIn, metrics.Network.BytesOut, metrics.Network.PacketsIn, metrics.Network.PacketsOut,
-		metrics.Network.ConnectionsIn, metrics.Network.ConnectionsOut, metrics.Network.ErrorsIn, metrics.Network.ErrorsOut,
-		metrics.System.Uptime, metrics.System.Processes, metrics.System.OS, metrics.System.Kernel, metrics.System.Architecture,
-	)
-
+	err := s.q.UpsertNodeMetrics(ctx, sqlcdb.UpsertNodeMetricsParams{
+		NodeID:                metrics.NodeID,
+		Timestamp:             metrics.Timestamp,
+		CpuUsage:              numStr(metrics.CPU.UsagePercent),
+		CpuCores:              numStr(metrics.CPU.UsageCores),
+		LoadAvg1:              numStr(metrics.CPU.LoadAverage1),
+		LoadAvg5:              numStr(metrics.CPU.LoadAverage5),
+		LoadAvg15:             numStr(metrics.CPU.LoadAverage15),
+		MemoryTotal:           int64N(metrics.Memory.Total),
+		MemoryUsed:            int64N(metrics.Memory.Used),
+		MemoryAvailable:       int64N(metrics.Memory.Available),
+		MemoryUsagePercent:    numStr(metrics.Memory.UsagePercent),
+		StorageTotal:          int64N(metrics.Storage.Total),
+		StorageUsed:           int64N(metrics.Storage.Used),
+		StorageAvailable:      int64N(metrics.Storage.Available),
+		StorageUsagePercent:   numStr(metrics.Storage.UsagePercent),
+		NetworkBytesIn:        int64N(metrics.Network.BytesIn),
+		NetworkBytesOut:       int64N(metrics.Network.BytesOut),
+		NetworkPacketsIn:      int64N(metrics.Network.PacketsIn),
+		NetworkPacketsOut:     int64N(metrics.Network.PacketsOut),
+		NetworkConnectionsIn:  int32N(metrics.Network.ConnectionsIn),
+		NetworkConnectionsOut: int32N(metrics.Network.ConnectionsOut),
+		NetworkErrorsIn:       int64N(metrics.Network.ErrorsIn),
+		NetworkErrorsOut:      int64N(metrics.Network.ErrorsOut),
+		// INTERVAL param — Postgres casts the bigint as seconds.
+		Uptime:       int64N(int64(metrics.System.Uptime.Seconds())),
+		Processes:    sql.NullInt32{Int32: int32(metrics.System.Processes), Valid: true},
+		Os:           strN(metrics.System.OS),
+		Kernel:       strN(metrics.System.Kernel),
+		Architecture: strN(metrics.System.Architecture),
+	})
 	if err != nil {
 		return fmt.Errorf("failed to store node metrics: %w", err)
 	}
-
-	// Store container metrics
-	for _, container := range metrics.Containers {
-		if err := s.storeContainerMetrics(ctx, metrics.NodeID, metrics.Timestamp, container); err != nil {
-			return fmt.Errorf("failed to store container metrics: %w", err)
-		}
-	}
-
 	return nil
 }
 
 // StoreServiceMetrics stores service metrics in the database
 func (s *PostgreSQLMetricsStorage) StoreServiceMetrics(ctx context.Context, metrics *ServiceMetrics) error {
-	query := `
-		INSERT INTO service_metrics (
-			service_id, service_name, project_id, timestamp,
-			requests_total, requests_success, requests_errors, requests_avg_latency,
-			requests_p95_latency, requests_p99_latency, requests_throughput,
-			errors_total, errors_rate, performance_response_time, performance_throughput,
-			performance_concurrency, performance_saturation, performance_utilization,
-			resource_cpu_usage, resource_memory_usage, resource_storage_usage,
-			resource_network_usage, resource_score
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23)
-		ON CONFLICT (service_id, timestamp) DO UPDATE SET
-			requests_total = EXCLUDED.requests_total,
-			requests_success = EXCLUDED.requests_success,
-			requests_errors = EXCLUDED.requests_errors,
-			requests_avg_latency = EXCLUDED.requests_avg_latency,
-			requests_p95_latency = EXCLUDED.requests_p95_latency,
-			requests_p99_latency = EXCLUDED.requests_p99_latency,
-			requests_throughput = EXCLUDED.requests_throughput,
-			errors_total = EXCLUDED.errors_total,
-			errors_rate = EXCLUDED.errors_rate,
-			performance_response_time = EXCLUDED.performance_response_time,
-			performance_throughput = EXCLUDED.performance_throughput,
-			performance_concurrency = EXCLUDED.performance_concurrency,
-			performance_saturation = EXCLUDED.performance_saturation,
-			performance_utilization = EXCLUDED.performance_utilization,
-			resource_cpu_usage = EXCLUDED.resource_cpu_usage,
-			resource_memory_usage = EXCLUDED.resource_memory_usage,
-			resource_storage_usage = EXCLUDED.resource_storage_usage,
-			resource_network_usage = EXCLUDED.resource_network_usage,
-			resource_score = EXCLUDED.resource_score
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		metrics.ServiceID, metrics.ServiceName, metrics.ProjectID, metrics.Timestamp,
-		metrics.Requests.Total, metrics.Requests.Success, metrics.Requests.Errors,
-		metrics.Requests.AvgLatency, metrics.Requests.P95Latency, metrics.Requests.P99Latency,
-		metrics.Requests.Throughput, metrics.Errors.Total, metrics.Errors.Rate,
-		metrics.Performance.ResponseTime, metrics.Performance.Throughput,
-		metrics.Performance.Concurrency, metrics.Performance.Saturation, metrics.Performance.Utilization,
-		metrics.Resources.CPUUsage, metrics.Resources.MemoryUsage, metrics.Resources.StorageUsage,
-		metrics.Resources.NetworkUsage, metrics.Resources.ResourceScore,
-	)
-
+	err := s.q.UpsertServiceMetrics(ctx, sqlcdb.UpsertServiceMetricsParams{
+		ServiceID:               metrics.ServiceID,
+		ServiceName:             metrics.ServiceName,
+		ProjectID:               metrics.ProjectID,
+		Timestamp:               metrics.Timestamp,
+		RequestsTotal:           int64N(metrics.Requests.Total),
+		RequestsSuccess:         int64N(metrics.Requests.Success),
+		RequestsErrors:          int64N(metrics.Requests.Errors),
+		RequestsAvgLatency:      numStr(metrics.Requests.AvgLatency),
+		RequestsP95Latency:      numStr(metrics.Requests.P95Latency),
+		RequestsP99Latency:      numStr(metrics.Requests.P99Latency),
+		RequestsThroughput:      numStr(metrics.Requests.Throughput),
+		ErrorsTotal:             int64N(metrics.Errors.Total),
+		ErrorsRate:              numStr(metrics.Errors.Rate),
+		PerformanceResponseTime: numStr(metrics.Performance.ResponseTime),
+		PerformanceThroughput:   numStr(metrics.Performance.Throughput),
+		PerformanceConcurrency:  int64N(metrics.Performance.Concurrency),
+		PerformanceSaturation:   numStr(metrics.Performance.Saturation),
+		PerformanceUtilization:  numStr(metrics.Performance.Utilization),
+		ResourceCpuUsage:        numStr(metrics.Resources.CPUUsage),
+		ResourceMemoryUsage:     int64N(metrics.Resources.MemoryUsage),
+		ResourceStorageUsage:    int64N(metrics.Resources.StorageUsage),
+		ResourceNetworkUsage:    int64N(metrics.Resources.NetworkUsage),
+		ResourceScore:           numStr(metrics.Resources.ResourceScore),
+	})
 	if err != nil {
 		return fmt.Errorf("failed to store service metrics: %w", err)
 	}
 
-	// Store instance metrics
+	// The service row must land first — instance_metrics references
+	// service_metrics(service_id, timestamp).
 	for _, instance := range metrics.Instances {
 		if err := s.storeInstanceMetrics(ctx, metrics.ServiceID, metrics.Timestamp, instance); err != nil {
 			return fmt.Errorf("failed to store instance metrics: %w", err)
 		}
 	}
-
 	return nil
 }
 
 // GetNodeMetrics retrieves node metrics from the database
 func (s *PostgreSQLMetricsStorage) GetNodeMetrics(ctx context.Context, nodeID string, from, to time.Time) ([]*NodeMetrics, error) {
-	query := `
-		SELECT node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
-			   memory_total, memory_used, memory_available, memory_usage_percent,
-			   storage_total, storage_used, storage_available, storage_usage_percent,
-			   network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			   network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			   uptime, processes, os, kernel, architecture
-		FROM node_metrics
-		WHERE node_id = $1 AND timestamp BETWEEN $2 AND $3
-		ORDER BY timestamp ASC
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, nodeID, from, to)
+	rows, err := s.q.ListNodeMetrics(ctx, sqlcdb.ListNodeMetricsParams{
+		NodeID:      nodeID,
+		Timestamp:   from,
+		Timestamp_2: to,
+	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to query node metrics: %w", err)
 	}
-	defer rows.Close()
 
 	var metrics []*NodeMetrics
-	for rows.Next() {
-		var m NodeMetrics
-		err := rows.Scan(
-			&m.NodeID, &m.Timestamp, &m.CPU.UsagePercent, &m.CPU.UsageCores,
-			&m.CPU.LoadAverage1, &m.CPU.LoadAverage5, &m.CPU.LoadAverage15,
-			&m.Memory.Total, &m.Memory.Used, &m.Memory.Available, &m.Memory.UsagePercent,
-			&m.Storage.Total, &m.Storage.Used, &m.Storage.Available, &m.Storage.UsagePercent,
-			&m.Network.BytesIn, &m.Network.BytesOut, &m.Network.PacketsIn, &m.Network.PacketsOut,
-			&m.Network.ConnectionsIn, &m.Network.ConnectionsOut, &m.Network.ErrorsIn, &m.Network.ErrorsOut,
-			&m.System.Uptime, &m.System.Processes, &m.System.OS, &m.System.Kernel, &m.System.Architecture,
-		)
-		if err != nil {
-			return nil, fmt.Errorf("failed to scan node metrics: %w", err)
-		}
-
-		// Get container metrics for this timestamp
-		containers, err := s.getContainerMetrics(ctx, nodeID, m.Timestamp)
-		if err != nil {
-			return nil, fmt.Errorf("failed to get container metrics: %w", err)
-		}
-		m.Containers = containers
-
-		metrics = append(metrics, &m)
+	for _, r := range rows {
+		metrics = append(metrics, &NodeMetrics{
+			NodeID:    r.NodeID,
+			Timestamp: r.Timestamp,
+			CPU: CPUMetrics{
+				UsagePercent:  f64v(r.CpuUsage),
+				UsageCores:    f64v(r.CpuCores),
+				LoadAverage1:  f64v(r.LoadAvg1),
+				LoadAverage5:  f64v(r.LoadAvg5),
+				LoadAverage15: f64v(r.LoadAvg15),
+			},
+			Memory: MemoryMetrics{
+				Total:        i64v(r.MemoryTotal),
+				Used:         i64v(r.MemoryUsed),
+				Available:    i64v(r.MemoryAvailable),
+				UsagePercent: f64v(r.MemoryUsagePercent),
+			},
+			Storage: StorageMetrics{
+				Total:        i64v(r.StorageTotal),
+				Used:         i64v(r.StorageUsed),
+				Available:    i64v(r.StorageAvailable),
+				UsagePercent: f64v(r.StorageUsagePercent),
+			},
+			Network: NetworkMetrics{
+				BytesIn:        i64v(r.NetworkBytesIn),
+				BytesOut:       i64v(r.NetworkBytesOut),
+				PacketsIn:      i64v(r.NetworkPacketsIn),
+				PacketsOut:     i64v(r.NetworkPacketsOut),
+				ConnectionsIn:  i32v(r.NetworkConnectionsIn),
+				ConnectionsOut: i32v(r.NetworkConnectionsOut),
+				ErrorsIn:       i64v(r.NetworkErrorsIn),
+				ErrorsOut:      i64v(r.NetworkErrorsOut),
+			},
+			System: SystemMetrics{
+				Uptime:       time.Duration(r.UptimeSeconds) * time.Second,
+				Processes:    int(r.Processes.Int32),
+				OS:           r.Os.String,
+				Kernel:       r.Kernel.String,
+				Architecture: r.Architecture.String,
+			},
+		})
 	}
-
 	return metrics, nil
 }
 
 // GetServiceMetrics retrieves service metrics from the database
 func (s *PostgreSQLMetricsStorage) GetServiceMetrics(ctx context.Context, serviceID string, from, to time.Time) ([]*ServiceMetrics, error) {
-	query := `
-		SELECT service_id, service_name, project_id, timestamp,
-			   requests_total, requests_success, requests_errors, requests_avg_latency,
-			   requests_p95_latency, requests_p99_latency, requests_throughput,
-			   errors_total, errors_rate, performance_response_time, performance_throughput,
-			   performance_concurrency, performance_saturation, performance_utilization,
-			   resource_cpu_usage, resource_memory_usage, resource_storage_usage,
-			   resource_network_usage, resource_score
-		FROM service_metrics
-		WHERE service_id = $1 AND timestamp BETWEEN $2 AND $3
-		ORDER BY timestamp ASC
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, serviceID, from, to)
+	rows, err := s.q.ListServiceMetrics(ctx, sqlcdb.ListServiceMetricsParams{
+		ServiceID:   serviceID,
+		Timestamp:   from,
+		Timestamp_2: to,
+	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to query service metrics: %w", err)
 	}
-	defer rows.Close()
 
 	var metrics []*ServiceMetrics
-	for rows.Next() {
-		var m ServiceMetrics
-		err := rows.Scan(
-			&m.ServiceID, &m.ServiceName, &m.ProjectID, &m.Timestamp,
-			&m.Requests.Total, &m.Requests.Success, &m.Requests.Errors,
-			&m.Requests.AvgLatency, &m.Requests.P95Latency, &m.Requests.P99Latency,
-			&m.Requests.Throughput, &m.Errors.Total, &m.Errors.Rate,
-			&m.Performance.ResponseTime, &m.Performance.Throughput,
-			&m.Performance.Concurrency, &m.Performance.Saturation, &m.Performance.Utilization,
-			&m.Resources.CPUUsage, &m.Resources.MemoryUsage, &m.Resources.StorageUsage,
-			&m.Resources.NetworkUsage, &m.Resources.ResourceScore,
-		)
-		if err != nil {
-			return nil, fmt.Errorf("failed to scan service metrics: %w", err)
+	for _, r := range rows {
+		m := &ServiceMetrics{
+			ServiceID:   r.ServiceID,
+			ServiceName: r.ServiceName,
+			ProjectID:   r.ProjectID,
+			Timestamp:   r.Timestamp,
+			Requests: RequestMetrics{
+				Total:      i64v(r.RequestsTotal),
+				Success:    i64v(r.RequestsSuccess),
+				Errors:     i64v(r.RequestsErrors),
+				AvgLatency: f64v(r.RequestsAvgLatency),
+				P95Latency: f64v(r.RequestsP95Latency),
+				P99Latency: f64v(r.RequestsP99Latency),
+				Throughput: f64v(r.RequestsThroughput),
+			},
+			Errors: ErrorMetrics{
+				Total: i64v(r.ErrorsTotal),
+				Rate:  f64v(r.ErrorsRate),
+			},
+			Performance: PerformanceMetrics{
+				ResponseTime: f64v(r.PerformanceResponseTime),
+				Throughput:   f64v(r.PerformanceThroughput),
+				Concurrency:  i64v(r.PerformanceConcurrency),
+				Saturation:   f64v(r.PerformanceSaturation),
+				Utilization:  f64v(r.PerformanceUtilization),
+			},
+			Resources: ResourceMetrics{
+				CPUUsage:      f64v(r.ResourceCpuUsage),
+				MemoryUsage:   i64v(r.ResourceMemoryUsage),
+				StorageUsage:  i64v(r.ResourceStorageUsage),
+				NetworkUsage:  i64v(r.ResourceNetworkUsage),
+				ResourceScore: f64v(r.ResourceScore),
+			},
 		}
 
-		// Get instance metrics for this timestamp
-		instances, err := s.getInstanceMetrics(ctx, serviceID, m.Timestamp)
+		instances, err := s.getInstanceMetrics(ctx, serviceID, r.Timestamp)
 		if err != nil {
 			return nil, fmt.Errorf("failed to get instance metrics: %w", err)
 		}
 		m.Instances = instances
-
-		metrics = append(metrics, &m)
+		metrics = append(metrics, m)
 	}
-
 	return metrics, nil
 }
 
-// GetAggregatedMetrics retrieves aggregated metrics based on a query
+// GetAggregatedMetrics retrieves aggregated metrics based on a query.
+// Bucketing uses date_bin (PostgreSQL 14+) — no TimescaleDB needed.
 func (s *PostgreSQLMetricsStorage) GetAggregatedMetrics(ctx context.Context, query MetricsQuery) (*AggregatedMetrics, error) {
-	// This is a simplified implementation
-	// In a real system, you'd build dynamic SQL based on the query
-
 	var timeSeries []TimeSeriesPoint
 	var summary map[string]MetricSummary
 
 	switch query.Type {
 	case "node":
-		// Aggregate node metrics
-		nodeQuery := `
-			SELECT 
-				time_bucket($1, timestamp) AS bucket,
-				AVG(cpu_usage) as avg_cpu,
-				AVG(memory_usage_percent) as avg_memory,
-				AVG(storage_usage_percent) as avg_storage
-			FROM node_metrics
-			WHERE node_id = $2 AND timestamp BETWEEN $3 AND $4
-			GROUP BY bucket
-			ORDER BY bucket ASC
-		`
-
-		rows, err := s.db.QueryContext(ctx, nodeQuery, query.Interval, query.ID, query.From, query.To)
+		seconds := int64(query.Interval.Seconds())
+		if seconds <= 0 {
+			seconds = 300
+		}
+		rows, err := s.q.AggregateNodeMetrics(ctx, sqlcdb.AggregateNodeMetricsParams{
+			Column1:     seconds,
+			NodeID:      query.ID,
+			Timestamp:   query.From,
+			Timestamp_2: query.To,
+		})
 		if err != nil {
 			return nil, fmt.Errorf("failed to query aggregated node metrics: %w", err)
 		}
-		defer rows.Close()
-
-		for rows.Next() {
-			var bucket time.Time
-			var avgCPU, avgMemory, avgStorage float64
-			if err := rows.Scan(&bucket, &avgCPU, &avgMemory, &avgStorage); err != nil {
-				return nil, fmt.Errorf("failed to scan aggregated metrics: %w", err)
-			}
-
-			point := TimeSeriesPoint{
+		for _, r := range rows {
+			bucket, _ := r.Bucket.(time.Time)
+			timeSeries = append(timeSeries, TimeSeriesPoint{
 				Timestamp: bucket,
 				Values: map[string]float64{
-					"cpu_usage":     avgCPU,
-					"memory_usage":  avgMemory,
-					"storage_usage": avgStorage,
+					"cpu_usage":     r.AvgCpu,
+					"memory_usage":  r.AvgMemory,
+					"storage_usage": r.AvgStorage,
 				},
-			}
-			timeSeries = append(timeSeries, point)
+			})
 		}
-
-		// Calculate summary statistics
 		summary = map[string]MetricSummary{
 			"cpu_usage":     calculateSummary(timeSeries, "cpu_usage"),
 			"memory_usage":  calculateSummary(timeSeries, "memory_usage"),
@@ -305,137 +298,69 @@ func (s *PostgreSQLMetricsStorage) GetAggregatedMetrics(ctx context.Context, que
 	}, nil
 }
 
-// Helper methods
-
-func (s *PostgreSQLMetricsStorage) storeContainerMetrics(ctx context.Context, nodeID string, timestamp time.Time, container ContainerMetrics) error {
-	query := `
-		INSERT INTO container_metrics (
-			node_id, timestamp, container_id, name, state, cpu, memory,
-			network_bytes_in, network_bytes_out, network_packets_in, network_packets_out, start_time
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
-		ON CONFLICT (node_id, timestamp, container_id) DO UPDATE SET
-			name = EXCLUDED.name,
-			state = EXCLUDED.state,
-			cpu = EXCLUDED.cpu,
-			memory = EXCLUDED.memory,
-			network_bytes_in = EXCLUDED.network_bytes_in,
-			network_bytes_out = EXCLUDED.network_bytes_out,
-			network_packets_in = EXCLUDED.network_packets_in,
-			network_packets_out = EXCLUDED.network_packets_out,
-			start_time = EXCLUDED.start_time
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		nodeID, timestamp, container.ContainerID, container.Name, container.State,
-		container.CPU, container.Memory, container.Network.BytesIn, container.Network.BytesOut,
-		container.Network.PacketsIn, container.Network.PacketsOut, container.StartTime,
-	)
-
-	return err
-}
-
 func (s *PostgreSQLMetricsStorage) storeInstanceMetrics(ctx context.Context, serviceID string, timestamp time.Time, instance InstanceMetrics) error {
-	query := `
-		INSERT INTO instance_metrics (
-			service_id, timestamp, instance_id, node_id, status, cpu, memory,
-			network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21)
-		ON CONFLICT (service_id, timestamp, instance_id) DO UPDATE SET
-			node_id = EXCLUDED.node_id,
-			status = EXCLUDED.status,
-			cpu = EXCLUDED.cpu,
-			memory = EXCLUDED.memory,
-			network_bytes_in = EXCLUDED.network_bytes_in,
-			network_bytes_out = EXCLUDED.network_bytes_out,
-			network_packets_in = EXCLUDED.network_packets_in,
-			network_packets_out = EXCLUDED.network_packets_out,
-			network_connections_in = EXCLUDED.network_connections_in,
-			network_connections_out = EXCLUDED.network_connections_out,
-			network_errors_in = EXCLUDED.network_errors_in,
-			network_errors_out = EXCLUDED.network_errors_out,
-			start_time = EXCLUDED.start_time,
-			last_seen = EXCLUDED.last_seen,
-			health_status = EXCLUDED.health_status,
-			health_last_check = EXCLUDED.health_last_check,
-			health_check_count = EXCLUDED.health_check_count,
-			health_failure_count = EXCLUDED.health_failure_count
-	`
-
-	_, err := s.db.ExecContext(ctx, query,
-		serviceID, timestamp, instance.InstanceID, instance.NodeID, instance.Status,
-		instance.CPU, instance.Memory, instance.Network.BytesIn, instance.Network.BytesOut,
-		instance.Network.PacketsIn, instance.Network.PacketsOut, instance.Network.ConnectionsIn,
-		instance.Network.ConnectionsOut, instance.Network.ErrorsIn, instance.Network.ErrorsOut,
-		instance.StartTime, instance.LastSeen, instance.Health.Status, instance.Health.LastCheck,
-		instance.Health.CheckCount, instance.Health.FailureCount,
-	)
-
-	return err
-}
-
-func (s *PostgreSQLMetricsStorage) getContainerMetrics(ctx context.Context, nodeID string, timestamp time.Time) ([]ContainerMetrics, error) {
-	query := `
-		SELECT container_id, name, state, cpu, memory,
-			   network_bytes_in, network_bytes_out, network_packets_in, network_packets_out, start_time
-		FROM container_metrics
-		WHERE node_id = $1 AND timestamp = $2
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, nodeID, timestamp)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	var containers []ContainerMetrics
-	for rows.Next() {
-		var c ContainerMetrics
-		err := rows.Scan(
-			&c.ContainerID, &c.Name, &c.State, &c.CPU, &c.Memory,
-			&c.Network.BytesIn, &c.Network.BytesOut, &c.Network.PacketsIn, &c.Network.PacketsOut, &c.StartTime,
-		)
-		if err != nil {
-			return nil, err
-		}
-		containers = append(containers, c)
-	}
-
-	return containers, nil
+	return s.q.UpsertInstanceMetrics(ctx, sqlcdb.UpsertInstanceMetricsParams{
+		ServiceID:             serviceID,
+		Timestamp:             timestamp,
+		InstanceID:            instance.InstanceID,
+		NodeID:                strN(instance.NodeID),
+		Status:                strN(instance.Status),
+		Cpu:                   numStr(instance.CPU),
+		Memory:                int64N(instance.Memory),
+		NetworkBytesIn:        int64N(instance.Network.BytesIn),
+		NetworkBytesOut:       int64N(instance.Network.BytesOut),
+		NetworkPacketsIn:      int64N(instance.Network.PacketsIn),
+		NetworkPacketsOut:     int64N(instance.Network.PacketsOut),
+		NetworkConnectionsIn:  int32N(instance.Network.ConnectionsIn),
+		NetworkConnectionsOut: int32N(instance.Network.ConnectionsOut),
+		NetworkErrorsIn:       int64N(instance.Network.ErrorsIn),
+		NetworkErrorsOut:      int64N(instance.Network.ErrorsOut),
+		StartTime:             timeN(instance.StartTime),
+		LastSeen:              timeN(instance.LastSeen),
+		HealthStatus:          strN(instance.Health.Status),
+		HealthLastCheck:       timeN(instance.Health.LastCheck),
+		HealthCheckCount:      sql.NullInt32{Int32: int32(instance.Health.CheckCount), Valid: true},
+		HealthFailureCount:    sql.NullInt32{Int32: int32(instance.Health.FailureCount), Valid: true},
+	})
 }
 
 func (s *PostgreSQLMetricsStorage) getInstanceMetrics(ctx context.Context, serviceID string, timestamp time.Time) ([]InstanceMetrics, error) {
-	query := `
-		SELECT instance_id, node_id, status, cpu, memory,
-			   network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
-			   network_connections_in, network_connections_out, network_errors_in, network_errors_out,
-			   start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
-		FROM instance_metrics
-		WHERE service_id = $1 AND timestamp = $2
-	`
-
-	rows, err := s.db.QueryContext(ctx, query, serviceID, timestamp)
+	rows, err := s.q.ListInstanceMetrics(ctx, sqlcdb.ListInstanceMetricsParams{
+		ServiceID: serviceID,
+		Timestamp: timestamp,
+	})
 	if err != nil {
 		return nil, err
 	}
-	defer rows.Close()
 
 	var instances []InstanceMetrics
-	for rows.Next() {
-		var i InstanceMetrics
-		err := rows.Scan(
-			&i.InstanceID, &i.NodeID, &i.Status, &i.CPU, &i.Memory,
-			&i.Network.BytesIn, &i.Network.BytesOut, &i.Network.PacketsIn, &i.Network.PacketsOut,
-			&i.Network.ConnectionsIn, &i.Network.ConnectionsOut, &i.Network.ErrorsIn, &i.Network.ErrorsOut,
-			&i.StartTime, &i.LastSeen, &i.Health.Status, &i.Health.LastCheck, &i.Health.CheckCount, &i.Health.FailureCount,
-		)
-		if err != nil {
-			return nil, err
-		}
-		instances = append(instances, i)
+	for _, r := range rows {
+		instances = append(instances, InstanceMetrics{
+			InstanceID: r.InstanceID,
+			NodeID:     r.NodeID.String,
+			Status:     r.Status.String,
+			CPU:        f64v(r.Cpu),
+			Memory:     i64v(r.Memory),
+			Network: NetworkMetrics{
+				BytesIn:        i64v(r.NetworkBytesIn),
+				BytesOut:       i64v(r.NetworkBytesOut),
+				PacketsIn:      i64v(r.NetworkPacketsIn),
+				PacketsOut:     i64v(r.NetworkPacketsOut),
+				ConnectionsIn:  i32v(r.NetworkConnectionsIn),
+				ConnectionsOut: i32v(r.NetworkConnectionsOut),
+				ErrorsIn:       i64v(r.NetworkErrorsIn),
+				ErrorsOut:      i64v(r.NetworkErrorsOut),
+			},
+			StartTime: r.StartTime.Time,
+			LastSeen:  r.LastSeen.Time,
+			Health: HealthMetrics{
+				Status:       r.HealthStatus.String,
+				LastCheck:    r.HealthLastCheck.Time,
+				CheckCount:   int(r.HealthCheckCount.Int32),
+				FailureCount: int(r.HealthFailureCount.Int32),
+			},
+		})
 	}
-
 	return instances, nil
 }
 
@@ -544,7 +469,9 @@ func (s *InMemoryMetricsStorage) GetServiceMetrics(ctx context.Context, serviceI
 }
 
 func (s *InMemoryMetricsStorage) GetAggregatedMetrics(ctx context.Context, query MetricsQuery) (*AggregatedMetrics, error) {
-	// Simplified implementation
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
 	return &AggregatedMetrics{
 		Query:      query,
 		TimeSeries: []TimeSeriesPoint{},

app/backend/internal/metrics/storage_test.go

@@ -0,0 +1,130 @@
+package metrics
+
+import (
+	"context"
+	"database/sql"
+	"os"
+	"testing"
+	"time"
+)
+
+// Live round-trip against a real Postgres — set METRICS_TEST_DSN (or
+// DATABASE_URL) to enable. Skipped by default so unit runs stay hermetic.
+func testDSN(t *testing.T) *sql.DB {
+	t.Helper()
+	dsn := os.Getenv("METRICS_TEST_DSN")
+	if dsn == "" {
+		dsn = os.Getenv("DATABASE_URL")
+	}
+	if dsn == "" {
+		t.Skip("METRICS_TEST_DSN not set")
+	}
+	db, err := sql.Open("postgres", dsn)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.PingContext(context.Background()); err != nil {
+		t.Fatalf("ping: %v", err)
+	}
+	t.Cleanup(func() { db.Close() })
+	return db
+}
+
+func TestPostgresStorageRoundTrip(t *testing.T) {
+	db := testDSN(t)
+	s := NewPostgreSQLMetricsStorage(db)
+	ctx := context.Background()
+
+	ts := time.Now().UTC().Truncate(time.Second)
+	nodeID := "test-node-" + ts.Format("150405")
+	svcID := "test-svc-" + ts.Format("150405")
+
+	// Clean slate + teardown
+	db.ExecContext(ctx, `DELETE FROM instance_metrics WHERE service_id = $1`, svcID)
+	db.ExecContext(ctx, `DELETE FROM service_metrics WHERE service_id = $1`, svcID)
+	db.ExecContext(ctx, `DELETE FROM node_metrics WHERE node_id = $1`, nodeID)
+	t.Cleanup(func() {
+		db.ExecContext(ctx, `DELETE FROM instance_metrics WHERE service_id = $1`, svcID)
+		db.ExecContext(ctx, `DELETE FROM service_metrics WHERE service_id = $1`, svcID)
+		db.ExecContext(ctx, `DELETE FROM node_metrics WHERE node_id = $1`, nodeID)
+	})
+
+	node := &NodeMetrics{
+		NodeID:    nodeID,
+		Timestamp: ts,
+		CPU:       CPUMetrics{UsagePercent: 42.5, UsageCores: 1.7, LoadAverage1: 0.5, LoadAverage5: 0.4, LoadAverage15: 0.3},
+		Memory:    MemoryMetrics{Total: 16 << 30, Used: 8 << 30, Available: 8 << 30, UsagePercent: 50.0},
+		Storage:   StorageMetrics{Total: 100 << 30, Used: 40 << 30, Available: 60 << 30, UsagePercent: 40.0},
+		Network:   NetworkMetrics{BytesIn: 1000, BytesOut: 2000, PacketsIn: 10, PacketsOut: 20, ConnectionsIn: 3, ConnectionsOut: 4, ErrorsIn: 0, ErrorsOut: 1},
+		System:    SystemMetrics{Uptime: 3600 * time.Second, Processes: 120, OS: "linux", Kernel: "6.8", Architecture: "amd64"},
+	}
+	if err := s.StoreNodeMetrics(ctx, node); err != nil {
+		t.Fatalf("store node: %v", err)
+	}
+	// Upsert idempotent on the same key.
+	if err := s.StoreNodeMetrics(ctx, node); err != nil {
+		t.Fatalf("store node (repeat): %v", err)
+	}
+
+	svc := &ServiceMetrics{
+		ServiceID:   svcID,
+		ServiceName: "svc",
+		ProjectID:   "proj",
+		Timestamp:   ts,
+		Requests:    RequestMetrics{Total: 100, Success: 95, Errors: 5, AvgLatency: 12.5, P95Latency: 80, P99Latency: 120, Throughput: 3.3},
+		Errors:      ErrorMetrics{Total: 5, Rate: 0.05},
+		Performance: PerformanceMetrics{ResponseTime: 12.5, Throughput: 3.3, Concurrency: 2, Saturation: 0.4, Utilization: 0.55},
+		Resources:   ResourceMetrics{CPUUsage: 42.5, MemoryUsage: 512 << 20, StorageUsage: 1 << 30, NetworkUsage: 3000, ResourceScore: 0.7},
+		Instances: []InstanceMetrics{{
+			InstanceID: "inst-1",
+			NodeID:     nodeID,
+			Status:     "running",
+			CPU:        42.5,
+			Memory:     512 << 20,
+			Network:    NetworkMetrics{BytesIn: 1000, BytesOut: 2000},
+			StartTime:  ts.Add(-time.Hour),
+			LastSeen:   ts,
+			Health:     HealthMetrics{Status: "healthy", LastCheck: ts, CheckCount: 10, FailureCount: 0},
+		}},
+	}
+	if err := s.StoreServiceMetrics(ctx, svc); err != nil {
+		t.Fatalf("store service: %v", err)
+	}
+
+	from, to := ts.Add(-time.Minute), ts.Add(time.Minute)
+	gotNodes, err := s.GetNodeMetrics(ctx, nodeID, from, to)
+	if err != nil {
+		t.Fatalf("get nodes: %v", err)
+	}
+	if len(gotNodes) != 1 {
+		t.Fatalf("want 1 node row, got %d", len(gotNodes))
+	}
+	if got := gotNodes[0]; got.CPU.UsagePercent != 42.5 || got.System.Processes != 120 || got.System.Uptime != time.Hour {
+		t.Errorf("node round-trip mismatch: %+v", got)
+	}
+
+	gotSvcs, err := s.GetServiceMetrics(ctx, svcID, from, to)
+	if err != nil {
+		t.Fatalf("get services: %v", err)
+	}
+	if len(gotSvcs) != 1 {
+		t.Fatalf("want 1 service row, got %d", len(gotSvcs))
+	}
+	if gotSvcs[0].Requests.P99Latency != 120 {
+		t.Errorf("p99 mismatch: %v", gotSvcs[0].Requests.P99Latency)
+	}
+	if len(gotSvcs[0].Instances) != 1 || gotSvcs[0].Instances[0].Health.Status != "healthy" {
+		t.Errorf("instance join mismatch: %+v", gotSvcs[0].Instances)
+	}
+
+	agg, err := s.GetAggregatedMetrics(ctx, MetricsQuery{Type: "node", ID: nodeID, From: from, To: to, Interval: 5 * time.Minute})
+	if err != nil {
+		t.Fatalf("aggregate: %v", err)
+	}
+	if len(agg.TimeSeries) != 1 || agg.TimeSeries[0].Values["cpu_usage"] != 42.5 {
+		t.Errorf("aggregate mismatch: %+v", agg.TimeSeries)
+	}
+	if agg.Summary["cpu_usage"].Avg != 42.5 {
+		t.Errorf("summary mismatch: %+v", agg.Summary)
+	}
+}

app/backend/sqlc/queries/domains.sql

@@ -0,0 +1,46 @@
+-- name: ListServiceDomains :many
+SELECT id, service_id, domain, is_default, cert_type, cert_status, last_checked_at, created_at
+FROM service_domains
+WHERE service_id = $1
+ORDER BY is_default DESC, created_at ASC;
+
+-- name: CountServiceDomains :one
+SELECT COUNT(*) FROM service_domains WHERE service_id = $1;
+
+-- name: ClearServiceDomainDefault :exec
+UPDATE service_domains SET is_default = false WHERE service_id = $1;
+
+-- name: CreateServiceDomain :one
+INSERT INTO service_domains (service_id, domain, is_default)
+VALUES ($1, $2, $3)
+RETURNING id, service_id, domain, is_default, cert_type, cert_status, created_at;
+
+-- name: DeleteServiceDomain :execrows
+DELETE FROM service_domains WHERE id = $1 AND service_id = $2;
+
+-- name: SetServiceDomainDefault :execrows
+UPDATE service_domains SET is_default = (id = $1) WHERE service_id = $2;
+
+-- name: TouchServiceDomainChecked :exec
+UPDATE service_domains SET last_checked_at = NOW() WHERE id = $1;
+
+-- name: GetServiceDomainDefault :one
+SELECT domain FROM service_domains WHERE service_id = $1 AND is_default;
+
+-- name: GetServiceDomainFirst :one
+SELECT domain FROM service_domains WHERE service_id = $1 ORDER BY created_at ASC LIMIT 1;
+
+-- name: SetServiceLegacyDomain :exec
+UPDATE services SET domain = $1 WHERE id = $2;
+
+-- name: GetServicePlacementBrief :one
+SELECT name, node_id, COALESCE(spread, false) AS spread FROM services WHERE id = $1;
+
+-- name: GetServiceAccess :one
+SELECT maintenance_mode, basic_auth_users FROM services WHERE id = $1;
+
+-- name: ServiceWriteAccess :one
+SELECT EXISTS(
+    SELECT 1 FROM services s JOIN projects p ON s.project_id = p.id
+    WHERE s.id = $1 AND (p.owner_id = $2 OR $3::bool)
+) AS allowed;

app/backend/sqlc/queries/metrics.sql

@@ -0,0 +1,147 @@
+-- name: UpsertNodeMetrics :exec
+INSERT INTO node_metrics (
+    node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+    memory_total, memory_used, memory_available, memory_usage_percent,
+    storage_total, storage_used, storage_available, storage_usage_percent,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    uptime, processes, os, kernel, architecture
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28
+)
+ON CONFLICT (node_id, timestamp) DO UPDATE SET
+    cpu_usage = EXCLUDED.cpu_usage,
+    cpu_cores = EXCLUDED.cpu_cores,
+    load_avg_1 = EXCLUDED.load_avg_1,
+    load_avg_5 = EXCLUDED.load_avg_5,
+    load_avg_15 = EXCLUDED.load_avg_15,
+    memory_total = EXCLUDED.memory_total,
+    memory_used = EXCLUDED.memory_used,
+    memory_available = EXCLUDED.memory_available,
+    memory_usage_percent = EXCLUDED.memory_usage_percent,
+    storage_total = EXCLUDED.storage_total,
+    storage_used = EXCLUDED.storage_used,
+    storage_available = EXCLUDED.storage_available,
+    storage_usage_percent = EXCLUDED.storage_usage_percent,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    uptime = EXCLUDED.uptime,
+    processes = EXCLUDED.processes,
+    os = EXCLUDED.os,
+    kernel = EXCLUDED.kernel,
+    architecture = EXCLUDED.architecture;
+
+-- name: UpsertServiceMetrics :exec
+INSERT INTO service_metrics (
+    service_id, service_name, project_id, timestamp,
+    requests_total, requests_success, requests_errors, requests_avg_latency,
+    requests_p95_latency, requests_p99_latency, requests_throughput,
+    errors_total, errors_rate, performance_response_time, performance_throughput,
+    performance_concurrency, performance_saturation, performance_utilization,
+    resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+    resource_network_usage, resource_score
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21, $22, $23
+)
+ON CONFLICT (service_id, timestamp) DO UPDATE SET
+    requests_total = EXCLUDED.requests_total,
+    requests_success = EXCLUDED.requests_success,
+    requests_errors = EXCLUDED.requests_errors,
+    requests_avg_latency = EXCLUDED.requests_avg_latency,
+    requests_p95_latency = EXCLUDED.requests_p95_latency,
+    requests_p99_latency = EXCLUDED.requests_p99_latency,
+    requests_throughput = EXCLUDED.requests_throughput,
+    errors_total = EXCLUDED.errors_total,
+    errors_rate = EXCLUDED.errors_rate,
+    performance_response_time = EXCLUDED.performance_response_time,
+    performance_throughput = EXCLUDED.performance_throughput,
+    performance_concurrency = EXCLUDED.performance_concurrency,
+    performance_saturation = EXCLUDED.performance_saturation,
+    performance_utilization = EXCLUDED.performance_utilization,
+    resource_cpu_usage = EXCLUDED.resource_cpu_usage,
+    resource_memory_usage = EXCLUDED.resource_memory_usage,
+    resource_storage_usage = EXCLUDED.resource_storage_usage,
+    resource_network_usage = EXCLUDED.resource_network_usage,
+    resource_score = EXCLUDED.resource_score;
+
+-- name: UpsertInstanceMetrics :exec
+INSERT INTO instance_metrics (
+    service_id, timestamp, instance_id, node_id, status, cpu, memory,
+    network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+    network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+    start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+    $16, $17, $18, $19, $20, $21
+)
+ON CONFLICT (service_id, timestamp, instance_id) DO UPDATE SET
+    node_id = EXCLUDED.node_id,
+    status = EXCLUDED.status,
+    cpu = EXCLUDED.cpu,
+    memory = EXCLUDED.memory,
+    network_bytes_in = EXCLUDED.network_bytes_in,
+    network_bytes_out = EXCLUDED.network_bytes_out,
+    network_packets_in = EXCLUDED.network_packets_in,
+    network_packets_out = EXCLUDED.network_packets_out,
+    network_connections_in = EXCLUDED.network_connections_in,
+    network_connections_out = EXCLUDED.network_connections_out,
+    network_errors_in = EXCLUDED.network_errors_in,
+    network_errors_out = EXCLUDED.network_errors_out,
+    start_time = EXCLUDED.start_time,
+    last_seen = EXCLUDED.last_seen,
+    health_status = EXCLUDED.health_status,
+    health_last_check = EXCLUDED.health_last_check,
+    health_check_count = EXCLUDED.health_check_count,
+    health_failure_count = EXCLUDED.health_failure_count;
+
+-- name: ListNodeMetrics :many
+SELECT node_id, timestamp, cpu_usage, cpu_cores, load_avg_1, load_avg_5, load_avg_15,
+       memory_total, memory_used, memory_available, memory_usage_percent,
+       storage_total, storage_used, storage_available, storage_usage_percent,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       coalesce(extract(epoch from uptime), 0)::bigint AS uptime_seconds,
+       processes, os, kernel, architecture
+FROM node_metrics
+WHERE node_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC;
+
+-- name: ListServiceMetrics :many
+SELECT service_id, service_name, project_id, timestamp,
+       requests_total, requests_success, requests_errors, requests_avg_latency,
+       requests_p95_latency, requests_p99_latency, requests_throughput,
+       errors_total, errors_rate, performance_response_time, performance_throughput,
+       performance_concurrency, performance_saturation, performance_utilization,
+       resource_cpu_usage, resource_memory_usage, resource_storage_usage,
+       resource_network_usage, resource_score
+FROM service_metrics
+WHERE service_id = $1 AND timestamp BETWEEN $2 AND $3
+ORDER BY timestamp ASC;
+
+-- name: ListInstanceMetrics :many
+SELECT instance_id, node_id, status, cpu, memory,
+       network_bytes_in, network_bytes_out, network_packets_in, network_packets_out,
+       network_connections_in, network_connections_out, network_errors_in, network_errors_out,
+       start_time, last_seen, health_status, health_last_check, health_check_count, health_failure_count
+FROM instance_metrics
+WHERE service_id = $1 AND timestamp = $2;
+
+-- name: AggregateNodeMetrics :many
+-- Portable bucket bucketing (no TimescaleDB): floor epoch seconds into
+-- bucket-sized buckets, then back to timestamptz.
+SELECT date_bin($1::interval, timestamp, '2000-01-01'::timestamptz) AS bucket,
+       AVG(cpu_usage)::float8 AS avg_cpu,
+       AVG(memory_usage_percent)::float8 AS avg_memory,
+       AVG(storage_usage_percent)::float8 AS avg_storage
+FROM node_metrics
+WHERE node_id = $2 AND timestamp BETWEEN $3 AND $4
+GROUP BY bucket
+ORDER BY bucket ASC;

app/backend/sqlc/schema.sql

@@ -346,3 +346,90 @@ CREATE TABLE notification_channels (
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
 );
+
+CREATE TABLE node_metrics (
+    node_id VARCHAR(255) NOT NULL,
+    timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
+    cpu_usage NUMERIC(5,2),
+    cpu_cores NUMERIC(10,2),
+    load_avg_1 NUMERIC(5,2),
+    load_avg_5 NUMERIC(5,2),
+    load_avg_15 NUMERIC(5,2),
+    memory_total BIGINT,
+    memory_used BIGINT,
+    memory_available BIGINT,
+    memory_usage_percent NUMERIC(5,2),
+    storage_total BIGINT,
+    storage_used BIGINT,
+    storage_available BIGINT,
+    storage_usage_percent NUMERIC(5,2),
+    network_bytes_in BIGINT,
+    network_bytes_out BIGINT,
+    network_packets_in BIGINT,
+    network_packets_out BIGINT,
+    network_connections_in INTEGER,
+    network_connections_out INTEGER,
+    network_errors_in BIGINT,
+    network_errors_out BIGINT,
+    uptime INTERVAL,
+    processes INTEGER,
+    os VARCHAR(50),
+    kernel VARCHAR(50),
+    architecture VARCHAR(20),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    PRIMARY KEY (node_id, timestamp)
+);
+
+CREATE TABLE service_metrics (
+    service_id VARCHAR(255) NOT NULL,
+    service_name VARCHAR(255) NOT NULL,
+    project_id VARCHAR(255) NOT NULL,
+    timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
+    requests_total BIGINT DEFAULT 0,
+    requests_success BIGINT DEFAULT 0,
+    requests_errors BIGINT DEFAULT 0,
+    requests_avg_latency NUMERIC(10,3),
+    requests_p95_latency NUMERIC(10,3),
+    requests_p99_latency NUMERIC(10,3),
+    requests_throughput NUMERIC(10,3),
+    errors_total BIGINT DEFAULT 0,
+    errors_rate NUMERIC(5,4),
+    performance_response_time NUMERIC(10,3),
+    performance_throughput NUMERIC(10,3),
+    performance_concurrency BIGINT,
+    performance_saturation NUMERIC(5,2),
+    performance_utilization NUMERIC(5,2),
+    resource_cpu_usage NUMERIC(5,2),
+    resource_memory_usage BIGINT,
+    resource_storage_usage BIGINT,
+    resource_network_usage BIGINT,
+    resource_score NUMERIC(5,2),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    PRIMARY KEY (service_id, timestamp)
+);
+
+CREATE TABLE instance_metrics (
+    service_id VARCHAR(255) NOT NULL,
+    timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
+    instance_id VARCHAR(255) NOT NULL,
+    node_id VARCHAR(255),
+    status VARCHAR(50),
+    cpu NUMERIC(5,2),
+    memory BIGINT,
+    network_bytes_in BIGINT,
+    network_bytes_out BIGINT,
+    network_packets_in BIGINT,
+    network_packets_out BIGINT,
+    network_connections_in INTEGER,
+    network_connections_out INTEGER,
+    network_errors_in BIGINT,
+    network_errors_out BIGINT,
+    start_time TIMESTAMP WITH TIME ZONE,
+    last_seen TIMESTAMP WITH TIME ZONE,
+    health_status VARCHAR(20),
+    health_last_check TIMESTAMP WITH TIME ZONE,
+    health_check_count INTEGER DEFAULT 0,
+    health_failure_count INTEGER DEFAULT 0,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    PRIMARY KEY (service_id, timestamp, instance_id)
+);

app/frontend/src/app/App.tsx

@@ -28,6 +28,7 @@ import {
 } from '@/features/secondary/pages';
 import { NodeDetailPage } from '@/features/nodes/NodeDetailPage';
 import { AcceptInvitePage, SignInPage, SignUpPage } from '@/features/auth/pages';
+import { SetupWizardPage } from '@/features/setup/SetupWizardPage';
 import { useAuthSession } from '@/lib/use-auth-session';
 import { useDemoMode } from '@/lib/demo-mode';
 import { getCurrentUserProfile } from '@/lib/api-client';
@@ -138,6 +139,7 @@ export default function App() {
         <Route path="/auth/sign-in" element={<SignInPage />} />
         <Route path="/auth/sign-up" element={<SignUpPage />} />
         <Route path="/auth/accept-invite" element={<AcceptInvitePage />} />
+        <Route path="/setup" element={<SetupWizardPage />} />
 
         {/* Public browsing — approved projects, templates, docs. */}
         {/* Project workspace renders outside the shell — fullscreen canvas, no nav chrome */}

app/frontend/src/app/layout/PlatformShell.tsx

@@ -1,4 +1,4 @@
-import { NavLink, Outlet, useLocation, useNavigate } from 'react-router-dom';
+import { NavLink, Navigate, Outlet, useLocation, useNavigate } from 'react-router-dom';
 import { useEffect, useState } from 'react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
@@ -36,6 +36,7 @@ import {
   getCurrentUserProfile,
   getUpgradeStatus,
   pingServer,
+  getSetupStatus,
   listNotifications,
   markAllNotificationsRead,
   markNotificationRead,
@@ -185,6 +186,13 @@ export function PlatformShell() {
     enabled: !isDemoMode && signedIn,
     refetchInterval: 30_000,
   });
+  // Fresh installs get routed through the setup wizard until the flag lands.
+  const setupQuery = useQuery({
+    queryKey: ['setup-status'],
+    queryFn: getSetupStatus,
+    enabled: !isDemoMode && signedIn,
+    staleTime: 60_000,
+  });
   const markReadMutation = useMutation({
     mutationFn: (id: string) => markNotificationRead(id),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['shell-notifications'] }),
@@ -247,6 +255,10 @@ export function PlatformShell() {
     </div>
   );
 
+  if (!isDemoMode && signedIn && setupQuery.data?.needs_setup) {
+    return <Navigate to="/setup" replace />;
+  }
+
   return (
     <div className="app-shell min-h-screen">
       <div className="ambient-glow" />

app/frontend/src/features/secondary/pages.tsx

@@ -1253,7 +1253,11 @@ export function GitHubAppCallbackPage() {
     mutationFn: (appCode: string) => convertGitHubAppCode(appCode),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['github-app-status'] });
-      navigate('/settings', { replace: true });
+      // The setup wizard stashes a return marker before submitting the
+      // manifest form — resume there instead of the settings page.
+      const inSetup = sessionStorage.getItem('containr.setup_return') === '1';
+      sessionStorage.removeItem('containr.setup_return');
+      navigate(inSetup ? '/setup' : '/settings', { replace: true });
     },
   });
   const firedRef = useRef(false);

app/frontend/src/features/setup/SetupWizardPage.test.tsx

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+import { SetupWizardPage } from './SetupWizardPage';
+import type { SetupStatus } from '@/lib/api-client';
+
+const mockStatus = vi.fn<() => Promise<SetupStatus>>();
+const mockSession = vi.fn();
+
+vi.mock('@/lib/api-client', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('@/lib/api-client')>();
+  return {
+    ...mod,
+    getSetupStatus: () => mockStatus(),
+    completeSetup: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+vi.mock('@/lib/use-auth-session', () => ({
+  useAuthSession: () => mockSession(),
+}));
+
+function renderWizard() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter initialEntries={['/setup']}>
+        <SetupWizardPage />
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+}
+
+const base: SetupStatus = {
+  has_users: false,
+  setup_completed: false,
+  needs_setup: true,
+  has_github_app: false,
+  has_tunnel: false,
+  signup_enabled: false,
+};
+
+describe('SetupWizardPage', () => {
+  beforeEach(() => {
+    mockSession.mockReturnValue({ data: null });
+  });
+
+  it('prompts for the admin account on a fresh install', async () => {
+    mockStatus.mockResolvedValue({ ...base });
+    renderWizard();
+    expect(await screen.findByText(/welcome to containr/i)).toBeInTheDocument();
+    expect(screen.getByText(/create admin account/i)).toBeInTheDocument();
+  });
+
+  it('offers sign-in when users exist but nobody is signed in', async () => {
+    mockStatus.mockResolvedValue({ ...base, has_users: true });
+    renderWizard();
+    expect(await screen.findByText(/sign in to continue setup/i)).toBeInTheDocument();
+  });
+
+  it('shows the git provider step for a signed-in admin without GitHub App', async () => {
+    mockStatus.mockResolvedValue({ ...base, has_users: true });
+    mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+    renderWizard();
+    expect(await screen.findByText(/connect a git provider/i)).toBeInTheDocument();
+    expect(screen.getByText(/set up github app/i)).toBeInTheDocument();
+  });
+
+  it('shows the tunnel step when git is already wired', async () => {
+    mockStatus.mockResolvedValue({ ...base, has_users: true, has_github_app: true });
+    mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+    renderWizard();
+    expect(
+      await screen.findByRole('heading', { name: /public access/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('lands on the finish step when everything is configured', async () => {
+    mockStatus.mockResolvedValue({
+      ...base,
+      has_users: true,
+      has_github_app: true,
+      has_tunnel: true,
+    });
+    mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+    renderWizard();
+    expect(await screen.findByText(/enter containr/i)).toBeInTheDocument();
+  });
+});

app/frontend/src/features/setup/SetupWizardPage.tsx

@@ -0,0 +1,279 @@
+import { useMemo, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Link, Navigate, useNavigate } from 'react-router-dom';
+import { Check, ChevronRight, Github, Loader2, Rocket, ShieldCheck } from 'lucide-react';
+import { useAuthSession } from '@/lib/use-auth-session';
+import {
+  completeSetup,
+  createGitHubAppManifest,
+  getSetupStatus,
+  updatePlatformSettings,
+} from '@/lib/api-client';
+
+// Marker the GitHub App callback reads so the wizard flow resumes here
+// instead of the settings page.
+const SETUP_RETURN_KEY = 'containr.setup_return';
+
+type Step = 'account' | 'github' | 'tunnel' | 'done';
+
+export function SetupWizardPage() {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const sessionQuery = useAuthSession();
+  const statusQuery = useQuery({ queryKey: ['setup-status'], queryFn: getSetupStatus });
+  const [override, setOverride] = useState<Step | null>(null);
+
+  const status = statusQuery.data;
+  const signedIn = Boolean(sessionQuery.data);
+
+  const step: Step = useMemo(() => {
+    if (override) return override;
+    if (!status) return 'account';
+    if (!status.has_users || !signedIn) return 'account';
+    if (!status.has_github_app) return 'github';
+    if (!status.has_tunnel) return 'tunnel';
+    return 'done';
+  }, [override, status, signedIn]);
+
+  const completeMutation = useMutation({
+    mutationFn: completeSetup,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['setup-status'] });
+      navigate('/projects', { replace: true });
+    },
+  });
+
+  if (statusQuery.isLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-[var(--bg-primary)]">
+        <Loader2 size={22} className="animate-spin text-[var(--accent-primary)]" />
+      </div>
+    );
+  }
+
+  // Wizard is optional once the instance is already configured.
+  if (status && !status.needs_setup && !override) {
+    return <Navigate to="/projects" replace />;
+  }
+
+  const steps: { key: Step; label: string }[] = [
+    { key: 'account', label: 'Admin account' },
+    { key: 'github', label: 'Git provider' },
+    { key: 'tunnel', label: 'Public access' },
+    { key: 'done', label: 'Done' },
+  ];
+  const activeIdx = steps.findIndex((s) => s.key === step);
+
+  return (
+    <div className="min-h-screen bg-[var(--bg-primary)] flex flex-col items-center px-5 py-16">
+      <div className="w-full max-w-lg">
+        <div className="flex items-center gap-2 mb-8">
+          {steps.map((s, i) => (
+            <div key={s.key} className="flex items-center gap-2">
+              <div
+                className={`w-6 h-6 rounded-full flex items-center justify-center text-[11px] font-semibold border ${
+                  i < activeIdx
+                    ? 'bg-[var(--accent-primary)] border-[var(--accent-primary)] text-[var(--accent-on)]'
+                    : i === activeIdx
+                      ? 'border-[var(--accent-primary)] text-[var(--accent-primary)]'
+                      : 'border-[var(--border-subtle)] text-[var(--text-muted)]'
+                }`}
+              >
+                {i < activeIdx ? <Check size={12} /> : i + 1}
+              </div>
+              <span
+                className={`text-xs ${i === activeIdx ? 'text-[var(--text-primary)] font-medium' : 'text-[var(--text-muted)]'}`}
+              >
+                {s.label}
+              </span>
+              {i < steps.length - 1 ? <div className="w-6 h-px bg-[var(--border-subtle)]" /> : null}
+            </div>
+          ))}
+        </div>
+
+        {step === 'account' ? (
+          <section className="panel p-6">
+            <h1 className="text-xl font-bold text-[var(--text-primary)]">Welcome to Containr</h1>
+            <p className="mt-2 text-sm text-[var(--text-secondary)]">
+              First boot detected. Create the admin account — registration closes to the public
+              right after, so this account owns the instance.
+            </p>
+            {status?.has_users && !signedIn ? (
+              <div className="mt-4">
+                <p className="text-sm text-[var(--text-secondary)]">
+                  An account already exists — sign in to continue setup.
+                </p>
+                <Link
+                  to="/auth/sign-in?redirect=/setup"
+                  className="mt-4 inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)]"
+                  style={{ background: 'var(--accent-primary)' }}
+                >
+                  Sign in <ChevronRight size={14} />
+                </Link>
+              </div>
+            ) : !status?.has_users ? (
+              <Link
+                to="/auth/sign-up?redirect=/setup"
+                className="mt-4 inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)]"
+                style={{ background: 'var(--accent-primary)' }}
+              >
+                Create admin account <ChevronRight size={14} />
+              </Link>
+            ) : null}
+          </section>
+        ) : null}
+
+        {step === 'github' ? <GitHubStep onNext={() => setOverride('tunnel')} /> : null}
+        {step === 'tunnel' ? <TunnelStep onNext={() => setOverride('done')} /> : null}
+
+        {step === 'done' ? (
+          <section className="panel p-6 text-center">
+            <Rocket size={28} className="mx-auto text-[var(--accent-primary)]" />
+            <h1 className="mt-4 text-xl font-bold text-[var(--text-primary)]">All set</h1>
+            <p className="mt-2 text-sm text-[var(--text-secondary)]">
+              Deploy your first service from a git repo, an image, or a template — the dashboard is
+              ready.
+            </p>
+            {completeMutation.isError ? (
+              <p className="mt-3 text-xs text-[var(--error)]">
+                {completeMutation.error instanceof Error
+                  ? completeMutation.error.message
+                  : 'Failed to save setup state'}
+              </p>
+            ) : null}
+            <button
+              type="button"
+              onClick={() => completeMutation.mutate()}
+              disabled={completeMutation.isPending}
+              className="mt-5 inline-flex items-center gap-2 h-10 px-6 rounded-[var(--radius-md)] text-sm font-semibold text-[var(--accent-on)] disabled:opacity-50"
+              style={{ background: 'var(--accent-primary)' }}
+            >
+              {completeMutation.isPending ? (
+                <Loader2 size={14} className="animate-spin" />
+              ) : (
+                <ShieldCheck size={15} />
+              )}
+              Enter Containr
+            </button>
+          </section>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function GitHubStep({ onNext }: { onNext: () => void }) {
+  const queryClient = useQueryClient();
+  const provisionMutation = useMutation({
+    mutationFn: async () => {
+      const { url, manifest } = await createGitHubAppManifest({
+        base_url: window.location.origin,
+      });
+      sessionStorage.setItem(SETUP_RETURN_KEY, '1');
+      const form = document.createElement('form');
+      form.method = 'POST';
+      form.action = url;
+      const input = document.createElement('input');
+      input.type = 'hidden';
+      input.name = 'manifest';
+      input.value = manifest;
+      form.appendChild(input);
+      document.body.appendChild(form);
+      form.submit();
+    },
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['setup-status'] }),
+  });
+
+  return (
+    <section className="panel p-6">
+      <div className="flex items-center gap-3 mb-3">
+        <Github size={20} className="text-[var(--text-primary)]" />
+        <h1 className="text-xl font-bold text-[var(--text-primary)]">Connect a git provider</h1>
+      </div>
+      <p className="text-sm text-[var(--text-secondary)]">
+        Provision the instance GitHub App — repo push events then trigger deployments and preview
+        environments automatically. Self-hosted GitLab/Gitea can be added later in Settings.
+      </p>
+      {provisionMutation.isError ? (
+        <p className="mt-3 text-xs text-[var(--error)]">
+          {provisionMutation.error instanceof Error
+            ? provisionMutation.error.message
+            : 'Could not start GitHub App provisioning'}
+        </p>
+      ) : null}
+      <div className="mt-5 flex items-center gap-3">
+        <button
+          type="button"
+          onClick={() => provisionMutation.mutate()}
+          disabled={provisionMutation.isPending}
+          className="inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)] disabled:opacity-50"
+          style={{ background: 'var(--accent-primary)' }}
+        >
+          {provisionMutation.isPending ? <Loader2 size={14} className="animate-spin" /> : null}
+          Set up GitHub App
+        </button>
+        <button
+          type="button"
+          onClick={onNext}
+          className="h-9 px-4 rounded-[var(--radius-md)] border border-[var(--border-subtle)] text-sm text-[var(--text-secondary)] hover:text-[var(--text-primary)] transition-colors"
+        >
+          Skip for now
+        </button>
+      </div>
+    </section>
+  );
+}
+
+function TunnelStep({ onNext }: { onNext: () => void }) {
+  const queryClient = useQueryClient();
+  const [token, setToken] = useState('');
+  const saveMutation = useMutation({
+    mutationFn: () =>
+      updatePlatformSettings({ cloudflareTunnelToken: token.trim() || undefined }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['setup-status'] });
+      onNext();
+    },
+  });
+
+  return (
+    <section className="panel p-6">
+      <h1 className="text-xl font-bold text-[var(--text-primary)]">Public access (optional)</h1>
+      <p className="mt-2 text-sm text-[var(--text-secondary)]">
+        Paste a Cloudflare Tunnel token to expose this instance on the internet. Without one,
+        Containr stays reachable on this network — you can add it later in Settings.
+      </p>
+      <input
+        type="password"
+        value={token}
+        onChange={(e) => setToken(e.target.value)}
+        placeholder="eyJhIjo… tunnel token"
+        className="mt-4 w-full h-10 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] text-sm text-[var(--text-primary)] placeholder:text-[var(--text-muted)] focus:border-[var(--accent-primary)] transition-colors"
+      />
+      {saveMutation.isError ? (
+        <p className="mt-3 text-xs text-[var(--error)]">
+          {saveMutation.error instanceof Error ? saveMutation.error.message : 'Failed to save token'}
+        </p>
+      ) : null}
+      <div className="mt-5 flex items-center gap-3">
+        <button
+          type="button"
+          onClick={() => (token.trim() ? saveMutation.mutate() : onNext())}
+          disabled={saveMutation.isPending}
+          className="inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)] disabled:opacity-50"
+          style={{ background: 'var(--accent-primary)' }}
+        >
+          {saveMutation.isPending ? <Loader2 size={14} className="animate-spin" /> : null}
+          {token.trim() ? 'Save tunnel token' : 'Continue'}
+        </button>
+        <button
+          type="button"
+          onClick={onNext}
+          className="h-9 px-4 rounded-[var(--radius-md)] border border-[var(--border-subtle)] text-sm text-[var(--text-secondary)] hover:text-[var(--text-primary)] transition-colors"
+        >
+          Skip
+        </button>
+      </div>
+    </section>
+  );
+}

app/frontend/src/features/templates/builder/TemplateBuilder.tsx

@@ -0,0 +1,467 @@
+import { useCallback, useMemo, useState } from 'react';
+import {
+  Background,
+  BackgroundVariant,
+  Handle,
+  MarkerType,
+  Position,
+  ReactFlow,
+  ReactFlowProvider,
+  useReactFlow,
+  type Connection,
+  type Edge,
+  type EdgeChange,
+  type Node,
+  type NodeChange,
+  type NodeProps,
+} from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+import { Database, GitBranch, Package, Timer, Trash2, X } from 'lucide-react';
+import {
+  canvasFromConfig,
+  configFromCanvas,
+  newServiceKey,
+  validateGraph,
+  type BuilderNode,
+  type BuilderService,
+  type BuilderServiceType,
+} from './builder-model';
+
+type ServiceBuilderNode = Node<{ svc: BuilderService }, 'tplService'>;
+
+const TYPE_META: Record<BuilderServiceType, { label: string; icon: typeof Package; cls: string }> = {
+  web: { label: 'Web', icon: Package, cls: 'text-[var(--accent-primary)]' },
+  worker: { label: 'Worker', icon: GitBranch, cls: 'text-[var(--info,#5eb3f6)]' },
+  cron: { label: 'Cron', icon: Timer, cls: 'text-[var(--warning)]' },
+  database: { label: 'Database', icon: Database, cls: 'text-[var(--success,#7bd88a)]' },
+};
+
+const DATABASE_ENGINES = ['postgresql', 'mysql', 'mariadb', 'mongodb', 'redis', 'dragonfly', 'clickhouse'];
+
+function ServiceBuilderNodeView({ data, selected }: NodeProps<ServiceBuilderNode>) {
+  const meta = TYPE_META[data.svc.type] ?? TYPE_META.web;
+  const Icon = meta.icon;
+  return (
+    <div
+      className={`relative w-[210px] rounded-[var(--radius-md)] border bg-[var(--bg-elevated)] px-3 py-2.5 shadow-sm transition-colors ${
+        selected ? 'border-[var(--accent-primary)]' : 'border-[var(--border-subtle)]'
+      }`}
+    >
+      <Handle type="target" position={Position.Left} className="!h-2.5 !w-2.5 !border-[var(--border-default)] !bg-[var(--bg-base)]" />
+      <Handle type="source" position={Position.Right} className="!h-2.5 !w-2.5 !border-[var(--border-default)] !bg-[var(--bg-base)]" />
+      <div className="flex items-center gap-2">
+        <Icon size={14} className={meta.cls} />
+        <span className="truncate text-[12.5px] font-semibold text-[var(--text-primary)]">
+          {data.svc.name || data.svc.key}
+        </span>
+      </div>
+      <div className="mt-1 flex items-center justify-between gap-2">
+        <span className="text-[10.5px] uppercase tracking-wide text-[var(--text-tertiary)]">{meta.label}</span>
+        <span className="mono max-w-[120px] truncate text-[10.5px] text-[var(--text-secondary)]">
+          {data.svc.runtime || data.svc.repo || '—'}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+const nodeTypes = { tplService: ServiceBuilderNodeView };
+
+// Edges run dependency → dependent: connecting A → B means "B depends_on A".
+export function TemplateBuilder(props: {
+  config: Record<string, unknown>;
+  onApply: (config: Record<string, unknown>) => void;
+  onCancel: () => void;
+}) {
+  return (
+    <ReactFlowProvider>
+      <BuilderInner {...props} />
+    </ReactFlowProvider>
+  );
+}
+
+function BuilderInner({
+  config,
+  onApply,
+  onCancel,
+}: {
+  config: Record<string, unknown>;
+  onApply: (config: Record<string, unknown>) => void;
+  onCancel: () => void;
+}) {
+  const { screenToFlowPosition } = useReactFlow();
+  const initial = useMemo(() => canvasFromConfig(config), [config]);
+  const [services, setServices] = useState<Map<string, BuilderService>>(
+    () => new Map(initial.map((n) => [n.key, { ...n.service }])),
+  );
+  const [positions, setPositions] = useState<Record<string, { x: number; y: number }>>(
+    () => Object.fromEntries(initial.map((n) => [n.key, n.position])),
+  );
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+
+  const flowNodes: ServiceBuilderNode[] = useMemo(
+    () =>
+      [...services.values()].map((svc) => ({
+        id: svc.key,
+        type: 'tplService' as const,
+        position: positions[svc.key] ?? { x: 0, y: 0 },
+        data: { svc },
+        selected: svc.key === selectedKey,
+      })),
+    [services, positions, selectedKey],
+  );
+
+  const flowEdges: Edge[] = useMemo(
+    () =>
+      [...services.values()].flatMap((svc) =>
+        (svc.depends_on ?? [])
+          .filter((dep) => services.has(dep))
+          .map((dep) => ({
+            id: `${dep}->${svc.key}`,
+            source: dep,
+            target: svc.key,
+            markerEnd: { type: MarkerType.ArrowClosed, width: 14, height: 14, color: 'rgba(180,227,74,0.55)' },
+            style: { stroke: 'rgba(180,227,74,0.42)', strokeWidth: 1.6 },
+            className: 'edge-premium',
+          })),
+      ),
+    [services],
+  );
+
+  const builderNodes: BuilderNode[] = useMemo(
+    () =>
+      [...services.values()].map((svc) => ({
+        key: svc.key,
+        service: svc,
+        position: positions[svc.key] ?? { x: 0, y: 0 },
+      })),
+    [services, positions],
+  );
+  const errors = useMemo(() => validateGraph(builderNodes), [builderNodes]);
+
+  const patchService = useCallback((key: string, patch: Partial<BuilderService>) => {
+    setServices((prev) => {
+      const svc = prev.get(key);
+      if (!svc) return prev;
+      const next = new Map(prev);
+      next.set(key, { ...svc, ...patch });
+      return next;
+    });
+  }, []);
+
+  const addService = useCallback((type: BuilderServiceType, position?: { x: number; y: number }) => {
+    setServices((prev) => {
+      const key = newServiceKey(type, new Set(prev.keys()));
+      const next = new Map(prev);
+      next.set(key, {
+        key,
+        type,
+        runtime: type === 'database' ? 'postgresql' : undefined,
+      });
+      setPositions((pos) => ({ ...pos, [key]: position ?? { x: 80, y: 40 + (next.size - 1) * 150 } }));
+      setSelectedKey(key);
+      return next;
+    });
+  }, []);
+
+  const removeService = useCallback((key: string) => {
+    setServices((prev) => {
+      const next = new Map(prev);
+      next.delete(key);
+      for (const svc of next.values()) {
+        svc.depends_on = svc.depends_on?.filter((d) => d !== key);
+      }
+      return next;
+    });
+    setPositions((prev) => {
+      const next = { ...prev };
+      delete next[key];
+      return next;
+    });
+    setSelectedKey((cur) => (cur === key ? null : cur));
+  }, []);
+
+  const onConnect = useCallback(
+    (conn: Connection) => {
+      if (!conn.source || !conn.target || conn.source === conn.target) return;
+      const target = services.get(conn.target);
+      if (!target) return;
+      patchService(conn.target, {
+        depends_on: [...new Set([...(target.depends_on ?? []), conn.source])],
+      });
+    },
+    [patchService, services],
+  );
+
+  const onNodesChange = useCallback(
+    (changes: NodeChange<ServiceBuilderNode>[]) => {
+      for (const ch of changes) {
+        if (ch.type === 'position' && ch.position) {
+          setPositions((prev) => ({ ...prev, [ch.id]: ch.position! }));
+        } else if (ch.type === 'remove') {
+          removeService(ch.id);
+        } else if (ch.type === 'select') {
+          if (ch.selected) setSelectedKey(ch.id);
+        }
+      }
+    },
+    [removeService],
+  );
+
+  const onEdgesChange = useCallback(
+    (changes: EdgeChange<Edge>[]) => {
+      for (const ch of changes) {
+        if (ch.type !== 'remove') continue;
+        const edge = flowEdges.find((e) => e.id === ch.id);
+        if (!edge) continue;
+        const svc = services.get(edge.target);
+        if (svc) {
+          patchService(edge.target, {
+            depends_on: (svc.depends_on ?? []).filter((d) => d !== edge.source),
+          });
+        }
+      }
+    },
+    [flowEdges, patchService, services],
+  );
+
+  const selected = selectedKey ? services.get(selectedKey) : null;
+
+  return (
+    <div className="flex min-h-0 flex-1">
+      <div className="relative flex-1">
+        <div className="absolute left-3 top-3 z-10 flex gap-1.5">
+          {(['web', 'database', 'cron', 'worker'] as const).map((t) => {
+            const meta = TYPE_META[t];
+            const Icon = meta.icon;
+            return (
+              <button
+                key={t}
+                type="button"
+                onClick={() => addService(t)}
+                className="canvas-pill inline-flex items-center gap-1.5 px-2.5 py-1.5 text-[11px] font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+              >
+                <Icon size={12} className={meta.cls} />
+                {meta.label}
+              </button>
+            );
+          })}
+        </div>
+        <ReactFlow
+          nodes={flowNodes}
+          edges={flowEdges}
+          nodeTypes={nodeTypes}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+          onConnect={onConnect}
+          onPaneClick={() => setSelectedKey(null)}
+          onDoubleClick={(e) => {
+            if ((e.target as HTMLElement).closest('.react-flow__node')) return;
+            addService('web', screenToFlowPosition({ x: e.clientX, y: e.clientY }));
+          }}
+          fitView
+          deleteKeyCode={['Backspace', 'Delete']}
+          proOptions={{ hideAttribution: true }}
+        >
+          <Background variant={BackgroundVariant.Dots} gap={22} size={1.2} color="rgba(255,255,255,0.07)" />
+        </ReactFlow>
+        <div className="canvas-pill absolute bottom-3 left-3 z-10 px-3 py-1.5 text-[10.5px] text-[var(--text-tertiary)]">
+          drag = move · connect handles = depends_on · double-click = add web · Del = remove
+        </div>
+      </div>
+
+      <div className="flex w-[290px] shrink-0 flex-col border-l border-[var(--border-subtle)]">
+        {selected ? (
+          <Inspector
+            key={selected.key}
+            svc={selected}
+            onPatch={(patch) => patchService(selected.key, patch)}
+            onRemove={() => removeService(selected.key)}
+          />
+        ) : (
+          <div className="flex flex-1 flex-col items-center justify-center gap-2 px-6 text-center">
+            <Package size={22} className="text-[var(--text-tertiary)]" />
+            <p className="text-xs text-[var(--text-tertiary)]">
+              Select a node to edit it, or add one from the toolbar.
+            </p>
+          </div>
+        )}
+        <div className="border-t border-[var(--border-subtle)] p-3">
+          {errors.length > 0 ? (
+            <div className="mb-2 max-h-[90px] overflow-y-auto rounded-[var(--radius-sm)] bg-[var(--error-soft)] px-3 py-2">
+              {errors.map((e) => (
+                <p key={e} className="text-[11px] text-[var(--error)]">• {e}</p>
+              ))}
+            </div>
+          ) : null}
+          <div className="flex gap-2">
+            <button
+              type="button"
+              onClick={onCancel}
+              className="flex-1 rounded-[var(--radius-md)] px-3 py-2 text-xs font-medium text-[var(--text-secondary)] hover:bg-[var(--surface-muted)]"
+            >
+              Back to JSON
+            </button>
+            <button
+              type="button"
+              disabled={errors.length > 0 || services.size === 0}
+              onClick={() => onApply(configFromCanvas(builderNodes, config))}
+              className="flex-1 rounded-[var(--radius-md)] bg-[var(--accent-primary)] px-3 py-2 text-xs font-semibold text-[var(--accent-on)] disabled:opacity-50"
+            >
+              Apply to JSON
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const FIELD_CLS =
+  'w-full rounded-[var(--radius-sm)] border border-[var(--border-default)] bg-[var(--bg-void)] px-2.5 py-1.5 text-[12px] text-[var(--text-primary)] outline-none focus:border-[var(--accent-primary)]';
+const LABEL_CLS = 'mb-1 block text-[10.5px] font-medium uppercase tracking-wide text-[var(--text-tertiary)]';
+
+function Inspector({
+  svc,
+  onPatch,
+  onRemove,
+}: {
+  svc: BuilderService;
+  onPatch: (patch: Partial<BuilderService>) => void;
+  onRemove: () => void;
+}) {
+  const envText = Object.entries(svc.environment ?? {})
+    .map(([k, v]) => `${k}=${v}`)
+    .join('\n');
+  const volText = (svc.volumes ?? []).map((v) => `${v.source}:${v.target}${v.read_only ? ':ro' : ''}`).join('\n');
+  return (
+    <div className="flex-1 overflow-y-auto p-4">
+      <div className="mb-3 flex items-center justify-between">
+        <span className="text-[12px] font-semibold text-[var(--text-primary)]">{svc.key}</span>
+        <button
+          type="button"
+          onClick={onRemove}
+          className="flex items-center gap-1 rounded-[var(--radius-sm)] px-2 py-1 text-[11px] text-[var(--error)] hover:bg-[var(--error-soft)]"
+        >
+          <Trash2 size={12} /> Remove
+        </button>
+      </div>
+
+      <label className={LABEL_CLS}>Key</label>
+      <input className={FIELD_CLS} value={svc.key} disabled title="Key is the node id — cannot be renamed" />
+
+      <label className={`${LABEL_CLS} mt-3`}>Display name</label>
+      <input className={FIELD_CLS} value={svc.name ?? ''} onChange={(e) => onPatch({ name: e.target.value || undefined })} placeholder="optional" />
+
+      <label className={`${LABEL_CLS} mt-3`}>Type</label>
+      <select
+        className={FIELD_CLS}
+        value={svc.type}
+        onChange={(e) => onPatch({ type: e.target.value as BuilderServiceType })}
+      >
+        <option value="web">Web</option>
+        <option value="worker">Worker</option>
+        <option value="cron">Cron</option>
+        <option value="database">Database</option>
+      </select>
+
+      {svc.type === 'database' ? (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Engine</label>
+          <select className={FIELD_CLS} value={svc.runtime ?? 'postgresql'} onChange={(e) => onPatch({ runtime: e.target.value })}>
+            {DATABASE_ENGINES.map((eng) => (
+              <option key={eng} value={eng}>{eng}</option>
+            ))}
+          </select>
+        </>
+      ) : (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Image (runtime)</label>
+          <input className={FIELD_CLS} value={svc.runtime ?? ''} onChange={(e) => onPatch({ runtime: e.target.value || undefined })} placeholder="nginx:latest" />
+          <label className={`${LABEL_CLS} mt-3`}>Git repo</label>
+          <input className={FIELD_CLS} value={svc.repo ?? ''} onChange={(e) => onPatch({ repo: e.target.value || undefined })} placeholder="owner/repo or clone URL" />
+          {svc.repo ? (
+            <>
+              <label className={`${LABEL_CLS} mt-3`}>Branch</label>
+              <input className={FIELD_CLS} value={svc.branch ?? ''} onChange={(e) => onPatch({ branch: e.target.value || undefined })} placeholder="main" />
+              <label className={`${LABEL_CLS} mt-3`}>Build command</label>
+              <input className={FIELD_CLS} value={svc.build_command ?? ''} onChange={(e) => onPatch({ build_command: e.target.value || undefined })} />
+            </>
+          ) : null}
+          <label className={`${LABEL_CLS} mt-3`}>Start command</label>
+          <input className={FIELD_CLS} value={svc.start_command ?? ''} onChange={(e) => onPatch({ start_command: e.target.value || undefined })} />
+        </>
+      )}
+
+      {svc.type === 'web' ? (
+        <>
+          <label className={`${LABEL_CLS} mt-3`}>Port</label>
+          <input
+            className={FIELD_CLS}
+            type="number"
+            value={svc.port ?? ''}
+            onChange={(e) => onPatch({ port: e.target.value ? Number(e.target.value) : undefined })}
+          />
+          <label className={`${LABEL_CLS} mt-3`}>Health check path</label>
+          <input className={FIELD_CLS} value={svc.health_check ?? ''} onChange={(e) => onPatch({ health_check: e.target.value || undefined })} placeholder="/health" />
+        </>
+      ) : null}
+
+      <label className={`${LABEL_CLS} mt-3`}>Environment (KEY=value, one per line)</label>
+      <textarea
+        className={`${FIELD_CLS} mono min-h-[70px] resize-y`}
+        defaultValue={envText}
+        spellCheck={false}
+        onBlur={(e) => {
+          const env: Record<string, string> = {};
+          for (const line of e.target.value.split('\n')) {
+            const idx = line.indexOf('=');
+            if (idx > 0) env[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+          }
+          onPatch({ environment: Object.keys(env).length ? env : undefined });
+        }}
+        placeholder={'DATABASE_URL={{service.db.url}}\nSECRET={{secret}}'}
+      />
+
+      <label className={`${LABEL_CLS} mt-3`}>Volumes (source:target[:ro], one per line)</label>
+      <textarea
+        className={`${FIELD_CLS} mono min-h-[50px] resize-y`}
+        defaultValue={volText}
+        spellCheck={false}
+        onBlur={(e) => {
+          const vols = e.target.value
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .map((l) => {
+              const [source, target, ro] = l.split(':');
+              return { source, target, read_only: ro === 'ro' || undefined };
+            })
+            .filter((v) => v.source && v.target);
+          onPatch({ volumes: vols.length ? vols : undefined });
+        }}
+        placeholder={'data:/var/lib/app\n./config:/etc/app:ro'}
+      />
+
+      {(svc.depends_on ?? []).length > 0 ? (
+        <div className="mt-3">
+          <span className={LABEL_CLS}>Depends on</span>
+          <div className="flex flex-wrap gap-1">
+            {svc.depends_on!.map((dep) => (
+              <span key={dep} className="inline-flex items-center gap-1 rounded-full bg-[var(--surface-muted)] px-2 py-0.5 text-[11px] text-[var(--text-secondary)]">
+                {dep}
+                <button
+                  type="button"
+                  onClick={() => onPatch({ depends_on: (svc.depends_on ?? []).filter((d) => d !== dep) })}
+                  className="text-[var(--text-tertiary)] hover:text-[var(--error)]"
+                >
+                  <X size={10} />
+                </button>
+              </span>
+            ))}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

app/frontend/src/features/templates/builder/builder-model.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vitest';
+import {
+  canvasFromConfig,
+  configFromCanvas,
+  layoutPositions,
+  newServiceKey,
+  validateGraph,
+  type BuilderNode,
+} from './builder-model';
+
+const plausibleConfig = {
+  version: 2,
+  services: [
+    { key: 'db', type: 'database', runtime: 'postgresql', environment: { POSTGRES_DB: 'plausible' } },
+    { key: 'events', type: 'database', runtime: 'clickhouse' },
+    {
+      key: 'web',
+      name: 'plausible',
+      type: 'web',
+      runtime: 'ghcr.io/plausible/community-edition:v2',
+      port: 8000,
+      health_check: '/api/health',
+      depends_on: ['db', 'events'],
+      environment: { DATABASE_URL: '{{service.db.url}}' },
+    },
+  ],
+};
+
+describe('canvasFromConfig', () => {
+  it('parses graph services into nodes with auto-layout', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    expect(nodes.map((n) => n.key)).toEqual(['db', 'events', 'web']);
+    // databases are roots (depth 0), web depends on both (depth 1)
+    expect(nodes[0].position.x).toBeLessThan(nodes[2].position.x);
+    expect(nodes[1].position.y).toBeGreaterThan(nodes[0].position.y);
+  });
+
+  it('restores saved canvas positions', () => {
+    const nodes = canvasFromConfig({
+      ...plausibleConfig,
+      canvas: { positions: { db: { x: 500, y: 500 } } },
+    });
+    expect(nodes[0].position).toEqual({ x: 500, y: 500 });
+  });
+
+  it('migrates flat legacy configs to a single node', () => {
+    const nodes = canvasFromConfig({
+      type: 'web',
+      runtime: 'nginx:latest',
+      port: 80,
+      environment: { FOO: 'bar' },
+    });
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].service).toMatchObject({ key: 'app', type: 'web', runtime: 'nginx:latest', port: 80 });
+  });
+
+  it('drops entries without a key', () => {
+    const nodes = canvasFromConfig({ version: 2, services: [{ type: 'web', runtime: 'x' }, { key: 'ok', type: 'web', runtime: 'y' }] });
+    expect(nodes.map((n) => n.key)).toEqual(['ok']);
+  });
+});
+
+describe('configFromCanvas', () => {
+  it('round-trips a graph config', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    const config = configFromCanvas(nodes, plausibleConfig);
+    const services = config.services as Record<string, unknown>[];
+    expect(config.version).toBe(2);
+    expect(services).toHaveLength(3);
+    const web = services.find((s) => s.key === 'web')!;
+    expect(web.depends_on).toEqual(['db', 'events']);
+    expect(web.port).toBe(8000);
+    expect((web.environment as Record<string, string>).DATABASE_URL).toBe('{{service.db.url}}');
+  });
+
+  it('persists node positions under config.canvas', () => {
+    const nodes = canvasFromConfig(plausibleConfig);
+    nodes[0].position = { x: 321, y: 123 };
+    const config = configFromCanvas(nodes, {});
+    expect((config.canvas as { positions: Record<string, { x: number; y: number }> }).positions.db).toEqual({ x: 321, y: 123 });
+    // and parses back to the same spot
+    expect(canvasFromConfig(config)[0].position).toEqual({ x: 321, y: 123 });
+  });
+
+  it('strips flat fields when converting a legacy config', () => {
+    const nodes = canvasFromConfig({ type: 'web', runtime: 'nginx:latest', port: 80 });
+    const config = configFromCanvas(nodes, { type: 'web', runtime: 'nginx:latest', port: 80 });
+    expect(config.type).toBeUndefined();
+    expect(config.runtime).toBeUndefined();
+    expect((config.services as unknown[]).length).toBe(1);
+  });
+});
+
+describe('layoutPositions', () => {
+  it('depths follow the depends_on chain', () => {
+    const pos = layoutPositions([
+      { key: 'a', type: 'database', runtime: 'postgresql' },
+      { key: 'b', type: 'web', runtime: 'img', depends_on: ['a'] },
+      { key: 'c', type: 'web', runtime: 'img', depends_on: ['b'] },
+    ]);
+    expect(pos.a.x).toBeLessThan(pos.b.x);
+    expect(pos.b.x).toBeLessThan(pos.c.x);
+  });
+
+  it('a dependency cycle does not hang', () => {
+    const pos = layoutPositions([
+      { key: 'a', type: 'web', runtime: 'x', depends_on: ['b'] },
+      { key: 'b', type: 'web', runtime: 'x', depends_on: ['a'] },
+    ]);
+    expect(pos.a).toBeDefined();
+    expect(pos.b).toBeDefined();
+  });
+});
+
+describe('validateGraph', () => {
+  const node = (key: string, extra: Partial<BuilderNode['service']> = {}): BuilderNode => ({
+    key,
+    position: { x: 0, y: 0 },
+    service: { key, type: 'web', runtime: 'img:1', ...extra },
+  });
+
+  it('accepts a valid graph', () => {
+    expect(validateGraph([node('db', { type: 'database', runtime: 'postgresql' }), node('web', { depends_on: ['db'] })])).toEqual([]);
+  });
+
+  it('rejects duplicate keys', () => {
+    expect(validateGraph([node('a'), node('a')])).toContain('duplicate key "a"');
+  });
+
+  it('rejects bad keys and self-deps', () => {
+    const errs = validateGraph([node('BAD KEY'), node('x', { depends_on: ['x'] })]);
+    expect(errs.some((e) => e.includes('not a valid key'))).toBe(true);
+    expect(errs).toContain('"x" depends on itself');
+  });
+
+  it('rejects deps on missing services', () => {
+    expect(validateGraph([node('web', { depends_on: ['ghost'] })])).toContain(
+      '"web" depends on unknown service "ghost"',
+    );
+  });
+
+  it('rejects database without engine and web without source', () => {
+    const errs = validateGraph([node('db', { type: 'database', runtime: undefined }), node('web', { runtime: undefined })]);
+    expect(errs).toContain('"db" is a database with no engine selected');
+    expect(errs).toContain('"web" needs an image (runtime) or a git repo');
+  });
+
+  it('reports dependency cycles', () => {
+    const errs = validateGraph([node('a', { depends_on: ['b'] }), node('b', { depends_on: ['a'] })]);
+    expect(errs.some((e) => e.startsWith('dependency cycle'))).toBe(true);
+  });
+});
+
+describe('newServiceKey', () => {
+  it('picks unused keys', () => {
+    expect(newServiceKey('database', new Set())).toBe('db');
+    expect(newServiceKey('database', new Set(['db']))).toBe('db2');
+    expect(newServiceKey('web', new Set(['web', 'web2']))).toBe('web3');
+  });
+});

app/frontend/src/features/templates/builder/builder-model.ts

@@ -0,0 +1,241 @@
+// Pure model for the visual template builder: converts between the
+// template `config` JSON (version 2 service graph, or a legacy flat
+// single-service config) and canvas state (nodes + positions), and
+// validates the graph before save. No React, no DOM — directly testable.
+
+export type BuilderServiceType = 'web' | 'worker' | 'cron' | 'database';
+
+export type BuilderService = {
+  key: string;
+  name?: string;
+  type: BuilderServiceType;
+  runtime?: string;
+  repo?: string;
+  branch?: string;
+  build_command?: string;
+  start_command?: string;
+  port?: number;
+  health_check?: string;
+  builder?: string;
+  environment?: Record<string, string>;
+  volumes?: { type?: string; source: string; target: string; read_only?: boolean }[];
+  depends_on?: string[];
+};
+
+export type BuilderCanvas = {
+  positions: Record<string, { x: number; y: number }>;
+};
+
+export type BuilderNode = {
+  key: string;
+  service: BuilderService;
+  position: { x: number; y: number };
+};
+
+const KEY_RE = /^[a-z][a-z0-9_-]*$/;
+const COL_X = 60;
+const ROW_Y = 200;
+
+function asService(raw: unknown): BuilderService | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const s = raw as Record<string, unknown>;
+  const key = typeof s.key === 'string' ? s.key : '';
+  if (!key) return null;
+  const type = typeof s.type === 'string' ? s.type : 'web';
+  return {
+    key,
+    name: typeof s.name === 'string' ? s.name : undefined,
+    type: (['web', 'worker', 'cron', 'database'] as const).includes(type as BuilderServiceType)
+      ? (type as BuilderServiceType)
+      : 'web',
+    runtime: typeof s.runtime === 'string' ? s.runtime : undefined,
+    repo: typeof s.repo === 'string' ? s.repo : undefined,
+    branch: typeof s.branch === 'string' ? s.branch : undefined,
+    build_command: typeof s.build_command === 'string' ? s.build_command : undefined,
+    start_command: typeof s.start_command === 'string' ? s.start_command : undefined,
+    port: typeof s.port === 'number' ? s.port : undefined,
+    health_check: typeof s.health_check === 'string' ? s.health_check : undefined,
+    builder: typeof s.builder === 'string' ? s.builder : undefined,
+    environment:
+      s.environment && typeof s.environment === 'object' && !Array.isArray(s.environment)
+        ? Object.fromEntries(
+            Object.entries(s.environment as Record<string, unknown>).map(([k, v]) => [k, String(v)]),
+          )
+        : undefined,
+    volumes: Array.isArray(s.volumes)
+      ? (s.volumes
+          .map((v) => {
+            if (!v || typeof v !== 'object') return null;
+            const vol = v as Record<string, unknown>;
+            if (typeof vol.target !== 'string' || !vol.target) return null;
+            return {
+              type: typeof vol.type === 'string' ? vol.type : undefined,
+              source: typeof vol.source === 'string' ? vol.source : '',
+              target: vol.target,
+              read_only: typeof vol.read_only === 'boolean' ? vol.read_only : undefined,
+            };
+          })
+          .filter((v): v is NonNullable<typeof v> => v !== null)
+        )
+      : undefined,
+    depends_on: Array.isArray(s.depends_on)
+      ? s.depends_on.filter((d): d is string => typeof d === 'string')
+      : undefined,
+  };
+}
+
+// Flat legacy configs ({type, runtime, port, …} with no services array)
+// map to a single service node so the builder can edit them without
+// losing fields the round-trip would drop.
+function flatToService(config: Record<string, unknown>): BuilderService | null {
+  const type = typeof config.type === 'string' ? config.type : '';
+  const runtime = typeof config.runtime === 'string' ? config.runtime : '';
+  if (!type && !runtime) return null;
+  const svc = asService({
+    key: 'app',
+    type: type || 'web',
+    runtime,
+    port: config.port,
+    health_check: config.health_check,
+    build_command: config.build_command,
+    start_command: config.start_command,
+    environment: config.environment,
+  });
+  return svc;
+}
+
+// Layered auto-layout: depth = longest depends_on chain; column per
+// depth, row per member. Deterministic so tests can assert positions.
+export function layoutPositions(services: BuilderService[]): Record<string, { x: number; y: number }> {
+  const depth = new Map<string, number>();
+  const visiting = new Set<string>();
+  const byKey = new Map(services.map((s) => [s.key, s]));
+  const depthOf = (key: string): number => {
+    const memo = depth.get(key);
+    if (memo !== undefined) return memo;
+    if (visiting.has(key)) return 0; // cycle guard
+    visiting.add(key);
+    const deps = byKey.get(key)?.depends_on ?? [];
+    let d = 0;
+    for (const dep of deps) {
+      if (byKey.has(dep)) d = Math.max(d, depthOf(dep) + 1);
+    }
+    visiting.delete(key);
+    depth.set(key, d);
+    return d;
+  };
+  const rows = new Map<number, number>();
+  const positions: Record<string, { x: number; y: number }> = {};
+  for (const svc of services) {
+    const d = depthOf(svc.key);
+    const row = rows.get(d) ?? 0;
+    rows.set(d, row + 1);
+    positions[svc.key] = { x: COL_X + d * 300, y: 40 + row * ROW_Y };
+  }
+  return positions;
+}
+
+export function canvasFromConfig(config: Record<string, unknown>): BuilderNode[] {
+  const canvas = (config.canvas ?? {}) as Partial<BuilderCanvas>;
+  const saved = canvas.positions ?? {};
+  const rawServices = Array.isArray(config.services) ? config.services : null;
+  const services = rawServices
+    ? rawServices.map(asService).filter((s): s is BuilderService => s !== null)
+    : [];
+  if (services.length === 0) {
+    const flat = flatToService(config);
+    if (flat) services.push(flat);
+  }
+  const auto = layoutPositions(services);
+  return services.map((service) => ({
+    key: service.key,
+    service,
+    position: saved[service.key] ?? auto[service.key] ?? { x: COL_X, y: 40 },
+  }));
+}
+
+export function configFromCanvas(
+  nodes: BuilderNode[],
+  rest: Record<string, unknown>,
+): Record<string, unknown> {
+  const services = nodes.map((node) => {
+    const svc = node.service;
+    const out: Record<string, unknown> = { key: svc.key, type: svc.type };
+    if (svc.name) out.name = svc.name;
+    if (svc.runtime) out.runtime = svc.runtime;
+    if (svc.repo) out.repo = svc.repo;
+    if (svc.branch) out.branch = svc.branch;
+    if (svc.build_command) out.build_command = svc.build_command;
+    if (svc.builder) out.builder = svc.builder;
+    if (svc.start_command) out.start_command = svc.start_command;
+    if (svc.port) out.port = svc.port;
+    if (svc.health_check) out.health_check = svc.health_check;
+    if (svc.environment && Object.keys(svc.environment).length > 0) out.environment = svc.environment;
+    if (svc.volumes && svc.volumes.length > 0) out.volumes = svc.volumes;
+    if (svc.depends_on && svc.depends_on.length > 0) out.depends_on = svc.depends_on;
+    return out;
+  });
+  const positions: Record<string, { x: number; y: number }> = {};
+  for (const node of nodes) positions[node.key] = node.position;
+  const restConfig = { ...rest };
+  // Flat (v1) fields and stale graph keys are dropped — the graph wins.
+  for (const k of ['type', 'runtime', 'build_command', 'start_command', 'port', 'health_check', 'environment', 'dockerfile', 'nixpacks_config', 'services', 'canvas']) {
+    delete restConfig[k];
+  }
+  return {
+    version: 2,
+    ...restConfig,
+    services,
+    canvas: { positions },
+  };
+}
+
+export function validateGraph(nodes: BuilderNode[]): string[] {
+  const errors: string[] = [];
+  const keys = new Set<string>();
+  for (const node of nodes) {
+    if (!KEY_RE.test(node.service.key)) {
+      errors.push(`"${node.service.key || '(empty)'}" is not a valid key (lowercase, digits, - or _)`);
+    }
+    if (keys.has(node.service.key)) errors.push(`duplicate key "${node.service.key}"`);
+    keys.add(node.service.key);
+    if (node.service.type === 'database' && !node.service.runtime) {
+      errors.push(`"${node.service.key}" is a database with no engine selected`);
+    }
+    if (node.service.type !== 'database' && !node.service.runtime && !node.service.repo) {
+      errors.push(`"${node.service.key}" needs an image (runtime) or a git repo`);
+    }
+  }
+  for (const node of nodes) {
+    for (const dep of node.service.depends_on ?? []) {
+      if (dep === node.service.key) errors.push(`"${dep}" depends on itself`);
+      else if (!keys.has(dep)) errors.push(`"${node.service.key}" depends on unknown service "${dep}"`);
+    }
+  }
+  // Cycle detection — a cycle makes topo sort fail at deploy time.
+  const state = new Map<string, 0 | 1 | 2>();
+  const byKey = new Map(nodes.map((n) => [n.service.key, n]));
+  const visit = (key: string, trail: string[]): void => {
+    const s = state.get(key) ?? 0;
+    if (s === 2) return;
+    if (s === 1) {
+      errors.push(`dependency cycle: ${[...trail, key].join(' → ')}`);
+      return;
+    }
+    state.set(key, 1);
+    for (const dep of byKey.get(key)?.service.depends_on ?? []) {
+      if (byKey.has(dep)) visit(dep, [...trail, key]);
+    }
+    state.set(key, 2);
+  };
+  for (const node of nodes) visit(node.service.key, []);
+  return errors;
+}
+
+export function newServiceKey(type: BuilderServiceType, existing: Set<string>): string {
+  const base = type === 'database' ? 'db' : type;
+  if (!existing.has(base)) return base;
+  let i = 2;
+  while (existing.has(`${base}${i}`)) i += 1;
+  return `${base}${i}`;
+}

app/frontend/src/features/templates/pages/TemplatesPage.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react';
+import { lazy, Suspense, useMemo, useState } from 'react';
 import { Link, useSearchParams } from 'react-router-dom';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import {
@@ -42,6 +42,10 @@ import {
   Network,
 } from 'lucide-react';
 
+const TemplateBuilder = lazy(() =>
+  import('@/features/templates/builder/TemplateBuilder').then((m) => ({ default: m.TemplateBuilder })),
+);
+
 function toServiceName(value: string): string {
   const normalized = value
     .toLowerCase()
@@ -127,6 +131,7 @@ export function TemplatesPage() {
   const isAdmin = Boolean(profileQuery.data?.isAdmin);
 
   const [editorOpen, setEditorOpen] = useState(false);
+  const [editorMode, setEditorMode] = useState<'json' | 'visual'>('json');
   const [editorJson, setEditorJson] = useState(EMPTY_TEMPLATE_JSON);
   const [editingTemplate, setEditingTemplate] = useState<TemplateEntity | null>(null);
   const [editorIsPublic, setEditorIsPublic] = useState(false);
@@ -1022,17 +1027,50 @@ export function TemplatesPage() {
       {/* Template editor — JSON only */}
       {editorOpen ? (
         <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4 backdrop-blur-sm">
-          <div className="flex max-h-[90vh] w-full max-w-2xl flex-col overflow-hidden rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--bg-base)] shadow-2xl">
+          <div className={`flex max-h-[92vh] w-full flex-col overflow-hidden rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--bg-base)] shadow-2xl ${editorMode === 'visual' ? 'max-w-6xl' : 'max-w-2xl'}`}>
             <div className="flex items-center justify-between border-b border-[var(--border-subtle)] px-5 py-4">
               <div>
                 <h2 className="text-[15px] font-semibold text-[var(--text-primary)]">
                   {editingTemplate ? `Edit ${editingTemplate.name}` : 'New template'}
                 </h2>
                 <p className="text-xs text-[var(--text-tertiary)]">
-                  JSON definition — name, category, config and variables.
+                  {editorMode === 'visual'
+                    ? 'Visual builder — drop service nodes, wire depends_on edges, apply back to JSON.'
+                    : 'JSON definition — name, category, config and variables.'}
                 </p>
               </div>
               <div className="flex items-center gap-2">
+                <div className="mr-1 inline-flex overflow-hidden rounded-[var(--radius-md)] border border-[var(--border-default)]">
+                  {(['json', 'visual'] as const).map((mode) => (
+                    <button
+                      key={mode}
+                      type="button"
+                      onClick={() => {
+                        if (mode === 'visual' && editorMode === 'json') {
+                          try {
+                            const parsed = JSON.parse(editorJson);
+                            if (!parsed || typeof parsed.config !== 'object') {
+                              setEditorError('Visual mode needs a valid JSON body with a "config" object first.');
+                              return;
+                            }
+                          } catch {
+                            setEditorError('Fix the JSON before switching to visual mode.');
+                            return;
+                          }
+                          setEditorError(null);
+                        }
+                        setEditorMode(mode);
+                      }}
+                      className={`px-3 py-1.5 text-[11px] font-medium capitalize ${
+                        editorMode === mode
+                          ? 'bg-[var(--surface-muted)] text-[var(--text-primary)]'
+                          : 'text-[var(--text-tertiary)] hover:text-[var(--text-primary)]'
+                      }`}
+                    >
+                      {mode}
+                    </button>
+                  ))}
+                </div>
                 <label className="inline-flex cursor-pointer items-center gap-1.5 rounded-[var(--radius-md)] border border-[var(--border-default)] px-3 py-1.5 text-xs font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]">
                   <Upload size={12} /> Upload .json
                   <input
@@ -1055,12 +1093,49 @@ export function TemplatesPage() {
                 </button>
               </div>
             </div>
-            <textarea
-              value={editorJson}
-              onChange={(e) => setEditorJson(e.target.value)}
-              spellCheck={false}
-              className="mono min-h-[380px] flex-1 resize-none bg-[var(--bg-void)] p-4 text-[12.5px] leading-relaxed text-[var(--text-secondary)] outline-none"
-            />
+            {editorMode === 'visual' ? (
+              <div className="flex min-h-[520px] flex-1 flex-col">
+                <Suspense
+                  fallback={
+                    <div className="flex flex-1 items-center justify-center text-[var(--text-tertiary)]">
+                      <Loader2 size={20} className="animate-spin" />
+                    </div>
+                  }
+                >
+                  {(() => {
+                    let cfg: Record<string, unknown> = {};
+                    try {
+                      const parsed = JSON.parse(editorJson) as { config?: Record<string, unknown> };
+                      cfg = parsed?.config ?? {};
+                    } catch {
+                      cfg = {};
+                    }
+                    return (
+                      <TemplateBuilder
+                        config={cfg}
+                        onCancel={() => setEditorMode('json')}
+                        onApply={(newConfig) => {
+                          try {
+                            const parsed = JSON.parse(editorJson) as Record<string, unknown>;
+                            setEditorJson(JSON.stringify({ ...parsed, config: newConfig }, null, 2));
+                          } catch {
+                            setEditorJson(JSON.stringify({ config: newConfig }, null, 2));
+                          }
+                          setEditorMode('json');
+                        }}
+                      />
+                    );
+                  })()}
+                </Suspense>
+              </div>
+            ) : (
+              <textarea
+                value={editorJson}
+                onChange={(e) => setEditorJson(e.target.value)}
+                spellCheck={false}
+                className="mono min-h-[380px] flex-1 resize-none bg-[var(--bg-void)] p-4 text-[12.5px] leading-relaxed text-[var(--text-secondary)] outline-none"
+              />
+            )}
             {composeWarnings.length > 0 ? (
               <div className="border-t border-[var(--border-subtle)] bg-[var(--warning-soft)]/60 px-5 py-2.5 text-xs text-[var(--warning)]">
                 <p className="font-medium mb-1">Compose import notes</p>
@@ -1074,7 +1149,7 @@ export function TemplatesPage() {
                 {editorError}
               </div>
             ) : null}
-            <div className="flex items-center justify-between border-t border-[var(--border-subtle)] px-5 py-3.5">
+            <div className={`flex items-center justify-between border-t border-[var(--border-subtle)] px-5 py-3.5 ${editorMode === 'visual' ? 'hidden' : ''}`}>
               <label className="inline-flex cursor-pointer items-center gap-2 text-[11px] text-[var(--text-secondary)]">
                 <input
                   type="checkbox"

app/frontend/src/features/workspace/canvas/ProjectCanvas.tsx

@@ -25,14 +25,22 @@ import {
 } from '@/lib/api-client';
 import { useToast } from '@/shared/hooks/use-toast';
 import { inferAutoConnections, type ServiceVariable } from '../auto-connections';
-import {
-  DEFAULT_VIEWPORT,
-  type CanvasGroup,
-  type CanvasNodeLayout,
-  type ProjectCanvasMetadata,
-} from '../model';
+import { DEFAULT_VIEWPORT, type ProjectCanvasMetadata } from '../model';
 import { hasCanvasMetadata, loadCanvasMetadata, saveCanvasMetadata } from '../storage';
 import { computeLayeredLayout, layoutFromVariables, NODE_HEIGHT, NODE_WIDTH } from './auto-layout';
+import {
+  buildMetadataFromFlow,
+  GROUP_DEFAULT_HEIGHT,
+  GROUP_DEFAULT_WIDTH,
+  GROUP_PAD_BOTTOM,
+  GROUP_PAD_TOP,
+  GROUP_PAD_X,
+  GRID_STEP,
+  groupSlot,
+  resolveFreeSpot,
+  type CanvasNode,
+  type Rect,
+} from './layout';
 import { GroupNode, ServiceNode, type GroupNodeData, type ServiceNodeData } from './nodes';
 import { ServiceInspector, type InspectorGroup } from './inspector';
 import { serviceAccent } from './service-visuals';
@@ -65,11 +73,7 @@ type CanvasProps = {
 
 type ServiceCanvasNode = Node<ServiceNodeData, 'serviceNode'>;
 type GroupCanvasNode = Node<GroupNodeData, 'groupNode'>;
-type CanvasNode = ServiceCanvasNode | GroupCanvasNode;
 type CanvasEdge = Edge<{ reasons: string[] }>;
-
-const GROUP_DEFAULT_WIDTH = 340;
-const GROUP_DEFAULT_HEIGHT = 230;
 const TRANSIENT_STATUSES = new Set(['building', 'deploying', 'pending', 'rolling_back']);
 
 const nodeTypes: NodeTypes = {
@@ -176,155 +180,6 @@ function toFlowEdges(
   });
 }
 
-const GROUP_PAD_X = 28;
-const GROUP_PAD_TOP = 56;
-const GROUP_PAD_BOTTOM = 24;
-const GROUP_ROW_GAP = 16;
-const GRID_STEP = 26;
-const NODE_GAP = 14;
-
-type Rect = { x: number; y: number; w: number; h: number };
-
-function rectsOverlap(a: Rect, b: Rect): boolean {
-  return (
-    a.x < b.x + b.w + NODE_GAP &&
-    a.x + a.w + NODE_GAP > b.x &&
-    a.y < b.y + b.h + NODE_GAP &&
-    a.y + a.h + NODE_GAP > b.y
-  );
-}
-
-// Nearest grid-aligned position where a node fits without touching any
-// occupied rect. Spiral-searches outward on the canvas lattice; falls back to
-// the given position when the neighbourhood is fully boxed in.
-function resolveFreeSpot(
-  desired: { x: number; y: number },
-  occupied: Rect[],
-  fallback: { x: number; y: number },
-  bounds?: Rect,
-): { x: number; y: number } {
-  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
-  const base = { x: snap(desired.x), y: snap(desired.y) };
-  const fits = (x: number, y: number) => {
-    if (bounds && (x < bounds.x || y < bounds.y || x + NODE_WIDTH > bounds.x + bounds.w || y + NODE_HEIGHT > bounds.y + bounds.h)) {
-      return false;
-    }
-    return !occupied.some((rect) => rectsOverlap({ x, y, w: NODE_WIDTH, h: NODE_HEIGHT }, rect));
-  };
-
-  if (fits(base.x, base.y)) {
-    return base;
-  }
-
-  for (let ring = 1; ring <= 12; ring++) {
-    for (let dx = -ring; dx <= ring; dx++) {
-      for (let dy = -ring; dy <= ring; dy++) {
-        if (Math.max(Math.abs(dx), Math.abs(dy)) !== ring) {
-          continue;
-        }
-        const x = base.x + dx * GRID_STEP;
-        const y = base.y + dy * GRID_STEP;
-        if (fits(x, y)) {
-          return { x, y };
-        }
-      }
-    }
-  }
-
-  return fallback;
-}
-
-// Where an incoming service lands inside a group frame. If the point already
-// fits inside the padded area, honour it. Otherwise append beneath the lowest
-// member and grow the frame just enough — keeps groups compact instead of
-// ballooning the frame to wherever the node used to sit.
-function groupSlot(
-  nodes: CanvasNode[],
-  groupId: string,
-  group: CanvasNode,
-  desiredX: number,
-  desiredY: number,
-  ignoreServiceId?: string,
-): { x: number; y: number; width: number; height: number } {
-  const width = typeof group.style?.width === 'number' ? group.style.width : GROUP_DEFAULT_WIDTH;
-  const height = typeof group.style?.height === 'number' ? group.style.height : GROUP_DEFAULT_HEIGHT;
-
-  const members = nodes.filter(
-    (node) => node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId,
-  );
-  const memberRects: Rect[] = members.map((node) => ({
-    x: node.position.x,
-    y: node.position.y,
-    w: NODE_WIDTH,
-    h: NODE_HEIGHT,
-  }));
-  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
-  const snappedX = snap(desiredX);
-  const snappedY = snap(desiredY);
-  const snappedFits =
-    snappedX >= GROUP_PAD_X &&
-    snappedY >= GROUP_PAD_TOP &&
-    snappedX + NODE_WIDTH <= width - GROUP_PAD_X &&
-    snappedY + NODE_HEIGHT <= height - GROUP_PAD_BOTTOM;
-  const collides = memberRects.some((rect) =>
-    rectsOverlap({ x: snappedX, y: snappedY, w: NODE_WIDTH, h: NODE_HEIGHT }, rect),
-  );
-
-  if (snappedFits && !collides) {
-    return { x: snappedX, y: snappedY, width, height };
-  }
-
-  let bottom = GROUP_PAD_TOP - GROUP_ROW_GAP;
-  for (const node of nodes) {
-    if (node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId) {
-      bottom = Math.max(bottom, node.position.y + NODE_HEIGHT);
-    }
-  }
-
-  const x = GROUP_PAD_X;
-  const y = bottom + GROUP_ROW_GAP;
-  return {
-    x,
-    y,
-    width: Math.max(width, x + NODE_WIDTH + GROUP_PAD_X),
-    height: Math.max(height, y + NODE_HEIGHT + GROUP_PAD_BOTTOM),
-  };
-}
-
-function buildMetadataFromFlow(nodes: CanvasNode[], viewport: { x: number; y: number; zoom: number }): ProjectCanvasMetadata {
-  const groups: CanvasGroup[] = [];
-  const layouts: CanvasNodeLayout[] = [];
-
-  for (const node of nodes) {
-    if (node.type === 'groupNode') {
-      const width = typeof node.style?.width === 'number' ? node.style.width : GROUP_DEFAULT_WIDTH;
-      const height = typeof node.style?.height === 'number' ? node.style.height : GROUP_DEFAULT_HEIGHT;
-      groups.push({
-        id: node.id,
-        title: node.data.title,
-        position: node.position,
-        width,
-        height,
-      });
-      continue;
-    }
-
-    if (node.type === 'serviceNode') {
-      layouts.push({
-        serviceId: node.id,
-        position: node.position,
-        groupId: node.parentId,
-      });
-    }
-  }
-
-  return {
-    groups,
-    nodes: layouts,
-    edges: [],
-    viewport,
-  };
-}
 
 function ZoomControls({ onTidy }: { onTidy: () => void }) {
   const { zoom } = useViewport();

app/frontend/src/features/workspace/canvas/canvas-layout.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildMetadataFromFlow,
+  groupSlot,
+  rectsOverlap,
+  resolveFreeSpot,
+} from './layout';
+import { NODE_HEIGHT, NODE_WIDTH } from './auto-layout';
+import type { GroupNodeType, ServiceNodeType } from './nodes';
+
+const GRID_STEP = 26;
+const NODE_GAP = 14;
+
+function serviceNode(
+  id: string,
+  position: { x: number; y: number },
+  parentId?: string,
+): ServiceNodeType {
+  return { id, type: 'serviceNode', position, parentId } as ServiceNodeType;
+}
+
+function groupNode(
+  id: string,
+  width = 340,
+  height = 230,
+): GroupNodeType {
+  return {
+    id,
+    type: 'groupNode',
+    position: { x: 0, y: 0 },
+    style: { width, height },
+    data: { title: `Group ${id}` },
+  } as GroupNodeType;
+}
+
+describe('rectsOverlap', () => {
+  const a = { x: 0, y: 0, w: 100, h: 100 };
+
+  it('detects intersection', () => {
+    expect(rectsOverlap(a, { x: 50, y: 50, w: 100, h: 100 })).toBe(true);
+    expect(rectsOverlap(a, { x: -50, y: -50, w: 100, h: 100 })).toBe(true);
+  });
+
+  it('returns false for fully disjoint rects', () => {
+    expect(rectsOverlap(a, { x: 500, y: 500, w: 100, h: 100 })).toBe(false);
+  });
+
+  it('treats the node gap as a collision zone', () => {
+    // b sits just inside NODE_GAP to the right of a.
+    expect(rectsOverlap(a, { x: 100 + NODE_GAP - 1, y: 0, w: 50, h: 50 })).toBe(true);
+    // Beyond the gap there is no overlap.
+    expect(rectsOverlap(a, { x: 100 + NODE_GAP + 1, y: 0, w: 50, h: 50 })).toBe(false);
+  });
+});
+
+describe('resolveFreeSpot', () => {
+  it('snaps the desired position to the grid when free', () => {
+    const spot = resolveFreeSpot({ x: 40, y: 70 }, [], { x: 0, y: 0 });
+    expect(spot).toEqual({ x: 52, y: 78 });
+    expect(spot.x % GRID_STEP).toBe(0);
+    expect(spot.y % GRID_STEP).toBe(0);
+  });
+
+  it('finds a neighbouring free grid point when occupied', () => {
+    const occupied = [{ x: 0, y: 0, w: NODE_WIDTH, h: NODE_HEIGHT }];
+    const spot = resolveFreeSpot({ x: 0, y: 0 }, occupied, { x: -1, y: -1 });
+    expect(spot).not.toEqual({ x: -1, y: -1 });
+    expect(Number.isInteger(spot.x / GRID_STEP)).toBe(true);
+    expect(Number.isInteger(spot.y / GRID_STEP)).toBe(true);
+    expect(
+      rectsOverlap({ x: spot.x, y: spot.y, w: NODE_WIDTH, h: NODE_HEIGHT }, occupied[0]),
+    ).toBe(false);
+  });
+
+  it('falls back when bounds reject every candidate', () => {
+    // Node is wider than the bounds, so nothing can fit.
+    const bounds = { x: 0, y: 0, w: 10, h: 10 };
+    const fallback = { x: 999, y: 888 };
+    expect(resolveFreeSpot({ x: 0, y: 0 }, [], fallback, bounds)).toEqual(fallback);
+  });
+});
+
+describe('groupSlot', () => {
+  it('honours a point that fits inside the padded frame', () => {
+    const group = groupNode('g1');
+    const slot = groupSlot([group], 'g1', group, 40, 70);
+    expect(slot).toEqual({ x: 52, y: 78, width: 340, height: 230 });
+  });
+
+  it('appends below the lowest member and grows the frame on collision', () => {
+    const group = groupNode('g1');
+    const member = serviceNode('s1', { x: 52, y: 78 }, 'g1');
+    const slot = groupSlot([group, member], 'g1', group, 40, 70);
+    // bottom = 78 + 104 = 182; y = 182 + 16 = 198; grows height to 326.
+    expect(slot.x).toBe(28);
+    expect(slot.y).toBe(198);
+    expect(slot.height).toBe(326);
+    expect(slot.width).toBe(340);
+  });
+
+  it('appends under the padding when the desired point is outside', () => {
+    const group = groupNode('g1');
+    const slot = groupSlot([group], 'g1', group, 5000, 5000);
+    expect(slot).toEqual({ x: 28, y: 56, width: 340, height: 230 });
+  });
+
+  it('ignores the dragged node when checking collisions', () => {
+    const group = groupNode('g1');
+    const dragged = serviceNode('s1', { x: 52, y: 78 }, 'g1');
+    const slot = groupSlot([group, dragged], 'g1', group, 40, 70, 's1');
+    expect(slot).toEqual({ x: 52, y: 78, width: 340, height: 230 });
+  });
+});
+
+describe('buildMetadataFromFlow', () => {
+  it('serializes groups and service layouts', () => {
+    const nodes = [
+      { ...groupNode('g1', 400, 300), position: { x: 10, y: 20 } },
+      serviceNode('s1', { x: 5, y: 6 }, 'g1'),
+      serviceNode('s2', { x: 100, y: 200 }),
+    ];
+    const viewport = { x: 1, y: 2, zoom: 0.5 };
+    const meta = buildMetadataFromFlow(nodes, viewport);
+
+    expect(meta.groups).toEqual([
+      { id: 'g1', title: 'Group g1', position: { x: 10, y: 20 }, width: 400, height: 300 },
+    ]);
+    expect(meta.nodes).toEqual([
+      { serviceId: 's1', position: { x: 5, y: 6 }, groupId: 'g1' },
+      { serviceId: 's2', position: { x: 100, y: 200 }, groupId: undefined },
+    ]);
+    expect(meta.edges).toEqual([]);
+    expect(meta.viewport).toEqual(viewport);
+  });
+
+  it('uses default group dimensions when style is missing', () => {
+    const bare = { id: 'g2', type: 'groupNode', position: { x: 0, y: 0 }, data: { title: 'bare' } } as GroupNodeType;
+    const meta = buildMetadataFromFlow([bare], { x: 0, y: 0, zoom: 1 });
+    expect(meta.groups[0].width).toBe(340);
+    expect(meta.groups[0].height).toBe(230);
+  });
+});

app/frontend/src/features/workspace/canvas/layout.ts

@@ -0,0 +1,156 @@
+import type { CanvasGroup, CanvasNodeLayout, ProjectCanvasMetadata } from '../model';
+import { NODE_HEIGHT, NODE_WIDTH } from './auto-layout';
+import type { GroupNodeType, ServiceNodeType } from './nodes';
+
+export type CanvasNode = ServiceNodeType | GroupNodeType;
+export type Rect = { x: number; y: number; w: number; h: number };
+
+export const GROUP_DEFAULT_WIDTH = 340;
+export const GROUP_DEFAULT_HEIGHT = 230;
+export const GROUP_PAD_X = 28;
+export const GROUP_PAD_TOP = 56;
+export const GROUP_PAD_BOTTOM = 24;
+export const GROUP_ROW_GAP = 16;
+export const GRID_STEP = 26;
+export const NODE_GAP = 14;
+
+export function rectsOverlap(a: Rect, b: Rect): boolean {
+  return (
+    a.x < b.x + b.w + NODE_GAP &&
+    a.x + a.w + NODE_GAP > b.x &&
+    a.y < b.y + b.h + NODE_GAP &&
+    a.y + a.h + NODE_GAP > b.y
+  );
+}
+
+// Nearest grid-aligned position where a node fits without touching any
+// occupied rect. Spiral-searches outward on the canvas lattice; falls back to
+// the given position when the neighbourhood is fully boxed in.
+export function resolveFreeSpot(
+  desired: { x: number; y: number },
+  occupied: Rect[],
+  fallback: { x: number; y: number },
+  bounds?: Rect,
+): { x: number; y: number } {
+  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
+  const base = { x: snap(desired.x), y: snap(desired.y) };
+  const fits = (x: number, y: number) => {
+    if (bounds && (x < bounds.x || y < bounds.y || x + NODE_WIDTH > bounds.x + bounds.w || y + NODE_HEIGHT > bounds.y + bounds.h)) {
+      return false;
+    }
+    return !occupied.some((rect) => rectsOverlap({ x, y, w: NODE_WIDTH, h: NODE_HEIGHT }, rect));
+  };
+
+  if (fits(base.x, base.y)) {
+    return base;
+  }
+
+  for (let ring = 1; ring <= 12; ring++) {
+    for (let dx = -ring; dx <= ring; dx++) {
+      for (let dy = -ring; dy <= ring; dy++) {
+        if (Math.max(Math.abs(dx), Math.abs(dy)) !== ring) {
+          continue;
+        }
+        const x = base.x + dx * GRID_STEP;
+        const y = base.y + dy * GRID_STEP;
+        if (fits(x, y)) {
+          return { x, y };
+        }
+      }
+    }
+  }
+
+  return fallback;
+}
+
+// Where an incoming service lands inside a group frame. If the point already
+// fits inside the padded area, honour it. Otherwise append beneath the lowest
+// member and grow the frame just enough — keeps groups compact instead of
+// ballooning the frame to wherever the node used to sit.
+export function groupSlot(
+  nodes: CanvasNode[],
+  groupId: string,
+  group: CanvasNode,
+  desiredX: number,
+  desiredY: number,
+  ignoreServiceId?: string,
+): { x: number; y: number; width: number; height: number } {
+  const width = typeof group.style?.width === 'number' ? group.style.width : GROUP_DEFAULT_WIDTH;
+  const height = typeof group.style?.height === 'number' ? group.style.height : GROUP_DEFAULT_HEIGHT;
+
+  const members = nodes.filter(
+    (node) => node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId,
+  );
+  const memberRects: Rect[] = members.map((node) => ({
+    x: node.position.x,
+    y: node.position.y,
+    w: NODE_WIDTH,
+    h: NODE_HEIGHT,
+  }));
+  const snap = (v: number) => Math.round(v / GRID_STEP) * GRID_STEP;
+  const snappedX = snap(desiredX);
+  const snappedY = snap(desiredY);
+  const snappedFits =
+    snappedX >= GROUP_PAD_X &&
+    snappedY >= GROUP_PAD_TOP &&
+    snappedX + NODE_WIDTH <= width - GROUP_PAD_X &&
+    snappedY + NODE_HEIGHT <= height - GROUP_PAD_BOTTOM;
+  const collides = memberRects.some((rect) =>
+    rectsOverlap({ x: snappedX, y: snappedY, w: NODE_WIDTH, h: NODE_HEIGHT }, rect),
+  );
+
+  if (snappedFits && !collides) {
+    return { x: snappedX, y: snappedY, width, height };
+  }
+
+  let bottom = GROUP_PAD_TOP - GROUP_ROW_GAP;
+  for (const node of nodes) {
+    if (node.type === 'serviceNode' && node.parentId === groupId && node.id !== ignoreServiceId) {
+      bottom = Math.max(bottom, node.position.y + NODE_HEIGHT);
+    }
+  }
+
+  const x = GROUP_PAD_X;
+  const y = bottom + GROUP_ROW_GAP;
+  return {
+    x,
+    y,
+    width: Math.max(width, x + NODE_WIDTH + GROUP_PAD_X),
+    height: Math.max(height, y + NODE_HEIGHT + GROUP_PAD_BOTTOM),
+  };
+}
+
+export function buildMetadataFromFlow(nodes: CanvasNode[], viewport: { x: number; y: number; zoom: number }): ProjectCanvasMetadata {
+  const groups: CanvasGroup[] = [];
+  const layouts: CanvasNodeLayout[] = [];
+
+  for (const node of nodes) {
+    if (node.type === 'groupNode') {
+      const width = typeof node.style?.width === 'number' ? node.style.width : GROUP_DEFAULT_WIDTH;
+      const height = typeof node.style?.height === 'number' ? node.style.height : GROUP_DEFAULT_HEIGHT;
+      groups.push({
+        id: node.id,
+        title: node.data.title,
+        position: node.position,
+        width,
+        height,
+      });
+      continue;
+    }
+
+    if (node.type === 'serviceNode') {
+      layouts.push({
+        serviceId: node.id,
+        position: node.position,
+        groupId: node.parentId,
+      });
+    }
+  }
+
+  return {
+    groups,
+    nodes: layouts,
+    edges: [],
+    viewport,
+  };
+}

app/frontend/src/generated/api-types.ts

@@ -5633,6 +5633,90 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/setup/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * First-run setup status
+         * @description Public. Drives the setup wizard — needs_setup is true until setup_completed is recorded. Instances with users and projects that predate the wizard report completed automatically.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Setup state */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            has_users?: boolean;
+                            setup_completed?: boolean;
+                            needs_setup?: boolean;
+                            /** @description GitHub App credentials configured (manifest flow or env) */
+                            has_github_app?: boolean;
+                            /** @description Cloudflare tunnel token configured */
+                            has_tunnel?: boolean;
+                            signup_enabled?: boolean;
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/setup/complete": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Mark the setup wizard complete */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Setup completed */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["MessageResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/settings": {
         parameters: {
             query?: never;

app/frontend/src/lib/api-client.ts

@@ -499,6 +499,23 @@ export async function pingServer(): Promise<void> {
   }
 }
 
+export type SetupStatus = {
+  has_users: boolean;
+  setup_completed: boolean;
+  needs_setup: boolean;
+  has_github_app: boolean;
+  has_tunnel: boolean;
+  signup_enabled: boolean;
+};
+
+export async function getSetupStatus(): Promise<SetupStatus> {
+  return requestJson<SetupStatus>('/setup/status');
+}
+
+export async function completeSetup(): Promise<void> {
+  await requestJson('/setup/complete', { method: 'POST', body: JSON.stringify({}) });
+}
+
 export function getAgentPublicBaseUrl(): string {
   return `${API_ROOT}/api/agents`;
 }

docs/api/openapi.yaml

@@ -3705,6 +3705,50 @@ paths:
                     type: boolean
                     description: True when the owner re-opened public registration in Settings
 
+  /setup/status:
+    get:
+      tags:
+        - Authentication
+      summary: First-run setup status
+      description: Public. Drives the setup wizard — needs_setup is true until setup_completed is recorded. Instances with users and projects that predate the wizard report completed automatically.
+      responses:
+        '200':
+          description: Setup state
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  has_users:
+                    type: boolean
+                  setup_completed:
+                    type: boolean
+                  needs_setup:
+                    type: boolean
+                  has_github_app:
+                    type: boolean
+                    description: GitHub App credentials configured (manifest flow or env)
+                  has_tunnel:
+                    type: boolean
+                    description: Cloudflare tunnel token configured
+                  signup_enabled:
+                    type: boolean
+
+  /setup/complete:
+    post:
+      tags:
+        - Authentication
+      summary: Mark the setup wizard complete
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Setup completed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+
   /settings:
     get:
       tags: