summaryrefslogtreecommitdiff
path: root/SKILL.md
blob: b4118a9e85e26a24af90850b99b32c3630938582 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
---
name: iphone-icloud-notes
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, mentions icloud.com/notes / iCloud Notes
  from Linux, or notes look huge / all Title after an update.
---

# iPhone notes via icloud.com/notes (Rust)

## Goal

Drive real Apple Notes through the iCloud Notes web app using the **Rust**
`icloud-note` binary. Do not use LocalSend unless the user wants file transfer.

## Create vs update (important)

| User intent | Command |
|---|---|
| New note / first send | `icloud-note create …` |
| Change / revise / refresh an existing note | `icloud-note update …` |

**Never use `create` when the user asks to update** — that would add a duplicate
note. `update` finds the note by title (case-insensitive) and replaces its
content in place. If no matching note exists, report the error; do not fall back
to `create` unless the user explicitly asks to create.

## Source of truth

Repo: `~/Code/iphone-notes`  
Binary: `~/.local/bin/icloud-note`  
Skill: `~/.agents/skills/iphone-icloud-notes` → that repo (`SKILL.md` here)

## Helper

```bash
icloud-note status
icloud-note login          # ONE-TIME only — only command that opens a window
icloud-note create --title "Title" --body "Body text"
icloud-note update --title "Title" --body "Revised body"
icloud-note update --title "Title" --body-file /path/to.txt
# optional: search under a different title than the new first line
icloud-note update --match-title "Old Title" --title "New Title" --body "…"
```

`create` / `update` / `status` are **always headless**. Never run `login` unless
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.
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)

```bash
"$HOME/Code/iphone-notes/scripts/setup.sh"
icloud-note login
```