Add "For agents" panel for Raven MCP and Stellar Skills - #2698
Conversation
Adds a floating "For agents" button to the bottom right of every docs page.
It opens a docked panel with the ways to point an AI agent at Stellar: the
Raven MCP server, Stellar Skills, and llms.txt.
Placement follows the design pass in Figma ("Agent menu"), which replaced the
original plan of a navbar dropdown next to search, so config/theme/navbar.ts
is untouched.
All copy and commands live in src/data/agentTools.ts, which both the panel and
the Building with AI page render. The page's per-client Tabs are now generated
from that data instead of hand-written, so the two cannot drift apart. Both
use the `mcp-client` tab group, so a tool picked in the panel is already
selected on the page and vice versa.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a persistent docs-only “For agents” panel for Raven MCP, Stellar Skills, and llms.txt.
Changes:
- Adds responsive panel, copy controls, keyboard navigation, and persistence.
- Centralizes agent setup commands and generates documentation tabs.
- Mounts the panel globally through the Docusaurus root.
Recommendation: NEEDS-CHANGES — address same-page tab synchronization, dialog accessibility, navigation focus restoration, and the incomplete single-source-of-truth claim.
Reviewed changes
Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
static/icons/sparkle.svg |
Adds trigger icon. |
src/theme/Root.tsx |
Globally mounts the panel. |
src/hooks/useSelectedAgentTool.ts |
Persists tool selection. |
src/data/agentTools.ts |
Defines shared agent instructions. |
src/components/ForAgentsPanel/styles.module.scss |
Styles responsive panel. |
src/components/ForAgentsPanel/index.tsx |
Implements panel behavior. |
src/components/ForAgentsPanel/CopyBlock.tsx |
Adds clipboard controls. |
src/components/AgentSetup/index.tsx |
Generates documentation tabs. |
docs/build/building-with-ai.mdx |
Replaces handwritten setup tabs. |
| const selectTool = useCallback((id: string) => { | ||
| setToolId(id); | ||
| try { | ||
| localStorage.setItem(AGENT_TOOL_STORAGE_KEY, id); |
There was a problem hiding this comment.
Fixed in bd6c848. Confirmed the bug: raw localStorage writes do not reach same-window listeners, so an open page kept its old tab. The hook now uses useStorageSlot from @docusaurus/theme-common, which also applies the site storage namespace (createStorageSlot → applyNamespace) that the manual key was ignoring. Local state backs it up so the picker still works when storage is a no-op (incognito, iframes).
Verified in a browser: picking Cursor in the panel switches the page tabs to Cursor with no reload, and picking Codex in the page tabs shows Codex selected when the panel reopens.
| // A docked panel would cover the content of the page the reader navigated to. | ||
| useEffect(() => { | ||
| setOpen(false); | ||
| }, [pathname]); |
There was a problem hiding this comment.
Fixed in bd6c848. The route-change effect now clears the restoration flag before closing, so focus stays where navigation put it. Verified: after following a panel link, document.activeElement is body, not the trigger. Closing with Esc or the close button still restores focus to the trigger.
| role="dialog" | ||
| aria-modal="false" |
There was a problem hiding this comment.
Fixed in bd6c848. Rather than declaring modality it does not have, the panel now matches its layout: aria-modal and the focus trap apply only when it is a full-screen sheet (useWindowSize() === "mobile", the same 996px breakpoint as the stylesheet). Docked on desktop the page behind stays visible and interactive, so it stays non-modal and focus is free to leave.
Verified: aria-modal="false" at 1440px, "true" at 390px, and 40 Tab presses in the mobile sheet keep focus inside the dialog.
| /** Section copy, shared so the panel and the page cannot drift apart. */ | ||
| export const AGENT_SECTIONS = { | ||
| raven: { | ||
| title: 'Raven MCP Server', | ||
| description: 'Connect your AI agent to Stellar data and tooling.', | ||
| guide: { label: 'Full guide', href: '/docs/build/building-with-ai' }, |
There was a problem hiding this comment.
Correct, and the PR description overclaimed. Narrowed rather than expanded: AGENT_SECTIONS is panel chrome, and the shared part is the per-client commands, which is where drift actually hurts. The page keeps its own ## headings because they are anchors other pages link to (#raven-mcp-server, #stellar-skills), and its prose is longer than a 400px panel holds. Comments in agentTools.ts and the panel now say exactly that, and the PR description has been corrected.
… when open
- Trigger label and sparkle use the body text color. It was link-colored,
which made a button read as a link.
- Redraw the sparkle with pinched points instead of a blob with a nub.
- "Try without installing" now shows the copy from the design ("Tell your
agent: Read skills.stellar.org before you start building on Stellar.")
instead of the placeholder that pointed at the website.
- Hide the trigger while the panel is open rather than sliding it left. The
panel has its own close button, and this matches the mobile behavior.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
1 similar comment
|
Preview is available here: |
- Selection now goes through Docusaurus' `useStorageSlot` instead of raw `localStorage`. The slot applies the site storage namespace and dispatches a synthetic `storage` event, so an already-open page's `<Tabs>` follow the panel immediately rather than on the next navigation. Local state backs it up so the picker still works when browser storage is unavailable. - Closing on route change no longer restores focus to the trigger, which was stealing focus from the destination page when following a panel link. Focus restoration now only happens when the reader closed the panel. - Modality matches the layout: `aria-modal` and the focus trap apply only when the panel is a full-screen sheet, since the docked desktop panel leaves the page visible and usable behind it. - Narrow the source-of-truth claim in comments. The per-client commands are shared with the Building with AI page; section headings are not, because they are `##` anchors other pages link to. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Requested: the panel belongs everywhere, including the homepage and meeting notes, not only under /docs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
1 similar comment
|
Preview is available here: |
|
Preview is available here: |
There was a problem hiding this comment.
LGTM! Verified on the preview build (static HTML + driven in a real browser at 1440px and 390px):
- Trigger renders site-wide (docs, homepage, even the 404 page), panel opens/closes, Esc closes and restores focus to the trigger, skills Install / Try-without-installing toggle swaps content, zero console errors.
- Tab sync is real both ways: picking Cursor in the panel flips both tab groups on Building with AI with no reload and survives a refresh; picking Codex in the page tabs shows Codex selected when the panel reopens. The hook goes through Docusaurus' useStorageSlot on docusaurus.tab.mcp-client, same slot as the page's .
- a11y: aria-modal is false docked at 1440px and true as the full-screen sheet at 390px; focus stayed trapped in the sheet across 25 Tab presses; panel closes on navigation without stealing focus from the destination.
- Page integrity: all four heading anchors (#raven-mcp-server, #stellar-skills, #using-llmstxt, #manual-installation) intact, breadcrumbs match production, both tab groups render all 6 clients, and every command in agentTools.ts is byte-identical to what production hand-writes today — no content drift from the refactor.
- Facts: raven.stellar.buzz/playground, skills.stellar.org, and both GitHub repos are live; /plugin install stellar-dev@stellar-dev matches the actual .claude-plugin/marketplace.json in stellar-dev-skill; /llms.txt serves on the preview.
Closes #2586.
Adds a floating "For agents" button to the bottom right of every docs page. It opens a docked panel with the three ways to point an AI agent at Stellar: the Raven MCP server, Stellar Skills, and
llms.txt.Placement follows MK's design pass, which replaced the original plan of a navbar dropdown next to search.
config/theme/navbar.tsis untouched.Shared content, one source of truth
src/data/agentTools.tsholds the per-client commands for every tool. Both the panel and the Building with AI page render them, so the commands cannot drift apart. The page's per-client<Tabs>are now generated from that data instead of hand-written.Section headings and prose are deliberately not shared: the page's
##headings are anchors other pages link to, and its prose is longer than a 400px panel holds.AGENT_SECTIONSis panel chrome only.Both also use the
mcp-clienttab group, which means the selection is genuinely shared: pick Codex in the panel and the Building with AI page opens on the Codex tab, and vice versa.What's here
src/data/agentTools.tssrc/components/ForAgentsPanel/src/components/AgentSetup/<Tabs>src/hooks/useSelectedAgentTool.tsdocusaurus.tab.mcp-clientsrc/theme/Root.tsxBehavior
--ifm-*variables only, no hardcoded colors. The selected pill inverts (black on white, white on black) to match the mockup in both themes.Esccloses and returns focus to the trigger, arrow keys plusHome/Endmove across the tool pills (role="radiogroup").aria-modaland traps focus; docked on desktop the page behind stays usable, so it does neither.Verified
pnpm buildpasses,pnpm lintis clean, andpnpm check:mdxis clean. Driven in a real browser (Playwright, built output): trigger renders, panel opens and closes, tool switching swaps the commands, the skills toggle swaps its content, the copy button writes the right command to the clipboard,Escrestores focus, the trigger renders on the homepage and meeting notes as well as docs, and the tool selection syncs both ways with the page's tabs with no reload. Also checked after review: focus is not stolen on navigation,aria-modalflips with the breakpoint, and focus stays trapped in the mobile sheet across 40 Tab presses. No console errors.Needs a decision before merge
--ifm-link-color, which is the site's teal. Changing that would mean hardcoding a color.~/.cursor/mcp.jsonis no longer inline code, and themcp-remotelink moved from inside the sentence to a link line under the snippet. Fixable by adding a rich-text field to the data if it matters.🤖 Generated with Claude Code