docs: clarify ai api access instructions, integrate mcp and markdown pages

fern/docs.yml

@@ -523,6 +523,8 @@ redirects:
     destination: /learn/docs/ai-features/mcp-server
   - source: /learn/docs/seo/llms-txt
     destination: /learn/docs/ai-features/llms-txt
+  - source: /learn/docs/developer-tools/view-markdown
+    destination: /learn/docs/ai-features/markdown
   - source: /learn/docs/scribe-api/slack-scribe/get-scribe-slack-install-link
     destination: /learn/docs/ai-features/fern-writer
 

fern/products/docs/docs.yml

@@ -178,6 +178,9 @@ navigation:
       - page: AI-generated examples
         path: ./pages/ai/ai-examples.mdx
         slug: ai-examples
+      - page: Markdown access
+        path: ./pages/ai/markdown.mdx
+        slug: markdown
       - section: llms-txt
         collapsed: open-by-default
         skip-slug: true
@@ -431,9 +434,7 @@ navigation:
       - page: GitLab
         path: ./pages/developer-tools/gitlab.mdx
       - page: Vale
-        path: ./pages/developer-tools/vale.mdx  
-      - page: View Markdown
-        path: ./pages/developer-tools/view-markdown.mdx
+        path: ./pages/developer-tools/vale.mdx
       - page: Download OpenAPI spec
         path: ./pages/developer-tools/openapi-spec.mdx
         slug: openapi-spec

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

@@ -11,7 +11,7 @@ Within pages, use `<llms-only>` and `<llms-ignore>` tags to control what content
 
 ### Content for AI only
 
-`<llms-only>` content appears only on the LLM-serving endpoints that external agents (like Claude, ChatGPT, or Cursor) fetch directly: `/llms.txt`, `/llms-full.txt`, and each page's [`.md`/`.mdx` source](/learn/docs/developer-tools/view-markdown). It's hidden from every human-facing surface, including the rendered page, [Copy page](/learn/docs/configuration/site-level-settings#page-actions-configuration), the search widget, and [Ask Fern](/learn/docs/ai-features/ask-fern/overview).
+`<llms-only>` content appears only on the LLM-serving endpoints that external agents (like Claude, ChatGPT, or Cursor) fetch directly: `/llms.txt`, `/llms-full.txt`, and each page's [`.md`/`.mdx` source](/learn/docs/ai-features/markdown). It's hidden from every human-facing surface, including the rendered page, [Copy page](/learn/docs/configuration/site-level-settings#page-actions-configuration), the search widget, and [Ask Fern](/learn/docs/ai-features/ask-fern/overview).
 
 Use `<llms-only>` for:
 - Technical context that's verbose but helpful for AI, like implementation details or architecture notes
@@ -79,7 +79,7 @@ On the docs site, human readers see only the numbered UI steps — the `<llms-on
 
 The guiding principle: **UI-only elements belong to human readers, and their programmatic equivalents belong to AI agents.** Wrap clickable cards and UI walkthroughs in `<llms-ignore>` so agents skip them, and pair each UI step with an `<llms-only>` block that gives the CLI or API equivalent.
 
-To preview and debug what AI sees for any page, you can append `.md` or `.mdx` to the page URL to [view its Markdown source](/learn/docs/developer-tools/view-markdown).
+To preview and debug what AI sees for any page, you can append `.md` or `.mdx` to the page URL to [view its Markdown source](/learn/docs/ai-features/markdown).
 
 ## Filter endpoint output
 

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

@@ -3,9 +3,7 @@ title: "`llms.txt` and `llms-full.txt`"
 description: Fern automatically generates llms.txt and llms-full.txt Markdown files so AI tools can discover and index your documentation.
 ---
 
-[`llms.txt`](https://llmstxt.org/) is a standard for exposing website content to AI developer tools. Fern implements this standard, automatically generating and maintaining `llms.txt` and `llms-full.txt` Markdown files so AI tools can discover and index your documentation.
-
-Fern also serves [clean Markdown instead of HTML](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation) on any page URL when the request includes an `Accept: text/markdown` header, ensuring agents only receive the content they need. Together, these features reduce token consumption by 90%+.
+[`llms.txt`](https://llmstxt.org/) is a standard for exposing website content to AI developer tools. Fern implements this standard, automatically generating and maintaining `llms.txt` and `llms-full.txt` Markdown files so AI tools can discover and index your documentation. For single pages, agents can also fetch [Markdown directly](/learn/docs/ai-features/markdown).
 
 <Frame>
   <img

fern/products/docs/pages/ai/markdown.mdx

@@ -0,0 +1,42 @@
+---
+title: Markdown access
+description: Access your documentation as Markdown — through per-page URLs, `llms.txt`, and `llms-full.txt` — for AI agents and tooling.
+---
+
+
+Fern serves clean Markdown for any documentation page — including API Reference pages — so agents can consume your content efficiently. Agents fetch the source by appending `.md` or `.mdx` to a page URL, or by sending an `Accept: text/markdown` header via [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation). Combined with [`llms.txt`](/learn/docs/ai-features/llms-txt), this reduces token consumption by 90%+ compared to HTML.
+
+<Frame caption="For example, `https://buildwithfern.com/learn/docs/ai-features/markdown.md` displays the Markdown source for this page.">
+  <img src="./markdown.png"
+       alt="Example showing a page's underlying Markdown"
+       className="rounded-lg border border-gray-200 dark:border-gray-700"
+  />
+</Frame>
+
+The same Markdown is used everywhere — single pages, `llms.txt`, and `llms-full.txt` — and respects the same `<llms-only>` and `<llms-ignore>` content controls.
+
+A [default per-page directive](/learn/docs/ai-features/agent-directives) is automatically prepended to every page's Markdown output when served to AI agents, pointing them to your `.md` URLs, `llms.txt`, and `llms-full.txt`. You can [override or disable this directive](/learn/docs/configuration/site-level-settings#agents-configuration) in `docs.yml`. The directive is only visible to agents — human-facing documentation is unaffected.
+
+## Accessing protected docs
+
+On sites with [authentication](/learn/docs/authentication/overview) enabled, agents must include a JWT on every Markdown request — whether for an individual page, `llms.txt`, or `llms-full.txt`. Exchange your [Fern token](/learn/cli-api/cli-reference/commands#fern-token) for a [JWT](/learn/docs/fern-api-reference/get-jwt):
+
+```bash Get a JWT
+curl https://docs.example.com/api/fern-docs/get-jwt \
+  -H "FERN_API_KEY: $FERN_TOKEN"
+# → { "fern_token": "eyJ...", "roles": [] }
+```
+
+Send the returned JWT as the `FERN_TOKEN` header on subsequent requests:
+
+```bash Fetch protected content
+curl https://docs.example.com/platform/overview \
+  -H 'Accept: text/markdown' \
+  -H "FERN_TOKEN: $JWT"
+```
+
+JWTs are valid for 30 days — cache and refresh as needed.
+
+## Markdown for troubleshooting
+
+Viewing the Markdown directly is also useful for troubleshooting layout problems. A **View as Markdown** button is enabled by default on every page and can be configured through the [page actions configuration](/learn/docs/configuration/site-level-settings#page-actions-configuration).

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

@@ -16,15 +16,7 @@ Your MCP server is available at `your-documentation-site.com/_mcp/server`. For e
 
 Both buttons are enabled by default on sites with Ask Fern. For other clients (Claude Desktop, Windsurf, etc.), users can add `your-documentation-site.com/_mcp/server` to their MCP configuration.
 
-## Direct API access for AI agents
+## Other ways agents can access your docs
 
-AI agents can access your documentation directly via HTTP. Fern serves content as clean Markdown for token efficiency.
+In addition to MCP, agents can fetch documentation directly over HTTP. Fern serves clean Markdown via [per-page URLs, `llms.txt`, and `llms-full.txt`](/learn/docs/ai-features/markdown) — including on authenticated sites.
 
-For authenticated sites, agents obtain a JWT via [`/api/fern-docs/get-jwt`](/learn/docs/fern-api-reference/get-jwt) with a Fern API key to access protected documentation content and search functionality.
-
-```bash Access protected content
-curl https://docs.example.com/platform/overview \
-  -H 'Accept: text/plain' \
-  -H 'x-fern-host: docs.example.com' \
-  -H 'FERN_TOKEN: your-jwt-here'
-```

fern/products/docs/pages/ai/overview.mdx

@@ -42,7 +42,8 @@ AI helps keep your documentation current. Fern Writer is a Slack-based technical
 
 Your site is automatically optimized for AI tools and search engines. Fern hosts `llms.txt` and `llms-full.txt` files so LLMs can index your documentation efficiently, and serves Markdown instead of HTML to AI agents. These features reduce token consumption and help agents process your content faster.
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
+  <Card title="Markdown access" icon="file-code" href="/learn/docs/ai-features/markdown" />
   <Card title="`llms.txt`" icon="file-text" href="/learn/docs/ai-features/llms-txt" />
   <Card title="Agent directives" icon="compass" href="/learn/docs/ai-features/agent-directives" />
 </CardGroup>

fern/products/docs/pages/navigation/site-level-settings.mdx

@@ -808,7 +808,7 @@ page-actions:
 </ParamField>
 
 <ParamField path="page-actions.options.view-as-markdown" type="boolean" required={false} default="true" toc={true}>
-  When enabled, displays a button that allows users to view the raw Markdown source of the current page. Users can also [view Markdown by appending `.md` to the page URL](/learn/docs/developer-tools/view-markdown). To control what content appears in the Markdown output, use [`<llms-ignore>`](/learn/docs/ai-features/customize-llm-output#content-for-humans-only) tags.
+  When enabled, displays a button that allows users to view the raw Markdown source of the current page. Users can also [view Markdown by appending `.md` to the page URL](/learn/docs/ai-features/markdown). To control what content appears in the Markdown output, use [`<llms-ignore>`](/learn/docs/ai-features/customize-llm-output#content-for-humans-only) tags.
 </ParamField>
 
 <ParamField path="page-actions.options.ask-ai" type="boolean" required={false} default="true" toc={true}>