From 47b1abd3da06f475650d107c5dcce0a82e6ca590 Mon Sep 17 00:00:00 2001 From: Christopher Warner Date: Sat, 10 Oct 2026 19:10:12 -0400 Subject: docs(skill): fold Title-style gotcha into continuous learning Capture the update TopoText regression, Apple list shortcuts, and the instinct/learnings loop so agents do not regress or advise recreate-only. Co-authored-by: Cursor --- SKILL.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 8 deletions(-) diff --git a/SKILL.md b/SKILL.md index 3365d97..b4118a9 100644 --- a/SKILL.md +++ b/SKILL.md @@ -4,8 +4,8 @@ description: >- Create or update real Apple Notes on the user's iPhone by driving icloud.com/notes from Linux with the Rust icloud-note CLI (headless Chromium). Use when the user asks to create/update a note, send/forward results to their - iPhone, push text to Apple Notes, or mentions icloud.com/notes / iCloud Notes - from Linux. + iPhone, push text to Apple Notes, mentions icloud.com/notes / iCloud Notes + from Linux, or notes look huge / all Title after an update. --- # iPhone notes via icloud.com/notes (Rust) @@ -31,7 +31,7 @@ to `create` unless the user explicitly asks to create. Repo: `~/Code/iphone-notes` Binary: `~/.local/bin/icloud-note` -Skill link: `~/.agents/skills/iphone-icloud-notes` → that repo +Skill: `~/.agents/skills/iphone-icloud-notes` → that repo (`SKILL.md` here) ## Helper @@ -51,16 +51,67 @@ re-auth is required. Do **not** set `ICLOUD_NOTES_DRY_RUN=1` for real sends. Config/session: `~/.config/icloud-notes/` (cookies / Chromium profile). **Private — never commit, paste into chat, or upload.** See `SECURITY.md`. +## Formatting (Apple Notes guides) + +Prefer Apple Notes–shaped Markdown. The CLI rewrites before write: + +| Input | Notes result | +|---|---| +| First line / `--title` | **Title** | +| `##` / `###` | Heading / Subheading | +| `*` list | Bulleted (`•`) | +| `-` list | Dashed (`–`) — Apple typing shortcut | +| `1.` | Numbered | +| `- [ ]` / `- [x]` | Checklist ☐ / ☑ | +| `---` | Divider stand-in | +| `>` | Block quote (`│ …`) | +| pipe table | Aligned monospaced grid | + +Apple docs: +- https://support.apple.com/guide/iphone/create-and-format-notes-iph1ac0b3a2/ios +- https://support.apple.com/guide/notes/format-notes-apd1955d3b21/mac +- https://support.apple.com/guide/notes/add-lists-apd93c815aa0/mac + +Preview without sending: `ICLOUD_NOTES_DRY_RUN=1 icloud-note create …` + +## [PERMANENT] Title-everywhere bug (do not regress) + +**Symptom:** After `update`, every line is huge (**Title** style). + +**Cause:** `Note.createInitialTopoTextString(text)` applies “New notes start with +Title” to **every** paragraph. + +**Correct update path (in `src/browser.rs` → `writeNoteText`):** +1. Scratch = `Note.createNoteWithTitleText(text, folder)` (first line Title, rest Body) +2. `topoTextManager.load(existingNote.id, scratch.TopoTextString)` +3. `removeUnsavedItem(scratch)` (or `didDeleteNote`) +4. Only then fall back to `createInitialTopoTextString` + +**Do not** “fix” by telling the user they must permanently create a new note. +Re-`update` with a binary that has the scratch path. Create-once is only a +temporary workaround. + +Regression guard: `browser::tests::update_write_prefers_styled_create_scratch`. + ## Agent workflow 1. Decide **create** vs **update** from the user’s wording. 2. `icloud-note status` — if not logged in, ask for `icloud-note login`. 3. Run create or update with `--title` + `--body-file` for long text. - Prefer Apple Notes–shaped Markdown: `##` headings, `*` for bullets, `-` for - dashed lists, `- [ ]` checklists, `---` dividers, `>` quotes, short paragraphs. - The CLI reformats to Notes style (title, Heading/Subheading, • / – / ☐ / ☑). - See Apple: https://support.apple.com/guide/iphone/create-and-format-notes-iph1ac0b3a2/ios -4. Report the `created:` or `updated:` line. +4. If the user says the note is all big/Title after an update: rebuild/install + latest `icloud-note`, then **re-update** the same title (do not duplicate). +5. Report the `created:` or `updated:` line. + +## Continuous learning (after Notes work) + +When you learn something non-obvious about this CLI / iCloud Notes web APIs: + +1. Record an instinct (`instinct-learning` skill / `main.cjs --action record`). +2. Append `~/.config/goose/memory/learnings.md` (and `issues.md` for gotchas). +3. Patch **this** `SKILL.md` in the repo (symlink already points here). +4. Keep tests green (`./tests/run.sh`); Title-style regression test must stay. + +Tags useful for instincts: `icloud-notes`, `apple-notes`, `topo-text`. ## Setup (human / once) -- cgit v1.2.3