Add "For agents" panel for Raven MCP and Stellar Skills by oceans404 · Pull Request #2698 · stellar/stellar-docs

oceans404 · 2026-07-27T13:07:27Z

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.ts is untouched.

Shared content, one source of truth

src/data/agentTools.ts holds 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_SECTIONS is panel chrome only.

Both also use the mcp-client tab 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

File	Purpose
`src/data/agentTools.ts`	Shared tools, commands, and section copy (no JSX, so either side can render it)
`src/components/ForAgentsPanel/`	The trigger, the docked panel, and the copy blocks
`src/components/AgentSetup/`	The docs-page rendering of the same data as `<Tabs>`
`src/hooks/useSelectedAgentTool.ts`	Tool selection, via Docusaurus' storage slot for `docusaurus.tab.mcp-client`
`src/theme/Root.tsx`	Mounts the panel once for the whole site, above the router

Behavior

Renders on every page: docs, the homepage, and meeting notes.
Light and dark mode from --ifm-* variables only, no hardcoded colors. The selected pill inverts (black on white, white on black) to match the mockup in both themes.
Desktop: 400px panel docked to the right edge below the navbar. The trigger hides while the panel is open, since the panel has its own close button. Below 996px the panel becomes a full-screen sheet.
Copy button per command block, with a checkmark on success.
Keyboard: Esc closes and returns focus to the trigger, arrow keys plus Home/End move across the tool pills (role="radiogroup").
Modality matches layout: as a full-screen sheet it is aria-modal and traps focus; docked on desktop the page behind stays usable, so it does neither.
Closes on navigation, so the panel never covers the page you just opened, without stealing focus from the destination.

Verified

pnpm build passes, pnpm lint is clean, and pnpm check:mdx is 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, Esc restores 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-modal flips with the breakpoint, and focus stays trapped in the mobile sheet across 40 Tab presses. No console errors.

Needs a decision before merge

Links render teal, not purple. The mockup's links are purple; these use --ifm-link-color, which is the site's teal. Changing that would mean hardcoding a color.
Two small losses on the Building with AI page from sharing plain-text notes: ~/.cursor/mcp.json is no longer inline code, and the mcp-remote link 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.
Mobile is my call, not design's. The Figma section only has 1440px states, so the full-screen sheet below 996px needs a look.

🤖 Generated with Claude Code

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>

Copilot

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.

oceans404 · 2026-07-27T13:24:30Z

+  const selectTool = useCallback((id: string) => {
+    setToolId(id);
+    try {
+      localStorage.setItem(AGENT_TOOL_STORAGE_KEY, id);


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.

oceans404 · 2026-07-27T13:24:31Z

+  // A docked panel would cover the content of the page the reader navigated to.
+  useEffect(() => {
+    setOpen(false);
+  }, [pathname]);


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.

oceans404 · 2026-07-27T13:24:33Z

+        role="dialog"
+        aria-modal="false"


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.

oceans404 · 2026-07-27T13:24:34Z

+/** 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' },


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>

stellar-jenkins-ci · 2026-07-27T13:16:55Z

Preview is available here:
http://developers-pr2698.previews.kube001.services.stellar-ops.com

stellar-jenkins-ci · 2026-07-27T13:21:58Z

Preview is available here:
http://developers-pr2698.previews.kube001.services.stellar-ops.com

- 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>

stellar-jenkins-ci · 2026-07-27T13:32:23Z

Preview is available here:
http://developers-pr2698.previews.kube001.services.stellar-ops.com

stellar-jenkins-ci · 2026-07-27T13:36:01Z

Preview is available here:
http://developers-pr2698.previews.kube001.services.stellar-ops.com

The preview at developers-pr2698 is serving bd6c848, one commit behind the branch, so the "For agents" trigger is missing on the homepage there even though c89d154 removed the docs-only gate. No code change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

stellar-jenkins-ci · 2026-07-28T02:39:07Z

Preview is available here:
http://developers-pr2698.previews.kube001.services.stellar-ops.com

Copilot AI review requested due to automatic review settings July 27, 2026 13:07

Copilot started reviewing on behalf of oceans404 July 27, 2026 13:07 View session

Copilot AI reviewed Jul 27, 2026

View reviewed changes

oceans404 and others added 2 commits July 27, 2026 08:24

Show the "For agents" trigger on every page, not just docs

c89d154

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>

oceans404 requested review from ElliotFriend, kaankacar and mmazco July 27, 2026 13:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add "For agents" panel for Raven MCP and Stellar Skills - #2698

Add "For agents" panel for Raven MCP and Stellar Skills#2698
oceans404 wants to merge 5 commits into
mainfrom
for-agents-panel

oceans404 commented Jul 27, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

oceans404 Jul 27, 2026

Uh oh!

oceans404 Jul 27, 2026

Uh oh!

oceans404 Jul 27, 2026

Uh oh!

oceans404 Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

oceans404 commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Shared content, one source of truth

What's here

Behavior

Verified

Needs a decision before merge

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

oceans404 Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

oceans404 Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

oceans404 Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

oceans404 Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

oceans404 commented Jul 27, 2026 •

edited

Loading