draft-hold

macOS quirks this skill handles for you

• Quote serialization: Notes' AppleScript body getter re-emits every " as the semicolon-less legacy entity &quot (verified 2026-06-29). We decode with textutil (a real HTML parser) instead of sed, so &quot/&amp/&lt etc. round-trip back to literal characters. Never hand-roll entity decoding here. The read-back verify now DETECTS a drift here automatically (✗ ENTITY-LEAK). A real HTML parser is not sufficient on its own (fixed 2026-07-20): because the stored form is semicolon-LESS, a note holding Write-Host "x"; $y comes back raw as Write-Host &quotx" $y, and textutil reads the closing &quot plus the author's own ; as one entity — silently eating the semicolon, so it round-tripped as Write-Host "x" $y. That corrupts most staged PowerShell/C/Java/JS with no error, which is fatal for a skill whose job is staging text a human will SEND. terminateLegacyEntities() in notes-core.ts now appends the ; to every bare entity before decoding, so a following literal ; stays literal. This is safe unconditionally because Notes escapes every & it stores (an author's literal & comes back as &ampamp;), so a terminated entity in Notes output can only ever be bare-entity + the author's semicolon.
• UTF-8 decode needs an explicit charset: textutil -format html assumes Latin-1 when the HTML has no charset declaration, mojibaking every non-ASCII character (关于 → 关于; verified 2026-07-02 with a Chinese draft). htmlToText therefore prepends <meta charset="utf-8"> before piping to textutil — keep that prefix.
• Note name = first body line, TRUNCATED: Notes names a note after its first line, ignoring any title you "set". new therefore prepends the title as a bold first line so get/list/replace can find it by title. Pass the message body only on STDIN. But Notes truncates a long first line to a capped name ending in an ellipsis … (verified 2026-07-20: a 66-char title stored as …(2026-07-20…), so an exact whose name is <title> lookup MISSES long-titled notes. The engine handles this: new reads its note back by id (not title) for the verify, and get/sticky/move-note resolve a title to a note truncation-tolerantly via noteNameMatchesTitle() (exact, else the stored name is the title truncated with a trailing …). Never rely on exact-name AppleScript matching for a possibly-long title.
• Proportional prose, monospace only in fences: prose paragraphs render in Notes' normal proportional font (so a long line reflows). Only ``` fenced blocks are wrapped in <tt> (Notes' "Monostyled" face) with spaces held as  . The mono face is fixed by Notes — it is not the global NSFixedPitchFont, which governs TextEdit-style apps, not Notes.

Getting the session UUID for provenance

Pass the current Claude Code session JSONL UUID via CLAUDE_SESSION_ID or --session so the note traces back to its session. If you don't know it, the statusline-tools:session-info skill reports it, or read the newest *.jsonl under ~/.claude/projects/<project-slug>/. If genuinely unavailable, omit it (the footer drops the token — never write a placeholder).

Rules

• Never send/commit from memory — always get the note first; the operator may have changed it.
• Notes is the source of truth. Stickies cannot be read back (no AppleScript dictionary), so never treat a sticky as the live draft.
• There is no scriptable deep-link to a specific note (open x-coredata://… fails; applenotes: links are UI-only) — reference drafts by folder + title.
• First run prompts once for Automation permission to control Notes.

Evolution log

• 2026-07-20 (b) — unified the truncation-match rule into one home (DRY). The 2026-07-20 (a) fix left the exact-then-truncated matching rule in TWO places: noteNameMatchesTitle() in notes-core.ts (used by draft-hold) AND a hand-copied AppleScript scan inside notes.ts OSA_MOVE, guarded only by a "keep the two rules in step" comment. Fix: added pure matchNoteIds(index, title) to notes-core.ts (exact ids first, else truncation-tolerant; returns every match so callers can flag ambiguity). move-note now indexes the source folder (OSA_NOTE_INDEX_BY_PATH), resolves the title in TS via matchNoteIds, and moves by id (OSA_MOVE_BY_ID); the name-matching AppleScript is deleted. draft-hold's own resolver + dedup route through matchNoteIds too. One rule, unit-tested (5 new tests, 30 total), impossible to drift. Invariant recorded in the plugin CLAUDE.md (#8).
• 2026-07-20 (a) — long titles broke read-back verify + move-note (name truncation). Trigger: parking a 66-char draft ("CPC Scanners — Procurement Intelligence & Deliverables (2026-07-20)") returned a false ✗ CONTENT-MISMATCH, and move-note "<that title>" then failed with "note not found in source folder", even though the note existed and its body was correct. Root cause: macOS Notes stores a long first-line name TRUNCATED with a trailing …, so new's read-back (body of note <title> of folder) and move-note's whose name is <title> both looked up a name that no longer equalled the title. Fix: added the pure, unit-tested noteNameMatchesTitle() + NOTES_NAME_ELLIPSIS to notes-core.ts (exact, else truncated-prefix match); new now verifies by id (OSA_GET_BY_ID) and dedups older copies via a JS-side folder index; get/sticky resolve title→id truncation-tolerantly; move-note (notes.ts) falls back to a truncated-prefix scan that captures matches by id (a live notes of src reference held past the loop throws -1728). Evidence: a 125-char-title probe now creates (clean id, no CONTENT-MISMATCH), gets its body, and move-notes across folders — all green; 5 new unit tests (25 pass total). Verified live on macOS Notes.
• 2026-07-18 (b) — migrated into notes-commander + hardened. The standalone draft-hold plugin was folded into the new notes-commander plugin as one of its skills; formatting + process wrappers moved to the shared scripts/lib/notes-core.ts engine. Added, per a web-researched audit of recent macOS AppleScript failure modes: silent-no-op detection (isNoteId on create — osascript can exit 0 yet create nothing on macOS 26), bounded retry on transient AppleEvent errors (-600/-1712), and a default-on read-back verify (entityLeaks + contentPresent). All pure helpers unit-tested (16 tests in notes-core.test.ts).
• 2026-07-18 (a) — hard-wrapped prose became forced mid-sentence breaks. A long bilingual briefing was passed with each paragraph pre-wrapped at ~100 chars; because the old bash new made each input line its own Notes paragraph (all wrapped in <tt>), the reader saw mid-sentence line breaks that did not reflow. First fix (insufficient): a "one line per paragraph" caller contract — but that only works if every caller remembers it. Real fix: reimplemented the engine as Bun/TypeScript, enforcing the formatting in code so the failure is impossible: prose blocks REFLOW (consecutive lines join; blank line = paragraph), list markers stay per-item, and only ``` fenced blocks are preserved verbatim/monospace (spaces held as  ). Verified by unit tests + a live Notes round-trip.

Post-Execution Reflection

After holding or sending a draft, check before closing:

1. Did read-back match what Notes shows? — if entities/quotes leaked (e.g. &quot), the decode path drifted; the verify step should have caught it — fix the textutil step in notes-core.ts, never hand-roll sed.
2. Did get/list find the note by title? — if not, the name==title assumption broke; fix the title-prepend in new.
3. Did Notes/Stickies change behavior? — update the macOS-quirks section so the next run doesn't rediscover it.

Only update if the issue is real and reproducible — not speculative.