nexus/.planning/phases/38-telegram-bridge/38-03-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
38-telegram-bridge	03	execute	1		ui/src/components/onboarding/TelegramStep.tsx ui/src/components/NexusOnboardingWizard.tsx	true	ONBRD-03	truths artifacts key_links The onboarding wizard includes a BotFather setup step that walks the user through creating a bot token The token is validated with a live API call before saving The step can be skipped without blocking onboarding completion path provides exports ui/src/components/onboarding/TelegramStep.tsx BotFather instructions, token input, validation, skip button TelegramStep path provides contains ui/src/components/NexusOnboardingWizard.tsx Updated step flow with TelegramStep inserted TelegramStep from to via pattern ui/src/components/onboarding/TelegramStep.tsx POST /api/telegram/token fetch call for token validation fetch.*telegram/token from to via pattern ui/src/components/NexusOnboardingWizard.tsx ui/src/components/onboarding/TelegramStep.tsx import and render as step 5 TelegramStep

Add a BotFather guided setup step to the onboarding wizard. Users are walked through creating a Telegram bot, entering the token, and validating it — all without touching config files.

Purpose: Makes Telegram bridge setup accessible to non-technical users during first-run onboarding. Output: TelegramStep.tsx component, updated NexusOnboardingWizard.tsx

<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/phases/38-telegram-bridge/38-CONTEXT.md @.planning/phases/38-telegram-bridge/38-RESEARCH.md @.planning/REQUIREMENTS.md

From ui/src/components/NexusOnboardingWizard.tsx:

// Current 6-step flow:
// Step 1: Hardware detection (HardwareSummaryStep)
// Step 2: Mode selection
// Step 3: Provider selection (ProviderSelectionStep)
// Step 4: Voice (VoiceStep)
// Step 5: Root directory
// Step 6: Summary (OnboardingSummaryStep)
//
// Step indicator shows "Step N of 5" (summary is step 6 but not counted)
// Each step has Next/Back/Skip buttons using <Button> from @/components/ui/button

From ui/src/components/onboarding/VoiceStep.tsx (pattern reference):

// VoiceStep receives props for onNext, onBack, onSkip
// Uses same Button/Input/cn imports as other steps

Token validation endpoint (from Plan 01):

// POST /api/telegram/token { token: string }
// Returns: { ok: true, botUsername: string } on success
// Returns: 400 { error: string } on invalid token

Task 1: Create TelegramStep onboarding component ui/src/components/onboarding/TelegramStep.tsx - ui/src/components/onboarding/VoiceStep.tsx (pattern reference for step component structure, props, styling) - ui/src/components/onboarding/HardwareSummaryStep.tsx (alternative pattern reference) - ui/src/components/ui/button.tsx (Button component API) - ui/src/components/ui/input.tsx (Input component API) Create `ui/src/components/onboarding/TelegramStep.tsx`:

1. Props interface: { onNext: () => void; onBack: () => void; } — match the pattern from VoiceStep or HardwareSummaryStep.

2. State:

   • token: string — the bot token input
   • validating: boolean — loading state during validation
   • botUsername: string | null — set after successful validation
   • error: string | null — validation error message

3. handleValidate function:

   • POST to /api/telegram/token with { token } body
   • On success: set botUsername from response, clear error
   • On failure: set error from response or generic "Invalid token"
   • Always clear validating in finally block

4. Render structure (follow existing step styling patterns):

   • Title: "Telegram Bridge" or "Connect Telegram" with a brief subtitle
   • BotFather instructions section — numbered steps:
     1. "Open Telegram and search for @BotFather"
     2. "Send /newbot and follow the prompts to create a bot"
     3. "Copy the bot token (looks like 123456:ABC-DEF...)"
     4. "Paste the token below"
   • Token input field: <Input type="text" placeholder="Paste bot token here" value={token} onChange={...} />
   • Validate button: <Button onClick={handleValidate} disabled={!token.trim() || validating}>Validate Token</Button>
   • Success state: when botUsername is set, show green checkmark/text: "Connected to @{botUsername}" and enable Next button
   • Error state: show red error text below input
   • Navigation buttons: Back (always), Skip (always, calls onNext without saving), Next/Continue (enabled only when botUsername is set, calls onNext)

5. Style with Tailwind classes matching existing onboarding steps — use cn() from ../lib/utils for conditional classes. Look at VoiceStep for the exact layout pattern (padding, spacing, button alignment). cd /opt/nexus/.claude/worktrees/agent-a61d32dc && pnpm --filter @paperclipai/ui exec tsc --noEmit 2>&1 | head -30 <acceptance_criteria>

   • grep -q "export.*TelegramStep|export function TelegramStep" ui/src/components/onboarding/TelegramStep.tsx
   • grep -q "telegram/token" ui/src/components/onboarding/TelegramStep.tsx
   • grep -q "botUsername|bot_username" ui/src/components/onboarding/TelegramStep.tsx
   • grep -q "BotFather|@BotFather" ui/src/components/onboarding/TelegramStep.tsx
   • grep -q "onNext|onBack" ui/src/components/onboarding/TelegramStep.tsx
   • grep -q "Skip" ui/src/components/onboarding/TelegramStep.tsx </acceptance_criteria> TelegramStep component exists with BotFather instructions, token input, live validation via POST /api/telegram/token, success/error states, and Skip/Back/Next navigation.

Task 2: Insert TelegramStep into NexusOnboardingWizard as step 5 ui/src/components/NexusOnboardingWizard.tsx - ui/src/components/NexusOnboardingWizard.tsx (full file — understand step flow, step state, step indicator, navigation callbacks) - ui/src/components/onboarding/TelegramStep.tsx (the component from Task 1) Modify `ui/src/components/NexusOnboardingWizard.tsx`:

1. Add import: import { TelegramStep } from "./onboarding/TelegramStep";

2. Update step comment to reflect 7-step flow: // Step 1: hardware detection, 2: mode selection, 3: provider selection, 4: voice, 5: telegram, 6: root directory, 7: summary

3. Update step indicator text:

   • Change "Step ${step} of 5" to "Step ${step} of 6" (telegram is now step 5, summary at 7 doesn't count)
   • Change step === 6 ? "Summary" to step === 7 ? "Summary"

4. Insert Telegram step block between step 4 (Voice) and what was step 5 (Root directory):

   {step === 5 && (
     <TelegramStep
       onNext={() => setStep(6)}
       onBack={() => setStep(4)}
     />
   )}
   

5. Shift existing step numbers:

   • What was step === 5 (root directory) becomes step === 6
   • What was step === 6 (summary) becomes step === 7
   • Update ALL setStep(5) calls that navigate TO root directory to setStep(6)
   • Update ALL setStep(6) calls that navigate TO summary to setStep(7)
   • Update the back button in root directory step from setStep(4) to setStep(5)
   • Update the back button in summary step (if any) accordingly

6. IMPORTANT: Be thorough — search for EVERY occurrence of setStep(5) and setStep(6) in the file and update them. Missing one will cause navigation bugs.

7. Update the error message that references "step 5" for root directory — change to "step 6". cd /opt/nexus/.claude/worktrees/agent-a61d32dc && pnpm --filter @paperclipai/ui exec tsc --noEmit 2>&1 | head -30 <acceptance_criteria>

   • grep -q "TelegramStep" ui/src/components/NexusOnboardingWizard.tsx
   • grep -q "step === 5" ui/src/components/NexusOnboardingWizard.tsx
   • grep -q "Step.*of 6" ui/src/components/NexusOnboardingWizard.tsx
   • grep -q "step === 7.*Summary|step === 7" ui/src/components/NexusOnboardingWizard.tsx </acceptance_criteria> NexusOnboardingWizard has 7 steps. TelegramStep is step 5. Root directory shifted to step 6, summary to step 7. All navigation callbacks updated. TypeScript compiles clean.

- `cd /opt/nexus/.claude/worktrees/agent-a61d32dc && pnpm --filter @paperclipai/ui exec tsc --noEmit` — zero errors - `grep -c "TelegramStep" ui/src/components/NexusOnboardingWizard.tsx` — at least 2 (import + render) - `grep "step === [1-7]" ui/src/components/NexusOnboardingWizard.tsx` — steps 1 through 7 all present

<success_criteria>

• TelegramStep component renders BotFather instructions and validates token via API
• Step is skippable without blocking onboarding
• Wizard flow is now 7 steps with telegram at position 5
• TypeScript compiles without errors </success_criteria>

After completion, create `.planning/phases/38-telegram-bridge/38-03-SUMMARY.md`