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

## Mobile web

Installed Sybil uses `standalone` display, retaining the system status bar where the browser supports it. The viewport keeps pinch zoom disabled. Compact regular-chat replies use the transcript width and the active provider/model appears beneath the title; Agent keeps its existing layout.

Horizontal navigation swipes start on workspace chrome or empty space. Text, tables, quotations, code, controls, existing selections and nested horizontal scrollers keep native gestures, including at scroll edges. Long-press/right-click on transcript text and links uses the native browser menu; the message-actions button provides Fork.

Agent notification settings include separate browser/server failure guidance and an expandable Android / GrapheneOS setup guide. See [mobile QA results and limitations](../docs/mobile-web-qa.md), including how to run the browser fixtures.