# Requirements Archive: v1.3 Chat & PWA

**Archived:** 2026-04-02
**Status:** SHIPPED

For current requirements, see `.planning/REQUIREMENTS.md`.

---

# Requirements: v1.3 Web Chat Interface

**Milestone:** v1.3
**Status:** Queued
**Source PRD:** ~/Downloads/nexus-v1.3-prd-web-chat.md
**Depends on:** v1.2 (Skill Aggregator + Generalist Agent)
**Total v1 requirements:** 65

---

## Categories

### Chat Core (14)

- [x] **CHAT-01** — Real-time streaming responses: tokens appear as they are generated, not after completion
- [x] **CHAT-02** — Markdown rendering in messages: code blocks with syntax highlighting, tables, lists, headings, links, images
- [x] **CHAT-03** — Code blocks have a one-click copy button and a language label
- [x] **CHAT-04** — Multiple concurrent conversations: sidebar shows the full conversation list
- [x] **CHAT-05** — Conversation titles: auto-generated from the first message, manually editable by the user
- [x] **CHAT-06** — Delete, archive, and pin conversations
- [x] **CHAT-07** — Full-text search across all conversations
- [x] **CHAT-08** — Agent selector: switch which agent you are talking to mid-conversation or per-conversation
- [x] **CHAT-09** — System message indicator: when the Brainstormer hands off to PM, or PM delegates to Engineer, the handoff is visible in chat
- [x] **CHAT-10** — Message editing: edit a previous message and regenerate the response
- [x] **CHAT-11** — Response regeneration: retry button on any assistant message
- [x] **CHAT-12** — Stop generation: cancel button available while a response is streaming
- [x] **CHAT-13** — Message reactions / bookmarks: mark important messages for later reference
- [x] **CHAT-14** — Conversation branching: editing a mid-conversation message creates a branch; both branches are preserved

### Input (7)

- [x] **INPUT-01** — Multi-line text input with auto-resize: grows with content up to a max height before scrolling
- [x] **INPUT-02** — File/image upload via drag-and-drop or button with inline preview before sending
- [x] **INPUT-03** — Paste image from clipboard directly into the chat input
- [x] **INPUT-04** — Voice input via Whisper (when local AI is enabled): record button with transcription preview before sending
- [x] **INPUT-05** — Slash commands: `/brainstorm`, `/ask-pm`, `/ask-engineer`, `/task`, `/search`
- [x] **INPUT-06** — `@mention` agents: type `@engineer` to route a message to a specific agent
- [x] **INPUT-07** — Keyboard shortcuts: Enter to send, Shift+Enter for newline, Cmd+K for search, Escape to cancel

### Agent Integration (7)

- [x] **AGENT-01** — Default agent is the Brainstormer (Generalist with a Superpowers-style system prompt, or a dedicated 4th Brainstormer agent)
- [x] **AGENT-02** — Brainstormer follows a structured questioning flow: asks clarifying questions, produces a spec template, and hands off to PM
- [x] **AGENT-03** — PM agent can receive specs from chat and create Nexus tasks/issues from them
- [x] **AGENT-04** — Agent responses show which agent is speaking with avatar and name
- [x] **AGENT-05** — Handoff indicators visible in chat: "Brainstormer → PM: Here's the spec for approval"
- [x] **AGENT-06** — Task creation from chat: user or agent can say "create a task for this" and it becomes a Nexus issue
- [x] **AGENT-07** — Status updates from agents appear in chat: "Engineer completed task X" notification in the relevant conversation

### History & Persistence (6)

- [x] **HIST-01** — All conversations persisted in libSQL
- [x] **HIST-02** — Conversation list in sidebar: sorted by most recent, searchable, filterable by agent
- [x] **HIST-03** — Infinite scroll in the conversation list sidebar
- [x] **HIST-04** — Conversation export: download as Markdown or JSON
- [x] **HIST-05** — Cross-device sync: conversations accessible from any device on the network via the Nexus server API
- [x] **HIST-06** — Chat history survives server restarts: no in-memory-only state

### PWA & Mobile (8)

- [x] **PWA-01** — Service worker for offline capability: cached UI loads instantly, queues messages until back online
- [x] **PWA-02** — Web App Manifest: installable on iOS, Android, macOS, and Windows as a standalone app
- [x] **PWA-03** — Responsive layout: adapts to phone, tablet, and desktop screen sizes
- [x] **PWA-04** — Mobile-optimized input: large touch targets, sticky input bar at bottom, keyboard-aware resize
- [x] **PWA-05** — Pull-to-refresh on the mobile conversation list
- [x] **PWA-06** — Push notifications (where supported): agent mentions, task completions, handoff requests
- [x] **PWA-07** — App icon and splash screen with Nexus branding, theme-aware
- [x] **PWA-08** — "Add to Home Screen" prompt on first mobile visit

### Theme Integration (3)

- [x] **THEME-01** — Chat interface respects the Nexus theme system (Catppuccin Mocha, Tokyo Night, Catppuccin Latte)
- [x] **THEME-02** — Code blocks use theme-appropriate syntax highlighting colors
- [x] **THEME-03** — Agent avatars/colors are visually distinguishable in all three themes

### Performance (5)

- [x] **PERF-01** — Initial load under 2 seconds on broadband, under 5 seconds on 3G
- [x] **PERF-02** — Streaming response latency under 100ms from server to UI
- [x] **PERF-03** — Conversations with 1,000+ messages scroll smoothly via a virtualized list
- [x] **PERF-04** — Full-text search returns results in under 500ms across 10,000+ messages
- [x] **PERF-05** — PWA cached load under 1 second

### File System (13)

- [x] **FILE-01** — Local file storage directory structure under `<nexus-root>/files/` with subdirectories: `projects/<slug>/assets/`, `projects/<slug>/docs/`, `projects/<slug>/generated/`, `projects/<slug>/placeholders/`, `chat/<conversation-id>/`, and `exports/`
- [x] **FILE-02** — libSQL `files` table tracking all file metadata: id, filename, original_filename, mime_type, size_bytes, storage_path, git_hash, checksum, dual-scope fields (project_id, conversation_id, message_id, agent_id, workspace_id, task_id), source, category, placeholder fields, and lifecycle timestamps
- [x] **FILE-03** — libSQL `file_references` table enabling a single file to be referenced from multiple conversations without duplication
- [x] **FILE-04** — Dual scoping: a file uploaded during a project-linked conversation lives in `files/projects/<slug>/` but is also referenced by the chat message; a file in a general chat (no project context) lives in `files/chat/<conversation-id>/`
- [x] **FILE-05** — File upload from chat input via drag-and-drop or button; file is stored on disk and its metadata is written to libSQL
- [x] **FILE-06** — Inline file preview in chat: images render inline, PDFs show a first-page preview, code files show a syntax-highlighted preview
- [x] **FILE-07** — One-click file download from chat for any attached or generated file
- [x] **FILE-08** — Agent-generated files (code output, specs, presentations) stored in `files/projects/<slug>/generated/`, linked to the originating task and conversation in libSQL
- [x] **FILE-09** — Git integration: `files/` is a git repository; every file operation (upload, generate, replace, delete) creates a commit with a descriptive message
- [x] **FILE-10** — Version history: user can view the git log for any file and see its change history
- [x] **FILE-11** — Placeholder asset tracking: Nexus auto-maintains a `PLACEHOLDERS.md` manifest in each project directory; when a placeholder is replaced by a final asset, the manifest and DB are updated with the replacement chain
- [x] **FILE-12** — File scope promotion: a chat-scoped file can be promoted to a project scope; a project file can be referenced in any chat conversation
- [x] **FILE-13** — Cross-device file access: files are served via the Nexus server API so a file uploaded on one device is accessible on any other device on the network

---

## Out of Scope (v1.4+)

The following are explicitly deferred:

- Voice call / audio conversation mode
- Video sharing / screen recording in chat
- Collaborative chat (multiple human users in one conversation)
- End-to-end encryption
- Chat API for third-party integrations
- Custom chat themes beyond the Nexus theme system
- Chat-based agent configuration / settings changes
- Telegram bridge (Telegram messages appearing in web chat and vice versa)

---

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| CHAT-01 | Phase 22 | Complete |
| CHAT-02 | Phase 21 | Complete |
| CHAT-03 | Phase 21 | Complete |
| CHAT-04 | Phase 21 | Complete |
| CHAT-05 | Phase 21 | Complete |
| CHAT-06 | Phase 21 | Complete |
| CHAT-07 | Phase 24 | Complete |
| CHAT-08 | Phase 22 | Complete |
| CHAT-09 | Phase 23 | Complete |
| CHAT-10 | Phase 22 | Complete |
| CHAT-11 | Phase 22 | Complete |
| CHAT-12 | Phase 22 | Complete |
| CHAT-13 | Phase 24 | Complete |
| CHAT-14 | Phase 24 | Complete |
| INPUT-01 | Phase 21 | Complete |
| INPUT-02 | Phase 25 | Complete |
| INPUT-03 | Phase 25 | Complete |
| INPUT-04 | Phase 25 | Complete |
| INPUT-05 | Phase 22 | Complete |
| INPUT-06 | Phase 22 | Complete |
| INPUT-07 | Phase 21 | Complete |
| AGENT-01 | Phase 23 | Complete |
| AGENT-02 | Phase 23 | Complete |
| AGENT-03 | Phase 23 | Complete |
| AGENT-04 | Phase 22 | Complete |
| AGENT-05 | Phase 23 | Complete |
| AGENT-06 | Phase 23 | Complete |
| AGENT-07 | Phase 23 | Complete |
| HIST-01 | Phase 21 | Complete |
| HIST-02 | Phase 21 | Complete |
| HIST-03 | Phase 21 | Complete |
| HIST-04 | Phase 24 | Complete |
| HIST-05 | Phase 21 | Complete |
| HIST-06 | Phase 21 | Complete |
| PWA-01 | Phase 26 | Complete |
| PWA-02 | Phase 26 | Complete |
| PWA-03 | Phase 26 | Complete |
| PWA-04 | Phase 26 | Complete |
| PWA-05 | Phase 26 | Complete |
| PWA-06 | Phase 26 | Complete |
| PWA-07 | Phase 26 | Complete |
| PWA-08 | Phase 26 | Complete |
| THEME-01 | Phase 21 | Complete |
| THEME-02 | Phase 21 | Complete |
| THEME-03 | Phase 22 | Complete |
| PERF-01 | Phase 26 | Complete |
| PERF-02 | Phase 22 | Complete |
| PERF-03 | Phase 22 | Complete |
| PERF-04 | Phase 24 | Complete |
| PERF-05 | Phase 26 | Complete |
| FILE-01 | Phase 25 | Complete |
| FILE-02 | Phase 25 | Complete |
| FILE-03 | Phase 25 | Complete |
| FILE-04 | Phase 25 | Complete |
| FILE-05 | Phase 25 | Complete |
| FILE-06 | Phase 25 | Complete |
| FILE-07 | Phase 25 | Complete |
| FILE-08 | Phase 25 | Complete |
| FILE-09 | Phase 25 | Complete |
| FILE-10 | Phase 25 | Complete |
| FILE-11 | Phase 25 | Complete |
| FILE-12 | Phase 25 | Complete |
| FILE-13 | Phase 25 | Complete |
