@roam-research/roam-tools-core 0.4.2 → 0.5.1

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAGhB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAQpB,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAuB;gBAEvB,MAAM,EAAE,gBAAgB;YAkBtB,OAAO;YAeP,gBAAgB;YAKhB,KAAK;IAInB,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAoBlC;;OAEG;IACH,OAAO,CAAC,cAAc;IAgDtB,OAAO,CAAC,aAAa;IASrB;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IA0CxC,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,OAAO,EAAO,GACnB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAuE5B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAGhB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAGpB,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAuB;gBAEvB,MAAM,EAAE,gBAAgB;YAoBtB,OAAO;YAeP,gBAAgB;YAKhB,KAAK;IAInB,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,qBAAqB;IAwB7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAiBlC;;OAEG;IACH,OAAO,CAAC,cAAc;IAsCtB,OAAO,CAAC,aAAa;IAMrB;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IAsCxC,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAuExF"}

package/dist/client.js

@@ -4,7 +4,7 @@ import { readFile } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
 import open from "open";
-import { EXPECTED_API_VERSION, getErrorMessage, RoamError, ErrorCodes, } from "./types.js";
+import { EXPECTED_API_VERSION, getErrorMessage, RoamError, ErrorCodes } from "./types.js";
 export class RoamClient {
     graphName;
     graphType;

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAgCA,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA0CD,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgiBzE"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA0CD,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4gBzE"}

package/dist/connect.js

@@ -1,6 +1,6 @@
 import { search, select, input } from "@inquirer/prompts";
 import { getPort, getConfiguredGraphsSafe, saveGraphToConfig, removeGraphFromConfig, } from "./graph-resolver.js";
-import { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify, } from "./roam-api.js";
+import { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify } from "./roam-api.js";
 // ============================================================================
 // API Functions
 // ============================================================================
@@ -121,7 +121,7 @@ export async function connect(options = {}) {
             try {
                 availableGraphs = await fetchAvailableGraphs(port);
             }
-            catch (retryError) {
+            catch {
                 console.error("\nCould not connect to Roam Desktop.");
                 console.error("Please make sure Roam is running and try again.");
                 process.exit(1);
@@ -171,8 +171,7 @@ export async function connect(options = {}) {
         else {
             // Match against available graphs
             const graphType = options.type;
-            const match = availableGraphs.find((g) => g.name === options.graph &&
-                (!graphType || g.type === graphType));
+            const match = availableGraphs.find((g) => g.name === options.graph && (!graphType || g.type === graphType));
             if (!match) {
                 console.error(`Error: Graph "${options.graph}" not found in available graphs.`);
                 if (availableGraphs.length > 0) {
@@ -243,8 +242,7 @@ export async function connect(options = {}) {
             source: async (input) => {
                 // Filter available graphs (exclude custom option placeholder)
                 const filtered = input
-                    ? choices.filter((g) => !g.isCustomOption &&
-                        g.name.toLowerCase().includes(input.toLowerCase()))
+                    ? choices.filter((g) => !g.isCustomOption && g.name.toLowerCase().includes(input.toLowerCase()))
                     : choices.filter((g) => !g.isCustomOption);
                 // Build results with custom option
                 const results = filtered.map((g) => {
@@ -280,7 +278,7 @@ export async function connect(options = {}) {
             const customName = await input({
                 message: "Enter the graph name:",
                 default: defaultName,
-                validate: (value) => value.trim() ? true : "Graph name cannot be empty",
+                validate: (value) => (value.trim() ? true : "Graph name cannot be empty"),
             });
             // Public graphs are always hosted
             const customType = "hosted";
@@ -370,7 +368,7 @@ export async function connect(options = {}) {
                 console.log("\nTo change this token's permissions:");
                 console.log("  1. Open Roam Desktop and open the graph");
                 console.log("  2. Go to Settings > Graph > Local API Tokens");
-                console.log('  3. Find the token and adjust its permissions');
+                console.log("  3. Find the token and adjust its permissions");
                 // Permission changes are synced when get_graph_guidelines calls getTokenInfo()
                 console.log("\nChanges will be synced automatically next time the MCP is started.");
                 return;

package/dist/graph-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-resolver.d.ts","sourceRoot":"","sources":["../src/graph-resolver.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,aAAa,EACb,WAAW,EACX,aAAa,EAGb,WAAW,EAEZ,MAAM,YAAY,CAAC;AAyBpB,wBAAsB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAG/C;AAmCD,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CA4G3D;AA+CD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B5E;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgB9E;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,oBAAoB,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,GAClF,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAOtE;AAMD;;GAEG;AACH,wBAAsB,eAAe,CACnC,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAYlC;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAClD,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAC9F,CAQA;AAMD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,aAAa,CAAC,CAgDxB;AAiBD;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAC5C,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CACtC,CAmBA"}
+{"version":3,"file":"graph-resolver.d.ts","sourceRoot":"","sources":["../src/graph-resolver.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,aAAa,EACb,WAAW,EACX,aAAa,EAGb,WAAW,EAEZ,MAAM,YAAY,CAAC;AAyBpB,wBAAsB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAG/C;AAmCD,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CA0G3D;AA+CD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B5E;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc9E;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,oBAAoB,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,GAClF,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAOtE;AAMD;;GAEG;AACH,wBAAsB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAU9F;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAClD,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAC9F,CAQA;AAMD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAkDjF;AAiBD;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAgBpF"}

package/dist/graph-resolver.js

@@ -223,7 +223,8 @@ export async function updateGraphTokenStatus(nickname, updates) {
         graph.accessLevel = updates.accessLevel;
         changed = true;
     }
-    if (updates.lastKnownTokenStatus !== undefined && graph.lastKnownTokenStatus !== updates.lastKnownTokenStatus) {
+    if (updates.lastKnownTokenStatus !== undefined &&
+        graph.lastKnownTokenStatus !== updates.lastKnownTokenStatus) {
         graph.lastKnownTokenStatus = updates.lastKnownTokenStatus;
         changed = true;
     }
@@ -288,7 +289,7 @@ export async function resolveGraph(providedGraph) {
         if (!graphConfig) {
             throw new RoamError(`Graph "${providedGraph}" not found in config. Available graph nicknames are listed below.`, ErrorCodes.GRAPH_NOT_CONFIGURED, {
                 available_graphs: await getConfiguredGraphs(),
-                instruction: "Pass the 'nickname' value as the graph parameter. Before operating on a graph, call get_graph_guidelines to understand its conventions.",
+                instruction: "Pass the 'nickname' value as the graph parameter. After identifying which graph to use, ALWAYS call get_graph_guidelines next — it returns essential context and orientation for the session.",
             });
         }
         return {
@@ -315,7 +316,7 @@ export async function resolveGraph(providedGraph) {
     // 3. Multiple graphs - require explicit selection
     throw new RoamError("Multiple graphs configured. Pass a graph nickname as the graph parameter to specify which graph to use.", ErrorCodes.GRAPH_NOT_SELECTED, {
         available_graphs: await getConfiguredGraphs(),
-        instruction: "Pass the 'nickname' value as the graph parameter. Before operating on a graph, call get_graph_guidelines to understand its conventions.",
+        instruction: "Pass the 'nickname' value as the graph parameter. After identifying which graph to use, ALWAYS call get_graph_guidelines next — it returns essential context and orientation for the session.",
     });
 }
 /**

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export type { CallToolResult, TextContent, ImageContent, GraphType, AccessLevel, GraphConfig, RoamMcpConfig, ResolvedGraph, ErrorCode, RoamApiError, RoamResponse, RoamClientConfig, Block, Page, BlockLocation, WindowType, SidebarWindow, SidebarWindowInfo, FocusedBlock, SelectedBlock, MainWindowViewType, MainWindowView, SearchResultPath, SearchResult, SearchResponse, Template, QueryResult, QueryResponse, TokenInfoResponse, TokenInfoResult, } from "./types.js";
+export type { CallToolResult, TextContent, ImageContent, GraphType, AccessLevel, GraphConfig, RoamMcpConfig, ResolvedGraph, ErrorCode, RoamApiError, RoamResponse, RoamClientConfig, Block, Page, BlockLocation, WindowType, SidebarWindow, SidebarWindowInfo, FocusedBlock, SelectedBlock, MainWindowViewType, MainWindowView, SearchResultPath, SearchResult, SearchResponse, RecentlyOpenedBlock, RecentlyOpenedItem, DailyNotePagesViewItem, RecentlyEditedPage, SearchSuggestionsResponse, SearchTemplatesResponse, GetPageResponse, GetBlockResponse, Template, QueryResult, QueryResponse, TokenInfoResponse, TokenInfoResult, } from "./types.js";
 export { GraphConfigSchema, RoamMcpConfigSchema, ErrorCodes, RoamError, CONFIG_VERSION, EXPECTED_API_VERSION, textResult, imageResult, errorResult, getErrorMessage, } from "./types.js";
 export { RoamClient } from "./client.js";
 export { getPort, resolveGraph, saveGraphToConfig, removeGraphFromConfig, updateGraphTokenStatus, getConfiguredGraphsSafe, getConfiguredGraphs, findGraphConfig, getMcpConfig, getOpenGraphs, } from "./graph-resolver.js";
-export { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify, } from "./roam-api.js";
-export type { AvailableGraph, GraphsResponse, TokenExchangeResponse, } from "./roam-api.js";
+export { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify } from "./roam-api.js";
+export type { AvailableGraph, GraphsResponse, TokenExchangeResponse } from "./roam-api.js";
 export { tools, findTool, routeToolCall } from "./tools.js";
-export type { ToolDefinition, ClientToolDefinition, StandaloneToolDefinition, } from "./tools.js";
+export type { ToolDefinition, ClientToolDefinition, StandaloneToolDefinition } from "./tools.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,cAAc,EAAE,WAAW,EAAE,YAAY,EACzC,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EACjE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EACvD,KAAK,EAAE,IAAI,EAAE,aAAa,EAC1B,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAC5C,YAAY,EAAE,aAAa,EAC3B,kBAAkB,EAAE,cAAc,EAClC,gBAAgB,EAAE,YAAY,EAAE,cAAc,EAC9C,QAAQ,EAAE,WAAW,EAAE,aAAa,EACpC,iBAAiB,EAAE,eAAe,GACnC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EAAE,mBAAmB,EACtC,UAAU,EAAE,SAAS,EACrB,cAAc,EAAE,oBAAoB,EACpC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,GACtD,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EACL,OAAO,EAAE,YAAY,EACrB,iBAAiB,EAAE,qBAAqB,EAAE,sBAAsB,EAChE,uBAAuB,EAAE,mBAAmB,EAAE,eAAe,EAC7D,YAAY,EAAE,aAAa,GAC5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,oBAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,GAChE,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EAAE,cAAc,EAAE,qBAAqB,GACtD,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EACV,cAAc,EAAE,oBAAoB,EAAE,wBAAwB,GAC/D,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,WAAW,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,KAAK,EACL,IAAI,EACJ,aAAa,EACb,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EACL,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAChG,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG3F,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -5,6 +5,6 @@ export { RoamClient } from "./client.js";
 // Graph resolution and config management
 export { getPort, resolveGraph, saveGraphToConfig, removeGraphFromConfig, updateGraphTokenStatus, getConfiguredGraphsSafe, getConfiguredGraphs, findGraphConfig, getMcpConfig, getOpenGraphs, } from "./graph-resolver.js";
 // Shared Roam API functions
-export { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify, } from "./roam-api.js";
+export { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify } from "./roam-api.js";
 // Tool definitions and routing
 export { tools, findTool, routeToolCall } from "./tools.js";

package/dist/operations/blocks.d.ts

@@ -2,16 +2,25 @@ import { z } from "zod";
 import type { RoamClient } from "../client.js";
 import type { CallToolResult } from "../types.js";
 export declare const CreateBlockSchema: z.ZodObject<{
-    parentUid: z.ZodString;
+    parentUid: z.ZodOptional<z.ZodString>;
+    pageTitle: z.ZodOptional<z.ZodString>;
+    dailyNotePage: z.ZodOptional<z.ZodString>;
+    nestUnder: z.ZodOptional<z.ZodString>;
     markdown: z.ZodString;
     order: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodEnum<["first", "last"]>]>>;
 }, "strip", z.ZodTypeAny, {
     markdown: string;
-    parentUid: string;
+    parentUid?: string | undefined;
+    pageTitle?: string | undefined;
+    dailyNotePage?: string | undefined;
+    nestUnder?: string | undefined;
     order?: number | "first" | "last" | undefined;
 }, {
     markdown: string;
-    parentUid: string;
+    parentUid?: string | undefined;
+    pageTitle?: string | undefined;
+    dailyNotePage?: string | undefined;
+    nestUnder?: string | undefined;
     order?: number | "first" | "last" | undefined;
 }>;
 export declare const GetBlockSchema: z.ZodObject<{
@@ -29,16 +38,22 @@ export declare const UpdateBlockSchema: z.ZodObject<{
     string: z.ZodOptional<z.ZodString>;
     open: z.ZodOptional<z.ZodBoolean>;
     heading: z.ZodOptional<z.ZodNumber>;
+    childrenViewType: z.ZodOptional<z.ZodEnum<["bullet", "numbered", "document"]>>;
+    textAlign: z.ZodOptional<z.ZodEnum<["left", "center", "right", "justify"]>>;
 }, "strip", z.ZodTypeAny, {
     uid: string;
     string?: string | undefined;
+    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
     open?: boolean | undefined;
     heading?: number | undefined;
+    textAlign?: "left" | "center" | "right" | "justify" | undefined;
 }, {
     uid: string;
     string?: string | undefined;
+    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
     open?: boolean | undefined;
     heading?: number | undefined;
+    textAlign?: "left" | "center" | "right" | "justify" | undefined;
 }>;
 export declare const DeleteBlockSchema: z.ZodObject<{
     uid: z.ZodString;
@@ -108,6 +123,7 @@ export interface BacklinkResult {
     }>;
 }
 export interface GetBacklinksResponse {
+    queriedAt?: string;
     total: number;
     results: BacklinkResult[];
 }
@@ -117,4 +133,44 @@ export declare function updateBlock(client: RoamClient, params: UpdateBlockParam
 export declare function deleteBlock(client: RoamClient, params: DeleteBlockParams): Promise<CallToolResult>;
 export declare function moveBlock(client: RoamClient, params: MoveBlockParams): Promise<CallToolResult>;
 export declare function getBacklinks(client: RoamClient, params: GetBacklinksParams): Promise<CallToolResult>;
+export declare const AddCommentSchema: z.ZodObject<{
+    blockUid: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+    commentMarkdown: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    blockUid: string;
+    comment?: string | undefined;
+    commentMarkdown?: string | undefined;
+}, {
+    blockUid: string;
+    comment?: string | undefined;
+    commentMarkdown?: string | undefined;
+}>;
+export declare const GetCommentsSchema: z.ZodObject<{
+    blockUid: z.ZodString;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    blockUid: string;
+    maxDepth?: number | undefined;
+}, {
+    blockUid: string;
+    maxDepth?: number | undefined;
+}>;
+export type AddCommentParams = z.infer<typeof AddCommentSchema>;
+export type GetCommentsParams = z.infer<typeof GetCommentsSchema>;
+export interface CommentResult {
+    parentUid: string;
+    author: string;
+    createdTime: string;
+    editedTime: string;
+    markdown: string;
+    singleEditableUid: string | null;
+}
+export interface GetCommentsResponse {
+    queriedAt?: string;
+    total: number;
+    comments: CommentResult[];
+}
+export declare function addComment(client: RoamClient, params: AddCommentParams): Promise<CallToolResult>;
+export declare function getComments(client: RoamClient, params: GetCommentsParams): Promise<CallToolResult>;
 //# sourceMappingURL=blocks.d.ts.map

package/dist/operations/blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/operations/blocks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAI5B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAK5B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;EAE5B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;EAI1B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU7B,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAGpE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAWxG;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAMlG;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQxG;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGxG;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAapG;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,cAAc,CAAC,CAezB"}
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/operations/blocks.ts"],"names":[],"mappings":"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"}

package/dist/operations/blocks.js

@@ -1,20 +1,47 @@
 import { z } from "zod";
-import { textResult } from "../types.js";
+import { textResult, RoamError, ErrorCodes } from "../types.js";
 // Schemas
 export const CreateBlockSchema = z.object({
-    parentUid: z.string().describe("UID of parent block or page"),
+    parentUid: z
+        .string()
+        .optional()
+        .describe("UID of parent block or page. Exactly one of parentUid, pageTitle, or dailyNotePage is required."),
+    pageTitle: z
+        .string()
+        .optional()
+        .describe("Page title to create block under (creates the page if it doesn't exist). Exactly one of parentUid, pageTitle, or dailyNotePage is required."),
+    dailyNotePage: z
+        .string()
+        .regex(/^\d{2}-\d{2}-\d{4}$/, "Must be MM-DD-YYYY format (e.g. '03-17-2026')")
+        .optional()
+        .describe("Daily note date in MM-DD-YYYY format (e.g. '03-17-2026'). Targets that day's daily note page, creating it if needed. Exactly one of parentUid, pageTitle, or dailyNotePage is required."),
+    nestUnder: z
+        .string()
+        .optional()
+        .describe("Insert under a direct child block matching this string (matches on the block's string field, including markup like **bold** or [[links]]). If no match exists, creates a new child block with this text first, then inserts under it. Works with parentUid, pageTitle, or dailyNotePage."),
     markdown: z.string().describe("Markdown content for the block"),
-    order: z.union([z.coerce.number(), z.enum(["first", "last"])]).optional().describe("Position (number, 'first', or 'last'). Defaults to 'last'"),
+    order: z
+        .union([z.coerce.number(), z.enum(["first", "last"])])
+        .optional()
+        .describe("Position (number, 'first', or 'last'). Defaults to 'last'"),
 });
 export const GetBlockSchema = z.object({
     uid: z.string().describe("Block UID"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (omit for full tree)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (omit for full tree)"),
 });
 export const UpdateBlockSchema = z.object({
     uid: z.string().describe("Block UID"),
     string: z.string().optional().describe("New text content"),
     open: z.boolean().optional().describe("Collapse state"),
     heading: z.coerce.number().optional().describe("Heading level (0-3)"),
+    childrenViewType: z
+        .enum(["bullet", "numbered", "document"])
+        .optional()
+        .describe("How children are displayed (bullet, numbered, or document)"),
+    textAlign: z.enum(["left", "center", "right", "justify"]).optional().describe("Text alignment"),
 });
 export const DeleteBlockSchema = z.object({
     uid: z.string().describe("Block UID to delete"),
@@ -22,28 +49,59 @@ export const DeleteBlockSchema = z.object({
 export const MoveBlockSchema = z.object({
     uid: z.string().describe("Block UID to move"),
     parentUid: z.string().describe("UID of the new parent block or page"),
-    order: z.union([z.coerce.number(), z.enum(["first", "last"])]).describe("Position in the new parent (number, 'first', or 'last')"),
+    order: z
+        .union([z.coerce.number(), z.enum(["first", "last"])])
+        .describe("Position in the new parent (number, 'first', or 'last')"),
 });
 export const GetBacklinksSchema = z.object({
     uid: z.string().optional().describe("UID of page or block (required if no title)"),
     title: z.string().optional().describe("Page title (required if no uid)"),
     offset: z.coerce.number().optional().describe("Skip first N results (default: 0)"),
     limit: z.coerce.number().optional().describe("Max results to return (default: 20)"),
-    sort: z.enum(["created-date", "edited-date", "daily-note-date"]).optional().describe("Sort order (default: created-date)"),
+    sort: z
+        .enum(["created-date", "edited-date", "daily-note-date"])
+        .optional()
+        .describe("Sort order (default: created-date)"),
     sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
-    search: z.string().optional().describe("Filter results by text match (searches block, parents, children, page title)"),
-    includePath: z.boolean().optional().describe("Include breadcrumb path to each result (default: true)"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (default: 2)"),
+    search: z
+        .string()
+        .optional()
+        .describe("Filter results by text match (searches block, parents, children, page title)"),
+    includePath: z
+        .boolean()
+        .optional()
+        .describe("Include breadcrumb path to each result (default: true)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (default: 2)"),
 });
 export async function createBlock(client, params) {
+    // Validate: exactly one of parentUid, pageTitle, or dailyNotePage
+    const targets = [params.parentUid, params.pageTitle, params.dailyNotePage].filter((v) => v !== undefined);
+    if (targets.length === 0) {
+        throw new RoamError("Either 'parentUid', 'pageTitle', or 'dailyNotePage' is required to specify where to create the block", ErrorCodes.VALIDATION_ERROR);
+    }
+    if (targets.length > 1) {
+        throw new RoamError("Provide only one of 'parentUid', 'pageTitle', or 'dailyNotePage'", ErrorCodes.VALIDATION_ERROR);
+    }
+    const location = {
+        order: params.order ?? "last",
+    };
+    if (params.parentUid !== undefined) {
+        location["parent-uid"] = params.parentUid;
+    }
+    else if (params.dailyNotePage !== undefined) {
+        location["page-title"] = { "daily-note-page": params.dailyNotePage };
+    }
+    else {
+        location["page-title"] = params.pageTitle;
+    }
+    if (params.nestUnder !== undefined) {
+        location["nest-under-str"] = params.nestUnder;
+    }
     const response = await client.call("data.block.fromMarkdown", [
-        {
-            location: {
-                "parent-uid": params.parentUid,
-                order: params.order ?? "last",
-            },
-            "markdown-string": params.markdown,
-        },
+        { location, "markdown-string": params.markdown },
     ]);
     return textResult(response.result ?? { uids: [] });
 }
@@ -62,6 +120,10 @@ export async function updateBlock(client, params) {
         block.open = params.open;
     if (params.heading !== undefined)
         block.heading = params.heading;
+    if (params.childrenViewType !== undefined)
+        block["children-view-type"] = params.childrenViewType;
+    if (params.textAlign !== undefined)
+        block["text-align"] = params.textAlign;
     await client.call("data.block.update", [{ block }]);
     return textResult({ success: true });
 }
@@ -106,3 +168,47 @@ export async function getBacklinks(client, params) {
     const response = await client.call("data.ai.getBacklinks", [apiParams]);
     return textResult(response.result ?? { total: 0, results: [] });
 }
+// --- Comments ---
+export const AddCommentSchema = z.object({
+    blockUid: z.string().describe("UID of the block to comment on"),
+    comment: z
+        .string()
+        .optional()
+        .describe("Plain text comment (single block, editable later via update_block). Required if commentMarkdown not provided. Preferred for simple comments."),
+    commentMarkdown: z
+        .string()
+        .optional()
+        .describe("Markdown comment parsed into multiple blocks. Required if comment not provided. Use only when you need structure (lists, headings). Harder to edit later."),
+});
+export const GetCommentsSchema = z.object({
+    blockUid: z.string().describe("UID of the block to get comments for"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in each comment's markdown (omit for full tree)"),
+});
+export async function addComment(client, params) {
+    // Validate: exactly one of comment or commentMarkdown must be provided
+    const hasComment = params.comment !== undefined;
+    const hasCommentMarkdown = params.commentMarkdown !== undefined;
+    if (!hasComment && !hasCommentMarkdown) {
+        throw new RoamError("Provide one of 'comment' or 'commentMarkdown'", ErrorCodes.VALIDATION_ERROR);
+    }
+    if (hasComment && hasCommentMarkdown) {
+        throw new RoamError("Provide 'comment' or 'commentMarkdown', not both", ErrorCodes.VALIDATION_ERROR);
+    }
+    const apiParams = { "block-uid": params.blockUid };
+    if (hasComment)
+        apiParams["reply-string"] = params.comment;
+    if (hasCommentMarkdown)
+        apiParams["reply-markdown"] = params.commentMarkdown;
+    const response = await client.call("data.block.addComment", [apiParams]);
+    return textResult(response.result ?? { uids: [] });
+}
+export async function getComments(client, params) {
+    const apiParams = { uid: params.blockUid };
+    if (params.maxDepth !== undefined)
+        apiParams.maxDepth = params.maxDepth;
+    const response = await client.call("data.ai.getComments", [apiParams]);
+    return textResult(response.result ?? { total: 0, comments: [] });
+}

package/dist/operations/datalog.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { RoamClient } from "../client.js";
+import type { CallToolResult } from "../types.js";
+export declare const DatalogQuerySchema: z.ZodObject<{
+    query: z.ZodString;
+    inputs: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    inputs?: unknown[] | undefined;
+}, {
+    query: string;
+    inputs?: unknown[] | undefined;
+}>;
+export type DatalogQueryParams = z.infer<typeof DatalogQuerySchema>;
+export declare function datalogQuery(client: RoamClient, params: DatalogQueryParams): Promise<CallToolResult>;
+//# sourceMappingURL=datalog.d.ts.map

package/dist/operations/datalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datalog.d.ts","sourceRoot":"","sources":["../../src/operations/datalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,eAAO,MAAM,kBAAkB;;;;;;;;;EAQ7B,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,wBAAsB,YAAY,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,cAAc,CAAC,CAIzB"}

package/dist/operations/datalog.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { textResult } from "../types.js";
+export const DatalogQuerySchema = z.object({
+    query: z
+        .string()
+        .describe("Datalog query string (e.g., '[:find ?title :where [?e :node/title ?title]]')"),
+    inputs: z
+        .array(z.unknown())
+        .optional()
+        .describe("Input parameters for the query, corresponding to :in clause bindings after $"),
+});
+export async function datalogQuery(client, params) {
+    const args = params.inputs ? [params.query, ...params.inputs] : [params.query];
+    const response = await client.call("q", args);
+    return textResult(response.result ?? []);
+}

package/dist/operations/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/operations/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,eAAO,MAAM,aAAa;;;;;;EAExB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;EAM3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;EAE3B,CAAC;AAGH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AA0GhE,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAkBhG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAiDtG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGtG"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/operations/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,eAAO,MAAM,aAAa;;;;;;EAExB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;EAkB3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;EAE3B,CAAC;AAGH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AA+GhE,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAkBhG;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,cAAc,CAAC,CAiDzB;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,cAAc,CAAC,CAGzB"}

package/dist/operations/files.js

@@ -7,11 +7,23 @@ export const FileGetSchema = z.object({
     url: z.string().describe("Firebase storage URL of the file"),
 });
 export const FileUploadSchema = z.object({
-    filePath: z.string().optional().describe("Local file path (preferred) - server reads the file directly"),
+    filePath: z
+        .string()
+        .optional()
+        .describe("Local file path (preferred) - server reads the file directly"),
     url: z.string().optional().describe("Remote URL to fetch the file from"),
-    base64: z.string().optional().describe("Base64-encoded file data (fallback for sandboxed clients)"),
-    mimetype: z.string().optional().describe("MIME type (e.g., image/png, image/jpeg) - auto-detected if not provided"),
-    filename: z.string().optional().describe("Original filename for reference - derived from path/url if not provided"),
+    base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded file data (fallback for sandboxed clients)"),
+    mimetype: z
+        .string()
+        .optional()
+        .describe("MIME type (e.g., image/png, image/jpeg) - auto-detected if not provided"),
+    filename: z
+        .string()
+        .optional()
+        .describe("Original filename for reference - derived from path/url if not provided"),
 });
 export const FileDeleteSchema = z.object({
     url: z.string().describe("Firebase storage URL of the file to delete"),
@@ -102,7 +114,8 @@ async function fetchRemoteFile(url) {
     // Try Content-Type header first, then extension, then magic bytes
     let mimetype = response.headers.get("content-type")?.split(";")[0];
     if (!mimetype || mimetype === "application/octet-stream") {
-        mimetype = detectMimeTypeFromExtension(urlPath) || detectMimeTypeFromBase64(base64) || undefined;
+        mimetype =
+            detectMimeTypeFromExtension(urlPath) || detectMimeTypeFromBase64(base64) || undefined;
     }
     if (!mimetype) {
         throw new Error(`Could not detect MIME type for URL: ${url}`);

package/dist/operations/graphs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphs.d.ts","sourceRoot":"","sources":["../../src/operations/graphs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAsBlD,eAAO,MAAM,gBAAgB,gDAAe,CAAC;AAE7C,eAAO,MAAM,mBAAmB;;;;;;;;;EAoB9B,CAAC;AAMH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMtE;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC,CAmB1D;AAqDD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,cAAc,CAAC,CAiKzB"}
+{"version":3,"file":"graphs.d.ts","sourceRoot":"","sources":["../../src/operations/graphs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgBlD,eAAO,MAAM,gBAAgB,gDAAe,CAAC;AAE7C,eAAO,MAAM,mBAAmB;;;;;;;;;EAkB9B,CAAC;AAMH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMtE;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC,CAqB1D;AAkDD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0JtF"}

package/dist/operations/graphs.js

@@ -3,7 +3,7 @@
 import { z } from "zod";
 import { textResult, RoamError, ErrorCodes } from "../types.js";
 import { getConfiguredGraphs, getConfiguredGraphsSafe, getPort, saveGraphToConfig, } from "../graph-resolver.js";
-import { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify, } from "../roam-api.js";
+import { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify } from "../roam-api.js";
 // ============================================================================
 // Schemas
 // ============================================================================
@@ -33,7 +33,7 @@ export async function listGraphs() {
         const graphs = await getConfiguredGraphs();
         return textResult({
             graphs,
-            instruction: "Pass the 'nickname' value as the graph parameter. Before operating on a graph, call get_graph_guidelines to understand its conventions.",
+            instruction: "Pass the 'nickname' value as the graph parameter. After identifying which graph to use, ALWAYS call get_graph_guidelines next — it returns essential context and orientation for the session.",
             setup: "To connect additional graphs, use the setup_new_graph tool (call it without arguments to see available graphs).",
         });
     }
@@ -78,8 +78,7 @@ async function fetchAvailableGraphsWithRetry(port) {
     }
     catch (error) {
         const err = error;
-        const isConnectionError = err.cause?.code === "ECONNREFUSED" ||
-            err.message?.includes("fetch failed");
+        const isConnectionError = err.cause?.code === "ECONNREFUSED" || err.message?.includes("fetch failed");
         if (!isConnectionError) {
             throw error;
         }

package/dist/operations/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/operations/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAkE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlH,eAAO,MAAM,oBAAoB,gDAAe,CAAC;AAEjD,eAAO,MAAM,kBAAkB,gDAAe,CAAC;AAE/C,eAAO,MAAM,oBAAoB;;;;;;;;;EAG/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;EAG5B,CAAC;AAGH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAShF;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAS9E;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ9G;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAUxG"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/operations/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAKV,cAAc,EACf,MAAM,aAAa,CAAC;AAIrB,eAAO,MAAM,oBAAoB,gDAAe,CAAC;AAEjD,eAAO,MAAM,kBAAkB,gDAAe,CAAC;AAE/C,eAAO,MAAM,oBAAoB;;;;;;;;;EAG/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;EAM5B,CAAC;AAGH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAShF;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAS9E;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAQzB;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,cAAc,CAAC,CAUzB"}

package/dist/operations/navigation.js

@@ -9,7 +9,10 @@ export const OpenMainWindowSchema = z.object({
 });
 export const OpenSidebarSchema = z.object({
     uid: z.string().describe("UID of page or block"),
-    type: z.enum(["block", "outline", "mentions"]).optional().describe("View type (default: outline)"),
+    type: z
+        .enum(["block", "outline", "mentions"])
+        .optional()
+        .describe("View type (default: outline)"),
 });
 export async function getOpenWindows(client) {
     const [mainResponse, sidebarResponse] = await Promise.all([

package/dist/operations/pages.d.ts

@@ -5,14 +5,17 @@ export declare const CreatePageSchema: z.ZodObject<{
     title: z.ZodString;
     markdown: z.ZodOptional<z.ZodString>;
     uid: z.ZodOptional<z.ZodString>;
+    childrenViewType: z.ZodOptional<z.ZodEnum<["document", "bullet", "numbered"]>>;
 }, "strip", z.ZodTypeAny, {
     title: string;
     markdown?: string | undefined;
     uid?: string | undefined;
+    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
 }, {
     title: string;
     markdown?: string | undefined;
     uid?: string | undefined;
+    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
 }>;
 export declare const GetPageSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;

package/dist/operations/pages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/operations/pages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;EAIxB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;EAE3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AAEH,eAAO,MAAM,mBAAmB,gDAAe,CAAC;AAGhD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQtG;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAMhG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGtG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAUtG;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAK/E"}
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/operations/pages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,aAAa,CAAC;AAInE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAa3B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;EAOxB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;EAE3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAa3B,CAAC;AAEH,eAAO,MAAM,mBAAmB,gDAAe,CAAC;AAGhD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,cAAc,CAAC,CASzB;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAQhG;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,cAAc,CAAC,CAUzB;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CA0B/E"}

package/dist/operations/pages.js

@@ -4,12 +4,22 @@ import { textResult } from "../types.js";
 export const CreatePageSchema = z.object({
     title: z.string().describe("Page title"),
     markdown: z.string().optional().describe("Markdown content for the page"),
-    uid: z.string().optional(),
+    uid: z
+        .string()
+        .optional()
+        .describe("Custom UID to assign to the new page. Omit to let Roam auto-generate one (recommended)"),
+    childrenViewType: z
+        .enum(["document", "bullet", "numbered"])
+        .optional()
+        .describe("How children are displayed (document, bullet, or numbered)"),
 });
 export const GetPageSchema = z.object({
     title: z.string().optional().describe("Page title (alternative to uid)"),
     uid: z.string().optional().describe("Page UID"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (omit for full tree)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (omit for full tree)"),
 });
 export const DeletePageSchema = z.object({
     uid: z.string().describe("Page UID to delete"),
@@ -17,21 +27,31 @@ export const DeletePageSchema = z.object({
 export const UpdatePageSchema = z.object({
     uid: z.string().describe("Page UID"),
     title: z.string().optional().describe("New page title"),
-    childrenViewType: z.enum(["document", "bullet", "numbered"]).optional().describe("How children are displayed (document, bullet, or numbered)"),
-    mergePages: z.boolean().optional().describe("If true, merge with existing page when renaming to a title that already exists (default: false)"),
+    childrenViewType: z
+        .enum(["document", "bullet", "numbered"])
+        .optional()
+        .describe("How children are displayed (document, bullet, or numbered)"),
+    mergePages: z
+        .boolean()
+        .optional()
+        .describe("If true, merge with existing page when renaming to a title that already exists (default: false)"),
 });
 export const GetGuidelinesSchema = z.object({});
 export async function createPage(client, params) {
+    const page = { title: params.title };
+    if (params.uid !== undefined)
+        page.uid = params.uid;
+    if (params.childrenViewType !== undefined)
+        page["children-view-type"] = params.childrenViewType;
     const response = await client.call("data.page.fromMarkdown", [
-        {
-            page: { title: params.title, uid: params.uid },
-            "markdown-string": params.markdown,
-        },
+        { page, "markdown-string": params.markdown },
     ]);
     return textResult(response.result ?? { uid: "" });
 }
 export async function getPage(client, params) {
-    const apiParams = params.uid ? { uid: params.uid } : { title: params.title };
+    const apiParams = params.uid
+        ? { uid: params.uid }
+        : { title: params.title };
     if (params.maxDepth !== undefined)
         apiParams.maxDepth = params.maxDepth;
     const response = await client.call("data.ai.getPage", [apiParams]);
@@ -55,5 +75,17 @@ export async function updatePage(client, params) {
 }
 export async function getGuidelines(client) {
     const response = await client.call("data.ai.getGraphGuidelines", []);
-    return textResult(response.result ?? { guidelines: null, starredPages: [] });
+    const result = response.result ?? {
+        guidelines: null,
+        starredPages: [],
+        todaysDailyNotePage: null,
+    };
+    const dnpTitle = result.todaysDailyNotePage;
+    const nextSteps = dnpTitle
+        ? `Start by reading today's daily note page ("${dnpTitle}") with get_page — this is the user's primary workspace for the day. If you need more context, call search with an empty query for recently edited and viewed content. Skip these orientation steps only when the user has already given you a specific task to execute (e.g. "create a page called X").`
+        : `Start by calling search with an empty query to see recently edited and viewed content. Skip this only when the user has already given you a specific task to execute.`;
+    return textResult({
+        ...result,
+        nextSteps,
+    });
 }

package/dist/operations/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/operations/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,aAAa,CAAC;AAKjE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;EAStB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wBAAsB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA2B5F"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/operations/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,aAAa,CAAC;AAKjE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BtB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wBAAsB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA2B5F"}

package/dist/operations/query.js

@@ -3,14 +3,32 @@ import { textResult } from "../types.js";
 // Schema for executing Roam queries ({{query: }} or {{[[query]]: }} blocks, NOT Datalog)
 // Supports two modes: UID mode (execute existing query block) or Query mode (raw query string)
 export const QuerySchema = z.object({
-    uid: z.string().optional().describe("UID of a block containing {{query: ...}} or {{[[query]]: ...}} - uses the block's saved display settings and filters"),
-    query: z.string().optional().describe("Raw Roam query string (e.g., \"{and: [[TODO]] {not: [[DONE]]}}\") - NOT Datalog - results are flat list, no user filters applied"),
-    sort: z.enum(["created-date", "edited-date", "daily-note-date"]).optional().describe("Sort order (only for query mode, default: created-date)"),
-    sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort direction (only for query mode, default: desc)"),
-    includePath: z.boolean().optional().describe("Include breadcrumb path in results (only for query mode, default: true)"),
+    uid: z
+        .string()
+        .optional()
+        .describe("UID of a block containing {{query: ...}} or {{[[query]]: ...}} - uses the block's saved display settings and filters"),
+    query: z
+        .string()
+        .optional()
+        .describe('Raw Roam query string (e.g., "{and: [[TODO]] {not: [[DONE]]}}") - NOT Datalog - results are flat list, no user filters applied'),
+    sort: z
+        .enum(["created-date", "edited-date", "daily-note-date"])
+        .optional()
+        .describe("Sort order (only for query mode, default: created-date)"),
+    sortOrder: z
+        .enum(["asc", "desc"])
+        .optional()
+        .describe("Sort direction (only for query mode, default: desc)"),
+    includePath: z
+        .boolean()
+        .optional()
+        .describe("Include breadcrumb path in results (only for query mode, default: true)"),
     offset: z.coerce.number().optional().describe("Skip first N results (default: 0)"),
     limit: z.coerce.number().optional().describe("Max results to return (default: 20)"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (default: 1)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (default: 1)"),
 });
 export async function query(client, params) {
     // Validate: exactly one of uid or query must be provided

package/dist/operations/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/operations/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAA4B,cAAc,EAAE,MAAM,aAAa,CAAC;AAI5E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;EAOvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;EAEhC,CAAC;AAGH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,wBAAsB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAY9F;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAKzB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/operations/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAIV,cAAc,EACf,MAAM,aAAa,CAAC;AAIrB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;EAoBvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;EAOhC,CAAC;AAGH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,wBAAsB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAc9F;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAKzB"}

package/dist/operations/search.js

@@ -2,15 +2,29 @@ import { z } from "zod";
 import { textResult } from "../types.js";
 // Schemas
 export const SearchSchema = z.object({
-    query: z.string().describe("Search query"),
-    scope: z.enum(["pages", "blocks", "all"]).optional().describe("Search scope: 'pages' for page titles only, 'blocks' for block content only, 'all' for both (default: 'all')"),
+    query: z
+        .string()
+        .describe("Search query — use empty string to get recently edited and viewed content"),
+    scope: z
+        .enum(["pages", "blocks", "all"])
+        .optional()
+        .describe("Search scope: 'pages' for page titles only, 'blocks' for block content only, 'all' for both (default: 'all')"),
     offset: z.coerce.number().optional().describe("Skip first N results (default: 0)"),
     limit: z.coerce.number().optional().describe("Max results (default: 20)"),
-    includePath: z.boolean().optional().describe("Include breadcrumb path to each result (default: true)"),
-    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (default: 0)"),
+    includePath: z
+        .boolean()
+        .optional()
+        .describe("Include breadcrumb path to each result (default: true)"),
+    maxDepth: z.coerce
+        .number()
+        .optional()
+        .describe("Max depth of children to include in markdown (default: 0)"),
 });
 export const SearchTemplatesSchema = z.object({
-    query: z.string().optional().describe("Keywords to filter templates by name (case-insensitive). Try relevant keywords first before listing all."),
+    query: z
+        .string()
+        .optional()
+        .describe("Keywords to filter templates by name (case-insensitive). Try relevant keywords first before listing all."),
 });
 export async function search(client, params) {
     const apiParams = {
@@ -22,12 +36,14 @@ export async function search(client, params) {
     };
     if (params.maxDepth !== undefined)
         apiParams.maxDepth = params.maxDepth;
-    const response = await client.call("data.ai.search", [apiParams]);
+    const response = await client.call("data.ai.search", [
+        apiParams,
+    ]);
     return textResult(response.result ?? { total: 0, results: [] });
 }
 export async function searchTemplates(client, params) {
     const response = await client.call("data.ai.searchTemplates", [
         { query: params.query },
     ]);
-    return textResult(response.result ?? []);
+    return textResult(response.result ?? { results: [] });
 }

package/dist/roam-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roam-api.d.ts","sourceRoot":"","sources":["../src/roam-api.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CACtD;AAMD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,EAAE,CAAC,CAc3B;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAehC;AAMD,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7C"}
+{"version":3,"file":"roam-api.d.ts","sourceRoot":"","sources":["../src/roam-api.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CACtD;AAMD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAclF;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAehC;AAMD,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7C"}

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAkC,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8BzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,EAAE,QAAQ,CAAC;CAChB;AAGD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAmL7E,eAAO,MAAM,KAAK,EAAE,cAAc,EAGjC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE;AA0FD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC,CA+HzB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAkC,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA+EzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,EAAE,QAAQ,CAAC;CAChB;AAGD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAsN7E,eAAO,MAAM,KAAK,EAAE,cAAc,EAA+C,CAAC;AAElF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE;AAuFD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC,CAyIzB"}

package/dist/tools.js

@@ -3,15 +3,19 @@ import { RoamError } from "./types.js";
 import { RoamClient } from "./client.js";
 import { resolveGraph, getPort, updateGraphTokenStatus } from "./graph-resolver.js";
 import { CreatePageSchema, GetPageSchema, DeletePageSchema, UpdatePageSchema, GetGuidelinesSchema, createPage, getPage, deletePage, updatePage, getGuidelines, } from "./operations/pages.js";
-import { CreateBlockSchema, GetBlockSchema, UpdateBlockSchema, DeleteBlockSchema, MoveBlockSchema, GetBacklinksSchema, createBlock, getBlock, updateBlock, deleteBlock, moveBlock, getBacklinks, } from "./operations/blocks.js";
-import { SearchSchema, SearchTemplatesSchema, search, searchTemplates } from "./operations/search.js";
+import { CreateBlockSchema, GetBlockSchema, UpdateBlockSchema, DeleteBlockSchema, MoveBlockSchema, GetBacklinksSchema, AddCommentSchema, GetCommentsSchema, createBlock, getBlock, updateBlock, deleteBlock, moveBlock, getBacklinks, addComment, getComments, } from "./operations/blocks.js";
+import { SearchSchema, SearchTemplatesSchema, search, searchTemplates, } from "./operations/search.js";
 import { QuerySchema, query } from "./operations/query.js";
+import { DatalogQuerySchema, datalogQuery } from "./operations/datalog.js";
 import { GetOpenWindowsSchema, GetSelectionSchema, OpenMainWindowSchema, OpenSidebarSchema, getOpenWindows, getSelection, openMainWindow, openSidebar, } from "./operations/navigation.js";
-import { FileGetSchema, FileUploadSchema, FileDeleteSchema, getFile, uploadFile, deleteFile } from "./operations/files.js";
-import { ListGraphsSchema, SetupNewGraphSchema, listGraphs, setupNewGraph } from "./operations/graphs.js";
+import { FileGetSchema, FileUploadSchema, FileDeleteSchema, getFile, uploadFile, deleteFile, } from "./operations/files.js";
+import { ListGraphsSchema, SetupNewGraphSchema, listGraphs, setupNewGraph, } from "./operations/graphs.js";
 // Common schema for graph parameter (used by most tools)
 const GraphSchema = z.object({
-    graph: z.string().optional().describe("Graph nickname or name (optional - auto-selects if only one graph is configured)"),
+    graph: z
+        .string()
+        .optional()
+        .describe("Graph nickname or name (optional - auto-selects if only one graph is configured)"),
 });
 // Helper to extend any schema with graph parameter
 function withGraph(schema) {
@@ -46,32 +50,44 @@ const graphManagementTools = [
 const GUIDELINES_NOTE = "\n\nNote: Call get_graph_guidelines first when starting to work with a graph.";
 // Content Tools (require graph/client)
 const contentTools = [
-    defineTool("get_graph_guidelines", "IMPORTANT: Call this tool first when starting to work with a graph, before performing any other operations. Returns user-defined instructions and preferences for AI agents. The user may have specified naming conventions, preferred structures, or constraints that should guide your behavior.", GetGuidelinesSchema, getGuidelines),
+    defineTool("get_graph_guidelines", "IMPORTANT: Call this tool first when starting to work with a graph, before performing any other operations. Returns user-defined instructions and preferences for AI agents. The user may have specified naming conventions, preferred structures, or constraints that should guide your behavior. After receiving the response, follow the nextSteps field — it contains orientation actions you should take before proceeding.", GetGuidelinesSchema, getGuidelines),
     defineTool("create_page", "Create a new page in Roam, optionally with markdown content." + GUIDELINES_NOTE, CreatePageSchema, createPage),
-    defineTool("create_block", "Create a new block under a parent, using markdown content. Supports nested bulleted lists - pass a markdown string with `- ` list items and indentation to create an entire block hierarchy in a single call." + GUIDELINES_NOTE, CreateBlockSchema, createBlock),
+    defineTool("create_block", "Create blocks from markdown content. Target by parentUid, pageTitle, or dailyNotePage (page created if needed). Use nestUnder to insert under a specific child block. Supports nested bulleted lists via markdown indentation." +
+        GUIDELINES_NOTE, CreateBlockSchema, createBlock),
     defineTool("update_block", "Update an existing block's content or properties." + GUIDELINES_NOTE, UpdateBlockSchema, updateBlock),
     defineTool("delete_block", "Delete a block and all its children." + GUIDELINES_NOTE, DeleteBlockSchema, deleteBlock),
     defineTool("move_block", "Move a block to a new location." + GUIDELINES_NOTE, MoveBlockSchema, moveBlock),
+    defineTool("add_comment", "Add a comment to a block (comment thread, NOT a child block). Prefer `comment` for simple text; use `commentMarkdown` for structured content. Same-day calls on the same block append to your existing comment." +
+        GUIDELINES_NOTE, AddCommentSchema, addComment),
+    defineTool("get_comments", "Get comments on a block with author, timestamps, and edit info. If singleEditableUid is set, the comment can be edited with update_block. Only works for blocks, not pages." +
+        GUIDELINES_NOTE, GetCommentsSchema, getComments),
     defineTool("delete_page", "Delete a page and all its contents." + GUIDELINES_NOTE, DeletePageSchema, deletePage),
-    defineTool("update_page", "Update a page's title or children view type. Set mergePages to true if renaming to a title that already exists." + GUIDELINES_NOTE, UpdatePageSchema, updatePage),
-    defineTool("search", "Search for pages and blocks by text. Returns paginated results with markdown content and optional breadcrumb paths." + GUIDELINES_NOTE, SearchSchema, search),
-    defineTool("search_templates", "Search Roam templates by name. When the user mentions 'my X template' or 'the X template', use this tool to find it. Templates are user-created reusable content blocks tagged with [[roam/templates]]. Returns template name, uid, and content as markdown." + GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates),
-    defineTool("roam_query", 'Execute a Roam query ({{query: }} or {{[[query]]: }} blocks, NOT Datalog). Two modes: (1) UID mode - pass a block UID containing a query component to run it with saved settings/filters; (2) Query mode - pass a raw query string like "{and: [[TODO]] {not: [[DONE]]}}". Returns paginated results with markdown content.' + GUIDELINES_NOTE, QuerySchema, query),
-    defineTool("get_page", "Get a page's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large pages." + GUIDELINES_NOTE, GetPageSchema, getPage),
-    defineTool("get_block", "Get a block's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large blocks." + GUIDELINES_NOTE, GetBlockSchema, getBlock),
-    defineTool("get_backlinks", "Get paginated backlinks (linked references) for a page or block, formatted as markdown. Returns total count and results with optional breadcrumb paths." + GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks),
+    defineTool("update_page", "Update a page's title or children view type. Set mergePages to true if renaming to a title that already exists." +
+        GUIDELINES_NOTE, UpdatePageSchema, updatePage),
+    defineTool("search", "Search for pages and blocks by text. Returns paginated results with markdown content and optional breadcrumb paths. Call with an empty query to get recently edited and viewed content — useful for understanding what the user is currently working on." +
+        GUIDELINES_NOTE, SearchSchema, search),
+    defineTool("search_templates", "Search Roam templates by name. When the user mentions 'my X template' or 'the X template', use this tool to find it. Templates are user-created reusable content blocks tagged with [[roam/templates]]. Returns template name, uid, and content as markdown." +
+        GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates),
+    defineTool("roam_query", 'Execute a Roam query ({{query: }} or {{[[query]]: }} blocks, NOT Datalog). Two modes: (1) UID mode - pass a block UID containing a query component to run it with saved settings/filters; (2) Query mode - pass a raw query string like "{and: [[TODO]] {not: [[DONE]]}}". Returns paginated results with markdown content.' +
+        GUIDELINES_NOTE, QuerySchema, query),
+    defineTool("datalog_query", "Execute a datomic-style datalog query against the graph's datascript database. Supported clauses: :find, :where, :in, and :timeout (ms). Inputs are positional parameters bound to :in variables after $. Write specific :where clauses to keep results bounded." +
+        GUIDELINES_NOTE, DatalogQuerySchema, datalogQuery),
+    defineTool("get_page", "Get a page's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large pages." +
+        GUIDELINES_NOTE, GetPageSchema, getPage),
+    defineTool("get_block", "Get a block's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large blocks." +
+        GUIDELINES_NOTE, GetBlockSchema, getBlock),
+    defineTool("get_backlinks", "Get paginated backlinks (linked references) for a page or block, formatted as markdown. Returns total count and results with optional breadcrumb paths." +
+        GUIDELINES_NOTE, GetBacklinksSchema, getBacklinks),
     defineTool("get_open_windows", "Get the current view in the main window and all open sidebar windows." + GUIDELINES_NOTE, GetOpenWindowsSchema, getOpenWindows),
     defineTool("get_selection", "Get the currently focused block and any multi-selected blocks." + GUIDELINES_NOTE, GetSelectionSchema, getSelection),
     defineTool("open_main_window", "Navigate to a page or block in the main window." + GUIDELINES_NOTE, OpenMainWindowSchema, openMainWindow),
     defineTool("open_sidebar", "Open a page or block in the right sidebar." + GUIDELINES_NOTE, OpenSidebarSchema, openSidebar),
     defineTool("file_get", "Fetch a file hosted on Roam (handles decryption for encrypted graphs)." + GUIDELINES_NOTE, FileGetSchema, getFile),
-    defineTool("file_upload", "Upload a file to Roam. Returns the Firebase storage URL. Usually you'll want to create a new block with the file as markdown: `![](url)`. Provide ONE of: filePath (preferred - local file, server reads directly), url (remote URL, server fetches), or base64 (raw data, fallback for sandboxed clients)." + GUIDELINES_NOTE, FileUploadSchema, uploadFile),
+    defineTool("file_upload", "Upload a file to Roam. Returns the Firebase storage URL. Usually you'll want to create a new block with the file as markdown: `![](url)`. Provide ONE of: filePath (preferred - local file, server reads directly), url (remote URL, server fetches), or base64 (raw data, fallback for sandboxed clients)." +
+        GUIDELINES_NOTE, FileUploadSchema, uploadFile),
     defineTool("file_delete", "Delete a file hosted on Roam." + GUIDELINES_NOTE, FileDeleteSchema, deleteFile),
 ];
-export const tools = [
-    ...graphManagementTools,
-    ...contentTools,
-];
+export const tools = [...graphManagementTools, ...contentTools];
 export function findTool(name) {
     return tools.find((t) => t.name === name);
 }
@@ -87,19 +103,13 @@ function prependGraphInfo(result, nickname) {
     if (first.type === "text") {
         return {
             ...result,
-            content: [
-                { ...first, text: `${prefix}\n\n${first.text}` },
-                ...content.slice(1),
-            ],
+            content: [{ ...first, text: `${prefix}\n\n${first.text}` }, ...content.slice(1)],
         };
     }
     // For image or other content types, prepend a text block
     return {
         ...result,
-        content: [
-            { type: "text", text: prefix },
-            ...content,
-        ],
+        content: [{ type: "text", text: prefix }, ...content],
     };
 }
 /**
@@ -206,9 +216,13 @@ export async function routeToolCall(toolName, args) {
             if (tokenInfoResult.status === "revoked") {
                 if (resolvedGraph.lastKnownTokenStatus !== "revoked") {
                     try {
-                        await updateGraphTokenStatus(resolvedGraph.nickname, { lastKnownTokenStatus: "revoked" });
+                        await updateGraphTokenStatus(resolvedGraph.nickname, {
+                            lastKnownTokenStatus: "revoked",
+                        });
+                    }
+                    catch {
+                        // best-effort status update
                     }
-                    catch { }
                 }
                 const baseResult = actionSettled.status === "fulfilled"
                     ? actionSettled.value
@@ -239,7 +253,9 @@ export async function routeToolCall(toolName, args) {
                             lastKnownTokenStatus: "active",
                         });
                     }
-                    catch { }
+                    catch {
+                        // best-effort status update
+                    }
                 }
                 if (!result.isError) {
                     const enriched = enrichResultWithTokenInfo(result, info);
@@ -252,7 +268,9 @@ export async function routeToolCall(toolName, args) {
                 try {
                     await updateGraphTokenStatus(resolvedGraph.nickname, { lastKnownTokenStatus: "active" });
                 }
-                catch { }
+                catch {
+                    // best-effort status update
+                }
             }
             if (!result.isError) {
                 return prependGraphInfo(result, resolvedGraph.nickname);

package/dist/types.d.ts

@@ -112,7 +112,7 @@ export declare class RoamError extends Error {
     constructor(message: string, code?: ErrorCode | undefined, context?: Record<string, unknown> | undefined);
 }
 export declare const CONFIG_VERSION = 1;
-export declare const EXPECTED_API_VERSION = "1.1.0";
+export declare const EXPECTED_API_VERSION = "1.1.2";
 export interface RoamApiError {
     message: string;
     code?: string;
@@ -188,14 +188,64 @@ export interface SearchResult {
     type?: "page";
 }
 export interface SearchResponse {
+    queriedAt?: string;
     total: number;
     results: SearchResult[];
 }
+export interface RecentlyOpenedBlock {
+    uid: string;
+    string: string;
+    openedAt: string;
+    path?: string;
+}
+export interface RecentlyOpenedItem {
+    uid: string;
+    title: string;
+    type: "page";
+    openedAt: string;
+    visitCount: number;
+    totalDurationMs: number;
+    currentlyOpen?: boolean;
+    blocks?: RecentlyOpenedBlock[];
+}
+export interface DailyNotePagesViewItem {
+    type: "dailyNotePagesView";
+    totalDurationMs: number;
+    currentlyOpen: boolean;
+}
+export interface RecentlyEditedPage {
+    uid: string;
+    title: string;
+    editedBy: string;
+    editedAt: string;
+}
+export interface SearchSuggestionsResponse {
+    queriedAt?: string;
+    suggestions: {
+        recentlyOpenedByUser: (RecentlyOpenedItem | DailyNotePagesViewItem)[];
+        recentlyEditedPages: RecentlyEditedPage[];
+    };
+}
 export interface Template {
     name: string;
     uid: string;
     content: string;
 }
+export interface SearchTemplatesResponse {
+    queriedAt?: string;
+    results: Template[];
+}
+export interface GetPageResponse {
+    uid: string;
+    markdown: string;
+    queriedAt: string;
+}
+export interface GetBlockResponse {
+    uid: string;
+    markdown: string;
+    path: string;
+    queriedAt: string;
+}
 export interface QueryResult {
     uid: string;
     markdown: string;
@@ -203,6 +253,7 @@ export interface QueryResult {
     type?: "page";
 }
 export interface QueryResponse {
+    queriedAt?: string;
     total: number;
     results: QueryResult[];
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACpG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAGzD;AAGD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAE1E;AAGD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAE3D;AAOD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAG7C,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;AAM/D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAsB5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAGhE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7C;AAOD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;CAkCb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAGrE,qBAAa,SAAU,SAAQ,KAAK;aAGhB,IAAI,CAAC,EAAE,SAAS;aAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjD,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,SAAS,YAAA,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAUD,eAAO,MAAM,cAAc,IAAI,CAAC;AAYhC,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAG5C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAIhF;AAGD,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAGD,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACvD,oBAAoB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;CAC3D;AAGD,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC;IACnB,oBAAoB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;CAC3D;AAID,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CAClC;AAGD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;AAErF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAGD,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,KAAK,GACL,OAAO,GACP,SAAS,GACT,KAAK,GACL,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAGD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAGD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAGD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAGD,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QACX,oBAAoB,EAAE,CAAC,kBAAkB,GAAG,sBAAsB,CAAC,EAAE,CAAC;QACtE,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;KAC3C,CAAC;CACH;AAGD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAGD,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB;AAGD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAGD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAG1B,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/types.js

@@ -16,14 +16,24 @@ export function errorResult(message) {
 // Graph names can only contain alphanumeric characters, hyphens, and underscores
 const GRAPH_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
 export const GraphConfigSchema = z.object({
-    name: z.string().regex(GRAPH_NAME_PATTERN, "Graph name can only contain letters, numbers, hyphens, and underscores").describe("Actual graph name in Roam"),
+    name: z
+        .string()
+        .regex(GRAPH_NAME_PATTERN, "Graph name can only contain letters, numbers, hyphens, and underscores")
+        .describe("Actual graph name in Roam"),
     type: z.enum(["hosted", "offline"]).default("hosted").describe("Graph type"),
     token: z.string().startsWith("roam-graph-local-token-").describe("Local API token"),
-    nickname: z.string()
+    nickname: z
+        .string()
         .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "Nickname must be lowercase letters, numbers, and hyphens")
         .describe("Short identifier for the graph (lowercase, hyphens, no spaces)"),
-    accessLevel: z.enum(["read-only", "read-append", "full"]).optional().describe("Token access level"),
-    lastKnownTokenStatus: z.enum(["active", "revoked"]).optional().describe("Token validity status from last sync with Roam"),
+    accessLevel: z
+        .enum(["read-only", "read-append", "full"])
+        .optional()
+        .describe("Token access level"),
+    lastKnownTokenStatus: z
+        .enum(["active", "revoked"])
+        .optional()
+        .describe("Token validity status from last sync with Roam"),
 });
 export const RoamMcpConfigSchema = z.object({
     version: z.number().int().positive().optional(),
@@ -81,8 +91,17 @@ export class RoamError extends Error {
 // so a newer version may write a config that an older version can't parse.
 // Bump this when the config schema changes in a breaking way.
 export const CONFIG_VERSION = 1;
-// API version this client expects (major.minor must match)
-export const EXPECTED_API_VERSION = "1.1.0";
+// API version this client expects. Sent as `expectedApiVersion` in every request.
+// Roam's compatibility check compares major.minor ONLY — patch is ignored.
+// So 1.1.0, 1.1.1, 1.1.2 are all compatible; 1.1.x and 1.2.x are NOT.
+//
+// When to bump:
+// - Patch bump on Roam side (e.g. 1.1.1 → 1.1.2): no change needed here, but
+//   you can bump for cosmetic alignment.
+// - Minor bump on Roam side (e.g. 1.1.x → 1.2.0): MUST bump here too, or all
+//   requests will fail with VERSION_MISMATCH.
+// - This is independent of the npm package version (0.x.y in package.json).
+export const EXPECTED_API_VERSION = "1.1.2";
 // Helper to extract error message from RoamResponse
 export function getErrorMessage(error) {
     if (!error)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roam-research/roam-tools-core",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Core library for Roam Research tools",
   "repository": {
     "type": "git",