feat(faq): add FAQ sections to 47 docs pages with :::faq directive + FAQPage JSON-LD

components/faq.tsx

@@ -0,0 +1,34 @@
+// ABOUTME: FAQ accordion section rendered from the :::faq MDX directive.
+// ABOUTME: Emits FAQPage JSON-LD (built by remark-custom-directives) for search engines.
+
+import type { ReactNode } from 'react';
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@/components/ui/accordion';
+
+export function FAQ({ jsonLd, children }: { jsonLd?: string; children: ReactNode }) {
+  return (
+    <section className="my-6">
+      {jsonLd ? (
+        <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLd }} />
+      ) : null}
+      <Accordion type="single" collapsible className="w-full">
+        {children}
+      </Accordion>
+    </section>
+  );
+}
+
+export function FAQItem({ question, children }: { question: string; children: ReactNode }) {
+  return (
+    <AccordionItem value={question}>
+      <AccordionTrigger className="text-base">{question}</AccordionTrigger>
+      <AccordionContent>
+        <div className="px-2 pb-4 text-fd-muted-foreground [&>p]:my-2">{children}</div>
+      </AccordionContent>
+    </AccordionItem>
+  );
+}

components/mdx/index.tsx

@@ -9,6 +9,7 @@ import { AuthorProfile } from '@/components/author-profile';
 import { Callout } from '@/components/callout';
 import * as CardComponents from '@/components/card';
 import { docskit } from '@/components/docskit/components';
+import { FAQ, FAQItem } from '@/components/faq';
 import { IntegrationGrid } from '@/components/integration-grid';
 import { OrderedList, UnorderedList } from '@/components/lists';
 import { RecipeCard, RecipeGrid } from '@/components/recipe-card';
@@ -41,6 +42,8 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
     Badge,
     Callout,
     ...CardComponents,
+    FAQ,
+    FAQItem,
     ...FilesComponents,
     ...StepsComponents,
     ...TabsComponents,

content/docs/integrations/agentkit.mdx

@@ -35,6 +35,23 @@ const page = browser.contexts()[0].pages()[0];
 
 Full runnable starter: [Steel + AgentKit recipe →](/cookbook/agentkit)
 
+### FAQ
+
+:::faq
+### Do I need to change my existing AgentKit code to use Steel?
+
+No — AgentKit keeps handling orchestration, routing, and shared state. Inside a tool handler you create a Steel session, connect Playwright over CDP, and call the resulting `page` from your handlers.
+
+### How do I connect AgentKit to a Steel browser session?
+
+Call `steel.sessions.create()`, connect with `chromium.connectOverCDP()` using the session's `websocketUrl` plus your `apiKey`, and take the first page of `browser.contexts()[0]` as the page your AgentKit tool handlers drive.
+
+### Does AgentKit work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — pass them to `sessions.create()` (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`). They're Steel-side session options, so your agent network and routers don't change.
+:::
+
+
 ### Resources
 
 *   [AgentKit documentation](https://agentkit.inngest.com/overview) – Official documentation for AgentKit

content/docs/integrations/agno.mdx

@@ -37,6 +37,27 @@ page = browser.contexts[0].pages[0]
 
 Full runnable starter: [Steel + Agno recipe →](/cookbook/agno)
 
+### FAQ
+
+:::faq
+### Do I need to change my existing Agno code to use Steel?
+
+No — Steel is exposed to Agno as a regular `Toolkit`. You connect Playwright to a Steel session over CDP and wrap the resulting `page` in the toolkit; agents, teams, memory, and reasoning stay as they were.
+
+### How do I connect Agno to a Steel browser session?
+
+Create a session with `steel.sessions.create()`, connect with `playwright.chromium.connect_over_cdp(f"{session.websocket_url}&apiKey={STEEL_API_KEY}")`, take `browser.contexts[0].pages[0]` as your page, and wrap it in an Agno `Toolkit`.
+
+### Does Agno work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — set them at session creation (e.g. `use_proxy`, `solve_captcha`, `stealth_config` on `sessions.create()`). Agno only sees the Playwright page, so these options don't touch your agent code.
+
+### Which model providers can I use with Agno on Steel?
+
+Any Agno-supported provider — Agno is model-agnostic and natively multi-modal, so OpenAI, Anthropic, or others all work. You just need the provider key plus your Steel API key.
+:::
+
+
 ### Resources
 
 *   [Agno documentation](https://docs.agno.com/) – Concepts, APIs, and examples for agents, teams, memory, and reasoning

content/docs/integrations/ai-sdk.mdx

@@ -46,6 +46,31 @@ Full runnable starters:
 *   Server-only typed agent: [Steel + Vercel AI SDK recipe →](/cookbook/vercel-ai-sdk)
 *   Next.js chat UI with embedded Steel Live View: [Steel + Vercel AI SDK + Next.js recipe →](/cookbook/vercel-ai-sdk-nextjs)
 
+### FAQ
+
+:::faq
+### Do I need to change my existing Vercel AI SDK code to use Steel?
+
+No — Steel slots in as a typed `tool()` from the `ai` package. The tool's `execute` opens a Steel session and connects Playwright over CDP; your streaming, provider setup, and the rest of the agent stay the same.
+
+### How do I connect the Vercel AI SDK to a Steel browser session?
+
+Inside a `tool()`'s `execute`, call `steel.sessions.create()` and connect with `chromium.connectOverCDP()` using the session's `websocketUrl` plus your `apiKey`. Subsequent tools (navigate, snapshot, extract) drive that browser and return typed results.
+
+### Does the Vercel AI SDK work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — pass them to `sessions.create()` (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`). They're session-creation options and don't touch the AI SDK's tool or streaming layers.
+
+### Can users watch the browser while the agent runs in a chat UI?
+
+Yes — the tool returns `liveViewUrl` (`session.sessionViewerUrl`), and the Next.js recipe embeds Steel's Live View iframe alongside the chat so users watch the browser as the agent works.
+
+### Which model providers can I use?
+
+Any AI SDK-supported provider — install a provider package like `@ai-sdk/anthropic` and bring an Anthropic, OpenAI, or other provider key. Steel only needs the CDP connection, so the model choice is independent. For current model recommendations, see the [Steel leaderboard](https://leaderboard.steel.dev/).
+:::
+
+
 ### Resources
 
 *   [Vercel AI SDK documentation](https://ai-sdk.dev/) – Tools, agents, streaming, and providers

content/docs/integrations/browser-use.mdx

@@ -40,6 +40,31 @@ Full runnable starters:
 *   Auto-solve captchas with Steel + Browser Use: [Captcha auto recipe →](/cookbook/browser-use-captcha-auto)
 *   Hand off captchas to a human via Steel Live View: [Manual captcha recipe →](/cookbook/browser-use-captcha-manual)
 
+### FAQ
+
+:::faq
+### Do I need to change my existing Browser Use code to use Steel?
+
+No — pass a `BrowserSession(cdp_url=...)` into your `Agent` and Browser Use drives Steel's cloud browser instead of a local one. Your task, LLM config, and `agent.run()` loop stay the same.
+
+### How do I connect Browser Use to a Steel browser session?
+
+Create a session with `client.sessions.create()`, build the CDP URL as `f"{session.websocket_url}&apiKey={STEEL_API_KEY}"`, and pass it to `BrowserSession(cdp_url=cdp_url)` on the `Agent`.
+
+### Does Browser Use work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — these are session-creation options (e.g. `use_proxy`, `solve_captcha`, `stealth_config` on `sessions.create`), invisible to Browser Use itself. The page links dedicated recipes for auto-solving CAPTCHAs and handing them to a human.
+
+### Which LLMs work with Browser Use on Steel?
+
+Vision-capable models — the page calls out GPT-5, Claude Sonnet 4, and Gemini 3 Pro, and the example wires `ChatOpenAI(model="gpt-5")`. You also need Python 3.11+. For up-to-date model recommendations for browser agents, check the [Steel leaderboard](https://leaderboard.steel.dev/).
+
+### Can a human take over when the agent hits a CAPTCHA?
+
+Yes — Steel's Live View lets a person solve the CAPTCHA in the running session while the agent waits. The page links a manual-captcha recipe showing this hand-off pattern.
+:::
+
+
 ### Resources
 
 *   [Browser Use documentation](https://docs.browser-use.com/) – Comprehensive guide to the browser-use library

content/docs/integrations/claude-agent-sdk.mdx

@@ -55,6 +55,27 @@ Pass the server into `query()` via `mcpServers` and pre-approve calls with `allo
 
 Full runnable starter: [Steel + Claude Agent SDK recipe →](/cookbook/claude-agent-sdk)
 
+### FAQ
+
+:::faq
+### Do I need to change my existing Claude Agent SDK code to use Steel?
+
+No — Steel is exposed as in-process MCP tools. Wrap a Steel session in a `tool()`, bundle it with `createSdkMcpServer`, and your `query()` loop and message handling stay exactly the same.
+
+### How do I connect the Claude Agent SDK to a Steel browser session?
+
+Define a `tool()` that calls `steel.sessions.create()` and connects via `chromium.connectOverCDP()` with the session's `websocketUrl` plus `apiKey`, bundle it into an in-process MCP server with `createSdkMcpServer`, then pass that server to `query()` via `mcpServers` and pre-approve calls with `allowedTools`.
+
+### Does the Claude Agent SDK work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — enable them when your tool creates the session (e.g. `useProxy`, `solveCaptcha`, `stealthConfig` on `sessions.create()`). The SDK's agent loop and MCP plumbing are unaffected.
+
+### Is the Steel integration available in both TypeScript and Python?
+
+Yes — use `@anthropic-ai/claude-agent-sdk` for TypeScript or `claude-agent-sdk` for Python, plus `steel-sdk` and `playwright`. You'll also need an Anthropic API key with access to a Claude 4 model.
+:::
+
+
 ### Resources
 
 *   [Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview) – Agent loop, custom MCP tools, hooks, subagents

content/docs/integrations/claude-code.mdx

@@ -67,6 +67,31 @@ After a successful run, Claude Code can help turn the browser workflow into some
 *   **First runs are usually the roughest.** Dynamic web apps often need a few retries before the workflow is stable.
 *   **Authenticated sites work best with prepared Steel auth state.** Reusing profiles or auth context is generally more reliable than repeated interactive logins.
 
+### FAQ
+
+:::faq
+### Do I need to write integration code to use Steel with Claude Code?
+
+No — the integration works through the Steel CLI. Install it with `curl -LsSf https://setup.steel.dev | sh`, run `steel login`, and Claude Code can start and control Steel sessions, scrape rendered pages, and run computer-use actions from the terminal.
+
+### How does Claude Code connect to a Steel browser session?
+
+Through Steel CLI commands in its shell. For better command discovery and more reliable workflows, install the `steel-browser` skill with `npx skills add steel-dev/skills --skill steel-browser -a claude-code -g` and restart Claude Code so it discovers the skill.
+
+### Does Claude Code work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — those are properties of the Steel session itself, not the client driving it. Sessions Claude Code starts run on the same Sessions API that supports `useProxy`, `solveCaptcha`, and `stealthConfig` at creation time.
+
+### How should I handle sites that require login?
+
+Prepare reusable auth state in Steel ahead of time via the Profiles API or Reusing Auth Context, rather than asking Claude Code to log in from scratch every run. The page calls prepared auth state more reliable than repeated interactive logins.
+
+### Can I watch what Claude Code is doing in the browser?
+
+Yes — Steel sessions return a viewer URL for monitoring the browser in real time. That's especially useful when Claude Code hits a modal, a sign-in wall, or a page that misbehaves, and successful runs can then be turned into scripts or runbooks.
+:::
+
+
 ### Resources
 
 *   [Give Claude Code a real browser](https://steel.dev/blog/give-claude-code-a-real-browser) – Blog post on using Claude Code with Steel

content/docs/integrations/claude-computer-use.mdx

@@ -42,6 +42,27 @@ Full runnable starters:
 *   Build a Claude Computer Use loop on Steel: [Steel + Claude Computer Use recipe →](/cookbook/claude-computer-use)
 *   Drive a mobile-viewport Steel session with Claude: [Mobile recipe →](/cookbook/claude-computer-use-mobile)
 
+### FAQ
+
+:::faq
+### Do I need Playwright or CSS selectors to use Claude Computer Use with Steel?
+
+No — Claude's computer-use loop is vision-based. Claude looks at screenshots, decides actions like click, type, or scroll, and Steel executes them through its `sessions.computer` API, so there are no custom selectors to write.
+
+### How do I connect Claude Computer Use to a Steel browser session?
+
+Create a session with explicit `dimensions` (the example uses 1024x768), take screenshots via `steel.sessions.computer(session.id, { action: "take_screenshot" })`, send the `base64_image` to Claude's `computer_20251124` tool, and route Claude's returned actions back through `steel.sessions.computer({ action: ... })`.
+
+### Does Claude Computer Use work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — the page notes it pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. These are enabled at session creation (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`) and don't change the agent loop.
+
+### How does the screenshot/action loop actually work?
+
+Steel takes a screenshot, you send it to Claude with the computer-use tool, Claude returns the next action (click, type, scroll), and Steel executes it via `sessions.computer` — then you screenshot again and repeat until the task completes.
+:::
+
+
 ### Resources
 
 *   [Anthropic Computer Use documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) – Official documentation from Anthropic

content/docs/integrations/codex.mdx

@@ -59,6 +59,31 @@ That works well for jobs like recurring research, internal reporting, or lightwe
 *   **Command approvals depend on your Codex settings.** Codex may ask before running shell commands unless you have configured a more permissive approval mode.
 *   **Authenticated workflows usually need preconfigured Steel auth state.** For reusable login state, see [Profiles API](/overview/profiles-api/overview) and [Reusing Auth Context](/overview/sessions-api/reusing-auth-context).
 
+### FAQ
+
+:::faq
+### Do I need to write integration code to use Steel with Codex?
+
+No — the integration works through the Steel CLI. Install it with `curl -LsSf https://setup.steel.dev | sh`, run `steel login`, and Codex can start and control Steel sessions, scrape rendered pages, and run computer-use actions from the terminal.
+
+### How does Codex connect to a Steel browser session?
+
+Once Steel CLI is on your `PATH`, Codex inspects command help, runs the commands it needs, and verifies results from the terminal. For better command discovery, install the `steel-browser` skill with `npx skills add steel-dev/skills --skill steel-browser -a codex -g` and restart Codex.
+
+### Does Codex work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — those are properties of the Steel session, not of Codex. Sessions started from the CLI run on the same Sessions API that supports `useProxy`, `solveCaptcha`, and `stealthConfig` at creation time.
+
+### How do I turn a one-off Codex browser run into a recurring job?
+
+After a successful manual run, prompt Codex with "Write a bash script based on what you just did", then schedule the script with cron or another runner. The page recommends this run-once, convert, schedule pattern for recurring research, reporting, and monitoring.
+
+### What should I know before pointing Codex at authenticated sites?
+
+Authenticated workflows usually need preconfigured Steel auth state — set up reusable login state via the Profiles API or Reusing Auth Context instead of interactive logins each run. Also note Codex may ask for command approvals depending on your approval mode.
+:::
+
+
 ### Resources
 
 *   [Codex + Steel + Resend blog post](https://steel.dev/blog/codex-wired-steel-and-resend-into-a-daily-newsletter) – Example workflow for building a daily newsletter with Codex

content/docs/integrations/crewai.mdx

@@ -38,6 +38,27 @@ class SteelScrapeTool(BaseTool):
 
 Full runnable starter: [Steel + CrewAI recipe →](/cookbook/crewai)
 
+### FAQ
+
+:::faq
+### Do I need to change my existing CrewAI code to use Steel?
+
+No — Steel plugs in as a regular CrewAI tool. Define a `BaseTool` subclass whose `_run` method calls Steel, hand it to your agents, and your crews, flows, and memory setup stay untouched.
+
+### How do I connect CrewAI to Steel?
+
+Expose Steel as a CrewAI `BaseTool`: instantiate the Steel client in `__init__` and call it from `_run`. The page's example tool scrapes a URL with `self._steel.scrape(url=url, format=["markdown"])` and returns markdown to the agent.
+
+### Does CrewAI work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — when your tool creates Steel sessions you can enable these at session creation (e.g. `use_proxy`, `solve_captcha`, `stealth_config`). They're Steel-side options, so CrewAI's orchestration doesn't change.
+
+### Do I need a full browser session, or is scraping enough for a crew?
+
+For read-only research, the page's tool uses Steel's `scrape` API to return page markdown — no session management needed. For interactive flows (forms, clicks, multi-step navigation), create a Steel session inside the tool instead.
+:::
+
+
 ### Resources
 
 *   [CrewAI documentation](https://docs.crewai.com/) – Official documentation for CrewAI

content/docs/integrations/gemini-computer-use.mdx

@@ -38,6 +38,27 @@ const { base64_image } = await steel.sessions.computer(session.id, {
 
 Full runnable starter: [Steel + Gemini Computer Use recipe →](/cookbook/gemini-computer-use)
 
+### FAQ
+
+:::faq
+### Do I need Playwright or CSS selectors to use Gemini Computer Use with Steel?
+
+No — Gemini's loop is vision-based. Gemini reads screenshots, decides actions like click, type, or scroll, and Steel executes them via its `sessions.computer` API, so no custom selectors are needed.
+
+### How do I connect Gemini Computer Use to a Steel browser session?
+
+Create a session with explicit `dimensions` (the example uses 1280x800), take a screenshot with `steel.sessions.computer(session.id, { action: "take_screenshot" })`, send the `base64_image` to Gemini 3 with its built-in computer-use tool, and route Gemini's returned actions back through `steel.sessions.computer({ action: ... })`.
+
+### Does Gemini Computer Use work with Steel's proxies, stealth mode, and CAPTCHA solving?
+
+Yes — the page notes it pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. These are session-creation options (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`) and don't change the agent loop.
+
+### Which Gemini model do I need, and how does the loop work?
+
+A Gemini 3 model with computer use — the tool is built in. Steel screenshots the session, Gemini decides the next action, Steel executes it via `sessions.computer`, and the loop repeats until the task completes. Consult the [Steel leaderboard](https://leaderboard.steel.dev/) for the most recent model recommendations.
+:::
+
+
 ### Resources
 
 *   [Gemini Computer Use documentation](https://ai.google.dev/gemini-api/docs/computer-use) – Official documentation from Google