ruflo 3.10.46 → 3.11.0

package/src/ruvocal/.husky/pre-commit

@@ -1,2 +1,2 @@
-set -e
-npx lint-staged --config ./.husky/lint-stage-config.js
+set -e
+npx lint-staged --config ./.husky/lint-stage-config.js

package/src/ruvocal/.prettierignore

@@ -1,14 +1,14 @@
-.DS_Store
-node_modules
-/build
-/.svelte-kit
-/package
-/chart
-.env
-.env.*
-!.env.example
-
-# Ignore files for PNPM, NPM and YARN
-pnpm-lock.yaml
-package-lock.json
-yarn.lock
+.DS_Store
+node_modules
+/build
+/.svelte-kit
+/package
+/chart
+.env
+.env.*
+!.env.example
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

package/src/ruvocal/.prettierrc

@@ -1,7 +1,7 @@
-{
-	"useTabs": true,
-	"trailingComma": "es5",
-	"printWidth": 100,
-	"plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"],
-	"overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
-}
+{
+	"useTabs": true,
+	"trailingComma": "es5",
+	"printWidth": 100,
+	"plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"],
+	"overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
+}

package/src/ruvocal/.swarm/hnsw.metadata.json

@@ -0,0 +1 @@
+[["entry_1777949290707_anh69v",{"id":"entry_1777949290707_anh69v","key":"-","namespace":"security_analysis","content":"name: RuVector Security Analysis\ndescription: Completed security audit of ruvector codebase\ntype: project\n---"}],["entry_1777949290871_wdj3j",{"id":"entry_1777949290871_wdj3j","key":"date-2026-04-02","namespace":"security_analysis","content":"Completed comprehensive security analysis of the ruvector npm package codebase across all critical components including CLI, MCP server, and core modules.\n\n**Key Findings:**\n- No hardcoded secrets or API keys detected\n- Good input validation in place for shell commands\n- Path validation is implemented with comprehensive checks\n- Most critical vulnerabilities mitigated through sanitization\n\n**Critical Issues:** 0\n**High Issues:** 2  \n**Medium Issues:** 3\n**Low Issues:** 2\n**Risk Score:** 28/100\n\n"}],["entry_1777949290886_afbl64",{"id":"entry_1777949290886_afbl64","key":"regtest","namespace":"sessions","content":"Session started: regtest"}],["entry_1777949290893_kfjdu",{"id":"entry_1777949290893_kfjdu","key":"test-123","namespace":"tasks","content":"Task completed: test-123"}],["entry_1777949290900_soy8c9",{"id":"entry_1777949290900_soy8c9","key":"test-fix-1","namespace":"tasks","content":"Task completed: test-fix-1"}],["entry_1777949290907_ardoho",{"id":"entry_1777949290907_ardoho","key":"verify-1686-fix","namespace":"tasks","content":"Task completed: Verify dbPath persistence fix increments metrics counts (agent: hooks-tester)"}],["entry_1777949290915_o6ppnq",{"id":"entry_1777949290915_o6ppnq","key":"verify-test-session","namespace":"sessions","content":"Session started: verify-test-session"}],["entry_1777949290922_kdxhgs",{"id":"entry_1777949290922_kdxhgs","key":"test-verify-001","namespace":"tasks","content":"Task completed: test-verify-001"}]]

package/src/ruvocal/.swarm/schema.sql

@@ -0,0 +1,305 @@
+
+-- RuFlo V3 Memory Database
+-- Version: 3.0.0
+-- Features: Pattern learning, vector embeddings, temporal decay, migration tracking
+
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+PRAGMA foreign_keys = ON;
+
+-- ============================================
+-- CORE MEMORY TABLES
+-- ============================================
+
+-- Memory entries (main storage)
+CREATE TABLE IF NOT EXISTS memory_entries (
+  id TEXT PRIMARY KEY,
+  key TEXT NOT NULL,
+  namespace TEXT DEFAULT 'default',
+  content TEXT NOT NULL,
+  type TEXT DEFAULT 'semantic' CHECK(type IN ('semantic', 'episodic', 'procedural', 'working', 'pattern')),
+
+  -- Vector embedding for semantic search (stored as JSON array)
+  embedding TEXT,
+  embedding_model TEXT DEFAULT 'local',
+  embedding_dimensions INTEGER,
+
+  -- Metadata
+  tags TEXT, -- JSON array
+  metadata TEXT, -- JSON object
+  owner_id TEXT,
+
+  -- Timestamps
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  expires_at INTEGER,
+  last_accessed_at INTEGER,
+
+  -- Access tracking for hot/cold detection
+  access_count INTEGER DEFAULT 0,
+
+  -- Status
+  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deleted')),
+
+  UNIQUE(namespace, key)
+);
+
+-- Indexes for memory entries
+CREATE INDEX IF NOT EXISTS idx_memory_namespace ON memory_entries(namespace);
+CREATE INDEX IF NOT EXISTS idx_memory_key ON memory_entries(key);
+CREATE INDEX IF NOT EXISTS idx_memory_type ON memory_entries(type);
+CREATE INDEX IF NOT EXISTS idx_memory_status ON memory_entries(status);
+CREATE INDEX IF NOT EXISTS idx_memory_created ON memory_entries(created_at);
+CREATE INDEX IF NOT EXISTS idx_memory_accessed ON memory_entries(last_accessed_at);
+CREATE INDEX IF NOT EXISTS idx_memory_owner ON memory_entries(owner_id);
+
+-- ============================================
+-- PATTERN LEARNING TABLES
+-- ============================================
+
+-- Learned patterns with confidence scoring and versioning
+CREATE TABLE IF NOT EXISTS patterns (
+  id TEXT PRIMARY KEY,
+
+  -- Pattern identification
+  name TEXT NOT NULL,
+  pattern_type TEXT NOT NULL CHECK(pattern_type IN (
+    'task-routing', 'error-recovery', 'optimization', 'learning',
+    'coordination', 'prediction', 'code-pattern', 'workflow'
+  )),
+
+  -- Pattern definition
+  condition TEXT NOT NULL, -- Regex or semantic match
+  action TEXT NOT NULL, -- What to do when pattern matches
+  description TEXT,
+
+  -- Confidence scoring (0.0 - 1.0)
+  confidence REAL DEFAULT 0.5,
+  success_count INTEGER DEFAULT 0,
+  failure_count INTEGER DEFAULT 0,
+
+  -- Temporal decay
+  decay_rate REAL DEFAULT 0.01, -- How fast confidence decays
+  half_life_days INTEGER DEFAULT 30, -- Days until confidence halves without use
+
+  -- Vector embedding for semantic pattern matching
+  embedding TEXT,
+  embedding_dimensions INTEGER,
+
+  -- Versioning
+  version INTEGER DEFAULT 1,
+  parent_id TEXT REFERENCES patterns(id),
+
+  -- Metadata
+  tags TEXT, -- JSON array
+  metadata TEXT, -- JSON object
+  source TEXT, -- Where the pattern was learned from
+
+  -- Timestamps
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  last_matched_at INTEGER,
+  last_success_at INTEGER,
+  last_failure_at INTEGER,
+
+  -- Status
+  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deprecated', 'experimental'))
+);
+
+-- Indexes for patterns
+CREATE INDEX IF NOT EXISTS idx_patterns_type ON patterns(pattern_type);
+CREATE INDEX IF NOT EXISTS idx_patterns_confidence ON patterns(confidence DESC);
+CREATE INDEX IF NOT EXISTS idx_patterns_status ON patterns(status);
+CREATE INDEX IF NOT EXISTS idx_patterns_last_matched ON patterns(last_matched_at);
+
+-- Pattern evolution history (for versioning)
+CREATE TABLE IF NOT EXISTS pattern_history (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  pattern_id TEXT NOT NULL REFERENCES patterns(id),
+  version INTEGER NOT NULL,
+
+  -- Snapshot of pattern state
+  confidence REAL,
+  success_count INTEGER,
+  failure_count INTEGER,
+  condition TEXT,
+  action TEXT,
+
+  -- What changed
+  change_type TEXT CHECK(change_type IN ('created', 'updated', 'success', 'failure', 'decay', 'merged', 'split')),
+  change_reason TEXT,
+
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pattern_history_pattern ON pattern_history(pattern_id);
+
+-- ============================================
+-- LEARNING & TRAJECTORY TABLES
+-- ============================================
+
+-- Learning trajectories (SONA integration)
+CREATE TABLE IF NOT EXISTS trajectories (
+  id TEXT PRIMARY KEY,
+  session_id TEXT,
+
+  -- Trajectory state
+  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'completed', 'failed', 'abandoned')),
+  verdict TEXT CHECK(verdict IN ('success', 'failure', 'partial', NULL)),
+
+  -- Context
+  task TEXT,
+  context TEXT, -- JSON object
+
+  -- Metrics
+  total_steps INTEGER DEFAULT 0,
+  total_reward REAL DEFAULT 0,
+
+  -- Timestamps
+  started_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  ended_at INTEGER,
+
+  -- Reference to extracted pattern (if any)
+  extracted_pattern_id TEXT REFERENCES patterns(id)
+);
+
+-- Trajectory steps
+CREATE TABLE IF NOT EXISTS trajectory_steps (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  trajectory_id TEXT NOT NULL REFERENCES trajectories(id),
+  step_number INTEGER NOT NULL,
+
+  -- Step data
+  action TEXT NOT NULL,
+  observation TEXT,
+  reward REAL DEFAULT 0,
+
+  -- Metadata
+  metadata TEXT, -- JSON object
+
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+CREATE INDEX IF NOT EXISTS idx_steps_trajectory ON trajectory_steps(trajectory_id);
+
+-- ============================================
+-- MIGRATION STATE TRACKING
+-- ============================================
+
+-- Migration state (for resume capability)
+CREATE TABLE IF NOT EXISTS migration_state (
+  id TEXT PRIMARY KEY,
+  migration_type TEXT NOT NULL, -- 'v2-to-v3', 'pattern', 'memory', etc.
+
+  -- Progress tracking
+  status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'in_progress', 'completed', 'failed', 'rolled_back')),
+  total_items INTEGER DEFAULT 0,
+  processed_items INTEGER DEFAULT 0,
+  failed_items INTEGER DEFAULT 0,
+  skipped_items INTEGER DEFAULT 0,
+
+  -- Current position (for resume)
+  current_batch INTEGER DEFAULT 0,
+  last_processed_id TEXT,
+
+  -- Source/destination info
+  source_path TEXT,
+  source_type TEXT,
+  destination_path TEXT,
+
+  -- Backup info
+  backup_path TEXT,
+  backup_created_at INTEGER,
+
+  -- Error tracking
+  last_error TEXT,
+  errors TEXT, -- JSON array of errors
+
+  -- Timestamps
+  started_at INTEGER,
+  completed_at INTEGER,
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- ============================================
+-- SESSION MANAGEMENT
+-- ============================================
+
+-- Sessions for context persistence
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+
+  -- Session state
+  state TEXT NOT NULL, -- JSON object with full session state
+  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'paused', 'completed', 'expired')),
+
+  -- Context
+  project_path TEXT,
+  branch TEXT,
+
+  -- Metrics
+  tasks_completed INTEGER DEFAULT 0,
+  patterns_learned INTEGER DEFAULT 0,
+
+  -- Timestamps
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  expires_at INTEGER
+);
+
+-- ============================================
+-- VECTOR INDEX METADATA (for HNSW)
+-- ============================================
+
+-- Track HNSW index state
+CREATE TABLE IF NOT EXISTS vector_indexes (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+
+  -- Index configuration
+  dimensions INTEGER NOT NULL,
+  metric TEXT DEFAULT 'cosine' CHECK(metric IN ('cosine', 'euclidean', 'dot')),
+
+  -- HNSW parameters
+  hnsw_m INTEGER DEFAULT 16,
+  hnsw_ef_construction INTEGER DEFAULT 200,
+  hnsw_ef_search INTEGER DEFAULT 100,
+
+  -- Quantization
+  quantization_type TEXT CHECK(quantization_type IN ('none', 'scalar', 'product')),
+  quantization_bits INTEGER DEFAULT 8,
+
+  -- Statistics
+  total_vectors INTEGER DEFAULT 0,
+  last_rebuild_at INTEGER,
+
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+-- ============================================
+-- SYSTEM METADATA
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS metadata (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at INTEGER DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+
+INSERT OR REPLACE INTO metadata (key, value) VALUES
+  ('schema_version', '3.0.0'),
+  ('backend', 'hybrid'),
+  ('created_at', '2026-05-05T02:48:10.665Z'),
+  ('sql_js', 'true'),
+  ('vector_embeddings', 'enabled'),
+  ('pattern_learning', 'enabled'),
+  ('temporal_decay', 'enabled'),
+  ('hnsw_indexing', 'enabled');
+
+-- Create default vector index configuration
+INSERT OR IGNORE INTO vector_indexes (id, name, dimensions) VALUES
+  ('default', 'default', 384),
+  ('patterns', 'patterns', 384);

package/src/ruvocal/CLAUDE.md

@@ -1,126 +1,126 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Overview
-
-Chat UI is a SvelteKit application that provides a chat interface for LLMs. It powers HuggingChat (hf.co/chat). The app speaks exclusively to OpenAI-compatible APIs via `OPENAI_BASE_URL`.
-
-## Commands
-
-```bash
-npm run dev          # Start dev server on localhost:5173
-npm run build        # Production build
-npm run preview      # Preview production build
-npm run check        # TypeScript validation (svelte-kit sync + svelte-check)
-npm run lint         # Check formatting (Prettier) and linting (ESLint)
-npm run format       # Auto-format with Prettier
-npm run test         # Run all tests (Vitest)
-```
-
-### Running a Single Test
-
-```bash
-npx vitest run path/to/file.spec.ts        # Run specific test file
-npx vitest run -t "test name"              # Run test by name
-npx vitest --watch path/to/file.spec.ts    # Watch mode for single file
-```
-
-### Test Environments
-
-Tests are split into three workspaces (configured in vite.config.ts):
-
-- **Client tests** (`*.svelte.test.ts`): Browser environment with Playwright
-- **SSR tests** (`*.ssr.test.ts`): Node environment for server-side rendering
-- **Server tests** (`*.test.ts`, `*.spec.ts`): Node environment for utilities
-
-## Architecture
-
-### Stack
-
-- **SvelteKit 2** with Svelte 5 (uses runes: `$state`, `$effect`, `$bindable`)
-- **MongoDB** for persistence (auto-fallback to in-memory with MongoMemoryServer when `MONGODB_URL` not set)
-- **TailwindCSS** for styling
-
-### Key Directories
-
-```
-src/
-├── lib/
-│   ├── components/       # Svelte components (chat/, mcp/, voice/, icons/)
-│   ├── server/
-│   │   ├── api/utils/       # Shared API helpers (auth, superjson, model/conversation resolvers)
-│   │   ├── textGeneration/  # LLM streaming pipeline
-│   │   ├── mcp/          # Model Context Protocol integration
-│   │   ├── router/       # Smart model routing (Omni)
-│   │   ├── database.ts   # MongoDB collections
-│   │   ├── models.ts     # Model registry from OPENAI_BASE_URL/models
-│   │   └── auth.ts       # OpenID Connect authentication
-│   ├── types/            # TypeScript interfaces (Conversation, Message, User, Model, etc.)
-│   ├── stores/           # Svelte stores for reactive state
-│   └── utils/            # Helpers (tree/, marked.ts, auth.ts, etc.)
-├── routes/               # SvelteKit file-based routing
-│   ├── conversation/[id]/  # Chat page + streaming endpoint
-│   ├── settings/         # User settings pages
-│   ├── api/              # Legacy v1 API endpoints (mcp, transcribe, fetch-url)
-│   ├── api/v2/           # REST API endpoints (+server.ts)
-│   └── r/[id]/           # Shared conversation view
-```
-
-### Text Generation Flow
-
-1. User sends message via `POST /conversation/[id]`
-2. Server validates user, fetches conversation history
-3. Builds message tree structure (see `src/lib/utils/tree/`)
-4. Calls LLM endpoint via OpenAI client
-5. Streams response back, stores in MongoDB
-
-### Model Context Protocol (MCP)
-
-MCP servers are configured via `MCP_SERVERS` env var. When enabled, tools are exposed as OpenAI function calls. The router can auto-select tools-capable models when `LLM_ROUTER_ENABLE_TOOLS=true`.
-
-### LLM Router (Omni)
-
-Smart routing via Arch-Router model. Configured with:
-
-- `LLM_ROUTER_ROUTES_PATH`: JSON file defining routes
-- `LLM_ROUTER_ARCH_BASE_URL`: Router endpoint
-- Shortcuts: multimodal routes bypass router if `LLM_ROUTER_ENABLE_MULTIMODAL=true`
-
-### Database Collections
-
-- `conversations` - Chat sessions with nested messages
-- `users` - User accounts (OIDC-backed)
-- `sessions` - Session data
-- `sharedConversations` - Public share links
-- `settings` - User preferences
-
-## Environment Setup
-
-Copy `.env` to `.env.local` and configure:
-
-```env
-OPENAI_BASE_URL=https://router.huggingface.co/v1
-OPENAI_API_KEY=hf_***
-# MONGODB_URL is optional; omit for in-memory DB persisted to ./db
-```
-
-See `.env` for full list of variables including router config, MCP servers, auth, and feature flags.
-
-## Code Conventions
-
-- TypeScript strict mode enabled
-- ESLint: no `any`, no non-null assertions
-- Prettier: tabs, 100 char width, Tailwind class sorting
-- Server vs client separation via SvelteKit conventions (`+page.server.ts` vs `+page.ts`)
-
-## Feature Development Checklist
-
-When building new features, consider:
-
-1. **HuggingChat vs self-hosted**: Wrap HuggingChat-specific features with `publicConfig.isHuggingChat`
-2. **Settings persistence**: Add new fields to `src/lib/types/Settings.ts`, update API endpoint at `src/routes/api/v2/user/settings/+server.ts`
-3. **Rich dropdowns**: Use `bits-ui` (Select, DropdownMenu) instead of native elements when you need icons/images in options
-4. **Scrollbars**: Use `scrollbar-custom` class for styled scrollbars
-5. **Icons**: Custom icons in `$lib/components/icons/`, use Carbon (`~icons/carbon/*`) or Lucide (`~icons/lucide/*`) for standard icons
-6. **Provider avatars**: Use `PROVIDERS_HUB_ORGS` from `@huggingface/inference` for HF provider avatar URLs
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Chat UI is a SvelteKit application that provides a chat interface for LLMs. It powers HuggingChat (hf.co/chat). The app speaks exclusively to OpenAI-compatible APIs via `OPENAI_BASE_URL`.
+
+## Commands
+
+```bash
+npm run dev          # Start dev server on localhost:5173
+npm run build        # Production build
+npm run preview      # Preview production build
+npm run check        # TypeScript validation (svelte-kit sync + svelte-check)
+npm run lint         # Check formatting (Prettier) and linting (ESLint)
+npm run format       # Auto-format with Prettier
+npm run test         # Run all tests (Vitest)
+```
+
+### Running a Single Test
+
+```bash
+npx vitest run path/to/file.spec.ts        # Run specific test file
+npx vitest run -t "test name"              # Run test by name
+npx vitest --watch path/to/file.spec.ts    # Watch mode for single file
+```
+
+### Test Environments
+
+Tests are split into three workspaces (configured in vite.config.ts):
+
+- **Client tests** (`*.svelte.test.ts`): Browser environment with Playwright
+- **SSR tests** (`*.ssr.test.ts`): Node environment for server-side rendering
+- **Server tests** (`*.test.ts`, `*.spec.ts`): Node environment for utilities
+
+## Architecture
+
+### Stack
+
+- **SvelteKit 2** with Svelte 5 (uses runes: `$state`, `$effect`, `$bindable`)
+- **MongoDB** for persistence (auto-fallback to in-memory with MongoMemoryServer when `MONGODB_URL` not set)
+- **TailwindCSS** for styling
+
+### Key Directories
+
+```
+src/
+├── lib/
+│   ├── components/       # Svelte components (chat/, mcp/, voice/, icons/)
+│   ├── server/
+│   │   ├── api/utils/       # Shared API helpers (auth, superjson, model/conversation resolvers)
+│   │   ├── textGeneration/  # LLM streaming pipeline
+│   │   ├── mcp/          # Model Context Protocol integration
+│   │   ├── router/       # Smart model routing (Omni)
+│   │   ├── database.ts   # MongoDB collections
+│   │   ├── models.ts     # Model registry from OPENAI_BASE_URL/models
+│   │   └── auth.ts       # OpenID Connect authentication
+│   ├── types/            # TypeScript interfaces (Conversation, Message, User, Model, etc.)
+│   ├── stores/           # Svelte stores for reactive state
+│   └── utils/            # Helpers (tree/, marked.ts, auth.ts, etc.)
+├── routes/               # SvelteKit file-based routing
+│   ├── conversation/[id]/  # Chat page + streaming endpoint
+│   ├── settings/         # User settings pages
+│   ├── api/              # Legacy v1 API endpoints (mcp, transcribe, fetch-url)
+│   ├── api/v2/           # REST API endpoints (+server.ts)
+│   └── r/[id]/           # Shared conversation view
+```
+
+### Text Generation Flow
+
+1. User sends message via `POST /conversation/[id]`
+2. Server validates user, fetches conversation history
+3. Builds message tree structure (see `src/lib/utils/tree/`)
+4. Calls LLM endpoint via OpenAI client
+5. Streams response back, stores in MongoDB
+
+### Model Context Protocol (MCP)
+
+MCP servers are configured via `MCP_SERVERS` env var. When enabled, tools are exposed as OpenAI function calls. The router can auto-select tools-capable models when `LLM_ROUTER_ENABLE_TOOLS=true`.
+
+### LLM Router (Omni)
+
+Smart routing via Arch-Router model. Configured with:
+
+- `LLM_ROUTER_ROUTES_PATH`: JSON file defining routes
+- `LLM_ROUTER_ARCH_BASE_URL`: Router endpoint
+- Shortcuts: multimodal routes bypass router if `LLM_ROUTER_ENABLE_MULTIMODAL=true`
+
+### Database Collections
+
+- `conversations` - Chat sessions with nested messages
+- `users` - User accounts (OIDC-backed)
+- `sessions` - Session data
+- `sharedConversations` - Public share links
+- `settings` - User preferences
+
+## Environment Setup
+
+Copy `.env` to `.env.local` and configure:
+
+```env
+OPENAI_BASE_URL=https://router.huggingface.co/v1
+OPENAI_API_KEY=hf_***
+# MONGODB_URL is optional; omit for in-memory DB persisted to ./db
+```
+
+See `.env` for full list of variables including router config, MCP servers, auth, and feature flags.
+
+## Code Conventions
+
+- TypeScript strict mode enabled
+- ESLint: no `any`, no non-null assertions
+- Prettier: tabs, 100 char width, Tailwind class sorting
+- Server vs client separation via SvelteKit conventions (`+page.server.ts` vs `+page.ts`)
+
+## Feature Development Checklist
+
+When building new features, consider:
+
+1. **HuggingChat vs self-hosted**: Wrap HuggingChat-specific features with `publicConfig.isHuggingChat`
+2. **Settings persistence**: Add new fields to `src/lib/types/Settings.ts`, update API endpoint at `src/routes/api/v2/user/settings/+server.ts`
+3. **Rich dropdowns**: Use `bits-ui` (Select, DropdownMenu) instead of native elements when you need icons/images in options
+4. **Scrollbars**: Use `scrollbar-custom` class for styled scrollbars
+5. **Icons**: Custom icons in `$lib/components/icons/`, use Carbon (`~icons/carbon/*`) or Lucide (`~icons/lucide/*`) for standard icons
+6. **Provider avatars**: Use `PROVIDERS_HUB_ORGS` from `@huggingface/inference` for HF provider avatar URLs