Rules for agents

Short list, all load-bearing. Each one exists because ignoring it produces a specific, recurring failure.

Validate before claiming done

Zero errors, or it isn't ready. Warnings are advisory; errors are not.

Saying "your diagram is ready" over a file that doesn't compile is the single worst thing an agent can do here, because the user finds out later and stops trusting everything else you said.

Search icons; never guess

npm run marrow -- icons search firewall

Icon ids are not guessable. affinity/tile/switch-multilayer, not affinity/tile/l3-switch. Getting it wrong costs a validation round trip that searching first would have avoided entirely.

Declare meaning; don't rely on inference

tier, zone, ha_pair_with. The engine will not read core-sw-01 and conclude the device is core. Structure drives layout, and structure only exists if you declare it.

Look at the result

snapshot then actually open the PNG. See the golden loop.

Never hand-edit generated or vendored trees

• output/ — regenerated on every build; edits are lost and misleading.
• icon-packs/**/svg/ — vendor artwork, replaced by icons fetch.
• node_modules/ — obviously.

One dev server per port

Check whether something is already listening on 5200 before starting another. A stale server serving an old directory looks exactly like a bug in the tool.

Never write credentials

No SSH passwords, no SNMP community strings, no API keys, no secrets in YAML — and especially not in a file that will be committed or in a diagram that will be shared. config: snippets are shown in the inspector of a file that's designed to be emailed around. Sanitize them.

Don't commit unless asked

Authoring and building are not committing. Wait to be asked.

legacy-v1/ is reference only

The archived Python v1. Don't author from it, don't build with it. Use marrow import to bring old YAML forward.

Delete x-v1-config: on sight

Inert. It records v1's engine × layout matrix, which v2 does not have and never reads. Leaving it in place makes the next reader expect outputs that will never appear.

When the picture is wrong, the description is wrong

There is no layout: key and nothing to drag. Resist the urge to reach for pin: — it bypasses placement, can create the overlaps that fail the build, and rots the moment the topology changes. Fix the structure instead.