# Reveal Documentation

**Welcome to Reveal's documentation hub.** This directory contains comprehensive guides for users, developers, and AI agents.

## Quick Start by Role

### 👤 New Users

**Start here:**
1. [QUICK_START.md](QUICK_START.md) - 5-minute quick start guide (NEW!)
2. [MARKDOWN_GUIDE.md](MARKDOWN_GUIDE.md) - Core functionality and basic usage
3. [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md) - Customize Reveal's behavior
4. [COOL_TRICKS.md](COOL_TRICKS.md) - Practical examples and workflows

**Then explore:**
- [HTML_GUIDE.md](HTML_GUIDE.md) - Working with HTML files
- [SCHEMA_VALIDATION_HELP.md](SCHEMA_VALIDATION_HELP.md) - Front matter validation

### 🔧 Developers & Contributors

**Extending Reveal:**
1. [ADAPTER_AUTHORING_GUIDE.md](ADAPTER_AUTHORING_GUIDE.md) - Create custom adapters
2. [PYTHON_ADAPTER_GUIDE.md](PYTHON_ADAPTER_GUIDE.md) - Python-specific patterns
3. [ANALYZER_PATTERNS.md](ANALYZER_PATTERNS.md) - Code analysis patterns

**Reveal internals:**
- [REVEAL_ADAPTER_GUIDE.md](REVEAL_ADAPTER_GUIDE.md) - Meta-analysis with Reveal
- [HELP_SYSTEM_GUIDE.md](HELP_SYSTEM_GUIDE.md) - Help system architecture
- [RELEASE_GUIDE.md](RELEASE_GUIDE.md) - Release process

**Best practices:**
- [ANTI_PATTERNS.md](ANTI_PATTERNS.md) - What NOT to do
- [DUPLICATE_DETECTION_GUIDE.md](DUPLICATE_DETECTION_GUIDE.md) - Handle duplicates

### 🤖 AI Agents

**Quick reference:**
- [AGENT_HELP.md](AGENT_HELP.md) - Concise patterns for AI agents (19KB)
- [AGENT_HELP_FULL.md](AGENT_HELP_FULL.md) - Comprehensive reference (41KB)

**Use Reveal for:**
- Code analysis and understanding
- Documentation extraction
- Schema validation
- Token-efficient code navigation

**See also:** [COOL_TRICKS.md](COOL_TRICKS.md) for agent-specific workflows

## Documentation Index

### Core Guides

| Guide | Purpose | Audience |
|-------|---------|----------|
| [QUICK_START.md](QUICK_START.md) | 5-minute quick start guide | New Users |
| [MARKDOWN_GUIDE.md](MARKDOWN_GUIDE.md) | Core Reveal functionality, markdown analysis | Users, Agents |
| [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md) | Configuration options, customization | Users, Developers |
| [SCHEMA_VALIDATION_HELP.md](SCHEMA_VALIDATION_HELP.md) | Front matter schema validation | Users, Agents |
| [COOL_TRICKS.md](COOL_TRICKS.md) | Practical examples, workflows, recipes | All |

### Language-Specific Guides

| Guide | Purpose | Audience |
|-------|---------|----------|
| [PYTHON_ADAPTER_GUIDE.md](PYTHON_ADAPTER_GUIDE.md) | Python code analysis patterns | Developers, Agents |
| [HTML_GUIDE.md](HTML_GUIDE.md) | HTML analysis and extraction | Users, Agents |

### Development Guides

| Guide | Purpose | Audience |
|-------|---------|----------|
| [ADAPTER_AUTHORING_GUIDE.md](ADAPTER_AUTHORING_GUIDE.md) | Create custom file adapters | Developers |
| [REVEAL_ADAPTER_GUIDE.md](REVEAL_ADAPTER_GUIDE.md) | Meta-analysis with Reveal | Developers |
| [ANALYZER_PATTERNS.md](ANALYZER_PATTERNS.md) | Code analysis patterns | Developers |
| [DUPLICATE_DETECTION_GUIDE.md](DUPLICATE_DETECTION_GUIDE.md) | Handle duplicate detection | Developers |
| [HELP_SYSTEM_GUIDE.md](HELP_SYSTEM_GUIDE.md) | Help system architecture | Developers |
| [RELEASE_GUIDE.md](RELEASE_GUIDE.md) | Release process | Maintainers |
| [ANTI_PATTERNS.md](ANTI_PATTERNS.md) | Common mistakes to avoid | Developers |
| [../../docs/BUG_PREVENTION.md](../../docs/BUG_PREVENTION.md) | Bug prevention patterns | Developers |

### Workflow Guides

| Guide | Purpose | Audience |
|-------|---------|----------|
| [../../docs/REVEAL_CODEBASE_REVIEW_GUIDE.md](../../docs/REVEAL_CODEBASE_REVIEW_GUIDE.md) | Using Reveal for codebase reviews | Users, Agents |

### AI Agent References

| Guide | Size | Purpose |
|-------|------|---------|
| [AGENT_HELP.md](AGENT_HELP.md) | 19KB | Quick patterns and examples |
| [AGENT_HELP_FULL.md](AGENT_HELP_FULL.md) | 41KB | Comprehensive reference |

## Common Tasks

### For Users

**"How do I analyze a Python file?"**
→ [PYTHON_ADAPTER_GUIDE.md](PYTHON_ADAPTER_GUIDE.md) - Python-specific features
→ [MARKDOWN_GUIDE.md](MARKDOWN_GUIDE.md) - General structure extraction

**"How do I validate front matter schemas?"**
→ [SCHEMA_VALIDATION_HELP.md](SCHEMA_VALIDATION_HELP.md) - Schema validation
→ [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md) - Configure validation rules

**"How do I customize Reveal's output?"**
→ [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md) - Configuration options
→ [COOL_TRICKS.md](COOL_TRICKS.md) - Practical examples

### For Developers

**"How do I create a custom adapter?"**
→ [ADAPTER_AUTHORING_GUIDE.md](ADAPTER_AUTHORING_GUIDE.md) - Adapter creation guide
→ [ANALYZER_PATTERNS.md](ANALYZER_PATTERNS.md) - Analysis patterns

**"How do I handle duplicates in my code?"**
→ [DUPLICATE_DETECTION_GUIDE.md](DUPLICATE_DETECTION_GUIDE.md) - Duplicate detection
→ [ANTI_PATTERNS.md](ANTI_PATTERNS.md) - Patterns to avoid

**"How does Reveal's help system work?"**
→ [HELP_SYSTEM_GUIDE.md](HELP_SYSTEM_GUIDE.md) - Help architecture
→ [REVEAL_ADAPTER_GUIDE.md](REVEAL_ADAPTER_GUIDE.md) - Meta-analysis

### For AI Agents

**"What can Reveal do?"**
→ [AGENT_HELP.md](AGENT_HELP.md) - Quick reference (start here)
→ [AGENT_HELP_FULL.md](AGENT_HELP_FULL.md) - Full capabilities

**"How do I use Reveal efficiently?"**
→ [COOL_TRICKS.md](COOL_TRICKS.md) - Token-efficient patterns
→ [MARKDOWN_GUIDE.md](MARKDOWN_GUIDE.md) - Progressive disclosure

## Recommended Reading Paths

### Path 1: User → Power User
1. [QUICK_START.md](QUICK_START.md) - 5-minute intro
2. [MARKDOWN_GUIDE.md](MARKDOWN_GUIDE.md) - Complete basics
3. [COOL_TRICKS.md](COOL_TRICKS.md) - Advanced usage
4. [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md) - Customization
5. [SCHEMA_VALIDATION_HELP.md](SCHEMA_VALIDATION_HELP.md) - Validation

### Path 2: Developer → Contributor
1. [ADAPTER_AUTHORING_GUIDE.md](ADAPTER_AUTHORING_GUIDE.md) - Extensibility
2. [ANALYZER_PATTERNS.md](ANALYZER_PATTERNS.md) - Patterns
3. [ANTI_PATTERNS.md](ANTI_PATTERNS.md) - Pitfalls
4. [RELEASE_GUIDE.md](RELEASE_GUIDE.md) - Contributing

### Path 3: AI Agent → Expert
1. [AGENT_HELP.md](AGENT_HELP.md) - Quick start
2. [COOL_TRICKS.md](COOL_TRICKS.md) - Workflows
3. [AGENT_HELP_FULL.md](AGENT_HELP_FULL.md) - Deep dive

## Getting Help

**Command-line help:**
```bash
reveal --help                    # General help
reveal --agent-help              # Quick AI agent reference
reveal help://markdown-guide     # View specific guide
reveal help://cool-tricks        # Practical examples
```

**Documentation:**
- Start with [QUICK_START.md](QUICK_START.md) for a 5-minute introduction
- Read [MARKDOWN_GUIDE.md](MARKDOWN_GUIDE.md) for complete basics
- See [COOL_TRICKS.md](COOL_TRICKS.md) for practical examples
- Check [ANTI_PATTERNS.md](ANTI_PATTERNS.md) if something's not working

**External resources:**
- [GitHub Issues](https://github.com/semantic-infrastructure-lab/reveal/issues) - Bug reports and features
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution guidelines
- [Project README](../../README.md) - Project overview

## Document Metadata

**Last updated:** 2026-01-19
**Reveal version:** 0.38.0+
**Total guides:** 19 (16 in reveal/docs/, 2 in docs/, 1 README)

---

**Navigation:** [← Back to Project README](../../README.md) | [Configuration Guide →](CONFIGURATION_GUIDE.md) | [Quick Tricks →](COOL_TRICKS.md)
