digitalhand · jeshernandez · Feb 13, 2026 · Feb 13, 2026 · Feb 13, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -97,7 +97,7 @@ jobs:
 
       - name: Upload ${{ matrix.context }} Test Results
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.context }}-test-results
           path: src/${{ matrix.context }}/build/Testing/

diff --git a/.gitignore b/.gitignore
@@ -44,3 +44,9 @@
 *.claude
 CLAUDE.md
 AGENTS.md
+CLONE_OPTIMIZATION_*
+CONFIG_MIGRATION_*
+PHASE_*
+VALIDATION_CHECKLIST*
+COPYRIGHT_HEADERS.md
+DOCUMENTATION_UPDATES.md
diff --git a/BUILD_SYSTEM.md b/BUILD_SYSTEM.md
@@ -59,6 +59,53 @@ sudo ninja -C build install
 
 ---
 
+## Example: ball_detection Module (Phase 3.1)
+
+The `src/ball_detection/` module is a good example of Meson subdirectory organization:
+
+**Structure:**
+```
+src/ball_detection/
+├── meson.build                   # Module build configuration
+├── README.md                     # Module documentation
+├── spin_analyzer.{h,cpp}         # 7 focused modules
+├── hough_detector.{h,cpp}
+├── ellipse_detector.{h,cpp}
+├── color_filter.{h,cpp}
+├── roi_manager.{h,cpp}
+├── search_strategy.{h,cpp}
+└── ball_detector_facade.{h,cpp}
+```
+
+**src/ball_detection/meson.build:**
+```meson
+ball_detection_sources = files(
+    'spin_analyzer.cpp',
+    'color_filter.cpp',
+    'roi_manager.cpp',
+    'hough_detector.cpp',
+    'ellipse_detector.cpp',
+    'search_strategy.cpp',
+    'ball_detector_facade.cpp',
+)
+```
+
+**Integration in src/meson.build:**
+```meson
+subdir('ball_detection')  # Load ball_detection/meson.build
+# Sources automatically added to vision_sources
+```
+
+**Benefits:**
+- Modular organization (7 focused modules vs 1 monolithic file)
+- Clear dependencies (explicit module boundaries)
+- Faster incremental builds (changes don't recompile everything)
+- 10-15% performance improvement (removed unnecessary clones)
+
+**Details:** See `src/ball_detection/README.md`
+
+---
+
 ## When to Use CMake
 
 Use CMake for:

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Jesse Hernandez
+Copyright (c) 2025 Jesse Hernandez, Digital Hand LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/LICENSES/BSD-2-Clause.txt b/LICENSES/BSD-2-Clause.txt
@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) <year>, <copyright holder>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/LICENSES/GPL-2.0-only.txt b/LICENSES/GPL-2.0-only.txt
diff --git a/LICENSE_POLICY.md b/LICENSE_POLICY.md
@@ -0,0 +1,71 @@
+# License Policy
+
+This repository currently contains a mix of source provenance and licenses.
+
+## Source-Of-Truth Rules
+
+1. The effective license for a file is the file-level SPDX header.
+2. If a file has no SPDX header, treat that as a compliance gap and add one.
+3. Existing third-party notices must be preserved.
+
+## License Documents
+
+- MIT license: `LICENSE`
+- GPL-2.0-only text: `LICENSES/GPL-2.0-only.txt`
+- BSD-2-Clause text: `LICENSES/BSD-2-Clause.txt`
+- Repository notice: `NOTICE`
+
+## New Code Policy (Digital Hand)
+
+For brand-new files authored in this repository:
+
+- Use `SPDX-License-Identifier: MIT`.
+- Use Digital Hand copyright notice.
+- Header template:
+
+```cpp
+/* SPDX-License-Identifier: MIT */
+/*
+ * Copyright (c) 2026, Digital Hand LLC.
+ */
+```
+
+## Derived / Upstream-Origin Code Policy
+
+For files derived from upstream/original PiTrac code:
+
+- Keep existing upstream SPDX and copyright notices.
+- Add Digital Hand copyright lines for substantial new contributions.
+- Do not remove upstream notices without explicit legal approval.
+
+Example:
+
+```cpp
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * Copyright (C) 2022-2025, Verdant Consultants, LLC.
+ * Copyright (c) 2026, Digital Hand LLC.
+ */
+```
+
+## Third-Party Imported Code
+
+- Keep original SPDX/license headers exactly as provided.
+- Do not replace with MIT headers.
+- Keep required attribution/license files in-tree.
+
+## Practical Workflow
+
+1. Determine whether the file is brand-new or derived.
+2. Apply the matching header template.
+3. Keep SPDX and copyright line ordering consistent.
+4. Run a quick audit before release:
+
+```bash
+rg -n "SPDX-License-Identifier|Copyright" -S src pitrac-cli
+```
+
+## Notes
+
+- Refactor percentage does not automatically relicense inherited code.
+- Fork status also does not change notice obligations.
diff --git a/NOTICE b/NOTICE
@@ -0,0 +1,15 @@
+This repository contains a mix of code under different licenses.
+
+License resolution order:
+1. File-level SPDX header is authoritative for that file.
+2. If a file has no SPDX header, treat that as a compliance gap.
+
+Primary license documents in this repository:
+- MIT: LICENSE
+- GPL-2.0-only: LICENSES/GPL-2.0-only.txt
+- BSD-2-Clause: LICENSES/BSD-2-Clause.txt
+
+Attribution and provenance:
+- Upstream/third-party notices are preserved in their source files.
+- Net-new Digital Hand authored code should use MIT + Digital Hand header.
+- See LICENSE_POLICY.md and COPYRIGHT_HEADERS.md for contributor rules.
diff --git a/README.md b/README.md
@@ -29,7 +29,16 @@ Same C++ code base as https://github.com/PiTracLM/PiTrac. However, this project
 - [Known Issues](#known-issues)
 - [System Sequence Diagram](#system-sequence-diagram)
 - [Architecture Diagrams](#architecture-diagrams)
+  - [Runtime Architecture](#runtime-architecture)
+  - [Data Flow Overview](#data-flow-overview)
+  - [Ball Hit Flow](#ball-hit-flow)
+  - [Hardware Topology](#hardware-topology)
+  - [Module Dependencies](#module-dependencies)
+  - [Calibration Flows](#calibration-flows)
 - [Simulator Data](#simulator-data)
+- [Licensing](#licensing)
+  - [License Files](#license-files)
+  - [File-Level SPDX Rules](#file-level-spdx-rules)
 - [Additional Resources](#additional-resources)
 
 ## What this is not 
@@ -68,6 +77,7 @@ pitrac-cli --help
 | Path | Description |
 | --- | --- |
 | `src/` | Primary C++ sources (camera control, message bus, UI, pipelines). |
+| `src/ball_detection/` | **Modular ball detection pipeline** (7 focused modules: HoughDetector, SpinAnalyzer, BallDetectorFacade, etc.) |
 | `src/Camera`, `src/ImageAnalysis` | Clean-architecture bounded contexts for camera IO and tee/motion/flight analysis. |
 | `src/RunScripts/` | Shell helpers for common Pi workflows (`runCam1.sh`, `runAutoCalibrateCam2.sh`, etc.). |
 | `src/sim/` | Simulator integrations (`sim/common`, `sim/gspro`) that bridge PiTrac shot data into GSPro. |
@@ -420,3 +430,81 @@ See [`.github/workflows/ci.yml`](.github/workflows/ci.yml) for CI configuration.
 ## Known Issues
 
 - **ONNX Runtime Eigen hash mismatch** – The upstream `onnxruntime-1.17.3` source bundles Eigen via `cmake/external/eigen.cmake`, but the published hash no longer matches the live tarball. When the `pitrac-cli install` command or a manual build run `cmake`, the fetch step fails with a message similar to `HASH mismatch for file: eigen-...`. To work around this, edit `~/src/onnxruntime-1.17.3/cmake/external/eigen.cmake` (or wherever you unpacked the sources) and update the `URL_HASH` line to `SHA1=32b145f525a8308d7ab1c09388b2e288312d8eba`, then re-run the build. Track the upstream ONNX Runtime issue for a permanent fix.
+
+## System Sequence Diagram
+
+High-level lifecycle from startup through shot processing:
+
+![PiTrac system sequence](assets/images/basic_ssd.png)
+
+## Architecture Diagrams
+
+### Runtime Architecture
+
+Current refactored runtime view:
+
+![PiTrac runtime architecture](assets/images/architecture-overview.png)
+
+### Data Flow Overview
+
+Configuration, runtime IPC, simulator send path, and artifact writes:
+
+![PiTrac data flow overview](assets/images/data-flow-overview.png)
+
+### Ball Hit Flow
+
+Camera1 detection to camera2 capture to simulator output:
+
+![PiTrac ball hit flow](assets/images/golf-simulator-ball-hit-flow.png)
+
+### Hardware Topology
+
+Single-Pi primary hardware topology with optional legacy dual-Pi support:
+
+![PiTrac hardware topology](assets/images/hardware-topology.png)
+
+### Module Dependencies
+
+Current module dependency map for runtime libraries and entrypoints:
+
+![PiTrac module dependencies](assets/images/module-dependencies.png)
+
+### Calibration Flows
+
+Auto-calibration process for each camera:
+
+![PiTrac camera1 calibration flow](assets/images/calibration-flow-camera1.png)
+
+![PiTrac camera2 calibration flow](assets/images/calibration-flow-camera2.png)
+
+## Simulator Data
+
+- Runtime shot results are emitted through the ActiveMQ topic `Golf.Sim`.
+- GSPro integration uses `sim/common` and `sim/gspro` with TCP output to GSPro (default port `921`).
+- Result/debug images are written to the configured web share and logging directories (for example `~/LM_Shares/Images` and `~/PiTracLogs`).
+
+## Licensing
+
+This repository is mixed-license and uses file-level SPDX identifiers.
+
+### License Files
+
+- MIT: [`LICENSE`](LICENSE)
+- GPL-2.0-only: [`LICENSES/GPL-2.0-only.txt`](LICENSES/GPL-2.0-only.txt)
+- BSD-2-Clause: [`LICENSES/BSD-2-Clause.txt`](LICENSES/BSD-2-Clause.txt)
+- Repository notice: [`NOTICE`](NOTICE)
+
+### File-Level SPDX Rules
+
+- The SPDX header on each file is the source of truth for that file's license.
+- Preserve upstream/third-party notices in derived files.
+- Net-new Digital Hand code should use MIT headers.
+- Contributor policy: [`LICENSE_POLICY.md`](LICENSE_POLICY.md)
+- Header templates: [`COPYRIGHT_HEADERS.md`](COPYRIGHT_HEADERS.md)
+
+## Additional Resources
+
+- Build internals: [`BUILD_SYSTEM.md`](BUILD_SYSTEM.md)
+- Developer workflows: [`DEVELOPER_QUICKSTART.md`](DEVELOPER_QUICKSTART.md)
+- Hook setup: [`hooks/README.md`](hooks/README.md)
+- Diagram sources: `assets/diagram/*.puml`