docs(export): E8 — user documentation for the Matter export bridge [no-release] - #129
Closed
simons-plugins wants to merge 3 commits into
Closed
docs(export): E8 — user documentation for the Matter export bridge [no-release]#129simons-plugins wants to merge 3 commits into
simons-plugins wants to merge 3 commits into
Conversation
INSTALL.md gains an "Exporting Indigo devices" section: prerequisites (Node >=22.13, the second npm package and the fact it is not yet published), first-export walkthrough, the pairing window and its security caveat, the expected "uncertified accessory" prompt with the Homebridge/matterbridge precedent per ADR-0006, removal/unpairing/stopping, and the two destructive recovery actions in the same words their dialogs use. Backups now cover the bridge storage dir (and no longer claim the backup menu is a stub — it has not been one since fabric_backup landed). Troubleshooting is split into controller and export-bridge tables, the latter sourced from the log strings the code actually emits. MATTER.md gains the outbound architecture section at the depth of the inbound one: the two processes, why the bridge node exists, the opt-in allow-list and why, fabrics (Apple takes two slots), endpoint identity and why it must never move, the v1 role table and the excluded set with reasons — both checked against export_catalog.py — and the honest ecosystem statement per ADR-0007. README.md's lede now shows both roles, with export's status stated as built-but-not-yet-live-validated. Three drifts fixed rather than papered over: * PRD 5.2's sensor rows implied a fixed unit->type mapping; the code offers the roles as a user choice with the unit heuristic picking only the default. * PRD 5.2's excluded set was missing the "reports neither an on/off state nor a value" sensor exclusion, which has always been in the code. * PRD 5.3 called indigo-matter-bridge a "published" npm package while 9's E7 row says it is not on the registry. PRD 9's E7/E8 rows are updated for what shipped; bridge-node/README.md no longer claims Alexa/Google/SmartThings. Nothing is claimed that the code does not do. Stated as unfinished: the unpublished npm package, XAC3/XAC5's pending live validation, the pairing page's dependence on Indigo Web Server auth, the no-declared-units limitation, and per-ecosystem export sets being v2. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxqGhP3DcENf68AZK21U4S
The build agent, checking HANDOVER rather than trusting the brief, wrote that no live Apple Home pairing had happened. HANDOVER was stale: the E0 gate paired an uncertified bridge into Apple Home with the prompt accepted, E3 controlled a light and a dimmer both directions, and the E5 upgrade kept three accessories' identity with no duplicates — all on the reference server, all in this session's logs. The caution was right in kind and wrong in fact, so both docs now list what was actually done and what genuinely is not: pairing through the plugin's own menu (the E0 pairing was driven from the node's console), a second admin alongside Apple, the reboot leg, and the LaunchAgent end to end. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxqGhP3DcENf68AZK21U4S
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Two whole-doc reviews — an accuracy pass falsifying every claim against the code, and a reader-experience pass following the guide cold. Accuracy (each verified on this branch): * The drift troubleshooting row prescribed a hand-copy out of a backup zip for a non-fault: node.ts:868-880 says drift after a factory reset is EXPECTED and is what the preserved map exists to report, and factoryReset() runs on both "Reset Matter Export Pairings…" and unpairing the last ecosystem — both of which this same doc walks users through. Expected-cause first, no action; storage loss second. * MATTER.md documented an exclusion the code cannot produce: a device this plugin created hits REASON_LOOP_GUARD before any type reasoning (export_catalog.py:232) and is then absent from the picker (plugin.py:1843), so it can never reach REASON_NO_ROLE. Energy meters moved to the loop-guard row; the no-role row now says what actually triggers it. * kPa was listed among the units taken on trust. Pressure is the one unit that IS converted (export_handlers.py:895-918 divides by HPA_PER_KPA), so as written a barometer owner would "fix" their sensor into the 10x error the code exists to prevent. * Apple Home finds "Indigo Matter Bridge" (node.ts:71 PRODUCT_NAME), not "Indigo" — that is what the user scans a phone screen for. * The picker is capped at EXPORT_PICKER_LIMIT = 300 with a truncation row, not "every Indigo device". * Export needs Node (Step 1) and a storage path (Step 3), not a healthy matter-server — "everything in Steps 1-4 working" contradicted MATTER.md's own "one can be broken while the other works". * Smaller: PROTOCOL not plugin version; the offered-role order for a full-colour dimmer per _dimmer/_default_first; the port-reload note is in the Matter port's Description only; Restore fabric backup's stated precondition; bridge_agent's docstring still called the package "published". Reader experience: * The npm blocker now leads the export section instead of arriving 250 lines in, and is echoed in the overview bullet and MATTER.md. * "You only pair the bridge once per ecosystem" added to Step E2 — guessing wrong means opening an unnecessary pairing window, which the security section says exposes the house. * Destructive actions ordered by recoverability, Rebuild (unrecoverable) first; the unpair row carries the last-ecosystem factory-reset consequence. * INSTALL retitled for both runtimes, with a contents list routing to the three export subsections that do not sit under the export heading. * "fabric" defined on first use; the two-node-processes fact stated up front. * Troubleshooting reordered to put observable symptoms before log strings, with rows for the two most likely first failures (exported but never paired; Add Accessory cannot find the bridge). EADDRINUSE now covers both its ports; the pressure/flow and room-change rows give a verdict rather than a hedge. * MATTER.md leads with the can/cannot-export tables; the identity subsection leads with its instruction; the status inventory lives in README only. * matter-server is Beta everywhere (upstream's own word). Status corrections, with dates, so HANDOVER and the PRD stop contradicting the README they are cited from: E0's pairing gate PASSED 2026-08-04, E3's live two-way E2E PASSED 2026-08-05, E5 deployed to jarvis 2026-08-05 with the upgrade migration observed (endpoints 3/5/4 kept, no duplicates). Pairing through the plugin's own menu, the second-admin proof, XAC5's reboot leg and E6/E7 end-to-end stay marked outstanding. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxqGhP3DcENf68AZK21U4S
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The final milestone. User-facing documentation for the export half, stacked on #128 — merge that first.
export_catalog.py), then two processes, the opt-in allow-list and why publication is the reason, fabrics and Apple's two slots, endpoint identityDoc/code disagreements found and fixed
Sensor rows implied unit→type when the code offers a choice with the unit picking only the default; a missing exclusion reason;
indigo-matter-bridgedescribed as "published" when it is not on the registry (in the PRD and inbridge_agent.py's docstring); the colour-temp downgrade path undocumented; E7's three new lifecycle menus missing. Also removed stray</content>artifacts that were rendering on the repo front page and in the published guide.Then a second, consolidated review batch (commit
docs(export): apply E8 review findings) against the code on this branch:node.ts:868-880says is expected after a factory reset — and both menu paths this doc walks users through trigger oneexport_catalog.py:232) and those devices are then absent from the picker (plugin.py:1843), so they never reachREASON_NO_ROLEexport_handlers.py:895-918)node.ts:71), not "Indigo"plugin.py:110), not "every Indigo device"Restore fabric backup…'s stated precondition; matter-server is Beta everywhere (upstream's own word), not Alpha in some placesStatus corrections
HANDOVER and the PRD said nothing had met a real ecosystem while README said the opposite. They now agree, with dates: E0's pairing gate PASSED 2026-08-04, E3's live two-way E2E PASSED 2026-08-05, E5 deployed to jarvis 2026-08-05 with the upgrade migration observed (three accessories kept endpoints 3/5/4 — their pre-upgrade values, out of creation order — with no duplicates). Pairing through the plugin's own menu, the second-admin proof, XAC5's reboot leg and E6/E7 end to end stay marked outstanding.
Deliberately not claimed
No Alexa/Google/SmartThings support (ADR-0007). No certified language. No ecosystem accessory caps.
Needs Simon
npm publish— everything in E6/E7 end-to-end is behind it (the local-install recipe in HANDOVER covers a dry run).docs/matter.htmlanddocs/index.html.matter.htmlis hand-built from an earlierMATTER.mdand carries zero export content, andindex.html's standfirst still says "two long reads" with no route to the export material or to INSTALL. Until that is done the published Field Notes site under-sells the feature, so README's export lede now points atdocs/MATTER.mddirectly. Recorded in HANDOVER → Deferred / not done.🤖 Generated with Claude Code
https://claude.ai/code/session_01JxqGhP3DcENf68AZK21U4S