# Navi Webclient — Context for Claude

## What this repo is

A new web client for **Navi** — a personal modular AI agent system. The backend (FastAPI + Ollama) already exists and is fully operational at `http://localhost:8099`. Your job is to build the frontend that talks to it.

The current client (`/home/gmikcon/Projects/navi-1/client/`) is a vanilla JS placeholder. It works, but it was built as a temporary scaffold. The new client should be a proper application.

## Server

The backend lives at `/home/gmikcon/Projects/navi-1/`.  
Running server: `http://localhost:8099`  
WebSocket: `ws://localhost:8099/ws/sessions/{session_id}`

**Do not modify the backend.** All server docs are in `docs/`.

## Key server docs (read these first)

| File | What's in it |
|------|-------------|
| `docs/api.md` | Complete REST + WebSocket API reference. Start here. |
| `docs/architecture.md` | How the server is structured internally |
| `docs/profiles.md` | What profiles are, their IDs and capabilities |
| `docs/sessions.md` | Session model, two-buffer design, compression |
| `docs/current-client-spec.md` | Full spec of the existing vanilla JS client: layout, state shape, WS event handling, component breakdown, design system (colors, typography), file/image attachment flow |
| `docs/spec.md` | **New client spec** — stack, component architecture, Pinia stores, WS logic, responsive layout, animations, error handling. Start here before implementing anything. |

## What the backend does

Navi is a tool-calling LLM agent. A session is a persistent conversation linked to a profile (e.g. "secretary", "server_admin"). The client sends messages over WebSocket and receives a stream of typed events in response:
- thinking chunks (model reasoning, collapsible)
- tool calls (what tools the agent is using and their results)
- text deltas (the final streamed response)

See `docs/api.md` for the full event reference and typical event sequences.

## Profiles

Three profiles are currently active:

| ID | Name | Purpose |
|----|------|---------|
| `secretary` | Personal Secretary | Research, writing, analysis, everyday tasks |
| `server_admin` | Server Administrator | Remote ops, monitoring, infrastructure |
| `developer` | Developer | Writing code, incl. Navi's own MCP servers |

Profiles are fetched live from `GET /agents/profiles`.

## Existing client (reference only)

The old client is at `/home/gmikcon/Projects/navi-1/client/`. You can read it to understand what was built before, but you are not constrained by its design. It uses vanilla JS ES modules, marked.js + highlight.js.

Key UX patterns worth knowing about:
- Session ID stored in URL hash for bookmarking
- Thinking blocks auto-collapse when reasoning ends, can be re-expanded
- Tool cards collapsed by default, expandable
- Profile can be switched mid-session by the agent (handle `profile_switched` event)
- Stop button during generation (`POST /sessions/{id}/stop`)
- Image paste/attach support (base64)
- File upload before sending a message (`POST /sessions/{id}/files`)

## What the user expects

- Clean, modern UI — this is a daily-use personal assistant
- Sidebar with session list (pinned sessions first)
- Main chat area with proper markdown rendering
- Tool call visibility — the user wants to see what the agent is doing
- Thinking blocks — collapsible, clearly separated from the response
- Profile indicator and ability to create sessions with a specific profile

## Design system (gnexus-ui-kit v1.0)

Full component docs, rules and demo live in the vendored copy:
**`vendor/gnexus-ui-kit/CLAUDE.md`** — read it before styling anything.

Facts specific to this app:

- Kit is consumed as **prebuilt CSS**: `import 'gnexus-ui-kit/css'` in `src/main.js`
  (kit v1.0's `_fonts.scss` references fonts by relative url(), which breaks
  Sass source compilation — the Vite bundler resolves them instead).
- **Theme**: default dark `dist/css/kit.css`. No theme switcher.
- **Tokens**: CSS variables `--gn-*` (colors/surfaces/borders/motion/spacing)
  everywhere in styles; SCSS structural tokens (`$space-*`, `$color-*`, `$border-*`,
  `focus_ring`) via `@use 'kit-deps' as *` (aliased to `vendor/gnexus-ui-kit/src/scss`
  in loadPaths). Typography tokens are NOT exported by kit-deps — use the
  `--gn-font-*` CSS variables or literals.
- **Icons**: Phosphor web font. Icon props and classes must carry the `ph` base
  class and `ph-` prefix (`ph ph-copy`, or `ph-copy` is auto-prefixed by kit).
- App-owned classes (`.card-grid-*`, `.card-modal-*` on CardGrid content, chat
  domain cards, `.session-item`) are locked by tests — do not rename.
- Surfaces intentionally NOT kit components (documented escape hatches):
  LoginScreen (SSO redirect, GnLoginCard doesn't fit), chat domain cards,
  MessageList, ImageLightbox.