roam-research-mcp 2.4.0 → 2.13.0

package/build/cli/commands/refs.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { SearchOperations } from '../../tools/operations/search/index.js';
 import { printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 /**
  * Format results grouped by page (default output)
  */
@@ -72,7 +73,7 @@ function parseIdentifier(identifier) {
 export function createRefsCommand() {
     return new Command('refs')
         .description('Find all blocks that reference a page, tag, or block')
-        .argument('<identifier>', 'Page title, #tag, [[Page]], or ((block-uid))')
+        .argument('[identifier]', 'Page title, #tag, [[Page]], or ((block-uid)). Reads from stdin if "-" or omitted.')
         .option('-n, --limit <n>', 'Limit number of results', '50')
         .option('--json', 'Output as JSON array')
         .option('--raw', 'Output raw UID + content lines (no grouping)')
@@ -82,49 +83,68 @@ export function createRefsCommand() {
 Examples:
   # Page references
   roam refs "Project Alpha"               # Blocks linking to page
-  roam refs "[[Meeting Notes]]"           # With bracket syntax
   roam refs "#TODO"                       # Blocks with #TODO tag
 
+  # Stdin / Batch references
+  echo "Project A" | roam refs            # Pipe page title
+  cat uids.txt | roam refs --json         # Find refs for multiple UIDs
+
   # Block references
   roam refs "((abc123def))"               # Blocks embedding this block
 
-  # Output options
-  roam refs "Work" --json                 # JSON array output
-  roam refs "Ideas" --raw                 # Raw UID + content (no grouping)
-  roam refs "Tasks" -n 100                # Limit to 100 results
+JSON output fields: uid, content, page
 `)
         .action(async (identifier, options) => {
         try {
             const graph = resolveGraph(options, false);
             const limit = parseInt(options.limit || '50', 10);
-            const { block_uid, title } = parseIdentifier(identifier);
-            if (options.debug) {
-                printDebug('Identifier', identifier);
-                printDebug('Graph', options.graph || 'default');
-                printDebug('Parsed', { block_uid, title });
-                printDebug('Options', options);
-            }
-            const searchOps = new SearchOperations(graph);
-            const result = await searchOps.searchBlockRefs({ block_uid, title });
-            if (options.debug) {
-                printDebug('Total matches', result.matches.length);
+            // Determine identifiers
+            let identifiers = [];
+            if (identifier && identifier !== '-') {
+                identifiers = [identifier];
             }
-            // Apply limit
-            const limitedMatches = result.matches.slice(0, limit);
-            // Format output
-            if (options.json) {
-                const jsonOutput = limitedMatches.map(m => ({
-                    uid: m.block_uid,
-                    content: m.content,
-                    page: m.page_title
-                }));
-                console.log(JSON.stringify(jsonOutput, null, 2));
+            else {
+                if (process.stdin.isTTY && identifier !== '-') {
+                    exitWithError('Identifier is required. Use: roam refs <title> or pipe identifiers via stdin');
+                }
+                const input = await readStdin();
+                if (input) {
+                    identifiers = input.split('\n').map(t => t.trim()).filter(Boolean);
+                }
             }
-            else if (options.raw) {
-                console.log(formatRaw(limitedMatches));
+            if (identifiers.length === 0) {
+                exitWithError('No identifiers provided');
             }
-            else {
-                console.log(formatGrouped(limitedMatches));
+            const searchOps = new SearchOperations(graph);
+            // Helper to process a single identifier
+            const processIdentifier = async (id) => {
+                const { block_uid, title } = parseIdentifier(id);
+                if (options.debug) {
+                    printDebug('Identifier', id);
+                    printDebug('Parsed', { block_uid, title });
+                }
+                const result = await searchOps.searchBlockRefs({ block_uid, title });
+                const limitedMatches = result.matches.slice(0, limit);
+                if (options.json) {
+                    return JSON.stringify(limitedMatches.map(m => ({
+                        uid: m.block_uid,
+                        content: m.content,
+                        page: m.page_title
+                    })));
+                }
+                else if (options.raw) {
+                    return formatRaw(limitedMatches);
+                }
+                else {
+                    return formatGrouped(limitedMatches);
+                }
+            };
+            // Execute
+            for (const id of identifiers) {
+                const output = await processIdentifier(id);
+                console.log(output);
+                if (identifiers.length > 1 && !options.json)
+                    console.log('\n---\n');
             }
         }
         catch (error) {

package/build/cli/commands/save.js

@@ -7,6 +7,7 @@ import { BatchOperations } from '../../tools/operations/batch.js';
 import { parseMarkdown, generateBlockUid, parseMarkdownHeadingLevel } from '../../markdown-utils.js';
 import { printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { q, createPage as roamCreatePage } from '@roam-research/roam-api-sdk';
 /**
@@ -27,14 +28,53 @@ function flattenNodes(nodes, baseLevel = 1) {
     return result;
 }
 /**
- * Read all input from stdin
+ * Infer hierarchy from heading levels when all blocks are at the same level.
+ * This handles prose-style markdown where headings (# ## ###) define structure
+ * without explicit indentation.
+ *
+ * Example: "# Title\n## Chapter\nContent" becomes:
+ *   - Title (level 1, H1)
+ *     - Chapter (level 2, H2)
+ *       - Content (level 3)
  */
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(chunk);
+function adjustLevelsForHeadingHierarchy(blocks) {
+    if (blocks.length === 0)
+        return blocks;
+    // Only apply heading-based adjustment when:
+    // 1. All blocks are at the same level (no indentation-based hierarchy)
+    // 2. There are headings present
+    const allSameLevel = blocks.every(b => b.level === blocks[0].level);
+    const hasHeadings = blocks.some(b => b.heading);
+    if (!allSameLevel || !hasHeadings) {
+        // Indentation-based hierarchy exists, preserve it
+        return blocks;
     }
-    return Buffer.concat(chunks).toString('utf-8');
+    const result = [];
+    // Track heading stack: each entry is { headingLevel: 1|2|3, adjustedLevel: number }
+    const headingStack = [];
+    for (const block of blocks) {
+        if (block.heading) {
+            // Pop headings of same or lower priority (higher h-number)
+            while (headingStack.length > 0 &&
+                headingStack[headingStack.length - 1].headingLevel >= block.heading) {
+                headingStack.pop();
+            }
+            // New heading level is one deeper than parent heading (or 1 if no parent)
+            const adjustedLevel = headingStack.length > 0
+                ? headingStack[headingStack.length - 1].adjustedLevel + 1
+                : 1;
+            headingStack.push({ headingLevel: block.heading, adjustedLevel });
+            result.push({ ...block, level: adjustedLevel });
+        }
+        else {
+            // Content: nest under current heading context
+            const adjustedLevel = headingStack.length > 0
+                ? headingStack[headingStack.length - 1].adjustedLevel + 1
+                : 1;
+            result.push({ ...block, level: adjustedLevel });
+        }
+    }
+    return result;
 }
 /**
  * Check if a string looks like a Roam block UID (9 alphanumeric chars with _ or -)
@@ -65,6 +105,8 @@ async function findOrCreatePage(graph, title) {
         action: 'create-page',
         page: { title }
     });
+    // Small delay for new page to be fully available as parent in Roam
+    await new Promise(resolve => setTimeout(resolve, 400));
     const results = await q(graph, findQuery, [title]);
     if (!results || results.length === 0) {
         throw new Error(`Could not find created page: ${title}`);
@@ -146,6 +188,7 @@ export function createSaveCommand() {
         .option('-c, --categories <tags>', 'Comma-separated tags appended to first block')
         .option('-t, --todo [text]', 'Add TODO item(s) to daily page. Accepts inline text or stdin')
         .option('--json', 'Force JSON array format: [{text, level, heading?}, ...]')
+        .option('--flatten', 'Disable heading hierarchy inference (all blocks at root level)')
         .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
         .option('--write-key <key>', 'Write confirmation key (non-default graphs)')
         .option('--debug', 'Show debug information')
@@ -169,6 +212,11 @@ Examples:
   roam save notes.md --title "My Notes" --update  # Smart update (preserves UIDs)
   cat data.json | roam save --json                # Pipe JSON blocks
 
+  # Stdin operations
+  echo "Task from CLI" | roam save --todo         # Pipe to TODO
+  cat note.md | roam save --title "From Pipe"     # Pipe file content to new page
+  echo "Quick capture" | roam save -p "Inbox"     # Pipe to specific page
+
   # Combine options
   roam save -p "Work" --parent "## Today" "Done with task" -c "wins"
 
@@ -219,7 +267,7 @@ JSON format (--json):
             let content;
             let isFile = false;
             let sourceFilename;
-            if (input) {
+            if (input && input !== '-') {
                 // Check if input is a file path that exists
                 if (existsSync(input)) {
                     isFile = true;
@@ -237,8 +285,8 @@ JSON format (--json):
                 }
             }
             else {
-                // Read from stdin
-                if (process.stdin.isTTY) {
+                // Read from stdin (or if input is explicit '-')
+                if (process.stdin.isTTY && input !== '-') {
                     exitWithError('No input. Use: roam save "text", roam save <file>, or pipe content');
                 }
                 content = await readStdin();
@@ -262,7 +310,9 @@ JSON format (--json):
             else if (isFile || content.includes('\n')) {
                 // Multi-line content: parse as markdown
                 const nodes = parseMarkdown(content);
-                contentBlocks = flattenNodes(nodes);
+                const flattened = flattenNodes(nodes);
+                // Apply heading hierarchy unless --flatten is specified
+                contentBlocks = options.flatten ? flattened : adjustLevelsForHeadingHierarchy(flattened);
             }
             else {
                 // Single line text: detect heading syntax and strip hashes
@@ -302,6 +352,7 @@ JSON format (--json):
                 printDebug('Input', input || 'stdin');
                 printDebug('Is file', isFile);
                 printDebug('Is JSON', isJson);
+                printDebug('Flatten mode', options.flatten || false);
                 printDebug('Graph', options.graph || 'default');
                 printDebug('Content blocks', contentBlocks.length);
                 printDebug('Parent UID', parentUid || 'none');

package/build/cli/commands/search.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { SearchOperations } from '../../tools/operations/search/index.js';
 import { formatSearchResults, printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 /**
  * Normalize a tag by stripping #, [[, ]] wrappers
  */
@@ -20,7 +21,7 @@ function contentHasTag(content, tag) {
 export function createSearchCommand() {
     return new Command('search')
         .description('Search blocks by text, tags, Datalog queries, or within specific pages')
-        .argument('[terms...]', 'Search terms (multiple terms use AND logic)')
+        .argument('[terms...]', 'Search terms (multiple terms use AND logic). Reads from stdin if omitted.')
         .option('--tag <tag>', 'Filter by tag (repeatable, comma-separated). Default: AND logic', (val, prev) => {
         // Support both comma-separated and multiple flags
         const tags = val.split(',').map(t => t.trim()).filter(Boolean);
@@ -41,43 +42,36 @@ export function createSearchCommand() {
         .option('--inputs <json>', 'JSON array of inputs for Datalog query')
         .option('--regex <pattern>', 'Client-side regex filter on Datalog results')
         .option('--regex-flags <flags>', 'Regex flags (e.g., "i" for case-insensitive)')
+        .option('--namespace <prefix>', 'Search for pages by namespace prefix (e.g., "Convention" finds "Convention/*")')
         .addHelpText('after', `
 Examples:
   # Text search
   roam search "meeting notes"               # Find blocks containing text
   roam search api integration               # Multiple terms (AND logic)
-  roam search "bug fix" -i                  # Case-insensitive search
+
+  # Namespace search (find pages by title prefix)
+  roam search --namespace Convention        # Find all Convention/* pages
+  roam search --namespace "Convention/"     # Same (trailing slash optional)
+
+  # Stdin search
+  echo "urgent project" | roam search       # Pipe terms
+  roam get today | roam search TODO         # Search within output
 
   # Tag search
   roam search --tag TODO                    # All blocks with #TODO
   roam search --tag "[[Project Alpha]]"     # Blocks with page reference
-  roam search --tag work --page "January 3rd, 2026"  # Tag on specific page
-
-  # Multiple tags
-  roam search --tag TODO --tag urgent       # Blocks with BOTH tags (AND)
-  roam search --tag "TODO,urgent,blocked"   # Comma-separated (AND)
-  roam search --tag TODO --tag urgent --any # Blocks with ANY tag (OR)
-
-  # Exclude tags
-  roam search --tag TODO --negtag done      # TODOs excluding #done
-  roam search --tag TODO --negtag "someday,maybe"  # Exclude multiple
 
-  # Combined filters
-  roam search urgent --tag TODO             # Text + tag filter
-  roam search "review" --page "Work"        # Search within page
+  # Datalog queries (advanced)
+  roam search -q '[:find ?uid ?s :where [?b :block/uid ?uid] [?b :block/string ?s]]' --regex "meeting"
 
-  # Output options
-  roam search "design" -n 50                # Limit to 50 results
-  roam search "api" --json                  # JSON output
+  # Chaining with jq
+  roam search TODO --json | jq '.[].block_uid'
 
-  # Datalog queries (advanced)
-  roam search -q '[:find ?title :where [?e :node/title ?title]]'
-  roam search -q '[:find ?s :in $ ?term :where [?b :block/string ?s] [(clojure.string/includes? ?s ?term)]]' --inputs '["TODO"]'
-  roam search -q '[:find ?uid ?s :where [?b :block/uid ?uid] [?b :block/string ?s]]' --regex "meeting" --regex-flags "i"
+Output format:
+  Markdown: Flat results with UIDs and content (no hierarchy).
+  JSON:     [{ block_uid, content, page_title }] or [{ page_uid, page_title }] for namespace
 
-Datalog tips:
-  Common attributes: :node/title, :block/string, :block/uid, :block/page, :block/children
-  Predicates: clojure.string/includes?, clojure.string/starts-with?, <, >, =
+Note: For hierarchical output with children, use 'roam get --tag/--text' instead.
 `)
         .action(async (terms, options) => {
         try {
@@ -87,14 +81,52 @@ Datalog tips:
                 json: options.json,
                 debug: options.debug
             };
+            let searchTerms = terms;
+            // If no terms provided as args, try stdin
+            if (searchTerms.length === 0 && !process.stdin.isTTY && !options.query && (options.tag?.length === 0)) {
+                const input = await readStdin();
+                if (input) {
+                    searchTerms = input.trim().split(/\s+/);
+                }
+            }
             if (options.debug) {
-                printDebug('Search terms', terms);
+                printDebug('Search terms', searchTerms);
                 printDebug('Graph', options.graph || 'default');
                 printDebug('Options', options);
             }
             const searchOps = new SearchOperations(graph);
+            // Namespace search mode (search page titles by prefix)
+            if (options.namespace) {
+                const result = await searchOps.searchByText({
+                    text: options.namespace,
+                    scope: 'page_titles'
+                });
+                if (!result.success) {
+                    exitWithError(result.message || 'Namespace search failed');
+                }
+                let matches = result.matches.slice(0, limit);
+                if (options.json) {
+                    // For JSON output, return page_uid and page_title
+                    const jsonMatches = matches.map(m => ({
+                        page_uid: m.block_uid,
+                        page_title: m.page_title
+                    }));
+                    console.log(JSON.stringify(jsonMatches, null, 2));
+                }
+                else {
+                    if (matches.length === 0) {
+                        console.log('No pages found.');
+                    }
+                    else {
+                        console.log(`Found ${result.matches.length} page(s)${result.matches.length > limit ? ` (showing first ${limit})` : ''}:\n`);
+                        for (const match of matches) {
+                            console.log(`- ${match.page_title} (${match.block_uid})`);
+                        }
+                    }
+                }
+                return;
+            }
             // Datalog query mode (bypasses other search options)
-            // See for query construction - Roam_Research_Datalog_Cheatsheet.md
             if (options.query) {
                 // Parse inputs if provided
                 let inputs;
@@ -109,11 +141,6 @@ Datalog tips:
                         exitWithError('Invalid JSON in --inputs');
                     }
                 }
-                if (options.debug) {
-                    printDebug('Datalog query', options.query);
-                    printDebug('Inputs', inputs || 'none');
-                    printDebug('Regex filter', options.regex || 'none');
-                }
                 const result = await searchOps.executeDatomicQuery({
                     query: options.query,
                     inputs,
@@ -126,7 +153,6 @@ Datalog tips:
                 // Apply limit and format output
                 const limitedMatches = result.matches.slice(0, limit);
                 if (options.json) {
-                    // For JSON output, parse the content back to objects
                     const parsed = limitedMatches.map(m => {
                         try {
                             return JSON.parse(m.content);
@@ -138,7 +164,6 @@ Datalog tips:
                     console.log(JSON.stringify(parsed, null, 2));
                 }
                 else {
-                    // For text output, show raw results
                     if (limitedMatches.length === 0) {
                         console.log('No results found.');
                     }
@@ -153,34 +178,22 @@ Datalog tips:
             }
             // Determine search type based on options
             const tags = options.tag || [];
-            if (tags.length > 0 && terms.length === 0) {
+            if (tags.length > 0 && searchTerms.length === 0) {
                 // Tag-only search
                 const normalizedTags = tags.map(normalizeTag);
                 const useOrLogic = options.any || false;
-                if (options.debug) {
-                    printDebug('Tag search', {
-                        tags: normalizedTags,
-                        logic: useOrLogic ? 'OR' : 'AND',
-                        page: options.page
-                    });
-                }
-                // Search for first tag, then filter by additional tags
                 const result = await searchOps.searchForTag(normalizedTags[0], options.page);
                 let matches = result.matches;
-                // Apply multi-tag filter if more than one tag
                 if (normalizedTags.length > 1) {
                     matches = matches.filter(m => {
                         if (useOrLogic) {
-                            // OR: has at least one tag
                             return normalizedTags.some(tag => contentHasTag(m.content, tag));
                         }
                         else {
-                            // AND: has all tags
                             return normalizedTags.every(tag => contentHasTag(m.content, tag));
                         }
                     });
                 }
-                // Apply negtag filter (exclude blocks with any of these tags)
                 const negTags = options.negtag || [];
                 if (negTags.length > 0) {
                     const normalizedNegTags = negTags.map(normalizeTag);
@@ -189,24 +202,18 @@ Datalog tips:
                 const limitedMatches = matches.slice(0, limit);
                 console.log(formatSearchResults(limitedMatches, outputOptions));
             }
-            else if (terms.length > 0) {
-                // Text search (with optional tag filter)
-                const searchText = terms.join(' ');
-                if (options.debug) {
-                    printDebug('Text search', { text: searchText, page: options.page, tag: options.tag });
-                }
+            else if (searchTerms.length > 0) {
+                // Text search
+                const searchText = searchTerms.join(' ');
                 const result = await searchOps.searchByText({
                     text: searchText,
                     page_title_uid: options.page
                 });
-                // Apply client-side filters
                 let matches = result.matches;
-                // Case-insensitive filter if requested
                 if (options.caseInsensitive) {
                     const lowerSearchText = searchText.toLowerCase();
                     matches = matches.filter(m => m.content.toLowerCase().includes(lowerSearchText));
                 }
-                // Tag filter if provided
                 if (tags.length > 0) {
                     const normalizedTags = tags.map(normalizeTag);
                     const useOrLogic = options.any || false;
@@ -219,13 +226,11 @@ Datalog tips:
                         }
                     });
                 }
-                // Negtag filter (exclude blocks with any of these tags)
                 const negTags = options.negtag || [];
                 if (negTags.length > 0) {
                     const normalizedNegTags = negTags.map(normalizeTag);
                     matches = matches.filter(m => !normalizedNegTags.some(tag => contentHasTag(m.content, tag)));
                 }
-                // Apply limit
                 console.log(formatSearchResults(matches.slice(0, limit), outputOptions));
             }
             else {

package/build/cli/commands/status.js

@@ -25,6 +25,8 @@ Examples:
 
   # JSON output for scripting
   roam status --json
+
+JSON output fields: { version, graphs: [{ name, default, protected, connected?, error? }] }
 `)
         .action(async (options) => {
         try {
@@ -34,15 +36,12 @@ Examples:
             for (const key of graphKeys) {
                 const config = registry.getConfig(key);
                 const isDefault = key === registry.defaultKey;
-                const isProtected = !!config.write_key;
+                const isProtected = !!config.protected;
                 const status = {
                     name: key,
                     default: isDefault,
                     protected: isProtected,
                 };
-                if (isProtected) {
-                    status.writeKey = config.write_key;
-                }
                 if (options.ping) {
                     try {
                         const graph = registry.getGraph(key);

package/build/cli/commands/update.js

@@ -1,8 +1,10 @@
 import { Command } from 'commander';
 import { BatchOperations } from '../../tools/operations/batch.js';
+import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
 import { parseMarkdownHeadingLevel } from '../../markdown-utils.js';
 import { printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 // Patterns for TODO/DONE markers (both {{TODO}} and {{[[TODO]]}} formats)
 const TODO_PATTERN = /\{\{(\[\[)?TODO(\]\])?\}\}\s*/g;
 const DONE_PATTERN = /\{\{(\[\[)?DONE(\]\])?\}\}\s*/g;
@@ -43,7 +45,7 @@ export function createUpdateCommand() {
     return new Command('update')
         .description('Update block content, heading, open/closed state, or TODO/DONE status')
         .argument('<uid>', 'Block UID to update (accepts ((uid)) wrapper)')
-        .argument('<content>', 'New content. Use # prefix for heading: "# Title" sets H1')
+        .argument('[content]', 'New content. Use # prefix for heading: "# Title" sets H1. Reads from stdin if "-" or omitted (when piped).')
         .option('-H, --heading <level>', 'Set heading level (1-3), or 0 to remove')
         .option('-o, --open', 'Expand block (show children)')
         .option('-c, --closed', 'Collapse block (hide children)')
@@ -72,30 +74,82 @@ Examples:
   roam update abc123def "Task" -T             # Set as TODO
   roam update abc123def "Task" -D             # Mark as DONE
   roam update abc123def "Task" --clear-status # Remove status marker
+
+  # Stdin / Partial Updates
+  echo "New text" | roam update abc123def     # Pipe content
+  roam update abc123def -T                    # Add TODO (fetches existing text)
+  roam update abc123def -o                    # Expand block (keeps text)
 `)
         .action(async (uid, content, options) => {
         try {
             // Strip (( )) wrapper if present
             const blockUid = uid.replace(/^\(\(|\)\)$/g, '');
-            // Detect heading from content unless explicitly set
-            let finalContent = content;
+            const graph = resolveGraph(options, true); // This is a write operation
+            let finalContent;
+            // 1. Determine new content from args or stdin
+            if (content && content !== '-') {
+                finalContent = content;
+            }
+            else if (content === '-' || (!content && !process.stdin.isTTY)) {
+                finalContent = await readStdin();
+                finalContent = finalContent.trim();
+            }
+            // 2. Identify if we need to fetch existing content
+            const isStatusUpdate = options.todo || options.done || options.clearStatus;
+            const isHeadingUpdate = options.heading !== undefined;
+            const isStateUpdate = options.open || options.closed;
+            if (finalContent === undefined) {
+                if (isStatusUpdate) {
+                    // Must fetch to apply status safely
+                    const blockRetrieval = new BlockRetrievalOperations(graph);
+                    const block = await blockRetrieval.fetchBlockWithChildren(blockUid, 0);
+                    if (!block) {
+                        exitWithError(`Block ${blockUid} not found`);
+                    }
+                    finalContent = block.string;
+                }
+                else if (!isHeadingUpdate && !isStateUpdate) {
+                    exitWithError('No content or update options provided.');
+                }
+            }
+            // 3. Process content if we have it
             let headingLevel;
-            if (options.heading !== undefined) {
-                // Explicit heading option takes precedence
-                const level = parseInt(options.heading, 10);
-                if (level >= 0 && level <= 3) {
-                    headingLevel = level === 0 ? undefined : level;
-                    // Still strip # prefix if present for consistency
-                    const { content: stripped } = parseMarkdownHeadingLevel(content);
-                    finalContent = stripped;
+            if (finalContent !== undefined) {
+                // Handle explicit heading option
+                if (options.heading !== undefined) {
+                    const level = parseInt(options.heading, 10);
+                    if (level >= 0 && level <= 3) {
+                        headingLevel = level === 0 ? undefined : level;
+                        const { content: stripped } = parseMarkdownHeadingLevel(finalContent);
+                        finalContent = stripped;
+                    }
+                }
+                else {
+                    // Auto-detect heading from content
+                    const { heading_level, content: stripped } = parseMarkdownHeadingLevel(finalContent);
+                    if (heading_level > 0) {
+                        headingLevel = heading_level;
+                        finalContent = stripped;
+                    }
+                }
+                // Handle TODO/DONE status
+                if (options.clearStatus) {
+                    finalContent = clearStatus(finalContent);
+                }
+                else if (options.todo) {
+                    finalContent = applyStatus(finalContent, 'TODO');
+                }
+                else if (options.done) {
+                    finalContent = applyStatus(finalContent, 'DONE');
                 }
             }
             else {
-                // Auto-detect heading from content
-                const { heading_level, content: stripped } = parseMarkdownHeadingLevel(content);
-                if (heading_level > 0) {
-                    headingLevel = heading_level;
-                    finalContent = stripped;
+                // No content update, just metadata
+                if (options.heading !== undefined) {
+                    const level = parseInt(options.heading, 10);
+                    if (level >= 0 && level <= 3) {
+                        headingLevel = level === 0 ? undefined : level;
+                    }
                 }
             }
             // Handle open/closed state
@@ -106,25 +160,14 @@ Examples:
             else if (options.closed) {
                 openState = false;
             }
-            // Handle TODO/DONE status
-            if (options.clearStatus) {
-                finalContent = clearStatus(finalContent);
-            }
-            else if (options.todo) {
-                finalContent = applyStatus(finalContent, 'TODO');
-            }
-            else if (options.done) {
-                finalContent = applyStatus(finalContent, 'DONE');
-            }
             if (options.debug) {
                 printDebug('Block UID', blockUid);
                 printDebug('Graph', options.graph || 'default');
-                printDebug('Content', finalContent);
+                printDebug('Content', finalContent !== undefined ? finalContent : '(no change)');
                 printDebug('Heading level', headingLevel ?? 'none');
                 printDebug('Open state', openState ?? 'unchanged');
                 printDebug('Status', options.todo ? 'TODO' : options.done ? 'DONE' : options.clearStatus ? 'cleared' : 'unchanged');
             }
-            const graph = resolveGraph(options, true); // This is a write operation
             const batchOps = new BatchOperations(graph);
             const result = await batchOps.processBatch([{
                     action: 'update-block',