# NAVI — Quick Reference

Personal modular AI agent system. FastAPI backend + Ollama LLM + 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`

## 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:

| 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.
- 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, downloads, and inline artifacts. `share_file` copies an existing local file into the session directory and returns a download link. `content_publish` registers an existing session file for inline viewing and does not copy from `workspace/`.

## Active 3D modeling improvements

Near-term work for `modeler_3d`:

- Convert abstract user requests into an internal technical specification before detailed planning or OpenSCAD generation.
- Make 3D implementation plans more detailed: object class, dimensions, print orientation, interfaces, tolerances, support strategy, geometry modules, verification steps.
- Use a fixed preview inspection checklist after `image_view`, comparing the rendered model against the technical specification.
- Require a critique/revision pass for medium+ 3D tasks before publishing, unless the model is a trivial primitive and the no-change rationale is explicit.
- Add a source comments contract to generated `.scad` files: purpose, units, assumptions, print orientation, key dimensions, parameters, and revision notes.