feat(templates): visual graph builder (#74)

Canvas mode in the template editor (lazy-loaded React Flow): service
nodes for web/worker/cron/database, connect handles to set depends_on,
per-node inspector (image/repo, engine, port, health check, env,
volumes), live validation (dup keys, missing deps, cycles, missing
source), and an Apply step that serializes back to the version-2 graph
config JSON.

- builder-model.ts is pure: config↔canvas round-trip, layered
  auto-layout, flat-legacy→single-node migration, validation —
  16 vitest cases cover all of it
- node positions persist under config.canvas (backend ignores unknown
  config keys, so no schema change)
- flat legacy templates open as a single node so nothing is lost on
  edit

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,
@@ -537,9 +540,18 @@ and wired refs, one click or one CLI call.
 - [ ] **sqlc port** — ~140 raw `database/sql` sites → `sqlc/queries/`.
 - [ ] **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/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/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: