Ship bestcodes screencast UX fixes: OAuth redirect URI, onboarding, verify-email CTA, logos, connector toggles

[kody-bot]

UX/product fixes from the bestcodes screencast review: OAuth redirect URI correctness, onboarding prompt + community CTA, verify-email CTA, integration logos, and remote connector toggle design.

What changed

A. OAuth redirect URI correctness (P0)

• /connect/oauth now shows a prominent Redirect URI card with the exact URI for the current origin (window.location.origin + pathname) and a copy button, plus a generic provider setup checklist (create app → register this exact redirect → enable APIs/scopes → paste client id/secret — the secret step is skipped when one is already stored).
• Agent-facing docs are positive, direct, and terse: docs/guides/oauth.md, docs/guides/integration-bootstrap.md, and the coding_guide_get oauth summary now literally state the redirect URI is https://heykody.dev/connect/oauth and connect URLs use https://heykody.dev/... (self-hosted deployments use their own origin plus /connect/oauth). No negative "don't use localhost" framing anywhere.

B. Onboarding starter prompt + community CTA

• buildOnboardingSetupPrompt() now steers agents to: briefly explain → use search + official guides (coding_guide_get) → connect one integration via the connect/secrets flows and verify with an ad hoc execute smoke test → no packages until the integration works (ad hoc execute first, package after).
• New "3. Explore community packages" card at the bottom of /onboarding with a primary Browse community packages button to /community.

C. Verify-email success CTA

• Continue to onboarding is now a primary button instead of a quiet text link. The muted Account link stays secondary and is hidden when the CTA already points at /account (email-change success).

D. Integrations page logos

• Added Slack, Spotify, and Discord brand marks to provider-icons.tsx so all six example integrations show a logo; the "Something else" card gets a neutral plug icon.

E. Remote connectors toggle design

• Replaced the remix/ui/toggle mixin (hardcoded light-mode green/white styling) with a theme-aware switch built from the shared design tokens: primary-colored track when on, token-based track/thumb, focus-visible ring, disabled and reduced-motion states. Looks clean in both light and dark mode. role="switch" preserved.

Testing

• npm run validate fully green (format, lint, typecheck, unit, Playwright E2E, MCP E2E) — re-run after the positive-framing docs rewrite and review-feedback fixes.
• Manual browser QA against the local dev server (logged-in session): scripted checks across all five surfaces in light + dark mode, including copy-button feedback (exact URI lands on the clipboard), switch toggling, disabled-attach behavior, per-card logo presence, the onboarding community CTA, and the verify-email primary button.

System recap — composes existing primitives (low risk)

Mode: recap · Base: main @ 18f67ce3 · Head: 96c5e62b

Classification: composes — UI copy/styling, onboarding prompt text, and docs guidance only; no primitive contracts, routes, storage, or auth flows changed.

Primitives touched

Primitive	Group	Impact
app-ui	surfaces	composes — redirect URI card, onboarding CTA, verify-email button, logos, switch styling
capability-registry	assistant	composes — coding_guide_get oauth guide summary wording (docs guides also updated)

System map

All app-ui changes are page-internal (five routes); the only cross-primitive path is agents fetching the updated oauth guide through coding_guide_get.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	appUi["app-ui<br/>Browser app (Remix 3)"]:::touched
	mcpServer["mcp-server<br/>MCP endpoint (/mcp)"]:::untouched
	capabilityRegistry["capability-registry<br/>Capability registry"]:::touched
	mcpServer -->|"coding_guide_get returns updated oauth / bootstrap guides"| capabilityRegistry
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Invariants

Per-user isolation untouched: all changes are client UI rendering, static prompt/doc text, and CSS.

Summary by CodeRabbit

• New Features
  • Added a copyable OAuth “Redirect URI” card with clearer, step-by-step provider setup checklist.
  • Added Slack, Spotify, and Discord provider icons.
  • Added an icon for the “Something else” integration suggestion.
  • Added an onboarding step linking to community packages.
• Improvements
  • Updated remote connector toggles for consistent light/dark theming.
  • Refreshed verify-email success actions layout and conditional “Account” link.
• Documentation
  • Clarified OAuth and integration setup with the exact https://heykody.dev/connect/oauth redirect URI.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR tightens OAuth origin and redirect URI guidance, adds a copyable redirect URI card and provider setup checklist, expands provider icons, updates integration and connector controls, and adds onboarding and verification UI changes.

Changes

Integration setup flow

Layer / File(s)	Summary
OAuth setup guidance docs/guides/oauth.md, docs/guides/integration-bootstrap.md, packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts	OAuth instructions now require the exact {origin}/connect/oauth redirect URI from the live Kody origin and describe registering credentials through the connection page.
Redirect URI and provider setup UI packages/worker/client/routes/connect-oauth.tsx	The OAuth page displays a copyable redirect URI and structured provider setup instructions in both configuration paths.
Onboarding setup instructions packages/worker/src/app/onboarding-data.ts	The setup prompt now guides users through describing Kody, connecting one integration, smoke testing it, and delaying package creation.

Account and onboarding interface

Layer / File(s)	Summary
Provider and integration presentation packages/worker/client/provider-icons.tsx, packages/worker/client/routes/account-integrations.tsx	Slack, Spotify, and Discord icons were added, and the “Something else” card now includes a plug icon.
Remote connector switches packages/worker/client/routes/account-remote-connectors.tsx	Connector checkboxes now use theme-aware switch styling and switch roles.
Onboarding and verification actions packages/worker/client/routes/onboarding.tsx, packages/worker/client/routes/verify-email.tsx	Onboarding adds a community packages step, and successful email verification uses a button-like CTA with a conditional Account link.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant ConnectOAuth
  participant OAuthProvider
  User->>ConnectOAuth: Open live-origin /connect/oauth
  ConnectOAuth->>User: Display exact redirect URI and copy control
  User->>OAuthProvider: Register copied redirect URI
  User->>ConnectOAuth: Enter provider client credentials

Loading

Possibly related PRs

• kentcdodds/kody#166: Updates related OAuth and integration guidance, including the official guide catalog.
• kentcdodds/kody#684: Extends provider icon rendering in the same file.
• kentcdodds/kody#690: Modifies the remote connector control implementation.

Suggested reviewers: kentcdodds

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main UX-focused changes, including OAuth, onboarding, email CTA, icons, and connector toggles.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/bestcodes-ux-fixes-ee05

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-744.kody-a99.workers.dev

Worker: kody-pr-744
D1: kody-pr-744-db
KV: kody-pr-744-oauth-kv

Mocks:

• cloudflare: https://kody-pr-744-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-744-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

packages/worker/client/routes/onboarding.tsx (1)

302-307: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract a shared "primary button as link" style instead of redefining it per-route.

Both new CTAs spread getPrimaryButtonCss(...) and re-add the same display: 'inline-flex' / textDecoration: 'none' overrides needed to use a primary button style on an <a> tag. A shared helper (e.g. getPrimaryLinkButtonCss(options?)) in style-primitives.ts would remove the duplication and keep future link-styled buttons consistent (this same pattern already exists, unchanged, for "Reconnect OAuth" in account-integrations.tsx).

• packages/worker/client/routes/onboarding.tsx#L302-L307: replace communityCtaCss's manual spread with the shared helper.
• packages/worker/client/routes/verify-email.tsx#L100-L105: replace ctaButtonCss's manual spread (keeping the size: 'lg', weight: 'semibold' options) with the shared helper.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/worker/client/routes/onboarding.tsx` around lines 302 - 307, The
primary-button-as-link styles are duplicated across both CTA routes. Add a
shared getPrimaryLinkButtonCss(options?) helper in style-primitives.ts that
applies getPrimaryButtonCss options plus the inline-flex and text-decoration
overrides, then update communityCtaCss in
packages/worker/client/routes/onboarding.tsx at lines 302-307 and ctaButtonCss
in packages/worker/client/routes/verify-email.tsx at lines 100-105 to use it;
preserve the verify-email size: 'lg' and weight: 'semibold' options.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/worker/client/routes/connect-oauth.tsx`:
- Around line 788-809: Update the checklist text in renderProviderInstructions
so confidential flows with hasStoredClientSecret true do not tell users to paste
an already-saved secret; change the wording to instruct them to enter a client
secret only if one is not already saved, while preserving the existing client-ID
wording and public-flow behavior.

In `@packages/worker/client/routes/verify-email.tsx`:
- Around line 68-82: Update the success-link rendering in the verify-email route
so the fallback CTA and the separate Account link are not both shown when
handling email-change success. Reuse the existing ctaHref/ctaLabel state or
email-change condition to hide the duplicate /account link while preserving the
CTA and account-link behavior for other verification outcomes.

In `@packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts`:
- Line 48: Clarify the OAuth guidance string in the coding capability so MCP
OAuth is explicitly presented as distinct from the PKCE and confidential
client-flow choices. Update the phrase near “PKCE vs confidential” to state that
it explains how those flows differ from, or are not, MCP OAuth.

---

Nitpick comments:
In `@packages/worker/client/routes/onboarding.tsx`:
- Around line 302-307: The primary-button-as-link styles are duplicated across
both CTA routes. Add a shared getPrimaryLinkButtonCss(options?) helper in
style-primitives.ts that applies getPrimaryButtonCss options plus the
inline-flex and text-decoration overrides, then update communityCtaCss in
packages/worker/client/routes/onboarding.tsx at lines 302-307 and ctaButtonCss
in packages/worker/client/routes/verify-email.tsx at lines 100-105 to use it;
preserve the verify-email size: 'lg' and weight: 'semibold' options.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c4e47375-6364-4a3c-9323-79de2dca4578

📥 Commits

Reviewing files that changed from the base of the PR and between 18f67ce and f2f13a8.

📒 Files selected for processing (10)

• docs/guides/integration-bootstrap.md
• docs/guides/oauth.md
• packages/worker/client/provider-icons.tsx
• packages/worker/client/routes/account-integrations.tsx
• packages/worker/client/routes/account-remote-connectors.tsx
• packages/worker/client/routes/connect-oauth.tsx
• packages/worker/client/routes/onboarding.tsx
• packages/worker/client/routes/verify-email.tsx
• packages/worker/src/app/onboarding-data.ts
• packages/worker/src/mcp/capabilities/coding/kody-official-guide.ts