kinemotion 0.9.0__tar.gz → 0.10.1__tar.gz

{kinemotion-0.9.0 → kinemotion-0.10.1}/.gitignore

@@ -42,9 +42,12 @@ env/
 htmlcov/
 
 # Output files
+*.mov
+*.MOV
 *.mp4
 *.avi
 *.json
+*.csv
 !pyproject.toml
 
 # Logs

{kinemotion-0.9.0 → kinemotion-0.10.1}/.pre-commit-config.yaml

@@ -25,10 +25,24 @@ repos:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.18.2
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.407
     hooks:
-      - id: mypy
-        args: [--ignore-missing-imports, --no-strict-optional]
+      - id: pyright
         files: ^src/
-        exclude: ^(tests/|examples/)
+        # Pyright reads configuration from pyproject.toml automatically
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.17
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-gfm>=0.3.5  # GitHub Flavored Markdown
+          - mdformat-tables  # Table formatting
+        exclude: ^CLAUDE\.md$
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.3.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]

{kinemotion-0.9.0 → kinemotion-0.10.1}/.tool-versions

@@ -1,2 +1,2 @@
-uv 0.8.17
+uv 0.9.7
 python 3.12.7

{kinemotion-0.9.0 → kinemotion-0.10.1}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.10.1 (2025-11-03)
+
+### Bug Fixes
+
+- Resolve SonarCloud code quality issues
+  ([`73f7784`](https://github.com/feniix/kinemotion/commit/73f778491bc01bfed973421fe5261364f8540147))
+
+### Build System
+
+- Add style checker for commit messages
+  ([`d25669b`](https://github.com/feniix/kinemotion/commit/d25669bdf17810a38a86fbd9b03e208ea14f5326))
+
+- Migrate from mypy to pyright for type checking
+  ([`521b526`](https://github.com/feniix/kinemotion/commit/521b52619553bb5b3ee61e0db4ff6fd06744ac7a))
+
+### Documentation
+
+- Install precommit hook for improving markdown
+  ([`546164b`](https://github.com/feniix/kinemotion/commit/546164b9f68cf3222da9753fdd2f2cd272ead90f))
+
+- Update documentation for batch processing and Python API
+  ([`f0fa8b6`](https://github.com/feniix/kinemotion/commit/f0fa8b69b927ff4a2e7f15bac242374592fe0eb9))
+
+
+## v0.10.0 (2025-11-02)
+
+### Features
+
+- Add batch processing mode to CLI
+  ([`b0ab3c6`](https://github.com/feniix/kinemotion/commit/b0ab3c6b37a013402ff7a89305a68e49549eeae3))
+
 ## v0.9.0 (2025-11-02)
 
 ### Features
@@ -14,7 +45,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add programmatic API for bulk video processing
   ([`213de56`](https://github.com/feniix/kinemotion/commit/213de564fda96b461807dbefa2795e037a5edc94))
 
-
 ## v0.8.3 (2025-11-02)
 
 ### Bug Fixes
@@ -27,7 +57,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update repository metadata for GHCR package description
   ([`4779355`](https://github.com/feniix/kinemotion/commit/4779355901a407514d83cf2aa82f55fa083e7e63))
 
-
 ## v0.8.2 (2025-11-02)
 
 ### Bug Fixes
@@ -35,7 +64,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add OCI annotations to Docker manifest for GHCR metadata
   ([`c6e2295`](https://github.com/feniix/kinemotion/commit/c6e2295dd5eb3eae6b820d3dc7a84d730772de41))
 
-
 ## v0.8.1 (2025-11-02)
 
 ### Bug Fixes
@@ -43,7 +71,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add OCI-compliant labels to Docker image
   ([`6b18b33`](https://github.com/feniix/kinemotion/commit/6b18b33538615048c8ea572c4ebc402160ee1c5e))
 
-
 ## v0.8.0 (2025-11-02)
 
 ### Features
@@ -51,7 +78,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add Docker support and GitHub Container Registry publishing
   ([`249ca4c`](https://github.com/feniix/kinemotion/commit/249ca4c0c0ab40cda5acfebac012db8075b9694f))
 
-
 ## v0.7.1 (2025-11-01)
 
 ### Bug Fixes
@@ -59,7 +85,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update documentation for auto-tuning system
   ([`6c1a135`](https://github.com/feniix/kinemotion/commit/6c1a135acf5cce7a627644dbc6393460277906ad))
 
-
 ## v0.7.0 (2025-11-01)
 
 ### Features
@@ -67,7 +92,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add intelligent auto-tuning and video rotation handling
   ([`7b35f67`](https://github.com/feniix/kinemotion/commit/7b35f6790dd8b6714f3e42389555107a043d486c))
 
-
 ## v0.6.4 (2025-10-26)
 
 ### Bug Fixes
@@ -75,7 +99,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Project urls
   ([`c7b5914`](https://github.com/feniix/kinemotion/commit/c7b5914d3516e0f59dcf88ac81f99ffe94edb706))
 
-
 ## v0.6.3 (2025-10-26)
 
 ### Bug Fixes
@@ -83,7 +106,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changelog markdown
   ([`976de66`](https://github.com/feniix/kinemotion/commit/976de66b2a964b83240a559ea097cb74f5e1a537))
 
-
 ## v0.6.2 (2025-10-26)
 
 ### Bug Fixes
@@ -91,7 +113,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add semantic-release insertion flag to CHANGELOG.md
   ([`93f3a28`](https://github.com/feniix/kinemotion/commit/93f3a28c750bdb70b2a57f9b0c1910b105753980))
 
-## [Unreleased]
+## \[Unreleased\]
 
 ### Added
 
@@ -117,7 +139,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Your security fix here.
 
-## [0.5.0] - 2025-10-26
+## \[0.5.0\] - 2025-10-26
 
 ### Added
 

{kinemotion-0.9.0 → kinemotion-0.10.1}/CLAUDE.md

@@ -30,7 +30,7 @@ Managed with `uv` and `asdf`:
 - pytest: Testing framework
 - black: Code formatting
 - ruff: Fast Python linter
-- mypy: Static type checking
+- pyright: Static type checking
 
 ### Development Commands
 
@@ -41,8 +41,8 @@ Managed with `uv` and `asdf`:
 - **Format code**: `uv run black src/`
 - **Lint code**: `uv run ruff check`
 - **Auto-fix lint issues**: `uv run ruff check --fix`
-- **Type check**: `uv run mypy src/kinemotion`
-- **Run all checks**: `uv run ruff check && uv run mypy src/kinemotion && uv run pytest`
+- **Type check**: `uv run pyright`
+- **Run all checks**: `uv run ruff check && uv run pyright && uv run pytest`
 
 ## Architecture
 
@@ -50,29 +50,41 @@ Managed with `uv` and `asdf`:
 
 ```text
 src/kinemotion/
-├── __init__.py
+├── __init__.py                 # Public API exports
+├── api.py                      # Python library API (process_video, process_videos_bulk)
+├── py.typed                    # PEP 561 type marker
 ├── cli.py                      # Main CLI entry point (registers subcommands)
 ├── core/                       # Shared functionality across all jump types
 │   ├── __init__.py
 │   ├── pose.py                 # MediaPipe Pose integration + CoM
 │   ├── smoothing.py            # Savitzky-Golay landmark smoothing
 │   ├── filtering.py            # Outlier rejection + bilateral filtering
+│   ├── auto_tuning.py          # Intelligent parameter auto-tuning
 │   └── video_io.py             # Video processing (VideoProcessor class)
 └── dropjump/                   # Drop jump specific analysis
     ├── __init__.py
-    ├── cli.py                  # Drop jump CLI command (dropjump-analyze)
+    ├── cli.py                  # Drop jump CLI command (dropjump-analyze) + batch mode
     ├── analysis.py             # Ground contact state detection
     ├── kinematics.py           # Drop jump metrics calculations
     └── debug_overlay.py        # Debug video overlay rendering
 
 tests/
-├── test_adaptive_threshold.py  # Adaptive threshold tests
-├── test_aspect_ratio.py        # Aspect ratio preservation tests
-├── test_com_estimation.py      # Center of mass estimation tests
-├── test_contact_detection.py  # Contact detection unit tests
-├── test_filtering.py           # Advanced filtering tests
-├── test_kinematics.py          # Metrics calculation tests
-└── test_polyorder.py           # Polynomial order tests
+├── test_adaptive_threshold.py  # Adaptive threshold tests (10 tests)
+├── test_api.py                 # API module tests (14 tests)
+├── test_aspect_ratio.py        # Aspect ratio preservation tests (4 tests)
+├── test_com_estimation.py      # Center of mass estimation tests (6 tests)
+├── test_contact_detection.py   # Contact detection unit tests (3 tests)
+├── test_filtering.py           # Advanced filtering tests (17 tests)
+├── test_kinematics.py          # Metrics calculation tests (2 tests)
+└── test_polyorder.py           # Polynomial order tests (5 tests)
+                                # Total: 61 tests
+
+examples/
+├── bulk/                       # Bulk processing examples
+│   ├── README.md               # Comprehensive API documentation
+│   ├── bulk_processing.py      # Advanced bulk processing examples
+│   └── simple_example.py       # Quick start examples
+└── programmatic_usage.py       # Low-level API example
 
 docs/
 ├── PARAMETERS.md               # Comprehensive guide to all CLI parameters
@@ -91,10 +103,21 @@ docs/
 **CLI Architecture:**
 
 - `src/kinemotion/cli.py` (20 lines): Main CLI group + command registration
-- `src/kinemotion/dropjump/cli.py` (358 lines): Complete dropjump-analyze command
+- `src/kinemotion/dropjump/cli.py` (724 lines): Complete dropjump-analyze command with batch mode
+- `src/kinemotion/api.py` (428 lines): Python library API for programmatic usage
 - Commands registered using Click's `cli.add_command()` pattern
 - Modular design allows easy addition of new jump type analysis commands
 
+**API Architecture:**
+
+- `src/kinemotion/api.py`: Public API for library usage
+  - `process_video()`: Process single videos programmatically
+  - `process_videos_bulk()`: Parallel batch processing with ProcessPoolExecutor
+  - `VideoConfig`: Configuration dataclass for video processing
+  - `VideoResult`: Result dataclass with success/error handling
+- Fully typed with PEP 561 compliance (py.typed marker)
+- Used by both CLI batch mode and external library consumers
+
 ### Analysis Pipeline
 
 1. **Pose Tracking** (core/pose.py): MediaPipe extracts body landmarks from each frame
@@ -149,16 +172,17 @@ docs/
 
 The codebase enforces strict code quality standards using multiple tools:
 
-### Type Checking with mypy
+### Type Checking with pyright
 
 - **Strict mode enabled**: All functions require type annotations
-- Configuration in `pyproject.toml` under `[tool.mypy]`
+- Configuration in `pyproject.toml` under `[tool.pyright]`
 - Key settings:
-  - `disallow_untyped_defs`: All functions must have complete type annotations
-  - `disallow_incomplete_defs`: Partial type hints not allowed
-  - `warn_return_any`: Warns on Any return types
-  - Third-party stubs: Ignores missing imports for cv2, mediapipe, scipy
-- Run with: `uv run mypy src/kinemotion`
+  - `typeCheckingMode: "strict"`: Enables strict type checking (equivalent to mypy's disallow_untyped_defs and related flags)
+  - `pythonVersion: "3.10"`: Target Python version
+  - `include: ["src"]`: Only check source files, exclude tests and examples
+  - `reportMissingImports: "none"`: Ignore missing stubs for cv2, mediapipe, scipy
+  - Additional warnings for unused imports, variables, and functions
+- Run with: `uv run pyright`
 
 ### Linting with ruff
 
@@ -187,7 +211,7 @@ uv run black src/
 uv run ruff check --fix
 
 # Type check
-uv run mypy src/kinemotion
+uv run pyright
 
 # Run tests
 uv run pytest
@@ -196,7 +220,55 @@ uv run pytest
 Or run all checks at once:
 
 ```bash
-uv run ruff check && uv run mypy src/kinemotion && uv run pytest
+uv run ruff check && uv run pyright && uv run pytest
+```
+
+### Commit Message Format
+
+**IMPORTANT**: All commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+
+The commit message format is enforced by the `conventional-pre-commit` hook and is required for semantic versioning with `python-semantic-release`.
+
+**Format:**
+```
+<type>(<optional scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Allowed types** (from `pyproject.toml`):
+- `feat`: A new feature (triggers minor version bump)
+- `fix`: A bug fix (triggers patch version bump)
+- `perf`: Performance improvement (triggers patch version bump)
+- `docs`: Documentation only changes
+- `style`: Code style changes (formatting, whitespace)
+- `refactor`: Code refactoring (no functional changes)
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks, dependency updates
+- `build`: Build system or dependency changes
+- `ci`: CI/CD pipeline changes
+
+**Examples:**
+```bash
+feat: Add batch processing mode to CLI
+fix: Correct aspect ratio handling for portrait videos
+docs: Update README with auto-tuning examples
+refactor: Extract video rotation logic into separate method
+perf: Optimize pose tracking with caching
+test: Add tests for CoM estimation edge cases
+chore(release): 0.10.0 [skip ci]
+```
+
+**Breaking changes:**
+Use `!` after type/scope or add `BREAKING CHANGE:` in footer:
+```bash
+feat!: Change API signature for process_video
+# or
+feat: Change API signature for process_video
+
+BREAKING CHANGE: drop_height parameter is now required
 ```
 
 ## Critical Implementation Details
@@ -815,6 +887,109 @@ uv run kinemotion dropjump-analyze low_quality.mp4 --drop-height 0.40
 uv run kinemotion dropjump-analyze high_quality.mp4 --drop-height 0.40
 ```
 
+### Batch Processing (CLI)
+
+Process multiple videos in parallel from the command line:
+
+```bash
+# Batch mode with glob pattern
+uv run kinemotion dropjump-analyze videos/*.mp4 --batch --drop-height 0.40 --workers 4
+
+# Save all results to directories
+uv run kinemotion dropjump-analyze videos/*.mp4 --batch --drop-height 0.40 \
+  --json-output-dir results/ \
+  --output-dir debug_videos/ \
+  --csv-summary summary.csv
+
+# Multiple explicit paths (batch mode auto-enabled)
+uv run kinemotion dropjump-analyze video1.mp4 video2.mp4 video3.mp4 --drop-height 0.40
+```
+
+**Batch options:**
+- `--batch`: Explicitly enable batch mode
+- `--workers <int>`: Number of parallel workers (default: 4)
+- `--output-dir <path>`: Directory for debug videos (auto-named per video)
+- `--json-output-dir <path>`: Directory for JSON metrics (auto-named per video)
+- `--csv-summary <path>`: Export aggregated results to CSV
+
+## Using Kinemotion as a Library
+
+The kinemotion package provides a Python API for programmatic use in automated pipelines and custom analysis tools.
+
+### Quick Start (Python API)
+
+```python
+from kinemotion import process_video
+
+# Process a single video
+metrics = process_video(
+    video_path="athlete_jump.mp4",
+    drop_height=0.40,  # 40cm drop box
+    quality="balanced",
+    verbose=True
+)
+
+# Access results
+print(f"Jump height: {metrics.jump_height:.3f} m")
+print(f"Ground contact time: {metrics.ground_contact_time * 1000:.1f} ms")
+```
+
+### Bulk Processing (Python API)
+
+```python
+from kinemotion import VideoConfig, process_videos_bulk
+
+# Configure multiple videos
+configs = [
+    VideoConfig("video1.mp4", drop_height=0.40),
+    VideoConfig("video2.mp4", drop_height=0.30, quality="accurate"),
+    VideoConfig("video3.mp4", drop_height=0.50, output_video="debug3.mp4"),
+]
+
+# Process in parallel with 4 workers
+results = process_videos_bulk(configs, max_workers=4)
+
+# Check results
+for result in results:
+    if result.success:
+        print(f"✓ {result.video_path}: {result.metrics.jump_height:.3f} m")
+    else:
+        print(f"✗ {result.video_path}: {result.error}")
+```
+
+### API Documentation
+
+See `examples/bulk/README.md` for comprehensive API documentation including:
+- Complete API reference
+- Common use cases (directory processing, CSV export, custom parameters)
+- Integration examples (Pandas, custom CLI)
+- Performance tips
+- Error handling patterns
+
+**Key API Functions:**
+
+- `process_video(video_path, drop_height, **kwargs) -> DropJumpMetrics`
+  - Process a single video programmatically
+  - Returns metrics object with all analysis results
+  - Raises FileNotFoundError or ValueError on errors
+
+- `process_videos_bulk(configs, max_workers=4, progress_callback=None) -> list[VideoResult]`
+  - Process multiple videos in parallel using ProcessPoolExecutor
+  - Each VideoResult contains success status, metrics, or error
+  - Error isolation: one failure doesn't crash the batch
+
+- `VideoConfig(video_path, drop_height, quality="balanced", ...)`
+  - Configuration dataclass for video processing
+  - All CLI parameters available as attributes
+
+- `VideoResult(video_path, success, metrics=None, error=None, processing_time=0.0)`
+  - Result dataclass with structured success/error handling
+
+**Type Safety:**
+- Fully typed API with PEP 561 compliance (py.typed marker)
+- IDE autocomplete and type checking support
+- All public functions have complete type annotations
+
 ## MCP Server Configuration
 
 The repository includes MCP server configuration in `.mcp.json`:

{kinemotion-0.9.0 → kinemotion-0.10.1}/CODE_OF_CONDUCT.md

@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
+- Focusing on what is best not just for us as individuals, but for the overall
   community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or advances of
+- The use of sexualized language or imagery, and sexual attention or advances of
   any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
   without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -120,14 +120,14 @@ version 2.1, available at
 [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
 
 Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
 
 For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
 [https://www.contributor-covenant.org/translations][translations].
 
+[faq]: https://www.contributor-covenant.org/faq
 [homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
+[mozilla coc]: https://github.com/mozilla/diversity
 [translations]: https://www.contributor-covenant.org/translations
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

{kinemotion-0.9.0 → kinemotion-0.10.1}/CONTRIBUTING.md

@@ -37,12 +37,12 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 We actively welcome pull requests! Here's how to submit one:
 
 1. Fork the repository
-2. Create a new branch from `main` for your changes
-3. Make your changes following our coding standards
-4. Add or update tests as needed
-5. Ensure all tests pass and code quality checks succeed
-6. Update documentation if needed
-7. Submit a pull request
+1. Create a new branch from `main` for your changes
+1. Make your changes following our coding standards
+1. Add or update tests as needed
+1. Ensure all tests pass and code quality checks succeed
+1. Update documentation if needed
+1. Submit a pull request
 
 ## Development Setup
 
@@ -54,23 +54,27 @@ We actively welcome pull requests! Here's how to submit one:
 ### Installation Steps
 
 1. **Clone your fork**:
+
    ```bash
    git clone https://github.com/YOUR-USERNAME/kinemotion.git
    cd kinemotion
    ```
 
-2. **Install asdf plugins** (if not already installed):
+1. **Install asdf plugins** (if not already installed):
+
    ```bash
    asdf plugin add python
    asdf plugin add uv
    ```
 
-3. **Install versions specified in `.tool-versions`**:
+1. **Install versions specified in `.tool-versions`**:
+
    ```bash
    asdf install
    ```
 
-4. **Install project dependencies**:
+1. **Install project dependencies**:
+
    ```bash
    uv sync
    ```
@@ -98,6 +102,7 @@ uv run mypy src/kinemotion
 ```
 
 **Requirements**:
+
 - All functions must have type annotations for parameters and return values
 - No `Any` types without justification
 - No untyped definitions
@@ -184,6 +189,7 @@ def calculate_jump_height(flight_time_ms, gravity=9.81):
 - Update README.md if adding new features
 
 Example:
+
 ```python
 def detect_ground_contact(
     positions: np.ndarray,
@@ -216,6 +222,7 @@ def detect_ground_contact(
 - Include edge cases and error conditions
 
 Example:
+
 ```python
 def test_contact_detection_with_clean_landing():
     """Test contact detection with a clean landing (no bounces)."""
@@ -232,7 +239,7 @@ def test_contact_detection_with_clean_landing():
 
 ## Project Structure
 
-```
+```text
 src/kinemotion/
 ├── __init__.py
 ├── cli.py                    # Main CLI entry point
@@ -256,9 +263,9 @@ tests/
 ### Adding New Features
 
 1. **Core functionality** (reusable across jump types) → `core/`
-2. **Jump-specific logic** → appropriate module (e.g., `dropjump/`)
-3. **New jump type** → create new module alongside `dropjump/`
-4. **Tests** → corresponding test file in `tests/`
+1. **Jump-specific logic** → appropriate module (e.g., `dropjump/`)
+1. **New jump type** → create new module alongside `dropjump/`
+1. **Tests** → corresponding test file in `tests/`
 
 ## Commit Message Guidelines
 
@@ -270,7 +277,8 @@ Use clear, descriptive commit messages:
 - Reference issues and pull requests when relevant
 
 Examples:
-```
+
+```text
 Add trajectory curvature analysis for landing detection
 
 Fix sub-frame interpolation edge case at video boundaries
@@ -283,23 +291,27 @@ Refactor contact detection to use derivative-based velocity
 ## Review Process
 
 1. **Automated checks** run on all pull requests:
+
    - Type checking (mypy)
    - Linting (ruff)
    - Tests (pytest)
    - Code formatting (black)
 
-2. **Code review** by maintainers:
+1. **Code review** by maintainers:
+
    - Code quality and style
    - Test coverage
    - Documentation
    - Performance implications
 
-3. **Feedback and iteration**:
+1. **Feedback and iteration**:
+
    - Address review comments
    - Push updates to your branch
    - Checks re-run automatically
 
-4. **Merge**:
+1. **Merge**:
+
    - Once approved and all checks pass
    - Squash and merge into `main`