Requirements

Functional Requirements

Semantic Search & Retrieval

ID	Requirement
FR-1	Semantic search over components by natural language query, returning ranked results with cosine similarity scores
FR-2	Semantic search across all indexed documentation by natural language query
FR-3	Exact component API lookup by name — inputs, outputs, selector, public methods
FR-4	Source code retrieval for any indexed component, optionally including its HTML template
FR-5	Usage example discovery — find where a component is used across the indexed codebase
FR-6	List all components with filtering by source, module path, and type (component/directive/pipe/injectable)
FR-7	List all indexed sources with per-source statistics (file count, chunk count, component count)

Indexing & Parsing

ID	Requirement
FR-8	Parse Angular components via TypeScript Compiler API — extract @Component, @Directive, @Pipe, @Injectable, @NgModule with inputs, outputs, public methods, selectors
FR-9	Parse Spring Boot classes (Java) via regex — extract @RestController, @Service, @Configuration, @Bean, and other Spring annotations with method signatures
FR-10	Parse Markdown by heading-based splitting (h1/h2/h3 sections)
FR-11	Parse HTML documentation — strip navigation/chrome, split by headings, preserve code blocks
FR-12	Parse Angular HTML templates — size-based chunking with structural boundary awareness
FR-13	Parse SCSS files — one chunk per file
FR-14	Configurable documentation sources via YAML — three types: git-repo (sparse clone at build time), html-site (wget at build time), local-mount (volume mount at runtime)
FR-14a	Support multiple versions of the same framework indexed simultaneously, scoped by source name (e.g., spring-boot-3 and spring-boot-4 side by side)
FR-15	Incremental re-indexing per source (delete + re-parse) and full reindex via --full flag

Storage & Integration

ID	Requirement
FR-16	Vector store (vectra) for semantic similarity search with 768-dimension embeddings
FR-17	Structured JSON registry for exact component lookups (name → full API surface)
FR-18	Both stores persisted to container volumes, surviving container restarts
FR-19	Expose all capabilities as 7 MCP tools via stdio transport
FR-20	All tools accept optional source parameter to scope results to a specific documentation source

Client Integration

ID	Requirement
FR-21	Provide MCP connection templates for Claude Code (.mcp.json), OpenCode (opencode.json → mcp), and Copilot CLI (~/.copilot/mcp-config.json / .vscode/mcp.json)
FR-22	Provide project instruction templates that tell the model which sources and framework versions to use — CLAUDE.md for Claude Code, AGENTS.md for OpenCode, .github/copilot-instructions.md for Copilot CLI
FR-23	Provide custom skill/agent definitions for common queries — Claude Code custom skills, OpenCode agents in .opencode/, Copilot CLI plugins
FR-24	Project instruction templates must include: available sources, framework version mappings (e.g., "this project uses Spring Boot 3 → use source: 'spring-boot-3'"), and when to prefer MCP tools over model training data

Non-Functional Requirements

No Internet at Runtime

ID	Requirement
NFR-1	Zero internet access at runtime — Podman network is internal: true (no external gateway); containers communicate only with each other
NFR-2	Embedding model (nomic-embed-text) baked into the Ollama container image at build time
NFR-3	All public documentation fetched at build time (git sparse clone, wget) and baked into the MCP server image
NFR-4	npm dependencies installed at build time, not runtime
NFR-5	Only inter-container traffic on the internal network (mcp-server ↔ ollama); no outbound internet connections
NFR-6	Internet access required only at build time; the runtime environment needs no internet

Performance & Resource Constraints

ID	Requirement
NFR-7	Embedding generation: batched (32 texts/request), concurrency-limited (2 concurrent Ollama calls), with retry + exponential backoff (3 attempts)
NFR-8	Ollama constrained to 4 CPUs / 4 GB RAM
NFR-9	Chunk size limits per parser (3000–4000 chars) to keep embeddings focused

Architecture

ID	Requirement
NFR-10	Three-container architecture: ollama (embedding), indexer (one-shot, exits after completion), mcp-server (long-running, stdio)
NFR-11	Indexer waits for Ollama health check before starting (60s timeout, polling /api/tags)
NFR-12	MCP server starts only after indexer completes successfully (service_completed_successfully)
NFR-13	File-backed stores only — no external database dependencies (vectra = local files, registry = JSON)

Extensibility

ID	Requirement
NFR-14	New documentation sources added via docs-sources.yml without code changes
NFR-15	Parser selection per source — mix and match from 6 parser types