docs: update docs and refine core API

Signed-off-by: arounamounchili <patouossa.mounchili@gmail.com>

Author: arounamounchili

ARCHITECTURE.md

@@ -33,9 +33,11 @@ The platform-independent heart of the project. **Strictly Zero-Dependency.**
 graph TB
     subgraph "Core Layer"
         Models[Data Models<br/>Robot/Link/Joint]
+        Composer[Composer API<br/>RobotBuilder/Assembly]
         Physics[Physics Engine<br/>Inertia/Validation]
         IO[Parsers & Generators<br/>URDF/XACRO/SRDF]
     end
+    Composer --> Models
     IO --> Models
     Physics --> Models
 ```
@@ -83,5 +85,5 @@ sequenceDiagram
 
 ---
 
-**Last Updated:** 2026-04-15
-**Version:** 1.3.0
+**Last Updated:** 2026-05-13
+**Version:** 1.4.0

README.md

@@ -118,7 +118,6 @@ If you want to contribute to LinkForge or use the latest source code:
 
 Complete examples in `examples/` directory:
 
-- `roundtrip_test_robot.urdf`: A comprehensive robot containing ALL 6 URDF joint types (fixed, revolute, continuous, prismatic, planar, floating), plus sensors. Perfect for testing full roundtrip capabilities.
 - `mobile_robot.urdf`: A simple mobile robot base.
 - `diff_drive_robot.urdf`: A differential drive robot with wheels.
 - `quadruped_robot.urdf`: A 4-legged robot demonstrating complex kinematic chains and multi-link assemblies.
@@ -136,7 +135,6 @@ Complete examples in `examples/` directory:
 ### Setup
 ```bash
 # 1. Install 'just' command runner (see Contributing Guide for OS-specific instructions)
-# 1. Install 'just' command runner
 # 2. Clone repository
 git clone https://github.com/arounamounchili/linkforge.git
 cd linkforge
@@ -157,15 +155,14 @@ For complete instructions on testing, linting, and building, see our [Contributi
 
 ## 🗺️ Roadmap
 
-
 ### Phase 0: The Foundation (Completed)
 - [x] **v1.0.0**: Core URDF/XACRO Export, Sensors, & `ros2_control` basics.
 - [x] **v1.1.0**: Enhanced Documentation, Workflow Polish, & Bug Fixes.
 - [x] **v1.2.0**: Architectural Stability (Hexagonal Core).
 
 ### Phase 1: The Professional Bridge (Current)
 - [x] **v1.3.0**: Performance & Control (NumPy Acceleration, Depsgraph, & ROS2 Control).
-- [/] **v1.4.0**: Modular Synthesis (Composer API, Namespaced Merging, & SRDF Generation).
+- [x] **v1.4.0**: Modular Synthesis (Composer API, Namespaced Merging, & SRDF Generation).
 - [ ] **v1.5.0**: Visual SRDF Editor in Blender & Semantic Assistant.
 - [ ] **v1.6.0**: LinkForge CLI & GitHub Actions for automated validation.
 

core/README.md

@@ -15,16 +15,16 @@ It provides robust, dependency-minimized parsing and generation of robot descrip
   - `physics/`: Math and kinematics utilities for inertia and joint dynamics.
   - `validation/`: Robust schema validation for robot data.
   - `utils/`: Common helpers and mathematical operations.
-  - `base.py`, `exceptions.py`, `logging_config.py`: Core interfaces, error handling, and logging.
+  - `base.py`, `constants.py`, `exceptions.py`, `logging_config.py`: Core interfaces, shared constants, error handling, and logging.
 
 ## Development
 
 The core library is built and managed using [`uv`](https://docs.astral.sh/uv/).
 
 ```bash
 # Install dependencies
-uv sync
+just install
 
 # Run core tests (execute from the project root directory)
-uv run pytest tests/unit/core
+just test-core
 ```

core/src/linkforge_core/__init__.py

@@ -14,7 +14,8 @@
 
 __version__ = "1.3.0"  # x-release-please-version
 
-from . import generators, models, parsers, physics
+from . import composer, generators, models, parsers, physics, validation
+from .composer import RobotBuilder
 from .exceptions import (
     LinkForgeError,
     RobotGeneratorError,
@@ -24,11 +25,16 @@
 )
 from .generators import URDFGenerator, XACROGenerator
 from .utils.math_utils import format_float, format_vector
+from .validation import RobotValidator
 
 __all__ = [
     "models",
     "physics",
     "parsers",
+    "composer",
+    "validation",
+    "RobotBuilder",
+    "RobotValidator",
     "URDFGenerator",
     "XACROGenerator",
     "format_float",

docs/source/index.md

@@ -26,6 +26,8 @@ LinkForge streamlines robotics modeling with the following capabilities:
 - **ROS2 Control Support**: Automatic hardware interface configuration.
 - **Complete Sensor Suite**: Integrated support for LiDAR, IMU, Depth Cameras, and more.
 - **Automatic Physics**: Scientific mass properties and inertia tensor calculation.
+- **Modular Robot Assembly**: Build and merge robots programmatically with the **Composer API** (v1.4.0).
+- **SRDF Generation**: Automatic creation of semantic metadata for complex systems (v1.4.0).
 
 ---
 

docs/source/reference/api/index.md

@@ -50,7 +50,7 @@ The `RobotBuilder` Composer is the recommended way to build robots in Python.
 It handles validation, prefixing, and SRDF generation automatically.
 
 ```python
-from linkforge_core.composer import RobotBuilder
+from linkforge_core import RobotBuilder
 from linkforge_core.models import Robot
 from linkforge_core.models.geometry import Vector3
 from linkforge_core.models.joint import JointLimits
@@ -106,7 +106,7 @@ inertia = calculate_cylinder_inertia(cylinder, mass=5.0)
 ### Validation
 
 ```python
-from linkforge_core.validation.validator import RobotValidator
+from linkforge_core import RobotValidator
 
 # Validate robot
 validator = RobotValidator()

platforms/blender/README.md

@@ -5,34 +5,28 @@ This package integrates the LinkForge core logic directly into Blender's UI and
 
 ## Structure
 
-- `linkforge/`: The Blender extension source code containing panels, operators, and property groups.
-  - `blender/`: The main Blender integration module.
-    - `adapters/`: Bridges between Blender objects and `linkforge_core` models.
-    - `handlers/`: Scene post-load and object update handlers.
-    - `logic/`: High-level operations bridging core models and the viewport.
-    - `operators/`: Blender Operators for importing, exporting, and managing robot data.
-    - `panels/`: Blender UI layouts and side panels.
-    - `properties/`: Blender Property Groups binding LinkForge data to Blender objects.
-    - `visualization/`: Interactive 3D view elements for limits, joints, and inertia.
-    - `utils/`: Blender-specific helper functions.
-    - `preferences.py`: Extension configuration and settings.
-  - `linkforge_core/`: Internal reference to the core library (symlinked for standalone use).
-- `scripts/`: Development scripts and utilities.
-- `wheels/`: Pre-built wheels for bundled Python dependencies.
-- `blender_manifest.toml`: The extension metadata for Blender 4.2+.
+- `linkforge/`: The primary extension package.
+  - `blender/`: Main integration logic (adapters, handlers, logic, operators, panels, etc.).
+  - `blender_manifest.toml`: Extension metadata for Blender 4.2+.
+- `scripts/`: Build and development utilities (e.g., `build.py`).
+- `wheels/`: Platform-specific Python dependencies (bundled in the final `.zip`).
+- `pyproject.toml`: Local development configuration.
+
+> [!NOTE]
+> The **LinkForge Core** library is located at the project root (`/core`) and is automatically bundled into this extension during the build process.
 
 ## Development
 
 To work on the Blender extension, make sure `uv` is installed, then sync the dependencies:
 
 ```bash
-uv sync
+just install
 ```
 
 ### Running Tests
 
 To run Blender-specific integration and unit tests, from the project root use:
 
 ```bash
-python blender_launcher.py
+just test-blender
 ```

tests/README.md

@@ -8,29 +8,49 @@ The test suite separates pure logic from platform-specific behavior:
 
 ### 1. `unit/`
 Isolated tests for individual components avoiding external dependencies.
-- **`unit/core/`**: Tests for robot models, parsers, and physics utilities. Runs in standard Python.
-- **`unit/platforms/blender/`**: Tests for Blender utilities (scene helpers, visualization, operators). Requires a Blender runtime.
+- **`unit/core/`**: Tests for robot models, parsers, and physics utilities.
+- **`unit/platforms/blender/`**: Tests for Blender utilities (scene helpers, visualization).
 
 ### 2. `integration/`
 End-to-end tests verifying the interaction between multiple components.
-- **`integration/core/`**: Verifies complex URDF parsing, Xacro expansion scenarios, and validation features like Inertia calculations.
-- **`integration/platforms/blender/`**: Verifies the complete roundtrip process (Import → Scene Setup → Export).
+- **`integration/core/`**: Verifies complex URDF/SRDF parsing and validation.
+- **`integration/platforms/blender/`**: Verifies the complete roundtrip process.
+
+### 3. Infrastructure
+- `blender_launcher.py` (Root): CLI tool to run tests inside a Blender environment.
+- `mock_bpy_env.py`: Comprehensive mock of the Blender API for fast logic testing.
+- `conftest.py`, `core_test_utils.py`, `blender_test_utils.py`: Shared fixtures and assertions.
 
 ## How to Run Tests
 
 ### Standard Python Tests
 To run core unit tests and core integration tests:
 ```bash
-pytest tests/unit/core tests/integration/core
+just test-core
 ```
 
 ### Blender-Dependent Tests
-To run tests that require the Blender Python API (`bpy`), use the launcher from the project root:
+#### A. Fast Logic Testing (No Blender Required)
+Tests the Blender integration logic using a comprehensive mock environment. This is very fast and runs in standard Python.
+```bash
+just test-blender-logic
+```
+
+#### B. Full Integration Testing (Requires Real Blender)
+Runs tests inside a real Blender instance to verify UI, visualization, and roundtrip fidelity.
 ```bash
-python blender_launcher.py
+just test-blender
 ```
 *Note: Ensure your `BLENDER_PATH` environment variable is set or Blender is installed at its default location.*
 
+## 📊 Test Coverage
+
+To run the entire suite and generate a combined coverage report (HTML):
+```bash
+just coverage
+```
+The report will be available at `htmlcov/index.html`.
+
 ## Best Practices for Contributors
 
 1. **Use Fixtures**: Place shared test resources (mock robots, custom builders) in `tests/conftest.py`. Prefer self-contained tests (inline strings or programmatic construction) over external file dependencies.