Doc-Serve Skill

Overview

doc-serve

Capabilities

1. Multi-Mode Search: BM25 (keyword), Vector (semantic), Hybrid (fusion)
2. Automatic Setup: Repository cloning and CLI tool installation
3. Server Management: Start/stop API server with health monitoring
4. Smart Indexing: Document processing with chunking and embeddings
5. Advanced Retrieval: Context-aware search with scoring transparency
6. API Integration: RESTful endpoints with OpenAPI documentation

When to Use

• Technical queries: "Find AuthenticationError handling"
• Conceptual questions: "How does OAuth authentication work?"
• Comprehensive search: "Complete guide to error handling"
• Domain knowledge: Search internal documentation and knowledge bases
• API references: Find function definitions, error codes, specifications

Core Workflow

1. Setup Verification

doc-svr-ctl --version  # Check CLI tools installed

2. Server Management

doc-serve &            # Start server in background
doc-svr-ctl status     # Verify server health

3. Document Indexing

doc-svr-ctl index /path/to/docs  # Index documentation

4. Intelligent Search

# Choose search mode based on query type
doc-svr-ctl query "exact function name" --mode bm25      # Technical terms
doc-svr-ctl query "how concept works" --mode vector      # Explanations
doc-svr-ctl query "complete solution" --mode hybrid      # Best of both

Search Mode Selection Guide

"AuthenticationError"

"recursiveCharacterTextSplitter"

"HTTP 404"

"how authentication works"

"best practices guide"

"implement OAuth with error handling"

"complete troubleshooting guide"

Best Practices

• Mode Selection: Use BM25 for technical terms, Vector for concepts, Hybrid for comprehensive results
• Threshold Tuning: Start at 0.7, lower to 0.3-0.5 for more results
• Alpha Weighting: Adjust hybrid balance (0.0=BM25, 1.0=Vector)
• Source Citation: Always reference source filenames in responses
• Background Operation: Run server with

  doc-serve &

  for interactive use

Reference Documentation

Search Mode Guides

• BM25 Search Guide: Exact keyword matching for technical queries
• Vector Search Guide: Semantic similarity for conceptual understanding
• Hybrid Search Guide: Intelligent fusion of keyword and semantic search

Troubleshooting

• Troubleshooting Guide: Common issues and solutions

API Documentation

• API Reference: Complete endpoint documentation

Example Usage Scenarios

Technical Query (BM25 Mode)

User: "What does the documentation say about AuthenticationError?"

Execution:

doc-svr-ctl query "AuthenticationError" --mode bm25 --threshold 0.2

Response: "According to

auth_module.md

Conceptual Query (Vector Mode)

User: "How does the authentication system work?"

Execution:

doc-svr-ctl query "authentication system flow" --mode vector --threshold 0.5

Response: "The authentication system uses a multi-step flow: credential validation, token generation with JWT, session management via Redis, and automatic logout after 30 minutes (from

auth_overview.md

Comprehensive Query (Hybrid Mode)

User: "Complete guide to implementing error handling"

Execution:

doc-svr-ctl query "error handling implementation guide" --mode hybrid --alpha 0.6 --top-k 8

Response: "Complete error handling implementation: 1) Exception hierarchy design, 2) Try-catch patterns, 3) Error logging with structured data, 4) User-friendly error messages, 5) Recovery strategies (from

error_handling.md

logging_guide.md

Performance Characteristics

Configuration Requirements

API Keys (for Vector/Hybrid modes)

# Required for semantic search
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."  # Optional

Environment Setup

# Install tools
task install:global

# Configure API keys in .env file
cd doc-serve-server
echo "OPENAI_API_KEY=your-key-here" > .env

Advanced Features

• Alpha Weighting: Fine-tune hybrid search balance
• Scoring Transparency: Individual vector/BM25 scores with

  --scores

• JSON Output: Structured data with

  --json

  for scripting
• Batch Processing: Efficient indexing of large document collections
• Health Monitoring: Server status and indexing progress tracking

Integration Patterns

CLI Scripting

# Automated searches in scripts
RESULT=$(doc-svr-ctl query "$QUERY" --mode hybrid --json)
echo "$RESULT" | jq '.results[0].text'

API Integration

import requests

response = requests.post('http://localhost:8000/query/', json={
    'query': 'authentication guide',
    'mode': 'hybrid',
    'alpha': 0.5
})
results = response.json()['results']

CI/CD Integration

# Documentation validation in CI
doc-svr-ctl query "deprecated feature" --mode bm25 --threshold 0.1
if [ $? -eq 0 ]; then echo "Documentation search working"; fi

Limitations & Considerations

• API Costs: Vector/hybrid modes require OpenAI API credits
• Setup Complexity: Initial configuration requires API keys and indexing
• Resource Usage: Server requires ~500MB RAM for typical document collections
• File Formats: Supports Markdown, PDF, plain text (not Word docs or images)

Getting Started Checklist

• Install CLI tools:

  task install:global

• Set API keys in environment or

  .env

  file
• Start server:

  doc-serve &

• Index documents:

  doc-svr-ctl index /path/to/docs

• Test search:

  doc-svr-ctl query "test query"

• Explore modes: Try BM25, vector, and hybrid search