docs+fix: reconcile the docs with the shipped tool surface, and stop under-scoping Full Disk Access

[sweetrb]

Description

Documentation sweep against the live tool inventory (dumped from the built server over MCP, not inferred). Every finding was adversarially verified before landing, and several were deliberately not applied where the verifier showed the claim was overstated or the proposed fix would have introduced a new false statement.

Fixed

• Full Disk Access was documented and diagnosed as a checklist-only concern, understating what breaks without it. docs/FULL-DISK-ACCESS.md — the page every FDA failure message hyperlinks to — opened with "One feature area needs Full Disk Access" and closed with "All other tools work normally", and the README, doctor, and health-check all said the same. Three more tools read the same protected NoteStore.sqlite: get-note-metadata fails outright without FDA, get-note-link's primary path is a database read (its AppleScript note link fallback exists only on macOS 12–15 and is gone from the SDEF on macOS 26+), and get-sync-status degrades silently — it still answers, but reports no pending uploads and no active sync. A user who ran doctor, saw the warning scoped to checklists they don't use, and skipped the grant got unexplained failures elsewhere. All five are now enumerated, with each one's no-FDA behaviour, in the guide, the README, the doctor check detail and the health-check line. get-note-link's own tool description, which said only "requires macOS 12+" and never mentioned FDA at all, now states the requirement and the fallback's version window.
• get-note-content's lossiness was invisible to structuredContent consumers. Inline base64 images over APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with [inline image omitted: …] text placeholders, but the only signal was prose appended to the text block — the structured payload carried the lossy body with no flag, which is precisely what an agent consuming structuredContent reads. Following the documented read-modify-write recipe (get-note-content → update-note) therefore replaced a note's real images with placeholder text, permanently. The output schema now carries strippedImages (count) and truncated (boolean); the tool description, the README get-note-content Returns block, the skill, and the warning string itself now say not to write the returned body back, and point at append-to-note instead.
• create-note blamed Notes.app for a folder it never creates. createNote addresses the target folder directly and does not create it, but the failure returned "Check that Notes.app is configured and accessible" — sending callers on a TCC/permissions hunt in the one case where Notes.app is demonstrably fine. The message now names the missing folder and points at list-folders / create-folder (or, for a bad account, at list-accounts), keeping the automation-permission advice as the fallback. The requirement is also stated in the tool description, the folder parameter description, and the README, matching the wording move-note already used.
• Automation-permission errors were the only setup-failure class with no docs URL and no doctor pointer, though the Full Disk Access path has carried both since 2.5.11. Both strings (the generic executor error mapping in src/utils/applescript.ts, which fronts every tool, and the health-check permission probe) now share one AUTOMATION_REMEDIATION constant in src/utils/docsUrls.ts that names the app to grant, says to quit and relaunch it, and ends with the absolute troubleshooting URL plus "run the doctor tool to verify".

Documentation

• The docs claimed several shipped capabilities were impossible. docs/APPLESCRIPT-LIMITATIONS.md still asserted there is "no readable or constructable applenotes:// / notes:// deep link" and that the show command "is deliberately not wrapped as a tool" — while get-note-link returns exactly that URL and show-note / show-folder / show-account / show-attachment all ship; and its pinned section argued that reading NoteStore.sqlite was "outside what an AppleScript-based server should do" and concluded "pinned read/write is not supported", after get-note-metadata had shipped doing it. Both sections are rewritten around what remains true — a note has no URL/url/link property (error -2753), link relationships still cannot be read or inserted, and pin state still cannot be set — with the database-backed paths that superseded the rest recorded alongside. The same obsolete claims are corrected in the README's limitations bullet and its "No pinned notes" row.
• README Roadmap deleted. It listed pinned-note support (Expose pinned notes (investigate feasibility) #28), tags/hashtags (Surface tags/hashtags #29), note links (Note-to-note links (investigate/document) #30) and a local integration suite (Add an integration test suite #31) as "deliberately deferred to a future release, tracked as open issues". All four issues closed on 2026-06-20; the capabilities ship as get-note-metadata, get-note-content's hashtags, get-note-link, and the required integration CI job. The two genuine residual limits (pin state unsettable, no note-to-note linking within a body) are already stated in the AppleScript-limitations section and the Known Limitations table, so nothing is lost.
• docs/STABILITY-PERF-AUDIT-2026-06-19.md marked all 17 findings "Open". Every one is closed. The status column now records the release each landed in, with L1 (Expose pinned notes (investigate feasibility) #28) and L3 (Note-to-note links (investigate/document) #30) marked partial — pin state is readable but not settable, and get-note-link supersedes only half of the note-links finding — and L2 (Surface tags/hashtags #29) marked read-only. The "Target release: 2.0.0" line is replaced with a note that the fixes landed across 2.0.0–2.6.x and the document is a historical record, not a live backlog. The audit body is left as the dated 1.4.4 snapshot it is.
• TODO.md and TECHNICAL_NOTES.md both still listed prepend as "GUI-only under every approach". append-to-note has done append and prepend over ordinary AppleScript since 2.6.0, with no Shortcuts bridge. Corrected in both, along with TODO.md's stale "As of v2.1.0" header; the Shortcuts-inventory table keeps "Prepend to a body" in its right-hand column (Notes genuinely ships no such Shortcuts action) but the column is retitled and footnoted so it no longer reads as a global impossibility. append-to-note's candidate bullet is amended rather than deleted, since a true in-place append that cannot disturb attachments is still unbuilt.
• The agent-facing skill and CLAUDE.md were missing five shipped tools, including the whole deep-link/UI group: append-to-note, show-note, get-note-link, get-selected-notes, get-default-location. The skill's canonical "Add milk to my shopping list" example walked an agent through reading the whole body and resending it via update-note — the destructive path — six releases after the purpose-built tool existed. The Updating Notes recipe now splits addition (append-to-note) from replacement (update-note), and the tool tables and CLAUDE.md cover all five. The Attachment-Safe Updates guidance is unchanged: append-to-note also rewrites the full body, so it is not an attachment-safe alternative.
• CLAUDE.md said get-checklist-state "Returns null" when a note has no checklists or the database is unreadable. It never returns null — all six failure modes come back as MCP error responses (isError: true), including the routine "this note has no checklist items", which an agent would otherwise treat as a tool failure. Replaced with the actual contract and the message text that distinguishes each case.
• create-folder was documented as flat-name-only, with an error it cannot raise. The README said name was a "Name for the new folder" and that the call errors "if folder already exists"; it in fact takes a whole nested path, creates every intermediate segment, skips existing ones, and is idempotent — which is what its live schema has always said. Corrected, and create-folder and batch-move-notes added to CLAUDE.md's nested-path list.
• The 500-id cap on batch-delete-notes / batch-move-notes was undocumented in prose. The schema already emitted maxItems: 500 to machine callers, but no README table, tool description, skill, or CLAUDE.md entry mentioned it. Added to all four.
• Fixed a silently retargeted link. docs/FULL-DISK-ACCESS.md's "See also: Known Limitations" pointed at #known-limitations, which GitHub resolves to the first matching heading — a Features-level subsection about pinned notes and note links that says nothing about checklists or Full Disk Access. That subsection is renamed to "AppleScript limitations", matching its own body, so the anchor reaches the Known Limitations table again. The README's own FDA heading is renamed from "Full Disk Access for Checklist Features" to "Full Disk Access" (its two inbound anchors updated) now that the section covers more than checklists.

Verification

lint (0 errors), typecheck, format:check, full test suite, plugin-manifest sync, skills drift check, and bundle-matches-source all pass — re-run independently of the authoring pass. skills/ edited at the canonical root only, then pnpm run sync:skills.

Checklist

• Version bumped to 2.6.13 with a real ## [2.6.13] CHANGELOG heading