diskos/agents/AGENTS.md

# diskOS - working rules for AI coding agents

This file is written for an AI coding agent (Claude Code, Codex, or similar) helping someone
hack on **diskOS** - a custom UI/firmware for the FiiO Snowsky Disc digital audio player
(Ingenic X2000 SoC). Drop it in as your `CLAUDE.md` or `AGENTS.md`, or paste it into the
session, and follow it. It encodes the discipline that keeps this project honest and the
device un-bricked.

## The one rule that matters most: verify, do not guess

This device's hardware, firmware, audio path, and command surface are **non-obvious and easy
to hallucinate**. Before you assert anything about how the device behaves:

- **Check `docs/HARDWARE.md`** (live-probed hardware capability map) for chip part numbers,
  sample rates, dev nodes, partition layout, I2C addresses.
- **Read the actual binary / source** for what code does - never state it from training priors
  or from earlier in the session.
- If a claim is not in a doc and you cannot verify it against the device or a binary, **say it
  is unverified** rather than stating it confidently.

"Probably", "should be", "likely already" are hallucination flags. Resolve them by reading
first.

## Hardware facts that are easy to get wrong

- Wireless chip is **BCM43438 / AP6212 (2.4 GHz only, BT over UART)**. There is **no 5 GHz**.
  (Old notes saying "BCM4345C5" are wrong - those `.hcd` files are leftovers for other models.)
- **Four CS43131 DACs**, fully balanced (L+/L-/R+/R-), driven by a kernel driver via **ioctl**
  on `/dev/cs43131{,b,c,d}` - **not** via ALSA controls.
- **No physical LED** on the unit. `/sys/class/leds` is empty; `RGB_*` config fields are
  vestigial. Plan no LED features.
- **No GPU / VPU / hardware JPEG / DVFS / thermal sensors.** MSA SIMD is the only accel.
- The rootfs partition (`mtd2`) is a **read-only squashfs**, which is why the boot hook cannot
  be edited in place; persistent state lives in the writable `/usr/data` (`mtd7`).

See `docs/HARDWARE.md` for the full map and the reproducible probe commands.

## Repo layout

- `diskos_installer/` - the Python installer (GUI + CLI) that builds a diskOS image from the
  user's own stock firmware and flashes it over mask-ROM USB.
- `flash/` - the low-level flashing pieces: the mask-ROM writer source (`my_write5.c`), the
  stage-1 SPL, and helper scripts.
- `spl-src/` - GPL corresponding source for the stage-1 DRAM bring-up SPL (patch series over
  upstream U-Boot). See `SPL_SOURCE.md`.
- `src/usbboot/` - the Ingenic mask-ROM USB loader (third-party GPL; do not rewrite).
- `payload/` - the on-device first-boot hook and the diskOS UI binary (`mq_ui`).
- `docs/` - hardware map and other reference docs.
- `licenses/`, `NOTICE.md` - third-party attribution and license texts.

## Device-safety rules (read before touching the device)

- A flash **rewrites the read-only rootfs**. It is **normally recoverable** because the Ingenic
  mask-ROM USB mode lives in on-chip ROM and is reached by a button combo *before* any flashed
  code runs - so a bad flash can usually be re-flashed. This is the safety net, not an A/B slot, and
  recovery is **not guaranteed** on every unit or failure mode (match the README's wording).
- The first-boot install is **fail-closed**: if the UI cannot be verified against the baked
  manifest (SHA-256), the stock UI runs instead. Never weaken that contract.
- **You cannot install from the device's own "System updates" menu** - it checks an ECDSA
  signature against FiiO's public key, which a custom image will not have. Mask-ROM USB is the
  only way in.
- The mask-ROM USB link is **flaky** - it allows roughly one `usbboot` run per power-cycle and
  hangs early ~1 in 3. If a run hangs at the download-to-start transition, power-cycle back
  into mask-ROM and retry rather than fighting it.

## Working habits

- **Honest limitations.** When something is blocked by hardware (no 5 GHz, no GPU, DAC ioctls
  not yet reverse-engineered) or a toolchain gap, say so plainly instead of implying it works.
- **Test before claiming success.** A change to the image builder or the boot hook is not
  "done" until it is validated against a real build / a real device, not just a passing
  typecheck. The installer carries offline validation (independent squashfs extraction, hash
  round-trips) precisely so the expensive on-device flash only tests what it must.
- **Fail closed, log loudly.** Every error path in the installer has a code (`E1xx` preflight,
  `E2xx` build, `E3xx` flash, `F1xx` device-writer). If you add a failure mode, give it a code
  and document it in `README.md`.
- **Cite file:line** when you summarize what changed, so a human can verify it.

## Contributing

- Keep the flashed image = stock FiiO rootfs + the minimal diskOS patch. We do **not**
  redistribute FiiO's rootfs; the installer builds it from the user's own firmware zip.
- GPL components (usbboot, squashfs-tools, the SPL) ship with corresponding source. If you
  touch how they are bundled, keep the source and `NOTICE.md` in sync.
- New firmware versions must be **flash-tested on real hardware** before being declared
  supported - command-tag meanings differ across versions and a wrong command can misbehave.