# MiniSearch Agent Guidelines

This is your navigation hub. Start here, follow the links, and return when you need orientation.

## Before You Start

**New to this codebase?** Read in this order:
1. `docs/quick-start.md` - Get it running
2. `docs/overview.md` - Understand the system
3. `docs/project-structure.md` - Navigate the code

**Making changes?** Check:
- `docs/coding-conventions.md` - Code style
- `docs/development-commands.md` - Available commands
- `docs/pull-requests.md` - How to submit

## Repository Map

### Getting Started
- **`docs/quick-start.md`** - Installation, first run, verification
- **`docs/overview.md`** - System architecture and data flow
- **`docs/project-structure.md`** - Directory layout and component organization

### Configuration & Setup
- **`docs/configuration.md`** - Environment variables and settings reference
- **`docs/configuration.md#tuning-the-search-engines`** - Replacing the SearXNG settings file at container start: engine selection, engines blocked from an IP, the `TMPDIR` requirement
- **`docs/security.md`** - Access control, privacy, and security model

### Core Functionality
- **`docs/api.md`** - HTTP endpoint reference: parameters, responses, and error codes
- **`docs/ai-integration.md`** - AI inference types (Wllama, OpenAI, AI Horde, Internal)
- **`docs/ui-components.md`** - Component architecture and PubSub patterns
- **`docs/search-history.md`** - History database schema and management
- **`docs/conversation-memory.md`** - Token budgeting and rolling summaries
- **`docs/reranking.md`** - Reranker subsystem and model lifecycle
- **`docs/page-content.md`** - Reading result pages to ground AI answers
- **`docs/glossary.md`** - Codebase-specific terms and domain concepts

### Development
- **`docs/development-commands.md`** - Docker, npm, and testing commands
- **`docs/failure-injection.md`** - Graceful-degradation test matrix
- **`docs/coding-conventions.md`** - Style guide and patterns
- **`docs/pull-requests.md`** - PR process and merge philosophy
- **`docs/core-technologies.md`** - Technology stack and dependencies
- **`docs/design.md`** - UI/UX design principles

## Agent Decision Tree

```
Need to:
├── Add a feature?
│   ├── UI component → docs/ui-components.md
│   ├── AI integration → docs/ai-integration.md
│   ├── Search functionality → client/modules/search.ts
│   └── Settings option → docs/configuration.md
├── Fix a bug?
│   ├── UI issue → Check component + PubSub channels
│   ├── AI not working → docs/ai-integration.md + browser console
│   ├── Search failing → Check SearXNG + server hooks
│   └── Build error → docs/development-commands.md
├── Configure deployment?
│   ├── Environment variables → docs/configuration.md
│   ├── Access control → docs/security.md
│   └── Docker setup → docs/overview.md
└── Understand data flow?
    ├── Search flow → client/modules/search.ts
    ├── AI generation → client/modules/textGeneration.ts
    ├── State management → docs/ui-components.md
    └── History/Chat → docs/search-history.md + docs/conversation-memory.md
```

## Key Files Reference

### Entry Points
- `client/index.tsx` - React app initialization
- `vite.config.ts` - Vite dev server with hooks
- `Dockerfile` - Single-stage container build

### Business Logic Modules
- `client/modules/search.ts` - Search orchestration and caching
- `client/modules/textGeneration.ts` - AI response flow
- `client/modules/pubSub.ts` - All PubSub channels
- `client/modules/settings.ts` - Settings management
- `client/modules/history.ts` - Search history database

### Server-Side Modules
- `server/searchEndpointServerHook.ts` - `/search` endpoints
- `server/pageContentEndpointServerHook.ts` - `/page-content` endpoint
- `server/internalApiEndpointServerHook.ts` - `/inference` proxy
- `server/webSearchService.ts` - SearXNG integration
- `server/rerankerService.ts` - Local result reranking

### UI Components
- `client/components/DictationButton.tsx` - Microphone control shared by the search field and the chat follow-up field
- `client/components/App/` - Application shell with error boundaries
- `client/components/Search/Form/` - Search input and form
- `client/components/Search/Results/` - Textual and graphical results display
- `client/components/Search/History/` - History drawer and button
- `client/components/AiResponse/` - AI response display and chat interface
- `client/components/Pages/Main/` - Main page layout
- `client/components/Pages/Main/Menu/` - Settings drawers (AI, Search, Interface, History, Voice, Actions)
- `client/components/Pages/AccessPage.tsx` - Access key validation page
- `client/components/Analytics/SearchStats.tsx` - Search analytics cards
- `client/components/Logs/` - Application logging modal
- `client/components/Settings/HistorySettings.tsx` - History configuration UI

### Client Modules
- `client/modules/pubSub.ts` - All PubSub channels for state management
- `client/modules/search.ts` - Search orchestration and IndexedDB caching
- `client/modules/textGeneration.ts` - AI response generation and chat handling
- `client/modules/textGenerationWithWllama.ts` - Browser-based inference
- `client/modules/textGenerationWithOpenAi.ts` - OpenAI-compatible API inference
- `client/modules/textGenerationWithHorde.ts` - AI Horde distributed inference
- `client/modules/textGenerationWithInternalApi.ts` - Internal API proxy inference
- `client/modules/settings.ts` - Default settings and inference type definitions
- `client/modules/history.ts` - IndexedDB persistence for searches and chat
- `client/modules/wllama.ts` - Wllama model configuration and management
- `client/modules/webGpu.ts` - WebGPU availability detection (`"gpu" in navigator`)
- `client/modules/querySuggestions.ts` - Search suggestion UI, stored in IndexedDB
- `client/modules/relatedSearchQuery.ts` - Generates related search queries
- `client/modules/followUpQuestions.ts` - Generates follow-up questions via `followUpQuestionPubSub`
- `client/modules/accessKey.ts` - Validates and stores access keys using argon2id hashing and localStorage
- `client/modules/parentWindow.ts` - PostMessage API for embedding in parent windows
- `client/modules/searchTokenHash.ts` - CSRF protection token generation
- `client/modules/pageContent.ts` - Requests extracted page text from `/page-content`
- `client/modules/pageExcerptAllocation.ts` - Pure page-excerpt budget logic, shared by the worker and the synchronous fallback
- `client/modules/pageExcerptWorker.ts` - Tokenizes page bodies off the main thread at the search-to-generation handoff
- `client/modules/pageExcerptWorkerProtocol.ts` - Message types shared by both sides of the excerpt worker
- `client/modules/systemPrompt.ts` - System prompt templates
- `client/modules/logEntries.ts` - Application logging with unique IDs
- `client/modules/appInfo.ts` - Application metadata and version info
- `client/modules/textToSpeech.ts` - Reads answers aloud: engine selection, fallback, and the playback queue
- `client/modules/textToSpeechWorker.ts` - Synthesizes sentences off the main thread
- `client/modules/textToSpeechWorkerProtocol.ts` - Message types shared by both sides of the worker
- `client/modules/piper.ts` - The only module that imports `@diffusionstudio/vits-web`
- `client/modules/speechToText.ts` - Dictation: microphone capture, the worker's lifecycle, and engine selection between the on-device model and `SpeechRecognition`
- `client/modules/speechToTextWorker.ts` - Runs the Moonshine transcriber off the main thread
- `client/modules/speechToTextWorkerProtocol.ts` - Message types shared by both sides of the dictation worker
- `client/modules/moonshine.ts` - The only module that imports `@moonshine-ai/moonshine-wasm`
- `client/modules/keyboard.ts` - Keyboard shortcut handling
- `client/modules/stringFormatters.ts` - Text formatting utilities
- `client/modules/types.ts` - Shared TypeScript type definitions

### Server Modules
- `server/searchEndpointServerHook.ts` - `/search/text` and `/search/images` endpoints
- `server/thumbnailEndpointServerHook.ts` - `/thumbnail` endpoint: one search-result thumbnail at a time, token-gated, with an in-process LRU in front of the upstream host
- `server/internalApiEndpointServerHook.ts` - `/inference` proxy to self-hosted API
- `server/validateAccessKeyServerHook.ts` - Access key validation endpoint
- `server/statusEndpointServerHook.ts` - `/status` health check endpoint
- `server/configEndpointServerHook.ts` - `/api/config` runtime client configuration
- `server/rerankerServiceHook.ts` - Reranker model lifecycle management
- `server/compressionServerHook.ts` - gzip/brotli compression for responses
- `server/crossOriginServerHook.ts` - COOP/COEP headers for SharedArrayBuffer
- `server/dictationModelServerHook.ts` - `/dictation-models/` endpoint: serves the pinned speech-to-text model files from the instance
- `server/cacheServerHook.ts` - Cache-Control headers (preview server only)
- `server/webSearchService.ts` - SearXNG integration with circuit breaker and retry logic
- `server/pageContentService.ts` - Reads result pages and extracts query-relevant passages
- `server/pageReadHostBreaker.ts` - Per-host circuit breaker for page reads: skips a host that refused the last three reads, then probes it once
- `server/utils/publicUrl.ts` - Blocks private and reserved addresses before a server-side fetch
- `server/rerankerService.ts` - Reranker service (ONNX Runtime inference)
- `server/rankSearchResults.ts` - Score-based filtering and result reordering
- `server/searchToken.ts` - CSRF token generation and storage
- `server/verifiedTokens.ts` - In-memory `Set<string>` of verified session tokens
- `server/verifyTokenAndRateLimit.ts` - Token verification and rate limiting
- `server/handleTokenVerification.ts` - Search token validation logic
- `server/searchesSinceLastRestart.ts` - In-memory search counters for analytics
- `server/downloadFileFromHuggingFaceRepository.ts` - Downloads model files from HuggingFace

### Hooks
- `client/hooks/useSearchHistory.ts` - Search history management from IndexedDB
- `client/hooks/useHistoryRestore.ts` - Restores full search state from history
- `client/hooks/useDrawerState.ts` - Drawer open/close state with logging
- `client/hooks/useScreenWakeLock.ts` - Keeps the screen awake while a response is generating

## Common Tasks Quick Reference

### Add a new AI model
1. Add to `client/modules/wllama.ts`
2. Update `docs/ai-integration.md`
3. Update `docs/configuration.md` defaults

### Add a new setting
1. Add to `client/modules/settings.ts` default object
2. Add UI in `client/components/Pages/Main/Menu/`
3. Update `docs/configuration.md` settings table

### Modify search behavior
1. Edit `client/modules/search.ts`
2. Update `server/webSearchService.ts` if server-side changes needed
3. Check `server/rerankerService.ts` if reranking affected

### Fix UI state issues
1. Check PubSub channels in `client/modules/pubSub.ts`
2. Verify component subscriptions in `docs/ui-components.md`
3. Ensure proper state updates in business logic modules

### Analyze test coverage
1. Run `npm run test:coverage` to generate reports
2. Check `coverage/coverage-summary.json` for quick metrics
3. See `docs/development-commands.md` for full coverage analysis guide

## Quality Gates

Before any change:
```bash
npm run lint
```

Inside the dev container, the same command is `docker compose exec development-server npm run lint`.

This runs:
- Biome (formatting/linting)
- TypeScript (type checking)
- knip (dead code detection)
- jscpd (copy-paste detection)
- Custom architectural linter
- Doc gardening and documentation validator scripts

### A bare `tsc` is not a full typecheck

The project is split across three TypeScript configs, and the default one covers less than its name suggests:

| Config | Covers |
| --- | --- |
| `tsconfig.json` | `client`, `shared`, `test` |
| `tsconfig.node.json` | `vite.config.ts`, `server`, `shared`, `e2e`, `playwright.config.ts` |
| `tsconfig.eval.json` | `eval`, `shared` |

So `npx tsc --noEmit` reports success while type errors sit in `server/` or `eval/`, and CI then fails on a change that looked clean locally. Only `npm run lint` runs all three configs. Never treat a bare `tsc` as a green typecheck.

## Agent-First Principles

**Repository as System of Record:**
- All knowledge lives in versioned docs/ structure
- This file is your entry point - start here
- Follow links, don't assume - verify in code

**Context Efficiency:**
- Use this map to navigate quickly
- Return to this file when context drifts
- Follow the decision tree for common tasks

**Architecture & Boundaries:**
- Respect PubSub boundaries - don't cross concerns
- Client vs server - keep them separate
- Feature-based organization - one folder per feature

**Documentation Maintenance:**
- Update these docs when you learn something new
- Add cross-references when linking concepts
- Keep examples current with actual code

## Technology Stack

React + TypeScript + Mantine UI v9, with privacy-first architecture.
See `docs/core-technologies.md` for complete dependency list and selection criteria.

## Need Help?

1. Check relevant doc in `docs/`
2. Read the module code in `client/modules/` or `server/`
3. Look at similar existing implementations
4. Run `npm run lint` to validate changes