v2.17.0 feat: add CLI commands for full page view and subpages (#15)

- roam get full <title>: full page view with content + linked references
- roam get subpages <prefix>: namespace-based sub-page listing
- Update README, CHANGELOG, and CLI reference
- Bump version to v2.17.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2b3pro

CHANGELOG.md

@@ -1,10 +1,21 @@
 # Changelog
 
-### v2.16.1 (2026-03-17)
+### v2.17.0 (2026-03-17)
+- **Feature:** Add `roam_fetch_page_full_view` tool + CLI `roam get full` — full page view with content + linked references (#15)
+  - Page's own content (blocks + heading structure)
+  - All linked references grouped by source page with breadcrumb context
+  - Children of each referring block expanded to configurable depth (default 4)
+  - `max_references` safety valve (default 200) prevents timeouts on heavily-referenced pages
+  - CLI: `roam get full "Page Title" [-d depth] [-n max-refs]`
+- **Feature:** Add `roam_get_subpages` tool + CLI `roam get subpages` — namespace-based sub-page listing
+  - Lists pages under a prefix (e.g. "Project/", "Framework/")
+  - Optional `filter_tag` to filter sub-pages containing a specific tag
+  - Optional `include_content` to include full block content
+  - CLI: `roam get subpages "Prefix" [--filter-tag tag] [--content]`
+- **Refactor:** Extract `fetchChildrenByDepth` into shared helper (`src/tools/helpers/fetch-children.ts`)
+- **Fix:** `convertToRoamActions` now correctly passes through `'first'`/`'last'` order strings instead of replacing with index
 - **Fix:** CLI `roam save <file.md> -p <page>` ignored `-p` flag and created a page from the filename
-  - When a file was passed as input, the command unconditionally entered PAGE MODE even when `-p` specified a target page
-  - Now file inputs with `-p` correctly append content to the specified page instead of deriving a page title from the filename
-  - Affected: any pipeline using `roam save <file> -p <page>` (e.g., AIIntel nightly delivery)
+- **Fix:** Typo in `roam_add_content` schema description
 
 ### v2.16.0 (2026-03-16)
 - **Feature:** Renamed `roam_fetch_block_with_children` → `roam_fetch_block` with bidirectional traversal

README.md

@@ -88,9 +88,11 @@ The MCP server exposes these tools to AI assistants (like Claude), enabling them
 | Tool Name | Description |
 | :--- | :--- |
 | `roam_fetch_page_by_title` | Fetch page content by title. |
+| `roam_fetch_page_full_view` | Fetch a page's content plus all linked references with breadcrumb context and children. |
 | `roam_fetch_block` | Fetch a block by UID with optional children (depth) and/or ancestors (up to page root). |
 | `roam_create_page` | Create new pages, optionally with mixed text and table content. |
 | `roam_update_page_markdown` | Update a page using smart diff (preserves block UIDs). |
+| `roam_get_subpages` | List sub-pages under a namespace prefix (e.g. "Project/") with optional tag filter. |
 | `roam_search_by_text` | Full-text search across the graph or within specific pages. Supports namespace prefix search for page titles. |
 | `roam_search_block_refs` | Find blocks that reference a page, tag, or block UID. |
 | `roam_search_by_status` | Find TODO or DONE items. |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "2.16.1",
+  "version": "2.17.0",
   "description": "MCP server and CLI for Roam Research",
   "private": false,
   "repository": {

src/cli/ROAM-CLI-REFERENCE_LLM.md

@@ -1,7 +1,7 @@
 ---
-version: 2.16.0
+version: 2.17.0
 date: 2026-01-12
-last_modified: 2026-03-16
+last_modified: 2026-03-17
 ---
 
 # Roam CLI Reference (LLM-Optimized)
@@ -23,6 +23,8 @@ roam batch -g system --write-key "$ROAM_SYSTEM_WRITE_KEY" commands.json
 roam get <title|today|yesterday|tomorrow>       # page by title
 roam get <9-char-uid>                           # block by UID
 roam get page <uid|url|title>                   # explicit page (URL/UID/title)
+roam get full <title>                           # full view: content + linked refs
+roam get subpages <prefix>                      # list namespace sub-pages
 roam get --uid <title>                          # resolve title→UID only
 roam get --todo [-p <page>] [-i terms] [-e terms]
 roam get --done [-p <page>]
@@ -32,7 +34,10 @@ roam get --text <text> [-p <page>]
 
 Options: `-j` json, `-d N` depth (0=no children), `-a` ancestors (chain to page root), `-r [N]` expand refs, `-f` flat, `--sort created|modified|page`, `--group-by page|tag`
 
-**Subcommand:** `roam get page <identifier>` - fetches page by UID, Roam URL, or title explicitly
+**Subcommands:**
+- `roam get page <identifier>` - fetches page by UID, Roam URL, or title explicitly
+- `roam get full <title>` - full page view: content + all linked references with breadcrumb context. Options: `-d N` depth (default 4), `-n N` max refs (default 200)
+- `roam get subpages <prefix>` - list sub-pages under namespace prefix (e.g. "Project/"). Options: `--filter-tag <tag>`, `--content`
 
 ### `roam search` - Query
 
@@ -145,6 +150,8 @@ roam status --json                              # for scripting
 | Multiple tags (OR) | `roam get --tag Tag1 --tag Tag2 --any` |
 | Block + ancestors | `roam get <uid> -a` |
 | Ancestors only | `roam get <uid> -a -d 0` |
+| Full view + backlinks | `roam get full "Page"` |
+| List sub-pages | `roam get subpages "Prefix"` |
 | Quick note | `roam save "Note"` |
 | Note to page | `roam save "Note" -p "Page"` |
 | Under heading | `roam save --parent "## Section" "Note"` |

src/cli/commands/get.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { PageOperations } from '../../tools/operations/pages.js';
 import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
 import { SearchOperations } from '../../tools/operations/search/index.js';
+import { FullPageViewOperations } from '../../tools/operations/full-page-view.js';
 import {
   formatPageOutput,
   formatBlockOutput,
@@ -248,6 +249,86 @@ Examples:
     });
 }
 
+/**
+ * Create the 'full' subcommand for full page view (content + linked references)
+ */
+function createFullSubcommand(): Command {
+  return new Command('full')
+    .description('Fetch full page view: content + linked references with breadcrumb context')
+    .argument('<title>', 'Page title (for date pages use "January 2nd, 2025")')
+    .option('-d, --depth <n>', 'Child depth for referring blocks (default: 4)', '4')
+    .option('-n, --max-refs <n>', 'Max linked references (default: 200)', '200')
+    .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+    .option('--debug', 'Show debug information')
+    .addHelpText('after', `
+Examples:
+  roam get full "Project Notes"              # Full view with backlinks
+  roam get full "TODO" -n 50                 # Cap references at 50
+  roam get full "Meeting Notes" -d 2         # Shallow children depth
+`)
+    .action(async (title: string, options: GraphOptions & { depth?: string; maxRefs?: string; debug?: boolean }) => {
+      try {
+        const resolvedTitle = resolveRelativeDate(title);
+        const depth = parseInt(options.depth || '4', 10);
+        const maxRefs = parseInt(options.maxRefs || '200', 10);
+
+        if (options.debug) {
+          printDebug('Title', resolvedTitle);
+          printDebug('Children depth', depth);
+          printDebug('Max references', maxRefs);
+          printDebug('Graph', options.graph || 'default');
+        }
+
+        const graph = resolveGraph(options, false);
+        const pageOps = new PageOperations(graph);
+        const fullViewOps = new FullPageViewOperations(graph, pageOps);
+        const result = await fullViewOps.fetchPageFullView(resolvedTitle, depth, maxRefs);
+        console.log(result);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        exitWithError(message);
+      }
+    });
+}
+
+/**
+ * Create the 'subpages' subcommand for namespace-based sub-page listing
+ */
+function createSubpagesSubcommand(): Command {
+  return new Command('subpages')
+    .description('List sub-pages under a namespace prefix (e.g. "Project/", "Framework/")')
+    .argument('<prefix>', 'Namespace prefix (trailing "/" added automatically)')
+    .option('--filter-tag <tag>', 'Only sub-pages containing this tag')
+    .option('--content', 'Include each sub-page\'s block content')
+    .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+    .option('--debug', 'Show debug information')
+    .addHelpText('after', `
+Examples:
+  roam get subpages "Project"                # List all Project/* pages
+  roam get subpages "Framework" --content    # With block content
+  roam get subpages "Project" --filter-tag active  # Only active projects
+`)
+    .action(async (prefix: string, options: GraphOptions & { filterTag?: string; content?: boolean; debug?: boolean }) => {
+      try {
+        if (options.debug) {
+          printDebug('Prefix', prefix);
+          printDebug('Filter tag', options.filterTag || 'none');
+          printDebug('Include content', options.content || false);
+          printDebug('Graph', options.graph || 'default');
+        }
+
+        const graph = resolveGraph(options, false);
+        const pageOps = new PageOperations(graph);
+        const fullViewOps = new FullPageViewOperations(graph, pageOps);
+        const result = await fullViewOps.fetchSubPages(prefix, options.filterTag, options.content);
+        console.log(result);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        exitWithError(message);
+      }
+    });
+}
+
 export function createGetCommand(): Command {
   const cmd = new Command('get')
     .description('Fetch pages, blocks, or TODO/DONE items with optional ref expansion')
@@ -708,6 +789,8 @@ Note: For flat results with UIDs, use 'roam search' instead.
 
   // Add subcommands
   cmd.addCommand(createPageSubcommand());
+  cmd.addCommand(createFullSubcommand());
+  cmd.addCommand(createSubpagesSubcommand());
 
   return cmd;
 }