docs: create roadmap (5 phases)

.planning/ROADMAP.md

@@ -0,0 +1,91 @@
+# Roadmap: Chat Agent WebApp
+
+## Overview
+
+Five phases take this project from an empty solution to a complete personal AI chat application. Each phase introduces one Blazor concept and delivers something verifiable. The dependency chain is strict: the WASM/API architecture must exist before storage, storage before conversations, conversations before AI, AI before display polish, and display before UI completeness. Streaming is deferred to v2. The result is a working, well-understood chat interface where every line of code is intentional and explained.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Architecture Foundation** - Two-project solution scaffold with WASM/API split and shared models; establishes the tutorial commenting convention
+- [ ] **Phase 2: Conversation Storage** - JSON file persistence and full conversation CRUD via repository pattern and Minimal API endpoints
+- [ ] **Phase 3: Basic AI Chat** - End-to-end chat loop (send message → OpenAI → display response) without streaming
+- [ ] **Phase 4: Message Display** - Markdown rendering, syntax-highlighted code blocks, and copy-to-clipboard
+- [ ] **Phase 5: UI Polish** - Sidebar layout, chat input area, and responsive design across screen sizes
+
+## Phase Details
+
+### Phase 1: Architecture Foundation
+**Goal**: The solution structure is locked in and the critical boundaries (no API key in WASM, no file I/O in WASM, no direct OpenAI calls from WASM) are architecturally enforced before any feature code is written
+**Depends on**: Nothing (first phase)
+**Requirements**: CODE-01, CODE-02
+**Success Criteria** (what must be TRUE):
+  1. Running `dotnet run` on both projects starts WASM client and API server without errors
+  2. A test HTTP request from the WASM client reaches the API server and returns a response (CORS working)
+  3. The shared models library is referenced by both projects with no duplication of DTOs
+  4. Running `dotnet publish` on the WASM project completes with no IL trim warnings
+  5. Every file introduced contains inline comments explaining the Blazor concept it demonstrates
+**Plans**: TBD
+**UI hint**: yes
+
+### Phase 2: Conversation Storage
+**Goal**: Users can create, switch between, and delete conversations that persist to disk and survive app restarts — with no AI integration yet
+**Depends on**: Phase 1
+**Requirements**: CONV-01, CONV-02, CONV-03, CONV-04
+**Success Criteria** (what must be TRUE):
+  1. User can create a new conversation and see it appear in the conversation list
+  2. User can click a conversation in the list and switch to it (conversation content loads)
+  3. User can delete a conversation and see it removed from the list
+  4. After closing and reopening the browser, all conversations and their messages are still present
+**Plans**: TBD
+
+### Phase 3: Basic AI Chat
+**Goal**: Users can send a message and receive an AI response in the active conversation, with the full request/response cycle working end-to-end
+**Depends on**: Phase 2
+**Requirements**: CHAT-01, CHAT-02
+**Success Criteria** (what must be TRUE):
+  1. User can type a message, press send, and see their message appear in the chat area
+  2. User receives an AI response from OpenAI GPT displayed in the chat area
+  3. The conversation history is preserved across the full exchange and saved to disk
+  4. The OpenAI API key is never present in any WASM project file or browser network request
+**Plans**: TBD
+
+### Phase 4: Message Display
+**Goal**: AI responses render as readable, formatted content — not raw markdown strings — with syntax-highlighted code and one-click copy
+**Depends on**: Phase 3
+**Requirements**: DISP-01, DISP-02, DISP-03
+**Success Criteria** (what must be TRUE):
+  1. An AI response containing markdown (headings, lists, bold, links) renders as formatted HTML in the chat area
+  2. Code blocks in AI responses display with syntax highlighting appropriate to the language
+  3. User can click a copy button on any message and the text is copied to the clipboard
+**Plans**: TBD
+**UI hint**: yes
+
+### Phase 5: UI Polish
+**Goal**: The app has a complete, usable layout — sidebar with conversation list, chat input area, and a responsive design that works across screen sizes
+**Depends on**: Phase 4
+**Requirements**: UI-01, UI-02, UI-03
+**Success Criteria** (what must be TRUE):
+  1. App displays a sidebar on the left with the conversation list and a main chat area on the right
+  2. The chat area has a text input field and a send button visible at the bottom of the screen
+  3. The layout reflows gracefully on a narrow viewport (mobile-width browser window) without horizontal scrolling or clipped content
+**Plans**: TBD
+**UI hint**: yes
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Architecture Foundation | 0/TBD | Not started | - |
+| 2. Conversation Storage | 0/TBD | Not started | - |
+| 3. Basic AI Chat | 0/TBD | Not started | - |
+| 4. Message Display | 0/TBD | Not started | - |
+| 5. UI Polish | 0/TBD | Not started | - |