konstruct/.planning/phases/03-operator-experience/03-02-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
03-operator-experience	02	ui	slack oauth whatsapp onboarding byo-keys nextjs react-hook-form tanstack-query shadcn-ui	phase plan provides 03-operator-experience 01 Slack OAuth endpoints, WhatsApp connect endpoint, channel test endpoint, LLM key CRUD endpoints (Plan 01)	Slack OAuth callback route handler at /api/slack/callback Onboarding wizard page at /onboarding (3-step stepper via URL searchParams) OnboardingStepper component with numbered steps, active/completed/pending states Step 1 - ConnectChannel Slack OAuth button + WhatsApp manual form with step-by-step instructions Step 2 - ConfigureAgent agent list with Agent Designer link, Next enabled only with active agent Step 3 - TestMessage per-channel Send Test Message buttons, required step, no Go Live button BYO API Key settings page at /settings/api-keys (list, add, delete with confirmation) TanStack Query hooks useSlackInstallUrl, useConnectWhatsApp, useSendTestMessage, useChannelConnections, useLlmKeys, useAddLlmKey, useDeleteLlmKey API types SlackInstallResponse, ChannelConnection, WhatsAppConnectRequest/Response, TestMessageResponse, LlmKey, LlmKeyCreate API Keys link in sidebar nav	03-03 (billing UI — shares the same nav, portal patterns) 03-04 (cost dashboard — same portal conventions)	added patterns recharts (was in package.json but not installed — installed to unblock portal build) Onboarding wizard step state via URL searchParams (step=1|2|3) — shareable/refreshable Auto-advance on successful channel connect (1500ms delay + router.push) Slack OAuth fetch install URL from backend, then window.location.href redirect to Slack WhatsApp inline expandable form with humanized step-by-step credential instructions BYO key display pattern show ...{key_hint} (last 4 chars) — never plaintext Dialog for add form and delete confirmation using @base-ui/react Dialog pattern	created modified packages/portal/app/api/slack/callback/route.ts packages/portal/components/onboarding-stepper.tsx packages/portal/app/(dashboard)/onboarding/page.tsx packages/portal/app/(dashboard)/onboarding/steps/connect-channel.tsx packages/portal/app/(dashboard)/onboarding/steps/configure-agent.tsx packages/portal/app/(dashboard)/onboarding/steps/test-message.tsx packages/portal/app/(dashboard)/settings/api-keys/page.tsx packages/portal/lib/api.ts (added channel and LLM key types) packages/portal/lib/queries.ts (added 7 new hooks) packages/portal/components/nav.tsx (added API Keys nav link)	Agent goes live automatically after test message — is_active is true by default, no separate Go Live button (per user decision) Test message step is REQUIRED — no skip button (per user decision) BYO API keys are tenant-level (v1 simplicity) — page reads tenant_id from searchParams Onboarding wizard uses URL searchParams for step state — step=1|2|3 makes URLs shareable and browser-back friendly Slack OAuth redirect: window.location.href = authorize_url — NOT router.push, Slack must redirect the actual browser tab Portal git initialized as submodule with its own .git repo — enables atomic per-task commits in portal	Submodule commit pattern: portal files committed inside packages/portal .git, then parent repo git add packages/portal to update gitlink Onboarding stepper: numbered circles + connector lines, completed steps show Check icon, active step shows ring-primary WhatsApp form: expandable card pattern — Button to expand, form appears inline, Cancel collapses	PRTA-03 PRTA-04 LLM-03	~35min	2026-03-23

Phase 3 Plan 02: Channel Connection Wizard and BYO API Key Management Summary

Slack OAuth callback route, 3-step onboarding wizard (connect channel, configure agent, test message), and BYO LLM API key management page — operators can connect Slack/WhatsApp and go live from the portal

Performance

• Duration: ~35 min
• Started: 2026-03-23
• Completed: 2026-03-23
• Tasks: 2 of 3 (Task 3 is a human-verify checkpoint)
• Files created/modified: 10

Accomplishments

• Slack OAuth callback route at /api/slack/callback — proxies code+state to FastAPI, redirects to onboarding step 2 on success
• 3-step onboarding wizard using URL searchParams for step state (shareable/refreshable)
• OnboardingStepper component with numbered circles, completed check marks, connector lines
• Step 1: ConnectChannel with Slack OAuth button (fetches install URL, redirects browser) + expandable WhatsApp form with step-by-step credential instructions
• Step 2: ConfigureAgent shows existing agents with link to Agent Designer; Next disabled until active agent exists
• Step 3: TestMessage sends POST to backend per channel, shows loading/success/error states, no Go Live button (per user decision)
• BYO API key settings page at /settings/api-keys — table showing provider/label/key_hint/date, Add dialog (provider select + label + masked key), delete confirmation
• 7 new TanStack Query hooks for channels and LLM keys
• Navigation sidebar updated with API Keys link
• Portal builds successfully (15 routes, TypeScript clean)

Task Commits

Portal commits (packages/portal):

1. Task 1: Slack OAuth callback, onboarding wizard, channel queries - 120dc85 (feat)
2. Task 2: BYO API key settings page and nav link - 8f4247b (feat)

Parent repo commit (portal gitlink update): 3. feat(03-02): 11c1e52 — updates portal submodule reference

Files Created

• packages/portal/app/api/slack/callback/route.ts — Slack OAuth GET handler, proxies to FastAPI
• packages/portal/components/onboarding-stepper.tsx — step progress indicator component
• packages/portal/app/(dashboard)/onboarding/page.tsx — 3-step wizard entry page
• packages/portal/app/(dashboard)/onboarding/steps/connect-channel.tsx — Slack + WhatsApp connect forms
• packages/portal/app/(dashboard)/onboarding/steps/configure-agent.tsx — agent review / Agent Designer link
• packages/portal/app/(dashboard)/onboarding/steps/test-message.tsx — test message sender, celebration on success
• packages/portal/app/(dashboard)/settings/api-keys/page.tsx — BYO key CRUD page

Files Modified

• packages/portal/lib/api.ts — added SlackInstallResponse, ChannelConnection, WhatsAppConnect*, TestMessageResponse, LlmKey, LlmKeyCreate types
• packages/portal/lib/queries.ts — added useSlackInstallUrl, useConnectWhatsApp, useSendTestMessage, useChannelConnections, useLlmKeys, useAddLlmKey, useDeleteLlmKey
• packages/portal/components/nav.tsx — added Key import and API Keys nav item

Decisions Made

• Agent auto-live: is_active: true by default — operator does not need a separate "Go Live" step after test message succeeds
• Test required: Test message step has no skip button — connectivity must be verified before operators leave the wizard
• Tenant-level API keys: BYO key page reads ?tenant_id= from URL (v1 simplicity, could be per-agent in future)
• Step state in URL: step=1|2|3 in searchParams — survives page refresh, supports browser back/forward, shareable
• Portal git initialized: Created packages/portal/.git repo to enable atomic commits — previously portal was an orphaned gitlink with no local git history

Deviations from Plan

Auto-fixed Issues

1. [Rule 3 - Blocking] recharts not installed despite being in package.json

• Found during: Task 1 verification (portal build)
• Issue: recharts was listed in package.json (added in a previous phase plan) but never installed. This caused Module not found: Can't resolve 'recharts' build error blocking the Task 1 verification
• Fix: Ran npm install recharts in packages/portal
• Files modified: packages/portal/package-lock.json
• Commit: 120dc85 (Task 1 commit)

2. [Rule 3 - Blocking] Portal had no local git repo (orphaned gitlink)

• Found during: Task 1 commit attempt
• Issue: The parent repo tracks packages/portal as a git submodule gitlink (commit 29a27100). However, packages/portal had no .git directory, making it impossible to run git add on portal files
• Fix: Initialized git repo in packages/portal with git init + git add . + git commit, then updated the parent's gitlink reference
• Impact: Portal now has its own git history with proper atomic commits

---

Total deviations: 2 auto-fixed (Rule 3 — blocking issues) Impact on plan: Both fixes were necessary for the build to succeed and commits to be made; no scope change.

Self-Check: PASSED

All 7 artifact files exist and portal builds successfully (exit 0, 15 routes, TypeScript clean).

---

Phase: 03-operator-experience Completed: 2026-03-23