roam-research-mcp 2.24.0 → 3.0.0

package/README.md

@@ -146,6 +146,24 @@ The MCP server exposes these tools to AI assistants (like Claude), enabling them
 | `roam_markdown_cheatsheet` | Retrieve the Roam-flavored markdown reference. |
 | `roam_get_guidelines` | Retrieve this graph's user-defined agent conventions. |
 
+### Structured results from write tools (v3.0.0+)
+
+The ten write tools declare an `outputSchema` and return `structuredContent` — a validated object — alongside the usual text. A client can read `page_uid`, `uid_map` or `success` directly instead of hunting for JSON inside a string, which makes chaining calls more reliable:
+
+```jsonc
+// roam_process_batch_actions
+{ "success": true, "uid_map": { "parent1": "Xk7mN2pQ9" },
+  "validation_passed": true, "actions_attempted": 4 }
+```
+
+Three things worth knowing:
+
+- **Nothing was taken away.** The text channel is unchanged, so a client that ignores `structuredContent` behaves exactly as before.
+- **Read tools deliberately have neither.** They already serialise their whole result into the text channel, so a schema would just double the payload.
+- **These fields are additive-only.** Some clients validate live responses against a cached tool list, so a field will be added or deprecated — never renamed or removed outside a major version.
+
+> **Upgrading from 2.x:** three write-result fields were renamed — `uid` → `page_uid` (`roam_create_page`), `created_uids` → `created_blocks` (`roam_create_outline`, `roam_import_markdown`) and `preservedUids` → `preserved_uids` (`roam_update_page_markdown`). This only affects code that reads those names; if you use the server through an AI assistant, nothing changes. See the [changelog](CHANGELOG.md) for why.
+
 ---
 
 ## Agent guidelines (per-graph)
@@ -161,22 +179,24 @@ This is distinct from `CUSTOM_INSTRUCTIONS_PATH`, and the two compose:
 | To change it | edit the file, restart the server | edit the page |
 | Answers | how to write Roam markdown | how *this user* wants *this graph* handled |
 
-**Opt-in.** A graph with no `guidelinesPage` and no `ROAM_GUIDELINES_PAGE` fallback has guidelines **disabled** — the tool reports that and never touches the graph. Nothing is read until you name a page, so a graph that happens to contain a similarly-titled page won't start feeding it to agents.
+**Just create the page.** With no configuration at all, `roam_get_guidelines` reads `[[roam/agent guidelines]]` — the same title Roam's own server reads, so writing it once makes both honour it. Creating a page with that exact namespaced title is the opt-in; nothing is read from the graph unless an agent explicitly calls the tool.
+
+If the page doesn't exist, the tool returns `exists: false` rather than failing, so it is always safe to call.
 
-Each graph can point at a different page:
+Each graph can point at a different page, or turn it off:
 
 ```bash
 ROAM_GRAPHS='{
-  "personal": {"token": "...", "graph": "...", "guidelinesPage": "roam/agent guidelines"},
+  "personal": {"token": "...", "graph": "..."},
   "work":     {"token": "...", "graph": "...", "guidelinesPage": "work/agent rules"},
-  "archive":  {"token": "...", "graph": "..."}
+  "private":  {"token": "...", "graph": "...", "guidelinesPage": false}
 }'
-ROAM_GUIDELINES_PAGE='roam/agent guidelines'   # fallback for graphs that name none
+ROAM_GUIDELINES_PAGE='team/agent guidelines'   # change the default for every graph
 ```
 
-Resolution order is **per-graph `guidelinesPage` → `ROAM_GUIDELINES_PAGE` → disabled**. Setting `guidelinesPage: false` disables it for one graph even when the env fallback is set. In the example above, `archive` uses the fallback; without that env var it would be disabled.
+Resolution order is **per-graph `guidelinesPage` → `ROAM_GUIDELINES_PAGE` → `roam/agent guidelines`**. Above: `personal` uses the env override, `work` uses its own page, and `private` has guidelines off entirely. **Only an explicit `false` disables it** — an unset value never does.
 
-If the named page doesn't exist the tool returns `exists: false` rather than failing, so it is safe to call unconditionally. Results are cached for 30 seconds — an edit to the page takes effect without a restart. A starter template lives at [`.roam/agent-guidelines.template.md`](.roam/agent-guidelines.template.md).
+Results are cached for 30 seconds — an edit to the page takes effect without a restart. A starter template lives at [`.roam/agent-guidelines.template.md`](.roam/agent-guidelines.template.md).
 
 Note that guidelines are read through the normal page path, so blocks tagged `#.rm-hide` / `#.rm-private` are withheld from them too — see below.
 
@@ -229,7 +249,7 @@ ROAM_SYSTEM_WRITE_KEY=your-secret-key
 |----------|----------|-------------|
 | `token` | Yes | Roam API token for this graph |
 | `graph` | Yes | Graph name/database identifier |
-| `protected` | No | If `true`, writes require `ROAM_SYSTEM_WRITE_KEY` confirmation |
+| `protected` | No | If `true`, writes require `ROAM_SYSTEM_WRITE_KEY` confirmation — **except on the default graph**, see below |
 | `memoriesTag` | No | Tag for `roam_remember`/`roam_recall` (overrides global default) |
 
 **Two kinds of access control (and how they differ)**
@@ -249,6 +269,8 @@ Think of a house: the **bearer token locks the front door** (keeps strangers out
 
 So: to mark a graph as needing the write key, set `protected: true` on it and configure `ROAM_SYSTEM_WRITE_KEY`; callers then pass a matching `write_key` for any write to that graph.
 
+> ⚠️ **`protected` does nothing on your default graph.** Writes to whichever graph `ROAM_DEFAULT_GRAPH` names are always allowed, before `protected` is ever consulted — the flag guards the graphs you have to *ask* for by name, on the reasoning that reaching for a non-default graph is the deliberate act worth confirming. If you want a graph write-guarded, it must not be your default.
+
 *Optional:*
 - `ROAM_MEMORIES_TAG`: Default tag for `roam_remember`/`roam_recall` (fallback when per-graph `memoriesTag` not set).
 - `HTTP_STREAM_PORT`: Port for the HTTP Stream transport (defaults to 8088).
@@ -348,6 +370,16 @@ docker run -p 8088:8088 --env-file .env roam-research-mcp --server
 
 Add to your MCP settings file (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json`):
 
+> **Pinning the version.** `npx -y roam-research-mcp` fetches the **latest** release every time your client starts the server, so a new major version arrives without warning. Pin the major to decide for yourself when to move:
+>
+> | `args` | You get |
+> | :--- | :--- |
+> | `["-y", "roam-research-mcp"]` | Latest, always — including the next major |
+> | `["-y", "roam-research-mcp@3"]` | 3.x only; majors need an edit here |
+> | `["-y", "roam-research-mcp@3.0.0"]` | Exactly this build |
+>
+> Pinning the major is the sensible default: you still get fixes and new tools, but a breaking change becomes something you opt into. The examples below stay unpinned to match what most people paste in first.
+
 *Single Graph:*
 ```json
 {

package/build/cli/commands/batch.js

@@ -247,10 +247,10 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                     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 (result.success && result.page_uid) {
+                            context.pageUids.set(title, result.page_uid);
                             if (options.debug) {
-                                printDebug(`Auto-created "${title}"`, result.uid);
+                                printDebug(`Auto-created "${title}"`, result.page_uid);
                             }
                         }
                         else {
@@ -313,12 +313,12 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                         // Report partial results before exiting
                         outputPartialResults(pageResults, pc.params.title);
                     }
-                    pageResults.push({ title: pc.params.title, uid: result.uid });
+                    pageResults.push({ title: pc.params.title, uid: result.page_uid });
                     if (pc.params.as) {
-                        context.placeholders.set(pc.params.as, result.uid);
+                        context.placeholders.set(pc.params.as, result.page_uid);
                     }
                     if (options.debug) {
-                        printDebug(`Created "${pc.params.title}"`, result.uid);
+                        printDebug(`Created "${pc.params.title}"`, result.page_uid);
                     }
                 }
             }

package/build/cli/commands/save.js

@@ -430,8 +430,8 @@ JSON format (--json):
                     if (result.success) {
                         console.log(`Updated page '${pageTitle}'`);
                         console.log(`  ${result.summary}`);
-                        if (result.preservedUids.length > 0) {
-                            console.log(`  Preserved ${result.preservedUids.length} block UID(s)`);
+                        if (result.preserved_uids.length > 0) {
+                            console.log(`  Preserved ${result.preserved_uids.length} block UID(s)`);
                         }
                     }
                     else {
@@ -441,7 +441,7 @@ JSON format (--json):
                 else {
                     const result = await pageOps.createPage(pageTitle, contentBlocks);
                     if (result.success) {
-                        console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
+                        console.log(`Created page '${pageTitle}' (uid: ${result.page_uid})`);
                     }
                     else {
                         exitWithError(`Failed to create page '${pageTitle}'`);

package/build/config/graph-registry.js

@@ -9,6 +9,7 @@
  */
 import { initializeGraph } from '@roam-research/roam-api-sdk';
 import { RoamError } from '../shared/errors.js';
+import { DEFAULT_GUIDELINES_PAGE } from '../tools/operations/guidelines.js';
 /** List of tool names that perform write operations */
 export const WRITE_OPERATIONS = [
     'roam_create_page',
@@ -70,15 +71,21 @@ export class GraphRegistry {
         return config?.memoriesTag ?? process.env.ROAM_MEMORIES_TAG ?? 'Memories';
     }
     /**
-     * Page holding a graph's agent conventions, or null when disabled.
+     * Page holding a graph's agent conventions, or null when explicitly disabled.
      *
-     * Precedence: per-graph config > ROAM_GUIDELINES_PAGE env var > **disabled**.
+     * Precedence: per-graph config > ROAM_GUIDELINES_PAGE env var >
+     * "roam/agent guidelines" (the shared convention).
      *
-     * Unlike memoriesTag this is opt-in: a graph with no `guidelinesPage` and no
-     * env fallback returns null rather than silently reading a conventional page
-     * title. Reading a page nobody asked us to read is a surprise, and a graph
-     * that happens to contain a similarly-named page should not start feeding it
-     * to agents.
+     * Reading the conventional title by default is deliberate. It is the same
+     * page Roam's own MCP server reads unconditionally, so writing it once makes
+     * both servers honour it — which is the entire point of a convention, and it
+     * stops working the moment it needs private configuration. Creating a page
+     * with that exact namespaced title IS the opt-in; nobody makes one by
+     * accident. And nothing here reads the graph unprompted: the lookup only
+     * happens when an agent explicitly calls roam_get_guidelines, so the tool
+     * call is already the consent.
+     *
+     * Set `guidelinesPage: false` to turn it off for a graph.
      */
     getGuidelinesPage(key) {
         const resolvedKey = key ?? this.defaultKey;
@@ -86,7 +93,7 @@ export class GraphRegistry {
         if (config?.guidelinesPage === false) {
             return null;
         }
-        return config?.guidelinesPage ?? process.env.ROAM_GUIDELINES_PAGE ?? null;
+        return config?.guidelinesPage ?? process.env.ROAM_GUIDELINES_PAGE ?? DEFAULT_GUIDELINES_PAGE;
     }
     /**
      * Get an initialized Graph instance, creating it lazily if needed

package/build/server/roam-server.js

@@ -20,6 +20,29 @@ const __dirname = dirname(__filename);
 const packageJsonPath = join(__dirname, '../../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 const serverVersion = packageJson.version;
+/**
+ * The single place a tool result is built, and the only place
+ * `structuredContent` may be attached.
+ *
+ * The wire invariant is **`structuredContent` is present iff the tool declares
+ * an `outputSchema`**. A schema-bearing tool that returns none, or a
+ * schema-less tool that returns some, is a protocol violation a strict client
+ * will reject. We use the low-level `Server` rather than `McpServer`, so the
+ * SDK does not enforce this for us — routing every result through here is what
+ * enforces it. Adding a schema in schemas.ts is therefore sufficient; no switch
+ * case needs touching.
+ *
+ * The text channel is unchanged either way, so clients that never look at
+ * structuredContent see exactly what they saw before.
+ */
+function toolResult(toolName, result) {
+    const declaresSchema = Boolean(toolSchemas[toolName]?.outputSchema);
+    const canStructure = declaresSchema && result !== null && typeof result === 'object';
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        ...(canStructure ? { structuredContent: result } : {}),
+    };
+}
 export class RoamServer {
     constructor() {
         this.toolHandlersCache = new Map();
@@ -126,9 +149,7 @@ export class RoamServer {
                     case 'roam_remember': {
                         const { memory, categories, heading, parent_uid, include_memories_tag } = cleanedArgs;
                         const result = await toolHandlers.remember(memory, categories, heading, parent_uid, include_memories_tag);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_fetch_page_full_view': {
                         const { title, children_depth, max_references } = cleanedArgs;
@@ -146,9 +167,7 @@ export class RoamServer {
                     }
                     case 'roam_get_guidelines': {
                         const result = await toolHandlers.getGuidelines();
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_fetch_page_by_title': {
                         const { title, format } = cleanedArgs;
@@ -160,30 +179,22 @@ export class RoamServer {
                     case 'roam_create_page': {
                         const { title, content } = cleanedArgs;
                         const result = await toolHandlers.createPage(title, content);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_import_markdown': {
                         const { content, page_uid, page_title, parent_uid, parent_string, order = 'first' } = cleanedArgs;
                         const result = await toolHandlers.importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_add_todo': {
                         const { todos } = cleanedArgs;
                         const result = await toolHandlers.addTodos(todos);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_create_outline': {
                         const { outline, page_title_uid, block_text_uid, order } = cleanedArgs;
                         const result = await toolHandlers.createOutline(outline, page_title_uid, block_text_uid, order);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_for_tag': {
                         const { primary_tag, page_title_uid, near_tag } = cleanedArgs;
@@ -191,23 +202,17 @@ export class RoamServer {
                             throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: primary_tag (the tag to search for). Use page_title_uid to limit search to a specific page.');
                         }
                         const result = await toolHandlers.searchForTag(primary_tag, page_title_uid, near_tag);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_by_status': {
                         const { status, page_title_uid, include, exclude } = cleanedArgs;
                         const result = await toolHandlers.searchByStatus(status, page_title_uid, include, exclude);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_block_refs': {
                         const params = cleanedArgs;
                         const result = await toolHandlers.searchBlockRefs(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_hierarchy': {
                         const params = cleanedArgs;
@@ -216,58 +221,42 @@ export class RoamServer {
                             throw new McpError(ErrorCode.InvalidRequest, 'Either parent_uid or child_uid must be provided, but not both');
                         }
                         const result = await toolHandlers.searchHierarchy(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_find_pages_modified_today': {
                         const { max_num_pages } = cleanedArgs;
                         const result = await toolHandlers.findPagesModifiedToday(max_num_pages || 50);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_by_text': {
                         const params = cleanedArgs;
                         const result = await toolHandlers.searchByText(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_by_date': {
                         const params = cleanedArgs;
                         const result = await toolHandlers.searchByDate(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_recall': {
                         const { sort_by = 'newest', filter_tag } = cleanedArgs;
                         const result = await toolHandlers.recall(sort_by, filter_tag);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_datomic_query': {
                         const { query, inputs } = cleanedArgs;
                         const result = await toolHandlers.executeDatomicQuery({ query, inputs });
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_process_batch_actions': {
                         const { actions } = cleanedArgs;
                         const result = await toolHandlers.processBatch(actions);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_fetch_block': {
                         const { block_uid, depth, include_ancestors } = cleanedArgs;
                         const result = await toolHandlers.fetchBlock(block_uid, depth, include_ancestors);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_create_table': {
                         const { parent_uid, order, headers, rows } = cleanedArgs;
@@ -277,30 +266,22 @@ export class RoamServer {
                             headers,
                             rows
                         });
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_move_block': {
                         const { block_uid, parent_uid, order = 'last' } = cleanedArgs;
                         const result = await toolHandlers.moveBlock(block_uid, parent_uid, order);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_update_page_markdown': {
                         const { title, markdown, dry_run = false } = cleanedArgs;
                         const result = await toolHandlers.updatePageMarkdown(title, markdown, dry_run);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_rename_page': {
                         const { old_title, uid, new_title } = cleanedArgs;
                         const result = await toolHandlers.renamePage({ old_title, uid, new_title });
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);

package/build/tools/operations/batch.js

@@ -3,6 +3,7 @@ import { generateBlockUid, parseMarkdownHeadingLevel } from '../../markdown-util
 import { validateBatchActions, formatValidationErrors } from '../../shared/validation.js';
 import { isRateLimitError, createRateLimitError } from '../../shared/errors.js';
 import { ensurePagesExist } from '../../shared/page-validator.js';
+import { withRateLimitRetry } from '../../shared/retry.js';
 // Regex to match UID placeholders like {{uid:parent1}}, {{uid:section-a}}, etc.
 const UID_PLACEHOLDER_REGEX = /\{\{uid:([^}]+)\}\}/g;
 const DEFAULT_RATE_LIMIT_CONFIG = {
@@ -69,36 +70,22 @@ export class BatchOperations {
         return obj;
     }
     /**
-     * Executes the batch operation with retry logic for rate limiting.
+     * Executes the batch operation, retrying while Roam throttles us.
+     *
+     * This used to be a hand-rolled loop identical to the one in
+     * `withRateLimitRetry`, which is precisely how `executeStagedBatch` came to
+     * be written with no retry at all — the logic was private here, so the next
+     * write path could not reuse it and simply went without. A half-written page
+     * and no undo was the cost.
+     *
+     * On exhaustion the shared helper rethrows Roam's original error rather than
+     * a synthesised one carrying `retryAfterMs`. `processBatch` never used that
+     * field's value for anything the caller saw except the backoff hint, which
+     * now comes from this instance's own config — a more honest source than
+     * whatever happened to be stapled to an error object.
      */
     async executeWithRetry(batchActions) {
-        let lastError;
-        let delay = this.rateLimitConfig.initialDelayMs;
-        for (let attempt = 0; attempt <= this.rateLimitConfig.maxRetries; attempt++) {
-            try {
-                await roamBatchActions(this.graph, { actions: batchActions });
-                return;
-            }
-            catch (error) {
-                if (!isRateLimitError(error)) {
-                    throw error;
-                }
-                lastError = error;
-                if (attempt < this.rateLimitConfig.maxRetries) {
-                    const waitTime = Math.min(delay, this.rateLimitConfig.maxDelayMs);
-                    console.log(`[batch] Rate limited, retrying in ${waitTime}ms (attempt ${attempt + 1}/${this.rateLimitConfig.maxRetries})`);
-                    await sleep(waitTime);
-                    delay *= this.rateLimitConfig.backoffMultiplier;
-                }
-            }
-        }
-        // Throw with rate limit context after all retries exhausted
-        const rateLimitError = new Error(`Rate limit exceeded after ${this.rateLimitConfig.maxRetries} retries. ` +
-            `Last error: ${lastError?.message || 'Unknown error'}. ` +
-            `Retry after ${this.rateLimitConfig.maxDelayMs}ms.`);
-        rateLimitError.isRateLimit = true;
-        rateLimitError.retryAfterMs = this.rateLimitConfig.maxDelayMs;
-        throw rateLimitError;
+        await withRateLimitRetry(() => roamBatchActions(this.graph, { actions: batchActions }), this.rateLimitConfig, (attempt, waitMs) => console.log(`[batch] Rate limited, retrying in ${waitMs}ms (attempt ${attempt}/${this.rateLimitConfig.maxRetries})`));
     }
     async processBatch(actions) {
         // Step 0: Pre-validate all actions before any execution
@@ -244,10 +231,10 @@ export class BatchOperations {
                 }
             }
             // Check if it's a rate limit error
-            if (isRateLimitError(error) || error.isRateLimit) {
+            if (isRateLimitError(error)) {
                 return {
                     success: false,
-                    error: createRateLimitError(error.retryAfterMs),
+                    error: createRateLimitError(this.rateLimitConfig.maxDelayMs),
                     validation_passed: true,
                     actions_attempted: batchActions.length
                     // No uid_map - nothing was committed

package/build/tools/operations/guidelines.js

@@ -10,14 +10,11 @@
  * server's mechanics and lives in a file. Guidelines are per-graph, live-edited
  * from inside Roam, and answer "how does this user want their graph handled".
  *
- * Opt-in: a graph must name its page via `guidelinesPage` or ROAM_GUIDELINES_PAGE.
- * With neither set the tool reports disabled and never touches the graph.
+ * Read by default; set `guidelinesPage: false` on a graph to disable it there.
  */
 import { PageOperations } from './pages.js';
 import { formatRoamDate } from '../../utils/helpers.js';
-/** The conventional page title, matching Roam's own server. Not applied
- * automatically — a graph must opt in via `guidelinesPage` or
- * ROAM_GUIDELINES_PAGE. */
+/** The shared convention, read by default and by Roam's own MCP server. */
 export const DEFAULT_GUIDELINES_PAGE = 'roam/agent guidelines';
 /**
  * Short TTL: the point of a page over a config file is that an edit takes
@@ -30,7 +27,7 @@ export class GuidelinesOperations {
     /**
      * @param guidelinesPage Page title to read, or null when disabled for this graph.
      */
-    constructor(graph, guidelinesPage = null) {
+    constructor(graph, guidelinesPage = DEFAULT_GUIDELINES_PAGE) {
         this.graph = graph;
         this.guidelinesPage = guidelinesPage;
         this.pageOps = new PageOperations(graph);

package/build/tools/operations/outline.js

@@ -313,7 +313,7 @@ export class OutlineOperations {
             success: true,
             page_uid: targetPageUid,
             parent_uid: targetParentUid,
-            created_uids: createdBlocks
+            created_blocks: createdBlocks
         };
     }
     async importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order = 'last') {
@@ -377,7 +377,7 @@ export class OutlineOperations {
             // Roam's write API does not echo back transacted UIDs, so we report the
             // UIDs we generated client-side rather than issuing a fragile post-write
             // re-query (which was also skipped entirely past VERIFICATION_THRESHOLD,
-            // leaving created_uids empty for larger imports).
+            // leaving created_blocks empty for larger imports).
             const { actions, blocks } = convertToRoamActionsWithBlocks(nodes, targetParentUid, order);
             // Execute batch actions to add content
             await executeBatch(this.graph, actions, 'import nested markdown content');
@@ -385,7 +385,7 @@ export class OutlineOperations {
                 success: true,
                 page_uid: targetPageUid,
                 parent_uid: targetParentUid,
-                created_uids: blockInfoToNestedBlocks(blocks)
+                created_blocks: blockInfoToNestedBlocks(blocks)
             };
         }
         else {
@@ -399,11 +399,11 @@ export class OutlineOperations {
                     block: { string: content }
                 }], 'create content block');
             // For single-line content, we still need to fetch the UID and construct a NestedBlock
-            const createdUids = [];
+            const createdBlocks = [];
             try {
                 const foundUid = await this.findBlockWithRetry(targetParentUid, content);
                 if (foundUid) {
-                    createdUids.push({
+                    createdBlocks.push({
                         uid: foundUid,
                         text: content,
                         level: 0,
@@ -420,7 +420,7 @@ export class OutlineOperations {
                 success: true,
                 page_uid: targetPageUid,
                 parent_uid: targetParentUid,
-                created_uids: createdUids
+                created_blocks: createdBlocks
             };
         }
     }

package/build/tools/operations/pages.js

@@ -155,7 +155,7 @@ export class PageOperations {
                 if (existingBlockCount && existingBlockCount > 0) {
                     // Page already has content - this might be a duplicate call
                     // Return success without adding duplicate content
-                    return { success: true, uid: pageUid };
+                    return { success: true, page_uid: pageUid };
                 }
                 // Process content items in order, tracking position for correct placement
                 // Tables and text blocks are interleaved at their original positions
@@ -323,7 +323,7 @@ export class PageOperations {
                 location: { 'parent-uid': pageUid, order: 'last' },
                 block: { string: `Processed: [[${formattedTodayTitle}]]` }
             }], 'add Processed block');
-        return { success: true, uid: pageUid };
+        return { success: true, page_uid: pageUid };
     }
     /**
      * Get the UID for a page by its title.
@@ -647,7 +647,7 @@ export class PageOperations {
             success: true,
             actions,
             stats,
-            preservedUids: [...diff.preservedUids],
+            preserved_uids: [...diff.preservedUids],
             summary: dryRun ? `[DRY RUN] ${summary}` : summary
         };
     }