# 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 |
| `navi.db` | SQLite session store |
| `workspace/` | Persistent working files |
| `manuals/` | Tool manuals (served by `tool_manual`) |

## Documentation

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

```
filesystem(action="query", path="docs/<file>.md", question="your question")
```

| 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 |
| `docs/memory.md` | Long-term memory system |
| `docs/api.md` | REST API endpoints |
| `docs/config.md` | All `.env` variables |

## Tool manuals

For detailed usage of any tool:

```
tool_manual("tool_name")
```

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

## Extending Navi

To add a new tool: `tool_manual("write_tool")` — full format reference + working example.