Add llms-only FAQ sections to high-traffic docs pages

fern/products/api-def/openapi/overview.mdx

@@ -167,3 +167,34 @@ This will initialize a directory like the following:
   </Folder>
 </Files>                                                
 
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: How do I use an OpenAPI spec with Fern?**
+A: Run `fern init --openapi ./path/to/openapi` (a local file or a URL) to create a `fern` folder that references your spec, then generate docs with `fern generate --docs` or SDKs with `fern generate`.
+
+**Q: Does Fern support OpenAPI 3.0 and 3.1?**
+A: Yes. Fern is compatible with the latest OpenAPI release (currently v3.1.1) and reads specs written in earlier 3.x versions, in either YAML or JSON.
+
+**Q: What Fern-specific OpenAPI extensions are available?**
+A: `x-fern-*` extensions customize generation without changing the meaning of your API: SDK group and method names, availability, audiences, base paths, default values, enum names, examples, global headers and parameters, idempotency, pagination, parameter and property names, retries, schema names, and server names. See the [extensions overview](/learn/api-definitions/openapi/extensions/overview).
+
+**Q: How do I use `x-fern-sdk-group-name` and `x-fern-sdk-method-name`?**
+A: Add them to an operation to control where it lands in the generated SDK: the group becomes the sub-client (`client.users.create(...)`) and the method name becomes the function. Multiple group names nest sub-clients. See [SDK method names](/learn/api-definitions/openapi/extensions/method-names).
+
+**Q: How do I deprecate an endpoint in OpenAPI with Fern?**
+A: Set `x-fern-availability: deprecated` on the operation. The API Reference shows a `Deprecated` tag, and the TypeScript generator marks the client method `@deprecated`. See [Availability](/learn/api-definitions/openapi/extensions/availability).
+
+**Q: Does Fern support PATCH, PUT, DELETE, and other HTTP methods?**
+A: Yes. Fern reads the standard OpenAPI operations for a path, so every HTTP method your spec declares is documented and generated.
+
+**Q: How do I configure retries with `x-fern-retries`?**
+A: Add `x-fern-retries: { disabled: true }` to an operation to turn retries off for it in every SDK language, overriding user-level retry settings. Use it for non-idempotent operations such as payments or order creation. See [Retry behavior](/learn/api-definitions/openapi/extensions/retry-behavior).
+
+**Q: Can I use an OpenAPI overlay with Fern?**
+A: Yes, and it's the recommended way to customize: keep your core spec untouched and put Fern extensions in an [overlay file](/learn/api-definitions/openapi/overlays).
+
+**Q: What should I fix in my spec before generating?**
+A: Give every endpoint a clear `operationId`, define reusable schemas under `components/schemas` and reference them with `$ref` rather than inlining, and keep customizations in overlays.
+</llms-only>

fern/products/cli-api-reference/pages/cli-get-started.mdx

@@ -109,3 +109,32 @@ The [general](/learn/cli-api-reference/cli-reference/general-commands), [docs](/
 
   </Accordion>
 </AccordionGroup>
+
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: What are the main Fern CLI commands?**
+A: `fern init` creates a project, `fern check` validates it, `fern docs dev` previews docs locally, `fern generate --docs` publishes docs, and `fern generate` builds and publishes SDKs. The [general](/learn/cli-api-reference/cli-reference/general-commands), [docs](/learn/cli-api-reference/cli-reference/docs-commands), and [SDK](/learn/cli-api-reference/cli-reference/sdk-commands) references document every command and flag.
+
+**Q: How do I install the Fern CLI?**
+A: `npm install -g fern-api` (Node.js 22 or higher) or `brew install fern-api` on macOS and Linux. Verify with `fern -v`.
+
+**Q: Can I install Fern per project instead of globally?**
+A: Yes. Run `npm install fern-api`, set `"version": "*"` in `fern.config.json`, and invoke commands through npm (`npm fern check`). Homebrew supports system-wide installs only.
+
+**Q: What does `fern generate` do?**
+A: It runs SDK generation for the generator groups in `generators.yml`. Add `--group <name>` for one group, `--preview` to generate into a local `.preview/` folder, and `--local` to generate on your own machine.
+
+**Q: How do I use `fern generate --docs` versus `fern generate`?**
+A: `--docs` builds and publishes your documentation site; without it, the command builds and publishes SDKs. They read the same project but different configuration: `docs.yml` for docs, `generators.yml` groups for SDKs.
+
+**Q: What does `fern check` do?**
+A: It validates your API definition and configuration — `fern.config.json`, `generators.yml`, and `docs.yml` — including broken internal links and API examples. It prints nothing when everything passes.
+
+**Q: What's `fern init` and when do I use it?**
+A: Use it once per project to create the `fern` folder. `fern init --openapi <path or URL>` starts from an existing spec, `fern init --docs` adds a sample docs site, and `--mintlify` or `--readme` import an existing docs site.
+
+**Q: How do I upgrade the Fern CLI?**
+A: `fern upgrade` bumps the version in `fern.config.json` and moves generators to their minimum-compatible versions; `fern upgrade --version <version>` targets a specific release, and `fern downgrade <version>` moves back. Upgrading the npm or Homebrew package updates the binary itself.
+</llms-only>

fern/products/cli-api-reference/pages/docs-commands.mdx

@@ -427,3 +427,29 @@ These commands build, preview, and publish a Fern documentation site, and valida
 
   </Accordion>
 </AccordionGroup>
+
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: What's the `fern generate --docs` command?**
+A: It builds your documentation site and publishes it to the instance URL configured in `docs.yml`. Use `--instance` to choose among multiple instances, `--preview` for a temporary preview deployment, `--id` for a stable preview name, and `--force` to skip the overwrite confirmation in CI.
+
+**Q: How do I preview my docs locally before publishing?**
+A: `fern docs dev` runs a local development server with hot reloading; pass `--port` to choose the port. On Windows it requires long path support enabled, or WSL.
+
+**Q: How do I share a preview with my team?**
+A: `fern generate --docs --preview` publishes a preview deployment and prints its URL. Adding `--preview --id my-feature` gives a stable `{org}-preview-{id}.docs.buildwithfern.com` link that updates in place — useful for one preview per pull request.
+
+**Q: How do I manage existing previews?**
+A: `fern docs preview list` shows preview deployments and `fern docs preview delete` removes one.
+
+**Q: How do I check for broken links?**
+A: `fern docs link check` checks links, including external ones, on a live published site. To validate internal links before publishing, use the `broken-links` rule run by `fern check`.
+
+**Q: How do I validate my MDX?**
+A: `fern docs md check` validates MDX syntax across your documentation files.
+
+**Q: How do I connect a coding agent to Fern over MCP?**
+A: `fern mcp install` registers Fern's MCP server with your supported clients; `--client` targets specific ones and `--org` overrides the organization from `fern.config.json`.
+</llms-only>

fern/products/cli-api-reference/pages/general-commands.mdx

@@ -493,3 +493,32 @@ These commands apply to every Fern project, whether it publishes [docs](/learn/c
 
   </Accordion>
 </AccordionGroup>
+
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: What does `fern check` do?**
+A: It validates your API definition and Fern configuration — `fern.config.json`, `generators.yml`, and `docs.yml` — reporting broken internal links, invalid examples, and configuration errors. Successful runs print nothing. Set each rule to `warn` or `error` under `check.rules` in `docs.yml`.
+
+**Q: Does `fern check` check my live site?**
+A: No. Its rules validate the navigation tree built from your local configuration and don't crawl your deployed site or follow external URLs. The exception is `missing-redirects`, which compares against the last published state and needs `fern login` or `FERN_TOKEN`. For a published site, use `fern docs link check`.
+
+**Q: How do I upgrade the Fern CLI?**
+A: `fern upgrade` sets `fern.config.json` to the latest allowed version and moves generators to their minimum-compatible versions. Use `--version` for a specific release, `--from` when version inference is wrong, and `--yes` in non-interactive environments. If your organization has a CLI version policy, the highest version the policy allows wins.
+
+**Q: What's `fern init` and when do I use it?**
+A: Run it once to create a `fern` workspace. `--openapi <path or URL>` scaffolds around an existing spec, `--docs` adds a sample docs site, and `--mintlify` or `--readme` convert an existing docs site into a Fern project.
+
+**Q: How do I authenticate the CLI?**
+A: `fern login` opens a browser for GitHub, Google, or Postman; `--device-code` covers environments without a browser, and `--email` uses enterprise SSO. For CI, generate an organization-scoped key with `fern token` and set it as `FERN_TOKEN`.
+
+**Q: How do I get an OpenAPI spec out of Fern?**
+A: `fern export path/to/openapi.yml` writes a spec for your API, which is useful when your API is defined in the Fern Definition. The extension (`.yml` or `.json`) chooses the output format.
+
+**Q: How do I pull the latest version of my spec?**
+A: `fern api update` fetches the spec from the `origin` configured in `generators.yml` and updates the local copy. The same step can run on a schedule in a GitHub Action.
+
+**Q: Can I pin one CLI version for my whole organization?**
+A: Yes. An organization admin sets a minimum, maximum, or exact version with `fern org set cli-version`, inspects it with `fern org get`, and clears it with `fern org unset cli-version`.
+</llms-only>

fern/products/cli-api-reference/pages/sdk-commands.mdx

@@ -378,4 +378,33 @@ These commands generate SDKs from your API definition, keep generators up to dat
     ```
 
   </Accordion>
-</AccordionGroup>
+</AccordionGroup>
+
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: What does `fern generate` do?**
+A: It runs the Fern compiler to produce SDKs for the generator groups in `generators.yml`, then publishes or saves each one to its configured output. Remote generation (the default) requires `fern login` or `FERN_TOKEN`; `--local` doesn't.
+
+**Q: How do I generate only one SDK?**
+A: `fern generate --group <group>`, using a group name or an alias defined in `generators.yml`. In multi-API projects, add `--api <name>` matching the folder in `fern/apis/`.
+
+**Q: How do I preview an SDK locally before publishing?**
+A: `fern generate --preview` writes the SDK to a local `.preview/` folder and publishes nothing to GitHub or a package registry.
+
+**Q: How do I generate SDKs on my own machine?**
+A: `fern generate --local` runs generation in Docker on your infrastructure, so a Docker daemon must be running. It requires no login and isn't rate limited.
+
+**Q: How do I set the SDK version?**
+A: `fern generate --version <semver>`, typically from a CI/CD release workflow. Combine it with `--group` and `--api` to version a single SDK.
+
+**Q: How do I run generation in CI without prompts?**
+A: Set `FERN_TOKEN` and pass `--force` to skip confirmation prompts.
+
+**Q: How do I build a distributable package without publishing to a registry?**
+A: `fern generate --package` builds an artifact (npm tarball, wheel, JAR, NuGet package, gem, Composer archive, crate, or Go source zip) into a `fern-dist/` folder for every `local-file-system` output. `--package-mode docker` runs the toolchains in containers, and `--package-only` keeps just the artifact.
+
+**Q: What are the Replay commands for?**
+A: `fern replay resolve` walks through conflicts left when the generator and your customizations touched the same lines, and `fern replay forget` removes tracked patches from `.fern/replay.lock`. `fern generate --no-replay` skips patch application for one local run.
+</llms-only>

fern/products/docs/pages/ai/fern-agent.mdx

@@ -200,3 +200,29 @@ What Fern Agent adds is context on your organization and more places to work fro
 Fern Agent acts with your own Fern permissions on every surface, so it reads and edits only the sites, analytics, and organization data your account can already see. Requests are scoped to a single session: the prompt, any Slack message or thread you tag it in, and attached files are stored to complete the task and aren't retained afterward.
 
 Editing is powered by [Devin from Cognition](https://cognition.ai/blog/introducing-devin). Neither Fern nor [Devin](https://docs.devin.ai/admin/security#how-is-your-data-used-to-improve-devin) uses your data to train AI models: Fern configures its Devin integration to opt out of any data collection for model training, so your messages, code, and documentation content are never used for training.
+
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: What's Fern Writer and how does it relate to Fern Agent?**
+A: Fern Agent is an expansion of Fern Writer. Fern Writer opened documentation pull requests from Slack and still does — existing installations keep working and the request flow is unchanged. Fern Agent adds organization context (traffic, reader questions, deployments, configuration) and two more surfaces: the Fern Dashboard and your coding agent over MCP.
+
+**Q: What can Fern Agent do?**
+A: Edit your docs (copy, navigation, versions, redirects, components, authentication), query analytics such as pageviews, 404s, referrers, search queries and reader feedback, summarize Ask Fern conversations and resolution rates, and report deployment history and site configuration. Organization administration stays read-only.
+
+**Q: How do I use Fern Agent to generate documentation?**
+A: Describe the change in the Dashboard chat panel, in a Slack channel where `@Fern` has been added, or through your coding agent over MCP. It reads your docs repository, makes the change, and delivers it as a pull request — or iterates live in the [visual editor](/learn/docs/writing-content/fern-editor).
+
+**Q: Can Fern Agent update existing documentation pages?**
+A: Yes. It edits existing pages and configuration as well as adding new ones, and it writes the accompanying Fern configuration — a moved page gets its redirect, a new page gets its navigation entry.
+
+**Q: Does Fern Agent work with the visual editor?**
+A: Yes. It can iterate on a change directly in Fern Editor instead of only opening a pull request.
+
+**Q: What are the requirements?**
+A: Editing requires a GitHub repository, because changes are delivered as pull requests; GitLab and other Git providers aren't supported for editing. Analysis and insights work regardless of your Git provider.
+
+**Q: Is my data used to train AI models?**
+A: No. Fern Agent acts with your own Fern permissions, requests are scoped to a single session and aren't retained afterward, and Fern's Devin integration is configured to opt out of any data collection for model training.
+</llms-only>

fern/products/docs/pages/ai/llms-txt/overview.mdx

@@ -72,3 +72,31 @@ The output format depends on whether you're requesting an individual page or a s
   </Card>
 </CardGroup>
 
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: What's `llms.txt` and why does Fern generate it?**
+A: `llms.txt` is a standard for exposing site content to AI developer tools. Fern generates and maintains one automatically so AI tools can discover and index your documentation instead of scraping HTML.
+
+**Q: How do I view my site's `llms.txt` file?**
+A: Fetch `/llms.txt` on your docs domain. It's available at any level of the hierarchy, so `/docs/llms.txt` and `/docs/ai-features/llms.txt` work too. To see what an agent gets for a single page, append `.md` or `.mdx` to the page URL.
+
+**Q: What's in it?**
+A: A one-sentence description and URL for each page, taken from the page's `description` frontmatter (falling back to `subtitle`), plus links to your OpenAPI and AsyncAPI specifications when your site documents endpoints or WebSocket channels.
+
+**Q: Does Fern generate `llms-full.txt`?**
+A: No. Full-site concatenation exceeded most model context windows and added serving overhead for little benefit. Use `llms.txt` to discover pages, then fetch each page's Markdown.
+
+**Q: How do I exclude a page from `llms.txt`?**
+A: Add `noindex: true` to the page's frontmatter. The page stays in your navigation and remains reachable by URL, but drops out of LLM endpoints.
+
+**Q: What's the difference between `<llms-only>` and `<llms-ignore>`?**
+A: `<llms-only>` content is hidden from the rendered page, Copy page, search, and Ask Fern, but served in `llms.txt` and page Markdown. `<llms-ignore>` is the inverse: served to human readers, stripped from `llms.txt` and page Markdown.
+
+**Q: How do I add content that only AI agents see?**
+A: Wrap it in `<llms-only>`. It suits programmatic equivalents of UI steps, implementation details, and cross-references that would clutter the page for human readers. See [Customize LLM output](/learn/docs/ai-features/customize-llm-output).
+
+**Q: Can I serve my own `llms.txt`?**
+A: Yes. Point `agents.llms-txt` in `docs.yml` at a file relative to `docs.yml`. It's served at the root `/llms.txt`; nested paths keep using the generated output.
+</llms-only>

fern/products/docs/pages/ai/mcp-server.mdx

@@ -104,3 +104,28 @@ This is especially useful on [authenticated sites](/learn/docs/authentication/ov
 
 Agents can also fetch documentation directly over HTTP. Fern serves clean Markdown via [per-page URLs and `llms.txt`](/learn/docs/ai-features/markdown) — including on authenticated sites.
 
+<llms-only>
+
+## Frequently Asked Questions
+
+**Q: What's the Fern MCP server and how does it work?**
+A: It's a [Model Context Protocol](https://modelcontextprotocol.io) server Fern generates and hosts for every site with Ask Fern enabled, served at `your-documentation-site.com/_mcp/server`. AI clients register it as an external data source and get answers about your product from your documentation.
+
+**Q: How do I enable the MCP server for my Fern docs site?**
+A: There's nothing to enable beyond [Ask Fern](/learn/docs/ai-features/ask-fern/overview) — the server and its connection buttons are on by default for sites that have it.
+
+**Q: Can AI coding assistants like Claude or Cursor use my docs?**
+A: Yes. On sites with Ask Fern, the **Connect to Claude Code** and **Connect to Cursor** page actions register the server in one click. Other clients (Claude Desktop, Windsurf, VS Code) add the server URL to their MCP configuration directly.
+
+**Q: How do MCP clients authenticate on a private docs site?**
+A: They must send a `FERN_TOKEN` header containing a valid JWT, obtained from the `get-jwt` endpoint (API key) or the password endpoint (password-protected sites). Without it the server returns only publicly visible content. JWTs expire and there's no automatic refresh in the MCP transport.
+
+**Q: How do I disable the MCP server?**
+A: Set `mcp: false` under `page-actions.options` in `docs.yml`. The endpoint then returns 404, the connection buttons disappear, and agents can no longer discover the server through `llms.txt` or agent prompts.
+
+**Q: What's the difference between this server and Fern's own MCP server?**
+A: This one serves your content to your readers. [Fern's MCP server](/learn/docs/ai-features/fern-mcp-servers) serves Fern's product documentation and your organization's Fern data to the agent you build your site with.
+
+**Q: What if an agent can't use MCP?**
+A: It can fetch your documentation as Markdown over plain HTTP through per-page `.md` URLs and [`llms.txt`](/learn/docs/ai-features/llms-txt), including on authenticated sites.
+</llms-only>