From f31da9e910dc3ef10d821ec63dfa179d9342b7d3 Mon Sep 17 00:00:00 2001
From: Barry Cape <barryonthecape@icloud.com>
Date: Sun, 20 Sep 2026 19:43:38 -0700
Subject: [PATCH 01/10] feat: add agent-driven Teams and Flows signup guides

---
 web/app/flows/page.tsx                  |   2 +
 web/app/signup/agent/[product]/route.ts |  21 ++
 web/app/teams/page.tsx                  |   2 +
 web/components/AgentSignup.tsx          |  44 ++++
 web/components/agent-signup.module.css  |  12 +
 web/lib/agent-signup.ts                 | 295 ++++++++++++++++++++++++
 web/lib/docs-markdown.ts                |   2 +
 web/lib/test/agent-signup.test.ts       |  58 +++++
 8 files changed, 436 insertions(+)
 create mode 100644 web/app/signup/agent/[product]/route.ts
 create mode 100644 web/components/AgentSignup.tsx
 create mode 100644 web/components/agent-signup.module.css
 create mode 100644 web/lib/agent-signup.ts
 create mode 100644 web/lib/test/agent-signup.test.ts

diff --git a/web/app/flows/page.tsx b/web/app/flows/page.tsx
index 11e3e02c..f4fc2646 100644
--- a/web/app/flows/page.tsx
+++ b/web/app/flows/page.tsx
@@ -17,6 +17,7 @@ import home from '../landing.module.css';
 import s from './flows.module.css';
 import { FlowExamples } from './FlowExamples';
 import { IntegrationMarquee } from './IntegrationMarquee';
+import { AgentSignup } from '../../components/AgentSignup';
 
 export const metadata: Metadata = {
   title: 'Flows: Script your agents',
@@ -98,6 +99,7 @@ export default function FlowsPage() {
                 Chat with founders
               </a>
             </div>
+            <AgentSignup product="flows" />
           </div>
         </section>
 
diff --git a/web/app/signup/agent/[product]/route.ts b/web/app/signup/agent/[product]/route.ts
new file mode 100644
index 00000000..d6623925
--- /dev/null
+++ b/web/app/signup/agent/[product]/route.ts
@@ -0,0 +1,21 @@
+import { agentSignupInstructions, isAgentSignupProduct } from '../../../../lib/agent-signup';
+import { teamsCloudUrl } from '../../../../lib/teams-cloud';
+import { SITE_URL } from '../../../../lib/site';
+
+export async function GET(request: Request, { params }: { params: Promise<{ product: string }> }) {
+  const { product } = await params;
+  if (!isAgentSignupProduct(product)) return new Response('Not found', { status: 404 });
+  const url = new URL(request.url);
+  // The apex router's HTTP fallback rewrites the URL to the marketing origin.
+  // Sign-in and /cloud remain on the public apex, never that upstream host.
+  const site = url.hostname === 'origin-web.agentrelay.com' ? SITE_URL : url.origin;
+  const cloud = new URL(teamsCloudUrl(''), site).href.replace(/\/$/, '');
+  return new Response(agentSignupInstructions(product, site, cloud), {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'Access-Control-Allow-Origin': '*',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  });
+}
diff --git a/web/app/teams/page.tsx b/web/app/teams/page.tsx
index fd62fe41..9a7df2a7 100644
--- a/web/app/teams/page.tsx
+++ b/web/app/teams/page.tsx
@@ -14,6 +14,7 @@ import { SiteFooter } from '../../components/SiteFooter';
 import { TEAMS_OG_ALT, TEAMS_OG_IMAGE_PATH, ogImage } from '../../lib/og-meta';
 import { absoluteUrl } from '../../lib/site';
 import { teamsCloudUrl } from '../../lib/teams-cloud';
+import { AgentSignup } from '../../components/AgentSignup';
 import home from '../landing.module.css';
 import flows from '../flows/flows.module.css';
 import { IntegrationMarquee } from '../flows/IntegrationMarquee';
@@ -68,6 +69,7 @@ export default function TeamsPage() {
                 </a>
                 <p className={s.signupNote}>No credit card required</p>
               </div>
+              <AgentSignup product="teams" />
             </div>
           </section>
 
diff --git a/web/components/AgentSignup.tsx b/web/components/AgentSignup.tsx
new file mode 100644
index 00000000..8f359bc3
--- /dev/null
+++ b/web/components/AgentSignup.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import { useRef, useState } from 'react';
+import { agentSignupPrompt, type AgentSignupProduct } from '../lib/agent-signup';
+import { SITE_URL } from '../lib/site';
+import s from './agent-signup.module.css';
+
+export function AgentSignup({ product }: { product: AgentSignupProduct }) {
+  const [origin, setOrigin] = useState(SITE_URL);
+  const [message, setMessage] = useState('');
+  const prompt = useRef<HTMLTextAreaElement>(null);
+  const text = agentSignupPrompt(product, origin);
+
+  async function copy() {
+    try {
+      await navigator.clipboard.writeText(text);
+      setMessage('Copied. Paste it into your agent.');
+    } catch {
+      prompt.current?.focus();
+      prompt.current?.select();
+      setMessage('Select and copy the prompt, then paste it into your agent.');
+    }
+  }
+
+  return (
+    <details className={s.root} onToggle={(event) => {
+      if (event.currentTarget.open) {
+        setOrigin(window.location.origin);
+        setMessage('');
+      }
+    }}>
+      <summary>Set up with my agent <span aria-hidden="true">↗</span></summary>
+      <div className={s.panel}>
+        <p>Paste this into your coding agent. It handles setup; you approve sign-in and connections.</p>
+        <textarea ref={prompt} aria-label="Agent signup prompt" value={text} readOnly rows={5} />
+        <div className={s.actions}>
+          <button type="button" onClick={() => void copy()}>Copy prompt</button>
+          <a href={`/signup/agent/${product}`}>Read agent instructions</a>
+        </div>
+        <p className={s.status} role="status">{message}</p>
+      </div>
+    </details>
+  );
+}
diff --git a/web/components/agent-signup.module.css b/web/components/agent-signup.module.css
new file mode 100644
index 00000000..097f7316
--- /dev/null
+++ b/web/components/agent-signup.module.css
@@ -0,0 +1,12 @@
+.root { width: min(100%, 520px); margin: 18px auto 0; color: #c3d6e4; text-align: left; }
+.root summary { width: fit-content; margin: 0 auto; cursor: pointer; font-size: 15px; text-underline-offset: 5px; }
+.root summary:hover { color: #fff; text-decoration: underline; }
+.root summary:focus-visible, .actions button:focus-visible, .actions a:focus-visible { outline: 2px solid #9bd0ed; outline-offset: 5px; }
+.root summary span { margin-left: 5px; }
+.panel { margin-top: 16px; padding: 20px; border: 1px solid #426077; border-radius: 12px; background: #102a3d; }
+.panel p { margin: 0 0 14px; font-size: 14px; line-height: 1.65; }
+.panel textarea { box-sizing: border-box; width: 100%; min-height: 145px; padding: 12px; resize: vertical; border: 1px solid #426077; border-radius: 6px; background: #091d2b; color: #e4f0f8; font: 13px/1.7 var(--font-mono), monospace; }
+.actions { display: flex; flex-wrap: wrap; align-items: center; gap: 16px; margin-top: 14px; font-size: 13px; }
+.actions button { border: 1px solid #85b8d7; border-radius: 6px; padding: 9px 14px; background: #c1e4f6; color: #102333; cursor: pointer; font: inherit; font-weight: 600; }
+.actions a { color: #c1e4f6; text-underline-offset: 4px; }
+.panel .status { margin: 8px 0 0; min-height: 22px; font-size: 12px; }
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
new file mode 100644
index 00000000..43a0145e
--- /dev/null
+++ b/web/lib/agent-signup.ts
@@ -0,0 +1,295 @@
+export type AgentSignupProduct = 'teams' | 'flows';
+
+export function isAgentSignupProduct(value: string): value is AgentSignupProduct {
+  return value === 'teams' || value === 'flows';
+}
+
+export function agentSignupPrompt(product: AgentSignupProduct, origin: string): string {
+  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Read and follow ${origin}/signup/agent/${product}. Handle the setup and API calls, open authorization pages for me to approve, and verify that setup completed.`;
+}
+
+/** Bundled strings: these instructions must also work on Workers without a filesystem. */
+export function agentSignupInstructions(product: AgentSignupProduct, site: string, cloud: string): string {
+  const title = product === 'teams' ? 'Teams' : 'Flows';
+  const shared = `# Agent Relay ${title}: agent-driven signup
+
+You are setting up Agent Relay on behalf of the user who gave you this URL.
+Do the API calls, installation, configuration, and verification yourself. Keep
+working across browser approvals; do not hand the user a checklist to execute.
+The user handles Google sign-in, device approval, and any provider or operating
+system consent. Never approve access on their behalf or ask for their password.
+
+Site: ${site}
+Cloud API base: ${cloud}
+All API paths below are relative to that Cloud base, including its /cloud prefix.
+Use this exact environment throughout; never fall back from local development
+to production. The Teams desktop app currently requires macOS 13 or later.
+Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
+
+## 1. Sign up and obtain an API session
+
+Use the existing OAuth device flow. No API key, invitation, dashboard wizard,
+or pre-existing Agent Relay account is required.
+
+POST /api/v1/auth/device/start with Content-Type: application/json:
+
+~~~json
+{"client_name":"My agent — ${title} setup","signup_source":"${product}"}
+~~~
+
+Expect HTTP 201 with device_code, user_code, verification_uri_complete,
+verification_uri, interval (seconds), and expires_in (seconds). Keep device_code
+private. Open verification_uri_complete in the user's browser and show the
+user_code so they can compare it. The page lets them sign in with Google,
+review the requesting device, and Approve or Deny. The signup marker in the
+returned URL creates the right account type; preserve it through sign-in.
+Do not call /auth/device/approve yourself.
+
+For a fresh signup, you can open ${cloud}/api/auth/google/start?next=<encoded-return-path>
+first, where encoded-return-path is the URL-encoded pathname plus query of
+verification_uri_complete. This opens Google immediately and returns to the
+same device approval with its code and signup marker intact.
+
+While the browser is open, wait interval seconds between POSTs to
+/api/v1/auth/device/token with this JSON (substitute the private device_code):
+
+~~~json
+{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"<device_code>"}
+~~~
+
+- authorization_pending: keep waiting; respect a returned interval.
+- slow_down: increase the interval by at least 5 seconds.
+- HTTP 429: respect Retry-After and increase the interval.
+- HTTP 5xx or request timeout: retry with backoff, bounded by expires_in.
+- access_denied: stop. expired_token or invalid_grant: explain and start a new
+  grant only if the user still wants to continue. Never poll past expiry.
+
+HTTP 200 returns access_token, refresh_token, access_token_expires_at,
+refresh_token_expires_at, api_url and token_type. Keep credentials in memory
+or a private file (directory 0700, file 0600) outside repositories. Never echo
+tokens, put them in chat or URLs, or dump full authentication responses.
+Use Authorization: Bearer <access_token> for subsequent Cloud requests.
+Reject an api_url pointing at another origin; keep using the Cloud base above.
+Set a 30-second request timeout and check every response status before proceeding.
+
+Before expiry, POST /api/v1/auth/token/refresh with {"refreshToken":"<refresh_token>"}.
+The response uses camelCase: accessToken, refreshToken, accessTokenExpiresAt,
+refreshTokenExpiresAt, apiUrl. Replace both stored tokens atomically. Serialize
+refreshes: the refresh token rotates and must not be shared between machines.
+An invalid/expired refresh requires a new device login, not an endless retry.
+
+GET /api/v1/auth/whoami. Require authenticated: true and read user.id,
+user.email, currentWorkspace.id, and currentOrganization.id. New signups create
+a workspace automatically. Reuse it; do not create duplicate accounts/workspaces.
+If currentWorkspace is missing, or an existing account is in the wrong workspace,
+resolve that with the user before connecting or activating anything. Never
+silently replace an existing connection to another account.
+
+## Credential handoff to the supported CLI
+
+When running a child process, pass these through its environment from your
+private session object (never interpolate their values into logged commands):
+
+~~~text
+CLOUD_API_URL=${cloud}
+CLOUD_API_ACCESS_TOKEN=<access_token>
+CLOUD_API_REFRESH_TOKEN=<refresh_token>
+CLOUD_API_ACCESS_TOKEN_EXPIRES_AT=<access_token_expires_at>
+CLOUD_API_REFRESH_TOKEN_EXPIRES_AT=<refresh_token_expires_at>
+~~~
+
+The official CLI consumes this session. The bundled desktop probe uses
+CLOUD_API_ACCESS_TOKEN to exchange for its own scoped History session, so it
+does not need a second Google login. Refresh the parent session before starting
+a long command; do not concurrently refresh it from parent and child processes.
+Do not overwrite an existing CLI auth file or copy a session to another machine.
+`;
+  return shared + (product === 'teams' ? teamsInstructions(site) : flowsInstructions(site, cloud));
+}
+
+function teamsInstructions(site: string): string {
+  const local = new URL(site).protocol === 'http:';
+  const name = local ? 'Agent Relay Dev' : 'Agent Relay';
+  const download = local
+    ? `${site}/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg`
+    : 'https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/AgentRelay-macOS-<arch>.dmg';
+  return `
+## 2. Download and install the desktop app
+
+Run sw_vers -productVersion and uname -m on the user's Mac. arm64 means Apple
+silicon; x86_64 means the x64 download. If this agent runs in a remote sandbox,
+it must obtain access to the user's Mac before installation; installing into
+the sandbox does not connect their computer. Report an unsupported OS honestly.
+
+Download ${download} and the same URL plus .sha256. Replace <arch> with arm64
+or x64. Use a private temporary directory, follow HTTPS release redirects, and
+fail on HTTP errors. Verify SHA-256 before mounting. For local development,
+only the architecture built by the Cloud launcher is available; a missing DMG
+means the local stack must be built, never that you should download production.
+
+Use hdiutil attach -nobrowse with a private mount point, then ditto the mounted
+${name}.app into ~/Applications/${name}.app (create ~/Applications if needed).
+Detach the image and clean up the temporary download after copying. Check for
+an already installed app in /Applications and ~/Applications first: reuse the
+correct app instead of overwriting a running or newer installation. Preserve
+macOS signing/quarantine checks. If macOS requires consent, let the user approve
+the normal Open / Privacy & Security prompt; do not strip quarantine or disable
+Gatekeeper. A checksum mismatch is a hard stop.
+The desktop app supports https://agentrelay.com and the local development stack;
+other preview hosts require a separately configured app. Do not connect a
+production app to a preview URL.
+
+## 3. Connect the app using its bundled CLI
+
+Set PROBE to the absolute path of the installed app's
+Contents/Helpers/agent-relay-probe. Use the bundled executable, not an unrelated
+binary on PATH. Run it with --help and verify support for cloud install --json
+and --selected-sessions-only. Read installs --json first, keeping local paths
+and account details private. Reuse a matching account/workspace install.
+
+Run this with the private credential environment from step 1. Substitute the
+actual user.id and currentWorkspace.id returned by whoami:
+
+~~~sh
+"$PROBE" cloud install --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --selected-sessions-only --json
+~~~
+
+This exchanges credentials, catalogs local sessions, and starts the background
+collector. Consume the NDJSON events until the process exits successfully;
+do not declare success when the process merely starts. If it requests another
+approval, verify the environment and credential expiry before retrying.
+
+Selected sessions is the default: signing up is not consent to upload all past
+conversations. When the user has selected sessions to share, list the catalog
+and pass their exact session keys to sessions include:
+
+~~~sh
+"$PROBE" sessions list --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --limit 500 --json
+"$PROBE" sessions include --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --session '<selected-key>' --json
+~~~
+
+Repeat --session for multiple keys. Do not choose sessions for the user.
+Only when explicitly requested, use --new-sessions-only or --include-existing
+instead of --selected-sessions-only during installation. Do not start duplicate
+collectors or silently stop an existing uploader for another environment.
+
+## 4. Verify and open the app
+
+~~~sh
+"$PROBE" status --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --json
+~~~
+
+Require running: true, paused: false, and the expected siteUrl, accountId, and
+workspaceId. Check delivery and lastCycle for failures. If sessions were selected,
+poll sessions list with a bounded wait until those sessions report uploaded;
+do not equate a running collector with uploaded content. If none were selected,
+report that the app is connected and no sessions have been shared yet.
+
+Open the installed ${name}.app after setup; it discovers the probe's saved
+connection. To select the exact account/workspace when multiple installs exist,
+open ${local ? 'agentrelay-dev' : 'agentrelay'}://connect?site=<encoded-site>&account=<encoded-user.id>&workspace=<encoded-currentWorkspace.id>
+with the installed app. URL-encode the three values; the link contains identifiers
+only, never tokens. Open ${site}/cloud/dashboard/sessions for the team history. Report
+the installed app, account/workspace, sharing choice, and verification outcome.
+Delete temporary authentication files after use; retain the app-managed scoped
+credentials so background collection continues. The user can pause, select
+sessions, or disconnect in the app.
+`;
+}
+
+function flowsInstructions(site: string, cloud: string): string {
+  return `
+## 2. Choose the flow and repository
+
+Ask only for missing product choices: repository, desired workflow/trigger, and
+approver. Infer them from the user's request and current repository where clear.
+Do not invent a repository or enable automation on an unrelated project.
+
+GET ${site}/api/v1/flows/catalog and select a matching entry from flows.
+GET ${site}/api/v1/flows/catalog/<id> for its full contract. Use the catalog's
+supportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and
+inputs.allowedAgents. Download source.rawUrl, verify its bytes against
+source.sha256, and use that source text unchanged for a recommended flow.
+The source is TypeScript, not the source URL. Do not guess a template or hash.
+For custom flows use ${site}/docs/relayflows/markdown/build.md and
+${site}/docs/relayflows/markdown/cloud.md for the authoring contract.
+
+## 3. Connect the required tools and coding agents
+
+Use bearer-authenticated POST /api/v1/integrations/connect-link:
+
+~~~json
+{"provider":"github","workspaceId":"<currentWorkspace.id>"}
+~~~
+
+Open the returned connectUrl for the user to approve. Keep token/sessionToken
+private. Connect only the repository and tools the chosen flow requires.
+For GitHub the user must grant repository access. Repeat with the chosen trigger
+provider if different. Reuse existing ready connections rather than relinking.
+Check GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status
+until ready is true (poll with backoff and a bounded timeout); a returned connect
+link or a closed popup alone does not prove the integration is ready.
+
+Connect the coding agent required by the catalog using the official Relay CLI
+with the private credential environment from step 1 and a PTY:
+
+~~~sh
+npx --yes agent-relay@latest cloud connect anthropic --api-url '${cloud}'
+~~~
+
+Use anthropic for Claude or openai for Codex, according to the selected flow.
+The command drives provider login; open its authorization URL for the user,
+and keep the process alive until it confirms the credential is connected.
+Google approval does not grant GitHub or model-provider access: those services
+may require their own consent. Never fabricate credentials or claim consent
+happened. If already connected, GET /api/v1/cloud-agents lets you inspect the
+account's credential state without reconnecting. Provider or sandbox service
+configuration failures must be fixed before activation can succeed.
+
+## 4. Activate through the same API as web onboarding
+
+POST /api/v1/flows/deploy with Content-Type: application/json and the bearer
+session. Construct the body from the chosen catalog entry and user choices:
+
+~~~json
+{
+  "workspaceId": "<currentWorkspace.id>",
+  "name": "<user's flow name>",
+  "workflow": "<catalog id>",
+  "source": "<verified TypeScript source text>",
+  "handoffId": "<one UUID generated for this setup>",
+  "inputs": {"approver": "<approver email>", "agents": ["<allowed coding agent>"]},
+  "mode": "activate",
+  "repository": {"owner": "<repository owner>", "name": "<repository name>"},
+  "sources": [{"provider": "<trigger provider>", "settings": {}}]
+}
+~~~
+
+Use the catalog's defaultTrigger for sources and apply the user's trigger
+settings. For GitLab set repository.host to gitlab and use the namespace path
+as owner. Reuse the handoffId on retry. Before retrying an ambiguous network
+failure, GET /api/v1/flows/listeners and check whether the flow already exists;
+do not create a new ID/name on every retry. Activation subscribes to matching
+future events and can run work; confirm the intended repository and trigger
+with the user if they have not specified them.
+
+HTTP 201 must contain agentId and status: listening. A draft is not completion.
+For a 409 workspace_mismatch, verify the active workspace; for connection
+preflight failures, fix the indicated connection before retrying. If the user
+wants to save incomplete work, use mode: draft explicitly and report that it
+is inactive. Never mask activation failures by silently falling back to draft.
+
+## 5. Verify
+
+GET /api/v1/flows/listeners/<agentId>. Require listener.status: listening and
+verify its repository and sources match the request. Open
+${site}/cloud/dashboard/workflows/listeners/<agentId> for the user. Report the flow name,
+workspace, repository, trigger, and verified listening state. This proves
+activation; only an actual completed run proves execution. Do not create a
+real issue or launch paid work merely to make the onboarding check turn green.
+Delete temporary authentication files after the work is complete.
+
+The desktop app is optional for Flows. If the user also wants local session
+sharing, follow ${site}/signup/agent/teams using the same signed-in account.
+`;
+}
diff --git a/web/lib/docs-markdown.ts b/web/lib/docs-markdown.ts
index 89b8925a..788e6d57 100644
--- a/web/lib/docs-markdown.ts
+++ b/web/lib/docs-markdown.ts
@@ -216,6 +216,8 @@ export function getLlmsText(): string {
     '',
     '## Documentation',
     '',
+    formatLink({ title: 'Sign up for Teams with an agent', url: absoluteUrl('/signup/agent/teams'), description: 'Google authorization, desktop installation, session sharing, and verification.' }),
+    formatLink({ title: 'Sign up for Flows with an agent', url: absoluteUrl('/signup/agent/flows'), description: 'Google authorization, repository and provider connections, flow activation, and verification.' }),
     formatLink({
       title: 'Full documentation content',
       url: absoluteUrl('/llms-full.txt'),
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
new file mode 100644
index 00000000..62d2730c
--- /dev/null
+++ b/web/lib/test/agent-signup.test.ts
@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { GET } from '../../app/signup/agent/[product]/route';
+import { agentSignupPrompt } from '../agent-signup';
+
+afterEach(() => vi.unstubAllEnvs());
+
+describe('agent signup instructions', () => {
+  it.each(['teams', 'flows'])('serves complete %s instructions without cookies or JavaScript', async (product) => {
+    vi.stubEnv('NEXT_PUBLIC_CLOUD_URL', '/cloud');
+    const response = await GET(new Request(`https://agentrelay.com/signup/agent/${product}`), {
+      params: Promise.resolve({ product }),
+    });
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toBe('text/markdown; charset=utf-8');
+    expect(response.headers.get('access-control-allow-origin')).toBe('*');
+    expect(response.headers.get('cache-control')).toBe('no-store');
+    const content = await response.text();
+    expect(content).toContain(`"signup_source":"${product}"`);
+    expect(content).toContain('Cloud API base: https://agentrelay.com/cloud');
+    expect(content).toContain('/api/v1/auth/device/token');
+    expect(content).toContain('/api/v1/auth/whoami');
+    expect(content).toContain('/api/v1/auth/token/refresh');
+    if (product === 'teams') {
+      expect(content).toContain('--selected-sessions-only --json');
+      expect(content).toContain('releases/latest/download/AgentRelay-macOS-<arch>.dmg');
+    } else {
+      expect(content).toContain('"mode": "activate"');
+      expect(content).toContain('/api/v1/flows/listeners/<agentId>');
+    }
+  });
+
+  it('keeps the local hostname and port for OAuth, APIs, and the dev desktop download', async () => {
+    vi.stubEnv('NEXT_PUBLIC_CLOUD_URL', '/cloud');
+    const content = await (await GET(new Request('http://127.0.0.1:3199/signup/agent/teams'), {
+      params: Promise.resolve({ product: 'teams' }),
+    })).text();
+    expect(content).toContain('Cloud API base: http://127.0.0.1:3199/cloud');
+    expect(content).toContain('http://127.0.0.1:3199/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg');
+    expect(content).not.toContain('releases/latest/download');
+    expect(agentSignupPrompt('teams', 'http://127.0.0.1:3199')).toContain('http://127.0.0.1:3199/signup/agent/teams');
+  });
+
+  it.each(['unknown', 'Teams', 'flows/extra'])('returns 404 for unsupported product %s', async (product) => {
+    const response = await GET(new Request('https://agentrelay.com/signup/agent/unknown'), {
+      params: Promise.resolve({ product }),
+    });
+    expect(response.status).toBe(404);
+  });
+
+  it('keeps the public apex when served through the router HTTP fallback', async () => {
+    vi.stubEnv('NEXT_PUBLIC_CLOUD_URL', '/cloud');
+    const content = await (await GET(new Request('https://origin-web.agentrelay.com/signup/agent/teams'), {
+      params: Promise.resolve({ product: 'teams' }),
+    })).text();
+    expect(content).toContain('Cloud API base: https://agentrelay.com/cloud');
+    expect(content).not.toContain('origin-web.agentrelay.com');
+  });
+});

From ef3751953a37135f8935c348a8fdf5f79ac831b6 Mon Sep 17 00:00:00 2001
From: Barry Cape <barryonthecape@icloud.com>
Date: Sun, 20 Sep 2026 20:50:09 -0700
Subject: [PATCH 02/10] fix: align agent signup guides with deployed API and
 probe contracts

---
 web/content/docs/relayflows/recommended.mdx | 25 +++++----
 web/lib/agent-signup.ts                     | 60 +++++++++++++++------
 web/lib/test/agent-signup.test.ts           | 26 +++++++++
 3 files changed, 84 insertions(+), 27 deletions(-)

diff --git a/web/content/docs/relayflows/recommended.mdx b/web/content/docs/relayflows/recommended.mdx
index 01e813d3..0a3a883b 100644
--- a/web/content/docs/relayflows/recommended.mdx
+++ b/web/content/docs/relayflows/recommended.mdx
@@ -11,7 +11,7 @@ Software Garden is the display name of the first recommended flow. Its stable ca
 
 The released source uses Claude Code for implementation and review, so catalog version 1 allows and defaults only that harness. A future catalog version can point at a new released source with a different requirement; clients do not rewrite the authored flow.
 
-Software Garden currently supports GitHub repositories. Each activation supplies one or more repositories, and Cloud scopes a GitHub listener to each one. The catalog deliberately does not define Babysitter behavior. Babysitter is a [flow plugin](/docs/relayflows/plugins) installed onto Software Garden, not a recommended flow of its own.
+Software Garden currently supports GitHub repositories. Deploy one listener per repository using the direct-source API below. The catalog deliberately does not define Babysitter behavior. Babysitter is a [flow plugin](/docs/relayflows/plugins) installed onto Software Garden, not a recommended flow of its own.
 
 ## Catalog API
 
@@ -30,21 +30,22 @@ The catalog does not copy or generate the flow body. `source` names the canonica
 https://github.com/AgentWorkforce/flows/blob/b4dd665eb433bd7f52d1045543aef5f14fb7891e/examples/software-factory/software-factory.flow.ts
 ```
 
-CI and the production release workflow resolve the release tag, fetch the pinned raw file with a size bound, and verify the digest. A broken, moved, mutable, or drifted source therefore fails before the catalog can ship. Cloud fetches it through the existing trusted source loader and stores the fetched body only as that deployment's immutable snapshot and provenance.
+CI and the production release workflow resolve the release tag, fetch the pinned raw file with a size bound, and verify the digest. A broken, moved, mutable, or drifted source therefore fails before the catalog can ship. For the direct-source deploy API, the client downloads `source.rawUrl`, verifies the bytes against `source.sha256`, and submits that source text; Cloud stores it as the deployment's source snapshot.
 
 ## Activation contract
 
-Cloud accepts the catalog ID and activation settings, then fetches the matching canonical source itself:
+The current `POST /cloud/api/v1/flows/deploy` endpoint accepts the same direct-source listener body as `flows deploy`. Authenticate with a Cloud bearer session, download and verify the catalog source, then submit:
 
 ```json
 {
   "workspaceId": "workspace-id",
-  "flowId": "software-factory",
-  "label": "Platform Garden",
-  "repositories": [
-    { "owner": "acme", "name": "api" },
-    { "owner": "acme", "name": "web" }
-  ],
+  "name": "Platform Garden",
+  "workflow": "software-factory",
+  "source": "<verified TypeScript source text>",
+  "handoffId": "<UUID generated for this deployment>",
+  "mode": "activate",
+  "repository": { "owner": "acme", "name": "api" },
+  "sources": [{ "provider": "github", "settings": { "repository": "acme/api" } }],
   "inputs": {
     "approver": "github:@octocat",
     "agents": ["claude"]
@@ -52,4 +53,8 @@ Cloud accepts the catalog ID and activation settings, then fetches the matching
 }
 ```
 
-`approver` is required. `agents` may be omitted to use the catalog default. The custom label names the visible activation group; each repository still gets its own scoped listener and run workspace.
+Replace the sample repository and approver with the user's choices. `approver` is required; for GitHub use `github:@handle`, not a Google email. Fill `agents` from the catalog defaults and supported harnesses. `workflow` labels the flow; it does not cause Cloud to fetch the source. The endpoint requires inline source text and one `repository`, not a `flowId`/`repositories` catalog request or the browser onboarding handoff.
+
+Set the GitHub trigger's `settings.repository` to the selected `owner/name`; Cloud does not derive that filter from `repository`, and an empty filter can wake the listener for other repositories in the workspace.
+
+For several repositories, submit one body per repository with its own trigger filter, distinct name, and `handoffId`; reuse that ID when retrying the same deployment. Connect required tools and coding agents before activation. Success is HTTP 201 with `agentId` and `status: "listening"`; verify the saved listener through `GET /cloud/api/v1/flows/listeners/<agentId>`. See the [complete agent signup instructions](/signup/agent/flows) for authentication, connections, and retry behavior.
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 43a0145e..8d1ac105 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -161,7 +161,9 @@ approval, verify the environment and credential expiry before retrying.
 
 Selected sessions is the default: signing up is not consent to upload all past
 conversations. When the user has selected sessions to share, list the catalog
-and pass their exact session keys to sessions include:
+and pass their exact session keys to sessions include. Each JSON row has source
+and session_id; construct the key as SOURCE:SESSION_ID (for example codex:abc123).
+The list response does not contain a precomputed key. Never pass a bare session_id:
 
 ~~~sh
 "$PROBE" sessions list --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --limit 500 --json
@@ -179,17 +181,21 @@ collectors or silently stop an existing uploader for another environment.
 "$PROBE" status --site-url '${site}' --account '<user.id>' --workspace '<currentWorkspace.id>' --json
 ~~~
 
-Require running: true, paused: false, and the expected siteUrl, accountId, and
-workspaceId. Check delivery and lastCycle for failures. If sessions were selected,
+Require running: true, paused: false, and the expected site_url, account_id, and
+workspace_id. These are the CLI's JSON field names. Check delivery and last_cycle
+for failures. If sessions were selected,
 poll sessions list with a bounded wait until those sessions report uploaded;
 do not equate a running collector with uploaded content. If none were selected,
 report that the app is connected and no sessions have been shared yet.
 
-Open the installed ${name}.app after setup; it discovers the probe's saved
-connection. To select the exact account/workspace when multiple installs exist,
-open ${local ? 'agentrelay-dev' : 'agentrelay'}://connect?site=<encoded-site>&account=<encoded-user.id>&workspace=<encoded-currentWorkspace.id>
-with the installed app. URL-encode the three values; the link contains identifiers
-only, never tokens. Open ${site}/cloud/dashboard/sessions for the team history. Report
+Use this as the initial handoff to the installed ${name}.app:
+${local ? 'agentrelay-dev' : 'agentrelay'}://connect?site=<encoded-site>&account=<encoded-user.id>&workspace=<encoded-currentWorkspace.id>
+URL-encode the three values; the link contains identifiers only, never tokens.
+The app discovers the probe's saved connection. If it is already attached to a
+different account/workspace, the link will report a conflict, not switch accounts.
+Ask the user to explicitly log out/switch in Account before retrying; do not
+disconnect an existing workspace automatically. Confirm the app's Account view
+matches the target. Open ${site}/cloud/dashboard/sessions for the team history. Report
 the installed app, account/workspace, sharing choice, and verification outcome.
 Delete temporary authentication files after use; retain the app-managed scoped
 credentials so background collection continues. The user can pause, select
@@ -202,7 +208,10 @@ function flowsInstructions(site: string, cloud: string): string {
 ## 2. Choose the flow and repository
 
 Ask only for missing product choices: repository, desired workflow/trigger, and
-approver. Infer them from the user's request and current repository where clear.
+approver. For GitHub use the approver's GitHub login as github:@handle (for
+example github:@octocat), not their Google email. Human-gate replies are matched
+to the provider identity. Infer choices from the user's request and current
+repository where clear.
 Do not invent a repository or enable automation on an unrelated project.
 
 GET ${site}/api/v1/flows/catalog and select a matching entry from flows.
@@ -249,24 +258,41 @@ configuration failures must be fixed before activation can succeed.
 ## 4. Activate through the same API as web onboarding
 
 POST /api/v1/flows/deploy with Content-Type: application/json and the bearer
-session. Construct the body from the chosen catalog entry and user choices:
+session. This is the direct-source listener API used by flows deploy, not the
+browser onboarding handoff: source is TypeScript text, repository is singular,
+and sources contains provider/settings objects. The catalog supplies the source
+reference and defaults; it is not itself a deploy request. The current endpoint
+does not accept a flowId/repositories-only catalog activation request or fetch
+the source for you. For multiple repositories, submit one deployment per
+repository with a distinct name and handoffId.
+
+For the catalog's Software Garden entry, construct this body, substituting the
+workspace, verified source, repository, GitHub approver and a new UUID:
 
 ~~~json
 {
   "workspaceId": "<currentWorkspace.id>",
-  "name": "<user's flow name>",
-  "workflow": "<catalog id>",
+  "name": "Platform Garden",
+  "workflow": "software-factory",
   "source": "<verified TypeScript source text>",
   "handoffId": "<one UUID generated for this setup>",
-  "inputs": {"approver": "<approver email>", "agents": ["<allowed coding agent>"]},
+  "inputs": {"approver": "github:@octocat", "agents": ["claude"]},
   "mode": "activate",
-  "repository": {"owner": "<repository owner>", "name": "<repository name>"},
-  "sources": [{"provider": "<trigger provider>", "settings": {}}]
+  "repository": {"owner": "acme", "name": "api"},
+  "sources": [{"provider": "github", "settings": {"repository": "acme/api"}}]
 }
 ~~~
 
-Use the catalog's defaultTrigger for sources and apply the user's trigger
-settings. For GitLab set repository.host to gitlab and use the namespace path
+For another catalog entry use its id as workflow, allowed agents, and
+defaultTrigger for sources, then apply the user's trigger settings. Scope a
+GitHub issue trigger with settings.repository set to the chosen owner/name;
+for GitLab use settings.project. Cloud does not derive this filter from the
+deployment repository. An empty filter can trigger on other repositories in
+the workspace. Only use a different trigger scope when explicitly requested.
+Give each repository its own trigger filter for multi-repository setup. Do not send
+the example acme repository or octocat approver unchanged. The workflow field
+is a label, not a source lookup; keep the verified source in the request.
+For GitLab set repository.host to gitlab and use the namespace path
 as owner. Reuse the handoffId on retry. Before retrying an ambiguous network
 failure, GET /api/v1/flows/listeners and check whether the flow already exists;
 do not create a new ID/name on every retry. Activation subscribes to matching
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 62d2730c..78c41461 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { GET } from '../../app/signup/agent/[product]/route';
 import { agentSignupPrompt } from '../agent-signup';
+import { getRecommendedFlow } from '../recommended-flow-catalog';
 
 afterEach(() => vi.unstubAllEnvs());
 
@@ -23,6 +24,10 @@ describe('agent signup instructions', () => {
     if (product === 'teams') {
       expect(content).toContain('--selected-sessions-only --json');
       expect(content).toContain('releases/latest/download/AgentRelay-macOS-<arch>.dmg');
+      expect(content).toContain('site_url, account_id, and\nworkspace_id');
+      expect(content).toContain('last_cycle');
+      expect(content).toContain('SOURCE:SESSION_ID');
+      expect(content).toContain('will report a conflict, not switch accounts');
     } else {
       expect(content).toContain('"mode": "activate"');
       expect(content).toContain('/api/v1/flows/listeners/<agentId>');
@@ -55,4 +60,25 @@ describe('agent signup instructions', () => {
     expect(content).toContain('Cloud API base: https://agentrelay.com/cloud');
     expect(content).not.toContain('origin-web.agentrelay.com');
   });
+
+  it('uses the direct-source listener body and a provider-addressable approver', async () => {
+    const content = await (await GET(new Request('https://agentrelay.com/signup/agent/flows'), {
+      params: Promise.resolve({ product: 'flows' }),
+    })).text();
+    const examples = [...content.matchAll(/~~~json\n([\s\S]*?)\n~~~/g)].map(match => JSON.parse(match[1]));
+    const deploy = examples.find(body => body.mode === 'activate');
+    const flow = getRecommendedFlow('software-factory')!;
+    expect(deploy).toMatchObject({
+      workflow: flow.id,
+      source: expect.any(String),
+      handoffId: expect.any(String),
+      repository: { owner: 'acme', name: 'api' },
+      sources: [{ ...flow.defaultTrigger, settings: { ...flow.defaultTrigger.settings, repository: 'acme/api' } }],
+      inputs: { approver: 'github:@octocat', agents: flow.inputs.defaults.agents },
+    });
+    expect(deploy).not.toHaveProperty('flowId');
+    expect(deploy).not.toHaveProperty('repositories');
+    expect(content).toContain('one deployment per');
+    expect(content).not.toContain('<approver email>');
+  });
 });

From a0f97cac9a8b425244663ae88b5ca2f55c66421c Mon Sep 17 00:00:00 2001
From: Barry Cape <barryonthecape@icloud.com>
Date: Sun, 20 Sep 2026 21:10:17 -0700
Subject: [PATCH 03/10] Make agent signup a visible copy-prompt card

---
 web/components/AgentSignup.tsx         |  68 ++++++++++----
 web/components/agent-signup.module.css | 118 ++++++++++++++++++++++---
 2 files changed, 157 insertions(+), 29 deletions(-)

diff --git a/web/components/AgentSignup.tsx b/web/components/AgentSignup.tsx
index 8f359bc3..d2d67543 100644
--- a/web/components/AgentSignup.tsx
+++ b/web/components/AgentSignup.tsx
@@ -1,20 +1,33 @@
 'use client';
 
-import { useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
+import { ArrowUpRight, Check, Copy, Terminal } from 'lucide-react';
+import { AgentToolLogo } from './AgentToolLogos';
 import { agentSignupPrompt, type AgentSignupProduct } from '../lib/agent-signup';
 import { SITE_URL } from '../lib/site';
 import s from './agent-signup.module.css';
 
+const agents = [
+  { id: 'any', label: 'Agent setup' },
+  { id: 'claude', label: 'Claude Code' },
+  { id: 'codex', label: 'Codex' },
+  { id: 'opencode', label: 'OpenCode' },
+] as const;
+
 export function AgentSignup({ product }: { product: AgentSignupProduct }) {
   const [origin, setOrigin] = useState(SITE_URL);
+  const [agent, setAgent] = useState<(typeof agents)[number]>(agents[0]);
   const [message, setMessage] = useState('');
   const prompt = useRef<HTMLTextAreaElement>(null);
   const text = agentSignupPrompt(product, origin);
+  const copied = message.startsWith('Copied.');
+
+  useEffect(() => { setOrigin(window.location.origin); }, []);
 
   async function copy() {
     try {
-      await navigator.clipboard.writeText(text);
-      setMessage('Copied. Paste it into your agent.');
+      await navigator.clipboard.writeText(agentSignupPrompt(product, window.location.origin));
+      setMessage('Copied. Paste it into your agent to get started.');
     } catch {
       prompt.current?.focus();
       prompt.current?.select();
@@ -23,22 +36,43 @@ export function AgentSignup({ product }: { product: AgentSignupProduct }) {
   }
 
   return (
-    <details className={s.root} onToggle={(event) => {
-      if (event.currentTarget.open) {
-        setOrigin(window.location.origin);
-        setMessage('');
-      }
-    }}>
-      <summary>Set up with my agent <span aria-hidden="true">↗</span></summary>
+    <section className={s.root} aria-label="Sign up with your agent">
+      <div className={s.agents} role="group" aria-label="Choose your coding agent">
+        {agents.map((option) => (
+          <button
+            className={s.agent}
+            key={option.id}
+            type="button"
+            aria-pressed={agent.id === option.id}
+            onClick={() => { setAgent(option); setMessage(''); }}
+          >
+            {option.id === 'any'
+              ? <Terminal className={s.logo} aria-hidden="true" />
+              : <AgentToolLogo className={s.logo} provider={option.id} />}
+            {option.label}
+          </button>
+        ))}
+      </div>
       <div className={s.panel}>
-        <p>Paste this into your coding agent. It handles setup; you approve sign-in and connections.</p>
-        <textarea ref={prompt} aria-label="Agent signup prompt" value={text} readOnly rows={5} />
-        <div className={s.actions}>
-          <button type="button" onClick={() => void copy()}>Copy prompt</button>
-          <a href={`/signup/agent/${product}`}>Read agent instructions</a>
+        <p className={s.heading}>Let your agent take it from here.</p>
+        <p className={s.instructions}>
+          Copy and paste this prompt into {agent.id === 'any' ? 'your coding agent' : agent.label}.
+          {' '}It handles setup. You approve sign-in and connections.
+        </p>
+        <div className={s.promptRow}>
+          <textarea ref={prompt} aria-label="Agent signup prompt" value={text} readOnly rows={4} />
+          <button className={s.copy} type="button" onClick={() => void copy()} aria-label="Copy prompt">
+            {copied ? <Check size={20} aria-hidden="true" /> : <Copy size={20} aria-hidden="true" />}
+            {copied ? 'Copied' : 'Copy'}
+          </button>
+        </div>
+        <div className={s.footer}>
+          <p className={s.status} role="status">{message || (product === 'teams'
+            ? 'Use an agent on your Mac to install and connect the app.'
+            : 'Use an agent with terminal access to configure your first flow.')}</p>
+          <a href={`/signup/agent/${product}`}>Read agent instructions <ArrowUpRight size={14} aria-hidden="true" /></a>
         </div>
-        <p className={s.status} role="status">{message}</p>
       </div>
-    </details>
+    </section>
   );
 }
diff --git a/web/components/agent-signup.module.css b/web/components/agent-signup.module.css
index 097f7316..263ef998 100644
--- a/web/components/agent-signup.module.css
+++ b/web/components/agent-signup.module.css
@@ -1,12 +1,106 @@
-.root { width: min(100%, 520px); margin: 18px auto 0; color: #c3d6e4; text-align: left; }
-.root summary { width: fit-content; margin: 0 auto; cursor: pointer; font-size: 15px; text-underline-offset: 5px; }
-.root summary:hover { color: #fff; text-decoration: underline; }
-.root summary:focus-visible, .actions button:focus-visible, .actions a:focus-visible { outline: 2px solid #9bd0ed; outline-offset: 5px; }
-.root summary span { margin-left: 5px; }
-.panel { margin-top: 16px; padding: 20px; border: 1px solid #426077; border-radius: 12px; background: #102a3d; }
-.panel p { margin: 0 0 14px; font-size: 14px; line-height: 1.65; }
-.panel textarea { box-sizing: border-box; width: 100%; min-height: 145px; padding: 12px; resize: vertical; border: 1px solid #426077; border-radius: 6px; background: #091d2b; color: #e4f0f8; font: 13px/1.7 var(--font-mono), monospace; }
-.actions { display: flex; flex-wrap: wrap; align-items: center; gap: 16px; margin-top: 14px; font-size: 13px; }
-.actions button { border: 1px solid #85b8d7; border-radius: 6px; padding: 9px 14px; background: #c1e4f6; color: #102333; cursor: pointer; font: inherit; font-weight: 600; }
-.actions a { color: #c1e4f6; text-underline-offset: 4px; }
-.panel .status { margin: 8px 0 0; min-height: 22px; font-size: 12px; }
+.root {
+  width: 100%;
+  min-width: 0;
+  margin: 30px auto 0;
+  color: #c3d6e4;
+  text-align: left;
+}
+
+.agents {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 18px;
+}
+
+.agent {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  padding: 11px 18px;
+  border: 1px solid transparent;
+  border-radius: 999px;
+  background: transparent;
+  color: #c3d6e4;
+  font: inherit;
+  font-size: 16px;
+  cursor: pointer;
+  transition: background 150ms ease, border-color 150ms ease;
+}
+
+.agent:hover { background: #ffffff0a; color: #fff; }
+.agent[aria-pressed='true'] { border-color: #7096b0; background: #a1d2f01c; color: #f3f9fd; }
+.logo { width: 24px; height: 24px; flex-shrink: 0; }
+.root button:focus-visible, .root a:focus-visible, .root textarea:focus-visible { outline: 2px solid #9bd0ed; outline-offset: 4px; }
+
+.panel {
+  padding: 26px;
+  border: 1px solid #36556c;
+  border-radius: 22px;
+  background: #0b2031;
+  box-shadow: 0 12px 32px #03111b1a;
+}
+
+.panel .heading { margin: 0 0 8px; color: #f0f7fc; font-size: 23px; font-weight: 500; line-height: 1.3; }
+.panel .instructions { margin: 0 0 22px; font-size: 15px; line-height: 1.6; }
+.promptRow { display: flex; overflow: hidden; border: 1px solid #395970; border-radius: 14px; background: #19364b; }
+.promptRow:focus-within { overflow: visible; }
+.promptRow textarea {
+  box-sizing: border-box;
+  display: block;
+  width: 100%;
+  min-width: 0;
+  min-height: 156px;
+  field-sizing: content;
+  padding: 20px 22px;
+  resize: vertical;
+  border: 0;
+  border-radius: 14px 0 0 14px;
+  background: transparent;
+  color: #f0f7fc;
+  font: inherit;
+  font-size: 18px;
+  line-height: 1.65;
+}
+.copy {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  min-width: 118px;
+  padding: 20px;
+  border: 0;
+  border-left: 1px solid #395970;
+  border-radius: 0 14px 14px 0;
+  background: #ffffff04;
+  color: #c1e4f6;
+  font: inherit;
+  font-size: 17px;
+  font-weight: 500;
+  cursor: pointer;
+}
+.copy:hover { background: #a1d2f014; color: #fff; }
+.footer { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: 8px 18px; margin-top: 16px; font-size: 12px; line-height: 1.6; }
+.footer .status { margin: 0; }
+.footer a { display: inline-flex; align-items: center; gap: 4px; color: #c1e4f6; text-underline-offset: 4px; }
+
+@media (max-width: 600px) {
+  .root { margin-top: 24px; }
+  .agents { justify-content: flex-start; gap: 8px 4px; margin-bottom: 14px; }
+  .agent { padding: 9px 12px; font-size: 14px; gap: 8px; }
+  .logo { width: 20px; height: 20px; }
+  .panel { padding: 20px 16px; border-radius: 18px; }
+  .panel .heading { font-size: 21px; }
+  .panel .instructions { font-size: 14px; margin-bottom: 18px; }
+  .promptRow { flex-direction: column; }
+  .promptRow textarea { min-height: 245px; padding: 16px; border-radius: 14px 14px 0 0; font-size: 16px; }
+  .copy { min-height: 52px; padding: 12px; border-top: 1px solid #395970; border-left: 0; border-radius: 0 0 14px 14px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .agent { transition: none; }
+}

From 0094d14826c61987772a2c78fe80b5e9ed3c4be6 Mon Sep 17 00:00:00 2001
From: Barry Cape <barryonthecape@icloud.com>
Date: Sun, 20 Sep 2026 22:06:03 -0700
Subject: [PATCH 04/10] Add live agent signup journey with evolving Relay
 animation

---
 web/app/flows/page.tsx                        |   5 +-
 web/app/signup/[product]/page.tsx             |  17 ++
 web/app/teams/page.tsx                        |   2 +-
 web/app/teams/teams-landing.module.css        |   4 +-
 web/components/AgentSignup.tsx                |  81 ++------
 web/components/AgentSignupJourney.tsx         | 189 ++++++++++++++++++
 web/components/SignupAtmosphere.tsx           | 157 +++++++++++++++
 web/components/SiteNav.tsx                    |   5 +-
 .../agent-signup-journey.module.css           |  55 +++++
 web/components/agent-signup.module.css        | 116 ++---------
 web/e2e/agent-signup.spec.ts                  |  80 ++++++++
 web/lib/agent-signup-progress.ts              |  38 ++++
 web/lib/agent-signup.ts                       |  44 ++++
 web/lib/relay-mark.ts                         |   5 +
 web/lib/test/agent-signup-progress.test.ts    |  26 +++
 15 files changed, 643 insertions(+), 181 deletions(-)
 create mode 100644 web/app/signup/[product]/page.tsx
 create mode 100644 web/components/AgentSignupJourney.tsx
 create mode 100644 web/components/SignupAtmosphere.tsx
 create mode 100644 web/components/agent-signup-journey.module.css
 create mode 100644 web/e2e/agent-signup.spec.ts
 create mode 100644 web/lib/agent-signup-progress.ts
 create mode 100644 web/lib/relay-mark.ts
 create mode 100644 web/lib/test/agent-signup-progress.test.ts

diff --git a/web/app/flows/page.tsx b/web/app/flows/page.tsx
index f4fc2646..c0032bec 100644
--- a/web/app/flows/page.tsx
+++ b/web/app/flows/page.tsx
@@ -95,11 +95,8 @@ export default function FlowsPage() {
                 Try Free with Cloud
                 <ArrowRight aria-hidden="true" size={17} strokeWidth={2} />
               </a>
-              <a href="/khaliq" className={s.ctaSecondary}>
-                Chat with founders
-              </a>
+              <AgentSignup product="flows" />
             </div>
-            <AgentSignup product="flows" />
           </div>
         </section>
 
diff --git a/web/app/signup/[product]/page.tsx b/web/app/signup/[product]/page.tsx
new file mode 100644
index 00000000..7d4da2a0
--- /dev/null
+++ b/web/app/signup/[product]/page.tsx
@@ -0,0 +1,17 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { isAgentSignupProduct } from '../../../lib/agent-signup';
+import { AgentSignupJourney } from '../../../components/AgentSignupJourney';
+
+export const metadata: Metadata = {
+  title: 'Let your agent do it',
+  description: 'Give your agent a prompt and watch it set up Agent Relay.',
+  robots: { index: false, follow: false },
+  referrer: 'no-referrer',
+};
+
+export default async function AgentSignupPage({ params }: { params: Promise<{ product: string }> }) {
+  const { product } = await params;
+  if (!isAgentSignupProduct(product)) notFound();
+  return <AgentSignupJourney product={product} />;
+}
diff --git a/web/app/teams/page.tsx b/web/app/teams/page.tsx
index 9a7df2a7..382dc095 100644
--- a/web/app/teams/page.tsx
+++ b/web/app/teams/page.tsx
@@ -67,9 +67,9 @@ export default function TeamsPage() {
                 <a className={home.ctaPrimary} href={signupHref}>
                   {signupLabel}
                 </a>
+                <AgentSignup product="teams" />
                 <p className={s.signupNote}>No credit card required</p>
               </div>
-              <AgentSignup product="teams" />
             </div>
           </section>
 
diff --git a/web/app/teams/teams-landing.module.css b/web/app/teams/teams-landing.module.css
index eea4ebe9..c748e2fd 100644
--- a/web/app/teams/teams-landing.module.css
+++ b/web/app/teams/teams-landing.module.css
@@ -101,5 +101,5 @@
   .sessionScreenshot a { border-radius: 8px; }
 }
 
-.page .signupCtas { flex-direction: column; align-items: center; gap: 12px; }
-.signupNote { margin: 0; color: var(--flows-muted); font-size: 13px; line-height: 1.5; }
+.page .signupCtas { flex-direction: row; align-items: center; gap: 12px; }
+.signupNote { flex-basis: 100%; margin: 0; color: var(--flows-muted); font-size: 13px; line-height: 1.5; }
diff --git a/web/components/AgentSignup.tsx b/web/components/AgentSignup.tsx
index d2d67543..da5ccda7 100644
--- a/web/components/AgentSignup.tsx
+++ b/web/components/AgentSignup.tsx
@@ -1,78 +1,21 @@
 'use client';
 
-import { useEffect, useRef, useState } from 'react';
-import { ArrowUpRight, Check, Copy, Terminal } from 'lucide-react';
+import Link from 'next/link';
+import Grok from '@lobehub/icons/es/Grok';
 import { AgentToolLogo } from './AgentToolLogos';
-import { agentSignupPrompt, type AgentSignupProduct } from '../lib/agent-signup';
-import { SITE_URL } from '../lib/site';
+import type { AgentSignupProduct } from '../lib/agent-signup';
 import s from './agent-signup.module.css';
 
-const agents = [
-  { id: 'any', label: 'Agent setup' },
-  { id: 'claude', label: 'Claude Code' },
-  { id: 'codex', label: 'Codex' },
-  { id: 'opencode', label: 'OpenCode' },
-] as const;
-
 export function AgentSignup({ product }: { product: AgentSignupProduct }) {
-  const [origin, setOrigin] = useState(SITE_URL);
-  const [agent, setAgent] = useState<(typeof agents)[number]>(agents[0]);
-  const [message, setMessage] = useState('');
-  const prompt = useRef<HTMLTextAreaElement>(null);
-  const text = agentSignupPrompt(product, origin);
-  const copied = message.startsWith('Copied.');
-
-  useEffect(() => { setOrigin(window.location.origin); }, []);
-
-  async function copy() {
-    try {
-      await navigator.clipboard.writeText(agentSignupPrompt(product, window.location.origin));
-      setMessage('Copied. Paste it into your agent to get started.');
-    } catch {
-      prompt.current?.focus();
-      prompt.current?.select();
-      setMessage('Select and copy the prompt, then paste it into your agent.');
-    }
-  }
-
   return (
-    <section className={s.root} aria-label="Sign up with your agent">
-      <div className={s.agents} role="group" aria-label="Choose your coding agent">
-        {agents.map((option) => (
-          <button
-            className={s.agent}
-            key={option.id}
-            type="button"
-            aria-pressed={agent.id === option.id}
-            onClick={() => { setAgent(option); setMessage(''); }}
-          >
-            {option.id === 'any'
-              ? <Terminal className={s.logo} aria-hidden="true" />
-              : <AgentToolLogo className={s.logo} provider={option.id} />}
-            {option.label}
-          </button>
-        ))}
-      </div>
-      <div className={s.panel}>
-        <p className={s.heading}>Let your agent take it from here.</p>
-        <p className={s.instructions}>
-          Copy and paste this prompt into {agent.id === 'any' ? 'your coding agent' : agent.label}.
-          {' '}It handles setup. You approve sign-in and connections.
-        </p>
-        <div className={s.promptRow}>
-          <textarea ref={prompt} aria-label="Agent signup prompt" value={text} readOnly rows={4} />
-          <button className={s.copy} type="button" onClick={() => void copy()} aria-label="Copy prompt">
-            {copied ? <Check size={20} aria-hidden="true" /> : <Copy size={20} aria-hidden="true" />}
-            {copied ? 'Copied' : 'Copy'}
-          </button>
-        </div>
-        <div className={s.footer}>
-          <p className={s.status} role="status">{message || (product === 'teams'
-            ? 'Use an agent on your Mac to install and connect the app.'
-            : 'Use an agent with terminal access to configure your first flow.')}</p>
-          <a href={`/signup/agent/${product}`}>Read agent instructions <ArrowUpRight size={14} aria-hidden="true" /></a>
-        </div>
-      </div>
-    </section>
+    <Link className={s.button} href={`/signup/${product}`}>
+      <span className={s.icons} aria-hidden="true">
+        <span><AgentToolLogo provider="codex" className={s.logo} /></span>
+        <span><AgentToolLogo provider="claude" className={s.logo} /></span>
+        <span><Grok size={24} /></span>
+        <span><AgentToolLogo provider="opencode" className={s.logo} /></span>
+      </span>
+      Let your agent do it
+    </Link>
   );
 }
diff --git a/web/components/AgentSignupJourney.tsx b/web/components/AgentSignupJourney.tsx
new file mode 100644
index 00000000..9d82904d
--- /dev/null
+++ b/web/components/AgentSignupJourney.tsx
@@ -0,0 +1,189 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import Link from 'next/link';
+import Grok from '@lobehub/icons/es/Grok';
+import { ArrowLeft, ArrowUpRight, Check, Copy, RefreshCw } from 'lucide-react';
+import { AgentToolLogo } from './AgentToolLogos';
+import { SignupAtmosphere } from './SignupAtmosphere';
+import type { AgentSignupProduct } from '../lib/agent-signup';
+import { isSignupProgress, signupSteps, trackedSignupPrompt, type SignupProgress, type SignupSession } from '../lib/agent-signup-progress';
+import { teamsCloudUrl } from '../lib/teams-cloud';
+import s from './agent-signup-journey.module.css';
+
+const apiPath = teamsCloudUrl('/api/v1/signup/agent/sessions');
+const storageKey = (product: string) => `agent-relay-signup:${product}`;
+
+class ProgressError extends Error {
+  constructor(message: string, readonly retryAfterMs = 6000, readonly expired = false) { super(message); }
+}
+
+async function readProgress(id: string, signal?: AbortSignal): Promise<SignupProgress> {
+  const response = await fetch(`${apiPath}/${encodeURIComponent(id)}`, { cache: 'no-store', signal });
+  if (response.status === 404) throw new ProgressError('This setup session has expired. Start a new session to continue.', 0, true);
+  if (!response.ok) {
+    const retry = response.headers.get('retry-after');
+    const seconds = Number(retry);
+    const delay = retry ? (Number.isFinite(seconds) ? seconds * 1000 : Date.parse(retry) - Date.now()) : 6000;
+    throw new ProgressError('Updates are temporarily unavailable. Your agent can keep working.', Number.isFinite(delay) ? Math.max(3000, delay) : 6000);
+  }
+  const data: unknown = await response.json();
+  if (!isSignupProgress(data)) throw new Error('Could not read setup progress. Retrying shortly.');
+  return data;
+}
+
+async function startSession(product: AgentSignupProduct): Promise<{ progress: SignupProgress; token?: string }> {
+  const requestedId = new URL(window.location.href).searchParams.get('session');
+  let saved: SignupSession | undefined;
+  try {
+    const value: unknown = JSON.parse(sessionStorage.getItem(storageKey(product)) || 'null');
+    if (isSignupProgress(value) && value.product === product && 'writeToken' in value &&
+        typeof value.writeToken === 'string' && /^[a-f0-9]{64}$/.test(value.writeToken)) saved = value as SignupSession;
+  } catch { /* Storage may be disabled; the current tab can still run setup. */ }
+  const id = requestedId || saved?.id;
+  if (id) {
+    const progress = await readProgress(id, AbortSignal.timeout(10_000));
+    if (progress.product !== product) throw new Error('This session belongs to a different product. Start a new session below.');
+    return { progress, token: saved?.id === id ? saved.writeToken : undefined };
+  }
+  const response = await fetch(apiPath, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ product }), signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) throw new Error('Could not start a setup session. Please try again.');
+  const session: unknown = await response.json();
+  if (!isSignupProgress(session) || session.product !== product || !('writeToken' in session) ||
+      typeof session.writeToken !== 'string' || !/^[a-f0-9]{64}$/.test(session.writeToken)) throw new Error('Could not start a setup session. Please try again.');
+  try { sessionStorage.setItem(storageKey(product), JSON.stringify(session)); } catch { /* Best effort reload recovery. */ }
+  return { progress: session, token: session.writeToken };
+}
+
+export function AgentSignupJourney({ product }: { product: AgentSignupProduct }) {
+  const [progress, setProgress] = useState<SignupProgress>();
+  const [token, setToken] = useState<string>();
+  const [origin, setOrigin] = useState('');
+  const [error, setError] = useState('');
+  const [copyMessage, setCopyMessage] = useState('');
+  const [expired, setExpired] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+  const [showPrompt, setShowPrompt] = useState(false);
+  const textarea = useRef<HTMLTextAreaElement>(null);
+  const boot = useRef<ReturnType<typeof startSession> | null>(null);
+  const steps = signupSteps[product];
+  const complete = progress?.state === 'complete';
+  const active = progress?.step || 0;
+  const paused = progress?.state === 'waiting' && active > 0;
+  const failed = progress?.state === 'failed';
+  const endpoint = origin ? new URL(apiPath, origin).href : '';
+  const prompt = progress && token ? trackedSignupPrompt(product, origin, endpoint, { id: progress.id, writeToken: token }) : '';
+
+  useEffect(() => {
+    let cancelled = false;
+    setOrigin(window.location.origin);
+    // Keep a single creation request through React StrictMode's effect replay.
+    boot.current ||= startSession(product);
+    void boot.current.then(({ progress: initial, token: writeToken }) => {
+      if (cancelled) return;
+      setProgress(initial); setToken(writeToken); setError('');
+      const url = new URL(window.location.href);
+      url.searchParams.set('session', initial.id);
+      window.history.replaceState(window.history.state, '', url);
+    }).catch((cause) => {
+      if (!cancelled) {
+        setError(cause instanceof Error && cause.name !== 'TimeoutError' ? cause.message : 'We couldn’t start live setup. Check your connection and try again.');
+        if (cause instanceof ProgressError && cause.expired) setExpired(true);
+      }
+    });
+    return () => { cancelled = true; };
+  }, [product, attempt]);
+
+  useEffect(() => {
+    if (!progress || complete) return;
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout>;
+    const controller = new AbortController();
+    const poll = async () => {
+      let delay = 3000;
+      if (Date.now() >= Date.parse(progress.expiresAt)) { setExpired(true); return; }
+      try {
+        const next = await readProgress(progress.id, AbortSignal.any([controller.signal, AbortSignal.timeout(10_000)]));
+        if (cancelled) return;
+        if (next.product !== product) throw new Error('This session belongs to another product.');
+        setProgress(previous => !previous || next.revision >= previous.revision ? next : previous);
+        setError('');
+        if (next.state === 'complete') return;
+      } catch (cause) {
+        if (cancelled) return;
+        if (cause instanceof ProgressError && cause.expired) { setExpired(true); return; }
+        delay = cause instanceof ProgressError ? cause.retryAfterMs : 6000;
+        setError(cause instanceof Error && cause.name !== 'TimeoutError' ? cause.message : 'Updates are temporarily unavailable. Retrying shortly.');
+      }
+      if (!cancelled) timer = setTimeout(() => void poll(), Math.min(delay, Math.max(0, Date.parse(progress.expiresAt) - Date.now())));
+    };
+    timer = setTimeout(() => void poll(), 1500);
+    return () => { cancelled = true; clearTimeout(timer); controller.abort(); };
+  }, [progress?.id, progress?.expiresAt, complete, product]);
+
+  async function copy() {
+    try { await navigator.clipboard.writeText(prompt); setCopyMessage('Copied. Paste it into your agent.'); }
+    catch { setShowPrompt(true); setCopyMessage('Select and copy the prompt below.'); requestAnimationFrame(() => { textarea.current?.focus(); textarea.current?.select(); }); }
+  }
+  function restart() {
+    try { sessionStorage.removeItem(storageKey(product)); } catch { /* Best effort. */ }
+    window.location.assign(window.location.pathname);
+  }
+  const title = expired ? 'Session expired' : complete ? 'You’re all set.' : failed ? 'Your agent needs a hand.' : paused ? 'A quick approval from you.' : active ? steps[active - 1].title : 'Waiting for your agent';
+  const detail = expired ? 'Start a new session to keep watching setup.' : complete ? 'Your agent has verified setup. You’re ready to go.' : failed ? 'Check your agent’s conversation to resolve the issue. Progress will resume here.' : paused ? 'Follow the approval request in your agent’s conversation. We’ll pick up right here.' : active ? steps[active - 1].detail : 'The show starts when you paste the prompt into your agent.';
+  const mode = expired || error ? 'offline' : complete ? 'complete' : failed ? 'failed' : paused ? 'paused' : active ? 'working' : 'waiting';
+
+  const heading = complete ? 'All yours.' : active ? title : 'Leave it to your agent.';
+
+  return (
+    <div className={s.page} data-mode={mode}>
+      <SignupAtmosphere className={s.atmosphere} step={complete ? 6 : active} mode={mode} />
+      <Link href={`/${product}`} className={s.back} aria-label={`Back to ${product}`}><ArrowLeft size={18} /></Link>
+      <main className={s.main}>
+        <div className={s.content}>
+          <h1>{heading}</h1>
+          <p className={s.subtitle}>{complete ? 'Your agent has verified setup. You’re ready to go.' : active ? detail : 'Give this prompt to your coding agent and hang out here to watch it sign you up.'}</p>
+          {!complete && !active && (
+            <div className={s.agents} role="img" aria-label="Codex, Claude Code, Grok, and OpenCode">
+              <span title="Codex"><AgentToolLogo provider="codex" className={s.agentLogo} /></span>
+              <span title="Claude Code"><AgentToolLogo provider="claude" className={s.agentLogo} /></span>
+              <span title="Grok"><Grok size={28} /></span>
+              <span title="OpenCode"><AgentToolLogo provider="opencode" className={s.agentLogo} /></span>
+            </div>
+          )}
+          {complete ? <a className={s.primary} href={teamsCloudUrl(product === 'teams' ? '/dashboard/sessions' : '/dashboard')}>Open {product === 'teams' ? 'your workspace' : 'dashboard'} <ArrowUpRight size={17} /></a>
+            : !active ? <button type="button" className={s.primary} disabled={!prompt || expired} onClick={() => void copy()}>{copyMessage.startsWith('Copied') ? <Check size={17} /> : <Copy size={17} />}{copyMessage.startsWith('Copied') ? 'Prompt copied' : 'Copy setup prompt'}</button> : null}
+          <p className={s.copyStatus} role="status">{complete ? '' : active ? (paused ? 'Your agent will continue after you approve.' : 'You can leave this page open.') : copyMessage || (progress && !token ? 'Watching this session. The prompt is in the original browser tab.' : product === 'teams' ? 'Paste into a coding agent on your Mac.' : 'Paste into a coding agent with terminal access.')}</p>
+          <div className={s.progress} role="status" aria-live="polite">
+            <div className={s.progressDots} aria-hidden="true">{steps.map((step, index) => <i key={step.title} data-done={complete || active > index + 1} data-current={!complete && active === index + 1} />)}</div>
+            <span>{expired ? 'Session expired' : error ? 'Waiting for a connection' : complete ? 'Setup complete' : active ? `${active} of 5 · ${paused ? 'Waiting for your approval' : failed ? 'Needs your attention' : steps[active - 1].title}` : progress ? 'Ready when your agent is' : 'Preparing your session…'}</span>
+          </div>
+          {error && <div className={s.error} role="alert"><p>{error}</p>{!progress && <button type="button" onClick={() => { boot.current = null; setError(''); setAttempt(value => value + 1); }}>Try again <RefreshCw size={12} /></button>}</div>}
+          <details className={s.details}>
+            <summary>Setup details</summary>
+            <div className={s.detailBody}>
+              <ol className={s.steps}>{[...steps, { title: 'Ready to go' }].map((step, index) => {
+                const done = complete || active > index + 1;
+                const current = complete ? index === 5 : active === index + 1;
+                return <li key={step.title} data-done={done} aria-current={current ? 'step' : undefined}>
+                  <span className={s.stepCircle}>{done ? <Check size={13} aria-label="Complete" /> : index + 1}</span>
+                  <span className={s.stepLabel}>{step.title}</span>
+                </li>;
+              })}</ol>
+              {progress && <p className={s.session}>Session <code>{progress.id}</code></p>}
+              <p>Live updates are reported by your agent.</p>
+              <a href={`/signup/agent/${product}`}>Agent instructions <ArrowUpRight size={12} /></a>
+              <button type="button" onClick={() => setShowPrompt(value => !value)} disabled={!prompt}>{showPrompt ? 'Hide prompt' : 'View prompt'}</button>
+              <button type="button" onClick={restart}>Start a new session</button>
+            </div>
+          </details>
+          {showPrompt && prompt && <textarea data-ph-no-capture className={s.prompt} ref={textarea} aria-label="Agent signup prompt" value={prompt} readOnly spellCheck={false} rows={12} />}
+          {expired && <button type="button" className={s.restart} onClick={restart}>Start a new session <RefreshCw size={13} /></button>}
+        </div>
+      </main>
+    </div>
+  );
+}
diff --git a/web/components/SignupAtmosphere.tsx b/web/components/SignupAtmosphere.tsx
new file mode 100644
index 00000000..49c2b291
--- /dev/null
+++ b/web/components/SignupAtmosphere.tsx
@@ -0,0 +1,157 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { RELAY_MARK_PATHS } from '../lib/relay-mark';
+
+type Props = { step: number; mode: string; className: string };
+const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(max, value));
+
+/** The actual Relay mark, woven from responsive ribbons of light. */
+export function SignupAtmosphere({ step, mode, className }: Props) {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const state = useRef({ step, mode });
+  state.current = { step, mode };
+
+  useEffect(() => {
+    const element = canvas.current;
+    const ctx = element?.getContext('2d');
+    if (!element || !ctx) return;
+    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const finePointer = window.matchMedia('(pointer: fine)');
+    // Sample the canonical paths once. No approximated logo or per-frame DOM work.
+    const shapes = RELAY_MARK_PATHS.map((d, index) => {
+      const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      path.setAttribute('d', d);
+      const length = path.getTotalLength();
+      return {
+        fill: new Path2D(d), centerX: index === 0 ? 37 : 89,
+        points: Array.from({ length: 193 }, (_, i) => {
+          const point = path.getPointAtLength(i / 192 * length);
+          return { x: point.x, y: point.y };
+        }),
+      };
+    });
+    let frame = 0; let width = 0; let height = 0;
+    let phase = 0; let last = 0; let staticFrame = '';
+    let shownStep = state.current.step;
+    let assembled = state.current.mode === 'complete' ? 1 : 0;
+    let hover = 0; let driftX = 0; let driftY = 0; let kickX = 0; let kickY = 0;
+    const pointer = { x: 0, y: 0, inside: false, lastX: 0, lastY: 0, lastTime: 0 };
+    const centerY = () => Math.min(height * .29, 260);
+    const baseSize = () => Math.min(width * .7, height * .44, 440);
+    const resize = () => {
+      width = element.clientWidth; height = element.clientHeight;
+      const ratio = Math.min(window.devicePixelRatio || 1, 1.5);
+      element.width = Math.round(width * ratio); element.height = Math.round(height * ratio);
+      staticFrame = '';
+      ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+    };
+    const move = (event: PointerEvent) => {
+      if (reduced.matches || !finePointer.matches || event.pointerType === 'touch') return;
+      const rect = element.getBoundingClientRect();
+      const x = event.clientX - rect.left; const y = event.clientY - rect.top;
+      const size = baseSize();
+      pointer.inside = size > 0 && Math.hypot((x - width / 2) / (size * .65), (y - centerY()) / (size * .55)) < 1;
+      if (pointer.inside) {
+        pointer.x = clamp((x - width / 2) / size, -.6, .6);
+        pointer.y = clamp((y - centerY()) / size, -.6, .6);
+        const elapsed = event.timeStamp - pointer.lastTime;
+        if (elapsed > 0 && elapsed < 120) {
+          kickX = clamp(kickX + (x - pointer.lastX) / elapsed * 3, -18, 18);
+          kickY = clamp(kickY + (y - pointer.lastY) / elapsed * 3, -18, 18);
+        }
+      }
+      pointer.lastX = x; pointer.lastY = y; pointer.lastTime = event.timeStamp;
+    };
+    const leave = () => { pointer.inside = false; pointer.lastTime = 0; };
+    const observer = new ResizeObserver(resize);
+    observer.observe(element); resize();
+    window.addEventListener('pointermove', move, { passive: true });
+    document.documentElement.addEventListener('pointerleave', leave);
+    window.addEventListener('blur', leave);
+
+    function draw(time: number) {
+      frame = requestAnimationFrame(draw);
+      if (document.hidden || time - last < 32) return;
+      const delta = Math.min(time - last, 50); last = time;
+      const current = state.current;
+      const motion = !reduced.matches && current.mode !== 'offline';
+      const complete = current.mode === 'complete';
+      const warm = current.mode === 'paused' || current.mode === 'failed';
+      const smooth = motion ? 1 - Math.exp(-delta / 650) : 1;
+      shownStep += (current.step - shownStep) * smooth;
+      assembled += ((complete ? 1 : 0) - assembled) * (motion ? 1 - Math.exp(-delta / 950) : 1);
+      if (assembled > .999) assembled = 1;
+      const progress = clamp(shownStep / 5, 0, 1);
+      if (motion) phase += delta * (warm ? .00008 : .00012 + progress * .00032) * (1 - assembled);
+      hover += ((pointer.inside && motion ? 1 : 0) - hover) * .09;
+      driftX += ((motion ? pointer.x * hover : 0) - driftX) * .075;
+      driftY += ((motion ? pointer.y * hover : 0) - driftY) * .075;
+      kickX *= .91; kickY *= .91;
+      if (!motion) { hover = 0; driftX = 0; driftY = 0; kickX = 0; kickY = 0; }
+      const frameKey = `${width}:${height}:${current.step}:${current.mode}`;
+      if (!motion && frameKey === staticFrame) return;
+      staticFrame = motion ? '' : frameKey;
+      const size = baseSize() * (.86 + progress * .14);
+      const scale = size / 112;
+      const cx = width / 2; const cy = centerY();
+      ctx!.clearRect(0, 0, width, height);
+      const glow = ctx!.createRadialGradient(cx, cy, 0, cx, cy, size * 1.15);
+      glow.addColorStop(0, `rgba(67,145,192,${.1 + progress * .1 + hover * .035})`);
+      glow.addColorStop(.5, 'rgba(30,85,126,.065)'); glow.addColorStop(1, 'rgba(10,27,40,0)');
+      ctx!.fillStyle = glow; ctx!.fillRect(0, 0, width, height);
+      ctx!.save();
+      ctx!.translate(cx + driftX * 16, cy + driftY * 12);
+      ctx!.rotate(driftX * .07 * (1 - assembled * .7));
+      ctx!.globalCompositeOperation = 'screen';
+
+      shapes.forEach((shape, shapeIndex) => {
+        const tone = shapeIndex === 0 ? 1 : .55;
+        for (let line = 0; line < 48; line++) {
+          const strand = line / 47;
+          const emphasis = Math.pow(Math.sin(strand * Math.PI), 2);
+          // Loose silk outlines gradually knit inward into the two solid facets.
+          const contour = (1 - assembled) * (.77 + strand * .32) + assembled * (.08 + strand * .92);
+          ctx!.beginPath();
+          shape.points.forEach((point, index) => {
+            const t = index / 192 * Math.PI * 2;
+            const wave = (1 - assembled) * (1 + progress * .35);
+            const flowX = Math.sin(t * 2 + phase + strand * 2.4) * 3.5 + Math.cos(t * 3 - phase * .7) * 1.7;
+            const flowY = Math.sin(t * 3 + phase * .8 + strand * 3) * 3;
+            const x = (point.x - shape.centerX) * contour + shape.centerX - 56;
+            const y = (point.y - 45.5) * contour;
+            // Pointer velocity excites a traveling ripple, then damps naturally.
+            const ripple = Math.sin(t * 2 - phase * 1.5 + strand * 4) * hover;
+            const px = (x + flowX * wave) * scale + ripple * kickX * (1 - assembled * .8);
+            const py = (y + flowY * wave) * scale + ripple * kickY * (1 - assembled * .8);
+            if (index === 0) ctx!.moveTo(px, py); else ctx!.lineTo(px, py);
+          });
+          const hue = warm ? 36 + strand * 16 : 195 + strand * 19;
+          ctx!.strokeStyle = `hsla(${hue}, 64%, ${58 + emphasis * 22}%, ${( .035 + emphasis * (.17 + progress * .1)) * tone * (1 - assembled * .65)})`;
+          ctx!.lineWidth = .7 + progress * .18;
+          ctx!.stroke();
+        }
+        // Resolve into the exact brand silhouette only on reported completion.
+        if (assembled > .01) {
+          ctx!.save();
+          ctx!.scale(scale, scale); ctx!.translate(-56, -45.5);
+          const fill = ctx!.createLinearGradient(25, 0, 75, 91);
+          fill.addColorStop(0, '#b4e5ff'); fill.addColorStop(.5, '#79bde5'); fill.addColorStop(1, '#4485b0');
+          ctx!.globalAlpha = assembled * .9 * tone;
+          ctx!.fillStyle = fill; ctx!.fill(shape.fill);
+          ctx!.restore();
+        }
+      });
+      ctx!.restore();
+    }
+    frame = requestAnimationFrame(draw);
+    return () => {
+      cancelAnimationFrame(frame); observer.disconnect();
+      window.removeEventListener('pointermove', move);
+      document.documentElement.removeEventListener('pointerleave', leave);
+      window.removeEventListener('blur', leave);
+    };
+  }, []);
+
+  return <canvas ref={canvas} className={className} aria-hidden="true" />;
+}
diff --git a/web/components/SiteNav.tsx b/web/components/SiteNav.tsx
index baab760f..70841bac 100644
--- a/web/components/SiteNav.tsx
+++ b/web/components/SiteNav.tsx
@@ -6,6 +6,7 @@ import Link from 'next/link';
 import { usePathname } from 'next/navigation';
 
 import s from './site-nav.module.css';
+import { RELAY_MARK_PATHS } from '../lib/relay-mark';
 
 export function LogoIcon() {
   return (
@@ -20,11 +21,11 @@ export function LogoIcon() {
       <path
         fillRule="evenodd"
         clipRule="evenodd"
-        d="M71.3682 21.7098L54.042 39.036C50.6567 42.4213 50.6568 47.9099 54.042 51.2952L71.3727 68.6259L52.8321 87.1665C48.6005 91.3981 41.7397 91.3981 37.5081 87.1665L3.17369 52.8321C-1.05789 48.6005 -1.0579 41.7397 3.17369 37.5081L37.5081 3.17369C41.7397 -1.0579 48.6005 -1.05789 52.8321 3.17369L71.3682 21.7098Z"
+        d={RELAY_MARK_PATHS[0]}
         fill="currentColor"
       />
       <path
-        d="M75.5711 72.8243C78.9563 76.2096 84.445 76.2096 87.8302 72.8243L109.359 51.2952C112.745 47.9099 112.745 42.4213 109.359 39.036L87.8302 17.507C84.445 14.1218 78.9563 14.1218 75.5711 17.507L71.3682 21.7098L88.6989 39.0405C92.0842 42.4258 92.0842 47.9144 88.6989 51.2997L71.3727 68.6259L75.5711 72.8243Z"
+        d={RELAY_MARK_PATHS[1]}
         fill="currentColor"
         opacity="0.5"
       />
diff --git a/web/components/agent-signup-journey.module.css b/web/components/agent-signup-journey.module.css
new file mode 100644
index 00000000..4cfe6984
--- /dev/null
+++ b/web/components/agent-signup-journey.module.css
@@ -0,0 +1,55 @@
+.page { position: relative; isolation: isolate; min-height: 100svh; overflow-x: clip; background: #091b28; color: #e8f2fa; }
+.atmosphere { position: absolute; inset: 0; width: 100%; height: max(780px, 100svh); pointer-events: none; z-index: -1; }
+.back { position: absolute; top: 30px; z-index: 1; display: grid; place-items: center; color: #98b6ca; }
+.back { left: 32px; width: 40px; height: 40px; border-radius: 50%; text-decoration: none; }
+.back:hover { color: #fff; background: #ffffff06; opacity: 1; }
+.main { display: flex; justify-content: center; min-height: 100svh; padding: min(52svh, 460px) 24px 44px; box-sizing: border-box; }
+.content { width: min(100%, 600px); text-align: center; }
+.content h1 { margin: 0; font-family: var(--font-heading), sans-serif; font-size: clamp(32px, 4.5vw, 48px); font-weight: 400; line-height: 1.2; letter-spacing: -.055em; text-wrap: balance; }
+.subtitle { max-width: 410px; margin: 18px auto 28px; min-height: 48px; color: #a0b9ca; font-size: 15px; line-height: 1.7; text-wrap: pretty; }
+.agents { display: flex; justify-content: center; align-items: center; gap: 26px; min-height: 48px; margin: 18px auto 28px; color: #c5dbe9; }
+.agents > span { display: grid; place-items: center; }
+.agentLogo { width: 28px; height: 28px; }
+.primary { composes: btn btn-primary from global; }
+.primary:disabled { opacity: .45; cursor: default; transform: none; }
+.copyStatus { min-height: 20px; margin: 14px 0 0; color: #7899af; font-size: 11px; line-height: 1.7; }
+.progress { margin: 32px 0 0; color: #9eb9cb; font-size: 11px; line-height: 1.7; }
+.progressDots { display: flex; gap: 6px; justify-content: center; margin-bottom: 11px; }
+.progressDots i { width: 23px; height: 2px; border-radius: 3px; background: #294355; transition: background 1s; }
+.progressDots i[data-current='true'] { background: #8dc7e9; box-shadow: 0 0 10px #8dc7e94d; }
+.progressDots i[data-done='true'] { background: #9fceca; }
+.page[data-mode='paused'] .progressDots i[data-current='true'], .page[data-mode='failed'] .progressDots i[data-current='true'] { background: #d9b985; }
+.details { margin: 26px auto 0; max-width: 600px; text-align: center; color: #8aabbf; font-size: 11px; }
+.details summary { display: inline-block; list-style: none; cursor: pointer; padding: 8px 14px; color: #7897ab; }
+.details summary::-webkit-details-marker { display: none; }
+.details summary::after { content: '+'; display: inline-block; margin-left: 7px; font-size: 13px; }
+.details[open] summary::after { content: '−'; }
+.detailBody { padding: 16px 0; border-top: 1px solid #ffffff0d; margin-top: 8px; }
+.steps { display: grid; grid-template-columns: repeat(6, minmax(0, 1fr)); list-style: none; padding: 0; margin: 4px 0 26px; }
+.steps li { position: relative; display: flex; flex-direction: column; align-items: center; gap: 10px; min-width: 0; }
+.steps li:not(:last-child)::after { content: ''; position: absolute; top: 15px; left: calc(50% + 20px); width: calc(100% - 40px); height: 1px; background: #294355; }
+.stepCircle { display: grid; place-items: center; box-sizing: border-box; width: 31px; height: 31px; border: 1px solid #355266; border-radius: 50%; color: #8aabbf; font-size: 11px; }
+.stepLabel { max-width: 92px; padding: 0 4px; font-size: 10px; line-height: 1.5; text-wrap: balance; }
+.steps li[aria-current='step'] { color: #e5f2fa; }
+.steps li[aria-current='step'] .stepCircle { border-color: #8dc7e9; color: #e5f2fa; background: #8dc7e911; box-shadow: 0 0 18px #8dc7e914; }
+.steps li[data-done='true'] .stepCircle { border-color: #729d9a; color: #9fceca; background: #9fceca0d; }
+.steps li[data-done='true']::after { background: #729d9a; }
+.detailBody p { font-size: 10px; line-height: 1.7; }
+.session code { overflow-wrap: anywhere; font-size: 9px; }
+.detailBody a, .detailBody button { display: inline-flex; align-items: center; gap: 3px; border: 0; padding: 7px; background: transparent; color: #9cbace; font: inherit; cursor: pointer; text-underline-offset: 3px; }
+.detailBody button:disabled { opacity: .4; cursor: default; }
+.prompt { box-sizing: border-box; width: 100%; padding: 20px; margin-top: 20px; border: 1px solid #ffffff1c; border-radius: 10px; background: #071722; color: #bdd5e4; font: 11px/1.8 var(--font-geist-mono), monospace; resize: vertical; field-sizing: content; }
+.error { max-width: 380px; margin: 20px auto; color: #d5b78d; font-size: 12px; line-height: 1.7; }
+.error button, .restart { display: inline-flex; align-items: center; gap: 7px; border: 0; padding: 5px; background: transparent; color: #c6dce9; font: inherit; font-size: 12px; cursor: pointer; }
+@media (max-width: 600px) {
+  .back { top: 18px; }.back { left: 15px; }
+  .main { padding-top: 43svh; padding-bottom: 30px; }.atmosphere { height: 720px; }
+  .content h1 { font-size: 34px; }.subtitle { font-size: 14px; margin-bottom: 24px; }
+  .progress { margin-top: 26px; }.copyStatus { font-size: 10px; }
+}
+@media (max-height: 700px) and (min-width: 601px) {
+  .main { padding-top: 360px; }.atmosphere { height: 720px; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .page * { transition: none !important; }.primary:hover { transform: none; }
+}
diff --git a/web/components/agent-signup.module.css b/web/components/agent-signup.module.css
index 263ef998..80392620 100644
--- a/web/components/agent-signup.module.css
+++ b/web/components/agent-signup.module.css
@@ -1,106 +1,16 @@
-.root {
-  width: 100%;
-  min-width: 0;
-  margin: 30px auto 0;
-  color: #c3d6e4;
-  text-align: left;
+.button { composes: btn btn-secondary from global; gap: 12px; white-space: nowrap; }
+.icons { position: relative; display: inline-block; width: 24px; height: 24px; flex-shrink: 0; }
+.icons > span { position: absolute; inset: 0; display: grid; place-items: center; opacity: 0; animation: agentIcon 16s infinite; }
+.icons > span:nth-child(2) { animation-delay: 4s; }
+.icons > span:nth-child(3) { animation-delay: 8s; }
+.icons > span:nth-child(4) { animation-delay: 12s; }
+.logo { width: 24px; height: 24px; }
+@keyframes agentIcon {
+  0%, 20% { opacity: 1; transform: translateY(0) scale(1); }
+  25%, 95% { opacity: 0; transform: translateY(-4px) scale(.85); }
+  100% { opacity: 1; transform: translateY(0) scale(1); }
 }
-
-.agents {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: space-between;
-  gap: 8px;
-  margin-bottom: 18px;
-}
-
-.agent {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  gap: 10px;
-  padding: 11px 18px;
-  border: 1px solid transparent;
-  border-radius: 999px;
-  background: transparent;
-  color: #c3d6e4;
-  font: inherit;
-  font-size: 16px;
-  cursor: pointer;
-  transition: background 150ms ease, border-color 150ms ease;
-}
-
-.agent:hover { background: #ffffff0a; color: #fff; }
-.agent[aria-pressed='true'] { border-color: #7096b0; background: #a1d2f01c; color: #f3f9fd; }
-.logo { width: 24px; height: 24px; flex-shrink: 0; }
-.root button:focus-visible, .root a:focus-visible, .root textarea:focus-visible { outline: 2px solid #9bd0ed; outline-offset: 4px; }
-
-.panel {
-  padding: 26px;
-  border: 1px solid #36556c;
-  border-radius: 22px;
-  background: #0b2031;
-  box-shadow: 0 12px 32px #03111b1a;
-}
-
-.panel .heading { margin: 0 0 8px; color: #f0f7fc; font-size: 23px; font-weight: 500; line-height: 1.3; }
-.panel .instructions { margin: 0 0 22px; font-size: 15px; line-height: 1.6; }
-.promptRow { display: flex; overflow: hidden; border: 1px solid #395970; border-radius: 14px; background: #19364b; }
-.promptRow:focus-within { overflow: visible; }
-.promptRow textarea {
-  box-sizing: border-box;
-  display: block;
-  width: 100%;
-  min-width: 0;
-  min-height: 156px;
-  field-sizing: content;
-  padding: 20px 22px;
-  resize: vertical;
-  border: 0;
-  border-radius: 14px 0 0 14px;
-  background: transparent;
-  color: #f0f7fc;
-  font: inherit;
-  font-size: 18px;
-  line-height: 1.65;
-}
-.copy {
-  display: flex;
-  flex-shrink: 0;
-  align-items: center;
-  justify-content: center;
-  gap: 10px;
-  min-width: 118px;
-  padding: 20px;
-  border: 0;
-  border-left: 1px solid #395970;
-  border-radius: 0 14px 14px 0;
-  background: #ffffff04;
-  color: #c1e4f6;
-  font: inherit;
-  font-size: 17px;
-  font-weight: 500;
-  cursor: pointer;
-}
-.copy:hover { background: #a1d2f014; color: #fff; }
-.footer { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: 8px 18px; margin-top: 16px; font-size: 12px; line-height: 1.6; }
-.footer .status { margin: 0; }
-.footer a { display: inline-flex; align-items: center; gap: 4px; color: #c1e4f6; text-underline-offset: 4px; }
-
-@media (max-width: 600px) {
-  .root { margin-top: 24px; }
-  .agents { justify-content: flex-start; gap: 8px 4px; margin-bottom: 14px; }
-  .agent { padding: 9px 12px; font-size: 14px; gap: 8px; }
-  .logo { width: 20px; height: 20px; }
-  .panel { padding: 20px 16px; border-radius: 18px; }
-  .panel .heading { font-size: 21px; }
-  .panel .instructions { font-size: 14px; margin-bottom: 18px; }
-  .promptRow { flex-direction: column; }
-  .promptRow textarea { min-height: 245px; padding: 16px; border-radius: 14px 14px 0 0; font-size: 16px; }
-  .copy { min-height: 52px; padding: 12px; border-top: 1px solid #395970; border-left: 0; border-radius: 0 0 14px 14px; }
-}
-
 @media (prefers-reduced-motion: reduce) {
-  .agent { transition: none; }
+  .icons > span { animation: none; }
+  .icons > span:first-child { opacity: 1; }
 }
diff --git a/web/e2e/agent-signup.spec.ts b/web/e2e/agent-signup.spec.ts
new file mode 100644
index 00000000..69d5a89e
--- /dev/null
+++ b/web/e2e/agent-signup.spec.ts
@@ -0,0 +1,80 @@
+import { expect, test } from '@playwright/test';
+
+const id = '537e4857-5590-42e8-8731-66441b466542';
+const token = 'a'.repeat(64);
+
+test('agent signup stays still until reported progress, restores its session, and supports reduced motion', async ({ page }) => {
+  let creates = 0;
+  let progress = { id, product: 'teams', step: 0, state: 'waiting', revision: 0, updatedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 7200000).toISOString() };
+  await page.route('**/cloud/api/v1/signup/agent/sessions**', route => {
+    const create = route.request().method() === 'POST';
+    if (create) creates++;
+    return route.fulfill({ status: create ? 201 : 200, json: create ? {...progress, writeToken: token} : progress });
+  });
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+  await page.goto('/signup/teams');
+  await expect(page.getByRole('button', { name: 'Copy setup prompt' })).toBeEnabled();
+  await expect(page.getByText('Ready when your agent is')).toBeVisible();
+  await expect(page).toHaveURL(new RegExp(`session=${id}`));
+  await page.reload();
+  await expect(page.getByRole('button', { name: 'Copy setup prompt' })).toBeEnabled();
+  expect(creates).toBe(1);
+  const canvas = page.locator('canvas');
+  await expect.poll(() => canvas.evaluate(el => (el as HTMLCanvasElement).width)).toBeGreaterThan(0);
+  // Frames must remain identical when the OS requests reduced motion.
+  const before = await canvas.evaluate(el => (el as HTMLCanvasElement).toDataURL());
+  await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+  expect(await canvas.evaluate(el => (el as HTMLCanvasElement).toDataURL())).toBe(before);
+  progress = {...progress, step: 1, state: 'waiting', revision: 1};
+  await expect(page.getByRole('heading', { name: 'A quick approval from you.' })).toBeVisible();
+  await expect(page.getByText('1 of 5 · Waiting for your approval')).toBeVisible();
+  progress = {...progress, step: 2, state: 'working', revision: 2};
+  await expect(page.getByRole('heading', { name: 'Install the app', exact: true })).toBeVisible();
+  await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+  const reducedFrame = await canvas.evaluate(el => (el as HTMLCanvasElement).toDataURL());
+  await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+  expect(await canvas.evaluate(el => (el as HTMLCanvasElement).toDataURL())).toBe(reducedFrame);
+  progress = {...progress, step: 5, state: 'complete', revision: 6};
+  await expect(page.getByRole('heading', { name: 'All yours.' })).toBeVisible();
+  await expect(page.getByRole('link', { name: 'Open your workspace' })).toHaveAttribute('href', /\/cloud\/dashboard\/sessions$/);
+});
+
+test('clipboard failure reveals and selects the entire prompt', async ({ page }) => {
+  const progress = { id, product: 'flows', step: 0, state: 'waiting', revision: 0, updatedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 7200000).toISOString() };
+  await page.route('**/cloud/api/v1/signup/agent/sessions**', route => route.fulfill({status: route.request().method() === 'POST' ? 201 : 200, json: {...progress, writeToken: token}}));
+  await page.goto('/signup/flows');
+  await page.evaluate(() => Object.defineProperty(navigator, 'clipboard', { value: { writeText: () => Promise.reject(new Error('denied')) }, configurable: true }));
+  await page.getByRole('button', { name: 'Copy setup prompt' }).click();
+  const prompt = page.getByRole('textbox', { name: 'Agent signup prompt' });
+  await expect(prompt).toBeVisible();
+  await expect.poll(() => prompt.evaluate(el => (el as HTMLTextAreaElement).selectionEnd - (el as HTMLTextAreaElement).selectionStart)).toBe((await prompt.inputValue()).length);
+  expect(await prompt.inputValue()).toContain('/signup/agent/flows');
+});
+
+test('logo ribbons respond to pointer movement and settle into the completed mark', async ({ page }, testInfo) => {
+  let progress = { id, product: 'teams', step: 0, state: 'waiting', revision: 0, updatedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 7200000).toISOString() };
+  await page.route('**/cloud/api/v1/signup/agent/sessions**', route => route.fulfill({ status: route.request().method() === 'POST' ? 201 : 200, json: route.request().method() === 'POST' ? {...progress, writeToken: token} : progress }));
+  await page.setViewportSize({ width: 1000, height: 900 });
+  await page.goto('/signup/teams');
+  await expect(page.getByRole('button', { name: 'Copy setup prompt' })).toBeEnabled();
+  const canvas = page.locator('canvas');
+  await expect.poll(() => canvas.evaluate(el => (el as HTMLCanvasElement).width)).toBeGreaterThan(0);
+  await page.screenshot({ path: testInfo.outputPath('signup-logo-waiting.png') });
+  await page.mouse.move(340, 220);
+  await page.mouse.move(580, 300, { steps: 10 });
+  await page.screenshot({ path: testInfo.outputPath('signup-logo-swish.png') });
+  await page.mouse.move(20, 850);
+  progress = {...progress, step: 5, state: 'working', revision: 5};
+  await expect(page.getByRole('heading', { name: 'Check everything works' })).toBeVisible();
+  await page.screenshot({ path: testInfo.outputPath('signup-logo-verifying.png') });
+  progress = {...progress, state: 'complete', revision: 6};
+  await expect(page.getByRole('heading', { name: 'All yours.' })).toBeVisible();
+  // Completion should reveal a filled left facet, not leave a hollow ribbon.
+  await expect.poll(() => canvas.evaluate(el => {
+    const c = el as HTMLCanvasElement;
+    const context = c.getContext('2d')!;
+    const ratio = c.width / c.clientWidth;
+    return context.getImageData(Math.round(400 * ratio), Math.round(260 * ratio), 1, 1).data[3];
+  }), { timeout: 15000 }).toBeGreaterThan(180);
+  await page.screenshot({ path: testInfo.outputPath('signup-logo-complete.png') });
+});
diff --git a/web/lib/agent-signup-progress.ts b/web/lib/agent-signup-progress.ts
new file mode 100644
index 00000000..4177d08f
--- /dev/null
+++ b/web/lib/agent-signup-progress.ts
@@ -0,0 +1,38 @@
+import type { AgentSignupProduct } from './agent-signup';
+
+export type SignupProgress = {
+  id: string; product: AgentSignupProduct; step: number;
+  state: 'working' | 'waiting' | 'failed' | 'complete';
+  revision: number; updatedAt: string; expiresAt: string;
+};
+export type SignupSession = SignupProgress & { writeToken: string };
+
+export function isSignupProgress(value: unknown): value is SignupProgress {
+  if (!value || typeof value !== 'object') return false;
+  const p = value as SignupProgress;
+  return typeof p.id === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(p.id) &&
+    ['teams', 'flows'].includes(p.product) && Number.isInteger(p.step) && p.step >= 0 && p.step <= 5 &&
+    ['working', 'waiting', 'failed', 'complete'].includes(p.state) && (p.state !== 'complete' || p.step === 5) &&
+    Number.isSafeInteger(p.revision) && p.revision >= 0 && typeof p.updatedAt === 'string' && typeof p.expiresAt === 'string' && Number.isFinite(Date.parse(p.updatedAt)) && Number.isFinite(Date.parse(p.expiresAt));
+}
+
+export function trackedSignupPrompt(product: AgentSignupProduct, origin: string, endpoint: string, session: Pick<SignupSession, 'id' | 'writeToken'>) {
+  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Follow ${origin}/signup/agent/${product} and report your progress so I can watch here.\n\nProgress session: ${session.id}\nProgress API: ${endpoint}/${session.id}\nProgress token: ${session.writeToken}\n\nUse the progress protocol in the guide. Handle setup and verification; open sign-in and approval pages for me when needed.`;
+}
+
+export const signupSteps = {
+  teams: [
+    { title: 'Sign in', detail: 'Your agent opens Google. You approve access.' },
+    { title: 'Install the app', detail: 'Download, verify, and install Agent Relay on your Mac.' },
+    { title: 'Connect your workspace', detail: 'Link the app to your account and workspace.' },
+    { title: 'Choose what to share', detail: 'Your agent asks which sessions you want to share.' },
+    { title: 'Check everything works', detail: 'Verify the connection and open your workspace.' },
+  ],
+  flows: [
+    { title: 'Sign in', detail: 'Your agent opens Google. You approve access.' },
+    { title: 'Choose your flow', detail: 'Pick a workflow and the repository it should work on.' },
+    { title: 'Connect your tools', detail: 'Approve the services and coding agents your flow needs.' },
+    { title: 'Activate your flow', detail: 'Configure the workflow and its repository triggers.' },
+    { title: 'Check everything works', detail: 'Verify activation and open your dashboard.' },
+  ],
+} as const;
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 8d1ac105..0a428d29 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -26,6 +26,50 @@ Use this exact environment throughout; never fall back from local development
 to production. The Teams desktop app currently requires macOS 13 or later.
 Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
 
+## Live progress (when the user's prompt includes a progress session)
+
+The user is watching a setup page. Report real milestones using the Progress API
+and Progress token supplied in their prompt. The token authorizes progress only;
+it is NOT a Cloud access token. Never send account tokens, OAuth codes, passwords,
+logs, approval URLs, or personal information to the progress endpoint. Do not put
+the progress token in URLs or output it in your final reply. Use the same site
+and /cloud origin shown above; never forward it to another environment.
+
+GET the supplied Progress API URL to obtain the current revision and product.
+Check that the product matches this guide. Start by PATCHing that URL with
+Authorization: Bearer <Progress token> and Content-Type: application/json:
+
+~~~json
+{"step":1,"state":"working","revision":0}
+~~~
+
+Use the revision returned by the latest GET/PATCH, not the example's literal 0.
+PATCH before each numbered progress step below. A move to the next step marks
+the previous step done; do not skip steps or report success before checking it.
+Set state: waiting when you need the user to approve access or choose an option.
+Set state: working at the same step when you resume, and state: failed if work
+cannot continue. After completing step 5's verification, PATCH step: 5,
+state: complete. Only report complete after the actual checks succeed.
+
+${product === 'teams' ? `Progress steps for Teams:
+1. Sign in: before device authorization (section 1).
+2. Install the app: before download and installation (section 2).
+3. Connect the workspace: before cloud install (section 3).
+4. Choose what to share: before asking for/selecting sessions in section 3.
+   Report waiting while the user chooses. Respect an explicit choice to share none.
+5. Check everything works: before status, upload, and app verification (section 4).` : `Progress steps for Flows correspond to sections 1 through 5 below:
+1. Sign in. 2. Choose the flow/repository. 3. Connect tools.
+4. Activate the flow. 5. Verify the listening state.`}
+
+On HTTP 409, GET current progress and reconcile; never overwrite newer progress
+or regress a step. If a PATCH response is lost, GET before retrying. If a step is
+already complete, verify the actual account/app/flow state before continuing;
+progress reports alone are not proof that setup succeeded. On 429, honor
+Retry-After. Retry transient network/5xx failures with bounded backoff. On 404,
+stop reporting (the session expired or the token is invalid) and tell the user;
+do not recreate or switch their session silently. A progress service outage
+must not roll back working setup or cause duplicate installation/activation.
+
 ## 1. Sign up and obtain an API session
 
 Use the existing OAuth device flow. No API key, invitation, dashboard wizard,
diff --git a/web/lib/relay-mark.ts b/web/lib/relay-mark.ts
new file mode 100644
index 00000000..acef3c43
--- /dev/null
+++ b/web/lib/relay-mark.ts
@@ -0,0 +1,5 @@
+// Canonical Relay mark, shared by the navigation and signup animation.
+export const RELAY_MARK_PATHS = [
+  'M71.3682 21.7098L54.042 39.036C50.6567 42.4213 50.6568 47.9099 54.042 51.2952L71.3727 68.6259L52.8321 87.1665C48.6005 91.3981 41.7397 91.3981 37.5081 87.1665L3.17369 52.8321C-1.05789 48.6005 -1.0579 41.7397 3.17369 37.5081L37.5081 3.17369C41.7397 -1.0579 48.6005 -1.05789 52.8321 3.17369L71.3682 21.7098Z',
+  'M75.5711 72.8243C78.9563 76.2096 84.445 76.2096 87.8302 72.8243L109.359 51.2952C112.745 47.9099 112.745 42.4213 109.359 39.036L87.8302 17.507C84.445 14.1218 78.9563 14.1218 75.5711 17.507L71.3682 21.7098L88.6989 39.0405C92.0842 42.4258 92.0842 47.9144 88.6989 51.2997L71.3727 68.6259L75.5711 72.8243Z',
+] as const;
diff --git a/web/lib/test/agent-signup-progress.test.ts b/web/lib/test/agent-signup-progress.test.ts
new file mode 100644
index 00000000..8ffa6089
--- /dev/null
+++ b/web/lib/test/agent-signup-progress.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { isSignupProgress, trackedSignupPrompt } from '../agent-signup-progress';
+import { agentSignupInstructions } from '../agent-signup';
+const id = '537e4857-5590-42e8-8731-66441b466542';
+const progress = { id, product: 'teams', step: 0, state: 'waiting', revision: 0, updatedAt: '2026-09-21T00:00:00.000Z', expiresAt: '2026-09-21T02:00:00.000Z' };
+
+describe('signup progress handoff', () => {
+  it('accepts valid progress and rejects malformed or premature completion', () => {
+    expect(isSignupProgress(progress)).toBe(true);
+    for (const invalid of [null, {}, {...progress, step: 6}, {...progress, state: 'complete'}, {...progress, id: '../'.repeat(12)}, {...progress, updatedAt: 0}, {...progress, revision: -1}]) expect(isSignupProgress(invalid)).toBe(false);
+    expect(isSignupProgress({...progress, step: 5, state: 'complete'})).toBe(true);
+  });
+  it.each(['teams', 'flows'] as const)('carries the %s progress capability separately from URLs and preserves the local environment', (product) => {
+    const token = 'a'.repeat(64);
+    const prompt = trackedSignupPrompt(product, 'http://localhost:3100', 'http://localhost:3100/cloud/api/v1/signup/agent/sessions', { id, writeToken: token });
+    expect(prompt).toContain(`http://localhost:3100/signup/agent/${product}`);
+    expect(prompt).toContain(`Progress session: ${id}`);
+    expect(prompt).toContain(`Progress token: ${token}`);
+    expect(prompt.match(/https?:\/\/\S+/g)?.every(url => !url.includes(token))).toBe(true);
+    const guide = agentSignupInstructions(product, 'http://localhost:3100', 'http://localhost:3100/cloud');
+    expect(guide).toContain('Authorization: Bearer <Progress token>');
+    expect(guide).toContain('revision returned by the latest GET/PATCH');
+    expect(guide).toContain('Only report complete after the actual checks succeed');
+    expect(guide).toContain('NOT a Cloud access token');
+  });
+});

From ef5d031a6cd9210e9947d7e50b8c20fb2d1799ba Mon Sep 17 00:00:00 2001
From: Barry Cape <barryonthecape@icloud.com>
Date: Sun, 20 Sep 2026 22:40:42 -0700
Subject: [PATCH 05/10] Require API-only agent signup without screen automation

---
 web/lib/agent-signup-progress.ts           |  5 ++-
 web/lib/agent-signup.ts                    | 47 +++++++++++++++++++---
 web/lib/test/agent-signup-progress.test.ts | 18 +++++++++
 web/lib/test/agent-signup.test.ts          |  1 +
 4 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/web/lib/agent-signup-progress.ts b/web/lib/agent-signup-progress.ts
index 4177d08f..59ad772b 100644
--- a/web/lib/agent-signup-progress.ts
+++ b/web/lib/agent-signup-progress.ts
@@ -1,4 +1,4 @@
-import type { AgentSignupProduct } from './agent-signup';
+import { agentSignupInteractionPolicy, type AgentSignupProduct } from './agent-signup';
 
 export type SignupProgress = {
   id: string; product: AgentSignupProduct; step: number;
@@ -17,7 +17,8 @@ export function isSignupProgress(value: unknown): value is SignupProgress {
 }
 
 export function trackedSignupPrompt(product: AgentSignupProduct, origin: string, endpoint: string, session: Pick<SignupSession, 'id' | 'writeToken'>) {
-  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Follow ${origin}/signup/agent/${product} and report your progress so I can watch here.\n\nProgress session: ${session.id}\nProgress API: ${endpoint}/${session.id}\nProgress token: ${session.writeToken}\n\nUse the progress protocol in the guide. Handle setup and verification; open sign-in and approval pages for me when needed.`;
+  const cloud = endpoint.replace(/\/api\/v1\/signup\/agent\/sessions\/?$/, '');
+  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Fetch ${origin}/signup/agent/${product} over HTTP and follow its full API runbook. Report your progress so I can watch the signup page.\n\n${agentSignupInteractionPolicy}\n\nCloud API base: ${cloud}\nStart sign-in: POST ${cloud}/api/v1/auth/device/start with {"client_name":"My agent — ${product === 'teams' ? 'Teams' : 'Flows'} setup","signup_source":"${product}"}. Open the returned verification_uri_complete for me to approve, then poll POST ${cloud}/api/v1/auth/device/token at its returned interval, using the guide’s request body. Verify identity with GET ${cloud}/api/v1/auth/whoami. Follow the guide for the remaining product-specific endpoints and CLI commands.\n\nProgress session: ${session.id}\nProgress API: ${endpoint}/${session.id}\nProgress token: ${session.writeToken}\n\nGET the Progress API for its revision; PATCH it with Authorization: Bearer <Progress token> and JSON {"step":1,"state":"working","revision":<current revision>}. Follow the guide’s steps and waiting/complete states. The Progress token is only for progress updates; use the device flow’s access_token for account APIs. Keep tokens private. Verify setup from API/CLI responses, without operating my screen.`;
 }
 
 export const signupSteps = {
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 0a428d29..698a530e 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -4,8 +4,10 @@ export function isAgentSignupProduct(value: string): value is AgentSignupProduct
   return value === 'teams' || value === 'flows';
 }
 
+export const agentSignupInteractionPolicy = 'Do NOT use computer use, browser automation, screenshots, DOM inspection, or mouse/keyboard control. Fetch the guide over HTTP and perform setup through its documented APIs. Use terminal commands only for HTTP requests and the documented installation/CLI operations. The user owns the screen: open approval URLs with the OS URL opener (or give the user the link), then wait and poll the documented API. Never operate the approval page or the desktop app UI.';
+
 export function agentSignupPrompt(product: AgentSignupProduct, origin: string): string {
-  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Read and follow ${origin}/signup/agent/${product}. Handle the setup and API calls, open authorization pages for me to approve, and verify that setup completed.`;
+  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Fetch and follow ${origin}/signup/agent/${product}. ${agentSignupInteractionPolicy} Use the exact Cloud API base, endpoints, request bodies, and polling rules in the guide. Verify completion through API/CLI responses.`;
 }
 
 /** Bundled strings: these instructions must also work on Workers without a filesystem. */
@@ -14,8 +16,17 @@ export function agentSignupInstructions(product: AgentSignupProduct, site: strin
   const shared = `# Agent Relay ${title}: agent-driven signup
 
 You are setting up Agent Relay on behalf of the user who gave you this URL.
+${agentSignupInteractionPolicy}
 Do the API calls, installation, configuration, and verification yourself. Keep
-working across browser approvals; do not hand the user a checklist to execute.
+working across user approvals; do not hand the user a checklist to execute.
+The signup page is a spectator view for the user. Do not read or control it;
+report progress only with GET/PATCH on the supplied Progress API URL.
+For an approval URL, use the OS URL opener (for example macOS open with the
+URL passed as a separate subprocess argument, never interpolated into shell
+code). If no opener is available, give the link to the user. Do not launch a
+browser-control tool. Verify approval by polling the API, never by inspecting
+the browser. If an operation has no documented API or CLI, report the blocker
+and ask the user for that specific action; never fall back to computer use.
 The user handles Google sign-in, device approval, and any provider or operating
 system consent. Never approve access on their behalf or ask for their password.
 
@@ -26,6 +37,28 @@ Use this exact environment throughout; never fall back from local development
 to production. The Teams desktop app currently requires macOS 13 or later.
 Flows can be configured from any machine with HTTPS and Node.js 22+ for the CLI.
 
+## API map — use these interfaces, not the UI
+
+Use an HTTP client such as fetch or curl. Send JSON request bodies with
+Content-Type: application/json. The sections below specify exact bodies,
+response fields, authentication, polling and error handling.
+
+- Sign-in: POST ${cloud}/api/v1/auth/device/start, then poll POST
+  ${cloud}/api/v1/auth/device/token. Only the user approves the returned URL.
+- Identity/workspace: GET ${cloud}/api/v1/auth/whoami with the access token.
+- Refresh: POST ${cloud}/api/v1/auth/token/refresh before token expiry.
+- Progress: GET/PATCH the exact Progress API URL in the user's prompt;
+  PATCH uses the separate Progress token, not the account access token.
+${product === 'teams' ? `- Desktop install/connect/share/status: the bundled agent-relay-probe CLI
+  in sections 2–4. These are local machine operations, not dashboard clicks;
+  there is no public HTTP endpoint that installs an app on the user's Mac.` : `- Flow catalog: GET ${site}/api/v1/flows/catalog and /<id>.
+- Tool consent links: POST ${cloud}/api/v1/integrations/connect-link;
+  poll GET ${cloud}/api/v1/workspaces/<workspaceId>/integrations/<provider>/status.
+- Coding-agent credentials: the official cloud connect CLI in section 3;
+  GET ${cloud}/api/v1/cloud-agents inspects existing connections.
+- Activation: POST ${cloud}/api/v1/flows/deploy with the body in section 4.
+- Verification: GET ${cloud}/api/v1/flows/listeners/<agentId>.`}
+
 ## Live progress (when the user's prompt includes a progress session)
 
 The user is watching a setup page. Report real milestones using the Progress API
@@ -162,7 +195,7 @@ function teamsInstructions(site: string): string {
 
 Run sw_vers -productVersion and uname -m on the user's Mac. arm64 means Apple
 silicon; x86_64 means the x64 download. If this agent runs in a remote sandbox,
-it must obtain access to the user's Mac before installation; installing into
+it needs authorized terminal access to the user's Mac before installation; installing into
 the sandbox does not connect their computer. Report an unsupported OS honestly.
 
 Download ${download} and the same URL plus .sha256. Replace <arch> with arm64
@@ -238,8 +271,12 @@ URL-encode the three values; the link contains identifiers only, never tokens.
 The app discovers the probe's saved connection. If it is already attached to a
 different account/workspace, the link will report a conflict, not switch accounts.
 Ask the user to explicitly log out/switch in Account before retrying; do not
-disconnect an existing workspace automatically. Confirm the app's Account view
-matches the target. Open ${site}/cloud/dashboard/sessions for the team history. Report
+disconnect an existing workspace automatically. The probe's JSON status verifies
+the collector, not whether the app accepted the handoff. Do not inspect the app's
+Account view yourself. Ask the user to confirm that the visible app account and
+workspace match the target after handoff. Until confirmed, report the app
+attachment as unverified and keep progress waiting at step 5; do not mark setup
+complete. Open ${site}/cloud/dashboard/sessions for the team history. Report
 the installed app, account/workspace, sharing choice, and verification outcome.
 Delete temporary authentication files after use; retain the app-managed scoped
 credentials so background collection continues. The user can pause, select
diff --git a/web/lib/test/agent-signup-progress.test.ts b/web/lib/test/agent-signup-progress.test.ts
index 8ffa6089..e1e931c9 100644
--- a/web/lib/test/agent-signup-progress.test.ts
+++ b/web/lib/test/agent-signup-progress.test.ts
@@ -15,6 +15,13 @@ describe('signup progress handoff', () => {
     const prompt = trackedSignupPrompt(product, 'http://localhost:3100', 'http://localhost:3100/cloud/api/v1/signup/agent/sessions', { id, writeToken: token });
     expect(prompt).toContain(`http://localhost:3100/signup/agent/${product}`);
     expect(prompt).toContain(`Progress session: ${id}`);
+    expect(prompt).toContain('Do NOT use computer use, browser automation');
+    expect(prompt).toContain('without operating my screen');
+    expect(prompt).toContain('Cloud API base: http://localhost:3100/cloud');
+    expect(prompt).toContain('POST http://localhost:3100/cloud/api/v1/auth/device/start');
+    expect(prompt).toContain('POST http://localhost:3100/cloud/api/v1/auth/device/token');
+    expect(prompt).toContain('GET http://localhost:3100/cloud/api/v1/auth/whoami');
+    expect(prompt).toContain(`"signup_source":"${product}"`);
     expect(prompt).toContain(`Progress token: ${token}`);
     expect(prompt.match(/https?:\/\/\S+/g)?.every(url => !url.includes(token))).toBe(true);
     const guide = agentSignupInstructions(product, 'http://localhost:3100', 'http://localhost:3100/cloud');
@@ -22,5 +29,16 @@ describe('signup progress handoff', () => {
     expect(guide).toContain('revision returned by the latest GET/PATCH');
     expect(guide).toContain('Only report complete after the actual checks succeed');
     expect(guide).toContain('NOT a Cloud access token');
+    expect(guide).toContain('Do NOT use computer use, browser automation');
+    expect(guide).toContain('Verify approval by polling the API');
+    expect(guide).toContain('POST http://localhost:3100/cloud/api/v1/auth/device/start');
+    if (product === 'teams') {
+      expect(guide).toContain('there is no public HTTP endpoint that installs an app');
+      expect(guide).toContain("Do not inspect the app's");
+      expect(guide).toContain("attachment as unverified and keep progress waiting at step 5");
+    } else {
+      expect(guide).toContain('POST http://localhost:3100/cloud/api/v1/flows/deploy');
+      expect(guide).toContain('GET http://localhost:3100/api/v1/flows/catalog');
+    }
   });
 });
diff --git a/web/lib/test/agent-signup.test.ts b/web/lib/test/agent-signup.test.ts
index 78c41461..7ef401f4 100644
--- a/web/lib/test/agent-signup.test.ts
+++ b/web/lib/test/agent-signup.test.ts
@@ -21,6 +21,7 @@ describe('agent signup instructions', () => {
     expect(content).toContain('/api/v1/auth/device/token');
     expect(content).toContain('/api/v1/auth/whoami');
     expect(content).toContain('/api/v1/auth/token/refresh');
+    expect(agentSignupPrompt(product as 'teams' | 'flows', 'https://agentrelay.com')).toContain('Do NOT use computer use, browser automation');
     if (product === 'teams') {
       expect(content).toContain('--selected-sessions-only --json');
       expect(content).toContain('releases/latest/download/AgentRelay-macOS-<arch>.dmg');

From fbcd0ea28b65149bdbcc3c999d553d9187399a66 Mon Sep 17 00:00:00 2001
From: Barry Cape <barryonthecape@icloud.com>
Date: Sun, 20 Sep 2026 22:51:22 -0700
Subject: [PATCH 06/10] Keep signup prompt concise and require prebuilt desktop
 downloads

---
 web/lib/agent-signup-progress.ts           |  5 ++---
 web/lib/agent-signup.ts                    | 15 ++++++++++-----
 web/lib/test/agent-signup-progress.test.ts | 13 +++++++------
 3 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/web/lib/agent-signup-progress.ts b/web/lib/agent-signup-progress.ts
index 59ad772b..e2ac7c75 100644
--- a/web/lib/agent-signup-progress.ts
+++ b/web/lib/agent-signup-progress.ts
@@ -1,4 +1,4 @@
-import { agentSignupInteractionPolicy, type AgentSignupProduct } from './agent-signup';
+import { agentSignupPrompt, type AgentSignupProduct } from './agent-signup';
 
 export type SignupProgress = {
   id: string; product: AgentSignupProduct; step: number;
@@ -17,8 +17,7 @@ export function isSignupProgress(value: unknown): value is SignupProgress {
 }
 
 export function trackedSignupPrompt(product: AgentSignupProduct, origin: string, endpoint: string, session: Pick<SignupSession, 'id' | 'writeToken'>) {
-  const cloud = endpoint.replace(/\/api\/v1\/signup\/agent\/sessions\/?$/, '');
-  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Fetch ${origin}/signup/agent/${product} over HTTP and follow its full API runbook. Report your progress so I can watch the signup page.\n\n${agentSignupInteractionPolicy}\n\nCloud API base: ${cloud}\nStart sign-in: POST ${cloud}/api/v1/auth/device/start with {"client_name":"My agent — ${product === 'teams' ? 'Teams' : 'Flows'} setup","signup_source":"${product}"}. Open the returned verification_uri_complete for me to approve, then poll POST ${cloud}/api/v1/auth/device/token at its returned interval, using the guide’s request body. Verify identity with GET ${cloud}/api/v1/auth/whoami. Follow the guide for the remaining product-specific endpoints and CLI commands.\n\nProgress session: ${session.id}\nProgress API: ${endpoint}/${session.id}\nProgress token: ${session.writeToken}\n\nGET the Progress API for its revision; PATCH it with Authorization: Bearer <Progress token> and JSON {"step":1,"state":"working","revision":<current revision>}. Follow the guide’s steps and waiting/complete states. The Progress token is only for progress updates; use the device flow’s access_token for account APIs. Keep tokens private. Verify setup from API/CLI responses, without operating my screen.`;
+  return `${agentSignupPrompt(product, origin)}\n\nReport real progress using the guide’s protocol so I can watch the signup page.\n\nProgress session: ${session.id}\nProgress API: ${endpoint}/${session.id}\nProgress token: ${session.writeToken}\n\nKeep this token private; it authorizes progress updates only.`;
 }
 
 export const signupSteps = {
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 698a530e..bd069794 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -4,10 +4,10 @@ export function isAgentSignupProduct(value: string): value is AgentSignupProduct
   return value === 'teams' || value === 'flows';
 }
 
-export const agentSignupInteractionPolicy = 'Do NOT use computer use, browser automation, screenshots, DOM inspection, or mouse/keyboard control. Fetch the guide over HTTP and perform setup through its documented APIs. Use terminal commands only for HTTP requests and the documented installation/CLI operations. The user owns the screen: open approval URLs with the OS URL opener (or give the user the link), then wait and poll the documented API. Never operate the approval page or the desktop app UI.';
+const agentSignupInteractionPolicy = 'Do NOT use computer use, browser automation, screenshots, DOM inspection, or mouse/keyboard control. Fetch the guide over HTTP and perform setup through its documented APIs. Use terminal commands only for HTTP requests and the documented installation/CLI operations. The user owns the screen: open approval URLs with the OS URL opener (or give the user the link), then wait and poll the documented API. Never operate the approval page or the desktop app UI.';
 
 export function agentSignupPrompt(product: AgentSignupProduct, origin: string): string {
-  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Fetch and follow ${origin}/signup/agent/${product}. ${agentSignupInteractionPolicy} Use the exact Cloud API base, endpoints, request bodies, and polling rules in the guide. Verify completion through API/CLI responses.`;
+  return `Set up Agent Relay ${product === 'teams' ? 'Teams' : 'Flows'} for me. Fetch and follow ${origin}/signup/agent/${product} over HTTP for the exact APIs and setup steps. Do NOT use computer use, browser automation, or screen control. Use the documented APIs and CLI commands; leave sign-in and approval pages to me. For desktop installation, download the prebuilt binary from the guide—never clone, build, or compile the app.`;
 }
 
 /** Bundled strings: these instructions must also work on Workers without a filesystem. */
@@ -27,6 +27,9 @@ code). If no opener is available, give the link to the user. Do not launch a
 browser-control tool. Verify approval by polling the API, never by inspecting
 the browser. If an operation has no documented API or CLI, report the blocker
 and ask the user for that specific action; never fall back to computer use.
+For desktop installation, download the prebuilt binary from this guide. Never
+clone the desktop repository, install build dependencies, run a build, compile
+from source, or generate a DMG. A missing binary is a blocker, not a build task.
 The user handles Google sign-in, device approval, and any provider or operating
 system consent. Never approve access on their behalf or ask for their password.
 
@@ -191,7 +194,7 @@ function teamsInstructions(site: string): string {
     ? `${site}/cloud/desktop-downloads/AgentRelay-Dev-macOS-<arch>.dmg`
     : 'https://github.com/AgentWorkforce/relay-desktop-releases/releases/latest/download/AgentRelay-macOS-<arch>.dmg';
   return `
-## 2. Download and install the desktop app
+## 2. Download and install the prebuilt desktop binary
 
 Run sw_vers -productVersion and uname -m on the user's Mac. arm64 means Apple
 silicon; x86_64 means the x64 download. If this agent runs in a remote sandbox,
@@ -201,8 +204,10 @@ the sandbox does not connect their computer. Report an unsupported OS honestly.
 Download ${download} and the same URL plus .sha256. Replace <arch> with arm64
 or x64. Use a private temporary directory, follow HTTPS release redirects, and
 fail on HTTP errors. Verify SHA-256 before mounting. For local development,
-only the architecture built by the Cloud launcher is available; a missing DMG
-means the local stack must be built, never that you should download production.
+use only the prebuilt DMG already served by the local stack. If the DMG or its
+checksum is unavailable for this architecture, stop and report the missing
+prebuilt artifact. Do not build it, run the development launcher to produce it,
+or switch to a production download.
 
 Use hdiutil attach -nobrowse with a private mount point, then ditto the mounted
 ${name}.app into ~/Applications/${name}.app (create ~/Applications if needed).
diff --git a/web/lib/test/agent-signup-progress.test.ts b/web/lib/test/agent-signup-progress.test.ts
index e1e931c9..ea318e29 100644
--- a/web/lib/test/agent-signup-progress.test.ts
+++ b/web/lib/test/agent-signup-progress.test.ts
@@ -16,12 +16,10 @@ describe('signup progress handoff', () => {
     expect(prompt).toContain(`http://localhost:3100/signup/agent/${product}`);
     expect(prompt).toContain(`Progress session: ${id}`);
     expect(prompt).toContain('Do NOT use computer use, browser automation');
-    expect(prompt).toContain('without operating my screen');
-    expect(prompt).toContain('Cloud API base: http://localhost:3100/cloud');
-    expect(prompt).toContain('POST http://localhost:3100/cloud/api/v1/auth/device/start');
-    expect(prompt).toContain('POST http://localhost:3100/cloud/api/v1/auth/device/token');
-    expect(prompt).toContain('GET http://localhost:3100/cloud/api/v1/auth/whoami');
-    expect(prompt).toContain(`"signup_source":"${product}"`);
+    expect(prompt).toContain('download the prebuilt binary');
+    expect(prompt).toContain('never clone, build, or compile the app');
+    expect(prompt).toContain(`Progress API: http://localhost:3100/cloud/api/v1/signup/agent/sessions/${id}`);
+    expect(prompt).not.toContain('/api/v1/auth/device/start');
     expect(prompt).toContain(`Progress token: ${token}`);
     expect(prompt.match(/https?:\/\/\S+/g)?.every(url => !url.includes(token))).toBe(true);
     const guide = agentSignupInstructions(product, 'http://localhost:3100', 'http://localhost:3100/cloud');
@@ -31,9 +29,12 @@ describe('signup progress handoff', () => {
     expect(guide).toContain('NOT a Cloud access token');
     expect(guide).toContain('Do NOT use computer use, browser automation');
     expect(guide).toContain('Verify approval by polling the API');
+    expect(guide).toContain('A missing binary is a blocker, not a build task.');
     expect(guide).toContain('POST http://localhost:3100/cloud/api/v1/auth/device/start');
     if (product === 'teams') {
       expect(guide).toContain('there is no public HTTP endpoint that installs an app');
+      expect(guide).toContain('Do not build it, run the development launcher to produce it');
+      expect(guide).not.toContain('the local stack must be built');
       expect(guide).toContain("Do not inspect the app's");
       expect(guide).toContain("attachment as unverified and keep progress waiting at step 5");
     } else {

From 73521a0361dd0985aeac03d7c1523bba0d5f7f24 Mon Sep 17 00:00:00 2001
From: Barry Cape <barryonthecape@icloud.com>
Date: Sun, 20 Sep 2026 23:45:59 -0700
Subject: [PATCH 07/10] Track agent signup funnels across browser and API

---
 web/analytics/agent-signup-funnel.md        | 121 ++++++++++++++++++++
 web/app/WebsitePostHogProvider.tsx          |  16 +++
 web/app/layout.tsx                          |  15 +--
 web/components/AgentSignup.tsx              |   4 +-
 web/components/AgentSignupJourney.tsx       |  50 ++++++--
 web/components/useSignupAnalytics.ts        |  14 +++
 web/lib/agent-signup-analytics.ts           |  64 +++++++++++
 web/lib/agent-signup.ts                     |  10 +-
 web/lib/signup-analytics-privacy.ts         |  30 +++++
 web/lib/test/agent-signup-analytics.test.ts |  84 ++++++++++++++
 10 files changed, 385 insertions(+), 23 deletions(-)
 create mode 100644 web/analytics/agent-signup-funnel.md
 create mode 100644 web/app/WebsitePostHogProvider.tsx
 create mode 100644 web/components/useSignupAnalytics.ts
 create mode 100644 web/lib/agent-signup-analytics.ts
 create mode 100644 web/lib/signup-analytics-privacy.ts
 create mode 100644 web/lib/test/agent-signup-analytics.test.ts

diff --git a/web/analytics/agent-signup-funnel.md b/web/analytics/agent-signup-funnel.md
new file mode 100644
index 00000000..f78bc446
--- /dev/null
+++ b/web/analytics/agent-signup-funnel.md
@@ -0,0 +1,121 @@
+# Agent signup funnels (Teams and Flows)
+
+This funnel measures the agent-led journey reached through “Let your agent do it.”
+It is separate from the existing manual Flows onboarding funnel (version 2).
+
+## Common event properties
+
+All events use `funnel=agent_signup`, `funnel_version=1`, `onboarding_method=agent`,
+`product=teams|flows`, `journey_id`, `step`, and `source=browser|server`.
+The journey ID is a random analytics identifier, **not** the progress session ID
+(the latter grants read access). The browser's existing PostHog distinct ID is
+passed to Cloud once at session creation so both sides refer to the same visitor.
+Use the same PostHog project for the marketing and Cloud clients.
+
+Server events additionally include `step_name`, `state`, `revision`, `elapsed_ms`
+(since session creation), `agent_type`, and `agent_attribution`.
+
+`agent_type` is self-reported by the agent's first progress PATCH and retained:
+`codex`, `claude_code`, `grok`, `opencode`, `cursor`, `gemini_cli`, `other`, or
+`unknown`. This describes the tool performing signup, not the models selected
+for the eventual Flows workflow. Rotating logos are decorative and never count
+as a user selection. Do not infer a known agent for visitors who never start it.
+
+## Event catalog
+
+| Event | Source | When |
+| --- | --- | --- |
+| `agent_signup_entry_clicked` | Browser | Landing-page secondary CTA |
+| `agent_signup_page_viewed` | Browser | Owner opens the signup page (including direct entry) |
+| `agent_signup_session_created` | Server | A new progress session is persisted |
+| `agent_signup_prompt_copied` | Browser | Clipboard write succeeds |
+| `agent_signup_manual_copy_shown` | Browser | Clipboard unavailable; full prompt revealed for manual copy |
+| `agent_signup_step_started` | Server | Agent advances into a numbered step |
+| `agent_signup_step_completed` | Server | Agent advances past a step, or completes verification |
+| `agent_signup_waiting` | Server | Agent reports waiting for approval or a choice |
+| `agent_signup_failed` | Server | Agent reports a blocked/failed step |
+| `agent_signup_resumed` | Server | Waiting/failed step resumes working |
+| `agent_signup_completed` | Server | Agent reports verified step 5 complete |
+| `agent_signup_details_opened` | Browser | Owner expands setup details |
+| `agent_signup_session_error` | Browser | Starting/restoring session fails (no error text sent) |
+| `agent_signup_expired` | Browser | Owner's open page observes expiry |
+| `agent_signup_restarted` | Browser | Owner explicitly starts a new session |
+| `agent_signup_page_left` | Browser | Owner's pagehide or SPA exit, with last observed step |
+| `agent_signup_dashboard_opened` | Browser | Completion CTA clicked |
+
+| Step | Teams `step_name` | Flows `step_name` |
+| --- | --- | --- |
+| 1 | `sign_in` | `sign_in` |
+| 2 | `install_app` | `choose_flow` |
+| 3 | `connect_workspace` | `connect_tools` |
+| 4 | `choose_sharing` | `activate_flow` |
+| 5 | `verify` | `verify` |
+
+## Build the two funnels
+
+Create a sequential funnel filtered to `funnel=agent_signup`, `funnel_version=1`,
+and `product=teams`; duplicate it with `product=flows`. Use a two-hour conversion
+window (session TTL), holding `journey_id` constant so separate attempts do not
+complete one another. The standard funnel counts people; for attempt counts,
+use a SQL insight grouped by `journey_id`, since a person can make multiple attempts.
+
+1. `agent_signup_page_viewed`
+2. `agent_signup_session_created`
+3. `agent_signup_step_started`, filter `step=1`
+4. `agent_signup_step_completed`, filter `step=1`
+5. `agent_signup_step_completed`, filter `step=2`
+6. `agent_signup_step_completed`, filter `step=3`
+7. `agent_signup_step_completed`, filter `step=4`
+8. `agent_signup_completed`
+
+Do not require clipboard success or the landing CTA in this main funnel: users
+can copy manually or arrive directly. Make separate entry→page and
+page→prompt-copied/manual-copy-shown→agent-started funnels to diagnose handoff.
+
+For an agent comparison, start at `agent_signup_step_started` with `step=1`,
+then add the completion steps. Break down by event property `agent_type`, using
+first-touch attribution on this agent-started funnel. This keeps non-starters
+in the overall funnel rather than silently excluding them for lacking an agent.
+To split the full funnel by agent, use last-touch attribution: pre-agent dropoffs
+remain `unknown`. See [PostHog funnel breakdown attribution](https://posthog.com/docs/product-analytics/funnels#attribution-types).
+
+For friction, trend `agent_signup_waiting` and `agent_signup_failed` by `product`,
+`step_name`, and `agent_type`; compare elapsed time at each completed step. Inspect
+the last server milestone per `journey_id` to see how far an attempt got. A
+`page_left` event is diagnostic, **not abandonment**: the agent can finish while
+the page is closed. Incomplete journeys after the two-hour window are dropoffs;
+there is no fabricated server "abandoned" event or fake completion.
+
+## Reliability, privacy, and rollout checks
+
+- Browser events and the server handoff are disabled when PostHog is absent,
+  uninitialized, or opted out at session creation. Server events continue for
+  that opted-in journey independently of the browser. Later browser opt-out
+  stops browser events; the existing server journey retains its original
+  capture context until its two-hour expiry. Do not claim per-request consent
+  revocation is implemented by this flow.
+- Server events follow committed writes. GET polling, watcher tabs, duplicate
+  PATCHes and rejected updates never emit milestones. Stable event UUIDs prevent
+  duplicate transport delivery. Tracking is best effort, bounded to 1.5 seconds
+  on Node and kept alive with Worker `waitUntil`; there is no durable retry outbox.
+- Events never include tokens, raw progress IDs, prompts, device codes, local
+  paths, user text, or approval URLs. SDK-enriched URLs redact the session query
+  and progress route IDs. Replay network capture drops the entire progress API
+  request/response, including serialized bodies and headers. The signup page is blocked from replay/autocapture;
+  intentional funnel events remain enabled.
+- Marketing uses its existing public project key at build time; Cloud uses its
+  existing shared server client and runtime ingest key. No new project or secret
+  is created. Ensure keys target the same project, and Cloud's stage is allowed
+  to emit analytics. The marketing GitHub build variable was compared with Cloud’s canonical production
+  ingest key and matches. No live PostHog project/dashboard was modified by this PR.
+- Before production signoff, perform one consented Teams signup and one Flows
+  signup, then find each `journey_id` in PostHog Live Events. Verify the visitor
+  joins browser and server events, the first PATCH has the actual agent type,
+  all five completion steps appear once, and no capabilities appear in event
+  JSON/replay. Repeat with analytics disabled: signup must still work.
+
+Local coverage: migrated database/real-handler tests exercise both products,
+concurrent retries, attribution, failures, and completion without browser polling;
+browser-tracker tests cover opt-out, reload, storage failures, product separation,
+restart, and sanitization. These prove instrumentation behavior, not production
+PostHog ingestion or real Google/provider/desktop onboarding.
diff --git a/web/app/WebsitePostHogProvider.tsx b/web/app/WebsitePostHogProvider.tsx
new file mode 100644
index 00000000..91f3ba50
--- /dev/null
+++ b/web/app/WebsitePostHogProvider.tsx
@@ -0,0 +1,16 @@
+'use client';
+// The public client provider shares @posthog/next's hook context. Keeping
+// configuration here lets before_send run without serializing a function
+// through the server-component boundary, and before the first SDK capture.
+import { PostHogProvider } from '@posthog/next/pages';
+import type { ReactNode } from 'react';
+import { maskSignupNetworkRequest, sanitizeSignupAnalytics } from '../lib/signup-analytics-privacy';
+
+export function WebsitePostHogProvider({ apiKey, host, children }: { apiKey: string; host: string; children: ReactNode }) {
+  return <PostHogProvider apiKey={apiKey} clientOptions={{
+    api_host: host, autocapture: true, capture_exceptions: true, capture_heatmaps: true,
+    capture_pageview: false, capture_pageleave: true,
+    session_recording: { maskAllInputs: true, blockSelector: '.ph-sensitive', maskCapturedNetworkRequestFn: maskSignupNetworkRequest },
+    before_send: sanitizeSignupAnalytics,
+  }}>{children}</PostHogProvider>;
+}
diff --git a/web/app/layout.tsx b/web/app/layout.tsx
index 3e86c2a7..d3ad036b 100644
--- a/web/app/layout.tsx
+++ b/web/app/layout.tsx
@@ -1,5 +1,5 @@
 import type { Metadata } from 'next';
-import { PostHogProvider } from '@posthog/next';
+import { WebsitePostHogProvider } from './WebsitePostHogProvider';
 import { Geist_Mono, Inter, Sora } from 'next/font/google';
 import type { ReactNode } from 'react';
 
@@ -118,19 +118,10 @@ const siteStructuredData = {
 export default function RootLayout({ children }: { children: ReactNode }) {
   const postHogKey = process.env.NEXT_PUBLIC_POSTHOG_KEY;
   const content = postHogKey ? (
-    <PostHogProvider
-      clientOptions={{
-        api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? POSTHOG_HOST,
-        autocapture: true,
-        capture_exceptions: true,
-        capture_heatmaps: true,
-        session_recording: { maskAllInputs: true, blockSelector: '.ph-sensitive' },
-        capture_pageleave: true,
-      }}
-    >
+    <WebsitePostHogProvider apiKey={postHogKey} host={process.env.NEXT_PUBLIC_POSTHOG_HOST ?? POSTHOG_HOST}>
       <WebsitePostHogPageView />
       {children}
-    </PostHogProvider>
+    </WebsitePostHogProvider>
   ) : (
     children
   );
diff --git a/web/components/AgentSignup.tsx b/web/components/AgentSignup.tsx
index da5ccda7..6cabc9ef 100644
--- a/web/components/AgentSignup.tsx
+++ b/web/components/AgentSignup.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { useSignupAnalytics } from './useSignupAnalytics';
 import Link from 'next/link';
 import Grok from '@lobehub/icons/es/Grok';
 import { AgentToolLogo } from './AgentToolLogos';
@@ -7,8 +8,9 @@ import type { AgentSignupProduct } from '../lib/agent-signup';
 import s from './agent-signup.module.css';
 
 export function AgentSignup({ product }: { product: AgentSignupProduct }) {
+  const analytics = useSignupAnalytics(product);
   return (
-    <Link className={s.button} href={`/signup/${product}`}>
+    <Link onClick={() => analytics.track('entry_clicked')} className={s.button} href={`/signup/${product}`}>
       <span className={s.icons} aria-hidden="true">
         <span><AgentToolLogo provider="codex" className={s.logo} /></span>
         <span><AgentToolLogo provider="claude" className={s.logo} /></span>
diff --git a/web/components/AgentSignupJourney.tsx b/web/components/AgentSignupJourney.tsx
index 9d82904d..b7361fb2 100644
--- a/web/components/AgentSignupJourney.tsx
+++ b/web/components/AgentSignupJourney.tsx
@@ -1,6 +1,8 @@
 'use client';
 
 import { useEffect, useRef, useState } from 'react';
+import { useSignupAnalytics } from './useSignupAnalytics';
+import type { SignupAnalyticsContext } from '../lib/agent-signup-analytics';
 import Link from 'next/link';
 import Grok from '@lobehub/icons/es/Grok';
 import { ArrowLeft, ArrowUpRight, Check, Copy, RefreshCw } from 'lucide-react';
@@ -32,7 +34,7 @@ async function readProgress(id: string, signal?: AbortSignal): Promise<SignupPro
   return data;
 }
 
-async function startSession(product: AgentSignupProduct): Promise<{ progress: SignupProgress; token?: string }> {
+async function startSession(product: AgentSignupProduct, analytics?: SignupAnalyticsContext): Promise<{ progress: SignupProgress; token?: string }> {
   const requestedId = new URL(window.location.href).searchParams.get('session');
   let saved: SignupSession | undefined;
   try {
@@ -48,7 +50,7 @@ async function startSession(product: AgentSignupProduct): Promise<{ progress: Si
   }
   const response = await fetch(apiPath, {
     method: 'POST', headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ product }), signal: AbortSignal.timeout(10_000),
+    body: JSON.stringify({ product, ...(analytics ? { analytics } : {}) }), signal: AbortSignal.timeout(10_000),
   });
   if (!response.ok) throw new Error('Could not start a setup session. Please try again.');
   const session: unknown = await response.json();
@@ -59,6 +61,11 @@ async function startSession(product: AgentSignupProduct): Promise<{ progress: Si
 }
 
 export function AgentSignupJourney({ product }: { product: AgentSignupProduct }) {
+  const analytics = useSignupAnalytics(product);
+  const viewed = useRef(false);
+  const lifecycle = useRef(0);
+  const trackedExpired = useRef(false);
+  const latest = useRef({ step: 0, owner: false });
   const [progress, setProgress] = useState<SignupProgress>();
   const [token, setToken] = useState<string>();
   const [origin, setOrigin] = useState('');
@@ -77,11 +84,34 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
   const endpoint = origin ? new URL(apiPath, origin).href : '';
   const prompt = progress && token ? trackedSignupPrompt(product, origin, endpoint, { id: progress.id, writeToken: token }) : '';
 
+  latest.current = { step: active, owner: Boolean(token) };
+  useEffect(() => {
+    const generation = ++lifecycle.current;
+    const leave = () => { if (latest.current.owner) analytics.leave(latest.current.step); };
+    const show = () => analytics.resume();
+    window.addEventListener('pagehide', leave);
+    window.addEventListener('pageshow', show);
+    return () => {
+      window.removeEventListener('pagehide', leave);
+      window.removeEventListener('pageshow', show);
+      // Ignore StrictMode's cleanup/setup probe, but include SPA Back exits.
+      queueMicrotask(() => { if (lifecycle.current === generation) leave(); });
+    };
+  }, [analytics]);
+  useEffect(() => {
+    if (expired && token && !trackedExpired.current) { trackedExpired.current = true; analytics.track('expired', active); }
+  }, [expired, token, active, analytics]);
+
   useEffect(() => {
     let cancelled = false;
     setOrigin(window.location.origin);
     // Keep a single creation request through React StrictMode's effect replay.
-    boot.current ||= startSession(product);
+    // Watcher links must not create a second funnel or inherit the owner's identity.
+    const requested = new URL(window.location.href).searchParams.get('session');
+    let owner = !requested;
+    try { owner ||= JSON.parse(sessionStorage.getItem(storageKey(product)) || 'null')?.id === requested; } catch { /* Read-only until proven otherwise. */ }
+    if (owner && !viewed.current) { analytics.track('page_viewed'); viewed.current = true; }
+    boot.current ||= startSession(product, owner ? analytics.context() : undefined);
     void boot.current.then(({ progress: initial, token: writeToken }) => {
       if (cancelled) return;
       setProgress(initial); setToken(writeToken); setError('');
@@ -90,12 +120,13 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
       window.history.replaceState(window.history.state, '', url);
     }).catch((cause) => {
       if (!cancelled) {
+        if (owner) analytics.track('session_error');
         setError(cause instanceof Error && cause.name !== 'TimeoutError' ? cause.message : 'We couldn’t start live setup. Check your connection and try again.');
         if (cause instanceof ProgressError && cause.expired) setExpired(true);
       }
     });
     return () => { cancelled = true; };
-  }, [product, attempt]);
+  }, [product, attempt, analytics]);
 
   useEffect(() => {
     if (!progress || complete) return;
@@ -125,10 +156,11 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
   }, [progress?.id, progress?.expiresAt, complete, product]);
 
   async function copy() {
-    try { await navigator.clipboard.writeText(prompt); setCopyMessage('Copied. Paste it into your agent.'); }
-    catch { setShowPrompt(true); setCopyMessage('Select and copy the prompt below.'); requestAnimationFrame(() => { textarea.current?.focus(); textarea.current?.select(); }); }
+    try { await navigator.clipboard.writeText(prompt); setCopyMessage('Copied. Paste it into your agent.'); analytics.track('prompt_copied'); }
+    catch { analytics.track('manual_copy_shown'); setShowPrompt(true); setCopyMessage('Select and copy the prompt below.'); requestAnimationFrame(() => { textarea.current?.focus(); textarea.current?.select(); }); }
   }
   function restart() {
+    analytics.restart(Boolean(token));
     try { sessionStorage.removeItem(storageKey(product)); } catch { /* Best effort. */ }
     window.location.assign(window.location.pathname);
   }
@@ -139,7 +171,7 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
   const heading = complete ? 'All yours.' : active ? title : 'Leave it to your agent.';
 
   return (
-    <div className={s.page} data-mode={mode}>
+    <div className={`${s.page} ph-sensitive ph-no-capture`} data-mode={mode}>
       <SignupAtmosphere className={s.atmosphere} step={complete ? 6 : active} mode={mode} />
       <Link href={`/${product}`} className={s.back} aria-label={`Back to ${product}`}><ArrowLeft size={18} /></Link>
       <main className={s.main}>
@@ -154,7 +186,7 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
               <span title="OpenCode"><AgentToolLogo provider="opencode" className={s.agentLogo} /></span>
             </div>
           )}
-          {complete ? <a className={s.primary} href={teamsCloudUrl(product === 'teams' ? '/dashboard/sessions' : '/dashboard')}>Open {product === 'teams' ? 'your workspace' : 'dashboard'} <ArrowUpRight size={17} /></a>
+          {complete ? <a onClick={() => { if (token) analytics.track('dashboard_opened', active); }} className={s.primary} href={teamsCloudUrl(product === 'teams' ? '/dashboard/sessions' : '/dashboard')}>Open {product === 'teams' ? 'your workspace' : 'dashboard'} <ArrowUpRight size={17} /></a>
             : !active ? <button type="button" className={s.primary} disabled={!prompt || expired} onClick={() => void copy()}>{copyMessage.startsWith('Copied') ? <Check size={17} /> : <Copy size={17} />}{copyMessage.startsWith('Copied') ? 'Prompt copied' : 'Copy setup prompt'}</button> : null}
           <p className={s.copyStatus} role="status">{complete ? '' : active ? (paused ? 'Your agent will continue after you approve.' : 'You can leave this page open.') : copyMessage || (progress && !token ? 'Watching this session. The prompt is in the original browser tab.' : product === 'teams' ? 'Paste into a coding agent on your Mac.' : 'Paste into a coding agent with terminal access.')}</p>
           <div className={s.progress} role="status" aria-live="polite">
@@ -162,7 +194,7 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
             <span>{expired ? 'Session expired' : error ? 'Waiting for a connection' : complete ? 'Setup complete' : active ? `${active} of 5 · ${paused ? 'Waiting for your approval' : failed ? 'Needs your attention' : steps[active - 1].title}` : progress ? 'Ready when your agent is' : 'Preparing your session…'}</span>
           </div>
           {error && <div className={s.error} role="alert"><p>{error}</p>{!progress && <button type="button" onClick={() => { boot.current = null; setError(''); setAttempt(value => value + 1); }}>Try again <RefreshCw size={12} /></button>}</div>}
-          <details className={s.details}>
+          <details className={s.details} onToggle={event => { if (event.currentTarget.open && token) analytics.track('details_opened', active); }}>
             <summary>Setup details</summary>
             <div className={s.detailBody}>
               <ol className={s.steps}>{[...steps, { title: 'Ready to go' }].map((step, index) => {
diff --git a/web/components/useSignupAnalytics.ts b/web/components/useSignupAnalytics.ts
new file mode 100644
index 00000000..6f8ea2d0
--- /dev/null
+++ b/web/components/useSignupAnalytics.ts
@@ -0,0 +1,14 @@
+'use client';
+import { useMemo } from 'react';
+import { usePostHog } from '@posthog/next';
+import type { AgentSignupProduct } from '../lib/agent-signup';
+import { SignupTracker } from '../lib/agent-signup-analytics';
+
+export function useSignupAnalytics(product: AgentSignupProduct) {
+  const ph = usePostHog();
+  return useMemo(() => new SignupTracker(ph, product, {
+    getItem: key => sessionStorage.getItem(key),
+    setItem: (key, value) => sessionStorage.setItem(key, value),
+    removeItem: key => sessionStorage.removeItem(key),
+  }), [ph, product]);
+}
diff --git a/web/lib/agent-signup-analytics.ts b/web/lib/agent-signup-analytics.ts
new file mode 100644
index 00000000..c6655ae6
--- /dev/null
+++ b/web/lib/agent-signup-analytics.ts
@@ -0,0 +1,64 @@
+import type { AgentSignupProduct } from './agent-signup';
+
+export type SignupAnalyticsContext = { distinctId: string; journeyId: string };
+export type SignupAnalyticsClient = {
+  __loaded?: boolean;
+  has_opted_out_capturing(): boolean;
+  get_distinct_id(): string;
+  capture(event: string, properties: Record<string, unknown>, options?: { transport: 'sendBeacon' }): unknown;
+};
+export type SignupBrowserEvent = 'entry_clicked' | 'page_viewed' | 'prompt_copied' | 'manual_copy_shown' | 'details_opened' | 'restarted' | 'page_left' | 'expired' | 'session_error' | 'dashboard_opened';
+const key = (product: string) => `agent-relay-signup-analytics:${product}`;
+const ttl = 2 * 60 * 60_000;
+
+/** Distinct from the read-capability session ID. Never put that ID in analytics. */
+export class SignupTracker {
+  private departed = false;
+  private cached?: { journeyId: string; startedAt: number };
+  constructor(private ph: SignupAnalyticsClient | null | undefined, private product: AgentSignupProduct,
+    private storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>, private uuid = () => crypto.randomUUID(), private now = Date.now) {}
+
+  context(): SignupAnalyticsContext | undefined {
+    try {
+      if (!this.ph?.__loaded || this.ph.has_opted_out_capturing()) return undefined;
+      const distinctId = this.ph.get_distinct_id();
+      if (!/^[a-zA-Z0-9._:-]{1,200}$/.test(distinctId)) return undefined;
+      if (!this.cached) {
+        try {
+          const saved = JSON.parse(this.storage.getItem(key(this.product)) || 'null');
+          if (saved && typeof saved.journeyId === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(saved.journeyId) &&
+            typeof saved.startedAt === 'number' && this.now() - saved.startedAt < ttl && saved.startedAt <= this.now()) this.cached = saved;
+        } catch { /* Storage is optional. */ }
+        this.cached ||= { journeyId: this.uuid(), startedAt: this.now() };
+        try { this.storage.setItem(key(this.product), JSON.stringify(this.cached)); } catch { /* In-memory fallback. */ }
+      }
+      return { distinctId, journeyId: this.cached.journeyId };
+    } catch { return undefined; }
+  }
+
+  track(event: SignupBrowserEvent, step = 0) {
+    try {
+      const context = this.context();
+      if (!context) return;
+      this.ph!.capture(`agent_signup_${event}`, {
+        funnel: 'agent_signup', funnel_version: 1, onboarding_method: 'agent', source: 'browser',
+        product: this.product, journey_id: context.journeyId,
+        step: Number.isInteger(step) && step >= 0 && step <= 5 ? step : 0,
+      }, event === 'page_left' || event === 'entry_clicked' || event === 'dashboard_opened' ? { transport: 'sendBeacon' } : undefined);
+    } catch { /* Optional telemetry cannot interrupt setup. */ }
+  }
+
+  leave(step: number) {
+    if (this.departed) return;
+    this.track('page_left', step);
+    this.departed = true;
+  }
+  resume() { this.departed = false; }
+
+  restart(track = true) {
+    if (track) this.track('restarted');
+    this.departed = true;
+    this.cached = undefined;
+    try { this.storage.removeItem(key(this.product)); } catch { /* Optional. */ }
+  }
+}
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index bd069794..ea5698a8 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -76,9 +76,17 @@ Check that the product matches this guide. Start by PATCHing that URL with
 Authorization: Bearer <Progress token> and Content-Type: application/json:
 
 ~~~json
-{"step":1,"state":"working","revision":0}
+{"step":1,"state":"working","revision":0,"agent":"<your agent type>"}
 ~~~
 
+Replace agent with your actual coding agent: codex, claude_code, grok, opencode,
+cursor, gemini_cli, other, or unknown. Report the tool running this setup, not
+its underlying model or the agents the user will run later. Use unknown if you
+cannot determine it; never guess from the logos on the page. Include agent in
+your first PATCH. It is stored once for signup funnel attribution; later PATCHes
+may omit it. A different known agent returns 409 agent_conflict: preserve the
+original attribution and omit agent when resuming from a different tool.
+
 Use the revision returned by the latest GET/PATCH, not the example's literal 0.
 PATCH before each numbered progress step below. A move to the next step marks
 the previous step done; do not skip steps or report success before checking it.
diff --git a/web/lib/signup-analytics-privacy.ts b/web/lib/signup-analytics-privacy.ts
new file mode 100644
index 00000000..7d866d76
--- /dev/null
+++ b/web/lib/signup-analytics-privacy.ts
@@ -0,0 +1,30 @@
+/** Scrub signup read capabilities from SDK-enriched URLs and replay metadata. */
+export function sanitizeSignupAnalytics<T>(event: T | null): T | null {
+  const seen = new WeakMap<object, unknown>();
+  function clean(value: unknown, key = ''): unknown {
+    if (/^(writeToken|write_token|progress_token|device_code|access_token|refresh_token|prompt)$/i.test(key)) return '[redacted]';
+    if (typeof value === 'string') return value
+      .replace(/([?&]session=)[^&#\s"']+/gi, '$1[redacted]')
+      .replace(/(\/api\/v1\/signup\/agent\/sessions\/)[0-9a-f-]{36}/gi, '$1[redacted]');
+    if (!value || typeof value !== 'object') return value;
+    if (seen.has(value)) return seen.get(value);
+    if (Array.isArray(value)) {
+      const result: unknown[] = []; seen.set(value, result);
+      value.forEach(item => result.push(clean(item))); return result;
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+    const result: Record<string, unknown> = {}; seen.set(value, result);
+    for (const [k, v] of Object.entries(value)) result[k] = clean(v, k);
+    return result;
+  }
+  return clean(event) as T | null;
+}
+
+/** Drop request AND response bodies/headers before the replay recorder sees them. */
+export function maskSignupNetworkRequest<T extends { name: string }>(request: T): T | null {
+  try {
+    const path = new URL(request.name, 'https://agentrelay.com').pathname;
+    if (/\/(?:cloud\/)?api\/v1\/signup\/agent\/sessions(?:\/|$)/.test(path)) return null;
+  } catch { /* A non-URL performance entry has no signup payload. */ }
+  return request;
+}
diff --git a/web/lib/test/agent-signup-analytics.test.ts b/web/lib/test/agent-signup-analytics.test.ts
new file mode 100644
index 00000000..84607da6
--- /dev/null
+++ b/web/lib/test/agent-signup-analytics.test.ts
@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { SignupTracker } from '../agent-signup-analytics';
+import { maskSignupNetworkRequest, sanitizeSignupAnalytics } from '../signup-analytics-privacy';
+
+const journeyId = '537e4857-5590-42e8-8731-66441b466542';
+const storage = () => {
+  const values = new Map<string, string>();
+  return { getItem: (key: string) => values.get(key) ?? null, setItem: (key: string, value: string) => { values.set(key, value); }, removeItem: (key: string) => { values.delete(key); } };
+};
+const ph = { __loaded: true, has_opted_out_capturing: vi.fn(() => false), get_distinct_id: vi.fn(() => 'anon-visitor'), capture: vi.fn() };
+beforeEach(() => { ph.__loaded = true; ph.has_opted_out_capturing.mockReturnValue(false); ph.capture.mockReset(); });
+
+describe('agent signup funnel', () => {
+  it.each(['teams', 'flows'] as const)('joins %s entry, copy, and server handoff across reloads', product => {
+    const store = storage();
+    const first = new SignupTracker(ph, product, store, () => journeyId, () => 1000);
+    first.track('entry_clicked');
+    expect(first.context()).toEqual({ journeyId, distinctId: 'anon-visitor' });
+    const reload = new SignupTracker(ph, product, store, () => { throw new Error('must reuse journey'); }, () => 2000);
+    reload.track('page_viewed'); reload.track('prompt_copied'); reload.track('page_left', 3);
+    const events = ph.capture.mock.calls;
+    expect(events.map(([event]) => event)).toEqual(['agent_signup_entry_clicked', 'agent_signup_page_viewed', 'agent_signup_prompt_copied', 'agent_signup_page_left']);
+    for (const [, properties] of events) expect(properties).toMatchObject({ journey_id: journeyId, product, funnel: 'agent_signup', funnel_version: 1 });
+    expect(events.at(-1)?.[1]).toMatchObject({ step: 3 });
+    expect(events.at(-1)?.[2]).toEqual({ transport: 'sendBeacon' });
+  });
+  it('creates distinct journeys by product and explicit restart', () => {
+    const uuid = vi.fn().mockReturnValueOnce(journeyId).mockReturnValueOnce('637e4857-5590-42e8-8731-66441b466542').mockReturnValueOnce('737e4857-5590-42e8-8731-66441b466542');
+    const store = storage();
+    const teams = new SignupTracker(ph, 'teams', store, uuid);
+    const flows = new SignupTracker(ph, 'flows', store, uuid);
+    expect(teams.context()?.journeyId).not.toBe(flows.context()?.journeyId);
+    teams.restart();
+    expect(teams.context()?.journeyId).not.toBe(journeyId);
+  });
+  it('deduplicates pagehide plus SPA unmount and does not seed a new journey when restarting', () => {
+    const uuid = vi.fn(() => journeyId);
+    const tracker = new SignupTracker(ph, 'teams', storage(), uuid);
+    tracker.context(); tracker.leave(3); tracker.leave(3);
+    expect(ph.capture.mock.calls.map(([event]) => event)).toEqual(['agent_signup_page_left']);
+    tracker.resume(); tracker.leave(4);
+    expect(ph.capture).toHaveBeenCalledTimes(2);
+    tracker.restart(); tracker.leave(4);
+    expect(ph.capture.mock.calls.map(([event]) => event)).toEqual(['agent_signup_page_left', 'agent_signup_page_left', 'agent_signup_restarted']);
+    expect(uuid).toHaveBeenCalledTimes(1);
+  });
+  it('does not send browser or server context when unconfigured or opted out', () => {
+    const tracker = new SignupTracker(ph, 'teams', storage(), () => journeyId);
+    ph.__loaded = false;
+    expect(tracker.context()).toBeUndefined(); tracker.track('page_viewed');
+    ph.__loaded = true; ph.has_opted_out_capturing.mockReturnValue(true);
+    expect(tracker.context()).toBeUndefined(); tracker.track('prompt_copied');
+    expect(ph.capture).not.toHaveBeenCalled();
+  });
+  it('keeps working with unavailable storage, a broken SDK, or malformed stored data', () => {
+    const broken = { getItem: () => { throw new Error(); }, setItem: () => { throw new Error(); }, removeItem: () => { throw new Error(); } };
+    const tracker = new SignupTracker(ph, 'teams', broken, () => journeyId);
+    expect(tracker.context()?.journeyId).toBe(journeyId);
+    ph.capture.mockImplementation(() => { throw new Error(); });
+    expect(() => tracker.track('page_viewed')).not.toThrow();
+    expect(() => tracker.restart()).not.toThrow();
+  });
+  it('drops replay network entries including serialized capability-bearing bodies and headers', () => {
+    for (const name of ['https://agentrelay.com/cloud/api/v1/signup/agent/sessions', '/cloud/api/v1/signup/agent/sessions/' + journeyId, 'https://cloud.example/api/v1/signup/agent/sessions/' + journeyId]) {
+      const entry = { name, requestBody: JSON.stringify({ product: 'teams' }),
+        responseBody: JSON.stringify({ id: journeyId, writeToken: 'a'.repeat(64) }),
+        requestHeaders: { Authorization: 'Bearer private' } };
+      expect(maskSignupNetworkRequest(entry)).toBeNull();
+    }
+    const safe = { name: 'https://agentrelay.com/api/v1/flows/catalog' };
+    expect(maskSignupNetworkRequest(safe)).toBe(safe);
+  });
+  it('scrubs SDK URL enrichment and nested replay metadata without mutating the original event', () => {
+    const id = '637e4857-5590-42e8-8731-66441b466542';
+    const event = { event: '$pageleave', properties: { $current_url: `https://agentrelay.com/signup/teams?session=${id}&utm_source=docs`, $referrer: `http://localhost:3100/signup/teams?session=${id}`, prompt: 'private prompt with token', writeToken: 'secret', journey_id: journeyId, nested: [{ url: `https://agentrelay.com/cloud/api/v1/signup/agent/sessions/${id}` }] } };
+    const clean = sanitizeSignupAnalytics(event)!;
+    expect(JSON.stringify(clean)).not.toContain(id);
+    expect(JSON.stringify(clean)).not.toContain('private prompt');
+    expect(JSON.stringify(clean)).not.toContain('secret');
+    expect(clean.properties.journey_id).toBe(journeyId);
+    expect(clean.properties.$current_url).toContain('utm_source=docs');
+    expect(event.properties.writeToken).toBe('secret');
+  });
+});

From 7b884efe4a398f6229dc3b9c72db241bbe6c3b1d Mon Sep 17 00:00:00 2001
From: agentrelaybot <agentrelaybot@agentrelay.dev>
Date: Tue, 22 Sep 2026 10:04:17 -0700
Subject: [PATCH 08/10] use cloud key first run

---
 web/lib/agent-signup.ts | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index ea5698a8..66a124ef 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -311,7 +311,9 @@ Do not invent a repository or enable automation on an unrelated project.
 GET ${site}/api/v1/flows/catalog and select a matching entry from flows.
 GET ${site}/api/v1/flows/catalog/<id> for its full contract. Use the catalog's
 supportedRepositoryHosts, defaultTrigger, inputs.required, inputs.defaults, and
-inputs.allowedAgents. Download source.rawUrl, verify its bytes against
+inputs.allowedAgents. Name a model per harness in inputs.models when the house
+default is wrong (for example {"claude": "claude-sonnet-4"}); omit it to fund
+the house default for each declared agent. Download source.rawUrl, verify its bytes against
 source.sha256, and use that source text unchanged for a recommended flow.
 The source is TypeScript, not the source URL. Do not guess a template or hash.
 For custom flows use ${site}/docs/relayflows/markdown/build.md and
@@ -333,8 +335,11 @@ Check GET /api/v1/workspaces/<workspaceId>/integrations/<provider>/status
 until ready is true (poll with backoff and a bounded timeout); a returned connect
 link or a closed popup alone does not prove the integration is ready.
 
-Connect the coding agent required by the catalog using the official Relay CLI
-with the private credential environment from step 1 and a PTY:
+Do not connect a Claude or Codex subscription yet. The first three runs use
+Cloud's own model key, so no provider login is needed to activate. After those
+runs, activation and launches will ask for your own subscription; only then use
+the official Relay CLI with the private credential environment from step 1 and
+a PTY:
 
 ~~~sh
 npx --yes agent-relay@latest cloud connect anthropic --api-url '${cloud}'
@@ -345,9 +350,8 @@ The command drives provider login; open its authorization URL for the user,
 and keep the process alive until it confirms the credential is connected.
 Google approval does not grant GitHub or model-provider access: those services
 may require their own consent. Never fabricate credentials or claim consent
-happened. If already connected, GET /api/v1/cloud-agents lets you inspect the
-account's credential state without reconnecting. Provider or sandbox service
-configuration failures must be fixed before activation can succeed.
+happened. GET /api/v1/cloud-agents lets you inspect the account's credential
+state without reconnecting.
 
 ## 4. Activate through the same API as web onboarding
 

From 4c129bb2db1d0ca307be647e5092e1627204d876 Mon Sep 17 00:00:00 2001
From: khaliqgant <khaliqgant@gmail.com>
Date: Tue, 22 Sep 2026 21:59:47 -0700
Subject: [PATCH 09/10] Fix expired-session recovery, retry, and analytics
 journey join

Cursor review on #112 surfaced three live defects in the signup
journey plus one stale finding:

- Expired sessions at step 0 still rendered waiting copy, agent
  icons, and a disabled copy CTA alongside the restart path.
- "Try again" after a missing-session 404 kept the dead ?session=
  param and expired state, re-requesting the same expired id.
- page_viewed and the session POST fired before PostHog finished
  loading, so Cloud stored no journey_id and later browser events
  could not join the funnel. contextWhenReady waits briefly (<=2s)
  for the SDK without ever blocking setup.
- The credential-copy finding was stale post Cloud #3944 (house
  promotion admits activation without a connected subscription);
  added the one real caveat: multi-agent flows can only house-fund
  a single declared harness per run.

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

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 web/components/AgentSignupJourney.tsx       | 29 +++++++++++++++------
 web/lib/agent-signup-analytics.ts           | 11 ++++++++
 web/lib/agent-signup.ts                     |  5 +++-
 web/lib/test/agent-signup-analytics.test.ts | 13 +++++++++
 4 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/web/components/AgentSignupJourney.tsx b/web/components/AgentSignupJourney.tsx
index b7361fb2..7460f58c 100644
--- a/web/components/AgentSignupJourney.tsx
+++ b/web/components/AgentSignupJourney.tsx
@@ -110,8 +110,14 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
     const requested = new URL(window.location.href).searchParams.get('session');
     let owner = !requested;
     try { owner ||= JSON.parse(sessionStorage.getItem(storageKey(product)) || 'null')?.id === requested; } catch { /* Read-only until proven otherwise. */ }
-    if (owner && !viewed.current) { analytics.track('page_viewed'); viewed.current = true; }
-    boot.current ||= startSession(product, owner ? analytics.context() : undefined);
+    if (owner && !viewed.current) viewed.current = true;
+    boot.current ||= (async () => {
+      // Wait briefly for PostHog so page_viewed, the session POST, and later
+      // events share one journey_id; never block setup on telemetry.
+      const context = owner ? await analytics.contextWhenReady() : undefined;
+      if (owner) analytics.track('page_viewed');
+      return startSession(product, context);
+    })();
     void boot.current.then(({ progress: initial, token: writeToken }) => {
       if (cancelled) return;
       setProgress(initial); setToken(writeToken); setError('');
@@ -168,7 +174,7 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
   const detail = expired ? 'Start a new session to keep watching setup.' : complete ? 'Your agent has verified setup. You’re ready to go.' : failed ? 'Check your agent’s conversation to resolve the issue. Progress will resume here.' : paused ? 'Follow the approval request in your agent’s conversation. We’ll pick up right here.' : active ? steps[active - 1].detail : 'The show starts when you paste the prompt into your agent.';
   const mode = expired || error ? 'offline' : complete ? 'complete' : failed ? 'failed' : paused ? 'paused' : active ? 'working' : 'waiting';
 
-  const heading = complete ? 'All yours.' : active ? title : 'Leave it to your agent.';
+  const heading = complete ? 'All yours.' : expired || failed || active ? title : 'Leave it to your agent.';
 
   return (
     <div className={`${s.page} ph-sensitive ph-no-capture`} data-mode={mode}>
@@ -177,8 +183,8 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
       <main className={s.main}>
         <div className={s.content}>
           <h1>{heading}</h1>
-          <p className={s.subtitle}>{complete ? 'Your agent has verified setup. You’re ready to go.' : active ? detail : 'Give this prompt to your coding agent and hang out here to watch it sign you up.'}</p>
-          {!complete && !active && (
+          <p className={s.subtitle}>{complete ? 'Your agent has verified setup. You’re ready to go.' : expired || failed || active ? detail : 'Give this prompt to your coding agent and hang out here to watch it sign you up.'}</p>
+          {!complete && !active && !expired && !failed && (
             <div className={s.agents} role="img" aria-label="Codex, Claude Code, Grok, and OpenCode">
               <span title="Codex"><AgentToolLogo provider="codex" className={s.agentLogo} /></span>
               <span title="Claude Code"><AgentToolLogo provider="claude" className={s.agentLogo} /></span>
@@ -187,13 +193,20 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
             </div>
           )}
           {complete ? <a onClick={() => { if (token) analytics.track('dashboard_opened', active); }} className={s.primary} href={teamsCloudUrl(product === 'teams' ? '/dashboard/sessions' : '/dashboard')}>Open {product === 'teams' ? 'your workspace' : 'dashboard'} <ArrowUpRight size={17} /></a>
-            : !active ? <button type="button" className={s.primary} disabled={!prompt || expired} onClick={() => void copy()}>{copyMessage.startsWith('Copied') ? <Check size={17} /> : <Copy size={17} />}{copyMessage.startsWith('Copied') ? 'Prompt copied' : 'Copy setup prompt'}</button> : null}
-          <p className={s.copyStatus} role="status">{complete ? '' : active ? (paused ? 'Your agent will continue after you approve.' : 'You can leave this page open.') : copyMessage || (progress && !token ? 'Watching this session. The prompt is in the original browser tab.' : product === 'teams' ? 'Paste into a coding agent on your Mac.' : 'Paste into a coding agent with terminal access.')}</p>
+            : !active && !expired ? <button type="button" className={s.primary} disabled={!prompt} onClick={() => void copy()}>{copyMessage.startsWith('Copied') ? <Check size={17} /> : <Copy size={17} />}{copyMessage.startsWith('Copied') ? 'Prompt copied' : 'Copy setup prompt'}</button> : null}
+          <p className={s.copyStatus} role="status">{complete ? '' : active ? (paused ? 'Your agent will continue after you approve.' : 'You can leave this page open.') : copyMessage || (expired ? '' : progress && !token ? 'Watching this session. The prompt is in the original browser tab.' : product === 'teams' ? 'Paste into a coding agent on your Mac.' : 'Paste into a coding agent with terminal access.')}</p>
           <div className={s.progress} role="status" aria-live="polite">
             <div className={s.progressDots} aria-hidden="true">{steps.map((step, index) => <i key={step.title} data-done={complete || active > index + 1} data-current={!complete && active === index + 1} />)}</div>
             <span>{expired ? 'Session expired' : error ? 'Waiting for a connection' : complete ? 'Setup complete' : active ? `${active} of 5 · ${paused ? 'Waiting for your approval' : failed ? 'Needs your attention' : steps[active - 1].title}` : progress ? 'Ready when your agent is' : 'Preparing your session…'}</span>
           </div>
-          {error && <div className={s.error} role="alert"><p>{error}</p>{!progress && <button type="button" onClick={() => { boot.current = null; setError(''); setAttempt(value => value + 1); }}>Try again <RefreshCw size={12} /></button>}</div>}
+          {error && <div className={s.error} role="alert"><p>{error}</p>{!progress && <button type="button" onClick={() => {
+            boot.current = null; setError(''); setExpired(false); trackedExpired.current = false;
+            try { sessionStorage.removeItem(storageKey(product)); } catch { /* Storage is optional. */ }
+            const url = new URL(window.location.href);
+            url.searchParams.delete('session');
+            window.history.replaceState(window.history.state, '', url);
+            setAttempt(value => value + 1);
+          }}>Try again <RefreshCw size={12} /></button>}</div>}
           <details className={s.details} onToggle={event => { if (event.currentTarget.open && token) analytics.track('details_opened', active); }}>
             <summary>Setup details</summary>
             <div className={s.detailBody}>
diff --git a/web/lib/agent-signup-analytics.ts b/web/lib/agent-signup-analytics.ts
index c6655ae6..dfdc3967 100644
--- a/web/lib/agent-signup-analytics.ts
+++ b/web/lib/agent-signup-analytics.ts
@@ -36,6 +36,17 @@ export class SignupTracker {
     } catch { return undefined; }
   }
 
+  /** Wait briefly for PostHog so early funnel events and the session POST share one journeyId. Telemetry never blocks setup longer than `timeoutMs`. */
+  async contextWhenReady(timeoutMs = 2000): Promise<SignupAnalyticsContext | undefined> {
+    const attempts = Math.max(1, Math.ceil(timeoutMs / 150));
+    for (let i = 0; i <= attempts; i++) {
+      const context = this.context();
+      if (context) return context;
+      if (i < attempts) await new Promise(resolve => setTimeout(resolve, 150));
+    }
+    return undefined;
+  }
+
   track(event: SignupBrowserEvent, step = 0) {
     try {
       const context = this.context();
diff --git a/web/lib/agent-signup.ts b/web/lib/agent-signup.ts
index 66a124ef..dc697090 100644
--- a/web/lib/agent-signup.ts
+++ b/web/lib/agent-signup.ts
@@ -336,7 +336,10 @@ until ready is true (poll with backoff and a bounded timeout); a returned connec
 link or a closed popup alone does not prove the integration is ready.
 
 Do not connect a Claude or Codex subscription yet. The first three runs use
-Cloud's own model key, so no provider login is needed to activate. After those
+Cloud's own model key, so no provider login is needed to activate. If the chosen
+flow declares more than one coding agent in inputs.agents, included Cloud runs
+can fund only one of them per run — connect your own subscription for at least
+one declared agent before activating a multi-agent flow. After the included
 runs, activation and launches will ask for your own subscription; only then use
 the official Relay CLI with the private credential environment from step 1 and
 a PTY:
diff --git a/web/lib/test/agent-signup-analytics.test.ts b/web/lib/test/agent-signup-analytics.test.ts
index 84607da6..054d9d54 100644
--- a/web/lib/test/agent-signup-analytics.test.ts
+++ b/web/lib/test/agent-signup-analytics.test.ts
@@ -44,6 +44,19 @@ describe('agent signup funnel', () => {
     expect(ph.capture.mock.calls.map(([event]) => event)).toEqual(['agent_signup_page_left', 'agent_signup_page_left', 'agent_signup_restarted']);
     expect(uuid).toHaveBeenCalledTimes(1);
   });
+  it('waits briefly for the SDK so early events and the session POST share one journey', async () => {
+    ph.__loaded = false;
+    const tracker = new SignupTracker(ph, 'flows', storage(), () => journeyId);
+    const pending = tracker.contextWhenReady(500);
+    ph.__loaded = true;
+    await expect(pending).resolves.toEqual({ journeyId, distinctId: 'anon-visitor' });
+  });
+  it('returns undefined without blocking setup when the SDK never loads', async () => {
+    ph.__loaded = false;
+    const tracker = new SignupTracker(ph, 'flows', storage(), () => journeyId);
+    await expect(tracker.contextWhenReady(50)).resolves.toBeUndefined();
+    expect(ph.capture).not.toHaveBeenCalled();
+  });
   it('does not send browser or server context when unconfigured or opted out', () => {
     const tracker = new SignupTracker(ph, 'teams', storage(), () => journeyId);
     ph.__loaded = false;

From e8d60fbd0ebad2fcc090a7529b9e775c2d16c380 Mon Sep 17 00:00:00 2001
From: khaliqgant <khaliqgant@gmail.com>
Date: Tue, 22 Sep 2026 22:09:53 -0700
Subject: [PATCH 10/10] Preserve recoverable sessions on retry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cursor re-review of 4c129bb (bug 37ba8ad7): Try again cleared the
stored session and ?session= unconditionally, so a transient load
failure discarded a still-valid session and silently forked a new
one — watchers could become owners of a different progress token.
Scope the session reset to the expired path only; other errors now
retry the same session id.

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

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 web/components/AgentSignupJourney.tsx | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/web/components/AgentSignupJourney.tsx b/web/components/AgentSignupJourney.tsx
index 7460f58c..89aaf70b 100644
--- a/web/components/AgentSignupJourney.tsx
+++ b/web/components/AgentSignupJourney.tsx
@@ -200,11 +200,15 @@ export function AgentSignupJourney({ product }: { product: AgentSignupProduct })
             <span>{expired ? 'Session expired' : error ? 'Waiting for a connection' : complete ? 'Setup complete' : active ? `${active} of 5 · ${paused ? 'Waiting for your approval' : failed ? 'Needs your attention' : steps[active - 1].title}` : progress ? 'Ready when your agent is' : 'Preparing your session…'}</span>
           </div>
           {error && <div className={s.error} role="alert"><p>{error}</p>{!progress && <button type="button" onClick={() => {
-            boot.current = null; setError(''); setExpired(false); trackedExpired.current = false;
-            try { sessionStorage.removeItem(storageKey(product)); } catch { /* Storage is optional. */ }
-            const url = new URL(window.location.href);
-            url.searchParams.delete('session');
-            window.history.replaceState(window.history.state, '', url);
+            boot.current = null; setError('');
+            if (expired) {
+              // Only a dead session gets replaced; transient failures retry the same one.
+              setExpired(false); trackedExpired.current = false;
+              try { sessionStorage.removeItem(storageKey(product)); } catch { /* Storage is optional. */ }
+              const url = new URL(window.location.href);
+              url.searchParams.delete('session');
+              window.history.replaceState(window.history.state, '', url);
+            }
             setAttempt(value => value + 1);
           }}>Try again <RefreshCw size={12} /></button>}</div>}
           <details className={s.details} onToggle={event => { if (event.currentTarget.open && token) analytics.track('details_opened', active); }}>