[codex] Add private browser first-admin claim flow (#6755)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Fresh self-hosted deployments need an operator path before any
invite exists.
> - Umbrel installs are private LAN deployments, so a one-time browser
claim is appropriate only when the deployment is private and unclaimed.
> - Public deployments and installs with active invites must keep the
existing invite-only model so admin creation is not exposed broadly.
> - GitHub PR #2927 established the useful direction, but it needed to
be adapted onto current `master` rather than merged as-is.
> - This pull request adds that adapted private-only claim flow across
server, UI, docs, and regression coverage.
> - The benefit is that a fresh private Umbrel-style install can be
claimed from the browser without weakening public deployment access.

## What Changed

- Added a first-admin claim service and access route support for
one-time admin claim eligibility on private unclaimed deployments.
- Updated the bootstrap/access UI so eligible private installs show a
setup claim path, while public and invited deployments keep invite-first
behavior.
- Added a bootstrap-pending setup UX lab covering claim, invite, public,
and signed-in access states.
- Updated deployment and local development docs for authenticated
private/public behavior and the Umbrel-style claim path.
- Added server and UI regression tests for private claim, public
no-claim, active invite fallback, existing board/no-access flows, and
health exposure reporting.
- Stabilized PR handoff verification by serializing the aggregate server
Vitest workspace run, forcing `NODE_ENV=test`, and relaxing the
heartbeat batching test around legitimate recovery follow-up runs.

## Verification

- `pnpm -r typecheck`
- `pnpm build`
- `pnpm vitest --run
server/src/__tests__/heartbeat-comment-wake-batching.test.ts`
- `pnpm vitest --run
server/src/__tests__/health-dev-server-token.test.ts`
- `pnpm test:run`
- QA validation: PAP-10115 passed browser validation with screenshots
for private fresh install claim, active invite versus claim conflict,
public invite-only/claim-absent behavior, existing invite fallback, and
normal board/no-access flows.
- GitHub closeout: issue #2579 and PR #2927 were updated with the
accepted direction: adapt the implementation, do not direct-merge #2927
as-is.

## Risks

- The claim endpoint must remain private-only and one-time; a regression
here could expose admin creation on public deployments.
- Existing invite behavior must remain intact for public deployments and
installs that already have an active invite.
- The stable Vitest harness now serializes the aggregate server
workspace group; this is slower, but it avoids DB-backed suite
collisions under root workspace mode.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected - check the roadmap
first. See `CONTRIBUTING.md`.
>
> ROADMAP.md checked: this is a scoped deployment bootstrap/access fix
and does not duplicate a listed roadmap project.

## Model Used

- OpenAI GPT-5 Codex via Paperclip `codex_local` for product
engineering, implementation, and verification, with tool-enabled local
code execution. Paperclip QA browser validation was performed in
PAP-10115 by the assigned QA agent; exact adapter model metadata for
that QA run is not exposed in this PR context.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

doc/DEPLOYMENT-MODES.md

@@ -125,19 +125,50 @@ When running `authenticated` mode, if the only instance admin is `local-board`,
 
 This prevents lockout when a user migrates from long-running local trusted usage to authenticated mode.
 
-## 8. Current Code Reality (As Of 2026-02-23)
+## 8. First Admin Setup For Fresh Authenticated Installs
+
+Fresh authenticated installs start in `bootstrap_pending` until the first
+`instance_admin` exists.
+
+For `authenticated/private`, Paperclip supports a browser-first setup path:
+
+1. open the Paperclip URL from the private network or appliance UI
+2. sign in or create a Paperclip account
+3. choose `Claim this instance` on the setup screen
+
+That browser claim promotes the signed-in session user to the first instance
+admin and then falls through to normal onboarding. The endpoint is available
+only to real browser session actors in `authenticated/private`; unauthenticated
+requests, agent keys, board API keys, and local implicit board actors are
+rejected.
+
+The CLI fallback remains supported in all authenticated setup states:
+
+```sh
+pnpm paperclipai auth bootstrap-ceo
+```
+
+That command prints a one-time first-admin invite URL. Browser claim and
+bootstrap invite acceptance share the same first-admin transaction, so whichever
+path wins first makes later attempts return a conflict.
+
+For `authenticated/public`, browser first-admin claim is intentionally disabled.
+Public deployments must use the high-entropy bootstrap invite path unless a
+future public-hosted setup design explicitly changes this policy.
+
+## 9. Current Code Reality (As Of 2026-02-23)
 
 - runtime values are `local_trusted | authenticated`
 - `authenticated` uses Better Auth sessions and bootstrap invite flow
 - `local_trusted` ensures a real local Board user principal in `authUsers` with `instance_user_roles` admin access
 - company creation ensures creator membership in `company_memberships` so user assignment/access flows remain consistent
 
-## 9. Naming and Compatibility Policy
+## 10. Naming and Compatibility Policy
 
 - canonical naming is `local_trusted` and `authenticated` with `private/public` exposure
 - no long-term compatibility alias layer for discarded naming variants
 
-## 10. Relationship to Other Docs
+## 11. Relationship to Other Docs
 
 - implementation plan: `doc/plans/deployment-auth-mode-consolidation.md`
 - V1 contract: `doc/SPEC-implementation.md`

doc/DEVELOPING.md

@@ -72,6 +72,13 @@ pnpm dev --bind lan
 ```
 
 This runs dev as `authenticated/private` with a private-network bind preset.
+On a fresh authenticated/private instance, open the app, sign in or create an
+account, and use the setup screen to claim the first instance admin from the
+browser. The CLI fallback remains:
+
+```sh
+pnpm paperclipai auth bootstrap-ceo
+```
 
 For Tailscale-only reachability on a detected tailnet address:
 

doc/DOCKER.md

@@ -117,6 +117,16 @@ services:
 - bootstrap invite URL defaults
 - hostname allowlist defaults (hostname extracted from URL)
 
+For fresh `authenticated/private` Docker or appliance-style installs, the first
+admin can now be claimed entirely from the browser after sign-in. Open the
+Paperclip URL, sign in or create an account, then choose `Claim this instance`
+on the setup screen. This browser claim is disabled for `authenticated/public`;
+public deployments should run the high-entropy CLI invite fallback instead:
+
+```sh
+pnpm paperclipai auth bootstrap-ceo
+```
+
 Granular overrides remain available if needed (`PAPERCLIP_AUTH_PUBLIC_BASE_URL`, `BETTER_AUTH_URL`, `BETTER_AUTH_TRUSTED_ORIGINS`, `PAPERCLIP_ALLOWED_HOSTNAMES`).
 
 Set `PAPERCLIP_ALLOWED_HOSTNAMES` explicitly only when you need additional hostnames beyond the public URL host (for example Tailscale/LAN aliases or multiple private hostnames).

scripts/run-vitest-stable.mjs

@@ -55,6 +55,11 @@ const generalWorkspacesBGroupName = "general-workspaces-b";
 const generalWorkspacesAProjects = ["@paperclipai/ui", "paperclipai"];
 const generalWorkspacesBProjects = nonServerProjects.filter((project) => !generalWorkspacesAProjects.includes(project));
 const generalGroupNames = [generalServerGroupName, generalWorkspacesAGroupName, generalWorkspacesBGroupName];
+const serializedServerVitestArgs = [
+  "--no-file-parallelism",
+  "--maxWorkers=1",
+  "--minWorkers=1",
+];
 
 function walk(dir) {
   const entries = readdirSync(dir);
@@ -241,6 +246,7 @@ function runVitest(args, label) {
   // Keep per-run paths compact so Unix socket fixtures stay under macOS path limits.
   const env = {
     ...process.env,
+    NODE_ENV: "test",
     PAPERCLIP_HOME: path.join(testRoot, "h"),
     PAPERCLIP_INSTANCE_ID: `vt-${process.pid}-${invocationIndex}`,
     TMPDIR: path.join(testRoot, "t"),
@@ -277,7 +283,12 @@ function runGeneralGroup(routeTests, groupName) {
   if (groupName === generalServerGroupName) {
     const excludeRouteArgs = routeTests.flatMap((file) => ["--exclude", file.serverPath]);
     runVitest(
-      ["--project", "@paperclipai/server", ...excludeRouteArgs],
+      [
+        "--project",
+        "@paperclipai/server",
+        ...serializedServerVitestArgs,
+        ...excludeRouteArgs,
+      ],
       `${groupName} server suites excluding ${routeTests.length} serialized suites`,
     );
     return;

server/src/__tests__/bootstrap-claim-routes.test.ts

@@ -0,0 +1,231 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createHash } from "node:crypto";
+import { accessRoutes } from "../routes/access.js";
+import { boardMutationGuard } from "../middleware/board-mutation-guard.js";
+import { errorHandler } from "../middleware/index.js";
+
+const claimFirstInstanceAdminMock = vi.hoisted(() => vi.fn());
+const accessServiceMock = vi.hoisted(() => ({
+  isInstanceAdmin: vi.fn(),
+  canUser: vi.fn(),
+  hasPermission: vi.fn(),
+  ensureMembership: vi.fn(),
+  setPrincipalGrants: vi.fn(),
+}));
+
+vi.mock("../first-admin-claim.js", () => ({
+  claimFirstInstanceAdmin: claimFirstInstanceAdminMock,
+}));
+
+vi.mock("../services/index.js", () => ({
+  accessService: () => accessServiceMock,
+  agentService: () => ({
+    getById: vi.fn(),
+  }),
+  boardAuthService: () => ({
+    createCliAuthChallenge: vi.fn(),
+    resolveBoardAccess: vi.fn(),
+    assertCurrentBoardKey: vi.fn(),
+    revokeBoardApiKey: vi.fn(),
+  }),
+  deduplicateAgentName: vi.fn(),
+  logActivity: vi.fn(),
+  notifyHireApproved: vi.fn(),
+}));
+
+function hashToken(token: string) {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+function createDb(invite?: Record<string, unknown>) {
+  return {
+    select: vi.fn(() => ({
+      from: vi.fn(() => ({
+        where: vi.fn(() => Promise.resolve(invite ? [invite] : [])),
+      })),
+    })),
+  } as any;
+}
+
+function createApp(input: {
+  actor?: Record<string, unknown>;
+  deploymentMode?: "authenticated" | "local_trusted";
+  deploymentExposure?: "private" | "public";
+  guardMutations?: boolean;
+  db?: Record<string, unknown>;
+}) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = input.actor ?? {
+      type: "board",
+      source: "session",
+      userId: "user-1",
+    };
+    next();
+  });
+  if (input.guardMutations) {
+    app.use(boardMutationGuard());
+  }
+  app.use(
+    "/api",
+    accessRoutes(input.db as any ?? createDb(), {
+      deploymentMode: input.deploymentMode ?? "authenticated",
+      deploymentExposure: input.deploymentExposure ?? "private",
+      bindHost: "127.0.0.1",
+      allowedHostnames: [],
+    }),
+  );
+  app.use(errorHandler);
+  return app;
+}
+
+describe("POST /bootstrap/claim", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    claimFirstInstanceAdminMock.mockResolvedValue({
+      status: "claimed",
+      userId: "user-1",
+      value: null,
+    });
+  });
+
+  it("claims first admin for an authenticated private browser session", async () => {
+    const app = createApp({});
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ claimed: true, userId: "user-1" });
+    expect(claimFirstInstanceAdminMock).toHaveBeenCalledWith(expect.anything(), { userId: "user-1" });
+  });
+
+  it("is not exposed in authenticated public mode", async () => {
+    const app = createApp({ deploymentExposure: "public" });
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(404);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+  });
+
+  it("is not exposed in local trusted mode", async () => {
+    const app = createApp({ deploymentMode: "local_trusted" });
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(404);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    [{ type: "none", source: "none" }, "anonymous caller"],
+    [{ type: "agent", source: "agent_key", agentId: "agent-1" }, "agent key"],
+    [{ type: "board", source: "board_key", userId: "user-1" }, "board API key"],
+    [{ type: "board", source: "local_implicit", userId: "local-board" }, "local implicit board"],
+  ])("rejects %s before opening the first-admin transaction", async (actor) => {
+    const app = createApp({ actor });
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(401);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+  });
+
+  it("returns conflict when first admin has already been claimed", async () => {
+    claimFirstInstanceAdminMock.mockResolvedValueOnce({
+      status: "already_claimed",
+      existingUserId: "user-2",
+      value: null,
+    });
+    const app = createApp({});
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(409);
+    expect(res.body.error).toContain("already claimed");
+  });
+
+  it("stays behind the board mutation origin guard", async () => {
+    const app = createApp({ guardMutations: true });
+
+    const blocked = await request(app).post("/api/bootstrap/claim").send({});
+    expect(blocked.status).toBe(403);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+
+    const allowed = await request(app)
+      .post("/api/bootstrap/claim")
+      .set("Host", "paperclip.local")
+      .set("Origin", "http://paperclip.local")
+      .send({});
+    expect(allowed.status).toBe(200);
+    expect(claimFirstInstanceAdminMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("bootstrap invite first-admin acceptance", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function createBootstrapInvite() {
+    return {
+      id: "invite-1",
+      companyId: null,
+      inviteType: "bootstrap_ceo",
+      allowedJoinTypes: "human",
+      tokenHash: hashToken("pcp_invite_test"),
+      defaultsPayload: {},
+      expiresAt: new Date("2027-03-10T00:00:00.000Z"),
+      invitedByUserId: null,
+      revokedAt: null,
+      acceptedAt: null,
+      createdAt: new Date("2026-03-07T00:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T00:00:00.000Z"),
+    };
+  }
+
+  it("uses the shared first-admin helper for bootstrap invite acceptance", async () => {
+    const invite = createBootstrapInvite();
+    claimFirstInstanceAdminMock.mockResolvedValueOnce({
+      status: "claimed",
+      userId: "user-1",
+      value: { ...invite, acceptedAt: new Date("2026-03-07T00:01:00.000Z") },
+    });
+    const app = createApp({ db: createDb(invite) });
+
+    const res = await request(app)
+      .post("/api/invites/pcp_invite_test/accept")
+      .send({ requestType: "human" });
+
+    expect(res.status).toBe(202);
+    expect(res.body).toMatchObject({
+      inviteId: "invite-1",
+      inviteType: "bootstrap_ceo",
+      bootstrapAccepted: true,
+      userId: "user-1",
+    });
+    expect(claimFirstInstanceAdminMock).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ userId: "user-1", onClaim: expect.any(Function) }),
+    );
+  });
+
+  it("conflicts cleanly when browser claim already won before invite acceptance", async () => {
+    claimFirstInstanceAdminMock.mockResolvedValueOnce({
+      status: "already_claimed",
+      existingUserId: "user-2",
+      value: null,
+    });
+    const app = createApp({ db: createDb(createBootstrapInvite()) });
+
+    const res = await request(app)
+      .post("/api/invites/pcp_invite_test/accept")
+      .send({ requestType: "human" });
+
+    expect(res.status).toBe(409);
+    expect(res.body.error).toContain("already claimed");
+  });
+});

server/src/__tests__/first-admin-claim.test.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { createDb, instanceUserRoles } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { claimFirstInstanceAdmin } from "../first-admin-claim.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+describeEmbeddedPostgres("claimFirstInstanceAdmin", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-first-admin-claim-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(instanceUserRoles);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("inserts exactly one first admin and reports later claims as conflicts", async () => {
+    const firstUserId = `user-${randomUUID()}`;
+    const first = await claimFirstInstanceAdmin(db, { userId: firstUserId });
+
+    expect(first).toMatchObject({ status: "claimed", userId: firstUserId });
+
+    const second = await claimFirstInstanceAdmin(db, { userId: `user-${randomUUID()}` });
+    expect(second).toMatchObject({ status: "already_claimed", existingUserId: firstUserId });
+
+    const roles = await db.select().from(instanceUserRoles);
+    expect(roles).toHaveLength(1);
+    expect(roles[0]).toMatchObject({ userId: firstUserId, role: "instance_admin" });
+  });
+
+  it("runs onClaim inside the winning transaction", async () => {
+    const userId = `user-${randomUUID()}`;
+    const result = await claimFirstInstanceAdmin(db, {
+      userId,
+      onClaim: async (tx) => {
+        const roles = await tx.select().from(instanceUserRoles);
+        return roles.map((role) => role.userId);
+      },
+    });
+
+    expect(result).toMatchObject({ status: "claimed", userId, value: [userId] });
+  });
+});

server/src/__tests__/health-dev-server-token.test.ts

@@ -96,6 +96,7 @@ describe("GET /health dev-server supervisor access", () => {
       expect(res.body).toEqual({
         status: "ok",
         deploymentMode: "authenticated",
+        deploymentExposure: "private",
         bootstrapStatus: "ready",
         bootstrapInviteActive: false,
         devServer: {

server/src/__tests__/health.test.ts

@@ -97,6 +97,7 @@ describe("GET /health", () => {
     expect(res.body).toEqual({
       status: "ok",
       deploymentMode: "authenticated",
+      deploymentExposure: "public",
       bootstrapStatus: "ready",
       bootstrapInviteActive: false,
     });
@@ -131,6 +132,7 @@ describe("GET /health", () => {
     expect(res.body).toEqual({
       status: "ok",
       deploymentMode: "authenticated",
+      deploymentExposure: "public",
       bootstrapStatus: "ready",
       bootstrapInviteActive: false,
     });

server/src/__tests__/heartbeat-comment-wake-batching.test.ts

@@ -442,12 +442,18 @@ describe("heartbeat comment wake batching", () => {
       gateway.releaseFirstWait();
 
       await waitFor(() => gateway.getAgentPayloads().length === 2);
+      const secondPayload = gateway.getAgentPayloads()[1] ?? {};
+      const secondRunId = typeof secondPayload.idempotencyKey === "string" ? secondPayload.idempotencyKey : null;
+      if (!secondRunId) {
+        throw new Error("Expected forwarded gateway payload to include an idempotencyKey run id");
+      }
+
       await waitFor(async () => {
         const runs = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.agentId, agentId));
-        return runs.length === 2 && runs.every((run) => run.status === "succeeded");
+        const statusesByRunId = new Map(runs.map((run) => [run.id, run.status]));
+        return statusesByRunId.get(firstRun!.id) === "succeeded" && statusesByRunId.get(secondRunId) === "succeeded";
       }, 90_000);
 
-      const secondPayload = gateway.getAgentPayloads()[1] ?? {};
       expect(secondPayload.paperclip).toMatchObject({
         wake: {
           commentIds: [comment2.id, comment3.id],

server/src/first-admin-claim.ts

@@ -0,0 +1,55 @@
+import { eq, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { instanceUserRoles } from "@paperclipai/db";
+
+type FirstAdminTransaction = Pick<Db, "execute" | "select" | "insert" | "update">;
+
+export type FirstAdminClaimResult<T = unknown> =
+  | {
+      status: "claimed";
+      userId: string;
+      value: T | null;
+    }
+  | {
+      status: "already_claimed";
+      existingUserId: string | null;
+      value: null;
+    };
+
+export async function claimFirstInstanceAdmin<T = unknown>(
+  db: Db,
+  input: {
+    userId: string;
+    onClaim?: (tx: FirstAdminTransaction) => Promise<T>;
+  },
+): Promise<FirstAdminClaimResult<T>> {
+  return db.transaction(async (tx) => {
+    await tx.execute(sql`lock table ${instanceUserRoles} in share row exclusive mode`);
+
+    const existingAdmin = await tx
+      .select({ userId: instanceUserRoles.userId })
+      .from(instanceUserRoles)
+      .where(eq(instanceUserRoles.role, "instance_admin"))
+      .then((rows) => rows[0] ?? null);
+
+    if (existingAdmin) {
+      return {
+        status: "already_claimed" as const,
+        existingUserId: existingAdmin.userId ?? null,
+        value: null,
+      };
+    }
+
+    await tx.insert(instanceUserRoles).values({
+      userId: input.userId,
+      role: "instance_admin",
+    });
+
+    const value = input.onClaim ? await input.onClaim(tx) : null;
+    return {
+      status: "claimed" as const,
+      userId: input.userId,
+      value,
+    };
+  });
+}

server/src/routes/access.ts

@@ -79,6 +79,7 @@ import {
   claimBoardOwnership,
   inspectBoardClaimChallenge
 } from "../board-claim.js";
+import { claimFirstInstanceAdmin } from "../first-admin-claim.js";
 import { getStorageService } from "../storage/index.js";
 
 function hashToken(token: string) {
@@ -2453,6 +2454,31 @@ export function accessRoutes(
     throw conflict("Board claim challenge is no longer available");
   });
 
+  router.post("/bootstrap/claim", async (req, res) => {
+    if (
+      opts.deploymentMode !== "authenticated" ||
+      opts.deploymentExposure !== "private"
+    ) {
+      throw notFound("Browser first-admin claim is not available");
+    }
+    if (
+      req.actor.type !== "board" ||
+      req.actor.source !== "session" ||
+      !req.actor.userId
+    ) {
+      throw unauthorized("Sign in from a browser session before claiming first admin");
+    }
+
+    const claimed = await claimFirstInstanceAdmin(db, {
+      userId: req.actor.userId,
+    });
+    if (claimed.status === "already_claimed") {
+      throw conflict("Someone else has already claimed this instance");
+    }
+
+    res.json({ claimed: true, userId: claimed.userId });
+  });
+
   router.post(
     "/cli-auth/challenges",
     validate(createCliAuthChallengeSchema),
@@ -3276,16 +3302,31 @@ export function accessRoutes(
           );
         }
         const userId = req.actor.userId ?? "local-board";
-        const existingAdmin = await access.isInstanceAdmin(userId);
+        const claimed = await claimFirstInstanceAdmin(db, {
-        if (!existingAdmin) {
+          userId,
-          await access.promoteInstanceAdmin(userId);
+          onClaim: async (tx) => {
+            const updatedInvite = await tx
+              .update(invites)
+              .set({ acceptedAt: new Date(), updatedAt: new Date() })
+              .where(
+                and(
+                  eq(invites.id, invite.id),
+                  isNull(invites.acceptedAt),
+                  isNull(invites.revokedAt)
+                )
+              )
+              .returning()
+              .then((rows) => rows[0] ?? null);
+            if (!updatedInvite) {
+              throw conflict("Bootstrap invite is no longer available");
+            }
+            return updatedInvite;
+          },
+        });
+        if (claimed.status === "already_claimed") {
+          throw conflict("Someone else has already claimed this instance");
         }
-        const updatedInvite = await db
+        const updatedInvite = claimed.value ?? invite;
-          .update(invites)
-          .set({ acceptedAt: new Date(), updatedAt: new Date() })
-          .where(eq(invites.id, invite.id))
-          .returning()
-          .then((rows) => rows[0] ?? invite);
         res.status(202).json({
           inviteId: updatedInvite.id,
           inviteType: updatedInvite.inviteType,

server/src/routes/health.ts

@@ -157,6 +157,7 @@ export function healthRoutes(
       res.json({
         status: "ok",
         deploymentMode: opts.deploymentMode,
+        deploymentExposure: opts.deploymentExposure,
         bootstrapStatus,
         bootstrapInviteActive,
         ...(devServer ? { devServer } : {}),

ui/src/App.test.tsx

@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 
-import { act, type ReactNode } from "react";
+import type { ReactNode } from "react";
+import { flushSync } from "react-dom";
 import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -16,6 +17,7 @@ const mockAuthApi = vi.hoisted(() => ({
 
 const mockAccessApi = vi.hoisted(() => ({
   getCurrentBoardAccess: vi.fn(),
+  claimBootstrapAdmin: vi.fn(),
 }));
 
 vi.mock("./api/health", () => ({
@@ -31,6 +33,7 @@ vi.mock("./api/access", () => ({
 }));
 
 vi.mock("@/lib/router", () => ({
+  Link: ({ to, children }: { to: string; children?: ReactNode }) => <a href={to}>{children}</a>,
   Navigate: ({ to }: { to: string }) => <div>Navigate:{to}</div>,
   Outlet: () => <div>Outlet content</div>,
   Route: ({ children }: { children?: ReactNode }) => <>{children}</>,
@@ -39,13 +42,39 @@ vi.mock("@/lib/router", () => ({
   useParams: () => ({}),
 }));
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
-
 async function flushReact() {
-  await act(async () => {
+  await Promise.resolve();
-    await Promise.resolve();
+  await new Promise((resolve) => window.setTimeout(resolve, 0));
-    await new Promise((resolve) => window.setTimeout(resolve, 0));
+}
+
+async function waitForText(container: HTMLElement, text: string) {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    if (container.textContent?.includes(text)) return;
+    await flushReact();
+  }
+  expect(container.textContent).toContain(text);
+}
+
+function renderGate(container: HTMLElement) {
+  const root = createRoot(container);
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  flushSync(() => {
+    root.render(
+      <QueryClientProvider client={queryClient}>
+        <CloudAccessGate />
+      </QueryClientProvider>,
+    );
+  });
+
+  return root;
+}
+
+function unmountRoot(root: ReturnType<typeof createRoot>) {
+  flushSync(() => {
+    root.unmount();
   });
 }
 
@@ -58,6 +87,7 @@ describe("CloudAccessGate", () => {
     mockHealthApi.get.mockResolvedValue({
       status: "ok",
       deploymentMode: "authenticated",
+      deploymentExposure: "private",
       bootstrapStatus: "ready",
     });
   });
@@ -82,28 +112,13 @@ describe("CloudAccessGate", () => {
       keyId: null,
     });
 
-    const root = createRoot(container);
+    const root = renderGate(container);
-    const queryClient = new QueryClient({
+    await waitForText(container, "No company access");
-      defaultOptions: { queries: { retry: false } },
-    });
-
-    await act(async () => {
-      root.render(
-        <QueryClientProvider client={queryClient}>
-          <CloudAccessGate />
-        </QueryClientProvider>,
-      );
-    });
-    await flushReact();
-    await flushReact();
-    await flushReact();
 
     expect(container.textContent).toContain("No company access");
     expect(container.textContent).not.toContain("Outlet content");
 
-    await act(async () => {
+    unmountRoot(root);
-      root.unmount();
-    });
   });
 
   it("allows authenticated users with company access through to the board", async () => {
@@ -120,27 +135,95 @@ describe("CloudAccessGate", () => {
       keyId: null,
     });
 
-    const root = createRoot(container);
+    const root = renderGate(container);
-    const queryClient = new QueryClient({
+    await waitForText(container, "Outlet content");
-      defaultOptions: { queries: { retry: false } },
-    });
-
-    await act(async () => {
-      root.render(
-        <QueryClientProvider client={queryClient}>
-          <CloudAccessGate />
-        </QueryClientProvider>,
-      );
-    });
-    await flushReact();
-    await flushReact();
-    await flushReact();
 
     expect(container.textContent).toContain("Outlet content");
     expect(container.textContent).not.toContain("No company access");
 
-    await act(async () => {
+    unmountRoot(root);
-      root.unmount();
+  });
+
+  it("shows browser sign-in setup for signed-out private bootstrap-pending instances", async () => {
+    mockHealthApi.get.mockResolvedValue({
+      status: "ok",
+      deploymentMode: "authenticated",
+      deploymentExposure: "private",
+      bootstrapStatus: "bootstrap_pending",
+      bootstrapInviteActive: false,
     });
+    mockAuthApi.getSession.mockResolvedValue(null);
+
+    const root = renderGate(container);
+    await waitForText(container, "Finish setting up this Paperclip");
+
+    expect(container.textContent).toContain("Finish setting up this Paperclip");
+    expect(container.textContent).toContain("Sign in / Create account");
+    expect(container.textContent).toContain("pnpm paperclipai auth bootstrap-ceo");
+    expect(mockAccessApi.getCurrentBoardAccess).not.toHaveBeenCalled();
+
+    unmountRoot(root);
+  });
+
+  it("shows the claim action for signed-in private bootstrap-pending instances", async () => {
+    mockHealthApi.get.mockResolvedValue({
+      status: "ok",
+      deploymentMode: "authenticated",
+      deploymentExposure: "private",
+      bootstrapStatus: "bootstrap_pending",
+      bootstrapInviteActive: false,
+    });
+    mockAuthApi.getSession.mockResolvedValue({
+      session: { id: "session-1", userId: "user-1" },
+      user: { id: "user-1", email: "user@example.com", name: "User", image: null },
+    });
+    mockAccessApi.claimBootstrapAdmin.mockResolvedValue({ claimed: true, userId: "user-1" });
+
+    const root = renderGate(container);
+    await waitForText(container, "Claim this instance");
+
+    expect(container.textContent).toContain("Claim this instance");
+    expect(container.textContent).toContain("Signed in as user@example.com");
+    expect(mockAccessApi.getCurrentBoardAccess).not.toHaveBeenCalled();
+
+    const button = Array.from(container.querySelectorAll("button")).find((candidate) =>
+      candidate.textContent?.includes("Claim this instance"),
+    );
+    expect(button).toBeTruthy();
+    flushSync(() => {
+      button?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await waitForText(container, "You're the instance admin");
+
+    expect(mockAccessApi.claimBootstrapAdmin).toHaveBeenCalledTimes(1);
+    expect(container.textContent).toContain("You're the instance admin");
+    expect(container.textContent).toContain("Continue to dashboard");
+
+    unmountRoot(root);
+  });
+
+  it("keeps public bootstrap-pending instances invite-only", async () => {
+    mockHealthApi.get.mockResolvedValue({
+      status: "ok",
+      deploymentMode: "authenticated",
+      deploymentExposure: "public",
+      bootstrapStatus: "bootstrap_pending",
+      bootstrapInviteActive: true,
+    });
+    mockAuthApi.getSession.mockResolvedValue({
+      session: { id: "session-1", userId: "user-1" },
+      user: { id: "user-1", email: "user@example.com", name: "User", image: null },
+    });
+
+    const root = renderGate(container);
+    await waitForText(container, "This Paperclip is waiting on its first admin");
+
+    expect(container.textContent).toContain("This Paperclip is waiting on its first admin");
+    expect(container.textContent).toContain("invite-only mode");
+    expect(container.textContent).not.toContain("Claim this instance");
+    expect(container.textContent).not.toContain("Sign in / Create account");
+    expect(mockAccessApi.claimBootstrapAdmin).not.toHaveBeenCalled();
+
+    unmountRoot(root);
   });
 });

ui/src/App.tsx

@@ -32,6 +32,7 @@ import { CompanySettings } from "./pages/CompanySettings";
 import { CompanyEnvironments } from "./pages/CompanyEnvironments";
 import { CloudUpstream } from "./pages/CloudUpstream";
 import { CloudUpstreamUxLab } from "./pages/CloudUpstreamUxLab";
+import { BootstrapSetupUxLab } from "./pages/BootstrapSetupUxLab";
 import { CompanySettingsPluginPage } from "./pages/CompanySettingsPluginPage";
 import { CompanyAccess, CompanyAccessLegacyRoute } from "./pages/CompanyAccess";
 import { CompanyInvites } from "./pages/CompanyInvites";
@@ -284,6 +285,7 @@ export function App() {
         <Route path="invite/:token" element={<InviteLandingPage />} />
         <Route path="tests/perf/long-thread" element={<IssueChatLongThreadPerf />} />
         <Route path="ux-lab/cloud-upstream" element={<CloudUpstreamUxLab />} />
+        <Route path="ux-lab/bootstrap-setup" element={<BootstrapSetupUxLab />} />
 
         <Route element={<CloudAccessGate />}>
           <Route index element={<CompanyRootRedirect />} />

ui/src/api/access.ts

@@ -384,6 +384,9 @@ export const accessApi = {
   claimBoard: (token: string, code: string) =>
     api.post<{ claimed: true; userId: string }>(`/board-claim/${token}/claim`, { code }),
 
+  claimBootstrapAdmin: () =>
+    api.post<{ claimed: true; userId: string }>("/bootstrap/claim", {}),
+
   getCliAuthChallenge: (id: string, token: string) =>
     api.get<CliAuthChallengeStatus>(`/cli-auth/challenges/${id}?token=${encodeURIComponent(token)}`),
 

ui/src/bootstrapSetup.ts

@@ -0,0 +1 @@
+export const BOOTSTRAP_FALLBACK_COMMAND = "pnpm paperclipai auth bootstrap-ceo";

ui/src/components/BootstrapPendingPage.tsx

@@ -0,0 +1,176 @@
+import type { ReactNode } from "react";
+import { Loader2, ShieldCheck, Terminal, TriangleAlert } from "lucide-react";
+import { Link } from "@/lib/router";
+import { Button } from "@/components/ui/button";
+import { BOOTSTRAP_FALLBACK_COMMAND } from "@/bootstrapSetup";
+import type { AuthSession } from "@paperclipai/shared";
+
+type BootstrapPendingPageProps = {
+  claimAvailable: boolean;
+  hasActiveInvite?: boolean;
+  session: AuthSession | null | undefined;
+  claimState: "idle" | "claiming" | "success";
+  claimError?: { status?: number; message?: string } | null;
+  onClaim: () => void;
+};
+
+function CliFallback({ hasActiveInvite = false }: { hasActiveInvite?: boolean }) {
+  return (
+    <div className="mt-6 border-t border-border pt-5">
+      <div className="flex items-center gap-2 text-sm font-medium">
+        <Terminal className="size-4 text-muted-foreground" aria-hidden />
+        <span>Prefer to finish setup from the host?</span>
+      </div>
+      <p className="mt-2 text-sm text-muted-foreground">
+        {hasActiveInvite
+          ? "A bootstrap invite is already active. Check your Paperclip startup logs for the first-admin URL, or run this command on the host to rotate it:"
+          : "Run this command on the host that runs Paperclip to print a one-time first-admin invite URL:"}
+      </p>
+      <pre className="mt-3 overflow-x-auto rounded-md border border-border bg-muted/30 p-3 font-mono text-xs">
+{BOOTSTRAP_FALLBACK_COMMAND}
+      </pre>
+    </div>
+  );
+}
+
+function StateChrome({ children }: { children: ReactNode }) {
+  return (
+    <div className="mx-auto max-w-xl py-10">
+      <div className="rounded-lg border border-border bg-card p-6">{children}</div>
+    </div>
+  );
+}
+
+function displayIdentity(session: AuthSession) {
+  return session.user.email || session.user.name || session.user.id;
+}
+
+function claimErrorCopy(error: BootstrapPendingPageProps["claimError"]) {
+  if (error?.status === 409) {
+    return {
+      title: "Someone else has already claimed this instance.",
+      body: "Refresh to sign in, or ask the existing admin to invite you from Instance settings -> Access.",
+    };
+  }
+  if (error?.status === 401) {
+    return {
+      title: "Your session expired. Sign in again to claim this instance.",
+      body: "",
+    };
+  }
+  return {
+    title: "We couldn't reach the server. Try again in a moment.",
+    body: "",
+  };
+}
+
+export function BootstrapPendingPage({
+  claimAvailable,
+  hasActiveInvite = false,
+  session,
+  claimState,
+  claimError,
+  onClaim,
+}: BootstrapPendingPageProps) {
+  if (!claimAvailable) {
+    return (
+      <StateChrome>
+        <h1 className="text-xl font-semibold">This Paperclip is waiting on its first admin</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          This instance runs in invite-only mode. The operator must generate a one-time first-admin invite URL
+          from the host. Once you have the link, open it from this browser to finish setup.
+        </p>
+        <CliFallback hasActiveInvite={hasActiveInvite} />
+        <p className="mt-4 text-xs text-muted-foreground">
+          Browser-based claim is intentionally disabled in public mode so anyone on the network can't promote
+          themselves.
+        </p>
+      </StateChrome>
+    );
+  }
+
+  if (claimState === "success") {
+    return (
+      <StateChrome>
+        <div className="flex items-start gap-3">
+          <div className="mt-0.5 flex size-9 flex-shrink-0 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
+            <ShieldCheck className="size-5" aria-hidden />
+          </div>
+          <div>
+            <h1 className="text-xl font-semibold">You're the instance admin</h1>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Setup is complete. Taking you to onboarding to create your first company...
+            </p>
+          </div>
+        </div>
+        <div className="mt-5 flex items-center gap-3">
+          <Loader2 className="size-4 animate-spin text-muted-foreground" aria-hidden />
+          <span className="text-sm text-muted-foreground">Redirecting...</span>
+        </div>
+        <div className="mt-5">
+          <Button asChild variant="outline">
+            <a href="/">Continue to dashboard</a>
+          </Button>
+        </div>
+      </StateChrome>
+    );
+  }
+
+  if (!session) {
+    return (
+      <StateChrome>
+        <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          No admin has claimed this instance yet. Sign in or create your Paperclip account to become the first
+          admin from this browser.
+        </p>
+        <div className="mt-5">
+          <Button asChild>
+            <Link to="/auth?next=/">Sign in / Create account</Link>
+          </Button>
+        </div>
+        <CliFallback hasActiveInvite={hasActiveInvite} />
+      </StateChrome>
+    );
+  }
+
+  const errorCopy = claimErrorCopy(claimError);
+  const isClaiming = claimState === "claiming";
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
+      </p>
+      <div className="mt-5 flex flex-wrap items-center gap-3">
+        <Button onClick={onClaim} disabled={isClaiming}>
+          {isClaiming && <Loader2 className="mr-2 size-4 animate-spin" aria-hidden />}
+          {isClaiming ? "Claiming..." : "Claim this instance"}
+        </Button>
+        <span className="text-sm text-muted-foreground">
+          Signed in as <span className="font-medium text-foreground">{displayIdentity(session)}</span>
+        </span>
+      </div>
+      <p className="mt-3 text-xs text-muted-foreground">
+        Wrong account?{" "}
+        <Link to="/auth?next=/" className="underline underline-offset-2">
+          Switch account
+        </Link>
+        .
+      </p>
+      {claimError && (
+        <div
+          role="alert"
+          className="mt-4 flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive"
+        >
+          <TriangleAlert className="mt-0.5 size-4 flex-shrink-0" aria-hidden />
+          <div>
+            <p className="font-medium">{errorCopy.title}</p>
+            {errorCopy.body && <p className="mt-1 text-destructive/90">{errorCopy.body}</p>}
+          </div>
+        </div>
+      )}
+      <CliFallback hasActiveInvite={hasActiveInvite} />
+    </StateChrome>
+  );
+}

ui/src/components/CloudAccessGate.tsx

@@ -1,27 +1,11 @@
 import { Navigate, Outlet, useLocation } from "@/lib/router";
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { accessApi } from "@/api/access";
+import { ApiError } from "@/api/client";
 import { authApi } from "@/api/auth";
 import { healthApi } from "@/api/health";
 import { queryKeys } from "@/lib/queryKeys";
-
+import { BootstrapPendingPage } from "@/components/BootstrapPendingPage";
-function BootstrapPendingPage({ hasActiveInvite = false }: { hasActiveInvite?: boolean }) {
-  return (
-    <div className="mx-auto max-w-xl py-10">
-      <div className="rounded-lg border border-border bg-card p-6">
-        <h1 className="text-xl font-semibold">Instance setup required</h1>
-        <p className="mt-2 text-sm text-muted-foreground">
-          {hasActiveInvite
-            ? "No instance admin exists yet. A bootstrap invite is already active. Check your Paperclip startup logs for the first admin invite URL, or run this command to rotate it:"
-            : "No instance admin exists yet. Run this command in your Paperclip environment to generate the first admin invite URL:"}
-        </p>
-        <pre className="mt-4 overflow-x-auto rounded-md border border-border bg-muted/30 p-3 text-xs">
-{`pnpm paperclipai auth bootstrap-ceo`}
-        </pre>
-      </div>
-    </div>
-  );
-}
 
 function NoBoardAccessPage() {
   return (
@@ -42,6 +26,7 @@ function NoBoardAccessPage() {
 
 export function CloudAccessGate() {
   const location = useLocation();
+  const queryClient = useQueryClient();
   const healthQuery = useQuery({
     queryKey: queryKeys.health,
     queryFn: () => healthApi.get(),
@@ -58,6 +43,7 @@ export function CloudAccessGate() {
   });
 
   const isAuthenticatedMode = healthQuery.data?.deploymentMode === "authenticated";
+  const isBootstrapPending = isAuthenticatedMode && healthQuery.data?.bootstrapStatus === "bootstrap_pending";
   const sessionQuery = useQuery({
     queryKey: queryKeys.auth.session,
     queryFn: () => authApi.getSession(),
@@ -68,14 +54,24 @@ export function CloudAccessGate() {
   const boardAccessQuery = useQuery({
     queryKey: queryKeys.access.currentBoardAccess,
     queryFn: () => accessApi.getCurrentBoardAccess(),
-    enabled: isAuthenticatedMode && !!sessionQuery.data,
+    enabled: isAuthenticatedMode && !isBootstrapPending && !!sessionQuery.data,
     retry: false,
   });
+  const claimMutation = useMutation({
+    mutationFn: () => accessApi.claimBootstrapAdmin(),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: queryKeys.auth.session });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.health });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.companies.all });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.companies.stats });
+      await queryClient.invalidateQueries({ queryKey: queryKeys.access.currentBoardAccess });
+    },
+  });
 
   if (
     healthQuery.isLoading ||
     (isAuthenticatedMode && sessionQuery.isLoading) ||
-    (isAuthenticatedMode && !!sessionQuery.data && boardAccessQuery.isLoading)
+    (isAuthenticatedMode && !isBootstrapPending && !!sessionQuery.data && boardAccessQuery.isLoading)
   ) {
     return <div className="mx-auto max-w-xl py-10 text-sm text-muted-foreground">Loading...</div>;
   }
@@ -92,8 +88,26 @@ export function CloudAccessGate() {
     );
   }
 
-  if (isAuthenticatedMode && healthQuery.data?.bootstrapStatus === "bootstrap_pending") {
+  if (isBootstrapPending) {
-    return <BootstrapPendingPage hasActiveInvite={healthQuery.data.bootstrapInviteActive} />;
+    const health = healthQuery.data;
+    if (!health) {
+      return <div className="mx-auto max-w-xl py-10 text-sm text-muted-foreground">Loading...</div>;
+    }
+    const claimError = claimMutation.error instanceof ApiError
+      ? { status: claimMutation.error.status, message: claimMutation.error.message }
+      : claimMutation.error instanceof Error
+        ? { message: claimMutation.error.message }
+        : null;
+    return (
+      <BootstrapPendingPage
+        claimAvailable={health.deploymentExposure === "private"}
+        hasActiveInvite={health.bootstrapInviteActive}
+        session={sessionQuery.data}
+        claimState={claimMutation.isSuccess ? "success" : claimMutation.isPending ? "claiming" : "idle"}
+        claimError={claimError}
+        onClaim={() => claimMutation.mutate()}
+      />
+    );
   }
 
   if (isAuthenticatedMode && !sessionQuery.data) {

ui/src/pages/BootstrapSetupUxLab.tsx

@@ -0,0 +1,247 @@
+import type { ReactElement, ReactNode } from "react";
+import { Loader2, ShieldCheck, Terminal, TriangleAlert } from "lucide-react";
+import { BOOTSTRAP_FALLBACK_COMMAND } from "@/bootstrapSetup";
+import { Button } from "@/components/ui/button";
+
+type LabFixtureKey =
+  | "signed-out-private"
+  | "signed-in-private"
+  | "claiming"
+  | "claim-error"
+  | "claim-success"
+  | "public-invite-only";
+
+const FIXTURE_LABELS: Record<LabFixtureKey, string> = {
+  "signed-out-private": "1 · authenticated/private — signed out (browser claim available)",
+  "signed-in-private": "2 · authenticated/private — signed in (claim CTA primary)",
+  claiming: "3 · authenticated/private — claim in flight",
+  "claim-error": "4 · authenticated/private — claim error (e.g. 409 already claimed)",
+  "claim-success": "5 · authenticated/private — claim succeeded, redirect pending",
+  "public-invite-only": "6 · authenticated/public — invite-only (no browser claim)",
+};
+
+const FIXTURE_ORDER: LabFixtureKey[] = [
+  "signed-out-private",
+  "signed-in-private",
+  "claiming",
+  "claim-error",
+  "claim-success",
+  "public-invite-only",
+];
+
+function CliFallback({ hasActiveInvite }: { hasActiveInvite: boolean }) {
+  return (
+    <div className="mt-6 border-t border-border pt-5">
+      <div className="flex items-center gap-2 text-sm font-medium">
+        <Terminal className="size-4 text-muted-foreground" aria-hidden />
+        <span>Prefer to finish setup from the host?</span>
+      </div>
+      <p className="mt-2 text-sm text-muted-foreground">
+        {hasActiveInvite
+          ? "A bootstrap invite is already active. Check your Paperclip startup logs for the first‑admin URL, or run this command on the host to rotate it:"
+          : "Run this command on the host that runs Paperclip to print a one‑time first‑admin invite URL:"}
+      </p>
+      <pre className="mt-3 overflow-x-auto rounded-md border border-border bg-muted/30 p-3 font-mono text-xs">
+{BOOTSTRAP_FALLBACK_COMMAND}
+      </pre>
+    </div>
+  );
+}
+
+function StateChrome({ children }: { children: ReactNode }) {
+  return (
+    <div className="mx-auto max-w-xl py-10">
+      <div className="rounded-lg border border-border bg-card p-6">{children}</div>
+    </div>
+  );
+}
+
+function SignedOutPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Sign in or create your Paperclip account to become the first
+        admin from this browser.
+      </p>
+      <div className="mt-5">
+        <Button asChild>
+          <a href="/auth?next=/">Sign in / Create account</a>
+        </Button>
+      </div>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function SignedInPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
+      </p>
+      <div className="mt-5 flex flex-wrap items-center gap-3">
+        <Button>Claim this instance</Button>
+        <span className="text-sm text-muted-foreground">
+          Signed in as <span className="font-medium text-foreground">jane@appliance.local</span>
+        </span>
+      </div>
+      <p className="mt-3 text-xs text-muted-foreground">
+        Wrong account?{" "}
+        <a href="/auth?next=/" className="underline underline-offset-2">
+          Switch account
+        </a>
+        .
+      </p>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function ClaimingPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
+      </p>
+      <div className="mt-5 flex flex-wrap items-center gap-3">
+        <Button disabled>
+          <Loader2 className="mr-2 size-4 animate-spin" aria-hidden />
+          Claiming…
+        </Button>
+        <span className="text-sm text-muted-foreground">
+          Signed in as <span className="font-medium text-foreground">jane@appliance.local</span>
+        </span>
+      </div>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function ClaimErrorPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
+      </p>
+      <div className="mt-5 flex flex-wrap items-center gap-3">
+        <Button>Claim this instance</Button>
+        <span className="text-sm text-muted-foreground">
+          Signed in as <span className="font-medium text-foreground">jane@appliance.local</span>
+        </span>
+      </div>
+      <div
+        role="alert"
+        className="mt-4 flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive"
+      >
+        <TriangleAlert className="mt-0.5 size-4 flex-shrink-0" aria-hidden />
+        <div>
+          <p className="font-medium">Someone else has already claimed this instance.</p>
+          <p className="mt-1 text-destructive/90">
+            Refresh to sign in, or ask the existing admin to invite you from{" "}
+            <span className="font-mono">Instance settings → Access</span>.
+          </p>
+        </div>
+      </div>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function ClaimSuccess() {
+  return (
+    <StateChrome>
+      <div className="flex items-start gap-3">
+        <div className="mt-0.5 flex size-9 flex-shrink-0 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
+          <ShieldCheck className="size-5" aria-hidden />
+        </div>
+        <div>
+          <h1 className="text-xl font-semibold">You&rsquo;re the instance admin</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Setup is complete. Taking you to onboarding to create your first company&hellip;
+          </p>
+        </div>
+      </div>
+      <div className="mt-5 flex items-center gap-3">
+        <Loader2 className="size-4 animate-spin text-muted-foreground" aria-hidden />
+        <span className="text-sm text-muted-foreground">Redirecting&hellip;</span>
+      </div>
+      <div className="mt-5">
+        <Button asChild variant="outline">
+          <a href="/">Continue to dashboard</a>
+        </Button>
+      </div>
+    </StateChrome>
+  );
+}
+
+function PublicInviteOnly() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">This Paperclip is waiting on its first admin</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        This instance runs in invite‑only mode. The operator must generate a one‑time first‑admin invite URL
+        from the host. Once you have the link, open it from this browser to finish setup.
+      </p>
+      <CliFallback hasActiveInvite />
+      <p className="mt-4 text-xs text-muted-foreground">
+        Browser‑based claim is intentionally disabled in public mode so anyone on the network can&rsquo;t
+        promote themselves.
+      </p>
+    </StateChrome>
+  );
+}
+
+const FIXTURE_BODIES: Record<LabFixtureKey, ReactElement> = {
+  "signed-out-private": <SignedOutPrivate />,
+  "signed-in-private": <SignedInPrivate />,
+  claiming: <ClaimingPrivate />,
+  "claim-error": <ClaimErrorPrivate />,
+  "claim-success": <ClaimSuccess />,
+  "public-invite-only": <PublicInviteOnly />,
+};
+
+export function BootstrapSetupUxLab() {
+  return (
+    <div className="bg-background min-h-screen pb-16">
+      <header className="border-b border-border bg-muted/20">
+        <div className="mx-auto max-w-3xl px-6 py-6">
+          <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">UX Lab</p>
+          <h1 className="mt-1 text-2xl font-semibold">Bootstrap-pending setup states</h1>
+          <p className="mt-2 max-w-2xl text-sm text-muted-foreground">
+            Fixtures for the bootstrap-pending screen in <span className="font-mono">CloudAccessGate</span>. Used
+            as the UX spec for{" "}
+            <a className="underline underline-offset-2" href="/PAP/issues/PAP-10113">
+              PAP-10113
+            </a>{" "}
+            and the implementation reference for{" "}
+            <a className="underline underline-offset-2" href="/PAP/issues/PAP-10114">
+              PAP-10114
+            </a>
+            . The browser claim CTA only appears when{" "}
+            <span className="font-mono">deploymentMode === &quot;authenticated&quot;</span> and{" "}
+            <span className="font-mono">deploymentExposure === &quot;private&quot;</span>.
+          </p>
+        </div>
+      </header>
+      <main className="mx-auto max-w-3xl space-y-12 px-6 pt-10">
+        {FIXTURE_ORDER.map((key) => (
+          <section key={key} aria-labelledby={`lab-${key}`}>
+            <h2
+              id={`lab-${key}`}
+              className="mb-3 text-xs font-medium uppercase tracking-wider text-muted-foreground"
+            >
+              {FIXTURE_LABELS[key]}
+            </h2>
+            <div className="rounded-lg border border-dashed border-border/70 bg-muted/10 p-2">
+              {FIXTURE_BODIES[key]}
+            </div>
+          </section>
+        ))}
+      </main>
+    </div>
+  );
+}