# NAVI — Project Context

Personal modular AI agent system. FastAPI backend + Ollama LLM + Vue webclient.

## Server

```bash
.venv/bin/uvicorn navi.main:app --reload --reload-dir navi --port 8000
```

- UI: `http://localhost:8000`
- Debug panel: `http://localhost:8000/debug`
- Default model: `gemma4:26b-a4b-it-q4_K_M` (26B, Q4)

## Key paths

| Path | What |
|---|---|
| `navi/core/agent.py` | Agent loop, planning, tool execution |
| `navi/profiles/` | Profile definitions (`secretary`, `server_admin`, `developer`) |
| `navi/api/websocket.py` | WebSocket handler + event replay |
| `tools/` | User tools (auto-loaded at startup) |
| `tools/enabled.json` | Tools enabled across all profiles |
| `persona.txt` | Global persona injected into every profile |
| `DATABASE_URL` | PostgreSQL session + memory store |
| `workspace/` | Persistent private working files for Navi |
| `session_files/{session_id}/` | Per-session uploads and publishable chat artifacts (`SESSION_FILES_DIR`) |
| `manuals/` | Tool manuals (served by `tool_manual`) |

## Documentation

Detailed reference is in `docs/`. Query a specific file when you need depth:

Use the `filesystem` tool with action `query` on the specific documentation file.

| File | Covers |
|---|---|
| `docs/agent.md` | Agent loop, 3-phase planning, thinking mechanics flags |
| `docs/profiles.md` | Profile fields, all config flags, how to add a profile |
| `docs/tools.md` | Built-in tools, user tool format, hot-reload |
| `docs/sessions.md` | Session model, dual-buffer, context compression |
| `docs/websocket.md` | WebSocket protocol, all event types, reconnect replay |
| `docs/memory.md` | Long-term memory system |
| `docs/api.md` | Full REST + WebSocket API reference with schemas |
| `docs/config.md` | All `.env` variables |
| `docs/architecture.md` | Component diagram, data flow, registry wiring |

## Tool manuals

For detailed usage of any tool:

Call the `tool_manual` tool with the relevant tool name.

Manuals exist for: `write_tool`, `spawn_agent`, `reflect`, `gmail`, `share_file`, `content_publish`.

## Extending Navi

To add a new tool: call the `tool_manual` tool for `write_tool` — full format reference + working example.

## Agent prompt conventions

- Keep the main agent context small: delegate bounded subtasks that need 3+ tool calls and can be summarized independently.
- Before asking the user for project facts, proactively check nearest `NAVI.md`, then `docs/`, `manuals/`, memory, files, tool schemas, or web sources.
- Treat `NAVI.md` as the active operational notebook for its directory, not just static project documentation. Update it with stable commands, conventions, local quirks, and current project decisions.
- For Navi internals, use `docs/index.md` as the documentation map before scanning broad source trees.
- File-location rule: `workspace/` is persistent/private working storage; `session_files/{session_id}/` is the per-session area for uploads and files that `content_publish` can show in chat. To publish an artifact, put the final file in the session directory first; `content_publish` only registers it and does not copy from `workspace/`.