1 files changed, 49 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d5f5081
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,49 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+`ak820-upload`: single-file Rust CLI (`src/main.rs`, std only, no crates)
+that writes an animation to the AJAZZ AK820 Pro screen over Linux hidraw.
+ffmpeg (subprocess) decodes any input to raw RGB565LE frames; the program
+builds the payload and drives the upload. `README.md` documents the protocol.
+
+On the maintainer's machine the release binary is linked into PATH, so a
+`cargo build --release` is live immediately:
+
+    ~/bin/ak820-upload -> target/release/ak820-upload
+
+## Protocol facts (verified on hardware, do not "simplify" away)
+
+The protocol comes from a USB capture of the official Windows app. Earlier
+attempts based on community projects (gohv, ajazz-ak820-config) failed in
+instructive ways:
+
+- The 64-byte GET_REPORT after every SET_REPORT is required. Without it the
+  keyboard accepts the bytes and does nothing. A zero-length GET is rejected
+  by the kernel with EINVAL and never reaches the device.
+- Control reports go out as report ID 0 with `04` as the first data byte
+  (`wValue 0x0300`), not report ID 4.
+- IMAGE sub-command is `0x02`. Chunks are plain 4096 bytes, no filler or
+  short packet (gohv's 4123-byte chunks misalign every other chunk).
+- Chunk acks arrive on endpoint 0x84, which belongs to interface 2 (the data
+  interface), not interface 3. Wait for each ack before the next chunk.
+- Frame delay byte is in 2 ms units (app value 50 -> 0x19, 250 -> 0x7d).
+- A still image is just a 1-frame animation; there is no separate path.
+
+Interfaces by `HID_PHYS` suffix: `/input2` = data (EP 0x03 OUT, 0x84 IN),
+`/input3` = control.
+
+## Testing
+
+`cargo test` checks the packet and payload layout against the captured
+bytes. `cargo clippy --release` must stay clean. A real check needs the
+keyboard: upload a few distinct, numbered frames and watch them cycle on the
+GIF page. If an upload is interrupted the keyboard shows "loading NN%";
+replug it before retrying.
+
+## Repo facts
+
+- License: GPL-2.0-only (`LICENSE`, SPDX header in `src/main.rs`).
+- Companion repo: `video2ak820` (bash, video to GIF).