summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristopher Warner <cwarner@kernelcode.com>2026-10-10 19:10:12 -0400
committerChristopher Warner <cwarner@kernelcode.com>2026-10-10 19:10:12 -0400
commit47b1abd3da06f475650d107c5dcce0a82e6ca590 (patch)
treec180f230831e440a13ec3f3f11926f1063b89d7a
parent0b3d1a7cab856fb77cf8a89e40108e1a49d60e5f (diff)
downloadiphone-notes-47b1abd3da06f475650d107c5dcce0a82e6ca590.tar.gz
iphone-notes-47b1abd3da06f475650d107c5dcce0a82e6ca590.tar.bz2
iphone-notes-47b1abd3da06f475650d107c5dcce0a82e6ca590.tar.xz
iphone-notes-47b1abd3da06f475650d107c5dcce0a82e6ca590.zip
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 <cursoragent@cursor.com>
-rw-r--r--SKILL.md67
1 files 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)