docs(agent-playground,optimization,falcon-ai): five captures and the cold-read fixes

[khushalsonawat]

What

The follow-on to #812. It was pushed while #812 was still open, but #812 merged first, so this commit never made it into that PR and none of it is live.

Five captures

Page	On screen	Callout
agent-playground/guides/create-agent	The Agents list, five agents with real column values	none, see Known gaps
.../build-workflow/configure-an-llm-prompt-node	Node drawer: Prompt Name, version select and Draft badge, Select Model, the message boxes	Sets the node's name
.../build-workflow/set-input-variables	The Variables drawer, eight variables filled	One value per prompt variable
optimization/guides/run-an-optimization	A dataset's Optimization tab with no runs yet	2, on the tab and on Run Optimization
falcon-ai/.../open-shortcut-panel	Replaced. The side panel open over the Tracing list	Past chats open here

The side panel replacement matters on its own: the page describes the panel three times and the old capture showed the floating button instead, so a reader who pressed ⌘K saw a UI matching none of the images.

The cold-read fixes, from four reader-analyst passes on the pages the captures changed most.

Why

One finding landed on all four pages: the captions restated the paragraph directly above them. Six of nine on chat-with-falcon-ai. The reader's words were that it taught them to stop reading captions, which then buried the two that did carry something. Ten are rewritten to say what the picture can't.

Three further findings were rated blockers by the readers:

• Three <img> embeds pointed at files that never existed, on run-an-optimization and read-optimization-results. A broken box with an italic caption describing what you cannot see reads as a page falling apart, and one of them landed exactly where a reader matches field names against their own screen. No docs page now references a missing image, apart from one pre-existing cookbook .mp4
• A failed connection test on connect-mcp-server had nowhere to go: the page named two failure strings and stopped. It now sends the reader back to Edit with the three fields worth re-checking
• The Variables capture sat directly above a worked example about invoices while showing variables about competitive research, so readers hunted the picture for an invoice. Moved up to the step that opens the drawer

What cases does this cover

• A tool call that took no arguments has no Parameters section, so a reader who opens one and finds only Result isn't looking at a bug. The anatomy is now three bullets instead of one semicolon-chained sentence
• An empty or short Variables list usually means an unsaved edit, not a missing variable. That was the likeliest first-timer panic and it was stranded at the tail of a paragraph; it's a Note now
• Both buttons on the empty Connectors page open the same form, which is exactly the state a first-timer sees
• A variable's value field sits underneath its name, not beside it. The page said beside

How

Captured over CDP at 3024×1890, annotated per annotation-conventions.md. Every oval was verified against its source programmatically rather than by eye, using empty_boxes-style flatness and darkness checks: all fourteen sit on empty canvas at std ≤ 2.4.

Masking: the competitor names behind {{KNOWN_COMPETITORS}} in the Variables drawer.

Known gaps

• create-agent.png ships without a callout. Every straight path to the Create Agent button is blocked: horizontal runs through View Docs and renders as a strikethrough on its label, vertical from below crosses the Updated at column on five rows, and vertical from above is blocked by the page header's own View Docs. Caption-only was the better of the two bad options
• Not written, because I could not verify them: what a successful Create looks like on the connector form (I never submitted it), and how long an optimization run takes
• The readers' top recommendation for chat-with-falcon-ai was to crop the screenshots, since four consecutive shots are the same empty state with a different small menu open. That contradicts §11's uniform full-window rule, and the ruling was to keep full-window

Recording

n/a — static pages.

Checklist

• All touched pages render locally (200)
• Every referenced asset resolves; no page references a missing image
• Every oval verified clear of UI against its source
• Documentation updated