docs: Update architecture docs and add CLI usage examples

ARCHITECTURE.md:
- Add Document Storage Design section with mermaid diagram
- Document context-aware search capabilities
- Update future considerations for data relationships
- Enhance tools section description

README.md:
- Add CLI usage section with command examples
- Improve command documentation accessibility
- Show how to access help for specific commands

These updates improve documentation clarity and reflect recent feature additions.

Author: arabold

.clinerules

@@ -8,6 +8,7 @@
 - When importing a relative path, avoid using file extensions like ".js" and ".ts".
 - NEVER update any files in the following directories: .git, node_modules
 - Add and update TSDoc for all classes, methods and functions. Focus on functionality and reasoning. Avoid documenting individual parameters or return values if their use can easily be derived from their name.
+- Git commit messages must be formatted as markdown
 
 ## Architecture Documentation Guidelines
 

ARCHITECTURE.md

@@ -40,10 +40,24 @@ The project maintains a `tools/` directory containing modular implementations of
 Current tools include:
 
 - Documentation scraping functionality
-- Search capabilities
+- Search capabilities with context-aware results
 - Library version management
 - Document management operations
 
+### Document Storage Design
+
+Documents are stored with URLs and sequential ordering to maintain source context:
+
+```mermaid
+graph LR
+    D1[Previous Doc] --> D2[Current Doc] --> D3[Next Doc]
+    subgraph Same URL/Version
+        D1 & D2 & D3
+    end
+```
+
+Search results include surrounding content to provide more complete responses, while maintaining efficient retrieval through compound indexing.
+
 ### Interface-Specific Adapters
 
 #### CLI (cli.ts)
@@ -119,6 +133,8 @@ This hierarchy ensures:
 When adding new functionality:
 
 1. Implement core logic in a new tool under `tools/`
-2. Add CLI command in `cli.ts`
-3. Add MCP tool in `index.ts`
-4. Maintain consistent error handling and progress reporting
+2. Consider data relationships and context requirements
+3. Design for efficient retrieval patterns
+4. Add CLI command in `cli.ts`
+5. Add MCP tool in `index.ts`
+6. Maintain consistent error handling and progress reporting

README.md

@@ -17,6 +17,19 @@ This server supports partial version matching, selecting the best available vers
 - If a partial version (e.g., `1.2`) is specified, the latest matching version (e.g., `1.2.5`) is used.
 - If the specified version (full or partial) is not found, the server will attempt to find the closest preceding version.
 
+## CLI Usage
+
+The `docs-mcp` CLI provides commands for managing documentation. To see available commands and options:
+
+```bash
+# Show all commands
+docs-mcp --help
+
+# Show help for a specific command
+docs-mcp scrape --help
+docs-mcp search --help
+```
+
 ## Development
 
 Install dependencies: