The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
[codex] Add private browser first-admin claim flow (#6755)
Dotta8da50dbcf8f9
diff --git a/doc/DEPLOYMENT-MODES.md b/doc/DEPLOYMENT-MODES.mdindex bf8dbdd4c7..96c78a43ca 100644--- a/doc/DEPLOYMENT-MODES.md+++ b/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`diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex 341f3b1117..ec1789a23e 100644--- a/doc/DEVELOPING.md+++ b/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:diff --git a/doc/DOCKER.md b/doc/DOCKER.mdindex 056a7bdf04..bc1fae8cae 100644--- a/doc/DOCKER.md+++ b/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).diff --git a/scripts/run-vitest-stable.mjs b/scripts/run-vitest-stable.mjsindex a3ef4ba4c0..42f13cddcf 100644--- a/scripts/run-vitest-stable.mjs+++ b/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;diff --git a/server/src/__tests__/bootstrap-claim-routes.test.ts b/server/src/__tests__/bootstrap-claim-routes.test.tsnew file mode 100644index 0000000000..d58daf42f4--- /dev/null+++ b/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");+ });+});diff --git a/server/src/__tests__/first-admin-claim.test.ts b/server/src/__tests__/first-admin-claim.test.tsnew file mode 100644index 0000000000..a0461a89db--- /dev/null+++ b/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] });+ });+});diff --git a/server/src/__tests__/health-dev-server-token.test.ts b/server/src/__tests__/health-dev-server-token.test.tsindex 536ef66c3b..e50b0930f1 100644--- a/server/src/__tests__/health-dev-server-token.test.ts+++ b/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: {diff --git a/server/src/__tests__/health.test.ts b/server/src/__tests__/health.test.tsindex 2d294c0e0d..66bf9a7749 100644--- a/server/src/__tests__/health.test.ts+++ b/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,});diff --git a/server/src/__tests__/heartbeat-comment-wake-batching.test.ts b/server/src/__tests__/heartbeat-comment-wake-batching.test.tsindex 606f69bca9..117ae4bb35 100644--- a/server/src/__tests__/heartbeat-comment-wake-batching.test.ts+++ b/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],diff --git a/server/src/first-admin-claim.ts b/server/src/first-admin-claim.tsnew file mode 100644index 0000000000..b134348f0b--- /dev/null+++ b/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,+ };+ });+}diff --git a/server/src/routes/access.ts b/server/src/routes/access.tsindex 44b1fbaf6f..0478f60ee1 100644--- a/server/src/routes/access.ts+++ b/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);- if (!existingAdmin) {- await access.promoteInstanceAdmin(userId);+ const claimed = await claimFirstInstanceAdmin(db, {+ 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- .update(invites)- .set({ acceptedAt: new Date(), updatedAt: new Date() })- .where(eq(invites.id, invite.id))- .returning()- .then((rows) => rows[0] ?? invite);+ const updatedInvite = claimed.value ?? invite;res.status(202).json({inviteId: updatedInvite.id,inviteType: updatedInvite.inviteType,diff --git a/server/src/routes/health.ts b/server/src/routes/health.tsindex 80a2dd7016..f5a99ce396 100644--- a/server/src/routes/health.ts+++ b/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 } : {}),diff --git a/ui/src/App.test.tsx b/ui/src/App.test.tsxindex bec9c199ae..ed6bba5d9e 100644--- a/ui/src/App.test.tsx+++ b/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 new Promise((resolve) => window.setTimeout(resolve, 0));+ await Promise.resolve();+ 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 queryClient = new QueryClient({- defaultOptions: { queries: { retry: false } },- });-- await act(async () => {- root.render(- <QueryClientProvider client={queryClient}>- <CloudAccessGate />- </QueryClientProvider>,- );- });- await flushReact();- await flushReact();- await flushReact();+ const root = renderGate(container);+ await waitForText(container, "No company access");expect(container.textContent).toContain("No company access");expect(container.textContent).not.toContain("Outlet content");- await act(async () => {- root.unmount();- });+ unmountRoot(root);});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 queryClient = new QueryClient({- defaultOptions: { queries: { retry: false } },+ const root = renderGate(container);+ await waitForText(container, "Outlet content");++ expect(container.textContent).toContain("Outlet content");+ expect(container.textContent).not.toContain("No company access");++ unmountRoot(root);+ });++ 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: "[email protected]", name: "User", image: null },+ });+ mockAccessApi.claimBootstrapAdmin.mockResolvedValue({ claimed: true, userId: "user-1" });++ const root = renderGate(container);+ await waitForText(container, "Claim this instance");- await act(async () => {- root.render(- <QueryClientProvider client={queryClient}>- <CloudAccessGate />- </QueryClientProvider>,- );+ expect(container.textContent).toContain("Claim this instance");+ expect(container.textContent).toContain("Signed in as [email protected]");+ 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 flushReact();- await flushReact();- await flushReact();+ await waitForText(container, "You're the instance admin");- expect(container.textContent).toContain("Outlet content");- expect(container.textContent).not.toContain("No company access");+ expect(mockAccessApi.claimBootstrapAdmin).toHaveBeenCalledTimes(1);+ expect(container.textContent).toContain("You're the instance admin");+ expect(container.textContent).toContain("Continue to dashboard");++ unmountRoot(root);+ });- await act(async () => {- root.unmount();+ 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: "[email protected]", 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);});});diff --git a/ui/src/App.tsx b/ui/src/App.tsxindex f6d81f2bc9..94522182c9 100644--- a/ui/src/App.tsx+++ b/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 />} />diff --git a/ui/src/api/access.ts b/ui/src/api/access.tsindex b5b68946c0..dc30475759 100644--- a/ui/src/api/access.ts+++ b/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)}`),diff --git a/ui/src/bootstrapSetup.ts b/ui/src/bootstrapSetup.tsnew file mode 100644index 0000000000..83ebeba84f--- /dev/null+++ b/ui/src/bootstrapSetup.ts@@ -0,0 +1 @@+export const BOOTSTRAP_FALLBACK_COMMAND = "pnpm paperclipai auth bootstrap-ceo";diff --git a/ui/src/components/BootstrapPendingPage.tsx b/ui/src/components/BootstrapPendingPage.tsxnew file mode 100644index 0000000000..659ad5723c--- /dev/null+++ b/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>+ );+}diff --git a/ui/src/components/CloudAccessGate.tsx b/ui/src/components/CloudAccessGate.tsxindex eaea736bcd..0ec4592676 100644--- a/ui/src/components/CloudAccessGate.tsx+++ b/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";--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>- );-}+import { BootstrapPendingPage } from "@/components/BootstrapPendingPage";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") {- return <BootstrapPendingPage hasActiveInvite={healthQuery.data.bootstrapInviteActive} />;+ if (isBootstrapPending) {+ 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) {diff --git a/ui/src/pages/BootstrapSetupUxLab.tsx b/ui/src/pages/BootstrapSetupUxLab.tsxnew file mode 100644index 0000000000..35d49644c8--- /dev/null+++ b/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">[email protected]</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">[email protected]</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">[email protected]</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’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>+ );+}++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’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 === "authenticated"</span> and{" "}+ <span className="font-mono">deploymentExposure === "private"</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>+ );+}