remnote-mcp-server 0.15.0 → 0.17.0

package/dist/tools/index.js

@@ -3,18 +3,39 @@ import { CreateNoteSchema } from '../schemas/remnote-schemas.js';
 import { SearchSchema } from '../schemas/remnote-schemas.js';
 import { SearchByTagSchema } from '../schemas/remnote-schemas.js';
 import { ReadNoteSchema } from '../schemas/remnote-schemas.js';
+import { GetMediaSchema } from '../schemas/remnote-schemas.js';
 import { UpdateNoteSchema } from '../schemas/remnote-schemas.js';
+import { SetDocumentStatusSchema } from '../schemas/remnote-schemas.js';
+import { ListChildrenSchema } from '../schemas/remnote-schemas.js';
+import { MoveNoteSchema } from '../schemas/remnote-schemas.js';
 import { InsertChildrenSchema } from '../schemas/remnote-schemas.js';
 import { ReplaceChildrenSchema } from '../schemas/remnote-schemas.js';
 import { UpdateTagsSchema } from '../schemas/remnote-schemas.js';
+import { SetPropertySchema } from '../schemas/remnote-schemas.js';
 import { AppendJournalSchema } from '../schemas/remnote-schemas.js';
 import { ReadTableSchema } from '../schemas/remnote-schemas.js';
 import { checkVersionCompatibility } from '../version-compat.js';
+import { parseMediaLocator, resolveManagedImage } from '../media.js';
+const MEDIA_CAPABILITY = 'media.images.v1';
 const NAVIGATION_PRESET = {
-    includeContent: 'structured',
+    contentMode: 'structured',
+    view: 'compact',
     depth: 1,
     childLimit: 500,
 };
+const ANCESTOR_SCHEMA = {
+    type: 'object',
+    properties: {
+        remId: { type: 'string', description: 'Ancestor Rem ID' },
+        title: { type: 'string', description: 'Rendered ancestor title' },
+        remType: {
+            type: 'string',
+            description: 'Ancestor Rem classification when available',
+        },
+    },
+    required: ['remId', 'title'],
+    additionalProperties: false,
+};
 const TAG_INFO_SCHEMA = {
     type: 'object',
     properties: {
@@ -24,19 +45,70 @@ const TAG_INFO_SCHEMA = {
     required: ['tagRemId', 'name'],
     additionalProperties: false,
 };
+const INLINE_REF_SCHEMA = {
+    type: 'object',
+    properties: {
+        text: { type: 'string', description: 'Rendered target text used in output' },
+        targetRemId: { type: 'string', description: 'Exact target Rem ID' },
+        kind: { type: 'string', enum: ['rem'], description: 'Inline reference kind' },
+    },
+    required: ['text', 'targetRemId', 'kind'],
+    additionalProperties: false,
+};
+const MATCHED_REM_SCHEMA = {
+    type: 'object',
+    properties: {
+        remId: { type: 'string', description: 'Directly tagged Rem ID' },
+        title: { type: 'string', description: 'Rendered title with markdown formatting' },
+        headline: { type: 'string', description: 'Display-oriented full line' },
+        inlineRefs: {
+            type: 'array',
+            items: INLINE_REF_SCHEMA,
+            description: 'Resolvable inline Rem references from the matched Rem title/headline',
+        },
+        remType: {
+            type: 'string',
+            description: 'Rem classification: document, dailyDocument, concept, descriptor, portal, or text',
+        },
+        parentRemId: {
+            type: 'string',
+            description: 'Direct parent Rem ID (omitted for top-level Rems)',
+        },
+        parentTitle: {
+            type: 'string',
+            description: 'Direct parent title/front text (omitted for top-level Rems)',
+        },
+        ancestors: {
+            type: 'array',
+            items: ANCESTOR_SCHEMA,
+            description: 'Parent-first ancestor chain when ancestorDepth is greater than zero',
+        },
+        ancestorsTruncated: {
+            type: 'boolean',
+            description: 'Whether the ancestor chain was capped by ancestorDepth',
+        },
+        tags: {
+            type: 'array',
+            items: TAG_INFO_SCHEMA,
+            description: 'Direct tags applied to the matched Rem as exact tag Rem IDs plus names',
+        },
+    },
+    required: ['remId', 'title', 'headline', 'remType'],
+    additionalProperties: false,
+};
 export const CREATE_NOTE_TOOL = {
     name: 'remnote_create_note',
-    description: 'Create a new note in RemNote with optional content, parent, and exact tag Rem IDs. Supports hierarchical markdown in content and flashcard syntax (e.g. "- Term :: Definition"). At least one of title or content must be provided. Recommended preflight once per session: remnote_status.',
+    description: 'Create a new note in RemNote with optional content, parent, and exact tag Rem IDs. Supports hierarchical markdown, flashcard syntax (e.g. "- Term :: Definition"), and exact inline Rem references as [[id:<remId>]]. At least one of title or content must be provided. Recommended preflight once per session: remnote_status.',
     inputSchema: {
         type: 'object',
         properties: {
             title: {
                 type: 'string',
-                description: 'The title of the note (optional if content is provided)',
+                description: 'The title of the note (optional if content is provided). Supports exact Rem references as [[id:<remId>]].',
             },
             content: {
                 type: 'string',
-                description: 'Content as plain text, child bullets or hierarchical markdown',
+                description: 'Content as plain text, child bullets, or hierarchical markdown. Use [[id:<remId>]] for exact Rem references.',
             },
             parentId: { type: 'string', description: 'Parent Rem ID' },
             tagRemIds: {
@@ -44,6 +116,10 @@ export const CREATE_NOTE_TOOL = {
                 items: { type: 'string' },
                 description: 'Exact tag Rem IDs to apply',
             },
+            asDocument: {
+                type: 'boolean',
+                description: 'Mark the created title/root Rem as a document while preserving any concept/card status',
+            },
         },
         required: [],
         additionalProperties: false,
@@ -67,17 +143,35 @@ export const CREATE_NOTE_TOOL = {
 };
 export const SEARCH_TOOL = {
     name: 'remnote_search',
-    description: 'Search the RemNote knowledge base. For whole-KB orientation, prefer includeContent="structured" with depth=1 and childLimit=500, then follow remIds with remnote_read_note. Use includeContent="markdown" for human-readable summaries.',
+    description: 'Search the RemNote knowledge base. Supports cursor paging through hasMore/nextCursor. For whole-KB orientation, prefer contentMode="structured" with view="compact", depth=1, and childLimit=500. Request ancestorDepth when hierarchy context matters.',
     inputSchema: {
         type: 'object',
         properties: {
             query: { type: 'string', description: 'Search query text' },
+            parentRemId: {
+                type: 'string',
+                minLength: 1,
+                description: "Optional non-empty Rem ID. Scope the search to within this Rem's subtree. The Rem itself is excluded from results.",
+            },
             limit: { type: 'number', description: 'Maximum results (1-150, default: 50)' },
-            includeContent: {
+            cursor: {
+                type: 'string',
+                description: 'Opaque cursor returned by a previous remnote_search response',
+            },
+            contentMode: {
                 type: 'string',
                 enum: ['none', 'markdown', 'structured'],
                 description: 'Content rendering mode: "none" omits content (default), "markdown" renders child subtree as indented markdown, "structured" returns nested child objects with remIds',
             },
+            view: {
+                type: 'string',
+                enum: ['compact', 'standard', 'full'],
+                description: 'Output detail level: compact, standard, or full',
+            },
+            ancestorDepth: {
+                type: 'number',
+                description: 'Number of parent Rems to include, direct parent first (0-20, default: 0)',
+            },
             depth: {
                 type: 'number',
                 description: 'Depth of child hierarchy to render for markdown/structured content (0-10, default: 1)',
@@ -108,6 +202,11 @@ export const SEARCH_TOOL = {
                             type: 'string',
                             description: 'Display-oriented full line: title + type-aware delimiter + detail (e.g. "Term :: Definition")',
                         },
+                        inlineRefs: {
+                            type: 'array',
+                            items: INLINE_REF_SCHEMA,
+                            description: 'Resolvable inline Rem references from the rendered title/headline. Markdown text preserves these as [[Target Title]].',
+                        },
                         parentRemId: {
                             type: 'string',
                             description: 'Direct parent Rem ID (omitted for top-level Rems)',
@@ -116,6 +215,15 @@ export const SEARCH_TOOL = {
                             type: 'string',
                             description: 'Direct parent title/front text (omitted for top-level Rems)',
                         },
+                        ancestors: {
+                            type: 'array',
+                            items: ANCESTOR_SCHEMA,
+                            description: 'Parent-first ancestor chain when ancestorDepth is greater than zero',
+                        },
+                        ancestorsTruncated: {
+                            type: 'boolean',
+                            description: 'Whether the ancestor chain was capped by ancestorDepth',
+                        },
                         aliases: {
                             type: 'array',
                             items: { type: 'string' },
@@ -130,17 +238,35 @@ export const SEARCH_TOOL = {
                             type: 'string',
                             description: 'Rem classification: document, dailyDocument, concept, descriptor, portal, or text',
                         },
+                        matchedRems: {
+                            type: 'array',
+                            items: MATCHED_REM_SCHEMA,
+                            description: 'For remnote_search_by_tag context mode, direct Rems carrying the requested tag that produced this context result',
+                        },
+                        contextRemId: {
+                            type: 'string',
+                            description: 'For remnote_search_by_tag tagged mode, resolved ancestor/context Rem ID for this direct match',
+                        },
+                        contextTitle: {
+                            type: 'string',
+                            description: 'For remnote_search_by_tag tagged mode, resolved ancestor/context title for this direct match',
+                        },
+                        contextReason: {
+                            type: 'string',
+                            enum: ['ancestor-document', 'ancestor-concept', 'ancestor-context', 'self'],
+                            description: 'For remnote_search_by_tag tagged mode, why the context Rem was selected',
+                        },
                         cardDirection: {
                             type: 'string',
                             description: 'Flashcard direction: forward, reverse, or bidirectional (omitted if not a flashcard)',
                         },
                         content: {
                             type: 'string',
-                            description: 'Rendered markdown content of child subtree (only when includeContent="markdown")',
+                            description: 'Rendered markdown content of child subtree (only when contentMode="markdown")',
                         },
                         contentStructured: {
                             type: 'array',
-                            description: 'Structured child subtree with nested remIds and metadata (only when includeContent="structured")',
+                            description: 'Structured child subtree with nested remIds and metadata (only when contentMode="structured")',
                             items: {
                                 type: 'object',
                                 properties: {
@@ -150,6 +276,11 @@ export const SEARCH_TOOL = {
                                         type: 'string',
                                         description: 'Display-oriented child line with type-aware delimiter',
                                     },
+                                    inlineRefs: {
+                                        type: 'array',
+                                        items: INLINE_REF_SCHEMA,
+                                        description: 'Resolvable inline Rem references from the child title/headline',
+                                    },
                                     aliases: {
                                         type: 'array',
                                         items: { type: 'string' },
@@ -170,11 +301,11 @@ export const SEARCH_TOOL = {
                                     },
                                     children: {
                                         type: 'array',
-                                        description: 'Nested child nodes (same shape recursively)',
+                                        description: 'Nested child nodes (same shape recursively; omitted for leaf nodes)',
                                         items: { type: 'object' },
                                     },
                                 },
-                                required: ['remId', 'title', 'headline', 'remType', 'children'],
+                                required: ['remId', 'title', 'headline', 'remType'],
                             },
                         },
                         contentProperties: {
@@ -198,12 +329,29 @@ export const SEARCH_TOOL = {
                     },
                 },
             },
+            hasMore: {
+                type: 'boolean',
+                description: 'Whether more results are available through nextCursor',
+            },
+            nextCursor: {
+                type: 'string',
+                description: 'Opaque cursor for the next page when hasMore is true',
+            },
+            truncated: {
+                type: 'boolean',
+                description: 'Whether search results may be incomplete because the bridge hit its snapshot cap',
+            },
+            truncationReason: {
+                type: 'string',
+                enum: ['cursor_snapshot_limit'],
+                description: 'Reason search results may be incomplete when truncated is true',
+            },
         },
     },
 };
 export const SEARCH_BY_TAG_TOOL = {
     name: 'remnote_search_by_tag',
-    description: 'Find notes by exact tag Rem ID and return resolved ancestor context targets (nearest document/daily document when available, otherwise nearest non-document ancestor). Does not look up tags by name or alias. Supports the same includeContent modes as remnote_search.',
+    description: 'Find notes by exact tag Rem ID. Supports cursor paging through hasMore/nextCursor. Default resultMode="context" returns resolved ancestor context targets with matchedRems; resultMode="tagged" returns directly tagged Rems with context metadata. Request ancestorDepth to include parent-first ancestors on both context results and matchedRems.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -211,12 +359,26 @@ export const SEARCH_BY_TAG_TOOL = {
                 type: 'string',
                 description: 'Exact tag Rem ID to search',
             },
+            resultMode: {
+                type: 'string',
+                enum: ['context', 'tagged'],
+                description: '"context" returns resolved ancestor context targets with matchedRems (default); "tagged" returns directly tagged Rems with context metadata',
+            },
             limit: { type: 'number', description: 'Maximum results (1-150, default: 50)' },
-            includeContent: {
+            contentMode: {
                 type: 'string',
                 enum: ['none', 'markdown', 'structured'],
                 description: 'Content rendering mode: "none" omits content (default), "markdown" renders child subtree as indented markdown, "structured" returns nested child objects with remIds',
             },
+            view: {
+                type: 'string',
+                enum: ['compact', 'standard', 'full'],
+                description: 'Output detail level: compact, standard, or full',
+            },
+            ancestorDepth: {
+                type: 'number',
+                description: 'Number of parent Rems to include, direct parent first (0-20, default: 0)',
+            },
             depth: {
                 type: 'number',
                 description: 'Depth of child hierarchy to render for markdown/structured content (0-10, default: 1)',
@@ -229,14 +391,31 @@ export const SEARCH_BY_TAG_TOOL = {
                 type: 'number',
                 description: 'Maximum character length for rendered content (default: 3000)',
             },
+            cursor: {
+                type: 'string',
+                description: 'Opaque cursor returned by a previous remnote_search_by_tag response',
+            },
+            timeoutMs: {
+                type: 'number',
+                description: 'Per-call bridge wait timeout in milliseconds (1-60000, default: 15000). Does not cancel plugin-side work.',
+            },
         },
         required: ['tagRemId'],
     },
-    outputSchema: SEARCH_TOOL.outputSchema,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            results: SEARCH_TOOL.outputSchema.properties.results,
+            hasMore: SEARCH_TOOL.outputSchema.properties.hasMore,
+            nextCursor: SEARCH_TOOL.outputSchema.properties.nextCursor,
+            truncated: SEARCH_TOOL.outputSchema.properties.truncated,
+            truncationReason: SEARCH_TOOL.outputSchema.properties.truncationReason,
+        },
+    },
 };
 export const READ_NOTE_TOOL = {
     name: 'remnote_read_note',
-    description: 'Read a specific note from RemNote by its Rem ID. For hierarchy traversal, prefer includeContent="structured" and start shallow (depth=1, childLimit=500), then deepen only selected branches. Use includeContent="markdown" for summarization.',
+    description: 'Read a specific note from RemNote by its Rem ID. For hierarchy traversal, prefer contentMode="structured" and start shallow (depth=1, childLimit=500), then deepen only selected branches. Request ancestorDepth when placement context matters.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -245,11 +424,20 @@ export const READ_NOTE_TOOL = {
                 type: 'number',
                 description: 'Depth of child hierarchy to render (0-10, default: 5)',
             },
-            includeContent: {
+            contentMode: {
                 type: 'string',
                 enum: ['none', 'markdown', 'structured'],
                 description: 'Content rendering mode: "markdown" renders child subtree (default), "structured" returns nested child objects with remIds, "none" omits content',
             },
+            view: {
+                type: 'string',
+                enum: ['compact', 'standard', 'full'],
+                description: 'Output detail level: compact, standard, or full',
+            },
+            ancestorDepth: {
+                type: 'number',
+                description: 'Number of parent Rems to include, direct parent first (0-20, default: 0)',
+            },
             childLimit: {
                 type: 'number',
                 description: 'Maximum children per level (1-500, default: 100)',
@@ -258,6 +446,10 @@ export const READ_NOTE_TOOL = {
                 type: 'number',
                 description: 'Maximum character length for rendered content (default: 100000)',
             },
+            includeMediaMetadata: {
+                type: 'boolean',
+                description: 'Include ordered image metadata from the root Rem text and backText fields (default: false)',
+            },
         },
         required: ['remId'],
     },
@@ -270,6 +462,11 @@ export const READ_NOTE_TOOL = {
                 type: 'string',
                 description: 'Display-oriented full line: title + type-aware delimiter + detail (e.g. "Term :: Definition")',
             },
+            inlineRefs: {
+                type: 'array',
+                items: INLINE_REF_SCHEMA,
+                description: 'Resolvable inline Rem references from the rendered title/headline. Markdown text preserves these as [[Target Title]].',
+            },
             parentRemId: {
                 type: 'string',
                 description: 'Direct parent Rem ID (omitted for top-level Rems)',
@@ -278,6 +475,15 @@ export const READ_NOTE_TOOL = {
                 type: 'string',
                 description: 'Direct parent title/front text (omitted for top-level Rems)',
             },
+            ancestors: {
+                type: 'array',
+                items: ANCESTOR_SCHEMA,
+                description: 'Parent-first ancestor chain when ancestorDepth is greater than zero',
+            },
+            ancestorsTruncated: {
+                type: 'boolean',
+                description: 'Whether the ancestor chain was capped by ancestorDepth',
+            },
             aliases: {
                 type: 'array',
                 items: { type: 'string' },
@@ -298,11 +504,11 @@ export const READ_NOTE_TOOL = {
             },
             content: {
                 type: 'string',
-                description: 'Rendered markdown content of child subtree (when includeContent="markdown", which is the default)',
+                description: 'Rendered markdown content of child subtree (when contentMode="markdown", which is the default)',
             },
             contentStructured: {
                 type: 'array',
-                description: 'Structured child subtree with nested remIds and metadata (only when includeContent="structured")',
+                description: 'Structured child subtree with nested remIds and metadata (only when contentMode="structured")',
                 items: {
                     type: 'object',
                     properties: {
@@ -312,6 +518,11 @@ export const READ_NOTE_TOOL = {
                             type: 'string',
                             description: 'Display-oriented child line with type-aware delimiter',
                         },
+                        inlineRefs: {
+                            type: 'array',
+                            items: INLINE_REF_SCHEMA,
+                            description: 'Resolvable inline Rem references from the child title/headline',
+                        },
                         aliases: {
                             type: 'array',
                             items: { type: 'string' },
@@ -332,11 +543,11 @@ export const READ_NOTE_TOOL = {
                         },
                         children: {
                             type: 'array',
-                            description: 'Nested child nodes (same shape recursively)',
+                            description: 'Nested child nodes (same shape recursively; omitted for leaf nodes)',
                             items: { type: 'object' },
                         },
                     },
-                    required: ['remId', 'title', 'headline', 'remType', 'children'],
+                    required: ['remId', 'title', 'headline', 'remType'],
                 },
             },
             contentProperties: {
@@ -357,17 +568,193 @@ export const READ_NOTE_TOOL = {
                     },
                 },
             },
+            media: {
+                type: 'array',
+                description: 'Ordered root-Rem image metadata from text followed by backText when includeMediaMetadata is true',
+                items: {
+                    type: 'object',
+                    properties: {
+                        mediaId: { type: 'string' },
+                        kind: { type: 'string', enum: ['image'] },
+                        field: { type: 'string', enum: ['text', 'backText'] },
+                        elementIndex: { type: 'number' },
+                        imageIndex: { type: 'number' },
+                        imgId: { type: 'string' },
+                        title: { type: 'string' },
+                        dimensions: {
+                            type: 'object',
+                            properties: { width: { type: 'number' }, height: { type: 'number' } },
+                            required: ['width', 'height'],
+                        },
+                        mimeType: { type: 'string' },
+                        source: { type: 'string', enum: ['remnote_managed_local'] },
+                    },
+                    required: ['mediaId', 'kind', 'field', 'elementIndex', 'imageIndex'],
+                },
+            },
         },
     },
 };
+export const GET_MEDIA_TOOL = {
+    name: 'remnote_get_media',
+    description: 'Retrieve a RemNote-managed local image as MCP-native image content. First call remnote_read_note with includeMediaMetadata=true, then pass the returned remId, field, and mediaId. Requires bridge capability media.images.v1. External URL retrieval is not supported.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string', description: 'Root Rem ID containing the image' },
+            field: {
+                type: 'string',
+                enum: ['text', 'backText'],
+                description: 'Rich-text field containing the image',
+            },
+            mediaId: {
+                type: 'string',
+                description: 'Stable media ID returned by remnote_read_note',
+            },
+            maxInlineBytes: {
+                type: 'number',
+                description: 'Maximum bytes to inline (default 5 MiB, hard maximum 10 MiB)',
+            },
+        },
+        required: ['remId', 'field', 'mediaId'],
+        additionalProperties: false,
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string' },
+            mediaId: { type: 'string' },
+            kind: { type: 'string', enum: ['image'] },
+            field: { type: 'string', enum: ['text', 'backText'] },
+            elementIndex: { type: 'number' },
+            imageIndex: { type: 'number' },
+            imgId: { type: 'string' },
+            title: { type: 'string' },
+            dimensions: {
+                type: 'object',
+                properties: { width: { type: 'number' }, height: { type: 'number' } },
+                required: ['width', 'height'],
+            },
+            mimeType: { type: 'string' },
+            source: { type: 'string', enum: ['remnote_managed_local'] },
+            sizeBytes: { type: 'number' },
+        },
+        required: [
+            'remId',
+            'mediaId',
+            'kind',
+            'field',
+            'elementIndex',
+            'imageIndex',
+            'mimeType',
+            'source',
+            'sizeBytes',
+        ],
+    },
+};
+export const LIST_CHILDREN_TOOL = {
+    name: 'remnote_list_children',
+    description: 'List direct child Rems under a parent without rendering a subtree. Use for cheap hierarchy traversal; page with nextCursor when hasMore is true.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            parentRemId: { type: 'string', description: 'Parent Rem ID whose direct children to list' },
+            limit: { type: 'number', description: 'Maximum direct children (1-150, default: 50)' },
+            cursor: {
+                type: 'string',
+                description: 'Opaque cursor returned by a previous remnote_list_children response',
+            },
+            view: {
+                type: 'string',
+                enum: ['compact', 'standard', 'full'],
+                description: 'Output detail level for child metadata: compact, standard, or full',
+            },
+            ancestorDepth: {
+                type: 'number',
+                description: 'Number of parent Rems to include for each child, direct parent first',
+            },
+        },
+        required: ['parentRemId'],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            children: {
+                type: 'array',
+                items: SEARCH_TOOL.outputSchema.properties.results.items,
+            },
+            hasMore: SEARCH_TOOL.outputSchema.properties.hasMore,
+            nextCursor: SEARCH_TOOL.outputSchema.properties.nextCursor,
+            totalChildren: {
+                type: 'number',
+                description: 'Total direct children observed when listing this parent',
+            },
+        },
+    },
+};
+export const MOVE_NOTE_TOOL = {
+    name: 'remnote_move_note',
+    description: 'Safely move an existing Rem and its subtree under a new parent. Defaults to dryRun=true; pass dryRun=false only after user approval. expectedOldParentRemId rejects stale move proposals.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string', description: 'Rem ID to move' },
+            newParentRemId: { type: 'string', description: 'New parent Rem ID' },
+            position: {
+                type: 'string',
+                enum: ['first', 'last', 'before', 'after'],
+                description: 'Where to place the moved Rem under the new parent (default: last)',
+            },
+            siblingRemId: {
+                type: 'string',
+                description: 'Sibling Rem ID required for before/after positioning',
+            },
+            dryRun: {
+                type: 'boolean',
+                description: 'Preview without mutating RemNote (default: true)',
+            },
+            expectedOldParentRemId: {
+                type: 'string',
+                description: 'Reject if the current direct parent differs from this Rem ID',
+            },
+            ancestorDepth: {
+                type: 'number',
+                description: 'Number of parent Rems to include before/after the move',
+            },
+        },
+        required: ['remId', 'newParentRemId'],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string' },
+            title: { type: 'string' },
+            dryRun: { type: 'boolean' },
+            oldParentRemId: { type: 'string' },
+            oldParentTitle: { type: 'string' },
+            newParentRemId: { type: 'string' },
+            newParentTitle: { type: 'string' },
+            position: { type: 'string', enum: ['first', 'last', 'before', 'after'] },
+            siblingRemId: { type: 'string' },
+            ancestorsBefore: { type: 'array', items: ANCESTOR_SCHEMA },
+            ancestorsBeforeTruncated: { type: 'boolean' },
+            ancestorsAfter: { type: 'array', items: ANCESTOR_SCHEMA },
+            ancestorsAfterTruncated: { type: 'boolean' },
+        },
+        required: ['remId', 'title', 'dryRun', 'newParentRemId', 'newParentTitle', 'position'],
+    },
+};
 export const UPDATE_NOTE_TOOL = {
     name: 'remnote_update_note',
-    description: 'Update note metadata in RemNote. Use this tool for title changes only.',
+    description: 'Update note metadata in RemNote. Use this tool for title changes only. The title supports exact Rem references as [[id:<remId>]].',
     inputSchema: {
         type: 'object',
         properties: {
             remId: { type: 'string', description: 'The Rem ID to update' },
-            title: { type: 'string', description: 'New title' },
+            title: {
+                type: 'string',
+                description: 'New title. Use [[id:<remId>]] for exact Rem references.',
+            },
         },
         required: ['remId', 'title'],
         additionalProperties: false,
@@ -389,6 +776,100 @@ export const UPDATE_NOTE_TOOL = {
         required: ['remIds', 'titles'],
     },
 };
+export const SET_DOCUMENT_STATUS_TOOL = {
+    name: 'remnote_set_document_status',
+    description: 'Preview or set whether an existing Rem is marked as a document. Uses dryRun=true by default, preserves Rem ID, children, parent, tags, and concept/card status, and requires write operations to be enabled.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string', description: 'The Rem ID whose document status should change' },
+            isDocument: {
+                type: 'boolean',
+                description: 'Whether the Rem should be marked as a document',
+            },
+            dryRun: {
+                type: 'boolean',
+                description: 'Preview the document-status change without mutating RemNote (default: true)',
+            },
+            expectedOldRemType: {
+                type: 'string',
+                enum: ['document', 'dailyDocument', 'concept', 'descriptor', 'portal', 'text'],
+                description: 'Optional stale-context guard; reject if current remType differs from this value',
+            },
+        },
+        required: ['remId', 'isDocument'],
+        additionalProperties: false,
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string', description: 'The Rem ID that was checked or changed' },
+            title: { type: 'string', description: 'Rendered title/front text' },
+            oldRemType: {
+                type: 'string',
+                description: 'Bridge remType before the requested document-status change',
+            },
+            newRemType: {
+                type: 'string',
+                description: 'Bridge remType after the change, or previewed remType for dry runs',
+            },
+            oldIsDocument: {
+                type: 'boolean',
+                description: 'Document status before the requested change',
+            },
+            newIsDocument: {
+                type: 'boolean',
+                description: 'Document status after the change, or previewed status for dry runs',
+            },
+            requestedIsDocument: {
+                type: 'boolean',
+                description: 'Requested document status',
+            },
+            dryRun: {
+                type: 'boolean',
+                description: 'Whether the request was only a preview',
+            },
+            changed: {
+                type: 'boolean',
+                description: 'Whether RemNote was actually mutated by this call',
+            },
+            wouldChange: {
+                type: 'boolean',
+                description: 'Whether the requested status differs from the current status',
+            },
+            sdkSupportsDocumentStatus: {
+                type: 'boolean',
+                description: 'Whether the bridge runtime exposes a safe SDK document-status setter',
+            },
+            warnings: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Important side-effect notes, especially around preserved card status',
+            },
+            cardDirectionBefore: {
+                type: 'string',
+                description: 'Card direction before the change when available',
+            },
+            cardDirectionAfter: {
+                type: 'string',
+                description: 'Card direction after the change when available',
+            },
+        },
+        required: [
+            'remId',
+            'title',
+            'oldRemType',
+            'newRemType',
+            'oldIsDocument',
+            'newIsDocument',
+            'requestedIsDocument',
+            'dryRun',
+            'changed',
+            'wouldChange',
+            'sdkSupportsDocumentStatus',
+        ],
+    },
+};
 export const INSERT_CHILDREN_TOOL = {
     name: 'remnote_insert_children',
     description: 'Insert new child Rems under a parent at a deterministic position without replacing existing children. Use this for tag description nodes and hierarchy maintenance.',
@@ -399,7 +880,10 @@ export const INSERT_CHILDREN_TOOL = {
                 type: 'string',
                 description: 'Parent Rem ID that will receive the new children',
             },
-            content: { type: 'string', description: 'Markdown content to insert as child Rems' },
+            content: {
+                type: 'string',
+                description: 'Markdown content to insert as child Rems. Use [[id:<remId>]] for exact Rem references.',
+            },
             position: {
                 type: 'string',
                 enum: ['first', 'last', 'before', 'after'],
@@ -427,7 +911,7 @@ export const REPLACE_CHILDREN_TOOL = {
             },
             content: {
                 type: 'string',
-                description: 'Markdown content to use as replacement children; empty string clears all direct children',
+                description: 'Markdown content to use as replacement children; empty string clears all direct children. Use [[id:<remId>]] for exact Rem references.',
             },
         },
         required: ['parentRemId', 'content'],
@@ -460,6 +944,77 @@ export const UPDATE_TAGS_TOOL = {
     },
     outputSchema: UPDATE_NOTE_TOOL.outputSchema,
 };
+export const SET_PROPERTY_TOOL = {
+    name: 'remnote_set_property',
+    description: 'Set or clear a tag/table property value on a Rem by exact IDs. The bridge verifies the property belongs to the supplied tag/table Rem, adds the tag idempotently, then writes the property value. For select properties, pass the option Rem ID as value.kind="rem_reference".',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string', description: 'The Rem ID whose tag property should be set' },
+            tagRemId: {
+                type: 'string',
+                description: 'Exact tag/table Rem ID that owns the property',
+            },
+            propertyRemId: {
+                type: 'string',
+                description: 'Exact property Rem ID under the tag/table Rem',
+            },
+            value: {
+                oneOf: [
+                    {
+                        type: 'object',
+                        properties: {
+                            kind: { type: 'string', const: 'text' },
+                            text: {
+                                type: 'string',
+                                description: 'Plain text or markdown property value. Use [[id:<remId>]] for exact Rem references.',
+                            },
+                        },
+                        required: ['kind', 'text'],
+                        additionalProperties: false,
+                    },
+                    {
+                        type: 'object',
+                        properties: {
+                            kind: { type: 'string', const: 'rem_reference' },
+                            remId: {
+                                type: 'string',
+                                description: 'Referenced Rem ID; use select-option Rem IDs here too',
+                            },
+                        },
+                        required: ['kind', 'remId'],
+                        additionalProperties: false,
+                    },
+                    {
+                        type: 'object',
+                        properties: {
+                            kind: { type: 'string', const: 'clear' },
+                        },
+                        required: ['kind'],
+                        additionalProperties: false,
+                    },
+                ],
+                description: 'Property value. Use text for plain values, rem_reference for Rem references and select options, or clear to remove the value.',
+            },
+        },
+        required: ['remId', 'tagRemId', 'propertyRemId', 'value'],
+        additionalProperties: false,
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            remId: { type: 'string', description: 'The Rem ID whose property was set' },
+            tagRemId: { type: 'string', description: 'Exact tag/table Rem ID' },
+            propertyRemId: { type: 'string', description: 'Exact property Rem ID' },
+            valueKind: {
+                type: 'string',
+                enum: ['text', 'rem_reference', 'clear'],
+                description: 'The value payload kind applied by the bridge',
+            },
+        },
+        required: ['remId', 'tagRemId', 'propertyRemId', 'valueKind'],
+    },
+};
 export const APPEND_JOURNAL_TOOL = {
     name: 'remnote_append_journal',
     description: "Append content to today's daily document in RemNote with optional exact tag Rem IDs. Recommended preflight once per session: remnote_status.",
@@ -468,7 +1023,7 @@ export const APPEND_JOURNAL_TOOL = {
         properties: {
             content: {
                 type: 'string',
-                description: "Content to append to today's daily document (markdown supported)",
+                description: "Content to append to today's daily document (markdown supported). Use [[id:<remId>]] for exact Rem references.",
             },
             timestamp: { type: 'boolean', description: 'Include timestamp (default: true)' },
             tagRemIds: {
@@ -510,6 +1065,11 @@ export const STATUS_TOOL = {
             connected: { type: 'boolean', description: 'Whether bridge plugin is currently connected' },
             serverVersion: { type: 'string', description: 'MCP server version' },
             pluginVersion: { type: 'string', description: 'Connected bridge plugin version' },
+            capabilities: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Bridge protocol capabilities advertised during handshake',
+            },
             version_warning: {
                 type: 'string',
                 description: 'Compatibility warning when server/bridge versions differ',
@@ -634,7 +1194,8 @@ export const PLAYBOOK_TOOL = {
                     orientation: {
                         type: 'object',
                         properties: {
-                            includeContent: { type: 'string' },
+                            contentMode: { type: 'string' },
+                            view: { type: 'string' },
                             depth: { type: 'number' },
                             childLimit: { type: 'number' },
                         },
@@ -670,21 +1231,27 @@ export const ALL_TOOLS = [
     SEARCH_TOOL,
     SEARCH_BY_TAG_TOOL,
     READ_NOTE_TOOL,
+    GET_MEDIA_TOOL,
+    LIST_CHILDREN_TOOL,
     UPDATE_NOTE_TOOL,
+    SET_DOCUMENT_STATUS_TOOL,
+    MOVE_NOTE_TOOL,
     INSERT_CHILDREN_TOOL,
     REPLACE_CHILDREN_TOOL,
     UPDATE_TAGS_TOOL,
+    SET_PROPERTY_TOOL,
     APPEND_JOURNAL_TOOL,
     PLAYBOOK_TOOL,
     STATUS_TOOL,
     READ_TABLE_TOOL,
 ];
-export function registerAllTools(server, wsServer, logger) {
+export function registerAllTools(server, wsServer, logger, mediaRoots = []) {
     const toolLogger = logger.child({ context: 'tools' });
     async function buildStatusResult() {
         const connected = wsServer.isConnected();
         const serverVersion = wsServer.getServerVersion();
         const bridgeVersion = wsServer.getBridgeVersion();
+        const bridgeCapabilities = wsServer.getBridgeCapabilities?.() ?? [];
         if (!connected) {
             return { connected: false, serverVersion, message: 'RemNote plugin not connected' };
         }
@@ -701,6 +1268,7 @@ export function registerAllTools(server, wsServer, logger) {
             connected: true,
             serverVersion,
             ...statusObj,
+            capabilities: bridgeCapabilities,
             ...(versionWarning ? { version_warning: versionWarning } : {}),
         };
     }
@@ -711,6 +1279,7 @@ export function registerAllTools(server, wsServer, logger) {
         toolLogger.debug({ tool: toolName, args: request.params.arguments }, 'Executing tool');
         try {
             let result;
+            let nativeToolResult;
             switch (toolName) {
                 case 'remnote_create_note': {
                     const args = CreateNoteSchema.parse(request.params.arguments);
@@ -724,7 +1293,8 @@ export function registerAllTools(server, wsServer, logger) {
                 }
                 case 'remnote_search_by_tag': {
                     const args = SearchByTagSchema.parse(request.params.arguments);
-                    result = await wsServer.sendRequest('search_by_tag', args);
+                    const { timeoutMs, ...payload } = args;
+                    result = await wsServer.sendRequest('search_by_tag', payload, timeoutMs);
                     break;
                 }
                 case 'remnote_read_note': {
@@ -732,16 +1302,62 @@ export function registerAllTools(server, wsServer, logger) {
                     result = await wsServer.sendRequest('read_note', args);
                     break;
                 }
+                case 'remnote_get_media': {
+                    const args = GetMediaSchema.parse(request.params.arguments);
+                    if (!wsServer.hasBridgeCapability(MEDIA_CAPABILITY)) {
+                        throw new Error(`Bridge capability/version mismatch: connected bridge does not advertise ${MEDIA_CAPABILITY}`);
+                    }
+                    const locator = parseMediaLocator(await wsServer.sendRequest('get_media_locator', {
+                        remId: args.remId,
+                        field: args.field,
+                        mediaId: args.mediaId,
+                    }));
+                    if (locator.remId !== args.remId ||
+                        locator.field !== args.field ||
+                        locator.mediaId !== args.mediaId) {
+                        throw new Error('Invalid media locator payload received from bridge: request identity mismatch');
+                    }
+                    const media = await resolveManagedImage(locator, mediaRoots, args.maxInlineBytes);
+                    const metadata = {
+                        ...media.metadata,
+                        mimeType: media.mimeType,
+                        sizeBytes: media.sizeBytes,
+                    };
+                    nativeToolResult = {
+                        structuredContent: metadata,
+                        content: [
+                            { type: 'image', data: media.data, mimeType: media.mimeType },
+                            { type: 'text', text: JSON.stringify(metadata) },
+                        ],
+                    };
+                    result = metadata;
+                    break;
+                }
+                case 'remnote_list_children': {
+                    const args = ListChildrenSchema.parse(request.params.arguments);
+                    result = await wsServer.sendRequest('list_children', args);
+                    break;
+                }
                 case 'remnote_update_note': {
                     const args = UpdateNoteSchema.parse(request.params.arguments);
                     result = await wsServer.sendRequest('update_note', args);
                     break;
                 }
+                case 'remnote_set_document_status': {
+                    const args = SetDocumentStatusSchema.parse(request.params.arguments);
+                    result = await wsServer.sendRequest('set_document_status', args);
+                    break;
+                }
                 case 'remnote_insert_children': {
                     const args = InsertChildrenSchema.parse(request.params.arguments);
                     result = await wsServer.sendRequest('insert_children', args);
                     break;
                 }
+                case 'remnote_move_note': {
+                    const args = MoveNoteSchema.parse(request.params.arguments);
+                    result = await wsServer.sendRequest('move_note', args);
+                    break;
+                }
                 case 'remnote_replace_children': {
                     const args = ReplaceChildrenSchema.parse(request.params.arguments);
                     result = await wsServer.sendRequest('replace_children', args);
@@ -752,6 +1368,11 @@ export function registerAllTools(server, wsServer, logger) {
                     result = await wsServer.sendRequest('update_tags', args);
                     break;
                 }
+                case 'remnote_set_property': {
+                    const args = SetPropertySchema.parse(request.params.arguments);
+                    result = await wsServer.sendRequest('set_property', args);
+                    break;
+                }
                 case 'remnote_append_journal': {
                     const args = AppendJournalSchema.parse(request.params.arguments);
                     result = await wsServer.sendRequest('append_journal', args);
@@ -769,45 +1390,65 @@ export function registerAllTools(server, wsServer, logger) {
                         };
                     }
                     result = {
-                        playbookVersion: '1.1.0',
-                        summary: 'Use this playbook to navigate RemNote efficiently via remIds, and to apply write-safety checks before mutations.',
+                        playbookVersion: '1.8.0',
+                        summary: 'Use this playbook to check RemNote connection and write gates, navigate by remId with paged search/read/list workflows, retrieve managed images through capability-gated metadata, choose compact/full output views, and apply safe exact-ID writes including inline [[id:<remId>]] references, tag property values, and dry-run-first document status changes.',
                         recommendedStatusCheck: {
                             tool: 'remnote_status',
                             cadence: 'recommended once per session and before risky writes',
-                            rationale: 'status exposes connection health, version compatibility warnings, and write-policy gates',
+                            rationale: 'status exposes connection health, version compatibility warnings, write-policy gates, and bridge capabilities',
                         },
                         decisionTree: [
                             'Need connection/capability context? Call remnote_status first.',
-                            'Need to orient across the KB? Use remnote_search with includeContent="structured", depth=1, childLimit=500.',
-                            'Need tagged-note context? Use remnote_search_by_tag with tagRemId; it does not resolve tag names or aliases.',
-                            'Need to traverse a specific branch? Use remnote_read_note on a chosen remId with includeContent="structured", depth=1, childLimit=500, then recurse by child remIds.',
+                            'Need an embedded RemNote-managed image? Confirm media.images.v1, call remnote_read_note with includeMediaMetadata=true, then call remnote_get_media with the returned remId, field, and mediaId.',
+                            'Need to orient across the KB? Use remnote_search with contentMode="structured", view="compact", depth=1, childLimit=500.',
+                            'Need broad search enumeration? Continue remnote_search or remnote_search_by_tag with nextCursor while hasMore is true.',
+                            'Need to search within a specific branch? Use remnote_search with parentRemId; keep the same parentRemId when continuing with nextCursor.',
+                            'Need tagged-note context/navigation? Use remnote_search_by_tag with tagRemId and default resultMode="context"; inspect matchedRems to see the direct tagged Rems behind each context result.',
+                            'Need hierarchy placement context? Add ancestorDepth, typically 5, to search/read/search_by_tag/list_children; ancestors are direct-parent first.',
+                            'Need strict tag verification? Use remnote_search_by_tag with resultMode="tagged", or verify the exact Rem in matchedRems from context mode.',
+                            'Need a large tag search to finish? Prefer cursor paging first; use remnote_search_by_tag.timeoutMs only as a bounded wait-time escape hatch.',
+                            'Need to traverse a specific branch cheaply? Use remnote_list_children on the parentRemId and page through direct children.',
+                            'Need to read a selected subtree? Use remnote_read_note on a chosen remId with contentMode="structured", depth=1, childLimit=500, then deepen selected branches.',
+                            'Need to follow inline graph references? Inspect inlineRefs on search/read results and structured child nodes for exact target Rem IDs.',
                             'Need tabular/structured data from an Advanced Table? Use remnote_read_table with either tableTitle or tableRemId. Use propertyFilter to limit columns for large tables.',
-                            'Need a human-readable summary? Switch to includeContent="markdown" on search/read results.',
-                            'Need to rename a note? Use remnote_update_note with remId and title only.',
-                            'Need to create a note? Use remnote_create_note; pass tagRemIds for exact-ID tag assignment.',
-                            'Need to append to today journal? Use remnote_append_journal; pass tagRemIds when the journal entry should be tagged.',
-                            'Need to insert children? Use remnote_insert_children with an explicit position.',
-                            'Need to replace children? Check remnote_status first; remnote_replace_children requires acceptReplaceOperation=true.',
+                            'Need a human-readable summary? Switch to contentMode="markdown" on search/read results.',
+                            'Need to rename a note? Use remnote_update_note with remId and title only; use [[id:<remId>]] inside the title for exact inline Rem references.',
+                            'Need to create a note? Use remnote_create_note; pass tagRemIds for exact-ID tag assignment, [[id:<remId>]] for exact inline Rem references, and asDocument=true when the title/root Rem should be a document.',
+                            'Need to mark an existing Rem as a document? Use remnote_set_document_status dryRun first, include expectedOldRemType for stale-context protection, then rerun with dryRun=false after approval.',
+                            'Need to append to today journal? Use remnote_append_journal; pass tagRemIds when the journal entry should be tagged and [[id:<remId>]] for exact inline Rem references.',
+                            'Need to insert children? Use remnote_insert_children with an explicit position; use [[id:<remId>]] for exact inline Rem references.',
+                            'Need to move a note? Use remnote_move_note dryRun first, include expectedOldParentRemId for stale-context protection, then rerun with dryRun=false after approval.',
+                            'Need to replace children? Check remnote_status first; remnote_replace_children requires acceptReplaceOperation=true and supports [[id:<remId>]] for exact inline Rem references.',
                             'Need to update tags on an existing note? Use remnote_update_tags with exact tag Rem IDs.',
+                            'Need to set a tag/table property value? Use remnote_set_property with exact remId, tagRemId, propertyRemId, and a text/rem_reference/clear value payload. For select properties, pass the option Rem ID as rem_reference.remId; for inline references in text values, use [[id:<remId>]].',
                         ],
                         navigationPresets: {
                             orientation: NAVIGATION_PRESET,
                             branchTraversal: NAVIGATION_PRESET,
                         },
                         contentModes: {
-                            structured: 'ID-first traversal mode. Returns contentStructured with child remIds for deterministic follow-up reads.',
-                            markdown: 'Summary mode. Returns rendered markdown content for human-facing synthesis, not deterministic child ID traversal.',
+                            structured: 'ID-first traversal mode. Returns contentStructured with child remIds and inlineRefs for deterministic follow-up reads.',
+                            markdown: 'Summary mode. Returns rendered markdown content for human-facing synthesis; inline Rem references render as [[Target Title]].',
                             none: 'Metadata-only mode when content is not needed.',
                         },
+                        outputViews: {
+                            compact: 'Small metadata surface for broad discovery. Omits tags, aliases, inlineRefs, and diagnostic fields unless another option requires them.',
+                            standard: 'Normal discovery metadata for most agent workflows.',
+                            full: 'Verbose metadata for diagnostics or detailed audits.',
+                        },
                         writePolicy: {
                             statusTool: 'remnote_status',
                             requiredFields: ['acceptWriteOperations', 'acceptReplaceOperation'],
                             guidance: [
                                 'Create/update/insert/replace/tag/journal writes require acceptWriteOperations=true.',
                                 'remnote_update_note is metadata-only; use insert_children, replace_children, and update_tags for structural or tag writes.',
+                                'remnote_set_document_status changes only document status; it preserves concept/card status and defaults to dryRun=true.',
                                 'remnote_replace_children requires acceptReplaceOperation=true.',
                                 'remnote_insert_children preserves existing child Rem IDs; remnote_replace_children removes them.',
+                                'remnote_move_note preserves the moved Rem ID and subtree; dryRun defaults to true.',
                                 'All production tag writes use exact tag Rem IDs: create_note.tagRemIds, append_journal.tagRemIds, and update_tags add/remove arrays.',
+                                'Markdown-capable write fields support [[id:<remId>]] to create real inline references to existing Rems without name lookup.',
+                                'remnote_set_property writes exact-ID tag/table property values and requires acceptWriteOperations=true.',
                             ],
                         },
                         currentStatus,
@@ -830,6 +1471,9 @@ export function registerAllTools(server, wsServer, logger) {
                 tool: toolName,
                 duration_ms: Date.now() - startTime,
             }, 'Tool completed');
+            if (nativeToolResult) {
+                return nativeToolResult;
+            }
             return {
                 structuredContent: result,
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],