From a29f5b2e48ed5ba92c3ef0c9fa6d7db52b05cdc5 Mon Sep 17 00:00:00 2001
From: runyaga <runyaga@users.noreply.github.com>
Date: Thu, 15 Jan 2026 15:44:49 -0600
Subject: [PATCH] docs: fix documentation discrepancies with codebase

CLI documentation:
- Add missing short flags (-f for --filter, -l for --limit)
- Document missing `init-config` command
- Document missing `inspect` command

Python API documentation:
- Fix get_document_by_id example to use string ID (not integer)
- Document filter parameter for ask() method

MCP documentation:
- Correct search_documents limit default (uses config, not hardcoded 5)
---
 docs/cli.md    | 40 +++++++++++++++++++++++++++++++++++-----
 docs/mcp.md    |  2 +-
 docs/python.md | 11 ++++++++++-
 3 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index b630af4e..f4b94367 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -34,7 +34,7 @@ haiku-rag list
 
 Filter documents by properties:
 ```bash
-# Filter by URI pattern
+# Filter by URI pattern (--filter or -f)
 haiku-rag list --filter "uri LIKE '%arxiv%'"
 
 # Filter by exact title
@@ -116,10 +116,10 @@ haiku-rag search "machine learning"
 
 With options:
 ```bash
-haiku-rag search "python programming" --limit 10
+haiku-rag search "python programming" --limit 10  # or -l 10
 ```
 
-With filters (filter by document properties):
+With filters (filter by document properties, use `--filter` or `-f`):
 ```bash
 # Filter by URI pattern
 haiku-rag search "neural networks" --filter "uri LIKE '%arxiv%'"
@@ -159,7 +159,7 @@ Flags:
 
 - `--cite`: Include citations showing which documents were used
 - `--deep`: Decompose the question into sub-questions answered in parallel before synthesizing a final answer
-- `--filter`: Restrict searches to documents matching the filter (see [Filtering Search Results](python.md#filtering-search-results))
+- `--filter` / `-f`: Restrict searches to documents matching the filter (see [Filtering Search Results](python.md#filtering-search-results))
 
 ## Chat
 
@@ -182,6 +182,27 @@ The chat interface provides:
 
 See [Applications](apps.md#chat-tui) for keyboard shortcuts and features.
 
+## Inspect
+
+Launch the interactive inspector TUI for browsing documents and chunks:
+
+```bash
+haiku-rag inspect
+haiku-rag inspect --db /path/to/database.lancedb
+```
+
+!!! note
+    Requires the `tui` extra: `pip install haiku.rag-slim[tui]` (included in full `haiku.rag` package)
+
+The inspector provides:
+
+- Browse all documents in the database
+- View document metadata and content
+- Explore individual chunks
+- Search and filter results
+
+See [Applications](apps.md#inspector) for details.
+
 ## Research
 
 Run the multi-step research graph:
@@ -198,7 +219,7 @@ haiku-rag research "What are the key findings?" --filter "uri LIKE '%paper%'"
 
 Flags:
 
-- `--filter`: SQL WHERE clause to filter documents (see [Filtering Search Results](python.md#filtering-search-results))
+- `--filter` / `-f`: SQL WHERE clause to filter documents (see [Filtering Search Results](python.md#filtering-search-results))
 
 Research parameters like `max_iterations`, `confidence_threshold`, and `max_concurrency` are configured in your [configuration file](configuration/index.md) under the `research` section.
 
@@ -234,6 +255,15 @@ View current configuration settings:
 haiku-rag settings
 ```
 
+### Generate Configuration File
+
+Generate a YAML configuration file with defaults:
+```bash
+haiku-rag init-config [output_path]
+```
+
+If no path is specified, creates `haiku.rag.yaml` in the current directory.
+
 ## Database Management
 
 ### Initialize Database
diff --git a/docs/mcp.md b/docs/mcp.md
index b1e10976..a3755d9f 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -37,7 +37,7 @@ The MCP server exposes `haiku.rag` as MCP tools for compatible MCP clients like
 
 - **`search_documents`** - Search using hybrid search (vector + full-text)
   - `query` (required): Search query
-  - `limit` (optional): Maximum results (default: 5)
+  - `limit` (optional): Maximum results (uses config default if not specified)
 
 ### Question Answering
 
diff --git a/docs/python.md b/docs/python.md
index 9b9dd31a..da4b9d71 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -120,7 +120,7 @@ See [Custom Processing Pipelines](custom-pipelines.md) for building pipelines wi
 
 By ID:
 ```python
-doc = await client.get_document_by_id(1)
+doc = await client.get_document_by_id("document-id-string")
 ```
 
 By URI:
@@ -370,6 +370,15 @@ answer, citations = await client.ask(
 )
 ```
 
+Filter to specific documents:
+
+```python
+answer, citations = await client.ask(
+    "What are the main findings?",
+    filter="uri LIKE '%paper%'"
+)
+```
+
 The QA agent searches your documents for relevant information and uses the configured LLM to generate an answer. The method returns a tuple of `(answer_text, list[Citation])`. Citations include page numbers, section headings, and document references.
 
 The QA provider and model are configured in `haiku.rag.yaml` or can be passed directly to the client (see [Configuration](configuration/index.md)).