refactor: code review improvements — fix bugs, extract shared utilities, add README

- Fix reactivity bug: use SvelteMap instead of Map in sessions store
- Fix theme listener memory leak: guard against double-init, return cleanup function
- Fix transport singleton ignoring different endpoints
- Fix form/button type mismatch in MessageInput
- Add safer retry validation in chat page
- Extract shared utilities: date formatting, session config check, result source config
- Extract shared components: Backdrop, PageHeader
- Extract orchestration composable from chat page (310→85 lines of script)
- Consolidate AuditTimeline switch functions into config record
- Move sample data to dedicated module
- Add dark mode support for LineageTree SVG colors
- Memoize leaf count computation in LineageTree
- Update README with usage guide and project structure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -1,3 +1,98 @@
 # llm-multiverse-ui
 
-Web frontend for the llm-multiverse orchestration system
+Web frontend for the **llm-multiverse** orchestration system. Built with SvelteKit 5, TypeScript, Tailwind CSS v4, and gRPC-Web (Connect).
+
+## Prerequisites
+
+- Node.js 20+
+- A running llm-multiverse gRPC backend (the UI proxies requests through Vite/your production reverse proxy)
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Generate protobuf TypeScript definitions (only needed after .proto changes)
+npm run generate
+
+# Start the dev server
+npm run dev
+```
+
+The app starts at `http://localhost:5173` by default.
+
+## Scripts
+
+| Command             | Description                                      |
+| ------------------- | ------------------------------------------------ |
+| `npm run dev`       | Start Vite dev server with HMR                   |
+| `npm run build`     | Production build                                 |
+| `npm run preview`   | Preview the production build locally             |
+| `npm run check`     | Run svelte-check for TypeScript/Svelte errors    |
+| `npm run lint`      | Run ESLint                                       |
+| `npm run format`    | Format code with Prettier                        |
+| `npm run generate`  | Regenerate protobuf TypeScript from `.proto` files |
+
+## Using the UI
+
+### Landing Page
+
+The root page (`/`) links to every section of the app.
+
+### Chat (`/chat`)
+
+The main interface for interacting with the orchestrator.
+
+- **Sessions** are listed in the left sidebar. Click **+ New Chat** to start a session, or select an existing one. On mobile, tap the hamburger menu to open the sidebar.
+- Type a message and press **Enter** (or the **Send** button) to send it. While the orchestrator is processing, a progress indicator and thinking section show the current state.
+- **Session Config** (gear icon / "Config" button) opens a right sidebar where you can adjust the override level, disable specific tools, grant permissions, and save/load presets.
+- If a request fails, an error banner appears with a **Retry** button.
+- Navigation links to Lineage, Memory, and Audit are in the header (hidden on small screens).
+
+### Agent Lineage (`/lineage`)
+
+Visualizes the agent spawn tree as an interactive SVG diagram.
+
+- Click a node to view agent details (ID, type, depth, children) in a side panel.
+- A legend at the bottom shows agent type colors.
+- Supports dark mode with theme-aware SVG colors.
+
+### Memory Candidates (`/memory`)
+
+Lists memory candidates captured during orchestration, grouped by session.
+
+- **Source filter** — filter by Tool Output, Model Knowledge, or Web.
+- **Confidence slider** — set a minimum confidence threshold.
+- Each card shows the candidate content, source badge, and a confidence bar.
+
+### Audit Log (`/audit`)
+
+Timeline view of orchestration events for each session.
+
+- Select a session from the dropdown, then optionally filter by event type (State Change, Tool, Error, Message).
+- Events are displayed chronologically with date separators and color-coded badges.
+
+### Theme
+
+Use the theme toggle (sun/moon icon in any header) to cycle between **System**, **Light**, and **Dark** modes. The preference is persisted in localStorage.
+
+## Project Structure
+
+```
+src/
+  lib/
+    components/      Svelte components (Backdrop, PageHeader, MessageInput, ...)
+    composables/     Reactive composables (useOrchestration)
+    data/            Sample/demo data generators
+    proto/           Generated protobuf TypeScript
+    services/        gRPC client (orchestrator)
+    stores/          Svelte 5 reactive stores (sessions, audit, memory, theme, ...)
+    types/           TypeScript types and helpers (lineage, resultSource)
+    utils/           Shared utilities (date formatting, session config)
+  routes/
+    chat/            Chat page
+    lineage/         Agent lineage visualization
+    memory/          Memory candidates browser
+    audit/           Audit log timeline
+```