roam-research-mcp 1.6.0 → 2.4.0

package/README.md

@@ -1,13 +1,13 @@
-![](./roam-research-mcp-image.jpeg)
+![Roam Research MCP + CLI](./roam-research-mcp-header.png)
 
-# Roam Research MCP Server
+# Roam Research MCP + CLI
 
 [![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)
-[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)
 
-A Model Context Protocol (MCP) server and standalone CLI that provides comprehensive access to Roam Research's API functionality. The MCP server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface, while the CLI (`roam`) lets you fetch, search, and import content directly from the command line. Supports standard input/output (stdio) and HTTP Stream communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
+A Model Context Protocol (MCP) server and standalone CLI that provides comprehensive access to Roam Research's API functionality. The MCP server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface, while the CLI (`roam`) lets you fetch, search, and import content directly from the command line. Supports multi-graph configurations, write protection, standard input/output (stdio) and HTTP Stream communication. (Personal project, not officially endorsed by Roam Research)
 
 <a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://glama.ai/mcp/servers/fzfznyaflu/badge" alt="Roam Research MCP server" /></a>
 <a href="https://mseep.ai/app/2b3pro-roam-research-mcp"><img width="380" height="200" src="https://mseep.net/pr/2b3pro-roam-research-mcp-badge.png" alt="MseeP.ai Security Assessment Badge" /></a>
@@ -85,7 +85,7 @@ docker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp
 
 ## Standalone CLI: `roam`
 
-A standalone command-line tool for interacting with Roam Research directly, without running the MCP server. Provides four subcommands: `get`, `search`, `save`, and `refs`.
+A standalone command-line tool for interacting with Roam Research directly, without running the MCP server. Provides eight subcommands: `get`, `search`, `save`, `refs`, `update`, `batch`, `rename`, and `status`.
 
 ### Installation
 
@@ -111,7 +111,7 @@ Configure via `.env` file in the project root or set as environment variables.
 
 ---
 
-### `roam get` - Fetch pages or blocks
+### `roam get` - Fetch pages, blocks, or TODOs
 
 Fetch content from Roam and output as markdown or JSON.
 
@@ -132,6 +132,18 @@ roam get "Daily Notes" --depth 2
 # Flatten hierarchy
 roam get "Daily Notes" --flat
 
+# Fetch TODO items
+roam get --todo
+
+# Fetch DONE items
+roam get --done
+
+# Filter TODOs by page
+roam get --todo -p "January 2nd, 2026"
+
+# Include/exclude filter
+roam get --todo -i "urgent,important" -e "someday"
+
 # Debug mode
 roam get "Daily Notes" --debug
 ```
@@ -141,6 +153,11 @@ roam get "Daily Notes" --debug
 - `--depth <n>` - Child levels to fetch (default: 4)
 - `--refs <n>` - Block ref expansion depth (default: 1)
 - `--flat` - Flatten hierarchy to single-level list
+- `--todo` - Fetch TODO items
+- `--done` - Fetch DONE items
+- `-p, --page <title>` - Filter TODOs/DONEs by page title
+- `-i, --include <terms>` - Include only items containing these terms (comma-separated)
+- `-e, --exclude <terms>` - Exclude items containing these terms (comma-separated)
 - `--debug` - Show query metadata
 
 ---
@@ -186,9 +203,9 @@ roam search "keyword" --json
 
 ---
 
-### `roam save` - Import markdown
+### `roam save` - Import markdown or create TODOs
 
-Import markdown content to Roam, creating or updating pages.
+Import markdown content to Roam, creating or updating pages, or add TODO items.
 
 ```bash
 # From a file (title derived from filename)
@@ -211,11 +228,21 @@ roam save --title "Quick Note" << EOF
 - Item 2
   - Nested item
 EOF
+
+# Create a TODO item on today's daily page
+roam save --todo "Buy groceries"
+
+# Create multiple TODOs from stdin (newline-separated)
+echo -e "Task 1\nTask 2\nTask 3" | roam save --todo
+
+# Pipe TODO list from file
+cat todos.txt | roam save --todo
 ```
 
 **Options:**
 - `--title <title>` - Page title (defaults to filename without `.md`)
 - `--update` - Update existing page using smart diff (preserves block UIDs)
+- `-t, --todo [text]` - Add a TODO item to today's daily page (text or stdin)
 - `--debug` - Show debug information
 
 **Features:**
@@ -223,6 +250,7 @@ EOF
 - Automatically links the new page from today's daily page
 - Converts standard markdown to Roam-flavored markdown
 - Smart diff mode (`--update`) preserves block UIDs for existing content
+- TODO mode creates `{{[[TODO]]}}` items on the daily page
 
 ---
 
@@ -278,6 +306,103 @@ JSON output for programmatic use:
 
 ---
 
+### `roam batch` - Execute multiple operations in one API call
+
+Execute multiple operations in a single batch API call to reduce rate limiting issues.
+
+```bash
+# From a JSON file
+roam batch commands.json
+
+# From stdin
+cat commands.json | roam batch
+
+# Dry run (validate without executing)
+roam batch --dry-run commands.json
+
+# With debug output
+roam batch --debug commands.json
+```
+
+**Command Format:**
+
+Input is a JSON array of command objects:
+
+```json
+[
+  { "command": "create", "params": { "text": "Parent block", "parent": "pageUid", "as": "p1" } },
+  { "command": "create", "params": { "text": "Child block", "parent": "{{p1}}" } },
+  { "command": "todo", "params": { "text": "Task item" } },
+  { "command": "codeblock", "params": { "parent": "{{p1}}", "language": "ts", "code": "const x = 1;" } }
+]
+```
+
+**Supported Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `create` | Create a block |
+| `update` | Update block content |
+| `delete` | Delete a block |
+| `move` | Move block to new location |
+| `todo` | Create TODO item |
+| `table` | Create table structure |
+| `outline` | Create nested outline |
+| `remember` | Create tagged memory |
+| `page` | Create page with content |
+| `codeblock` | Create code block |
+
+**Features:**
+
+- Placeholder references (`{{name}}`) for cross-command dependencies
+- Automatic page title → UID resolution
+- Daily page auto-resolution for `todo` and `remember`
+- Level-based hierarchy for `outline` command
+- `--dry-run` mode for validation
+
+**Options:**
+- `--dry-run` - Validate and show planned actions without executing
+- `--debug` - Show debug information
+- `-g, --graph <name>` - Target graph (multi-graph mode)
+- `--write-key <key>` - Write confirmation key
+
+See [docs/batch-cli-spec.md](docs/batch-cli-spec.md) for full specification.
+
+---
+
+### `roam status` - Show available graphs
+
+Display configured graphs and their connection status.
+
+```bash
+# Show available graphs
+roam status
+
+# Test connectivity to all graphs
+roam status --ping
+
+# Output as JSON
+roam status --json
+```
+
+**Example Output:**
+
+```
+Roam Research MCP v2.4.0
+
+Graphs:
+  • personal (default)  ✓ connected
+  • work [protected]    ✓ connected
+
+Write-protected graphs require --write-key flag for modifications.
+```
+
+**Options:**
+- `--ping` - Test connection to each graph
+- `--json` - Output as JSON for scripting
+
+---
+
 ## To Test
 
 Run [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build using the provided npm script:
@@ -304,7 +429,7 @@ The server provides powerful tools for interacting with Roam Research:
 
 1. `roam_fetch_page_by_title`: Fetch page content by title. Returns content in the specified format.
 2. `roam_fetch_block_with_children`: Fetch a block by its UID along with its hierarchical children down to a specified depth. Automatically handles `((UID))` formatting.
-3. `roam_create_page`: Create new pages with optional content and headings. **Now supports mixed content types** - content array can include both text blocks and tables in a single call using `{type: "table", headers, rows}` format. Creates a block on the daily page linking to the newly created page.
+3. `roam_create_page`: Create new pages with optional content and headings. **Now supports mixed content types** - content array can include both text blocks and tables in a single call using `{type: "table", headers, rows}` format. Automatically adds a "Processed: [[date]]" block at the end of the page linking to today's daily page.
 4. `roam_create_table`: Create a properly formatted Roam table with specified headers and rows. Abstracts Roam's complex nested table structure, validates row/column consistency, and handles empty cells automatically.
 5. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
 6. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
@@ -316,12 +441,13 @@ The server provides powerful tools for interacting with Roam Research:
 12. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
 13. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
 14. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby or exclude blocks with a specific tag. This tool supports pagination via the `limit` and `offset` parameters.
-15. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
+15. `roam_remember`: Add a memory or piece of information to remember. Supports optional `heading` parameter to nest under a specific heading on the daily page (created if missing), or `parent_uid` to nest under a specific block. (Internally uses `roam_process_batch_actions`.)
 16. `roam_recall`: Retrieve all stored memories.
 17. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. Now supports client-side regex filtering for enhanced post-query processing. Optimal for complex filtering (including regex), highly complex boolean logic, arbitrary sorting criteria, and proximity search.
 18. `roam_markdown_cheatsheet`: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if `CUSTOM_INSTRUCTIONS_PATH` environment variable is set.
 19. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. **Now includes pre-validation** that catches errors before API execution, with structured error responses and automatic rate limit retry with exponential backoff. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
 20. `roam_update_page_markdown`: Update an existing page with new markdown content using smart diff. **Preserves block UIDs** where possible, keeping references intact across the graph. Uses three-phase matching (exact text → normalized → position fallback) to generate minimal operations. Supports `dry_run` mode to preview changes. Ideal for syncing external markdown files, AI-assisted content updates, and batch modifications without losing block references.
+21. `roam_move_block`: Move a block to a new location (different parent or position). Convenience wrapper around `roam_process_batch_actions` for single block moves. Parameters: `block_uid` (required), `parent_uid` (required), `order` (optional, defaults to "last").
 
 **Deprecated Tools**:
 The following tools have been deprecated as of `v0.36.2` in favor of the more powerful and flexible `roam_process_batch_actions`:
@@ -462,9 +588,13 @@ The tool will match existing blocks by content, update changed text, add new blo
    - Create a new token
 
 2. Configure the environment variables:
-   You have two options for configuring the required environment variables:
 
-   Option 1: Using a .env file (Recommended for development)
+   ### Single Graph Mode (Default)
+
+   For most users with one Roam graph, use the simple configuration:
+
+   **Option 1: Using a .env file (Recommended for development)**
+
    Create a `.env` file in the roam-research directory:
 
    ```
@@ -475,7 +605,8 @@ The tool will match existing blocks by content, update changed text, add new blo
    HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication
    ```
 
-   Option 2: Using MCP settings (Alternative method)
+   **Option 2: Using MCP settings (Alternative method)**
+
    Add the configuration to your MCP settings file. Note that you may need to update the `args` to `["/path/to/roam-research-mcp/build/index.js"]` if you are running the server directly.
 
    - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
@@ -501,6 +632,62 @@ The tool will match existing blocks by content, update changed text, add new blo
 
    Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.
 
+   ---
+
+   ### Multi-Graph Mode (v2.0.0+)
+
+   For users with multiple Roam graphs, you can configure a single MCP server instance to connect to all of them. This is more token-efficient than running multiple server instances.
+
+   **Configuration:**
+
+   ```json
+   ROAM_GRAPHS="{\"personal\":{\"token\":\"roam-graph-token-xxx\",\"graph\":\"my-personal-graph\"},\"work\":{\"token\":\"roam-graph-token-yyy\",\"graph\":\"company-graph\",\"write_key\":\"confirm-work-write\"}}"
+   ROAM_DEFAULT_GRAPH=personal
+   ```
+
+   | Field | Required | Description |
+   |-------|----------|-------------|
+   | `token` | Yes | Roam API token for this graph |
+   | `graph` | Yes | Roam graph name |
+   | `write_key` | No | Required confirmation string for writes to non-default graphs |
+
+   **Usage in Tools:**
+
+   All tools accept optional `graph` and `write_key` parameters:
+
+   ```json
+   {
+     "title": "My Page",
+     "graph": "work",
+     "write_key": "confirm-work-write"
+   }
+   ```
+
+   - **Read operations**: Can target any graph using the `graph` parameter
+   - **Write operations on default graph**: Work without additional parameters
+   - **Write operations on non-default graphs**: Require the `write_key` if configured
+
+   **CLI Usage:**
+
+   All CLI commands support the `-g, --graph` flag:
+
+   ```bash
+   # Read from work graph
+   roam get "Meeting Notes" -g work
+
+   # Write to work graph (requires --write-key if configured)
+   roam save notes.md -g work --write-key "confirm-work-write"
+   ```
+
+   **Safety Model:**
+
+   The `write_key` serves as a confirmation gate (not a secret) to prevent accidental writes to non-default graphs. When a write is attempted without the required key, the error message reveals the expected key:
+
+   ```
+   Write to "work" graph requires write_key confirmation.
+   Provide write_key: "confirm-work-write" to proceed.
+   ```
+
 3. Build the server (make sure you're in the root directory of the MCP):
 
    Note: Customize 'Roam_Markdown_Cheatsheet.md' with any notes and preferences specific to your graph BEFORE building.

package/build/Roam_Markdown_Cheatsheet.md

@@ -1,4 +1,4 @@
-# Roam Markdown Cheatsheet — Generic Foundation v2.0.0
+# Roam Markdown Cheatsheet — Generic Foundation v2.0.1
 
 > ⚠️ **MODEL DIRECTIVE**: Always consult this cheatsheet BEFORE making any Roam tool calls. Syntax errors in Roam are unforgiving.
 
@@ -36,6 +36,8 @@
 
 ⚠️ **CRITICAL**: Never concatenate multi-word tags. `#knowledgemanagement` ≠ `#[[knowledge management]]`
 
+⚠️ **CRITICAL**: Never use `#` to mean "number" (e.g., `#1`, `#2`). In Roam, `#` **always** creates a hashtag. Write `Step 1`, `No. 1`, or just spell out the number instead.
+
 ### Dates
 - **Always use ordinal format**: `[[January 1st, 2025]]`, `[[December 23rd, 2024]]`
 - Ordinals: 1st, 2nd, 3rd, 4th–20th, 21st, 22nd, 23rd, 24th–30th, 31st
@@ -72,7 +74,7 @@ Source:: https://example.com
 | `Note:: Some observation` | Just write the text, or use `#note` | One-off labels don't need attribute syntax |
 | `Summary:: The main point` | `**Summary:** The main point` | Section headers are formatting, not metadata |
 | `Definition:: Some text` | `Term:: Definition` | Only use for actual definitions you want to query |
-| `Implementation Tier 3 (Societal Restructuring):: Some text` | `** Implementation Tier 3 (Societal Restructuring)**: Some text` | Label is specific to current concept |
+| `Implementation Tier 3 (Societal Restructuring):: Some text` | `**Implementation Tier 3 (Societal Restructuring):** Some text` | Label is specific to current concept |
 
 ⚠️ **The Test**: Ask yourself: "Will I ever query for all blocks with this attribute across my graph?" If no, use **bold formatting** (`**Label:**`) instead of `::` syntax.
 
@@ -174,6 +176,7 @@ Tables use nested indentation. Each column header/cell nests ONE LEVEL DEEPER th
 |----------|-----------|-----|
 | `Step 1:: Do this` | `**Step 1:** Do this` | `::` creates queryable attributes; use bold for page-specific labels |
 | `#multiplewords` | `#[[multiple words]]` | Concatenated tags create dead references |
+| `#1`, `#2`, `#3` | `Step 1`, `No. 1`, or spell out | `#` always creates hashtags, never means "number" |
 | `[[january 1, 2025]]` | `[[January 1st, 2025]]` | Must use ordinal format with proper capitalization |
 | `[text](((block-uid)))` | `[text](<((block-uid))>)` | Block ref links need angle bracket wrapper |
 | `{{embed: ((uid))}}` | `{{[[embed]]: ((uid))}}` | Embed requires double brackets around keyword |
@@ -198,9 +201,17 @@ CREATING CONTENT IN ROAM:
 │   └─ Complex/nested markdown → roam_import_markdown
 │       (for deeply nested content, tables, etc.)
 │
+├─ Replacing/revising ENTIRE page content?
+│   └─ roam_update_page_markdown
+│       (fetches page internally, computes smart diff, preserves UIDs)
+│
 ├─ Need to CREATE, UPDATE, MOVE, or DELETE individual blocks?
 │   └─ roam_process_batch_actions
-│       (fine-grained control, temporary UIDs for parent refs)
+│       (fine-grained control, UID placeholders for parent refs)
+│
+├─ Creating a TABLE?
+│   └─ roam_create_table
+│       (handles complex nested structure automatically)
 │
 ├─ Adding a memory/note to remember?
 │   └─ roam_remember (auto-tags with MEMORIES_TAG)
@@ -210,9 +221,11 @@ CREATING CONTENT IN ROAM:
 │
 └─ SEARCHING/READING:
     ├─ Find by tag → roam_search_for_tag
-    ├─ Find by text → roam_search_by_text  
+    ├─ Find by text → roam_search_by_text
     ├─ Find by date range → roam_search_by_date
     ├─ Find by status → roam_search_by_status
+    ├─ Find block/page references → roam_search_block_refs
+    ├─ Find pages modified today → roam_find_pages_modified_today
     ├─ Get page content → roam_fetch_page_by_title
     ├─ Get block + children → roam_fetch_block_with_children
     ├─ Recall memories → roam_recall
@@ -226,18 +239,18 @@ CREATING CONTENT IN ROAM:
 The Roam API has rate limits. Follow these guidelines to minimize API calls:
 
 ### Tool Efficiency Ranking (Best to Worst)
-1. **`roam_process_batch_actions`** - Single API call for multiple operations (MOST EFFICIENT)
-2. **`roam_create_page`** - Batches content with page creation
-3. **`roam_create_outline` / `roam_import_markdown`** - Include verification queries (use for smaller operations)
-4. **Multiple sequential tool calls** - Each call = multiple API requests (AVOID)
+1. **`roam_update_page_markdown`** - Single call: fetches, diffs, and updates (MOST EFFICIENT for revisions)
+2. **`roam_process_batch_actions`** - Single API call for multiple operations
+3. **`roam_create_page`** - Batches content with page creation
+4. **`roam_create_outline` / `roam_import_markdown`** - Include verification queries (use for smaller operations)
+5. **Multiple sequential tool calls** - Each call = multiple API requests (AVOID)
 
 ### Best Practices for Intensive Operations
 
 #### When Updating/Revising a Page:
-1. Fetch the page content ONCE at the start
-2. Plan ALL changes needed (creates, updates, deletes)
-3. Execute ALL changes in a SINGLE `roam_process_batch_actions` call
-4. Do NOT fetch-modify-fetch-modify in a loop
+1. **Preferred**: Use `roam_update_page_markdown` — it fetches, diffs, and updates in one call
+2. **Alternative** (for fine-grained control): Fetch once with `roam_fetch_page_by_title`, then execute ALL changes in a SINGLE `roam_process_batch_actions` call
+3. Do NOT fetch-modify-fetch-modify in a loop
 
 #### When Creating Large Content:
 - For 10+ blocks: Use `roam_process_batch_actions` with nested structure
@@ -285,6 +298,11 @@ When using `roam_process_batch_actions` to create nested blocks, use **placehold
 
 **Do this:**
 ```
+1. roam_update_page_markdown → single call handles fetch, diff, and updates
+```
+
+**Alternative** (when you need fine-grained control):
+```
 1. roam_fetch_page_by_title → get page UID and content
 2. roam_process_batch_actions → ALL creates/updates in one call
 ```

package/build/cli/batch/resolver.js

@@ -0,0 +1,138 @@
+/**
+ * Resolver for page/block title lookups before batch execution
+ */
+import { q } from '@roam-research/roam-api-sdk';
+import { capitalizeWords } from '../../tools/helpers/text.js';
+import { formatRoamDate } from '../../utils/helpers.js';
+import { pageUidCache } from '../../cache/page-uid-cache.js';
+/**
+ * Resolve a page title to its UID, trying multiple case variations
+ */
+export async function resolvePageUid(graph, title) {
+    // Check cache first
+    const cachedUid = pageUidCache.get(title);
+    if (cachedUid) {
+        return cachedUid;
+    }
+    // Try different case variations
+    const variations = [
+        title,
+        capitalizeWords(title),
+        title.toLowerCase()
+    ];
+    const orClause = variations.map(v => `[?e :node/title "${v}"]`).join(' ');
+    const searchQuery = `[:find ?uid .
+                        :where [?e :block/uid ?uid]
+                               (or ${orClause})]`;
+    const result = await q(graph, searchQuery, []);
+    const uid = (result === null || result === undefined) ? null : String(result);
+    // Cache the result
+    if (uid) {
+        pageUidCache.set(title, uid);
+    }
+    return uid;
+}
+/**
+ * Get today's daily page title in Roam format
+ */
+export function getDailyPageTitle() {
+    return formatRoamDate(new Date());
+}
+/**
+ * Resolve today's daily page UID
+ */
+export async function resolveDailyPageUid(graph) {
+    const dailyTitle = getDailyPageTitle();
+    return resolvePageUid(graph, dailyTitle);
+}
+/**
+ * Collect all unique page titles that need resolution from commands
+ */
+export function collectPageTitles(commands) {
+    const titles = new Set();
+    for (const cmd of commands) {
+        const params = cmd.params;
+        // Commands that can have 'page' param
+        if ('page' in params && typeof params.page === 'string') {
+            titles.add(params.page);
+        }
+        // Remember command can have heading that needs parent page resolution
+        // But heading lookup is handled separately
+        // Todo/remember without explicit page need daily page
+        if (cmd.command === 'todo' || cmd.command === 'remember') {
+            if (!('page' in params) && !('pageUid' in params) && !('parent' in params)) {
+                titles.add(getDailyPageTitle());
+            }
+        }
+    }
+    return titles;
+}
+/**
+ * Check if any commands need daily page resolution
+ */
+export function needsDailyPage(commands) {
+    for (const cmd of commands) {
+        const params = cmd.params;
+        if (cmd.command === 'todo' || cmd.command === 'remember') {
+            if (!('page' in params) && !('pageUid' in params) && !('parent' in params)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Resolve all page titles to UIDs
+ * Returns a map of title -> uid
+ */
+export async function resolveAllPages(graph, titles) {
+    const resolved = new Map();
+    // Resolve in parallel for efficiency
+    const entries = Array.from(titles);
+    const results = await Promise.all(entries.map(async (title) => {
+        const uid = await resolvePageUid(graph, title);
+        return [title, uid];
+    }));
+    for (const [title, uid] of results) {
+        if (uid) {
+            resolved.set(title, uid);
+        }
+    }
+    return resolved;
+}
+/**
+ * Create initial resolution context
+ */
+export function createResolutionContext() {
+    return {
+        pageUids: new Map(),
+        placeholders: new Map(),
+        levelStack: [],
+        currentParent: null,
+        dailyPageUid: null
+    };
+}
+/**
+ * Resolve a parent reference - could be a UID, placeholder, or page title
+ */
+export function resolveParentRef(ref, context) {
+    // Check if it's a placeholder reference {{name}}
+    const placeholderMatch = ref.match(/^\{\{([^}]+)\}\}$/);
+    if (placeholderMatch) {
+        const name = placeholderMatch[1];
+        return context.placeholders.get(name) || `{{uid:${name}}}`;
+    }
+    // Check if it's a resolved page title
+    if (context.pageUids.has(ref)) {
+        return context.pageUids.get(ref);
+    }
+    // Assume it's a direct UID
+    return ref;
+}
+/**
+ * Generate a placeholder UID for tracking
+ * Returns the placeholder in {{uid:name}} format for batch processing
+ */
+export function generatePlaceholder(name) {
+    return `{{uid:${name}}}`;
+}