Add ak820-upload: AK820 Pro screen uploader over hidraw

Std-only Rust CLI. ffmpeg decodes any image/GIF/video to 128x128
RGB565LE frames; the upload follows a USB capture of the official
Windows software: report-ID-0 feature reports each followed by a
64-byte GET_REPORT, IMAGE sub 0x02 with chunk count, 4096-byte chunks
on interface 2 paced by the keyboard's acks on EP 0x84, then SAVE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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).