docs: Comprehensive documentation update with detailed docstrings

Major improvements:
1. **README.md**:
   - Clarified Thread Safety section with detailed explanations
   - Distinguished between read and write operations
   - Added concrete examples of thread-safe usage patterns
   - Explained when external synchronization is needed

2. **src/python_prtree/core.py**:
   - Added comprehensive docstrings to all classes and methods
   - Included detailed Args, Returns, Raises, Examples sections
   - Added performance complexity analysis
   - Documented thread safety for each method
   - Added See Also cross-references
   - Explained precision selection behavior
   - Provided extensive usage examples for each method

3. **docs/README.md** (new):
   - Created documentation directory guide
   - Explained purpose of each subdirectory
   - Added navigation guide for users and developers

Documentation now follows NumPy/Google docstring style with:
- Complete parameter descriptions with types
- Return value specifications
- Exception documentation
- Performance characteristics
- Thread safety notes
- Practical examples for all methods
- Cross-references between related methods

All README examples verified to work correctly with implementation.

Author: claude

README.md

@@ -193,9 +193,33 @@ providing true native precision at each level for better performance and accurac
 
 ### Thread Safety
 
-- Query operations are thread-safe
-- Insert/erase operations are NOT thread-safe
-- Use external synchronization for concurrent updates
+**Read Operations (Thread-Safe):**
+- `query()` and `batch_query()` are thread-safe when used concurrently from multiple threads
+- Multiple threads can safely perform read operations simultaneously
+- No external synchronization needed for concurrent queries
+
+**Write Operations (Require Synchronization):**
+- `insert()`, `erase()`, and `rebuild()` modify the tree structure
+- These operations use internal mutex locks for atomicity
+- **Important**: Do NOT perform write operations concurrently with read operations
+- Use external synchronization (locks) to prevent concurrent reads and writes
+
+**Recommended Pattern:**
+```python
+import threading
+
+tree = PRTree2D([1, 2], [[0, 0, 1, 1], [2, 2, 3, 3]])
+lock = threading.Lock()
+
+# Multiple threads can query safely without locks
+def query_worker():
+    result = tree.query([0.5, 0.5, 1.5, 1.5])  # Safe without lock
+
+# Write operations need external synchronization
+def insert_worker(idx, box):
+    with lock:  # Protect against concurrent reads/writes
+        tree.insert(idx, box)
+```
 
 ## Installation from Source
 

docs/README.md

@@ -0,0 +1,64 @@
+# Documentation Directory
+
+This directory contains comprehensive documentation for python_prtree developers and contributors.
+
+## Contents
+
+### Core Documentation
+
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Project architecture and design decisions
+  - Directory structure and separation of concerns
+  - Data flow diagrams
+  - Build system overview
+  - Native precision support architecture
+
+- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Development environment setup
+  - Prerequisites and installation
+  - Build instructions
+  - Testing and code quality tools
+  - Troubleshooting guide
+
+- **[MIGRATION.md](MIGRATION.md)** - Migration guides between versions
+  - v0.7.0 project restructuring guide
+  - Breaking changes and migration steps
+  - Planned future migrations
+
+### Supplementary Resources
+
+- **baseline/** - Performance baseline measurements
+  - System information
+  - Benchmark results and analysis
+  - Used for regression testing and performance comparison
+
+- **examples/** - Example notebooks and scripts
+  - Experimental notebooks for exploring the API
+  - Usage demonstrations
+  - Prototyping and development examples
+
+- **images/** - Documentation images
+  - Benchmark graphs used in README
+  - Performance comparison charts
+  - Referenced by main documentation
+
+## For Users
+
+If you're a user looking for usage documentation, see:
+- [README.md](../README.md) - Main user documentation with examples
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - How to contribute to the project
+- [CHANGES.md](../CHANGES.md) - Version history and changelog
+
+## For Developers
+
+Start with these files in order:
+1. [README.md](../README.md) - Understand what the library does
+2. [DEVELOPMENT.md](DEVELOPMENT.md) - Set up your development environment
+3. [ARCHITECTURE.md](ARCHITECTURE.md) - Understand the codebase structure
+4. [CONTRIBUTING.md](../CONTRIBUTING.md) - Learn the contribution workflow
+
+## Keeping Documentation Updated
+
+When making changes:
+- Update ARCHITECTURE.md if you change the project structure
+- Update DEVELOPMENT.md if you change build/test processes
+- Update MIGRATION.md when introducing breaking changes
+- Regenerate benchmarks if performance characteristics change