app/plans/REVISED-remaining-work.md

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)