docs: add AI-native onboarding group (docs for AI/agents, MCP setup, prompt library)

[claude]

Requested by Matthew Cruz · Slack thread

What / why

Option C (paved paths) Slice 4 — AI-native onboarding group (ethereum-optimism/solutions, projects/docs-improver/plans/option-c-paved-paths.md). The docs platform already serves machine-readable surfaces (llms.txt index, per-page markdown, a contextual copy/open-in-assistant menu configured in docs.json) — nothing on the site tells readers or agents about them. This PR surfaces those affordances as a small Get-Started-adjacent nav group with three new pages.

Before: an AI-assisted reader or agent has no on-site pointer to llms.txt or per-page markdown, no guidance for wiring the docs into an MCP-capable assistant, and no curated prompts — every assistant starts from scraped HTML and stale training data.

After: an "AI & Agents" group sits beside the Quickstart group with:

• ai/docs-for-agents — the machine-readable surfaces: the llms.txt index, .md-suffix per-page access, the contextual copy/open-in-ChatGPT/open-in-Claude menu, and grounding tips (specs are normative; re-check version-sensitive values).
• ai/mcp-setup — how to wire the docs into an MCP-capable assistant. No hosted MCP endpoint exists for docs.optimism.io today, so the page documents the llms.txt/markdown route (works with or without MCP) plus a reference fetch-server config; the hosted-MCP request is filed separately as ethereum-optimism/solutions#959 per the plan's fallback.
• ai/prompt-library — nine curated prompts mapped to the traced reader journeys (batcher cost audit, deposit flow, challenger deployment, node-stack choice, node setup, L1 bridging, fee estimation, Supersim, stuck withdrawal). Every entry names its persona (2 chain operator, 2 node operator, 5 app developer) and links at least one in-site page; entries will cross-link solution guides as later slices ship them. Carries last-reviewed: frontmatter per the plan's curation contract.

docs.json delta: one 8-line nav group, zero moves, zero redirects.

Verification (lite accuracy pass)

• Contextual-menu claim vs docs.json: verified in-repo — contextual.options is exactly ["copy", "chatgpt", "claude"] (docs.json lines 31–37 on this branch); the page describes exactly those three actions and no others.
• In-site link targets: all 20 unique in-site targets referenced across the three pages (markdown links + the .md URLs inside prompt blocks) verified to exist as .mdx files in the repo by script; link text checked against each target's frontmatter title.
• Live URL resolution (llms.txt + per-page .md): could not be completed from this session — needs one human browser check before merge. Attempted https://docs.optimism.io/llms.txt, /node-operators/overview.md, and /chain-operators/guides/configuration/batcher.md via two independent fetch pipelines; every request to docs.optimism.io returns 403 to non-browser clients from this environment (the session's egress gateway policy-denies the host, and the site's bot protection 403s the web-fetch pipeline — the whole host including / behaves the same, so this is not a missing-page signal). Corroboration used instead: web search confirms the docs reference /llms.txt as the complete documentation index, and the merged Option C plan records that the platform serves llms.txt and per-page .md natively. Reviewer: please open https://docs.optimism.io/llms.txt and one .md page URL in a browser and confirm both render raw markdown.
• Hosted MCP endpoint: availability on the current plan unconfirmed from this session → per the plan's fallback, the page leads with the llms.txt/markdown route and the hosted-MCP request is filed as ethereum-optimism/solutions#959.
• External links: the MCP reference fetch server path (modelcontextprotocol/servers → src/fetch) and its uvx mcp-server-fetch invocation verified against the live repo README.
• docs.json parses as valid JSON after the edit.

Reviewer checklist

• Browser check: https://docs.optimism.io/llms.txt and one per-page .md URL render raw markdown (see verification note above)
• Nav placement: "AI & Agents" beside Quickstart is the right Get-Started-adjacent position (C1's router may re-home it later)
• Prompt library: personas and page pairings read correctly; nothing over-promises
• MCP page makes no claims about a hosted endpoint we don't have

Tracking

Tracks ethereum-optimism/solutions#958
Part of the serialized docs.json lane; will be rebased as earlier lane PRs merge.
More context: projects/docs-improver/README.md in ethereum-optimism/solutions.

🤖 Drafted by the docs-improver agent — review before merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L

---

Generated by Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Optimism-Docs	🟢 Ready	View Preview	Jul 16, 2026, 7:32 AM

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Optimism-Docs	🟡 Building	–	Jul 16, 2026, 7:31 AM

[claude]

synced with develop after #21841 merged.