Sybil-2/web/README.md

# Sybil Web

Preact + Vite frontend for the Sybil backend.

## Setup

1. Copy env values:

```bash
cp .env.example .env
```

2. Install and run:

```bash
npm install
npm run dev
```

Default dev URL: `http://localhost:5173`

## Environment variables

- `VITE_API_BASE_URL`: backend API base URL. Defaults to `http://localhost:8787`.
- `VITE_ADMIN_TOKEN`: optional. Pre-fills a token in the login form.

## Authentication

- On startup, the app checks `GET /v1/auth/session`.
- If backend runs with `ADMIN_TOKEN`, sign in using that token.
- If backend runs in open mode (`ADMIN_TOKEN` unset), you can continue without a token.
- The entered token is stored in browser `localStorage` and can be cleared via Logout.

## UI

- Left panel: mixed list of chat conversations and Exa searches.
- Sidebar search uses `GET /v1/workspace-items?q=…` to search all saved titles,
  conversation messages, and web-search queries/answers. It waits 300 ms while
  typing and cancels superseded requests. Results include a single-line matching excerpt
  with matching words in bold and middle truncation
  (or “Title match” for title-only chat matches), with up to 100 newest matches.
  Clear the field or press Escape to return to recent items. Matching uses word
  prefixes, so `plan` also finds `planning`.
- Right panel:
  - Chat mode: transcript + provider/model controls.
  - Search mode: top AI answer block + Google-style Exa results view.
- Composer adapts to the active item:
  - Chat sends `POST /v1/chat-completions/stream` (SSE).
  - Search sends `POST /v1/searches/:searchId/run/stream` (SSE).
- Keyboard shortcuts:
  - `Cmd/Ctrl+J`: start a new chat.
  - `Shift+Cmd/Ctrl+J`: start a new search.
  - `Cmd/Ctrl+Up/Down`: move through the sidebar list.

Client API contract docs:
- `../docs/api/rest.md`
- `../docs/api/streaming-chat.md`

## Routes

- `/`: full Sybil app (sidebar + chat/search workspace)
- `/search?q=bitcoin+price`: standalone search page that renders only the search query box and results panel