Onboarding — Connect a broker (optional)

Summary

An unnumbered, always-skippable interstitial shown once, after plan selection and before the dashboard. Not "Step 3" — onboarding-consent and onboarding-plan remain the only two counted onboarding steps; this is a discovery nudge for settings-linked-brokers, not a core step. Reuses the same broker cards and copy as that Settings surface so there's one canonical "connect a broker" experience, entered from two places.

Raw wireframe

• .context/designs/web/onboarding/connect-broker.html

Copy

• Badge: "Optional"
• Heading: "Want your holdings to sync automatically?"
• Sub: "Connect a broker and Chitragupt reads your current holdings for you — no statement to find or upload. Read-only: we can see your holdings and trades, never place an order. Skip this if you'd rather upload statements, or come back to it any time from Settings."
• Broker cards: Dhan ("Holdings only · no live price on this broker's feed"), Zerodha (Kite), Upstox, Angel One — each "Holdings + live price" except Dhan.
• Bottom bar: "← Back" (to onboarding-plan) · "Skip for now →" (to dashboard)
• Footer: "Don't use one of these brokers? No problem — upload your broker's holdings statement in Inbox instead, any time."

Behaviour

• Never blocks. Skip and Connect both land on the dashboard — Skip immediately, Connect after the OAuth redirect/callback completes. Route is /onboarding/brokers; both exits from the plan step (paid and skipped) lead here.
• Connecting a broker here writes the same linked-account record and triggers the same first sync as connecting from settings-linked-brokers — there's no onboarding-specific data path. Enforced structurally, not by convention: this page renders the same server option list and drives the same useBrokerConnect controller and credential form as the Settings surface. Only the layout differs (cards here, a row list there), per the two wireframes.
• The broker redirects back to one registered URL — /settings/brokers/callback — regardless of where the connect started, so the starting surface is stashed in sessionStorage and read back: a connect begun here lands on the dashboard, not in Settings mid-signup. Never carried in the redirect URL, since that round-trips through the broker's own domain.
• Shown once per account, at signup. Does not reappear on later sign-ins.

Flows that touch this surface

• new-user-to-dashboard — step 6

Entities referenced

• copy-strings

Sources

• .context/wiki/decisions/2026-09-01-onboarding-broker-nudge.md
• .context/wiki/decisions/2026-09-07-broker-connect-per-broker-auth.md
• .context/designs/web/onboarding/connect-broker.html