docs/README.md

DeepBoner Documentation

Welcome to the DeepBoner documentation. This directory contains comprehensive documentation for developers, contributors, and operators.

Quick Navigation

Need to...	Go to...
Get started quickly	Getting Started
Understand the architecture	Architecture Overview
Assess production readiness	Production Readiness
Set up for development	Development Guide
Deploy the application	Deployment Guide
Look up configuration	Reference
Track technical debt	Technical Debt

Documentation Structure

docs/
├── README.md                     # This file - documentation index
│
├── getting-started/              # Onboarding documentation
│   ├── installation.md           # Installation guide
│   ├── quickstart.md             # 5-minute quickstart
│   ├── configuration.md          # Configuration guide
│   └── troubleshooting.md        # Common issues and solutions
│
├── architecture/                 # System design documentation
│   ├── overview.md               # High-level architecture
│   ├── agent-tool-state-contracts.md  # Agent/Tool/State contracts (CRITICAL)
│   ├── production-readiness.md   # Enterprise gap analysis (HONEST)
│   ├── system-registry.md        # Service registry (canonical wiring)
│   ├── workflow-diagrams.md      # Visual workflow diagrams
│   ├── component-inventory.md    # Complete component catalog
│   ├── data-models.md            # Pydantic model documentation
│   └── exception-hierarchy.md    # Exception types and handling
│
├── development/                  # Developer guides
│   ├── testing.md                # Testing strategy and patterns
│   ├── code-style.md             # Code style and conventions
│   └── release-process.md        # Release workflow
│
├── deployment/                   # Deployment documentation
│   ├── docker.md                 # Docker deployment
│   ├── huggingface-spaces.md     # HuggingFace Spaces deployment
│   └── mcp-integration.md        # MCP server setup
│
├── technical-debt/               # Known issues and improvements
│   ├── index.md                  # Technical debt overview
│   └── debt-registry.md          # Itemized debt tracking
│
├── reference/                    # API and configuration reference
│   ├── configuration.md          # All configuration options
│   └── environment-variables.md  # Environment variable reference
│
├── bugs/                         # Bug tracking (existing)
│   ├── active-bugs.md
│   └── p3-progress-bar-positioning.md
│
├── decisions/                    # Architecture Decision Records (existing)
│   └── 2025-11-27-pr55-evaluation.md
│
└── future-roadmap/               # Future feature specs (existing)
    └── 16-pubmed-fulltext.md

Documentation Standards

File Naming

• Use kebab-case for all filenames (e.g., getting-started.md)
• Keep names descriptive but concise

Content Guidelines

• Start each document with a clear title and purpose
• Include a table of contents for longer documents
• Use Mermaid diagrams for visual documentation
• Link to related documentation
• Keep content current - update when code changes

Markdown Conventions

• Use ATX-style headers (#, ##, etc.)
• Code blocks with language specification
• Tables for structured data
• Admonitions for warnings/notes (where supported)

Key Documents

For New Developers

1. Installation - Set up your environment
2. Quickstart - Run your first query
3. Architecture Overview - Understand the system
4. Testing - Run and write tests

For Contributors

1. CONTRIBUTING.md - Contribution guidelines
2. Code Style - Style conventions
3. Testing - Testing requirements

For Operators

1. Docker Deployment - Container deployment
2. HuggingFace Spaces - Cloud deployment
3. Configuration Reference - All options

For Understanding the Codebase

1. Agent-Tool-State Contracts - CRITICAL - Agent coordination contracts
2. Component Inventory - All modules
3. Data Models - Core types
4. System Registry - Service wiring
5. Technical Debt - Known issues

Related Documentation

• README.md - Project overview and quick start
• CLAUDE.md - AI agent developer reference
• CHANGELOG.md - Release history
• SECURITY.md - Security policy
• CODE_OF_CONDUCT.md - Community guidelines

Contributing to Documentation

Documentation is code. Please:

1. Keep docs updated when changing related code
2. Follow the naming and style conventions
3. Test links before committing
4. Add new documents to this index

See CONTRIBUTING.md for full guidelines.

---

"Well-documented boners only. We take evidence-based documentation very seriously." 📚