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

---
phase: 38-telegram-bridge
plan: 03
type: execute
wave: 1
depends_on: []
files_modified:
  - ui/src/components/onboarding/TelegramStep.tsx
  - ui/src/components/NexusOnboardingWizard.tsx
autonomous: true
requirements: [ONBRD-03]

must_haves:
  truths:
    - "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"
  artifacts:
    - path: "ui/src/components/onboarding/TelegramStep.tsx"
      provides: "BotFather instructions, token input, validation, skip button"
      exports: ["TelegramStep"]
    - path: "ui/src/components/NexusOnboardingWizard.tsx"
      provides: "Updated step flow with TelegramStep inserted"
      contains: "TelegramStep"
  key_links:
    - from: "ui/src/components/onboarding/TelegramStep.tsx"
      to: "POST /api/telegram/token"
      via: "fetch call for token validation"
      pattern: "fetch.*telegram/token"
    - from: "ui/src/components/NexusOnboardingWizard.tsx"
      to: "ui/src/components/onboarding/TelegramStep.tsx"
      via: "import and render as step 5"
      pattern: "TelegramStep"
---

<objective>
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`
</objective>

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

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

<interfaces>
<!-- Existing onboarding step pattern -->

From ui/src/components/NexusOnboardingWizard.tsx:
```typescript
// 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):
```typescript
// VoiceStep receives props for onNext, onBack, onSkip
// Uses same Button/Input/cn imports as other steps
```

Token validation endpoint (from Plan 01):
```typescript
// POST /api/telegram/token { token: string }
// Returns: { ok: true, botUsername: string } on success
// Returns: 400 { error: string } on invalid token
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create TelegramStep onboarding component</name>
  <files>ui/src/components/onboarding/TelegramStep.tsx</files>
  <read_first>
    - 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)
  </read_first>
  <action>
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).
  </action>
  <verify>
    <automated>cd /opt/nexus/.claude/worktrees/agent-a61d32dc && pnpm --filter @paperclipai/ui exec tsc --noEmit 2>&1 | head -30</automated>
  </verify>
  <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>
  <done>TelegramStep component exists with BotFather instructions, token input, live validation via POST /api/telegram/token, success/error states, and Skip/Back/Next navigation.</done>
</task>

<task type="auto">
  <name>Task 2: Insert TelegramStep into NexusOnboardingWizard as step 5</name>
  <files>ui/src/components/NexusOnboardingWizard.tsx</files>
  <read_first>
    - 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)
  </read_first>
  <action>
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):
   ```tsx
   {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".
  </action>
  <verify>
    <automated>cd /opt/nexus/.claude/worktrees/agent-a61d32dc && pnpm --filter @paperclipai/ui exec tsc --noEmit 2>&1 | head -30</automated>
  </verify>
  <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>
  <done>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.</done>
</task>

</tasks>

<verification>
- `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
</verification>

<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>

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