apple-notes-mcp 2.5.10 → 2.5.11

package/README.md

@@ -12,7 +12,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 [![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
 
 <p align="center">
-  <img src="codex/assets/screenshot.png" alt="Apple Notes MCP — create, search, and organize Apple Notes from Codex, Claude, and other AI assistants" width="680">
+  <img src="https://raw.githubusercontent.com/sweetrb/apple-notes-mcp/main/codex/assets/screenshot.png" alt="Apple Notes MCP — create, search, and organize Apple Notes from Codex, Claude, and other AI assistants" width="680">
 </p>
 
 ## What is This?
@@ -39,6 +39,12 @@ Install the sweetrb/apple-notes-mcp MCP server so you can help me manage my Appl
 
 Claude will handle the installation and configuration automatically.
 
+Or register it yourself with one deterministic command:
+
+```bash
+claude mcp add apple-notes -s user -- npx -y apple-notes-mcp
+```
+
 ### Using the Plugin Marketplace
 
 Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:
@@ -50,6 +56,8 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 This method also installs a **skill** that teaches Claude when and how to use Apple Notes effectively.
 
+On the first tool call, macOS shows an Automation permission prompt ("Claude" wants access to control "Notes") — click **OK**. Optionally, grant **Full Disk Access** to the app that launches the server to enable the checklist-state and note-metadata features; see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md). Everything else works without it.
+
 ### Using the Codex Marketplace
 
 The same plugin is available for Codex. Add the marketplace and install the plugin:
@@ -65,14 +73,14 @@ The Codex plugin runs the published `apple-notes-mcp` server through `npx` and s
 
 Configuration for two more hosts is included — each registers the same `apple-notes` MCP server (`npx -y apple-notes-mcp`):
 
-- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-notes --command npx --args -y apple-notes-mcp`, or merge [`.hermes-plugin/config.yaml`](.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](.hermes-plugin/README.md).
-- **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
+- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-notes --command npx --args -y apple-notes-mcp`, or merge [`.hermes-plugin/config.yaml`](https://github.com/sweetrb/apple-notes-mcp/blob/main/.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](https://github.com/sweetrb/apple-notes-mcp/blob/main/.hermes-plugin/README.md).
+- **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](https://github.com/sweetrb/apple-notes-mcp/blob/main/.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
 
-### Manual Installation
+### Using Claude Desktop
 
 **1. Install the server:**
 ```bash
-npm install -g github:sweetrb/apple-notes-mcp
+npm install -g apple-notes-mcp
 ```
 
 **2. Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
@@ -81,7 +89,7 @@ npm install -g github:sweetrb/apple-notes-mcp
   "mcpServers": {
     "apple-notes": {
       "command": "npx",
-      "args": ["apple-notes-mcp"]
+      "args": ["-y", "apple-notes-mcp"]
     }
   }
 }
@@ -133,7 +141,7 @@ common workflows: `find-note`, `weekly-review`, `new-meeting-note`.
 ### Known limitations
 
 A few Notes UI features are not exposed to AppleScript and therefore cannot be
-supported. See **[docs/APPLESCRIPT-LIMITATIONS.md](docs/APPLESCRIPT-LIMITATIONS.md)**
+supported. See **[docs/APPLESCRIPT-LIMITATIONS.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/APPLESCRIPT-LIMITATIONS.md)**
 for the investigation and verification behind each:
 
 - **Pinned notes** — Notes has no scriptable `pinned` property via AppleScript. Pin state can now be **read** with the BETA `get-note-metadata` tool (from the NoteStore database), but it still cannot be **set** programmatically.
@@ -155,17 +163,16 @@ Creates a new note in Apple Notes.
 |-----------|------|----------|-------------|
 | `title` | string | Yes | The title of the note. Automatically prepended as `<h1>` — do NOT include the title in `content` |
 | `content` | string | Yes | The body content of the note (do not repeat the title here) |
-| `tags` | string[] | No | Tags for organization (stored in metadata) |
+| `tags` | string[] | No | Returned-only metadata — **NOT written to Notes.app**. Apple Notes tags can't be set via AppleScript, so values passed here are echoed back in the response but do not appear on the created note. Use inline `#hashtags` in `content` instead (Notes.app turns those into real tags) |
 | `folder` | string | No | Folder to create the note in. Supports nested paths like `"Work/Clients"`. Defaults to account root |
 | `account` | string | No | Account name (defaults to iCloud) |
 | `format` | string | No | Content format: `"plaintext"` (default) or `"html"`. In both formats, the title is automatically prepended as `<h1>`. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities |
 
-**Example:**
+**Example (tagged with inline hashtags):**
 ```json
 {
   "title": "Meeting Notes",
-  "content": "Discussed Q4 roadmap and budget allocation",
-  "tags": ["work", "meetings"]
+  "content": "Discussed Q4 roadmap and budget allocation\n\n#work #meetings"
 }
 ```
 
@@ -264,7 +271,7 @@ Retrieves the full content of a specific note.
 **Returns:** The HTML content of the note, or error if not found. The
 `structuredContent` also includes `hashtags` — any inline `#hashtag` tags parsed
 from the body. Apple Notes tags are inline hashtags, not a scriptable property;
-see [docs/APPLESCRIPT-LIMITATIONS.md](../docs/APPLESCRIPT-LIMITATIONS.md#tags--hashtags-29). Smart Folders are not scriptable.
+see [docs/APPLESCRIPT-LIMITATIONS.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/APPLESCRIPT-LIMITATIONS.md#tags--hashtags-29). Smart Folders are not scriptable.
 
 ---
 
@@ -393,7 +400,7 @@ Updates an existing note's content and/or title.
 
 **Note:** `newContent` **replaces the entire note body** — it is not appended. To preserve existing content, read it first (e.g. with `get-note-content`) and include it in `newContent`.
 
-**Attachments:** A full-body replace can drop embedded files, images, scans, PDFs, or audio. When a note may hold attachments, run [`list-attachments`](#list-attachments) first, and either save them with `save-attachment` or build a new note rather than overwriting. See the skill's [Attachment-Safe Updates](skills/apple-notes/SKILL.md#attachment-safe-updates) guidance.
+**Attachments:** A full-body replace can drop embedded files, images, scans, PDFs, or audio. When a note may hold attachments, run [`list-attachments`](#list-attachments) first, and either save them with `save-attachment` or build a new note rather than overwriting. See the skill's [Attachment-Safe Updates](https://github.com/sweetrb/apple-notes-mcp/blob/main/skills/apple-notes/SKILL.md#attachment-safe-updates) guidance.
 
 ---
 
@@ -460,8 +467,6 @@ Moves a note to a different folder. The note is relocated in place via Notes.app
 
 **Returns:** Confirmation message, or error if note or folder not found.
 
-**Note:** This operation copies the note to the new folder then deletes the original. If the delete fails, the note will exist in both locations.
-
 ---
 
 #### `list-notes`
@@ -796,7 +801,7 @@ Run a full setup diagnostic: Notes.app reachability, the Automation permission,
 
 **Parameters:** None
 
-**Returns:** A per-check report (`structuredContent` carries the raw `{healthy, checks[]}`). The Full Disk Access check tells you whether checklist-state features will work — see [Full Disk Access Setup](docs/FULL-DISK-ACCESS.md).
+**Returns:** A per-check report (`structuredContent` carries the raw `{healthy, checks[]}`). The Full Disk Access check tells you whether checklist-state features will work — see [Full Disk Access Setup](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md).
 
 ---
 
@@ -891,7 +896,7 @@ AI: [calls create-note with title="Acme Corp", content="...", folder="Work/Clien
 ### npm (Recommended)
 
 ```bash
-npm install -g github:sweetrb/apple-notes-mcp
+npm install -g apple-notes-mcp
 ```
 
 ### From Source
@@ -901,7 +906,9 @@ git clone https://github.com/sweetrb/apple-notes-mcp.git
 cd apple-notes-mcp
 ```
 
-The repo ships a prebuilt, dependency-free `build/index.js`, so a bare clone runs with nothing but Node installed. `npm install` and `npm run build` are only needed when you change the source.
+The repo ships a prebuilt, dependency-free `build/index.js`, so a bare clone runs with nothing but Node installed. `pnpm install` and `pnpm run build` are only needed when you change the source (development uses [pnpm](https://pnpm.io/), not npm).
+
+You can also install straight from the git repo with `npm install -g github:sweetrb/apple-notes-mcp` (building from source requires pnpm), but the published npm package above is the recommended path.
 
 If installed from source, use this configuration:
 ```json
@@ -976,7 +983,7 @@ MCP stores no secrets, but as a general rule keep only non-secret config here.
 
 The `get-checklist-state` tool and checklist annotations in `get-note-markdown` read directly from the Apple Notes SQLite database. This requires **Full Disk Access** for the process running the MCP server.
 
-> 📘 **For the full why-and-how walkthrough (which app to grant, verifying with `doctor`, graceful degradation), see the [Full Disk Access Setup Guide](docs/FULL-DISK-ACCESS.md).** The summary below is the quick version.
+> 📘 **For the full why-and-how walkthrough (which app to grant, verifying with `doctor`, graceful degradation), see the [Full Disk Access Setup Guide](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md).** The summary below is the quick version.
 
 ### How to Grant Full Disk Access
 
@@ -1016,7 +1023,7 @@ All other tools work normally without Full Disk Access. Only checklist state fea
 | No pinned notes | Pin status is not exposed via AppleScript ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)) |
 | Limited rich formatting | Use `format: "html"` on create/update for headings, lists, bold, code blocks; some complex formatting may not render |
 | Title matching | Most operations require exact title matches |
-| Checklist state | Requires [Full Disk Access](docs/FULL-DISK-ACCESS.md) to read done/undone state from the database |
+| Checklist state | Requires [Full Disk Access](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md) to read done/undone state from the database |
 | Checklist **creation** | Not supported. AppleScript's `body of note` setter strips `<input type="checkbox">` and ignores any checklist-styling CSS class. Apple Notes stores checklist items as a protobuf paragraph style (`style_type=103`) that AppleScript doesn't expose, and the SQLite database is read-only. See [Creating Checklists](#creating-checklists) below for the workaround. |
 
 ### Roadmap
@@ -1084,7 +1091,7 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 
 ### "Permission denied"
 - macOS needs automation permission
-- Go to System Preferences > Privacy & Security > Automation
+- Go to System Settings > Privacy & Security > Automation
 - Ensure your terminal/Claude has permission to control Notes
 
 ### "Note not found"
@@ -1097,9 +1104,14 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 - Use `\\` to represent each literal backslash
 - See "Backslash Escaping" section under Known Limitations
 
+### Notes accumulate blank lines after repeated updates
+- Repeatedly updating a note (especially with HTML content) can accumulate whitespace artifacts — `<div><br></div>` tags that persist between sections even after you remove them from your content
+- Apple Notes' internal HTML processing preserves empty divs from previous edits, so the gaps are baked into the note's internal representation and cannot be fixed through further updates
+- Fix: delete the note with `delete-note` and create a fresh one with `create-note`
+
 ### `apple-notes` server fails to connect when run from a clone
 - Launch `claude` from **inside the repo directory** so `CLAUDE_PROJECT_DIR` resolves to the repo root (the bare `.` fallback is unreliable — it points at the launching process's working directory)
-- If you've been editing the source, rerun `npm run build` — the entrypoint is `${CLAUDE_PROJECT_DIR:-.}/build/index.js`, and the committed bundle only reflects your changes after a rebuild
+- If you've been editing the source, rerun `pnpm run build` — the entrypoint is `${CLAUDE_PROJECT_DIR:-.}/build/index.js`, and the committed bundle only reflects your changes after a rebuild
 - Run `claude mcp list` to check for a conflicting `apple-notes` entry at another scope (project-scope outranks user-scope, but local-scope outranks project-scope)
 - Approve the pending project-scope server when Claude Code prompts you
 
@@ -1107,14 +1119,16 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 
 ## Development
 
+Development uses [pnpm](https://pnpm.io/) (see `packageManager` in `package.json`):
+
 ```bash
-npm install            # Install dependencies
-npm run build          # Typecheck, then bundle src/index.ts into build/index.js (esbuild)
-npm test               # Run unit test suite (mocked AppleScript)
-npm run test:integration  # Run integration tests against real Notes.app
-npm run test:all       # Unit + integration
-npm run lint           # Check code style
-npm run format         # Format code
+pnpm install            # Install dependencies
+pnpm run build          # Typecheck, then bundle src/index.ts into build/index.js (esbuild)
+pnpm test               # Run unit test suite (mocked AppleScript)
+pnpm run test:integration  # Run integration tests against real Notes.app
+pnpm run test:all       # Unit + integration
+pnpm run lint           # Check code style
+pnpm run format         # Format code
 ```
 
 The integration suite (`test/integration.test.ts`) drives the real
@@ -1136,11 +1150,11 @@ A software consulting, contracting, and development company.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT License - see [LICENSE](https://github.com/sweetrb/apple-notes-mcp/blob/main/LICENSE) for details.
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/CONTRIBUTING.md) for guidelines.
 
 ## Related Projects
 
@@ -1152,4 +1166,4 @@ Part of a family of macOS MCP servers:
 
 ## Recurring macOS permission prompts
 
-If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), see [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md) — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.
+If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), the cause is almost always an **ad-hoc-signed Node** (typically Homebrew's): its code signature (cdhash) changes on every update, so macOS TCC treats each new build as a brand-new binary and silently drops the grants you already made. The fix is to run this server under an official, **Developer-ID-signed Node at a stable path** — its signing identity stays the same across updates, so you grant the permission once and it persists. The `doctor` tool detects the ad-hoc-signature case and the full walkthrough is in [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md).

package/build/index.js

@@ -38717,7 +38717,7 @@ var ERROR_MAPPINGS = [
   // Permission errors
   {
     pattern: /not authorized|not permitted|access.*denied/i,
-    message: "Permission denied. Grant automation access in System Preferences > Privacy & Security > Automation."
+    message: "Permission denied. Grant automation access in System Settings > Privacy & Security > Automation."
   },
   // Application not running
   {
@@ -38975,6 +38975,10 @@ function embeddedMessage(field) {
   return decodeMessage(bytes);
 }
 
+// src/utils/docsUrls.ts
+var FULL_DISK_ACCESS_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md";
+var NODE_RUNTIME_TCC_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md";
+
 // src/utils/checklistParser.ts
 var CHECKLIST_STYLE_TYPE = 103;
 var NOTES_DB_PATH = path.join(
@@ -39095,7 +39099,7 @@ function getChecklistItems(noteId) {
     return {
       items: null,
       error: "no_fda",
-      message: "Full Disk Access is required to read checklist state. Grant access in System Settings > Privacy & Security > Full Disk Access, then add and restart this application."
+      message: `Full Disk Access is required to read checklist state. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`
     };
   }
   if (!hexData) {
@@ -40529,7 +40533,7 @@ var AppleNotesManager = class {
         message: "Notes.app is accessible"
       });
     } else {
-      const errorHint = appCheck.error?.includes("not authorized") ? " (check Automation permissions in System Preferences)" : "";
+      const errorHint = appCheck.error?.includes("not authorized") ? " (check Automation permissions in System Settings > Privacy & Security > Automation)" : "";
       checks.push({
         name: "notes_app",
         passed: false,
@@ -40549,7 +40553,7 @@ var AppleNotesManager = class {
       checks.push({
         name: "permissions",
         passed: !isPermError,
-        message: isPermError ? "AppleScript permissions denied. Grant access in System Preferences > Privacy & Security > Automation" : `Permission check returned: ${permCheck.error}`
+        message: isPermError ? "AppleScript permissions denied. Grant access in System Settings > Privacy & Security > Automation" : `Permission check returned: ${permCheck.error}`
       });
       if (isPermError) {
         return { healthy: false, checks };
@@ -41463,7 +41467,7 @@ var NOTES_DB_PATH3 = path3.join(
   os3.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
 );
-var FDA_MESSAGE = "Full Disk Access is required to read note metadata. Grant access in System Settings > Privacy & Security > Full Disk Access, then add and restart this application.";
+var FDA_MESSAGE = `Full Disk Access is required to read note metadata. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
 var COLUMN_MAP = [
   { key: "pinned", column: "ZISPINNED", type: "bool" },
   { key: "hasChecklist", column: "ZHASCHECKLIST", type: "bool" },
@@ -41644,7 +41648,7 @@ function runDoctor(manager) {
   checks.push({
     name: "Full Disk Access",
     status: fda ? "ok" : "warn",
-    detail: fda ? "granted \u2014 checklist features available" : "not granted \u2014 get-checklist-state and checklist annotations in get-note-markdown won't work. Grant in System Settings > Privacy & Security > Full Disk Access."
+    detail: fda ? "granted \u2014 checklist features available" : `not granted \u2014 get-checklist-state and checklist annotations in get-note-markdown won't work. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it and re-run doctor. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`
   });
   checks.push(checkNodeRuntimeSignature());
   const healthy = !checks.some((c) => c.status === "fail");
@@ -41667,7 +41671,7 @@ function checkNodeRuntimeSignature() {
       return {
         name,
         status: "warn",
-        detail: `${process.execPath} is ad-hoc signed (no Team ID). macOS revokes its Automation and Full Disk Access grants every time the binary changes (e.g. every brew upgrade), which looks like random permission loss. Fix: run the server with a Developer-ID-signed Node at a stable path \u2014 see docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md.`
+        detail: `${process.execPath} is ad-hoc signed (no Team ID). macOS revokes its Automation and Full Disk Access grants every time the binary changes (e.g. every brew upgrade), which looks like random permission loss. Fix: run the server with a Developer-ID-signed Node at a stable path \u2014 see ${NODE_RUNTIME_TCC_GUIDE_URL}`
       };
     }
     const team = /^TeamIdentifier=(.+)$/m.exec(out)?.[1];
@@ -42671,7 +42675,7 @@ server.registerTool(
       return `  ${icon} ${c.name}: ${c.message}`;
     }).join("\n");
     const fdaAvailable = hasFullDiskAccess();
-    const fdaLine = fdaAvailable ? "  \u2713 full_disk_access: Granted (checklist features available)" : "  \u24D8 full_disk_access: Not granted (optional \u2014 needed for get-checklist-state and checklist annotations in get-note-markdown). Grant in System Settings > Privacy & Security > Full Disk Access.";
+    const fdaLine = fdaAvailable ? "  \u2713 full_disk_access: Granted (checklist features available)" : `  \u24D8 full_disk_access: Not granted (optional \u2014 needed for get-checklist-state and checklist annotations in get-note-markdown). In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
     return successResponse(`${statusIcon} ${statusText}
 
 ${checkLines}

package/docs/APPLESCRIPT-LIMITATIONS.md

@@ -0,0 +1,92 @@
+# AppleScript Limitations
+
+Apple Notes is automated through its AppleScript dictionary. A few features that
+exist in the Notes UI are simply **not exposed to AppleScript**, so this MCP
+server cannot read or write them no matter how the script is written. This page
+documents what was investigated, how it was verified, and the conclusion, so the
+limitation isn't re-investigated every release.
+
+The full set of properties Notes exposes on a `note` is:
+
+```
+container, class, password protected, modification date, creation date,
+shared, body, id, name, plaintext
+```
+
+(obtained with `properties of note 1 of account "iCloud"`).
+
+## Pinned notes (#28)
+
+**Status: not feasible via AppleScript.** The Notes UI lets you pin a note to
+the top of a folder, but the `note` class has no `pinned` property. Asking for
+it raises error `-1700`:
+
+```applescript
+tell application "Notes"
+    set p to pinned of note 1 of account "iCloud"
+    -- error -1700: Can't make pinned of note id "x-coredata://…" into type specifier.
+end tell
+```
+
+There is no alternative property, element, or command (`pin`, `pinned`,
+`favorite`, …) in the dictionary. Pinned state lives only in Notes' private
+Core Data store (`NoteStore.sqlite`), which is not part of the scriptable
+surface. Reading it would require parsing the SQLite store directly — brittle
+across macOS releases and outside what an AppleScript-based server should do —
+and there is no supported way to *set* it at all.
+
+**Conclusion:** pinned read/write is not supported and will not be added while
+Notes lacks a scriptable property. If a future macOS exposes one, revisit by
+re-running the probe above.
+
+## Note-to-note links (#30)
+
+**Status: not supported as data; navigation-only.** Apple Notes lets you insert
+a link from one note to another in the UI, but AppleScript exposes no property
+or element for it:
+
+- A `note` has no `URL`, `url`, or `link` property — each raises error `-2753`
+  (undefined). There is no element that enumerates outgoing/incoming links.
+- There is no readable or constructable `applenotes://` / `notes://` deep link.
+  The note's `id` (`x-coredata://…/ICNote/p123`) is the only stable handle, and
+  it is a Core Data URI, not a shareable or clickable link.
+
+The one related capability that *does* work is the `show` command, which reveals
+a note in the Notes UI by id:
+
+```applescript
+tell application "Notes" to show note id "x-coredata://…/ICNote/p123"
+```
+
+This is deliberately **not** wrapped as a tool: it pops the GUI (unhelpful for a
+headless server), and an agent already has the note's content via
+`get-note-content` / `get-note-markdown`. Link relationships between notes
+cannot be read at all, so a "list links in this note" feature is not possible.
+
+**Conclusion:** note-to-note link data is not exposed and cannot be surfaced.
+The `id` field already returned by every read tool is the canonical reference;
+use that to address a specific note.
+
+## Tags / hashtags (#29)
+
+**Status: parsed from the body, not first-class.** Apple Notes "tags" are inline
+`#hashtag` tokens you type into a note's text. They are **not** a scriptable
+property — the `note` class exposes no `tags` element, and the tag relationship
+lives only in Notes' private Core Data store. So the only way to surface a
+note's tags via AppleScript is to read them back out of the body text.
+
+This server does that: `get-note-content` parses the body and returns the tags
+as `hashtags` in its `structuredContent` (see `src/utils/hashtags.ts`). The
+rules match Notes' own behaviour — a token is `#` followed by letters/digits/
+underscores containing **at least one letter**, so `#123` is not a tag; tokens
+are de-duplicated case-insensitively.
+
+Two related caveats:
+
+- The `tags` parameter on `create-note` is an application-level pass-through. It
+  is stored on the returned object but Notes does **not** persist it, and it does
+  **not** create real `#hashtags` in the body. To make a real tag, put `#tag`
+  in the note content.
+- **Smart folders are not scriptable.** Notes' tag-driven Smart Folders cannot be
+  created, read, or enumerated via AppleScript; there is no `smart folder` class
+  in the dictionary. Only regular folders are scriptable.

package/docs/FULL-DISK-ACCESS.md

@@ -0,0 +1,72 @@
+# Full Disk Access for Checklist Features
+
+Apple Notes MCP works almost entirely without any special disk permission. **One
+feature area** needs **Full Disk Access (FDA)** for the process that runs the MCP
+server:
+
+- **`get-checklist-state`** — reads a note's checklist done/undone state.
+- **Checklist annotations in `get-note-markdown`** — the `[x]` / `[ ]` prefixes on
+  checklist items.
+
+Everything else (creating, reading, searching, updating, moving, deleting notes;
+folders, accounts, attachments, stats, export, etc.) works **without** Full Disk
+Access.
+
+## Why it's needed
+
+Apple Notes stores checklist items as a paragraph style inside a gzipped protobuf
+blob in its SQLite store, `NoteStore.sqlite`. AppleScript's `body of note`
+interface strips that state — it can't tell you whether a checklist item is
+checked. To recover it, the MCP reads the SQLite store directly.
+
+That database lives in a macOS-protected directory:
+
+```
+~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite
+```
+
+Reading anything under `~/Library/Group Containers/` requires **Full Disk
+Access** for the host process — without it, macOS denies the read and the MCP
+cannot parse checklist state. (The MCP only ever **reads** this database; it never
+writes to it.)
+
+## How to grant Full Disk Access
+
+1. Open **System Settings** (or **System Preferences** on older macOS).
+2. Go to **Privacy & Security → Full Disk Access**.
+3. Click the **+** button (you may need to unlock with Touch ID / your password
+   first), and add the application that **hosts** the MCP server — i.e. the app
+   that actually launches `node`:
+   - **Claude Desktop** → `/Applications/Claude.app`
+   - **Terminal** (if you run Claude Code from a shell) → `/Applications/Utilities/Terminal.app`
+   - **iTerm** → `/Applications/iTerm.app`
+   - **VS Code** → `/Applications/Visual Studio Code.app`
+4. Make sure the toggle next to the app is **on**.
+5. **Fully quit and reopen the host app.** macOS only applies the new permission
+   to processes started *after* the change — a reload or restart-server is not
+   enough; the host application itself must be quit (⌘Q) and relaunched.
+
+> **Grant FDA to the right app.** FDA applies to the process that spawns the
+> server, not to `node` or to Notes.app. If you launch Claude Code from iTerm,
+> grant it to iTerm; if you use Claude Desktop, grant it to Claude. Granting it to
+> the wrong app has no effect.
+
+## Verifying it worked
+
+Run the **`doctor`** tool. It reports a dedicated **Full Disk Access** check as
+`ok` / `warn` / `fail` with the reason, so you can confirm the grant took effect
+without guessing. You can also just call `get-checklist-state` on a note that has
+a checklist — if it returns items with `[x]`/`[ ]` state, FDA is working.
+
+## Without Full Disk Access
+
+The server degrades gracefully — nothing crashes:
+
+- `get-checklist-state` returns a clear error explaining that database access is
+  needed (and points here).
+- `get-note-markdown` still returns the note as Markdown, but checklist items
+  appear as plain list items without the `[x]`/`[ ]` annotations.
+- **All other tools work normally.**
+
+See also: [Known Limitations](../README.md#known-limitations) and
+[Creating Checklists](../README.md#creating-checklists) in the README.

package/docs/JXA_RESEARCH.md

@@ -0,0 +1,129 @@
+# JXA (JavaScript for Automation) Research
+
+This document summarizes research into using JXA as an alternative to AppleScript for interacting with Apple Notes.
+
+## Background
+
+JXA was introduced in OS X Yosemite (10.10) as an alternative scripting language for the OSA (Open Scripting Architecture) framework. It allows JavaScript to be used instead of AppleScript for automation tasks.
+
+**Hypothesis**: JXA might provide advantages over AppleScript:
+- Simpler string escaping (standard JavaScript)
+- Better Unicode handling
+- Familiar syntax for developers
+- Native JSON support
+
+## Implementation
+
+Created `src/utils/jxa.ts` with:
+- `executeJXA(script, options)` - Execute JXA via `osascript -l JavaScript`
+- `escapeForJXA(str)` - Standard JavaScript string escaping
+- `buildNotesJXA(code)` - Wrapper for Notes.app context
+
+## Test Results
+
+### Performance Comparison
+
+| Operation | AppleScript | JXA | Ratio |
+|-----------|-------------|-----|-------|
+| List Accounts | 124ms | 152ms | 0.8x |
+| List Folders | 141ms | 153ms | 0.9x |
+| Count Notes | 148ms | 138ms | 1.1x |
+| Get First Note Title | 154ms | 155ms | 1.0x |
+| Get Creation Date | 152ms | 150ms | 1.0x |
+| **Unicode Search** | **155ms** | **4129ms** | **0.04x** |
+| **Text Search** | **311ms** | **4115ms** | **0.08x** |
+
+**Overall**: JXA is **0.13x the speed of AppleScript** (7.6x slower)
+
+### Why Search is So Slow in JXA
+
+AppleScript's `whose` clause is optimized at the OSA/Notes.app level:
+```applescript
+-- Fast: filtered server-side
+notes whose name contains "test"
+```
+
+JXA must iterate in JavaScript:
+```javascript
+// Slow: fetches all notes, filters client-side
+Notes.notes().filter(n => n.name().includes("test"))
+```
+
+The 347-note test database showed search operations taking 4+ seconds in JXA vs ~300ms in AppleScript.
+
+### Output Format Comparison
+
+| Aspect | AppleScript | JXA |
+|--------|-------------|-----|
+| **Dates** | Locale-dependent ("Wednesday, December 31, 2025 at 5:33:09 PM") | ISO format with `.toISOString()` |
+| **Arrays** | Comma-separated string | Native JavaScript arrays |
+| **Null handling** | "missing value" | JavaScript null/undefined |
+
+### String Escaping Comparison
+
+**AppleScript** (complex, multi-layer):
+```typescript
+// Must escape for: shell → AppleScript → HTML
+str.replace(/\\/g, "\")       // HTML entity for backslash
+   .replace(/"/g, "\\\"")          // AppleScript quote escape
+   .replace(/'/g, "'\\''")         // Shell quote escape
+```
+
+**JXA** (simpler, standard JavaScript):
+```typescript
+str.replace(/\\/g, "\\\\")         // Standard JS escaping
+   .replace(/"/g, '\\"')
+   .replace(/\n/g, "\\n")
+```
+
+### Unicode Handling
+
+Both handle Unicode identically - they share the same underlying OSA framework. No advantage either way.
+
+### Error Messages
+
+Both produce similar error messages from the OSA framework:
+- AppleScript: `execution error: Notes got an error: Can't get note "X". (-1728)`
+- JXA: `execution error: Error: Error: Can't get object. (-1728)`
+
+## Recommendation
+
+**Do NOT migrate to JXA for Apple Notes operations.**
+
+### Reasons
+
+1. **Critical Performance Penalty**: Search operations are 10-26x slower due to client-side filtering
+2. **No Significant Escaping Advantage**: While JXA escaping is simpler, our AppleScript escaping is already robust and well-tested
+3. **Same Underlying Limitations**: Both use OSA, so neither can access locked notes, sync state, etc.
+4. **Maintenance Burden**: Would require maintaining two scripting approaches
+
+### Limited Use Cases for JXA
+
+JXA could be useful for:
+1. **Date formatting**: Returns ISO dates instead of locale-dependent strings (but we can parse AppleScript dates)
+2. **JSON output**: Native `JSON.stringify()` for complex data (but our current parsing works fine)
+3. **One-off scripts**: Developer tools/scripts where performance isn't critical
+
+### Conclusion
+
+The current AppleScript implementation should remain the primary execution method. The simpler escaping in JXA doesn't justify the 7.6x performance penalty, especially for operations involving filtering or searching.
+
+The JXA utilities (`src/utils/jxa.ts`) have been created and tested, and can be used for specific scenarios where its advantages (ISO dates, simpler escaping) outweigh the performance cost.
+
+## Files Created
+
+- `src/utils/jxa.ts` - JXA execution utilities
+- `src/utils/jxa.test.ts` - Unit tests (16 tests)
+- `scripts/jxa-comparison.ts` - Real-world comparison script
+- `docs/JXA_RESEARCH.md` - This document
+
+## Test Environment
+
+- macOS Sequoia 26.2.0
+- Notes.app with 347 notes across 4 accounts
+- Node.js with tsx for TypeScript execution
+
+---
+
+*Research completed: January 2025*
+*Branch: feature/jxa-alternative*

package/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md

@@ -0,0 +1,109 @@
+# Node runtime & TCC permission stability
+
+macOS gates this MCP server's access to your data behind **TCC** permissions —
+**Full Disk Access** (to read app data such as Mail, Notes, or Photos) and
+**Automation / Apple Events** (to drive an app like Mail.app or Notes.app via
+AppleScript). See this repo's Full Disk Access / Automation notes for *which*
+operations need which permission.
+
+This page is about a **separate, recurring annoyance**: being asked to approve
+those permissions **over and over**, often right after a routine `brew upgrade`.
+
+## Symptom
+
+- You granted Full Disk Access (and/or Automation) to "node", but days later
+  macOS prompts again — `"node" wants access to ...` or `"node" wants to control
+  "Mail"`.
+- System Settings → Privacy & Security → Full Disk Access shows **several
+  identical "node" rows**, usually only one enabled.
+- It tends to happen immediately after you update Node.
+
+## Cause
+
+TCC binds a permission grant to the **code identity of the binary that performs
+the access** — here, the `node` executable that launches the MCP server. For a
+binary that is only **ad-hoc signed** (no Developer ID / Team ID), TCC keys the
+grant to the binary's **cdhash**, a hash of its contents.
+
+Homebrew's `node` formula is ad-hoc signed:
+
+```bash
+$ codesign -dvvv "$(which node)" 2>&1 | grep -E 'Signature|TeamIdentifier'
+Signature=adhoc
+TeamIdentifier=not set
+```
+
+Every Node update **replaces the binary**, which **changes the cdhash**, so TCC
+no longer recognizes it as the thing you approved — and re-prompts. The extra
+"node" rows are stale cdhashes from previous versions.
+
+By contrast, properly signed apps (Chrome, Slack, …) keep their permissions
+across auto-updates because TCC matches them on a stable **Designated
+Requirement** derived from their Developer ID, not on the cdhash.
+
+## Fix: run the MCP under the official, Developer-ID-signed Node
+
+Node binaries distributed from **nodejs.org** are signed with a real Developer
+ID (`Node.js Foundation`, Team `HX7739G8FX`), notarized, and self-contained.
+Pointing the MCP server at one gives TCC a **stable** identity to match, so a
+permission you grant **persists across future Node updates**. It also decouples
+the MCP runtime from your Homebrew/dev Node, which can keep updating freely.
+
+### Steps (Apple Silicon shown; use `darwin-x64` on Intel)
+
+1. Install a current LTS to a stable path (kept off `PATH` so it won't shadow
+   your dev Node):
+
+   ```bash
+   VER=v24.17.0 ARCH=darwin-arm64
+   mkdir -p ~/mcp-runtime && cd ~/mcp-runtime
+   curl -O https://nodejs.org/dist/$VER/node-$VER-$ARCH.tar.gz
+   curl -O https://nodejs.org/dist/$VER/SHASUMS256.txt
+   grep "  node-$VER-$ARCH.tar.gz$" SHASUMS256.txt | shasum -a 256 -c -   # must print OK
+   tar -xzf node-$VER-$ARCH.tar.gz
+   ln -sfn node-$VER-$ARCH node-current
+   ```
+
+2. Confirm it's Developer-ID signed:
+
+   ```bash
+   codesign -dvvv ~/mcp-runtime/node-current/bin/node 2>&1 | grep -E 'Authority=Developer ID|TeamIdentifier'
+   # Authority=Developer ID Application: Node.js Foundation (HX7739G8FX)
+   # TeamIdentifier=HX7739G8FX
+   ```
+
+3. Point this MCP server's launcher at it. For Claude Desktop, edit
+   `~/Library/Application Support/Claude/claude_desktop_config.json` and set this
+   server's `command` to the absolute path:
+
+   ```json
+   {
+     "mcpServers": {
+       "apple-notes": {
+         "command": "/Users/<you>/mcp-runtime/node-current/bin/node",
+         "args": ["/path/to/apple-notes-mcp/build/index.js"]
+       }
+     }
+   }
+   ```
+
+   Servers launched via `npx` that don't need Full Disk Access can stay on
+   Homebrew Node.
+
+4. **Restart your MCP client** so the server relaunches under the new Node.
+
+5. **Grant the permissions once** to the new binary:
+   - *Full Disk Access*: System Settings → Privacy & Security → Full Disk Access
+     → **+** → ⌘⇧G → paste `~/mcp-runtime/node-current/bin/node`.
+   - *Automation*: the first time the server drives an app you'll get a one-time
+     `"node" wants to control "<App>"` prompt — click **Allow**.
+
+   Both grants are keyed to the official Node's stable signature, so you should
+   not be asked again — including after future Node updates. You can delete the
+   stale "node" rows from the Full Disk Access list.
+
+### Updating the dedicated Node later
+
+Drop a newer official LTS tarball into `~/mcp-runtime/`, repoint the
+`node-current` symlink, and restart your client. The signing identity is
+unchanged, so existing grants carry over — no re-approval.

package/docs/STABILITY-PERF-AUDIT-2026-06-19.md

@@ -0,0 +1,151 @@
+# apple-notes-mcp — Stability & Performance Audit
+
+**Date:** 2026-06-19 · **Version audited:** 1.4.4 (`main` @ `bb677d6`)
+**Scope:** full codebase — `services/appleNotesManager.ts` (~2375 LOC), `index.ts` (23 tools), `utils/{applescript,jxa,checklistParser,protobuf,syncDetection}.ts`, CI/publish workflows.
+
+This audit measures apple-notes-mcp against the maturity bar set by its sibling
+**apple-mail-mcp (v2.1.1)** — robustness, performance, and the maturity surface
+(structured output, diagnostics, resources/prompts, config). Findings are ranked
+by **impact × likelihood** with rough effort (S/M/L). Many fixes are direct ports
+of code already hardened in apple-mail. Line numbers are against `main` @ `bb677d6`.
+
+## Resolution status
+
+| # | Finding | Tier | Issue | Status |
+|---|---------|------|-------|--------|
+| H1 | `execSync` has no `maxBuffer` cap | High | [#16](https://github.com/sweetrb/apple-notes-mcp/issues/16) | Open |
+| H2 | No `with timeout` + SIGTERM wedges Notes.app | High | [#17](https://github.com/sweetrb/apple-notes-mcp/issues/17) | Open |
+| H3 | Printable `\|\|\|` / comma delimiters collide with user content | High | [#18](https://github.com/sweetrb/apple-notes-mcp/issues/18) | Open |
+| H4 | Swallowed failures return `[]`/`null`/`0` | High | [#19](https://github.com/sweetrb/apple-notes-mcp/issues/19) | Open |
+| H5 | Unbounded full-library scans, no partial-result signal | High | [#20](https://github.com/sweetrb/apple-notes-mcp/issues/20) | Open |
+| M1 | No `structuredContent` on any tool | Medium | [#21](https://github.com/sweetrb/apple-notes-mcp/issues/21) | Open |
+| M2 | No `doctor` tool (incl. Full Disk Access check) | Medium | [#22](https://github.com/sweetrb/apple-notes-mcp/issues/22) | Open |
+| M3 | No MCP resources or prompts | Medium | [#23](https://github.com/sweetrb/apple-notes-mcp/issues/23) | Open |
+| M4 | No file-based config loader | Medium | [#24](https://github.com/sweetrb/apple-notes-mcp/issues/24) | Open |
+| M5 | Locale-fragile date parsing | Medium | [#25](https://github.com/sweetrb/apple-notes-mcp/issues/25) | Open |
+| M6 | Batch ops are N+1 osascript fan-out | Medium | [#26](https://github.com/sweetrb/apple-notes-mcp/issues/26) | Open |
+| M7 | No `save-attachment` / `fetch-attachment` | Medium | [#27](https://github.com/sweetrb/apple-notes-mcp/issues/27) | Open |
+| L1 | Pinned notes not exposed | Low | [#28](https://github.com/sweetrb/apple-notes-mcp/issues/28) | Open |
+| L2 | Tags/hashtags not surfaced | Low | [#29](https://github.com/sweetrb/apple-notes-mcp/issues/29) | Open |
+| L3 | Note-to-note links not supported | Low | [#30](https://github.com/sweetrb/apple-notes-mcp/issues/30) | Open |
+| L5 | No integration test suite | Low | [#31](https://github.com/sweetrb/apple-notes-mcp/issues/31) | Open |
+| L6 | Full Disk Access guide + commit this audit | Low | [#32](https://github.com/sweetrb/apple-notes-mcp/issues/32) | Open |
+
+Target release for the fixes: **2.0.0** (full parity with apple-mail), built on a
+long-lived `v2` branch, one item at a time with tests, then full regression +
+docs + merge.
+
+---
+
+## High
+
+### H1 — `execSync` has no `maxBuffer` cap → ENOBUFS on large output (S)
+`src/utils/applescript.ts:324` and `src/utils/jxa.ts:103` call `execSync` with no
+`maxBuffer`, inheriting Node's 1 MB default. `export-notes-json` (full-library
+JSON), `getRecentlyModifiedCounts` (every note's mod-date across all accounts,
+`appleNotesManager.ts:1838-1851`), `get name of notes`, and `get-note-content` on
+long notes can exceed it. Over the limit `execSync` throws and the catch path
+returns `[]`/`null` — a silent, data-dependent failure. **Fix:** add a 64 MB
+default `maxBuffer` (env-overridable) to both executors (port apple-mail #27).
+
+### H2 — No `with timeout` wrap; SIGTERM kill wedges Notes.app (M)
+`applescript.ts` wraps nothing in `with timeout` and relies on `execSync`'s
+default SIGTERM (timeout detection keys on `signal === "SIGTERM"`, line 88).
+Killing osascript with SIGTERM leaves work already dispatched inside the
+single-threaded app running, wedging it for subsequent calls (apple-mail #11).
+**Fix:** port `wrapWithTimeout()` (a script-level `with timeout` set below the
+process timeout) and `killSignal: "SIGKILL"`.
+
+### H3 — Printable `|||` / comma delimiters collide with user content (M)
+Output is split on printable tokens a user can type into a note title or folder
+name: `|||` and `|||ITEM|||` (~20 sites in `appleNotesManager.ts`), bare commas in
+`parseCommaSeparatedList` (`:495`, used at `:1242` and `:1656`), and comma
+field-splitting in `parseNotePropertiesOutput` (`:326-345`). A note titled
+"Groceries, etc." splits into two phantom notes. **This is a real
+data-corruption-on-ordinary-input bug.** **Fix:** switch field/record delimiters
+to control chars (`\x1f`/`\x1e`/`\x1d`) and stop comma-splitting list output
+(port apple-mail #30).
+
+### H4 — Swallowed failures: error → `return []`/`null`/`0` (M)
+On `result.success === false`, many manager methods log to stderr and return an
+empty/neutral value, so the caller can't distinguish "operation failed" from "no
+notes": search `:808-810`, list `:1212-1216`/`:1239`, folders `:1367-1371`,
+accounts `:1652`, `getRecentlyModifiedCounts` `:1852-1853`, and `getNotesStats`
+(wrong totals if any folder scan fails). **Fix:** surface failures (throw or a
+discriminated result) and add partial-coverage diagnostics (apple-mail #28/#29).
+
+### H5 — Unbounded full-library scans, no partial-result signal (M)
+`getRecentlyModifiedCounts` (`:1838-1851`) iterates *every note of every account*
+into one giant string; `getNotesStats` (`:1785-1815`) loops account×folder calling
+`listNotes` (one osascript spawn) per folder. No bound, no coverage diagnostic —
+this both trips H1's buffer and H2's timeout on large libraries. **Fix:** bound
+the scan, batch stats into fewer Apple Events, report coverage (apple-mail #24).
+
+## Medium
+
+### M1 — No `structuredContent` on any tool (M)
+No tool returns `structuredContent` (grep: none); `export-notes-json` even
+stringifies JSON into a text block (`index.ts:955-961`). **Fix:** add
+`successResponse`/`errorResponse` helpers carrying typed JSON and emit from all
+read/list/get tools (apple-mail A1).
+
+### M2 — No `doctor` tool (M)
+Only a thin `health-check` (`index.ts:763`, `appleNotesManager.ts:1687`). **Fix:**
+add a `doctor` checking Notes.app reachability, Automation permission, **Full Disk
+Access** (required for checklist parsing — a common silent-failure source),
+account list, and default-account resolution, with actionable messages +
+`structuredContent` (apple-mail C3).
+
+### M3 — No MCP resources or prompts (M)
+No `registerResource`/`registerPrompt`. **Fix:** expose resources
+(`notes://accounts`, `notes://folders`, `notes://note/{id}`) and prompts
+(find-note, create-checklist, weekly-review) (apple-mail D2).
+
+### M4 — No file-based config loader (S)
+**Fix:** port `fileConfig` reading
+`~/Library/Application Support/apple-notes-mcp/config.json`, merged without
+overriding existing env, so settings work when the host app strips the MCP `env`
+block (apple-mail 2.1.1) — relevant for the default-account setting.
+
+### M5 — Locale-fragile date parsing (S)
+`parseAppleScriptDate` (`:252-266`) feeds AppleScript `(date as text)` into
+`new Date()` and falls back to `new Date()` (now) on failure — breaks under
+non-en-US locales, corrupting created/modified timestamps and recency counts.
+`listNotes`/search already use the locale-safe `whose modification date >=` clause
+(`:1188`, `:774`); the read path doesn't. **Fix:** emit ISO-stable date components
+from AppleScript (or parse explicitly) and never fall back to "now."
+
+### M6 — Batch ops are N+1 osascript fan-out (M)
+`batchDeleteNotes` (`:2041`) and `batchMoveNotes` (`:2088`) loop per id issuing
+several separate osascript spawns each. **Fix:** collapse existence/property reads
+and mutations into single scripts where feasible, preserving per-item isolation
+(apple-mail #31).
+
+### M7 — No `save-attachment` / `fetch-attachment` (M)
+`list-attachments` (`:1887`) returns metadata only. **Fix:** add `save-attachment`
+(AppleScript `save attachment … in (POSIX file …)`, validated path) and
+`fetch-attachment` (base64), mirroring apple-mail.
+
+## Low
+
+- **L1 — Pinned notes** ([#28](https://github.com/sweetrb/apple-notes-mcp/issues/28)): AppleScript `pinned` support is version-dependent; investigate, expose if feasible, else document.
+- **L2 — Tags/hashtags** ([#29](https://github.com/sweetrb/apple-notes-mcp/issues/29)): `create-note`'s `tags` is cosmetic (`:608`); Notes tags are inline `#hashtags` not in the dictionary — parse from body and document; smart folders aren't scriptable.
+- **L3 — Note-to-note links** ([#30](https://github.com/sweetrb/apple-notes-mcp/issues/30)): weak AppleScript support; investigate/document.
+- **L5 — Integration tests** ([#31](https://github.com/sweetrb/apple-notes-mcp/issues/31)): 327 unit tests, no integration suite/CI job; add opt-in tests against a real library (gated).
+- **L6 — FDA guide + audit doc** ([#32](https://github.com/sweetrb/apple-notes-mcp/issues/32)): add a Full-Disk-Access setup guide; commit this audit.
+
+## Recommended sequencing
+
+1. **Stability core** (H1–H4): port the hardened executor wholesale from apple-mail
+   (`maxBuffer` + `with timeout` + `SIGKILL`), control-char delimiters, stop
+   swallowing failures. Highest risk reduction per line; bring over apple-mail's
+   buffer/timeout/delimiter unit tests.
+2. **Scan safety** (H5, M6): bound and batch the stats/recent scans and the batch
+   mutations; add partial-coverage diagnostics.
+3. **Maturity surface** (M1, M2): `structuredContent` everywhere + `doctor` (the
+   Full Disk Access check is the high-value Notes-specific piece).
+4. **Config + dates** (M4, M5): small, isolated ports.
+5. **Resources/prompts** (M3) and **attachments** (M7).
+6. **Tests + docs** (L5, L6): integration suite + permissions guide.
+7. **Notes-specific** (L1, L2, L3): verify AppleScript feasibility first; document
+   limits where not feasible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.5.10",
+  "version": "2.5.11",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
@@ -10,6 +10,7 @@
   },
   "files": [
     "build",
+    "docs",
     "README.md",
     "LICENSE"
   ],