docs: check in the AI-assistant guidance contributors were missing

[widgetii]

The repo has never carried a CLAUDE.md or AGENTS.md, so anyone pointing an AI assistant at defib started from whatever it could infer by grepping — a bad place to start on a tool whose failure mode is an erased camera.

This adds the file, fact-checked line by line against the tree.

Corrections over the draft that was sitting untracked

Claim	Reality
HiSilicon/Goke over UART	Rockchip USB recovery was missing entirely — src/defib/rockusb/ is ~1.5k LOC with its own extra, its own profile (rv1106) and a RECOVERY field in the profile schema
~6700 LOC Python / ~500 LOC C	~15k and ~4k — understated 2.3x and 8x
7 CLI commands	12 top-level + 7 agent subcommands; restore was omitted, a headline README feature
6 agent opcodes, "921600 baud"	13 opcodes; the agent comes up at 115200 and is switched to 921600 by CMD_SET_BAUD afterwards
load address via link.ld	link.ld is generic; addresses are per-SoC ifeq stanzas in agent/Makefile. all-socs builds 4 of 10
"optional FastAPI server"	Does not exist — src/defib/web/ is a one-line placeholder and the web extra is vestigial
protocols and power controllers via entry points	Only protocols. The defib.power group is declared in pyproject but nothing reads it; power/factory.py is a hardcoded if/elif
"120+ JSON files"	112 files. defib list-chips shows 123 because the 11 V500/CV6xx chips are hardcoded in their protocol classes rather than filed
3 transports	6. Also: mypy has a second override for usb.*, and CI runs both JS test files

One thing the review surfaced

Writing the protocol section down made a latent trap visible:
HiSiliconStandard.matches() is just "does a profile JSON exist with this
stem", the entry points load alphabetically as [CV6xx, Standard, V500], and
find_protocol() returns the first match. The only reason Standard does not
swallow the V500 chips is that they deliberately have no profile file. So
adding a profile JSON for a V500-family chip would silently route it to the
wrong protocol. Documented in both the architecture section and the add-a-chip
checklist.

What it adds beyond corrections

The things this repo has never documented anywhere:

• That there are no guard rails. No confirmation prompt, no --dry-run,
  no --force exists in the CLI — install/restore/agent flash/agent write
  start erasing on invocation. So: back up before you write, with the command.
  Plus a read-only vs irreversible command table.
• The three ways to work without hardware — MockTransport, QEMU over
  socket://, .dcap replay — including the trap that defib replay only
  prints a capture.
• Serial reality — the /dev/uart-* udev symlink convention that
  serial_ports.py and PoE port discovery depend on but nothing creates for
  you, the dialout group, and which commands need root.
• The add-a-chip checklist, including the hand-maintained PROFILES copy
  in web/index.html that nothing regenerates — the omission behind web: 65 frame-blast (PRESTEP0) chips are selectable but the web build never sends PRESTEP0 #121.
• Commit conventions, and a note that "agent" here means the bare-metal ARM32
  flash agent, not an AI one.

Safety claims are held to what is on master: the Rockchip zero-capacity and
out-of-range read guards are real but live on an unmerged branch, so they are
not listed yet.

AGENTS.md is a symlink to CLAUDE.md so assistants looking for the
vendor-neutral name find the same text. Windows checkouts without symlink
support will see a one-line file containing CLAUDE.md.

Verification

Every command the file documents was run in a clean worktree:

• pytest tests/ --ignore=tests/fuzz — 715 passed, 2 skipped
• pytest tests/fuzz/ --hypothesis-seed=0 — 16 passed
• ruff check src/ tests/ — clean
• mypy src/defib/ --ignore-missing-imports — clean, 66 files
• make -C agent test HOST_CC=gcc — 5412/5412
• node --test web/protocol.test.js web/profile-parity.test.js — 86 passed
• make -C agent and make -C agent SOC=hi3516cv300 — both build

The uv sync line adds --extra rockchip, which CI does not currently
install — worth considering for the test job so the six tests/test_rockusb_*.py
files run with pyusb present.

Not included

README.md is stale in the same ways — it still says "HiSilicon, Goke, and
other SoC families" with no mention of Rockchip despite #125 having shipped,
and omits dump-flash/detect. Left for a separate PR.

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add repository guidance for AI coding assistants

📝 Documentation 🕐 10-20 Minutes

AI Description

• Adds fact-checked assistant guidance covering architecture, workflows, and contribution
 conventions.
• Highlights destructive-command risks, backups, privileges, and hardware-free testing paths.
• Exposes identical guidance through the vendor-neutral AGENTS.md symlink.

Diagram

graph TD
  A["AI Assistant"] --> B["AGENTS.md"] --> C["CLAUDE.md"] --> D["Repo Architecture"]
  C --> E["Safety Guidance"]
  C --> F["Dev Workflows"]
  C --> G["Contribution Rules"]

Loading

High-Level Assessment

A canonical CLAUDE.md with an AGENTS.md symlink is appropriate: it supports vendor-specific and vendor-neutral discovery without maintaining duplicate guidance. Separate copies would risk drift, while choosing only one filename would reduce assistant compatibility.

Files changed (2) +298 / -0

Documentation (2) +298 / -0

AGENTS.mdExpose canonical guidance under the vendor-neutral filename +1/-0

Expose canonical guidance under the vendor-neutral filename

• Adds a symlink to 'CLAUDE.md' so assistants that discover repository instructions through 'AGENTS.md' receive the same canonical guidance.

AGENTS.md

CLAUDE.mdDocument repository architecture, safety, and contributor workflows +297/-0

Document repository architecture, safety, and contributor workflows

• Adds comprehensive, fact-checked guidance for AI-assisted development, including architecture, build and test commands, hardware safety, offline testing, chip onboarding, and commit conventions. It also clarifies Rockchip USB recovery and distinguishes the bare-metal flash agent from AI assistants.

CLAUDE.md