Kp/refine (#12)

* fix: add complete conversion utility functions
* full refactor on docs, more CoT types
* testing and android specific fixes for unflatten

Author: Kit Plummer

README.md

@@ -0,0 +1,178 @@
+# Ditto CoT Documentation Index
+
+Complete index of all documentation for the Ditto CoT library, organized by category and purpose.
+
+## 📁 Documentation Structure
+
+```
+docs/
+├── technical/           # Architecture and system design
+├── development/         # Getting started and building
+├── integration/         # SDK integration and examples
+└── reference/          # API reference and schemas
+```
+
+## 🏗️ Technical Documentation
+
+Deep technical content about system architecture, algorithms, and performance.
+
+| Document | Description | Audience |
+|----------|-------------|----------|
+| **[Architecture](technical/architecture.md)** | System design, components, and data flow | Developers, Architects |
+| **[CRDT Optimization](technical/crdt-optimization.md)** | Advanced P2P synchronization algorithms | Distributed Systems Engineers |
+| **[Performance](technical/performance.md)** | Benchmarks, optimization techniques | Performance Engineers |
+
+## 🛠️ Development Guides
+
+Getting started, building, and testing the library.
+
+| Document | Description | Audience |
+|----------|-------------|----------|
+| **[Getting Started](development/getting-started.md)** | Quick setup for all languages | New Developers |
+| **[Building](development/building.md)** | Build procedures and requirements | Contributors |
+| **[Testing](development/testing.md)** | Testing strategies and E2E scenarios | QA Engineers, Contributors |
+
+## 🔌 Integration Guides
+
+Real-world usage patterns and SDK integration.
+
+| Document | Description | Audience |
+|----------|-------------|----------|
+| **[Ditto SDK Integration](integration/ditto-sdk.md)** | Observer patterns and DQL operations | App Developers |
+| **[Rust Examples](integration/examples/rust.md)** | Rust-specific patterns and async handling | Rust Developers |
+| **[Java Examples](integration/examples/java.md)** | Java/Android with Spring Boot | Java/Android Developers |
+| **[Migration Guide](integration/migration.md)** | Version upgrades and legacy migration | System Administrators |
+
+## 📖 Reference Documentation
+
+Complete API documentation, schemas, and troubleshooting.
+
+| Document | Description | Audience |
+|----------|-------------|----------|
+| **[API Reference](reference/api-reference.md)** | Complete API for all languages | All Developers |
+| **[Schema Reference](reference/schema.md)** | Document schemas and validation | System Integrators |
+| **[Troubleshooting](reference/troubleshooting.md)** | Common issues and solutions | Support Engineers |
+
+## 🎯 Language-Specific Documentation
+
+Implementation-specific guides and APIs.
+
+| Document | Description | Audience |
+|----------|-------------|----------|
+| **[Rust README](../rust/README.md)** | Rust-specific APIs and patterns | Rust Developers |
+| **[Java README](../java/README.md)** | Java-specific APIs and patterns | Java Developers |
+
+## 🔗 Cross-Reference Matrix
+
+Quick navigation between related topics:
+
+### For New Users
+Start Here → [Getting Started](development/getting-started.md) → [Integration Examples](integration/examples/) → [API Reference](reference/api-reference.md)
+
+### For System Architects
+[Architecture](technical/architecture.md) → [CRDT Optimization](technical/crdt-optimization.md) → [Performance](technical/performance.md) → [Schema Reference](reference/schema.md)
+
+### For Integration Developers
+[Ditto SDK Integration](integration/ditto-sdk.md) → [Language Examples](integration/examples/) → [Migration Guide](integration/migration.md) → [Troubleshooting](reference/troubleshooting.md)
+
+### For Contributors
+[Building](development/building.md) → [Testing](development/testing.md) → [Architecture](technical/architecture.md) → [API Reference](reference/api-reference.md)
+
+## 📚 Documentation Categories
+
+### By Complexity Level
+
+**Beginner**:
+- [Getting Started](development/getting-started.md)
+- [Basic Integration Examples](integration/examples/)
+- [Troubleshooting](reference/troubleshooting.md)
+
+**Intermediate**:
+- [Building](development/building.md)
+- [Ditto SDK Integration](integration/ditto-sdk.md)
+- [API Reference](reference/api-reference.md)
+- [Schema Reference](reference/schema.md)
+
+**Advanced**:
+- [Architecture](technical/architecture.md)
+- [CRDT Optimization](technical/crdt-optimization.md)
+- [Performance](technical/performance.md)
+- [Migration Guide](integration/migration.md)
+
+### By Use Case
+
+**Setting Up Development Environment**:
+1. [Getting Started](development/getting-started.md)
+2. [Building](development/building.md)
+3. [Testing](development/testing.md)
+
+**Integrating into Applications**:
+1. [Ditto SDK Integration](integration/ditto-sdk.md)
+2. [Language-Specific Examples](integration/examples/)
+3. [API Reference](reference/api-reference.md)
+
+**Understanding System Design**:
+1. [Architecture](technical/architecture.md)
+2. [CRDT Optimization](technical/crdt-optimization.md)
+3. [Schema Reference](reference/schema.md)
+
+**Optimizing Performance**:
+1. [Performance](technical/performance.md)
+2. [CRDT Optimization](technical/crdt-optimization.md)
+3. [Troubleshooting](reference/troubleshooting.md)
+
+**Migrating Systems**:
+1. [Migration Guide](integration/migration.md)
+2. [Schema Reference](reference/schema.md)
+3. [Integration Examples](integration/examples/)
+
+## 🔍 Quick Search
+
+### Find by Keyword
+
+**CRDT**: [Architecture](technical/architecture.md) | [CRDT Optimization](technical/crdt-optimization.md) | [Schema Reference](reference/schema.md)
+
+**Performance**: [Performance](technical/performance.md) | [CRDT Optimization](technical/crdt-optimization.md) | [Troubleshooting](reference/troubleshooting.md)
+
+**API**: [API Reference](reference/api-reference.md) | [Integration Examples](integration/examples/) | [Language READMEs](../rust/README.md)
+
+**Testing**: [Testing Guide](development/testing.md) | [Building](development/building.md) | [Troubleshooting](reference/troubleshooting.md)
+
+**Schema**: [Schema Reference](reference/schema.md) | [API Reference](reference/api-reference.md) | [Migration Guide](integration/migration.md)
+
+**Integration**: [Ditto SDK Integration](integration/ditto-sdk.md) | [Examples](integration/examples/) | [Migration](integration/migration.md)
+
+### Find by Language
+
+**Rust**: [Rust Examples](integration/examples/rust.md) | [Rust README](../rust/README.md) | [API Reference](reference/api-reference.md#rust-api)
+
+**Java**: [Java Examples](integration/examples/java.md) | [Java README](../java/README.md) | [API Reference](reference/api-reference.md#java-api)
+
+**Multi-Language**: [Architecture](technical/architecture.md) | [Integration Guide](integration/ditto-sdk.md) | [Schema Reference](reference/schema.md)
+
+## 📋 Documentation Status
+
+| Document | Last Updated | Status | Cross-Links |
+|----------|-------------|--------|-------------|
+| Architecture | Phase 2 | ✅ Complete | ✅ Linked |
+| CRDT Optimization | Phase 2 | ✅ Complete | ✅ Linked |
+| Performance | Phase 2 | ✅ Complete | ✅ Linked |
+| Getting Started | Phase 2 | ✅ Complete | ✅ Linked |
+| Building | Phase 2 | ✅ Complete | ✅ Linked |
+| Testing | Phase 2 | ✅ Complete | ✅ Linked |
+| Ditto SDK Integration | Phase 3 | ✅ Complete | ✅ Linked |
+| Rust Examples | Phase 3 | ✅ Complete | ✅ Linked |
+| Java Examples | Phase 3 | ✅ Complete | ✅ Linked |
+| API Reference | Phase 3 | ✅ Complete | ✅ Linked |
+| Schema Reference | Phase 3 | ✅ Complete | ✅ Linked |
+| Troubleshooting | Phase 3 | ✅ Complete | ✅ Linked |
+| Migration Guide | Phase 3 | ✅ Complete | ✅ Linked |
+
+---
+
+**Last Updated**: Phase 4 - Cross-Reference System Implementation  
+**Total Documents**: 13  
+**Cross-Links Added**: 100%  
+**Navigation Aids**: Complete
+
+For the most up-to-date documentation, always refer to the main [README](../README.md).