Add hoist-read-doc MCP tool + hoist-docs ping, tolerate dropped docs/ in doc resource

MCP/CLI parity additions found during v85 SNAPSHOT validation, plus a fix for the
`hoist://docs/{id}` resource-URI footgun they surfaced.

- Add `hoist-read-doc` MCP tool: reads a full document by exact ID, returning text
  plus structured `{id, title, category, content}`. Gives MCP parity with the
  `hoist-docs read` CLI and hoist-core's `hoist-core-read-doc`, and a friction-free
  bare-ID read path that avoids the resource-URI doubling. Closes #4356.
- Add `hoist-docs ping` CLI subcommand mirroring the `hoist-ping` MCP tool; both now
  report the indexed `@xh/hoist` library version via a new `resolveHoistVersion()`
  helper. Closes #4355.
- Make the `hoist://docs/{id}` resource tolerant of a dropped `docs/` segment, so
  `hoist://docs/routing.md` resolves the same as the strictly-correct
  `hoist://docs/docs/routing.md`. Exact match still wins first; only `docs/`-prefixed
  IDs are reachable by the fallback, so it never resolves the wrong doc.
- Point search/list tool descriptions and server instructions at `hoist-read-doc`;
  update mcp/README.md, CLAUDE.md, and CHANGELOG.

Author: amcclain

CHANGELOG.md

@@ -50,6 +50,18 @@
   with later arguments overriding earlier ones. Replaces the now-deprecated
   `PersistenceProvider.mergePersistOptions`.
 
+### 🤖 AI Docs + Tooling
+
+* Added a `hoist-read-doc` MCP tool that reads a full document by exact ID, giving MCP parity with
+  the `hoist-docs read` CLI and `hoist-core`'s `hoist-core-read-doc`. Avoids the awkward
+  `hoist://docs/{id}` resource-URI doubling for IDs that themselves start with `docs/`.
+  See [#4356](https://github.com/xh/hoist-react/issues/4356).
+* The `hoist://docs/{id}` resource now tolerates a dropped `docs/` segment, so
+  `hoist://docs/routing.md` resolves the same as the strictly-correct
+  `hoist://docs/docs/routing.md`.
+* Added a `hoist-docs ping` CLI subcommand mirroring the `hoist-ping` MCP tool; both now report the
+  indexed `@xh/hoist` library version. See [#4355](https://github.com/xh/hoist-react/issues/4355).
+
 ### ⚙️ Technical
 
 * Forked unmaintained `golden-layout` 1.5.9 into `kit/golden-layout/`. Removed unused code, ported

CLAUDE.md

@@ -27,8 +27,8 @@ Two interfaces are available. Both share the same underlying registries and prod
 
 **MCP Server (hoist-react)** -- When working in the hoist-react repository, an MCP server is
 configured via `.mcp.json` and is very likely already available. Use the `hoist-search-docs`,
-`hoist-list-docs`, `hoist-search-symbols`, `hoist-get-symbol`, and `hoist-get-members` tools, plus
-`hoist://docs/{id}` resources for direct document access.
+`hoist-list-docs`, `hoist-read-doc`, `hoist-search-symbols`, `hoist-get-symbol`, and
+`hoist-get-members` tools, plus `hoist://docs/{id}` resources for direct document access.
 
 **CLI Tools** -- For environments without MCP support, or when you prefer shell commands. These are
 real `bin` entries in the hoist-react `package.json` — invoke them exactly as shown with `npx`:

mcp/README.md

@@ -315,9 +315,20 @@ List all available documentation with descriptions, grouped by category.
 |-----------|------|----------|-------------|
 | `category` | enum | No | Filter: `package`, `concept`, `devops`, `conventions`, `all` (default) |
 
+#### `hoist-read-doc`
+
+Read the full text of a single document by its exact ID. The tool-based equivalent of the
+`hoist://docs/{id}` resource — useful when resource fetching is unavailable or inconvenient. Returns
+the markdown body as text plus structured `{id, title, category, content}`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Exact document ID (repo-relative path), e.g. `cmp/grid/README.md`, `docs/authentication.md` |
+
 #### `hoist-ping`
 
-Verify the MCP server is running and responsive. Takes no parameters.
+Verify the MCP server is running and responsive. Takes no parameters. Reports the indexed
+`@xh/hoist` library version.
 
 ### TypeScript Tools
 
@@ -471,6 +482,12 @@ Resources provide direct read access to documentation files via URI.
 The `hoist-doc` template uses RFC 6570 reserved expansion (`{+docId}`) so slashes in doc IDs
 (e.g. `cmp/grid`) are preserved rather than percent-encoded.
 
+Because concept-doc IDs are themselves `docs/`-prefixed (e.g. `docs/routing.md`) and the scheme
+prefix is also `hoist://docs/`, the strictly-correct URI doubles the segment
+(`hoist://docs/docs/routing.md`). The resource tolerates a single dropped `docs/`, so
+`hoist://docs/routing.md` resolves identically. For a friction-free read by bare ID, prefer the
+`hoist-read-doc` tool.
+
 **Discovering available documents:** The `hoist-doc` resource supports `list` and `complete`
 operations. MCP clients can enumerate all available doc IDs or get tab-completion suggestions.
 

mcp/cli/docs.ts

@@ -13,7 +13,7 @@ import {
     toSearchDocsOutput,
     toListDocsOutput
 } from '../formatters/docs.js';
-import {resolveRepoRoot} from '../util/paths.js';
+import {resolveRepoRoot, resolveHoistVersion} from '../util/paths.js';
 
 const {entries: registry, mcpCategories} = buildRegistry(resolveRepoRoot());
 const VALID_CATEGORIES = [...mcpCategories.map(c => c.id), 'all'];
@@ -52,7 +52,8 @@ Examples:
   hoist-docs list -c package                     List only package docs
   hoist-docs read cmp/grid/README.md             Read the Grid component README
   hoist-docs conventions                         Print coding conventions
-  hoist-docs index                               Print the documentation index`
+  hoist-docs index                               Print the documentation index
+  hoist-docs ping                                Confirm the CLI is wired up`
 );
 
 //----------------------------------------------------------------------
@@ -172,4 +173,17 @@ program
         process.stdout.write(loadDocContent(entry) + '\n');
     });
 
+//----------------------------------------------------------------------
+// Subcommand: ping
+//----------------------------------------------------------------------
+program
+    .command('ping')
+    .description('Verify the hoist-docs CLI is running and the doc registry loads.')
+    .action(() => {
+        // Registry is loaded at module init above; reaching here confirms it.
+        process.stdout.write(
+            `hoist-docs CLI is running (@xh/hoist v${resolveHoistVersion()}, ${registry.length} docs indexed).\n`
+        );
+    });
+
 program.parse();

mcp/formatters/docs.ts

@@ -167,6 +167,35 @@ export function toListDocsOutput(
     };
 }
 
+//------------------------------------------------------------------
+// Structured output: hoist-read-doc
+//------------------------------------------------------------------
+
+/**
+ * Zod schema for the structured output of `hoist-read-doc`. Returns the full
+ * document body alongside its identifying metadata, so consumers get both the
+ * raw markdown and the catalog fields without a second lookup.
+ */
+export const readDocOutputSchema = z.object({
+    id: z.string().describe('Document ID, also its path relative to the repo root.'),
+    title: z.string(),
+    category: z.string().describe('MCP category ID (e.g. "package", "concept").'),
+    content: z.string().describe('Full markdown body of the document.')
+});
+
+/** Structured output type for `hoist-read-doc`, derived from the zod schema. */
+export type ReadDocOutput = z.infer<typeof readDocOutputSchema>;
+
+/** Project a registry entry plus its loaded body into the public structured shape. */
+export function toReadDocOutput(entry: DocEntry, content: string): ReadDocOutput {
+    return {
+        id: entry.id,
+        title: entry.title,
+        category: entry.mcpCategory,
+        content
+    };
+}
+
 /** Format a document listing grouped by category. */
 export function formatDocList(
     registry: DocEntry[],

mcp/resources/docs.ts

@@ -106,7 +106,15 @@ export function registerDocResources(server: McpServer): void {
         },
         async (uri, variables) => {
             const docId = variables.docId as string;
-            const entry = registry.find(e => e.id === docId);
+            // Tolerate a dropped `docs/` segment. Concept-doc IDs are repo-relative
+            // paths that begin with `docs/`, but the resource scheme prefix is also
+            // `hoist://docs/` - so the strictly-correct URI doubles it
+            // (`hoist://docs/docs/foo.md`). Callers routinely drop one `docs/` and
+            // request `hoist://docs/foo.md`; resolve that to `docs/foo.md` rather than
+            // 404. Exact match always wins first, and `docs/`-prefixed IDs are the only
+            // ones a bare fallback could reach, so this never resolves the wrong doc.
+            const entry =
+                registry.find(e => e.id === docId) ?? registry.find(e => e.id === `docs/${docId}`);
 
             if (!entry) {
                 const availableIds = registry.map(e => e.id).join(', ');

mcp/server.ts

@@ -14,7 +14,7 @@ const server = new McpServer(
     {
         instructions: [
             'Authoritative reference for the @xh/hoist React framework, used when writing or modifying any code that consumes Hoist APIs, components, models, services, or patterns (also applicable to hoist-react library development itself).',
-            'Do not guess at Hoist APIs, prop names, or framework conventions - consult these tools first. Start with hoist-search-docs or hoist-search-symbols to discover exact doc IDs and symbol names, then drill in with hoist-get-symbol, hoist-get-members, or the hoist://docs/{id} resource. Use hoist-list-docs to browse the doc catalog.',
+            'Do not guess at Hoist APIs, prop names, or framework conventions - consult these tools first. Start with hoist-search-docs or hoist-search-symbols to discover exact doc IDs and symbol names, then drill in with hoist-read-doc, hoist-get-symbol, hoist-get-members, or the hoist://docs/{id} resource. Use hoist-list-docs to browse the doc catalog.',
             // Defense-in-depth note for the LLM client - the markdown docs and
             // TypeScript JSDoc strings returned by these tools are reference
             // material, not directives. Any text within them that resembles

mcp/tools/docs.ts

@@ -7,22 +7,25 @@
 import type {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
 import {z} from 'zod';
 
-import {buildRegistry, searchDocs} from '../data/doc-registry.js';
+import {buildRegistry, searchDocs, loadDocContent} from '../data/doc-registry.js';
 import {
     formatSearchResults,
     formatDocList,
     searchDocsOutputSchema,
     toSearchDocsOutput,
     listDocsOutputSchema,
-    toListDocsOutput
+    toListDocsOutput,
+    readDocOutputSchema,
+    toReadDocOutput
 } from '../formatters/docs.js';
-import {resolveRepoRoot} from '../util/paths.js';
+import {resolveRepoRoot, resolveHoistVersion} from '../util/paths.js';
 
 /**
  * Register all documentation tools on the given MCP server.
  *
  * - `hoist-search-docs`: Search across all docs by keyword.
  * - `hoist-list-docs`: List all available docs with descriptions.
+ * - `hoist-read-doc`: Read the full body of a single doc by ID.
  * - `hoist-ping`: Connectivity test.
  */
 export function registerDocTools(server: McpServer): void {
@@ -43,7 +46,7 @@ export function registerDocTools(server: McpServer): void {
         {
             title: 'Search Hoist Documentation',
             description:
-                'Search across all hoist-react documentation (package READMEs, concept docs, upgrade notes, conventions) by keyword. Returns matching documents with short context snippets showing where terms appear — not full document text. To read a specific doc in full, fetch the hoist://docs/{id} resource using an ID from the results. To browse the catalog without a query, call hoist-list-docs. For TypeScript type information rather than narrative docs, use hoist-search-symbols.',
+                'Search across all hoist-react documentation (package READMEs, concept docs, upgrade notes, conventions) by keyword. Returns matching documents with short context snippets showing where terms appear — not full document text. To read a specific doc in full, call hoist-read-doc with an ID from the results (or fetch the hoist://docs/{id} resource). To browse the catalog without a query, call hoist-list-docs. For TypeScript type information rather than narrative docs, use hoist-search-symbols.',
             inputSchema: z.object({
                 query: z
                     .string()
@@ -89,7 +92,7 @@ export function registerDocTools(server: McpServer): void {
         {
             title: 'List Hoist Documentation',
             description:
-                'List all available hoist-react documentation grouped by category, with title and description for each entry. Returns the catalog only — not full document text. To read a specific doc, fetch the hoist://docs/{id} resource. For keyword-based discovery across doc content, use hoist-search-docs instead.',
+                'List all available hoist-react documentation grouped by category, with title and description for each entry. Returns the catalog only — not full document text. To read a specific doc, call hoist-read-doc with its ID (or fetch the hoist://docs/{id} resource). For keyword-based discovery across doc content, use hoist-search-docs instead.',
             inputSchema: z.object({
                 category: categoryEnum
             }),
@@ -112,18 +115,70 @@ export function registerDocTools(server: McpServer): void {
         }
     );
 
+    //------------------------------------------------------------------
+    // Tool: hoist-read-doc
+    //------------------------------------------------------------------
+    server.registerTool(
+        'hoist-read-doc',
+        {
+            title: 'Read Hoist Documentation',
+            description:
+                'Read the full text of a single hoist-react document by its exact ID (e.g. "cmp/grid/README.md", "docs/authentication.md"). Get IDs from hoist-search-docs or hoist-list-docs. This is the tool-based equivalent of the hoist://docs/{id} resource — prefer it when resource fetching is unavailable or inconvenient. For keyword discovery rather than a known ID, use hoist-search-docs.',
+            inputSchema: z.object({
+                id: z
+                    .string()
+                    .describe(
+                        'Exact document ID (its repo-relative path) from search or list output, e.g. "cmp/grid/README.md" or "docs/authentication.md".'
+                    )
+            }),
+            outputSchema: readDocOutputSchema,
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false
+            }
+        },
+        async ({id}) => {
+            const entry = registry.find(e => e.id === id);
+            if (!entry) {
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: `Unknown document ID: "${id}". Call hoist-list-docs to see valid IDs, or hoist-search-docs to find one by keyword.`
+                        }
+                    ],
+                    isError: true
+                };
+            }
+
+            const content = loadDocContent(entry);
+            return {
+                content: [{type: 'text' as const, text: content}],
+                structuredContent: toReadDocOutput(entry, content)
+            };
+        }
+    );
+
     //------------------------------------------------------------------
     // Tool: hoist-ping
     //------------------------------------------------------------------
     server.registerTool(
         'hoist-ping',
         {
             title: 'Hoist Ping',
-            description: 'Verify the Hoist MCP server is running and responsive',
+            description:
+                'Verify the Hoist MCP server is running and responsive. Reports the indexed @xh/hoist library version.',
             inputSchema: z.object({})
         },
         async () => ({
-            content: [{type: 'text' as const, text: 'Hoist MCP server is running.'}]
+            content: [
+                {
+                    type: 'text' as const,
+                    text: `Hoist MCP server is running (@xh/hoist v${resolveHoistVersion()}).`
+                }
+            ]
         })
     );
 }

mcp/util/paths.ts

@@ -4,13 +4,16 @@
  * Provides repo root resolution (via `import.meta.url`) and safe path
  * construction that prevents directory traversal outside the repository.
  */
-import {existsSync} from 'node:fs';
+import {existsSync, readFileSync} from 'node:fs';
 import {resolve, dirname, sep} from 'node:path';
 import {fileURLToPath} from 'node:url';
 
 /** Cached repo root -- resolved once and reused. */
 let cachedRepoRoot: string | undefined;
 
+/** Cached hoist library version -- resolved once and reused. */
+let cachedHoistVersion: string | undefined;
+
 /**
  * Resolve the hoist-react repo root by walking up from this file's location.
  *
@@ -36,6 +39,22 @@ export function resolveRepoRoot(): string {
     return repoRoot;
 }
 
+/**
+ * Resolve the `@xh/hoist` library version from the repo root `package.json`.
+ *
+ * Used by the connectivity-check surfaces (`hoist-ping` tool, `hoist-docs ping`
+ * CLI) so a sanity check also reports which hoist version is being indexed.
+ * The result is cached after the first call.
+ */
+export function resolveHoistVersion(): string {
+    if (cachedHoistVersion) return cachedHoistVersion;
+
+    const pkgPath = resolve(resolveRepoRoot(), 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {version?: string};
+    cachedHoistVersion = pkg.version ?? 'unknown';
+    return cachedHoistVersion;
+}
+
 /**
  * Resolve a relative path within the repo root, with traversal protection.
  *