roam-research-mcp 2.22.0 → 2.23.0

package/README.md

@@ -116,6 +116,47 @@ 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 |
+
+Configure per graph, or disable with `false`:
+
+```bash
+ROAM_GRAPHS='{"personal": {"token": "...", "graph": "...", "guidelinesPage": "roam/agent guidelines"}, "work": {"token": "...", "graph": "...", "guidelinesPage": false}}'
+ROAM_GUIDELINES_PAGE='roam/agent guidelines'   # fallback when a graph sets none
+```
+
+If no such page exists 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 +196,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 +288,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,18 @@ 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.
+     * Same precedence as memoriesTag: per-graph config > env var > default.
+     */
+    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 ?? 'roam/agent guidelines';
+    }
     /**
      * Get an initialized Graph instance, creating it lazily if needed
      * @param key - Graph key from config. Defaults to defaultKey if not specified.
@@ -83,7 +95,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 +143,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('defaults to the shared roam/agent guidelines convention', () => {
+        delete process.env.ROAM_GUIDELINES_PAGE;
+        const r = make({ personal: { token: 't', graph: 'g' } });
+        expect(r.getGuidelinesPage('personal')).toBe('roam/agent guidelines');
+    });
+    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', () => {

package/build/server/roam-server.js

@@ -4,6 +4,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ListToolsRequestSchema, ListPromptsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { HTTP_STREAM_PORT, HTTP_STREAM_HOST, HTTP_AUTH_TOKEN, validateEnvironment } from '../config/environment.js';
 import { isBearerAuthorized } from '../utils/auth.js';
+import { RoamError, toErrorResult } from '../shared/errors.js';
 import { createRegistryFromEnv } from '../config/graph-registry.js';
 import { toolSchemas } from '../tools/schemas.js';
 import { ToolHandlers } from '../tools/tool-handlers.js';
@@ -46,7 +47,8 @@ export class RoamServer {
             return cached;
         }
         const memoriesTag = this.registry.getMemoriesTag(graphKey);
-        const handlers = new ToolHandlers(graph, memoriesTag);
+        const guidelinesPage = this.registry.getGuidelinesPage(graphKey);
+        const handlers = new ToolHandlers(graph, memoriesTag, guidelinesPage);
         this.toolHandlersCache.set(graphKey, handlers);
         return handlers;
     }
@@ -142,6 +144,12 @@ export class RoamServer {
                             content: [{ type: 'text', text: content }],
                         };
                     }
+                    case 'roam_get_guidelines': {
+                        const result = await toolHandlers.getGuidelines();
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     case 'roam_fetch_page_by_title': {
                         const { title, format } = cleanedArgs;
                         const content = await toolHandlers.fetchPageByTitle(title, format);
@@ -299,6 +307,13 @@ export class RoamServer {
                 }
             }
             catch (error) {
+                // A RoamError is a TOOL failure, not a protocol failure: return it as
+                // content with isError so the model can read the code and the recovery
+                // context (available_graphs, and so on) and act on it. Throwing would
+                // collapse all of that into a JSON-RPC error string.
+                if (error instanceof RoamError) {
+                    return toErrorResult(error);
+                }
                 if (error instanceof McpError) {
                     throw error;
                 }
@@ -394,6 +409,23 @@ export class RoamServer {
                         await transport.handleRequest(req, res);
                         return;
                     }
+                    // A request that carries a session ID we don't know (the daemon
+                    // restarted, or the session was terminated) is a dead session. Per
+                    // the MCP streamable-HTTP spec the server MUST respond 404 so the
+                    // client starts a new session with a fresh InitializeRequest.
+                    // Falling through to a new transport instead makes the SDK answer
+                    // HTTP 400 "Server not initialized", which clients do not treat as
+                    // a re-initialize signal — they keep retrying the dead session and
+                    // every tool call times out with no useful error.
+                    if (sessionId) {
+                        res.writeHead(404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({
+                            jsonrpc: '2.0',
+                            error: { code: -32001, message: 'Session not found' },
+                            id: null,
+                        }));
+                        return;
+                    }
                     // Create new transport and server for new sessions
                     const httpMcpServer = this.createMcpServer('-http');
                     const httpStreamTransport = new StreamableHTTPServerTransport({