diff --git a/docs/agents.md b/docs/agents.md
index 4d2d82c7..59e314cc 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -13,7 +13,8 @@ The simple QA agent answers a single question using the knowledge base. It retri
 Key points:
 
 - Uses a single `search_documents` tool to fetch relevant chunks
-- Can be run with or without inline citations in the prompt
+- Can be run with or without inline citations in the prompt (citations prefer
+  document titles when present, otherwise URIs)
 - Returns a plain string answer
 
 Python usage:
diff --git a/docs/cli.md b/docs/cli.md
index 29304493..79ae0fbb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -33,6 +33,9 @@ From file or URL:
 ```bash
 haiku-rag add-src /path/to/document.pdf
 haiku-rag add-src https://example.com/article.html
+
+# Optionally set a human‑readable title stored in the DB schema
+haiku-rag add-src /mnt/data/doc1.pdf --title "Q3 Financial Report"
 ```
 
 !!! note
@@ -83,6 +86,7 @@ haiku-rag ask "Who is the author of haiku.rag?" --cite
 ```
 
 The QA agent will search your documents for relevant information and provide a comprehensive answer. With `--cite`, responses include citations showing which documents were used.
+When available, citations use the document title; otherwise they fall back to the URI.
 
 ## Research
 
diff --git a/docs/index.md b/docs/index.md
index a788105c..514fe5bf 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -15,6 +15,7 @@
 - **Extended file format support**: Parse 40+ file formats including PDF, DOCX, HTML, Markdown, code files and more. Or add a URL!
 - **MCP server**: Exposes functionality as MCP tools
 - **CLI commands**: Access all functionality from your terminal
+  - Add sources from text, files, or URLs, optionally with a human‑readable title
 - **Python client**: Call `haiku.rag` from your own python applications
 
 ## Quick Start
@@ -42,6 +43,7 @@ async with HaikuRAG("database.lancedb") as client:
 Or use the CLI:
 ```bash
 haiku-rag add "Your document content"
+haiku-rag add-src /path/to/document.pdf --title "Q3 Financial Report"
 haiku-rag search "query"
 haiku-rag ask "Who is the author of haiku.rag?"
 haiku-rag migrate old_database.sqlite  # Migrate from SQLite
diff --git a/docs/python.md b/docs/python.md
index 94209792..78649480 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -23,6 +23,7 @@ From text:
 doc = await client.create_document(
     content="Your document content here",
     uri="doc://example",
+    title="My Example Document",  # optional human‑readable title
     metadata={"source": "manual", "topic": "example"}
 )
 ```
@@ -54,12 +55,16 @@ doc = await client.create_document(
 
 From file:
 ```python
-doc = await client.create_document_from_source("path/to/document.pdf")
+doc = await client.create_document_from_source(
+    "path/to/document.pdf", title="Project Brief"
+)
 ```
 
 From URL:
 ```python
-doc = await client.create_document_from_source("https://example.com/article.html")
+doc = await client.create_document_from_source(
+    "https://example.com/article.html", title="Example Article"
+)
 ```
 
 ### Retrieving Documents
@@ -159,6 +164,7 @@ for chunk, relevance_score in results:
     print(f"Content: {chunk.content}")
     print(f"From document: {chunk.document_id}")
     print(f"Document URI: {chunk.document_uri}")
+    print(f"Document Title: {chunk.document_title}")  # when available
     print(f"Document metadata: {chunk.document_meta}")
 ```
 
@@ -201,7 +207,7 @@ answer = await client.ask("Who is the author of haiku.rag?", cite=True)
 print(answer)
 ```
 
-The QA agent will search your documents for relevant information and use the configured LLM to generate a comprehensive answer. With `cite=True`, responses include citations showing which documents were used as sources.
+The QA agent will search your documents for relevant information and use the configured LLM to generate a comprehensive answer. With `cite=True`, responses include citations showing which documents were used as sources. Citations prefer the document title when present, otherwise they use the URI.
 
 The QA provider and model can be configured via environment variables (see [Configuration](configuration.md)).