Wiring jots

Line format

<harness> <color> <from> <to> <purpose...>

Example: dash RD batt.1 ign.1 constant 12v feed

• One wire per line, space separated. Purpose runs to end of line.
• Only lines inside a ```jot block are parsed. Blank lines and # lines are skipped.
• Connector names are free-form (batt, ecu, gnd, battery+). Same name across notes = same connector.
• Pin numbers are arbitrary integers; they get sorted and labelled automatically.

Endpoints

Fields 3 and 4 are endpoints. An endpoint is either name.pin, or a bare name with no dot, in which case the pin defaults to 1.

chassis RED battery+ fusebox main feed   ->  battery+.1 -> fusebox.1, purpose "main feed"
chassis RED batt.2 fuse.7 main feed      ->  batt.2 -> fuse.7,        purpose "main feed"

Names may contain letters, digits, _, - and +, so battery+ is a legal connector name. A name may not contain a dot: foo.bar is neither a bare name nor name.pin, and is a hard error naming the file, line number and offending endpoint.

Unrouted wires

Jot a wire before you know where it lands by putting ? in field 3. Everything after it is the purpose.

<harness> <color> ? <purpose...>

Example: engine BL ? AC compressor clutch

Precedence, in order:

1. Field 3 is ? → unrouted, purpose is fields 4 onward.
2. Fewer than 4 fields → unrouted, purpose is fields 3 onward. engine BL AC still works.
3. Otherwise → routed, fields 3 and 4 are endpoints.

Five or more fields without ? is always routed

Because bare names count as endpoints, engine BL AC compressor clutch no longer means “unrouted, purpose AC compressor clutch” — it parses as AC.1 -> compressor.1 with purpose clutch, and silently invents two connectors. Any unrouted wire whose purpose runs to two or more words needs the explicit ?. The three-field short form only survives because there is no field 4 to consume.

Unrouted wires still appear in the harness with their colour and label, as a stub with nothing attached at either end — so the wire is on the diagram and in the BOM while the routing is still unknown.

Harnesses with no routed wires

A cable with zero connections has no edge to hang off, and WireViz drops it from the diagram entirely — which is exactly what a brand-new harness looks like the moment you first jot one. Every wire of such a harness is instead attached to a synthetic yellow ? connector marked not yet traced, so the cable, its colours and its labels all render. The placeholder is kept out of the BOM, and stderr carries a warning:

warning: harness 'chassis' has no routed wires - rendered against a placeholder

A harness with at least one routed wire never gets a placeholder — its unrouted wires stay plain stubs.

Colors

BL means blue

WireViz has no BL code of its own, so it used to fall through to black — the worst possible silent failure on a wiring diagram. BL is now an alias for BU (blue).

Two letters = solid. Base + stripe is the two codes concatenated, e.g. RDBK red with black stripe, GNWH green/white, BNWH brown/white. Aliases work on both halves, so BLBK and BLUBLK both mean blue with a black stripe.

Aliases are case-insensitive. Anything that still does not resolve to a real WireViz colour is a hard error naming the file, line number and offending code — the render stops rather than guessing.

The full WireViz palette is BG BK BN BU CU GD GN GY IV LB OG OL PK RD SL SN SR TQ VT WH YE.

Render

~/coding/wiring_diagram/render.sh            # all notes -> out/car.png
~/coding/wiring_diagram/render.sh dash       # -> out/dash.png
~/coding/wiring_diagram/render.sh dash engine

Output lands in ~/coding/wiring_diagram/out/. Every run prints a wire count to stderr, followed by a per-harness breakdown, so a typo’d line that got skipped as prose shows up as a wrong total and a whole harness going quiet is visible on its own line:

12 wires (10 routed, 2 unrouted)
  chassis  1 wire   (0 routed, 1 unrouted)
  dash     5 wires  (5 routed, 0 unrouted)
  engine   6 wires  (5 routed, 1 unrouted)

On success the PNG is also copied into diagrams/ in this folder, so it syncs to the phone and previews inline below. Same basename each time, so a re-render overwrites rather than piling up. That folder is gitignored.

Jots kept in Apple Notes render with --notes / --notes-prefix instead — see below.

Apple Notes capture

Jots do not have to live in the vault. notes2jot.py reads Apple Notes and emits the same jot lines, which is what makes dictating a wire to Siri while standing at the car workable. Downstream the pipeline is identical.

There are no ```jot fences in Apple Notes. Every line of the note is tested and only lines whose second field resolves to a wire colour are kept. Titles, sentences and reminders fail that test and are dropped silently, so prose and jots can share one note without ceremony.

Notes are read through the AppleScript plaintext property, which hands back the note as clean newline-separated text. Nothing in the pipeline parses or strips HTML.

Two ways to mark a note as wiring

The two markers are independent and neither knows about the other, so a note can carry both. Choose per note, not per project.

The prefix match is done by Notes itself:

tell application "Notes" to get name of every note whose name starts with "w:"

That filter never opens a note body, so it stays cheap across the whole library — roughly 0.2s over 430 notes, against 11s to read all 430 bodies. Only the matching notes get their plaintext fetched. The prefix stays in the title line, and the title line is discarded by the same field-2-must-be-a-colour test that discards prose.

The output basename is the prefix with non-alphanumeric characters stripped, so w: renders to out/w.png and publishes as diagrams/w.png.

Prefix mode also sees Recently Deleted

every note whose name starts with "w:" spans the whole library including the trash, so a w: note you deleted keeps rendering for the 30 days it sits in Recently Deleted. Empty the trash, or rename the note before deleting it. Filtering it out server-side is not possible — container is missing value on a trashed note and Notes errors with Can’t make missing value into type folder if you put it in the whose clause. Folder mode is unaffected.

Hashtags cannot be used

#wiring inside the note body is the obvious marker and it does not work. The Notes AppleScript dictionary exposes no tag class, no hashtag property and no smart-folder class — tags exist only inside the app’s UI. Finding #wiring would mean pulling the body of every note in the library and searching it here, which costs ~11s today and gets worse as the library grows. Folder and title prefix are the only markers the app can filter on. Do not retry this.

Current diagram

Notes

• pipeline — how this works and why (WireViz, jot2wv, design decisions)
• dash
• engine
• cluzter — GUI successor project (2026-07-30). This grammar is its import format and its omnibox syntax, so keep the five fields stable. Note the colour-code standards differ: this pipeline speaks WireViz codes (BL aliased to BU), cluzter defaults to JIS/Suzuki slash notation where Bl/G means blue-with-green-tracer — same trap, different spelling (cluzter-wiring-gotchas)