From 2c28b0edc23142a6f67e24b427a421f3b5ef9d5f Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Wed, 11 Feb 2026 05:47:03 -0700
Subject: [PATCH] Add CLAUDE.md with project context and protocol notes

---
 CLAUDE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ea0777a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,51 @@
+# Winegard Trav'ler
+
+Control a Winegard Trav'ler motorized satellite dish via RS-485 for amateur radio satellite tracking.
+
+## Project
+
+- **Package:** `travler-rotor` (installed via `uv sync`)
+- **CLI entry point:** `travler-rotor` (init / serve / pos / move)
+- **Source layout:** `src/travler_rotor/` (src-layout)
+- **Original upstream:** `Trav-ler-Rotor-For-HAL-2.05/` — Gabe Emerson's scripts, kept as reference (do not modify)
+
+## Build & Lint
+
+```bash
+uv sync                           # Install deps + package
+uv run ruff check src/             # Lint
+uv run ruff format --check src/    # Format check
+uv run travler-rotor --help        # CLI smoke test
+```
+
+## Architecture
+
+```
+protocol.py   — FirmwareProtocol ABC + HAL205Protocol / HAL000Protocol
+                Serial I/O owned here. Each firmware version is a subclass.
+leapfrog.py   — Pure function: apply_leapfrog(target, current) -> adjusted
+                Predictive overshoot to compensate for mechanical motor lag.
+antenna.py    — TravlerAntenna: high-level control wrapping protocol + leapfrog
+                This is what consumers (CLI, rotctld, future MCP server) call.
+rotctld.py    — RotctldServer: Hamlib rotctld TCP protocol (p/P/S/_/q)
+                Bridges Gpredict to the antenna.
+cli.py        — Click CLI with init/serve/pos/move subcommands
+```
+
+## Hardware Protocol Notes
+
+- RS-485 serial, 57600 baud, 8N1
+- Motor commands: `a <motor_id> <degrees>` (0=azimuth, 1=elevation)
+- Position query: `a` returns `AZ = <val>  EL = <val>  SK = <val>`
+- HAL 2.05 motor submenu: `motor` command; search kill via `ngsearch -> s -> q`
+- HAL 0.0.00 motor submenu: `mot` command; search kill sequence undocumented
+- Boot signals (HAL 2.05): "NoGPS" or "No LNB Voltage" indicate homing complete
+- Elevation floor: HAL 2.05 unreliable below 15 degrees with direct motor commands
+
+## Known Bugs (from upstream)
+
+- Leap-frog elevation bug: original `travler_rotor.py` lines 98-105 modify `target_az` instead of `target_el`. Fixed in `leapfrog.py`. See `docs/bugs.md`.
+
+## Testing
+
+No hardware-in-the-loop tests yet. Protocol implementations can be mocked for unit testing — `FirmwareProtocol` is an ABC with clear method contracts.