# Wasot Documentation 📚

Welcome to the comprehensive documentation for Wasot - a markup language designed for human-AI collaboration. This guide will help you find exactly what you need, whether you're a first-time user or building advanced integrations.

## 🚀 Quick Navigation

### New to Wasot?
- **[Language Overview](../SYNTAX.md)** - Complete syntax reference and examples
- **[Architecture Overview](architecture.md)** - How Wasot works under the hood
- **[Core Principles](principles.md)** - Philosophy and design decisions

### Ready to Code?
- **[Testing Infrastructure](testing.md)** - Fast/slow tests, auto-generated syntax tests, scripts
- **[IDE Support](#ide--editor-support)** - Language server and editor integration
- **[Python Integration](../python/)** - Use Wasot from Python code
- **[Command Line Tools](../README.md#-core-features)** - CLI reference and examples

### Building Applications?
- **[Use Cases](use_cases.md)** - Real-world applications and patterns
- **[Data Model](wasot_and_xml.md)** - Internal representation and XML mapping
- **[Performance Analysis](memory_analysis.md)** - Memory usage and optimization

---

## 📖 Documentation Sections

### 🎯 **Core Concepts**

#### [Language Syntax](../SYNTAX.md)
Complete reference for Wasot markup language:
- Meta-lines and block structure (`.block`, `..nested`, `...deep`)
- Arguments and parameters (`arg1 "arg 2" key=value`)
- IDs and linking (`:identifier` syntax)
- Block lifecycle and explicit closing (`./`)
- [Void elements](void_elements.md) (`.hr:` self-closing syntax)

#### [Architecture Deep Dive](architecture.md)
Understanding Wasot's event-driven architecture:
- Producer-consumer pattern (Emitters → Consumers)
- Event system and data flow
- Extensibility points and plugin architecture
- Performance characteristics

#### [Core Principles](principles.md)
Philosophy behind Wasot's design:
- Human readability vs machine processability
- Fault tolerance and error recovery
- Speed of thought principle
- Collaboration-first design

### 🔧 **Development & Integration**

#### [Data Model & XML Mapping](wasot_and_xml.md)
Technical deep dive into Wasot's internal representation:
- Block hierarchy and nesting rules
- XML schema and validation
- Data transformation pipeline
- Format conversion details

#### [Use Cases & Patterns](use_cases.md)
Real-world applications and best practices:
- Document authoring workflows
- API documentation generation
- Content management systems
- Data interchange formats

#### [Memory & Performance](memory_analysis.md)
Optimization guide and performance characteristics:
- Memory usage patterns
- Large file handling
- Streaming processing benefits
- Benchmarking results

### 🛠 **IDE & Editor Support**

#### [Language Server Protocol](lsp.md)
Complete LSP implementation for IDE features:
- **Features**: Hover, symbols, go-to-definition, diagnostics
- **VS Code**: Automated extension with syntax highlighting
- **Installation**: Building and configuring the LSP server
- **Multi-editor**: Generic LSP client setup

#### [Neovim Setup Tutorial](lsp-neovim-tutorial.md) ⭐
Step-by-step Neovim integration guide:
- **Installation**: Multiple methods (system-wide, user-local, project)
- **Configuration**: Complete nvim-lspconfig setup with examples
- **Troubleshooting**: Common issues and solutions
- **Advanced**: Plugin integration (nvim-cmp, telescope, mason)
- **Performance**: Tips for large files and optimization

*This is the most comprehensive guide for getting Wasot working in your editor!*

### 🐍 **Programming Interfaces**

#### [Python Bindings](../python/)
Use Wasot from Python applications:
- **Installation**: `maturin develop --features python`
- **API**: `parse_wasot_string()`, `parse_wasot_file()`
- **Examples**: Document processing and analysis
- **Performance**: Benchmarking and optimization

#### [Command Line Interface](../README.md#-quick-start)
Complete CLI reference:
- **Conversion**: `wasot xml-listener`, `wasot to-sqlite`
- **Validation**: `wasot validate`
- **Processing**: `wasot pretty`, `wasot from-binary`
- **Examples**: Real-world usage patterns

### 🔌 **Plugin Development**

#### [Plugin Architecture](plugin_architecture.md)
Complete guide to Wasot's plugin system:
- Socket-based communication protocol
- Plugin lifecycle and discovery
- gRPC service implementation
- Security and process isolation

#### [Rust Plugin Tutorial](rust_plugin_tutorial.md) ⭐
Step-by-step tutorial for writing Wasot plugins in Rust:
- Project setup and dependencies
- Implementing gRPC services with Tonic
- Event processing and context management
- Testing and debugging plugins
- Complete working example included

*Perfect for Rust developers with 1+ years experience!*

#### [Plugin Socket Communication](plugin_socket_communication.md)
Technical deep dive into the plugin communication protocol:
- Unix domain socket lifecycle
- Event serialization formats
- Context protocol specification
- Performance characteristics and benchmarks
- Debugging and monitoring techniques

#### [Tools System](tools.md)
Overview of Wasot's tool system and processing pipeline:
- Tool registration and discovery
- Event filtering with selectors
- Context variables and state management
- Integration with plugin architecture

### 🔗 **Advanced Topics**

#### [Links & References](links.md)
Advanced linking and reference system:
- Internal ID references
- External URL handling
- Footnote generation
- Link validation

#### [Selectors](selectors.md)
CSS-like selector system for querying Wasot documents:
- Selector syntax and patterns
- Type and descendant combinators
- Query implementation details
- Future selector features

#### [Selector Specificity](specificity.md)
CSS-inspired specificity calculation:
- Specificity rules and priorities
- Calculation algorithm
- Conflict resolution
- Implementation details

#### [Abstract Syntax Tree](ast.md)
Wasot's internal AST representation:
- Node types and structure
- Parsing process
- AST transformation
- Code generation

#### [Actions System](actions.md)
Action framework for document processing:
- Action definitions
- Event handling
- Custom actions
- Integration patterns

#### [StackFrameCollector](stack_frame_collector.md)
Utility helper for managing document stack state and selector matching:
- Automatic stack management during event processing
- Child index tracking for `:nth-child()` selectors
- CSS-like selector matching with introspection
- Integration patterns and migration guide

#### [Wasot to XML Conversion](wasot_to_xml.md)
Detailed guide on XML transformation:
- Conversion rules
- Element mapping
- Attribute handling
- Schema compliance

#### [Random Generator](random-generator.md)
Testing and fuzzing infrastructure:
- Stress testing with generated content
- Edge case discovery
- Performance benchmarking
- Quality assurance

#### [Testing Infrastructure](testing.md) ⭐
Comprehensive guide to Wasot's testing landscape:
- **Fast vs Slow Tests**: Performance-optimized test categorization
- **Test Types**: Unit, integration, fuzz, honey badger, auto-generated
- **Auto-Generated Tests**: 263 syntax tests from markdown specifications
- **Test Scripts**: `test_fast.sh`, `test_all.sh`, performance analysis tools
- **Development Workflow**: Quick feedback loops and full validation

*Essential reading for understanding Wasot's comprehensive testing approach!*

#### [Project Structure](project.md)
Development and contribution guide:
- Codebase organization
- Building from source
- Testing strategy
- Contributing guidelines

### 📊 **Architecture Diagrams**

#### Database Schema
- [Wasot ER Diagram](Wasot%20ER%20Diagram.png) - Entity relationship diagram
- [Revised ER Diagram with Indexes](Revised%20ER%20Diagram%20with%20Indexes.png) - Optimized database schema

#### System Architecture
- [Architecture Diagram](architecture.png) - System components overview
- [Current System Diagram](current.png) - Current implementation state
- [Data Model Diagram](wasot_data_model.png) - Internal data structures

### 🧠 **Development Notes**

#### [Selector Parser Design](selector_parser_notes.md)
Implementation notes for the selector system:
- Parser architecture decisions
- Grammar design considerations
- Performance optimizations
- Future improvements

#### [Selector Parsing Brainstorming](brain_storming_selector_parsing.md)
Initial design explorations:
- Alternative approaches considered
- Trade-off analysis
- Implementation strategies
- Lessons learned

---

## 🎯 **Choose Your Path**

### I want to... 

#### **📝 Write Documents in Wasot**
1. Start with [Language Syntax](../SYNTAX.md)
2. Set up your editor with [LSP support](#ide--editor-support)
3. Check [Use Cases](use_cases.md) for patterns

#### **🔧 Build Applications with Wasot**
1. Understand the [Architecture](architecture.md)
2. Review the [Data Model](wasot_and_xml.md)
3. Explore [Python Integration](../python/) or CLI tools

#### **⚙️ Integrate with My Editor**
1. **Neovim**: Follow the [complete tutorial](lsp-neovim-tutorial.md)
2. **VS Code**: Use the [automated extension](lsp.md#vs-code-extension)
3. **Other editors**: See [manual LSP setup](lsp.md#manual-lsp-setup)

#### **🚀 Contribute to Wasot**
1. Read [Core Principles](principles.md)
2. Study the [Architecture](architecture.md)
3. Understand [Testing Infrastructure](testing.md)
4. Check [Project Structure](project.md)

#### **🔌 Extend Wasot with Plugins**
1. Learn the [Plugin Architecture](plugin_architecture.md)
2. Follow the [Rust Plugin Tutorial](rust_plugin_tutorial.md)
3. Study the [Socket Communication Protocol](plugin_socket_communication.md)
4. Understand the [Tools System](tools.md)

#### **🔍 Understand How It Works**
1. Start with [Architecture Overview](architecture.md)
2. Dive into [Data Model](wasot_and_xml.md)
3. Review [Memory Analysis](memory_analysis.md)

---

## 💡 **Getting Help**

- **🐛 Found a bug?** Open an issue on [GitHub](https://github.com/tom-010/wasot/issues)
- **💬 Have questions?** Check existing [GitHub discussions](https://github.com/tom-010/wasot/discussions)
- **📖 Missing docs?** Contribute improvements via pull request
- **🚀 Want a feature?** Propose it in [GitHub issues](https://github.com/tom-010/wasot/issues)

## 📋 **Quick Reference**

### Essential Commands
```bash
# Build the project
cargo build --release

# Run quality checks  
./scripts/pre-commit.sh

# Convert formats
wasot xml-listener input.wasot > output.xml
wasot to-sqlite input.wasot -d output.db

# Install LSP server
cargo build --release --bin wasot-lsp
sudo cp target/release/wasot-lsp /usr/local/bin/
```

### Key File Extensions
- `.wasot` - Standard Wasot markup files
- `.wst` - Alternative Wasot file extension
- Both extensions have full LSP support

### Core Syntax Reminder
```wasot
.document .. title="My Document" :doc1
Content goes here.

.section .. level=1 :intro
This is a section.

..paragraph
Nested paragraph content.

.# This is a heading
Headings are self-closing.

.hr:                              # Void element (self-closing, no content)
.img: alt text .. src="x.jpg"     # Void with inline text and args

./
```

---

**Happy documenting with Wasot!** 🎉

*This documentation is maintained by the Wasot community. Last updated: $(date +"%Y-%m-%d")*