Added homekit-decode.sh to the mix, and updated the readmes.

CLAUDE.md

@@ -5,13 +5,20 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## What this is
 
 A collection of Matter commissioning QR decoders (the `MT:` URI format used by
-Matter/CHIP devices). Users either paste an `MT:` URI or scan a QR code; the
-result shows the decoded payload (version, vendor/product IDs, commissioning
-flow, discovery capabilities, discriminator, passcode). Three artifacts:
+Matter/CHIP devices), plus a standalone bash decoder for Apple **HomeKit**
+setup codes (the `X-HM://` payload — a different on-wire format, in
+`homekit-decode.sh`). For Matter, users either paste an `MT:` URI or scan a QR
+code; the result shows the decoded payload (version, vendor/product IDs,
+commissioning flow, discovery capabilities, discriminator, passcode). Key files:
 
 - `matter-qr-decoder.html` — the single-file browser app (Vue 3 + Bootstrap).
 - `matter-decode.sh` — a pure-bash CLI port of the same decode logic (no camera
   scanning; takes a URI as an argument or on stdin).
+- `homekit-decode.sh` — a standalone pure-bash decoder for Apple **HomeKit**
+  setup codes (the `X-HM://` payload an accessory shows on first setup — a
+  *different* format from Matter's `MT:`). No browser counterpart and no
+  companion TSV (the accessory-category table is inlined). See the
+  HomeKit setup-code decode section below.
 - `manufacturers.tsv` — `vendor ID → name` table (~900 rows), shared by both
   tools and optional (a missing file only drops the vendor-name lookup).
 - `gen-manufacturers.py` — Python 3 stdlib script that regenerates
@@ -151,6 +158,45 @@ Two helpers, defined just above `main()`:
    (user-intent `1`, custom `2`) append 5-digit vendor and product groups. Result:
    11 digits for the standard flow, 21 otherwise, plus the check digit.
 
+### HomeKit setup-code decode (bash only)
+
+`homekit-decode.sh` is a *second, independent* decoder — for Apple **HomeKit**
+setup codes, the `X-HM://` payload an accessory (or its packaging) shows on first
+setup. That is a different on-wire format from Matter's `MT:`, so this is **not**
+a port of the HTML app's pipeline; it is standalone, with no browser counterpart
+and no companion TSV (the accessory-category table is inlined). It sits alongside
+`matter-decode.sh` as the repo's other CLI decoder.
+
+Input is an optional positional argument, defaulting to the demo payload
+`005KEOUCE`. A leading `X-HM://` is stripped if present. The first 9 characters
+are the fixed parameter block; anything after them is a variable-length **setup
+id**, carried through verbatim (it is not part of the numeric block).
+
+Unlike Matter's **base38** payload (charset `0-9 A-Z - .`, 38 symbols), the
+HomeKit block is **base36** (`0-9 A-Z`, 36 symbols): each char does
+`val = val*36 + digit`, and an out-of-range character is a hard error (to
+stderr, exit 1). `val` is then sliced **LSB-first** into the HomeKit layout:
+
+    pin(27) | flag(4) | categoryId(8) | reserved(4) | version(3)
+
+- `flag` is a 4-bit sub-flag set — `1`=NFC, `2`=IP, `4`=BLE, `8`=WAC/MFi —
+  printed as True/False lines.
+- `categoryId` is resolved to its HAP `homekit_accessory_category_*` name (e.g.
+    `5` → "Lightbulb", `8` → "Switch") via an inlined `case`; an id not in the
+   table prints "unknown" (id `25` is reserved by HomeKit, so it is unknown by
+   design, and "Heater" corrects a "Header" typo in the source table). A `case`
+   rather than an associative array is used on purpose so the script runs on the
+   stock macOS bash 3.2 that `#!/usr/bin/env bash` resolves to.
+- The decoded fields are packed back into a 9-char block (mirroring
+   `composeSetupUri`'s stepwise packing) and printed as a reconstructed
+   `X-HM://…` payload, so the output is a complete record the barcode can be
+   rebuilt from.
+
+This is the **corrected** bit layout — the one `composeSetupUri` in the
+`homekit-code` package actually encodes — rather than a misaligned earlier one.
+The header comments in `homekit-decode.sh` record each fix (the categoryId / flag
+/ version positions, and the dropped "Thread" misread of categoryId bits).
+
 ## Gotchas
 
 - The `BarcodeDetector` scanner polls the camera via `setInterval` every 200ms and
@@ -166,6 +212,11 @@ Two helpers, defined just above `main()`:
   mirror it in the script (and vice versa). The script's extras are the optional `manufacturers.tsv` (vendor name),
   `products.tsv` (product name), and `vendor-equivalents.tsv` (vendor
   equivalences); without any of them it still decodes everything else.
+- `homekit-decode.sh` is **not** part of that lockstep: it decodes a *different*
+  on-wire format (Apple HomeKit `X-HM://`, **base36** — not Matter's base38) and
+  has no HTML-app counterpart. Don't try to unify the two decoders or mirror
+  HomeKit changes into the HTML app; when editing it, keep the corrected bit layout
+  (`pin / flag / categoryId / reserved / version`) as the source of truth.
 - `manufacturers.tsv` is regenerated with `gen-manufacturers.py` (Python 3
   stdlib). Default source is the **upstream `manufacturers.xml` fetched over the
   network** (via `curl`; a GitHub `blob/` URL is auto-rewritten to its