@noteplanco/noteplan-mcp 1.1.6 → 1.1.8

package/dist/server.js

@@ -19,12 +19,18 @@ import * as memoryTools from './tools/memory.js';
 import * as uiTools from './tools/ui.js';
 import * as pluginTools from './tools/plugins.js';
 import * as themeTools from './tools/themes.js';
+import * as templateTools from './tools/templates.js';
+import * as attachmentTools from './tools/attachments.js';
 import { parseFlexibleDate } from './utils/date-utils.js';
-import { upgradeMessage, getNotePlanVersion, getMcpServerVersion, MIN_BUILD_ADVANCED_FEATURES } from './utils/version.js';
+import { upgradeMessage, getNotePlanVersion, getMcpServerVersion, MIN_BUILD_ADVANCED_FEATURES, MIN_BUILD_CREATE_BACKUP } from './utils/version.js';
 import { initSqlite } from './noteplan/sqlite-loader.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PLUGIN_API_DOCS_DIR = path.join(__dirname, '../docs/plugin-api');
+const DOCS_DIR = path.join(__dirname, '../docs');
+const GENERAL_DOC_RESOURCES = [
+    { file: 'x-callback-url.md', name: 'x-callback-url Reference', desc: 'NotePlan URL scheme — all actions (openNote, addText, addNote, addQuickTask, search, runPlugin, etc.), parameters, and encoding examples' },
+];
 const PLUGIN_API_RESOURCES = [
     { file: 'plugin-api-condensed.md', name: 'Plugin API Reference (Condensed)', desc: 'Complete NotePlan plugin API — all signatures, types, and patterns in one reference. Read this first.' },
     { file: 'getting-started.md', name: 'Getting Started Guide', desc: 'How to create NotePlan plugins — structure, setup, first plugin, testing, HTML views' },
@@ -200,6 +206,8 @@ function getToolOutputSchema(toolName) {
         case 'noteplan_plugins':
         case 'noteplan_themes':
         case 'noteplan_embeddings':
+        case 'noteplan_templates':
+        case 'noteplan_attachments':
             return GENERIC_TOOL_OUTPUT_SCHEMA;
         default:
             return GENERIC_TOOL_OUTPUT_SCHEMA;
@@ -371,6 +379,7 @@ function getToolAnnotations(toolName) {
         'noteplan_plugins',
         'noteplan_themes',
         'noteplan_embeddings',
+        'noteplan_attachments',
     ]);
     const nonIdempotentTools = new Set([
         'noteplan_manage_note',
@@ -384,11 +393,14 @@ function getToolAnnotations(toolName) {
         'noteplan_plugins',
         'noteplan_themes',
         'noteplan_embeddings',
+        'noteplan_templates',
+        'noteplan_attachments',
     ]);
     const openWorldTools = new Set([
         'noteplan_eventkit',
         'noteplan_embeddings',
         'noteplan_plugins',
+        'noteplan_templates',
     ]);
     return {
         readOnlyHint: readOnlyTools.has(toolName),
@@ -459,6 +471,12 @@ function getToolSearchAliases(toolName) {
         case 'noteplan_embeddings':
             aliases.push('embeddings', 'semantic search', 'vector search', 'similarity');
             break;
+        case 'noteplan_templates':
+            aliases.push('template', 'templates', 'render template', 'list templates', 'template types', 'meeting template', 'project template', 'debug template', 'test template');
+            break;
+        case 'noteplan_attachments':
+            aliases.push('attachment', 'attachments', 'image', 'file', 'upload', 'add image', 'add file', 'add attachment', 'list attachments', 'get attachment', 'base64', 'photo', 'screenshot');
+            break;
     }
     return aliases;
 }
@@ -516,7 +534,7 @@ function searchToolDefinitions(tools, query, limit) {
 function inferToolErrorMeta(toolName, errorMessage, registeredToolNames) {
     const message = errorMessage.toLowerCase();
     if (message.includes('unknown tool')) {
-        const toolList = registeredToolNames?.join(', ') ?? 'noteplan_get_notes, noteplan_search, noteplan_manage_note, noteplan_edit_content, noteplan_paragraphs, noteplan_folders, noteplan_filters, noteplan_eventkit, noteplan_memory';
+        const toolList = registeredToolNames?.join(', ') ?? 'noteplan_get_notes, noteplan_search, noteplan_manage_note, noteplan_edit_content, noteplan_paragraphs, noteplan_folders, noteplan_filters, noteplan_eventkit, noteplan_memory, noteplan_templates, noteplan_attachments';
         return {
             code: 'ERR_UNKNOWN_TOOL',
             hint: `Check tool name spelling. Available tools: ${toolList}.`,
@@ -737,6 +755,12 @@ function withSuggestedNextTools(result, toolName, availableToolNames) {
         case 'noteplan_themes':
             suggestedNextTools = ['noteplan_themes'];
             break;
+        case 'noteplan_templates':
+            suggestedNextTools = ['noteplan_templates', 'noteplan_manage_note', 'noteplan_edit_content'];
+            break;
+        case 'noteplan_attachments':
+            suggestedNextTools = ['noteplan_attachments', 'noteplan_edit_content', 'noteplan_get_notes'];
+            break;
         default:
             suggestedNextTools = [];
     }
@@ -798,12 +822,59 @@ function withDuration(result, durationMs, includeTiming) {
 export function createServer() {
     const server = new Server({
         name: 'NotePlan',
-        version: '1.1.4',
+        version: '1.1.7',
     }, {
         capabilities: {
             tools: {},
             resources: {},
         },
+        instructions: [
+            'You have access to NotePlan — a markdown-based note-taking and task management app for macOS/iOS.',
+            'All tools use action-based dispatch: one tool per domain, with an `action` parameter to select the operation.',
+            '',
+            '## Workflow',
+            '',
+            'Prefer granular edits over full-note rewrites to avoid large context payloads and accidental data loss.',
+            '',
+            '1. **Find** the note: `noteplan_get_notes` (by id/title/filename/date) or `noteplan_search`',
+            '2. **Inspect** content: `noteplan_paragraphs(action: get)` for line metadata, `noteplan_paragraphs(action: search)` for text lookup',
+            '3. **Edit** with targeted mutations:',
+            '   - `noteplan_edit_content(action: edit_line)` — single-line change',
+            '   - `noteplan_edit_content(action: insert/append)` — add content at a position or heading',
+            '   - `noteplan_edit_content(action: delete_lines)` — remove lines',
+            '4. Only use `noteplan_manage_note(action: update)` for intentional full-note rewrites',
+            '',
+            '## Tasks',
+            '',
+            '- Add tasks via `noteplan_paragraphs(action: add)` — the server auto-formats the task marker to match the user\'s NotePlan settings. Never write raw markers like `- [ ]` or `* [ ]`; just pass the task text.',
+            '- Find tasks: `noteplan_paragraphs(action: search)` in one note, or `search_global` across all notes',
+            '- Complete/update: `noteplan_paragraphs(action: complete/update)`',
+            '- Use `heading` parameter to target a specific section (e.g., heading: "Tasks")',
+            '',
+            '## Destructive Operations',
+            '',
+            'Delete, move, rename, and restore use a 2-step safety flow:',
+            '1. Call with `dryRun=true` → get a preview and `confirmationToken`',
+            '2. Call again with that `confirmationToken` to execute',
+            '',
+            '## Key Behaviors',
+            '',
+            '- Calendar notes (daily/weekly/etc.) are auto-created when targeted by date — no need to create them first',
+            '- Notes can be targeted by `id`, `filename`, `title`, `date`, or `query` — prefer `id` or `filename` when available for precision',
+            '- Errors include a `hint` and often a `suggestedTool` to guide recovery',
+            '- The `noteplan_memory` tool stores user preferences (formatting, style, workflow) persistently across sessions',
+            '',
+            '## Templates',
+            '',
+            '- IMPORTANT: Before writing or editing templates, ALWAYS search the built-in documentation first: `noteplan_templates(action: "search_docs", query: "your topic")`',
+            '- Use `get_doc` to read the full text of a doc chunk returned by `search_docs`',
+            '- Then use `render` to test/debug your template code',
+            '',
+            '## Action Discovery',
+            '',
+            '- Every tool supports `action: "list_actions"` — call it to get a list of all available actions with descriptions',
+            '- Use `list_actions` when you are unsure what a tool can do or need to discover capabilities',
+        ].join('\n'),
     });
     let embeddingsToolsEnabled = false;
     try {
@@ -977,14 +1048,14 @@ export function createServer() {
         },
         {
             name: 'noteplan_manage_note',
-            description: 'Manage notes: create, update, delete, move, restore, rename, or manage frontmatter properties.\n\nActions:\n- create: Create a project note (requires title)\n- update: Replace note content (requires filename, content, fullReplace + confirmationToken)\n- delete/move/restore/rename: Lifecycle ops (requires id or filename + dryRun/confirmationToken)\n- set_property/remove_property: Frontmatter (requires filename + key)',
+            description: 'Manage notes: create, update, delete, move, restore, rename, or manage frontmatter properties.\n\nActions:\n- create: Create a project note (requires title). Set noteType="template" to create in @Templates with proper frontmatter. After creating a template, verify it with noteplan_templates(action: "render").\n- update: Replace note content (requires filename, content, fullReplace + confirmationToken)\n- delete/move/restore: Lifecycle ops (requires id or filename + dryRun/confirmationToken)\n- rename: Rename a note (accepts id, filename, title, or query to find the note + newTitle for the new name + dryRun/confirmationToken)\n- set_property/remove_property: Frontmatter (requires filename + key)',
             inputSchema: {
                 type: 'object',
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['create', 'update', 'delete', 'move', 'restore', 'rename', 'set_property', 'remove_property'],
-                        description: 'Action to perform',
+                        enum: ['create', 'update', 'delete', 'move', 'restore', 'rename', 'set_property', 'remove_property', 'list_actions'],
+                        description: 'Action: create | update | delete | move | restore | rename | set_property | remove_property | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -996,7 +1067,11 @@ export function createServer() {
                     },
                     title: {
                         type: 'string',
-                        description: 'Note title — required for create',
+                        description: 'Note title — required for create. Also used by rename to find the note by title (fuzzy matched).',
+                    },
+                    query: {
+                        type: 'string',
+                        description: 'Fuzzy search query to find the note — used by rename',
                     },
                     content: {
                         type: 'string',
@@ -1010,6 +1085,16 @@ export function createServer() {
                         type: 'boolean',
                         description: 'Bypass smart matching and create exact folder name — used by create',
                     },
+                    noteType: {
+                        type: 'string',
+                        enum: ['note', 'template'],
+                        description: 'Type of note to create. Use "template" to create in @Templates with proper frontmatter — used by create',
+                    },
+                    templateTypes: {
+                        type: 'array',
+                        items: { type: 'string', enum: ['empty-note', 'meeting-note', 'project-note', 'calendar-note'] },
+                        description: 'Template type tags — used by create with noteType="template"',
+                    },
                     space: {
                         type: 'string',
                         description: 'Space name or ID scope',
@@ -1036,11 +1121,11 @@ export function createServer() {
                     },
                     newFilename: {
                         type: 'string',
-                        description: 'New filename for local notes — used by rename',
+                        description: 'New filename for local notes — used by rename. Prefer newTitle instead.',
                     },
                     newTitle: {
                         type: 'string',
-                        description: 'New title for TeamSpace notes — used by rename',
+                        description: 'New title for the note — used by rename. Works for both local and TeamSpace notes. For local notes this renames the file and updates the # heading.',
                     },
                     keepExtension: {
                         type: 'boolean',
@@ -1060,14 +1145,14 @@ export function createServer() {
         },
         {
             name: 'noteplan_edit_content',
-            description: 'Edit note content: insert, append, delete lines, edit a line, or replace a range of lines.\n\nActions:\n- insert: Insert at position (start/end/after-heading/in-section/at-line)\n- append: Append to end (shorthand for insert at end). Use date="today" to append to today\'s daily note (replaces noteplan_add_to_today).\n- delete_lines: Delete line range (requires startLine, endLine + dryRun/confirmationToken)\n- edit_line: Edit one line (requires line + content)\n- replace_lines: Replace line range (requires startLine, endLine, content + dryRun/confirmationToken)\n\nTarget note via id, filename, title, date, or query. Calendar notes (date param) are auto-created if they don\'t exist yet — no need to create them first. Always use tab characters for indentation.\n\nNotePlan syntax: Tasks use "- [ ] text" (open), "- [x]" (done), "- [-]" (cancelled), "- [>]" (scheduled). The task marker (*/- with or without checkbox) follows user settings — prefer noteplan_paragraphs(action=add) for auto-formatted tasks. Schedule tasks to dates with >YYYY-MM-DD. Link to notes with [[Note Name]]. Never add block IDs (^id) — only the NotePlan app creates these.\n\nUse scheduleDate to auto-append >YYYY-MM-DD scheduling to content.',
+            description: 'Edit note content. IMPORTANT: action values use snake_case.\n\nValid actions (exactly these strings):\n- "insert": Insert at position. Combine any position with heading="Section Name" to scope insertion to that section. position="start" + heading inserts right after the heading. position="end" + heading appends at end of the heading\'s section. position="after-heading" inserts right after a heading. position="in-section" appends at end of a heading\'s section. position="start" (no heading) inserts after frontmatter. position="at-line" inserts at a specific line number. position="end" (no heading) appends to note.\n- "append": Shorthand for insert at end. Supports heading="Section Name" to append at end of that section. Use date="today" to append to today\'s daily note.\n- "delete_lines": Delete a line range. Requires startLine + endLine (1-indexed). Use dryRun=true first, then confirmationToken to execute.\n- "edit_line": Edit a single line. Requires line (1-indexed) + content. Set content="" to clear a line.\n- "replace_lines": Replace a line range. Requires startLine + endLine + content. Use dryRun=true first, then confirmationToken to execute.\n\nTarget note via id, filename, title, date, or query. Calendar notes (date param) are auto-created if they don\'t exist yet. Always use tab characters for indentation.\n\nAdding tasks: When inserting a task, set type="task" and pass only the task text as content (e.g. content="Buy groceries", type="task"). Do NOT include raw markers like "* [ ]" or "- [ ]" in content — the type parameter handles formatting to match the user\'s configured style. For checklists use type="checklist". For task lifecycle (complete, update, search), use noteplan_paragraphs instead.\n\nSchedule tasks with >YYYY-MM-DD. Link to notes with [[Note Name]]. Never add block IDs (^id).\n\nUse scheduleDate to auto-append >YYYY-MM-DD to content.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['insert', 'append', 'delete_lines', 'edit_line', 'replace_lines'],
-                        description: 'Action to perform',
+                        enum: ['insert', 'append', 'delete_lines', 'edit_line', 'replace_lines', 'list_actions'],
+                        description: 'Action: insert | append | delete_lines | edit_line | replace_lines | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -1095,16 +1180,16 @@ export function createServer() {
                     },
                     content: {
                         type: 'string',
-                        description: 'Content to insert/append/replace, or new line content for edit_line',
+                        description: 'Content to insert/append/replace, or new line content for edit_line. NEVER include task markers like "- [ ]", "* [ ]", or "* " — instead set type="task" and pass only the task text (e.g. content="Buy groceries", NOT content="- [ ] Buy groceries").',
                     },
                     position: {
                         type: 'string',
                         enum: ['start', 'end', 'after-heading', 'at-line', 'in-section'],
-                        description: 'Where to insert: start (after frontmatter), end, after-heading (right after heading/marker line), in-section (at end of section, before next heading/marker), or at-line — used by insert',
+                        description: 'Where to insert. With heading: start=right after heading, end/in-section=end of section. Without heading: start=after frontmatter, end=bottom of note. at-line=specific line number — used by insert',
                     },
                     heading: {
                         type: 'string',
-                        description: 'Heading or section marker text (required for after-heading and in-section; matches both ## headings and **bold:** section markers) — used by insert',
+                        description: 'Heading or section marker text (required for after-heading and in-section; matches both ## headings and **bold:** section markers) — used by insert, append',
                     },
                     line: {
                         type: 'number',
@@ -1167,14 +1252,14 @@ export function createServer() {
         },
         {
             name: 'noteplan_paragraphs',
-            description: 'Paragraph and task operations on notes.\n\nParagraph actions:\n- get: Get note lines with metadata (requires filename). Returns line, lineIndex, content, type, etc.\n- search: Search for matching lines in a note (requires query + note ref via id/filename/title/date)\n\nTask actions:\n- search_global: Search tasks across all notes (requires query, supports "*" wildcard)\n- add: Add a task (requires target + content). Task marker format auto-matches user settings. Use scheduleDate to auto-append >YYYY-MM-DD scheduling to content, [[Note Name]] to link, #tag for tags, @person for mentions.\n- complete: Mark task done (requires filename + lineIndex or line)\n- update: Update task content/status (requires filename + lineIndex or line)',
+            description: 'Task lifecycle and paragraph inspection.\n\nParagraph actions:\n- get: Get note lines with metadata (requires filename). Returns line, lineIndex, content, type, etc.\n- search: Search for matching lines in a note (requires query + note ref via id/filename/title/date)\n\nTask actions:\n- search_global: Search tasks across all notes (requires query, supports "*" wildcard)\n- add: Add a task (requires target + content). Target is a date ("today", "tomorrow", "YYYY-MM-DD") for daily notes or a filename for project notes. Pass only the task text as content — formatting auto-matches user settings. Position+heading combos: position="start"+heading inserts right after the heading, position="end"+heading appends at end of that section, position="after-heading" inserts right after heading, position="in-section" appends at end of section. Default position is "end" (bottom of note). Use scheduleDate for >YYYY-MM-DD, [[Note Name]] to link, #tag for tags, @person for mentions.\n- complete: Mark task done (requires filename + lineIndex or line)\n- update: Update task content/status (requires filename + lineIndex or line)',
             inputSchema: {
                 type: 'object',
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['get', 'search', 'search_global', 'add', 'complete', 'update'],
-                        description: 'Action to perform',
+                        enum: ['get', 'search', 'search_global', 'add', 'complete', 'update', 'list_actions'],
+                        description: 'Action: get | search | search_global | add | complete | update | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -1236,16 +1321,16 @@ export function createServer() {
                     },
                     target: {
                         type: 'string',
-                        description: 'Target for add: date (today/tomorrow/YYYY-MM-DD) for daily notes or filename for project notes',
+                        description: 'Target note for add: use a date string (today, tomorrow, yesterday, YYYY-MM-DD, YYYYMMDD) for daily/calendar notes, or a filename path for project notes. Daily notes are auto-created if they don\'t exist.',
                     },
                     position: {
                         type: 'string',
                         enum: ['start', 'end', 'after-heading', 'in-section'],
-                        description: 'Where to add task (default: end) — used by add',
+                        description: 'Where to add task (default: end). With heading: start=right after heading, end/in-section=end of section. Without heading: start=top of note, end=bottom of note — used by add',
                     },
                     heading: {
                         type: 'string',
-                        description: 'Heading or section marker text (matches both ## headings and **bold:** section markers) — used by add',
+                        description: 'Heading or section marker text to scope insertion (matches both ## headings and **bold:** section markers). Combine with position to control placement — used by add',
                     },
                     lineIndex: {
                         type: 'number',
@@ -1320,8 +1405,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['list', 'find', 'resolve', 'create', 'move', 'rename', 'delete', 'list_spaces'],
-                        description: 'Action to perform',
+                        enum: ['list', 'find', 'resolve', 'create', 'move', 'rename', 'delete', 'list_spaces', 'list_actions'],
+                        description: 'Action: list | find | resolve | create | move | rename | delete | list_spaces | list_actions (discover all actions)',
                     },
                     path: {
                         type: 'string',
@@ -1423,8 +1508,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['list', 'get', 'get_tasks', 'list_parameters', 'save', 'rename'],
-                        description: 'Action to perform',
+                        enum: ['list', 'get', 'get_tasks', 'list_parameters', 'save', 'rename', 'list_actions'],
+                        description: 'Action: list | get | get_tasks | list_parameters | save | rename | list_actions (discover all actions)',
                     },
                     name: {
                         type: 'string',
@@ -1508,8 +1593,8 @@ export function createServer() {
                     },
                     action: {
                         type: 'string',
-                        enum: ['get_events', 'list_calendars', 'create_event', 'update_event', 'delete_event', 'get', 'list_lists', 'create', 'complete', 'update', 'delete'],
-                        description: 'Action to perform',
+                        enum: ['get_events', 'list_calendars', 'create_event', 'update_event', 'delete_event', 'get', 'list_lists', 'create', 'complete', 'update', 'delete', 'list_actions'],
+                        description: 'Action: get_events | list_calendars | create_event | update_event | delete_event | get | list_lists | create | complete | update | delete | list_actions (discover all actions)',
                     },
                     // Calendar params
                     eventId: {
@@ -1610,8 +1695,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['list', 'save', 'update', 'delete'],
-                        description: 'Action to perform',
+                        enum: ['list', 'save', 'update', 'delete', 'list_actions'],
+                        description: 'Action: list | save | update | delete | list_actions (discover all actions)',
                     },
                     id: {
                         type: 'string',
@@ -1657,8 +1742,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['search', 'list_tags'],
-                        description: 'Action to perform (default: search)',
+                        enum: ['search', 'list_tags', 'list_actions'],
+                        description: 'Action to perform (default: search) | list_actions (discover all actions)',
                     },
                     query: {
                         type: 'string',
@@ -1746,8 +1831,8 @@ export function createServer() {
                 properties: {
                     action: {
                         type: 'string',
-                        enum: ['status', 'search', 'sync', 'reset'],
-                        description: 'Action to perform',
+                        enum: ['status', 'search', 'sync', 'reset', 'list_actions'],
+                        description: 'Action: status | search | sync | reset | list_actions (discover all actions)',
                     },
                     query: {
                         type: 'string',
@@ -1824,196 +1909,282 @@ export function createServer() {
             },
         });
     }
-    if (advancedFeaturesEnabled) {
-        toolDefinitions.push({
-            name: 'noteplan_ui',
-            description: 'NotePlan UI control via AppleScript.\n\nActions:\n- open_note: Open a note (title or filename)\n- open_today: Open today\'s note\n- search: Search in UI\n- run_plugin: Run a plugin command (requires pluginId + command)\n- open_view: Open a named view\n- toggle_sidebar: Toggle sidebar visibility\n- close_plugin_window: Close plugin window (by windowID/title, or omit both to close all)\n- list_plugin_windows: List open plugin windows',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    action: {
-                        type: 'string',
-                        enum: ['open_note', 'open_today', 'search', 'run_plugin', 'open_view', 'toggle_sidebar', 'close_plugin_window', 'list_plugin_windows'],
-                        description: 'Action to perform',
-                    },
-                    title: {
-                        type: 'string',
-                        description: 'Note title — used by open_note; window title — used by close_plugin_window',
-                    },
-                    filename: {
-                        type: 'string',
-                        description: 'Filename — used by open_note',
-                    },
-                    inNewWindow: {
-                        type: 'boolean',
-                        description: 'Open in new window — used by open_note',
-                    },
-                    inSplitView: {
-                        type: 'boolean',
-                        description: 'Open in split view — used by open_note',
-                    },
-                    query: {
-                        type: 'string',
-                        description: 'Search text — used by search',
-                    },
-                    pluginId: {
-                        type: 'string',
-                        description: 'Plugin ID — used by run_plugin',
-                    },
-                    command: {
-                        type: 'string',
-                        description: 'Command name — used by run_plugin',
-                    },
-                    arguments: {
-                        type: 'string',
-                        description: 'JSON arguments string — used by run_plugin',
-                    },
-                    name: {
-                        type: 'string',
-                        description: 'View name — used by open_view',
-                    },
-                    windowID: {
-                        type: 'string',
-                        description: 'Window ID — used by close_plugin_window',
-                    },
+    // noteplan_ui is always available — basic AppleScript commands work on all NotePlan versions
+    toolDefinitions.push({
+        name: 'noteplan_ui',
+        description: 'NotePlan UI control via AppleScript.\n\nActions:\n- open_note: Open a note (title or filename)\n- open_today: Open today\'s note\n- search: Search in UI\n- run_plugin: Run a plugin command (requires pluginId + command)\n- open_view: Open a named view\n- toggle_sidebar: Toggle sidebar visibility\n- close_plugin_window: Close plugin window (by windowID/title, or omit both to close all)\n- list_plugin_windows: List open plugin windows\n- backup: Create a full backup of all notes, calendars, themes, filters, and plugin data. Old backups are pruned automatically.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['open_note', 'open_today', 'search', 'run_plugin', 'open_view', 'toggle_sidebar', 'close_plugin_window', 'list_plugin_windows', 'backup', 'list_actions'],
+                    description: 'Action: open_note | open_today | search | run_plugin | open_view | toggle_sidebar | close_plugin_window | list_plugin_windows | backup | list_actions (discover all actions)',
                 },
-                required: ['action'],
-            },
-        }, {
-            name: 'noteplan_plugins',
-            description: 'Plugin management: list, create, delete, install, read source/log, update HTML, screenshot.\n\nActions:\n- list: List installed plugins\n- list_available: List plugins from online repository\n- create: Create plugin with HTML view (requires pluginId, pluginName, commandName, html)\n- delete: Delete plugin (requires pluginId + confirmationToken)\n- install: Install from repository (requires pluginId)\n- log: Read plugin console log (requires pluginId)\n- source: Read plugin source (requires pluginId)\n- update_html: Apply find/replace patches (requires pluginId + patches)\n- screenshot: Capture plugin WebView screenshot (requires pluginId)',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    action: {
-                        type: 'string',
-                        enum: ['list', 'list_available', 'create', 'delete', 'install', 'log', 'source', 'update_html', 'screenshot'],
-                        description: 'Action to perform',
-                    },
-                    pluginId: {
-                        type: 'string',
-                        description: 'Plugin ID — used by create, delete, install, log, source, update_html, screenshot',
-                    },
-                    pluginName: {
-                        type: 'string',
-                        description: 'Display name — used by create',
-                    },
-                    commandName: {
-                        type: 'string',
-                        description: 'Command name — used by create',
-                    },
-                    html: {
-                        type: 'string',
-                        description: 'HTML content — used by create',
-                    },
-                    icon: {
-                        type: 'string',
-                        description: 'Font Awesome icon name — used by create',
-                    },
-                    iconColor: {
-                        type: 'string',
-                        description: 'Tailwind color — used by create',
-                    },
-                    displayMode: {
-                        type: 'string',
-                        enum: ['main', 'split', 'window'],
-                        description: 'Display mode (default: main) — used by create',
-                    },
-                    autoLaunch: {
-                        type: 'boolean',
-                        description: 'Auto-reload and run — used by create, update_html',
-                    },
-                    patches: {
-                        type: 'array',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                find: { type: 'string' },
-                                replace: { type: 'string' },
-                            },
-                            required: ['find', 'replace'],
-                        },
-                        description: 'Find/replace patches — used by update_html',
-                    },
-                    query: {
-                        type: 'string',
-                        description: 'Filter/search — used by list, list_available, source',
-                    },
-                    includeBeta: {
-                        type: 'boolean',
-                        description: 'Include beta plugins — used by list_available',
-                    },
-                    tail: {
-                        type: 'integer',
-                        description: 'Return last N lines — used by log',
-                    },
-                    clear: {
-                        type: 'boolean',
-                        description: 'Clear log after reading — used by log',
-                    },
-                    startLine: {
-                        type: 'integer',
-                        description: 'Start line (1-based) — used by source',
-                    },
-                    endLine: {
-                        type: 'integer',
-                        description: 'End line (1-based) — used by source',
-                    },
-                    contextLines: {
-                        type: 'integer',
-                        description: 'Context lines around matches — used by source',
-                    },
-                    confirmationToken: {
-                        type: 'string',
-                        description: 'Token for confirmation — used by delete',
-                    },
+                title: {
+                    type: 'string',
+                    description: 'Note title — used by open_note; window title — used by close_plugin_window',
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Filename — used by open_note',
+                },
+                inNewWindow: {
+                    type: 'boolean',
+                    description: 'Open in new window — used by open_note',
+                },
+                inSplitView: {
+                    type: 'boolean',
+                    description: 'Open in split view — used by open_note',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search text — used by search',
+                },
+                pluginId: {
+                    type: 'string',
+                    description: 'Plugin ID — used by run_plugin',
+                },
+                command: {
+                    type: 'string',
+                    description: 'Command name — used by run_plugin',
+                },
+                arguments: {
+                    type: 'string',
+                    description: 'JSON arguments string — used by run_plugin',
+                },
+                name: {
+                    type: 'string',
+                    description: 'View name — used by open_view',
+                },
+                windowID: {
+                    type: 'string',
+                    description: 'Window ID — used by close_plugin_window',
                 },
-                required: ['action'],
             },
-        }, {
-            name: 'noteplan_themes',
-            description: 'Theme management: list, get, save, set active.\n\nActions:\n- list: List all themes and active theme names\n- get: Read a custom theme JSON (requires filename)\n- save: Create/update a custom theme (requires filename + theme)\n- set_active: Activate a theme (requires name)',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    action: {
-                        type: 'string',
-                        enum: ['list', 'get', 'save', 'set_active'],
-                        description: 'Action to perform',
-                    },
-                    filename: {
-                        type: 'string',
-                        description: 'Theme filename — used by get, save',
-                    },
-                    name: {
-                        type: 'string',
-                        description: 'Theme name — used by set_active',
-                    },
-                    theme: {
+            required: ['action'],
+        },
+    });
+    // Always register all tools — if NotePlan is too old for a specific action,
+    // the action handler returns a helpful upgrade message instead of hiding the tool entirely.
+    toolDefinitions.push({
+        name: 'noteplan_plugins',
+        description: 'Plugin management: list, create, delete, install, read source/log, update HTML, screenshot.\n\nActions:\n- list: List installed plugins\n- list_available: List plugins from online repository\n- create: Create plugin with HTML view (requires pluginId, pluginName, commandName, html)\n- delete: Delete plugin (requires pluginId + confirmationToken)\n- install: Install from repository (requires pluginId)\n- log: Read plugin console log (requires pluginId)\n- source: Read plugin source (requires pluginId)\n- update_html: Apply find/replace patches (requires pluginId + patches)\n- screenshot: Capture plugin WebView screenshot (requires pluginId)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'list_available', 'create', 'delete', 'install', 'log', 'source', 'update_html', 'screenshot', 'list_actions'],
+                    description: 'Action: list | list_available | create | delete | install | log | source | update_html | screenshot | list_actions (discover all actions)',
+                },
+                pluginId: {
+                    type: 'string',
+                    description: 'Plugin ID — used by create, delete, install, log, source, update_html, screenshot',
+                },
+                pluginName: {
+                    type: 'string',
+                    description: 'Display name — used by create',
+                },
+                commandName: {
+                    type: 'string',
+                    description: 'Command name — used by create',
+                },
+                html: {
+                    type: 'string',
+                    description: 'HTML content — used by create',
+                },
+                icon: {
+                    type: 'string',
+                    description: 'Font Awesome icon name — used by create',
+                },
+                iconColor: {
+                    type: 'string',
+                    description: 'Tailwind color — used by create',
+                },
+                displayMode: {
+                    type: 'string',
+                    enum: ['main', 'split', 'window'],
+                    description: 'Display mode (default: main) — used by create',
+                },
+                autoLaunch: {
+                    type: 'boolean',
+                    description: 'Auto-reload and run — used by create, update_html',
+                },
+                patches: {
+                    type: 'array',
+                    items: {
                         type: 'object',
-                        description: 'Theme object — used by save',
                         properties: {
-                            name: { type: 'string' },
-                            style: { type: 'string', enum: ['Light', 'Dark'] },
-                            author: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } },
-                            editor: { type: 'object' },
-                            styles: { type: 'object' },
+                            find: { type: 'string' },
+                            replace: { type: 'string' },
                         },
+                        required: ['find', 'replace'],
                     },
-                    setActive: {
-                        type: 'boolean',
-                        description: 'Apply theme immediately — used by save (default: true)',
-                    },
-                    mode: {
-                        type: 'string',
-                        enum: ['light', 'dark', 'auto'],
-                        description: 'Mode to apply for — used by save, set_active',
+                    description: 'Find/replace patches — used by update_html',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Filter/search — used by list, list_available, source',
+                },
+                includeBeta: {
+                    type: 'boolean',
+                    description: 'Include beta plugins — used by list_available',
+                },
+                tail: {
+                    type: 'integer',
+                    description: 'Return last N lines — used by log',
+                },
+                clear: {
+                    type: 'boolean',
+                    description: 'Clear log after reading — used by log',
+                },
+                startLine: {
+                    type: 'integer',
+                    description: 'Start line (1-based) — used by source',
+                },
+                endLine: {
+                    type: 'integer',
+                    description: 'End line (1-based) — used by source',
+                },
+                contextLines: {
+                    type: 'integer',
+                    description: 'Context lines around matches — used by source',
+                },
+                confirmationToken: {
+                    type: 'string',
+                    description: 'Token for confirmation — used by delete',
+                },
+            },
+            required: ['action'],
+        },
+    }, {
+        name: 'noteplan_themes',
+        description: 'Theme management: list, get, save, set active.\n\nActions:\n- list: List all themes and active theme names\n- get: Read a custom theme JSON (requires filename)\n- save: Create/update a custom theme (requires filename + theme)\n- set_active: Activate a theme (requires name)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'get', 'save', 'set_active', 'list_actions'],
+                    description: 'Action: list | get | save | set_active | list_actions (discover all actions)',
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Theme filename — used by get, save',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Theme name — used by set_active',
+                },
+                theme: {
+                    type: 'object',
+                    description: 'Theme object — used by save',
+                    properties: {
+                        name: { type: 'string' },
+                        style: { type: 'string', enum: ['Light', 'Dark'] },
+                        author: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } },
+                        editor: { type: 'object' },
+                        styles: { type: 'object' },
                     },
                 },
-                required: ['action'],
+                setActive: {
+                    type: 'boolean',
+                    description: 'Apply theme immediately — used by save (default: true)',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['light', 'dark', 'auto'],
+                    description: 'Mode to apply for — used by save, set_active',
+                },
             },
-        });
-    }
+            required: ['action'],
+        },
+    }, {
+        name: 'noteplan_templates',
+        description: 'Template operations: list available templates, render a template, or search template documentation.\n\nActions:\n- list: List templates from @Templates folder with their types and preview\n- render: Render a template by title (saved template) or raw content string (for debugging). Rendering requires a recent NotePlan build.\n- search_docs: Semantic search over bundled NotePlan template documentation. Requires query param. Uses embeddings API or NotePlan built-in embedding. Returns matched doc chunks ranked by relevance — use this to look up template syntax, helpers, and examples before writing templates.\n- get_doc: Retrieve the full text of a doc chunk by noteTitle and chunkIndex (from search_docs results). Use this to read complete method signatures, format tokens, and examples that may be truncated in search_docs previews.\n\nDebugging workflow: After creating or editing a template, use render with its title or raw content to verify the output. Check variables, date formatting, and logic. If rendering fails or produces unexpected output, read the plugin log via noteplan_plugins(action: "log", pluginId: "np.Templating") for error details.\n\nTemplate syntax: <%- expr %> (output), <% code %> (logic), <%= expr %> (escaped output). Common helpers: date.now("YYYY-MM-DD"), web.weather(), date.tomorrow("format").',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'render', 'search_docs', 'get_doc', 'list_actions'],
+                    description: 'Action: list | render | search_docs | get_doc | list_actions (discover all actions)',
+                },
+                templateTitle: {
+                    type: 'string',
+                    description: 'Template title — used by render (loads a saved template by title)',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Raw template content string — used by render (renders arbitrary template code for debugging)',
+                },
+                folder: {
+                    type: 'string',
+                    description: 'Template subfolder — used by list (default: @Templates)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum results — used by list',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Pagination offset — used by list',
+                },
+                cursor: {
+                    type: 'string',
+                    description: 'Cursor from previous page — used by list',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search query — used by search_docs',
+                },
+                includeContent: {
+                    type: 'boolean',
+                    description: 'Include full chunk text in results — used by search_docs',
+                },
+                noteTitle: {
+                    type: 'string',
+                    description: 'Doc note title — used by get_doc (from search_docs results)',
+                },
+                chunkIndex: {
+                    type: 'number',
+                    description: 'Chunk index — used by get_doc (from search_docs results, default 0)',
+                },
+            },
+            required: ['action'],
+        },
+    }, {
+        name: 'noteplan_attachments',
+        description: 'Attachment operations: add files/images to notes, list attachments, get attachment data, or move between notes.\n\nActions:\n- add: Write a file to the note\'s _attachments folder. Requires data (base64) + attachmentFilename. Returns markdownLink — use noteplan_edit_content to place it in the note (insertLink defaults to false).\n- list: List all attachments for a note with filenames, sizes, and markdown links.\n- get: Get attachment metadata. Set includeData=true for base64 content. Use maxDataSize to cap large images.\n- move: Move an attachment between notes. Source note via id/filename/title/date, destination via destinationId/destinationFilename/destinationTitle/destinationDate. Moves file, removes old link from source, returns new markdownLink.\n\nAttachments are stored in {notename}_attachments/ sibling folder. Images: ![image](path), files: ![file](path). Use attachmentFilename for both add, get, and move.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['add', 'list', 'get', 'move', 'list_actions'],
+                    description: 'Action: add | list | get | move | list_actions (discover all actions)',
+                },
+                id: { type: 'string', description: 'Source note ID — used by all actions' },
+                filename: { type: 'string', description: 'Source note filename/path — used by all actions' },
+                title: { type: 'string', description: 'Source note title — used by all actions' },
+                date: { type: 'string', description: 'Source calendar note date (YYYYMMDD or YYYY-MM-DD) — used by all actions' },
+                query: { type: 'string', description: 'Search query to find the source note' },
+                space: { type: 'string', description: 'Space name or ID' },
+                data: { type: 'string', description: 'Base64-encoded file data — required for add' },
+                attachmentFilename: { type: 'string', description: 'Attachment filename (e.g. "photo.png") — required for add, get, and move' },
+                mimeType: { type: 'string', description: 'MIME type hint (e.g. "image/png") — used by add' },
+                insertLink: { type: 'boolean', description: 'Auto-insert markdown link into note — used by add (default: false). Prefer placing links yourself via noteplan_edit_content.' },
+                destinationId: { type: 'string', description: 'Destination note ID — used by move' },
+                destinationFilename: { type: 'string', description: 'Destination note filename — used by move' },
+                destinationTitle: { type: 'string', description: 'Destination note title — used by move' },
+                destinationDate: { type: 'string', description: 'Destination calendar note date — used by move' },
+                includeData: { type: 'boolean', description: 'Include base64 data in response — used by get (default: false)' },
+                maxDataSize: { type: 'number', description: 'Max file size in bytes for data inclusion — used by get. Files exceeding this are skipped.' },
+            },
+            required: ['action'],
+        },
+    });
     const annotatedToolDefinitions = toolDefinitions.map((tool) => ({
         ...tool,
         inputSchema: withDebugTimingsInputSchema(tool.inputSchema),
@@ -2030,42 +2201,178 @@ export function createServer() {
     });
     // Register resource listing handler
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        return {
-            resources: PLUGIN_API_RESOURCES.map((r) => ({
-                uri: `noteplan://plugin-api/${r.file}`,
-                name: r.name,
-                description: r.desc,
-                mimeType: r.file.endsWith('.md') ? 'text/markdown' : r.file.endsWith('.json') ? 'application/json' : 'text/javascript',
-            })),
-        };
+        const pluginResources = PLUGIN_API_RESOURCES.map((r) => ({
+            uri: `noteplan://plugin-api/${r.file}`,
+            name: r.name,
+            description: r.desc,
+            mimeType: r.file.endsWith('.md') ? 'text/markdown' : r.file.endsWith('.json') ? 'application/json' : 'text/javascript',
+        }));
+        const generalResources = GENERAL_DOC_RESOURCES.map((r) => ({
+            uri: `noteplan://docs/${r.file}`,
+            name: r.name,
+            description: r.desc,
+            mimeType: 'text/markdown',
+        }));
+        return { resources: [...pluginResources, ...generalResources] };
     });
     // Register resource read handler
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const uri = request.params.uri;
-        const prefix = 'noteplan://plugin-api/';
-        if (!uri.startsWith(prefix)) {
-            throw new Error(`Unknown resource URI: ${uri}`);
+        const pluginPrefix = 'noteplan://plugin-api/';
+        const docsPrefix = 'noteplan://docs/';
+        let filePath;
+        if (uri.startsWith(pluginPrefix)) {
+            const filename = uri.slice(pluginPrefix.length);
+            const entry = PLUGIN_API_RESOURCES.find((r) => r.file === filename);
+            if (!entry) {
+                throw new Error(`Unknown resource: ${filename}. Available: ${PLUGIN_API_RESOURCES.map((r) => r.file).join(', ')}`);
+            }
+            filePath = path.join(PLUGIN_API_DOCS_DIR, entry.file);
+        }
+        else if (uri.startsWith(docsPrefix)) {
+            const filename = uri.slice(docsPrefix.length);
+            const entry = GENERAL_DOC_RESOURCES.find((r) => r.file === filename);
+            if (!entry) {
+                throw new Error(`Unknown resource: ${filename}. Available: ${GENERAL_DOC_RESOURCES.map((r) => r.file).join(', ')}`);
+            }
+            filePath = path.join(DOCS_DIR, entry.file);
         }
-        const filename = uri.slice(prefix.length);
-        const entry = PLUGIN_API_RESOURCES.find((r) => r.file === filename);
-        if (!entry) {
-            throw new Error(`Unknown resource: ${filename}. Available: ${PLUGIN_API_RESOURCES.map((r) => r.file).join(', ')}`);
+        else {
+            throw new Error(`Unknown resource URI: ${uri}`);
         }
-        const filePath = path.join(PLUGIN_API_DOCS_DIR, entry.file);
         if (!fs.existsSync(filePath)) {
             throw new Error(`Resource file not found on disk: ${filePath}`);
         }
         const content = fs.readFileSync(filePath, 'utf-8');
+        const mimeType = filePath.endsWith('.md') ? 'text/markdown' : filePath.endsWith('.json') ? 'application/json' : 'text/javascript';
         return {
-            contents: [
-                {
-                    uri,
-                    mimeType: entry.file.endsWith('.md') ? 'text/markdown' : entry.file.endsWith('.json') ? 'application/json' : 'text/javascript',
-                    text: content,
-                },
-            ],
+            contents: [{ uri, mimeType, text: content }],
         };
     });
+    // ── Action registry for list_actions discovery ──
+    const TOOL_ACTIONS = {
+        noteplan_get_notes: [
+            { action: 'get', description: 'Get a single note by id, filename, title, date, or query' },
+            { action: 'list', description: 'List notes with optional folder/type/date filtering' },
+            { action: 'resolve', description: 'Resolve a reference (title, filename, query) to a single note' },
+            { action: 'today', description: 'Get today\'s daily note' },
+            { action: 'calendar', description: 'Get a calendar note by date' },
+            { action: 'periodic', description: 'Get a periodic note (week, month, quarter, year)' },
+            { action: 'range', description: 'Get calendar notes in a date range' },
+        ],
+        noteplan_search: [
+            { action: 'search', description: 'Full-text or metadata search across notes' },
+            { action: 'list_tags', description: 'List all tags/hashtags with optional filtering' },
+        ],
+        noteplan_manage_note: [
+            { action: 'create', description: 'Create a project note (requires title)' },
+            { action: 'update', description: 'Replace note content (requires filename, content, fullReplace + confirmationToken)' },
+            { action: 'delete', description: 'Delete a note (requires dryRun/confirmationToken)' },
+            { action: 'move', description: 'Move a note to another folder (requires dryRun/confirmationToken)' },
+            { action: 'restore', description: 'Restore a trashed note (requires dryRun/confirmationToken)' },
+            { action: 'rename', description: 'Rename a note (requires newTitle)' },
+            { action: 'set_property', description: 'Set a frontmatter property (requires key + value)' },
+            { action: 'remove_property', description: 'Remove a frontmatter property (requires key)' },
+        ],
+        noteplan_edit_content: [
+            { action: 'insert', description: 'Insert content at a position. Use heading param to scope to a section' },
+            { action: 'append', description: 'Append content at end of note or section' },
+            { action: 'delete_lines', description: 'Delete a line range (requires startLine + endLine, 1-indexed)' },
+            { action: 'edit_line', description: 'Edit a single line (requires line + content)' },
+            { action: 'replace_lines', description: 'Replace a line range (requires startLine + endLine + content)' },
+        ],
+        noteplan_paragraphs: [
+            { action: 'get', description: 'Get note lines with metadata (requires filename)' },
+            { action: 'search', description: 'Search for matching lines in a note (requires query + note ref)' },
+            { action: 'search_global', description: 'Search tasks across all notes (requires query, supports "*" wildcard)' },
+            { action: 'add', description: 'Add a task (requires target + content)' },
+            { action: 'complete', description: 'Mark task done (requires filename + lineIndex or line)' },
+            { action: 'update', description: 'Update task content/status (requires filename + lineIndex or line)' },
+        ],
+        noteplan_folders: [
+            { action: 'list', description: 'List folders with optional filtering' },
+            { action: 'find', description: 'Find folder matches for exploration' },
+            { action: 'resolve', description: 'Resolve to one canonical folder path' },
+            { action: 'create', description: 'Create a folder' },
+            { action: 'move', description: 'Move a folder (requires dryRun/confirmationToken)' },
+            { action: 'rename', description: 'Rename a folder (requires dryRun/confirmationToken)' },
+            { action: 'delete', description: 'Delete folder to trash (requires dryRun/confirmationToken)' },
+            { action: 'list_spaces', description: 'List spaces/workspaces' },
+        ],
+        noteplan_filters: [
+            { action: 'list', description: 'List saved filters' },
+            { action: 'get', description: 'Get one filter with parsed params (requires name)' },
+            { action: 'get_tasks', description: 'Execute a filter against tasks (requires name)' },
+            { action: 'list_parameters', description: 'List supported filter parameter keys' },
+            { action: 'save', description: 'Create or update a filter (requires name + items)' },
+            { action: 'rename', description: 'Rename a filter (requires oldName + newName)' },
+        ],
+        noteplan_eventkit: [
+            { action: 'get_events', description: 'Get events for a date/range (source: calendar)' },
+            { action: 'list_calendars', description: 'List all calendars (source: calendar)' },
+            { action: 'create_event', description: 'Create event (source: calendar, requires title + startDate)' },
+            { action: 'update_event', description: 'Update event (source: calendar, requires eventId)' },
+            { action: 'delete_event', description: 'Delete event (source: calendar, requires eventId + dryRun/confirmationToken)' },
+            { action: 'get', description: 'Get reminders (source: reminders, optional list/query filter)' },
+            { action: 'list_lists', description: 'List reminder lists (source: reminders)' },
+            { action: 'create', description: 'Create reminder (source: reminders, requires title)' },
+            { action: 'complete', description: 'Mark reminder done (source: reminders, requires reminderId)' },
+            { action: 'update', description: 'Update reminder (source: reminders, requires reminderId)' },
+            { action: 'delete', description: 'Delete reminder (source: reminders, requires reminderId + dryRun/confirmationToken)' },
+        ],
+        noteplan_memory: [
+            { action: 'list', description: 'List/search stored memories' },
+            { action: 'save', description: 'Save a new memory (requires content)' },
+            { action: 'update', description: 'Update memory content/tags (requires id)' },
+            { action: 'delete', description: 'Delete a memory (requires id)' },
+        ],
+        noteplan_ui: [
+            { action: 'open_note', description: 'Open a note by title or filename' },
+            { action: 'open_today', description: 'Open today\'s note' },
+            { action: 'search', description: 'Search in UI' },
+            { action: 'run_plugin', description: 'Run a plugin command (requires pluginId + command)' },
+            { action: 'open_view', description: 'Open a named view' },
+            { action: 'toggle_sidebar', description: 'Toggle sidebar visibility' },
+            { action: 'close_plugin_window', description: 'Close plugin window (by windowID/title, or omit both to close all)' },
+            { action: 'list_plugin_windows', description: 'List open plugin windows' },
+            { action: 'backup', description: 'Create a full backup of all notes, calendars, themes, filters, and plugin data' },
+        ],
+        noteplan_plugins: [
+            { action: 'list', description: 'List installed plugins' },
+            { action: 'list_available', description: 'List plugins from online repository' },
+            { action: 'create', description: 'Create plugin with HTML view (requires pluginId, pluginName, commandName, html)' },
+            { action: 'delete', description: 'Delete plugin (requires pluginId + confirmationToken)' },
+            { action: 'install', description: 'Install from repository (requires pluginId)' },
+            { action: 'log', description: 'Read plugin console log (requires pluginId)' },
+            { action: 'source', description: 'Read plugin source (requires pluginId)' },
+            { action: 'update_html', description: 'Apply find/replace patches (requires pluginId + patches)' },
+            { action: 'screenshot', description: 'Capture plugin WebView screenshot (requires pluginId)' },
+        ],
+        noteplan_themes: [
+            { action: 'list', description: 'List all themes and active theme names' },
+            { action: 'get', description: 'Read a custom theme JSON (requires filename)' },
+            { action: 'save', description: 'Create/update a custom theme (requires filename + theme)' },
+            { action: 'set_active', description: 'Activate a theme (requires name)' },
+        ],
+        noteplan_embeddings: [
+            { action: 'status', description: 'Get embeddings config and index status' },
+            { action: 'search', description: 'Semantic search over indexed notes (requires query)' },
+            { action: 'sync', description: 'Build/refresh embeddings index' },
+            { action: 'reset', description: 'Delete index rows (requires dryRun/confirmationToken)' },
+        ],
+        noteplan_templates: [
+            { action: 'list', description: 'List templates from @Templates folder with types and preview' },
+            { action: 'render', description: 'Render a template by title or raw content string' },
+            { action: 'search_docs', description: 'Semantic search over bundled template documentation (requires query). Use this to look up template syntax, helpers, and examples before writing templates' },
+            { action: 'get_doc', description: 'Get full text of a doc chunk by noteTitle + chunkIndex (from search_docs results)' },
+        ],
+        noteplan_attachments: [
+            { action: 'add', description: 'Write a file to the note\'s _attachments folder (requires data + attachmentFilename)' },
+            { action: 'list', description: 'List all attachments for a note' },
+            { action: 'get', description: 'Get attachment metadata. Set includeData=true for base64 content' },
+            { action: 'move', description: 'Move an attachment between notes' },
+        ],
+    };
     // Register tool call handler
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
@@ -2074,6 +2381,12 @@ export function createServer() {
         const startTime = Date.now();
         try {
             let result;
+            // ── Intercept list_actions for any tool with an action registry ──
+            if (args?.action === 'list_actions' && TOOL_ACTIONS[normalizedName]) {
+                result = { success: true, tool: normalizedName, actions: TOOL_ACTIONS[normalizedName] };
+                const resultWithDuration = withDuration(result, Date.now() - startTime, includeTiming);
+                return { content: [{ type: 'text', text: JSON.stringify(resultWithDuration, null, 2) }] };
+            }
             switch (normalizedName) {
                 // ── Primary consolidated tools ──
                 case 'noteplan_get_notes':
@@ -2121,7 +2434,7 @@ export function createServer() {
                         case 'remove_property':
                             result = noteTools.removeProperty(args);
                             break;
-                        default: throw new Error(`Unknown action: ${action}`);
+                        default: throw new Error(`Unknown action: "${action}". Valid actions: create, update, delete, move, restore, rename, set_property, remove_property`);
                     }
                     break;
                 }
@@ -2152,7 +2465,7 @@ export function createServer() {
                         case 'replace_lines':
                             result = noteTools.replaceLines(a);
                             break;
-                        default: throw new Error(`Unknown action: ${action}`);
+                        default: throw new Error(`Unknown action: "${action}". Valid actions: insert, append, delete_lines, edit_line, replace_lines (snake_case required)`);
                     }
                     break;
                 }
@@ -2166,6 +2479,10 @@ export function createServer() {
                     if (a.scheduleDate && a.content) {
                         a.content = appendScheduleDate(a.content, a.scheduleDate);
                     }
+                    // Derive `target` for addTaskToNote from date/filename when not provided
+                    if (!a.target && (a.date || a.filename)) {
+                        a.target = a.date || a.filename;
+                    }
                     const action = a?.action;
                     switch (action) {
                         case 'get':
@@ -2175,7 +2492,7 @@ export function createServer() {
                             result = noteTools.searchParagraphs(a);
                             break;
                         case 'search_global':
-                            result = taskTools.searchTasksGlobal(a);
+                            result = noteTools.searchParagraphsGlobal(a);
                             break;
                         case 'add':
                             result = taskTools.addTaskToNote(a);
@@ -2346,7 +2663,67 @@ export function createServer() {
                         case 'list_plugin_windows':
                             result = uiTools.listPluginWindows(args);
                             break;
-                        default: throw new Error(`Unknown action: ${action}`);
+                        case 'backup': {
+                            if (versionInfo.build < MIN_BUILD_CREATE_BACKUP) {
+                                result = { success: false, error: `Backup requires NotePlan build ${MIN_BUILD_CREATE_BACKUP}+. Current: ${versionInfo.build}.`, code: 'ERR_VERSION_GATE' };
+                            }
+                            else {
+                                result = uiTools.createBackup(args);
+                            }
+                            break;
+                        }
+                        default: {
+                            // Help the LLM recover from common mistakes (camelCase, missing underscore, etc.)
+                            const UI_ACTION_ALIASES = {
+                                open: 'open_note', opennote: 'open_note', open_notes: 'open_note',
+                                opentoday: 'open_today', today: 'open_today',
+                                openview: 'open_view', view: 'open_view',
+                                runplugin: 'run_plugin', plugin: 'run_plugin',
+                                togglesidebar: 'toggle_sidebar', sidebar: 'toggle_sidebar',
+                                closepluginwindow: 'close_plugin_window',
+                                listpluginwindows: 'list_plugin_windows',
+                                navigate: 'open_note', show: 'open_note', select: 'open_note',
+                            };
+                            const normalized = (action || '').toLowerCase().replace(/[\s_-]/g, '');
+                            const resolved = UI_ACTION_ALIASES[normalized];
+                            if (resolved) {
+                                args.action = resolved;
+                                // Re-dispatch with corrected action
+                                switch (resolved) {
+                                    case 'open_note':
+                                        result = uiTools.openNote(args);
+                                        break;
+                                    case 'open_today':
+                                        result = uiTools.openToday(args);
+                                        break;
+                                    case 'search':
+                                        result = uiTools.searchNotes(args);
+                                        break;
+                                    case 'run_plugin':
+                                        result = uiTools.runPlugin(args);
+                                        break;
+                                    case 'open_view':
+                                        result = uiTools.openView(args);
+                                        break;
+                                    case 'toggle_sidebar':
+                                        result = uiTools.toggleSidebar(args);
+                                        break;
+                                    case 'close_plugin_window':
+                                        result = uiTools.closePluginWindow(args);
+                                        break;
+                                    case 'list_plugin_windows':
+                                        result = uiTools.listPluginWindows(args);
+                                        break;
+                                    case 'backup':
+                                        result = uiTools.createBackup(args);
+                                        break;
+                                    default: throw new Error(`Unknown action: ${action}. Valid actions: open_note, open_today, search, run_plugin, open_view, toggle_sidebar, close_plugin_window, list_plugin_windows, backup`);
+                                }
+                            }
+                            else {
+                                throw new Error(`Unknown action: "${action}". Valid actions: open_note, open_today, search, run_plugin, open_view, toggle_sidebar, close_plugin_window, list_plugin_windows, backup`);
+                            }
+                        }
                     }
                     break;
                 }
@@ -2422,6 +2799,44 @@ export function createServer() {
                     }
                     break;
                 }
+                case 'noteplan_templates': {
+                    const action = args?.action;
+                    switch (action) {
+                        case 'list':
+                            result = templateTools.listTemplates(args);
+                            break;
+                        case 'render':
+                            result = templateTools.renderTemplate(args);
+                            break;
+                        case 'search_docs':
+                            result = await templateTools.searchDocs(args);
+                            break;
+                        case 'get_doc':
+                            result = templateTools.getDoc(args);
+                            break;
+                        default: throw new Error(`Unknown action: ${action}`);
+                    }
+                    break;
+                }
+                case 'noteplan_attachments': {
+                    const action = args?.action;
+                    switch (action) {
+                        case 'add':
+                            result = attachmentTools.addAttachment(args);
+                            break;
+                        case 'list':
+                            result = attachmentTools.listAttachments(args);
+                            break;
+                        case 'get':
+                            result = attachmentTools.getAttachment(args);
+                            break;
+                        case 'move':
+                            result = attachmentTools.moveAttachment(args);
+                            break;
+                        default: throw new Error(`Unknown action: ${action}. Valid actions: add, list, get, move`);
+                    }
+                    break;
+                }
                 default:
                     throw new Error(`Unknown tool: ${name} (normalized: ${normalizedName})`);
             }
@@ -2462,7 +2877,12 @@ export function createServer() {
             };
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            let errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            // Append list_actions hint for unknown action errors
+            if (errorMessage.includes('Unknown action') && TOOL_ACTIONS[normalizedName]) {
+                const validActions = TOOL_ACTIONS[normalizedName].map(a => a.action).join(', ');
+                errorMessage += `. Valid actions: ${validActions}. Tip: use action "list_actions" to discover all actions with descriptions.`;
+            }
             const meta = inferToolErrorMeta(normalizedName, errorMessage, registeredToolNames);
             const errorResult = {
                 success: false,