nexus/.planning/phases/21-chat-foundation/21-04-PLAN.md

---
phase: 21-chat-foundation
plan: 04
type: execute
wave: 3
depends_on: ["21-03"]
files_modified: []
autonomous: false
requirements:
  - CHAT-02
  - CHAT-03
  - CHAT-04
  - CHAT-05
  - CHAT-06
  - INPUT-01
  - INPUT-07
  - HIST-01
  - HIST-02
  - HIST-03
  - HIST-05
  - HIST-06
  - THEME-01
  - THEME-02

must_haves:
  truths:
    - "All phase 21 success criteria verified visually by user"
  artifacts: []
  key_links: []
---

<objective>
Visual and functional verification checkpoint for the complete Phase 21 chat foundation.

Purpose: Confirm the chat interface works end-to-end with correct theme integration, markdown rendering, and persistence before marking the phase complete.
Output: User approval or list of issues to fix.
</objective>

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

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/21-chat-foundation/21-03-SUMMARY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Run full test suite and generate migration</name>
  <files></files>
  <read_first>
    server/src/__tests__/chat-service.test.ts,
    server/src/__tests__/chat-routes.test.ts
  </read_first>
  <action>
    1. Run `pnpm db:generate` to generate the migration SQL if not already done. Verify generated SQL file exists under `packages/db/src/migrations/` and contains `CREATE TABLE "chat_conversations"` and `CREATE TABLE "chat_messages"` with `ON DELETE CASCADE`.

    2. Run the full test suite: `pnpm test:run`
       All tests must pass, including the new chat-service and chat-routes tests.

    3. Run `pnpm --filter @paperclipai/ui build` to verify the UI compiles cleanly with all new components.

    4. If the dev server is not running, start it: `pnpm dev`
  </action>
  <verify>
    <automated>cd /Volumes/UsbNvme/repos/nexus && pnpm test:run && pnpm --filter @paperclipai/ui build</automated>
  </verify>
  <acceptance_criteria>
    - `pnpm test:run` exits 0
    - `pnpm --filter @paperclipai/ui build` exits 0
    - Migration SQL file exists in packages/db/src/migrations/ containing "chat_conversations" and "chat_messages"
  </acceptance_criteria>
  <done>Full test suite green, UI builds clean, migration SQL generated.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 2: Visual and functional verification of chat foundation</name>
  <files></files>
  <action>
    Present the running application to the user for visual verification of all Phase 21 requirements. Ensure the dev server is running at http://localhost:5173 and the database migration has been applied.
  </action>
  <verify>User provides "approved" signal</verify>
  <done>User confirms chat foundation works correctly.</done>
  <what-built>Complete chat foundation: right-side chat panel with conversation sidebar, markdown message rendering with syntax-highlighted code blocks and copy buttons, auto-resize input with keyboard shortcuts, theme-aware styling across all three themes, and persistent storage in PostgreSQL.</what-built>
  <how-to-verify>
    1. Open the app at http://localhost:5173
    2. Click the chat icon (MessageSquare) in the top-right area of the layout — the chat panel should slide open from the right (380px wide)
    3. Verify the PropertiesPanel (if visible) closes when chat opens
    4. Click "New conversation" (Plus icon) — a conversation should appear in the sidebar list
    5. Type "Hello, this is a test message" and press Enter — the message should appear right-aligned in the message area
    6. Type a message with markdown: "Here is some **bold** and a code block:\n```typescript\nconst x: number = 42;\nconsole.log(x);\n```" and press Enter
    7. Verify the code block has:
       - Syntax highlighting (colored keywords)
       - A "typescript" language label in the top-left
       - A copy button in the top-right (click it — should show checkmark for 2 seconds)
    8. Switch themes: click the theme toggle button. For each theme (Catppuccin Mocha, Tokyo Night, Catppuccin Latte):
       - Verify the chat panel background matches the theme
       - Verify code block highlighting colors change with the theme
       - Verify text is readable and contrast is good
    9. Test keyboard shortcuts:
       - Shift+Enter in the input should create a newline (not send)
       - Enter should send the message
       - Escape with text in input should clear the input
       - Escape with empty input should close the chat panel
    10. Test conversation management: hover over a conversation in the sidebar, click the "..." menu:
        - Pin the conversation (should show pin icon)
        - Rename the conversation (should allow inline editing)
        - Archive the conversation (should disappear from list)
        - Create another conversation and delete it (should show "Delete this conversation?" confirmation)
    11. Reload the page — conversations and messages should persist
    12. Verify auto-resize: type multiple lines in the input — it should grow up to about 6 lines then scroll internally
  </how-to-verify>
  <resume-signal>Type "approved" or describe any issues found</resume-signal>
</task>

</tasks>

<verification>
Full visual and functional verification by user covering all 14 phase requirements.
</verification>

<success_criteria>
User approves the chat foundation as working correctly across all themes with proper markdown rendering, keyboard shortcuts, conversation CRUD, and persistence.
</success_criteria>

<output>
After completion, create `.planning/phases/21-chat-foundation/21-04-SUMMARY.md`
</output>