emcd · emcd · Dec 14, 2025 · Dec 14, 2025 · Dec 14, 2025 · Dec 14, 2025
diff --git a/documentation/architecture/designs/index.rst b/documentation/architecture/designs/index.rst
@@ -28,8 +28,4 @@ Each design documents Python-specific architecture, interface contracts, module
    :maxdepth: 2
    :glob:
 
-   processor-detection-system
-   inventory-processors
-   structure-processors
-   results-objects
    ../openspec/specs/*/design
diff --git a/documentation/architecture/designs/processor-detection-system.rst b/documentation/architecture/designs/processor-detection-system.rst
diff --git a/documentation/architecture/designs/results-objects.rst b/documentation/architecture/designs/results-objects.rst
diff --git a/documentation/architecture/openspec/specs/caching/spec.md b/documentation/architecture/openspec/specs/caching/spec.md
@@ -0,0 +1,36 @@
+# Caching
+
+## Purpose
+The Caching capability ensures high performance and reduced network usage by storing retrieved inventories and content locally.
+
+## Requirements
+
+### Requirement: Caching System
+The system SHALL implement intelligent caching for inventories and content.
+
+Priority: High
+
+#### Scenario: Cache Hit
+- **WHEN** a user requests a resource that was recently accessed
+- **THEN** the system returns the cached version
+- **AND** no network request is made
+
+### Requirement: Cache Invalidation
+The system SHALL enforce appropriate TTL and invalidation strategies.
+
+Priority: High
+
+#### Scenario: Cache Expiry
+- **WHEN** a resource's TTL has expired
+- **THEN** the system fetches a fresh copy from the network
+- **AND** updates the cache
+
+### Requirement: Efficiency
+The system SHALL use a memory-efficient caching strategy.
+
+Priority: High
+
+#### Scenario: Large Inventories
+- **WHEN** large inventories are cached
+- **THEN** the system manages memory usage effectively
+- **AND** prevents excessive consumption
diff --git a/documentation/architecture/openspec/specs/cli/spec.md b/documentation/architecture/openspec/specs/cli/spec.md
@@ -0,0 +1,55 @@
+# CLI Interface
+
+## Purpose
+The CLI (Command Line Interface) provides human developers with direct access to documentation search and extraction capabilities. It serves as a testing ground for the engine and a standalone tool for offline documentation access.
+
+## Requirements
+
+### Requirement: CLI Implementation
+The system SHALL implement a human-usable command-line interface.
+
+Priority: High
+
+#### Scenario: Basic Usage
+- **WHEN** a user runs the `librovore` command
+- **THEN** help text is displayed showing available commands
+
+### Requirement: Inventory Query Command
+The CLI SHALL provide a command for searching documentation inventories.
+
+Priority: High
+
+#### Scenario: Searching from CLI
+- **WHEN** a user runs `librovore search <term>`
+- **THEN** the system searches configured inventories
+- **AND** displays matching results in a human-readable table
+
+### Requirement: Content Extraction Command
+The CLI SHALL provide a command for extracting full content.
+
+Priority: High
+
+#### Scenario: Extracting Content
+- **WHEN** a user runs `librovore extract <url>`
+- **THEN** the system downloads and processes the page
+- **AND** outputs the clean Markdown to stdout or a file
+
+### Requirement: Output Formats
+The CLI SHALL support multiple output formats (JSON, Markdown).
+
+Priority: High
+
+#### Scenario: JSON Output
+- **WHEN** a user runs a command with `--format json`
+- **THEN** the output is strictly valid JSON
+- **AND** suitable for piping to tools like `jq`
+
+### Requirement: Configuration Support
+The CLI SHALL support configuration files.
+
+Priority: High
+
+#### Scenario: Loading Config
+- **WHEN** the CLI starts
+- **THEN** it looks for a configuration file
+- **AND** applies settings for inventories, cache, etc.
diff --git a/...itecture/designs/inventory-processors.rst → ...spec/specs/inventory-processing/design.md b/...itecture/designs/inventory-processors.rst → ...spec/specs/inventory-processing/design.md
diff --git a/documentation/architecture/openspec/specs/inventory-processing/spec.md b/documentation/architecture/openspec/specs/inventory-processing/spec.md
@@ -0,0 +1,55 @@
+# Inventory Processing
+
+## Purpose
+The Inventory Processing capability extracts and provides object inventories from documentation sources, enabling discovery and search operations across different documentation formats (Sphinx, MkDocs, Pydoctor, Rustdoc).
+
+## Requirements
+
+### Requirement: Sphinx Support
+The system SHALL provide full support for Sphinx documentation sites.
+
+Priority: Critical
+
+#### Scenario: Processing Sphinx Site
+- **WHEN** a Sphinx site URL is provided
+- **THEN** the system parses the `objects.inv` file
+- **AND** correctly identifies cross-references and content structure
+
+### Requirement: MkDocs Support
+The system SHALL provide full support for MkDocs sites, specifically with `mkdocstrings`.
+
+Priority: Critical
+
+#### Scenario: Processing MkDocs Site
+- **WHEN** an MkDocs site URL is provided
+- **THEN** the system parses the inventory
+- **AND** extracts content from Material for MkDocs theme structures
+
+### Requirement: Pydoctor Support
+The system SHALL provide full support for Pydoctor documentation sites.
+
+Priority: Critical
+
+#### Scenario: Processing Pydoctor Site
+- **WHEN** a Pydoctor site URL is provided
+- **THEN** the system parses the inventory
+- **AND** extracts content from Pydoctor-generated HTML
+
+### Requirement: Rustdoc Support
+The system SHALL provide full support for Rustdoc documentation sites.
+
+Priority: Critical
+
+#### Scenario: Processing Rustdoc Site
+- **WHEN** a Rustdoc site URL is provided
+- **THEN** the system parses the `search-index.js`
+- **AND** extracts content from Rustdoc-generated HTML
+
+### Requirement: Extensibility
+The system SHALL provide a plugin architecture for additional processors.
+
+Priority: Low
+
+#### Scenario: Adding a Plugin
+- **WHEN** a developer implements the processor interface
+- **THEN** the system discovers and uses the new processor
diff --git a/documentation/architecture/openspec/specs/mcp-server/spec.md b/documentation/architecture/openspec/specs/mcp-server/spec.md
@@ -0,0 +1,55 @@
+# MCP Server
+
+## Purpose
+The MCP (Model Context Protocol) Server interface enables AI agents to programmatically discover, search, and extract technical documentation. It acts as the primary bridge between AI systems and the documentation engine.
+
+## Requirements
+
+### Requirement: MCP Server Implementation
+The system SHALL implement a complete MCP server with FastMCP framework.
+
+Priority: Critical
+
+#### Scenario: AI Agent Connection
+- **WHEN** an AI agent connects to the MCP server
+- **THEN** the server accepts the connection
+- **AND** exposes available tools (query_inventory, query_content, summarize_inventory)
+
+### Requirement: JSON Schema Generation
+The server SHALL generate JSON schemas for all tool parameters.
+
+Priority: Critical
+
+#### Scenario: Tool Discovery
+- **WHEN** an AI agent requests the list of available tools
+- **THEN** the server returns the tool list
+- **AND** includes valid JSON schemas for all parameters
+
+### Requirement: Query Inventory Tool
+The server SHALL implement a `query_inventory` tool for searching documentation objects.
+
+Priority: Critical
+
+#### Scenario: Searching Inventory
+- **WHEN** the agent calls `query_inventory` with a search term
+- **THEN** the server searches the loaded inventories
+- **AND** returns a list of matching objects
+
+### Requirement: Query Content Tool
+The server SHALL implement a `query_content` tool for retrieving full text.
+
+Priority: Critical
+
+#### Scenario: Fetching Content
+- **WHEN** the agent calls `query_content` with a URL or object ID
+- **THEN** the server retrieves the content
+- **AND** returns it in clean Markdown format
+
+### Requirement: Summarize Inventory Tool
+The server SHALL implement a `summarize_inventory` tool for high-level overview.
+
+Priority: Critical
+
+#### Scenario: Inventory Summary
+- **WHEN** the agent calls `summarize_inventory` for a site
+- **THEN** the server provides statistics and top-level structure of the documentation