CLI: Label the tools help Output block as the --json shape

[kasperpeulen]

Closes #36087

What I did

storybook tools stories preview --help documents an output the command doesn't print.

What you run:

$ storybook tools stories preview --stories '[{"storyId":"core-button--docs"}]'
http://localhost:6007/?path=/story/core-button--docs

What its help promised:

Output:
- `stories` (array, required)
    - `title` (string, required)
    - `name` (string, required)
    - `previewUrl` (string, required)

Three fields documented, one bare URL delivered. It reads as a broken tool.

It isn't. Every tool produces two renderings of one run: markdown for stdout, structured data for --json. The Output: block is generated from the output schema, so it has always described the --json half — it just never said so.

The fix

The heading now names the flag:

- Output:
+ Output (`--json`):

One line in methodBodyLines, which all three help views compose, so the root reference, the per-toolset view and the per-method view are covered at once.

It has to be the heading rather than a footnote somewhere: --help on a single tool prints no notes block, and that is the view you reach for right after a surprising result.

Two smaller things:

• The root help's notes block gains a line: Tool results print as markdown; the Output blocks below describe the --json data.
• The renderToolsHelp docblock claimed the Options block is the flags' only documentation. The notes block documents flag behaviour too, so that stopped being true.

What I left alone

formatPreviewStories still emits a bare URL per story. Over MCP, title and name already travel in structuredContent next to the text blocks, so repeating them in the markdown would duplicate what the structured half exists to carry.

Why this surfaced now: the two-rendering split is a straight port from the standalone MCP repo, which shipped no CLI. Over MCP both halves always arrive in the same reply, so the mismatch was invisible. storybook tools is the first surface that shows one and puts the other behind a flag.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

help.test.ts asserts all three renderings as full inline snapshots, so the new wording is readable straight from the diff. run.test.ts covers the run-level path to the help dump. No new test seam was needed.

Manual testing

Build once, then run each command from code/:

yarn nx compile core

1. node core/dist/bin/dispatcher.js tools stories preview --help — the schema block is headed Output (`--json`):
2. node core/dist/bin/dispatcher.js tools --help — the notes block under Commands: carries the new markdown/--json line
3. node core/dist/bin/dispatcher.js tools docs list --help — a tool with no output schema still prints no Output section at all
4. Against a running Storybook, run stories preview for real: stdout is a bare URL, and --json returns the shape the help documents

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update MIGRATION.MD

The changed text is itself the documentation — the tools help is generated at runtime and has no separate docs page.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 640f810b-9af9-48d0-9123-2fca5561b181

📥 Commits

Reviewing files that changed from the base of the PR and between 8256cee and 446cb9f.

📒 Files selected for processing (3)

• code/core/src/cli/tools/help.test.ts
• code/core/src/cli/tools/help.ts
• code/core/src/cli/tools/run.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

Walkthrough

The tools CLI help now identifies output schemas as the data returned by --json. Root help states that normal results print as markdown. Help tests verify the updated wording across root, toolset, and method views.

Changes

Tools CLI help output clarification

Layer / File(s)	Summary
Label structured output and document default rendering code/core/src/cli/tools/help.ts	The shared output heading now reads Output (\--json`):. Root help states that results print as markdown and that --json` prints the documented structured data. The discovery-surface comment identifies the flags block as the sole flag documentation location.
Validate rendered help text code/core/src/cli/tools/help.test.ts, code/core/src/cli/tools/run.test.ts	Help snapshots and the run-level assertion now require the qualified Output (\--json`):` heading across the affected views.

Merge Risk: ⚪ Minimal · up to 446cb

This change clarifies that the documented Output shape is returned by --json while leaving tool execution behavior unchanged; no actionable merge-blocking risk remains beyond normal checks and review.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}