Onboarding flow on the new Shell

[schmug]

After the rebrand work shipped (PRs #59, #60, #61), the only public surface that doesn't sit inside `app/components/phishsoc/Shell` is `app/routes/home.tsx` — the mailbox picker users hit before they have a mailbox selected. Today it shows:

• `` header (added in PR PhishSOC UI continuation: rebrand sweep + loading/error states + auto-draft & model picker #59)
• "Create mailbox" + "select existing mailbox" UI
• No CF Access onboarding context, no setup checks, no welcome state.

Upstream PR #10 was an attempt at a richer onboarding flow but predates the Shell and was based on different design assumptions. We chose not to pull it in.

What "PhishSOC onboarding" needs

To be discussed in a brainstorming session, but candidates:

1. First-run wizard — detect zero mailboxes + zero settings and offer guided setup: domain entered, R2 bucket confirmed, CF Access configured, first mailbox created.
2. CF Access JWT error UX — upstream issue #4 flagged the unhelpful "Missing required CF Access JWT" surface. New onboarding flow should detect this state (Worker reachable but Access misconfigured) and link to the troubleshooting steps in README.
3. Empty-state copy on home — once we have ≥1 mailbox, the empty-state messaging in `home.tsx` should reflect the SOC framing ("No mailboxes yet — set one up to start triaging mail").
4. Telemetry / quickstart checklist — show the user what's working (Email Routing rule, R2, AI binding) and what isn't, so a misconfiguration is visible without hitting the logs.

Architecture note

Onboarding should consume the Shell where possible (e.g., a "setup" route at `/setup` that uses a stripped-down Shell variant without the mailbox-required nav). The mailbox picker stays as the index route; `/setup` is a separate flow.

Sequence

This is its own brainstorming → spec → plan cycle. Do not start implementing without a written spec.

[schmug]

Spec proposal: phase the onboarding into three small flows, not one big wizard

Re-reading the issue's four candidates, they collapse into three flows with different ownership, different trigger conditions, and different blockers. Treating them as one "first-run wizard" forces all of them to happen in the wrong order.

Phase 1 — Honest empty-state (ship immediately, no spec needed)

Trigger: mailboxes.length === 0, page is / (org overview) or /mailboxes.

Action: Replace the current empty-state copy in home.tsx and mailboxes.tsx with the SOC framing the issue calls out:

"No mailboxes yet — set one up to start triaging mail."

Why first: This is a 30-line PR that closes the issue's candidate #3. No new routes, no new state. The remaining phases land on top.

Phase 2 — /setup route with diagnostic checklist (issue's candidate #4)

Trigger: Operator clicks "Run setup check" from the empty-state CTA, or hits /setup directly.

Action: Render a Shell variant (no mailbox-required nav) showing four readiness checks against the worker:

1. Domain configured: GET /api/v1/config returns at least one entry in domains. ✓ / ✗ + the configured value.
2. R2 bucket reachable: worker performs a HEAD on a known key (or returns the binding shape). ✓ / ✗.
3. AI binding live: worker runs a tiny ai.run("@cf/meta/llama-3.1-8b-instruct-fast", {prompt: "ok", max_tokens: 1}) once, caches result for 5 min. ✓ / ✗.
4. Email Routing rule: can't be detected from inside the worker (no API). Render as a checklist item the operator confirms manually with a link to the Email Routing dashboard.

Each row links to the README section that documents how to fix it. Stretch: a "Refresh" button re-runs all checks.

Why this shape: Replaces the "look at the logs to figure out what's misconfigured" failure mode with a single page. Doesn't pretend to do the setup — operators still configure secrets via wrangler / dashboard. Avoids the trap of building a config UI that reads/writes secrets through the worker, which would itself need its own auth model.

Phase 3 — Access-misconfig detection (issue's candidate #2)

Trigger: Worker returns the existing "Missing required CF Access JWT" error.

Action: The frontend already shows that error. Wrap it with:

• "Cloudflare Access isn't configured on this Worker yet."
• A direct link to the relevant Cloudflare dashboard page.
• A pointer to the README troubleshooting section (the one that exists since the rebrand).

Why last: This is the bug from upstream cloudflare/agentic-inbox#4 that the README troubleshooting section already addresses. Operators who hit this know to look at the README — wrapping the inline error is polish, not a blocker.

Explicitly NOT in scope

• A first-run wizard in the sense of a multi-step modal that creates the mailbox + writes secrets + tests Access for you. Secrets must stay in the wrangler/dashboard channel, period. A wizard that doesn't write secrets is just a worse version of the diagnostic checklist.
• Telemetry beyond the four checks above. We don't have an anonymous-telemetry channel and adding one is its own decision.

Proposed sequencing

1. Phase 1 lands as a small PR — closes the home.tsx/mailboxes.tsx empty-state portion of this issue.
2. Phase 2 gets its own issue + PR, blocked on agreement that the four checks are the right four.
3. Phase 3 gets its own small PR, no spec needed beyond the wrap.

Happy to take Phase 1 as a quick follow-up if this shape sounds right. Phases 2/3 want a written-down ack first since they touch routing.

[schmug]

Spec needed before implementation.

The Shell rebrand (PRs #59–#61) landed, but this issue's scope is still under-specified. Before picking this up, the following questions need answers:

1. Trigger: Is the onboarding flow shown only on first login (empty-state detect) or always accessible from a settings page?
2. Steps: Which steps are in scope? (domain setup, mailbox creation, MX record check, DKIM/SPF check, test email send, CF Access policy link?)
3. State machine: Where is "completed" stored? org/settings.json onboardingComplete: true? Or is it derived from whether any mailbox exists?
4. Relationship to Add in-app domain onboarding flow (replace wrangler.jsonc DOMAINS edit) #181: The in-app domain onboarding flow (PR feat: in-app domain onboarding flow (#181) #226) covers the domain-add step. Does this issue superset that, or is it a separate wizard that calls the same API?

Recommend defining acceptance criteria (ideally as a checklist matching the AC format used in #151, #181, etc.) before implementation starts.

---

Generated by Claude Code

[schmug]

Triage: Bucket C — written spec required before implementation.

The issue explicitly calls this out. Below is a proposed 1-page spec to review; once accepted, implementation can be dispatched.

---

PhishSOC Onboarding Flow — Draft Spec

Goal: Give a first-time operator a guided path from zero → first scoped mailbox, without requiring them to read the README.

Routes

Route	Purpose
/ (existing home.tsx)	Mailbox picker; no change to existing flow
/setup (new)	Linear wizard; stripped-down Shell (no mailbox nav)

/setup is only reachable explicitly (no auto-redirect from /). Operators who already have mailboxes can ignore it.

Wizard steps (in order)

1. Welcome — short copy explaining what PhishSOC does. "Let's get you set up."
2. CF Access check — the Worker calls itself to confirm CF-Access-JWT-Assertion is present. If missing (Access misconfigured), show inline troubleshooting: link to README § Access setup, "retry" button.
3. Domain entry — text input for the domain to receive mail. Validates format only (no DNS check at this step).
4. Infrastructure checklist — read-only status tiles fetched from a new GET /api/v1/setup/status endpoint:
   • R2 bucket reachable (try a BUCKET.head("__setup_probe__"))
   • AI binding present (env.AI !== undefined)
   • Email Routing rule (can't auto-detect; show "configure in Cloudflare dashboard" link with a checkbox the operator ticks manually)
5. Create first mailbox — calls the existing POST /api/v1/mailboxes with the domain from step 3. On success, redirects to /mailbox/:id.

Empty-state copy update (home.tsx)

When mailbox list is empty: "No mailboxes yet — set one up to start triaging mail." Button: "Run setup wizard" → /setup.

CF Access JWT error surface

On any 401/403 from the Worker, the app (not just /setup) should display: "CF Access is misconfigured — see [troubleshooting]" rather than a blank screen.

Out of scope for v1

• Telemetry/quickstart checklist beyond the infrastructure tiles.
• Bulk-onboarding multiple mailboxes.
• Auto-detecting Email Routing rule configuration (Cloudflare API scope is not available from inside the Worker).

---

Please confirm or revise before implementation begins.

---

Generated by Claude Code

[schmug]

Draft Spec: PhishSOC Onboarding Flow

This spec is filed before implementation per the issue's explicit instruction. Awaiting human review before any code ships.

---

Goals

1. A first-time operator who has just deployed the Worker should be guided to a working state without reading the README.
2. An operator whose CF Access is misconfigured should see a clear error with a fix path, not a blank screen.
3. Once onboarded, the home route's empty-state copy should reflect the SOC framing.

---

Routes

Route	Purpose	Shell variant
/ (home.tsx)	Mailbox picker / entry point	Existing <Shell> without mailbox nav
/setup	Step-by-step wizard (zero-mailbox state only)	Stripped Shell: no mailbox nav, no sidebar

Auto-redirect: if the API returns 0 mailboxes AND the user has never dismissed setup, redirect from / to /setup. Once one mailbox exists, /setup redirects back to /.

---

/setup wizard steps

Step 1 — Prerequisites check (read-only API calls, no mutations)

• R2 binding reachable? (GET /api/v1/health/r2)
• AI binding available? (GET /api/v1/health/ai)
• Email Routing rule exists? (heuristic: GET /api/v1/mailboxes succeeds without 500)
• Render a checklist: green ✓ / red ✗ per check. Failing checks link to the relevant README section.

Step 2 — Create first mailbox

• Inline form: mailbox name, accepted domain(s), catch-all address.
• On success: store setup_dismissed = true in localStorage and redirect to the new mailbox view.

Step 3 — (Optional) Intel hub

• Input for hub URL + API key.
• "Skip for now" advances; hub config can be set later in Settings.

Wizard state is client-side only (no DO/KV writes for setup progress). If the user closes and returns, Step 1 re-runs the health checks; completed steps are not persisted across sessions.

---

CF Access error UX

Detection: the Worker returns 401 or 403 with body containing "CF-Access" or "JWT" when Access is misconfigured. Alternatively, the SPA fails to reach /api/v1/me entirely.

Handling (in app/root.tsx or a top-level error boundary):

• If the root fetch to /api/v1/me returns 401/403, render a full-page error card (no Shell needed):
  • Heading: "Access not configured"
  • Body: "PhishSOC is protected by Cloudflare Access. You may need to log in or the Access policy may not be configured correctly."
  • Link: "Troubleshooting guide" → README anchor #cloudflare-access-setup
  • Link: "Try again" → window.location.reload()

---

Empty-state copy (home.tsx)

When 0 mailboxes exist and setup has been dismissed (or wizard is skipped):

No mailboxes yet — set one up to start triaging mail.
[Create mailbox →]

When ≥1 mailbox exists but none selected:

Select a mailbox from the left, or create a new one.

---

Out of scope for v1

• Telemetry / quickstart checklist beyond the Step 1 health check (too much infra surface for onboarding)
• Multi-step progress persistence in DO/KV
• /setup/sidecar route (API-sidecar mode is tracked in feat: API-sidecar mode — score existing tenant mail without MX change (Workspace + M365) #31 and depends on feat: MailProvider adapter interface — refactor inbound/outbound behind a pluggable provider boundary #30)
• Automated test for the CF Access error card (requires mocking the Access layer)

---

Open questions for human review

1. Should Step 1 health checks be real API endpoints added to workers/index.ts, or client-side guesses based on whether /api/v1/mailboxes succeeds? Real endpoints are more reliable but add surface; heuristic is simpler.
2. Should "setup_dismissed" live in localStorage (simple, per-browser) or in the org-level DO settings (consistent across devices)? The DO approach requires a new settings key.
3. Does the /setup route need CF Access protection? (It's inside the Worker so Access applies to the whole origin already.)

---

needs-spec label applied. Implementation should not start until questions above are resolved.

---

Generated by Claude Code

[schmug]

Onboarding Flow — Draft Spec v0.1

Posted per the "spec before implementation" instruction in the issue body. Awaiting review before any code is written.

---

Problem statement

After the PhishSOC rebrand (PRs #59–#61), home.tsx is the only public surface outside the Shell. A new operator hitting a fresh deploy sees either:

• The org overview with empty/zero stats (no context for what to do next)
• The bare EmptyOrg empty state — currently just an EnvelopeIcon and a link to /mailboxes

There is no detection of misconfiguration, no CF Access error guidance, and no SOC-framed setup narrative.

---

Goals

#	Goal	Priority
G1	Replace EmptyOrg with a first-run checklist that explains what to configure	High
G2	Detect and explain the "Worker reachable but CF Access misconfigured" state	High
G3	Update SOC-framed empty-state copy throughout home.tsx	Medium
G4	Quickstart health checklist (Email Routing, R2, AI binding)	Low — requires health-check API (file separately)

---

Proposed states / surfaces

State 1 — First-run: zero mailboxes (replaces EmptyOrg)

When data.mailboxesCount === 0 && mailboxCount === 0, replace the current generic card with a numbered checklist:

Start here
──────────────────────────────────────────────
1. Configure Cloudflare Email Routing
   Forward your domain's catch-all to this Worker.

2. Create your first mailbox
   [Go to Mailboxes →]

3. Set up domain security (DMARC / SPF / DKIM)
   [Go to Domains →]

4. Connect a threat-intel hub (optional)
   [Go to Hub →]

No infra detection in v1 — static list. Dynamic health checks are a follow-up (G4).

State 2 — CF Access JWT error UX

Detection: API responses with 401 status whose body includes "Missing required CF Access JWT" or "cf-access" in the WWW-Authenticate header.

Surface in OrgError (already rendered on isError): replace the generic "Couldn't load the org overview" with a card:

CF Access not configured
────────────────────────
The Worker is reachable but Cloudflare Access rejected the
request. This usually means the Access application isn't
assigned to your account or the JWT cookie expired.

→ Troubleshooting steps in README
→ Retry

Implementation: detect the CF Access error in the useOrgOverview query's queryFn (throw a typed error) and branch in OrgError on the error type.

State 3 — Empty-state SOC copy

Update EmptyOrg copy:

• Heading: "No mailboxes yet" → "No mailboxes yet — set one up to start triaging mail."
• Body: remove generic "Provision a mailbox…" text; replace with CTA-first layout

---

Architecture options

Option	Description	Effort	Recommendation
A	Modify EmptyOrg + OrgError in home.tsx directly	Small (1–2 files)	Ship first
B	New /setup route with stripped Shell variant	Medium (new route + Shell variant)	Follow-up issue once A ships and design is agreed
C	First-run modal/overlay	Medium	Not recommended — routes are simpler

Recommendation: Ship Option A (G1, G2, G3) in one PR. File a separate feat: /setup route issue for Option B once operator feedback confirms what's needed.

---

Open questions (need answers before implementation)

1. Health-check API (G4): Should the first-run checklist detect actual infra state (Email Routing rule, R2 bucket, AI binding) via a /api/v1/health endpoint, or stay as a static list in v1? Static is faster; dynamic requires a new Worker endpoint.

2. CF Access error detection placement: Should detection happen in the query queryFn (typed error), in the React Router error boundary, or as a Response header from the Worker itself (return X-PhishSOC-Error: cf-access-jwt on 401)?

3. Design sign-off: Is there a mockup or design expectation, or is copy + behavior description sufficient to implement?

4. /setup route scope: Should the /setup route (Option B) be scoped to this issue or filed separately?

---

Proposed implementation breakdown (once spec approved)

1. app/routes/home.tsx — Update EmptyOrg with first-run checklist copy (G1, G3)
2. app/routes/home.tsx / app/queries/org.ts — CF Access error detection and display (G2)
3. Follow-up issue: feat: /setup route with stripped Shell variant (Option B)
4. Follow-up issue: feat: health-check API endpoint for dynamic infra status (G4)

---

Drafted by Claude Code autonomous cleanup pass. Awaiting human review before any code changes.

---

Generated by Claude Code

[schmug]

Draft spec — PhishSOC onboarding flow

This is a spec draft for human review, not an implementation. Per the issue body: "Do not start implementing without a written spec."

---

Scope

Add a lightweight onboarding experience for the two states where app/routes/home.tsx currently shows nothing useful:

1. Zero-mailbox / unconfigured state — user has authenticated but has not yet created a mailbox or confirmed infra is wired.
2. CF Access misconfiguration state — Worker is reachable but the Cf-Access-Authenticated-User-Email header is absent, producing a confusing error surface.

Out of scope for this spec: the full telemetry/quickstart checklist (candidate 4 from the issue), the /setup wizard route (candidate 1), and any changes inside Shell.tsx.

---

Route structure

No new routes. Changes live entirely within app/routes/home.tsx (the index route rendered before a mailbox is selected).

/            →  home.tsx (already exists)

The issue suggests a /setup route as a separate flow, but introducing a new route requires a new nav entry, new breadcrumb handling, and new auth guards — that is a larger change than this spec targets. Recommend keeping onboarding in home.tsx as conditional render states and filing /setup as a follow-up if full wizard UX is needed.

---

Proposed render states in home.tsx

State	Condition	UI
Loading	useMailboxes() is pending	existing skeleton / spinner
CF Access error	useMe() returns an error (Access header absent)	AccessErrorBanner (see below)
Empty state	mailboxes list is empty	enhanced empty-state with SOC framing (see below)
Has mailboxes	mailboxes list is non-empty	existing mailbox picker, unchanged

Detection of the CF Access error state: GET /api/v1/me is already wired (PR #204, api.getMe()). An error from that endpoint while the Worker is reachable indicates Access is misconfigured. The useMe query can be added to home.tsx and checked before rendering the mailbox picker.

---

Component specs

AccessErrorBanner

A yellow/warning banner rendered above the mailbox picker when useMe() fails:

⚠  CF Access is not configured correctly.

The Worker is reachable but your identity could not be verified.
Check that the Access application covers this domain and that
you are visiting via the Cloudflare Access URL (not a direct Workers URL).

[View setup docs]   [Retry]

• "View setup docs" links to the README anchor for CF Access setup (no external URL guessing — anchor into the same repo README).
• "Retry" calls refetch() on the useMe query.
• Does not block the rest of the page — the mailbox picker still renders below it (in case Access is partially working).

Empty-state copy

Replace the generic "Create mailbox" UI text with SOC-framed copy:

No mailboxes yet

Set one up to start triaging phishing mail.
Each mailbox gets its own AI pipeline, threat-intel hub connection,
and per-sender history.

[Create your first mailbox]

The "Create your first mailbox" button opens the existing create-mailbox flow (no new routes needed).

---

Open design questions for human review

1. CF Access error banner placement: above vs. replacing the mailbox picker. Above is friendlier (doesn't block legitimate setups where Access is partially working); replacing is cleaner. Which do you prefer?

2. Empty-state illustration: the current UI uses no illustrations. Should the empty state include a simple icon/graphic, or is copy-only preferred to keep the UI minimal?

3. /setup wizard scope: the issue lists a first-run wizard (candidate 1) as a candidate. Should this spec expand to include it in the same PR, or land the simpler empty-state + Access-error UX first and file /setup separately?

4. Telemetry checklist (candidate 4 from issue): this requires calling Cloudflare APIs to check binding health (R2, Email Routing, AI). That is a significant scope addition. Defer to a separate issue?

---

Acceptance criteria (proposed)

• home.tsx renders AccessErrorBanner when GET /api/v1/me fails with a non-network error while the Worker is reachable.
• Empty-state copy uses SOC framing ("No mailboxes yet — set one up to start triaging mail").
• No new routes introduced; no changes to Shell.tsx.
• Existing mailbox-picker behavior is unchanged when mailboxes exist.
• Unit tests for the two new render states (Access error + empty state).

---

Awaiting human review on the four open questions before implementation begins.

---

Generated by Claude Code