xonecas.io
60255
Zn

Zoea-Nova / commit ebccfa0

docs: reorganize documentation into structured directories

Organized 52 documentation files into logical categories for easier
navigation and maintenance.

Directory Structure:
- architecture/ - Core system design (5 files)
- guides/ - How-to guides for users and developers (6 files)
- current/ - Active status docs (3 files: TODO, KNOWN_ISSUES, KNOWN_SERVER_ISSUES)
- reports/ - Completed implementation reports (9 files)
- archive/ - Historical/obsolete investigations (13 files)
- investigations/ - Active research (kept as-is, 5 files)
- plans/ - Implementation plans (kept as-is, 10 files)

New Documentation:
- documentation/README.md - Central index with quick links and search guide
- documentation/archive/README.md - Archive purpose and guidelines

Updated References:
- AGENTS.md - Updated all documentation paths
- README.md - Updated KNOWN_ISSUES and TERMINAL_COMPATIBILITY paths

File Lifecycle Documented:
1. Investigation → investigations/
2. Plan → plans/
3. Implementation (commits)
4. Report → reports/
5. Archive → archive/

Benefits:
- Clear categorization (architecture vs guides vs reports)
- Easy navigation (by topic, by date, by status)
- Prevents duplication (archive vs active docs separated)
- Better discoverability (comprehensive index)
- Lifecycle clarity (where docs go at each stage)

All documentation now organized and indexed.

xonecas2026-02-06 ebccfa0089c309588654e1bbf1503967d47cf5f3 parent b9fc89a

41 files changed

AGENTS.md+7−7
@@ -8,8 +8,8 @@ Guidelines for AI agents working on the Zoea Nova codebase—a TUI-based swarm c
88
99 **YOU MUST**:
1010
11-- **NEVER edit `documentation/TODO.md`** - This file is managed exclusively by the user. If you believe items should be added or removed, ask the user to update it. This rule has no exceptions.
12-- Not change the game servers api, if we detect an issue with the api, document it in `documentation/KNOWN_SERVER_ISSUES.md`
11+- **NEVER edit `documentation/current/TODO.md`** - This file is managed exclusively by the user. If you believe items should be added or removed, ask the user to update it. This rule has no exceptions.
12+- Not change the game servers api, if we detect an issue with the api, document it in `documentation/current/KNOWN_SERVER_ISSUES.md`
1313 - Use Go 1.22+ idioms. No CGO dependencies.
1414 - Keep all application code in `internal/` packages. Only `cmd/zoea/main.go` is public.
1515 - Use interfaces for external dependencies (LLM providers, MCP, store).
@@ -20,7 +20,7 @@ Guidelines for AI agents working on the Zoea Nova codebase—a TUI-based swarm c
2020 - Keep the TUI responsive. All LLM/network calls must be non-blocking (goroutines + channels).
2121 - Follow the Bubble Tea Elm Architecture: Model → Update → View.
2222 - No "nice to haves." This is an MVP. Keep scope minimal. MVP is not an escuse for lack of testing or code quality.
23-- Keep track of known issues in `documentation/KNOWN_ISSUES.md` and ensure the list is up-do-date and correct.
23+- Keep track of known issues in `documentation/current/KNOWN_ISSUES.md` and ensure the list is up-do-date and correct.
2424 - Not duplicate information between README.md and AGENTS.md files. Use AGENTS for technical information, and README for user facing information. Keep README minimal and concise.
2525 - Follow the versioning rules. See bellow
2626 - Never open interactive editors when using git. use the `-m` or appropriate parameter to supply messages.
@@ -44,7 +44,7 @@ To run Zoea Nova without connecting to the SpaceMolt MCP server, use the `--offl
4444
4545 This uses a stub MCP client that returns mock data for essential tools (`get_status`, `get_system`, etc.), allowing TUI development and testing without an active game session.
4646
47-See `documentation/OFFLINE_MODE.md` for supported tools and limitations.
47+See `documentation/architecture/OFFLINE_MODE.md` for supported tools and limitations.
4848
4949 ## Terminal Requirements:
5050
@@ -67,7 +67,7 @@ Zoea Nova enforces minimum terminal dimensions at startup. If the terminal is to
6767 - Unicode fonts: Cascadia Code, Ubuntu Mono, Inconsolata
6868 - Fallback: DejaVu Sans Mono (decent Unicode coverage)
6969
70-See `documentation/TERMINAL_COMPATIBILITY.md` for detailed terminal testing results and `documentation/TUI_TESTING.md` for testing guidelines.
70+See `documentation/guides/TERMINAL_COMPATIBILITY.md` for detailed terminal testing results and `documentation/guides/TUI_TESTING.md` for testing guidelines.
7171
7272 ## TUI Testing:
7373
@@ -200,7 +200,7 @@ The application uses SQLite for persistence.
200200 - **Dashboard**: TUI view showing swarm status, broadcast history, and Mysis list.
201201 - **Memory**: A stored conversation message with role (system/user/assistant/tool) and source.
202202 - **Source**: Origin of a memory—`direct` (single Mysis), `broadcast` (swarm), `system`, `llm`, or `tool`.
203-- **Context Compression**: Sliding window that sends only recent messages + system prompt to LLM. See [documentation/CONTEXT_COMPRESSION.md](documentation/CONTEXT_COMPRESSION.md).
203+- **Context Compression**: Sliding window that sends only recent messages + system prompt to LLM. See [documentation/architecture/CONTEXT_COMPRESSION.md](documentation/architecture/CONTEXT_COMPRESSION.md).
204204
205205 ## Architecture
206206
@@ -219,7 +219,7 @@ flowchart LR
219219
220220 ## State Machine
221221
222-See `documentation/MYSIS_STATE_MACHINE.md` for valid Mysis transitions and triggers.
222+See `documentation/architecture/MYSIS_STATE_MACHINE.md` for valid Mysis transitions and triggers.
223223
224224 ## Workflow:
225225
README.md+2−2
@@ -41,7 +41,7 @@ Zoea Nova uses a small set of in-app terms (Mysis, Commander, Swarm, Provider, M
4141 - Alacritty, Kitty, WezTerm, Ghostty (best compatibility)
4242 - iTerm2 (macOS), Windows Terminal (with Nerd Font)
4343
44-See `documentation/TERMINAL_COMPATIBILITY.md` for detailed compatibility information.
44+See `documentation/guides/TERMINAL_COMPATIBILITY.md` for detailed compatibility information.
4545
4646 ## Try it
4747
@@ -75,4 +75,4 @@ or
7575
7676 ## Known Issues
7777
78-For a list of current bugs, technical debt, and planned improvements, see [KNOWN_ISSUES.md](documentation/KNOWN_ISSUES.md).
78+For a list of current bugs, technical debt, and planned improvements, see [KNOWN_ISSUES.md](documentation/current/KNOWN_ISSUES.md).
documentation/README.md+193−0
@@ -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
documentation/architecture/CONTEXT_COMPRESSION.md+0−0
documentation/architecture/INITIAL_IMPLEMENTATION_DESIGN.md+0−0
documentation/architecture/MYSIS_STATE_MACHINE.md+0−0
documentation/architecture/OFFLINE_MODE.md+0−0
documentation/architecture/RATE_LIMITING_PLAN.md+0−0
documentation/archive/AUTO_SCROLL_INVESTIGATION.md+0−0
documentation/archive/CLEANUP_ORDER_ANALYSIS.md+0−0
documentation/archive/FOOTER_OVERFLOW_TEST_REPORT.md+0−0
documentation/archive/GOROUTINE_CLEANUP_ANALYSIS.md+0−0
documentation/archive/INPUT_OVERFLOW_TEST_REPORT.md+0−0
documentation/archive/LLM_THINKING_STATE_INVESTIGATION.md+0−0
documentation/archive/OLD_PROMPT_BASELINE_BEHAVIOR.md+0−0
documentation/archive/PHASE_13_PRE_RC_VERIFICATION.md+0−0
documentation/archive/PHASE_2_HEADER_INVESTIGATION.md+0−0
documentation/archive/PHASE_6_LAYOUT_VERIFICATION_SUMMARY.md+0−0
documentation/archive/README.md+80−0
@@ -0,0 +1,80 @@
1+# Archive
2+
3+Historical investigations, analyses, and reports that have been **completed**, **superseded**, or are now **obsolete**.
4+
5+---
6+
7+## Purpose
8+
9+This directory contains documentation that:
10+- Solved a problem (implementation complete)
11+- Led to a decision (recorded in reports/)
12+- Is no longer relevant (obsolete)
13+- Provides historical context for future reference
14+
15+**Do NOT use as active reference** - See parent README.md for current documentation.
16+
17+---
18+
19+## Categories
20+
21+### Superseded Investigations
22+Investigations that led to implementations (code now shipped).
23+
24+- **AUTO_SCROLL_INVESTIGATION.md** → Replaced by reports/SMART_AUTO_SCROLL_IMPLEMENTATION.md
25+- **CLEANUP_ORDER_ANALYSIS.md** → Implemented in commit 4613e12
26+- **GOROUTINE_CLEANUP_ANALYSIS.md** → Implemented in commit 4613e12
27+- **LLM_THINKING_STATE_INVESTIGATION.md** → Implemented in reports/LLM_THINKING_STATE_IMPLEMENTATION.md
28+- **TUI_QUIT_HANDLING_ANALYSIS.md** → Fixed in commit series
29+
30+### Fixed Overflow/Layout Issues
31+Tests and investigations for layout problems (all resolved).
32+
33+- **FOOTER_OVERFLOW_TEST_REPORT.md** - Fixed
34+- **INPUT_OVERFLOW_TEST_REPORT.md** - Fixed
35+- **STATUSBAR_OVERFLOW_TEST_REPORT.md** - Fixed
36+- **VIEW_HEIGHT_OVERFLOW_ANALYSIS.md** - Fixed
37+
38+### Historical Reports
39+Early development phase reports (no longer relevant for current work).
40+
41+- **PHASE_2_HEADER_INVESTIGATION.md** - Header design iterations (pre-v0.1.0)
42+- **PHASE_6_LAYOUT_VERIFICATION_SUMMARY.md** - Early layout validation
43+- **PHASE_13_PRE_RC_VERIFICATION.md** - Pre-release verification (superseded)
44+- **OLD_PROMPT_BASELINE_BEHAVIOR.md** - Historical AI behavior reference
45+- **STREAMING_TEST_REPORT.md** - Provider streaming tests (feature complete)
46+
47+---
48+
49+## When to Archive
50+
51+**Archive a document when:**
52+1. Implementation is complete and merged
53+2. Investigation led to a decision (recorded elsewhere)
54+3. Problem is fully resolved
55+4. Report is superseded by newer analysis
56+5. Historical context only (no active reference needed)
57+
58+**Do NOT archive if:**
59+1. Still referenced by active code
60+2. Contains unique information not captured elsewhere
61+3. Needed for current/future decisions
62+4. Part of active troubleshooting
63+
64+---
65+
66+## Finding Archived Content
67+
68+**Why was X archived?**
69+- Check the parent README.md archive section
70+- Look for "Implemented in commit X" or "Replaced by Y"
71+- See git log for the file: `git log --follow archive/FILENAME.md`
72+
73+**Need to reference archived content?**
74+- It's still in git history
75+- Read directly from archive/ directory
76+- Consider if content should be extracted to current docs
77+
78+---
79+
80+Last updated: 2026-02-06
documentation/archive/STATUSBAR_OVERFLOW_TEST_REPORT.md+0−0
documentation/archive/STREAMING_TEST_REPORT.md+0−0
documentation/archive/TUI_QUIT_HANDLING_ANALYSIS.md+0−0
documentation/archive/VIEW_HEIGHT_OVERFLOW_ANALYSIS.md+0−0
documentation/current/KNOWN_ISSUES.md+0−0
documentation/current/KNOWN_SERVER_ISSUES.md+0−0
documentation/current/TODO.md+0−0
documentation/guides/GO_COMPILATION.md+0−0
documentation/guides/OLLAMA_MODELS.md+0−0
documentation/guides/OPENCODE_ZEN_MODELS.md+0−0
documentation/guides/SHELL_COMMANDS_AND_COMPLETIONS.md+0−0
documentation/guides/TERMINAL_COMPATIBILITY.md+0−0
documentation/guides/TUI_TESTING.md+0−0
documentation/reports/CODE_QUALITY_REVIEW_2026-02-06.md+0−0
documentation/reports/GOROUTINE_CLEANUP_SECURITY_REVIEW.md+0−0
documentation/reports/HTTP_CLIENT_CLEANUP_IMPLEMENTATION.md+0−0
documentation/reports/LLM_THINKING_STATE_IMPLEMENTATION.md+0−0
documentation/reports/MEMORY_GROWTH_REPORT.md+0−0
documentation/reports/POST_V044_CLEANUP_SUMMARY.md+0−0
documentation/reports/SCROLLBAR_GAP_FIX_REPORT.md+0−0
documentation/reports/SMART_AUTO_SCROLL_IMPLEMENTATION.md+0−0
documentation/reports/UI_LAYOUT_REPORT.md+0−0