Document Search

Search project documentation efficiently using the Serena Document Index system.

Why This Matters

Rule: Never read documentation files until the document index fails to answer.

Document Index Location

.serena/cache/documents/document_index.json

Index Types Available:

• tag_index

  - Search by tags (architecture, api, testing, etc.)

• title_index

  - Search by section titles

• project_index

  - Filter by project (basecamp-server, interface-cli, etc.)

• doc_type_index

  - Filter by document type (readme, guide, api-reference, etc.)

• content_index

  - Keyword-based content search

Workflow Pattern

Step 1: Search Document Index (Python CLI)

# Search for relevant documentation sections
cd /Users/kun/github/1ambda/dataops-platform
python3 scripts/serena/document_indexer.py --search "hexagonal architecture" --max-results 5

Step 2: Read Specific Section Only

After finding relevant section from search:

# Use section coordinates from search result
# Example: project-basecamp-server/docs/PATTERNS.md#module-placement-rules
# Read only that section (lines 45-80) instead of entire file
Read(file_path="project-basecamp-server/docs/PATTERNS.md", offset=45, limit=35)

Step 3: Alternative - Direct JSON Query

# For programmatic access in agent workflows
import json
from pathlib import Path

cache_path = Path(".serena/cache/documents/document_index.json")
index = json.loads(cache_path.read_text())

# Search by tag
architecture_docs = index['tag_index'].get('architecture', [])

# Search by project
server_docs = index['project_index'].get('project-basecamp-server', [])

# Get section content
for ref in architecture_docs[:3]:
    print(f"Section: {ref['section_title']}")
    print(f"File: {ref['relative_path']}")
    print(f"Lines: {ref['line_start']}-{ref['line_end']}")

Decision Tree

Need documentation?
|
+-- What patterns exist for X?
|   +-- doc-search: tag_index["patterns"] or tag_index["architecture"]
|
+-- How to implement feature in project Y?
|   +-- doc-search: project_index["project-Y"] + tag_index["implementation"]
|
+-- What does README say about Z?
|   +-- doc-search: title_index["Z"] or content_index["keyword"]
|
+-- Full context needed?
    +-- Read specific section (lines from search result)
    +-- LAST RESORT: Read full file

Integration with mcp-efficiency

Document search is the first step before Serena symbol queries:

# 1. Search docs for patterns/context
doc_search("hexagonal architecture", max_results=3)

# 2. Use Serena for code structure
serena.get_symbols_overview("module-core-domain/")

# 3. Find specific symbols
serena.find_symbol("RepositoryJpa", depth=1)

Common Search Queries

"hexagonal" OR "architecture"

"api" OR "endpoint" OR "controller"

"test" OR "testing" OR "fixture"

"entity" OR "repository" OR "jpa"

"command" OR "cli" OR "dli"

"config" OR "environment" OR "settings"

Token Savings Examples

Updating the Index

# Rebuild after documentation changes
python3 scripts/serena/update-symbols.py --with-docs

# Incremental update (changed files only)
python3 scripts/serena/update-symbols.py --changed-only --with-docs

# Full rebuild
python3 scripts/serena/document_indexer.py --project-root . --rebuild

Anti-Patterns

Quick Reference

# CLI search (recommended)
python3 scripts/serena/document_indexer.py --search "QUERY" --max-results 5

# Build/rebuild index
python3 scripts/serena/update-symbols.py --with-docs

# Check index stats
python3 -c "import json; d=json.load(open('.serena/cache/documents/document_index.json')); print(d['metadata'])"