@@ -13,7 +13,7 @@ Guidelines for AI agents working on the Zoea Nova codebase—a TUI-based swarm c
1313 - Use interfaces for external dependencies (LLM providers, MCP, store).
1414 - Run `make fmt` before committing. Fix all warnings and linter errors.
1515 - When committing, use `required_permissions: ["all"]` to bypass sandbox restrictions (GPG signing requires full filesystem access).
16-- Write unit tests for all modules. Target 95%+ coverage.
16+- Write unit tests for all modules. Target 80%+ coverage (currently ~61%).
1717 - Never write data migrations. Schema changes require a fresh database.
1818 - Use `zerolog` for logging. Never log to stdout/stderr (TUI owns the terminal).
1919 - Keep the TUI responsive. All LLM/network calls must be non-blocking (goroutines + channels).
@@ -42,6 +42,15 @@ Multi-byte Unicode characters cause width calculation bugs:
4242 - **Style padding affects alignment**: `lipgloss.Style.Padding(0, 1)` adds 1 space on each side. If one element has padding and another doesn't, their decorations won't align even if both are "width" chars total.
4343 - **`lipgloss.Width()` sets content width**: When using `style.Width(n)`, the `n` sets the CONTENT width. Borders and padding are added ON TOP. So `style.Width(98)` with a border produces total width 100.
4444
45+## Database Management:
46+
47+The application uses SQLite for persistence.
48+
49+- **Location**: `~/.zoea-nova/zoea.db`
50+- **Querying**: Use `sqlite3 ~/.zoea-nova/zoea.db` to run manual queries.
51+- **Wiping**: To reset the state or apply schema changes (since migrations are not supported), delete the database and its temporary files: `rm ~/.zoea-nova/zoea.db*`.
52+- **Testing**: Tests use `t.TempDir()` for isolated database files. Never use the production database path in tests.
53+
4554 ## Terminology:
4655
4756 - **Agent**: An AI-controlled player instance with its own provider, memory, and state.
@@ -54,13 +63,14 @@ Multi-byte Unicode characters cause width calculation bugs:
5463 - **Dashboard**: TUI view showing swarm status, broadcast history, and agent list.
5564 - **Memory**: A stored conversation message with role (system/user/assistant/tool) and source.
5665 - **Source**: Origin of a memory—`direct` (single agent), `broadcast` (swarm), `system`, `llm`, or `tool`.
66+- **Context Compression**: Sliding window that sends only recent messages + system prompt to LLM. See [documentation/CONTEXT_COMPRESSION.md](documentation/CONTEXT_COMPRESSION.md).
5767
5868 ## Workflow:
5969
6070 The user follows a structured development workflow. Respect these phases:
6171
6272 1. **Design**: Documentation for this project is in `documentation/` Keep it up to date and accurate.
63-2. **Plan**: Complex changes require a plan in `.cursor/plans/`. Reference the plan while implementing.
73+2. **Plan**: Complex changes require a plan in `.opencode/plans/`. Reference the plan while implementing.
6474 3. **Implement**: Follow the plan phase-by-phase. Update tests alongside code, add more as needed.
6575 4. **Test**: Run `make test` after each phase. Fix failures before moving on.
6676 5. **Build**: Run `make build` to verify compilation. Address any warnings.