Shooter and Turret code.

.cursor/rules/java.mdc

@@ -2,3 +2,10 @@
 globs: src/main/java/**
 alwaysApply: false
 ---
+
+Use this rule when writing or refactoring Java robot code under `src/main/java/**`.
+
+## Expected notation
+
+- **Public static methods**: Must start with an uppercase letter.
+  - Example: `public static void Register(...)` (not `public static void register(...)`).

.cursor/rules/lighting.mdc

@@ -0,0 +1,70 @@
+---
+description: Rules for extending and using the robot lighting framework (LightsSubsystem, lighting effects, and polling-based multi-command orchestration)
+globs:
+  - src/main/java/frc/robot/subsystem/LightsSubsystem.java
+  - src/main/java/frc/robot/util/lighting/**
+  - src/main/java/frc/robot/command/lighting/**
+  - src/main/java/frc/robot/command/util/PollingCommand.java
+  - src/main/java/frc/robot/constant/LEDConstants.java
+  - src/main/java/frc/robot/RobotContainer.java
+alwaysApply: false
+---
+
+Use this rule when modifying robot lights code.
+
+## Core ownership model
+
+- `LightsSubsystem` is the only class that should write LED hardware frames.
+- `LightsEngine` owns effect composition, priorities, blend logic, diffing, and compression.
+- `PollingCommand` is the default command of `LightsSubsystem` and runs multiple lighting commands per loop.
+
+Do not add direct CANdle writes in lighting commands.
+
+## Multi-command model (important)
+
+The lights subsystem supports multiple independent lighting commands via polling:
+- Register commands with `LightsSubsystem.addLightsCommand(...)`.
+- Keep the default command as the internal `PollingCommand`.
+- Do not overwrite default command in `RobotContainer` for lights orchestration.
+
+If adding a new lighting behavior, make it a command in `src/main/java/frc/robot/command/lighting`.
+
+## Read-only command expectations
+
+Lighting commands should be read-only signal producers:
+- Read robot state (sensors, subsystem status, operator inputs).
+- Create effects in `initialize()`.
+- Update effect parameters in `execute()` (for example `setInput` / `setProgress`).
+- Cleanup with `removeEffect(...)` in `end(...)` when appropriate.
+
+They should not:
+- Mutate unrelated robot subsystem state.
+- Perform scheduling side effects.
+- Send raw hardware controls directly.
+
+## API conventions
+
+- Prefer named zones through `lights.rangeOf(LightZone.X)` over raw indices when possible.
+- Keep `EffectHandle<TInput>` references in command state; this is the stable id for updates/removal.
+- Prefer typed updates through `setInput(handle, value)` when an effect exposes a typed input.
+- For base layers: lower priority + `BlendMode.OVERWRITE`.
+- For overlays: higher priority + `BlendMode.ADD`.
+- Clamp-like behavior is already handled in effect/color classes; do not duplicate ad hoc clamp logic unless needed.
+
+## Render semantics to preserve
+
+- Effects are composited in ascending priority.
+- `OVERWRITE` replaces touched pixels only.
+- `ADD` channel-adds and clamps each channel to 255.
+- If frame diff is empty, no writes are emitted.
+- If segment count exceeds `LEDConstants.maxSolidWritesPerCycle`, adaptive compression must remain active.
+
+## Safe extension checklist
+
+When introducing a new effect type:
+1. Add effect class under `src/main/java/frc/robot/util/lighting/effects`.
+2. Extend `LightsSubsystem` with a typed `addX(...)` creation method.
+3. Choose an input type `T` for `LightEffect<T>` (`Void` if no runtime input), and wire `updateInput` if needed.
+4. Keep behavior deterministic with respect to `(ledIndex, nowSeconds)` inputs.
+5. Add/extend tests in `src/test/java/frc/robot/util/lighting`.
+6. Preserve existing priority/blend/segment invariants.

.gitignore

@@ -208,4 +208,6 @@ src/main/deploy/config
 
 *.db
 .coverage
+*.lock
+*.bin
 checkpoints/

AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS
+
+## Verified workflows
+
+- Workspace bootstrap: `git submodule update --init --recursive` then `npm install`
+- Full robot build: `./gradlew build`
+  - Also runs dynamic vendor dependency build (`scripts/clone_and_build_repos.py --config-file-path config.ini`) and protobuf generation.
+- Java build wrapper: `make build`
+- Java simulation: `./gradlew simulateJava`
+- Robot deploy: `./gradlew deploy -PteamNumber=<TEAM_NUMBER>`
+- Robot deploy wrapper: `make deploy` (uses `TEAM_NUMBER`, default `4765`)
+- Combined deploy flow: `./gradlew deployAll`
+  - Runs robot deploy plus backend deploy task.
+- Gradle backend deploy task: `./gradlew deployBackend`
+  - Invokes `make deploy-backend` and validates deployed Pi count against `EXPECTED_NUM_OF_PIS`.
+- Python backend deploy directly: `make deploy-backend`
+- Python test flow: `make initialize` (creates `.venv`, installs `requirements.txt`, then runs tests) and `make test`
+- Config generation from TypeScript: `npm run config -- --dir src/config`
+- Regenerate Thrift TS bindings: `npm run generate-thrift`
+- Generate backend code artifacts: `make generate` (Python protobuf + Python thrift + Java proto task)
+- Java protobuf generation via Gradle: `./gradlew generate` (depends on `generateProto`)
+
+## Command notes
+
+- `make build` and `make deploy` enforce Java 17 via `/usr/libexec/java_home -v 17`.
+- `make deploy` defaults `TEAM_NUMBER=4765` unless overridden.
+- `./gradlew deployBackend` expects deployment on `EXPECTED_NUM_OF_PIS` (currently `2`) and fails if mismatch.
+- Dynamic vendor dependency builds are intentionally forced every Gradle compile/build cycle (`buildDynamicDeps.outputs.upToDateWhen { false }`).
+
+## TODO
+
+- Confirm whether automation should keep `TEAM_NUMBER=4765` and `EXPECTED_NUM_OF_PIS=2` as defaults or document per-robot override policy.
+- README references `applyBackend` and `make prep-project`; verify whether docs should be updated to `deployBackend`/`make initialize`.
+
+## Agent docs
+
+- Lighting API and extension guide: `docs/LightingApiForAgents.md`

Makefile

@@ -14,6 +14,16 @@ THRIFT_GEN_DIR = $(GEN_DIR)/thrift
 THRIFT_TS_SCHEMA_GEN_DIR = $(THRIFT_GEN_DIR)/ts_schema
 PROTO_PY_GEN_DIR = $(PROTO_GEN_DIR)/python
 
+TEAM_NUMBER=4765
+
+build:
+	export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+	./gradlew build
+
+deploy:
+	export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+	./gradlew deploy -PteamNumber=$(TEAM_NUMBER)
+
 initialize:
 	python3 -m venv .venv
 	.venv/bin/pip install -r requirements.txt
@@ -37,7 +47,10 @@ thrift-to-py:
 		-out $(THRIFT_GEN_DIR) \
 		$(THRIFT_ROOT_FILE);
 
-generate: generate-proto-python thrift-to-py
+proto-to-java:
+	./gradlew generateProto
+
+generate: generate-proto-python thrift-to-py proto-to-java
 
 deploy-backend:
 	PYTHONPATH="$(PWD)/src" $(VENV_PYTHON) -m backend.deploy