roam-research-mcp 2.22.0 → 2.24.0

package/README.md

@@ -18,6 +18,34 @@ What started as an backend for AI agents evolved into a full-featured **Standalo
 
 Whether you want to give Claude superpowers over your knowledge base or just want a robust CLI for your own scripts, this project has you covered.
 
+![Before and after: copy-pasting notes into Roam by hand, versus Claude and your terminal reading and writing the graph directly — install with npm i -g roam-research-mcp, then `roam save "idea"` or pipe with `echo "Buy milk" | roam save --todo`](./roam-research-mcp-sketchnote.png)
+
+## How this differs from Roam's official MCP server
+
+Roam Research ships its own MCP server and CLI ([`@roam-research/roam-mcp`](https://github.com/Roam-Research/roam-tools)). It is a good tool, and this project is not trying to replace it. **They talk to two different Roam APIs, which is the difference everything else follows from.**
+
+|                    | **This project**                                                       | **Official `@roam-research/roam-mcp`**                          |
+| ------------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Talks to           | Roam's **backend REST API** (graph token + graph name)                 | Roam **Desktop's local HTTP API**                                |
+| Needs Roam running | No — works headless                                                    | Yes, the desktop app must be open (it deep-links to launch it)   |
+| Where it can run   | Anywhere: laptop, server, container, CI                                | The machine running Roam Desktop                                 |
+| Shared daemon      | Yes — `roam server` runs one HTTP daemon for every client              | Per-client stdio                                                 |
+| Multi-graph        | `ROAM_GRAPHS` env var, with `write_key` protection for chosen graphs   | `~/.roam-tools.json`, one token per graph                        |
+| Web-only graphs    | Works                                                                  | Desktop only                                                     |
+
+**Reach for the official server when** you want Roam's own supported path, or you need things only the running app can do: controlling the Desktop UI (open a page, read the current selection, drive the sidebar), semantic/embeddings search, link suggestions, file upload, comments, or invoking tools that Roam extensions register.
+
+**Reach for this one when** Roam isn't running or isn't installed — a server, a container, a cron job, a CI step. Or when you want the extras this project has grown: a full standalone CLI with stdin piping, a shared HTTP daemon with optional bearer auth, smart page diffing that preserves block UIDs (and therefore your block references), batch operations with UID placeholders for building nested structures in one call, and agent memory tools.
+
+One deliberate omission: **there is no page-delete tool here.** Roam has no undo that can reverse a bulk API deletion. The official server does offer `delete_page`; this project takes the more conservative line.
+
+### They interoperate
+
+The two servers share conventions on purpose, so running both costs you nothing:
+
+- **`[[roam/agent guidelines]]`** — both read the same page for your conventions. Write them once; both honour them. See [Agent guidelines](#agent-guidelines-per-graph).
+- **`#.rm-hide` / `#.rm-private`** — both withhold tagged blocks from AI-facing content. Tag once, hidden from both. See [Hiding content from the AI](#hiding-content-from-the-ai).
+
 ## Standalone CLI: `roam`
 
 The `roam` CLI lets you interact with your graph directly from the terminal. It supports **standard input (stdin) piping** for all content creation and retrieval commands, making it perfect for automation workflows.
@@ -116,6 +144,55 @@ The MCP server exposes these tools to AI assistants (like Claude), enabling them
 | `roam_remember` / `roam_recall` | specialized tools for AI memory management within Roam. |
 | `roam_datomic_query` | Execute raw Datalog queries for advanced filtering. |
 | `roam_markdown_cheatsheet` | Retrieve the Roam-flavored markdown reference. |
+| `roam_get_guidelines` | Retrieve this graph's user-defined agent conventions. |
+
+---
+
+## Agent guidelines (per-graph)
+
+`roam_get_guidelines` reads a page **inside the graph** — `[[roam/agent guidelines]]` by default — holding your own conventions: how you tag, how you namespace pages, what an agent should never do. Roam's official MCP server reads the same page title, so one page serves both.
+
+This is distinct from `CUSTOM_INSTRUCTIONS_PATH`, and the two compose:
+
+| | `CUSTOM_INSTRUCTIONS_PATH` | `[[roam/agent guidelines]]` |
+|---|---|---|
+| Lives in | a file on disk | a page in the graph |
+| Scope | server-wide, all graphs | **per-graph** |
+| 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.
+
+Each graph can point at a different page:
+
+```bash
+ROAM_GRAPHS='{
+  "personal": {"token": "...", "graph": "...", "guidelinesPage": "roam/agent guidelines"},
+  "work":     {"token": "...", "graph": "...", "guidelinesPage": "work/agent rules"},
+  "archive":  {"token": "...", "graph": "..."}
+}'
+ROAM_GUIDELINES_PAGE='roam/agent guidelines'   # fallback for graphs that name none
+```
+
+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.
+
+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).
+
+Note that guidelines are read through the normal page path, so blocks tagged `#.rm-hide` / `#.rm-private` are withheld from them too — see below.
+
+---
+
+## Hiding content from the AI
+
+Blocks tagged `#.rm-hide` or `#.rm-private` — and everything nested under them — are omitted from the content these tools return. Both the hashtag (`#.rm-hide`, `#[[.rm-hide]]`) and link (`[[.rm-hide]]`) forms work. `.rm-private` is Roam's existing "hidden from other users" tag; `.rm-hide` hides from the AI specifically.
+
+This follows the same convention as Roam's official MCP server, so a block tagged for one is hidden from the other.
+
+Applied to: `roam_fetch_page_by_title`, `roam_fetch_block`, `roam_fetch_page_full_view`, `roam_get_subpages`, `roam_search_by_text`, `roam_search_for_tag`, `roam_search_by_status`, `roam_search_block_refs`, `roam_search_hierarchy`, `roam_search_by_date`.
+
+**This is a convenience filter, not a security guarantee.** `roam_datomic_query` reads the database directly and deliberately does **not** apply it, so a capable agent can still surface hidden blocks through raw Datalog. Treat these tags as "keep it out of the AI's way," not "keep it secret."
+
+Tag matching is case-insensitive, and only exact tags match — `#.rm-hidden` and `#.rm-highlight` are left alone. The set of hidden UIDs is cached for 30 seconds, so a block tagged just now may remain visible for up to that long.
 
 ---
 
@@ -155,14 +232,28 @@ ROAM_SYSTEM_WRITE_KEY=your-secret-key
 | `protected` | No | If `true`, writes require `ROAM_SYSTEM_WRITE_KEY` confirmation |
 | `memoriesTag` | No | Tag for `roam_remember`/`roam_recall` (overrides global default) |
 
-**Write Protection:**
-Protected graphs require the `write_key` parameter matching `ROAM_SYSTEM_WRITE_KEY` for any write operation. This prevents accidental writes to sensitive graphs.
+**Two kinds of access control (and how they differ)**
+
+The server has two independent locks. They're easy to mix up because both are "keys" — here's the plain version (both are **optional and off by default**):
+
+| | **Bearer token** — `HTTP_AUTH_TOKEN` | **Write key** — `ROAM_SYSTEM_WRITE_KEY` |
+|---|---|---|
+| In a phrase | The key to the **front door** | The latch on a **safe inside** |
+| Controls | *Who can reach the server at all* | *Whether a write to a `protected` graph is allowed* |
+| Covers | Everything — reads **and** writes, all graphs | Only **writes**, and only to graphs marked `protected` |
+| Protects reading? | **Yes** | **No** |
+| When you need it | Only if the server is reachable beyond your own machine (e.g. `-H 0.0.0.0`) | Whenever you want a guard against accidental edits to important graphs |
+| How it's sent | HTTP header: `Authorization: Bearer <token>` | A `write_key` argument on write tools / CLI commands |
+
+Think of a house: the **bearer token locks the front door** (keeps strangers out entirely), and the **write key locks a safe inside** (even someone already in the house needs it to change what's in the safe). On your own machine bound to `127.0.0.1`, the front door faces a wall — you don't need the bearer token there. The write key is still handy locally as an "are you sure?" guard, because **Roam has no undo**.
+
+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.
 
 *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).
 - `HTTP_STREAM_HOST`: Host to bind the HTTP transport to in `--server` mode (defaults to `127.0.0.1`, loopback-only). Set to `0.0.0.0` to expose on the LAN.
-- `HTTP_AUTH_TOKEN`: Optional bearer token for the HTTP MCP endpoint (**authentication**). Unset = open (fine for loopback). When set, every HTTP MCP request must send `Authorization: Bearer <token>` (`GET /health` stays open). Use it whenever you bind beyond `127.0.0.1`. This is separate from `ROAM_SYSTEM_WRITE_KEY` (per-graph write authorization).
+- `HTTP_AUTH_TOKEN`: Optional bearer token that locks the **whole** HTTP endpoint. Unset = open (fine for loopback). When set, every MCP request must send `Authorization: Bearer <token>` (`GET /health` stays open). Use it whenever you bind beyond `127.0.0.1`. Different from `ROAM_SYSTEM_WRITE_KEY` — see [Two kinds of access control](#two-kinds-of-access-control-and-how-they-differ).
 
 ### Running the Server
 
@@ -233,11 +324,9 @@ Clients then send the token as a header:
 }
 ```
 
-These are two **distinct** layers — keep both:
-- **`HTTP_AUTH_TOKEN`** = *authentication* (who may connect). Gates **all** requests — reads and writes, every graph.
-- **`ROAM_SYSTEM_WRITE_KEY`** = *authorization* (what a connected caller may do). Gates only **writes** to `protected` graphs; it does **not** protect reads.
+Keep **both** — they do different jobs (see [Two kinds of access control](#two-kinds-of-access-control-and-how-they-differ) above): the bearer token controls **who can connect**, the write key only guards **writes to protected graphs**.
 
-> ⚠️ `write_key` is **not** transport auth. On an exposed server without `HTTP_AUTH_TOKEN`, anyone on the network can still **read every graph** and write non-protected graphs. For anything beyond loopback, set `HTTP_AUTH_TOKEN`.
+> ⚠️ The write key is **not** a substitute for the bearer token. On an exposed server without `HTTP_AUTH_TOKEN`, anyone on the network can still **read every graph** (and write non-protected ones). For anything beyond loopback, set `HTTP_AUTH_TOKEN`.
 
 **Keeping it running (macOS LaunchAgent):**
 Create `~/Library/LaunchAgents/com.example.roam-mcp.plist` with `RunAtLoad` + `KeepAlive`, your env vars under `EnvironmentVariables`, and `--server` as the last `ProgramArguments` entry. Keep `StandardOutPath`/`StandardErrorPath` on a **local** path (e.g. `~/Library/Logs/`), then:

package/build/Roam_Markdown_Cheatsheet.md

@@ -23,6 +23,7 @@
 
 ⚠️ Never concatenate: `#knowledgemanagement` ≠ `#[[knowledge management]]`
 ⚠️ `#` always creates tags — write `Step 1` not `#1`
+⚠️ Because `#` creates tags, a bare `#N` silently creates a numbered page. When you must show the literal form, put it in quotes: `"#1"`, `"#2"` — otherwise rephrase (`Step 1`, `No. 1`, `item 1`)
 
 ### Dates
 Always ordinal format: `[[January 1st, 2025]]`, `[[December 23rd, 2024]]`
@@ -161,7 +162,7 @@ Theme via CSS: `:root { --mermaidjs-theme: dark; }` (in `roam/css`)
 | ❌ Wrong | ✅ Correct |
 |----------|-----------|
 | `#multiplewords` | `#[[multiple words]]` |
-| `#1`, `#2` | `Step 1`, `No. 1` |
+| `#1`, `#2` | `Step 1`, `No. 1`, or quoted: `"#1"` |
 | `[[january 1, 2025]]` | `[[January 1st, 2025]]` |
 | `[text](((uid)))` | `[text](<((uid))>)` |
 | `{{embed: ((uid))}}` | `{{[[embed]]: ((uid))}}` |
@@ -243,6 +244,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.
@@ -251,199 +254,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/utils/graph.js

@@ -33,8 +33,10 @@ export function resolveGraph(options, isWriteOp = false) {
                 if (!systemWriteKey) {
                     throw new Error(`Write to protected graph "${graphKey}" failed: ROAM_SYSTEM_WRITE_KEY not configured.`);
                 }
-                throw new Error(`Write to "${graphKey}" graph requires --write-key confirmation.\n` +
-                    `Use: --write-key "${systemWriteKey}"`);
+                // Never echo the key itself — CLI output lands in scrollback, logs and
+                // transcripts. Name the variable so the shell can expand it instead.
+                throw new Error(`Write to protected graph "${graphKey}" requires --write-key confirmation.\n` +
+                    `Use: --write-key "$ROAM_SYSTEM_WRITE_KEY"`);
             }
         }
     }

package/build/config/graph-registry.js

@@ -8,7 +8,7 @@
  * - Lazy graph initialization (connects only when first accessed)
  */
 import { initializeGraph } from '@roam-research/roam-api-sdk';
-import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { RoamError } from '../shared/errors.js';
 /** List of tool names that perform write operations */
 export const WRITE_OPERATIONS = [
     'roam_create_page',
@@ -69,6 +69,25 @@ export class GraphRegistry {
         // Priority: per-graph config > env var > default
         return config?.memoriesTag ?? process.env.ROAM_MEMORIES_TAG ?? 'Memories';
     }
+    /**
+     * Page holding a graph's agent conventions, or null when disabled.
+     *
+     * Precedence: per-graph config > ROAM_GUIDELINES_PAGE env var > **disabled**.
+     *
+     * 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.
+     */
+    getGuidelinesPage(key) {
+        const resolvedKey = key ?? this.defaultKey;
+        const config = this.configs.get(resolvedKey);
+        if (config?.guidelinesPage === false) {
+            return null;
+        }
+        return config?.guidelinesPage ?? process.env.ROAM_GUIDELINES_PAGE ?? null;
+    }
     /**
      * Get an initialized Graph instance, creating it lazily if needed
      * @param key - Graph key from config. Defaults to defaultKey if not specified.
@@ -83,7 +102,7 @@ export class GraphRegistry {
         // Get config
         const config = this.configs.get(resolvedKey);
         if (!config) {
-            throw new McpError(ErrorCode.InvalidParams, `Unknown graph: "${resolvedKey}". Available graphs: ${this.getAvailableGraphs().join(', ')}`);
+            throw new RoamError(`Unknown graph: "${resolvedKey}".`, 'UNKNOWN_GRAPH', { requested_graph: resolvedKey, available_graphs: this.getAvailableGraphs() });
         }
         // Initialize the graph
         const graph = initializeGraph({
@@ -131,15 +150,19 @@ export class GraphRegistry {
         if (!this.isWriteAllowed(resolvedKey, providedWriteKey)) {
             const config = this.configs.get(resolvedKey);
             if (!config) {
-                throw new McpError(ErrorCode.InvalidParams, `Unknown graph: "${resolvedKey}". Available graphs: ${this.getAvailableGraphs().join(', ')}`);
+                throw new RoamError(`Unknown graph: "${resolvedKey}".`, 'UNKNOWN_GRAPH', { requested_graph: resolvedKey, available_graphs: this.getAvailableGraphs() });
             }
             const systemWriteKey = process.env.ROAM_SYSTEM_WRITE_KEY;
             if (!systemWriteKey) {
-                throw new McpError(ErrorCode.InvalidParams, `Write to protected graph "${resolvedKey}" failed: ROAM_SYSTEM_WRITE_KEY not configured.`);
+                throw new RoamError(`Write to protected graph "${resolvedKey}" failed: ROAM_SYSTEM_WRITE_KEY is not configured on the server.`, 'WRITE_KEY_NOT_CONFIGURED', { graph: resolvedKey });
             }
-            // Provide informative error with the required key
-            throw new McpError(ErrorCode.InvalidParams, `Write to "${resolvedKey}" graph requires write_key confirmation.\n` +
-                `Provide write_key: "${systemWriteKey}" to proceed.`);
+            // Say what is required, never what the value is. Echoing the key here
+            // hands the caller the means to retry and get through, which makes the
+            // whole gate decorative — including for a caller that simply guessed
+            // wrong. A legitimate operator can read ROAM_SYSTEM_WRITE_KEY from their
+            // own environment; an agent that cannot is exactly who this stops.
+            throw new RoamError(`Write to protected graph "${resolvedKey}" requires write_key confirmation. ` +
+                `Pass the value of the ROAM_SYSTEM_WRITE_KEY environment variable as the write_key parameter.`, 'WRITE_KEY_REQUIRED', { graph: resolvedKey, required_parameter: 'write_key' });
         }
     }
     /**

package/build/config/graph-registry.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { GraphRegistry } from './graph-registry.js';
 describe('GraphRegistry', () => {
     describe('getMemoriesTag', () => {
@@ -65,3 +65,94 @@ describe('GraphRegistry', () => {
         });
     });
 });
+describe('getGuidelinesPage', () => {
+    const make = (configs, def = 'personal') => new GraphRegistry(configs, def);
+    it('is disabled when a graph configures nothing — opt-in, not opt-out', () => {
+        delete process.env.ROAM_GUIDELINES_PAGE;
+        const r = make({ personal: { token: 't', graph: 'g' } });
+        expect(r.getGuidelinesPage('personal')).toBeNull();
+    });
+    it('prefers per-graph config over the env var', () => {
+        process.env.ROAM_GUIDELINES_PAGE = 'env/page';
+        const r = make({ work: { token: 't', graph: 'g', guidelinesPage: 'work/rules' } }, 'work');
+        expect(r.getGuidelinesPage('work')).toBe('work/rules');
+        delete process.env.ROAM_GUIDELINES_PAGE;
+    });
+    it('falls back to the env var when a graph sets nothing', () => {
+        process.env.ROAM_GUIDELINES_PAGE = 'env/page';
+        const r = make({ personal: { token: 't', graph: 'g' } });
+        expect(r.getGuidelinesPage('personal')).toBe('env/page');
+        delete process.env.ROAM_GUIDELINES_PAGE;
+    });
+    it('returns null when a graph disables guidelines', () => {
+        const r = make({ personal: { token: 't', graph: 'g', guidelinesPage: false } });
+        expect(r.getGuidelinesPage('personal')).toBeNull();
+    });
+    it('resolves the default graph when no key is given', () => {
+        delete process.env.ROAM_GUIDELINES_PAGE;
+        const r = make({ personal: { token: 't', graph: 'g', guidelinesPage: 'p/rules' } });
+        expect(r.getGuidelinesPage()).toBe('p/rules');
+    });
+});
+describe('write-key denial does not disclose the key', () => {
+    /**
+     * The write key is the whole gate on protected graphs. An error that tells
+     * the caller what the key is hands the agent the means to retry and get
+     * through — the protection becomes decorative.
+     */
+    const SECRET = 'super-secret-write-key';
+    const original = process.env.ROAM_SYSTEM_WRITE_KEY;
+    beforeEach(() => {
+        process.env.ROAM_SYSTEM_WRITE_KEY = SECRET;
+    });
+    afterEach(() => {
+        if (original !== undefined)
+            process.env.ROAM_SYSTEM_WRITE_KEY = original;
+        else
+            delete process.env.ROAM_SYSTEM_WRITE_KEY;
+    });
+    // 'work' must be NON-default: writes to the default graph bypass protection
+    // by design, so a protected default graph never reaches the denial path.
+    const protectedRegistry = () => new GraphRegistry({
+        personal: { token: 't', graph: 'p' },
+        work: { token: 't', graph: 'g', protected: true },
+    }, 'personal');
+    it('never puts the key in the denial message', () => {
+        let message = '';
+        try {
+            protectedRegistry().validateWriteAccess('roam_create_page', 'work', undefined);
+        }
+        catch (e) {
+            message = e.message;
+        }
+        expect(message, 'denial message must not be empty').not.toBe('');
+        expect(message).not.toContain(SECRET);
+    });
+    it('never discloses the key when a wrong one is supplied', () => {
+        let message = '';
+        try {
+            protectedRegistry().validateWriteAccess('roam_create_page', 'work', 'wrong-guess');
+        }
+        catch (e) {
+            message = e.message;
+        }
+        expect(message).not.toContain(SECRET);
+    });
+    it('still explains what is required, so a legitimate caller can proceed', () => {
+        let message = '';
+        try {
+            protectedRegistry().validateWriteAccess('roam_create_page', 'work', undefined);
+        }
+        catch (e) {
+            message = e.message;
+        }
+        expect(message).toMatch(/write_key/);
+        expect(message).toMatch(/work/);
+    });
+    it('lets a correct key through', () => {
+        expect(() => protectedRegistry().validateWriteAccess('roam_create_page', 'work', SECRET)).not.toThrow();
+    });
+    it('does not gate reads on protected graphs', () => {
+        expect(() => protectedRegistry().validateWriteAccess('roam_search_by_text', 'work', undefined)).not.toThrow();
+    });
+});

package/build/markdown-utils.js

@@ -83,7 +83,10 @@ function convertToRoamMarkdown(text) {
     text = text.replace(/\*\*(.+?)\*\*/g, '**$1**'); // Preserve double asterisks
     // Handle single asterisks/underscores (italic)
     text = text.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '__$1__'); // Single asterisk to double underscore
-    text = text.replace(/(?<!_)_(?!_)(.+?)(?<!_)_(?!_)/g, '__$1__'); // Single underscore to double underscore
+    // Single underscore to italic, but only at word boundaries. Underscores flanked by
+    // word chars (\w includes _) are literal per CommonMark, so snake_case filenames and
+    // URLs like /wiki/Ning_Li_(physicist) are left intact instead of becoming __Li__.
+    text = text.replace(/(?<!\w)_(?!_)(.+?)_(?!\w)/g, '__$1__');
     // Handle highlights
     text = text.replace(/==(.+?)==/g, '^^$1^^');
     // Convert tasks

package/build/markdown-utils.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseMarkdown, convertToRoamActions, convertToRoamActionsWithBlocks, nestUnderHeadings } from './markdown-utils.js';
+import { parseMarkdown, convertToRoamActions, convertToRoamActionsWithBlocks, nestUnderHeadings, convertToRoamMarkdown } from './markdown-utils.js';
 describe('markdown-utils', () => {
     describe('parseMarkdown - numbered lists', () => {
         it('should detect numbered list items and strip prefixes', () => {
@@ -153,6 +153,27 @@ And this--too`;
             expect(blocks[1].children[0].children).toHaveLength(1); // Beta.1.a
         });
     });
+    describe('convertToRoamMarkdown - italic vs literal underscores', () => {
+        it('still converts genuine word-boundary italics to Roam __italic__', () => {
+            expect(convertToRoamMarkdown('this is _italic_ text')).toBe('this is __italic__ text');
+            expect(convertToRoamMarkdown('_leading_ and *starred*')).toBe('__leading__ and __starred__');
+        });
+        it('leaves intra-word (snake_case) underscores literal', () => {
+            const line = 'Source transcript on disk :: american_alchemy_dave_rossi.txt';
+            expect(convertToRoamMarkdown(line)).toBe(line);
+        });
+        it('leaves underscores inside URLs literal', () => {
+            const line = 'Ning Li: https://en.wikipedia.org/wiki/Ning_Li_(physicist)';
+            expect(convertToRoamMarkdown(line)).toBe(line);
+        });
+        it('does not treat word_bounded_ trailing underscores as emphasis', () => {
+            expect(convertToRoamMarkdown('foo_bar_baz')).toBe('foo_bar_baz');
+        });
+        it('keeps underscores literal when wrapped in inline code (backtick escape hatch)', () => {
+            const line = 'literal `_not_italic_` here';
+            expect(convertToRoamMarkdown(line)).toBe(line);
+        });
+    });
     describe('nestUnderHeadings', () => {
         const node = (content, heading_level = 0, children = []) => ({ content, level: 1, heading_level, children });
         it('nests content and deeper headings under their section heading', () => {