From a7cb2708ece4c6561ab5e331e6820a8aa021b713 Mon Sep 17 00:00:00 2001 From: Simon Clark Date: Fri, 12 Jun 2026 23:41:21 +0100 Subject: [PATCH 1/3] docs: remove references to the private ADR from the public repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0006 lives in the private Domio repo; the public repo and the GitHub Pages site were pointing readers at a document they cannot reach. All references replaced with self-contained wording — the share model is fully explained in docs/MATTER.md / matter.html, which now stand as the public record of the decision. Also tightened the fabrics claim while in there: "typically 5+" → the spec requires every certified device to accept at least five fabrics. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 2 +- README.md | 2 +- docs/HANDOVER.md | 2 +- docs/INSTALL.md | 2 +- docs/MATTER.md | 9 ++++----- docs/PRD-indigo-matter-plugin.md | 8 ++++---- docs/matter.html | 10 +++++----- indigo-matter.indigoPlugin/Contents/Info.plist | 2 +- 8 files changed, 18 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f0961cd..9e6523e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,7 @@ Domio (iOS, MatterSupport) ──commission+handoff──▶ indigo-matter ─ ## Related projects - [`../domio-code/`](../domio-code/) — iOS app; owns commissioning. The Domio↔plugin HTTP contract is **`docs/API.md`** (mirrored in both repos; keep in sync). -- Workspace **ADR-0006** (`domio-code/docs/adr/`, = workspace `docs/adr/0004`) — the Matter architecture decision (Apple TV TBR + matter-server + multi-admin handoff). +- The Matter architecture decision (the **share model**: the user's existing ecosystem commissions as admin 1, the plugin joins as a second admin over IP, the ecosystem's hub is the Thread border router) is explained for users in [`docs/MATTER.md`](./docs/MATTER.md). ## Architecture (this plugin) diff --git a/README.md b/README.md index 8a90a53..86e4b41 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Indigo-owned Matter fabric, and translates Matter clusters ↔ Indigo device typ Domio (iOS) ──share code──▶ indigo-matter ──WebSocket──▶ matter-server ──IP──▶ Wi-Fi Matter devices ``` -Commissioning uses the **share model** (ADR-0006, "C4"): Apple Home commissions the +Commissioning uses the **share model**: Apple Home commissions the device first, Domio relays a share/pairing code to the plugin, and the plugin joins the device's fabric as a second admin over IP. The plugin owns runtime control for the device's lifetime. diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index 4f7b33c..751fb2e 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -254,7 +254,7 @@ rsync -c "$SRC/Info.plist" "$DST/Info.plist" ### Read-only probe (run ON jarvis): `~/matter-probe.js` Dumps `server_info` + `get_nodes`/`get_node` + toggles. Run: `source ~/.nvm/nvm.sh; nvm use 22 >/dev/null; node ~/matter-probe.js`. -## 5. Domio integration (share model — ADR-0006 C4) — CONFIRMED this session +## 5. Domio integration (share model) — CONFIRMED this session Domio no longer commissions; it relays a **share code** (Apple Home is admin 1; the plugin joins as admin 2 over IP). diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 46c98bb..51597e2 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -27,7 +27,7 @@ A few things to know before you start: - **Domio drives commissioning.** You add devices from the **Domio iOS app**, not from Indigo. Apple Home commissions the device first; Domio relays a share/pairing code to the plugin, and the plugin joins the device's fabric as a second admin over IP (the - "share model", ADR-0006). The plugin owns runtime control for the device's lifetime. + "share model"). The plugin owns runtime control for the device's lifetime. - **matter-server is Alpha software.** Pin the version, back up the fabric, and expect occasional rough edges. diff --git a/docs/MATTER.md b/docs/MATTER.md index 48a3663..7257802 100644 --- a/docs/MATTER.md +++ b/docs/MATTER.md @@ -89,8 +89,8 @@ have BLE radios and (for Thread) the network credentials. A headless Mac running Indigo is a poor first commissioner: matter-server runs without BLE on macOS, and macOS has no Thread credential store. -This plugin sidesteps the problem entirely with the **share model** (the -architecture decision recorded as ADR-0006, option "C4"): +This plugin sidesteps the problem entirely with the **share model** — the +plugin's founding architecture decision: > An ecosystem you already own — Apple Home, or equally Alexa / Google Home — > commissions the device first: it owns the BLE step and gets the device onto @@ -103,8 +103,8 @@ That's only possible because of Matter's best feature: multi-admin. A Matter **fabric** is a controller's trust domain — a set of cryptographic credentials a controller installs on a device. The crucial design choice in -Matter is that **a device can belong to several fabrics at once** (typically -5+). Each controller talks to the device directly and locally; none of them +Matter is that **a device can belong to several fabrics at once** — the spec +requires every certified device to accept at least five; many accept more. Each controller talks to the device directly and locally; none of them knows or cares about the others. A single plug in this house happily serves four admins simultaneously: Apple @@ -322,6 +322,5 @@ reversible. *Further reading:* [INSTALL.md](./INSTALL.md) (setup) · [API.md](./API.md) (Domio ↔ plugin contract) · [IMPLEMENTATION.md](./IMPLEMENTATION.md) (internals) · -ADR-0006 in the Domio repo (the architecture decision behind the share model) · [Home Assistant's Matter docs](https://www.home-assistant.io/integrations/matter/) (an excellent ecosystem-neutral primer that inspired this page). diff --git a/docs/PRD-indigo-matter-plugin.md b/docs/PRD-indigo-matter-plugin.md index cfa16db..e8519c0 100644 --- a/docs/PRD-indigo-matter-plugin.md +++ b/docs/PRD-indigo-matter-plugin.md @@ -11,8 +11,8 @@ > are stale — e.g. decommission is now `POST …?nodeId=`, not `DELETE`), > [`MATTER.md`](./MATTER.md) for architecture/landscape (incl. the corrected > Thread position), [`INSTALL.md`](./INSTALL.md) for setup, and -> [`HANDOVER.md`](./HANDOVER.md) for current state. The ADR is **ADR-0006** -> in the Domio repo (mirrored as workspace ADR-0004), not the 0001 path below. +> [`HANDOVER.md`](./HANDOVER.md) for current state. The architecture decision +> (the share model) is summarised in [`MATTER.md`](./MATTER.md), not the 0001 path below. > > Still genuinely pending from this PRD: **M11 — Plugin Store submission**, > and OQ4's "Indigo admin removed externally" detection beyond basic @@ -20,8 +20,8 @@ **Status:** Historical — shipped (see banner) **Owner:** Simon -**Related ADR:** ADR-0006 in the Domio repo (= workspace ADR-0004) -**Companion PRD:** Domio Matter Commissioning (in Domio repo) — also shipped +**Related ADR:** maintained privately; the decision is summarised in [`MATTER.md`](./MATTER.md) +**Companion PRD:** Domio Matter Commissioning — also shipped **Last updated:** 2026-05-15 (content); 2026-06-10 (status banner) ## 1. Summary diff --git a/docs/matter.html b/docs/matter.html index 6afeafd..9111d89 100644 --- a/docs/matter.html +++ b/docs/matter.html @@ -117,12 +117,11 @@

Bluetooth, commissioning, and why this plugin needs neither

BLE radios and, for Thread, the network credentials. A headless Mac running Indigo is a poor first commissioner — matter-server runs without BLE on macOS, and macOS has no Thread credential store.

-

This plugin sidesteps the problem entirely with the share model (the - architecture decision recorded as ADR-0006):

+

This plugin sidesteps the problem entirely with the share model — + the plugin’s founding architecture decision:

An ecosystem you already own commissions the device first — it owns the Bluetooth step. Then the device is shared to Indigo over plain IP. Indigo never - needs BLE, Thread credentials, or proximity to the device.ADR-0006 · the share - model
+ needs BLE, Thread credentials, or proximity to the device.The share model

That’s only possible because of Matter’s best feature: multi-admin.

@@ -133,7 +132,8 @@

Bluetooth, commissioning, and why this plugin needs neither

Fabrics & multi-admin: one device, many controllers

A Matter fabric is a controller’s trust domain — a set of cryptographic credentials a controller installs on a device. The crucial design choice in Matter is that - a device can belong to several fabrics at once (typically five or more). + a device can belong to several fabrics at once — the spec requires + every certified device to accept at least five; many accept more. Each controller talks to the device directly and locally; none of them knows or cares about the others.

A single plug in this house happily serves four admins simultaneously:

diff --git a/indigo-matter.indigoPlugin/Contents/Info.plist b/indigo-matter.indigoPlugin/Contents/Info.plist index c53ce8d..a1d2883 100644 --- a/indigo-matter.indigoPlugin/Contents/Info.plist +++ b/indigo-matter.indigoPlugin/Contents/Info.plist @@ -20,7 +20,7 @@ IwsApiVersion 1.0.0 PluginVersion - 2026.2.23 + 2026.2.24 ServerApiVersion 3.6 From acde0483ff8e6d85a3dd7f96cf794e7a781080d4 Mon Sep 17 00:00:00 2001 From: Simon Clark Date: Fri, 12 Jun 2026 23:42:43 +0100 Subject: [PATCH 2/3] docs: firmware also arrives via ecosystem OTA providers, not only vendor apps Apple Home auto-updates Matter accessory firmware (observed on the house Tapo plug); the vendor app just typically gets releases first. Soften the vendor-app-only framing in MATTER.md and matter.html. Co-Authored-By: Claude Fable 5 --- docs/MATTER.md | 9 ++++++--- docs/matter.html | 8 ++++++-- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/MATTER.md b/docs/MATTER.md index 7257802..fa62d6b 100644 --- a/docs/MATTER.md +++ b/docs/MATTER.md @@ -270,9 +270,12 @@ energy metering and battery merge into the primary device's states. ## Firmware updates (and why they matter more than usual) -Matter devices typically receive firmware through their **vendor's app**, and -vendors are still actively *adding Matter features* via firmware. Real -example from this house: a Tapo P110M energy plug shipped exposing only on/off +Matter firmware arrives by two routes: the device **vendor's app**, and the +ecosystems themselves — those that act as Matter OTA providers push updates +too (**Apple Home auto-updates Matter accessory firmware**; observed on this +house's Tapo plug). The vendor app typically gets releases first, so check +there when you're waiting on a feature. And vendors are still actively +*adding Matter features* via firmware. Real example from this house: a Tapo P110M energy plug shipped exposing only on/off over Matter — the energy-measurement clusters (a Matter 1.3 feature) appeared only after a firmware update via the Tapo app. The plugin re-reads a node's capabilities whenever it rejoins, so the existing Indigo device **gained its diff --git a/docs/matter.html b/docs/matter.html index 9111d89..87bcf8f 100644 --- a/docs/matter.html +++ b/docs/matter.html @@ -315,8 +315,12 @@

What’s supported

§ 10

Firmware updates — they matter more than usual

-

Matter devices typically receive firmware through their vendor’s app, - and vendors are still actively adding Matter features via firmware.

+

Matter firmware arrives by two routes: the device vendor’s app, and + the ecosystems themselves — those that act as Matter OTA providers push updates too + (Apple Home auto-updates Matter accessory firmware; observed on this + house’s Tapo plug). The vendor app typically gets releases first, so check there when + you’re waiting on a feature. And vendors are still actively adding Matter + features via firmware.

A Tapo P110M shipped exposing only on/off over Matter. The energy clusters appeared after a firmware update — and the existing Indigo device gained its energy states automatically. No restart, no re-pairing.Field note, this house, From b1ccb5c4c66d1ea6d3c9cda4f5b43f658be616d2 Mon Sep 17 00:00:00 2001 From: Simon Clark Date: Fri, 12 Jun 2026 23:44:03 +0100 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20fabrics=20=E2=80=94=20the=20five-fa?= =?UTF-8?q?bric=20spec=20floor=20is=20also=20the=20typical=20shipped=20cou?= =?UTF-8?q?nt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Many accept more" oversold it: each fabric slot costs persistent storage, so embedded SDKs default to the minimum and most devices ship exactly five. Say "treat five as your planning number" instead. Co-Authored-By: Claude Fable 5 --- docs/MATTER.md | 5 +++-- docs/matter.html | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/MATTER.md b/docs/MATTER.md index fa62d6b..3cde62a 100644 --- a/docs/MATTER.md +++ b/docs/MATTER.md @@ -103,8 +103,9 @@ That's only possible because of Matter's best feature: multi-admin. A Matter **fabric** is a controller's trust domain — a set of cryptographic credentials a controller installs on a device. The crucial design choice in -Matter is that **a device can belong to several fabrics at once** — the spec -requires every certified device to accept at least five; many accept more. Each controller talks to the device directly and locally; none of them +Matter is that **a device can belong to several fabrics at once**. The spec +floor is five — and since each fabric slot costs the device persistent storage, +the floor is also what most devices ship. Treat five as your planning number. Each controller talks to the device directly and locally; none of them knows or cares about the others. A single plug in this house happily serves four admins simultaneously: Apple diff --git a/docs/matter.html b/docs/matter.html index 87bcf8f..da74e1d 100644 --- a/docs/matter.html +++ b/docs/matter.html @@ -132,8 +132,9 @@

Bluetooth, commissioning, and why this plugin needs neither

Fabrics & multi-admin: one device, many controllers

A Matter fabric is a controller’s trust domain — a set of cryptographic credentials a controller installs on a device. The crucial design choice in Matter is that - a device can belong to several fabrics at once — the spec requires - every certified device to accept at least five; many accept more. + a device can belong to several fabrics at once. The spec floor is + five — and since each fabric slot costs the device persistent storage, the floor is + also what most devices ship. Treat five as your planning number. Each controller talks to the device directly and locally; none of them knows or cares about the others.

A single plug in this house happily serves four admins simultaneously: