# REVISED: Remaining Work for Ponderants

## What We Actually Have ✅

After reviewing the codebase, here's what's **already implemented**:

### Backend/API ✅
- `/api/nodes` - Node creation with ATproto publishing + SurrealDB caching
- `/api/suggest-links` - Vector similarity search for related nodes
- `/api/calculate-graph` - UMAP dimensionality reduction for 3D coordinates
- `/api/chat` - AI conversation endpoint
- `/api/tts` - Text-to-speech generation
- `/api/voice-token` - Deepgram token generation
- Embedding generation (`lib/ai.ts`)
- ATproto publishing (write-through cache pattern)

### Frontend Components ✅
- `components/ThoughtGalaxy.tsx` - Full R3F 3D visualization
- `app/galaxy/page.tsx` - Galaxy view page with graph calculation
- `app/chat/page.tsx` - Chat interface with voice mode
- Voice mode state machine (`lib/voice-machine.ts`) - FULLY TESTED
- User authentication with OAuth
- User profile menu

### Infrastructure ✅
- SurrealDB schema with permissions
- ATproto OAuth flow
- Vector embeddings (gemini-embedding-001)
- Graph relationships in SurrealDB

---

## What's Actually Missing ❌

### **~8-12 hours of focused work** across 3 main areas:

## 1. App-Level Navigation & State (3-4 hours)

### Missing:
- App-level state machine to manage Convo ↔ Edit ↔ Galaxy transitions
- Persistent navigation UI (bottom bar mobile, sidebar desktop)
- Route navigation that respects app state

### Tasks:
1. Create `lib/app-machine.ts` (XState)
   - States: `convo`, `edit`, `galaxy`
   - Context: `currentNodeId`, `mode`
   - Events: `NAVIGATE_TO_EDIT`, `NAVIGATE_TO_GALAXY`, `NAVIGATE_TO_CONVO`

2. Create `components/AppStateMachine.tsx` provider

3. Create `components/Navigation/MobileBottomBar.tsx`
   - 3 buttons: Convo, Edit, Galaxy
   - Fixed at bottom
   - Highlights active state

4. Create `components/Navigation/DesktopSidebar.tsx`
   - Vertical nav links
   - Same 3 modes

5. Update `app/layout.tsx` with Mantine `AppShell`
   - Responsive navigation
   - Wraps with AppStateMachine provider

**Acceptance Criteria:**
- Can navigate between /chat, /edit, /galaxy
- Active mode highlighted in nav
- State persists across page refreshes
- Works on mobile and desktop

---

## 2. Node Editor UI (3-4 hours)

### Missing:
- Visual editor for node title/content
- Link suggestion UI
- Publish/Cancel/Continue buttons
- Integration with existing `/api/nodes` and `/api/suggest-links`

### Tasks:
1. Create `/app/edit/page.tsx`
   - Fetches current draft from app state
   - Shows editor form

2. Create `components/Edit/NodeEditor.tsx`
   - Mantine TextInput for title
   - Mantine Textarea (or RTE) for content
   - Markdown preview
   - Buttons: "Publish to ATproto", "Cancel", "Continue Conversation"

3. Create `components/Edit/LinkSuggestions.tsx`
   - Calls `/api/suggest-links` on content change (debounced)
   - Shows top 5 related nodes
   - Checkboxes to approve links
   - Shows similarity scores

4. Create `hooks/useNodeEditor.ts`
   - Mantine useForm integration
   - Handles publish flow
   - Manages link selection

**Acceptance Criteria:**
- Can edit node title and content
- Markdown preview works
- Link suggestions appear based on content
- "Publish" calls `/api/nodes` with approved links
- "Cancel" discards draft, returns to /chat
- "Continue" saves draft to state, returns to /chat

---

## 3. AI Node Suggestion Integration (2-3 hours)

### Missing:
- AI detection that user wants to create a node
- UI to show node suggestion in conversation
- Flow from suggestion → draft → edit mode

### Tasks:
1. Update AI system prompt in `/api/chat/route.ts`
   - Teach AI to suggest nodes when appropriate
   - Use structured output or tool calling

2. Create `components/Conversation/NodeSuggestionCard.tsx`
   - Shows suggested title/content from AI
   - "Save to Edit" button
   - "Dismiss" button
   - Appears inline in chat

3. Update `app/chat/page.tsx`
   - Detect node suggestions in AI responses
   - Show NodeSuggestionCard when detected
   - "Save to Edit" sets app state and navigates to /edit

4. (Optional) Add explicit "Save" button to chat UI
   - Always visible in bottom bar
   - Creates node from last N messages

**Acceptance Criteria:**
- AI can suggest creating a node
- Suggestion appears as a card in chat
- "Save to Edit" transitions to edit mode with draft
- Draft includes conversation context as content

---

## 4. Polish & Integration (1-2 hours)

### Missing:
- Galaxy → Edit mode flow (click node to edit)
- Edit → Galaxy flow (after publish, view in galaxy)
- Error handling & loading states
- Mobile responsiveness tweaks

### Tasks:
1. Update `components/ThoughtGalaxy.tsx`
   - On node click: navigate to /edit with that node ID
   - Fetch node data in edit page

2. Add "View in Galaxy" button to edit page
   - After successful publish
   - Transitions to galaxy with smooth camera animation

3. Add loading states everywhere
   - Skeleton loaders for galaxy
   - Spinner during publish
   - Disabled states during operations

4. Mobile testing & fixes
   - Touch controls in galaxy
   - Bottom bar doesn't overlap content
   - Voice mode works on mobile

**Acceptance Criteria:**
- Can click node in galaxy to edit it
- After publishing, can view node in galaxy
- All operations have loading feedback
- Works smoothly on mobile

---

## Revised Total Estimate

| Area | Est. Hours |
|------|------------|
| App Navigation & State | 3-4 |
| Node Editor UI | 3-4 |
| AI Node Suggestions | 2-3 |
| Polish & Integration | 1-2 |
| **TOTAL** | **9-13 hours** |

---

## What We DON'T Need to Build

❌ Galaxy visualization (EXISTS)
❌ Node creation API (EXISTS)
❌ Vector search (EXISTS)
❌ UMAP graph calculation (EXISTS)
❌ Voice mode state machine (EXISTS & TESTED)
❌ ATproto publishing (EXISTS)
❌ Embedding generation (EXISTS)
❌ SurrealDB schema (EXISTS)

---

## Implementation Priority

### Phase 1: Core Flow (P0) - 5-7 hours
1. App state machine
2. Navigation UI
3. Node editor
4. Basic node suggestion (even if manual)

### Phase 2: AI Integration (P1) - 2-3 hours
5. AI-powered node suggestions
6. Conversation context in drafts

### Phase 3: Polish (P2) - 1-2 hours
7. Galaxy ↔ Edit integration
8. Loading states
9. Mobile fixes

---

## Next Steps

1. **Start with Phase 1, Task 1**: Create `lib/app-machine.ts`
2. **Then Task 2**: Build navigation UI
3. **Then Task 3**: Build node editor

The rest can be done incrementally and tested along the way.

---

## Testing Strategy

- **Manual testing with Playwright MCP** for each phase
- **Update magnitude tests** as new features are added
- **Focus on user flows**:
  - Convo → Suggestion → Edit → Publish → Galaxy
  - Galaxy → Click node → Edit → Publish
  - Voice mode → Node creation (should work seamlessly)