diff --git a/README.md b/README.md
deleted file mode 100644
index 686beb25..00000000
--- a/README.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# BOS README
-***
-## What is Docker?
-###  What does it do? 
-Basically, Docker lets you package an application <br>
-into a container that can be distributed as images to <br>
-run on other platforms. For example, let's say you have <br>
-an application that works on your computer, but not on <br>
-the server you want to eventually run it on. Docker <br>
-solves that. It lets you package an application and <br>
-the environment it needs to run on into a bundle that <br>
-can then be run anywhere.
-
-## Docker commands you need to know
-### How to pull images using docker pull
-run `docker pull ghcr.io/frc971/bos/orin:latest`.
-
-This will pull a docker image for you to use on your computer.
-
-### How to run the container on your computer
-To run the docker container on your computer, <br>
-run the following commands in the terminal:
-```bash
-    docker run --privileged --network host --name orin -it ghcr.io/frc971/bos/orin:latest
-    docker exec -it orin /bin/bash
-```
-This will run the docker container on your computer within a <br>
-contained environment that simulates an ORIN.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..ac7b544c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,23 @@
+# BOS Documentation
+
+This folder contains project-level docs for the BOS codebase.
+
+## Contents
+
+- [Architecture Overview](architecture.md)
+- [Build and Run](build-and-run.md)
+- [Scripts Reference](scripts.md)
+- [Testing Guide](testing.md)
+
+## Quick Start
+
+```bash
+./scripts/build.sh
+```
+
+Primary executables are built from `src/`:
+
+- `main_bot_main`
+- `second_bot_main`
+- `unambiguous_first`
+- `unambiguous_second`
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..396ff3d4
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,89 @@
+# Architecture Overview
+
+## High-Level Flow
+
+The runtime system is built around a vision and localization pipeline:
+
+1. Camera modules capture frames.
+2. AprilTag detectors produce per-frame detections.
+3. Solvers estimate robot pose from detections.
+4. Position senders publish results to NetworkTables (and optional simulation outputs).
+5. Pathing and controller logic consume localization output and publish control intents.
+
+## Source Tree Map
+
+### `src/camera`
+
+- Camera interfaces and implementations (`CV`, `UVC`, disk replay).
+- Frame production wrappers (`CameraSource`, `MultiCameraSource`).
+- CSCore streaming to webpage and opencv write to disk.
+- Camera constants loading from JSON.
+- Camera selection for testing
+
+### `src/localization`
+
+- AprilTag detector interface and implementations:
+  - OpenCV ArUco AprilTag
+  - 971 GPU AprilTag (austin_gpu)
+  - NVIDIA VPI AprilTag
+- Pose solvers:
+  - `SquareSolver` (single tag)
+  - `MultiTagSolver` (multi-tag)
+  - `JointSolver` (multi-camera optimization)
+  - `UnambiguousEstimator` (ambiguity resolution and fusion)
+- Main localization loop (`run_localization`).
+- Publishers and receivers for position data.
+
+### `src/pathing`
+
+- BFS grid pathfinding.
+- Spline generation.
+- Control loop integration for command publication.
+
+### `src/yolo` and `src/gamepiece`
+
+- TensorRT-based YOLO wrapper.
+- Gamepiece pipeline built on top of camera + yolo + localization utilities.
+
+### `src/utils`
+
+- Shared cross-cutting helpers:
+  - logging
+  - timers
+  - transforms / matrix operations
+  - NetworkTables utility helpers
+  - JSON constant handling
+
+### `src/calibration`
+
+- Intrinsics calibration tools.
+- Frame display and focus calibration binaries.
+
+### `src/test`
+
+- `unit_test`: tests whose output can be decided without human input.
+- `integration_test`: tests whose output is in the form of a log or feed which must be reviewed
+
+## Top-Level Binaries (Some deprecated)
+
+Defined in `src/CMakeLists.txt`:
+
+- `main_bot_main`
+- `second_bot_main`
+- `unambiguous_first`
+- `unambiguous_second`
+
+## Dependency Snapshot
+
+Major linked dependencies across modules:
+
+- OpenCV
+- Eigen3
+- WPILib (`wpilibc`, `wpiutil`, `ntcore`)
+- libuvc
+- NVIDIA VPI
+- TensorRT / CUDA (`nvinfer`, `nvinfer_plugin`, `cudart`)
+- 971 AprilTag
+- abseil
+- nlohmann/json
+- GoogleTest
diff --git a/docs/build-and-run.md b/docs/build-and-run.md
new file mode 100644
index 00000000..83ba41b0
--- /dev/null
+++ b/docs/build-and-run.md
@@ -0,0 +1,47 @@
+# Build and Run
+
+## Prerequisites
+
+You can get set up in two ways:
+
+1. Get access to the build server over Tailscale.
+2. Build your own BOS Docker container from `https://github.com/frc971/bos-docker`.
+
+Also ensure CUDA binaries are on your shell `PATH` by adding this to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export PATH="/usr/local/cuda-12.6/bin:$PATH"
+```
+
+If you are using the build server or the BOS Docker container, required toolchains and dependencies are already provided.
+
+## Build
+
+Use the project build script instead of running CMake manually:
+
+```bash
+./scripts/build.sh
+```
+
+Optional named build directory:
+
+```bash
+./scripts/build.sh --name=mybuild
+```
+
+## Main Runtime Binaries
+
+After building, these are the primary app entry points (some deprecated):
+
+- `main_bot_main`
+- `second_bot_main`
+- `unambiguous_first`
+- `unambiguous_second`
+
+## Calibration Tools
+
+Built in `src/calibration`:
+
+- `intrinsics_calibrate`
+- `frame_shower`
+- `focus_calibrate`
diff --git a/docs/scripts.md b/docs/scripts.md
new file mode 100644
index 00000000..4d6df4ed
--- /dev/null
+++ b/docs/scripts.md
@@ -0,0 +1,102 @@
+# Scripts Reference
+
+This document describes the scripts under `scripts/` and when to use them.
+
+## Build and Static Analysis
+
+### `scripts/build.sh`
+
+- Main build entrypoint.
+- Initializes submodules.
+- Creates `/bos/constants` when running outside `/bos`.
+- Configures a Release Ninja build with clang-tidy disabled.
+
+Usage:
+
+```bash
+./scripts/build.sh
+./scripts/build.sh --name=mybuild
+```
+
+### `scripts/clang_tidy_build.sh`
+
+- Build helper with clang-tidy enabled.
+- Uses `build/` as the output directory.
+- Usually used for CI checks rather than day-to-day local builds.
+
+Usage:
+
+```bash
+./scripts/clang_tidy_build.sh
+```
+
+## Test Execution
+
+### `scripts/run_tests.sh`
+
+- Runs all executable files in `build/src/test/unit_test`.
+- Returns non-zero if any test fails.
+
+Usage:
+
+```bash
+./scripts/run_tests.sh
+```
+
+## Deploy and Remote Sync
+
+### `scripts/copy_to_bin.sh`
+
+- Collects built executables from `build/src` into `bin/`.
+- Also copies `.so` and `.a` artifacts from `build/` into `bin/`.
+
+Usage:
+
+```bash
+./scripts/copy_to_bin.sh
+```
+
+### `scripts/deploy.sh`
+
+- Builds project, stages binaries into `bin/`, then rsyncs `bin/` and `constants/` to remote `/bos`.
+- Optional remote service restart (`bos.service`).
+
+Usage:
+
+```bash
+./scripts/deploy.sh nvidia@10.99.71.11
+./scripts/deploy.sh nvidia@10.99.71.11 true
+```
+
+### `scripts/remote_deploy.sh`
+
+- Like `deploy.sh`, but lets you pass a custom remote shell command (for jump-host/tunnel setups).
+- Current workflow uses a reverse tunnel through the build server.
+
+Usage:
+
+```bash
+ssh -R 9000:localhost:22 root@build-server
+./scripts/remote_deploy.sh "ssh -J charlie@localhost:9000" "nvidia@10.9.71.11"
+```
+
+### `scripts/upload_navgrid.sh`
+
+- Copies a local navgrid file into the running `orin` Docker container.
+- Then deploys to `nvidia@10.99.71.11` without restart.
+
+Usage:
+
+```bash
+./scripts/upload_navgrid.sh
+```
+
+### `scripts/upload_public_key.sh`
+
+- Uploads local `~/.ssh/id_ed25519.pub` and appends it to remote `authorized_keys`.
+
+Usage:
+
+```bash
+./scripts/upload_public_key.sh nvidia@10.99.71.11
+```
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 00000000..6ec3dabc
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,32 @@
+# Testing Guide
+
+## Test Layout
+
+Tests live under `src/test`:
+
+- `src/test/unit_test`: GoogleTest-based unit tests.
+- `src/test/integration_test`: integration executables for subsystems and end-to-end checks.
+
+## Build Tests
+
+Tests are part of the normal project build. Use the project build script:
+
+```bash
+./scripts/build.sh
+```
+
+If you use a named build directory, keep that same directory when running tests:
+
+```bash
+./scripts/build.sh --name=mybuild
+```
+
+## Run Tests
+
+Use the test runner script instead of running test binaries manually:
+
+```bash
+./scripts/run_tests.sh
+```
+
+This script runs executable tests in `build/src/test/unit_test` and returns a failing exit code if any test fails.
diff --git a/src/calibration/README.md b/src/calibration/README.md
new file mode 100644
index 00000000..acec2893
--- /dev/null
+++ b/src/calibration/README.md
@@ -0,0 +1,20 @@
+# Calibration
+
+This directory contains camera-calibration tools and the shared ChArUco-board utilities they use.
+
+## Files
+
+- `CMakeLists.txt` builds the standalone calibration executables in this directory.
+- `focus_calibrate.cc` opens a selected camera, streams frames through CSCore, and prints a Laplacian-based focus score so the lens can be adjusted live.
+- `frame_shower.cc` opens a selected camera and streams raw frames to a configurable port for visual inspection and camera bring-up.
+- `intrinsics_calibrate.cc` is the interactive calibration executable. It captures ChArUco detections from a selected camera, generates `calibration_board.png`, calibrates the camera, and writes `intrinsics.json`.
+- `intrinsics_calibrate_lib.h` declares the ChArUco calibration data structures, board constants, detector factory, drawing helpers, JSON conversion, and calibration routine.
+- `intrinsics_calibrate_lib.cc` implements the shared ChArUco workflow: detector construction, board rendering, board detection, annotation, OpenCV calibration, and intrinsic-parameter JSON serialization.
+
+## Main Types And Functions
+
+- `calibration::DetectionResult` holds one frame's ChArUco corners, IDs, object points, and image points.
+- `calibration::CreateDetector` builds an OpenCV `cv::aruco::CharucoDetector` using the project's board geometry.
+- `calibration::GenerateBoard` renders the printable ChArUco board image.
+- `calibration::DetectCharucoBoard` extracts calibration observations from an image.
+- `calibration::CalibrateCamera` converts collected observations into an OpenCV camera matrix and distortion coefficients.
diff --git a/src/camera/README.md b/src/camera/README.md
new file mode 100644
index 00000000..ddb3fc45
--- /dev/null
+++ b/src/camera/README.md
@@ -0,0 +1,29 @@
+# Camera
+
+This directory defines the camera abstraction used by localization, calibration, gamepiece detection, tests, and replay tooling.
+
+## Files
+
+- `CMakeLists.txt` builds the `camera` library from the camera implementations and helpers.
+- `camera.h` defines `camera::TimestampedFrame`, the common frame-plus-timestamp payload, and `camera::ICamera`, the interface implemented by all frame sources.
+- `camera_constants.h` declares `camera::CameraConstant`, `camera::DetectorType`, the camera-constant map type, and loaders for configured camera constants.
+- `camera_constants.cc` loads camera configuration data from JSON into `CameraConstant` records.
+- `camera_source.h` / `camera_source.cc` wrap one `ICamera` in a background acquisition thread and expose the most recent timestamped frame safely.
+- `multi_camera_source.h` / `multi_camera_source.cc` coordinate several `ICamera` instances, including replay-oriented modes that wait for consumers to use every frame.
+- `cv_camera.h` / `cv_camera.cc` adapt OpenCV/GStreamer `cv::VideoCapture` cameras to the `ICamera` interface and optionally log captured frames.
+- `uvc_camera.h` / `uvc_camera.cc` adapt libuvc devices to `ICamera`, including UVC-specific setup, frame buffering, restart, and cleanup.
+- `disk_camera.h` / `disk_camera.cc` replay timestamped image logs from disk as an `ICamera`, preserving logged timing with optional speed, start, and end controls.
+- `cscore_streamer.h` / `cscore_streamer.cc` publish OpenCV frames through WPILib CSCore MJPEG streams for debugging and dashboards.
+- `select_camera.h` / `select_camera.cc` choose a configured camera interactively or from a provided camera name.
+- `write_frame.h` / `write_frame.cc` write timestamped frames to disk for later replay.
+
+## Main Types
+
+- `camera::ICamera` is the polymorphic interface for live cameras and replay sources.
+- `camera::CameraSource` is a frame provider which independently spins up a thread to read the latest frame.
+- `camera::MultiCameraSource` is basically a bundle of camera sources, but it is responsible for maintaining all the latest frames across 2+ cameras.
+- `camera::CVCamera`, `camera::UVCCamera`, and `camera::DiskCamera` provide the concrete live and replay frame sources.
+  - `camera::CVCamera` is the standard camera stream reader, can process anything like IMX or USB. WARNING usb cameras using usb 2.0 will claim too much bandwidth over this protocol, so use `camera::UVCCamera` instead.
+  - `camera::UVCCamera` is for USB specifically, and manually adjusts payload size so that we can get many simultaneous USB camera feeds.
+  - `camera::DiskCamera` is for testing, and can process frames in a specific time range and go faster if requested.
+- `camera::CscoreStreamer` is the standard debug-stream output path.
diff --git a/src/gamepiece/README.md b/src/gamepiece/README.md
new file mode 100644
index 00000000..978a487c
--- /dev/null
+++ b/src/gamepiece/README.md
@@ -0,0 +1,14 @@
+# Gamepiece
+
+This directory connects YOLO object detections to robot-relative gamepiece positions. TODO extend
+
+## Files
+
+- `CMakeLists.txt` builds the `gamepiece` library.
+- `gamepiece.h` declares the gamepiece detection entry points.
+- `gamepiece.cc` runs YOLO on camera frames, estimates coral and algae positions from camera intrinsics/extrinsics and bounding-box centers, publishes the resulting `frc::Pose2d` values to NetworkTables, and provides a no-image inference path for model testing.
+
+## Main Functions
+
+- `gamepiece::run_gamepiece_detect` consumes frames from `camera::CameraSource`, runs a `yolo::Yolo` model, converts detections into robot-relative poses, and publishes coral/algae pose topics.
+- `gamepiece::run_gamepiece_detect_no_img` exercises the YOLO model without the live camera-position publishing loop.
diff --git a/src/localization/README.md b/src/localization/README.md
new file mode 100644
index 00000000..7e957dc6
--- /dev/null
+++ b/src/localization/README.md
@@ -0,0 +1,34 @@
+# Localization
+
+This directory contains AprilTag detection, pose solving, estimate disambiguation, and publishing/receiving code for robot localization.
+
+## Files
+
+- `position.h` defines shared data records: `TagDetection`, `PositionEstimate`, and `Point3d`.
+- `apriltag_detector.h` defines `IAprilTagDetector`, the common interface for all AprilTag detector backends.
+- `gpu_apriltag_detector.h` / `gpu_apriltag_detector.cc` wrap the 971 GPU AprilTag detector and convert GPU detections into project `TagDetection` records.
+- `opencv_apriltag_detector.h` / `opencv_apriltag_detector.cc` implement a CPU AprilTag 36h11 detector using OpenCV ArUco APIs and undistort returned corners.
+- `nvidia_apriltag_detector.h` / `nvidia_apriltag_detector.cc` wrap NVIDIA VPI AprilTag detection for PVA or CPU backends.
+- `position_solver.h` defines shared AprilTag geometry constants, the 2026 field layout, estimate variance helper, and `IPositionSolver`.
+- `square_solver.h` / `square_solver.cc` solve single-tag poses using OpenCV `SOLVEPNP_IPPE_SQUARE` and convert camera-relative tag poses into robot field poses.
+- `multi_tag_solver.h` / `multi_tag_solver.cc` solve one pose from multiple tag observations, while retaining single-tag ambiguous estimates for disambiguation.
+- `joint_solver.h` / `joint_solver.cc` refine a robot pose from observations across multiple named cameras using camera matrices and field tag geometry.
+- `unambiguous_estimator.h` / `unambiguous_estimator.cc` run a multi-camera localization pipeline, collect ambiguous estimates, choose a consistent pose, stream diagnostics, and publish camera status.
+- `position_sender.h` defines `IPositionSender`, the output interface for pose estimate sinks.
+- `networktable_sender.h` / `networktable_sender.cc` publish pose estimates, metadata, tag IDs, rejected tags, latency, loss, and logs through NetworkTables/WPILib logging.
+- `simulation_sender.h` / `simulation_sender.cc` draw estimated robot poses onto a field image and stream the visualization.
+- `position_receiver.h` / `position_receiver.cc` subscribe to the robot drive pose topic and expose the current `frc::Pose2d`.
+- `run_localization.h` / `run_localization.cc` compose a `CameraSource`, detector, solver, and senders into the continuous localization loop, with a simulation replay variant.
+
+## Main Interfaces
+
+- `localization::IAprilTagDetector` converts images into tag corner detections.
+- `localization::IPositionSolver` converts tag detections into robot pose estimates.
+- `localization::IPositionSender` publishes or visualizes pose estimates.
+
+## How to Choose Solvers
+
+- `localization::UnambiguousEstimator` is the default for multiple camera streams (TODO when joint solve is tested this will become the default).
+- `localization::MultiTagSolver` is the default for single camera multiple tag detections. It has the potential to be ambiguous with only 1 tag.
+- `localization::SquareSolver` should be most accurate for single tag detections (TODO run rigorous test) because it uses more constraints. High rate of ambiguity, should never be used without some method of handling ambiguity.
+- `localization::JointSolver` is in progress (TODO update when joint solve is merged) and will be implemented on top of unambiguous to achieve the most stable pose estimates
diff --git a/src/pathing/README.md b/src/pathing/README.md
new file mode 100644
index 00000000..2eefc0dc
--- /dev/null
+++ b/src/pathing/README.md
@@ -0,0 +1,19 @@
+# Pathing
+
+This directory contains grid pathfinding, spline generation, and a NetworkTables-driven path controller.
+
+## Files
+
+- `CMakeLists.txt` builds the `pathing` library.
+- `pathfinding.h` / `pathfinding.cc` define grid `Node` and `Point` structures and implement `pathing::BFS`, which searches an obstacle grid and returns a node path.
+- `splines.h` / `splines.cc` provide B-spline helpers (`KnotVector`, `basis`, `evaluate`) and `createSpline`, which converts a BFS path into smooth `frc::Pose2d` waypoints.
+- `controller.h` / `controller.cc` implement `RunController`, which reads a navigation grid, receives current and target poses through NetworkTables, generates a spline path, and publishes velocity commands plus the next path pose.
+- `simulator.cc` is a standalone path-following simulation experiment that logs pose, velocity, and acceleration data. It is not currently part of the `pathing` library target in this directory's CMake file.
+
+## Main Types And Functions
+
+- `pathing::Node` represents one grid cell, including traversal state, obstacle status, parent link, and path markers.
+- `pathing::Point` is the integer grid coordinate used as BFS input.
+- `pathing::BFS` finds a grid path between two points.
+- `pathing::createSpline` turns that grid path into meter-space poses for motion.
+- `pathing::RunController` connects path generation to robot pose and target topics.
diff --git a/src/test/README.md b/src/test/README.md
new file mode 100644
index 00000000..0f835332
--- /dev/null
+++ b/src/test/README.md
@@ -0,0 +1,8 @@
+# Test
+
+This directory groups manual integration test programs and GoogleTest unit tests.
+
+## Subdirectories
+
+- `integration_test/` contains the tests which require human oversight to determine if they pass
+- `unit_test/` are the automated tests
diff --git a/src/test/integration_test/README.md b/src/test/integration_test/README.md
new file mode 100644
index 00000000..14b0db0b
--- /dev/null
+++ b/src/test/integration_test/README.md
@@ -0,0 +1,19 @@
+# Integration Tests
+
+This directory contains executable diagnostics and end-to-end tests for camera, localization, pathing, NetworkTables, YOLO, and NVIDIA VPI behavior. Many of these programs are interactive or hardware-dependent rather than hermetic CI tests.
+
+## Files
+
+- `CMakeLists.txt` builds each integration test executable.
+- `apriltag_detect_test.cc` opens a configured camera, runs the GPU AprilTag detector, solves poses with `SquareSolver`, logs estimates, and streams an annotated frame.
+- `bfs_tester.cc` loads the navigation grid, runs BFS and spline helpers, and displays/prints pathfinding behavior for manual inspection.
+- `gamepiece_test.cc` opens a camera, constructs the color YOLO model, and starts the gamepiece detection loop publishing coral and algae poses.
+- `intrinsics_test.cc` loads camera intrinsics, streams raw and undistorted camera frames side by side, and validates calibration files visually.
+- `localization_test.cc` replays logged camera images from one or more folders, resolves camera constants, runs localization, and streams/publishes simulation outputs.
+- `localization_test2.cc` runs the multi-camera `UnambiguousEstimator` against left/right replay folders.
+- `networktable_performance_test.cc` subscribes to the drive pose topic and prints observed NetworkTables update frequency and period.
+- `path_plan_test.cc` is a standalone visual path-planning playground with its own grid node class and drawing helpers.
+- `pva_test.cc` is an NVIDIA VPI AprilTag sample-style test for PVA/CPU AprilTag detection and visualization.
+- `solver_test.cc` feeds synthetic tag-corner observations into `SquareSolver` and prints resulting pose estimates.
+- `stress_test.cc` is an older multi-threaded localization stress harness for several camera/detector/solver pipelines.
+- `yolo_test.cc` opens a camera, runs YOLO inference, draws detections, estimates object angle, and streams the annotated result.
diff --git a/src/test/unit_test/README.md b/src/test/unit_test/README.md
new file mode 100644
index 00000000..6565026b
--- /dev/null
+++ b/src/test/unit_test/README.md
@@ -0,0 +1,16 @@
+# Unit Tests
+
+This directory contains GoogleTest-based checks for localization solvers, transformation math, pathfinding, and shared test helpers.
+
+## Files
+
+- `CMakeLists.txt` builds the unit test executables.
+- `general_solver_test.cc` compares `SquareSolver` and `MultiTagSolver` on synthetic detections and a real AprilTag image.
+- `joint_solve_test.cc` exercises `JointSolver` from a perturbed starting pose and compares it against square-solver output.
+- `matrix.cc` validates transformation decomposition and recomposition helpers from `utils::transform`.
+- `multi_tag_test.cc` checks that a single-tag multi-tag solve matches the square-solver pose matrix.
+- `pathing_test.cc` loads the navigation grid and verifies BFS returns the expected node sequence.
+- `square_solve_test.cc` validates basic `SquareSolver` orientation behavior from shared fake detections.
+- `unit_test_utils.h` declares fake detections, numeric tolerances, pose print support, and comparison helpers for tests.
+- `unit_test_utils.cc` implements GoogleTest pose printing and approximate `position_estimate_t` equality helpers.
+- `test_image.jpg` is an image fixture available to unit tests.
diff --git a/src/utils/README.md b/src/utils/README.md
new file mode 100644
index 00000000..fe1c55a9
--- /dev/null
+++ b/src/utils/README.md
@@ -0,0 +1,23 @@
+# Utils
+
+This directory contains shared helpers for camera JSON files, NetworkTables setup, logging, timing, and coordinate transforms.
+
+## Files
+
+- `CMakeLists.txt` builds the `utils` library.
+- `pch.h` centralizes commonly used standard-library, OpenCV, Eigen, WPILib, NetworkTables, and JSON includes.
+- `camera_utils.h` / `camera_utils.cc` read camera intrinsic and extrinsic JSON files from disk.
+- `constants_from_json.h` / `constants_from_json.cc` convert JSON camera calibration data into OpenCV, Eigen, WPILib, and project transform types.
+- `log.h` / `log.cc` print WPILib poses, transforms, and OpenCV transformation matrices in readable form.
+- `log_path.h` / `log_path.cc` generate new log paths under the configured log directory.
+- `nt_utils.h` / `nt_utils.cc` start and configure NetworkTables for the robot/team environment.
+- `timer.h` / `timer.cc` define `utils::Timer`, an RAII-style timer used to measure and optionally print elapsed time for a scoped operation.
+- `transform.h` / `transform.cc` provide coordinate-system conversion and transform helpers between OpenCV, Eigen, and WPILib conventions.
+
+## Main Types And Functions
+
+- `utils::Timer` measures runtime until `Stop()` or destruction.
+- `utils::CameraMatrixFromJson` and `utils::DistortionCoefficientsFromJson` create calibration matrices from intrinsic JSON.
+- `utils::ExtrinsicsJsonToCameraToRobot` converts extrinsic JSON into a WPILib camera-to-robot transform.
+- `utils::ChangeBasis`, `utils::Pose3dToCvMat`, and `utils::ConvertOpencvTransformationMatrixToWpilibPose` keep pose math consistent across libraries.
+- `utils::StartNetworktables` initializes NetworkTables for runtime programs.
diff --git a/src/yolo/README.md b/src/yolo/README.md
new file mode 100644
index 00000000..a2738900
--- /dev/null
+++ b/src/yolo/README.md
@@ -0,0 +1,15 @@
+# YOLO
+
+This directory wraps TensorRT YOLO inference and stores model metadata used by gamepiece detection and tests.
+
+## Files
+
+- `CMakeLists.txt` builds the `yolo` library.
+- `model_constants.h` defines `yolo::ModelInfo`, the available model enum, model engine paths, class names, and color/gray model settings.
+- `yolo.h` declares the `yolo::Yolo` TensorRT wrapper, including inference, post-processing, object-angle calculation, and detection drawing APIs.
+- `yolo.cc` implements TensorRT engine loading, CUDA/OpenCV preprocessing, inference execution, YOLO post-processing, detection drawing, and GPU resource cleanup.
+
+## Main Types
+
+- `yolo::ModelInfo` describes one serialized TensorRT model and its classes.
+- `yolo::Yolo` owns the TensorRT runtime, engine, execution context, CUDA stream, and input/output buffers needed to run inference.