From ff60e57ad4d3d85893e721a00d720a5126abd9da Mon Sep 17 00:00:00 2001
From: Kasper Peulen <kasperpeulen@gmail.com>
Date: Tue, 4 Aug 2026 13:43:42 +0200
Subject: [PATCH 1/6] =?UTF-8?q?Review=201/6=20=E2=80=94=20the=20contract:?=
 =?UTF-8?q?=20the=20open-service=20README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 code/core/src/shared/open-service/README.md | 57 +++++++++++++++++----
 1 file changed, 48 insertions(+), 9 deletions(-)

diff --git a/code/core/src/shared/open-service/README.md b/code/core/src/shared/open-service/README.md
index 6d4b692db1da..0aa72c9dc29a 100644
--- a/code/core/src/shared/open-service/README.md
+++ b/code/core/src/shared/open-service/README.md
@@ -31,8 +31,8 @@ client/server registration API.
 The environment-agnostic API consists of:
 
 - `defineService`
-- `defineToolset`, `registerToolset`, `getRegisteredToolsets` — the public toolset construct (see
-  [Toolset](#toolset))
+- `defineToolset`, `registerToolset`, `getToolset`, `getRegisteredToolsets` — the public toolset
+  construct (see [Toolset](#toolset))
 - the exported type aliases from [types.ts](./types.ts)
 
 The server-only API consists of:
@@ -64,7 +64,8 @@ Internal tests and implementation code may import from the individual modules di
 - [types.ts](./types.ts): core type model for definitions, contexts, runtime instances, and static build data
 - [service-definition.ts](./service-definition.ts): `defineService()` typing that preserves inline inference when declaring services
 - [toolset-definition.ts](./toolset-definition.ts): `defineToolset()` typing for public toolsets and their handler context
-- [toolset-registry.ts](./toolset-registry.ts): `registerToolset` / `getRegisteredToolsets` — the realm-global toolset inventory adapters read
+- [toolset-registry.ts](./toolset-registry.ts): `registerToolset` / `getToolset` / `getRegisteredToolsets` — the realm-global toolset inventory adapters read
+- [toolset-names.ts](./toolset-names.ts): `MCP_TOOL_NAMES` — the frozen public MCP tool names — and `getRef` for consumer-aware cross-references (display titles are editable prose on each method, not part of the frozen contract)
 - `services/`: core OSA service definitions and per-runtime registration helpers
 - `toolsets/`: public toolsets (docs, stories, test, review), mirroring the services tree
 - [service-validation.ts](./service-validation.ts): sync + async schema validation helpers and error wrapping
@@ -100,15 +101,53 @@ Use `defineService()` to preserve the concrete query and command map types.
 
 Services and toolsets are sibling constructs behind this one entry: **services** own internal state
 and synchronization; **toolsets** are the public agent surface for CLI and MCP adapters. A toolset
-(`defineToolset`) has an `id`, a description, and methods carrying only `schema`, `description`, and
-`handler`. Handlers receive `(input, ctx)` where `ctx` has `consumer` (`'cli' | 'mcp'`), an optional
-`origin`, a required `format` (`'markdown' | 'json'` — adapters own the mapping; methods never
-declare the format), and `getService` for calling OSA services (with `{ internal: true }`).
+(`defineToolset`) has an `id`, a description, a `telemetryGroup` (`'dev' | 'test' | 'docs'` —
+stories and review report under `dev`), and methods carrying five fields:
+
+- `title` — required short display label shown by client UIs; editable prose, not part of the
+  frozen wire contract (`MCP_TOOL_NAMES` owns the invokable tool name)
+- `description` — `string`, or a function of `ctx` when the prose differs per consumer
+- `schema` — the input schema
+- `outputSchema` — optional; published as the MCP `outputSchema`, and `structuredContent` is
+  narrowed to it. An outcome's `data` may carry more than this declares; only the declared shape
+  reaches the wire
+- `handler(input, ctx)` — the one execution: produces the data, renders the text, and owns side
+  effects and telemetry
+
+`handler` returns a `ToolsetOutcome<TSuccess, TFailure = TSuccess>` — a discriminated union of
+`{ ok: true, data, markdown }` and `{ ok: false, data, markdown }`, written as plain object
+literals (no factory helpers). The failure model is one line each: could not do the job →
+**throw**; did the job and the answer is bad news (a failed test run, a not-found lookup) →
+**return `{ ok: false, data, markdown }`**. Infallible methods declare `TFailure = never`.
+
+One handler owns data and rendering because one MCP reply carries `content` (text) and
+`structuredContent` (JSON) at once and both must come from a single run — re-running a method with
+side effects would repeat them. Usage telemetry reports inline in the handler with the rendered
+text in hand, so no consumer can forget it. Adapters unwrap outcomes mechanically — text blocks
+from `markdown`, `structuredContent` from `data`, MCP `isError` (and later CLI exit codes) from
+`ok` — and must not re-derive meaning from the data. `markdown` may be `string | string[]`:
+`preview-stories` renders one text block per URL; the CLI's `--json` (Milestone 5) becomes "return
+`data`, skip `markdown`".
+
+An error whose message speaks to the agent and names its own recovery declares `agentFacing: true`
+(a `StorybookError` constructor prop); adapters surface such errors verbatim by reading that
+property — never by keeping a class list, which misclassifies across bundle copies.
+
+`ctx` is `{ consumer: 'cli' | 'mcp', origin?, uiRoot?, getService, telemetry? }`. `uiRoot` is where
+the consumer's Storybook UI is reachable when that differs from `origin` (a sub-path-hosted dev
+server); methods that link into the UI prefer it, and the adapter derives it from the request.
+Descriptions that name a sibling tool must render it through `getRef(ctx)` rather than hardcoding
+either spelling, so the same sentence reads as the MCP tool name or the CLI command per consumer.
+Facts that are fixed at boot (whether review or a11y is enabled) are factory options on the
+toolset, not `ctx` fields.
 
 Toolsets register imperatively via `registerToolset`, called from the same place the paired service
 registers (for core and addons, the `services` preset hook — the mechanism itself is
-preset-independent so manager- or preview-realm toolsets can use it later). Adapters obtain the
-registered set via `getRegisteredToolsets()`; the MCP server consumes it from Milestone 4 and the
+preset-independent so manager- or preview-realm toolsets can use it later). A toolset must be
+registered wherever a consumer resolves it, including consumers that only read its descriptions and
+schemas: `getToolset(id)` throws on an unregistered id rather than silently dropping a tool.
+Adapters resolve one toolset with `getToolset(id)` or take the whole set via
+`getRegisteredToolsets()`; `@storybook/addon-mcp` and `@storybook/mcp` consume them today, and the
 `storybook tools` CLI from Milestone 5.
 
 ### Query

From 5bc15c9b41b7786bb5405b18efa15224fb36b3d6 Mon Sep 17 00:00:00 2001
From: Kasper Peulen <kasperpeulen@gmail.com>
Date: Tue, 4 Aug 2026 13:43:54 +0200
Subject: [PATCH 2/6] =?UTF-8?q?Review=202/6=20=E2=80=94=20the=20construct:?=
 =?UTF-8?q?=20defineToolset,=20toolset=20types,=20the=20registry,=20the=20?=
 =?UTF-8?q?frozen=20names?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../open-service/toolset-definition.test-d.ts | 217 +++++++++++++++---
 .../shared/open-service/toolset-definition.ts | 139 +++++++++--
 .../src/shared/open-service/toolset-names.ts  |  42 ++++
 .../shared/open-service/toolset-registry.ts   |  37 ++-
 .../src/shared/open-service/toolset-types.ts  |  18 ++
 5 files changed, 403 insertions(+), 50 deletions(-)
 create mode 100644 code/core/src/shared/open-service/toolset-names.ts
 create mode 100644 code/core/src/shared/open-service/toolset-types.ts

diff --git a/code/core/src/shared/open-service/toolset-definition.test-d.ts b/code/core/src/shared/open-service/toolset-definition.test-d.ts
index cd203207fd59..effba734cd7e 100644
--- a/code/core/src/shared/open-service/toolset-definition.test-d.ts
+++ b/code/core/src/shared/open-service/toolset-definition.test-d.ts
@@ -1,20 +1,27 @@
 import * as v from 'valibot';
 import { describe, expectTypeOf, it } from 'vitest';
 
-import { defineToolset, type ToolsetDefinition } from './index.ts';
+import {
+  defineToolset,
+  type ToolsetCtx,
+  type ToolsetDefinition,
+  type ToolsetOutcome,
+} from './index.ts';
 
 const exampleToolset = defineToolset({
   id: 'example',
   description: 'Example API',
+  telemetryGroup: 'dev',
   methods: {
     greet: {
+      title: 'Greet',
       description: 'Greets a person.',
       schema: v.object({ name: v.string() }),
-      handler: async ({ name }) => {
-        expectTypeOf(name).toEqualTypeOf<string>();
-
-        return `Hello ${name}`;
-      },
+      handler: async ({ name }): Promise<ToolsetOutcome<{ greeting: string }, never>> => ({
+        ok: true,
+        data: { greeting: `Hello ${name}` },
+        markdown: `Hello ${name}`,
+      }),
     },
   },
 });
@@ -22,35 +29,191 @@ const exampleToolset = defineToolset({
 const reviewToolset = defineToolset({
   id: 'review',
   description: 'Create a review',
+  telemetryGroup: 'dev',
   methods: {
     create: {
-      description: 'Create a review',
+      title: 'Create review',
+      description: (ctx) => `Create a review (${ctx.consumer})`,
       schema: v.object({ title: v.string() }),
-      handler: async (input, ctx) => {
-        expectTypeOf(input.title).toEqualTypeOf<string>();
-        expectTypeOf(ctx.consumer).toEqualTypeOf<'cli' | 'mcp'>();
-        expectTypeOf(ctx.origin).toEqualTypeOf<string | undefined>();
-        expectTypeOf(ctx.format).toEqualTypeOf<'markdown' | 'json'>();
-        expectTypeOf(
-          ctx.getService<{ ok: true }>('core/review', { internal: true })
-        ).toEqualTypeOf<{
-          ok: true;
-        }>();
-
-        return input.title;
-      },
+      outputSchema: v.object({ title: v.string() }),
+      handler: async (
+        input,
+        ctx
+      ): Promise<
+        ToolsetOutcome<{ title: string; origin?: string }, { title: string; reason: string }>
+      > =>
+        input.title
+          ? { ok: true, data: { title: input.title, origin: ctx.origin }, markdown: input.title }
+          : {
+              ok: false,
+              data: { title: input.title, reason: 'missing title' },
+              markdown: 'missing title',
+            },
     },
   },
 });
 
 describe('defineToolset types', () => {
-  it('preserves method schema output types in handlers', () => {
+  // Assertions live outside the definition literal: inside it, the first contextual-typing pass
+  // sees `any`/`unknown` params, so exact-type checks there would report on the wrong pass.
+  it('types handler input from the method schema', () => {
+    const greet: (
+      input: { name: string },
+      context: ToolsetCtx
+    ) => Promise<ToolsetOutcome<{ greeting: string }, never>> =
+      exampleToolset.methods.greet.handler;
+    const create: (
+      input: { title: string },
+      context: ToolsetCtx
+    ) => Promise<
+      ToolsetOutcome<{ title: string; origin?: string }, { title: string; reason: string }>
+    > = reviewToolset.methods.create.handler;
+
+    expectTypeOf(greet).toBeFunction();
+    expectTypeOf(create).toBeFunction();
     expectTypeOf(exampleToolset).toMatchTypeOf<ToolsetDefinition>();
-    expectTypeOf(exampleToolset.methods.greet.handler).parameter(0).toEqualTypeOf<{
-      name: string;
-    }>();
-    expectTypeOf(reviewToolset.methods.create.handler).parameter(0).toEqualTypeOf<{
-      title: string;
-    }>();
+  });
+
+  it('narrows both branches of an outcome on its tag', async () => {
+    const outcome = await reviewToolset.methods.create.handler(
+      { title: 'x' },
+      { consumer: 'cli', getService: () => ({}) as never }
+    );
+
+    if (outcome.ok) {
+      expectTypeOf(outcome.data).toEqualTypeOf<{ title: string; origin?: string }>();
+    } else {
+      expectTypeOf(outcome.data).toEqualTypeOf<{ title: string; reason: string }>();
+    }
+  });
+
+  it('makes the failure branch unreachable for infallible methods', async () => {
+    const outcome = await exampleToolset.methods.greet.handler({ name: 'x' });
+
+    if (!outcome.ok) {
+      expectTypeOf(outcome.data).toBeNever();
+    }
+  });
+
+  it('resolves description functions against the toolset context', () => {
+    const description: string | ((context: ToolsetCtx) => string) =
+      reviewToolset.methods.create.description;
+
+    expectTypeOf(description).not.toBeNever();
+  });
+});
+
+describe('method titles', () => {
+  it('rejects a method that omits its display title', () => {
+    defineToolset({
+      id: 'untitled',
+      description: 'Rejected',
+      telemetryGroup: 'dev',
+      methods: {
+        // @ts-expect-error — every method must declare its display `title`
+        create: {
+          description: 'Has no title.',
+          schema: v.object({}),
+          handler: async (): Promise<ToolsetOutcome<{ done: boolean }, never>> => ({
+            ok: true,
+            data: { done: true },
+            markdown: 'x',
+          }),
+        },
+      },
+    });
+  });
+});
+
+describe('schema-bound outcomes', () => {
+  // `reviewToolset` above is the acceptance case: its success data carries `origin`, which the
+  // output schema does not declare — outcome data may be a superset of the published contract.
+
+  it('rejects data that renames a schema-declared field', () => {
+    defineToolset({
+      id: 'renamed-field',
+      description: 'Rejected',
+      telemetryGroup: 'dev',
+      methods: {
+        create: {
+          title: 'Create',
+          description: 'Renames title to heading.',
+          schema: v.object({}),
+          outputSchema: v.object({ title: v.string() }),
+          // @ts-expect-error — `data` lacks the schema-declared `title` field
+          handler: async (): Promise<ToolsetOutcome<{ heading: string }, never>> => ({
+            ok: true,
+            data: { heading: 'x' },
+            markdown: 'x',
+          }),
+        },
+      },
+    });
+  });
+
+  it('rejects data that drops a schema-declared field', () => {
+    defineToolset({
+      id: 'dropped-field',
+      description: 'Rejected',
+      telemetryGroup: 'dev',
+      methods: {
+        create: {
+          title: 'Create',
+          description: 'Publishes title but returns nothing.',
+          schema: v.object({}),
+          outputSchema: v.object({ title: v.string() }),
+          // @ts-expect-error — `data` is missing the schema-declared `title` field
+          handler: async (): Promise<ToolsetOutcome<Record<string, never>, never>> => ({
+            ok: true,
+            data: {},
+            markdown: 'x',
+          }),
+        },
+      },
+    });
+  });
+
+  it('rejects data that mistypes a schema-declared field', () => {
+    defineToolset({
+      id: 'mistyped-field',
+      description: 'Rejected',
+      telemetryGroup: 'dev',
+      methods: {
+        create: {
+          title: 'Create',
+          description: 'Returns a number where the schema declares a string.',
+          schema: v.object({}),
+          outputSchema: v.object({ title: v.string() }),
+          // @ts-expect-error — `title` is a number where the schema declares a string
+          handler: async (): Promise<ToolsetOutcome<{ title: number }, never>> => ({
+            ok: true,
+            data: { title: 1 },
+            markdown: 'x',
+          }),
+        },
+      },
+    });
+  });
+
+  it('constrains the failure branch to the schema too', () => {
+    defineToolset({
+      id: 'unbound-failure',
+      description: 'Rejected',
+      telemetryGroup: 'dev',
+      methods: {
+        create: {
+          title: 'Create',
+          description: 'Failure data skips the published contract.',
+          schema: v.object({}),
+          outputSchema: v.object({ title: v.string() }),
+          // @ts-expect-error — failure `data` lacks the schema-declared `title` field
+          handler: async (): Promise<ToolsetOutcome<{ title: string }, { reason: string }>> => ({
+            ok: false,
+            data: { reason: 'x' },
+            markdown: 'x',
+          }),
+        },
+      },
+    });
   });
 });
diff --git a/code/core/src/shared/open-service/toolset-definition.ts b/code/core/src/shared/open-service/toolset-definition.ts
index f747a8b68d28..41ac65a0b7d0 100644
--- a/code/core/src/shared/open-service/toolset-definition.ts
+++ b/code/core/src/shared/open-service/toolset-definition.ts
@@ -6,12 +6,6 @@ type AnySchema = StandardSchemaV1<unknown, unknown>;
 
 export type ToolsetConsumer = 'cli' | 'mcp';
 
-/**
- * Output representation requested by the adapter. Methods never declare the format themselves;
- * adapters own the mapping (CLI `--json` flag, MCP `json` tool input).
- */
-export type ToolsetFormat = 'markdown' | 'json';
-
 /**
  * Service lookup for toolset handlers. Intentionally not keyed to ServerCoreServices:
  * toolsets may call core OSA (with `{ internal: true }`) or optional addon services by id.
@@ -20,23 +14,100 @@ export type ToolsetGetService = {
   <TInstance = unknown>(serviceId: string, options?: GetServiceOptions): TInstance;
 };
 
+/**
+ * Emits one telemetry event for a toolset method.
+ *
+ * Adapters supply the sink so surface-specific fields (MCP session id, client info) stay with the
+ * adapter while the event name and payload — the part that describes the capability — stay in the
+ * method. Absent when the consumer has telemetry disabled.
+ */
+export type ToolsetTelemetry = (event: string, payload: Record<string, unknown>) => Promise<void>;
+
 export type ToolsetCtx = {
   consumer: ToolsetConsumer;
   /** Storybook server origin. Absent when running from a CLI without a live Storybook. */
   origin?: string;
-  format: ToolsetFormat;
+  /**
+   * Where this consumer's Storybook UI is reachable, when that differs from `origin` — a
+   * sub-path-hosted dev server answers MCP at `<root><endpoint>` while its UI lives at `<root>`.
+   * Methods that link into the UI prefer this over `origin`; the adapter derives it from the
+   * request it is serving.
+   */
+  uiRoot?: string;
   getService: ToolsetGetService;
+  telemetry?: ToolsetTelemetry;
 };
 
-export type ToolsetMethod<TSchema extends AnySchema = AnySchema> = {
-  description: string;
+/**
+ * A method description, resolved per consumer.
+ *
+ * The function form exists because descriptions cross-reference sibling methods, and each surface
+ * spells those differently (`get-changed-stories` on MCP, `npx storybook tools stories changed` on
+ * the CLI). Use `getRef(ctx)` to render a reference rather than hardcoding either spelling.
+ */
+export type ToolsetMethodDescription = string | ((context: ToolsetCtx) => string);
+
+/**
+ * The result of one method run: the tag, the structured data, and the rendered Markdown, all from a
+ * single execution.
+ *
+ * The failure model in one line each: could not do the job → throw; did the job and the answer is
+ * bad news → return `{ ok: false, data, markdown }`. Adapters unwrap mechanically — text blocks
+ * from `markdown`, `structuredContent` from `data`, MCP `isError` (and later CLI exit codes) from
+ * `ok` — so everything a method means lives on its definition, never re-derived outside it.
+ *
+ * Declare `TFailure = never` for infallible methods; the signature then documents fallibility and
+ * TypeScript narrows both branches. Return plain object literals: contextual typing against this
+ * union does the narrowing, no factory helpers needed.
+ *
+ * `markdown` may be multiple strings: MCP renders each as its own text block (preview-stories
+ * renders one block per URL), the CLI joins them with newlines.
+ */
+export type ToolsetOutcome<TSuccess, TFailure = TSuccess> =
+  | { readonly ok: true; readonly data: TSuccess; readonly markdown: string | string[] }
+  | { readonly ok: false; readonly data: TFailure; readonly markdown: string | string[] };
+
+// `any` permits heterogeneous outcome maps. Each individual method remains typed by `defineToolset`.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyToolsetOutcome = ToolsetOutcome<any, any>;
+
+/**
+ * One public method: description, input schema, optional output schema, and one handler.
+ *
+ * The handler produces the whole {@link ToolsetOutcome} — data, side effects, telemetry, and the
+ * rendered Markdown — because one MCP response carries `content` (text) and `structuredContent`
+ * (JSON) at once, and both must come from a single run: re-running a method with side effects
+ * would repeat them. Usage telemetry reports inline in the handler, with the rendered text in
+ * hand, so no consumer can forget it.
+ */
+export type ToolsetMethod<
+  TSchema extends AnySchema = AnySchema,
+  TOutcome extends AnyToolsetOutcome = AnyToolsetOutcome,
+> = {
+  /**
+   * Short display label shown by client UIs (e.g. an MCP client's tool list). Editable prose like
+   * `description`, not a frozen contract — the invokable tool name lives in `MCP_TOOL_NAMES`.
+   */
+  title: string;
+  description: ToolsetMethodDescription;
   schema: TSchema;
-  handler: (input: StandardSchemaV1.InferOutput<TSchema>, context: ToolsetCtx) => unknown;
+  /** Published as the MCP tool's `outputSchema`. Declare it only where the JSON is contractual. */
+  outputSchema?: AnySchema;
+  handler: (
+    input: StandardSchemaV1.InferOutput<TSchema>,
+    context: ToolsetCtx
+  ) => TOutcome | Promise<TOutcome>;
 };
 
 // `any` permits a heterogeneous method map. Each individual method remains typed by `defineToolset`.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type ToolsetMethods = Record<string, ToolsetMethod<any>>;
+type ToolsetMethods = Record<string, ToolsetMethod<any, AnyToolsetOutcome>>;
+
+/**
+ * Which surface group a toolset's telemetry reports under. Part of the definition — not adapter
+ * wiring — so the grouping cannot drift between consumers. Stories and review report under `dev`.
+ */
+export type ToolsetTelemetryGroup = 'dev' | 'test' | 'docs';
 
 export type ToolsetDefinition<
   TId extends string = string,
@@ -44,22 +115,58 @@ export type ToolsetDefinition<
 > = {
   id: TId;
   description: string;
+  telemetryGroup: ToolsetTelemetryGroup;
   methods: TMethods;
 };
 
 export type AnyToolsetDefinition = ToolsetDefinition;
 
-type DefinedToolsetMethods<TSchemas extends Record<string, AnySchema>> = {
-  [TKey in keyof TSchemas]: ToolsetMethod<TSchemas[TKey]>;
+/**
+ * What a handler may return when its method publishes an `outputSchema`: outcomes whose `data` —
+ * on both branches, since adapters validate failure data into `structuredContent` too — carries at
+ * least the schema's declared shape. The open record keeps the data-superset pattern legal: the
+ * rendered Markdown may use fields the public contract does not ship. The schema's *input* type is
+ * the right side of the contract, because that is what the adapters' runtime validation accepts.
+ */
+type SchemaBoundData<TSchema extends AnySchema> = StandardSchemaV1.InferInput<TSchema> &
+  Record<string, unknown>;
+
+type MethodOutcomeContract<TMethod> = TMethod extends { outputSchema: infer TOut extends AnySchema }
+  ? ToolsetOutcome<SchemaBoundData<TOut>> | Promise<ToolsetOutcome<SchemaBoundData<TOut>>>
+  : unknown;
+
+/**
+ * Second contextual-typing pass for the methods literal: `handler` input comes from that method's
+ * own `schema`, and its outcome data from the method's `outputSchema` where one is declared — so
+ * renaming or removing a published field is a compile error at the definition site. Intersecting
+ * this with the inferred map is what makes the flow work on both the stable and the native
+ * TypeScript compiler — inferring a separate record does not.
+ */
+type MethodContracts<TMethods extends ToolsetMethods> = {
+  [TKey in keyof TMethods]: {
+    handler: (
+      input: StandardSchemaV1.InferOutput<TMethods[TKey]['schema']>,
+      context: ToolsetCtx
+    ) => MethodOutcomeContract<TMethods[TKey]>;
+  };
 };
 
 export function defineToolset<
   const TId extends string,
-  const TSchemas extends Record<string, AnySchema>,
+  const TMethods extends ToolsetMethods,
 >(definition: {
   id: TId;
   description: string;
-  methods: DefinedToolsetMethods<TSchemas>;
-}): ToolsetDefinition<TId, DefinedToolsetMethods<TSchemas>> {
+  telemetryGroup: ToolsetTelemetryGroup;
+  methods: TMethods & MethodContracts<TMethods>;
+}): ToolsetDefinition<TId, TMethods> {
   return definition;
 }
+
+/** Resolves a method description for one consumer. */
+export function resolveToolsetDescription(
+  description: ToolsetMethodDescription,
+  context: ToolsetCtx
+): string {
+  return typeof description === 'function' ? description(context) : description;
+}
diff --git a/code/core/src/shared/open-service/toolset-names.ts b/code/core/src/shared/open-service/toolset-names.ts
new file mode 100644
index 000000000000..d151629b2084
--- /dev/null
+++ b/code/core/src/shared/open-service/toolset-names.ts
@@ -0,0 +1,42 @@
+import type { ToolsetCtx } from './toolset-definition.ts';
+
+/**
+ * Maps a toolset method to the MCP tool name that exposes it.
+ *
+ * These names are the public MCP contract of `@storybook/addon-mcp` and `@storybook/mcp`: clients
+ * and downstream integrations call them by name, so they are frozen independently of the method
+ * names they point at. Both adapters register from this map, and descriptions render
+ * cross-references through {@link getRef}, so description prose and registration cannot disagree.
+ */
+export const MCP_TOOL_NAMES = {
+  'stories.preview': 'preview-stories',
+  'stories.changed': 'get-changed-stories',
+  'stories.findByComponent': 'get-stories-by-component',
+  'test.run': 'run-story-tests',
+  'review.create': 'display-review',
+  'docs.list': 'list-all-documentation',
+  'docs.show': 'get-documentation',
+  'docs.showStory': 'get-documentation-for-story',
+} as const;
+
+export type ToolsetMethodRef = keyof typeof MCP_TOOL_NAMES;
+
+/** `stories.findByComponent` -> `stories find-by-component`. */
+function toCliPath(method: ToolsetMethodRef): string {
+  const [toolsetId, methodName] = method.split('.');
+  const kebabMethod = methodName.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+  return `${toolsetId} ${kebabMethod}`;
+}
+
+/**
+ * Renders a reference to a sibling method in the consumer's own vocabulary.
+ *
+ * Descriptions that tell an agent to call another tool must name it the way that agent can call it,
+ * so never hardcode a tool name or a command in description prose — use this instead.
+ */
+export function getRef(context: Pick<ToolsetCtx, 'consumer'>) {
+  return (method: ToolsetMethodRef): string =>
+    context.consumer === 'mcp'
+      ? MCP_TOOL_NAMES[method]
+      : `npx storybook tools ${toCliPath(method)}`;
+}
diff --git a/code/core/src/shared/open-service/toolset-registry.ts b/code/core/src/shared/open-service/toolset-registry.ts
index f0b7aa4b0e32..4fa51960d1ff 100644
--- a/code/core/src/shared/open-service/toolset-registry.ts
+++ b/code/core/src/shared/open-service/toolset-registry.ts
@@ -1,4 +1,9 @@
+import {
+  OpenServiceDuplicateToolsetError,
+  OpenServiceMissingToolsetError,
+} from '../../server-errors.ts';
 import type { AnyToolsetDefinition } from './toolset-definition.ts';
+import type { KnownToolsets } from './toolset-types.ts';
 
 const TOOLSET_REGISTRY_SYMBOL = Symbol.for('storybook.open-service.toolset-registry');
 
@@ -24,23 +29,41 @@ function getToolsetRegistry(): Map<string, AnyToolsetDefinition> {
  *
  * Call it from the same place the paired OSA service registers (for core, the `services` preset
  * hook). Registration is deliberately independent of the Node preset system so manager- or
- * preview-realm toolsets can use the same API later. Idempotent by id, mirroring `registerService`:
- * a repeated registration is a no-op.
+ * preview-realm toolsets can use the same API later.
+ *
+ * Unlike `registerService`, a repeated id throws instead of being ignored: services re-register
+ * legitimately (HMR, repeated composition), while every toolset registration site is a one-shot
+ * preset hook, so a duplicate id can only mean two hosts claimed the same public surface.
  */
 export function registerToolset(toolset: AnyToolsetDefinition): void {
   const registry = getToolsetRegistry();
 
-  if (!registry.has(toolset.id)) {
-    registry.set(toolset.id, toolset);
+  if (registry.has(toolset.id)) {
+    throw new OpenServiceDuplicateToolsetError({ toolsetId: toolset.id });
   }
+
+  registry.set(toolset.id, toolset);
 }
 
 /**
- * Returns the registered toolsets in registration order.
+ * Returns one registered toolset by id, typed for the core toolsets.
  *
- * Adapter-facing: the MCP server (Milestone 4) and the `storybook tools` CLI (Milestone 5) read the
- * public tool surface from here; nothing consumes it before then.
+ * Throws when the id is not registered — an adapter asking for a toolset that no host wired up is
+ * a configuration error, not an empty result.
  */
+export function getToolset<TId extends keyof KnownToolsets>(toolsetId: TId): KnownToolsets[TId];
+export function getToolset(toolsetId: string): AnyToolsetDefinition;
+export function getToolset(toolsetId: string): AnyToolsetDefinition {
+  const toolset = getToolsetRegistry().get(toolsetId);
+
+  if (!toolset) {
+    throw new OpenServiceMissingToolsetError({ toolsetId });
+  }
+
+  return toolset;
+}
+
+/** Returns the registered toolsets in registration order. */
 export function getRegisteredToolsets(): AnyToolsetDefinition[] {
   return Array.from(getToolsetRegistry().values());
 }
diff --git a/code/core/src/shared/open-service/toolset-types.ts b/code/core/src/shared/open-service/toolset-types.ts
new file mode 100644
index 000000000000..3133ddbe70b4
--- /dev/null
+++ b/code/core/src/shared/open-service/toolset-types.ts
@@ -0,0 +1,18 @@
+import type { DocsToolset } from './toolsets/docs/definition.ts';
+import type { ReviewToolset } from './toolsets/review/definition.ts';
+import type { StoriesToolset } from './toolsets/stories/definition.ts';
+import type { TestToolset } from './toolsets/test/definition.ts';
+
+/**
+ * The public toolsets core can register, keyed by id.
+ *
+ * Mirrors `core-service-types.ts` for services: it is what makes `getToolset('stories')` return a
+ * typed toolset instead of an opaque definition. A toolset registered by an addon under its own id
+ * is still resolvable — it falls through to the untyped `getToolset` overload.
+ */
+export type KnownToolsets = {
+  docs: DocsToolset;
+  stories: StoriesToolset;
+  test: TestToolset;
+  review: ReviewToolset;
+};

From 1b8f71960899499a095eac2af8304cfd53ea6982 Mon Sep 17 00:00:00 2001
From: Kasper Peulen <kasperpeulen@gmail.com>
Date: Tue, 4 Aug 2026 13:43:59 +0200
Subject: [PATCH 3/6] =?UTF-8?q?Review=203/6=20=E2=80=94=20the=20tool=20sur?=
 =?UTF-8?q?face:=20all=20four=20toolset=20definitions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../open-service/toolsets/docs/definition.ts  | 603 ++++++++++--------
 .../toolsets/review/definition.ts             | 185 +++++-
 .../toolsets/stories/definition.ts            | 231 +++++--
 .../open-service/toolsets/test/definition.ts  | 145 ++++-
 4 files changed, 810 insertions(+), 354 deletions(-)

diff --git a/code/core/src/shared/open-service/toolsets/docs/definition.ts b/code/core/src/shared/open-service/toolsets/docs/definition.ts
index e7a4af5a74b4..c5c7752f9648 100644
--- a/code/core/src/shared/open-service/toolsets/docs/definition.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/definition.ts
@@ -1,297 +1,372 @@
 import * as v from 'valibot';
 
-import {
-  OpenServiceDocgenMissingComponentError,
-  OpenServiceMissingServiceError,
-} from '../../../../server-errors.ts';
-import type { DocgenService } from '../../services/docgen/definition.ts';
-import type { StoryDocsService } from '../../services/story-docs/definition.ts';
-import { defineToolset, type ToolsetCtx } from '../../toolset-definition.ts';
-import { classifyServices } from './classify-services.ts';
-import {
-  adaptCoreComponent,
-  adaptCoreDoc,
-  adaptCoreStories,
-} from './manifest-formatter/adapt-core-manifest.ts';
-import type {
-  AllManifests,
-  ComponentManifestV1,
-  DocV1,
-} from './manifest-formatter/manifest-types.ts';
+import { defineToolset, type ToolsetCtx, type ToolsetOutcome } from '../../toolset-definition.ts';
+import { getRef } from '../../toolset-names.ts';
+import type { DocsAccess, ResolvedDocsEntry } from './access.ts';
 import {
   formatComponentManifest,
   formatDocsManifest,
   formatManifestsToLists,
+  formatMultiSourceManifestsToLists,
   formatStoryDocumentation,
+  MAX_STORIES_TO_SHOW,
 } from './manifest-formatter/markdown.ts';
-import {
-  mapDocsList,
-  mapDocsShow,
-  mapDocsShowStory,
-  mapStoryDocsEntries,
-  resolveImportStatement,
-  selectAttachedDocs,
-  type MdxPayload,
-} from './map.ts';
-
-/** Stable addon-docs MDX service id. Kept local so the docs toolset does not import core-server. */
-const MDX_SERVICE_ID = 'addon-docs/mdx';
-
-type MdxService = {
-  queries: {
-    mdxForAllComponents: {
-      loaded: () => Promise<Record<string, MdxPayload | undefined>>;
-    };
-    mdxForComponent: {
-      loaded: (input: { id: string }) => Promise<MdxPayload | undefined>;
+import type { AllManifests } from './manifest-formatter/manifest-types.ts';
+import { listSources, type DocsSource } from './multi-source.ts';
+import type { SourceListing } from './sources.ts';
+import { estimateTokens } from '../estimate-tokens.ts';
+
+/**
+ * Which Storybooks these tools serve — exactly one of the two.
+ *
+ * Modelled as an exclusive union so neither "no access at all" nor "both, one silently winning" can
+ * be constructed: a composition takes a `storybookId` on every lookup and a single Storybook must
+ * not ask for one, and that difference is decided here.
+ */
+export type CreateDocsToolsetOptions =
+  | {
+      /** Reads the one Storybook these tools serve. */
+      docsAccess: DocsAccess;
+      sources?: never;
+    }
+  | {
+      /** The composed Storybooks these tools serve; ids are only unique within a source. */
+      sources: DocsSource[];
+      docsAccess?: never;
     };
-  };
+
+export type DocsListOutput = {
+  withStoryIds: boolean;
+  /** Single-source listing. */
+  manifests?: AllManifests;
+  /** Per-source listings, in composition. */
+  sources?: SourceListing[];
 };
 
-function tryGetService<T>(ctx: ToolsetCtx, serviceId: string): T | undefined {
-  try {
-    return ctx.getService<T>(serviceId, { internal: true });
-  } catch (error) {
-    if (error instanceof OpenServiceMissingServiceError) {
-      return undefined;
-    }
-    throw error;
+export type DocsShowOutput = {
+  id: string;
+  entry?: ResolvedDocsEntry;
+  storybookId?: string;
+  /** Set when the request named no source, or one that does not exist. */
+  sourceError?: string;
+};
+
+export type DocsShowStoryOutput = {
+  componentId: string;
+  storyName: string;
+  entry?: ResolvedDocsEntry;
+  storybookId?: string;
+  sourceError?: string;
+};
+
+/**
+ * The manifests a listing should be reported against.
+ *
+ * Reporting predates composition and describes one Storybook, so a composed listing is reported
+ * against the first source that produced one. Nothing is returned when no source did — a listing of
+ * nothing but errors is not a usage signal.
+ */
+export function selectReportedManifests({
+  manifests,
+  sources,
+}: DocsListOutput): AllManifests | undefined {
+  return manifests ?? sources?.find((listing) => listing.manifests)?.manifests;
+}
+
+/**
+ * One classification of a `show` lookup, shared by the failure predicate and the renderer so the
+ * outcome tag and the rendered prose cannot disagree.
+ */
+type ShowResolution =
+  | { kind: 'source-error'; message: string }
+  | { kind: 'entry-missing' }
+  | { kind: 'found'; entry: ResolvedDocsEntry };
+
+function resolveShow({ entry, sourceError }: DocsShowOutput): ShowResolution {
+  if (sourceError !== undefined) {
+    return { kind: 'source-error', message: sourceError };
   }
+  if (entry === undefined) {
+    return { kind: 'entry-missing' };
+  }
+  return { kind: 'found', entry };
+}
+
+type ComponentEntry = Extract<ResolvedDocsEntry, { kind: 'component' }>;
+
+/** The `showStory` counterpart of {@link ShowResolution}. */
+type ShowStoryResolution =
+  | { kind: 'source-error'; message: string }
+  | { kind: 'component-missing' }
+  | { kind: 'story-missing'; component: ComponentEntry['component'] }
+  | { kind: 'found'; component: ComponentEntry['component'] };
+
+function resolveShowStory({
+  entry,
+  storyName,
+  sourceError,
+}: DocsShowStoryOutput): ShowStoryResolution {
+  if (sourceError !== undefined) {
+    return { kind: 'source-error', message: sourceError };
+  }
+  if (entry === undefined || entry.kind !== 'component') {
+    return { kind: 'component-missing' };
+  }
+  const { component } = entry;
+  return component.stories?.some((story) => story.name === storyName)
+    ? { kind: 'found', component }
+    : { kind: 'story-missing', component };
 }
 
 /**
- * Component payload loads throw when an id has no component entry in the index. Standalone docs
- * ids and ids that don't exist at all both land there, and both are answered by absence rather
- * than a failure, so the typed error becomes `undefined`.
+ * Whether `docs.show` failed: an unusable source, or an id that resolved to nothing.
+ *
+ * The handlers encode this in the outcome tag; the predicate stays exported because it is part of
+ * the frozen `@storybook/mcp` API.
  */
-async function loadOptionalComponentPayload<T>(
-  load: Promise<T | undefined>
-): Promise<T | undefined> {
-  try {
-    return await load;
-  } catch (error) {
-    if (error instanceof OpenServiceDocgenMissingComponentError) {
-      return undefined;
+export function isDocsShowError(output: DocsShowOutput): boolean {
+  return resolveShow(output).kind !== 'found';
+}
+
+/** Whether `docs.showStory` failed: an unusable source, a missing component, or a missing story. */
+export function isDocsShowStoryError(output: DocsShowStoryOutput): boolean {
+  return resolveShowStory(output).kind !== 'found';
+}
+
+function describeList(ctx: ToolsetCtx): string {
+  const ref = getRef(ctx);
+  return `List all available UI components and documentation entries from the Storybook, returning the IDs the other documentation tools take as input. Call this first for any UI task — before writing a new component, check what the design system already provides and build on it instead of hand-rolling a duplicate; before answering any question about props, API, or usage, discover the relevant IDs here rather than reading component source. Then fetch the entries with ${ref('docs.show')}, referencing only IDs returned here — never guess IDs. When multiple Storybook sources are configured, entries from every source are included; scope follow-up calls to one source via their \`storybookId\` input. Pass \`withStoryIds: true\` when you need story IDs for other tools.`;
+}
+
+function describeShow(ctx: ToolsetCtx): string {
+  return `Get documentation for a UI component or docs entry.
+
+Returns the first ${MAX_STORIES_TO_SHOW} stories (including story IDs) with code snippets showing how props are used, plus TypeScript prop definitions. Call this before using a component to avoid hallucinating prop names, types, or valid combinations, and to answer any question about a component's props, API, or usage — reading or grepping the component source is not a substitute. Stories reveal real prop usage patterns, interactions, and edge cases that type definitions alone don't show. If the example stories don't show the prop you need, use the ${getRef(ctx)('docs.showStory')} tool to fetch the story documentation for the specific story variant you need.
+
+Example: id="button" returns Primary, Secondary, Large stories with code like <Button variant="primary" size="large"> showing actual prop combinations.`;
+}
+
+/** Not-found message for an unknown component or docs id. */
+function formatEntryNotFound(id: string, storybookId: string | undefined, ctx: ToolsetCtx): string {
+  const suffix = storybookId ? ` in source "${storybookId}"` : '';
+  return ctx.consumer === 'mcp'
+    ? `Component or Docs Entry not found: "${id}"${suffix}. Use the ${getRef(ctx)('docs.list')} tool to see available components and documentation entries.`
+    : `Component or Docs Entry not found: "${id}"${suffix}.`;
+}
+
+/** Pure renderer for `show`; the handler attaches it to both outcome branches. */
+function renderShow(data: DocsShowOutput, ctx: ToolsetCtx): string {
+  const resolution = resolveShow(data);
+  switch (resolution.kind) {
+    case 'source-error':
+      return resolution.message;
+    case 'entry-missing':
+      return formatEntryNotFound(data.id, data.storybookId, ctx);
+    case 'found':
+      return resolution.entry.kind === 'doc'
+        ? formatDocsManifest(resolution.entry.doc)
+        : formatComponentManifest(resolution.entry.component);
+    default: {
+      const exhaustive: never = resolution;
+      return exhaustive;
     }
-    throw error;
   }
 }
 
-async function loadDocsListServices(ctx: ToolsetCtx) {
-  const docgen = ctx.getService<DocgenService>('core/docgen', { internal: true });
-  const storyDocs = ctx.getService<StoryDocsService>('core/story-docs', { internal: true });
-  const mdx = tryGetService<MdxService>(ctx, MDX_SERVICE_ID);
-  const [allDocgen, allStoryDocs, allMdx] = await Promise.all([
-    docgen.queries.docgenForAllComponents.loaded(),
-    storyDocs.queries.storyDocsForAllComponents.loaded(),
-    mdx?.queries.mdxForAllComponents.loaded() ??
-      Promise.resolve({} as Record<string, MdxPayload | undefined>),
-  ]);
-
-  return {
-    allDocgen,
-    allStoryDocs,
-    allMdx,
-    classification: classifyServices({ allDocgen, allStoryDocs, allMdx }),
-  };
+/** Pure renderer for `showStory`. */
+function renderShowStory(data: DocsShowStoryOutput, ctx: ToolsetCtx): string {
+  const resolution = resolveShowStory(data);
+  switch (resolution.kind) {
+    case 'source-error':
+      return resolution.message;
+    case 'component-missing':
+      return ctx.consumer === 'mcp'
+        ? `Component not found: "${data.componentId}". Use the ${getRef(ctx)('docs.list')} tool to see available components.`
+        : `Component not found: "${data.componentId}".`;
+    case 'story-missing': {
+      const availableStories = resolution.component.stories?.map((story) => story.name).join(', ');
+      return `Story "${data.storyName}" not found for component "${data.componentId}". Available stories: ${availableStories || 'none'}`;
+    }
+    case 'found':
+      return formatStoryDocumentation(resolution.component, data.storyName);
+    default: {
+      const exhaustive: never = resolution;
+      return exhaustive;
+    }
+  }
 }
 
-/** Not-found message matching `@storybook/mcp`'s `get-documentation` for the MCP consumer. */
-function formatEntryNotFound(id: string, ctx: ToolsetCtx): string {
-  return ctx.consumer === 'mcp'
-    ? `Component or Docs Entry not found: "${id}". Use the list-all-documentation tool to see available components and documentation entries.`
-    : `Component or Docs Entry not found: "${id}".`;
+const storybookIdField = {
+  storybookId: v.pipe(
+    v.string(),
+    v.description('The ID of the Storybook source to query (e.g., "local", "design-system")')
+  ),
+};
+
+/**
+ * Picks the access for a lookup, or explains which source the caller should have named.
+ *
+ * In a composition the id alone is ambiguous, so a missing or unknown `storybookId` is a result the
+ * agent can act on — the available ids and where to find them — rather than a thrown error.
+ */
+function selectSource(
+  sources: DocsSource[] | undefined,
+  storybookId: string | undefined,
+  ctx: ToolsetCtx
+): { access?: DocsAccess; sourceError?: string } {
+  if (!sources?.length) {
+    return {};
+  }
+
+  const available = sources.map(({ source }) => source.id).join(', ');
+  const listRef = `Use the ${getRef(ctx)('docs.list')} tool to see available sources.`;
+
+  if (!storybookId) {
+    return { sourceError: `storybookId is required. Available sources: ${available}. ${listRef}` };
+  }
+
+  const match = sources.find(({ source }) => source.id === storybookId);
+  if (!match) {
+    return {
+      sourceError: `Storybook source not found: "${storybookId}". Available sources: ${available}. ${listRef}`,
+    };
+  }
+
+  return { access: match.access };
 }
 
-export const docsToolset = defineToolset({
-  id: 'docs',
-  description: 'Storybook component and docs documentation.',
-  methods: {
-    list: {
-      schema: v.object({
-        withStoryIds: v.optional(
-          v.pipe(v.boolean(), v.description('When true, include story ids under each component.')),
-          false
-        ),
-      }),
-      description:
-        'Lists components and standalone docs entries. Optionally includes story ids per component.',
-      handler: async (input, ctx) => {
-        const { classification, allDocgen, allStoryDocs, allMdx } = await loadDocsListServices(ctx);
-
-        if (ctx.format === 'json') {
-          return mapDocsList({
-            classification,
-            allDocgen,
-            allStoryDocs,
-            allMdx,
-            withStoryIds: input.withStoryIds,
-          });
-        }
-
-        // Mirrors the manifest index addon-mcp builds in-process for `list-all-documentation`:
-        // shallow component rows, stories inlined only when story ids are requested.
-        const components: Record<string, ComponentManifestV1> = {};
-        for (const id of classification.componentIds) {
-          const payload = allDocgen[id];
-          const stories =
-            input.withStoryIds && classification.storyBasedIds.has(id)
-              ? (adaptCoreStories(allStoryDocs[id]?.stories) ?? [])
-              : undefined;
-          components[id] = {
-            id,
-            name: payload?.name ?? id,
-            ...(payload?.description !== undefined ? { description: payload.description } : {}),
-            ...(payload?.summary !== undefined ? { summary: payload.summary } : {}),
-            ...(stories ? { stories } : {}),
-          };
-        }
-
-        const docs: Record<string, DocV1> = {};
-        for (const [docId, name] of classification.unattachedDocs) {
-          const payload = allMdx[docId]?.docs?.[docId];
-          docs[docId] = {
-            id: docId,
-            name,
-            ...(payload?.summary !== undefined ? { summary: payload.summary } : {}),
-          };
-        }
+/**
+ * Creates the public docs API over an injected {@link DocsAccess}.
+ *
+ * The toolset never reads services or manifests itself, so the same definition serves the dev
+ * server (open services or the built manifests), a hosted Storybook (manifest files over any
+ * provider), and a composition of several of those.
+ */
+export function createDocsToolset(options: CreateDocsToolsetOptions) {
+  const { docsAccess, sources } = options;
+  const multiSource = !!sources?.length;
 
-        const manifests: AllManifests = {
-          componentManifest: { v: 1, components },
-          ...(Object.keys(docs).length > 0 ? { docsManifest: { v: 1, docs } } : {}),
-        };
-        return formatManifestsToLists(manifests, { withStoryIds: input.withStoryIds });
-      },
-    },
-    show: {
-      schema: v.object({
-        id: v.pipe(v.string(), v.description('Component or docs entry id.')),
-      }),
-      description: 'Returns documentation for one component or standalone docs entry by id.',
-      handler: async (input, ctx) => {
-        const docgen = ctx.getService<DocgenService>('core/docgen', { internal: true });
-        const storyDocs = ctx.getService<StoryDocsService>('core/story-docs', { internal: true });
-        const mdx = tryGetService<MdxService>(ctx, MDX_SERVICE_ID);
-        const [docgenPayload, storyDocsPayload, mdxPayload] = await Promise.all([
-          loadOptionalComponentPayload(docgen.queries.docgen.loaded({ id: input.id })),
-          loadOptionalComponentPayload(storyDocs.queries.storyDocs.loaded({ id: input.id })),
-          mdx?.queries.mdxForComponent.loaded({ id: input.id }) ?? Promise.resolve(undefined),
-        ]);
-
-        const classification = classifyServices({
-          allDocgen: docgenPayload ? { [input.id]: docgenPayload } : {},
-          allStoryDocs: storyDocsPayload ? { [input.id]: storyDocsPayload } : {},
-          allMdx: mdxPayload ? { [input.id]: mdxPayload } : {},
-        });
-
-        if (ctx.format === 'json') {
-          return mapDocsShow({
-            id: input.id,
-            classification,
-            docgen: docgenPayload,
-            storyDocs: storyDocsPayload,
-            mdx: mdxPayload,
-          });
-        }
-
-        // Mirrors addon-mcp's in-process `resolveEntry`: standalone docs render through the docs
-        // formatter, components assemble docgen + story-docs + attached MDX.
-        if (classification.unattachedDocs.has(input.id)) {
-          const doc = mdxPayload?.docs?.[input.id];
-          if (!doc) {
-            return formatEntryNotFound(input.id, ctx);
-          }
-          return formatDocsManifest(adaptCoreDoc(doc));
-        }
-
-        if (!classification.componentIds.includes(input.id)) {
-          return formatEntryNotFound(input.id, ctx);
-        }
-
-        const docs = selectAttachedDocs(classification, input.id, mdxPayload);
-
-        return formatComponentManifest(
-          adaptCoreComponent({
-            ...docgenPayload,
-            id: input.id,
-            name: docgenPayload?.name ?? input.id,
-            ...(storyDocsPayload?.stories ? { stories: storyDocsPayload.stories } : {}),
-            ...(storyDocsPayload?.import ? { import: storyDocsPayload.import } : {}),
-            ...(docs ? { docs } : {}),
-          })
-        );
-      },
-    },
-    showStory: {
-      schema: v.object({
-        componentId: v.pipe(v.string(), v.description('Component id.')),
-        storyName: v.pipe(v.string(), v.description('Story display name (not story id).')),
-      }),
-      description: 'Returns documentation for one story of a component.',
-      handler: async (input, ctx) => {
-        const storyDocs = ctx.getService<StoryDocsService>('core/story-docs', { internal: true });
-        const docgen = ctx.getService<DocgenService>('core/docgen', { internal: true });
-        const [storyDocsPayload, docgenPayload] = await Promise.all([
-          loadOptionalComponentPayload(
-            storyDocs.queries.storyDocs.loaded({ id: input.componentId })
+  // The options union cannot exclude an empty array, and every handler would otherwise fail later
+  // with a bare TypeError on a missing access.
+  if (!multiSource && !docsAccess) {
+    throw new Error('createDocsToolset requires a docsAccess or at least one source.');
+  }
+
+  // A composition needs the caller to say which Storybook they mean; a single one must not ask.
+  const showSchema = multiSource
+    ? v.object({
+        id: v.pipe(v.string(), v.description('The component or docs entry ID (e.g., "button")')),
+        ...storybookIdField,
+      })
+    : v.object({
+        id: v.pipe(v.string(), v.description('The component or docs entry ID (e.g., "button")')),
+      });
+
+  const showStorySchema = multiSource
+    ? v.object({ componentId: v.string(), storyName: v.string(), ...storybookIdField })
+    : v.object({ componentId: v.string(), storyName: v.string() });
+
+  /** The access for a lookup, plus the id it was scoped to. */
+  const access = (storybookId: string | undefined, ctx: ToolsetCtx) =>
+    multiSource ? selectSource(sources, storybookId, ctx) : { access: docsAccess };
+
+  return defineToolset({
+    id: 'docs',
+    description: 'Storybook component and docs documentation.',
+    telemetryGroup: 'docs',
+    methods: {
+      list: {
+        schema: v.object({
+          withStoryIds: v.optional(
+            v.pipe(
+              v.boolean(),
+              v.description(
+                'When true, includes story sub-bullets under each component with story name and story ID. Use this to discover IDs for downstream story-focused workflows without filesystem lookup.'
+              )
+            ),
+            false
           ),
-          loadOptionalComponentPayload(docgen.queries.docgen.loaded({ id: input.componentId })),
-        ]);
-
-        if (ctx.format === 'json') {
-          if (!storyDocsPayload && !docgenPayload) {
-            return mapDocsShowStory({
-              componentId: input.componentId,
-              storyName: input.storyName,
-              show: { kind: 'not-found', id: input.componentId },
+        }),
+        title: 'List All Documentation',
+        description: describeList,
+        handler: async (input, ctx): Promise<ToolsetOutcome<DocsListOutput, never>> => {
+          const { withStoryIds } = input;
+          const data: DocsListOutput = multiSource
+            ? { withStoryIds, sources: await listSources(sources!, { withStoryIds }) }
+            : { withStoryIds, manifests: await docsAccess!.list({ withStoryIds }) };
+
+          const markdown = data.sources
+            ? formatMultiSourceManifestsToLists(data.sources, { withStoryIds })
+            : formatManifestsToLists(data.manifests!, { withStoryIds });
+
+          // A listing of nothing but errors is not a usage signal, so nothing is counted then.
+          const counted = selectReportedManifests(data);
+          if (counted) {
+            await ctx.telemetry?.('tool:listAllDocumentation', {
+              componentCount: Object.keys(counted.componentManifest.components).length,
+              docsCount: Object.keys(counted.docsManifest?.docs ?? {}).length,
+              resultTokenCount: estimateTokens(markdown),
+              sourceCount: data.sources?.length,
             });
           }
 
-          const stories = storyDocsPayload?.stories
-            ? mapStoryDocsEntries(storyDocsPayload.stories)
-            : [];
-
-          const importStatement = resolveImportStatement(storyDocsPayload, docgenPayload);
-
-          return mapDocsShowStory({
-            componentId: input.componentId,
-            storyName: input.storyName,
-            show: {
-              kind: 'component',
-              id: input.componentId,
-              name: docgenPayload?.name ?? storyDocsPayload?.name ?? input.componentId,
-              ...(importStatement !== undefined ? { import: importStatement } : {}),
-              stories,
-            },
+          return { ok: true, data, markdown };
+        },
+      },
+      show: {
+        schema: showSchema,
+        title: 'Get Documentation',
+        description: describeShow,
+        handler: async (input, ctx): Promise<ToolsetOutcome<DocsShowOutput>> => {
+          const { id, storybookId } = input as { id: string; storybookId?: string };
+          const selected = access(storybookId, ctx);
+          const data: DocsShowOutput = selected.sourceError
+            ? { id, storybookId, sourceError: selected.sourceError }
+            : { id, storybookId, entry: await selected.access!.resolve(id) };
+
+          const markdown = renderShow(data, ctx);
+
+          await ctx.telemetry?.('tool:getDocumentation', {
+            componentId: id,
+            found: data.entry !== undefined,
+            resultTokenCount: estimateTokens(markdown),
           });
-        }
-
-        // Mirrors `@storybook/mcp`'s `get-documentation-for-story`, including its miss messages.
-        if (!storyDocsPayload && !docgenPayload) {
-          return ctx.consumer === 'mcp'
-            ? `Component not found: "${input.componentId}". Use the list-all-documentation tool to see available components.`
-            : `Component not found: "${input.componentId}".`;
-        }
-
-        const component = adaptCoreComponent({
-          ...docgenPayload,
-          id: input.componentId,
-          name: docgenPayload?.name ?? input.componentId,
-          ...(storyDocsPayload?.stories ? { stories: storyDocsPayload.stories } : {}),
-          ...(storyDocsPayload?.import ? { import: storyDocsPayload.import } : {}),
-        });
-
-        const story = component.stories?.find((entry) => entry.name === input.storyName);
-        if (!story) {
-          const availableStories = component.stories?.map((entry) => entry.name).join(', ');
-          return `Story "${input.storyName}" not found for component "${input.componentId}". Available stories: ${availableStories || 'none'}`;
-        }
-
-        return formatStoryDocumentation(component, input.storyName);
+
+          return isDocsShowError(data)
+            ? { ok: false, data, markdown }
+            : { ok: true, data, markdown };
+        },
+      },
+      showStory: {
+        schema: showStorySchema,
+        title: 'Get Documentation for Story',
+        description:
+          'Get detailed documentation for a specific story variant of a UI component. Use this when you need to see more usage examples of a component, via the stories written for it.',
+        handler: async (input, ctx): Promise<ToolsetOutcome<DocsShowStoryOutput>> => {
+          const { componentId, storyName, storybookId } = input as {
+            componentId: string;
+            storyName: string;
+            storybookId?: string;
+          };
+          const selected = access(storybookId, ctx);
+          const data: DocsShowStoryOutput = selected.sourceError
+            ? { componentId, storyName, storybookId, sourceError: selected.sourceError }
+            : {
+                componentId,
+                storyName,
+                storybookId,
+                entry: await selected.access!.resolve(componentId),
+              };
+
+          const markdown = renderShowStory(data, ctx);
+
+          return isDocsShowStoryError(data)
+            ? { ok: false, data, markdown }
+            : { ok: true, data, markdown };
+        },
       },
     },
-  },
-});
+  });
+}
 
-export type DocsToolset = typeof docsToolset;
+export type DocsToolset = ReturnType<typeof createDocsToolset>;
diff --git a/code/core/src/shared/open-service/toolsets/review/definition.ts b/code/core/src/shared/open-service/toolsets/review/definition.ts
index 49c00d3aab0f..c518c0aedbc0 100644
--- a/code/core/src/shared/open-service/toolsets/review/definition.ts
+++ b/code/core/src/shared/open-service/toolsets/review/definition.ts
@@ -1,27 +1,155 @@
 import * as v from 'valibot';
 
-import { OpenServiceMissingOriginError } from '../../../../server-errors.ts';
-import { defineToolset } from '../../toolset-definition.ts';
-import { reviewStateSchema, type ReviewService } from '../../services/review/definition.ts';
+import {
+  OpenServiceMissingOriginError,
+  describeUnknownStoryIds,
+  OpenServiceUnknownStoryIdsError,
+} from '../../../../server-errors.ts';
+import { defineToolset, type ToolsetCtx, type ToolsetOutcome } from '../../toolset-definition.ts';
+import { getRef } from '../../toolset-names.ts';
+import type { ReviewService } from '../../services/review/definition.ts';
+
+/** Storybook manager route the review page is registered at. */
+const REVIEW_PAGE_PATH = '/review/';
+
+const reviewCollectionSchema = v.object({
+  title: v.pipe(
+    v.string(),
+    v.description(
+      'Title describing **what** this collection consists of, phrased the way a person would say it. Avoid typographic marks and CamelCase. Plain text, no markdown.'
+    )
+  ),
+  rationale: v.pipe(
+    v.string(),
+    v.description(
+      'Rationale explaining **why** this collection is relevant to the user. Shown alongside the title. One or two sentences. Plain text, no markdown.'
+    )
+  ),
+  storyIds: v.pipe(
+    v.array(v.string()),
+    v.description(
+      'Story IDs that represent this collection (e.g. "button--primary"). The page renders exactly these.'
+    )
+  ),
+});
 
 const reviewCreateInputSchema = v.object({
-  ...v.omit(reviewStateSchema, ['createdAt', 'stale', 'changedFiles']).entries,
+  title: v.pipe(
+    v.string(),
+    v.description(
+      'Terse, human-readable title for the overall review. What is this review about? Avoid typographic marks and CamelCase. Plain text, no markdown.'
+    )
+  ),
+  description: v.pipe(
+    v.string(),
+    v.description(
+      "Description of the review scope, including what's there, why it's relevant, and what to look for. Preferably one or two sentences. At most 2 paragraphs for reviews spanning multiple topics. Markdown formatting restricted to **bold**, _italic_, and `code` (backticks). Use emphasis for the key **what** and _why_, and backticks for literal source code references like component or token names."
+    )
+  ),
+  collections: v.pipe(
+    v.array(reviewCollectionSchema),
+    v.description(
+      'Groups of stories to show in the review, most relevant first. Prefer 2-5 groups.'
+    )
+  ),
   changedFiles: v.pipe(
     v.array(v.string()),
     v.description(
-      'Changed file paths, most central first. Pass an empty array when nothing changed.'
+      'Paths of the files you changed, most central first. Pass an empty array `[]` only when no code changed (browse requests, Trigger 2).'
     )
   ),
 });
 
+type ReviewCreateInput = v.InferOutput<typeof reviewCreateInputSchema>;
+
+const reviewCreateOutputSchema = v.object({
+  reviewUrl: v.pipe(
+    v.string(),
+    v.description(
+      'URL of the Storybook review page. Always include this URL in your final user-facing response so the user can open it directly.'
+    )
+  ),
+});
+
+export type ReviewCreateOutput = {
+  reviewUrl: string;
+  collectionCount: number;
+  storyCount: number;
+};
+
+function describeCreate(ctx: ToolsetCtx): string {
+  const ref = getRef(ctx);
+  return `Publish a curated review to Storybook's review page for spot-checking **visual impact**. Each call replaces the single active review — call it again whenever the user iterates on the changes.
+
+## When to call
+- **Trigger 1 — visual change** (components, stories, CSS, themes, colors, design tokens, i18n — anything that changes how the UI looks): when the user should spot-check rendering. A shared file (token, style, util) has no stories of its own — review its consumers' stories. Skip non-visual refactors unless side-effects are plausible. Start from \`${ref('stories.changed')}\`; fall back to \`${ref('stories.findByComponent')}\` if change detection is unavailable. Include \`changedFiles\`.
+- **Trigger 2 — browse request** ("show me the Badge component"): resolve via \`${ref('stories.findByComponent')}\` / \`${ref('docs.list')}\`; you may consult other sources to interpret the ask, but IDs must still come from those tools. Pass \`changedFiles: []\` — no code changed.
+
+## Hard rules
+1. Every \`storyId\` MUST come from those tools. Reject IDs derived from file paths, story names, or memory. Unknown IDs cause a runtime error; obtain real IDs via \`${ref('stories.findByComponent')}\` or \`${ref('docs.list')}\`, then retry.
+2. Every story you CREATED in this change MUST appear in the review — including interaction/play-function stories. Showing the stories you modified is encouraged too. Curate by grouping, never by omission.
+3. Prefer 2-5 collections; avoid one-story collections unless truly isolated.
+4. Follow-up reviews: stabilize collection/story order to avoid disorientation from reshuffling.
+5. Apply the field formatting rules from each schema property. Do not use em-dashes in review payload field values (title, rationale, description, etc.).
+6. Do not instruct or tell the user what to do unless they explicitly ask for guidance.
+7. "Collection" and "trigger" are internal terms for this tool's mechanics and mean nothing to users. Never use them in user-facing text unless the user used them first; say "group of stories" or just describe the contents in plain language.
+
+## Curating (Trigger 1)
+Trace the **visual cascade** up the **import graph** to **page-level UI surfaces** — one collection per layer (\`distance 0\` → direct importers → page context). Include **control stories** where the change is **not supposed to be visible**. **Theme tokens**, **shared styles**, and **layout primitives** need page-level coverage even from a single-file edit. **Localized changes:** affected component → **usage locations** → outer surfaces. **Larger features:** central page/module → lower-level pieces → outer **usage locations**.
+
+## Curating (Trigger 2)
+Exactly what the user asked for — **no more, no less**. Group logically or follow **story index hierarchy**.`;
+}
+
+/**
+ * Recovery coaching for fabricated story ids.
+ *
+ * The service reports which ids missed the index; the actionable part — which tools resolve real
+ * ids on this surface — is consumer-specific, so it is composed here rather than in the service.
+ */
+function formatUnknownStoryIdsError(unknownIds: string[], ctx: ToolsetCtx): string {
+  const ref = getRef(ctx);
+  const list = unknownIds.map((id) => `- \`${id}\``).join('\n');
+  return `${describeUnknownStoryIds(unknownIds)}\n${list}\n\nThis usually means the IDs were inferred from file paths or naming conventions rather than returned by a tool. Resolve real IDs by calling \`${ref('stories.findByComponent')}\` (for components you've edited or want covered) or \`${ref('docs.list')}\` (to browse the index), then retry \`${ref('review.create')}\` with the verified IDs. Do not invent IDs to satisfy this check.`;
+}
+
+/** Pure renderer for a published review, per consumer. */
+function formatReviewApplied(
+  { reviewUrl, collectionCount, storyCount }: ReviewCreateOutput,
+  ctx: ToolsetCtx
+): string {
+  const storyNoun = storyCount === 1 ? 'y' : 'ies';
+  const summary = `Review applied: ${collectionCount} collection${collectionCount === 1 ? '' : 's'}, ${storyCount} stor${storyNoun}.`;
+
+  if (ctx.consumer !== 'mcp') {
+    return `${summary} Open ${reviewUrl} to view it.`;
+  }
+
+  // Agents were observed ending visual work at the tool result, so the result itself has to
+  // carry both follow-ups: open the page, and surface the link in the final response.
+  // The running instance is named by the same UI root the review link is built from — for a
+  // sub-path-hosted Storybook the bare origin is not an address the agent can reach.
+  return `${summary} Storybook is already running at ${ctx.uiRoot ?? ctx.origin} — reuse it. Do NOT start another Storybook or change its port to view this review; the running instance already serves it.
+
+Two things you must do now, both of them:
+1. **Open ${reviewUrl} yourself in your preview browser.** If you have any browser-preview or navigate tool in this session (e.g. preview_eval or an equivalent), call it on this URL so the review opens in your preview window immediately. Don't merely print the link and stop — actually open it.
+2. **Show the link to the user too.** End your final response with a dedicated review section as the very last thing: its own heading on a line by itself (e.g. \`## 👀 Review your changes\`), then a one-line explanation of what the review is, then on the next line the review page as a markdown link prefixed with a 👉 so it's easy to spot: \`👉 [Open the Storybook review page](${reviewUrl})\`. For the explanation, use something like: "The review shows the ${storyCount} stor${storyNoun} most relevant for you to review right now. Because this is AI-curated, results may be inaccurate or incomplete." Put nothing after the link — not a trailing sentence the user has to hunt for. The user needs to see this link even after you've opened it yourself.`;
+}
+
 export const reviewToolset = defineToolset({
   id: 'review',
   description: 'Create a curated Storybook review.',
+  telemetryGroup: 'dev',
   methods: {
     create: {
       schema: reviewCreateInputSchema,
-      description: 'Validates story ids, publishes review state, and returns the review page URL.',
-      handler: async (review, ctx) => {
+      outputSchema: reviewCreateOutputSchema,
+      title: 'Display Storybook review',
+      description: describeCreate,
+      handler: async (
+        review: ReviewCreateInput,
+        ctx
+      ): Promise<ToolsetOutcome<ReviewCreateOutput, never>> => {
         if (!ctx.origin) {
           throw new OpenServiceMissingOriginError({
             toolsetId: 'review',
@@ -29,19 +157,40 @@ export const reviewToolset = defineToolset({
           });
         }
 
-        await ctx
-          .getService<ReviewService>('core/review', { internal: true })
-          .commands.setReview(review);
-
-        const reviewUrl = `${ctx.origin.replace(/\/$/, '')}/?path=/review/`;
-        if (ctx.format === 'json') {
-          return { reviewUrl };
+        try {
+          await ctx
+            .getService<ReviewService>('core/review', { internal: true })
+            .commands.setReview(review);
+        } catch (error) {
+          if (error instanceof OpenServiceUnknownStoryIdsError) {
+            throw new Error(formatUnknownStoryIdsError(error.data.unknownIds, ctx));
+          }
+          throw error;
         }
 
-        const markdown = `Review created: ${reviewUrl}`;
-        return ctx.consumer === 'mcp'
-          ? `${markdown}\n\nShow this review URL to the user in your final response.`
-          : markdown;
+        const collectionCount = review.collections.length;
+        const storyCount = review.collections.reduce(
+          (total, collection) => total + collection.storyIds.length,
+          0
+        );
+
+        await ctx.telemetry?.('tool:displayReview', {
+          collectionCount,
+          storyCount,
+          changedFileCount: review.changedFiles.length,
+        });
+
+        // The review page lives under the consumer's UI root, which differs from the origin for a
+        // sub-path-hosted Storybook. Preferring `uiRoot` here is the method's choice, not adapter
+        // wiring.
+        const uiRoot = ctx.uiRoot ?? ctx.origin;
+        const data: ReviewCreateOutput = {
+          reviewUrl: `${uiRoot.replace(/\/$/, '')}/?path=${REVIEW_PAGE_PATH}`,
+          collectionCount,
+          storyCount,
+        };
+
+        return { ok: true, data, markdown: formatReviewApplied(data, ctx) };
       },
     },
   },
diff --git a/code/core/src/shared/open-service/toolsets/stories/definition.ts b/code/core/src/shared/open-service/toolsets/stories/definition.ts
index f2e2b85d7048..9d8cb0b28530 100644
--- a/code/core/src/shared/open-service/toolsets/stories/definition.ts
+++ b/code/core/src/shared/open-service/toolsets/stories/definition.ts
@@ -1,22 +1,34 @@
 import type { StoryIndex } from 'storybook/internal/types';
 
-import { resolve as resolvePath } from 'pathe';
 import * as v from 'valibot';
 
-import { OpenServiceMissingOriginError } from '../../../../server-errors.ts';
+import {
+  OpenServiceMissingOriginError,
+  OpenServiceModuleGraphUnavailableError,
+} from '../../../../server-errors.ts';
 import type { ModuleGraphService } from '../../services/module-graph/definition.ts';
-import { defineToolset } from '../../toolset-definition.ts';
+import { defineToolset, type ToolsetCtx, type ToolsetOutcome } from '../../toolset-definition.ts';
+import { getRef, MCP_TOOL_NAMES } from '../../toolset-names.ts';
 import type { StatusesByStoryIdAndTypeId } from '../../../status-store/index.ts';
 import { getChangedStories } from './changed.ts';
-import { findStoriesByComponent } from './find-by-component.ts';
+import { DEFAULT_MAX_DISTANCE, findStoriesByComponent } from './find-by-component.ts';
+import type { ModuleGraphStatus } from './resolve-component-stories.ts';
 import { formatChangedStories, formatFindByComponent, formatPreviewStories } from './format.ts';
 import { previewStories } from './preview-stories.ts';
 import { storyInputArraySchema, storyInputSchema } from './story-input.ts';
+import { detectUnreachableFiles } from './unreachable-files.ts';
 
 const previewSuccessSchema = v.object({
   title: v.string(),
   name: v.string(),
-  previewUrl: v.pipe(v.string(), v.description('Direct URL for the story preview.')),
+  previewUrl: v.pipe(
+    v.string(),
+    v.description(
+      // An `outputSchema` is built once per toolset, with no `ctx` to resolve a sibling tool's
+      // spelling against, so this names the frozen MCP tool rather than a hardcoded string.
+      `Direct URL to open the story preview. Include this URL in the final user-facing response so users can open it directly — unless a curated review page is being published via ${MCP_TOOL_NAMES['review.create']}, in which case link the review page instead of listing individual URLs.`
+    )
+  ),
 });
 
 const previewFailureSchema = v.object({
@@ -66,28 +78,44 @@ const storyMatchSchema = v.object({
   distance: v.pipe(
     v.number(),
     v.description(
-      'Import-graph depth from the story file to the component. 0 = path is a story file; 1 = direct import; 2+ = transitive.'
+      'Import-graph depth from the story file to the component (lower = stronger). 0: the path you passed is itself a story file (self-match). 1: story file directly imports the component. 2+: reached through N hops.'
     )
   ),
 });
 
+const clippedByMaxDistanceSchema = v.pipe(
+  v.object({
+    count: v.number(),
+    distances: v.array(v.number()),
+  }),
+  v.description(
+    'Present only when `maxDistance` filtered out one or more matches. `count` is how many were dropped; `distances` lists the (sorted, distinct) distances those dropped matches sat at — widen `maxDistance` to include them.'
+  )
+);
+
 const findByComponentOutputSchema = v.object({
   results: v.array(
     v.object({
       componentPath: v.string(),
       matches: v.array(storyMatchSchema),
-      clipped: v.optional(
-        v.object({
-          count: v.number(),
-          distances: v.array(v.number()),
-        })
+      clipped: v.optional(clippedByMaxDistanceSchema),
+      pathNotFound: v.pipe(
+        v.optional(v.boolean()),
+        v.description(
+          '`true` when no file exists at the resolved absolute path. Distinguishes a typo from "this component has no stories yet". The agent should re-check the path it sent.'
+        )
       ),
-      pathNotFound: v.optional(v.boolean()),
     })
   ),
 });
 
-export type FindByComponentOutput = v.InferOutput<typeof findByComponentOutputSchema>;
+/**
+ * `maxDistance` echoes the ceiling actually applied so formatters can name it; it is deliberately
+ * absent from {@link findByComponentOutputSchema}, which is the published output contract.
+ */
+export type FindByComponentOutput = v.InferOutput<typeof findByComponentOutputSchema> & {
+  maxDistance: number;
+};
 
 export type StoryIndexAccess = {
   getIndex: () => Promise<StoryIndex>;
@@ -110,72 +138,133 @@ export type CreateStoriesToolsetOptions = {
   git: StoriesGitAccess;
   /** Change-detection status snapshot; wired by the server host, not imported from core-server. */
   changeStatuses: StoriesChangeStatusesAccess;
+  /**
+   * Whether curated reviews are available in this Storybook. Reviews are the intended end of visual
+   * work, so when they exist several methods steer the agent there instead of at raw preview links.
+   */
+  reviewEnabled?: boolean;
 };
 
+function describePreview(ctx: ToolsetCtx, reviewEnabled: boolean): string {
+  if (!reviewEnabled) {
+    return `Use this tool to get one or more Storybook preview URLs.
+Call it after editing anything that changes how the UI looks — components, stories, styles, CSS, themes, colors, or design tokens — no exceptions. A shared file has no stories of its own: preview the stories of the components that consume it.
+Include each returned preview URL in your final user-facing response so users can open them directly.`;
+  }
+
+  // With reviews available this is strictly a mid-loop tool: no "include the URLs in your final
+  // response" default (that sanctioned preview links as the ending of visual work) and no hedging
+  // about the review tool's availability (a hedged "when available" let an agent that wrongly
+  // believed the tool was missing treat raw links as a sanctioned fallback).
+  return `Use this tool to get Storybook preview URLs while iterating on a specific story, or when the user asks for a direct link to one.
+Do not end visual work or browse requests with these links — publish a curated review with ${getRef(ctx)('review.create')} instead (passing changedFiles: [] when no code changed) and link that.`;
+}
+
+function describeChanged(ctx: ToolsetCtx): string {
+  return `Get Storybook stories marked as new, modified, or related. Returns story metadata only (no URLs).
+
+The result reflects the cumulative working-tree diff, not just your latest edit — after multiple edits in one session, a non-empty result may cover an earlier sub-change and miss your most recent one. Check that every file you touched is represented; for any that isn't, find its consumer components and pass their paths to ${getRef(ctx)('stories.findByComponent')} instead. The response surfaces this gap with a "coverage sanity check" hint when it detects unreachable working-tree files.`;
+}
+
+function describeFindByComponent(ctx: ToolsetCtx, reviewEnabled: boolean): string {
+  const ref = getRef(ctx);
+  const handOffTargets = reviewEnabled
+    ? `${ref('stories.preview')} or ${ref('review.create')}`
+    : ref('stories.preview');
+  const inputShapes = reviewEnabled
+    ? `files you just edited, a feature/domain/topic the user named, a query like "all consumers of X", or an autonomous review after a UI change`
+    : `files you just edited, a feature/domain/topic the user named, or a query like "all consumers of X"`;
+  const cascadeGuidance = reviewEnabled
+    ? `For ${ref('review.create')}, the distance buckets map onto the visual cascade (the component itself → direct importers → page-level context) — one collection per layer; when several stories of a component share a distance, prefer the variant whose name signals it renders the changed surface.`
+    : `The distance buckets map onto the visual cascade (the component itself → direct importers → page-level context) — use them to decide which stories to preview; when several stories of a component share a distance, prefer the variant whose name signals it renders the changed surface.`;
+
+  return `Map component source files to the stories that render them, returning grounded \`storyId\` values from the live Storybook index — hand these to ${handOffTargets} instead of guessing.
+
+Reach for this whenever you need story IDs, whatever shape the input has: ${inputShapes}. First resolve the input to a list of absolute component file paths using filesystem search (grep / Glob / find) and code reading — that bridge is yours to build; this tool starts where it ends. One common trap: when the changed file is _shared_ infrastructure (theme token, design token, util, hook, CSS module) it isn't itself a component — grep for its consumers and pass _their_ paths, not the shared file's. If the symbol you grepped looks like one member of a related group (sibling tokens, neighboring exports), widen to the rest of the group too — a too-narrow grep silently drops stories. Try \`${ref('stories.changed')}\` first for "I just edited X" when it's available; if a file you touched is missing from its response, treat that file as the shared-infrastructure case and route its consumers through this tool.
+
+Results are sorted by \`distance\` (0 = the path you passed is itself a story file, 1 = direct importer, 2+ = transitive; lower = stronger). Shared primitives are usually consumed through wrapper components, so the distance-1 bucket is often empty — the default \`maxDistance: ${DEFAULT_MAX_DISTANCE}\` keeps that cascade visible while capping noise from wide decorators; raise it to widen recall, lower it to tighten precision. ${cascadeGuidance}
+
+Never invent IDs from file names, feature names, or memory; title strings can be overridden by story authors, so only IDs returned by discovery tools resolve. If a component has no matches here, it has no stories yet (say so, don't fabricate).
+
+Backed by Storybook's live reverse dependency graph, available only when the dev server runs a builder that supports change detection (e.g. Vite) — otherwise returns a typed error.`;
+}
+
 /** Creates the public stories API with request-local access to Storybook runtime dependencies. */
 export function createStoriesToolset({
   storyIndex,
   git,
   changeStatuses,
+  reviewEnabled = false,
 }: CreateStoriesToolsetOptions) {
   return defineToolset({
     id: 'stories',
     description: 'Story discovery, change detection, and preview URL generation.',
+    telemetryGroup: 'dev',
     methods: {
       preview: {
         schema: v.object({
           stories: v.pipe(
             storyInputArraySchema,
-            v.description('Stories to preview. Prefer { storyId } when available.')
+            v.description(
+              `Stories to preview.
+Prefer { storyId } when you don't already have story file context, since this avoids filesystem discovery.
+Use { storyId } when IDs were discovered from documentation tools.
+Use { absoluteStoryPath + exportName } only when you're already working in a specific .stories.* file and already have that context.`
+            )
           ),
         }),
-        description: 'Resolves story selectors to preview URLs.',
-        handler: async (input, ctx) => {
-          const origin = ctx.origin;
-          if (!origin) {
+        outputSchema: previewOutputSchema,
+        title: 'Get story preview URLs',
+        description: (ctx) => describePreview(ctx, reviewEnabled),
+        handler: async (input, ctx): Promise<ToolsetOutcome<PreviewStoriesOutput, never>> => {
+          if (!ctx.origin) {
             throw new OpenServiceMissingOriginError({
               toolsetId: 'stories',
               methodName: 'preview',
             });
           }
           const data = previewStories({
-            origin,
+            origin: ctx.origin,
             index: await storyIndex.getIndex(),
             stories: input.stories,
           });
-          return ctx.format === 'json' ? data : formatPreviewStories(data);
+
+          await ctx.telemetry?.('tool:previewStories', {
+            inputStoryCount: input.stories.length,
+            outputStoryCount: data.stories.length,
+          });
+
+          return { ok: true, data, markdown: formatPreviewStories(data, ctx, { reviewEnabled }) };
         },
       },
       changed: {
         schema: v.object({}),
-        description:
-          'Returns new, modified, and related stories from change detection, plus unreachable working-tree files.',
-        handler: async (input, ctx) => {
+        title: 'Get changed stories metadata',
+        description: describeChanged,
+        handler: async (_input, ctx): Promise<ToolsetOutcome<ChangedStoriesOutput, never>> => {
           const moduleGraph = ctx.getService<ModuleGraphService>('core/module-graph', {
             internal: true,
           });
-          const [statuses, index, changedFiles, repoRoot] = await Promise.all([
+          const [statuses, index] = await Promise.all([
             Promise.resolve(changeStatuses.getAll()),
             storyIndex.getIndex(),
-            git.getChangedFiles(),
-            git.getRepoRoot(),
           ]);
-          const files = [...new Set([...changedFiles.changed, ...changedFiles.new])].map((file) =>
-            resolvePath(repoRoot, file)
-          );
-          let unreachableFiles: string[] = [];
-          const status = await moduleGraph.queries.status.loaded(undefined);
-          if (status.value === 'ready') {
-            const storiesForFiles = await moduleGraph.queries.storiesForFiles.loaded({ files });
-            unreachableFiles = files.filter(
-              (_file, fileIndex) => storiesForFiles[fileIndex]?.length === 0
-            );
-          }
+
           const data = {
             ...getChangedStories({ statuses, index }),
-            unreachableFiles,
+            // Files outside the story graph are why an empty or partial result can still be wrong,
+            // so they are part of the answer rather than a separate lookup.
+            unreachableFiles: await detectUnreachableFiles({ git, moduleGraph }),
           };
-          return ctx.format === 'json' ? data : formatChangedStories(data);
+
+          await ctx.telemetry?.('tool:getChangedStories', {
+            storyCount: data.stories.length,
+            newStoryCount: data.counts.new,
+            modifiedStoryCount: data.counts.modified,
+            affectedStoryCount: data.counts.affected,
+          });
+
+          return { ok: true, data, markdown: formatChangedStories(data, ctx, { reviewEnabled }) };
         },
       },
       findByComponent: {
@@ -183,26 +272,70 @@ export function createStoriesToolset({
           componentPaths: v.pipe(
             v.array(v.string()),
             v.minLength(1),
-            v.description('Component file paths (absolute preferred).')
+            v.description(
+              `Absolute paths to component source files (e.g. "/repo/src/Button.tsx").
+Pass the components you actually want stories for — typically files you just read, edited, or that the user mentioned.
+Relative paths are also accepted and resolved against the Storybook working directory, but absolute paths are preferred for unambiguous results.
+Story files (\`*.stories.*\`) are accepted too: they appear at distance 0 as self-matches, plus any reverse-graph hits (other stories that import them).`
+            )
           ),
           maxDistance: v.pipe(
             v.optional(v.pipe(v.number(), v.minValue(1), v.integer())),
-            v.description('Maximum import-graph distance to include. Defaults to 3.')
+            v.description(
+              `Ceiling on the import depth to include in results. Must be a positive integer.
+- 1: only stories that directly import the component.
+- 2+: also include stories that reach the component through N hops.
+Defaults to ${DEFAULT_MAX_DISTANCE}; raise it to widen recall, lower it to tighten precision. Shared components (Button, Icon, …) accumulate noisy indirect matches at distance ≥ 3, so the default cap protects against runaway results.`
+            )
           ),
         }),
-        description: 'Finds stories that import the given component paths via the module graph.',
-        handler: async (input, ctx) => {
+        outputSchema: findByComponentOutputSchema,
+        title: 'Get stories for component files',
+        description: (ctx) => describeFindByComponent(ctx, reviewEnabled),
+        handler: async (input, ctx): Promise<ToolsetOutcome<FindByComponentOutput, never>> => {
           const moduleGraph = ctx.getService<ModuleGraphService>('core/module-graph', {
             internal: true,
           });
-          const index = await storyIndex.getIndex();
-          const data = await findStoriesByComponent({
+          const maxDistance = input.maxDistance ?? DEFAULT_MAX_DISTANCE;
+          const lookup = await findStoriesByComponent({
             componentPaths: input.componentPaths,
-            maxDistance: input.maxDistance,
-            index,
-            moduleGraph,
+            maxDistance,
+            index: await storyIndex.getIndex(),
+            // The service handle carries commands and a looser status payload than the lookup
+            // needs; this narrows it to the two queries the reverse-index walk actually calls.
+            moduleGraph: {
+              queries: {
+                status: {
+                  loaded: () =>
+                    moduleGraph.queries.status.loaded(undefined) as Promise<ModuleGraphStatus>,
+                },
+                storiesForFiles: {
+                  loaded: (files: { files: string[] }) =>
+                    moduleGraph.queries.storiesForFiles.loaded(files),
+                },
+              },
+            },
+          });
+
+          if (!lookup.available) {
+            throw new OpenServiceModuleGraphUnavailableError({ reason: lookup.reason });
+          }
+
+          const unmatchedCount = lookup.results.filter(
+            (result) => !result.pathNotFound && result.matches.length === 0
+          ).length;
+          await ctx.telemetry?.('tool:getStoriesByComponent', {
+            componentCount: input.componentPaths.length,
+            matchedComponentCount: input.componentPaths.length - unmatchedCount,
+            totalMatchCount: lookup.results.reduce(
+              (total, result) => total + result.matches.length,
+              0
+            ),
+            maxDistance,
           });
-          return ctx.format === 'json' ? data : formatFindByComponent(data);
+
+          const data: FindByComponentOutput = { results: lookup.results, maxDistance };
+          return { ok: true, data, markdown: formatFindByComponent(data, ctx) };
         },
       },
     },
diff --git a/code/core/src/shared/open-service/toolsets/test/definition.ts b/code/core/src/shared/open-service/toolsets/test/definition.ts
index 7fab504ea9d9..e23a1cd64cfd 100644
--- a/code/core/src/shared/open-service/toolsets/test/definition.ts
+++ b/code/core/src/shared/open-service/toolsets/test/definition.ts
@@ -1,9 +1,9 @@
 import * as v from 'valibot';
 
-import { defineToolset } from '../../toolset-definition.ts';
+import { defineToolset, type ToolsetCtx, type ToolsetOutcome } from '../../toolset-definition.ts';
 import type { StoryIndexAccess } from '../stories/definition.ts';
 import { storyInputArraySchema } from '../stories/story-input.ts';
-import { formatTestRun } from './format.ts';
+import { formatTestRun, summarizeTestRun } from './format.ts';
 import { createAsyncQueue, runStoryTests, type TestChannel } from './run.ts';
 
 const errorLikeSchema: v.GenericSchema = v.object({
@@ -62,6 +62,8 @@ const testRunResultSchema = v.object({
 const testRunOutputSchema = v.variant('status', [
   v.object({
     status: v.literal('no-stories'),
+    /** Per-selector lookup failures. When nothing matched, they are the whole answer. */
+    notFoundMessages: v.array(v.string()),
   }),
   v.object({
     status: v.literal('completed'),
@@ -82,50 +84,147 @@ const testRunOutputSchema = v.variant('status', [
 export type TestRunResult = v.InferOutput<typeof testRunResultSchema>;
 export type TestRunOutput = v.InferOutput<typeof testRunOutputSchema>;
 
+/**
+ * What `run` renders: the run result plus whether accessibility tests were part of this run, which
+ * the result payload itself does not state.
+ */
+export type TestRunData = TestRunOutput & { a11y: boolean };
+
+/**
+ * The outcome split for `test.run`: a crashed or cancelled run is a failure that still carries its
+ * full report, so clients keying on the tag cannot count it as a pass while agents keep the
+ * diagnostic detail.
+ */
+export type TestRunSuccessData = Extract<TestRunOutput, { status: 'completed' | 'no-stories' }> & {
+  a11y: boolean;
+};
+
+export type TestRunFailureData = Extract<TestRunOutput, { status: 'error' | 'cancelled' }> & {
+  a11y: boolean;
+};
+
+const runInputSchema = v.object({
+  stories: v.optional(
+    v.pipe(
+      storyInputArraySchema,
+      v.description(
+        `Stories to test for focused feedback. Omit this field to run tests for all available stories.
+Prefer running tests for specific stories while developing to get faster feedback,
+and only omit this when you explicitly need to run all tests for comprehensive verification.
+Prefer { storyId } when you don't already have story file context, since this avoids filesystem discovery.
+Use { storyId } when IDs were discovered from documentation tools.
+Use { absoluteStoryPath + exportName } only when you're currently working in a story file and already know those values.`
+      )
+    )
+  ),
+  a11y: v.optional(
+    v.pipe(
+      v.boolean(),
+      v.description(
+        'Whether to run accessibility tests. Defaults to true. Disable if you only need component test results.'
+      )
+    ),
+    true
+  ),
+});
+
+type RunInput = v.InferOutput<typeof runInputSchema>;
+
+/**
+ * The accessibility half of this tool's contract only holds when addon-a11y is enabled, so the
+ * promise is dropped from the description rather than made and then broken.
+ */
+function describeRun(a11yEnabled: boolean): string {
+  return (
+    `Run story tests.
+Run them after editing anything that changes how the UI looks — components, stories, styles, CSS, themes, colors, or design tokens — shell-level substitutes like typecheck, lint, or package.json test scripts do not replace this.
+Provide stories for focused runs (faster while iterating),
+or omit stories to run all tests for full-project verification.
+Use this continuously to monitor test results as you work on your UI components and stories.
+Results will include passing/failing status` +
+    (a11yEnabled
+      ? `, and accessibility violation reports.
+For visual/design accessibility violations (for example color contrast), ask the user before changing styles.`
+      : '.')
+  );
+}
+
+/**
+ * Reports a run that reached a verdict. A run that never got one — a channel error, a cancellation —
+ * stays silent, so the event counts runs whose numbers mean something.
+ */
+async function reportRunTelemetry(data: TestRunData, input: RunInput, ctx: ToolsetCtx) {
+  const inputStoryCount = input.stories?.length ?? 0;
+
+  if (data.status === 'no-stories') {
+    await ctx.telemetry?.('tool:runStoryTests', {
+      runA11y: data.a11y,
+      inputStoryCount,
+      matchedStoryCount: 0,
+      passingStoryCount: 0,
+      failingStoryCount: 0,
+      a11yViolationCount: 0,
+      unhandledErrorCount: 0,
+    });
+    return;
+  }
+
+  if (data.status !== 'completed') {
+    return;
+  }
+
+  await ctx.telemetry?.('tool:runStoryTests', {
+    runA11y: data.a11y,
+    inputStoryCount,
+    // A partially resolved selector list never reaches a run, so every input matched by this point.
+    matchedStoryCount: data.result.storyIds?.length ?? inputStoryCount,
+    ...summarizeTestRun(data.result, data.a11y),
+  });
+}
+
 export type CreateTestToolsetOptions = {
   channel: TestChannel;
   storyIndex: StoryIndexAccess;
+  /** Whether accessibility tests run alongside component tests (addon-a11y enabled). */
+  a11yEnabled: boolean;
 };
 
 /**
  * Creates the public test API. Each registration owns a queue because addon-vitest supports one
  * live test run at a time.
  */
-export function createTestToolset({ channel, storyIndex }: CreateTestToolsetOptions) {
+export function createTestToolset({ channel, storyIndex, a11yEnabled }: CreateTestToolsetOptions) {
   const queue = createAsyncQueue();
 
   return defineToolset({
     id: 'test',
     description: 'Run Storybook story tests via addon-vitest.',
+    telemetryGroup: 'test',
     methods: {
       run: {
-        schema: v.object({
-          stories: v.optional(
-            v.pipe(
-              storyInputArraySchema,
-              v.description('Stories to test. Omit to run all available stories.')
-            )
-          ),
-          a11y: v.optional(
-            v.pipe(
-              v.boolean(),
-              v.description('Whether to include accessibility tests. Defaults to true.')
-            ),
-            true
-          ),
-        }),
-        description:
-          'Runs story tests for the given selectors, or all stories when stories is omitted.',
-        handler: async (input, ctx) => {
+        schema: runInputSchema,
+        title: 'Storybook Tests',
+        description: describeRun(a11yEnabled),
+        handler: async (
+          input,
+          ctx
+        ): Promise<ToolsetOutcome<TestRunSuccessData, TestRunFailureData>> => {
           const done = await queue.wait();
           try {
-            const result = await runStoryTests({
+            const output = await runStoryTests({
               channel,
               getIndex: storyIndex.getIndex,
               stories: input.stories,
               a11y: input.a11y,
             });
-            return ctx.format === 'json' ? result : formatTestRun(result);
+            const data: TestRunData = { ...output, a11y: input.a11y };
+
+            await reportRunTelemetry(data, input, ctx);
+
+            const markdown = formatTestRun(data, ctx);
+            return data.status === 'error' || data.status === 'cancelled'
+              ? { ok: false, data, markdown }
+              : { ok: true, data, markdown };
           } finally {
             done();
           }

From 539cf0217f0ab5a35fce994d366f0c70e9f0d245 Mon Sep 17 00:00:00 2001
From: Kasper Peulen <kasperpeulen@gmail.com>
Date: Tue, 4 Aug 2026 13:44:02 +0200
Subject: [PATCH 4/6] =?UTF-8?q?Review=204/6=20=E2=80=94=20the=20docs=20acc?=
 =?UTF-8?q?ess=20machinery?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../toolsets/docs/access-local.ts             |  53 ++
 .../toolsets/docs/access-manifest.ts          | 121 +++++
 .../toolsets/docs/access-provider.ts          | 505 ++++++++++++++++++
 .../toolsets/docs/access-service.ts           | 261 +++++++++
 .../open-service/toolsets/docs/access.ts      |  50 ++
 .../toolsets/docs/instructions.ts             |  24 +
 .../toolsets/docs/multi-source.ts             | 104 ++++
 .../open-service/toolsets/docs/public.ts      |  91 ++++
 .../open-service/toolsets/docs/sources.ts     |  97 ++++
 9 files changed, 1306 insertions(+)
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-local.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-manifest.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-provider.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-service.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/instructions.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/multi-source.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/public.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/sources.ts

diff --git a/code/core/src/shared/open-service/toolsets/docs/access-local.ts b/code/core/src/shared/open-service/toolsets/docs/access-local.ts
new file mode 100644
index 000000000000..97bb6f22753d
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-local.ts
@@ -0,0 +1,53 @@
+/**
+ * Local docs access with registration-based selection between the two engines.
+ *
+ * Docgen-server mode moves docs data out of the served manifests and into the open services, but
+ * the `experimentalDocgenServer` flag alone is not enough to read from them: the docgen
+ * registrations are skipped for manager-only builds and when no docgen worker is available. Every
+ * consumer that reads the local Storybook — core's own docs toolset and a composition's local
+ * source alike — must make the same choice, so it lives here: the services when they actually
+ * registered, and otherwise the manifests, which every mode still writes.
+ *
+ * The registry probe runs per call, because some consumers (addon-mcp's dev-server hook) create
+ * this access before the `services` preset hooks have necessarily run.
+ */
+
+import type { StoryIndex } from 'storybook/internal/types';
+
+import { DOCGEN_SERVICE_ID } from '../../services/docgen/paths.ts';
+import { STORY_DOCS_SERVICE_ID } from '../../services/story-docs/paths.ts';
+import { getRegisteredServices, getService } from '../../service-registry.ts';
+import type { ToolsetGetService } from '../../toolset-definition.ts';
+import { createManifestDocsAccess, type RawManifests } from './access-manifest.ts';
+import { createServiceDocsAccess } from './access-service.ts';
+import type { DocsAccess } from './access.ts';
+
+export type LocalDocsAccessOptions = {
+  storyIndex: { getIndex: () => Promise<StoryIndex> };
+  /** Reads the live inline manifests, e.g. core-server's `loadManifests`. */
+  getManifests: () => Promise<RawManifests>;
+};
+
+export function createLocalDocsAccess({
+  storyIndex,
+  getManifests,
+}: LocalDocsAccessOptions): DocsAccess {
+  const serviceAccess = createServiceDocsAccess({
+    storyIndex,
+    getService: getService as ToolsetGetService,
+  });
+  const manifestAccess = createManifestDocsAccess({ getManifests });
+  // The service access hard-requires every one of these; a partial registration would make every
+  // call throw, so it degrades to the manifests instead of trusting that core's registration block
+  // always registers them together.
+  const requiredServiceIds = [DOCGEN_SERVICE_ID, STORY_DOCS_SERVICE_ID];
+  const pick = () => {
+    const registered = new Set(getRegisteredServices().map((service) => service.id));
+    return requiredServiceIds.every((id) => registered.has(id)) ? serviceAccess : manifestAccess;
+  };
+
+  return {
+    list: (options) => pick().list(options),
+    resolve: (id) => pick().resolve(id),
+  };
+}
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-manifest.ts b/code/core/src/shared/open-service/toolsets/docs/access-manifest.ts
new file mode 100644
index 000000000000..840c972c7d1b
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-manifest.ts
@@ -0,0 +1,121 @@
+/**
+ * Docs access backed by the manifests core builds itself (the default mode, with
+ * `experimentalDocgenServer` off).
+ *
+ * Those manifests are fully inline: component rows carry their docgen, stories, and attached MDX
+ * content, and standalone docs carry their MDX content. `$ref` indirection only appears in
+ * docgen-server mode, which `createServiceDocsAccess` covers instead — so listing and resolving are
+ * plain lookups here.
+ *
+ * The loader is injected because the manifests are assembled in `core-server`, which the docs
+ * toolset must not import.
+ */
+
+import { emptyManifests, type DocsAccess, type ResolvedDocsEntry } from './access.ts';
+import type {
+  AllManifests,
+  ComponentManifest,
+  ComponentManifestMap,
+  ComponentManifestV0,
+  ComponentManifestV1,
+  DocsManifestMap,
+  DocV0,
+  DocV1,
+} from './manifest-formatter/manifest-types.ts';
+
+/** The manifests as they leave core's manifest builder, before any shape is assumed. */
+export type RawManifests = {
+  components?: unknown;
+  docs?: unknown;
+};
+
+export type ManifestDocsAccessOptions = {
+  getManifests: () => Promise<RawManifests>;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Anything other than an explicit `v: 1` is the inline (v0) format. */
+function isShallow(manifest: Record<string, unknown>): boolean {
+  return manifest.v === 1;
+}
+
+function toComponentManifest(value: unknown): ComponentManifestMap | undefined {
+  if (!isRecord(value) || !isRecord(value.components)) {
+    return undefined;
+  }
+  return isShallow(value)
+    ? { v: 1, components: value.components as Record<string, ComponentManifestV1> }
+    : { v: 0, components: value.components as Record<string, ComponentManifestV0> };
+}
+
+function toDocsManifest(value: unknown): DocsManifestMap | undefined {
+  if (!isRecord(value) || !isRecord(value.docs)) {
+    return undefined;
+  }
+  return isShallow(value)
+    ? { v: 1, docs: value.docs as Record<string, DocV1> }
+    : { v: 0, docs: value.docs as Record<string, DocV0> };
+}
+
+/**
+ * Inline manifests always carry their stories. `list` promises story ids only when they were asked
+ * for, so drop them otherwise and keep the listing shape identical across access implementations.
+ */
+function withoutStories(manifest: ComponentManifestMap): ComponentManifestMap {
+  const components = Object.fromEntries(
+    Object.entries(manifest.components).map(([id, { stories: _stories, ...rest }]) => [id, rest])
+  );
+  return manifest.v === 1
+    ? { v: 1, components: components as Record<string, ComponentManifestV1> }
+    : { v: 0, components: components as Record<string, ComponentManifestV0> };
+}
+
+export function createManifestDocsAccess({ getManifests }: ManifestDocsAccessOptions): DocsAccess {
+  return {
+    async list({ withStoryIds }): Promise<AllManifests> {
+      const raw = await getManifests();
+      const componentManifest = toComponentManifest(raw.components);
+      const docsManifest = toDocsManifest(raw.docs);
+
+      return {
+        ...emptyManifests(),
+        ...(componentManifest
+          ? {
+              componentManifest: withStoryIds
+                ? componentManifest
+                : withoutStories(componentManifest),
+            }
+          : {}),
+        ...(docsManifest ? { docsManifest } : {}),
+      };
+    },
+
+    async resolve(id): Promise<ResolvedDocsEntry | undefined> {
+      const raw = await getManifests();
+
+      // Cast: these manifests are inline, so a row is already the resolved shape. A shallow row
+      // could only appear in docgen-server mode, which `createServiceDocsAccess` serves instead;
+      // if one did, its `$ref`s would simply not render, as before.
+      // Own-property guards: a prototype member like `constructor` must answer "not found".
+      const components = toComponentManifest(raw.components)?.components;
+      const component =
+        components && Object.hasOwn(components, id)
+          ? (components[id] as ComponentManifest | undefined)
+          : undefined;
+      if (component) {
+        return { kind: 'component', component };
+      }
+
+      const docs = toDocsManifest(raw.docs)?.docs;
+      const doc = docs && Object.hasOwn(docs, id) ? docs[id] : undefined;
+      if (doc) {
+        return { kind: 'doc', doc };
+      }
+
+      return undefined;
+    },
+  };
+}
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-provider.ts b/code/core/src/shared/open-service/toolsets/docs/access-provider.ts
new file mode 100644
index 000000000000..62cc2f08ae2f
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-provider.ts
@@ -0,0 +1,505 @@
+/**
+ * Docs access backed by manifest files, wherever they are served from.
+ *
+ * This is the access a hosted Storybook uses: the manifests arrive as JSON over a provider (HTTP by
+ * default, but the caller can supply any fetcher — S3, a static bundle, an authenticated proxy), so
+ * they are untrusted input and are validated on arrival. In the split/ref (v1) format the index
+ * rows only carry `$ref`s to externalized payloads, which are followed here so the toolset always
+ * receives fully-assembled entries.
+ *
+ * Refs are read verbatim from the entry and never fabricated from an id, so a provider is only ever
+ * asked for a top-level manifest path or a path a manifest already pointed at.
+ */
+
+import * as v from 'valibot';
+
+import {
+  adaptCoreComponent,
+  adaptCoreDoc,
+  adaptCoreStories,
+  type CoreDocgenComponent,
+} from './manifest-formatter/adapt-core-manifest.ts';
+import {
+  ComponentManifestMap,
+  DocsManifestMap,
+  type AllManifests,
+  type ComponentManifest,
+  type ComponentManifestEntry,
+  type Doc,
+  type DocEntry,
+} from './manifest-formatter/manifest-types.ts';
+import { emptyManifests, type DocsAccess, type ResolvedDocsEntry } from './access.ts';
+import { mapWithConcurrency } from './map-with-concurrency.ts';
+import { ManifestGetError, RequiresOwnMcpError, type Source } from './sources.ts';
+
+/** Cap on in-flight story `$ref` fetches while expanding one source's listing. */
+const STORY_REF_CONCURRENCY = 16;
+
+/** Where the top-level manifests live, relative to the Storybook build. */
+export const COMPONENT_MANIFEST_PATH = './manifests/components.json';
+export const DOCS_MANIFEST_PATH = './manifests/docs.json';
+
+/**
+ * Fetches one manifest file by path. `request` is the incoming MCP request, which the default
+ * provider uses to derive the origin; custom providers may ignore it.
+ */
+export type ManifestProvider = (
+  request: Request | undefined,
+  path: string,
+  source?: Source
+) => Promise<string>;
+
+export type ProviderDocsAccessOptions = {
+  manifestProvider?: ManifestProvider;
+  /** The in-flight request. Read per call, because the access outlives any single request. */
+  getRequest?: () => Request | undefined;
+  /** The composed source this access reads, when part of a composition. */
+  source?: Source;
+  /**
+   * Resolves a single entry in-process, bypassing the manifest index. The dev server passes this
+   * for its local source when `experimentalDocgenServer` is on, so one lookup never triggers
+   * docgen extraction for every component.
+   */
+  resolveEntry?: (id: string, source?: Source) => Promise<ResolvedDocsEntry | undefined>;
+};
+
+function getManifestUrlFromRequest(request: Request, path: string): string {
+  return new URL(`/${path.replace(/^\.\//, '')}`, request.url).toString();
+}
+
+async function defaultManifestProvider(
+  request: Request | undefined,
+  path: string
+): Promise<string> {
+  if (!request) {
+    throw new ManifestGetError(
+      "Request is required when using the default manifest provider. You must either pass the original request forward to the server context, or set a custom manifestProvider that doesn't need the request."
+    );
+  }
+  const manifestUrl = getManifestUrlFromRequest(request, path);
+  const response = await fetch(manifestUrl);
+
+  if (!response.ok) {
+    throw new ManifestGetError(
+      `Failed to fetch manifest: ${response.status} ${response.statusText}`,
+      manifestUrl
+    );
+  }
+
+  const contentType = response.headers.get('content-type');
+  if (!contentType?.includes('application/json')) {
+    throw new ManifestGetError(
+      `Invalid content type: expected application/json, got ${contentType}`,
+      manifestUrl
+    );
+  }
+  return response.text();
+}
+
+function parseManifest<T extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>({
+  jsonString,
+  schema,
+  name,
+  url,
+}: {
+  jsonString: string;
+  schema: T;
+  name: string;
+  url: string;
+}): v.InferOutput<T> {
+  try {
+    return v.parse(v.pipe(v.string(), v.parseJson(), schema), jsonString);
+  } catch (error) {
+    throw new ManifestGetError(
+      `Failed to parse ${name} manifest:
+${error instanceof v.ValiError ? error.issues.map((i) => i.message).join('\n') : String(error)}`,
+      url
+    );
+  }
+}
+
+/** Fetches and validates the component and docs manifests for one source. */
+export async function fetchManifests(
+  request?: Request,
+  manifestProvider?: ManifestProvider,
+  source?: Source
+): Promise<AllManifests> {
+  const provider = manifestProvider ?? defaultManifestProvider;
+
+  const [componentResult, docsResult] = await Promise.allSettled([
+    provider(request, COMPONENT_MANIFEST_PATH, source),
+    provider(request, DOCS_MANIFEST_PATH, source),
+  ]);
+
+  const getUrl = (path: string) =>
+    request ? getManifestUrlFromRequest(request, path) : 'Unknown manifest source';
+
+  if (componentResult.status === 'rejected') {
+    const reason = componentResult.reason;
+    if (reason instanceof RequiresOwnMcpError) {
+      throw reason;
+    }
+    const is404 = reason instanceof ManifestGetError && reason.message.includes('404');
+    const hint = is404
+      ? `\nHint: The Storybook at this URL may not have the component manifest enabled. Add \`features: { componentsManifest: true }\` (or \`features: { experimentalComponentsManifest: true }\` for older Storybook versions) to its main.ts config.`
+      : '';
+    throw new ManifestGetError(
+      `Failed to get component manifest: ${reason instanceof Error ? reason.message : String(reason)}${hint}`,
+      getUrl(COMPONENT_MANIFEST_PATH),
+      reason instanceof Error ? reason : undefined
+    );
+  }
+
+  const componentManifest = parseManifest({
+    jsonString: componentResult.value,
+    schema: ComponentManifestMap,
+    name: 'component',
+    url: getUrl(COMPONENT_MANIFEST_PATH),
+  });
+
+  if (Object.keys(componentManifest.components).length === 0) {
+    throw new ManifestGetError(
+      `No components found in the manifest`,
+      getUrl(COMPONENT_MANIFEST_PATH)
+    );
+  }
+
+  if (docsResult.status === 'rejected') {
+    return { componentManifest };
+  }
+
+  const docsManifest = parseManifest({
+    jsonString: docsResult.value,
+    schema: DocsManifestMap,
+    name: 'docs',
+    url: getUrl(DOCS_MANIFEST_PATH),
+  });
+
+  return { componentManifest, docsManifest };
+}
+
+/**
+ * Resolves a `$ref` into the provider path of the referenced file and the JSON-pointer segments
+ * into it.
+ *
+ * The path is relative to the component manifest's location, e.g.
+ * `"../services/core/docgen/button.json#/components/button"` resolves to
+ * `./services/core/docgen/button.json` with pointer `["components", "button"]`.
+ */
+export function parseManifestRef(ref: string): { path: string; pointer: string[] } {
+  const [filePath = '', hash = ''] = ref.split('#');
+
+  const manifestDir = COMPONENT_MANIFEST_PATH.replace(/^\.\//, '').replace(/[^/]+$/, '');
+  const resolved = new URL(filePath, `https://localhost/${manifestDir}`).pathname.replace(
+    /^\//,
+    ''
+  );
+
+  const pointer = hash
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));
+
+  return { path: `./${resolved}`, pointer };
+}
+
+/**
+ * Envelopes for the three kinds of payload a `$ref` can point at.
+ *
+ * These check the shape the adapters actually read, not the full docgen format: the payloads carry
+ * renderer-specific fields that core must pass through untouched, so a strict schema here would
+ * reject valid manifests. What matters is that a hosted Storybook cannot hand the adapters a string
+ * or an array where they expect a record.
+ */
+/**
+ * A JSON object. `looseObject` alone would let an array through, since arrays are objects, and the
+ * adapters then read `.name` / `.stories` off it and silently produce an empty component.
+ */
+const jsonObject = <TSchema extends v.GenericSchema>(schema: TSchema) =>
+  v.pipe(
+    // Checked on the raw input: `looseObject` copies an array's entries into a plain object, so by
+    // the time it has run there is nothing left to recognise.
+    v.custom<unknown>((input) => !Array.isArray(input), 'Expected a JSON object'),
+    schema
+  );
+
+const DocgenRefPayload = jsonObject(v.looseObject({}));
+const StoryDocsRefPayload = v.nullable(
+  jsonObject(
+    v.looseObject({
+      // A record keyed by story id, or an already-resolved array — `adaptCoreStories` accepts both.
+      stories: v.optional(
+        v.union([v.record(v.string(), v.looseObject({})), v.array(v.looseObject({}))])
+      ),
+      import: v.optional(v.string()),
+    })
+  )
+);
+const MdxRefPayload = jsonObject(
+  v.looseObject({ id: v.optional(v.string()), name: v.optional(v.string()) })
+);
+
+/** Fetches the file a `$ref` points at, walks its JSON pointer and validates what it lands on. */
+async function fetchRefValue<T>(
+  ref: string,
+  request: Request | undefined,
+  provider: ManifestProvider,
+  source: Source | undefined,
+  schema: v.GenericSchema
+): Promise<T> {
+  const { path, pointer } = parseManifestRef(ref);
+  const jsonString = await provider(request, path, source);
+
+  let target: unknown;
+  try {
+    target = JSON.parse(jsonString);
+  } catch (error) {
+    throw new ManifestGetError(
+      `Failed to parse externalized payload referenced by "${ref}"`,
+      path,
+      error instanceof Error ? error : undefined
+    );
+  }
+
+  for (const key of pointer) {
+    // Own properties only: the pointer comes from a fetched manifest, so `constructor` or
+    // `__proto__` would otherwise walk into the prototype instead of failing as unresolvable.
+    if (target && typeof target === 'object' && Object.hasOwn(target, key)) {
+      target = (target as Record<string, unknown>)[key];
+    } else {
+      throw new ManifestGetError(
+        `Reference "${ref}" could not be resolved: missing "${key}".`,
+        path
+      );
+    }
+  }
+
+  const parsed = v.safeParse(schema, target);
+  if (!parsed.success) {
+    throw new ManifestGetError(
+      `Payload referenced by "${ref}" is not a valid manifest payload.`,
+      path
+    );
+  }
+
+  return parsed.output as T;
+}
+
+/**
+ * Resolves a component index row into a full component manifest by following any `$ref`s it carries
+ * (docgen, story-docs, attached MDX), then adapting the payloads into the formatter's shape. Rows
+ * without any `$ref` are already in resolved (inline/v0) form and are returned unchanged.
+ */
+export async function resolveComponentEntry(
+  component: ComponentManifestEntry,
+  request?: Request,
+  manifestProvider?: ManifestProvider,
+  source?: Source
+): Promise<ComponentManifest> {
+  const docgenRef = 'docgen' in component ? component.docgen?.$ref : undefined;
+  const storiesRef =
+    component.stories && !Array.isArray(component.stories) ? component.stories.$ref : undefined;
+  const docEntries: [string, DocEntry][] = component.docs ? Object.entries(component.docs) : [];
+  const docRefs = docEntries.filter(([, doc]) => 'mdx' in doc && !!doc.mdx?.$ref);
+
+  if (!docgenRef && !storiesRef && docRefs.length === 0) {
+    return component as ComponentManifest;
+  }
+
+  const provider = manifestProvider ?? defaultManifestProvider;
+
+  // Identity fields from the index row are authoritative; the docgen payload supplies
+  // path/props/jsDocTags/subcomponents.
+  const identity = {
+    id: component.id,
+    name: component.name,
+    ...(component.description !== undefined ? { description: component.description } : {}),
+    ...(component.summary !== undefined ? { summary: component.summary } : {}),
+    ...(component.error !== undefined ? { error: component.error } : {}),
+  };
+
+  let core: CoreDocgenComponent = identity;
+
+  if (docgenRef) {
+    const payload = await fetchRefValue<CoreDocgenComponent>(
+      docgenRef,
+      request,
+      provider,
+      source,
+      DocgenRefPayload
+    );
+    core = { ...core, ...payload, ...identity };
+  }
+
+  // Preserve inline stories (mixed/v0) when there's no story-docs ref to follow.
+  if (Array.isArray(component.stories)) {
+    core.stories = component.stories;
+  }
+
+  if (storiesRef) {
+    const storyDocs = await fetchRefValue<{
+      stories?: CoreDocgenComponent['stories'];
+      import?: string;
+    } | null>(storiesRef, request, provider, source, StoryDocsRefPayload);
+    if (storyDocs?.stories) {
+      core.stories = storyDocs.stories;
+    }
+    if (storyDocs?.import) {
+      core.import = storyDocs.import;
+    }
+  }
+
+  if (docEntries.length > 0) {
+    const docs: Record<string, Doc> = {};
+    for (const [docId, doc] of docEntries) {
+      const mdxRef = 'mdx' in doc ? doc.mdx?.$ref : undefined;
+      docs[docId] = mdxRef
+        ? await fetchRefValue<Doc>(mdxRef, request, provider, source, MdxRefPayload)
+        : (doc as Doc);
+    }
+    core.docs = docs;
+  }
+
+  return adaptCoreComponent(core);
+}
+
+/**
+ * Resolves only a component's stories `$ref`, leaving docgen and docs refs untouched. Listing with
+ * story ids uses this so it doesn't pay for docgen and MDX resolution it won't show.
+ */
+export async function resolveComponentStories(
+  component: ComponentManifestEntry,
+  request?: Request,
+  manifestProvider?: ManifestProvider,
+  source?: Source
+): Promise<ComponentManifestEntry> {
+  if (!component.stories || Array.isArray(component.stories)) {
+    return component;
+  }
+
+  const provider = manifestProvider ?? defaultManifestProvider;
+  const storyDocs = await fetchRefValue<{ stories?: CoreDocgenComponent['stories'] } | null>(
+    component.stories.$ref,
+    request,
+    provider,
+    source,
+    StoryDocsRefPayload
+  );
+
+  return {
+    ...component,
+    stories: storyDocs?.stories ? (adaptCoreStories(storyDocs.stories) ?? []) : [],
+  };
+}
+
+/** Resolves a standalone docs row, following its `mdx.$ref` when present. */
+export async function resolveDocEntry(
+  doc: DocEntry,
+  request?: Request,
+  manifestProvider?: ManifestProvider,
+  source?: Source
+): Promise<Doc> {
+  const ref = 'mdx' in doc ? doc.mdx?.$ref : undefined;
+  if (!ref) {
+    return doc as Doc;
+  }
+
+  const provider = manifestProvider ?? defaultManifestProvider;
+  const payload = await fetchRefValue<Doc>(ref, request, provider, source, MdxRefPayload);
+
+  return adaptCoreDoc({
+    ...payload,
+    id: payload.id ?? doc.id,
+    name: payload.name ?? doc.name,
+  });
+}
+
+/** Docs access over manifest files served by a provider. */
+export function createProviderDocsAccess({
+  manifestProvider,
+  getRequest,
+  source,
+  resolveEntry,
+}: ProviderDocsAccessOptions = {}): DocsAccess {
+  const request = () => getRequest?.();
+
+  return {
+    async list({ withStoryIds }): Promise<AllManifests> {
+      const manifests = await fetchManifests(request(), manifestProvider, source);
+
+      // The split/ref format keeps stories behind a `$ref`, so resolve them only when story ids
+      // were asked for and plain listing stays cheap. One `$ref` per component means a large
+      // Storybook would otherwise open hundreds of connections to the host at once.
+      if (withStoryIds) {
+        const components = manifests.componentManifest.components as Record<
+          string,
+          ComponentManifestEntry
+        >;
+        try {
+          const resolved = await mapWithConcurrency(
+            Object.entries(components),
+            STORY_REF_CONCURRENCY,
+            async ([id, component]) =>
+              [
+                id,
+                await resolveComponentStories(component, request(), manifestProvider, source),
+              ] as const
+          );
+          for (const [id, component] of resolved) {
+            components[id] = component;
+          }
+        } catch (error) {
+          // One composed source must not lose its whole listing because a single story `$ref` was
+          // unreachable: leave its rows unresolved instead. A single Storybook has no other source
+          // to fall back on, so there the failure is the answer.
+          if (!source) {
+            throw error;
+          }
+        }
+      }
+
+      return { ...emptyManifests(), ...manifests };
+    },
+
+    async resolve(id): Promise<ResolvedDocsEntry | undefined> {
+      // The in-process services back the local Storybook only, so a source with a URL always goes
+      // through the fetch path below.
+      if (resolveEntry && !source?.url) {
+        return resolveEntry(id, source);
+      }
+
+      const { componentManifest, docsManifest } = await fetchManifests(
+        request(),
+        manifestProvider,
+        source
+      );
+
+      // Own-property guards: ids come straight from the agent, and a prototype member like
+      // `constructor` must answer "not found" rather than render as a component.
+      const components = componentManifest.components as Record<string, ComponentManifestEntry>;
+      const componentEntry = Object.hasOwn(components, id) ? components[id] : undefined;
+      if (componentEntry) {
+        return {
+          kind: 'component',
+          component: await resolveComponentEntry(
+            componentEntry,
+            request(),
+            manifestProvider,
+            source
+          ),
+        };
+      }
+
+      const docs = docsManifest?.docs as Record<string, DocEntry> | undefined;
+      const docEntry = docs && Object.hasOwn(docs, id) ? docs[id] : undefined;
+      if (docEntry) {
+        return {
+          kind: 'doc',
+          doc: await resolveDocEntry(docEntry, request(), manifestProvider, source),
+        };
+      }
+
+      return undefined;
+    },
+  };
+}
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-service.ts b/code/core/src/shared/open-service/toolsets/docs/access-service.ts
new file mode 100644
index 000000000000..76a37d97656b
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-service.ts
@@ -0,0 +1,261 @@
+/**
+ * Docs access backed by the live open services (docgen-server mode, selected when the docgen
+ * services actually registered — see `createLocalDocsAccess`).
+ *
+ * Two properties make this different from reading the service aggregates directly. Visibility comes
+ * from the story index, so the listing matches what core's manifest generator would emit — same
+ * `manifest` tag filter, same component selection, same order — instead of whatever happens to have
+ * been extracted so far. And single-entry lookups use the per-id queries, so resolving one
+ * component never triggers docgen extraction for every component.
+ */
+
+import type { StoryIndex } from 'storybook/internal/types';
+
+import { getComponentIdFromEntry } from '../../../../common/utils/component-id.ts';
+import { selectComponentEntriesByComponentId } from '../../../../common/utils/select-component-entry.ts';
+import {
+  OpenServiceDocgenMissingComponentError,
+  OpenServiceMissingServiceError,
+} from '../../../../server-errors.ts';
+import { Tag } from '../../../constants/tags.ts';
+import type { DocgenService } from '../../services/docgen/definition.ts';
+import type { StoryDocsService } from '../../services/story-docs/definition.ts';
+import type { ToolsetGetService } from '../../toolset-definition.ts';
+import { toShallowManifests, type DocsAccess, type ResolvedDocsEntry } from './access.ts';
+import type { DocsClassification } from './classify-services.ts';
+import {
+  adaptCoreComponent,
+  adaptCoreDoc,
+  adaptCoreStories,
+  type CoreDocgenComponent,
+} from './manifest-formatter/adapt-core-manifest.ts';
+import type { ComponentManifestV1, DocV1 } from './manifest-formatter/manifest-types.ts';
+import { selectAttachedDocs, type MdxPayload } from './map.ts';
+
+/** Stable addon-docs MDX service id. Kept local so the docs toolset does not import core-server. */
+const MDX_SERVICE_ID = 'addon-docs/mdx';
+
+type MdxService = {
+  queries: {
+    mdxForAllComponents: {
+      loaded: () => Promise<Record<string, MdxPayload | undefined>>;
+    };
+    mdxForComponent: {
+      loaded: (input: { id: string }) => Promise<MdxPayload | undefined>;
+    };
+  };
+};
+
+export type ServiceDocsAccessOptions = {
+  storyIndex: { getIndex: () => Promise<StoryIndex> };
+  getService: ToolsetGetService;
+};
+
+/**
+ * Derives the visible set from the story index using core's manifest rules.
+ *
+ * Component ids keep story-index order: the sidebar order is the order a reader expects, and
+ * re-sorting here would silently disagree with every other manifest surface.
+ */
+function classifyIndex(index: StoryIndex): DocsClassification {
+  const entries = Object.values(index.entries).filter(
+    (entry) => entry.tags?.includes(Tag.MANIFEST) ?? false
+  );
+  const selected = selectComponentEntriesByComponentId(entries);
+
+  const storyBasedIds = new Set<string>();
+  for (const [id, entry] of selected) {
+    if (entry.type === 'story') {
+      storyBasedIds.add(id);
+    }
+  }
+
+  const attachedDocsByComponent = new Map<string, string[]>();
+  const unattachedDocs = new Map<string, string>();
+  for (const entry of entries) {
+    if (entry.type !== 'docs') {
+      continue;
+    }
+    if (entry.tags?.includes(Tag.UNATTACHED_MDX)) {
+      unattachedDocs.set(entry.id, entry.name);
+    } else if (entry.tags?.includes(Tag.ATTACHED_MDX)) {
+      const componentId = getComponentIdFromEntry(entry);
+      attachedDocsByComponent.set(componentId, [
+        ...(attachedDocsByComponent.get(componentId) ?? []),
+        entry.id,
+      ]);
+    }
+  }
+
+  return {
+    componentIds: [...selected.keys()],
+    storyBasedIds,
+    unattachedDocs,
+    attachedDocsByComponent,
+  };
+}
+
+/** Optional services resolve to `undefined` rather than throwing when they are not registered. */
+function tryGetService<T>(getService: ToolsetGetService, serviceId: string): T | undefined {
+  try {
+    return getService<T>(serviceId, { internal: true });
+  } catch (error) {
+    if (error instanceof OpenServiceMissingServiceError) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Component payload loads throw when an id has no component entry in the index. Standalone docs ids
+ * and ids that don't exist at all both land there, and both are answered by absence rather than a
+ * failure, so the typed error becomes `undefined`.
+ */
+async function loadOptionalComponentPayload<T>(
+  load: Promise<T | undefined>
+): Promise<T | undefined> {
+  try {
+    return await load;
+  } catch (error) {
+    if (error instanceof OpenServiceDocgenMissingComponentError) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export function createServiceDocsAccess({
+  storyIndex,
+  getService,
+}: ServiceDocsAccessOptions): DocsAccess {
+  // The index and the services are read on every call. Both cache internally, and re-reading is
+  // what keeps the toolset in lock-step with HMR.
+  const classify = async () => classifyIndex(await storyIndex.getIndex());
+  const getDocgen = () => getService<DocgenService>('core/docgen', { internal: true });
+  const getStoryDocs = () => getService<StoryDocsService>('core/story-docs', { internal: true });
+  const getMdx = () => tryGetService<MdxService>(getService, MDX_SERVICE_ID);
+
+  async function listComponents(
+    classification: DocsClassification,
+    withStoryIds: boolean
+  ): Promise<Record<string, ComponentManifestV1>> {
+    // Every component must be listed even without a prior extraction, so load rather than read.
+    const allDocgen = await getDocgen().queries.docgenForAllComponents.loaded();
+
+    const storyDocs = getStoryDocs();
+    const storyBasedIds = withStoryIds
+      ? classification.componentIds.filter((id) => classification.storyBasedIds.has(id))
+      : [];
+    // Per-id loads, so listing without story ids never pays for story-docs extraction.
+    const storiesById = new Map(
+      await Promise.all(
+        storyBasedIds.map(
+          async (id) =>
+            [
+              id,
+              await loadOptionalComponentPayload(storyDocs.queries.storyDocs.loaded({ id })),
+            ] as const
+        )
+      )
+    );
+
+    const components: Record<string, ComponentManifestV1> = {};
+    for (const id of classification.componentIds) {
+      const payload = allDocgen[id];
+      components[id] = {
+        id,
+        name: payload?.name ?? id,
+        ...(payload?.description !== undefined ? { description: payload.description } : {}),
+        ...(payload?.summary !== undefined ? { summary: payload.summary } : {}),
+        ...(classification.storyBasedIds.has(id) && withStoryIds
+          ? { stories: adaptCoreStories(storiesById.get(id)?.stories) ?? [] }
+          : {}),
+      };
+    }
+
+    return components;
+  }
+
+  async function listDocs(classification: DocsClassification): Promise<Record<string, DocV1>> {
+    if (classification.unattachedDocs.size === 0) {
+      return {};
+    }
+
+    const allMdx = (await getMdx()?.queries.mdxForAllComponents.loaded()) ?? {};
+
+    const docs: Record<string, DocV1> = {};
+    for (const [docId, name] of classification.unattachedDocs) {
+      // The display name comes from the index entry: it exists even when the MDX service does not.
+      const payload = allMdx[docId]?.docs?.[docId];
+      docs[docId] = {
+        id: docId,
+        name,
+        ...(payload?.summary !== undefined ? { summary: payload.summary } : {}),
+      };
+    }
+
+    return docs;
+  }
+
+  async function resolveComponent(
+    id: string,
+    classification: DocsClassification
+  ): Promise<ResolvedDocsEntry> {
+    const mdx = getMdx();
+    const [docgenPayload, storyDocsPayload] = await Promise.all([
+      loadOptionalComponentPayload(getDocgen().queries.docgen.loaded({ id })),
+      loadOptionalComponentPayload(getStoryDocs().queries.storyDocs.loaded({ id })),
+    ]);
+
+    const hasAttachedDocs = (classification.attachedDocsByComponent.get(id)?.length ?? 0) > 0;
+    const mdxPayload =
+      hasAttachedDocs && mdx
+        ? await loadOptionalComponentPayload(mdx.queries.mdxForComponent.loaded({ id }))
+        : undefined;
+    const docs = selectAttachedDocs(classification, id, mdxPayload);
+
+    const core: CoreDocgenComponent = {
+      ...docgenPayload,
+      id,
+      name: docgenPayload?.name ?? id,
+      ...(storyDocsPayload?.stories ? { stories: storyDocsPayload.stories } : {}),
+      ...(storyDocsPayload?.import ? { import: storyDocsPayload.import } : {}),
+      ...(docs ? { docs } : {}),
+    };
+
+    return { kind: 'component', component: adaptCoreComponent(core) };
+  }
+
+  async function resolveStandaloneDoc(id: string): Promise<ResolvedDocsEntry | undefined> {
+    const mdx = getMdx();
+    const payload = mdx
+      ? await loadOptionalComponentPayload(mdx.queries.mdxForComponent.loaded({ id }))
+      : undefined;
+    const doc = payload?.docs?.[id];
+    return doc ? { kind: 'doc', doc: adaptCoreDoc(doc) } : undefined;
+  }
+
+  return {
+    async list({ withStoryIds }) {
+      const classification = await classify();
+      const [components, docs] = await Promise.all([
+        listComponents(classification, withStoryIds),
+        listDocs(classification),
+      ]);
+      return toShallowManifests(components, docs);
+    },
+
+    async resolve(id) {
+      const classification = await classify();
+
+      if (classification.unattachedDocs.has(id)) {
+        return resolveStandaloneDoc(id);
+      }
+      if (classification.componentIds.includes(id)) {
+        return resolveComponent(id, classification);
+      }
+      return undefined;
+    },
+  };
+}
diff --git a/code/core/src/shared/open-service/toolsets/docs/access.ts b/code/core/src/shared/open-service/toolsets/docs/access.ts
new file mode 100644
index 000000000000..9cc4a92552f8
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access.ts
@@ -0,0 +1,50 @@
+/**
+ * The docs toolset's one environment-specific dependency.
+ *
+ * Everything that differs between runtimes — live open services, the manifests core builds itself,
+ * or manifest files fetched from a hosted Storybook — is hidden behind this seam, so the toolset
+ * definition stays a pure mapping from ids to formatted output.
+ */
+
+import type {
+  AllManifests,
+  ComponentManifest,
+  ComponentManifestV1,
+  Doc,
+  DocV1,
+} from './manifest-formatter/manifest-types.ts';
+
+/**
+ * One fully-assembled entry: docgen, stories, and MDX content already merged. This is the shape the
+ * Markdown formatters consume, which is why it uses the inline manifest types rather than the
+ * shallow index rows `list` returns.
+ */
+export type ResolvedDocsEntry =
+  | { kind: 'component'; component: ComponentManifest }
+  | { kind: 'doc'; doc: Doc };
+
+export type DocsAccess = {
+  /** Shallow component + standalone-docs index. Story ids are resolved only when requested. */
+  list(options: { withStoryIds: boolean }): Promise<AllManifests>;
+  /** One component or standalone docs entry, fully assembled; undefined when the id is unknown. */
+  resolve(id: string): Promise<ResolvedDocsEntry | undefined>;
+};
+
+/** A listing with no components and no standalone docs. */
+export function emptyManifests(): AllManifests {
+  return { componentManifest: { v: 1, components: {} } };
+}
+
+/**
+ * Assembles a shallow (v1) listing. The docs manifest is omitted entirely when there are no
+ * standalone docs — the formatters read its absence as "print no Docs section".
+ */
+export function toShallowManifests(
+  components: Record<string, ComponentManifestV1>,
+  docs: Record<string, DocV1>
+): AllManifests {
+  return {
+    componentManifest: { v: 1, components },
+    ...(Object.keys(docs).length > 0 ? { docsManifest: { v: 1, docs } } : {}),
+  };
+}
diff --git a/code/core/src/shared/open-service/toolsets/docs/instructions.ts b/code/core/src/shared/open-service/toolsets/docs/instructions.ts
new file mode 100644
index 000000000000..128a5db31a29
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/instructions.ts
@@ -0,0 +1,24 @@
+import { MCP_TOOL_NAMES } from '../../toolset-names.ts';
+
+/**
+ * Server-level guidance for the docs tools.
+ *
+ * This is the workflow an agent should follow across the three tools, which no single tool
+ * description can state: discover ids first, then fetch, and never invent a prop. It lives with the
+ * toolset so both MCP surfaces serve the same text, and names its tools through the frozen map so
+ * the prose cannot drift from what is registered.
+ */
+export const DOCS_TOOLSET_INSTRUCTIONS = `## Documentation Workflow
+
+**CRITICAL: Never hallucinate component properties!** Before using ANY property on a component (even common-sounding ones like \`shadow\`), you MUST verify it is documented via these tools. If it is not documented, it does not exist — never assume props from naming conventions or other libraries; report it to the user instead.
+
+1. Call **${MCP_TOOL_NAMES['docs.list']}** once at the start of the task to discover available component and docs IDs.
+2. Call **${MCP_TOOL_NAMES['docs.show']}** with an \`id\` from that list to retrieve full component docs, props, usage examples, and stories.
+3. Call **${MCP_TOOL_NAMES['docs.showStory']}** for extra docs on a story variant not covered by the component docs.
+
+Only use properties explicitly documented or shown in example stories. Only reference IDs returned by these tools; never guess IDs.
+
+## Multi-Source Requests
+
+- With multiple sources configured, **${MCP_TOOL_NAMES['docs.list']}** returns entries from every source; pass \`storybookId\` to **${MCP_TOOL_NAMES['docs.show']}** to scope one.
+`;
diff --git a/code/core/src/shared/open-service/toolsets/docs/multi-source.ts b/code/core/src/shared/open-service/toolsets/docs/multi-source.ts
new file mode 100644
index 000000000000..582d6975f4b7
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/multi-source.ts
@@ -0,0 +1,104 @@
+/**
+ * Composition support for the docs toolset.
+ *
+ * A composed Storybook is not a different kind of docs engine — it is several of the same one. So
+ * composition is modelled as a set of {@link DocsAccess} instances, one per source, rather than a
+ * parallel implementation: whatever backs a single Storybook (manifests over HTTP, the open
+ * services in-process) backs one source of a composition unchanged.
+ *
+ * What composition does add is per-source failure isolation when listing; routing a lookup to the
+ * source the caller named is the toolset's job, since only it knows how to explain a bad id.
+ */
+
+import { createProviderDocsAccess, type ManifestProvider } from './access-provider.ts';
+import type { DocsAccess, ResolvedDocsEntry } from './access.ts';
+import {
+  ManifestGetError,
+  RequiresOwnMcpError,
+  type Source,
+  type SourceListing,
+} from './sources.ts';
+
+/** One composed source and the access that reads it. */
+export type DocsSource = {
+  source: Source;
+  access: DocsAccess;
+};
+
+export type CompositionDocsSourcesOptions = {
+  sources: Source[];
+  manifestProvider?: ManifestProvider;
+  getRequest?: () => Request | undefined;
+  /**
+   * Reads the local Storybook — the source with no `url` — instead of fetching manifests from it.
+   * The dev server passes its service-backed access here when `experimentalDocgenServer` is on,
+   * where the local `/manifests/*.json` are deliberately 404'd and the data lives in the services.
+   */
+  localAccess?: DocsAccess;
+  /**
+   * Resolves a single entry in-process, short-cutting the manifest index. Part of the hosted
+   * package's public context, so it stays available to embedders that supply one.
+   */
+  resolveEntry?: (id: string, source?: Source) => Promise<ResolvedDocsEntry | undefined>;
+};
+
+/**
+ * Builds one access per composed source.
+ *
+ * Remote sources are read through the same provider access a single hosted Storybook uses, which is
+ * what lets a composition reuse that implementation rather than a parallel one. The local source
+ * may instead be handed a ready-made access, so the dev server reads itself the same way in a
+ * composition as it does alone.
+ */
+export function createCompositionDocsSources({
+  sources,
+  manifestProvider,
+  getRequest,
+  localAccess,
+  resolveEntry,
+}: CompositionDocsSourcesOptions): DocsSource[] {
+  return sources.map((source) => ({
+    source,
+    access:
+      localAccess && !source.url
+        ? localAccess
+        : createProviderDocsAccess({ source, manifestProvider, getRequest, resolveEntry }),
+  }));
+}
+
+/**
+ * Lists every source concurrently, turning a failure into that source's own outcome.
+ *
+ * One unreachable or private source must not cost the agent the entire listing, which is the whole
+ * reason each result is captured rather than awaited together.
+ */
+export async function listSources(
+  sources: DocsSource[],
+  options: { withStoryIds: boolean }
+): Promise<SourceListing[]> {
+  const listings = await Promise.all(
+    sources.map(async ({ source, access }): Promise<SourceListing> => {
+      try {
+        return { source, manifests: await access.list(options) };
+      } catch (error) {
+        if (error instanceof RequiresOwnMcpError) {
+          return { source, notice: { kind: 'requires-own-mcp', endpoint: error.endpoint } };
+        }
+        return { source, error: error instanceof Error ? error.message : String(error) };
+      }
+    })
+  );
+
+  // Isolation is only worth it while something still reads. If no source produced output at all,
+  // a page of repeated errors buries the reason, so report the failure itself.
+  const usable = listings.filter((listing) => !listing.error);
+  if (usable.length === 0) {
+    throw new ManifestGetError(
+      `Failed to fetch manifests from any source. Errors:\n${listings
+        .map((listing) => `- ${listing.source.title}: ${listing.error}`)
+        .join('\n')}`
+    );
+  }
+
+  return listings;
+}
diff --git a/code/core/src/shared/open-service/toolsets/docs/public.ts b/code/core/src/shared/open-service/toolsets/docs/public.ts
new file mode 100644
index 000000000000..6d77a7aa384d
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/public.ts
@@ -0,0 +1,91 @@
+/**
+ * Dependency-light entry for the docs toolset (`storybook/internal/toolsets-docs`).
+ *
+ * `@storybook/mcp` consumes the manifest formatter and toolset from here and bundles this entry
+ * into its own dist (core is only a dev dependency there), so everything reachable from this file
+ * must stay free of Node-only and server-only imports.
+ */
+
+export { MCP_TOOL_NAMES, getRef } from '../../toolset-names.ts';
+export type { ToolsetMethodRef } from '../../toolset-names.ts';
+export { resolveToolsetDescription } from '../../toolset-definition.ts';
+export type { ToolsetCtx, ToolsetOutcome } from '../../toolset-definition.ts';
+export { DOCS_TOOLSET_INSTRUCTIONS } from './instructions.ts';
+export { emptyManifests } from './access.ts';
+export type { DocsAccess, ResolvedDocsEntry } from './access.ts';
+export { selectReportedManifests } from './definition.ts';
+export { createDocsToolset, isDocsShowError, isDocsShowStoryError } from './definition.ts';
+export type {
+  CreateDocsToolsetOptions,
+  DocsListOutput,
+  DocsShowOutput,
+  DocsShowStoryOutput,
+  DocsToolset,
+} from './definition.ts';
+export {
+  COMPONENT_MANIFEST_PATH,
+  createProviderDocsAccess,
+  DOCS_MANIFEST_PATH,
+  fetchManifests,
+  parseManifestRef,
+  resolveComponentEntry,
+  resolveComponentStories,
+  resolveDocEntry,
+} from './access-provider.ts';
+export type { ManifestProvider, ProviderDocsAccessOptions } from './access-provider.ts';
+export { estimateTokens } from '../estimate-tokens.ts';
+export { createCompositionDocsSources, listSources } from './multi-source.ts';
+export type { CompositionDocsSourcesOptions, DocsSource } from './multi-source.ts';
+export {
+  formatRequiresOwnMcpNotice,
+  getSourceMcpEndpoint,
+  ManifestGetError,
+  RequiresOwnMcpError,
+} from './sources.ts';
+export type { RequiresOwnMcpNotice, Source, SourceListing } from './sources.ts';
+export {
+  adaptCoreComponent,
+  adaptCoreDoc,
+  adaptCoreStories,
+  type CoreDocgenComponent,
+} from './manifest-formatter/adapt-core-manifest.ts';
+export {
+  ComponentManifestMap,
+  ComponentManifestMapV0,
+  ComponentManifestMapV1,
+  DocsManifestMap,
+  DocsManifestMapV0,
+  DocsManifestMapV1,
+  JsonRef,
+} from './manifest-formatter/manifest-types.ts';
+export {
+  extractDocsSummary,
+  MAX_SUMMARY_LENGTH,
+} from './manifest-formatter/extract-docs-summary.ts';
+export type {
+  AllManifests,
+  ComponentManifest,
+  ComponentManifestEntry,
+  ComponentManifestV0,
+  ComponentManifestV1,
+  Doc,
+  DocEntry,
+  DocV0,
+  DocV1,
+  ManifestError,
+  Story,
+  SubcomponentManifest,
+} from './manifest-formatter/manifest-types.ts';
+export {
+  formatComponentManifest,
+  formatDocsManifest,
+  formatManifestsToLists,
+  formatStoryDocumentation,
+  MAX_STORIES_TO_SHOW,
+} from './manifest-formatter/markdown.ts';
+export {
+  parseReactComponentMeta,
+  parseReactDocgen,
+  parseReactDocgenTypescript,
+  type ParsedDocgen,
+} from './manifest-formatter/parse-react-docgen.ts';
diff --git a/code/core/src/shared/open-service/toolsets/docs/sources.ts b/code/core/src/shared/open-service/toolsets/docs/sources.ts
new file mode 100644
index 000000000000..a553e9ed4a07
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/sources.ts
@@ -0,0 +1,97 @@
+/**
+ * Composed Storybook sources.
+ *
+ * A composition serves several Storybooks through one MCP endpoint: the local one plus every
+ * `refs` entry. Each source is read independently, so one unreachable or private source degrades
+ * to a message in its own section rather than failing the whole listing.
+ */
+
+import type { AllManifests } from './manifest-formatter/manifest-types.ts';
+
+/** One Storybook in a composition. The local source has no `url`. */
+export type Source = {
+  /** Stable identifier, used as the `storybookId` tool input. */
+  id: string;
+  /** Human-readable title, used as the section header when listing. */
+  title: string;
+  /** Remote URL; undefined for the local Storybook. */
+  url?: string;
+};
+
+export type SourceWithUrl = Source & { url: string };
+
+/** Guidance for a source that can only be read through its own MCP endpoint. */
+export type RequiresOwnMcpNotice = {
+  kind: 'requires-own-mcp';
+  endpoint: string;
+};
+
+/**
+ * One source's contribution to a composed listing. Exactly one of `manifests`, `error` or `notice`
+ * carries the outcome, so a failing source occupies its own section instead of the whole listing.
+ */
+export type SourceListing = {
+  source: Source;
+  manifests?: AllManifests;
+  error?: string;
+  notice?: RequiresOwnMcpNotice;
+};
+
+export function getSourceMcpEndpoint(source: SourceWithUrl): string {
+  const base = new URL(source.url);
+  base.pathname = `${base.pathname.replace(/\/$/, '')}/`;
+  return new URL('mcp', base).toString();
+}
+
+/**
+ * A private composed Storybook cannot be proxied — its credentials belong to the user, not to this
+ * server — so the answer is the address the agent should talk to instead.
+ */
+export function formatRequiresOwnMcpNotice(
+  source: Source,
+  endpoint: string,
+  options: { includeHeader?: boolean } = {}
+): string {
+  const parts: string[] = [];
+
+  if (options.includeHeader ?? true) {
+    parts.push(`# ${source.title}`);
+    parts.push(`id: ${source.id}`);
+    parts.push('');
+  }
+
+  parts.push(
+    'This composed Storybook is private and cannot be read through the local Storybook MCP proxy.'
+  );
+  parts.push('');
+  parts.push("Use this source's own MCP endpoint instead:");
+  parts.push(endpoint);
+
+  return parts.join('\n');
+}
+
+export class RequiresOwnMcpError extends Error {
+  public readonly source: SourceWithUrl;
+  public readonly endpoint: string;
+
+  constructor(source: SourceWithUrl) {
+    const endpoint = getSourceMcpEndpoint(source);
+    super(`Composed Storybook "${source.title}" requires its own MCP endpoint: ${endpoint}`);
+    this.name = 'RequiresOwnMcpError';
+    this.source = source;
+    this.endpoint = endpoint;
+  }
+}
+
+/** Thrown when a manifest cannot be fetched or does not parse. */
+export class ManifestGetError extends Error {
+  public readonly url: string;
+  public override readonly cause?: Error;
+
+  constructor(message: string, url?: string, cause?: Error) {
+    super(message);
+    this.name = 'ManifestGetError';
+    this.url = url ?? 'No source URL provided';
+    this.cause = cause;
+  }
+}

From 8f6b23f7eef8d241c851e32cb42dc4b0d4b5fe4a Mon Sep 17 00:00:00 2001
From: Kasper Peulen <kasperpeulen@gmail.com>
Date: Tue, 4 Aug 2026 13:44:05 +0200
Subject: [PATCH 5/6] =?UTF-8?q?Review=205/6=20=E2=80=94=20wiring=20and=20b?=
 =?UTF-8?q?uild:=20the=20registration=20sites=20and=20the=20portable=20ent?=
 =?UTF-8?q?ry?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 code/addons/vitest/src/preset.ts              |  34 +++++
 code/core/build-config.ts                     |   9 ++
 code/core/src/core-server/index.ts            |  23 ++++
 .../src/core-server/presets/common-preset.ts  |  71 ++++++++---
 .../core-server/utils/manifests/manifests.ts  |  22 ++++
 scripts/build/utils/entry-utils.ts            |  10 ++
 .../build/utils/generate-types-rolldown.ts    | 120 ++++++++++++------
 7 files changed, 237 insertions(+), 52 deletions(-)

diff --git a/code/addons/vitest/src/preset.ts b/code/addons/vitest/src/preset.ts
index 0b17ab781ddc..e2e2f439fc4e 100644
--- a/code/addons/vitest/src/preset.ts
+++ b/code/addons/vitest/src/preset.ts
@@ -9,8 +9,10 @@ import {
 } from 'storybook/internal/common';
 import {
   type StoryIndexGenerator,
+  createTestToolset,
   experimental_UniversalStore,
   experimental_getTestProviderStore,
+  registerToolset,
 } from 'storybook/internal/core-server';
 import { logger } from 'storybook/internal/node-logger';
 import { cleanPaths, oneWayHash, sanitizeError, telemetry } from 'storybook/internal/telemetry';
@@ -43,6 +45,12 @@ import { runTestRunner } from './node/boot-test-runner.ts';
 import type { CachedState, ErrorLike, StoreState } from './types.ts';
 import type { StoreEvent } from './types.ts';
 
+/**
+ * Preset marker: true exactly when this addon is enabled, since only enabled addons' presets load.
+ * addon-mcp's availability gate reads it through `presets.apply('isAddonVitestEnabled', false)`.
+ */
+export const isAddonVitestEnabled = true;
+
 type Event =
   | {
       type: 'test-discrepancy';
@@ -58,6 +66,32 @@ type Event =
       payload: StoreState['currentRun'];
     };
 
+/**
+ * Registers the public `test` toolset.
+ *
+ * This addon owns the toolset because running stories needs its channel protocol, but it must
+ * register from the `services` hook rather than `experimental_serverChannel`: consumers resolve
+ * the toolset for its descriptions and schemas alone, and the two places that do so — `storybook
+ * ai` metadata generation (which never starts a dev server) and a non-Vite dev server (where the
+ * channel hook returns early) — would otherwise ask for a toolset that was never registered and
+ * fail hard. Registering here matches the availability gate that decides whether the tool is
+ * offered at all: that gate reads the `isAddonVitestEnabled` marker this preset exports, which is
+ * true exactly when the addon is enabled — the same condition under which this hook runs. The
+ * channel is used only when a run is actually triggered.
+ */
+export const services = async (_value: void, options: Options): Promise<void> => {
+  const storyIndexGenerator =
+    await options.presets.apply<Promise<StoryIndexGenerator>>('storyIndexGenerator');
+
+  registerToolset(
+    createTestToolset({
+      channel: options.channel as Channel,
+      storyIndex: { getIndex: () => storyIndexGenerator.getIndex() },
+      a11yEnabled: await options.presets.apply('isAddonA11yEnabled', false),
+    })
+  );
+};
+
 export const experimental_serverChannel = async (channel: Channel, options: Options) => {
   const core = await options.presets.apply('core');
 
diff --git a/code/core/build-config.ts b/code/core/build-config.ts
index 341ead7bc67d..a84e4c491830 100644
--- a/code/core/build-config.ts
+++ b/code/core/build-config.ts
@@ -206,6 +206,15 @@ const config: BuildEntries = {
         exportEntries: ['./open-service'],
         entryPoint: './src/shared/open-service/index.ts',
       },
+      {
+        // Dependency-light docs toolset surface bundled into `@storybook/mcp`'s dist (core is a
+        // dev dependency there), replacing that package's own manifest-formatter copies. Portable:
+        // its d.ts is one flat self-contained file so that consumer can inline it through standard
+        // resolution; guarded by `portable-dist.test.ts` next to the entry source.
+        exportEntries: ['./internal/toolsets-docs'],
+        entryPoint: './src/shared/open-service/toolsets/docs/public.ts',
+        portable: { external: ['valibot'] },
+      },
     ],
     runtime: [
       {
diff --git a/code/core/src/core-server/index.ts b/code/core/src/core-server/index.ts
index 96d4ea12447f..a8874d0dcd92 100644
--- a/code/core/src/core-server/index.ts
+++ b/code/core/src/core-server/index.ts
@@ -58,6 +58,29 @@ export {
   registerService as experimental_registerService,
 } from '../shared/open-service/server.ts';
 
+/**
+ * Toolset registration for addons that host a public toolset.
+ *
+ * Exposed from the Node entry rather than `storybook/open-service`: toolset factories reach
+ * server-only code, and that entry is built for the browser.
+ */
+export { registerToolset } from '../shared/open-service/toolset-registry.ts';
+export { createTestToolset } from '../shared/open-service/toolsets/test/definition.ts';
+export type {
+  CreateTestToolsetOptions,
+  TestToolset,
+} from '../shared/open-service/toolsets/test/definition.ts';
+export { createDocsToolset } from '../shared/open-service/toolsets/docs/definition.ts';
+export { emptyManifests } from '../shared/open-service/toolsets/docs/access.ts';
+export type { DocsAccess, ResolvedDocsEntry } from '../shared/open-service/toolsets/docs/access.ts';
+export { createServiceDocsAccess } from '../shared/open-service/toolsets/docs/access-service.ts';
+export { createManifestDocsAccess } from '../shared/open-service/toolsets/docs/access-manifest.ts';
+export { createLocalDocsAccess } from '../shared/open-service/toolsets/docs/access-local.ts';
+export { loadManifests } from './utils/manifests/manifests.ts';
+export { createStoriesToolset } from '../shared/open-service/toolsets/stories/definition.ts';
+export type { PreviewStoriesOutput } from '../shared/open-service/toolsets/stories/definition.ts';
+export { reviewToolset } from '../shared/open-service/toolsets/review/definition.ts';
+
 export { UniversalStore as experimental_UniversalStore } from '../shared/universal-store/index.ts';
 export { MockUniversalStore as experimental_MockUniversalStore } from '../shared/universal-store/mock.ts';
 export {
diff --git a/code/core/src/core-server/presets/common-preset.ts b/code/core/src/core-server/presets/common-preset.ts
index 398498b32653..d5a51c1680ff 100644
--- a/code/core/src/core-server/presets/common-preset.ts
+++ b/code/core/src/core-server/presets/common-preset.ts
@@ -19,15 +19,16 @@ import { StoryIndexGenerator } from 'storybook/internal/core-server';
 import { loadCsf } from 'storybook/internal/csf-tools';
 import { logger } from 'storybook/internal/node-logger';
 import { telemetry } from 'storybook/internal/telemetry';
-import type {
-  CoreConfig,
-  DocgenProviderDescriptor,
-  Indexer,
-  Options,
-  PresetProperty,
-  PresetPropertyFn,
-  StoryDocsProvider,
-  StorybookConfigRaw,
+import {
+  CHANGE_DETECTION_STATUS_TYPE_ID,
+  type CoreConfig,
+  type DocgenProviderDescriptor,
+  type Indexer,
+  type Options,
+  type PresetProperty,
+  type PresetPropertyFn,
+  type StoryDocsProvider,
+  type StorybookConfigRaw,
 } from 'storybook/internal/types';
 
 import { OpenServiceServicesAppliedTwiceError } from '../../server-errors.ts';
@@ -36,9 +37,14 @@ import { createDocgenWorkerClient } from '../../shared/open-service/services/doc
 import { registerModuleGraphService } from '../../shared/open-service/services/module-graph/server.ts';
 import { registerReviewService } from '../../shared/open-service/services/review/server.ts';
 import { registerStoryDocsService } from '../../shared/open-service/services/story-docs/server.ts';
+import { createLocalDocsAccess } from '../../shared/open-service/toolsets/docs/access-local.ts';
 import { registerToolset } from '../../shared/open-service/toolset-registry.ts';
-import { docsToolset } from '../../shared/open-service/toolsets/docs/definition.ts';
+import { createDocsToolset } from '../../shared/open-service/toolsets/docs/definition.ts';
 import { reviewToolset } from '../../shared/open-service/toolsets/review/definition.ts';
+import { createStoriesToolset } from '../../shared/open-service/toolsets/stories/definition.ts';
+import { GitDiffProvider } from '../change-detection/GitDiffProvider.ts';
+import { getStatusStoreByTypeId } from '../stores/status.ts';
+import { loadManifests } from '../utils/manifests/manifests.ts';
 
 import * as pathe from 'pathe';
 import { isAbsolute, join } from 'pathe';
@@ -50,7 +56,7 @@ import { initCreateNewStoryChannel } from '../server-channel/create-new-story-ch
 import { initFileSearchChannel } from '../server-channel/file-search-channel.ts';
 import { initGhostStoriesChannel } from '../server-channel/ghost-stories-channel.ts';
 import { initOpenInEditorChannel } from '../server-channel/open-in-editor-channel.ts';
-import { isReviewFeatureEnabled } from '../../shared/review/features.ts';
+import { isReviewExplicitlyEnabled, isReviewFeatureEnabled } from '../../shared/review/features.ts';
 import { initReviewChannel } from '../server-channel/review-channel.ts';
 import { initTelemetryChannel } from '../server-channel/telemetry-channel.ts';
 import { initializeChecklist } from '../utils/checklist.ts';
@@ -367,13 +373,31 @@ export const services = async (_value: void, options: Options): Promise<void> =>
     presets: options.presets,
   });
 
-  // Toolsets register imperatively alongside their services: addons contribute both from their own
-  // `services` hook. The stories and test toolsets join once their boot-time dependencies are wired
-  // (stories factory; test moves to addon-vitest).
-  registerToolset(docsToolset);
-
   const features = await options.presets.apply('features');
 
+  // Toolsets register imperatively alongside their services: addons contribute both from their own
+  // `services` hook. The test toolset registers from addon-vitest, which owns the channel it needs.
+  const storyIndex = { getIndex: () => storyIndexGenerator.getIndex() };
+  const gitDiffProvider = new GitDiffProvider(process.cwd());
+
+  registerToolset(
+    createStoriesToolset({
+      storyIndex,
+      git: {
+        getRepoRoot: () => gitDiffProvider.getRepoRoot(),
+        getChangedFiles: () => gitDiffProvider.getChangedFiles(),
+      },
+      changeStatuses: {
+        getAll: () => getStatusStoreByTypeId(CHANGE_DETECTION_STATUS_TYPE_ID).getAll(),
+      },
+      // The explicit opt-in gate, not `isReviewFeatureEnabled`: with the flag unset the review
+      // infrastructure below still registers (the `storybook ai` CLI channel enables the tool per
+      // request), but direct MCP clients never see `display-review`, so the stories prose must
+      // not point at it.
+      reviewEnabled: isReviewExplicitlyEnabled(features),
+    })
+  );
+
   if (isReviewFeatureEnabled(features)) {
     registerReviewService({
       getIndex: () => storyIndexGenerator.getIndex(),
@@ -410,12 +434,27 @@ export const services = async (_value: void, options: Options): Promise<void> =>
       });
     }
 
+    // Story-docs registers whenever this block runs, docgen only when a worker is available, so
+    // docgen registered ⇒ story-docs registered. `createLocalDocsAccess` requires both before
+    // reading from the services and degrades to the manifests otherwise, so reordering or gating
+    // these registrations cannot make the docs toolset throw — only fall back.
     registerStoryDocsService({
       getIndex: () => storyIndexGenerator.getIndex(),
       storyDocsProvider,
       workingDir: process.cwd(),
     });
   }
+
+  registerToolset(
+    createDocsToolset({
+      // Registration-based selection between the docgen services and the inline manifests, shared
+      // with addon-mcp's composed local source so both read this Storybook the same way.
+      docsAccess: createLocalDocsAccess({
+        storyIndex,
+        getManifests: () => loadManifests(options.presets),
+      }),
+    })
+  );
 };
 
 // Store the promise (not the result) to prevent race conditions.
diff --git a/code/core/src/core-server/utils/manifests/manifests.ts b/code/core/src/core-server/utils/manifests/manifests.ts
index 3096be75a6dd..e759c2c68f8d 100644
--- a/code/core/src/core-server/utils/manifests/manifests.ts
+++ b/code/core/src/core-server/utils/manifests/manifests.ts
@@ -70,6 +70,18 @@ function mergeServicePayloads(
   );
 }
 
+/**
+ * Whether the dev server should 404 `manifests/components.json` and `manifests/docs.json` because
+ * docgen-server mode owns that data.
+ *
+ * Deliberately flag-based, while the docs toolset's engine selection (`createLocalDocsAccess`) is
+ * registration-based. The two can disagree: with the flag on but the docgen services unregistered
+ * (manager-only build, no docgen worker), the toolset falls back to reading the inline manifests
+ * while this route keeps 404ing them — so a composing parent Storybook fetching manifests over
+ * HTTP sees nothing even though the local MCP tools still serve docs. Accepted for now: switching
+ * this gate to registration would change composition behavior that only the live-fixture suites
+ * cover, so it is deferred to its own change.
+ */
 function isDocgenServerManifestMode(features: {
   experimentalDocgenServer?: boolean;
   componentsManifest?: boolean;
@@ -123,6 +135,16 @@ async function getManifests(
   );
 }
 
+/**
+ * Loads the live manifests, the same way the dev-server manifest routes do.
+ *
+ * Exposed for the docs toolset, which reads manifest data in-process instead of fetching its own
+ * server over loopback HTTP.
+ */
+export async function loadManifests(presets: Presets) {
+  return getManifests(presets, await getManifestEntries(presets), { watch: true });
+}
+
 /**
  * Resolves the docgen `meta` for the components HTML debugger.
  *
diff --git a/scripts/build/utils/entry-utils.ts b/scripts/build/utils/entry-utils.ts
index 3988b533101b..d503cbb414d0 100644
--- a/scripts/build/utils/entry-utils.ts
+++ b/scripts/build/utils/entry-utils.ts
@@ -11,6 +11,16 @@ export type BuildEntry = {
   entryPoint: `./src/${string}`; // the source file to bundle, e.g. "./src/manager-api/index.ts",
   external?: string[]; // the list of external dependencies to exclude from the bundle
   dts?: false; // default to generating d.ts files for all entries, except if set to false
+  /**
+   * Bundle this entry's d.ts in an isolated single-entry pass, producing one flat self-contained
+   * file instead of sharing type chunks with the package's other entries. For entries other
+   * packages bundle into their own dist, where a shared chunk would drag unrelated type surfaces
+   * along. `external` lists the only imports the flat file may keep — packages every consumer of
+   * the entry declares itself (it only affects this d.ts pass, never the JS bundle). A producer-side
+   * test guards each portable artifact: flatness, the import allowlist (kept there as a deliberate
+   * second copy, so widening it is a reviewer-visible edit), and a size budget.
+   */
+  portable?: { external: string[] };
 };
 export type BuildEntriesByPlatform = Partial<Record<EntryType, BuildEntry[]>>;
 
diff --git a/scripts/build/utils/generate-types-rolldown.ts b/scripts/build/utils/generate-types-rolldown.ts
index bdb867a68e07..cbbc24355e94 100644
--- a/scripts/build/utils/generate-types-rolldown.ts
+++ b/scripts/build/utils/generate-types-rolldown.ts
@@ -266,10 +266,10 @@ export async function generateTypesFiles(
 ) {
   const DIR_REL = relative(DIR_CODE, cwd);
 
-  const dtsEntries = Object.values(data.entries)
+  const dtsBuildEntries = Object.values(data.entries)
     .flat()
-    .filter((entry) => entry.dts !== false)
-    .map((e) => e.entryPoint);
+    .filter((entry) => entry.dts !== false);
+  const dtsEntries = dtsBuildEntries.map((e) => e.entryPoint);
 
   if (dtsEntries.length === 0) {
     return;
@@ -285,14 +285,25 @@ export async function generateTypesFiles(
         id.includes(`${sep}node_modules${sep}${dep}${sep}`)
     );
 
+  // ./src/client-logger/index.ts -> client-logger/index
+  const entryName = (entryPoint: string) =>
+    entryPoint.replace(/^\.\/src\//, '').replace(/\.tsx?$/, '');
+
   // Build entry map: { 'client-logger/index': '/absolute/path/src/client-logger/index.ts', ... }
   const entryMap: Record<string, string> = {};
   for (const entry of dtsEntries) {
-    // ./src/client-logger/index.ts -> client-logger/index
-    const name = entry.replace(/^\.\/src\//, '').replace(/\.tsx?$/, '');
-    entryMap[name] = join(cwd, entry);
+    entryMap[entryName(entry)] = join(cwd, entry);
   }
 
+  // Portable entries leave the shared pass: bundled alone, everything outside the entry's own
+  // external allowlist inlines into one flat file instead of importing shared type chunks (see
+  // BuildEntry.portable).
+  const portableByName = new Map(
+    dtsBuildEntries
+      .filter((entry) => entry.portable)
+      .map((entry) => [entryName(entry.entryPoint), entry.portable!])
+  );
+
   // The dts plugin and tsgo derive rootDir from path.dirname(tsconfig).
   // When rootDir is the package dir, declarations for cross-package imports
   // would be emitted next to their source files. Fix: create a temporary
@@ -304,6 +315,9 @@ export async function generateTypesFiles(
   const useTsgo = options?.tsgo ?? false;
   const resolver = options?.resolver ?? 'hybrid';
 
+  const include = [`${relative(DIR_ROOT, cwd)}/src/**/*`];
+  const exclude = DTS_EXCLUDES;
+
   // tsgo removed support for `baseUrl`, and ts.getParsedCommandLineOfConfigFile
   // needs concrete options anyway: resolve the tsconfig chain and write a flat
   // config.
@@ -313,8 +327,8 @@ export async function generateTypesFiles(
     wrapperTsconfig,
     JSON.stringify({
       compilerOptions,
-      include: [`${relative(DIR_ROOT, cwd)}/src/**/*`],
-      exclude: DTS_EXCLUDES,
+      include,
+      exclude,
     })
   );
 
@@ -332,8 +346,8 @@ export async function generateTypesFiles(
         emitTsconfig,
         JSON.stringify({
           compilerOptions: { ...compilerOptions, ...dtsEmitCompilerOptions(emitDir) },
-          include: [`${relative(DIR_ROOT, cwd)}/src/**/*`],
-          exclude: DTS_EXCLUDES,
+          include,
+          exclude,
         })
       );
       emitPackageDeclarationsNative(emitTsconfig, wrapperTsconfig, emitDir);
@@ -348,38 +362,72 @@ export async function generateTypesFiles(
       ])
     );
 
-    const out = await rolldown({
-      input,
-      external: externalFn,
-      plugins: [
-        createTextAssetStubPlugin(),
-        ...(resolver === 'hybrid' ? [createTypesFallbackResolverPlugin(externalFn)] : []),
-        dts({
-          cwd,
-          tsconfig: wrapperTsconfig,
-          dtsInput: true,
-          emitDtsOnly: true,
-          resolver: resolver === 'tsc' ? 'tsc' : 'oxc',
-        }),
-      ],
-      logLevel: 'warn',
-    });
-
-    const { output } = await out.write({
-      dir: join(cwd, 'dist'),
-      format: 'es',
-      // Name shared chunks purely by content hash: the default `[name]-[hash]`
-      // inherits a base name from whichever module rolldown happens to pick,
-      // which varies across runs and would make the output non-deterministic.
-      chunkFileNames: 'chunk-[hash].js',
-    });
+    const sharedInput = Object.fromEntries(
+      Object.entries(input).filter(([name]) => !portableByName.has(name))
+    );
+    const portableInputs = Object.entries(input)
+      .filter(([name]) => portableByName.has(name))
+      .map(([name, emitted]) => ({
+        input: { [name]: emitted },
+        allowedExternal: portableByName.get(name)!.external,
+      }));
+
+    const bundleDts = async (
+      bundleInput: Record<string, string>,
+      isExternal: (id: string) => boolean
+    ) => {
+      const out = await rolldown({
+        input: bundleInput,
+        external: isExternal,
+        plugins: [
+          createTextAssetStubPlugin(),
+          ...(resolver === 'hybrid' ? [createTypesFallbackResolverPlugin(isExternal)] : []),
+          dts({
+            cwd,
+            tsconfig: wrapperTsconfig,
+            dtsInput: true,
+            emitDtsOnly: true,
+            resolver: resolver === 'tsc' ? 'tsc' : 'oxc',
+          }),
+        ],
+        logLevel: 'warn',
+      });
+
+      const { output } = await out.write({
+        dir: join(cwd, 'dist'),
+        format: 'es',
+        // Name shared chunks purely by content hash: the default `[name]-[hash]`
+        // inherits a base name from whichever module rolldown happens to pick,
+        // which varies across runs and would make the output non-deterministic.
+        chunkFileNames: 'chunk-[hash].js',
+      });
+      return output;
+    };
+
+    // A portable pass bundles with the package-wide externals plus the entry's allowlist: an
+    // external that nothing in the kept types references is tree-shaken from the output, so the
+    // flat file ends up importing only what its closure genuinely uses — which the entry's
+    // producer-side guard then asserts is exactly the allowlist.
+    const portableExternalFn = (allowed: string[]) => (id: string) =>
+      externalFn(id) || allowed.some((dep) => id === dep || id.startsWith(`${dep}/`));
+
+    const outputs = [
+      ...(Object.keys(sharedInput).length > 0 ? [await bundleDts(sharedInput, externalFn)] : []),
+      // One isolated pass per portable entry, so nothing is shared between it and the rest.
+      ...(await Promise.all(
+        portableInputs.map(({ input: portableInput, allowedExternal }) =>
+          bundleDts(portableInput, portableExternalFn(allowedExternal))
+        )
+      )),
+    ];
 
     // Everything meaningful in this build is a .d.ts file; rolldown still
     // emits its runtime helper chunk as plain JS, which nothing references.
     // Only touch our own chunk namespace: the JS bundle writes real entry
     // files into the same dist directory in parallel.
     await Promise.all(
-      output
+      outputs
+        .flat()
         .filter((chunk) => /^chunk-[^/]+\.js$/.test(chunk.fileName))
         .map((chunk) => rm(join(cwd, 'dist', chunk.fileName), { force: true }))
     );

From a5ab56cdaf224f6fc2b62a3d9918bdf96338e582 Mon Sep 17 00:00:00 2001
From: Kasper Peulen <kasperpeulen@gmail.com>
Date: Tue, 4 Aug 2026 13:44:17 +0200
Subject: [PATCH 6/6] =?UTF-8?q?Review=206/6=20=E2=80=94=20the=20ported=20e?=
 =?UTF-8?q?ngine=20bodies=20and=20their=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 code/addons/vitest/src/preset.test.ts         |  30 +
 code/core/package.json                        |   6 +
 code/core/src/server-errors.ts                |  79 +-
 code/core/src/shared/open-service/index.ts    |  25 +-
 .../open-service/services/docgen/types.ts     |   5 +-
 .../open-service/toolset-registry.test.ts     |  34 +-
 .../toolsets/docs/access-local.test.ts        |  77 ++
 .../toolsets/docs/access-manifest.test.ts     | 100 ++
 .../toolsets/docs/access-parity.test.ts       | 177 ++++
 .../docs/access-provider-isolation.test.ts    | 107 ++
 .../toolsets/docs/access-provider.test.ts     | 937 ++++++++++++++++++
 .../toolsets/docs/access-service.test.ts      | 327 ++++++
 .../toolsets/docs/classify-services.test.ts   |  82 --
 .../toolsets/docs/classify-services.ts        |  52 +-
 .../toolsets/docs/definition.test.ts          | 375 +++----
 .../adapt-core-manifest.test.ts               |  91 ++
 .../manifest-formatter/adapt-core-manifest.ts |   6 +-
 .../docs/manifest-formatter/manifest-types.ts | 224 +++--
 .../docs/manifest-formatter/markdown.test.ts  |  36 +-
 .../docs/manifest-formatter/markdown.ts       |  67 +-
 .../parse-react-docgen.test.ts                | 462 +++++++++
 .../manifest-formatter/parse-react-docgen.ts  |   8 +-
 .../toolsets/docs/map-with-concurrency.ts     |  27 +
 .../open-service/toolsets/docs/map.test.ts    | 126 ---
 .../shared/open-service/toolsets/docs/map.ts  | 246 -----
 .../toolsets/docs/multi-source.test.ts        |  75 ++
 .../toolsets/docs/portable-dist.test.ts       |  84 ++
 .../toolsets/docs/runtime-agnostic.test.ts    |  75 ++
 .../toolsets/docs/sources.test.ts             |  12 +
 .../toolsets/estimate-tokens.test.ts          |  61 ++
 .../open-service/toolsets/estimate-tokens.ts  |  66 ++
 .../toolsets/review/definition.test.ts        | 203 +++-
 .../toolsets/stories/definition.test.ts       | 525 +++++++---
 .../stories/find-by-component.test.ts         | 242 ++---
 .../toolsets/stories/find-by-component.ts     | 141 +--
 .../open-service/toolsets/stories/format.ts   | 259 ++++-
 .../stories/resolve-component-stories.test.ts | 336 +++++++
 .../stories/resolve-component-stories.ts      | 305 ++++++
 .../toolsets/stories/story-input.ts           |  64 +-
 .../toolsets/stories/unreachable-files.ts     |  78 ++
 .../toolsets/test/definition.test.ts          | 381 ++++++-
 .../open-service/toolsets/test/format.ts      | 285 +++++-
 .../open-service/toolsets/test/run.test.ts    |   8 +-
 .../shared/open-service/toolsets/test/run.ts  |  26 +-
 code/core/src/shared/review/features.test.ts  |  24 +-
 code/core/src/shared/review/features.ts       |  11 +
 code/core/src/shared/review/review-state.ts   |  15 +-
 code/core/src/storybook-error.ts              |  11 +
 yarn.lock                                     |   1 +
 49 files changed, 5604 insertions(+), 1390 deletions(-)
 create mode 100644 code/addons/vitest/src/preset.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-local.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-manifest.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-parity.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-provider-isolation.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-provider.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/access-service.test.ts
 delete mode 100644 code/core/src/shared/open-service/toolsets/docs/classify-services.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/map-with-concurrency.ts
 delete mode 100644 code/core/src/shared/open-service/toolsets/docs/map.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/multi-source.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/portable-dist.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/runtime-agnostic.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/docs/sources.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/estimate-tokens.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/estimate-tokens.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.test.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.ts
 create mode 100644 code/core/src/shared/open-service/toolsets/stories/unreachable-files.ts

diff --git a/code/addons/vitest/src/preset.test.ts b/code/addons/vitest/src/preset.test.ts
new file mode 100644
index 000000000000..ce77142db42a
--- /dev/null
+++ b/code/addons/vitest/src/preset.test.ts
@@ -0,0 +1,30 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { clearToolsetRegistry, getToolset } from 'storybook/open-service';
+import type { Options } from 'storybook/internal/types';
+
+import { services } from './preset.ts';
+
+const options = {
+  channel: { on: () => {}, off: () => {}, emit: () => {} },
+  presets: {
+    apply: async (key: string, fallback?: unknown) =>
+      key === 'storyIndexGenerator' ? { getIndex: async () => ({ v: 5, entries: {} }) } : fallback,
+  },
+} as unknown as Options;
+
+describe('services preset hook', () => {
+  beforeEach(() => {
+    clearToolsetRegistry();
+  });
+
+  // Consumers resolve the `test` toolset for its descriptions and schemas alone, without a dev
+  // server: `storybook ai` metadata generation applies `services` but never starts one, and a
+  // non-Vite dev server returns from `experimental_serverChannel` before it could register. Both
+  // used to hit an unregistered toolset and fail hard.
+  it('registers the test toolset without a server channel', async () => {
+    await services(undefined, options);
+
+    expect(getToolset('test').methods.run.description).toBeDefined();
+  });
+});
diff --git a/code/core/package.json b/code/core/package.json
index 9af4f0803ea4..e9e0a92b13d9 100644
--- a/code/core/package.json
+++ b/code/core/package.json
@@ -198,6 +198,11 @@
       "code": "./src/telemetry/index.ts",
       "default": "./dist/telemetry/index.js"
     },
+    "./internal/toolsets-docs": {
+      "types": "./dist/shared/open-service/toolsets/docs/public.d.ts",
+      "code": "./src/shared/open-service/toolsets/docs/public.ts",
+      "default": "./dist/shared/open-service/toolsets/docs/public.js"
+    },
     "./internal/types": {
       "types": "./dist/types/index.d.ts",
       "code": "./src/types/index.ts",
@@ -371,6 +376,7 @@
     "npmlog": "^7.0.0",
     "p-limit": "^7.2.0",
     "package-manager-detector": "^1.1.0",
+    "pathe": "^1.1.2",
     "picocolors": "^1.1.0",
     "picomatch": "^2.3.0",
     "picoquery": "^2.5.0",
diff --git a/code/core/src/server-errors.ts b/code/core/src/server-errors.ts
index a614343cacef..93324e303619 100644
--- a/code/core/src/server-errors.ts
+++ b/code/core/src/server-errors.ts
@@ -319,15 +319,23 @@ export class OpenServiceMissingOriginError extends StorybookError {
   }
 }
 
+/**
+ * Why a review was refused. The toolset renders this as the opening of a longer, coaching message,
+ * so it lives here rather than in both places — the two copies had already drifted apart once.
+ */
+export function describeUnknownStoryIds(unknownIds: string[]): string {
+  const plural = unknownIds.length === 1 ? 'ID is' : 'IDs are';
+  return `Refusing to publish review: ${unknownIds.length} story ${plural} not backed by a story entry in the live Storybook index (docs entries cannot be review slots):`;
+}
+
 export class OpenServiceUnknownStoryIdsError extends StorybookError {
   constructor(public data: { unknownIds: string[] }) {
     const list = data.unknownIds.map((id) => `- ${id}`).join('\n');
-    const plural = data.unknownIds.length === 1 ? 'ID is' : 'IDs are';
     super({
       name: 'OpenServiceUnknownStoryIdsError',
       category: Category.CORE_COMMON,
       code: 18,
-      message: `Refusing to publish review: ${data.unknownIds.length} story ${plural} not backed by a story entry in the live Storybook index (docs entries cannot be review slots):\n${list}`,
+      message: `${describeUnknownStoryIds(data.unknownIds)}\n${list}`,
     });
   }
 }
@@ -356,6 +364,73 @@ export class OpenServiceServicesAppliedTwiceError extends StorybookError {
   }
 }
 
+export class OpenServiceMissingToolsetError extends StorybookError {
+  constructor(public data: { toolsetId: string }) {
+    super({
+      name: 'OpenServiceMissingToolsetError',
+      category: Category.CORE_COMMON,
+      code: 23,
+      message: `No registered toolset with id "${data.toolsetId}" exists in this environment.`,
+    });
+  }
+}
+
+export class OpenServiceDuplicateToolsetError extends StorybookError {
+  constructor(public data: { toolsetId: string }) {
+    super({
+      name: 'OpenServiceDuplicateToolsetError',
+      category: Category.CORE_COMMON,
+      code: 24,
+      message: `A toolset with id "${data.toolsetId}" is already registered. Each public toolset must be registered exactly once.`,
+    });
+  }
+}
+
+/**
+ * The story module graph cannot answer a query right now (still building, unsupported builder, or
+ * a build failure).
+ *
+ * Its `message` is written for the agent that triggered the lookup and names the recovery, which
+ * is what `agentFacing` declares: adapters surface it verbatim rather than wrapping it as an
+ * unexpected failure.
+ */
+export class OpenServiceModuleGraphUnavailableError extends StorybookError {
+  constructor(public data: { reason: string }) {
+    super({
+      name: 'OpenServiceModuleGraphUnavailableError',
+      category: Category.CORE_COMMON,
+      code: 25,
+      message: data.reason,
+      agentFacing: true,
+    });
+  }
+}
+
+/**
+ * A toolset method returned data its own published `outputSchema` rejects.
+ *
+ * Always a bug in the method: the schema is the contract adapters publish to their clients, so the
+ * mismatch is raised instead of quietly shipping unvalidated data.
+ */
+export class OpenServiceToolsetOutputMismatchError extends StorybookError {
+  constructor(public data: { issues: readonly unknown[] }) {
+    // Validation issues embed the rejected input, which can be large or circular — the diagnostic
+    // must never throw or balloon while reporting the real bug.
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(data.issues)?.slice(0, 2000) ?? String(data.issues);
+    } catch {
+      serialized = `${data.issues.length} issue(s) that could not be serialized`;
+    }
+    super({
+      name: 'OpenServiceToolsetOutputMismatchError',
+      category: Category.CORE_COMMON,
+      code: 26,
+      message: `Toolset output did not match its published output schema: ${serialized}`,
+    });
+  }
+}
+
 export class WebpackMissingStatsError extends StorybookError {
   constructor() {
     super({
diff --git a/code/core/src/shared/open-service/index.ts b/code/core/src/shared/open-service/index.ts
index 6e1213469514..490f84bd0602 100644
--- a/code/core/src/shared/open-service/index.ts
+++ b/code/core/src/shared/open-service/index.ts
@@ -8,17 +8,36 @@
 export { defineService } from './service-definition.ts';
 export { seedQueryState } from './query-state.ts';
 
-export { defineToolset } from './toolset-definition.ts';
+export { defineToolset, resolveToolsetDescription } from './toolset-definition.ts';
 export type {
   AnyToolsetDefinition,
+  AnyToolsetOutcome,
   ToolsetConsumer,
   ToolsetCtx,
   ToolsetDefinition,
-  ToolsetFormat,
   ToolsetGetService,
   ToolsetMethod,
+  ToolsetMethodDescription,
+  ToolsetOutcome,
+  ToolsetTelemetry,
+  ToolsetTelemetryGroup,
 } from './toolset-definition.ts';
-export { getRegisteredToolsets, registerToolset } from './toolset-registry.ts';
+export { getRef, MCP_TOOL_NAMES } from './toolset-names.ts';
+export type { ToolsetMethodRef } from './toolset-names.ts';
+export {
+  clearToolsetRegistry,
+  getRegisteredToolsets,
+  getToolset,
+  registerToolset,
+} from './toolset-registry.ts';
+// The errors the registry functions above throw. Catchers must import them from this same entry:
+// each core entry bundles its own copy of a class, so an error class imported from another entry
+// is a different constructor and `instanceof` silently fails.
+export {
+  OpenServiceDuplicateToolsetError,
+  OpenServiceMissingToolsetError,
+} from '../../server-errors.ts';
+export type { KnownToolsets } from './toolset-types.ts';
 
 export type { DocgenService } from './services/docgen/definition.ts';
 export type { DocgenPayload } from './services/docgen/types.ts';
diff --git a/code/core/src/shared/open-service/services/docgen/types.ts b/code/core/src/shared/open-service/services/docgen/types.ts
index 21edf6585d21..7ba94fba0678 100644
--- a/code/core/src/shared/open-service/services/docgen/types.ts
+++ b/code/core/src/shared/open-service/services/docgen/types.ts
@@ -1,4 +1,7 @@
-import type { StrictArgTypes } from '../../../../types/modules/csf.ts';
+// From the defining module, not the `types/modules/csf.ts` barrel: that barrel re-exports through
+// the bare `storybook/internal/csf` specifier, which the portable `toolsets-docs` d.ts (this file
+// is in its closure) must not reference — its guard allows no `storybook/*` imports.
+import type { StrictArgTypes } from '../../../../csf/story.ts';
 import type { IndexEntry } from '../../../../types/modules/indexer.ts';
 
 /**
diff --git a/code/core/src/shared/open-service/toolset-registry.test.ts b/code/core/src/shared/open-service/toolset-registry.test.ts
index 1e8c2e9600c6..c21b17163b91 100644
--- a/code/core/src/shared/open-service/toolset-registry.test.ts
+++ b/code/core/src/shared/open-service/toolset-registry.test.ts
@@ -2,10 +2,15 @@ import { beforeEach, describe, expect, it } from 'vitest';
 
 import * as v from 'valibot';
 
+import {
+  OpenServiceDuplicateToolsetError,
+  OpenServiceMissingToolsetError,
+} from '../../server-errors.ts';
 import { defineToolset } from './toolset-definition.ts';
 import {
   clearToolsetRegistry,
   getRegisteredToolsets,
+  getToolset,
   registerToolset,
 } from './toolset-registry.ts';
 
@@ -13,11 +18,13 @@ const makeToolset = (id: string, description = `${id} toolset`) =>
   defineToolset({
     id,
     description,
+    telemetryGroup: 'dev',
     methods: {
       noop: {
+        title: 'No-op',
         description: 'No-op method.',
         schema: v.object({}),
-        handler: () => undefined,
+        handler: () => ({ ok: true, data: undefined, markdown: '' }) as const,
       },
     },
   });
@@ -37,17 +44,28 @@ describe('registerToolset', () => {
     expect(getRegisteredToolsets()).toEqual([docs, review]);
   });
 
-  it('is idempotent by id: the first registration wins', () => {
-    const first = makeToolset('docs', 'first');
-    const second = makeToolset('docs', 'second');
-
-    registerToolset(first);
-    registerToolset(second);
+  it('throws on a duplicate id: two hosts claiming one public surface is mis-wiring', () => {
+    registerToolset(makeToolset('docs', 'first'));
 
-    expect(getRegisteredToolsets()).toEqual([first]);
+    expect(() => registerToolset(makeToolset('docs', 'second'))).toThrow(
+      OpenServiceDuplicateToolsetError
+    );
   });
 
   it('returns an empty list before any registration', () => {
     expect(getRegisteredToolsets()).toEqual([]);
   });
 });
+
+describe('getToolset', () => {
+  it('returns a registered toolset by id', () => {
+    const docs = makeToolset('docs');
+    registerToolset(docs);
+
+    expect(getToolset('docs')).toBe(docs);
+  });
+
+  it('throws for an unregistered id instead of returning an empty result', () => {
+    expect(() => getToolset('stories')).toThrow(OpenServiceMissingToolsetError);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-local.test.ts b/code/core/src/shared/open-service/toolsets/docs/access-local.test.ts
new file mode 100644
index 000000000000..2d0d80cb74a7
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-local.test.ts
@@ -0,0 +1,77 @@
+/**
+ * Selection contract for the local docs access: which engine serves is decided by whether the
+ * docgen services actually registered, never by the feature flag alone. Composed and uncomposed
+ * consumers share this helper, so this is the single place the choice is pinned.
+ */
+
+import type { StoryIndex } from 'storybook/internal/types';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createLocalDocsAccess } from './access-local.ts';
+import type { RawManifests } from './access-manifest.ts';
+
+const getRegisteredServices = vi.hoisted(() => vi.fn<() => Array<{ id: string }>>(() => []));
+const getService = vi.hoisted(() =>
+  vi.fn(() => {
+    throw new Error('read from the docgen services');
+  })
+);
+vi.mock('../../service-registry.ts', () => ({ getRegisteredServices, getService }));
+
+const manifests: RawManifests = {
+  components: {
+    v: 0,
+    components: { button: { id: 'button', name: 'Button' } },
+    meta: { docgen: 'react-docgen', durationMs: 1 },
+  },
+};
+
+const emptyIndex = { v: 5, entries: {} } as StoryIndex;
+
+const createAccess = () =>
+  createLocalDocsAccess({
+    storyIndex: { getIndex: async () => emptyIndex },
+    getManifests: async () => manifests,
+  });
+
+beforeEach(() => {
+  getRegisteredServices.mockReturnValue([]);
+});
+
+describe('createLocalDocsAccess', () => {
+  it('serves from the inline manifests when the docgen services never registered', async () => {
+    const listing = await createAccess().list({ withStoryIds: false });
+
+    expect(Object.keys(listing.componentManifest.components)).toEqual(['button']);
+    expect(getService).not.toHaveBeenCalled();
+  });
+
+  it('serves from the open services once the docgen services registered', async () => {
+    getRegisteredServices.mockReturnValue([{ id: 'core/docgen' }, { id: 'core/story-docs' }]);
+
+    await expect(createAccess().list({ withStoryIds: false })).rejects.toThrow(
+      'read from the docgen services'
+    );
+  });
+
+  it('falls back to the inline manifests when docgen registered without story-docs', async () => {
+    getRegisteredServices.mockReturnValue([{ id: 'core/docgen' }]);
+
+    const listing = await createAccess().list({ withStoryIds: false });
+
+    expect(Object.keys(listing.componentManifest.components)).toEqual(['button']);
+    expect(getService).not.toHaveBeenCalled();
+  });
+
+  it('probes per call, because it can be created before the services preset hooks run', async () => {
+    const access = createAccess();
+
+    await expect(access.list({ withStoryIds: false })).resolves.toBeDefined();
+
+    getRegisteredServices.mockReturnValue([{ id: 'core/docgen' }, { id: 'core/story-docs' }]);
+    await expect(access.list({ withStoryIds: false })).rejects.toThrow(
+      'read from the docgen services'
+    );
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-manifest.test.ts b/code/core/src/shared/open-service/toolsets/docs/access-manifest.test.ts
new file mode 100644
index 000000000000..0cd579d8bb00
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-manifest.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createManifestDocsAccess, type RawManifests } from './access-manifest.ts';
+
+const button = {
+  id: 'button',
+  name: 'Button',
+  summary: 'A button',
+  stories: [{ id: 'button--primary', name: 'Primary', snippet: '<Button />' }],
+  docs: { 'button--docs': { id: 'button--docs', name: 'Button docs', content: '# Button' } },
+};
+
+const guide = {
+  id: 'guide--docs',
+  name: 'Guide',
+  title: 'Getting started',
+  content: '# Guide',
+  summary: 'Intro',
+};
+
+const inlineManifests: RawManifests = {
+  components: { v: 0, components: { button }, meta: { docgen: 'react-docgen', durationMs: 1 } },
+  docs: { v: 0, docs: { 'guide--docs': guide } },
+};
+
+const createAccess = (manifests: RawManifests = inlineManifests) =>
+  createManifestDocsAccess({ getManifests: async () => manifests });
+
+describe('createManifestDocsAccess list', () => {
+  it('returns the inline manifests as the shared listing shape', async () => {
+    const manifests = await createAccess().list({ withStoryIds: true });
+
+    expect(manifests.componentManifest.v).toBe(0);
+    expect(manifests.componentManifest.components.button).toEqual(button);
+    expect(manifests.docsManifest).toEqual({ v: 0, docs: { 'guide--docs': guide } });
+  });
+
+  it('drops inline stories when story ids were not requested', async () => {
+    const manifests = await createAccess().list({ withStoryIds: false });
+
+    expect(manifests.componentManifest.components.button).not.toHaveProperty('stories');
+    expect(manifests.componentManifest.components.button).toMatchObject({
+      id: 'button',
+      name: 'Button',
+      summary: 'A button',
+    });
+  });
+
+  it('keeps the shallow version marker when the manifest is shallow', async () => {
+    const manifests = await createAccess({
+      components: { v: 1, components: { button: { id: 'button', name: 'Button' } } },
+    }).list({ withStoryIds: true });
+
+    expect(manifests.componentManifest.v).toBe(1);
+    expect(manifests.docsManifest).toBeUndefined();
+  });
+
+  it('returns an empty listing when no manifests are configured', async () => {
+    await expect(createAccess({}).list({ withStoryIds: true })).resolves.toEqual({
+      componentManifest: { v: 1, components: {} },
+    });
+  });
+});
+
+describe('createManifestDocsAccess resolve', () => {
+  it('resolves a component with everything the inline manifest carries', async () => {
+    await expect(createAccess().resolve('button')).resolves.toEqual({
+      kind: 'component',
+      component: button,
+    });
+  });
+
+  it('falls through to the docs manifest', async () => {
+    await expect(createAccess().resolve('guide--docs')).resolves.toEqual({
+      kind: 'doc',
+      doc: guide,
+    });
+  });
+
+  it('returns undefined for unknown ids', async () => {
+    await expect(createAccess().resolve('nope')).resolves.toBeUndefined();
+  });
+
+  it.each(['constructor', 'toString', 'hasOwnProperty'])(
+    'answers absence for the prototype member %s instead of rendering it',
+    async (id) => {
+      await expect(createAccess().resolve(id)).resolves.toBeUndefined();
+    }
+  );
+
+  it('reloads the manifests on every call so edits are picked up', async () => {
+    const getManifests = vi.fn(async () => inlineManifests);
+    const access = createManifestDocsAccess({ getManifests });
+
+    await access.list({ withStoryIds: true });
+    await access.resolve('button');
+
+    expect(getManifests).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-parity.test.ts b/code/core/src/shared/open-service/toolsets/docs/access-parity.test.ts
new file mode 100644
index 000000000000..6bf8e762b46a
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-parity.test.ts
@@ -0,0 +1,177 @@
+/**
+ * Cross-mode parity for the docs tools.
+ *
+ * Whether the docgen services registered decides which access the docs toolset runs on (see
+ * `createLocalDocsAccess`), and the two build their answers from completely different sources —
+ * the open services versus the manifests core builds.
+ * Agents must not be able to tell which one served them, so the same project expressed both ways
+ * has to render the same text. This is the only mechanical comparison of the two modes; the e2e
+ * suite exercises the default mode only.
+ */
+
+import type { StoryIndex } from 'storybook/internal/types';
+import { describe, expect, it } from 'vitest';
+
+import { Tag } from '../../../constants/tags.ts';
+import type { ToolsetCtx } from '../../toolset-definition.ts';
+import { createManifestDocsAccess } from './access-manifest.ts';
+import { createServiceDocsAccess } from './access-service.ts';
+import { createDocsToolset } from './definition.ts';
+
+const ctx: ToolsetCtx = { consumer: 'mcp', getService: () => ({}) as never };
+
+const storyIndex = {
+  v: 5,
+  entries: {
+    'button--primary': {
+      id: 'button--primary',
+      title: 'Button',
+      name: 'Primary',
+      importPath: './src/Button.stories.tsx',
+      type: 'story',
+      subtype: 'story',
+      componentPath: './src/Button.tsx',
+      tags: [Tag.MANIFEST],
+    },
+    'guide--docs': {
+      id: 'guide--docs',
+      title: 'Guide',
+      name: 'Guide',
+      importPath: './src/Guide.mdx',
+      type: 'docs',
+      tags: [Tag.MANIFEST, Tag.UNATTACHED_MDX],
+    },
+  },
+} as unknown as StoryIndex;
+
+const docgenPayload = {
+  id: 'button',
+  name: 'Button',
+  path: './src/Button.tsx',
+  description: 'A button',
+  summary: 'Clickable',
+  props: [{ name: 'variant', type: 'string', required: false, description: 'Visual style' }],
+};
+
+const storyDocsPayload = {
+  id: 'button',
+  name: 'Button',
+  path: './src/Button.stories.tsx',
+  import: "import { Button } from './Button'",
+  stories: {
+    'button--primary': { id: 'button--primary', name: 'Primary', snippet: '<Button />' },
+  },
+};
+
+const mdxPayload = {
+  id: 'guide--docs',
+  name: 'Guide',
+  docs: {
+    'guide--docs': { id: 'guide--docs', name: 'Guide', summary: 'How to', content: '# Guide' },
+  },
+};
+
+/** The same project as the open services expose it (docgen-server mode). */
+function serviceToolset() {
+  const services: Record<string, unknown> = {
+    'core/docgen': {
+      queries: {
+        docgenForAllComponents: { loaded: async () => ({ button: docgenPayload }) },
+        docgen: {
+          loaded: async ({ id }: { id: string }) => (id === 'button' ? docgenPayload : undefined),
+        },
+      },
+    },
+    'core/story-docs': {
+      queries: {
+        storyDocsForAllComponents: { loaded: async () => ({ button: storyDocsPayload }) },
+        storyDocs: {
+          loaded: async ({ id }: { id: string }) =>
+            id === 'button' ? storyDocsPayload : undefined,
+        },
+      },
+    },
+    'addon-docs/mdx': {
+      queries: {
+        mdxForAllComponents: { loaded: async () => ({ 'guide--docs': mdxPayload }) },
+        mdxForComponent: {
+          loaded: async ({ id }: { id: string }) => (id === 'guide--docs' ? mdxPayload : undefined),
+        },
+      },
+    },
+  };
+
+  return createDocsToolset({
+    docsAccess: createServiceDocsAccess({
+      storyIndex: { getIndex: async () => storyIndex },
+      getService: ((id: string) => services[id]) as never,
+    }),
+  });
+}
+
+/** The same project as core's manifest builder emits it (the default mode). */
+function manifestToolset() {
+  return createDocsToolset({
+    docsAccess: createManifestDocsAccess({
+      getManifests: async () => ({
+        components: {
+          v: 0,
+          components: {
+            button: {
+              id: 'button',
+              name: 'Button',
+              description: 'A button',
+              summary: 'Clickable',
+              props: docgenPayload.props,
+              import: storyDocsPayload.import,
+              stories: [{ id: 'button--primary', name: 'Primary', snippet: '<Button />' }],
+            },
+          },
+        },
+        docs: {
+          v: 0,
+          docs: {
+            'guide--docs': {
+              id: 'guide--docs',
+              name: 'Guide',
+              summary: 'How to',
+              content: '# Guide',
+            },
+          },
+        },
+      }),
+    }),
+  });
+}
+
+async function renderList(toolset: ReturnType<typeof createDocsToolset>, withStoryIds: boolean) {
+  return (await toolset.methods.list.handler({ withStoryIds }, ctx)).markdown;
+}
+
+async function renderShow(toolset: ReturnType<typeof createDocsToolset>, id: string) {
+  return (await toolset.methods.show.handler({ id }, ctx)).markdown;
+}
+
+describe('docs tools render the same text in both docgen modes', () => {
+  it.each([false, true])('list with withStoryIds=%s', async (withStoryIds) => {
+    expect(await renderList(serviceToolset(), withStoryIds)).toBe(
+      await renderList(manifestToolset(), withStoryIds)
+    );
+  });
+
+  it.each(['button', 'guide--docs', 'unknown-id'])('show %s', async (id) => {
+    expect(await renderShow(serviceToolset(), id)).toBe(await renderShow(manifestToolset(), id));
+  });
+
+  it('showStory', async () => {
+    const render = async (toolset: ReturnType<typeof createDocsToolset>) =>
+      (
+        await toolset.methods.showStory.handler(
+          { componentId: 'button', storyName: 'Primary' },
+          ctx
+        )
+      ).markdown;
+
+    expect(await render(serviceToolset())).toBe(await render(manifestToolset()));
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-provider-isolation.test.ts b/code/core/src/shared/open-service/toolsets/docs/access-provider-isolation.test.ts
new file mode 100644
index 000000000000..b65e5eac5fd8
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-provider-isolation.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Failure isolation and fan-out while expanding a listing's story `$ref`s.
+ *
+ * A composed listing is assembled from several Storybooks over the network, so one unreachable
+ * `$ref` must cost that source its story ids — not its rows, and not the other sources.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { createProviderDocsAccess } from './access-provider.ts';
+
+const COMPONENTS = JSON.stringify({
+  v: 1,
+  components: {
+    button: { id: 'button', name: 'Button', stories: { $ref: 'services/stories.json#/button' } },
+    card: { id: 'card', name: 'Card', stories: { $ref: 'services/stories.json#/card' } },
+  },
+});
+
+const SOURCE = { id: 'design-system', title: 'Design System', url: 'https://ds.example.com' };
+
+/** Serves the index, and fails every story `$ref` fetch. */
+function providerWithBrokenStoryRefs() {
+  return async (_request: unknown, path: string) => {
+    if (path.endsWith('components.json')) {
+      return COMPONENTS;
+    }
+    if (path.endsWith('docs.json')) {
+      return JSON.stringify({ v: 1, docs: {} });
+    }
+    throw new Error(`unreachable: ${path}`);
+  };
+}
+
+describe('resolving hostile ids', () => {
+  it.each(['constructor', 'toString', 'hasOwnProperty'])(
+    'answers absence for the prototype member %s instead of rendering it',
+    async (id) => {
+      const access = createProviderDocsAccess({ manifestProvider: providerWithBrokenStoryRefs() });
+
+      await expect(access.resolve(id)).resolves.toBeUndefined();
+    }
+  );
+});
+
+describe('expanding story refs', () => {
+  it('keeps a composed source listed when its story refs fail', async () => {
+    const access = createProviderDocsAccess({
+      source: SOURCE,
+      manifestProvider: providerWithBrokenStoryRefs(),
+    });
+
+    const manifests = await access.list({ withStoryIds: true });
+
+    expect(Object.keys(manifests.componentManifest.components)).toEqual(['button', 'card']);
+  });
+
+  it('fails the listing of a single Storybook, which has nothing to fall back on', async () => {
+    const access = createProviderDocsAccess({ manifestProvider: providerWithBrokenStoryRefs() });
+
+    await expect(access.list({ withStoryIds: true })).rejects.toThrow();
+  });
+
+  it('bounds how many story refs are in flight at once', async () => {
+    const total = 60;
+    const components = Object.fromEntries(
+      Array.from({ length: total }, (_, index) => [
+        `c${index}`,
+        {
+          id: `c${index}`,
+          name: `C${index}`,
+          stories: { $ref: `services/stories.json#/c${index}` },
+        },
+      ])
+    );
+
+    let inFlight = 0;
+    let peak = 0;
+    const access = createProviderDocsAccess({
+      source: SOURCE,
+      manifestProvider: async (_request: unknown, path: string) => {
+        if (path.endsWith('components.json')) {
+          return JSON.stringify({ v: 1, components });
+        }
+        if (path.endsWith('docs.json')) {
+          return JSON.stringify({ v: 1, docs: {} });
+        }
+        inFlight += 1;
+        peak = Math.max(peak, inFlight);
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        inFlight -= 1;
+        // Every pointer must resolve: a failed ref would reject the whole fan-out after the first
+        // wave, and the bound would never be exercised past the initial 16.
+        return JSON.stringify(
+          Object.fromEntries(
+            Array.from({ length: total }, (_, index) => [`c${index}`, { stories: {} }])
+          )
+        );
+      },
+    });
+
+    await access.list({ withStoryIds: true });
+
+    expect(peak).toBeLessThanOrEqual(16);
+    expect(peak).toBeGreaterThan(1);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-provider.test.ts b/code/core/src/shared/open-service/toolsets/docs/access-provider.test.ts
new file mode 100644
index 000000000000..4fdfeab33cbe
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-provider.test.ts
@@ -0,0 +1,937 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  fetchManifests as getManifests,
+  parseManifestRef,
+  resolveComponentEntry,
+  resolveComponentStories,
+  resolveDocEntry as resolveDoc,
+} from './access-provider.ts';
+import { createCompositionDocsSources, listSources } from './multi-source.ts';
+import { ManifestGetError, RequiresOwnMcpError, type Source } from './sources.ts';
+import type {
+  ComponentManifest,
+  ComponentManifestMap,
+  ComponentManifestV1,
+  Doc,
+  DocsManifestMap,
+  DocV1,
+} from './manifest-formatter/manifest-types.ts';
+
+/**
+ * Composition listing, expressed the way the tools now reach it: one access per source, each
+ * failing independently. Mirrors the shape the previous `getMultiSourceManifests` returned.
+ */
+async function getMultiSourceManifests(
+  sources: Source[],
+  request?: Request,
+  manifestProvider?: Parameters<typeof createCompositionDocsSources>[0]['manifestProvider']
+) {
+  const listings = await listSources(
+    createCompositionDocsSources({ sources, manifestProvider, getRequest: () => request }),
+    { withStoryIds: false }
+  );
+  return listings.map(({ source, manifests, error, notice }) => ({
+    source,
+    componentManifest: manifests?.componentManifest ?? { v: 1 as const, components: {} },
+    docsManifest: manifests?.docsManifest,
+    ...(error ? { error } : {}),
+    ...(notice ? { notice } : {}),
+  }));
+}
+
+/**
+ * Helper function to create a mock Request object
+ */
+function createMockRequest(url: string): Request {
+  return new Request(url, {
+    method: 'POST',
+  });
+}
+
+/**
+ * Helper to create a successful JSON fetch response
+ */
+function createJsonResponse(data: unknown) {
+  return {
+    ok: true,
+    headers: {
+      get: vi.fn().mockReturnValue('application/json'),
+    },
+    text: vi.fn().mockResolvedValue(JSON.stringify(data)),
+  };
+}
+
+/**
+ * Helper to create a 404 response
+ */
+function create404Response() {
+  return {
+    ok: false,
+    status: 404,
+    statusText: 'Not Found',
+  };
+}
+
+/**
+ * Helper to create a fetch mock that returns different responses based on URL
+ */
+function createFetchMock(responses: { components?: unknown; docs?: unknown }) {
+  return vi.fn().mockImplementation((url: string) => {
+    if (url.includes('components.json')) {
+      if (responses.components instanceof Error) {
+        return Promise.reject(responses.components);
+      }
+      return Promise.resolve(
+        responses.components !== undefined
+          ? createJsonResponse(responses.components)
+          : create404Response()
+      );
+    }
+    if (url.includes('docs.json')) {
+      if (responses.docs instanceof Error) {
+        return Promise.reject(responses.docs);
+      }
+      return Promise.resolve(
+        responses.docs !== undefined ? createJsonResponse(responses.docs) : create404Response()
+      );
+    }
+    return Promise.resolve(create404Response());
+  });
+}
+
+/**
+ * Helper to create a manifestProvider mock that returns different responses based on path
+ */
+function createManifestProviderMock(responses: {
+  components?: string | Error;
+  docs?: string | Error;
+}) {
+  return vi.fn().mockImplementation((_request: Request | undefined, path: string) => {
+    if (path.includes('components.json')) {
+      if (responses.components instanceof Error) {
+        return Promise.reject(responses.components);
+      }
+      return responses.components !== undefined
+        ? Promise.resolve(responses.components)
+        : Promise.reject(new Error('Components not found'));
+    }
+    if (path.includes('docs.json')) {
+      if (responses.docs instanceof Error) {
+        return Promise.reject(responses.docs);
+      }
+      return responses.docs !== undefined
+        ? Promise.resolve(responses.docs)
+        : Promise.reject(new Error('Docs not found'));
+    }
+    return Promise.reject(new Error('Unknown path'));
+  });
+}
+
+describe('getManifest', () => {
+  beforeEach(() => {
+    vi.stubGlobal('fetch', vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe('error cases', () => {
+    it('should throw ManifestGetError when request is not provided and using default provider', async () => {
+      await expect(getManifests()).rejects.toThrow(ManifestGetError);
+      await expect(getManifests()).rejects.toThrow(
+        "You must either pass the original request forward to the server context, or set a custom manifestProvider that doesn't need the request"
+      );
+    });
+    it('should throw ManifestGetError when request is undefined and using default provider', async () => {
+      await expect(getManifests(undefined)).rejects.toThrow(ManifestGetError);
+      await expect(getManifests(undefined)).rejects.toThrow(
+        "You must either pass the original request forward to the server context, or set a custom manifestProvider that doesn't need the request"
+      );
+    });
+    it('should throw ManifestGetError when fetch fails with 404 and include hint about componentsManifest', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          ok: false,
+          status: 404,
+          statusText: 'Not Found',
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      await expect(getManifests(request)).rejects.toThrow(ManifestGetError);
+      await expect(getManifests(request)).rejects.toThrow(
+        'Failed to fetch manifest: 404 Not Found'
+      );
+      await expect(getManifests(request)).rejects.toThrow('componentsManifest');
+      await expect(getManifests(request)).rejects.toThrow('experimentalComponentsManifest');
+    });
+
+    it('should throw ManifestGetError when fetch fails with 500 without manifest hint', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          ok: false,
+          status: 500,
+          statusText: 'Internal Server Error',
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      await expect(getManifests(request)).rejects.toThrow(
+        'Failed to fetch manifest: 500 Internal Server Error'
+      );
+      try {
+        await getManifests(request);
+      } catch (error) {
+        expect((error as Error).message).not.toContain('componentsManifest');
+      }
+    });
+
+    it('should throw ManifestGetError when content type is not JSON', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          ok: true,
+          headers: {
+            get: vi.fn().mockReturnValue('text/html'),
+          },
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      await expect(getManifests(request)).rejects.toThrow(ManifestGetError);
+      await expect(getManifests(request)).rejects.toThrow(
+        'Invalid content type: expected application/json, got text/html'
+      );
+    });
+
+    it('should throw ManifestGetError when response is not valid JSON', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockImplementation((url: string) => {
+          if (url.includes('components.json')) {
+            return Promise.resolve({
+              ok: true,
+              headers: {
+                get: vi.fn().mockReturnValue('application/json'),
+              },
+              text: vi.fn().mockResolvedValue('not valid json{'),
+            });
+          }
+          return Promise.resolve(create404Response());
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      await expect(getManifests(request)).rejects.toThrow(ManifestGetError);
+      await expect(getManifests(request)).rejects.toThrow('Failed to parse component manifest:');
+    });
+
+    it('should throw ManifestGetError when manifest schema is invalid', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          ok: true,
+          headers: {
+            get: vi.fn().mockReturnValue('application/json'),
+          },
+          text: vi.fn().mockResolvedValue(
+            JSON.stringify({
+              // Missing required 'components' field
+              v: 1,
+            })
+          ),
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      await expect(getManifests(request)).rejects
+        .toThrowErrorMatchingInlineSnapshot(`[ManifestGetError: Failed to parse component manifest:
+Invalid key: Expected "components" but received undefined]`);
+    });
+
+    it('should throw ManifestGetError when components object is empty', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          ok: true,
+          headers: {
+            get: vi.fn().mockReturnValue('application/json'),
+          },
+          text: vi.fn().mockResolvedValue(
+            JSON.stringify({
+              v: 1,
+              components: {},
+            })
+          ),
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      await expect(getManifests(request)).rejects.toThrow(ManifestGetError);
+      await expect(getManifests(request)).rejects.toThrow('No components found in the manifest');
+    });
+
+    it('should wrap network errors in ManifestGetError', async () => {
+      vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('Network connection failed')));
+
+      const request = createMockRequest('https://example.com/mcp');
+      await expect(getManifests(request)).rejects.toThrow(ManifestGetError);
+      await expect(getManifests(request)).rejects.toThrow('Network connection failed');
+    });
+
+    it('should preserve ManifestGetError when already thrown', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          ok: false,
+          status: 404,
+          statusText: 'Not Found',
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      try {
+        await getManifests(request);
+      } catch (error) {
+        expect(error).toBeInstanceOf(ManifestGetError);
+        expect((error as ManifestGetError).url).toBe(
+          'https://example.com/manifests/components.json'
+        );
+      }
+    });
+  });
+
+  describe('success cases', () => {
+    it('should successfully fetch and parse a valid manifest', async () => {
+      const validManifest: ComponentManifestMap = {
+        v: 0,
+        components: {
+          button: {
+            id: 'button',
+            path: 'src/components/Button.tsx',
+            name: 'Button',
+            description: 'A button component',
+          },
+        },
+      };
+
+      vi.stubGlobal('fetch', createFetchMock({ components: validManifest }));
+
+      const request = createMockRequest('https://example.com/mcp');
+      const result = await getManifests(request);
+
+      expect(result).toEqual({ componentManifest: validManifest });
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+      expect(global.fetch).toHaveBeenCalledWith('https://example.com/manifests/components.json');
+      expect(global.fetch).toHaveBeenCalledWith('https://example.com/manifests/docs.json');
+    });
+
+    it.each([
+      ['https://example.com/mcp', 'https://example.com'],
+      ['https://example.com/mcp/', 'https://example.com'],
+      ['https://example.com/tools/mcp?transport=sse', 'https://example.com'],
+      ['https://example.com/storybook/tools/mcp', 'https://example.com'],
+      ['http://localhost:6006/custom-mcp', 'http://localhost:6006'],
+    ])('should derive manifest URLs from the request origin for %s', async (requestUrl, origin) => {
+      const validManifest: ComponentManifestMap = {
+        v: 0,
+        components: {
+          button: {
+            id: 'button',
+            path: 'src/components/Button.tsx',
+            name: 'Button',
+            description: 'A button component',
+          },
+        },
+      };
+
+      vi.stubGlobal('fetch', createFetchMock({ components: validManifest }));
+
+      const request = createMockRequest(requestUrl);
+      const result = await getManifests(request);
+
+      expect(result).toEqual({ componentManifest: validManifest });
+      expect(global.fetch).toHaveBeenCalledWith(`${origin}/manifests/components.json`);
+      expect(global.fetch).toHaveBeenCalledWith(`${origin}/manifests/docs.json`);
+    });
+
+    it('should successfully fetch and parse both component and docs manifests', async () => {
+      const validComponentManifest: ComponentManifestMap = {
+        v: 0,
+        components: {
+          button: {
+            id: 'button',
+            path: 'src/components/Button.tsx',
+            name: 'Button',
+            description: 'A button component',
+          },
+        },
+      };
+
+      const validDocsManifest: DocsManifestMap = {
+        v: 0,
+        docs: {
+          'getting-started': {
+            id: 'getting-started',
+            name: 'Getting Started',
+            title: 'Getting Started Guide',
+            path: 'docs/getting-started.mdx',
+            content: '# Getting Started\n\nWelcome to our component library.',
+          },
+        },
+      };
+
+      vi.stubGlobal(
+        'fetch',
+        createFetchMock({
+          components: validComponentManifest,
+          docs: validDocsManifest,
+        })
+      );
+
+      const request = createMockRequest('https://example.com/mcp');
+      const result = await getManifests(request);
+
+      expect(result).toEqual({
+        componentManifest: validComponentManifest,
+        docsManifest: validDocsManifest,
+      });
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('manifestProvider', () => {
+    it('should use manifestProvider when provided', async () => {
+      const validManifest: ComponentManifestMap = {
+        v: 0,
+        components: {
+          button: {
+            id: 'button',
+            path: 'src/components/Button.tsx',
+            name: 'Button',
+            description: 'A button component',
+          },
+        },
+      };
+
+      const request = createMockRequest('https://example.com/mcp');
+      const manifestProvider = createManifestProviderMock({
+        components: JSON.stringify(validManifest),
+      });
+
+      const result = await getManifests(request, manifestProvider);
+
+      expect(result).toEqual({ componentManifest: validManifest });
+      expect(manifestProvider).toHaveBeenCalledTimes(2);
+      expect(manifestProvider).toHaveBeenCalledWith(
+        request,
+        './manifests/components.json',
+        undefined
+      );
+      expect(manifestProvider).toHaveBeenCalledWith(request, './manifests/docs.json', undefined);
+      // fetch should not be called when manifestProvider is used
+      expect(global.fetch).not.toHaveBeenCalled();
+    });
+
+    it('should allow manifestProvider to work without request', async () => {
+      const validManifest: ComponentManifestMap = {
+        v: 0,
+        components: {
+          button: {
+            id: 'button',
+            path: 'src/components/Button.tsx',
+            name: 'Button',
+            description: 'A button component',
+          },
+        },
+      };
+
+      const manifestProvider = createManifestProviderMock({
+        components: JSON.stringify(validManifest),
+      });
+
+      const result = await getManifests(undefined, manifestProvider);
+
+      expect(result).toEqual({ componentManifest: validManifest });
+      expect(manifestProvider).toHaveBeenCalledTimes(2);
+      expect(manifestProvider).toHaveBeenCalledWith(
+        undefined,
+        './manifests/components.json',
+        undefined
+      );
+      // fetch should not be called when manifestProvider is used
+      expect(global.fetch).not.toHaveBeenCalled();
+    });
+
+    it('should fallback to fetch when manifestProvider is not provided', async () => {
+      const validManifest: ComponentManifestMap = {
+        v: 0,
+        components: {
+          button: {
+            id: 'button',
+            path: 'src/components/Button.tsx',
+            name: 'Button',
+            description: 'A button component',
+          },
+        },
+      };
+
+      vi.stubGlobal('fetch', createFetchMock({ components: validManifest }));
+
+      const request = createMockRequest('https://example.com/mcp');
+      const result = await getManifests(request);
+
+      expect(result).toEqual({ componentManifest: validManifest });
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+      expect(global.fetch).toHaveBeenCalledWith('https://example.com/manifests/components.json');
+    });
+
+    it('should handle errors from manifestProvider', async () => {
+      const request = createMockRequest('https://example.com/mcp');
+      const manifestProvider = createManifestProviderMock({
+        components: new Error('File not found'),
+      });
+
+      await expect(getManifests(request, manifestProvider)).rejects.toThrow(ManifestGetError);
+      await expect(getManifests(request, manifestProvider)).rejects.toThrow(
+        'Failed to get component manifest: File not found'
+      );
+    });
+
+    it('should handle invalid JSON from manifestProvider', async () => {
+      const request = createMockRequest('https://example.com/mcp');
+      const manifestProvider = createManifestProviderMock({
+        components: 'not valid json{',
+      });
+
+      await expect(getManifests(request, manifestProvider)).rejects.toThrow(ManifestGetError);
+    });
+  });
+
+  describe('getMultiSourceManifests', () => {
+    const localSource: Source = { id: 'local', title: 'Local' };
+    const remoteSource: Source & { url: string } = {
+      id: 'remote',
+      title: 'Remote',
+      url: 'http://remote.example.com',
+    };
+
+    const localManifest: ComponentManifestMap = {
+      v: 0,
+      components: {
+        button: {
+          id: 'button',
+          path: 'src/Button.tsx',
+          name: 'Button',
+        },
+      },
+    };
+
+    const remoteManifest: ComponentManifestMap = {
+      v: 0,
+      components: {
+        badge: {
+          id: 'badge',
+          path: 'src/Badge.tsx',
+          name: 'Badge',
+        },
+      },
+    };
+
+    it('should fetch manifests from multiple sources in parallel', async () => {
+      const manifestProvider = vi
+        .fn()
+        .mockImplementation((_req: Request | undefined, path: string, source?: Source) => {
+          if (path.includes('docs.json')) {
+            return Promise.reject(new Error('Not found'));
+          }
+          const manifest = source?.id === 'remote' ? remoteManifest : localManifest;
+          return Promise.resolve(JSON.stringify(manifest));
+        });
+
+      const results = await getMultiSourceManifests(
+        [localSource, remoteSource],
+        undefined,
+        manifestProvider
+      );
+
+      expect(results).toHaveLength(2);
+      expect(results[0]!.source.id).toBe('local');
+      expect(results[0]!.componentManifest).toEqual(localManifest);
+      expect(results[0]!.error).toBeUndefined();
+      expect(results[1]!.source.id).toBe('remote');
+      expect(results[1]!.componentManifest).toEqual(remoteManifest);
+      expect(results[1]!.error).toBeUndefined();
+    });
+
+    it('should capture errors for individual sources without failing', async () => {
+      const manifestProvider = vi
+        .fn()
+        .mockImplementation((_req: Request | undefined, path: string, source?: Source) => {
+          if (source?.id === 'remote') {
+            return Promise.reject(new Error('401 Unauthorized'));
+          }
+          if (path.includes('docs.json')) {
+            return Promise.reject(new Error('Not found'));
+          }
+          return Promise.resolve(JSON.stringify(localManifest));
+        });
+
+      const results = await getMultiSourceManifests(
+        [localSource, remoteSource],
+        undefined,
+        manifestProvider
+      );
+
+      expect(results).toHaveLength(2);
+      expect(results[0]!.error).toBeUndefined();
+      expect(results[0]!.componentManifest).toEqual(localManifest);
+      expect(results[1]!.error).toContain('401 Unauthorized');
+      expect(results[1]!.componentManifest).toEqual({ v: 1, components: {} });
+    });
+
+    it('should capture requires-own-mcp notices without treating them as failed output', async () => {
+      const manifestProvider = vi
+        .fn()
+        .mockImplementation((_req: Request | undefined, path: string, source?: Source) => {
+          if (source?.id === 'remote') {
+            return Promise.reject(new RequiresOwnMcpError(remoteSource));
+          }
+          if (path.includes('docs.json')) {
+            return Promise.reject(new Error('Not found'));
+          }
+          return Promise.resolve(JSON.stringify(localManifest));
+        });
+
+      const results = await getMultiSourceManifests(
+        [localSource, remoteSource],
+        undefined,
+        manifestProvider
+      );
+
+      expect(results).toHaveLength(2);
+      expect(results[0]!.error).toBeUndefined();
+      expect(results[1]!.error).toBeUndefined();
+      expect(results[1]!.notice).toEqual({
+        kind: 'requires-own-mcp',
+        endpoint: 'http://remote.example.com/mcp',
+      });
+    });
+
+    it('should throw when all sources fail', async () => {
+      const manifestProvider = vi.fn().mockRejectedValue(new Error('Failed'));
+
+      await expect(
+        getMultiSourceManifests([localSource, remoteSource], undefined, manifestProvider)
+      ).rejects.toThrow('Failed to fetch manifests from any source');
+    });
+
+    it('should pass source to manifestProvider', async () => {
+      const manifestProvider = vi
+        .fn()
+        .mockImplementation((_req: Request | undefined, path: string, _source?: Source) => {
+          if (path.includes('docs.json')) {
+            return Promise.reject(new Error('Not found'));
+          }
+          return Promise.resolve(JSON.stringify(localManifest));
+        });
+
+      await getMultiSourceManifests([localSource, remoteSource], undefined, manifestProvider);
+
+      // Each source calls provider twice (components + docs)
+      expect(manifestProvider).toHaveBeenCalledWith(
+        undefined,
+        './manifests/components.json',
+        localSource
+      );
+      expect(manifestProvider).toHaveBeenCalledWith(
+        undefined,
+        './manifests/components.json',
+        remoteSource
+      );
+    });
+  });
+});
+
+describe('parseManifestRef', () => {
+  it('resolves a `../`-prefixed ref relative to the component manifest location', () => {
+    expect(parseManifestRef('../services/core/docgen/button.json#/components/button')).toEqual({
+      path: './services/core/docgen/button.json',
+      pointer: ['components', 'button'],
+    });
+  });
+
+  it('resolves a sibling ref within the manifests directory', () => {
+    expect(parseManifestRef('./button.json#/components/button')).toEqual({
+      path: './manifests/button.json',
+      pointer: ['components', 'button'],
+    });
+  });
+
+  it('decodes JSON-pointer escape sequences', () => {
+    expect(parseManifestRef('../x.json#/a~1b/c~0d')).toEqual({
+      path: './x.json',
+      pointer: ['a/b', 'c~d'],
+    });
+  });
+});
+
+describe('resolveComponentEntry', () => {
+  const stub: ComponentManifestV1 = {
+    id: 'button',
+    name: 'Button',
+    description: 'A button',
+    docgen: { $ref: '../services/core/docgen/button.json#/components/button' },
+  };
+
+  it('returns the component unchanged when it has no docgen $ref', async () => {
+    const plain: ComponentManifest = { id: 'button', name: 'Button', path: 'src/Button.tsx' };
+    const provider = vi.fn();
+    await expect(resolveComponentEntry(plain, undefined, provider)).resolves.toBe(plain);
+    expect(provider).not.toHaveBeenCalled();
+  });
+
+  it('fetches the referenced file and merges the resolved entry over the stub', async () => {
+    const provider = vi.fn().mockResolvedValue(
+      JSON.stringify({
+        components: {
+          button: {
+            id: 'button',
+            name: 'Button',
+            path: 'src/Button.tsx',
+            stories: [{ name: 'Primary', snippet: '<Button />' }],
+          },
+        },
+      })
+    );
+
+    const resolved = await resolveComponentEntry(stub, undefined, provider);
+
+    // Provider is asked for the resolved (relative) path of the referenced file.
+    expect(provider).toHaveBeenCalledWith(
+      undefined,
+      './services/core/docgen/button.json',
+      undefined
+    );
+    expect(resolved.path).toBe('src/Button.tsx');
+    expect(resolved.stories).toEqual([{ name: 'Primary', snippet: '<Button />' }]);
+    // Stub identity fields are retained.
+    expect(resolved.id).toBe('button');
+  });
+
+  it('throws when the JSON pointer does not resolve', async () => {
+    const provider = vi.fn().mockResolvedValue(JSON.stringify({ components: {} }));
+    await expect(resolveComponentEntry(stub, undefined, provider)).rejects.toThrow(
+      ManifestGetError
+    );
+  });
+});
+
+describe('resolveComponentEntry (split/ref format)', () => {
+  // Provider that serves the per-component service files referenced from the index.
+  const provider = vi.fn(async (_req: Request | undefined, path: string) => {
+    switch (path) {
+      case './services/core/docgen/button.json':
+        return JSON.stringify({
+          components: {
+            button: {
+              id: 'button',
+              name: 'Button',
+              path: 'src/Button.tsx',
+              jsDocTags: {},
+              reactComponentMeta: {
+                props: { label: { type: { name: 'string' }, required: true } },
+              },
+              // argTypes must be dropped by the adapter.
+              argTypes: { label: { control: 'text' } },
+            },
+          },
+        });
+      case './services/core/story-docs/button.json':
+        return JSON.stringify({
+          components: {
+            button: {
+              id: 'button',
+              name: 'Button',
+              path: 'src/Button.tsx',
+              import: "import { Button } from './Button'",
+              stories: {
+                'button--primary': {
+                  id: 'button--primary',
+                  name: 'Primary',
+                  snippet: '<Button />',
+                },
+              },
+            },
+          },
+        });
+      case './services/addon-docs/mdx/button.json':
+        return JSON.stringify({
+          components: {
+            button: {
+              id: 'button',
+              name: 'Button',
+              docs: {
+                'button--docs': {
+                  id: 'button--docs',
+                  name: 'Docs',
+                  title: 'Button',
+                  content: '# Button',
+                },
+              },
+            },
+          },
+        });
+      default:
+        throw new ManifestGetError(`unexpected path ${path}`);
+    }
+  });
+
+  beforeEach(() => {
+    provider.mockClear();
+  });
+
+  const indexEntry: ComponentManifestV1 = {
+    id: 'button',
+    name: 'Button',
+    summary: 'A button',
+    docgen: { $ref: '../services/core/docgen/button.json#/components/button' },
+    stories: { $ref: '../services/core/story-docs/button.json#/components/button' },
+    docs: {
+      'button--docs': {
+        id: 'button--docs',
+        name: 'Docs',
+        mdx: {
+          $ref: '../services/addon-docs/mdx/button.json#/components/button/docs/button--docs',
+        },
+      },
+    },
+  };
+
+  it('follows docgen, story-docs and mdx refs and adapts to the internal shape', async () => {
+    const resolved = await resolveComponentEntry(indexEntry, undefined, provider);
+
+    // docgen: reactComponentMeta passed through, argTypes dropped.
+    expect(resolved.reactComponentMeta).toEqual({
+      props: { label: { type: { name: 'string' }, required: true } },
+    });
+    expect('argTypes' in resolved).toBe(false);
+    expect(resolved.path).toBe('src/Button.tsx');
+    // story-docs record -> Story[]
+    expect(resolved.stories).toEqual([
+      { id: 'button--primary', name: 'Primary', snippet: '<Button />' },
+    ]);
+    expect(resolved.import).toBe("import { Button } from './Button'");
+    // mdx ref row -> resolved Doc
+    expect(resolved.docs?.['button--docs']).toEqual({
+      id: 'button--docs',
+      name: 'Docs',
+      title: 'Button',
+      content: '# Button',
+    });
+    // identity from the index entry is authoritative
+    expect(resolved.id).toBe('button');
+  });
+
+  it('returns inline (v0) entries unchanged without calling the provider', async () => {
+    const inline: ComponentManifest = {
+      id: 'button',
+      name: 'Button',
+      stories: [{ name: 'Primary', snippet: '<Button />' }],
+    };
+    const localProvider = vi.fn();
+    await expect(resolveComponentEntry(inline, undefined, localProvider)).resolves.toBe(inline);
+    expect(localProvider).not.toHaveBeenCalled();
+  });
+
+  it('resolveComponentStories follows only the stories ref', async () => {
+    const resolved = await resolveComponentStories(indexEntry, undefined, provider);
+    expect(resolved.stories).toEqual([
+      { id: 'button--primary', name: 'Primary', snippet: '<Button />' },
+    ]);
+    // Only the story-docs file is fetched (not docgen/mdx).
+    expect(provider).toHaveBeenCalledTimes(1);
+    expect(provider).toHaveBeenCalledWith(
+      undefined,
+      './services/core/story-docs/button.json',
+      undefined
+    );
+  });
+
+  it('resolveDoc follows a standalone doc mdx ref', async () => {
+    const docRow: DocV1 = {
+      id: 'button--docs',
+      name: 'Docs',
+      mdx: { $ref: '../services/addon-docs/mdx/button.json#/components/button/docs/button--docs' },
+    };
+    const resolved = await resolveDoc(docRow, undefined, provider);
+    expect(resolved).toEqual({
+      id: 'button--docs',
+      name: 'Docs',
+      title: 'Button',
+      content: '# Button',
+    });
+  });
+
+  it('resolveDoc returns inline docs unchanged', async () => {
+    const inlineDoc: Doc = { id: 'intro', name: 'Intro', title: 'Intro', content: '# Hi' };
+    const localProvider = vi.fn();
+    await expect(resolveDoc(inlineDoc, undefined, localProvider)).resolves.toBe(inlineDoc);
+    expect(localProvider).not.toHaveBeenCalled();
+  });
+});
+
+describe('validating referenced payloads', () => {
+  /** Serves an index whose refs are honoured, and one ref target of the caller's choosing. */
+  const providerServing = (refBody: unknown) => async (_request: unknown, path: string) =>
+    path.includes('services') ? JSON.stringify(refBody) : '{}';
+
+  it('rejects a docgen payload that is not a record', async () => {
+    const component: ComponentManifestV1 = {
+      id: 'button',
+      name: 'Button',
+      docgen: { $ref: '../services/core/docgen/button.json#/components/button' },
+    };
+
+    await expect(
+      resolveComponentEntry(component, undefined, providerServing({ components: { button: [] } }))
+    ).rejects.toThrow(ManifestGetError);
+  });
+
+  it('rejects a story-docs payload whose stories are a string', async () => {
+    const component: ComponentManifestV1 = {
+      id: 'button',
+      name: 'Button',
+      stories: { $ref: '../services/core/story-docs/button.json#/components/button' },
+    };
+
+    await expect(
+      resolveComponentStories(
+        component,
+        undefined,
+        providerServing({ components: { button: { stories: 'Primary' } } })
+      )
+    ).rejects.toThrow(ManifestGetError);
+  });
+
+  it('accepts story-docs whose stories are a record, which is what core emits', async () => {
+    const component: ComponentManifestV1 = {
+      id: 'button',
+      name: 'Button',
+      stories: { $ref: '../services/core/story-docs/button.json#/components/button' },
+    };
+
+    const resolved = await resolveComponentStories(
+      component,
+      undefined,
+      providerServing({
+        components: { button: { stories: { 'button--primary': { name: 'Primary' } } } },
+      })
+    );
+
+    expect(resolved.stories).toEqual([{ name: 'Primary' }]);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/access-service.test.ts b/code/core/src/shared/open-service/toolsets/docs/access-service.test.ts
new file mode 100644
index 000000000000..574783f721d8
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/access-service.test.ts
@@ -0,0 +1,327 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { IndexEntry, StoryIndex } from 'storybook/internal/types';
+
+import {
+  OpenServiceDocgenMissingComponentError,
+  OpenServiceMissingServiceError,
+} from '../../../../server-errors.ts';
+import type { ToolsetGetService } from '../../toolset-definition.ts';
+import { createServiceDocsAccess } from './access-service.ts';
+
+const storyEntry = (id: string, name: string, tags: string[]): IndexEntry => ({
+  type: 'story',
+  subtype: 'story',
+  id,
+  name,
+  title: id.split('--')[0],
+  importPath: `./${id.split('--')[0]}.stories.tsx`,
+  tags,
+});
+
+const docsEntry = (id: string, name: string, tags: string[], storiesImports: string[]) => ({
+  type: 'docs' as const,
+  id,
+  name,
+  title: id.split('--')[0],
+  importPath: `./${id.split('--')[0]}.mdx`,
+  storiesImports,
+  tags,
+});
+
+// Deliberately not alphabetical: `zebra` before `alpha` proves component ids keep index order.
+const fullIndex: StoryIndex = {
+  v: 5,
+  entries: {
+    'zebra--primary': storyEntry('zebra--primary', 'Primary', ['manifest', 'dev']),
+    'alpha--primary': storyEntry('alpha--primary', 'Primary', ['manifest']),
+    'alpha--secondary': storyEntry('alpha--secondary', 'Secondary', ['manifest']),
+    'untagged--primary': storyEntry('untagged--primary', 'Primary', ['dev']),
+    'alpha--docs': docsEntry(
+      'alpha--docs',
+      'Alpha docs',
+      ['manifest', 'attached-mdx'],
+      ['./alpha.stories.tsx']
+    ),
+    'only-docs--docs': docsEntry(
+      'only-docs--docs',
+      'Only docs',
+      ['manifest', 'attached-mdx'],
+      ['./only-docs.stories.tsx']
+    ),
+    'guide--docs': docsEntry('guide--docs', 'Guide', ['manifest', 'unattached-mdx'], []),
+    'untagged--docs': docsEntry('untagged--docs', 'Untagged', ['unattached-mdx'], []),
+  },
+};
+
+const zebraDocgen = {
+  id: 'zebra',
+  name: 'Zebra',
+  path: './zebra.tsx',
+  description: 'Striped',
+  summary: 'A zebra',
+  jsDocTags: {},
+};
+const alphaDocgen = { id: 'alpha', name: 'Alpha', path: './alpha.tsx', jsDocTags: {} };
+const alphaStoryDocs = {
+  id: 'alpha',
+  name: 'Alpha',
+  path: './alpha.stories.tsx',
+  import: "import { Alpha } from './alpha'",
+  stories: {
+    'alpha--primary': { id: 'alpha--primary', name: 'Primary', snippet: '<Alpha />' },
+    'alpha--secondary': { id: 'alpha--secondary', name: 'Secondary' },
+  },
+};
+const zebraStoryDocs = {
+  id: 'zebra',
+  name: 'Zebra',
+  path: './zebra.stories.tsx',
+  stories: { 'zebra--primary': { id: 'zebra--primary', name: 'Primary' } },
+};
+const alphaMdx = {
+  id: 'alpha',
+  name: 'Alpha',
+  docs: {
+    'alpha--docs': { id: 'alpha--docs', name: 'Alpha docs', content: '# Alpha', summary: 'Alpha!' },
+  },
+};
+const onlyDocsMdx = {
+  id: 'only-docs',
+  name: 'Only docs',
+  docs: { 'only-docs--docs': { id: 'only-docs--docs', name: 'Only docs', content: '# Only' } },
+};
+const guideMdx = {
+  id: 'guide--docs',
+  name: 'Guide',
+  docs: {
+    'guide--docs': {
+      id: 'guide--docs',
+      name: 'Guide',
+      title: 'Getting started',
+      content: '# Guide',
+      summary: 'Intro',
+    },
+  },
+};
+
+const docgenForAllComponents = vi.fn();
+const docgen = vi.fn();
+const storyDocs = vi.fn();
+const mdxForAllComponents = vi.fn();
+const mdxForComponent = vi.fn();
+
+const services: Record<string, unknown> = {
+  'core/docgen': {
+    queries: {
+      docgenForAllComponents: { loaded: docgenForAllComponents },
+      docgen: { loaded: docgen },
+    },
+  },
+  'core/story-docs': { queries: { storyDocs: { loaded: storyDocs } } },
+  'addon-docs/mdx': {
+    queries: {
+      mdxForAllComponents: { loaded: mdxForAllComponents },
+      mdxForComponent: { loaded: mdxForComponent },
+    },
+  },
+};
+
+let index: StoryIndex;
+let mdxAvailable: boolean;
+let getService: ToolsetGetService;
+
+const createAccess = () =>
+  createServiceDocsAccess({
+    storyIndex: { getIndex: async () => index },
+    getService,
+  });
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  index = fullIndex;
+  mdxAvailable = true;
+  getService = vi.fn((id: string) => {
+    if (id === 'addon-docs/mdx' && !mdxAvailable) {
+      throw new OpenServiceMissingServiceError({ serviceId: 'addon-docs/mdx' });
+    }
+    return services[id];
+  }) as ToolsetGetService;
+
+  docgenForAllComponents.mockResolvedValue({ zebra: zebraDocgen, alpha: alphaDocgen });
+  mdxForAllComponents.mockResolvedValue({ 'guide--docs': guideMdx });
+  // The real per-id loads reject for ids with no component entry in the index.
+  const componentPayloads: Record<string, Record<string, unknown>> = {
+    alpha: alphaStoryDocs,
+    zebra: zebraStoryDocs,
+  };
+  storyDocs.mockImplementation(async ({ id }: { id: string }) => {
+    if (!componentPayloads[id]) {
+      throw new OpenServiceDocgenMissingComponentError({ id });
+    }
+    return componentPayloads[id];
+  });
+  docgen.mockImplementation(async ({ id }: { id: string }) => {
+    if (id === 'alpha') {
+      return alphaDocgen;
+    }
+    if (id === 'zebra') {
+      return zebraDocgen;
+    }
+    throw new OpenServiceDocgenMissingComponentError({ id });
+  });
+  mdxForComponent.mockImplementation(async ({ id }: { id: string }) => {
+    const payloads: Record<string, unknown> = {
+      alpha: alphaMdx,
+      'only-docs': onlyDocsMdx,
+      'guide--docs': guideMdx,
+    };
+    return payloads[id];
+  });
+});
+
+describe('createServiceDocsAccess list', () => {
+  it('lists manifest-tagged components in story-index order', async () => {
+    const manifests = await createAccess().list({ withStoryIds: false });
+
+    expect(Object.keys(manifests.componentManifest.components)).toEqual([
+      'zebra',
+      'alpha',
+      'only-docs',
+    ]);
+    expect(manifests.componentManifest.components.zebra).toEqual({
+      id: 'zebra',
+      name: 'Zebra',
+      description: 'Striped',
+      summary: 'A zebra',
+    });
+    // No docgen payload yet: the id stands in for the name.
+    expect(manifests.componentManifest.components['only-docs']).toEqual({
+      id: 'only-docs',
+      name: 'only-docs',
+    });
+  });
+
+  it('omits untagged entries from both manifests', async () => {
+    const manifests = await createAccess().list({ withStoryIds: false });
+
+    expect(manifests.componentManifest.components).not.toHaveProperty('untagged');
+    expect(manifests.docsManifest?.docs).not.toHaveProperty('untagged--docs');
+  });
+
+  it('skips story-docs entirely when story ids are not requested', async () => {
+    const manifests = await createAccess().list({ withStoryIds: false });
+
+    expect(storyDocs).not.toHaveBeenCalled();
+    expect(manifests.componentManifest.components.alpha).not.toHaveProperty('stories');
+  });
+
+  it('resolves story ids per component id when they are requested', async () => {
+    const manifests = await createAccess().list({ withStoryIds: true });
+
+    expect(manifests.componentManifest.components.alpha?.stories).toEqual([
+      { id: 'alpha--primary', name: 'Primary', snippet: '<Alpha />' },
+      { id: 'alpha--secondary', name: 'Secondary' },
+    ]);
+    expect(storyDocs).toHaveBeenCalledWith({ id: 'alpha' });
+    expect(storyDocs).toHaveBeenCalledWith({ id: 'zebra' });
+    // A docs-only component has no stories to resolve.
+    expect(storyDocs).not.toHaveBeenCalledWith({ id: 'only-docs' });
+    expect(manifests.componentManifest.components['only-docs']).not.toHaveProperty('stories');
+  });
+
+  it('names standalone docs from the index and summarizes them from MDX', async () => {
+    const manifests = await createAccess().list({ withStoryIds: false });
+
+    expect(manifests.docsManifest).toEqual({
+      v: 1,
+      docs: { 'guide--docs': { id: 'guide--docs', name: 'Guide', summary: 'Intro' } },
+    });
+  });
+
+  it('still lists standalone docs when the MDX service is not registered', async () => {
+    mdxAvailable = false;
+
+    const manifests = await createAccess().list({ withStoryIds: false });
+
+    expect(manifests.docsManifest).toEqual({
+      v: 1,
+      docs: { 'guide--docs': { id: 'guide--docs', name: 'Guide' } },
+    });
+  });
+
+  it('omits the docs manifest, and the MDX load, when there are no standalone docs', async () => {
+    index = {
+      v: 5,
+      entries: { 'alpha--primary': fullIndex.entries['alpha--primary'] },
+    };
+
+    const manifests = await createAccess().list({ withStoryIds: false });
+
+    expect(manifests.docsManifest).toBeUndefined();
+    expect(mdxForAllComponents).not.toHaveBeenCalled();
+  });
+});
+
+describe('createServiceDocsAccess resolve', () => {
+  it('assembles a component from docgen, story docs, and attached MDX', async () => {
+    const entry = await createAccess().resolve('alpha');
+
+    expect(entry).toMatchObject({
+      kind: 'component',
+      component: {
+        id: 'alpha',
+        name: 'Alpha',
+        import: "import { Alpha } from './alpha'",
+        stories: [
+          { id: 'alpha--primary', name: 'Primary', snippet: '<Alpha />' },
+          { id: 'alpha--secondary', name: 'Secondary' },
+        ],
+        docs: { 'alpha--docs': { id: 'alpha--docs', content: '# Alpha' } },
+      },
+    });
+    expect(docgen).toHaveBeenCalledWith({ id: 'alpha' });
+    expect(mdxForAllComponents).not.toHaveBeenCalled();
+  });
+
+  it('resolves a component whose payloads are absent, falling back to the id', async () => {
+    const entry = await createAccess().resolve('only-docs');
+
+    expect(entry).toMatchObject({
+      kind: 'component',
+      component: {
+        id: 'only-docs',
+        name: 'only-docs',
+        docs: { 'only-docs--docs': { id: 'only-docs--docs', content: '# Only' } },
+      },
+    });
+  });
+
+  it('resolves a standalone docs entry', async () => {
+    const entry = await createAccess().resolve('guide--docs');
+
+    expect(entry).toEqual({
+      kind: 'doc',
+      doc: {
+        id: 'guide--docs',
+        name: 'Guide',
+        title: 'Getting started',
+        content: '# Guide',
+        summary: 'Intro',
+      },
+    });
+  });
+
+  it('returns undefined for ids the index does not know, without touching the services', async () => {
+    await expect(createAccess().resolve('nope')).resolves.toBeUndefined();
+    expect(docgen).not.toHaveBeenCalled();
+    expect(storyDocs).not.toHaveBeenCalled();
+    expect(mdxForComponent).not.toHaveBeenCalled();
+  });
+
+  it('returns undefined for a standalone doc whose MDX service is not registered', async () => {
+    mdxAvailable = false;
+
+    await expect(createAccess().resolve('guide--docs')).resolves.toBeUndefined();
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/classify-services.test.ts b/code/core/src/shared/open-service/toolsets/docs/classify-services.test.ts
deleted file mode 100644
index 434762a8746d..000000000000
--- a/code/core/src/shared/open-service/toolsets/docs/classify-services.test.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { classifyServices } from './classify-services.ts';
-
-const storyDocsPayload = {
-  id: 'button',
-  name: 'Button',
-  path: './Button.stories.tsx',
-  stories: {
-    'button--primary': {
-      id: 'button--primary',
-      name: 'Primary',
-    },
-  },
-};
-
-const attachedMdxPayload = {
-  id: 'button',
-  name: 'Button',
-  docs: {
-    'button--docs': {
-      id: 'button--docs',
-      name: 'Docs',
-    },
-  },
-};
-
-const unattachedMdxPayload = {
-  id: 'introduction',
-  name: 'Introduction',
-  docs: {
-    introduction: {
-      id: 'introduction',
-      name: 'Introduction',
-    },
-  },
-};
-
-describe('classifyServices', () => {
-  it('uses service aggregate keys as the visibility source of truth', () => {
-    const classification = classifyServices({
-      allDocgen: {
-        'docgen-only': {
-          id: 'docgen-only',
-          name: 'Docgen only',
-          path: './DocgenOnly.tsx',
-          jsDocTags: {},
-        },
-      },
-      allStoryDocs: {},
-      allMdx: {},
-    });
-
-    expect(classification.componentIds).toEqual(['docgen-only']);
-    expect(classification.storyBasedIds).toEqual(new Set());
-  });
-
-  it('derives components and attached versus unattached docs from service payloads', () => {
-    const classification = classifyServices({
-      allDocgen: {
-        button: {
-          id: 'button',
-          name: 'Button',
-          path: './Button.tsx',
-          jsDocTags: {},
-        },
-      },
-      allStoryDocs: { button: storyDocsPayload },
-      allMdx: {
-        button: attachedMdxPayload,
-        introduction: unattachedMdxPayload,
-      },
-    });
-
-    expect(classification).toEqual({
-      componentIds: ['button'],
-      storyBasedIds: new Set(['button']),
-      unattachedDocs: new Map([['introduction', 'Introduction']]),
-      attachedDocsByComponent: new Map([['button', ['button--docs']]]),
-    });
-  });
-});
diff --git a/code/core/src/shared/open-service/toolsets/docs/classify-services.ts b/code/core/src/shared/open-service/toolsets/docs/classify-services.ts
index b09926764554..5d7b020da2bc 100644
--- a/code/core/src/shared/open-service/toolsets/docs/classify-services.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/classify-services.ts
@@ -1,9 +1,13 @@
-import type { DocgenPayload } from '../../services/docgen/types.ts';
-import type { StoryDocsPayload } from '../../services/story-docs/types.ts';
-import type { MdxPayload } from './map.ts';
-
+/**
+ * How `createServiceDocsAccess` sees a project's documentable entries.
+ *
+ * Derived from the story index filtered by the manifest tag, not from the docgen and story-docs
+ * aggregates: the index is what decides which components a Storybook publishes, and it carries
+ * their order. Classifying from the aggregates instead would list components the project does not
+ * expose, and alphabetise what the sidebar deliberately does not.
+ */
 export type DocsClassification = {
-  /** Component ids present in docgen and/or story-docs aggregates. */
+  /** Component ids the story index publishes, in index order. */
   componentIds: string[];
   /** Component ids backed by a story-docs payload. */
   storyBasedIds: Set<string>;
@@ -12,41 +16,3 @@ export type DocsClassification = {
   /** Attached MDX docs ids grouped by owning component id. */
   attachedDocsByComponent: Map<string, string[]>;
 };
-
-/**
- * Visibility intentionally follows composed service payloads because this API has no story-index
- * dependency with which to reapply manifest filtering.
- */
-export function classifyServices({
-  allDocgen,
-  allStoryDocs,
-  allMdx,
-}: {
-  allDocgen: Record<string, DocgenPayload | undefined>;
-  allStoryDocs: Record<string, StoryDocsPayload | undefined>;
-  allMdx: Record<string, MdxPayload | undefined>;
-}): DocsClassification {
-  const storyBasedIds = new Set(Object.keys(allStoryDocs));
-  const unattachedDocs = new Map<string, string>();
-  const attachedDocsByComponent = new Map<string, string[]>();
-  const componentIds = new Set([...Object.keys(allDocgen), ...Object.keys(allStoryDocs)]);
-
-  for (const [id, payload] of Object.entries(allMdx)) {
-    if (!payload) {
-      continue;
-    }
-    if (payload.docs[id]) {
-      unattachedDocs.set(id, payload.docs[id].name);
-      continue;
-    }
-    componentIds.add(id);
-    attachedDocsByComponent.set(id, Object.keys(payload.docs));
-  }
-
-  return {
-    componentIds: [...componentIds].sort(),
-    storyBasedIds,
-    unattachedDocs,
-    attachedDocsByComponent,
-  };
-}
diff --git a/code/core/src/shared/open-service/toolsets/docs/definition.test.ts b/code/core/src/shared/open-service/toolsets/docs/definition.test.ts
index 4f1f945a283d..3bab17ac6f8c 100644
--- a/code/core/src/shared/open-service/toolsets/docs/definition.test.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/definition.test.ts
@@ -1,243 +1,196 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import * as v from 'valibot';
+import { describe, expect, it } from 'vitest';
 
-import {
-  OpenServiceDocgenMissingComponentError,
-  OpenServiceMissingServiceError,
-} from '../../../../server-errors.ts';
 import type { ToolsetCtx } from '../../toolset-definition.ts';
-import { docsToolset } from './definition.ts';
-
-const docgenForAllComponents = vi.fn();
-const storyDocsForAllComponents = vi.fn();
-const mdxForAllComponents = vi.fn();
-const docgen = vi.fn();
-const storyDocs = vi.fn();
-const mdxForComponent = vi.fn();
-
-const services = {
-  'core/docgen': {
-    queries: {
-      docgenForAllComponents: { loaded: docgenForAllComponents },
-      docgen: { loaded: docgen },
-    },
-  },
-  'core/story-docs': {
-    queries: {
-      storyDocsForAllComponents: { loaded: storyDocsForAllComponents },
-      storyDocs: { loaded: storyDocs },
-    },
-  },
-  'addon-docs/mdx': {
-    queries: {
-      mdxForAllComponents: { loaded: mdxForAllComponents },
-      mdxForComponent: { loaded: mdxForComponent },
-    },
-  },
+import type { DocsAccess } from './access.ts';
+import { createDocsToolset } from './definition.ts';
+
+const button = {
+  id: 'button',
+  name: 'Button',
+  description: 'Click me',
+  summary: 'A button',
+  stories: [{ id: 'button--primary', name: 'Primary', snippet: '<Button />' }],
+  import: "import { Button } from './Button'",
 };
 
-let ctx: ToolsetCtx;
-let mdxAvailable: boolean;
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  mdxAvailable = true;
-  ctx = {
-    consumer: 'cli',
-    origin: 'http://localhost:6006',
-    format: 'markdown',
-    getService: vi.fn((id) => {
-      if (id === 'addon-docs/mdx' && !mdxAvailable) {
-        throw new OpenServiceMissingServiceError({ serviceId: 'addon-docs/mdx' });
-      }
-      return services[id as keyof typeof services];
-    }) as ToolsetCtx['getService'],
-  };
-  const buttonDocgen = {
-    id: 'button',
-    name: 'Button',
-    path: './Button.tsx',
-    description: 'Click me',
-    summary: 'A button',
-    jsDocTags: {},
-  };
-  const buttonStoryDocs = {
-    id: 'button',
-    name: 'Button',
-    path: './Button.stories.tsx',
-    import: "import { Button } from './Button'",
-    stories: {
-      'button--primary': {
-        id: 'button--primary',
-        name: 'Primary',
-        snippet: '<Button />',
-      },
-    },
-  };
-  const guideMdx = {
-    id: 'guide--docs',
-    name: 'Guide',
-    docs: {
-      'guide--docs': {
-        id: 'guide--docs',
-        name: 'Guide',
-        path: './Guide.mdx',
-        title: 'Getting started',
-        summary: 'Intro',
+const guide = { id: 'guide--docs', name: 'Guide', summary: 'How to' };
+
+/** Fake access: the seam exists precisely so the toolset is testable without services. */
+const docsAccess: DocsAccess = {
+  list: async ({ withStoryIds }) => ({
+    componentManifest: {
+      v: 1,
+      components: {
+        button: {
+          id: 'button',
+          name: 'Button',
+          summary: 'A button',
+          ...(withStoryIds ? { stories: button.stories } : {}),
+        },
       },
     },
-  };
-  docgenForAllComponents.mockResolvedValue({ button: buttonDocgen });
-  storyDocsForAllComponents.mockResolvedValue({ button: buttonStoryDocs });
-  mdxForAllComponents.mockResolvedValue({ 'guide--docs': guideMdx });
-  // Per-id component loads throw when the id has no component entry, like the real
-  // extraction service — standalone docs ids and unknown ids both hit that path.
-  docgen.mockImplementation(async ({ id }: { id: string }) => {
-    if (id !== 'button') {
-      throw new OpenServiceDocgenMissingComponentError({ id });
+    docsManifest: { v: 1, docs: { 'guide--docs': guide } },
+  }),
+  resolve: async (id) => {
+    if (id === 'button') {
+      return { kind: 'component', component: button };
     }
-    return buttonDocgen;
-  });
-  storyDocs.mockImplementation(async ({ id }: { id: string }) => {
-    if (id !== 'button') {
-      throw new OpenServiceDocgenMissingComponentError({ id });
+    if (id === 'guide--docs') {
+      return { kind: 'doc', doc: guide };
     }
-    return buttonStoryDocs;
+    return undefined;
+  },
+};
+
+const toolset = createDocsToolset({ docsAccess });
+
+const mcpCtx: ToolsetCtx = { consumer: 'mcp', getService: () => ({}) as never };
+const cliCtx: ToolsetCtx = { consumer: 'cli', getService: () => ({}) as never };
+
+describe('docs.list', () => {
+  it('returns the manifests from the access and renders the list Markdown', async () => {
+    const outcome = await toolset.methods.list.handler({ withStoryIds: false }, mcpCtx);
+
+    expect(outcome.ok).toBe(true);
+    expect(Object.keys(outcome.data.manifests!.componentManifest.components)).toEqual(['button']);
+    expect(outcome.markdown).toContain('button');
+    expect(outcome.markdown).toContain('Guide');
+    expect(outcome.markdown).not.toContain('button--primary');
+  });
+
+  it('includes story ids only when requested', async () => {
+    const outcome = await toolset.methods.list.handler({ withStoryIds: true }, mcpCtx);
+
+    expect(outcome.markdown).toContain('button--primary');
+  });
+
+  it('cross-references the show tool per consumer in its description', () => {
+    const describe_ = toolset.methods.list.description;
+    const resolved = typeof describe_ === 'function' ? describe_(mcpCtx) : describe_;
+    const resolvedCli = typeof describe_ === 'function' ? describe_(cliCtx) : describe_;
+
+    expect(resolved).toContain('get-documentation');
+    expect(resolvedCli).toContain('npx storybook tools docs show');
   });
-  mdxForComponent.mockImplementation(async ({ id }: { id: string }) =>
-    id === 'guide--docs' ? guideMdx : undefined
-  );
 });
 
-describe('docs API', () => {
-  it('returns the MCP list Markdown by default after loading services through context', async () => {
-    await expect(
-      docsToolset.methods.list.handler(
-        v.parse(docsToolset.methods.list.schema, { withStoryIds: true }),
-        ctx
-      )
-    ).resolves.toBe(
-      [
-        '# Components',
-        '',
-        '- Button (button): A button',
-        '  - Primary (button--primary)',
-        '',
-        '# Docs',
-        '',
-        '- Guide (guide--docs): Intro',
-      ].join('\n')
-    );
-    expect(ctx.getService).toHaveBeenCalledWith('core/docgen', { internal: true });
-    expect(ctx.getService).toHaveBeenCalledWith('core/story-docs', { internal: true });
-    expect(ctx.getService).toHaveBeenCalledWith('addon-docs/mdx', { internal: true });
+describe('docs.show', () => {
+  it('renders component documentation for a known component id', async () => {
+    const outcome = await toolset.methods.show.handler({ id: 'button' }, mcpCtx);
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data.entry?.kind).toBe('component');
+    expect(outcome.markdown).toContain('Button');
   });
 
-  it('returns structured JSON when the adapter requests it', async () => {
-    ctx.format = 'json';
-    await expect(
-      docsToolset.methods.list.handler(
-        v.parse(docsToolset.methods.list.schema, { withStoryIds: true }),
-        ctx
-      )
-    ).resolves.toEqual({
-      components: [
-        {
-          id: 'button',
-          name: 'Button',
-          summary: 'A button',
-          storyIds: ['button--primary'],
-        },
-      ],
-      docs: [{ id: 'guide--docs', name: 'Guide', title: 'Getting started', summary: 'Intro' }],
-    });
+  it('renders standalone docs entries', async () => {
+    const outcome = await toolset.methods.show.handler({ id: 'guide--docs' }, mcpCtx);
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data.entry?.kind).toBe('doc');
+    expect(outcome.markdown).toContain('Guide');
   });
 
-  it('shows component and story documentation via per-id loaders', async () => {
-    await expect(
-      docsToolset.methods.show.handler(
-        v.parse(docsToolset.methods.show.schema, { id: 'button' }),
-        ctx
-      )
-    ).resolves.toContain('Button');
-    expect(docgen).toHaveBeenCalledWith({ id: 'button' });
-    expect(storyDocs).toHaveBeenCalledWith({ id: 'button' });
-
-    await expect(
-      docsToolset.methods.showStory.handler(
-        v.parse(docsToolset.methods.showStory.schema, {
-          componentId: 'button',
-          storyName: 'Primary',
-        }),
-        ctx
-      )
-    ).resolves.toBe(
-      [
-        '# Button - Primary',
-        '',
-        '```',
-        "import { Button } from './Button'",
-        '',
-        '<Button />',
-        '```',
-      ].join('\n')
+  it('answers unknown ids with a failure carrying the @storybook/mcp miss message', async () => {
+    const outcome = await toolset.methods.show.handler({ id: 'nope' }, mcpCtx);
+
+    expect(outcome.ok).toBe(false);
+    expect(outcome.data.entry).toBeUndefined();
+    expect(outcome.markdown).toBe(
+      'Component or Docs Entry not found: "nope". Use the list-all-documentation tool to see available components and documentation entries.'
     );
-    expect(storyDocs).toHaveBeenCalledWith({ id: 'button' });
-    expect(mdxForAllComponents).not.toHaveBeenCalled();
+
+    const cliOutcome = await toolset.methods.show.handler({ id: 'nope' }, cliCtx);
+    expect(cliOutcome.markdown).toBe('Component or Docs Entry not found: "nope".');
   });
+});
+
+describe('docs.showStory', () => {
+  it('renders the story documentation for a known story name', async () => {
+    const outcome = await toolset.methods.showStory.handler(
+      {
+        componentId: 'button',
+        storyName: 'Primary',
+      },
+      mcpCtx
+    );
 
-  it('returns the existing not-found result for unknown ids', async () => {
-    ctx.format = 'json';
-    await expect(
-      docsToolset.methods.show.handler(
-        v.parse(docsToolset.methods.show.schema, { id: 'missing' }),
-        ctx
-      )
-    ).resolves.toEqual({ kind: 'not-found', id: 'missing' });
+    expect(outcome.ok).toBe(true);
+    expect(outcome.markdown).toContain('<Button />');
   });
 
-  it('shows a standalone docs entry, whose id has no component payloads', async () => {
-    ctx.format = 'json';
+  it('lists available stories in a failure when the story name misses', async () => {
+    const outcome = await toolset.methods.showStory.handler(
+      {
+        componentId: 'button',
+        storyName: 'Missing',
+      },
+      mcpCtx
+    );
 
-    await expect(
-      docsToolset.methods.show.handler(
-        v.parse(docsToolset.methods.show.schema, { id: 'guide--docs' }),
-        ctx
-      )
-    ).resolves.toMatchObject({ kind: 'docs', id: 'guide--docs' });
+    expect(outcome.ok).toBe(false);
+    expect(outcome.markdown).toBe(
+      'Story "Missing" not found for component "button". Available stories: Primary'
+    );
   });
 
-  it('mirrors the @storybook/mcp miss messages for the MCP consumer', async () => {
-    ctx.consumer = 'mcp';
+  it('answers unknown components with the miss message per consumer', async () => {
+    const outcome = await toolset.methods.showStory.handler(
+      {
+        componentId: 'nope',
+        storyName: 'Primary',
+      },
+      mcpCtx
+    );
 
-    await expect(
-      docsToolset.methods.show.handler(
-        v.parse(docsToolset.methods.show.schema, { id: 'missing' }),
-        ctx
-      )
-    ).resolves.toBe(
-      'Component or Docs Entry not found: "missing". Use the list-all-documentation tool to see available components and documentation entries.'
+    expect(outcome.ok).toBe(false);
+    expect(outcome.markdown).toBe(
+      'Component not found: "nope". Use the list-all-documentation tool to see available components.'
     );
 
-    await expect(
-      docsToolset.methods.showStory.handler(
-        v.parse(docsToolset.methods.showStory.schema, { componentId: 'missing', storyName: 'X' }),
-        ctx
-      )
-    ).resolves.toBe(
-      'Component not found: "missing". Use the list-all-documentation tool to see available components.'
+    const cliOutcome = await toolset.methods.showStory.handler(
+      { componentId: 'nope', storyName: 'Primary' },
+      cliCtx
     );
+    expect(cliOutcome.markdown).toBe('Component not found: "nope".');
+  });
+});
+
+describe('usage reporting', () => {
+  /** Runs a method the way a consumer does; the handler reports usage inline. */
+  async function run(methodName: 'list' | 'show', input: unknown, consumer: 'cli' | 'mcp') {
+    const events: Array<[string, Record<string, unknown>]> = [];
+    const ctx: ToolsetCtx = {
+      consumer,
+      getService: () => ({}) as never,
+      telemetry: async (event, payload) => {
+        events.push([event, payload]);
+      },
+    };
+
+    await toolset.methods[methodName].handler(input as never, ctx);
+
+    return events;
+  }
+
+  it.each(['cli', 'mcp'] as const)('reports a listing on %s', async (consumer) => {
+    const [[event, payload] = []] = await run('list', { withStoryIds: false }, consumer);
+
+    expect(event).toBe('tool:listAllDocumentation');
+    expect(payload).toMatchObject({ componentCount: 1, docsCount: 1 });
+    expect(payload!.resultTokenCount).toBeGreaterThan(0);
+  });
+
+  it.each(['cli', 'mcp'] as const)('reports a lookup on %s', async (consumer) => {
+    const [[event, payload] = []] = await run('show', { id: 'button' }, consumer);
+
+    expect(event).toBe('tool:getDocumentation');
+    expect(payload).toMatchObject({ componentId: 'button', found: true });
   });
 
-  it('continues without MDX when the optional service is unavailable', async () => {
-    ctx.format = 'json';
-    mdxAvailable = false;
+  it('reports a miss as not found', async () => {
+    const [[, payload] = []] = await run('show', { id: 'nope' }, 'mcp');
 
-    await expect(
-      docsToolset.methods.list.handler(v.parse(docsToolset.methods.list.schema, {}), ctx)
-    ).resolves.toEqual({
-      components: [{ id: 'button', name: 'Button', summary: 'A button' }],
-      docs: [],
-    });
+    expect(payload).toMatchObject({ componentId: 'nope', found: false });
   });
 });
diff --git a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.test.ts b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.test.ts
new file mode 100644
index 000000000000..1efda14df1eb
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.test.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { adaptCoreComponent, adaptCoreDoc, adaptCoreStories } from './adapt-core-manifest.ts';
+import type { CoreDocgenComponent } from './adapt-core-manifest.ts';
+
+describe('adaptCoreStories', () => {
+  it('maps a story-docs record into a Story[]', () => {
+    expect(
+      adaptCoreStories({
+        'button--primary': { id: 'button--primary', name: 'Primary', snippet: '<Button />' },
+        'button--secondary': { id: 'button--secondary', name: 'Secondary' },
+      })
+    ).toEqual([
+      { id: 'button--primary', name: 'Primary', snippet: '<Button />' },
+      { id: 'button--secondary', name: 'Secondary' },
+    ]);
+  });
+
+  it('returns an already-resolved array unchanged', () => {
+    const stories = [{ name: 'Primary', snippet: '<Button />' }];
+    expect(adaptCoreStories(stories)).toBe(stories);
+  });
+
+  it('returns undefined when there are no stories', () => {
+    expect(adaptCoreStories(undefined)).toBeUndefined();
+  });
+});
+
+describe('adaptCoreDoc', () => {
+  it('keeps optional fields when present and omits them otherwise', () => {
+    expect(
+      adaptCoreDoc({ id: 'intro', name: 'Intro', title: 'Introduction', content: '# Hi' })
+    ).toEqual({ id: 'intro', name: 'Intro', title: 'Introduction', content: '# Hi' });
+
+    expect(adaptCoreDoc({ id: 'intro', name: 'Intro' })).toEqual({ id: 'intro', name: 'Intro' });
+  });
+});
+
+describe('adaptCoreComponent', () => {
+  it('passes reactComponentMeta through and drops argTypes', () => {
+    const core: CoreDocgenComponent = {
+      id: 'button',
+      name: 'Button',
+      path: 'src/Button.tsx',
+      reactComponentMeta: { props: { label: { type: { name: 'string' }, required: true } } },
+      argTypes: { label: { control: 'text' } },
+    };
+
+    const result = adaptCoreComponent(core);
+
+    expect(result.reactComponentMeta).toEqual(core.reactComponentMeta);
+    expect('argTypes' in result).toBe(false);
+    expect(result.path).toBe('src/Button.tsx');
+  });
+
+  it('maps the story-docs record and attached docs into the internal shape', () => {
+    const core: CoreDocgenComponent = {
+      id: 'button',
+      name: 'Button',
+      stories: {
+        'button--primary': { id: 'button--primary', name: 'Primary', snippet: '<Button />' },
+      },
+      import: "import { Button } from './Button'",
+      docs: {
+        'button--docs': { id: 'button--docs', name: 'Docs', title: 'Button', content: '# Button' },
+      },
+    };
+
+    const result = adaptCoreComponent(core);
+
+    expect(result.stories).toEqual([
+      { id: 'button--primary', name: 'Primary', snippet: '<Button />' },
+    ]);
+    expect(result.import).toBe("import { Button } from './Button'");
+    expect(result.docs).toEqual({
+      'button--docs': { id: 'button--docs', name: 'Docs', title: 'Button', content: '# Button' },
+    });
+  });
+
+  it('keeps subcomponents (incl. their reactComponentMeta) intact', () => {
+    const core: CoreDocgenComponent = {
+      id: 'button',
+      name: 'Button',
+      subcomponents: {
+        Icon: { name: 'Icon', path: 'src/Icon.tsx', reactComponentMeta: { props: {} } },
+      },
+    };
+
+    const result = adaptCoreComponent(core);
+    expect(result.subcomponents).toEqual(core.subcomponents);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.ts b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.ts
index ceeb40cb66ae..4deffbde43b1 100644
--- a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/adapt-core-manifest.ts
@@ -5,11 +5,7 @@ import type { ComponentManifest, Doc, Story } from './manifest-types.ts';
 
 /**
  * Adapts the `experimentalDocgenServer` open-service payloads into the manifest formatter's
- * {@link ComponentManifest}/{@link Doc} shapes. Verbatim port of `@storybook/mcp`'s
- * `packages/mcp/src/utils/adapt-core-manifest.ts` (which bridges the same formats for the addon's
- * in-process `resolveEntry` hook); the copies must not drift until Milestone 4 deletes the
- * original. Deviation: the source declares structural `Core*` stand-in types to avoid importing
- * Storybook core — here the real service payload types are used directly.
+ * {@link ComponentManifest}/{@link Doc} shapes.
  *
  * Only `argTypes` is dropped: prop types still come from `reactComponentMeta` and
  * the `react*` docgen-engine fields, which are passed through unchanged.
diff --git a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/manifest-types.ts b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/manifest-types.ts
index cccd11f03f07..abefa2a2d376 100644
--- a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/manifest-types.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/manifest-types.ts
@@ -1,91 +1,166 @@
 /**
- * Structural port of the manifest types consumed by the `@storybook/mcp` manifest formatter
- * (`packages/mcp/src/types.ts`). The source defines these as valibot schemas because it validates
- * fetched manifests; here they type in-process data only, so the inferred shapes are ported as
- * plain types. Both copies must not drift until Milestone 4 deletes the original.
+ * The component/docs manifest format, as schemas.
+ *
+ * Storybook writes one of two formats, distinguished by the top-level `v` field on
+ * `components.json` / `docs.json`:
+ *
+ * - v0 — inline/legacy: every component carries its docgen, stories array and attached docs (with
+ *   MDX `content`) inline.
+ * - v1 — split/ref: the manifests are shallow indexes; the heavy docgen, story-docs and MDX
+ *   payloads live in sibling `services/*.json` files and are referenced via `$ref`. The in-process
+ *   dev index emits an even shallower v1 (no `docgen`/`mdx` refs), because those entries are
+ *   resolved from the open services instead.
+ *
+ * These are valibot schemas rather than plain types because manifests fetched from a hosted
+ * Storybook are untrusted input and are validated on arrival. In-process callers build the same
+ * shapes directly and skip validation; the `$ref` fields are optional, so an in-process row is a
+ * valid instance of the same type.
  */
 
-export type ManifestError = {
-  name: string;
-  message: string;
-};
+import * as v from 'valibot';
 
-export type Story = {
-  name: string;
-  description?: string;
-  jsDocTags?: Record<string, string[]>;
-  error?: ManifestError;
-  id?: string;
-  snippet?: string;
-  summary?: string;
-};
+const JSDocTag = v.record(v.string(), v.array(v.string()));
 
-/** Inline (v0) docs entry: the full MDX `content` is embedded. */
-export type DocV0 = {
-  id: string;
-  name: string;
-  title?: string;
-  path?: string;
-  content?: string;
-  summary?: string;
-  error?: ManifestError;
-};
+const ManifestErrorSchema = v.object({
+  name: v.string(),
+  message: v.string(),
+});
+export type ManifestError = v.InferOutput<typeof ManifestErrorSchema>;
+
+const BaseManifest = v.object({
+  name: v.string(),
+  description: v.optional(v.string()),
+  jsDocTags: v.optional(JSDocTag),
+  error: v.optional(ManifestErrorSchema),
+});
+
+const StorySchema = v.object({
+  ...BaseManifest.entries,
+  id: v.optional(v.string()),
+  snippet: v.optional(v.string()),
+  summary: v.optional(v.string()),
+});
+export type Story = v.InferOutput<typeof StorySchema>;
 
 /**
- * Shallow (v1) docs entry. Storybook's in-process dev index carries just identity and summary;
- * the full MDX payload is resolved separately.
+ * A JSON Reference (`{ $ref }`) pointing at a value in another manifest document. Used by the v1
+ * (split/ref) format for docgen, story-docs and MDX payloads.
  */
-export type DocV1 = {
-  id: string;
-  name: string;
-  summary?: string;
-  error?: ManifestError;
-};
+export const JsonRef = v.object({
+  $ref: v.string(),
+});
+export type JsonRef = v.InferOutput<typeof JsonRef>;
 
-/* eslint-disable @typescript-eslint/no-explicit-any -- mirrors the source schema's `v.any()`
-   docgen-engine fields, which the parsers narrow structurally at runtime. */
-type BaseInlineComponentProperties = {
-  name: string;
-  description?: string;
-  jsDocTags?: Record<string, string[]>;
-  error?: ManifestError;
-  path?: string;
-  summary?: string;
-  import?: string;
-  reactDocgen?: any;
-  reactDocgenTypescript?: any;
-  reactComponentMeta?: any;
-};
-/* eslint-enable @typescript-eslint/no-explicit-any */
+// ---- v0: inline / legacy ----
+
+/** Inline (v0) docs entry: the full MDX `content` is embedded. */
+export const DocV0 = v.object({
+  id: v.string(),
+  name: v.string(),
+  title: v.optional(v.string()),
+  path: v.optional(v.string()),
+  content: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  error: v.optional(ManifestErrorSchema),
+});
+export type DocV0 = v.InferOutput<typeof DocV0>;
 
-export type SubcomponentManifest = BaseInlineComponentProperties;
+const BaseInlineComponentProperties = v.object({
+  ...BaseManifest.entries,
+  path: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  import: v.optional(v.string()),
+  // Mirrors the docgen-engine payloads, which the parsers narrow structurally at runtime.
+  reactDocgen: v.optional(v.any()),
+  reactDocgenTypescript: v.optional(v.any()),
+  reactComponentMeta: v.optional(v.any()),
+});
+
+export const SubcomponentManifest = v.object({
+  ...BaseInlineComponentProperties.entries,
+});
+export type SubcomponentManifest = v.InferOutput<typeof SubcomponentManifest>;
 
 /** Inline (v0) component: docgen, stories and attached docs are all embedded. */
-export type ComponentManifestV0 = BaseInlineComponentProperties & {
-  id: string;
-  stories?: Story[];
-  subcomponents?: Record<string, SubcomponentManifest>;
-  docs?: Record<string, DocV0>;
-};
+export const ComponentManifestV0 = v.object({
+  ...BaseInlineComponentProperties.entries,
+  id: v.string(),
+  stories: v.optional(v.array(StorySchema)),
+  subcomponents: v.optional(v.record(v.string(), SubcomponentManifest)),
+  docs: v.optional(v.record(v.string(), DocV0)),
+});
+export type ComponentManifestV0 = v.InferOutput<typeof ComponentManifestV0>;
 
-/** Shallow (v1) component index row: identity + summary inlined for cheap listing. */
-export type ComponentManifestV1 = {
-  id: string;
-  name: string;
-  description?: string;
-  summary?: string;
-  error?: ManifestError;
-  /** Inline stories, present when the list is built with story ids resolved. */
-  stories?: Story[];
-};
+export const ComponentManifestMapV0 = v.object({
+  v: v.literal(0),
+  components: v.record(v.string(), ComponentManifestV0),
+});
+export type ComponentManifestMapV0 = v.InferOutput<typeof ComponentManifestMapV0>;
+
+export const DocsManifestMapV0 = v.object({
+  v: v.literal(0),
+  docs: v.record(v.string(), DocV0),
+});
+export type DocsManifestMapV0 = v.InferOutput<typeof DocsManifestMapV0>;
+
+// ---- v1: split / ref ----
+
+/**
+ * Shallow (v1) docs entry. The full MDX payload lives behind `mdx.$ref`; `mdx` is optional because
+ * the in-process dev index omits it.
+ */
+export const DocV1 = v.object({
+  id: v.string(),
+  name: v.string(),
+  summary: v.optional(v.string()),
+  mdx: v.optional(JsonRef),
+  error: v.optional(ManifestErrorSchema),
+});
+export type DocV1 = v.InferOutput<typeof DocV1>;
+
+/**
+ * Shallow (v1) component index row. Identity and summary are inlined for cheap listing; docgen and
+ * story-docs live behind `$ref`s, attached docs behind nested `mdx.$ref`s. `stories` may also be an
+ * inline array, which is how a listing built with story ids resolved carries them.
+ */
+export const ComponentManifestV1 = v.object({
+  id: v.string(),
+  name: v.string(),
+  description: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  error: v.optional(ManifestErrorSchema),
+  docgen: v.optional(JsonRef),
+  stories: v.optional(v.union([JsonRef, v.array(StorySchema)])),
+  docs: v.optional(v.record(v.string(), DocV1)),
+});
+export type ComponentManifestV1 = v.InferOutput<typeof ComponentManifestV1>;
+
+export const ComponentManifestMapV1 = v.object({
+  v: v.literal(1),
+  components: v.record(v.string(), ComponentManifestV1),
+});
+export type ComponentManifestMapV1 = v.InferOutput<typeof ComponentManifestMapV1>;
+
+export const DocsManifestMapV1 = v.object({
+  v: v.literal(1),
+  docs: v.record(v.string(), DocV1),
+});
+export type DocsManifestMapV1 = v.InferOutput<typeof DocsManifestMapV1>;
+
+// ---- discriminated unions (the wire schema for top-level manifests) ----
+
+/** `components.json`, discriminated on `v` (0 = inline, 1 = split/ref). */
+export const ComponentManifestMap = v.variant('v', [
+  ComponentManifestMapV0,
+  ComponentManifestMapV1,
+]);
+export type ComponentManifestMap = v.InferOutput<typeof ComponentManifestMap>;
 
-export type ComponentManifestMap =
-  | { v: 0; components: Record<string, ComponentManifestV0> }
-  | { v: 1; components: Record<string, ComponentManifestV1> };
+/** `docs.json` for standalone documentation entries, discriminated on `v`. */
+export const DocsManifestMap = v.variant('v', [DocsManifestMapV0, DocsManifestMapV1]);
+export type DocsManifestMap = v.InferOutput<typeof DocsManifestMap>;
 
-export type DocsManifestMap =
-  | { v: 0; docs: Record<string, DocV0> }
-  | { v: 1; docs: Record<string, DocV1> };
+// ---- working / resolved types ----
 
 /** A component index row as it appears in either format. */
 export type ComponentManifestEntry = ComponentManifestV0 | ComponentManifestV1;
@@ -95,7 +170,8 @@ export type DocEntry = DocV0 | DocV1;
 
 /**
  * A fully-resolved component, as consumed by the formatters: inline shape (stories as an array,
- * attached docs with `content`, docgen inlined). Identical to the v0 shape.
+ * attached docs with `content`, docgen inlined). Identical to the v0 shape — v1 rows reach it by
+ * following their `$ref`s, or by being built in-process from the open services.
  */
 export type ComponentManifest = ComponentManifestV0;
 
diff --git a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.test.ts b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.test.ts
index 657e7a4720a4..caa5d42fd5d9 100644
--- a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.test.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.test.ts
@@ -1,11 +1,12 @@
-// Ported verbatim from `@storybook/mcp`'s manifest-formatter tests
-// (`packages/mcp/src/utils/manifest-formatter/markdown.test.ts`): the parity suite binding the MCP
-// consumer's Markdown output to this port until Milestone 4 deletes the original. The
-// multi-source describe block is omitted along with its formatter.
+// The parity suite binding the Markdown every docs-tool consumer receives.
 import { describe, it, expect } from 'vitest';
 import type { AllManifests, ComponentManifest, ComponentManifestMap } from './manifest-types.ts';
 import fullManifestFixture from './full-manifest.fixture.json' with { type: 'json' };
-import { formatComponentManifest, formatManifestsToLists } from './markdown.ts';
+import {
+  formatComponentManifest,
+  formatManifestsToLists,
+  formatMultiSourceManifestsToLists,
+} from './markdown.ts';
 
 describe('MarkdownFormatter - formatComponentManifest', () => {
   it('formats all full fixtures', () => {
@@ -1485,3 +1486,28 @@ describe('MarkdownFormatter - formatManifestsToLists', () => {
     });
   });
 });
+
+describe('MarkdownFormatter - formatMultiSourceManifestsToLists', () => {
+  it('formats requires-own-mcp source notices without an error prefix', () => {
+    const result = formatMultiSourceManifestsToLists([
+      {
+        source: { id: 'tetra', title: 'Tetra Design System', url: 'https://tetra.chromatic.com' },
+        notice: {
+          kind: 'requires-own-mcp',
+          endpoint: 'https://tetra.chromatic.com/mcp',
+        },
+      },
+    ]);
+
+    expect(result).toMatchInlineSnapshot(`
+			"# Tetra Design System
+			id: tetra
+
+			This composed Storybook is private and cannot be read through the local Storybook MCP proxy.
+
+			Use this source's own MCP endpoint instead:
+			https://tetra.chromatic.com/mcp"
+		`);
+    expect(result).not.toContain('error:');
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.ts b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.ts
index 9f153b741efa..2da7e516039c 100644
--- a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/markdown.ts
@@ -1,12 +1,10 @@
 /**
- * Verbatim port of the `@storybook/mcp` manifest formatter
- * (`packages/mcp/src/utils/manifest-formatter/markdown.ts`). Milestone 4 swaps addon-mcp onto the
- * docs toolset with byte-identical output, so the two copies must not drift until it deletes the
- * original. Omitted: `formatMultiSourceManifestsToLists` (multi-source composition has no core
- * counterpart). `dedent` comes from `ts-dedent`, the package the source vendors verbatim.
+ * Markdown rendering for the docs toolset: the text every consumer of the docs tools receives.
  */
 import { dedent } from 'ts-dedent';
 
+import { formatRequiresOwnMcpNotice, type SourceListing } from '../sources.ts';
+
 import { extractDocsSummary, MAX_SUMMARY_LENGTH } from './extract-docs-summary.ts';
 import type {
   AllManifests,
@@ -364,6 +362,65 @@ export function formatManifestsToLists(
   return parts.join('\n').trim();
 }
 
+/**
+ * Formats one listing per composed source.
+ *
+ * Sources are grouped under their own heading rather than merged, because ids are only unique
+ * within a source and the follow-up tools take a `storybookId`. A source that failed or needs its
+ * own endpoint prints that in place of its listing, so the rest still reads.
+ */
+export function formatMultiSourceManifestsToLists(
+  sources: SourceListing[],
+  options: ListFormattingOptions = {}
+): string {
+  const parts: string[] = [];
+
+  for (const { source, manifests, error, notice } of sources) {
+    parts.push(`# ${source.title}`);
+    parts.push(`id: ${source.id}`);
+    parts.push('');
+
+    if (error) {
+      parts.push(`error: ${error}`);
+      parts.push('');
+      continue;
+    }
+
+    if (notice) {
+      parts.push(formatRequiresOwnMcpNotice(source, notice.endpoint, { includeHeader: false }));
+      parts.push('');
+      continue;
+    }
+
+    const components = Object.values(manifests?.componentManifest.components ?? {});
+    if (components.length > 0) {
+      parts.push('## Components');
+      parts.push('');
+      for (const component of components) {
+        parts.push(formatComponentLine(component));
+        if (options.withStoryIds && Array.isArray(component.stories)) {
+          for (const story of component.stories) {
+            parts.push(formatStorySubLine(story));
+          }
+        }
+      }
+      parts.push('');
+    }
+
+    const docs = Object.values(manifests?.docsManifest?.docs ?? {});
+    if (docs.length > 0) {
+      parts.push('## Docs');
+      parts.push('');
+      for (const doc of docs) {
+        parts.push(formatDocLine(doc));
+      }
+      parts.push('');
+    }
+  }
+
+  return parts.join('\n').trim();
+}
+
 /**
  * Format a single story's documentation.
  */
diff --git a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.test.ts b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.test.ts
new file mode 100644
index 000000000000..4afd2ce5c60c
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.test.ts
@@ -0,0 +1,462 @@
+import { describe, expect, test } from 'vitest';
+import {
+  parseReactDocgen as parseDocgen,
+  parseReactDocgenTypescript as parseDocgenTypescript,
+} from './parse-react-docgen.ts';
+
+/**
+ * The fixtures below are real `react-docgen` / `react-docgen-typescript` payloads, while the
+ * parsers are typed against the structural subset they actually read — so the literals carry
+ * fields (`computed`, `name`, nullable defaults) the parameter types don't declare. Widening here
+ * keeps the fixtures faithful to what the parsers receive in production.
+ */
+const parseReactDocgen = (input: unknown) =>
+  parseDocgen(input as Parameters<typeof parseDocgen>[0]);
+const parseReactDocgenTypescript = (input: unknown) =>
+  parseDocgenTypescript(input as Parameters<typeof parseDocgenTypescript>[0]);
+
+describe('parseReactDocgen', () => {
+  test('prefers raw over computed for unions (and copies default/required)', () => {
+    const result = parseReactDocgen({
+      props: {
+        size: {
+          description: 'Visual size',
+          required: false,
+          defaultValue: { value: '"md"', computed: false },
+          tsType: {
+            name: 'union',
+            raw: '"sm" | "md" | "lg"',
+            elements: [
+              { name: 'literal', value: '"sm"' },
+              { name: 'literal', value: '"md"' },
+              { name: 'literal', value: '"lg"' },
+            ],
+          },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "size": {
+            "defaultValue": ""md"",
+            "description": "Visual size",
+            "required": false,
+            "type": ""sm" | "md" | "lg"",
+          },
+        },
+      }
+    `);
+  });
+
+  test('serializes union when raw is missing', () => {
+    const result = parseReactDocgen({
+      props: {
+        tone: {
+          description: 'Semantic tone',
+          required: false,
+          tsType: {
+            name: 'union',
+            elements: [
+              { name: 'literal', value: '"primary"' },
+              { name: 'literal', value: '"secondary"' },
+            ],
+          },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "tone": {
+            "defaultValue": undefined,
+            "description": "Semantic tone",
+            "required": false,
+            "type": ""primary" | "secondary"",
+          },
+        },
+      }
+    `);
+  });
+
+  test('serializes intersection', () => {
+    const result = parseReactDocgen({
+      props: {
+        options: {
+          tsType: {
+            name: 'intersection',
+            elements: [
+              {
+                name: 'Record',
+                elements: [{ name: 'string' }, { name: 'number' }],
+              },
+              {
+                name: 'signature',
+                type: 'object',
+                signature: {
+                  properties: [{ key: 'a', value: { name: 'string', required: true } }],
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "options": {
+            "defaultValue": undefined,
+            "description": undefined,
+            "required": undefined,
+            "type": "Record<string, number> & { a: string }",
+          },
+        },
+      }
+    `);
+  });
+
+  test('serializes Array fallback as T[]', () => {
+    const result = parseReactDocgen({
+      props: {
+        tags: {
+          tsType: { name: 'Array', elements: [{ name: 'string' }] },
+          defaultValue: { value: '[]', computed: false },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "tags": {
+            "defaultValue": "[]",
+            "description": undefined,
+            "required": undefined,
+            "type": "string[]",
+          },
+        },
+      }
+    `);
+  });
+
+  test('serializes tuple', () => {
+    const result = parseReactDocgen({
+      props: {
+        anchor: {
+          tsType: {
+            name: 'tuple',
+            elements: [{ name: 'literal', value: '"x"' }, { name: 'number' }],
+          },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "anchor": {
+            "defaultValue": undefined,
+            "description": undefined,
+            "required": undefined,
+            "type": "["x", number]",
+          },
+        },
+      }
+    `);
+  });
+
+  test('serializes literal', () => {
+    const result = parseReactDocgen({
+      props: {
+        variant: {
+          tsType: { name: 'literal', value: '"solid"' },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "variant": {
+            "defaultValue": undefined,
+            "description": undefined,
+            "required": undefined,
+            "type": ""solid"",
+          },
+        },
+      }
+    `);
+  });
+
+  test('serializes function signature', () => {
+    const result = parseReactDocgen({
+      props: {
+        onClick: {
+          description: 'Click handler',
+          tsType: {
+            name: 'signature',
+            type: 'function',
+            signature: {
+              arguments: [{ name: 'ev', type: { name: 'MouseEvent' } }],
+              return: { name: 'void' },
+            },
+          },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "onClick": {
+            "defaultValue": undefined,
+            "description": "Click handler",
+            "required": undefined,
+            "type": "(ev: MouseEvent) => void",
+          },
+        },
+      }
+    `);
+  });
+
+  test('serializes object signature with required and optional properties', () => {
+    const result = parseReactDocgen({
+      props: {
+        asKind: {
+          tsType: {
+            name: 'signature',
+            type: 'object',
+            signature: {
+              properties: [
+                {
+                  key: 'kind',
+                  value: { name: 'literal', value: '"button"', required: true },
+                },
+                {
+                  key: 'type',
+                  value: {
+                    name: 'union',
+                    raw: '"button" | "submit" | "reset"',
+                    required: false,
+                  },
+                },
+              ],
+            },
+          },
+          defaultValue: {
+            value: '{ kind: "button", type: "button" }',
+            computed: false,
+          },
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "asKind": {
+            "defaultValue": "{ kind: "button", type: "button" }",
+            "description": undefined,
+            "required": undefined,
+            "type": "{ kind: "button"; type?: "button" | "submit" | "reset" }",
+          },
+        },
+      }
+    `);
+  });
+
+  test('generic type serialization and bare names', () => {
+    const result = parseReactDocgen({
+      props: {
+        items: {
+          tsType: {
+            name: 'Array',
+            elements: [{ name: 'Item', elements: [{ name: 'TMeta' }] }],
+          },
+        },
+        children: { tsType: { name: 'ReactNode' } },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "children": {
+            "defaultValue": undefined,
+            "description": undefined,
+            "required": undefined,
+            "type": "ReactNode",
+          },
+          "items": {
+            "defaultValue": undefined,
+            "description": undefined,
+            "required": undefined,
+            "type": "Item<TMeta>[]",
+          },
+        },
+      }
+    `);
+  });
+
+  test('handles undefined tsType and defaultValue null', () => {
+    const result = parseReactDocgen({
+      props: {
+        icon: {
+          tsType: undefined,
+          defaultValue: { value: null, computed: false },
+          required: true,
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "props": {
+          "icon": {
+            "defaultValue": null,
+            "description": undefined,
+            "required": true,
+            "type": undefined,
+          },
+        },
+      }
+    `);
+  });
+});
+
+describe('parseReactDocgenTypescript', () => {
+  test('parses basic props with type.name', () => {
+    const result = parseReactDocgenTypescript({
+      displayName: 'Button',
+      filePath: 'src/Button.tsx',
+      description: 'A button component',
+      methods: [],
+      props: {
+        label: {
+          name: 'label',
+          description: 'The button label',
+          type: { name: 'string' },
+          defaultValue: null,
+          required: true,
+        },
+        disabled: {
+          name: 'disabled',
+          description: 'Whether the button is disabled',
+          type: { name: 'boolean' },
+          defaultValue: { value: 'false' },
+          required: false,
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+			{
+			  "props": {
+			    "disabled": {
+			      "defaultValue": "false",
+			      "description": "Whether the button is disabled",
+			      "required": false,
+			      "type": "boolean",
+			    },
+			    "label": {
+			      "defaultValue": undefined,
+			      "description": "The button label",
+			      "required": true,
+			      "type": "string",
+			    },
+			  },
+			}
+		`);
+  });
+
+  test('prefers type.raw over type.name for enums', () => {
+    const result = parseReactDocgenTypescript({
+      displayName: 'Button',
+      filePath: 'src/Button.tsx',
+      description: '',
+      methods: [],
+      props: {
+        variant: {
+          name: 'variant',
+          description: 'The variant',
+          type: {
+            name: 'enum',
+            raw: '"primary" | "secondary" | "danger"',
+            value: [{ value: '"primary"' }, { value: '"secondary"' }, { value: '"danger"' }],
+          },
+          defaultValue: { value: 'primary' },
+          required: false,
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+			{
+			  "props": {
+			    "variant": {
+			      "defaultValue": "primary",
+			      "description": "The variant",
+			      "required": false,
+			      "type": ""primary" | "secondary" | "danger"",
+			    },
+			  },
+			}
+		`);
+  });
+
+  test('falls back to type.name when type.raw is not present', () => {
+    const result = parseReactDocgenTypescript({
+      displayName: 'Callback',
+      filePath: 'src/Callback.tsx',
+      description: '',
+      methods: [],
+      props: {
+        onClick: {
+          name: 'onClick',
+          description: 'Click handler',
+          type: { name: '(event: MouseEvent) => void' },
+          defaultValue: null,
+          required: true,
+        },
+      },
+    });
+    expect(result).toMatchInlineSnapshot(`
+			{
+			  "props": {
+			    "onClick": {
+			      "defaultValue": undefined,
+			      "description": "Click handler",
+			      "required": true,
+			      "type": "(event: MouseEvent) => void",
+			    },
+			  },
+			}
+		`);
+  });
+
+  test('handles empty description as undefined', () => {
+    const result = parseReactDocgenTypescript({
+      displayName: 'Box',
+      filePath: 'src/Box.tsx',
+      description: '',
+      methods: [],
+      props: {
+        children: {
+          name: 'children',
+          description: '',
+          type: { name: 'ReactNode' },
+          defaultValue: null,
+          required: false,
+        },
+      },
+    });
+    expect(result.props.children!.description).toBeUndefined();
+  });
+
+  test('handles empty props object', () => {
+    const result = parseReactDocgenTypescript({
+      displayName: 'Empty',
+      filePath: 'src/Empty.tsx',
+      description: '',
+      methods: [],
+      props: {},
+    });
+    expect(result).toMatchInlineSnapshot(`
+			{
+			  "props": {},
+			}
+		`);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.ts b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.ts
index dbeddaa24d16..7366c9887304 100644
--- a/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/manifest-formatter/parse-react-docgen.ts
@@ -1,8 +1,8 @@
 /**
- * Verbatim port of `@storybook/mcp`'s `packages/mcp/src/utils/parse-react-docgen.ts`. Both copies
- * must not drift until Milestone 4 deletes the original. Deviation: core does not depend on
- * `react-docgen` / `react-docgen-typescript`, so the type-only imports are replaced with the
- * structural subsets the parsers actually read.
+ * The single implementation of react-docgen prop parsing, shared by the dev server and the hosted
+ * `@storybook/mcp` package, which bundles this entry. Core does not depend on `react-docgen` /
+ * `react-docgen-typescript`, so the type-only imports are the structural subsets the parsers
+ * actually read rather than those packages' own types.
  */
 
 /** Structural subset of react-docgen's `tsType` / `type` prop descriptor field. */
diff --git a/code/core/src/shared/open-service/toolsets/docs/map-with-concurrency.ts b/code/core/src/shared/open-service/toolsets/docs/map-with-concurrency.ts
new file mode 100644
index 000000000000..62e286496848
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/map-with-concurrency.ts
@@ -0,0 +1,27 @@
+/** Maps `items` with at most `limit` concurrent in-flight `fn` calls. */
+export async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  // Guard against a non-finite `limit` (e.g. NaN), which would otherwise make `concurrency` NaN
+  // and spawn zero workers, leaving results unfilled.
+  const safeLimit = Number.isFinite(limit) ? limit : items.length;
+  const concurrency = Math.max(1, Math.min(safeLimit, items.length));
+  const results = Array<R>(items.length);
+  let nextIndex = 0;
+
+  async function worker(): Promise<void> {
+    while (nextIndex < items.length) {
+      const index = nextIndex++;
+      results[index] = await fn(items[index]!, index);
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, () => worker()));
+  return results;
+}
diff --git a/code/core/src/shared/open-service/toolsets/docs/map.test.ts b/code/core/src/shared/open-service/toolsets/docs/map.test.ts
deleted file mode 100644
index 22c59ab9b926..000000000000
--- a/code/core/src/shared/open-service/toolsets/docs/map.test.ts
+++ /dev/null
@@ -1,126 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { mapDocsList, mapDocsShow, mapDocsShowStory } from './map.ts';
-
-describe('mapDocsList', () => {
-  it('lists components and optional story ids', () => {
-    const result = mapDocsList({
-      classification: {
-        componentIds: ['button'],
-        storyBasedIds: new Set(['button']),
-        attachedDocsByComponent: new Map(),
-        unattachedDocs: new Map([['guide--docs', 'Guide']]),
-      },
-      allDocgen: {
-        button: {
-          id: 'button',
-          name: 'Button',
-          path: './Button.tsx',
-          summary: 'A button',
-          jsDocTags: {},
-        },
-      },
-      allStoryDocs: {
-        button: {
-          id: 'button',
-          name: 'Button',
-          path: './Button.stories.tsx',
-          stories: {
-            'button--primary': { id: 'button--primary', name: 'Primary' },
-          },
-        },
-      },
-      allMdx: {
-        'guide--docs': {
-          id: 'guide--docs',
-          name: 'Guide',
-          docs: {
-            'guide--docs': {
-              id: 'guide--docs',
-              name: 'Guide',
-              title: 'Getting started',
-              summary: 'Intro',
-            },
-          },
-        },
-      },
-      withStoryIds: true,
-    });
-
-    expect(result).toEqual({
-      components: [
-        { id: 'button', name: 'Button', summary: 'A button', storyIds: ['button--primary'] },
-      ],
-      docs: [{ id: 'guide--docs', name: 'Guide', title: 'Getting started', summary: 'Intro' }],
-    });
-  });
-});
-
-describe('mapDocsShow / mapDocsShowStory', () => {
-  it('maps component docs and story lookup outcomes', () => {
-    const show = mapDocsShow({
-      id: 'button',
-      classification: {
-        componentIds: ['button'],
-        storyBasedIds: new Set(['button']),
-        attachedDocsByComponent: new Map(),
-        unattachedDocs: new Map(),
-      },
-      docgen: {
-        id: 'button',
-        name: 'Button',
-        path: './Button.tsx',
-        description: 'Click me',
-        jsDocTags: {},
-      },
-      storyDocs: {
-        id: 'button',
-        name: 'Button',
-        path: './Button.stories.tsx',
-        import: "import { Button } from './Button'",
-        stories: {
-          'button--primary': {
-            id: 'button--primary',
-            name: 'Primary',
-            snippet: '<Button />',
-          },
-        },
-      },
-    });
-
-    expect(show).toMatchObject({
-      kind: 'component',
-      id: 'button',
-      name: 'Button',
-      import: "import { Button } from './Button'",
-      stories: [{ id: 'button--primary', name: 'Primary', snippet: '<Button />' }],
-    });
-
-    expect(mapDocsShowStory({ componentId: 'button', storyName: 'Primary', show })).toMatchObject({
-      kind: 'story',
-      component: { id: 'button', name: 'Button' },
-      story: { name: 'Primary' },
-    });
-
-    expect(mapDocsShowStory({ componentId: 'button', storyName: 'Missing', show })).toEqual({
-      kind: 'story-not-found',
-      componentId: 'button',
-      storyName: 'Missing',
-      availableStoryNames: ['Primary'],
-    });
-  });
-
-  it('returns not-found for unknown ids', () => {
-    expect(
-      mapDocsShow({
-        id: 'missing',
-        classification: {
-          componentIds: [],
-          storyBasedIds: new Set(),
-          attachedDocsByComponent: new Map(),
-          unattachedDocs: new Map(),
-        },
-      })
-    ).toEqual({ kind: 'not-found', id: 'missing' });
-  });
-});
diff --git a/code/core/src/shared/open-service/toolsets/docs/map.ts b/code/core/src/shared/open-service/toolsets/docs/map.ts
index 6c1fa9aa3563..d653d8bdb03a 100644
--- a/code/core/src/shared/open-service/toolsets/docs/map.ts
+++ b/code/core/src/shared/open-service/toolsets/docs/map.ts
@@ -1,5 +1,3 @@
-import type { DocgenPayload } from '../../services/docgen/types.ts';
-import type { StoryDocsPayload } from '../../services/story-docs/types.ts';
 import type { DocsClassification } from './classify-services.ts';
 
 export type MdxDoc = {
@@ -42,247 +40,3 @@ export function selectAttachedDocs(
   }
   return docs;
 }
-
-export type DocsListResult = {
-  components: Array<{
-    id: string;
-    name: string;
-    summary?: string;
-    storyIds?: string[];
-  }>;
-  docs: Array<{
-    id: string;
-    name: string;
-    title?: string;
-    summary?: string;
-  }>;
-};
-
-export type DocsShowResult =
-  | {
-      kind: 'component';
-      id: string;
-      name: string;
-      path?: string;
-      description?: string;
-      summary?: string;
-      import?: string;
-      jsDocTags?: Record<string, string[]>;
-      reactDocgen?: unknown;
-      reactDocgenTypescript?: unknown;
-      reactComponentMeta?: unknown;
-      stories?: Array<{
-        id?: string;
-        name: string;
-        description?: string;
-        summary?: string;
-        snippet?: string;
-        error?: { name: string; message: string };
-      }>;
-      subcomponents?: Record<string, unknown>;
-      docs?: Record<string, MdxDoc>;
-      error?: { name: string; message: string };
-    }
-  | {
-      kind: 'docs';
-      id: string;
-      name: string;
-      title?: string;
-      path?: string;
-      content?: string;
-      summary?: string;
-      error?: { name: string; message: string };
-    }
-  | { kind: 'not-found'; id: string };
-
-export type DocsShowStoryResult =
-  | {
-      kind: 'story';
-      component: { id: string; name: string; import?: string };
-      story: {
-        id?: string;
-        name: string;
-        description?: string;
-        summary?: string;
-        snippet?: string;
-        error?: { name: string; message: string };
-      };
-    }
-  | { kind: 'component-not-found'; componentId: string }
-  | {
-      kind: 'story-not-found';
-      componentId: string;
-      storyName: string;
-      availableStoryNames: string[];
-    };
-
-function summaryOf(item: { summary?: string; description?: string }): string | undefined {
-  return item.summary ?? item.description;
-}
-
-/** Builds the transport-neutral `docs.list` payload from settled dependency data. */
-export function mapDocsList(params: {
-  classification: DocsClassification;
-  allDocgen: Record<string, DocgenPayload | undefined>;
-  allStoryDocs: Record<string, StoryDocsPayload | undefined>;
-  allMdx: Record<string, MdxPayload | undefined>;
-  withStoryIds: boolean;
-}): DocsListResult {
-  const { classification, allDocgen, allStoryDocs, allMdx, withStoryIds } = params;
-
-  const components = classification.componentIds.map((id) => {
-    const payload = allDocgen[id];
-    const component: DocsListResult['components'][number] = {
-      id,
-      name: payload?.name ?? id,
-    };
-    const summary = summaryOf(payload ?? {});
-    if (summary !== undefined) {
-      component.summary = summary;
-    }
-    if (withStoryIds && classification.storyBasedIds.has(id)) {
-      const stories = allStoryDocs[id]?.stories;
-      component.storyIds = stories
-        ? Object.values(stories)
-            .map((story) => story.id)
-            .filter((storyId): storyId is string => typeof storyId === 'string')
-        : [];
-    }
-    return component;
-  });
-
-  const docs = [...classification.unattachedDocs.entries()].map(([docId, name]) => {
-    const payload = allMdx[docId]?.docs?.[docId];
-    const doc: DocsListResult['docs'][number] = {
-      id: docId,
-      name,
-    };
-    if (payload?.title !== undefined) {
-      doc.title = payload.title;
-    }
-    if (payload?.summary !== undefined) {
-      doc.summary = payload.summary;
-    }
-    return doc;
-  });
-
-  return { components, docs };
-}
-
-/** Maps story-docs entries to the transport-neutral story shape, omitting absent fields. */
-export function mapStoryDocsEntries(stories: NonNullable<StoryDocsPayload['stories']>) {
-  return Object.values(stories).map((story) => ({
-    ...(story.id !== undefined ? { id: story.id } : {}),
-    name: story.name,
-    ...(story.description !== undefined ? { description: story.description } : {}),
-    ...(story.summary !== undefined ? { summary: story.summary } : {}),
-    ...(story.snippet !== undefined ? { snippet: story.snippet } : {}),
-    ...(story.error !== undefined ? { error: story.error } : {}),
-  }));
-}
-
-/** A story-docs import statement wins over docgen's; either may be absent. */
-export function resolveImportStatement(
-  storyDocs?: StoryDocsPayload,
-  docgen?: DocgenPayload
-): string | undefined {
-  return typeof storyDocs?.import === 'string'
-    ? storyDocs.import
-    : typeof docgen?.import === 'string'
-      ? docgen.import
-      : undefined;
-}
-
-/** Builds the transport-neutral `docs.show` payload for one id. */
-export function mapDocsShow(params: {
-  id: string;
-  classification: DocsClassification;
-  docgen?: DocgenPayload;
-  storyDocs?: StoryDocsPayload;
-  mdx?: MdxPayload;
-}): DocsShowResult {
-  const { id, classification, docgen, storyDocs, mdx } = params;
-
-  if (classification.unattachedDocs.has(id)) {
-    const doc = mdx?.docs?.[id];
-    if (!doc) {
-      return { kind: 'not-found', id };
-    }
-    return {
-      kind: 'docs',
-      id: doc.id,
-      name: doc.name,
-      ...(doc.title !== undefined ? { title: doc.title } : {}),
-      ...(doc.path !== undefined ? { path: doc.path } : {}),
-      ...(doc.content !== undefined ? { content: doc.content } : {}),
-      ...(doc.summary !== undefined ? { summary: doc.summary } : {}),
-      ...(doc.error !== undefined ? { error: doc.error } : {}),
-    };
-  }
-
-  if (!classification.componentIds.includes(id)) {
-    return { kind: 'not-found', id };
-  }
-
-  const docs = selectAttachedDocs(classification, id, mdx);
-
-  const stories = storyDocs?.stories ? mapStoryDocsEntries(storyDocs.stories) : undefined;
-
-  const importStatement = resolveImportStatement(storyDocs, docgen);
-
-  return {
-    kind: 'component',
-    id,
-    name: docgen?.name ?? id,
-    ...(docgen?.path !== undefined ? { path: docgen.path } : {}),
-    ...(docgen?.description !== undefined ? { description: docgen.description } : {}),
-    ...(docgen?.summary !== undefined ? { summary: docgen.summary } : {}),
-    ...(importStatement !== undefined ? { import: importStatement } : {}),
-    ...(docgen?.jsDocTags !== undefined ? { jsDocTags: docgen.jsDocTags } : {}),
-    ...(docgen?.reactDocgen !== undefined ? { reactDocgen: docgen.reactDocgen } : {}),
-    ...(docgen?.reactDocgenTypescript !== undefined
-      ? { reactDocgenTypescript: docgen.reactDocgenTypescript }
-      : {}),
-    ...(docgen?.reactComponentMeta !== undefined
-      ? { reactComponentMeta: docgen.reactComponentMeta }
-      : {}),
-    ...(stories ? { stories } : {}),
-    ...(docgen?.subcomponents !== undefined ? { subcomponents: docgen.subcomponents } : {}),
-    ...(docs && Object.keys(docs).length > 0 ? { docs } : {}),
-    ...(docgen?.error !== undefined ? { error: docgen.error } : {}),
-  };
-}
-
-/** Builds the transport-neutral `docs.showStory` payload. */
-export function mapDocsShowStory(params: {
-  componentId: string;
-  storyName: string;
-  show: DocsShowResult;
-}): DocsShowStoryResult {
-  const { componentId, storyName, show } = params;
-
-  if (show.kind !== 'component') {
-    return { kind: 'component-not-found', componentId };
-  }
-
-  const stories = show.stories ?? [];
-  const story = stories.find((entry) => entry.name === storyName);
-  if (!story) {
-    return {
-      kind: 'story-not-found',
-      componentId,
-      storyName,
-      availableStoryNames: stories.map((entry) => entry.name),
-    };
-  }
-
-  return {
-    kind: 'story',
-    component: {
-      id: show.id,
-      name: show.name,
-      ...(show.import !== undefined ? { import: show.import } : {}),
-    },
-    story,
-  };
-}
diff --git a/code/core/src/shared/open-service/toolsets/docs/multi-source.test.ts b/code/core/src/shared/open-service/toolsets/docs/multi-source.test.ts
new file mode 100644
index 000000000000..fd8662542c90
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/multi-source.test.ts
@@ -0,0 +1,75 @@
+/**
+ * How a composition picks the access for each of its sources.
+ *
+ * The local Storybook is a source like any other, but it is the one this process can read directly.
+ * These tests pin that routing, so a composition cannot quietly grow a second way of reading the
+ * Storybook it is already serving.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import type { DocsAccess } from './access.ts';
+import { createCompositionDocsSources } from './multi-source.ts';
+
+const LOCAL = { id: 'local', title: 'Local' };
+const REMOTE = { id: 'design-system', title: 'Design System', url: 'https://ds.example.com' };
+
+/** Serves a minimal but valid pair of manifests, whatever path is asked for. */
+function providerStub() {
+  return vi.fn(async (_request: unknown, path: string) =>
+    path.endsWith('docs.json')
+      ? '{"v":1,"docs":{}}'
+      : '{"v":1,"components":{"a":{"id":"a","name":"A"}}}'
+  );
+}
+
+function accessStub(): DocsAccess {
+  return {
+    list: vi.fn().mockResolvedValue({ componentManifest: { v: 1, components: {} } }),
+    resolve: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('createCompositionDocsSources', () => {
+  it('reads the local source through the access it was given', async () => {
+    const localAccess = accessStub();
+    const manifestProvider = vi.fn();
+
+    const [local] = createCompositionDocsSources({
+      sources: [LOCAL],
+      localAccess,
+      manifestProvider,
+    });
+
+    await local!.access.list({ withStoryIds: false });
+
+    expect(localAccess.list).toHaveBeenCalled();
+    expect(manifestProvider).not.toHaveBeenCalled();
+  });
+
+  it('still fetches remote sources over the provider when a local access is given', async () => {
+    const localAccess = accessStub();
+    const manifestProvider = providerStub();
+
+    const sources = createCompositionDocsSources({
+      sources: [LOCAL, REMOTE],
+      localAccess,
+      manifestProvider,
+    });
+    const remote = sources.find(({ source }) => source.id === REMOTE.id)!;
+
+    await remote.access.list({ withStoryIds: false });
+
+    expect(manifestProvider).toHaveBeenCalled();
+    expect(localAccess.list).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the provider for the local source when no access is given', async () => {
+    const manifestProvider = providerStub();
+
+    const [local] = createCompositionDocsSources({ sources: [LOCAL], manifestProvider });
+    await local!.access.list({ withStoryIds: false });
+
+    expect(manifestProvider).toHaveBeenCalled();
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/portable-dist.test.ts b/code/core/src/shared/open-service/toolsets/docs/portable-dist.test.ts
new file mode 100644
index 000000000000..c2a0e876a01a
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/portable-dist.test.ts
@@ -0,0 +1,84 @@
+/**
+ * Guards the portable d.ts artifact of the `storybook/internal/toolsets-docs` entry.
+ *
+ * `@storybook/mcp` bundles this entry's declarations into its own dist through standard module
+ * resolution, so the artifact must be one flat self-contained file whose only external imports are
+ * on that package's own dependency list. An edit that entangles the entry with react, another core
+ * surface, or a shared type chunk must fail here — where the artifact is produced — with a message
+ * naming the offending import, not in a consumer's build.
+ *
+ * Deliberately reads the real built artifact (no memfs): the guarded property is what the build
+ * actually wrote to disk.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+const DTS_ARTIFACT = join(
+  import.meta.dirname,
+  '../../../../../dist/shared/open-service/toolsets/docs/public.d.ts'
+);
+
+/**
+ * The only module specifiers the flat file may reference.
+ *
+ * Deliberately a copy of the entry's `portable.external` in `build-config.ts`, not derived from
+ * it: every allowed import is a dependency each consumer must declare, so widening the list has to
+ * be a reviewer-visible edit here rather than something the config change passes silently.
+ */
+const IMPORT_ALLOWLIST = ['valibot'];
+
+/**
+ * Headroom over the current size (~64 KB), so ordinary edits pass but a bundling regression does
+ * not — the shared-chunk entanglement this pass exists to prevent once pulled in ~904 KB.
+ */
+const SIZE_BUDGET_BYTES = 100_000;
+
+/**
+ * Every syntactic position that references another module in a d.ts: static `from`, dynamic
+ * `import(...)` type references, `require(...)`, side-effect `import "..."`, and ambient
+ * `declare module "..."` augmentation.
+ */
+const MODULE_SPECIFIER_RE =
+  /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+|\bmodule\s+)["']([^"']+)["']/g;
+
+/**
+ * Triple-slash directives (`/// <reference types|path|lib="..." />`) pull in declarations outside
+ * the import syntax above, so their targets count as specifiers too: a `path` reference breaks
+ * flatness and a `types`/`lib` reference must pass the allowlist like any import.
+ */
+const REFERENCE_DIRECTIVE_RE = /^\/\/\/\s*<reference\s+(?:types|path|lib)\s*=\s*["']([^"']+)["']/gm;
+
+function readSpecifiers(): string[] {
+  const source = readFileSync(DTS_ARTIFACT, 'utf-8');
+  return [...source.matchAll(MODULE_SPECIFIER_RE), ...source.matchAll(REFERENCE_DIRECTIVE_RE)].map(
+    (match) => match[1]
+  );
+}
+
+/**
+ * The dist-reading assertions are skipped on a working copy that has not been production-built,
+ * which would make them pass vacuously in CI — where a build always precedes the tests. So there,
+ * the artifact's absence is the failure.
+ */
+const DTS_BUILT = existsSync(DTS_ARTIFACT);
+
+describe('portable toolsets-docs declarations', () => {
+  it.runIf(process.env.CI)('are built before this suite runs', () => {
+    expect(DTS_BUILT).toBe(true);
+  });
+
+  it.runIf(DTS_BUILT)('are one flat file: no relative imports', () => {
+    expect(readSpecifiers().filter((specifier) => specifier.startsWith('.'))).toEqual([]);
+  });
+
+  it.runIf(DTS_BUILT)('import exactly the allowlist', () => {
+    expect([...new Set(readSpecifiers())].sort()).toEqual(IMPORT_ALLOWLIST);
+  });
+
+  it.runIf(DTS_BUILT)('stay within their size budget', () => {
+    expect(statSync(DTS_ARTIFACT).size).toBeLessThan(SIZE_BUDGET_BYTES);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/runtime-agnostic.test.ts b/code/core/src/shared/open-service/toolsets/docs/runtime-agnostic.test.ts
new file mode 100644
index 000000000000..ec6bfb6e3bd3
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/runtime-agnostic.test.ts
@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+const DOCS_TOOLSET_DIR = import.meta.dirname;
+const CORE_SRC = resolve(DOCS_TOOLSET_DIR, '../../../..');
+
+/** Entry points that must stay runtime-agnostic so every consumer can compose them. */
+const ENTRY_POINTS = ['definition.ts', 'access.ts', 'access-service.ts', 'access-manifest.ts'];
+
+const IMPORT_RE = /^\s*(?:import|export)\s(?:[\s\S]*?)from\s+['"]([^'"]+)['"]/gm;
+const TYPE_ONLY_RE = /^\s*(?:import|export)\s+type\s/;
+
+function importsOf(filePath: string): string[] {
+  const source = readFileSync(filePath, 'utf-8');
+  const specifiers: string[] = [];
+  for (const match of source.matchAll(IMPORT_RE)) {
+    // Type-only imports are erased, so they cannot drag a runtime dependency into a bundle.
+    if (TYPE_ONLY_RE.test(match[0])) {
+      continue;
+    }
+    specifiers.push(match[1]);
+  }
+  return specifiers;
+}
+
+function walk(entry: string): Map<string, string[]> {
+  const reached = new Map<string, string[]>();
+  const queue: Array<{ file: string; trail: string[] }> = [{ file: entry, trail: [] }];
+
+  while (queue.length > 0) {
+    const { file, trail } = queue.shift()!;
+    if (reached.has(file)) {
+      continue;
+    }
+    reached.set(file, trail);
+
+    for (const specifier of importsOf(file)) {
+      if (!specifier.startsWith('.')) {
+        reached.set(specifier, [...trail, relative(CORE_SRC, file)]);
+        continue;
+      }
+      const target = join(dirname(file), specifier);
+      // Relative imports in this repo always carry their extension, so anything else is a match
+      // from prose rather than a real import.
+      if (!existsSync(target)) {
+        continue;
+      }
+      queue.push({ file: target, trail: [...trail, relative(CORE_SRC, file)] });
+    }
+  }
+
+  return reached;
+}
+
+/**
+ * The docs toolset is composed by the dev server, by the hosted MCP server, and (from Milestone 5)
+ * by the CLI. Everything environment-specific has to stay behind the injected `DocsAccess`, so a
+ * dependency on core-server would silently make the toolset dev-server-only again.
+ */
+describe('docs toolset stays runtime-agnostic', () => {
+  it.each(ENTRY_POINTS)('%s never reaches core-server', (entryPoint) => {
+    const reached = walk(join(DOCS_TOOLSET_DIR, entryPoint));
+
+    const offenders = [...reached.entries()].filter(
+      ([target]) =>
+        target.includes('storybook/internal/core-server') || target.includes('core-server/')
+    );
+
+    expect(
+      offenders.map(([target, trail]) => `${target} (via ${trail.join(' -> ') || 'direct'})`)
+    ).toEqual([]);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/docs/sources.test.ts b/code/core/src/shared/open-service/toolsets/docs/sources.test.ts
new file mode 100644
index 000000000000..2231350cc430
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/docs/sources.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { getSourceMcpEndpoint } from './sources.ts';
+
+describe('getSourceMcpEndpoint', () => {
+  it.each([
+    ['https://example.com', 'https://example.com/mcp'],
+    ['https://example.com/storybook/', 'https://example.com/storybook/mcp'],
+    ['https://example.com/storybook/?foo=bar#section', 'https://example.com/storybook/mcp'],
+  ])('returns the source-specific MCP endpoint for %s', (url, expected) => {
+    expect(getSourceMcpEndpoint({ id: 'remote', title: 'Remote', url })).toBe(expected);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/estimate-tokens.test.ts b/code/core/src/shared/open-service/toolsets/estimate-tokens.test.ts
new file mode 100644
index 000000000000..a19b64772876
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/estimate-tokens.test.ts
@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { estimateTokens } from './estimate-tokens.ts';
+
+describe('estimateTokens', () => {
+  it('should return 0 for empty string', () => {
+    expect(estimateTokens('')).toBe(0);
+  });
+
+  it('should count single word', () => {
+    expect(estimateTokens('hello')).toBe(1);
+  });
+
+  it('should count words separated by single space', () => {
+    expect(estimateTokens('hello world')).toBe(3); // hello + space + world
+  });
+
+  it('should count multiple continuous spaces as single token', () => {
+    expect(estimateTokens('hello   world')).toBe(3); // hello + multiple-spaces + world
+  });
+
+  it('should count tabs and newlines as single whitespace token', () => {
+    expect(estimateTokens('hello\t\nworld')).toBe(3); // hello + tab-newline + world
+  });
+
+  it('should count hyphenated words separately', () => {
+    expect(estimateTokens('hello-world')).toBe(3); // hello + hyphen + world
+  });
+
+  it('should count continuous special characters individually', () => {
+    expect(estimateTokens('hello---world')).toBe(5); // hello + - + - + - + world
+  });
+
+  it('should count punctuation individually', () => {
+    expect(estimateTokens('hello, world!')).toBe(5); // hello + comma + space + world + exclamation
+  });
+
+  it('should handle leading and trailing whitespace', () => {
+    expect(estimateTokens('  hello world  ')).toBe(5); // leading-spaces + hello + space + world + trailing-spaces
+  });
+
+  it('should count complex text correctly', () => {
+    const text = `# Getting Started
+
+Welcome to the component library.`;
+    // # + space + Getting + space + Started + double-newline + Welcome + space + to + space + the + space + component + space + library + .
+    const result = estimateTokens(text);
+    expect(result).toBe(16);
+  });
+
+  it('should handle code examples with punctuation and symbols', () => {
+    const text = 'const x = 123;';
+    // const + space + x + space + = + space + 123 + ;
+    expect(estimateTokens(text)).toBe(8);
+  });
+
+  it('should count URLs correctly', () => {
+    const text = 'https://example.com/path';
+    // https + : + / + / + example + . + com + / + path
+    expect(estimateTokens(text)).toBe(9);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/estimate-tokens.ts b/code/core/src/shared/open-service/toolsets/estimate-tokens.ts
new file mode 100644
index 000000000000..f60fde6474ba
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/estimate-tokens.ts
@@ -0,0 +1,66 @@
+/**
+ * Checks if a character code is whitespace (space, tab, newline, carriage return)
+ *
+ * Checking char codes is slightly faster than using regex or string methods.
+ */
+function isWhitespace(code: number): boolean {
+  return code === 32 || code === 9 || code === 10 || code === 13;
+}
+
+/**
+ * Checks if a character code is alphanumeric or underscore
+ * 0-9 (48-57), A-Z (65-90), a-z (97-122), underscore (95)
+ *
+ * Checking char codes is slightly faster than using regex or string methods.
+ */
+function isAlphanumeric(code: number): boolean {
+  return (
+    (code >= 48 && code <= 57) ||
+    (code >= 65 && code <= 90) ||
+    (code >= 97 && code <= 122) ||
+    code === 95
+  );
+}
+
+/**
+ * Estimates token count from text using a fast approximation.
+ * Counts:
+ * - Continuous whitespace as a single token
+ * - Continuous alphanumeric sequences as single tokens
+ * - Each special character as an individual token
+ *
+ * This is a cheap approximation suitable for telemetry purposes.
+ *
+ * @param text - The text to estimate token count for
+ * @returns Estimated token count
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+
+  let tokenCount = 0;
+  let i = 0;
+  const len = text.length;
+
+  while (i < len) {
+    const code = text.charCodeAt(i);
+
+    if (isWhitespace(code)) {
+      tokenCount++;
+      i++;
+      while (i < len && isWhitespace(text.charCodeAt(i))) {
+        i++;
+      }
+    } else if (isAlphanumeric(code)) {
+      tokenCount++;
+      i++;
+      while (i < len && isAlphanumeric(text.charCodeAt(i))) {
+        i++;
+      }
+    } else {
+      tokenCount++;
+      i++;
+    }
+  }
+
+  return tokenCount;
+}
diff --git a/code/core/src/shared/open-service/toolsets/review/definition.test.ts b/code/core/src/shared/open-service/toolsets/review/definition.test.ts
index 3b1adb0f3eb3..f51f1f289bac 100644
--- a/code/core/src/shared/open-service/toolsets/review/definition.test.ts
+++ b/code/core/src/shared/open-service/toolsets/review/definition.test.ts
@@ -1,10 +1,15 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import * as v from 'valibot';
 
-import type { ToolsetCtx } from '../../toolset-definition.ts';
-import { OpenServiceMissingOriginError } from '../../../../server-errors.ts';
+import {
+  OpenServiceMissingOriginError,
+  OpenServiceUnknownStoryIdsError,
+} from '../../../../server-errors.ts';
+import { resolveToolsetDescription, type ToolsetCtx } from '../../toolset-definition.ts';
 import { reviewToolset } from './definition.ts';
 
+const reviewUrl = 'http://localhost:6006/?path=/review/';
+
 const input = {
   title: 'Button tweaks',
   description: 'Check primary',
@@ -19,11 +24,13 @@ const input = {
 };
 
 const setReview = vi.fn();
-let ctx: ToolsetCtx;
+let cliCtx: ToolsetCtx;
+let mcpCtx: ToolsetCtx;
 let serviceError: Error | undefined;
 
 function createReview(
-  overrides: Partial<v.InferInput<typeof reviewToolset.methods.create.schema>> = {}
+  overrides: Partial<v.InferInput<typeof reviewToolset.methods.create.schema>> = {},
+  ctx: ToolsetCtx = cliCtx
 ) {
   return reviewToolset.methods.create.handler(
     v.parse(reviewToolset.methods.create.schema, { ...input, ...overrides }),
@@ -31,27 +38,66 @@ function createReview(
   );
 }
 
-describe('review API', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    serviceError = undefined;
-    setReview.mockImplementation(async () => {
-      if (serviceError) {
-        throw serviceError;
-      }
+beforeEach(() => {
+  vi.clearAllMocks();
+  serviceError = undefined;
+  setReview.mockImplementation(async () => {
+    if (serviceError) {
+      throw serviceError;
+    }
+  });
+  cliCtx = {
+    consumer: 'cli',
+    origin: 'http://localhost:6006',
+    getService: vi.fn(() => ({ commands: { setReview } })) as ToolsetCtx['getService'],
+  };
+  mcpCtx = { ...cliCtx, consumer: 'mcp' };
+});
+
+describe('review.create', () => {
+  it('publishes the review and returns its page URL plus what it contains', async () => {
+    const outcome = await createReview();
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data).toEqual({
+      reviewUrl,
+      collectionCount: 1,
+      storyCount: 1,
+    });
+    expect(setReview).toHaveBeenCalledWith(input);
+    expect(cliCtx.getService).toHaveBeenCalledWith('core/review', { internal: true });
+  });
+
+  it('counts stories across every collection', async () => {
+    const outcome = await createReview({
+      collections: [
+        { title: 'Primary', rationale: 'edited', storyIds: ['button--primary', 'button--large'] },
+        { title: 'Pages', rationale: 'context', storyIds: ['page--default'] },
+      ],
     });
-    ctx = {
-      consumer: 'cli',
-      origin: 'http://localhost:6006/',
-      format: 'markdown',
-      getService: vi.fn(() => ({ commands: { setReview } })) as ToolsetCtx['getService'],
-    };
+
+    expect(outcome.data).toMatchObject({ collectionCount: 2, storyCount: 3 });
+  });
+
+  it('builds one review URL whether or not the origin ends in a slash', async () => {
+    const outcome = await createReview({}, { ...cliCtx, origin: 'http://localhost:6006/' });
+
+    expect(outcome.data).toMatchObject({ reviewUrl });
   });
 
-  it('rejects with a missing-origin error when no server origin is configured', async () => {
-    ctx.origin = undefined;
+  it('prefers the request-derived uiRoot over the origin for the review link', async () => {
+    // A sub-path-hosted Storybook answers MCP under its root; the review page lives there too.
+    const outcome = await createReview({}, { ...cliCtx, uiRoot: 'http://localhost:6006/nested' });
+
+    expect(outcome.data).toMatchObject({
+      reviewUrl: 'http://localhost:6006/nested/?path=/review/',
+    });
+  });
 
-    await expect(createReview()).rejects.toBeInstanceOf(OpenServiceMissingOriginError);
+  it('rejects when the adapter has no Storybook origin to link to', async () => {
+    await expect(createReview({}, { ...cliCtx, origin: undefined })).rejects.toBeInstanceOf(
+      OpenServiceMissingOriginError
+    );
     expect(setReview).not.toHaveBeenCalled();
   });
 
@@ -61,31 +107,108 @@ describe('review API', () => {
     await expect(createReview()).rejects.toBe(serviceError);
   });
 
-  it('sets review state and returns Markdown by default', async () => {
-    await expect(createReview()).resolves.toBe(
-      'Review created: http://localhost:6006/?path=/review/'
-    );
-    expect(setReview).toHaveBeenCalledWith(input);
-    expect(ctx.getService).toHaveBeenCalledWith('core/review', { internal: true });
+  describe('fabricated story ids', () => {
+    beforeEach(() => {
+      serviceError = new OpenServiceUnknownStoryIdsError({
+        unknownIds: ['button--ghost', 'card--imagined'],
+      });
+    });
+
+    it('replaces the service error with recovery coaching naming the MCP tools', async () => {
+      const error = await createReview({}, mcpCtx).catch((reason: unknown) => reason);
+
+      expect(error).not.toBeInstanceOf(OpenServiceUnknownStoryIdsError);
+      expect((error as Error).message)
+        .toBe(`Refusing to publish review: 2 story IDs are not backed by a story entry in the live Storybook index (docs entries cannot be review slots):
+- \`button--ghost\`
+- \`card--imagined\`
+
+This usually means the IDs were inferred from file paths or naming conventions rather than returned by a tool. Resolve real IDs by calling \`get-stories-by-component\` (for components you've edited or want covered) or \`list-all-documentation\` (to browse the index), then retry \`display-review\` with the verified IDs. Do not invent IDs to satisfy this check.`);
+    });
+
+    it('names the CLI commands for the CLI consumer', async () => {
+      const error = await createReview().catch((reason: unknown) => reason);
+
+      expect((error as Error).message).toContain(
+        'calling `npx storybook tools stories find-by-component`'
+      );
+      expect((error as Error).message).toContain('retry `npx storybook tools review create`');
+    });
+
+    it('agrees with the singular case', async () => {
+      serviceError = new OpenServiceUnknownStoryIdsError({ unknownIds: ['button--ghost'] });
+
+      const error = await createReview().catch((reason: unknown) => reason);
+
+      expect((error as Error).message).toContain(
+        'Refusing to publish review: 1 story ID is not backed by a story entry in the live Storybook index (docs entries cannot be review slots)'
+      );
+    });
   });
 
-  it('adds the user-facing instruction only for the MCP Markdown response', async () => {
-    const cliResult = await createReview();
-    ctx.consumer = 'mcp';
-    const mcpResult = await createReview();
+  describe('rendering', () => {
+    it('summarizes the review in one line for the CLI', async () => {
+      const outcome = await createReview();
 
-    expect(cliResult).not.toContain('Show this review URL');
-    expect(mcpResult).toBe(
-      `${cliResult}\n\nShow this review URL to the user in your final response.`
-    );
+      expect(outcome.markdown).toBe(
+        `Review applied: 1 collection, 1 story. Open ${reviewUrl} to view it.`
+      );
+    });
+
+    it('pluralizes the CLI summary', async () => {
+      const outcome = await createReview({
+        collections: [
+          { title: 'Primary', rationale: 'edited', storyIds: ['button--primary'] },
+          { title: 'Pages', rationale: 'context', storyIds: ['page--default'] },
+        ],
+      });
+
+      expect(outcome.markdown).toBe(
+        `Review applied: 2 collections, 2 stories. Open ${reviewUrl} to view it.`
+      );
+    });
+
+    it('tells MCP to reuse the request-derived UI root, not the bare origin', async () => {
+      // A sub-path-hosted Storybook serves its UI under the request root; "already running at"
+      // must name the address the agent can actually reach, like the review link does.
+      const outcome = await createReview({}, { ...mcpCtx, uiRoot: 'http://localhost:6006/nested' });
+
+      expect(outcome.markdown).toContain(
+        'Storybook is already running at http://localhost:6006/nested — reuse it.'
+      );
+    });
+
+    it('tells MCP to open the page itself and to surface the link to the user', async () => {
+      const outcome = await createReview({}, mcpCtx);
+
+      expect(outcome.markdown)
+        .toBe(`Review applied: 1 collection, 1 story. Storybook is already running at http://localhost:6006 — reuse it. Do NOT start another Storybook or change its port to view this review; the running instance already serves it.
+
+Two things you must do now, both of them:
+1. **Open ${reviewUrl} yourself in your preview browser.** If you have any browser-preview or navigate tool in this session (e.g. preview_eval or an equivalent), call it on this URL so the review opens in your preview window immediately. Don't merely print the link and stop — actually open it.
+2. **Show the link to the user too.** End your final response with a dedicated review section as the very last thing: its own heading on a line by itself (e.g. \`## 👀 Review your changes\`), then a one-line explanation of what the review is, then on the next line the review page as a markdown link prefixed with a 👉 so it's easy to spot: \`👉 [Open the Storybook review page](${reviewUrl})\`. For the explanation, use something like: "The review shows the 1 story most relevant for you to review right now. Because this is AI-curated, results may be inaccurate or incomplete." Put nothing after the link — not a trailing sentence the user has to hunt for. The user needs to see this link even after you've opened it yourself.`);
+    });
   });
 
-  it('returns structured data when the adapter requests JSON', async () => {
-    ctx.format = 'json';
+  describe('description', () => {
+    it('names the discovery tools the way an MCP client calls them', () => {
+      const description = resolveToolsetDescription(
+        reviewToolset.methods.create.description,
+        mcpCtx
+      );
 
-    await expect(createReview()).resolves.toEqual({
-      reviewUrl: 'http://localhost:6006/?path=/review/',
+      expect(description).toContain('Start from `get-changed-stories`');
+      expect(description).toContain('fall back to `get-stories-by-component`');
+    });
+
+    it('names the discovery tools as CLI commands', () => {
+      const description = resolveToolsetDescription(
+        reviewToolset.methods.create.description,
+        cliCtx
+      );
+
+      expect(description).toContain('Start from `npx storybook tools stories changed`');
+      expect(description).toContain('fall back to `npx storybook tools stories find-by-component`');
     });
-    expect(setReview).toHaveBeenCalledWith(input);
   });
 });
diff --git a/code/core/src/shared/open-service/toolsets/stories/definition.test.ts b/code/core/src/shared/open-service/toolsets/stories/definition.test.ts
index bf0b469f4ecf..8a743fda2737 100644
--- a/code/core/src/shared/open-service/toolsets/stories/definition.test.ts
+++ b/code/core/src/shared/open-service/toolsets/stories/definition.test.ts
@@ -1,14 +1,19 @@
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 
 import type { StoryIndex } from 'storybook/internal/types';
 
+import { vol } from 'memfs';
+import { resolve } from 'pathe';
 import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import * as v from 'valibot';
-import { vol } from 'memfs';
 
-import type { ToolsetCtx } from '../../toolset-definition.ts';
+import {
+  OpenServiceMissingOriginError,
+  OpenServiceModuleGraphUnavailableError,
+} from '../../../../server-errors.ts';
 import { CHANGE_DETECTION_STATUS_TYPE_ID } from '../../../status-store/index.ts';
-import { createStoriesToolset } from './definition.ts';
+import { resolveToolsetDescription, type ToolsetCtx } from '../../toolset-definition.ts';
+import { createStoriesToolset, type StoriesToolset } from './definition.ts';
 
 vi.mock('node:fs', { spy: true });
 
@@ -27,16 +32,28 @@ const index = {
   },
 } as StoryIndex;
 
-const repoRoot = '/repo';
-const storybookWorkingDir = '/repo/packages/ui';
-const componentPath = `${storybookWorkingDir}/src/Button.tsx`;
-const themePath = `${storybookWorkingDir}/src/theme.ts`;
+// Resolved with pathe — the resolver's own path library — so the fixtures match its output on
+// Windows too (drive-letter prefix, forward slashes).
+const repoRoot = resolve('/repo');
+const storybookWorkingDir = resolve(repoRoot, 'packages/ui');
+const componentPath = resolve(storybookWorkingDir, 'src/Button.tsx');
+/** On disk, but no story reaches it — the "component without stories yet" case. */
+const orphanPath = resolve(storybookWorkingDir, 'src/Orphan.tsx');
+const themePath = resolve(storybookWorkingDir, 'src/theme.ts');
+// Git reports paths relative to the repository root, and the response echoes them in that form.
+const changedComponentFile = 'packages/ui/src/Button.tsx';
+const changedThemeFile = 'packages/ui/src/theme.ts';
+
+const buttonStoryHit = { storyFile: './src/Button.stories.tsx', depth: 1 };
+const previewUrl = 'http://localhost:6006/?path=/story/button--primary';
+
 const getIndex = vi.fn();
 const getChangedFiles = vi.fn();
 const getRepoRoot = vi.fn();
 const getStatuses = vi.fn();
 const graphStatus = vi.fn();
 const storiesForFiles = vi.fn();
+const telemetry = vi.fn();
 const cwd = vi.spyOn(process, 'cwd');
 const moduleGraph = {
   queries: {
@@ -48,40 +65,73 @@ const moduleGraph = {
 const storyIndex = { getIndex };
 const git = { getChangedFiles, getRepoRoot };
 const changeStatuses = { getAll: getStatuses };
+
 let statusesFixture: Record<string, Record<string, unknown>>;
 let graphMatchesByFile: Map<string, Array<{ storyFile: string; depth: number }>>;
-let ctx: ToolsetCtx;
+let cliCtx: ToolsetCtx;
+let mcpCtx: ToolsetCtx;
+let toolset: StoriesToolset;
 
-function createToolset() {
-  return createStoriesToolset({
-    storyIndex,
-    git,
-    changeStatuses,
-  });
+function createToolset({ reviewEnabled = false } = {}): StoriesToolset {
+  return createStoriesToolset({ storyIndex, git, changeStatuses, reviewEnabled });
+}
+
+function runPreview(
+  stories: Array<Record<string, unknown>>,
+  ctx: ToolsetCtx = cliCtx,
+  target: StoriesToolset = toolset
+) {
+  return target.methods.preview.handler(v.parse(target.methods.preview.schema, { stories }), ctx);
+}
+
+function runChanged(ctx: ToolsetCtx = cliCtx, target: StoriesToolset = toolset) {
+  return target.methods.changed.handler(v.parse(target.methods.changed.schema, {}), ctx);
 }
 
-beforeEach(async () => {
-  const memfs = await vi.importActual<typeof import('memfs')>('memfs');
+function runFindByComponent(
+  input: Record<string, unknown>,
+  ctx: ToolsetCtx = cliCtx,
+  target: StoriesToolset = toolset
+) {
+  return target.methods.findByComponent.handler(
+    v.parse(target.methods.findByComponent.schema, input),
+    ctx
+  );
+}
+
+/** Marks a changed file as reachable from a story, which keeps it out of `unreachableFiles`. */
+function markReachable(absolutePath: string) {
+  graphMatchesByFile.set(absolutePath, [buttonStoryHit]);
+}
 
+function markChanged(storyId: string, value: string) {
+  statusesFixture[storyId] = {
+    [CHANGE_DETECTION_STATUS_TYPE_ID]: { storyId, value },
+  };
+}
+
+beforeEach(() => {
   vi.clearAllMocks();
   vol.reset();
-  vol.fromNestedJSON({ [componentPath]: '' });
-  vi.mocked(existsSync).mockImplementation(memfs.fs.existsSync as typeof existsSync);
+  vol.fromNestedJSON({ [componentPath]: '', [orphanPath]: '' });
+  vi.mocked(existsSync).mockImplementation((filePath) => vol.existsSync(filePath));
+  vi.mocked(realpathSync.native).mockImplementation((filePath) =>
+    String(vol.realpathSync(filePath))
+  );
   cwd.mockReturnValue(storybookWorkingDir);
   statusesFixture = {};
-  graphMatchesByFile = new Map([
-    [componentPath, [{ storyFile: './src/Button.stories.tsx', depth: 1 }]],
-  ]);
-  ctx = {
+  graphMatchesByFile = new Map([[componentPath, [buttonStoryHit]]]);
+  cliCtx = {
     consumer: 'cli',
     origin: 'http://localhost:6006',
-    format: 'markdown',
     getService: vi.fn(() => moduleGraph) as ToolsetCtx['getService'],
+    telemetry,
   };
+  mcpCtx = { ...cliCtx, consumer: 'mcp' };
   getIndex.mockResolvedValue(index);
   getChangedFiles.mockResolvedValue({
-    changed: new Set(['packages/ui/src/Button.tsx']),
-    new: new Set(['packages/ui/src/theme.ts']),
+    changed: new Set([changedComponentFile]),
+    new: new Set([changedThemeFile]),
   });
   getRepoRoot.mockResolvedValue(repoRoot);
   getStatuses.mockImplementation(() => statusesFixture);
@@ -89,6 +139,7 @@ beforeEach(async () => {
   storiesForFiles.mockImplementation(async ({ files }: { files: string[] }) =>
     files.map((file) => graphMatchesByFile.get(file) ?? [])
   );
+  toolset = createToolset();
 });
 
 afterAll(() => {
@@ -96,79 +147,221 @@ afterAll(() => {
   vol.reset();
 });
 
-describe('stories API', () => {
-  it('returns compact Markdown preview URLs by default', async () => {
-    const storiesToolset = createToolset();
+describe('stories.preview', () => {
+  it('resolves story ids against the live index', async () => {
+    const outcome = await runPreview([{ storyId: 'button--primary' }]);
 
-    await expect(
-      storiesToolset.methods.preview.handler(
-        v.parse(storiesToolset.methods.preview.schema, {
-          stories: [{ storyId: 'button--primary' }],
-        }),
-        ctx
-      )
-    ).resolves.toBe(
-      [
-        '# Story previews',
-        '- Button - Primary',
-        '  http://localhost:6006/?path=/story/button--primary',
-      ].join('\n')
-    );
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data).toEqual({
+      stories: [{ title: 'Button', name: 'Primary', previewUrl }],
+    });
+    expect(getIndex).toHaveBeenCalledOnce();
   });
 
-  it('returns the structured preview result when the adapter requests JSON', async () => {
-    ctx.format = 'json';
-    const storiesToolset = createToolset();
+  it('reports per-input lookup failures instead of failing the call', async () => {
+    const outcome = await runPreview([{ storyId: 'gone--story' }]);
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data).toEqual({
+      stories: [
+        {
+          input: { storyId: 'gone--story' },
+          error: 'No story found for story ID "gone--story"',
+        },
+      ],
+    });
+  });
 
+  it('rejects when the adapter has no Storybook origin to build URLs from', async () => {
     await expect(
-      storiesToolset.methods.preview.handler(
-        v.parse(storiesToolset.methods.preview.schema, {
-          stories: [{ storyId: 'button--primary' }],
-        }),
-        ctx
-      )
-    ).resolves.toEqual({
+      runPreview([{ storyId: 'button--primary' }], { ...cliCtx, origin: undefined })
+    ).rejects.toBeInstanceOf(OpenServiceMissingOriginError);
+  });
+
+  it('reports the story counts it resolved', async () => {
+    await runPreview([{ storyId: 'button--primary' }, { storyId: 'gone--story' }]);
+
+    expect(telemetry).toHaveBeenCalledWith('tool:previewStories', {
+      inputStoryCount: 2,
+      outputStoryCount: 2,
+    });
+  });
+
+  describe('rendering', () => {
+    it('lists titled entries for the CLI', async () => {
+      const outcome = await runPreview([{ storyId: 'button--primary' }]);
+
+      expect(outcome.markdown).toBe(
+        ['# Story previews', '- Button - Primary', `  ${previewUrl}`].join('\n')
+      );
+    });
+
+    it('returns one text block per URL for MCP', async () => {
+      const outcome = await runPreview([{ storyId: 'button--primary' }], mcpCtx);
+
+      expect(outcome.markdown).toEqual([previewUrl]);
+    });
+
+    it('appends a review nudge for MCP once a URL resolved and reviews exist', async () => {
+      const withReviews = createToolset({ reviewEnabled: true });
+      const outcome = await runPreview([{ storyId: 'button--primary' }], mcpCtx, withReviews);
+
+      expect(outcome.markdown).toEqual([
+        previewUrl,
+        'These preview links are for iterating or sharing a specific story — they are not how visual work or a browse request ends. The display-review tool is available in this session: if you are finishing visually observable work or showing a set of stories, publish the review with **display-review** and link that instead.',
+      ]);
+    });
+
+    it('leaves an all-error result unnudged, since there is nothing to curate', async () => {
+      const withReviews = createToolset({ reviewEnabled: true });
+      const outcome = await runPreview([{ storyId: 'gone--story' }], mcpCtx, withReviews);
+
+      expect(outcome.markdown).toEqual(['No story found for story ID "gone--story"']);
+    });
+  });
+});
+
+describe('stories.changed', () => {
+  it('enriches change-detection statuses and lists unreachable working-tree files', async () => {
+    markChanged('button--primary', 'status-value:modified');
+
+    const outcome = await runChanged();
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data).toEqual({
       stories: [
         {
+          storyId: 'button--primary',
+          statusValue: 'status-value:modified',
           title: 'Button',
           name: 'Primary',
-          previewUrl: 'http://localhost:6006/?path=/story/button--primary',
+          importPath: './src/Button.stories.tsx',
         },
       ],
+      counts: { new: 0, modified: 1, affected: 0 },
+      unreachableFiles: [changedThemeFile],
     });
-    expect(getIndex).toHaveBeenCalledOnce();
+    expect(getStatuses).toHaveBeenCalledOnce();
+    expect(cliCtx.getService).toHaveBeenCalledWith('core/module-graph', { internal: true });
   });
 
-  it('formats component matches using the module graph from context', async () => {
-    const storiesToolset = createToolset();
+  it('degrades to "no changes detected" when git is unusable, as the pre-toolset tool did', async () => {
+    getChangedFiles.mockRejectedValue(new Error('not a git repository'));
+    getRepoRoot.mockRejectedValue(new Error('not a git repository'));
 
-    await expect(
-      storiesToolset.methods.findByComponent.handler(
-        v.parse(storiesToolset.methods.findByComponent.schema, { componentPaths: [componentPath] }),
-        ctx
-      )
-    ).resolves.toBe(
-      [
-        '# Stories by component',
-        `## ${componentPath}`,
-        '- Button - Primary (button--primary, distance 1)',
-        '  ./src/Button.stories.tsx',
-      ].join('\n')
-    );
-    expect(ctx.getService).toHaveBeenCalledWith('core/module-graph', { internal: true });
-    expect(storiesForFiles).toHaveBeenCalledWith({ files: [componentPath] });
+    const outcome = await runChanged(mcpCtx);
+
+    expect(outcome.data.stories).toEqual([]);
+    expect(outcome.data.unreachableFiles).toEqual([]);
+    expect(outcome.markdown).toBe('No new, modified, or related stories detected.');
   });
 
-  it('returns structured component matches when the adapter requests JSON', async () => {
-    ctx.format = 'json';
-    const storiesToolset = createToolset();
+  it('anchors Git-relative paths at the repository root, not the Storybook working directory', async () => {
+    await runChanged();
 
-    await expect(
-      storiesToolset.methods.findByComponent.handler(
-        v.parse(storiesToolset.methods.findByComponent.schema, { componentPaths: [componentPath] }),
-        ctx
-      )
-    ).resolves.toEqual({
+    expect(storiesForFiles).toHaveBeenCalledWith({ files: [componentPath, themePath] });
+  });
+
+  it('reports the per-status counts', async () => {
+    markChanged('button--primary', 'status-value:new');
+
+    await runChanged();
+
+    expect(telemetry).toHaveBeenCalledWith('tool:getChangedStories', {
+      storyCount: 1,
+      newStoryCount: 1,
+      modifiedStoryCount: 0,
+      affectedStoryCount: 0,
+    });
+  });
+
+  describe('rendering', () => {
+    it('summarizes counts and unreachable files for the CLI', async () => {
+      markChanged('button--primary', 'status-value:new');
+      const outcome = await runChanged();
+
+      expect(outcome.markdown).toBe(
+        [
+          '# Changed stories',
+          'New: 1, modified: 0, affected: 0',
+          '- [new] Button - Primary',
+          '',
+          '## Unreachable files',
+          `- ${changedThemeFile}`,
+        ].join('\n')
+      );
+    });
+
+    it('buckets stories by status for MCP', async () => {
+      markChanged('button--primary', 'status-value:new');
+      markReachable(themePath);
+      const outcome = await runChanged(mcpCtx);
+
+      expect(outcome.markdown).toBe(
+        `Detected 1 changed story (1 new, 0 modified, 0 related).
+
+New stories:
+- \`button--primary\`: Button / Primary (\`./src/Button.stories.tsx\`)`
+      );
+    });
+
+    it('points MCP at the review tool as the next step when reviews are enabled', async () => {
+      markChanged('button--primary', 'status-value:new');
+      markReachable(themePath);
+      const withReviews = createToolset({ reviewEnabled: true });
+      const outcome = await runChanged(mcpCtx, withReviews);
+
+      expect(outcome.markdown).toBe(
+        `Detected 1 changed story (1 new, 0 modified, 0 related).
+
+Next: if the change is visually observable, publish the review now — call **display-review** curating these story IDs. That review link is how you finish; do not substitute individual preview URLs for it.
+
+New stories:
+- \`button--primary\`: Button / Primary (\`./src/Button.stories.tsx\`)`
+      );
+    });
+
+    it('brackets a non-empty MCP result with a coverage banner and a sanity-check note', async () => {
+      markChanged('button--primary', 'status-value:new');
+      const outcome = await runChanged(mcpCtx);
+
+      expect(outcome.markdown).toBe(
+        `⚠ Coverage gap: 1 modified file unreachable from any story (${changedThemeFile}) — full sanity-check note at end of this response.
+
+Detected 1 changed story (1 new, 0 modified, 0 related).
+
+New stories:
+- \`button--primary\`: Button / Primary (\`./src/Button.stories.tsx\`)
+
+Coverage sanity check: the working tree also contains modified file(s) that aren't reachable from any story above (no static import path connects them — typically theme tokens, decorators, or other preview-runtime files):
+- ${changedThemeFile}
+
+The list above is real but may be stale w.r.t. these files — they're often left over from an earlier sub-change in the same diff. Before composing a review, grep the codebase for their exports and call \`get-stories-by-component\` with the runtime consumers' file paths. Do not assume the list above already covers them, and never invent story IDs to fill the gap.`
+      );
+    });
+
+    it('tells MCP how to recover when nothing changed but files are unreachable', async () => {
+      const outcome = await runChanged(mcpCtx);
+
+      expect(outcome.markdown).toBe(
+        `No new, modified, or related stories detected.
+
+The following working-tree file(s) are modified but unreachable from any story (no static import path connects them — they are likely theme tokens, decorators, or other Storybook-preview-runtime files):
+- ${changedThemeFile}
+
+For these, grep the codebase for their exports (e.g. specific tokens or symbols) to find runtime consumers, then call \`get-stories-by-component\` with those consumer file paths.`
+      );
+    });
+  });
+});
+
+describe('stories.findByComponent', () => {
+  it('returns index-backed matches together with the ceiling that was applied', async () => {
+    const outcome = await runFindByComponent({ componentPaths: [componentPath] });
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data).toEqual({
+      maxDistance: 3,
       results: [
         {
           componentPath,
@@ -184,86 +377,120 @@ describe('stories API', () => {
         },
       ],
     });
+    expect(cliCtx.getService).toHaveBeenCalledWith('core/module-graph', { internal: true });
+    expect(storiesForFiles).toHaveBeenCalledWith({ files: [componentPath] });
   });
 
-  it('returns compact Markdown for changed stories by default', async () => {
-    statusesFixture = {
-      'button--primary': {
-        [CHANGE_DETECTION_STATUS_TYPE_ID]: {
-          storyId: 'button--primary',
-          value: 'status-value:new',
-        },
-      },
-    };
-    const storiesToolset = createToolset();
+  it('echoes a caller-supplied ceiling', async () => {
+    const outcome = await runFindByComponent({ componentPaths: [componentPath], maxDistance: 1 });
 
-    await expect(
-      storiesToolset.methods.changed.handler(
-        v.parse(storiesToolset.methods.changed.schema, {}),
-        ctx
-      )
-    ).resolves.toBe(
-      [
-        '# Changed stories',
-        'New: 1, modified: 0, affected: 0',
-        '- [new] Button - Primary',
-        '',
-        '## Unreachable files',
-        `- ${themePath}`,
-      ].join('\n')
-    );
-    expect(getStatuses).toHaveBeenCalledOnce();
-    expect(getChangedFiles).toHaveBeenCalledOnce();
-    expect(getRepoRoot).toHaveBeenCalledOnce();
-    expect(ctx.getService).toHaveBeenCalledWith('core/module-graph', { internal: true });
-    expect(storiesForFiles).toHaveBeenCalledWith({
-      files: [componentPath, themePath],
-    });
+    expect(outcome.data).toMatchObject({ maxDistance: 1 });
   });
 
-  it('anchors Git-relative paths when Storybook runs below the repository root', async () => {
-    const storiesToolset = createToolset();
+  it('rejects with the graph reason rather than answering "no stories"', async () => {
+    graphStatus.mockResolvedValue({
+      value: 'unavailable',
+      reason: 'builder does not support change detection',
+    });
 
-    await storiesToolset.methods.changed.handler(
-      v.parse(storiesToolset.methods.changed.schema, {}),
-      ctx
+    const error = await runFindByComponent({ componentPaths: [componentPath] }).catch(
+      (reason: unknown) => reason
     );
 
-    expect(process.cwd()).toBe(storybookWorkingDir);
-    expect(storiesForFiles).toHaveBeenCalledWith({
-      files: [componentPath, themePath],
+    expect(error).toBeInstanceOf(OpenServiceModuleGraphUnavailableError);
+    // The adapter hands this message straight to the agent, so it must name both the
+    // adapter-specific cause the service reported and the remedy that cause does not say.
+    expect((error as Error).message).toBe(
+      "Storybook's story dependency graph is unavailable: builder does not support change detection. Make sure the dev server is running with a builder that supports change detection."
+    );
+  });
+
+  it('reports how many of the requested components matched', async () => {
+    await runFindByComponent({ componentPaths: [componentPath, orphanPath] });
+
+    expect(telemetry).toHaveBeenCalledWith('tool:getStoriesByComponent', {
+      componentCount: 2,
+      matchedComponentCount: 1,
+      totalMatchCount: 1,
+      maxDistance: 3,
     });
   });
 
-  it('returns structured changed stories when the adapter requests JSON', async () => {
-    ctx.format = 'json';
-    statusesFixture = {
-      'button--primary': {
-        [CHANGE_DETECTION_STATUS_TYPE_ID]: {
-          storyId: 'button--primary',
-          value: 'status-value:modified',
-        },
-      },
-    };
-    const storiesToolset = createToolset();
+  describe('rendering', () => {
+    it('renders a headed section per component for the CLI', async () => {
+      const outcome = await runFindByComponent({ componentPaths: [componentPath] });
 
-    await expect(
-      storiesToolset.methods.changed.handler(
-        v.parse(storiesToolset.methods.changed.schema, {}),
-        ctx
-      )
-    ).resolves.toEqual({
-      stories: [
-        {
-          storyId: 'button--primary',
-          statusValue: 'status-value:modified',
-          title: 'Button',
-          name: 'Primary',
-          importPath: './src/Button.stories.tsx',
-        },
-      ],
-      counts: { new: 0, modified: 1, affected: 0 },
-      unreachableFiles: [themePath],
+      expect(outcome.markdown).toBe(
+        `# Stories by component
+## ${componentPath}
+${componentPath}:
+→ 1 story across 1 component, distances 1..1 (d1=1)
+distance 1:
+  - \`button--primary\`: Button / Primary (\`./src/Button.stories.tsx\`)`
+      );
     });
+
+    it('renders distance buckets without headings for MCP', async () => {
+      const outcome = await runFindByComponent({ componentPaths: [componentPath] }, mcpCtx);
+
+      expect(outcome.markdown).toBe(
+        `${componentPath}:
+→ 1 story across 1 component, distances 1..1 (d1=1)
+distance 1:
+  - \`button--primary\`: Button / Primary (\`./src/Button.stories.tsx\`)`
+      );
+    });
+
+    it('tells MCP to re-check a path that does not exist on disk', async () => {
+      const outcome = await runFindByComponent({ componentPaths: [themePath] }, mcpCtx);
+
+      expect(outcome.markdown).toBe(
+        `${themePath}: path does not exist on disk — re-check the path you sent.`
+      );
+    });
+  });
+});
+
+describe('descriptions', () => {
+  it('names sibling tools the way an MCP client calls them', () => {
+    expect(resolveToolsetDescription(toolset.methods.changed.description, mcpCtx)).toContain(
+      'get-stories-by-component'
+    );
+  });
+
+  it('names sibling tools as CLI commands', () => {
+    expect(resolveToolsetDescription(toolset.methods.changed.description, cliCtx)).toContain(
+      'npx storybook tools stories find-by-component'
+    );
+  });
+
+  it('makes preview the end of visual work when no review page exists', () => {
+    expect(resolveToolsetDescription(toolset.methods.preview.description, mcpCtx))
+      .toBe(`Use this tool to get one or more Storybook preview URLs.
+Call it after editing anything that changes how the UI looks — components, stories, styles, CSS, themes, colors, or design tokens — no exceptions. A shared file has no stories of its own: preview the stories of the components that consume it.
+Include each returned preview URL in your final user-facing response so users can open them directly.`);
+  });
+
+  it('demotes preview to a mid-loop tool when reviews are enabled', () => {
+    const withReviews = createToolset({ reviewEnabled: true });
+
+    expect(resolveToolsetDescription(withReviews.methods.preview.description, mcpCtx))
+      .toBe(`Use this tool to get Storybook preview URLs while iterating on a specific story, or when the user asks for a direct link to one.
+Do not end visual work or browse requests with these links — publish a curated review with display-review instead (passing changedFiles: [] when no code changed) and link that.`);
+
+    expect(resolveToolsetDescription(withReviews.methods.preview.description, cliCtx))
+      .toBe(`Use this tool to get Storybook preview URLs while iterating on a specific story, or when the user asks for a direct link to one.
+Do not end visual work or browse requests with these links — publish a curated review with npx storybook tools review create instead (passing changedFiles: [] when no code changed) and link that.`);
+  });
+
+  it('offers the review page as a hand-off target only when reviews are enabled', () => {
+    const withReviews = createToolset({ reviewEnabled: true });
+
+    expect(
+      resolveToolsetDescription(withReviews.methods.findByComponent.description, mcpCtx)
+    ).toContain('hand these to preview-stories or display-review');
+    expect(
+      resolveToolsetDescription(toolset.methods.findByComponent.description, mcpCtx)
+    ).toContain('hand these to preview-stories instead of guessing');
   });
 });
diff --git a/code/core/src/shared/open-service/toolsets/stories/find-by-component.test.ts b/code/core/src/shared/open-service/toolsets/stories/find-by-component.test.ts
index 22cd9f45dc9e..08f09933db98 100644
--- a/code/core/src/shared/open-service/toolsets/stories/find-by-component.test.ts
+++ b/code/core/src/shared/open-service/toolsets/stories/find-by-component.test.ts
@@ -1,15 +1,28 @@
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
 
 import type { StoryIndex } from 'storybook/internal/types';
 
-import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { vol } from 'memfs';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-import type { ModuleGraphService } from '../../services/module-graph/definition.ts';
-import { findStoriesByComponent, resolveComponentMatches } from './find-by-component.ts';
+import { DEFAULT_MAX_DISTANCE, findStoriesByComponent } from './find-by-component.ts';
+import type { ModuleGraphAccess, ModuleGraphStoryHit } from './resolve-component-stories.ts';
 
 vi.mock('node:fs', { spy: true });
 
+// Path resolution, barrel expansion, canonicalisation and dedupe belong to
+// `resolveComponentStories` and are covered by resolve-component-stories.test.ts. What is asserted
+// here is only what this module adds on top: maxDistance clipping, story-index enrichment, and the
+// pass-through of the resolver's `pathNotFound` / unavailable outcomes.
+
+const WORKING_DIR = path.resolve('/repo');
+const BUTTON = path.join(WORKING_DIR, 'src/Button.tsx');
+const MISSING = path.join(WORKING_DIR, 'src/Missing.tsx');
+
+/** The forward-slashed form the resolver queries the module graph with. */
+const asGraphPath = (filePath: string) => path.normalize(filePath).replaceAll('\\', '/');
+
 const index: StoryIndex = {
   v: 5,
   entries: {
@@ -44,38 +57,43 @@ const index: StoryIndex = {
 };
 
 const storiesForFiles = vi.fn();
-const moduleGraph = {
-  queries: {
-    storiesForFiles: {
-      loaded: storiesForFiles,
+
+/** A ready module graph whose reverse index answers with `hits` for every queried file. */
+function readyGraph(hits: ModuleGraphStoryHit[]): ModuleGraphAccess {
+  storiesForFiles.mockImplementation(async ({ files }: { files: string[] }) =>
+    files.map((file) => (file === asGraphPath(BUTTON) ? hits : []))
+  );
+  return {
+    queries: {
+      status: { loaded: async () => ({ value: 'ready' }) },
+      storiesForFiles: { loaded: storiesForFiles },
     },
-  },
-} as unknown as ModuleGraphService;
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vol.reset();
+  vol.fromNestedJSON({ [BUTTON]: '' });
+  vi.mocked(existsSync).mockImplementation((filePath) => vol.existsSync(filePath));
+  vi.mocked(realpathSync.native).mockImplementation((filePath) =>
+    String(vol.realpathSync(filePath))
+  );
+});
 
 describe('findStoriesByComponent', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    vi.mocked(existsSync).mockReturnValue(true);
-  });
-
-  it('enriches matches from the story index', async () => {
-    storiesForFiles.mockResolvedValue([
-      [
-        { storyFile: './src/Button.stories.tsx', depth: 1 },
-        { storyFile: './src/Button.stories.tsx', depth: 1 },
-      ],
-    ]);
-
+  it('enriches every match with its story-index metadata', async () => {
     const result = await findStoriesByComponent({
-      componentPaths: ['/repo/src/Button.tsx'],
+      componentPaths: [BUTTON],
       index,
-      moduleGraph,
+      moduleGraph: readyGraph([{ storyFile: './src/Button.stories.tsx', depth: 1 }]),
     });
 
     expect(result).toEqual({
+      available: true,
       results: [
         {
-          componentPath: '/repo/src/Button.tsx',
+          componentPath: asGraphPath(BUTTON),
           matches: [
             {
               storyId: 'button--primary',
@@ -97,153 +115,93 @@ describe('findStoriesByComponent', () => {
     });
   });
 
-  it('marks pathNotFound and skips enrichment', async () => {
-    vi.mocked(existsSync).mockReturnValue(false);
-
+  it('clips matches past maxDistance and reports the distances that were dropped', async () => {
     const result = await findStoriesByComponent({
-      componentPaths: ['/repo/src/Missing.tsx'],
+      componentPaths: [BUTTON],
+      maxDistance: 1,
       index,
-      moduleGraph,
+      moduleGraph: readyGraph([
+        { storyFile: './src/Button.stories.tsx', depth: 1 },
+        { storyFile: './src/Input.stories.tsx', depth: 3 },
+      ]),
     });
 
     expect(result).toEqual({
+      available: true,
       results: [
         {
-          componentPath: '/repo/src/Missing.tsx',
-          matches: [],
-          pathNotFound: true,
+          componentPath: asGraphPath(BUTTON),
+          matches: [
+            expect.objectContaining({ storyId: 'button--primary', distance: 1 }),
+            expect.objectContaining({ storyId: 'button--secondary', distance: 1 }),
+          ],
+          clipped: { count: 1, distances: [3] },
         },
       ],
     });
-    expect(storiesForFiles).not.toHaveBeenCalled();
   });
 
-  it('clips matches beyond maxDistance and records clipped distances', async () => {
-    storiesForFiles.mockResolvedValue([
-      [
-        { storyFile: './src/Button.stories.tsx', depth: 1 },
-        { storyFile: './src/Input.stories.tsx', depth: 3 },
-      ],
-    ]);
-
+  it(`defaults the ceiling to ${DEFAULT_MAX_DISTANCE}`, async () => {
     const result = await findStoriesByComponent({
-      componentPaths: ['/repo/src/Button.tsx'],
-      maxDistance: 1,
+      componentPaths: [BUTTON],
       index,
-      moduleGraph,
+      moduleGraph: readyGraph([
+        { storyFile: './src/Button.stories.tsx', depth: DEFAULT_MAX_DISTANCE },
+        { storyFile: './src/Input.stories.tsx', depth: DEFAULT_MAX_DISTANCE + 1 },
+      ]),
     });
 
-    expect(result.results[0]?.matches).toHaveLength(2);
-    expect(result.results[0]?.clipped).toEqual({
-      count: 1,
-      distances: [3],
+    expect(result).toMatchObject({
+      available: true,
+      results: [
+        {
+          matches: [
+            expect.objectContaining({ storyId: 'button--primary' }),
+            expect.objectContaining({ storyId: 'button--secondary' }),
+          ],
+          clipped: { count: 1, distances: [DEFAULT_MAX_DISTANCE + 1] },
+        },
+      ],
     });
   });
 
-  it('defaults maxDistance to 3', async () => {
-    storiesForFiles.mockResolvedValue([
-      [
-        { storyFile: './src/Button.stories.tsx', depth: 3 },
-        { storyFile: './src/Input.stories.tsx', depth: 4 },
-      ],
-    ]);
-
+  it('omits `clipped` when nothing was dropped', async () => {
     const result = await findStoriesByComponent({
-      componentPaths: ['/repo/src/Button.tsx'],
+      componentPaths: [BUTTON],
       index,
-      moduleGraph,
+      moduleGraph: readyGraph([{ storyFile: './src/Button.stories.tsx', depth: 1 }]),
     });
 
-    expect(result.results[0]?.matches.map((m) => m.storyId)).toEqual([
-      'button--primary',
-      'button--secondary',
-    ]);
-    expect(result.results[0]?.clipped).toEqual({ count: 1, distances: [4] });
-  });
-});
-
-describe('resolveComponentMatches', () => {
-  const existingPath = '/repo/src/Button.tsx';
-  const missingPath = `${existingPath}.missing`;
-  let graphResults: Array<Array<{ storyFile: string; depth: number }>>;
-  let graphError: Error | undefined;
-
-  beforeEach(async () => {
-    const memfs = await vi.importActual<typeof import('memfs')>('memfs');
-
-    vi.clearAllMocks();
-    vol.reset();
-    vol.fromNestedJSON({ [existingPath]: '' });
-    vi.mocked(existsSync).mockImplementation(memfs.fs.existsSync as typeof existsSync);
-    graphResults = [];
-    graphError = undefined;
-    storiesForFiles.mockImplementation(async () => {
-      if (graphError) {
-        throw graphError;
-      }
-      return graphResults;
+    expect(result).toEqual({
+      available: true,
+      results: [expect.not.objectContaining({ clipped: expect.anything() })],
     });
   });
 
-  afterAll(() => {
-    vol.reset();
-  });
-
-  it('maps existing component files to story ids', async () => {
-    graphResults = [[{ storyFile: './src/Button.stories.tsx', depth: 1 }]];
-
-    await expect(
-      resolveComponentMatches({ componentPaths: [existingPath], index, moduleGraph })
-    ).resolves.toEqual([
-      {
-        componentPath: existingPath,
-        matches: [
-          { storyId: 'button--primary', depth: 1 },
-          { storyId: 'button--secondary', depth: 1 },
-        ],
-      },
-    ]);
-  });
-
-  it('marks paths that do not exist', async () => {
-    graphResults = [[]];
-
-    await expect(
-      resolveComponentMatches({ componentPaths: [missingPath], index, moduleGraph })
-    ).resolves.toEqual([
-      {
-        componentPath: missingPath,
-        matches: [],
-        pathNotFound: true,
-      },
-    ]);
-  });
-
-  it('keeps each story id at its shortest depth', async () => {
-    graphResults = [
-      [
-        { storyFile: './src/Button.stories.tsx', depth: 3 },
-        { storyFile: './src/Button.stories.tsx', depth: 1 },
-      ],
-    ];
-
-    const [result] = await resolveComponentMatches({
-      componentPaths: [existingPath],
+  it('passes `pathNotFound` through without querying the reverse index', async () => {
+    const result = await findStoriesByComponent({
+      componentPaths: [MISSING],
       index,
-      moduleGraph,
+      moduleGraph: readyGraph([{ storyFile: './src/Button.stories.tsx', depth: 1 }]),
     });
 
-    expect(result.matches).toEqual([
-      { storyId: 'button--primary', depth: 1 },
-      { storyId: 'button--secondary', depth: 1 },
-    ]);
+    expect(result).toEqual({
+      available: true,
+      results: [{ componentPath: asGraphPath(MISSING), matches: [], pathNotFound: true }],
+    });
+    expect(storiesForFiles).not.toHaveBeenCalled();
   });
 
-  it('returns empty matches when the module graph errors', async () => {
-    graphError = new Error('graph failed');
+  it('reports the graph as unavailable rather than as a component without stories', async () => {
+    const result = await findStoriesByComponent({
+      componentPaths: [BUTTON],
+      index,
+      moduleGraph: undefined,
+    });
 
-    await expect(
-      resolveComponentMatches({ componentPaths: [existingPath], index, moduleGraph })
-    ).resolves.toEqual([{ componentPath: existingPath, matches: [] }]);
+    expect(result).toEqual({
+      available: false,
+      reason: expect.stringMatching(/module graph is unavailable/i),
+    });
   });
 });
diff --git a/code/core/src/shared/open-service/toolsets/stories/find-by-component.ts b/code/core/src/shared/open-service/toolsets/stories/find-by-component.ts
index bf46bc1c691c..7414d4f05b2c 100644
--- a/code/core/src/shared/open-service/toolsets/stories/find-by-component.ts
+++ b/code/core/src/shared/open-service/toolsets/stories/find-by-component.ts
@@ -1,26 +1,18 @@
-import { existsSync } from 'node:fs';
-
 import type { StoryIndex } from 'storybook/internal/types';
 
-import { isAbsolute, join } from 'pathe';
-
-import type { ModuleGraphService } from '../../services/module-graph/definition.ts';
 import type { FindByComponentOutput } from './definition.ts';
+import {
+  resolveComponentStories,
+  type ComponentStoryDepth,
+  type ModuleGraphAccess,
+} from './resolve-component-stories.ts';
 
-/** Default import-graph distance ceiling (mirrors addon-mcp). */
+/** Default import-graph distance ceiling. */
 export const DEFAULT_MAX_DISTANCE = 3;
 
-export type ComponentStoryDepth = {
-  storyId: string;
-  depth: number;
-};
-
-export type ResolveComponentMatchesResult = {
-  /** Echo of the caller's input path (normalized by the resolver). */
-  componentPath: string;
-  matches: ComponentStoryDepth[];
-  /** `true` when no file exists at the resolved path. */
-  pathNotFound?: boolean;
+export type ClippedByMaxDistance = {
+  count: number;
+  distances: number[];
 };
 
 export type FindStoriesByComponentParams = {
@@ -28,13 +20,19 @@ export type FindStoriesByComponentParams = {
   /** Maximum import-graph distance to include. Defaults to {@link DEFAULT_MAX_DISTANCE}. */
   maxDistance?: number;
   index: StoryIndex;
-  moduleGraph: ModuleGraphService;
+  moduleGraph: ModuleGraphAccess | undefined;
 };
 
-export type ClippedByMaxDistance = {
-  count: number;
-  distances: number[];
-};
+/**
+ * Either the per-path matches, or why the module graph could not answer.
+ *
+ * The unavailable case is distinct on purpose: reporting "no stories" when the graph is still
+ * building or the builder has no change detection would tell an agent that every component is
+ * unused.
+ */
+export type FindStoriesByComponentResult =
+  | { available: false; reason: string }
+  | { available: true; results: FindByComponentOutput['results'] };
 
 function applyMaxDistance(
   depths: ComponentStoryDepth[],
@@ -44,12 +42,12 @@ function applyMaxDistance(
   const clippedDistances = new Set<number>();
   let clippedCount = 0;
 
-  for (const d of depths) {
-    if (d.depth <= maxDistance) {
-      kept.push(d);
+  for (const depth of depths) {
+    if (depth.depth <= maxDistance) {
+      kept.push(depth);
     } else {
       clippedCount++;
-      clippedDistances.add(d.depth);
+      clippedDistances.add(depth.depth);
     }
   }
 
@@ -64,79 +62,6 @@ function applyMaxDistance(
   return { kept, clipped };
 }
 
-export async function resolveComponentMatches({
-  componentPaths,
-  index,
-  moduleGraph,
-}: {
-  componentPaths: string[];
-  index: StoryIndex;
-  moduleGraph: ModuleGraphService;
-}): Promise<ResolveComponentMatchesResult[]> {
-  // Exists-check first so missing paths skip the graph query cost when every path is missing.
-  // Mixed present/missing still queries once for the batch (module-graph API is bulk).
-  const absolutePaths = componentPaths.map((componentPath) =>
-    isAbsolute(componentPath) ? componentPath : join(process.cwd(), componentPath)
-  );
-  const missing = absolutePaths.map((absolute) => !existsSync(absolute));
-  if (missing.every(Boolean)) {
-    return componentPaths.map((componentPath) => ({
-      componentPath,
-      matches: [],
-      pathNotFound: true,
-    }));
-  }
-
-  let storiesForFiles: Array<Array<{ storyFile: string; depth: number }>>;
-  try {
-    storiesForFiles = await moduleGraph.queries.storiesForFiles.loaded({
-      files: componentPaths,
-    });
-  } catch {
-    return componentPaths.map((componentPath, position) =>
-      missing[position]
-        ? { componentPath, matches: [], pathNotFound: true }
-        : { componentPath, matches: [] }
-    );
-  }
-
-  const storyIdsByFile = new Map<string, string[]>();
-  for (const entry of Object.values(index.entries)) {
-    if (entry.type !== 'story' || entry.importPath.startsWith('virtual:')) {
-      continue;
-    }
-    const key = entry.importPath.startsWith('./') ? entry.importPath : `./${entry.importPath}`;
-    const ids = storyIdsByFile.get(key) ?? [];
-    ids.push(entry.id);
-    storyIdsByFile.set(key, ids);
-  }
-
-  return componentPaths.map((componentPath, position) => {
-    if (missing[position]) {
-      return { componentPath, matches: [], pathNotFound: true };
-    }
-
-    const byStoryId = new Map<string, number>();
-    for (const { storyFile, depth } of storiesForFiles[position] ?? []) {
-      for (const storyId of storyIdsByFile.get(storyFile) ?? []) {
-        const existing = byStoryId.get(storyId);
-        if (existing === undefined || depth < existing) {
-          byStoryId.set(storyId, depth);
-        }
-      }
-    }
-
-    return {
-      componentPath,
-      matches: [...byStoryId.entries()]
-        .map(([storyId, depth]) => ({ storyId, depth }))
-        .sort((a, b) =>
-          a.depth !== b.depth ? a.depth - b.depth : a.storyId.localeCompare(b.storyId)
-        ),
-    };
-  });
-}
-
 /**
  * Resolves reverse-graph matches into the `stories.findByComponent` output, applying
  * `maxDistance` clipping and story-index enrichment.
@@ -146,10 +71,20 @@ export async function findStoriesByComponent({
   maxDistance = DEFAULT_MAX_DISTANCE,
   index,
   moduleGraph,
-}: FindStoriesByComponentParams): Promise<FindByComponentOutput> {
-  const resolved = await resolveComponentMatches({ componentPaths, index, moduleGraph });
+}: FindStoriesByComponentParams): Promise<FindStoriesByComponentResult> {
+  const lookup = await resolveComponentStories(
+    { componentPaths },
+    { getStoryIndex: async () => index, moduleGraph }
+  );
+
+  if (!lookup.available) {
+    return {
+      available: false,
+      reason: lookup.reason ?? "Storybook's story module graph is unavailable.",
+    };
+  }
 
-  const results: FindByComponentOutput['results'] = resolved.map((entry) => {
+  const results = (lookup.results ?? []).map((entry) => {
     if (entry.pathNotFound) {
       return { componentPath: entry.componentPath, matches: [], pathNotFound: true };
     }
@@ -176,5 +111,5 @@ export async function findStoriesByComponent({
       : { componentPath: entry.componentPath, matches };
   });
 
-  return { results };
+  return { available: true, results };
 }
diff --git a/code/core/src/shared/open-service/toolsets/stories/format.ts b/code/core/src/shared/open-service/toolsets/stories/format.ts
index c3eee4b44ac4..c877bb4eb450 100644
--- a/code/core/src/shared/open-service/toolsets/stories/format.ts
+++ b/code/core/src/shared/open-service/toolsets/stories/format.ts
@@ -1,74 +1,239 @@
+import type { ToolsetCtx } from '../../toolset-definition.ts';
+import { getRef } from '../../toolset-names.ts';
 import type {
   ChangedStoriesOutput,
   FindByComponentOutput,
   PreviewStoriesOutput,
 } from './definition.ts';
 
-/** Formats preview URLs as compact Markdown for humans and agents. */
-export function formatPreviewStories({ stories }: PreviewStoriesOutput): string {
-  const lines = ['# Story previews'];
+function pluralize(count: number, singular: string, plural = `${singular}s`): string {
+  return count === 1 ? singular : plural;
+}
 
-  for (const story of stories) {
-    if ('error' in story) {
-      lines.push(`- Error: ${story.error}`);
-    } else {
-      lines.push(`- ${story.title} - ${story.name}`, `  ${story.previewUrl}`);
-    }
+/**
+ * Recovery nudge for the review exit ramp: agents that skip the review tool end visual work on
+ * exactly this call, so the result itself has to contradict that while a step remains to recover in.
+ */
+function previewReviewNudge(ctx: ToolsetCtx): string {
+  const reviewTool = getRef(ctx)('review.create');
+  return `These preview links are for iterating or sharing a specific story — they are not how visual work or a browse request ends. The ${reviewTool} tool is available in this session: if you are finishing visually observable work or showing a set of stories, publish the review with **${reviewTool}** and link that instead.`;
+}
+
+/**
+ * Splits a preview result into the text blocks a consumer shows.
+ *
+ * MCP renders one block per URL, so this returns the blocks; {@link formatPreviewStories} joins
+ * them for consumers that want a single string.
+ */
+export function formatPreviewStoryBlocks(
+  { stories }: PreviewStoriesOutput,
+  ctx: ToolsetCtx,
+  { reviewEnabled = false }: { reviewEnabled?: boolean } = {}
+): string[] {
+  if (ctx.consumer !== 'mcp') {
+    return [
+      '# Story previews',
+      ...stories.map((story) =>
+        'error' in story
+          ? `- Error: ${story.error}`
+          : `- ${story.title} - ${story.name}\n  ${story.previewUrl}`
+      ),
+    ];
   }
 
-  return lines.join('\n');
+  const blocks = stories.map((story) => ('error' in story ? story.error : story.previewUrl));
+
+  // An all-error result has nothing to curate, so the nudge only applies once a URL resolved.
+  if (reviewEnabled && stories.some((story) => 'previewUrl' in story)) {
+    blocks.push(previewReviewNudge(ctx));
+  }
+
+  return blocks;
 }
 
-/** Formats changed stories as compact Markdown for humans and agents. */
-export function formatChangedStories({
-  stories,
-  counts,
-  unreachableFiles,
-}: ChangedStoriesOutput): string {
-  const lines = [
-    '# Changed stories',
-    `New: ${counts.new}, modified: ${counts.modified}, affected: ${counts.affected}`,
-  ];
+export function formatPreviewStories(
+  data: PreviewStoriesOutput,
+  ctx: ToolsetCtx,
+  options: { reviewEnabled?: boolean } = {}
+): string | string[] {
+  const blocks = formatPreviewStoryBlocks(data, ctx, options);
+  // MCP renders one text block per URL; the CLI list reads better as one joined document.
+  return ctx.consumer === 'mcp' ? blocks : blocks.join('\n');
+}
 
-  for (const story of stories) {
-    lines.push(
-      `- [${story.statusValue.replace('status-value:', '')}] ${story.title} - ${story.name}`
-    );
-  }
+const BANNER_INLINE_LIMIT = 3;
 
-  if (unreachableFiles.length > 0) {
-    lines.push('', '## Unreachable files', ...unreachableFiles.map((file) => `- ${file}`));
+/**
+ * Front-loaded coverage warning.
+ *
+ * Duplicates {@link formatPartialCoverageHint}'s information on purpose: with a long story list the
+ * tail hint can land past a host's tool-output truncation cap, and the leading banner is the part
+ * that survives.
+ */
+function formatPartialCoverageBanner(unreachable: string[]): string {
+  if (unreachable.length === 0) {
+    return '';
   }
+  const fileList =
+    unreachable.length <= BANNER_INLINE_LIMIT
+      ? unreachable.join(', ')
+      : `${unreachable.slice(0, BANNER_INLINE_LIMIT).join(', ')}, +${unreachable.length - BANNER_INLINE_LIMIT} more`;
+  return `⚠ Coverage gap: ${unreachable.length} modified ${pluralize(unreachable.length, 'file')} unreachable from any story (${fileList}) — full sanity-check note at end of this response.\n\n`;
+}
 
-  return lines.join('\n');
+/** Hint appended to an empty changed-stories response. */
+function formatUnreachableHint(unreachable: string[], ctx: ToolsetCtx): string {
+  if (unreachable.length === 0) {
+    return '';
+  }
+  const lines = unreachable.map((file) => `- ${file}`).join('\n');
+  return `\n\nThe following working-tree file(s) are modified but unreachable from any story (no static import path connects them — they are likely theme tokens, decorators, or other Storybook-preview-runtime files):\n${lines}\n\nFor these, grep the codebase for their exports (e.g. specific tokens or symbols) to find runtime consumers, then call \`${getRef(ctx)('stories.findByComponent')}\` with those consumer file paths.`;
 }
 
-/** Formats component-to-story matches as compact Markdown for humans and agents. */
-export function formatFindByComponent({ results }: FindByComponentOutput): string {
-  const lines = ['# Stories by component'];
+/**
+ * Hint for the non-empty case: the changed list is real but may be stale with respect to files the
+ * diff also touched that no story reaches, so the agent has to check coverage rather than trust it.
+ */
+function formatPartialCoverageHint(unreachable: string[], ctx: ToolsetCtx): string {
+  if (unreachable.length === 0) {
+    return '';
+  }
+  const lines = unreachable.map((file) => `- ${file}`).join('\n');
+  return `\n\nCoverage sanity check: the working tree also contains modified file(s) that aren't reachable from any story above (no static import path connects them — typically theme tokens, decorators, or other preview-runtime files):\n${lines}\n\nThe list above is real but may be stale w.r.t. these files — they're often left over from an earlier sub-change in the same diff. Before composing a review, grep the codebase for their exports and call \`${getRef(ctx)('stories.findByComponent')}\` with the runtime consumers' file paths. Do not assume the list above already covers them, and never invent story IDs to fill the gap.`;
+}
 
-  for (const result of results) {
-    lines.push(`## ${result.componentPath}`);
-    if (result.pathNotFound) {
-      lines.push('Path not found.');
-      continue;
-    }
-    if (result.matches.length === 0) {
-      lines.push('No matching stories.');
-      continue;
+export function formatChangedStories(
+  { stories, counts, unreachableFiles }: ChangedStoriesOutput,
+  ctx: ToolsetCtx,
+  { reviewEnabled = false }: { reviewEnabled?: boolean } = {}
+): string {
+  if (ctx.consumer !== 'mcp') {
+    const lines = [
+      '# Changed stories',
+      `New: ${counts.new}, modified: ${counts.modified}, affected: ${counts.affected}`,
+      ...stories.map(
+        (story) =>
+          `- [${story.statusValue.replace('status-value:', '')}] ${story.title} - ${story.name}`
+      ),
+    ];
+    if (unreachableFiles.length > 0) {
+      lines.push('', '## Unreachable files', ...unreachableFiles.map((file) => `- ${file}`));
     }
-    for (const story of result.matches) {
-      lines.push(
-        `- ${story.title} - ${story.name} (${story.storyId}, distance ${story.distance})`,
-        `  ${story.importPath}`
-      );
+    return lines.join('\n');
+  }
+
+  if (stories.length === 0) {
+    return `No new, modified, or related stories detected.${formatUnreachableHint(unreachableFiles, ctx)}`;
+  }
+
+  const buckets = {
+    new: stories.filter((story) => story.statusValue === 'status-value:new'),
+    modified: stories.filter((story) => story.statusValue === 'status-value:modified'),
+    affected: stories.filter((story) => story.statusValue === 'status-value:affected'),
+  };
+
+  let text = `${formatPartialCoverageBanner(unreachableFiles)}Detected ${stories.length} changed stor${pluralize(stories.length, 'y', 'ies')} (${counts.new} new, ${counts.modified} modified, ${counts.affected} related).`;
+
+  // Front-loaded like the banner: host-side output caps can cut the tail of a long story list, and
+  // this next step is what keeps agents from ending visual work at preview URLs.
+  if (reviewEnabled) {
+    text += `\n\nNext: if the change is visually observable, publish the review now — call **${getRef(ctx)('review.create')}** curating these story IDs. That review link is how you finish; do not substitute individual preview URLs for it.`;
+  }
+
+  const serializeStory = ({
+    storyId,
+    title,
+    name,
+    importPath,
+  }: ChangedStoriesOutput['stories'][number]) =>
+    `- \`${storyId}\`: ${title} / ${name} (\`${importPath}\`)`;
+
+  if (buckets.new.length > 0) {
+    text += `\n\nNew stories:\n${buckets.new.map(serializeStory).join('\n')}`;
+  }
+  if (buckets.modified.length > 0) {
+    text += `\n\nModified stories:\n${buckets.modified.map(serializeStory).join('\n')}`;
+  }
+  if (buckets.affected.length > 0) {
+    text += `\n\nRelated stories:\n${buckets.affected.map(serializeStory).join('\n')}`;
+  }
+
+  return text + formatPartialCoverageHint(unreachableFiles, ctx);
+}
+
+function formatClippedTail(
+  clipped: { count: number; distances: number[] },
+  maxDistance: number
+): string {
+  const { distances } = clipped;
+  const rangeText =
+    distances.length === 1
+      ? `distance ${distances[0]}`
+      : `distances ${distances[0]}..${distances[distances.length - 1]}`;
+  return `+${clipped.count} more ${pluralize(clipped.count, 'story', 'stories')} at ${rangeText} hidden by \`maxDistance: ${maxDistance}\``;
+}
+
+/** Renders one component's matches, bucketed by import-graph distance. */
+export function serializeComponentSection(
+  { componentPath, matches, clipped, pathNotFound }: FindByComponentOutput['results'][number],
+  maxDistance: number
+): string {
+  if (pathNotFound) {
+    return `${componentPath}: path does not exist on disk — re-check the path you sent.`;
+  }
+
+  // "No stories at all" and "the cap filtered everything out" need different follow-ups.
+  if (matches.length === 0) {
+    if (clipped && clipped.count > 0) {
+      return `${componentPath}: no stories within \`maxDistance: ${maxDistance}\` — ${formatClippedTail(clipped, maxDistance)}.`;
     }
-    if (result.clipped) {
+    return `${componentPath}: no stories found`;
+  }
+
+  const byDistance = new Map<number, FindByComponentOutput['results'][number]['matches']>();
+  for (const match of matches) {
+    const bucket = byDistance.get(match.distance) ?? [];
+    bucket.push(match);
+    byDistance.set(match.distance, bucket);
+  }
+
+  const distances = [...byDistance.keys()].sort((a, b) => a - b);
+  const componentCount = new Set(matches.map((match) => match.title)).size;
+  const bucketSummary = distances.map((d) => `d${d}=${byDistance.get(d)!.length}`).join(', ');
+  const lines = [
+    `${componentPath}:`,
+    `→ ${matches.length} ${pluralize(matches.length, 'story', 'stories')} across ${componentCount} ${pluralize(componentCount, 'component')}, distances ${distances[0]}..${distances[distances.length - 1]} (${bucketSummary})`,
+  ];
+
+  for (const distance of distances) {
+    lines.push(`distance ${distance}:`);
+    for (const match of byDistance.get(distance)!) {
       lines.push(
-        `Clipped ${result.clipped.count} match${result.clipped.count === 1 ? '' : 'es'} at distance${result.clipped.distances.length === 1 ? '' : 's'} ${result.clipped.distances.join(', ')}.`
+        `  - \`${match.storyId}\`: ${match.title} / ${match.name} (\`${match.importPath}\`)`
       );
     }
   }
 
+  if (clipped && clipped.count > 0) {
+    lines.push(`  (${formatClippedTail(clipped, maxDistance)}.)`);
+  }
+
   return lines.join('\n');
 }
+
+export function formatFindByComponent(
+  { results, maxDistance }: FindByComponentOutput,
+  ctx: ToolsetCtx
+): string {
+  if (ctx.consumer !== 'mcp') {
+    const lines = ['# Stories by component'];
+    for (const result of results) {
+      lines.push(`## ${result.componentPath}`, serializeComponentSection(result, maxDistance));
+    }
+    return lines.join('\n');
+  }
+
+  return results.length === 0
+    ? 'No component paths provided.'
+    : results.map((result) => serializeComponentSection(result, maxDistance)).join('\n\n');
+}
diff --git a/code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.test.ts b/code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.test.ts
new file mode 100644
index 000000000000..bd0232b155ed
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.test.ts
@@ -0,0 +1,336 @@
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+
+import type { StoryIndex } from 'storybook/internal/types';
+
+import { vol } from 'memfs';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  ModuleGraphAccess,
+  ModuleGraphStatus,
+  ModuleGraphStoryHit,
+  ResolveComponentStoriesDeps,
+} from './resolve-component-stories.ts';
+import { resolveComponentStories } from './resolve-component-stories.ts';
+
+vi.mock('node:fs', { spy: true });
+
+// `path.resolve` gives the fixture a drive letter on Windows, matching what the
+// resolver's own `resolve(workingDir, …)` produces there.
+const FAKE_WORKING_DIR = path.resolve('/repo');
+const BADGE_ABS = path.join(FAKE_WORKING_DIR, 'src/components/Badge/Badge.tsx');
+const BADGE_BARREL = path.join(FAKE_WORKING_DIR, 'src/components/Badge/index.ts');
+
+/** The forward-slashed form the resolver queries the module graph with. */
+const asGraphPath = (p: string) => path.normalize(p).replaceAll('\\', '/');
+const storyFileAbs = (rel: string) => path.join(FAKE_WORKING_DIR, rel);
+
+/**
+ * Stubs the module-graph service surface. `storiesByFile` keys are the forward-slashed absolute
+ * input paths the resolver looks up; values are the relative story-file hits the graph returns.
+ */
+function moduleGraphStub(opts: {
+  status?: ModuleGraphStatus;
+  storiesByFile?: Record<string, ModuleGraphStoryHit[]>;
+}): ModuleGraphAccess {
+  const status: ModuleGraphStatus = opts.status ?? { value: 'ready' };
+  const storiesByFile = opts.storiesByFile ?? {};
+  return {
+    queries: {
+      status: { loaded: async () => status },
+      storiesForFiles: {
+        loaded: async ({ files }) => files.map((file) => storiesByFile[file] ?? []),
+      },
+    },
+  };
+}
+
+function buildStoryIndex(byFile: Record<string, string[]>): StoryIndex {
+  const entries: StoryIndex['entries'] = {};
+  for (const [absStoryFile, ids] of Object.entries(byFile)) {
+    const relative = path.relative(FAKE_WORKING_DIR, absStoryFile);
+    for (const id of ids) {
+      entries[id] = {
+        type: 'story',
+        subtype: 'story',
+        id,
+        name: id,
+        title: id,
+        importPath: relative,
+        tags: [],
+      } as StoryIndex['entries'][string];
+    }
+  }
+  return { v: 5, entries };
+}
+
+function depsFor(
+  byFile: Record<string, string[]> = {},
+  moduleGraph: ModuleGraphAccess | undefined = moduleGraphStub({})
+): ResolveComponentStoriesDeps {
+  const index = buildStoryIndex(byFile);
+  return { getStoryIndex: async () => index, moduleGraph, workingDir: FAKE_WORKING_DIR };
+}
+
+beforeEach(() => {
+  vol.reset();
+  vol.fromNestedJSON({ [BADGE_ABS]: '' });
+  vi.mocked(existsSync).mockImplementation((filePath) => vol.existsSync(filePath));
+  vi.mocked(realpathSync.native).mockImplementation((filePath) =>
+    String(vol.realpathSync(filePath))
+  );
+});
+
+describe('resolveComponentStories', () => {
+  it('strips trailing slashes so `Badge.tsx/` queries the file, not the parent-name barrel', async () => {
+    // Regression for the silent-corruption bug: when a caller pastes
+    // `Badge/Badge.tsx/`, the trailing slash flipped `basename === dirname`
+    // in the barrel-expansion heuristic and we returned stories that
+    // consumed the *barrel* (`Badge/index.ts`) instead of `Badge.tsx`.
+    const graph = moduleGraphStub({
+      storiesByFile: {
+        [asGraphPath(BADGE_ABS)]: [
+          { storyFile: './src/A.stories.tsx', depth: 1 },
+          { storyFile: './src/B.stories.tsx', depth: 2 },
+        ],
+        [asGraphPath(BADGE_BARREL)]: [{ storyFile: './src/C.stories.tsx', depth: 1 }],
+      },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: [`${BADGE_ABS}/`] },
+      depsFor(
+        {
+          [storyFileAbs('src/A.stories.tsx')]: ['a--default'],
+          [storyFileAbs('src/B.stories.tsx')]: ['b--default'],
+          [storyFileAbs('src/C.stories.tsx')]: ['c--default'],
+        },
+        graph
+      )
+    );
+    expect(res.available).toBe(true);
+    expect(res.results?.[0]?.matches.map((m) => m.storyId).sort()).toEqual([
+      'a--default',
+      'b--default',
+    ]);
+    // And critically does NOT include the barrel-only consumer:
+    expect(res.results?.[0]?.matches.map((m) => m.storyId)).not.toContain('c--default');
+  });
+
+  it('resolves relative paths against the workingDir', async () => {
+    const graph = moduleGraphStub({
+      storiesByFile: { [asGraphPath(BADGE_ABS)]: [{ storyFile: './src/A.stories.tsx', depth: 1 }] },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: ['src/components/Badge/Badge.tsx'] },
+      depsFor({ [storyFileAbs('src/A.stories.tsx')]: ['a--default'] }, graph)
+    );
+    expect(res.results?.[0]?.matches.map((m) => m.storyId)).toEqual(['a--default']);
+  });
+
+  it('normalizes redundant slashes (`/services//webapp/`)', async () => {
+    const graph = moduleGraphStub({
+      storiesByFile: { [asGraphPath(BADGE_ABS)]: [{ storyFile: './src/A.stories.tsx', depth: 1 }] },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: [`${FAKE_WORKING_DIR}${path.sep}src//components/Badge/Badge.tsx`] },
+      depsFor({ [storyFileAbs('src/A.stories.tsx')]: ['a--default'] }, graph)
+    );
+    expect(res.results?.[0]?.matches.map((m) => m.storyId)).toEqual(['a--default']);
+  });
+
+  it('maps `./`-less story index importPaths to the relative hits the module graph returns', async () => {
+    // The story index here uses `src/A.stories.tsx` (no `./`); the module graph returns
+    // `./src/A.stories.tsx`. The resolver normalizes both to the same form so they line up.
+    const graph = moduleGraphStub({
+      storiesByFile: { [asGraphPath(BADGE_ABS)]: [{ storyFile: './src/A.stories.tsx', depth: 3 }] },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      depsFor({ [storyFileAbs('src/A.stories.tsx')]: ['a--default'] }, graph)
+    );
+    expect(res.results?.[0]?.matches).toEqual([{ storyId: 'a--default', depth: 3 }]);
+  });
+
+  it('skips virtual: importPath entries when building the file→storyIds map', async () => {
+    const graph = moduleGraphStub({
+      storiesByFile: { [asGraphPath(BADGE_ABS)]: [{ storyFile: './src/A.stories.tsx', depth: 1 }] },
+    });
+    const indexWithVirtual: StoryIndex = {
+      v: 5,
+      entries: {
+        'a--default': {
+          type: 'story',
+          subtype: 'story',
+          id: 'a--default',
+          name: 'Default',
+          title: 'A',
+          importPath: 'src/A.stories.tsx',
+          tags: [],
+        } as StoryIndex['entries'][string],
+        'virtual--page': {
+          type: 'story',
+          subtype: 'story',
+          id: 'virtual--page',
+          name: 'Virtual',
+          title: 'V',
+          importPath: 'virtual:storybook/auto-docs',
+          tags: [],
+        } as StoryIndex['entries'][string],
+      },
+    };
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      {
+        getStoryIndex: async () => indexWithVirtual,
+        moduleGraph: graph,
+        workingDir: FAKE_WORKING_DIR,
+      }
+    );
+    expect(res.results?.[0]?.matches.map((m) => m.storyId)).toEqual(['a--default']);
+  });
+
+  it('expands barrel targets and merges the minimum depth across them', async () => {
+    // `Badge/Badge.tsx` ↔ `Badge/index.ts`: both reach `A.stories.tsx`, but via different
+    // depths. The merge must keep the shorter (barrel) path's depth.
+    vol.fromNestedJSON({ [BADGE_BARREL]: '' });
+    const graph = moduleGraphStub({
+      storiesByFile: {
+        [asGraphPath(BADGE_ABS)]: [{ storyFile: './src/A.stories.tsx', depth: 2 }],
+        [asGraphPath(BADGE_BARREL)]: [{ storyFile: './src/A.stories.tsx', depth: 1 }],
+      },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      depsFor({ [storyFileAbs('src/A.stories.tsx')]: ['a--default'] }, graph)
+    );
+    expect(res.results?.[0]?.matches).toEqual([{ storyId: 'a--default', depth: 1 }]);
+  });
+
+  it('canonicalises wrong-case input so case-insensitive filesystems still hit the index', async () => {
+    const wrongCase = path.join(FAKE_WORKING_DIR, 'src/components/BADGE/Badge.tsx');
+    vi.mocked(realpathSync.native).mockImplementation((filePath) =>
+      asGraphPath(String(filePath)) === asGraphPath(wrongCase)
+        ? BADGE_ABS
+        : String(vol.realpathSync(filePath))
+    );
+    // Only the canonical spelling is a key in the reverse index.
+    const graph = moduleGraphStub({
+      storiesByFile: { [asGraphPath(BADGE_ABS)]: [{ storyFile: './src/A.stories.tsx', depth: 1 }] },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: [wrongCase] },
+      depsFor({ [storyFileAbs('src/A.stories.tsx')]: ['a--default'] }, graph)
+    );
+    expect(res.results?.[0]?.matches).toEqual([{ storyId: 'a--default', depth: 1 }]);
+  });
+
+  it('dedupes repeated component paths into a single result', async () => {
+    const graph = moduleGraphStub({
+      storiesByFile: { [asGraphPath(BADGE_ABS)]: [{ storyFile: './src/A.stories.tsx', depth: 1 }] },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS, BADGE_ABS] },
+      depsFor({ [storyFileAbs('src/A.stories.tsx')]: ['a--default'] }, graph)
+    );
+    expect(res.results).toHaveLength(1);
+    expect(res.results?.[0]?.matches.map((m) => m.storyId)).toEqual(['a--default']);
+  });
+
+  it('sorts matches by depth, then by story id', async () => {
+    const graph = moduleGraphStub({
+      storiesByFile: {
+        [asGraphPath(BADGE_ABS)]: [
+          { storyFile: './src/A.stories.tsx', depth: 2 },
+          { storyFile: './src/B.stories.tsx', depth: 1 },
+        ],
+      },
+    });
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      depsFor(
+        {
+          [storyFileAbs('src/A.stories.tsx')]: ['b--second', 'a--first'],
+          [storyFileAbs('src/B.stories.tsx')]: ['z--closest'],
+        },
+        graph
+      )
+    );
+    expect(res.results?.[0]?.matches).toEqual([
+      { storyId: 'z--closest', depth: 1 },
+      { storyId: 'a--first', depth: 2 },
+      { storyId: 'b--second', depth: 2 },
+    ]);
+  });
+
+  it('flags pathNotFound when the component file does not exist on disk', async () => {
+    const ghost = path.join(FAKE_WORKING_DIR, 'src/components/Ghost/Ghost.tsx');
+    const res = await resolveComponentStories({ componentPaths: [ghost] }, depsFor());
+    expect(res.available).toBe(true);
+    expect(res.results?.[0]?.pathNotFound).toBe(true);
+    expect(res.results?.[0]?.matches).toEqual([]);
+  });
+
+  it('rethrows non-ENOENT realpath failures instead of misreporting them as pathNotFound', async () => {
+    // A permission/IO error is a real failure, not a missing path — surfacing it as
+    // `pathNotFound` would hide the underlying cause, so the resolver must let it propagate.
+    const locked = path.join(FAKE_WORKING_DIR, 'src/components/Locked/Locked.tsx');
+    vi.mocked(realpathSync.native).mockImplementation((filePath) => {
+      if (asGraphPath(String(filePath)) === asGraphPath(locked)) {
+        throw Object.assign(new Error(`EACCES: ${locked}`), { code: 'EACCES' });
+      }
+      return String(vol.realpathSync(filePath));
+    });
+    await expect(resolveComponentStories({ componentPaths: [locked] }, depsFor())).rejects.toThrow(
+      /EACCES/
+    );
+  });
+
+  it('returns available:false when the module graph service is not registered', async () => {
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      { ...depsFor(), moduleGraph: undefined }
+    );
+    expect(res.available).toBe(false);
+    expect(res.reason).toMatch(/module graph is unavailable/i);
+    expect(res.results).toBeUndefined();
+  });
+
+  it('returns available:false while the graph is still booting', async () => {
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      depsFor({}, moduleGraphStub({ status: { value: 'booting' } }))
+    );
+    expect(res.available).toBe(false);
+    expect(res.reason).toMatch(/hasn't built yet/i);
+  });
+
+  it('returns available:false with the remedy the agent needs when unavailable', async () => {
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      depsFor(
+        {},
+        moduleGraphStub({
+          status: { value: 'unavailable', reason: 'builder does not support change detection' },
+        })
+      )
+    );
+    expect(res.available).toBe(false);
+    // The service's cause plus the remedy: the agent is told what failed and what to change.
+    expect(res.reason).toBe(
+      "Storybook's story dependency graph is unavailable: builder does not support change detection. Make sure the dev server is running with a builder that supports change detection."
+    );
+  });
+
+  it('returns available:false with the serialized error message when the graph errored', async () => {
+    const res = await resolveComponentStories(
+      { componentPaths: [BADGE_ABS] },
+      depsFor(
+        {},
+        moduleGraphStub({ status: { value: 'error', error: { message: 'boom while parsing' } } })
+      )
+    );
+    expect(res.available).toBe(false);
+    expect(res.reason).toMatch(/boom while parsing/);
+  });
+});
diff --git a/code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.ts b/code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.ts
new file mode 100644
index 000000000000..ac038153f631
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/stories/resolve-component-stories.ts
@@ -0,0 +1,305 @@
+import { existsSync, realpathSync } from 'node:fs';
+
+import type { StoryIndex } from 'storybook/internal/types';
+
+import { basename, dirname, extname, join, normalize, resolve } from 'pathe';
+
+import type { ModuleGraphServiceState } from '../../services/module-graph/definition.ts';
+
+/** Lifecycle status reported by the `core/module-graph` service. */
+export type ModuleGraphStatus = ModuleGraphServiceState['status'];
+
+/** One reverse-index hit: a story file (story-index-relative path) and its BFS import depth. */
+export type ModuleGraphStoryHit = {
+  /** Story-index-style relative path such as `./src/Button.stories.tsx`. */
+  storyFile: string;
+  /** Breadth-first-search depth: shortest number of import edges to the story file. */
+  depth: number;
+};
+
+/**
+ * The slice of the `core/module-graph` service this resolver needs. Structural so the caller can
+ * inject the real service (or a stub) without this module doing service lookup itself.
+ */
+export type ModuleGraphAccess = {
+  queries: {
+    status: { loaded: (input?: undefined) => Promise<ModuleGraphStatus> };
+    /** Positional: result `i` corresponds to input `files[i]`. */
+    storiesForFiles: {
+      loaded: (input: { files: string[] }) => Promise<Array<ModuleGraphStoryHit[] | undefined>>;
+    };
+  };
+};
+
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'] as const;
+const INDEX_BASENAMES = SOURCE_EXTENSIONS.map((ext) => `index${ext}`);
+
+/** Storybook import paths always use forward slashes, even on Windows. */
+function slash(filePath: string): string {
+  return filePath.replace(/\\/g, '/');
+}
+
+/**
+ * Expands `Foo/Foo.tsx` ↔ `Foo/index.tsx` so a query against either form hits stories that
+ * imported the other. Only expands when filename or dirname clearly names the directory's
+ * main export.
+ */
+function expandBarrelTargets(absoluteComponentPath: string): string[] {
+  const targets = new Set<string>([absoluteComponentPath]);
+  const dir = dirname(absoluteComponentPath);
+  const ext = extname(absoluteComponentPath);
+  const base = basename(absoluteComponentPath, ext);
+  const dirName = basename(dir);
+
+  if (base.toLowerCase() === 'index') {
+    for (const candidateExt of SOURCE_EXTENSIONS) {
+      const candidate = join(dir, `${dirName}${candidateExt}`);
+      if (existsSync(candidate)) {
+        targets.add(candidate);
+      }
+    }
+  } else if (base.toLowerCase() === dirName.toLowerCase()) {
+    for (const indexBasename of INDEX_BASENAMES) {
+      const candidate = join(dir, indexBasename);
+      if (existsSync(candidate)) {
+        targets.add(candidate);
+      }
+    }
+  }
+
+  // The module graph accepts absolute paths but normalizes them with forward slashes; `pathe`'s
+  // `normalize` emits forward slashes on Windows too, including for `realpath` output.
+  return [...targets].map((target) => normalize(target));
+}
+
+/**
+ * Canonicalises a path via `realpath`. Fixes silent misses on case-insensitive filesystems
+ * (macOS APFS) where `BUTTON/Button.tsx` and `Button/Button.tsx` resolve to the same file but
+ * only the canonical form is in the reverse-index keyset.
+ *
+ * Returns `undefined` if the path doesn't exist on disk — the caller surfaces that as a
+ * distinct "path not found" outcome rather than a generic "no stories".
+ */
+function canonicalise(absolutePath: string): string | undefined {
+  try {
+    return realpathSync.native(absolutePath);
+  } catch (err) {
+    // Only a missing path is "not found"; permission/IO errors are real failures and must not be
+    // silently misreported as `pathNotFound`, so rethrow anything that isn't ENOENT.
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Normalizes a story-index `importPath` to the `./`-prefixed, forward-slash form the module graph
+ * returns for its story files (e.g. `./src/Button.stories.tsx`). The module graph keys story files
+ * this way, so we match on it instead of the absolute path.
+ */
+function toStoryFileKey(importPath: string): string {
+  const normalized = slash(importPath);
+  if (normalized.startsWith('./') || normalized.startsWith('../')) {
+    return normalized;
+  }
+  return `./${normalized}`;
+}
+
+/**
+ * Map story-index-relative story-file path → story IDs declared in that file. Skips virtual entries.
+ * Keys match the `storyFile` values returned by the module graph's `storiesForFiles`.
+ */
+function buildStoryIdsByFile(storyIndex: StoryIndex): Map<string, Set<string>> {
+  const storyIdsByFile = new Map<string, Set<string>>();
+  for (const entry of Object.values(storyIndex.entries)) {
+    if (entry.type !== 'story' || entry.importPath.startsWith('virtual:')) {
+      continue;
+    }
+    const filePath = toStoryFileKey(entry.importPath);
+    let ids = storyIdsByFile.get(filePath);
+    if (!ids) {
+      ids = new Set<string>();
+      storyIdsByFile.set(filePath, ids);
+    }
+    ids.add(entry.id);
+  }
+  return storyIdsByFile;
+}
+
+/** Builds the unavailable reason for a non-`ready` module-graph status. */
+function reasonForStatus(status: ModuleGraphStatus): string {
+  switch (status.value) {
+    case 'booting':
+      return "Storybook's story module graph hasn't built yet — it is still being constructed. Retry shortly.";
+    case 'unavailable':
+      // The service's own reason names the adapter-specific cause; the remedy sentence stays
+      // appended because the agent's next move is to check how the dev server runs, which that
+      // reason does not say.
+      return `Storybook's story dependency graph is unavailable: ${status.reason}. Make sure the dev server is running with a builder that supports change detection.`;
+    case 'error':
+      return `Storybook's story module graph failed to build: ${status.error.message}`;
+    case 'ready':
+      return "Storybook's story module graph is ready.";
+    default: {
+      const exhaustive: never = status;
+      return exhaustive;
+    }
+  }
+}
+
+export interface ComponentStoriesRequest {
+  componentPaths: string[];
+}
+
+export interface ComponentStoryDepth {
+  storyId: string;
+  depth: number;
+}
+
+export interface ComponentStoriesResult {
+  /** Echoes the caller's input path, lightly normalized (redundant separators etc. collapsed). */
+  componentPath: string;
+  matches: ComponentStoryDepth[];
+  /** `true` when no file exists at the resolved absolute path — distinguishes "typo" from "no stories yet". */
+  pathNotFound?: boolean;
+}
+
+export interface ComponentStoriesResponse {
+  available: boolean;
+  reason?: string;
+  results?: ComponentStoriesResult[];
+}
+
+export interface ResolveComponentStoriesDeps {
+  /** Live story index; injectable so tests can pin a fixed value. */
+  getStoryIndex: () => Promise<StoryIndex>;
+  /**
+   * The `core/module-graph` service, or `undefined` when it isn't registered in this process (e.g.
+   * a builder without change detection, or an older Storybook without the open-service API).
+   */
+  moduleGraph: ModuleGraphAccess | undefined;
+  /** Defaults to `process.cwd()`, matching the dev server. */
+  workingDir?: string;
+}
+
+/** Per-component target set, resolved before the batched module-graph lookup. */
+interface ResolvedComponent {
+  /** Cleaned-up echo of the caller's input path. */
+  componentPath: string;
+  /** Forward-slashed absolute target paths (barrel-expanded) to look up. */
+  targets: string[];
+  pathNotFound?: boolean;
+}
+
+/**
+ * Looks up stories that consume each component path via Storybook's `core/module-graph` reverse
+ * index. Returns `{ available: false }` when the graph isn't ready; otherwise per-path results.
+ *
+ * The unavailable/booting/error cases are reported rather than flattened into "no matches" so a
+ * caller can't mistake an unsupported builder or a still-booting graph for "this component is
+ * unused".
+ */
+export async function resolveComponentStories(
+  request: ComponentStoriesRequest,
+  deps: ResolveComponentStoriesDeps
+): Promise<ComponentStoriesResponse> {
+  const { moduleGraph } = deps;
+  if (!moduleGraph) {
+    return {
+      available: false,
+      reason:
+        "Storybook's story module graph is unavailable. This Storybook version may not ship the open-service API, the module-graph service isn't registered (e.g. a builder without change detection), or the dev server is not running.",
+    };
+  }
+
+  // `status.loaded` awaits the graph's settle barrier, so by the time it resolves the status is
+  // no longer `booting` unless the graph genuinely never built — handle every non-ready case.
+  const status = await moduleGraph.queries.status.loaded(undefined);
+  if (status.value !== 'ready') {
+    return { available: false, reason: reasonForStatus(status) };
+  }
+
+  const workingDir = deps.workingDir ?? process.cwd();
+  const storyIndex = await deps.getStoryIndex();
+  const storyIdsByFile = buildStoryIdsByFile(storyIndex);
+
+  // Dedupe inputs so an agent that grep'd loosely doesn't get the same component echoed back twice.
+  const deduped = [...new Set(request.componentPaths)];
+
+  // Phase 1: resolve each component to its expanded set of target paths.
+  const resolved: ResolvedComponent[] = deduped.map((componentPath) => {
+    // Normalize first: a trailing slash on `/abs/Badge/Badge.tsx/` would otherwise flip the
+    // barrel-expansion heuristic and silently return barrel consumers instead of the file.
+    const absolute = resolve(workingDir, componentPath);
+    const canonical = canonicalise(absolute);
+
+    // Echo a cleaned-up form of the input (no redundant separators / `..` segments) rather than the
+    // raw string. Keeps relative paths relative and absolute paths absolute.
+    const echo = normalize(componentPath);
+
+    if (!canonical) {
+      return { componentPath: echo, targets: [], pathNotFound: true };
+    }
+
+    // Include both the input's normalized form and the canonical form. On case-insensitive
+    // filesystems they differ when the caller passed a wrong-case path; using both means we hit
+    // the graph regardless of which form the caller supplied.
+    const targets = new Set<string>(expandBarrelTargets(absolute));
+    if (canonical !== absolute) {
+      for (const target of expandBarrelTargets(canonical)) {
+        targets.add(target);
+      }
+    }
+
+    return { componentPath: echo, targets: [...targets] };
+  });
+
+  // Phase 2: one batched reverse-index lookup over the union of every component's targets.
+  const allTargets = [...new Set(resolved.flatMap((component) => component.targets))];
+  const hitsByTarget = new Map<string, ModuleGraphStoryHit[]>();
+  if (allTargets.length > 0) {
+    const batched = await moduleGraph.queries.storiesForFiles.loaded({ files: allTargets });
+    // Output is positional: result `i` corresponds to input `allTargets[i]`.
+    allTargets.forEach((target, i) => {
+      hitsByTarget.set(target, batched[i] ?? []);
+    });
+  }
+
+  // Phase 3: merge hits back per component, keeping the minimum depth per storyId.
+  const results: ComponentStoriesResult[] = resolved.map((component) => {
+    if (component.pathNotFound) {
+      return { componentPath: component.componentPath, matches: [], pathNotFound: true };
+    }
+
+    const byStoryId = new Map<string, number>();
+    for (const target of component.targets) {
+      const hits = hitsByTarget.get(target) ?? [];
+      for (const { storyFile, depth } of hits) {
+        const storyIds = storyIdsByFile.get(storyFile);
+        if (!storyIds) {
+          continue;
+        }
+        for (const storyId of storyIds) {
+          const existing = byStoryId.get(storyId);
+          if (existing === undefined || depth < existing) {
+            byStoryId.set(storyId, depth);
+          }
+        }
+      }
+    }
+
+    const matches: ComponentStoryDepth[] = [...byStoryId.entries()]
+      .map(([storyId, depth]) => ({ storyId, depth }))
+      .sort((a, b) => {
+        if (a.depth !== b.depth) {
+          return a.depth - b.depth;
+        }
+        return a.storyId.localeCompare(b.storyId);
+      });
+
+    return { componentPath: component.componentPath, matches };
+  });
+
+  return { available: true, results };
+}
diff --git a/code/core/src/shared/open-service/toolsets/stories/story-input.ts b/code/core/src/shared/open-service/toolsets/stories/story-input.ts
index af319b5b7466..5b88c83d7e67 100644
--- a/code/core/src/shared/open-service/toolsets/stories/story-input.ts
+++ b/code/core/src/shared/open-service/toolsets/stories/story-input.ts
@@ -1,5 +1,30 @@
 import * as v from 'valibot';
 
+import { MCP_TOOL_NAMES } from '../../toolset-names.ts';
+
+/**
+ * Per-shape props/globals selectors, shared by both story selector variants.
+ *
+ * The prose predates the toolsets and is eval-tuned, so it is kept verbatim. It names sibling
+ * capabilities by their MCP tool names rather than through `getRef`, because valibot descriptions
+ * are static strings with no per-consumer rendering. One of them, `get-storybook-story-instructions`,
+ * is an `@storybook/addon-mcp` tool with no toolset method and so no entry in {@link MCP_TOOL_NAMES};
+ * a CLI consumer would need this sentence rewritten rather than re-rendered.
+ */
+const storyInputProps = {
+  props: v.pipe(
+    v.optional(v.record(v.string(), v.any())),
+    v.description(`Optional custom props to pass to the story for rendering. Use this when you don't want to render the default story,
+but you want to customize some args or other props.
+You can look up the component's documentation using the get-storybook-story-instructions tool to see what props are available.`)
+  ),
+  globals: v.pipe(
+    v.optional(v.record(v.string(), v.any())),
+    v.description(`Optional Storybook globals to set for the story preview. Globals are used for things like theme, locale, viewport, and other cross-cutting concerns.
+Common globals include 'theme' (e.g., 'dark', 'light'), 'locale' (e.g., 'en', 'fr'), and 'backgrounds' (e.g., { value: '#000' }).`)
+  ),
+};
+
 /**
  * Shared story selector used by the stories and test APIs.
  *
@@ -9,38 +34,37 @@ export const storyInputSchema = v.union([
   v.object({
     exportName: v.pipe(
       v.string(),
-      v.description('Export name of the story from the story file (for example "Primary").')
+      v.description(
+        `The export name of the story from the story file.
+Use this path-based shape only when you're already editing a .stories.* file and know the export names in that file.
+If you do not already have story file context, prefer the storyId shape instead of searching files.`
+      )
     ),
     explicitStoryName: v.pipe(
       v.optional(v.string()),
-      v.description('Story `name` when it differs from the export name.')
+      v.description(
+        `If the story has an explicit name set via the "name" property, that is different from the export name, provide it here.
+Otherwise don't set this.`
+      )
     ),
     absoluteStoryPath: v.pipe(
       v.string(),
-      v.description('Absolute path to the story file, used with exportName.')
-    ),
-    props: v.pipe(
-      v.optional(v.record(v.string(), v.any())),
-      v.description('Optional story args/props overrides.')
-    ),
-    globals: v.pipe(
-      v.optional(v.record(v.string(), v.any())),
-      v.description('Optional Storybook globals (theme, locale, viewport, …).')
+      v.description(
+        'Absolute path to the story file. Use together with exportName only when story file context is already available.'
+      )
     ),
+    ...storyInputProps,
   }),
   v.object({
     storyId: v.pipe(
       v.string(),
-      v.description('Full Storybook story id (for example "button--primary").')
-    ),
-    props: v.pipe(
-      v.optional(v.record(v.string(), v.any())),
-      v.description('Optional story args/props overrides.')
-    ),
-    globals: v.pipe(
-      v.optional(v.record(v.string(), v.any())),
-      v.description('Optional Storybook globals (theme, locale, viewport, …).')
+      v.description(
+        `The full Storybook story ID (for example "button--primary").
+Prefer this shape whenever you are not already working in a specific story file.
+Use IDs discovered from ${MCP_TOOL_NAMES['docs.list']} (withStoryIds=true) or ${MCP_TOOL_NAMES['docs.show']}.`
+      )
     ),
+    ...storyInputProps,
   }),
 ]);
 
diff --git a/code/core/src/shared/open-service/toolsets/stories/unreachable-files.ts b/code/core/src/shared/open-service/toolsets/stories/unreachable-files.ts
new file mode 100644
index 000000000000..30429f0f8d1d
--- /dev/null
+++ b/code/core/src/shared/open-service/toolsets/stories/unreachable-files.ts
@@ -0,0 +1,78 @@
+import { logger } from 'storybook/internal/node-logger';
+
+import { resolve as resolvePath } from 'pathe';
+
+import type { ModuleGraphService } from '../../services/module-graph/definition.ts';
+import type { StoriesGitAccess } from './definition.ts';
+
+const SOURCE_EXT_RE = /\.(?:tsx?|jsx?|mjs|cjs)$/i;
+
+/**
+ * Module-graph query batch size. Bounds the per-call file list so a large working tree doesn't
+ * issue one oversized reverse-index query; we early-exit between chunks once `maxFiles` is reached.
+ */
+const CHUNK_SIZE = 50;
+
+/** Cap on files reported inline, so a large working tree can't dominate the response. */
+const DEFAULT_MAX_FILES = 10;
+
+/**
+ * Lists working-tree files that no story reaches through the import graph.
+ *
+ * This is the "your edit isn't in the graph; you'll need to grep" case — typical for theme tokens,
+ * decorator config, and other files consumed through Storybook's preview runtime rather than a
+ * story-file import. Paths stay repo-root-relative because they are shown to an agent that will
+ * grep for them.
+ */
+export async function detectUnreachableFiles({
+  git,
+  moduleGraph,
+  maxFiles = DEFAULT_MAX_FILES,
+}: {
+  git: StoriesGitAccess;
+  moduleGraph: ModuleGraphService;
+  maxFiles?: number;
+}): Promise<string[]> {
+  const status = await moduleGraph.queries.status.loaded(undefined);
+  if (status.value !== 'ready') {
+    return [];
+  }
+
+  let changedFiles: Awaited<ReturnType<StoriesGitAccess['getChangedFiles']>>;
+  let repoRoot: string;
+  try {
+    [changedFiles, repoRoot] = await Promise.all([git.getChangedFiles(), git.getRepoRoot()]);
+  } catch (error) {
+    // Not a git repository, or git itself is unusable. Change detection legitimately answers
+    // "no changes detected" here — the pre-toolset tool degraded the same way — so the failure
+    // must not turn the whole tool into an error for the agent.
+    logger.debug(`Unreachable-file detection skipped, git is unavailable: ${error}`);
+    return [];
+  }
+  const relativeFiles = [...new Set([...changedFiles.changed, ...changedFiles.new])].filter(
+    (file) => SOURCE_EXT_RE.test(file)
+  );
+
+  const unreachable: string[] = [];
+  for (
+    let start = 0;
+    start < relativeFiles.length && unreachable.length < maxFiles;
+    start += CHUNK_SIZE
+  ) {
+    const chunk = relativeFiles.slice(start, start + CHUNK_SIZE);
+    // One batched lookup per chunk; the result is positional.
+    const hits = await moduleGraph.queries.storiesForFiles.loaded({
+      files: chunk.map((file) => resolvePath(repoRoot, file)),
+    });
+    for (const [position, file] of chunk.entries()) {
+      if (unreachable.length >= maxFiles) {
+        break;
+      }
+      if ((hits[position]?.length ?? 0) === 0) {
+        unreachable.push(file);
+      }
+    }
+  }
+
+  return unreachable;
+}
diff --git a/code/core/src/shared/open-service/toolsets/test/definition.test.ts b/code/core/src/shared/open-service/toolsets/test/definition.test.ts
index 18236d767591..c90df40a7b2c 100644
--- a/code/core/src/shared/open-service/toolsets/test/definition.test.ts
+++ b/code/core/src/shared/open-service/toolsets/test/definition.test.ts
@@ -4,7 +4,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import * as v from 'valibot';
 
 import type { ToolsetCtx } from '../../toolset-definition.ts';
-import type { TestRunOutput } from './definition.ts';
+import type { TestRunOutput, TestRunResult } from './definition.ts';
 import { createTestToolset } from './definition.ts';
 import { runStoryTests } from './run.ts';
 
@@ -13,28 +13,54 @@ vi.mock('./run.ts', { spy: true });
 const index = { v: 5, entries: {} } as StoryIndex;
 const getIndex = vi.fn();
 const storyIndex = { getIndex };
+const telemetry = vi.fn();
+const channel = {} as never;
+
 const ctx = {
   consumer: 'cli',
   origin: 'http://localhost:6006',
-  format: 'json',
   getService: vi.fn() as ToolsetCtx['getService'],
+  telemetry,
 } satisfies ToolsetCtx;
 
-const completedRun: TestRunOutput = {
-  status: 'completed',
-  result: {
-    config: { a11y: true },
-    componentTestStatuses: [],
-    a11yStatuses: [],
-    componentTestCount: { success: 2, error: 0 },
-    a11yCount: { success: 1, warning: 0, error: 0 },
-    a11yReports: {},
-    reports: {},
-    totalTestCount: 3,
-    unhandledErrors: [],
-  },
+const mcpCtx = { ...ctx, consumer: 'mcp' } satisfies ToolsetCtx;
+
+const baseResult: TestRunResult = {
+  config: { coverage: false, a11y: false },
+  componentTestStatuses: [],
+  a11yStatuses: [],
+  componentTestCount: { success: 0, error: 0 },
+  a11yCount: { success: 0, warning: 0, error: 0 },
+  a11yReports: {},
+  reports: {},
+  unhandledErrors: [],
 };
 
+function componentTest(
+  storyId: string,
+  value: 'status-value:success' | 'status-value:error',
+  description = ''
+) {
+  return {
+    storyId,
+    typeId: 'storybook/component-test',
+    value,
+    title: 'Component Test',
+    description,
+  };
+}
+
+function completed(result: Partial<TestRunResult> = {}): TestRunOutput {
+  return { status: 'completed', result: { ...baseResult, ...result } };
+}
+
+const completedRun = completed({
+  componentTestCount: { success: 2, error: 0 },
+  a11yCount: { success: 1, warning: 0, error: 0 },
+  totalTestCount: 3,
+});
+
+let toolset: ReturnType<typeof createTestToolset>;
 let pendingRun: Promise<TestRunOutput> | undefined;
 
 beforeEach(() => {
@@ -42,26 +68,27 @@ beforeEach(() => {
   pendingRun = undefined;
   getIndex.mockResolvedValue(index);
   vi.mocked(runStoryTests).mockImplementation(() => pendingRun ?? Promise.resolve(completedRun));
+  toolset = createTestToolset({ channel, storyIndex, a11yEnabled: true });
 });
 
+function runTests(
+  input: v.InferInput<typeof toolset.methods.run.schema> = {},
+  runCtx: ToolsetCtx = ctx
+) {
+  return toolset.methods.run.handler(v.parse(toolset.methods.run.schema, input), runCtx);
+}
+
+/** Runs and renders the way the MCP adapter does: one handler call, markdown from the outcome. */
+async function runForMcp(input: v.InferInput<typeof toolset.methods.run.schema> = {}) {
+  return runTests(input, mcpCtx);
+}
+
 describe('test API', () => {
-  it('returns a useful Markdown summary by default', async () => {
-    const channel = {} as never;
-    const testToolset = createTestToolset({ channel, storyIndex });
-
-    await expect(
-      testToolset.methods.run.handler(v.parse(testToolset.methods.run.schema, {}), {
-        ...ctx,
-        format: 'markdown',
-      })
-    ).resolves.toBe(
-      [
-        '# Test run completed',
-        '- Total tests: 3',
-        '- Component tests: 2 passed, 0 failed',
-        '- Accessibility tests: 1 passed, 0 warnings, 0 failed',
-      ].join('\n')
-    );
+  it('runs all stories and reports the requested a11y flag alongside the outcome', async () => {
+    const outcome = await runTests();
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome.data).toEqual({ ...completedRun, a11y: true });
     expect(runStoryTests).toHaveBeenCalledWith({
       channel,
       getIndex,
@@ -70,32 +97,302 @@ describe('test API', () => {
     });
   });
 
-  it('returns the existing TestRunOutput when the adapter requests JSON', async () => {
-    const testToolset = createTestToolset({ channel: {} as never, storyIndex });
+  it('summarizes counts for the CLI consumer', async () => {
+    const outcome = await runTests();
 
-    await expect(
-      testToolset.methods.run.handler(v.parse(testToolset.methods.run.schema, {}), ctx)
-    ).resolves.toEqual(completedRun);
+    expect(outcome.markdown).toBe(
+      [
+        '# Test run completed',
+        '- Total tests: 3',
+        '- Component tests: 2 passed, 0 failed',
+        '- Accessibility tests: 1 passed, 0 warnings, 0 failed',
+      ].join('\n')
+    );
   });
 
   it('serializes concurrent test runs for one API registration', async () => {
-    const testToolset = createTestToolset({ channel: {} as never, storyIndex });
     let completePendingRun!: () => void;
     pendingRun = new Promise((resolve) => {
       completePendingRun = () => resolve(completedRun);
     });
 
-    const input = v.parse(testToolset.methods.run.schema, {});
-    const firstRun = testToolset.methods.run.handler(input, ctx);
+    const firstRun = runTests();
     await vi.waitFor(() => expect(runStoryTests).toHaveBeenCalledOnce());
 
-    const secondRun = testToolset.methods.run.handler(input, ctx);
+    const secondRun = runTests();
     await Promise.resolve();
     expect(runStoryTests).toHaveBeenCalledOnce();
 
     completePendingRun();
     await firstRun;
-    await expect(secondRun).resolves.toEqual(completedRun);
+    await expect(secondRun).resolves.toMatchObject({
+      ok: true,
+      data: { ...completedRun, a11y: true },
+    });
     expect(runStoryTests).toHaveBeenCalledTimes(2);
   });
+
+  describe('description', () => {
+    it('promises accessibility reports when a11y is enabled', () => {
+      expect(toolset.methods.run.description).toContain(
+        'For visual/design accessibility violations (for example color contrast), ask the user before changing styles.'
+      );
+    });
+
+    it('makes no accessibility promise when a11y is disabled', () => {
+      const withoutA11y = createTestToolset({ channel, storyIndex, a11yEnabled: false });
+
+      expect(withoutA11y.methods.run.description).not.toContain('accessibility');
+      expect(withoutA11y.methods.run.description).toContain(
+        'Results will include passing/failing status.'
+      );
+    });
+  });
+
+  describe('MCP rendering', () => {
+    it('lists passing stories', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue(
+        completed({
+          storyIds: ['button--primary'],
+          totalTestCount: 1,
+          componentTestCount: { success: 1, error: 0 },
+          componentTestStatuses: [componentTest('button--primary', 'status-value:success')],
+        })
+      );
+
+      expect((await runForMcp()).markdown).toBe(`## Passing Stories
+
+- button--primary`);
+    });
+
+    it('lists failing stories with their descriptions', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue(
+        completed({
+          componentTestCount: { success: 1, error: 1 },
+          componentTestStatuses: [
+            componentTest('button--primary', 'status-value:success'),
+            componentTest(
+              'button--secondary',
+              'status-value:error',
+              'Expected button text to be "Secondary"'
+            ),
+          ],
+        })
+      );
+
+      expect((await runForMcp()).markdown).toBe(`## Passing Stories
+
+- button--primary
+
+## Failing Stories
+
+### button--secondary
+
+Expected button text to be "Secondary"`);
+    });
+
+    it('reports accessibility violations with inspect links built from the origin', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue(
+        completed({
+          componentTestCount: { success: 1, error: 0 },
+          a11yCount: { success: 0, warning: 1, error: 1 },
+          componentTestStatuses: [componentTest('button--primary', 'status-value:success')],
+          a11yReports: {
+            'button--primary': [
+              {
+                violations: [
+                  {
+                    id: 'color-contrast',
+                    description: 'Color contrast ratio is insufficient',
+                    nodes: [
+                      {
+                        html: '<button style="color: #fff; background: #ccc;">Click me</button>',
+                        impact: 'critical',
+                        failureSummary: '2.5:1 (required: 4.5:1)',
+                        linkPath: '/inspect/button--primary?inspectPath=button.0',
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        })
+      );
+
+      expect((await runForMcp()).markdown).toBe(`## Passing Stories
+
+- button--primary
+
+## Accessibility Violations
+
+### button--primary - color-contrast
+
+Color contrast ratio is insufficient
+
+#### Affected Elements
+- **Impact**: critical
+  **Message**: 2.5:1 (required: 4.5:1)
+  **Element**: <button style="color: #fff; background: #ccc;">Click me</button>
+  **Inspect**: http://localhost:6006/inspect/button--primary?inspectPath=button.0`);
+    });
+
+    it('omits accessibility violations when the run disabled a11y', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue(
+        completed({
+          componentTestStatuses: [componentTest('button--primary', 'status-value:success')],
+          a11yReports: {
+            'button--primary': [
+              {
+                violations: [
+                  {
+                    id: 'color-contrast',
+                    description: 'Color contrast ratio is insufficient',
+                    nodes: [{ html: '<button>Click me</button>', impact: 'critical' }],
+                  },
+                ],
+              },
+            ],
+          },
+        })
+      );
+
+      expect((await runForMcp({ a11y: false })).markdown).toBe(`## Passing Stories
+
+- button--primary`);
+    });
+
+    it('reports unhandled errors without claiming any story passed', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue(
+        completed({
+          unhandledErrors: [
+            {
+              name: 'ReferenceError',
+              message: 'foo is not defined',
+              stack: 'ReferenceError: foo is not defined\n    at Button.tsx:10:5',
+              VITEST_TEST_PATH: '/src/Button.stories.tsx',
+              VITEST_TEST_NAME: 'Button > Primary',
+            },
+          ],
+        })
+      );
+
+      expect((await runForMcp()).markdown).toBe(`## Unhandled Errors
+
+### ReferenceError
+
+**Error message**: foo is not defined
+**Path**: /src/Button.stories.tsx
+**Test name**: Button > Primary
+**Stack trace**:
+ReferenceError: foo is not defined
+    at Button.tsx:10:5`);
+    });
+
+    it('returns the per-selector lookup failures when nothing matched', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue({
+        status: 'no-stories',
+        notFoundMessages: [
+          'No story found for story ID "missing--story"',
+          'No story found for story ID "gone--story"',
+        ],
+      });
+
+      const outcome = await runForMcp({
+        stories: [{ storyId: 'missing--story' }, { storyId: 'gone--story' }],
+      });
+
+      expect(outcome.ok).toBe(true);
+      expect(outcome.markdown).toBe(`No stories found matching the provided input.
+
+No story found for story ID "missing--story"
+No story found for story ID "gone--story"`);
+    });
+
+    it('flags a failed run as a failure while still rendering the error line', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue({
+        status: 'error',
+        error: { message: 'Vitest failed to start' },
+      });
+
+      const outcome = await runForMcp();
+
+      expect(outcome.ok).toBe(false);
+      expect(outcome.markdown).toBe('Error: Vitest failed to start');
+    });
+
+    it('flags a cancelled run as a failure while still rendering the error line', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue({ status: 'cancelled' });
+
+      const outcome = await runForMcp();
+
+      expect(outcome.ok).toBe(false);
+      expect(outcome.markdown).toBe('Error: Test run was cancelled');
+    });
+  });
+
+  describe('telemetry', () => {
+    it('reports result counts for a completed run', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue(
+        completed({
+          storyIds: ['button--primary'],
+          componentTestCount: { success: 1, error: 0 },
+          a11yCount: { success: 0, warning: 1, error: 0 },
+          componentTestStatuses: [componentTest('button--primary', 'status-value:success')],
+          a11yReports: {
+            'button--primary': [
+              {
+                violations: [
+                  {
+                    id: 'color-contrast',
+                    description: 'Color contrast ratio is insufficient',
+                    nodes: [{ html: '<button>Click me</button>', impact: 'critical' }],
+                  },
+                ],
+              },
+            ],
+          },
+        })
+      );
+
+      await runTests({ stories: [{ storyId: 'button--primary' }] });
+
+      expect(telemetry).toHaveBeenCalledWith('tool:runStoryTests', {
+        runA11y: true,
+        inputStoryCount: 1,
+        matchedStoryCount: 1,
+        passingStoryCount: 1,
+        failingStoryCount: 0,
+        a11yViolationCount: 1,
+        unhandledErrorCount: 0,
+      });
+    });
+
+    it('reports zeroed counts when no story matched', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue({
+        status: 'no-stories',
+        notFoundMessages: ['No story found for story ID "missing--story"'],
+      });
+
+      await runTests({ stories: [{ storyId: 'missing--story' }], a11y: false });
+
+      expect(telemetry).toHaveBeenCalledWith('tool:runStoryTests', {
+        runA11y: false,
+        inputStoryCount: 1,
+        matchedStoryCount: 0,
+        passingStoryCount: 0,
+        failingStoryCount: 0,
+        a11yViolationCount: 0,
+        unhandledErrorCount: 0,
+      });
+    });
+
+    it('stays silent for a run that never reached a verdict', async () => {
+      vi.mocked(runStoryTests).mockResolvedValue({ status: 'cancelled' });
+
+      await runTests();
+
+      expect(telemetry).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/code/core/src/shared/open-service/toolsets/test/format.ts b/code/core/src/shared/open-service/toolsets/test/format.ts
index fa0afa991f77..b5b701cc8837 100644
--- a/code/core/src/shared/open-service/toolsets/test/format.ts
+++ b/code/core/src/shared/open-service/toolsets/test/format.ts
@@ -1,16 +1,280 @@
-import type { TestRunOutput } from './definition.ts';
+import type { ToolsetCtx } from '../../toolset-definition.ts';
+import type { TestRunData, TestRunResult } from './definition.ts';
 
-/** Formats a test run result as a compact summary for humans and agents. */
-export function formatTestRun(output: TestRunOutput): string {
-  switch (output.status) {
+type ComponentTestStatus = TestRunResult['componentTestStatuses'][number];
+
+/**
+ * Shapes of the addon-vitest / addon-a11y payloads that travel over the channel. The run result is
+ * not validated on arrival, so these describe what the formatter reads rather than what it is
+ * promised — every access below stays defensive for that reason.
+ */
+type A11yViolationNode = {
+  impact?: string;
+  failureSummary?: string;
+  html?: string;
+  linkPath?: string;
+};
+
+type A11yViolation = {
+  id: string;
+  description: string;
+  nodes: A11yViolationNode[];
+};
+
+type A11yReport = {
+  error?: { message: string };
+  violations?: unknown;
+};
+
+type UnhandledError = {
+  name?: string;
+  message?: string;
+  stack?: string;
+  VITEST_TEST_PATH?: string;
+  VITEST_TEST_NAME?: string;
+};
+
+export type TestRunSummary = {
+  passingStoryCount: number;
+  failingStoryCount: number;
+  a11yViolationCount: number;
+  unhandledErrorCount: number;
+};
+
+function isPassing(status: ComponentTestStatus): boolean {
+  return status.value === 'status-value:success';
+}
+
+function isFailing(status: ComponentTestStatus): boolean {
+  return status.value === 'status-value:error';
+}
+
+function getA11yReports(result: TestRunResult): Record<string, A11yReport[]> {
+  return result.a11yReports as Record<string, A11yReport[]>;
+}
+
+function getA11yViolations(report: A11yReport): A11yViolation[] {
+  if (!('violations' in report)) {
+    return [];
+  }
+
+  const { violations } = report;
+  if (!Array.isArray(violations)) {
+    return [];
+  }
+
+  return violations.map((violation) => ({
+    id: violation.id,
+    description: violation.description,
+    nodes: violation.nodes.map((node: Record<string, unknown>) => ({
+      impact: typeof node.impact === 'string' ? node.impact : undefined,
+      failureSummary: typeof node.failureSummary === 'string' ? node.failureSummary : undefined,
+      html: typeof node.html === 'string' ? node.html : undefined,
+      linkPath: typeof node.linkPath === 'string' ? node.linkPath : undefined,
+    })),
+  }));
+}
+
+function countA11yViolations(a11yReports: Record<string, A11yReport[]>): number {
+  let count = 0;
+
+  for (const reports of Object.values(a11yReports ?? {})) {
+    for (const report of reports) {
+      if ('error' in report && report.error) {
+        continue;
+      }
+
+      count += getA11yViolations(report).length;
+    }
+  }
+
+  return count;
+}
+
+/** Result counts, shared with the handler so telemetry reports the numbers the text shows. */
+export function summarizeTestRun(result: TestRunResult, a11y: boolean): TestRunSummary {
+  return {
+    passingStoryCount: result.componentTestStatuses.filter(isPassing).length,
+    failingStoryCount: result.componentTestStatuses.filter(isFailing).length,
+    a11yViolationCount: a11y ? countA11yViolations(getA11yReports(result)) : 0,
+    unhandledErrorCount: result.unhandledErrors.length,
+  };
+}
+
+function formatPassingStoriesSection(passingStories: ComponentTestStatus[]): string {
+  return `## Passing Stories
+
+- ${passingStories.map((status) => status.storyId).join('\n- ')}`;
+}
+
+function formatFailingStoriesSection(statuses: ComponentTestStatus[]): string {
+  const entries = statuses.map(
+    (status) =>
+      `### ${status.storyId}
+
+${status.description || 'No failure details available.'}`
+  );
+
+  return `## Failing Stories
+
+${entries.join('\n\n')}`;
+}
+
+function formatA11yReportsSection({
+  a11yReports,
+  origin,
+}: {
+  a11yReports: Record<string, A11yReport[]>;
+  origin?: string;
+}): string | undefined {
+  const a11yViolationSections: string[] = [];
+
+  for (const [storyId, reports] of Object.entries(a11yReports)) {
+    for (const report of reports) {
+      if ('error' in report && report.error) {
+        a11yViolationSections.push(`### ${storyId} - Error
+
+${report.error.message}`);
+        continue;
+      }
+
+      const violations = getA11yViolations(report);
+      if (violations.length === 0) {
+        continue;
+      }
+
+      for (const violation of violations) {
+        const nodes = violation.nodes
+          .map((node) => {
+            const inspectLink = origin && node.linkPath ? `${origin}${node.linkPath}` : undefined;
+            const parts: string[] = [];
+
+            if (node.impact) {
+              parts.push(`- **Impact**: ${node.impact}`);
+            }
+
+            if (node.failureSummary) {
+              parts.push(`  **Message**: ${node.failureSummary}`);
+            }
+
+            parts.push(`  **Element**: ${node.html || '(no html available)'}`);
+
+            if (inspectLink) {
+              parts.push(`  **Inspect**: ${inspectLink}`);
+            }
+
+            return parts.join('\n');
+          })
+          .join('\n');
+
+        a11yViolationSections.push(`### ${storyId} - ${violation.id}
+
+${violation.description}
+
+#### Affected Elements
+${nodes}`);
+      }
+    }
+  }
+
+  if (a11yViolationSections.length === 0) {
+    return undefined;
+  }
+
+  return `## Accessibility Violations
+
+${a11yViolationSections.join('\n\n')}`;
+}
+
+function formatUnhandledErrorsSection(errors: UnhandledError[]): string {
+  const formattedErrors = errors.map(
+    (unhandledError) =>
+      `### ${unhandledError.name || 'Unknown Error'}
+
+**Error message**: ${unhandledError.message || 'No message available'}
+**Path**: ${unhandledError.VITEST_TEST_PATH || 'No path available'}
+**Test name**: ${unhandledError.VITEST_TEST_NAME || 'No test name available'}
+**Stack trace**:
+${unhandledError.stack || 'No stack trace available'}`
+  );
+
+  return `## Unhandled Errors
+
+${formattedErrors.join('\n\n')}`;
+}
+
+/**
+ * Only the sections that carry information are emitted, so a run with nothing to report renders as
+ * an empty string.
+ */
+function formatCompletedRun(
+  result: TestRunResult,
+  { a11y, origin }: { a11y: boolean; origin?: string }
+): string {
+  const sections: string[] = [];
+  const passingStories = result.componentTestStatuses.filter(isPassing);
+  const failingStories = result.componentTestStatuses.filter(isFailing);
+
+  if (passingStories.length > 0) {
+    sections.push(formatPassingStoriesSection(passingStories));
+  }
+
+  if (failingStories.length > 0) {
+    sections.push(formatFailingStoriesSection(failingStories));
+  }
+
+  const a11yReports = getA11yReports(result);
+  if (a11y && a11yReports && Object.keys(a11yReports).length > 0) {
+    const a11ySection = formatA11yReportsSection({ a11yReports, origin });
+    if (a11ySection) {
+      sections.push(a11ySection);
+    }
+  }
+
+  if (result.unhandledErrors.length > 0) {
+    sections.push(formatUnhandledErrorsSection(result.unhandledErrors as UnhandledError[]));
+  }
+
+  return sections.join('\n\n');
+}
+
+/**
+ * Agent-facing rendering, kept identical to the `run-story-tests` MCP tool.
+ *
+ * Failed and cancelled runs read as `Error: …` because that tool surfaced them by throwing; the
+ * `isError` flag that accompanied them belongs to the adapter, not to text.
+ */
+function formatTestRunForAgent(data: TestRunData, ctx: ToolsetCtx): string {
+  switch (data.status) {
+    case 'no-stories':
+      return `No stories found matching the provided input.
+
+${data.notFoundMessages.join('\n')}`;
+    case 'completed':
+      return formatCompletedRun(data.result, { a11y: data.a11y, origin: ctx.origin });
+    case 'error':
+      return `Error: ${data.error.message}`;
+    case 'cancelled':
+      return 'Error: Test run was cancelled';
+    default: {
+      // Type-only: a new outcome must get its own agent-facing text rather than falling through.
+      const _exhaustive: never = data;
+      return _exhaustive;
+    }
+  }
+}
+
+/** Compact summary for a human reading terminal output. */
+function formatTestRunSummary(data: TestRunData): string {
+  switch (data.status) {
     case 'no-stories':
       return '# No stories matched\nNo story tests were run.';
     case 'error':
-      return `# Test run failed\n${output.error.message}`;
+      return `# Test run failed\n${data.error.message}`;
     case 'cancelled':
       return '# Test run cancelled\nThe test run was cancelled.';
     case 'completed': {
-      const { componentTestCount, a11yCount, totalTestCount } = output.result;
+      const { componentTestCount, a11yCount, totalTestCount } = data.result;
       const total =
         totalTestCount ??
         componentTestCount.success +
@@ -26,5 +290,14 @@ export function formatTestRun(output: TestRunOutput): string {
         `- Accessibility tests: ${a11yCount.success} passed, ${a11yCount.warning} warnings, ${a11yCount.error} failed`,
       ].join('\n');
     }
+    default: {
+      // Type-only: a new outcome must get its own summary rather than falling through.
+      const _exhaustive: never = data;
+      return _exhaustive;
+    }
   }
 }
+
+export function formatTestRun(data: TestRunData, ctx: ToolsetCtx): string {
+  return ctx.consumer === 'mcp' ? formatTestRunForAgent(data, ctx) : formatTestRunSummary(data);
+}
diff --git a/code/core/src/shared/open-service/toolsets/test/run.test.ts b/code/core/src/shared/open-service/toolsets/test/run.test.ts
index 1f5fb78449a9..656f7900278e 100644
--- a/code/core/src/shared/open-service/toolsets/test/run.test.ts
+++ b/code/core/src/shared/open-service/toolsets/test/run.test.ts
@@ -92,7 +92,7 @@ describe('createAsyncQueue', () => {
 });
 
 describe('runStoryTests', () => {
-  it('returns an error when any focused selector is unresolved', async () => {
+  it('returns no-stories with the per-selector messages when nothing matched', async () => {
     const channel = createMockChannel();
     const emitSpy = vi.spyOn(channel, 'emit');
 
@@ -103,8 +103,8 @@ describe('runStoryTests', () => {
     });
 
     expect(result).toEqual({
-      status: 'error',
-      error: { message: expect.stringContaining('missing--story') },
+      status: 'no-stories',
+      notFoundMessages: ['No story found for story ID "missing--story"'],
     });
     expect(emitSpy).not.toHaveBeenCalled();
   });
@@ -133,7 +133,7 @@ describe('runStoryTests', () => {
       stories: [],
     });
 
-    expect(result).toEqual({ status: 'no-stories' });
+    expect(result).toEqual({ status: 'no-stories', notFoundMessages: [] });
     expect(emitSpy).not.toHaveBeenCalled();
   });
 
diff --git a/code/core/src/shared/open-service/toolsets/test/run.ts b/code/core/src/shared/open-service/toolsets/test/run.ts
index 2ba20799cce3..06bc1953c920 100644
--- a/code/core/src/shared/open-service/toolsets/test/run.ts
+++ b/code/core/src/shared/open-service/toolsets/test/run.ts
@@ -172,24 +172,26 @@ export async function runStoryTests({
   if (stories) {
     const index = await getIndex();
     const resolved = findStoryIds(index, stories);
-    const unresolved = resolved.filter((story): story is NotFoundStory => !('entry' in story));
+    const found = resolved.filter((story): story is FoundStory => 'entry' in story);
+    const notFoundMessages = resolved
+      .filter((story): story is NotFoundStory => !('entry' in story))
+      .map((story) => story.errorMessage);
+
+    // Nothing to run: the per-selector failures are the answer, so they travel with the outcome.
+    if (found.length === 0) {
+      return { status: 'no-stories', notFoundMessages };
+    }
 
-    if (unresolved.length > 0) {
+    // Running the matched subset would report a verdict for stories that were never run, so a
+    // partially resolved selector list fails instead.
+    if (notFoundMessages.length > 0) {
       return {
         status: 'error',
-        error: {
-          message: unresolved.map((story) => story.errorMessage).join('; '),
-        },
+        error: { message: notFoundMessages.join('; ') },
       };
     }
 
-    storyIds = resolved
-      .filter((story): story is FoundStory => 'entry' in story)
-      .map((s) => s.entry.id);
-
-    if (storyIds.length === 0) {
-      return { status: 'no-stories' };
-    }
+    storyIds = found.map((story) => story.entry.id);
   }
 
   let response: TriggerTestRunResponse;
diff --git a/code/core/src/shared/review/features.test.ts b/code/core/src/shared/review/features.test.ts
index 739b6dc83c5b..b1a5a9913261 100644
--- a/code/core/src/shared/review/features.test.ts
+++ b/code/core/src/shared/review/features.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 import type { StorybookFeatures } from '../../types/modules/core-common.ts';
 import { features as defaultFeaturesPreset } from '../../core-server/presets/common-preset.ts';
-import { isReviewFeatureEnabled } from './features.ts';
+import { isReviewExplicitlyEnabled, isReviewFeatureEnabled } from './features.ts';
 
 describe('isReviewFeatureEnabled', () => {
   it('is enabled with the untouched default features preset', async () => {
@@ -40,3 +40,25 @@ describe('isReviewFeatureEnabled', () => {
     expect(isReviewFeatureEnabled(undefined)).toBe(false);
   });
 });
+
+describe('isReviewExplicitlyEnabled', () => {
+  // The flag-unset default is where the two gates differ, and prose gated on the wrong one
+  // advertises `display-review` to MCP clients that cannot see it: the infrastructure gate is on
+  // by default, the direct-client gate only on explicit opt-in.
+  it('stays off when the flag is unset, unlike the infrastructure gate', () => {
+    const defaults = { changeDetection: true };
+    expect(isReviewFeatureEnabled(defaults)).toBe(true);
+    expect(isReviewExplicitlyEnabled(defaults)).toBe(false);
+  });
+
+  it('is enabled only on explicit opt-in with change detection', () => {
+    expect(isReviewExplicitlyEnabled({ changeDetection: true, experimentalReview: true })).toBe(
+      true
+    );
+    expect(isReviewExplicitlyEnabled({ changeDetection: true, experimentalReview: false })).toBe(
+      false
+    );
+    expect(isReviewExplicitlyEnabled({ experimentalReview: true })).toBe(false);
+    expect(isReviewExplicitlyEnabled(undefined)).toBe(false);
+  });
+});
diff --git a/code/core/src/shared/review/features.ts b/code/core/src/shared/review/features.ts
index 18638eadda73..223a3152987f 100644
--- a/code/core/src/shared/review/features.ts
+++ b/code/core/src/shared/review/features.ts
@@ -16,3 +16,14 @@ import type { StorybookFeatures } from '../../types/modules/core-common.ts';
  */
 export const isReviewFeatureEnabled = (features: StorybookFeatures | undefined): boolean =>
   features?.experimentalReview !== false && !!features?.changeDetection;
+
+/**
+ * Whether review is available to direct MCP clients: the explicit `experimentalReview` opt-in.
+ *
+ * Contrast with {@link isReviewFeatureEnabled}: with the flag unset the review infrastructure
+ * still mounts (the `storybook ai` CLI channel turns review on per request), but direct MCP
+ * clients never see `display-review` — so tool descriptions and result prose must not advertise
+ * it. Mirrors `getReviewStatus().available` in `@storybook/addon-mcp`.
+ */
+export const isReviewExplicitlyEnabled = (features: StorybookFeatures | undefined): boolean =>
+  !!features?.experimentalReview && !!features?.changeDetection;
diff --git a/code/core/src/shared/review/review-state.ts b/code/core/src/shared/review/review-state.ts
index 119c955a04b8..0b0c81d77b57 100644
--- a/code/core/src/shared/review/review-state.ts
+++ b/code/core/src/shared/review/review-state.ts
@@ -1,14 +1,11 @@
 /**
- * The review payload an agent pushes via the `display-review` MCP tool.
+ * The review payload an agent publishes via the `review.create` toolset method.
  *
- * Flow:
- *   MCP `display-review` tool → emit PUSH_REVIEW on the Storybook channel
- *   → core-server adapts it into the `core/review` service
- *   → manager tabs subscribe to the service's current-review query.
+ * Flow: `review.create` calls the `core/review` service's `setReview` command; manager tabs
+ * subscribe to the service's current-review query.
  *
- * This mirrors the canonical valibot schema in `@storybook/addon-mcp` →
- * `tools/display-review.ts`. The manager only renders the data — it does
- * not validate — so it needs the type, not the validator. Keep `title` /
+ * This mirrors the canonical valibot schema in the review toolset definition. The manager only
+ * renders the data — it does not validate — so it needs the type, not the validator. Keep `title` /
  * `description` / `collections` in sync with that schema.
  */
 
@@ -24,7 +21,7 @@ export interface ReviewState {
   collections: ReviewCollection[];
   changedFiles?: string[];
   /**
-   * Server-side creation timestamp (unix ms) assigned when PUSH_REVIEW is
+   * Server-side creation timestamp (unix ms) assigned when the review is
    * received; used for live "Created x minutes ago" UI in the summary.
    */
   createdAt?: number;
diff --git a/code/core/src/storybook-error.ts b/code/core/src/storybook-error.ts
index 6fe3d142e022..f78a879d1e42 100644
--- a/code/core/src/storybook-error.ts
+++ b/code/core/src/storybook-error.ts
@@ -50,6 +50,14 @@ export abstract class StorybookError extends Error {
   /** Flag used to easily determine if the error originates from Storybook. */
   readonly fromStorybook: true = true as const;
 
+  /**
+   * Marks an error whose message is written for the agent that triggered the call and names its
+   * own recovery. Adapters surface such errors verbatim instead of wrapping them as unexpected
+   * failures. A property rather than a class list, so the trait travels with the instance across
+   * bundle copies where `instanceof` would misclassify.
+   */
+  public readonly agentFacing: boolean;
+
   /**
    * Flag used to determine if the error is handled by us and should therefore not be shown to the
    * user.
@@ -98,6 +106,8 @@ export abstract class StorybookError extends Error {
     cause?: unknown;
     documentation?: boolean | string | string[];
     isHandledError?: boolean;
+    /** See {@link StorybookError.agentFacing}. Defaults to false. */
+    agentFacing?: boolean;
     name: string;
     /**
      * Optional array of sub-errors that are related to this error. When this error is sent to
@@ -113,6 +123,7 @@ export abstract class StorybookError extends Error {
     this.documentation = props.documentation ?? false;
     this.code = props.code;
     this.isHandledError = props.isHandledError ?? false;
+    this.agentFacing = props.agentFacing ?? false;
     this.name = props.name;
     this.subErrors = props.subErrors ?? [];
   }
diff --git a/yarn.lock b/yarn.lock
index 41c1c5ce8295..48a512d3ba2e 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -36614,6 +36614,7 @@ __metadata:
     oxc-resolver: "npm:^11.19.1"
     p-limit: "npm:^7.2.0"
     package-manager-detector: "npm:^1.1.0"
+    pathe: "npm:^1.1.2"
     picocolors: "npm:^1.1.0"
     picomatch: "npm:^2.3.0"
     picoquery: "npm:^2.5.0"