From d2fabb9f13cb3f90765a7287d3233fffc85d9391 Mon Sep 17 00:00:00 2001
From: Yiorgis Gozadinos <ggozadinos@gmail.com>
Date: Fri, 16 Jan 2026 12:47:16 +0200
Subject: [PATCH] Update docs

---
 CHANGELOG.md   | 10 ++++++++++
 docs/agents.md | 26 ++++++++++++++++++++++++++
 docs/cli.md    | 29 +++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0801be0d..30daf3f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,16 @@
 # Changelog
 ## [Unreleased]
 
+### Added
+
+- **Background Context Support**: Pass initial context to agents via CLI or Python API
+  - `haiku-rag ask --context "..." --context-file path` for Q&A with background context
+  - `haiku-rag research --context "..." --context-file path` for research with background context
+  - `haiku-rag chat --context "..." --context-file path` for chat sessions with persistent context
+  - `ResearchContext(initial_context="...")` for Python API usage
+  - `ChatSessionState(initial_context="...")` for chat agent sessions
+  - Context is included in agent system prompts and research graph planning
+
 ## [0.26.4] - 2026-01-15
 
 ### Added
diff --git a/docs/agents.md b/docs/agents.md
index 70c436f1..02121300 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -103,6 +103,7 @@ The `ChatSessionState` maintains:
 
 - `session_id` — Unique identifier for the session
 - `qa_history` — List of previous Q/A pairs (FIFO, max 50)
+- `initial_context` — Optional background context for the conversation
 - `embedding_cache` — Cached embeddings for semantic ranking
 
 Q/A history is used to:
@@ -111,6 +112,19 @@ Q/A history is used to:
 2. Avoid repeating previous answers
 3. Enable semantic ranking of relevant past answers
 
+### Background Context
+
+You can provide background context that persists throughout the conversation:
+
+```python
+session = ChatSessionState(
+    initial_context="Focus on Python programming concepts and best practices."
+)
+deps = ChatDeps(client=client, config=config, session_state=session)
+```
+
+The context is included in the agent's system prompt and passed to the research graph when answering questions.
+
 ### AG-UI Integration
 
 When using the chat agent with AG-UI streaming, state is emitted under a namespaced key to avoid conflicts with other agents:
@@ -216,6 +230,18 @@ async with HaikuRAG(path_to_db) as client:
     print(report.executive_summary)
 ```
 
+**With background context:**
+
+```python
+context = ResearchContext(
+    original_question="What are the safety protocols?",
+    initial_context="Industrial manufacturing and workplace safety domain."
+)
+state = ResearchState.from_config(context=context, config=Config)
+```
+
+The `initial_context` provides domain background that helps the planning and synthesis agents understand the context of the research question.
+
 **With custom config:**
 
 ```python
diff --git a/docs/cli.md b/docs/cli.md
index f4b94367..4b733ef5 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -153,6 +153,12 @@ Filter to specific documents:
 haiku-rag ask "What are the main findings?" --filter "uri LIKE '%paper%'"
 ```
 
+Provide background context for the question:
+```bash
+haiku-rag ask "What are the protocols?" --context "Focus on security best practices"
+haiku-rag ask "Summarize the findings" --context-file background.txt
+```
+
 The QA agent searches your documents for relevant information and provides a comprehensive answer. When available, citations use the document title; otherwise they fall back to the URI.
 
 Flags:
@@ -160,6 +166,8 @@ 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` / `-f`: Restrict searches to documents matching the filter (see [Filtering Search Results](python.md#filtering-search-results))
+- `--context`: Background context for the question (passed to the agent as system context)
+- `--context-file`: Path to a file containing background context
 
 ## Chat
 
@@ -170,6 +178,12 @@ haiku-rag chat
 haiku-rag chat --db /path/to/database.lancedb
 ```
 
+Provide background context for the conversation:
+```bash
+haiku-rag chat --context "Focus on Python programming concepts"
+haiku-rag chat --context-file domain-context.txt
+```
+
 !!! note
     Requires the `tui` extra: `pip install haiku.rag-slim[tui]` (included in full `haiku.rag` package)
 
@@ -179,6 +193,12 @@ The chat interface provides:
 - Expandable citations with source metadata
 - Session memory for context-aware follow-up questions
 - Visual grounding to inspect chunk source locations
+- Background context that persists across the entire conversation
+
+Flags:
+
+- `--context`: Background context for the conversation
+- `--context-file`: Path to a file containing background context
 
 See [Applications](apps.md#chat-tui) for keyboard shortcuts and features.
 
@@ -217,9 +237,18 @@ Filter to specific documents:
 haiku-rag research "What are the key findings?" --filter "uri LIKE '%paper%'"
 ```
 
+Provide background context for the research:
+
+```bash
+haiku-rag research "What are the safety protocols?" --context "Industrial manufacturing context"
+haiku-rag research "Analyze the methodology" --context-file research-background.txt
+```
+
 Flags:
 
 - `--filter` / `-f`: SQL WHERE clause to filter documents (see [Filtering Search Results](python.md#filtering-search-results))
+- `--context`: Background context for the research
+- `--context-file`: Path to a file containing background context
 
 Research parameters like `max_iterations`, `confidence_threshold`, and `max_concurrency` are configured in your [configuration file](configuration/index.md) under the `research` section.