docs: Fix README and CONTRIBUTING inconsistencies with implementation

- Update README.md API Reference to match actual implementation
  - Add detailed parameter descriptions for all methods
  - Include missing getter methods for precision control
  - Fix insert() signature to show optional parameters
  - Add len() and n property documentation
  - Remove "(2D only)" from varargs query (works for 3D/4D too)
  - Add return type annotations for clarity

- Update CONTRIBUTING.md project structure
  - Update file paths to reflect current project layout
  - Change cpp/ to include/prtree/core/ and src/cpp/bindings/
  - Update Python wrapper path from __init__.py to core.py
  - Add pyproject.toml to project structure
  - Update test directory structure (unit/integration/e2e)

All examples verified to work correctly with current implementation.

Author: claude

CONTRIBUTING.md

@@ -103,9 +103,10 @@ make quick       # Quick test (clean + build + test)
    ```
 
 3. **Make changes**
-   - C++ code: `cpp/prtree.h`, `cpp/main.cc`
-   - Python wrapper: `src/python_prtree/__init__.py`
-   - Tests: `tests/test_PRTree.py`
+   - C++ core: `include/prtree/core/prtree.h`
+   - Python bindings: `src/cpp/bindings/python_bindings.cc`
+   - Python wrapper: `src/python_prtree/core.py`
+   - Tests: `tests/unit/`, `tests/integration/`, `tests/e2e/`
 
 4. **Build and test**
    ```bash
@@ -144,7 +145,7 @@ make quick       # Quick test (clean + build + test)
 
 3. **Implement feature**
    ```cpp
-   // cpp/prtree.h
+   // include/prtree/core/prtree.h
    // Add implementation
    ```
 
@@ -205,20 +206,30 @@ make test-coverage
 
 ```
 python_prtree/
-├── cpp/                    # C++ implementation
-│   ├── prtree.h           # PRTree core implementation
-│   ├── main.cc            # Python bindings
-│   ├── parallel.h         # Parallel processing utilities
-│   └── small_vector.h     # Optimized vector
-├── src/python_prtree/     # Python wrapper
-│   └── __init__.py
+├── include/               # C++ public headers
+│   └── prtree/
+│       ├── core/          # Core algorithm headers
+│       │   └── prtree.h   # PRTree core implementation
+│       └── utils/         # Utility headers
+│           ├── parallel.h # Parallel processing utilities
+│           └── small_vector.h # Optimized vector
+├── src/
+│   ├── cpp/               # C++ implementation
+│   │   └── bindings/      # Python bindings
+│   │       └── python_bindings.cc
+│   └── python_prtree/     # Python wrapper
+│       ├── __init__.py    # Package entry point
+│       └── core.py        # Main user-facing classes
 ├── tests/                 # Test suite
-│   └── test_PRTree.py
+│   ├── unit/              # Unit tests
+│   ├── integration/       # Integration tests
+│   └── e2e/               # End-to-end tests
 ├── third/                 # Third-party libraries (submodules)
 │   ├── pybind11/
 │   └── snappy/
 ├── CMakeLists.txt         # CMake configuration
-├── setup.py               # Packaging configuration
+├── pyproject.toml         # Project metadata and dependencies
+├── setup.py               # Build configuration
 ├── Makefile              # Development workflow
 └── README.md             # User documentation
 ```

README.md

@@ -67,7 +67,7 @@ tree4d = PRTree4D(indices, boxes_4d)  # 4D boxes
 ```python
 # Query with point coordinates
 result = tree.query([0.5, 0.5])        # Returns indices
-result = tree.query(0.5, 0.5)          # Varargs also supported (2D only)
+result = tree.query(0.5, 0.5)          # Varargs also supported
 ```
 
 ### Dynamic Updates
@@ -216,22 +216,93 @@ For detailed development setup, see [DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
 #### Constructor
 ```python
-PRTree2D(indices=None, boxes=None)
-PRTree2D(filename)  # Load from file
+PRTree2D()                             # Empty tree
+PRTree2D(indices, boxes)               # With data
+PRTree2D(filename)                     # Load from file
 ```
 
+**Parameters:**
+- `indices` (optional): Array of integer indices for each bounding box
+- `boxes` (optional): Array of bounding boxes (shape: [n, 2*D] where D is dimension)
+- `filename` (optional): Path to saved tree file
+
 #### Methods
-- `query(box, return_obj=False)` - Find overlapping boxes
-- `batch_query(boxes)` - Parallel batch queries
-- `query_intersections()` - Find all intersecting pairs
-- `insert(idx, bb, obj=None)` - Add box
-- `erase(idx)` - Remove box
-- `rebuild()` - Rebuild tree for optimal performance
-- `save(filename)` - Save to binary file
-- `load(filename)` - Load from binary file
-- `size()` - Get number of boxes
-- `get_obj(idx)` - Get stored object
-- `set_obj(idx, obj)` - Update stored object
+
+**Query Methods:**
+- `query(*args, return_obj=False)` → `List[int]` or `List[Any]`
+  - Find all bounding boxes that overlap with the query box or point
+  - Accepts box coordinates as list/array or varargs (e.g., `query(x, y)` for 2D points)
+  - Set `return_obj=True` to return associated objects instead of indices
+
+- `batch_query(boxes)` → `List[List[int]]`
+  - Parallel batch queries for multiple query boxes
+  - Returns a list of result lists, one per query
+
+- `query_intersections()` → `np.ndarray`
+  - Find all pairs of intersecting bounding boxes
+  - Returns array of shape (n_pairs, 2) containing index pairs
+
+**Modification Methods:**
+- `insert(idx=None, bb=None, obj=None)` → `None`
+  - Add a new bounding box to the tree
+  - `idx`: Index for the box (auto-assigned if None)
+  - `bb`: Bounding box coordinates (required)
+  - `obj`: Optional Python object to associate with the box
+
+- `erase(idx)` → `None`
+  - Remove a bounding box by index
+
+- `rebuild()` → `None`
+  - Rebuild tree for optimal performance after many updates
+
+**Persistence Methods:**
+- `save(filename)` → `None`
+  - Save tree to binary file
+
+- `load(filename)` → `None`
+  - Load tree from binary file
+
+**Object Storage Methods:**
+- `get_obj(idx)` → `Any`
+  - Retrieve the Python object associated with a bounding box
+
+- `set_obj(idx, obj)` → `None`
+  - Update the Python object associated with a bounding box
+
+**Size and Properties:**
+- `size()` → `int`
+  - Get the number of bounding boxes in the tree
+
+- `len(tree)` → `int`
+  - Same as `size()`, allows using `len(tree)`
+
+- `n` → `int` (property)
+  - Get the number of bounding boxes (same as `size()`)
+
+**Precision Control Methods:**
+- `set_adaptive_epsilon(enabled)` → `None`
+  - Enable/disable adaptive epsilon based on box sizes
+
+- `set_relative_epsilon(epsilon)` → `None`
+  - Set relative epsilon for intersection tests
+
+- `set_absolute_epsilon(epsilon)` → `None`
+  - Set absolute epsilon for near-zero cases
+
+- `set_subnormal_detection(enabled)` → `None`
+  - Enable/disable subnormal number detection
+
+- `get_adaptive_epsilon()` → `bool`
+  - Check if adaptive epsilon is enabled
+
+- `get_relative_epsilon()` → `float`
+  - Get current relative epsilon value
+
+- `get_absolute_epsilon()` → `float`
+  - Get current absolute epsilon value
+
+- `get_subnormal_detection()` → `bool`
+  - Check if subnormal detection is enabled
 
 ## Version History