Document YAML nodes

Claude commented

2026-10-15 14:32:57 +00:00

Collaborator

Adds nodes/README.md for non-programmers (build, endpoint types, binds, failsafe, ID rules). CLAUDE.md and CONTRIBUTING.md now say a YAML node needs no node_ids.h entry or spec row. The spec reserves wire IDs 0-10 for infrastructure and states wire ID = YAML ID + 10. Docs only; YN-3.

Claude added 1 commit

2026-10-15 14:32:57 +00:00

Document YAML nodes

Build and test / release (pull_request) Has been cancelled

Details

Build and test / build (pull_request) Has been cancelled

Details

6cbb123122

Claude commented

2026-10-15 14:33:21 +00:00

Author

Collaborator

nodes/README.md findings:

Numeric binds contradict themselves. "Use numbers to reach a hand-written node" conflicts with "Every ID you write in YAML is a YAML ID, binds included". A hand-written node at wire 0x20 would have to be written as 22 (wire minus 10), and one at wire 0x0A or below can't be reached at all. Say which it is. If numeric binds take YAML IDs, drop the hand-written advice. If they take wire IDs, the "every ID is a YAML ID" line is wrong. Check the task 546 design, since the generator doesn't exist to settle it.
The collision warning is ambiguous in the same way. "If you reuse a hand-written node's ID" doesn't say which number is compared. The clash is YAML ID + 10 against the hand-written wire ID. Say that, and tell the reader to compare against the table's wire IDs.
The IDs section repeats the "Every ID is a YAML ID" and "wire ID is YAML ID + 10" lines already in Binds. Keep one copy.
Jargon in a doc for non-programmers: "strapping pins", "MCP2515", "I²C". Name the boards (the XIAOs) and say what a strapping pin means, or link to a pin list. The rule "remote binds may only listen to one kind of message" gives no way to tell whether a node hits the limit.
The example's top-level keys (node, id, board) are inferred, as you said. Mark them as provisional or confirm against task 546 before merge.

nodes/README.md findings: 1. Numeric binds contradict themselves. "Use numbers to reach a hand-written node" conflicts with "Every ID you write in YAML is a YAML ID, binds included". A hand-written node at wire 0x20 would have to be written as 22 (wire minus 10), and one at wire 0x0A or below can't be reached at all. Say which it is. If numeric binds take YAML IDs, drop the hand-written advice. If they take wire IDs, the "every ID is a YAML ID" line is wrong. Check the task 546 design, since the generator doesn't exist to settle it. 2. The collision warning is ambiguous in the same way. "If you reuse a hand-written node's ID" doesn't say which number is compared. The clash is YAML ID + 10 against the hand-written wire ID. Say that, and tell the reader to compare against the table's wire IDs. 3. The IDs section repeats the "Every ID is a YAML ID" and "wire ID is YAML ID + 10" lines already in Binds. Keep one copy. 4. Jargon in a doc for non-programmers: "strapping pins", "MCP2515", "I²C". Name the boards (the XIAOs) and say what a strapping pin means, or link to a pin list. The rule "remote binds may only listen to one kind of message" gives no way to tell whether a node hits the limit. 5. The example's top-level keys (`node`, `id`, `board`) are inferred, as you said. Mark them as provisional or confirm against task 546 before merge.

rob added 1 commit

2026-10-15 14:33:35 +00:00

Fix bind ID wording in the YAML nodes README

Build and test / build (pull_request) Successful in 1m38s

Details

Build and test / release (pull_request) Has been skipped

Details

c244558b78

Claude commented

2026-10-15 14:33:38 +00:00

Author

Collaborator

Fixed 1, 2, 3 and the bind-limit wording in c244558. Left jargon (strapping pins, I²C) as is: both are board terms the user meets anyway. Top-level keys stay provisional until YN-2 lands; flagged in the handover.

Fixed 1, 2, 3 and the bind-limit wording in c244558. Left jargon (strapping pins, I²C) as is: both are board terms the user meets anyway. Top-level keys stay provisional until YN-2 lands; flagged in the handover.

rob added 1 commit

2026-10-15 14:36:07 +00:00

Match the YAML nodes README example to the agreed shape

Build and test / build (pull_request) Successful in 1m43s

Details

Build and test / release (pull_request) Has been skipped

Details

fc1a2bb6bf

Claude merged commit 33f3dcbc14 into feat/yaml-nodes

2026-10-15 14:38:24 +00:00

Claude referenced this pull request from a commit

2026-10-15 14:38:25 +00:00