roam-research-mcp 2.15.3 → 2.19.1

package/README.md

@@ -34,6 +34,9 @@ cat meeting_notes.md | roam save --title "Meeting: Project Alpha"
 # Create a TODO item on today's daily page
 echo "Buy milk" | roam save --todo
 
+# Prepend to top of page (newest-first ordering)
+roam save -p "Changelog" --order first "v2.18.0 release"
+
 # Search your graph and pipe results to another tool
 roam search "important" --json | jq .
 
@@ -43,6 +46,16 @@ roam search --namespace "Convention"    # Finds all Convention/* pages
 # Fetch a page by title
 roam get "Roam Research"
 
+# Fetch daily pages using any date format (auto-normalized)
+roam get today                          # Today's daily page
+roam get 2026-03-21                     # ISO date → "March 21st, 2026"
+roam get "03/21/2026"                   # US date → "March 21st, 2026"
+roam get "March 21"                     # Named (assumes current year)
+
+# Fetch a block with ancestors (parent chain to page root)
+roam get abc123def -a              # Block + children + ancestors
+roam get abc123def -a -d 0         # Ancestors only, no children
+
 # Fetch page by UID or Roam URL
 roam get page abc123def
 roam get page "https://roamresearch.com/#/app/my-graph/page/abc123def"
@@ -84,9 +97,11 @@ The MCP server exposes these tools to AI assistants (like Claude), enabling them
 | Tool Name | Description |
 | :--- | :--- |
 | `roam_fetch_page_by_title` | Fetch page content by title. |
-| `roam_fetch_block_with_children` | Fetch a block and its nested children by UID (resolves refs). |
+| `roam_fetch_page_full_view` | Fetch a page's content plus all linked references with breadcrumb context and children. |
+| `roam_fetch_block` | Fetch a block by UID with optional children (depth) and/or ancestors (up to page root). |
 | `roam_create_page` | Create new pages, optionally with mixed text and table content. |
 | `roam_update_page_markdown` | Update a page using smart diff (preserves block UIDs). |
+| `roam_get_subpages` | List sub-pages under a namespace prefix (e.g. "Project/") with optional tag filter. |
 | `roam_search_by_text` | Full-text search across the graph or within specific pages. Supports namespace prefix search for page titles. |
 | `roam_search_block_refs` | Find blocks that reference a page, tag, or block UID. |
 | `roam_search_by_status` | Find TODO or DONE items. |

package/build/Roam_Markdown_Cheatsheet.md

@@ -184,6 +184,12 @@ CREATING:
 ├─ Memory → roam_remember
 └─ Todos → roam_add_todo
 
+NESTING (roam_import_markdown): nests by BOTH indentation AND markdown heading
+level — content and deeper headings fold under their heading (## under #, ### under
+##). Use it for heading-structured docs. roam_create_page nests ONLY by explicit
+per-item `level` integers, so heading-structured markdown sent to create_page
+imports flat. Don't use `---` dividers; they become horizontal-rule blocks.
+
 SEARCHING:
 ├─ By tag → roam_search_for_tag
 ├─ By text → roam_search_by_text
@@ -192,7 +198,7 @@ SEARCHING:
 ├─ Block refs → roam_search_block_refs
 ├─ Modified today → roam_find_pages_modified_today
 ├─ Page content → roam_fetch_page_by_title
-├─ Block + children → roam_fetch_block_with_children
+├─ Block (children/ancestors) → roam_fetch_block
 ├─ Memories → roam_recall
 └─ Complex → roam_datomic_query
 ```
@@ -237,6 +243,8 @@ Server returns `{"uid_map": {"parent": "Xk7mN2pQ9"}}`.
 **Open question:** `{{[[TODO]]}} Research: <question> #[[open questions]]`
 
 ---
+<personalization_layer>
+
 # Roam Preferences — Personalization Layer
 
 > This section contains YOUR specific conventions, tagging philosophy, and graph-specific rules. Customize to match your workflow.
@@ -245,199 +253,21 @@ Server returns `{"uid_map": {"parent": "Xk7mN2pQ9"}}`.
 
 ## Graph-Level Behaviors
 
-### On Creating New Pages
-<!-- CUSTOMIZE: What should happen when a new page is created? -->
-- After creating a new page, add a reference block on today's daily page: `Created page: [[New Page Name]]`
-- <!-- Add any naming conventions, required metadata, etc. -->
-
-### On Adding Content
-<!-- CUSTOMIZE: Any rules about where/how content gets added? -->
-- Default location for quick captures: Daily page
-- Long-form content: Create dedicated page, link from daily page
-- <!-- Your preferences here -->
-
----
 
 ## Tagging Philosophy
 
-### Core Principle
-> Tag for **intellectual collision** and **future discovery**, not just categorization. Every tag should maximize potential for unexpected connections.
-
-### The Serendipity Test
-Before tagging, ask: *"Could this concept surprise me by connecting to something completely unrelated?"*
-
-### What To Tag — Decision Framework
-
-```
-ASK YOURSELF:
-┌─ How will Future Me find this?
-│   └─ Tag by retrieval context, not just content
-│
-├─ What domain does this belong to?
-│   └─ Use broad category tags: #[[knowledge management]], #[[decision-making]]
-│
-├─ Is this a proper noun?
-│   └─ YES → Wrap name (no titles): [[Werner Erhard]], [[NASA]]
-│   └─ For abbreviations: [NASA]([[National Aeronautics and Space Administration (NASA)]])
-│
-├─ Could this alias to existing page?
-│   └─ YES → [displayed phrase]([[existing page name]])
-│   └─ Example: [frameworks for decisions]([[decision-making frameworks]])
-│
-└─ Parent block with children?
-    └─ Tag parent when category applies to all children
-    └─ Tag individual children for specific categorization
-```
-
-### Tag Type Selection
-
-| Use This | When |
-|----------|------|
-| `[[Page Reference]]` | Concept deserves its own page, will be expanded |
-| `#[[hashtag]]` | Categorization, filtering, won't be a standalone page |
-| `#single-word` | Simple, unambiguous category |
-| Attribute `Type::` | Structured metadata for queries |
-
-### WHEN creating Endnotes/Footnotes:
-- Find/Create the block with heading "Footnotes::" and nest footnote item below. (Footnotes do not need to be on the same page as the block to which it references. Typically on the same page unless instructed otherwise.)
-- If not known, retrieve the block_uid reference for this footnote item.
-- In the block referencing the footnote, append the reference with footnote-item-block_id, example: "- <block_text> #ref ((block_uid))"
-
-### Structural Tagging (Beyond Content)
-
-Tag by **patterns and mechanisms**, not just subjects:
-
-| Structural Tag | Connects |
-|----------------|----------|
-| `#[[has feedback loops]]` | Systems, habits, markets, conversations |
-| `#[[requires calibration]]` | Instruments, relationships, AI prompts |
-| `#[[exhibits emergence]]` | Complexity, culture, creativity |
-| `#[[perspective switching]]` | Photography, negotiation, analysis |
-| `#[[flow dynamics]]` | Fluids, music, conversation, sequences |
-
-### Problem-Oriented Tagging
-
-Tag by problems solved, not methods used:
-
-- `#[[breaking cognitive constraints]]`
-- `#[[expanding solution spaces]]`
-- `#[[preventing expert blindness]]`
-
-### Temporal & State-Based Tags
-
-| Tag Type | Examples |
-|----------|----------|
-| Future relevance | `#[[will be relevant in 5 years]]`, `#[[connects to unborn projects]]` |
-| Mental state triggers | `#[[feeling stuck in patterns]]`, `#[[needing fresh perspective]]` |
-| Review scheduling | `[[For review]]: [[August 12th, 2026]]` |
-
----
 
 ## Formatting Conventions
 
-### Quotes
-```
-<quote text> —[[Author Name]] #quote #[[topic1]] #[[topic2]]
-```
-Always include 2-3 relevant hashtags after quotes.
-
-### TODOs and Follow-ups
-```
-{{[[TODO]]}} <action needed>
-{{[[TODO]]}} #researchThis : <topic to investigate> 
-```
-
-### Scheduled Reviews
-
-- Any block tagged with a date will show on that respective daily page.
-
-```
-[[For review]]: [[Date in ordinal format]]
-```
-Optional labels: "Deadline", "Approved", "Pending", "Deferred", "Postponed until"
-
-### Aliasing for Case Sensitivity
-When a tag would awkwardly affect sentence capitalization:
-```
-[Cognitive biases]([[cognitive biases]]) affect decision-making...
-```
-
-### Definitions (OVERRIDE)
-```
-#def [[<term>]] : <definition>
-```
-
----
 
 ## Constraints & Guardrails
 
-### DON'T
-- **Overtag** — Quality over quantity; each tag should earn its place
-- **Tag obvious/redundant** — If parent block is tagged, children inherit context
-- **Use inconsistent capitalization** — Tags are lowercase unless proper nouns
-- **Create orphan tags** — Check if existing page/tag serves the purpose
-- **Bold Attributes** - ❌ `**Attribute**::`, ✅ `Attribute::` (Roam auto-formats)
-- **Separators** - `---` Don't use them.
-
-### DO
-- **Think retrieval-first** — How will you search for this later?
-- **Cross-pollinate domains** — Force unlikely intellectual meetings
-- **Update aging tags** — As interests evolve, so should tag vocabulary
-- **Track surprise discoveries** — When unexpected connections yield insights, engineer more of those patterns
-
----
 
 ## Custom Rules
 
-<!-- 
-CUSTOMIZE THIS SECTION with your specific conventions:
-- Naming patterns for certain page types
-- Required attributes for books/articles/people
-- Project-specific tagging schemes
-- Integration rules with other tools
-- etc.
--->
-
-### Example Custom Rules (modify as needed):
-
-**Books:**
-```
-[[Book/<title> | <author>]]
-Type:: Book
-Author:: [[Author Name]]
-Status:: Reading | Completed | Abandoned
-Rating:: X/5
-```
-
-**People:**
-```
-[[Person Name]]
-Type:: Person
-Context:: How I know them
-```
-- When linking bibliographic references —>
-  Example: `McAdams, D.P. (2001) [The Psychology of Life Stories](https://journals.sagepub.com/doi/10.1037/1089-2680.5.2.100) — foundational paper`
-  - [McAdams, D.P.]([[Dan McAdams]]) - author's name in the graph
-  - If source URL, link to source: [The Psychology of Life Stories](https://journals.sagepub.com/doi/10.1037/1089-2680.5.2.100)
-  - If notes page exists or will exist in Roam: append ` | [Notes]([[Article/The Psychology of Life Stories]]), if not, just leave it without link.
-  
-**Projects:**
-```
-[[Project/<project anme>]]
-Status:: Active | Paused | Completed
-Start:: [[Date]]
-```
----
 
 ## Integration Notes
 
 <!-- CUSTOMIZE: Any rules about how Roam integrates with your other tools/systems -->
 
-- Daily pages serve as: <!-- inbox / journal / task list / etc. -->
-- Weekly reviews occur on: <!-- day of week -->
-- Content flows from: <!-- capture tools, read-later apps, etc. -->
-- Content flows to: <!-- publishing, archives, etc. -->
-
----
-
-*End of Personalization Layer*
+</personalization_layer>

package/build/cli/batch/resolver.js

@@ -45,6 +45,21 @@ export async function resolveDailyPageUid(graph) {
     const dailyTitle = getDailyPageTitle();
     return resolvePageUid(graph, dailyTitle);
 }
+/**
+ * Check if a string looks like a valid Roam UID (not a page title)
+ */
+export function isUidFormat(ref) {
+    // 9 alphanumeric characters (standard block UID)
+    if (/^[a-zA-Z0-9_-]{9}$/.test(ref))
+        return true;
+    // MM-DD-YYYY daily page UID
+    if (/^\d{2}-\d{2}-\d{4}$/.test(ref))
+        return true;
+    // Placeholder {{name}}
+    if (/^\{\{[^}]+\}\}$/.test(ref))
+        return true;
+    return false;
+}
 /**
  * Collect all unique page titles that need resolution from commands
  */
@@ -56,6 +71,13 @@ export function collectPageTitles(commands) {
         if ('page' in params && typeof params.page === 'string') {
             titles.add(params.page);
         }
+        // Commands that can have 'parent' param — if it looks like a page title, resolve it
+        if ('parent' in params && typeof params.parent === 'string') {
+            const parent = params.parent;
+            if (!isUidFormat(parent)) {
+                titles.add(parent);
+            }
+        }
         // Remember command can have heading that needs parent page resolution
         // But heading lookup is handled separately
         // Todo/remember without explicit page need daily page
@@ -126,8 +148,13 @@ export function resolveParentRef(ref, context) {
     if (context.pageUids.has(ref)) {
         return context.pageUids.get(ref);
     }
-    // Assume it's a direct UID
-    return ref;
+    // If it looks like a UID, return as-is
+    if (isUidFormat(ref)) {
+        return ref;
+    }
+    // Not a UID and not resolved — this is a page title that wasn't collected/resolved
+    // Return null so callers can handle it (should not happen if collectPageTitles is correct)
+    return null;
 }
 /**
  * Generate a placeholder UID for tracking

package/build/cli/batch/translator.js

@@ -39,7 +39,10 @@ export function translateCommand(command, context) {
 function getParentUid(params, context) {
     // Direct parent UID or placeholder
     if (params.parent) {
-        return resolveParentRef(params.parent, context) || params.parent;
+        const resolved = resolveParentRef(params.parent, context);
+        if (resolved)
+            return resolved;
+        throw new Error(`Parent "${params.parent}" could not be resolved to a UID. Page may not exist.`);
     }
     // Page UID
     if (params.pageUid) {

package/build/cli/commands/batch.js

@@ -227,7 +227,7 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                 return;
             }
             const graph = resolveGraph(options, true);
-            // Phase 1: Collect and resolve page titles
+            // Phase 1: Collect and resolve page titles (from 'page' AND 'parent' params)
             const context = createResolutionContext();
             const pageTitles = collectPageTitles(commands);
             if (pageTitles.size > 0) {
@@ -238,10 +238,25 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                 for (const [title, uid] of resolved) {
                     context.pageUids.set(title, uid);
                 }
-                // Check for unresolved pages
+                // Auto-create unresolved pages (e.g., parent: "Page Title" for a page that doesn't exist yet)
                 const unresolved = Array.from(pageTitles).filter(t => !context.pageUids.has(t));
                 if (unresolved.length > 0) {
-                    exitWithError(`Page(s) not found: ${unresolved.map(t => `"${t}"`).join(', ')}`);
+                    if (options.debug) {
+                        printDebug('Auto-creating pages', unresolved);
+                    }
+                    const pageOps = new PageOperations(graph);
+                    for (const title of unresolved) {
+                        const result = await pageOps.createPage(title);
+                        if (result.success && result.uid) {
+                            context.pageUids.set(title, result.uid);
+                            if (options.debug) {
+                                printDebug(`Auto-created "${title}"`, result.uid);
+                            }
+                        }
+                        else {
+                            exitWithError(`Failed to create page "${title}"`);
+                        }
+                    }
                 }
                 if (options.debug) {
                     printDebug('Resolved pages', Object.fromEntries(context.pageUids));

package/build/cli/commands/get.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { PageOperations } from '../../tools/operations/pages.js';
 import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
 import { SearchOperations } from '../../tools/operations/search/index.js';
+import { FullPageViewOperations } from '../../tools/operations/full-page-view.js';
 import { formatPageOutput, formatBlockOutput, formatTodoOutput, formatGroupedOutput, flattenBlocks, blocksToMarkdown, printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
 import { readStdin } from '../utils/input.js';
@@ -179,13 +180,91 @@ Examples:
         }
     });
 }
+/**
+ * Create the 'full' subcommand for full page view (content + linked references)
+ */
+function createFullSubcommand() {
+    return new Command('full')
+        .description('Fetch full page view: content + linked references with breadcrumb context')
+        .argument('<title>', 'Page title (for date pages use "January 2nd, 2025")')
+        .option('-d, --depth <n>', 'Child depth for referring blocks (default: 4)', '4')
+        .option('-n, --max-refs <n>', 'Max linked references (default: 200)', '200')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+        .option('--debug', 'Show debug information')
+        .addHelpText('after', `
+Examples:
+  roam get full "Project Notes"              # Full view with backlinks
+  roam get full "TODO" -n 50                 # Cap references at 50
+  roam get full "Meeting Notes" -d 2         # Shallow children depth
+`)
+        .action(async (title, options) => {
+        try {
+            const resolvedTitle = resolveRelativeDate(title);
+            const depth = parseInt(options.depth || '4', 10);
+            const maxRefs = parseInt(options.maxRefs || '200', 10);
+            if (options.debug) {
+                printDebug('Title', resolvedTitle);
+                printDebug('Children depth', depth);
+                printDebug('Max references', maxRefs);
+                printDebug('Graph', options.graph || 'default');
+            }
+            const graph = resolveGraph(options, false);
+            const pageOps = new PageOperations(graph);
+            const fullViewOps = new FullPageViewOperations(graph, pageOps);
+            const result = await fullViewOps.fetchPageFullView(resolvedTitle, depth, maxRefs);
+            console.log(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}
+/**
+ * Create the 'subpages' subcommand for namespace-based sub-page listing
+ */
+function createSubpagesSubcommand() {
+    return new Command('subpages')
+        .description('List sub-pages under a namespace prefix (e.g. "Project/", "Framework/")')
+        .argument('<prefix>', 'Namespace prefix (trailing "/" added automatically)')
+        .option('--filter-tag <tag>', 'Only sub-pages containing this tag')
+        .option('--content', 'Include each sub-page\'s block content')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+        .option('--debug', 'Show debug information')
+        .addHelpText('after', `
+Examples:
+  roam get subpages "Project"                # List all Project/* pages
+  roam get subpages "Framework" --content    # With block content
+  roam get subpages "Project" --filter-tag active  # Only active projects
+`)
+        .action(async (prefix, options) => {
+        try {
+            if (options.debug) {
+                printDebug('Prefix', prefix);
+                printDebug('Filter tag', options.filterTag || 'none');
+                printDebug('Include content', options.content || false);
+                printDebug('Graph', options.graph || 'default');
+            }
+            const graph = resolveGraph(options, false);
+            const pageOps = new PageOperations(graph);
+            const fullViewOps = new FullPageViewOperations(graph, pageOps);
+            const result = await fullViewOps.fetchSubPages(prefix, options.filterTag, options.content);
+            console.log(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}
 export function createGetCommand() {
     const cmd = new Command('get')
         .description('Fetch pages, blocks, or TODO/DONE items with optional ref expansion')
         .argument('[target]', 'Page title, block UID, or relative date. Reads from stdin if "-" or omitted.')
         .option('-j, --json', 'Output as JSON instead of markdown')
         .option('-s, --structure', 'Output flattened structure with UIDs and order (for surgical updates)')
-        .option('-d, --depth <n>', 'Child levels to fetch (default: 4)', '4')
+        .option('-d, --depth <n>', 'Child levels to fetch (default: 4, 0 = no children)', '4')
+        .option('-a, --ancestors', 'Include ancestor chain up to page root')
         .option('-r, --refs [n]', 'Expand ((uid)) refs in output (default depth: 1, max: 4)')
         .option('-f, --flat', 'Flatten hierarchy to single-level list')
         .option('-u, --uid', 'Return only the page UID (resolve title to UID)')
@@ -240,6 +319,8 @@ Examples:
   roam get "Page" -j                          # JSON output
   roam get "Page" -f                          # Flat list (no hierarchy)
   roam get abc123def -d 2                     # Limit depth to 2 levels
+  roam get abc123def -a                       # Include ancestors up to page root
+  roam get abc123def -a -d 0                  # Ancestors only, no children
   roam get "Page" -r                          # Expand block refs (depth 1)
   roam get "Page" -r 3                        # Expand refs up to 3 levels deep
 
@@ -288,6 +369,7 @@ Note: For flat results with UIDs, use 'roam search' instead.
         try {
             const graph = resolveGraph(options, false);
             const depth = parseInt(options.depth || '4', 10);
+            const ancestors = options.ancestors || false;
             // Parse refs: true/string means enabled, number sets max depth (default 1, max 4)
             const refsDepth = options.refs !== undefined
                 ? Math.min(4, Math.max(1, parseInt(options.refs, 10) || 1))
@@ -472,7 +554,7 @@ Note: For flat results with UIDs, use 'roam search' instead.
                 // Standard output: fetch full blocks with children
                 const blocks = [];
                 for (const match of limitedMatches) {
-                    let block = await blockOps.fetchBlockWithChildren(match.block_uid, depth);
+                    let block = await blockOps.fetchBlock(match.block_uid, depth, ancestors);
                     if (block) {
                         // Resolve refs if requested (default: enabled for tag/text search)
                         const effectiveRefsDepth = refsDepth > 0 ? refsDepth : 1;
@@ -533,7 +615,7 @@ Note: For flat results with UIDs, use 'roam search' instead.
                     if (options.debug)
                         printDebug('Fetching block', { uid: blockUid });
                     const blockOps = new BlockRetrievalOperations(graph);
-                    let block = await blockOps.fetchBlockWithChildren(blockUid, depth);
+                    let block = await blockOps.fetchBlock(blockUid, depth, ancestors);
                     if (!block) {
                         // If fetching multiple, maybe warn instead of exit?
                         // For now, consistent behavior: print error message to stderr but continue?
@@ -590,5 +672,7 @@ Note: For flat results with UIDs, use 'roam search' instead.
     });
     // Add subcommands
     cmd.addCommand(createPageSubcommand());
+    cmd.addCommand(createFullSubcommand());
+    cmd.addCommand(createSubpagesSubcommand());
     return cmd;
 }

package/build/cli/commands/save.js

@@ -193,6 +193,7 @@ export function createSaveCommand() {
         .option('--json', 'Force JSON array format: [{text, level, heading?}, ...]')
         .option('--flatten', 'Disable heading hierarchy inference (all blocks at root level)')
         .option('--lines', 'Treat each non-empty line as a separate block (bypass markdown parsing)')
+        .option('--order <position>', 'Insertion position for top-level blocks: "first", "last", or integer (default: "last")')
         .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')
@@ -223,6 +224,10 @@ Examples:
   pbpaste | roam save --lines --title "Clipboard" # Each line = separate block
   cat list.txt | roam save --lines -p "Notes"     # Lines to blocks on page
 
+  # Insertion order
+  roam save -p "Changelog" --order first "v2.18.0"   # Prepend to top
+  roam save -p "Log" --order 1 "After first block"    # Insert at position
+
   # Combine options
   roam save -p "Work" --parent "## Today" "Done with task" -c "wins"
 
@@ -363,12 +368,30 @@ JSON format (--json):
                     }
                 }
             }
+            // Parse --order option
+            let orderValue = 'last';
+            if (options.order !== undefined) {
+                if (options.order === 'first') {
+                    orderValue = 'first';
+                }
+                else if (options.order === 'last') {
+                    orderValue = 'last';
+                }
+                else {
+                    const parsed = parseInt(options.order, 10);
+                    if (isNaN(parsed) || parsed < 0) {
+                        exitWithError('--order must be "first", "last", or a non-negative integer');
+                    }
+                    orderValue = parsed;
+                }
+            }
             if (options.debug) {
                 printDebug('Input', input || 'stdin');
                 printDebug('Is file', isFile);
                 printDebug('Is JSON', isJson);
                 printDebug('Lines mode', options.lines || false);
                 printDebug('Flatten mode', options.flatten || false);
+                printDebug('Order', orderValue);
                 printDebug('Graph', options.graph || 'default');
                 printDebug('Content blocks', contentBlocks.length);
                 printDebug('Parent UID', parentUid || 'none');
@@ -392,7 +415,7 @@ JSON format (--json):
             const hasParent = parentUid || parentHeading;
             const hasTitle = options.title;
             const wantsPage = hasTitle && !hasParent;
-            if (wantsPage || (isFile && !hasParent)) {
+            if (wantsPage || (isFile && !hasParent && !options.page)) {
                 // PAGE MODE: create a page
                 const pageTitle = options.title || (sourceFilename ? basename(sourceFilename, '.md').replace('.json', '') : undefined);
                 if (!pageTitle) {
@@ -439,8 +462,16 @@ JSON format (--json):
                     uidMap[i] = uidPlaceholder;
                     // Determine parent for this block
                     let blockParent;
+                    let blockOrder;
                     if (block.level === 1) {
                         blockParent = parentUid;
+                        // Apply --order to top-level blocks only
+                        if (typeof orderValue === 'number') {
+                            blockOrder = orderValue + i;
+                        }
+                        else {
+                            blockOrder = orderValue;
+                        }
                     }
                     else {
                         // Find the closest ancestor at level - 1
@@ -454,12 +485,13 @@ JSON format (--json):
                         else {
                             blockParent = parentUid;
                         }
+                        blockOrder = 'last';
                     }
                     actions.push({
                         action: 'create-block',
                         location: {
                             'parent-uid': blockParent,
-                            order: 'last'
+                            order: blockOrder
                         },
                         string: block.text,
                         uid: `{{uid:${uidPlaceholder}}}`,
@@ -521,8 +553,16 @@ JSON format (--json):
                 uidMap[i] = uidPlaceholder;
                 // Determine parent for this block
                 let blockParent;
+                let blockOrder;
                 if (block.level === 1) {
                     blockParent = targetParentUid;
+                    // Apply --order to top-level blocks only
+                    if (typeof orderValue === 'number') {
+                        blockOrder = orderValue + i;
+                    }
+                    else {
+                        blockOrder = orderValue;
+                    }
                 }
                 else {
                     // Find the closest ancestor at level - 1
@@ -536,6 +576,7 @@ JSON format (--json):
                     else {
                         blockParent = targetParentUid;
                     }
+                    blockOrder = 'last';
                 }
                 // Append category tags to first block only
                 const blockText = i === 0 && categoryTags
@@ -545,7 +586,7 @@ JSON format (--json):
                     action: 'create-block',
                     location: {
                         'parent-uid': blockParent,
-                        order: 'last'
+                        order: blockOrder
                     },
                     string: blockText,
                     uid: `{{uid:${uidPlaceholder}}}`,