# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

HANDLER NAME
============
docs-search

DESCRIPTION
============
Real-time documentation search with FTS5 (Full-Text Search). Replaces Context7 MCP.
Searches docs/, wiki/, docs/help/ and cached web documentation.
Uses SQLite indexing for fast queries; Fallback to LIKE search.

OPERATIONS
===========

search <query>
  Full-text search of all indexed documents.
  Limit: 20 hits (FTS5 ranking).
  Fallback: LIKE search if FTS5 is missing.
  For empty results: Direct file search in docs/, wiki/, docs/help/.

index
  Rebuilds or updates search index.
  Processes: .md, .txt, .rst, .py files.
  Checks via MD5 checksum whether an update is necessary.
  Extracts title from first line (without #).
  Writes: document_index, document_fts.

lookup <library> <topic>
  Search library-specific docs.
  Limit: 10 hits.
  Uses 'library' and 'doc_type' columns.

fetch <url>
  Downloads documentation page, converts HTML to Markdown,
  cached in data/cache/docs/ (MD5 hash as filename).
  Uses html2text (optimal) or regex fallback.
  Registers URL with library name in document_index.
  Timeout: 15 seconds.

stats
  Shows index statistics: Total, Local, Web, Libraries.
  Default operation if no parameters.

EXAMPLES
=========

bach docs-search search "SQLite optimization"
  -> Search "SQLite optimization" in docs/, wiki/, docs/help/

bach docs-search index
  -> Build/update index

bach docs-search lookup numpy array_operations
  -> Search for "array_operations" in "numpy" library docs

bach docs-search fetch https://docs.python.org/3/library/sqlite3.html
  -> Download, cache, index HTML page

bach docs-search stats
  -> Show index statistics

FILES
=======
data/bach.db
  SQLite database with tables:
  - document_index: metadata + content of all documents
  - document_fts: FTS5 Virtual Table for full-text search

data/cache/docs/
  Cached web documentation (MD5-Hash.md)
  Generated by fetch operation.

docs/
wiki/
docs/help/
  Source directories for local documentation.
  Searches recursively during index operation.

SEE ALSO
==========
docs/help/ More handler documentation
data/ database and cache folder
hub/base.py BaseHandler implementation
