macos-notes

# macOS Notes

Manage Apple Notes via `$SKILL_DIR/scripts/notes.sh`. Notes content is stored as HTML internally; the script accepts plain text or HTML body and returns plaintext when reading.

## Quick start

### List folders

Always list folders first to discover accounts and folder names:

```bash
"$SKILL_DIR/scripts/notes.sh" list-folders
```

Output format: `account → folder` (one per line).

### Create a note

```bash
echo '<json>' | "$SKILL_DIR/scripts/notes.sh" create-note
```

JSON fields:

| Field | Required | Default | Description |
|---|---|---|---|
| `title` | yes | - | Note title (becomes the first line / heading) |
| `body` | no | "" | Note content (plain text — converted to HTML automatically) |
| `html` | no | "" | Raw HTML body (overrides `body` if both provided) |
| `folder` | no | default folder | Folder name (from list-folders) |
| `account` | no | default account | Account name (from list-folders) |

### Read a note

```bash
echo '<json>' | "$SKILL_DIR/scripts/notes.sh" read-note
```

JSON fields:

| Field | Required | Default | Description |
|---|---|---|---|
| `name` | yes | - | Note title (exact match) |
| `folder` | no | all folders | Folder to search in |
| `account` | no | default account | Account to search in |

### List notes

```bash
echo '<json>' | "$SKILL_DIR/scripts/notes.sh" list-notes
```

JSON fields:

| Field | Required | Default | Description |
|---|---|---|---|
| `folder` | no | default folder | Folder name |
| `account` | no | default account | Account name |
| `limit` | no | 20 | Max notes to return |

### Search notes

```bash
echo '<json>' | "$SKILL_DIR/scripts/notes.sh" search-notes
```

JSON fields:

| Field | Required | Default | Description |
|---|---|---|---|
| `query` | yes | - | Text to search for in note titles |
| `account` | no | default account | Account to search in |
| `limit` | no | 10 | Max results to return |

## Interpreting natural language

Map user requests to commands:

| User says | Command | Key fields |
|---|---|---|
| "Note this down: ..." | `create-note` | `title`, `body` |
| "Save meeting notes" | `create-note` | `title: "Meeting notes — <date>"`, `body` |
| "What did I write about X?" | `search-notes` | `query: "X"` |
| "Show my notes" | `list-notes` | (defaults) |
| "Read my note about X" | `read-note` | `name: "X"` |
| "Save this in my work notes" | `create-note` | Match closest `account`/`folder` from list-folders |

## Example prompts

**"Note down the API key format: prefix_xxxx"**
```bash
echo '{"title":"API key format","body":"Format: prefix_xxxx"}' | "$SKILL_DIR/scripts/notes.sh" create-note
```

**"Show my recent notes"**
```bash
echo '{}' | "$SKILL_DIR/scripts/notes.sh" list-notes
```

**"What did I write about passwords?"**
```bash
echo '{"query":"password"}' | "$SKILL_DIR/scripts/notes.sh" search-notes
```

**"Read my note about Hinge"**
```bash
echo '{"name":"Hinge"}' | "$SKILL_DIR/scripts/notes.sh" read-note
```

**"Create a meeting summary in my iCloud notes"**
```bash
"$SKILL_DIR/scripts/notes.sh" list-folders
```
Then:
```bash
echo '{"title":"Meeting summary — 2026-02-17","body":"Discussed roadmap.\n- Q1: launch MVP\n- Q2: iterate","account":"iCloud","folder":"Notes"}' | "$SKILL_DIR/scripts/notes.sh" create-note
```

## Critical rules

1. **Always list folders first** if the user hasn't specified an account/folder — folder names are reused across accounts
2. **Specify both account and folder** when targeting a specific location — `folder: "Notes"` alone is ambiguous
3. **Password-protected notes are skipped** — the script cannot read or modify them
4. **Pass JSON via stdin** — never as a CLI argument (avoids leaking data in process list)
5. **All fields are validated** by the script (type coercion, range checks) — invalid input is rejected with an error
6. **All actions are logged** to `logs/notes.log` with timestamp, command, and note title
7. **Body uses plain text** — newlines in `body` are converted to `<br>` automatically; use `html` for rich formatting
8. **Note title = first line** — Notes.app treats the first line of the body as the note name