@@ -0,0 +1,193 @@
1+# Zoea Nova Documentation Index
2+
3+Central index for all Zoea Nova documentation organized by category.
4+
5+---
6+
7+## Quick Links
8+
9+**Current Status:**
10+- [TODO](current/TODO.md) - Active work items
11+- [Known Issues](current/KNOWN_ISSUES.md) - Bugs and technical debt
12+- [Known Server Issues](current/KNOWN_SERVER_ISSUES.md) - SpaceMolt API problems
13+
14+**For Developers:**
15+- [Go Compilation Guide](guides/GO_COMPILATION.md)
16+- [TUI Testing Guide](guides/TUI_TESTING.md)
17+- [Terminal Compatibility](guides/TERMINAL_COMPATIBILITY.md)
18+- [Shell Commands](guides/SHELL_COMMANDS_AND_COMPLETIONS.md)
19+
20+**For Users:**
21+- [Ollama Models](guides/OLLAMA_MODELS.md)
22+- [OpenCode Zen Models](guides/OPENCODE_ZEN_MODELS.md)
23+
24+---
25+
26+## Directory Structure
27+
28+### `architecture/`
29+Core system design and architectural decisions.
30+
31+- **[Initial Implementation Design](architecture/INITIAL_IMPLEMENTATION_DESIGN.md)** - Original system architecture and rationale
32+- **[Mysis State Machine](architecture/MYSIS_STATE_MACHINE.md)** - Valid state transitions and triggers
33+- **[Context Compression](architecture/CONTEXT_COMPRESSION.md)** - Memory management and sliding window
34+- **[Rate Limiting](architecture/RATE_LIMITING_PLAN.md)** - Provider rate limiting strategy
35+- **[Offline Mode](architecture/OFFLINE_MODE.md)** - Stub MCP server for development
36+
37+### `guides/`
38+How-to guides and reference material for developers and users.
39+
40+**Development:**
41+- **[Go Compilation](guides/GO_COMPILATION.md)** - Build instructions and requirements
42+- **[TUI Testing](guides/TUI_TESTING.md)** - Testing patterns for Bubble Tea UI
43+- **[Terminal Compatibility](guides/TERMINAL_COMPATIBILITY.md)** - Supported terminals and font requirements
44+- **[Shell Commands](guides/SHELL_COMMANDS_AND_COMPLETIONS.md)** - CLI reference
45+
46+**Configuration:**
47+- **[Ollama Models](guides/OLLAMA_MODELS.md)** - Local model configuration
48+- **[OpenCode Zen Models](guides/OPENCODE_ZEN_MODELS.md)** - Remote provider setup
49+
50+### `current/`
51+Active tracking documents (frequently updated).
52+
53+- **[TODO](current/TODO.md)** - Current work items
54+- **[Known Issues](current/KNOWN_ISSUES.md)** - Active bugs and technical debt
55+- **[Known Server Issues](current/KNOWN_SERVER_ISSUES.md)** - SpaceMolt API quirks
56+
57+### `reports/`
58+Completed implementation and analysis reports.
59+
60+**Recent (2026-02-06):**
61+- **[Code Quality Review](reports/CODE_QUALITY_REVIEW_2026-02-06.md)** - 5-agent review of recent changes
62+- **[Goroutine Cleanup Security](reports/GOROUTINE_CLEANUP_SECURITY_REVIEW.md)** - Shutdown safety analysis
63+- **[Smart Auto-Scroll](reports/SMART_AUTO_SCROLL_IMPLEMENTATION.md)** - Stateless auto-scroll design
64+
65+**Feature Implementations:**
66+- **[LLM Thinking State](reports/LLM_THINKING_STATE_IMPLEMENTATION.md)** - Busy state indicator
67+- **[HTTP Client Cleanup](reports/HTTP_CLIENT_CLEANUP_IMPLEMENTATION.md)** - Connection pooling
68+- **[Scrollbar Gap Fix](reports/SCROLLBAR_GAP_FIX_REPORT.md)** - Layout arithmetic correction
69+
70+**Analysis:**
71+- **[Memory Growth](reports/MEMORY_GROWTH_REPORT.md)** - Memory usage patterns
72+- **[UI Layout](reports/UI_LAYOUT_REPORT.md)** - Comprehensive layout analysis
73+- **[Post-v0.4.4 Cleanup](reports/POST_V044_CLEANUP_SUMMARY.md)** - Refactoring summary
74+
75+### `plans/`
76+Implementation plans for features and fixes.
77+
78+**2026-02-06:**
79+- **[Goroutine Cleanup Fixes](plans/2026-02-06-goroutine-cleanup-fixes.md)** - 8-phase cleanup plan
80+
81+**2026-02-05:**
82+- **[Broadcast Sender Tracking](plans/2026-02-05-broadcast-sender-tracking.md)**
83+- **[Context Size Logging](plans/2026-02-05-context-size-logging.md)**
84+- **[Statusbar Tick Timestamps](plans/2026-02-05-statusbar-tick-timestamps.md)**
85+- **[TUI Enhancements](plans/2026-02-05-tui-enhancements.md)**
86+
87+**2026-02-04:**
88+- **[Captain's Log Bug](plans/2026-02-04-captains-log-bug.md)**
89+- **[Context Compaction](plans/2026-02-04-context-compaction-plan.md)**
90+- **[Tool Payload Bloat](plans/2026-02-04-remove-tool-payload-bloat.md)**
91+
92+**Milestone Plans:**
93+- **[UI Fixes for RC](plans/ui-fixes-for-rc.md)**
94+- **[V1 Complete](plans/v1-complete.md)**
95+
96+### `investigations/`
97+Active investigations and research (work in progress).
98+
99+- **[Auto Polling Debug](investigations/AUTO_POLLING_DEBUG_REPORT.md)**
100+- **[Get Notifications API](investigations/GET_NOTIFICATIONS_API_INVESTIGATION.md)**
101+- **[Get Notifications Plan](investigations/GET_NOTIFICATIONS_IMPLEMENTATION_PLAN.md)**
102+- **[Tick Investigation](investigations/TICK_INVESTIGATION_FINDINGS.md)**
103+- **[TUI Tick Display](investigations/TUI_TICK_DISPLAY_INVESTIGATION.md)**
104+
105+See `investigations/README.md` for details.
106+
107+### `archive/`
108+Historical investigations and reports (completed, superseded, or obsolete).
109+
110+**Superseded Investigations:**
111+- **[Auto-Scroll Investigation](archive/AUTO_SCROLL_INVESTIGATION.md)** - Replaced by reports/SMART_AUTO_SCROLL_IMPLEMENTATION.md
112+- **[Cleanup Order Analysis](archive/CLEANUP_ORDER_ANALYSIS.md)** - Implemented in commit 4613e12
113+- **[Goroutine Cleanup Analysis](archive/GOROUTINE_CLEANUP_ANALYSIS.md)** - Implemented in commit 4613e12
114+- **[LLM Thinking Investigation](archive/LLM_THINKING_STATE_INVESTIGATION.md)** - Implemented
115+- **[TUI Quit Handling](archive/TUI_QUIT_HANDLING_ANALYSIS.md)** - Fixed
116+
117+**Overflow/Layout Fixes:**
118+- **[Footer Overflow](archive/FOOTER_OVERFLOW_TEST_REPORT.md)** - Fixed
119+- **[Input Overflow](archive/INPUT_OVERFLOW_TEST_REPORT.md)** - Fixed
120+- **[Statusbar Overflow](archive/STATUSBAR_OVERFLOW_TEST_REPORT.md)** - Fixed
121+- **[View Height Overflow](archive/VIEW_HEIGHT_OVERFLOW_ANALYSIS.md)** - Fixed
122+
123+**Historical Reports:**
124+- **[Phase 2 Header](archive/PHASE_2_HEADER_INVESTIGATION.md)** - Early development
125+- **[Phase 6 Layout](archive/PHASE_6_LAYOUT_VERIFICATION_SUMMARY.md)** - Early development
126+- **[Phase 13 Pre-RC](archive/PHASE_13_PRE_RC_VERIFICATION.md)** - Pre-release check
127+- **[Old Prompt Baseline](archive/OLD_PROMPT_BASELINE_BEHAVIOR.md)** - Historical reference
128+- **[Streaming Test](archive/STREAMING_TEST_REPORT.md)** - Provider testing
129+
130+---
131+
132+## Documentation Guidelines
133+
134+**When adding new docs:**
135+
136+1. **Current work** → `current/` (TODO, KNOWN_ISSUES)
137+2. **Feature implementation** → Start in `plans/`, finish in `reports/`
138+3. **Active research** → `investigations/`
139+4. **Architecture decisions** → `architecture/`
140+5. **How-to guides** → `guides/`
141+6. **Completed/obsolete** → `archive/`
142+
143+**Naming conventions:**
144+- Plans: `YYYY-MM-DD-feature-name.md`
145+- Reports: `FEATURE_NAME_IMPLEMENTATION.md` or `FEATURE_NAME_REPORT.md`
146+- Guides: `TOPIC_NAME.md` (uppercase with underscores)
147+- Architecture: `CONCEPT_NAME.md` (uppercase with underscores)
148+
149+**File lifecycle:**
150+1. Investigation starts in `investigations/`
151+2. Plan created in `plans/`
152+3. Implementation happens (code commits)
153+4. Report written in `reports/`
154+5. Investigation/plan archived in `archive/`
155+
156+---
157+
158+## Finding Documentation
159+
160+**By Topic:**
161+- **Build/compile issues** → guides/GO_COMPILATION.md
162+- **Test failures** → guides/TUI_TESTING.md
163+- **Terminal rendering** → guides/TERMINAL_COMPATIBILITY.md
164+- **State transitions** → architecture/MYSIS_STATE_MACHINE.md
165+- **Memory management** → architecture/CONTEXT_COMPRESSION.md
166+- **Offline development** → architecture/OFFLINE_MODE.md
167+- **Known bugs** → current/KNOWN_ISSUES.md
168+- **SpaceMolt quirks** → current/KNOWN_SERVER_ISSUES.md
169+
170+**By Date:**
171+- **Recent work** → `reports/` (sorted by date in filename)
172+- **Current sprint** → `current/TODO.md`
173+- **Past investigations** → `archive/` (historical context)
174+
175+---
176+
177+## Maintenance
178+
179+**Keep current:**
180+- Update `current/TODO.md` as work completes
181+- Move completed items from TODO to appropriate category
182+- Archive investigations after implementation
183+- Consolidate related reports periodically
184+
185+**Avoid duplication:**
186+- Check existing docs before creating new ones
187+- Reference other docs with relative links
188+- Consolidate overlapping content
189+- Remove obsolete docs after archiving
190+
191+---
192+
193+Last updated: 2026-02-06