diff --git a/.agents/skills/fern-docs/SKILL.md b/.agents/skills/fern-docs/SKILL.md
new file mode 100644
index 000000000..3d5e974df
--- /dev/null
+++ b/.agents/skills/fern-docs/SKILL.md
@@ -0,0 +1,154 @@
+---
+name: fern-docs
+description: >-
+  Author and edit Fern documentation: MDX pages, navigation, docs.yml config,
+  custom components, landing pages, and changelog entries. Use when working in a
+  Fern docs repo (a fern/ directory with docs.yml). Routes to a detailed
+  reference per task.
+---
+
+# Fern docs authoring
+
+Write and edit documentation on a Fern site. `SKILL.md` is the index: follow the
+principles below, then read the `references/` file that matches the
+task before writing. Don't work from this page alone when a reference exists.
+
+**Scope: this skill governs Fern docs content only** — MDX pages, navigation,
+`docs.yml` and related config, snippets, changelog entries, custom components,
+and landing pages. It does **not** govern repo governance or tooling files that
+happen to live in the same repo, such as `CLAUDE.md`, `AGENTS.md`,
+`STYLE-GUIDE.md`, and contributor guides. Never apply the principles below —
+"one canonical home," "prefer editing over creating," consolidation — to those
+files. Leave them alone unless the user explicitly asks you to edit them.
+
+## Fern resources
+
+Fern's configuration evolves. Look things up rather than guessing.
+
+- **Docs:** https://buildwithfern.com/learn/docs/getting-started/overview.md
+  (append `.md` to any docs URL for clean markdown to fetch)
+- **Page index:** https://buildwithfern.com/learn/llms.txt
+- **MCP server** — connect your agent to Fern's live docs and query it for any
+  syntax or behavior you're unsure of. The endpoint works with any MCP client;
+  for Claude Code:
+
+  ```bash
+  claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server
+  ```
+
+## Routing
+
+| Task | Read |
+|------|------|
+| Writing or editing a changelog entry | `references/changelog.md` |
+| Setting up a product switcher, adding a product, or refactoring nav into products | `references/products.md` |
+| Moving, renaming, or deleting a page, or any edit that changes a published URL | `references/redirects.md` |
+| Restricting pages or content by role (RBAC), or wiring docs into an auth method (password, SSO, JWT, OAuth) | `references/authentication.md` |
+| Editing the same content across multiple pages, or adding generic/boilerplate content (e.g. "contact support") | `references/snippets.md` |
+| Translating pages into another language, adding a language, or updating existing translations (multi-language Fern repo) | `references/translations.md` |
+
+## Core principles
+
+- **Defer to the repo's own conventions.** When a docs repo has an established
+  pattern, voice, or structure — a `CLAUDE.md`, a style guide, or just the
+  consistent practice of surrounding pages — follow it over the guidance here.
+  This skill is the default, not an override.
+- **Write what the reader needs to succeed — no more.** Every sentence earns its place.
+- **Prefer editing over creating.** Search the repo for a page that already
+  covers the topic and update it instead of adding a duplicate.
+- **Make minimal, precise edits.** Don't rewrite a page when a paragraph fix will do.
+- **Push back when something seems wrong.** Explain why rather than complying silently.
+- **Ask when unclear.** Don't fill gaps with assumptions.
+- **Never fabricate.** If you don't know a config key or behavior, look it up
+  (MCP server or docs) or say so. Don't invent frontmatter or YAML fields.
+- **Cross-reference.** When you mention a concept documented elsewhere, link to it
+  so readers can find their way.
+- **Preserve URLs when they change.** Any edit that moves, renames, or deletes a
+  page — or changes a slug, section, or product — can change a published URL.
+  When it does, set up [redirects](https://buildwithfern.com/learn/docs/seo/redirects.md)
+  from the old path (see `references/redirects.md`) so inbound links and search
+  rankings survive.
+
+## Links
+
+Internal links are URL paths derived from **this repo's own `docs.yml` and page
+frontmatter** — not file paths on disk or relative paths. Nearly every edit
+touches a link, so get this right every time.
+
+A page URL is `<base-path>/<product-slug>/<rest>`:
+
+- **Base path** — the prefix in your docs URL (e.g. `/learn`, `/docs`; may be empty).
+- **Product slug** — the product's `slug` in `fern/docs.yml`. Omitted for a
+  product with no `slug:` (such as a default single Home product).
+- **`<rest>`** — found by step 1 or step 2 below.
+
+To find `<rest>`:
+
+1. **Open the target page and check its frontmatter for `slug:`.** A frontmatter
+   slug is **absolute within the product**: it *is* `<rest>` on its own, and it
+   replaces the entire section/folder hierarchy. The section's slug does not
+   appear. Do not walk the navigation.
+2. **Otherwise, walk `docs.yml`** within the product, from section through any
+   folders to the page. Each level contributes one slug:
+   - Its explicit `slug:` if set.
+   - Otherwise auto-derived from the display name: lowercased, spaces to
+     hyphens, special characters stripped (so `v3 (Latest)` becomes
+     `v-3-latest`). Auto-derivation isn't always obvious — verify, don't assume.
+   - In folder-based navigation, a page's slug comes from its **filename**, not
+     a display name (`quick-start.mdx` to `quick-start`).
+   - **Omit any level with `skip-slug: true`** — it contributes no segment.
+
+Example — page `./pages/ai/overview.mdx` under section "AI features", in product
+`docs`, base path `/learn`:
+
+- with frontmatter `slug: ai-ai` → `/learn/docs/ai-ai` (the `ai-features`
+  section slug is dropped)
+- with no frontmatter slug → `/learn/docs/ai-features/overview` (section
+  auto-slug `ai-features` + page auto-slug `overview`)
+
+Section slugs frequently differ from folder names, so never guess the URL from
+the directory layout. If you can't resolve a path from `docs.yml` and the page's
+frontmatter, say so rather than guessing.
+
+**Anchors** append `#heading`, and only resolve for real `##`/`###` Markdown
+headings — not for JSX title props like `<Step title>`, `<Tab title>`,
+`<Accordion title>`, or `<Card title>`.
+
+**Not internal links** (leave as-is): external `https://` URLs, image paths
+(`./images/...`), snippet includes (`<Markdown src="/snippets/..." />`), and
+same-page anchors (`#section`).
+
+## Cross-referencing
+
+When you document new functionality — a new page, or new behavior on an existing
+one — related pages usually need a pointer to it, or the new content is hard to
+find from where readers actually start. This applies to small edits too, not
+just new pages.
+
+- **One canonical home.** The full explanation lives on one page; every other
+  page that touches the topic links to it instead of restating it. If you're
+  copying more than a sentence or two onto another page, it belongs on the
+  canonical page.
+- **Find the targets.** Grep the docs for the feature name and one or two related
+  keywords, then read each hit and decide whether a pointer is warranted:
+
+  ```bash
+  grep -rln "<feature>\|<keyword>" fern --include="*.mdx"
+  ```
+
+  Common targets: pages for behavior the feature affects, adjacent feature pages,
+  and overview or landing pages.
+- **Use the lightest form that works:** an inline link inside an existing
+  sentence, then a `<Note>` for a secondary aside, then a new `##` section, then
+  a new page. Inline links and Notes add no maintenance surface; new pages and
+  sections do.
+- **Phrase inline links naturally — never "See [page]."** Put the link on a noun
+  phrase already in the sentence, not a tacked-on pointer sentence. Don't wrap a
+  lone link in a `<Tip>` whose only job is to host it.
+  - Good: "Each request counts against your [rate limit](...), which resets hourly."
+  - Bad: "Requests are rate limited. See the [rate limits reference](...) for details."
+  - Bad: a standalone `<Tip>` containing only "For more, see [rate limits](...)."
+- **Frame by function, not plumbing.** Contrast what each feature does ("X
+  decides A; Y decides B"), not that they share a config key or sit in the same
+  directory. If the only thing linking two features is the same YAML key, it's
+  not worth a cross-reference.
diff --git a/.agents/skills/fern-docs/references/authentication.md b/.agents/skills/fern-docs/references/authentication.md
new file mode 100644
index 000000000..c86ad86ca
--- /dev/null
+++ b/.agents/skills/fern-docs/references/authentication.md
@@ -0,0 +1,180 @@
+# Authentication & RBAC
+
+Gate a docs site so readers only see content meant for them. Read this when a
+task involves restricting pages or content by role (RBAC), or wiring docs into an
+auth method (password, SSO, JWT, OAuth).
+
+This page is decision context: what each piece is, which surface it lives on, and
+**which canonical doc to fetch before you edit**. Don't work the syntax from
+memory — fetch the matching page (append `.md` for clean markdown) or query the
+Fern MCP server, since the config evolves.
+
+## First, locate the surface
+
+Most of an auth setup is *not* in the docs repo. Before touching anything,
+work out which surface the task actually lives on — it changes whether you edit a
+file at all:
+
+- **In the repo (`docs.yml` + MDX)** — declaring roles and gating content. This is
+  RBAC, and it's the bulk of what you'll edit here.
+- **In the Fern Dashboard** — password protection (passwords mapped to roles).
+- **With Fern support** — SSO, OAuth, and JWT signing secrets. You send Fern your
+  identity-provider details; Fern provisions the connection. **The repo never
+  holds client secrets or signing keys** — if a task asks you to put one in
+  `docs.yml`, push back.
+
+When a request is really "turn on SSO" or "set the docs password," the answer is a
+pointer to the Dashboard or support, not a `docs.yml` edit. Say so rather than
+inventing config.
+
+## RBAC (the in-repo part)
+
+RBAC has three moving parts, all in the repo. You'll usually touch more than one
+in a single task, so know what each is for:
+
+- **Declare roles** — a top-level `roles:` list in `docs.yml`. Every role
+  referenced anywhere must be declared here or `fern check` fails. `everyone` is
+  auto-assigned to all visitors, including unauthenticated ones — but it is *not*
+  exempt from the declaration rule: if you reference it in `viewers:` or
+  `<If roles>`, you must still list `everyone` under `roles:` or `fern check`
+  fails with "Role 'everyone' is used but not declared."
+- **Gate navigation** — a `viewers:` key on a navigation item. Only listed roles
+  see it. Fern allows `viewers:` on **products, versions, tabs, sections, pages,
+  api references, and changelogs** — every level of the tree.
+- **Gate inline content** — the `<If roles={[...]}>` component, to hide part of a
+  page rather than the whole page.
+
+Three behaviors that are easy to get backwards — get these right or the gating is
+silently wrong:
+
+- **Omitting `viewers:` is authenticated-only, NOT public.** A navigation item
+  with no `viewers:` key is visible to *any signed-in user* but hidden from
+  logged-out visitors. To make something truly public you must set it explicitly:
+  `viewers: [everyone]`. "No key" and `[everyone]` are different states — don't
+  treat a bare item as public.
+- **Viewership is inherited.** If a section is restricted to `admins`, all its
+  pages and nested sections are admins-only too — you don't repeat `viewers:` on
+  each child. So to test or reason about one level in isolation, keep its parents
+  permissive; otherwise an inherited restriction, not the key you're looking at,
+  is what's gating.
+- **Gated items are hidden, not locked.** By default an unauthorized reader sees
+  no trace of the item in nav (not a 404 or lock screen), and unauthenticated
+  users are redirected to login. A "visible but locked" presentation exists but
+  must be requested from Fern, so don't assume it's on.
+
+**`viewers:` placement depends on the item.** On most items it sits directly on
+the navigation entry, but **on a tab it goes in the `tabs:` map, not on the
+`- tab:` entry** in `navigation:`. Putting it on the `- tab:` entry fails
+`fern check`.
+
+**Fetch before editing:**
+https://buildwithfern.com/learn/docs/authentication/features/rbac.md — for exact
+`roles:`/`viewers:`/`<If>` syntax.
+
+### Gating a level means that level must exist in the nav
+
+To gate, say, the tab or version level, the nav must actually contain a tab or a
+version — and Fern's nav structure rules vary by file type in ways that bite when
+you build a fixture or restructure to add a gate:
+
+- A **versioned product**'s version files use flat navigation (sections/pages);
+  **tabs are not supported there** — put tab-level structure in a non-versioned
+  product, whose product file does support `tabs:`.
+- A **versioned product entry** in `docs.yml` needs both a top-level `path:` (the
+  default version) **and** a `versions:` list.
+- An `- api:` reference node validates in a product's flat navigation but is
+  rejected inside a version file's tab layout.
+
+These are navigation-structure rules, not RBAC rules, but they surface the moment
+you add a gate to a level that wasn't there before. Confirm structure against the
+[products](https://buildwithfern.com/learn/docs/configuration/products.md) and
+[versions](https://buildwithfern.com/learn/docs/configuration/versions.md) docs
+(or `references/products.md`) rather than guessing — getting the wrong shape costs
+far more time than looking it up.
+
+### You can't verify RBAC in local preview
+
+`fern docs dev` renders the site but does **not** enforce `viewers:` — every
+reader is effectively unauthenticated, so restricted content just won't appear and
+you can't confirm a role sees what it should. RBAC only takes effect on the
+**published** site once an auth method is configured. Plan to verify on the
+deployed site (or a preview instance) with real credentials, and tell the user
+that local preview can't prove the gating works.
+
+## Auth methods — which one, and where it's configured
+
+Four ways to establish *who* a reader is; RBAC then decides what they see. JWT,
+OAuth, and SSO all work through a `fern_token` browser cookie.
+
+| Method | Configured | RBAC | API key injection | Fetch when working on it |
+|--------|-----------|------|-------------------|--------------------------|
+| Password | Dashboard | ✅ up to 3 roles | ❌ | [`setup/password-protection.md`](https://buildwithfern.com/learn/docs/authentication/setup/password-protection.md) |
+| SSO | Fern support | ❌ | ❌ | [`setup/sso.md`](https://buildwithfern.com/learn/docs/authentication/setup/sso.md) |
+| OAuth | Fern support | ✅ | ✅ | [`setup/oauth.md`](https://buildwithfern.com/learn/docs/authentication/setup/oauth.md) |
+| JWT | You (mint the token) | ✅ | ✅ | [`setup/jwt.md`](https://buildwithfern.com/learn/docs/authentication/setup/jwt.md) |
+
+Pick by the constraints, not preference:
+
+- **Password** — quick gate for a small set of audiences. **Capped at three
+  password-mapped roles**, no API key injection. Passwords (and their role
+  mapping) are set in the Fern Dashboard → Settings → Password card, not in the
+  repo. Each Dashboard role name must match a string in `docs.yml`'s `roles:` list
+  **exactly**, or the password won't unlock the content it's meant to. You don't
+  map a password to `everyone` — that's the built-in unauthenticated role.
+- **SSO** — internal docs behind corporate login (SAML 2.0 / OIDC). No RBAC, no
+  API key injection — it's all-or-nothing access.
+- **OAuth** — Fern runs the flow against your provider; supports RBAC and API key
+  injection. Choose over JWT when you'd rather not mint tokens yourself.
+- **JWT** — you sign the `fern_token` yourself, so you control the payload. The
+  only method with meaningful repo/code involvement: roles travel in the token's
+  `fern` claim, and you can inject an API key into the API Explorer through it.
+  Fetch `setup/jwt.md` for the claim shape and a token-minting example, and
+  [`features/api-key-injection.md`](https://buildwithfern.com/learn/docs/authentication/features/api-key-injection.md)
+  for the injection payload schema.
+
+## Footguns
+
+- **Declare before you use.** Any role in `viewers:` or `<If roles>` must be in the
+  top-level `roles:` list, or `fern check` fails.
+- **Bare ≠ public.** An item with no `viewers:` is authenticated-only, not public.
+  Set `viewers: [everyone]` for anything that should reach logged-out visitors.
+- **Inherited restrictions hide more than you think.** Because viewership cascades
+  down, a permissive-looking child can still be gated by an ancestor. Check the
+  whole path from product down, not just the item itself.
+- **Gating without auth exposes everything.** `viewers:` and `<If roles>` are
+  inert until an auth method is configured. On a published site with *no* auth
+  method, all gated content is publicly visible — *not* hidden, and not locked.
+  `fern check` passing does not mean content is protected. Never treat `viewers:`
+  as protection until auth is wired up and verified live.
+- **Secrets never live in the repo.** Signing keys, client secrets, and passwords
+  belong in the Dashboard or with Fern support.
+- **Gating ≠ moving.** Hiding a page with `viewers:` doesn't change its URL, so
+  it's not a redirect situation. Renaming or moving it still is — see
+  `references/redirects.md`.
+
+## Verify
+
+Run `fern check` after editing roles or `viewers:` — it catches undeclared roles
+and malformed config. But neither `fern check` nor `fern docs dev` proves the
+gating works: visibility is only enforced on the **published** site with an auth
+method configured, so a passing check is necessary, not sufficient.
+
+Validating RBAC end-to-end happens mostly outside the repo. Walk the user through
+the full loop and present it as concrete next steps:
+
+1. **Publish** — `fern generate --docs` (needs `fern login` or a `FERN_TOKEN`; add
+   `--no-prompt` for non-interactive runs).
+2. **Configure an auth method** — declaring and gating in the repo enforces
+   nothing on its own. For a quick RBAC test, password protection is the fastest
+   path: in the Dashboard, add one password per role, with role names matching
+   `docs.yml` exactly. Fetch
+   https://buildwithfern.com/learn/dashboard/configuration/password-protection.md
+   for the current Dashboard steps and walk the user through them — don't recite
+   menus from memory, since the UI changes.
+3. **Verify per role** — load the published site and enter each role's credential
+   in turn, confirming each role sees exactly its slice and *not* another's. Give
+   the user a role → expected-visible-content table so they know what correct
+   looks like.
+
+Always tell the user that local checks can't validate RBAC and that auth must be
+live first.
diff --git a/.agents/skills/fern-docs/references/changelog.md b/.agents/skills/fern-docs/references/changelog.md
new file mode 100644
index 000000000..19e91aa79
--- /dev/null
+++ b/.agents/skills/fern-docs/references/changelog.md
@@ -0,0 +1,141 @@
+# Writing changelog entries
+
+A changelog entry announces a shipped change to users. Each entry is a dated
+`.mdx` file; the filename date is the title. This reference covers how to *write*
+an entry. For setup (folder location, `docs.yml` wiring, RSS, navigation), see
+the official docs: https://buildwithfern.com/learn/docs/configuration/changelogs.md
+
+## File and naming
+
+- Entries go directly in the `changelog/` folder inside `fern/`. The folder must
+  be named `changelog` exactly. **No subdirectories** — nested files are silently
+  ignored.
+- One entry per date, named by date. Supported filename formats: `YYYY-MM-DD`
+  (preferred, sorts cleanly), `MM-DD-YYYY`, `MM-DD-YY`. Always use `.mdx` (Fern
+  also accepts `.md`, but `.mdx` is the standard and unlocks the component
+  library).
+- Sort order comes from the **filename date**, not frontmatter. A wrong filename
+  date puts the entry in the wrong position.
+- The date is the title. **Do not add an h1.**
+- If a file already exists for that date, add your feature as a new `##` section
+  in it rather than creating a second file.
+
+## Frontmatter tags
+
+Every entry needs a `tags` array. Tags drive the changelog's filtering, so use
+specific, descriptive tags users would search for — by product area, feature,
+release stage, platform, or impact:
+
+```mdx
+---
+tags: ["voice-api", "breaking-change"]
+---
+```
+
+**Reuse existing tags** for consistency before adding a new one:
+
+```bash
+grep -rh "^tags:" changelog/ | sort | uniq -c | sort -rn
+```
+
+A near-duplicate tag (`auth` when `security` already exists) fragments the
+filter.
+
+## Entry format
+
+```mdx
+---
+tags: ["search"]
+---
+
+## Filter search results by section
+
+You can now scope a search to a single section of your docs. Visitors pick a
+section from the search bar, and results are limited to pages under it.
+
+- Available on all plans.
+- Configured per docs instance.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/docs/customization/search">Read the docs</Button>
+```
+
+- **One `##` per feature.** No h1.
+- **Lead with the capability** — "You can now…" — not the implementation.
+- **Keep it short:** 2–6 sentences. Bullets for detail lists, not the whole entry.
+- **End with a Button** linking to the relevant docs page (recommended).
+- For dashboard/UI changes, give the click-path (**Settings** > **Page access**)
+  before the Button.
+
+## The docs-link Button
+
+The `href` is a docs **URL path** built from `docs.yml`, not a file path:
+`<base-path>/<section-slug>/<page-slug>`.
+
+```mdx
+<!-- WRONG: file path on disk -->         href="/changelog/../pages/search/configuration"
+<!-- WRONG: guessed from folder names --> href="/docs/search-config/configuration"
+<!-- CORRECT: built from docs.yml -->     href="/docs/customization/search"
+```
+
+See the **Links** section of `SKILL.md` for how to construct the path (base
+path, product slug, frontmatter slugs, `skip-slug`) from this repo's `docs.yml`.
+
+## Voice
+
+Dry and direct. Cut hedges ("just", "simply", "make sure you") and filler ("in
+order to", "so that"). At most one em dash per short paragraph.
+
+## Options
+
+Beyond a plain entry, the changelog supports:
+
+- **Overview page** — an `overview.mdx` in the `changelog/` folder renders above
+  all entries. `overview.mdx` is a reserved filename, so it is never treated as a
+  dated entry.
+- **Components are available but avoid them.** `.mdx` entries *can* use Fern's
+  component library (`<Note>`, `<Card>`, `<Accordion>`, etc.), but stacked across
+  a list of short entries they create visual noise. House rule: prose + the
+  `<Button>` only. Reach for another component only when it's genuinely the only
+  way to convey something.
+- **Tab or section** — the changelog is wired in `docs.yml` either as a tab
+  (`tabs: { changelog: { changelog: ./changelog } }`) or as a section
+  (`navigation: [ { changelog: ./changelog, title: ..., slug: ... } ]`).
+- **RSS feed** — generated automatically; append `.rss` to the changelog path
+  (e.g. `https://yourdomain.com/docs/changelog.rss`). No config needed.
+- **Per-entry permalinks** — each entry gets `…/changelog/YYYY/M/D` (month and
+  day are not zero-padded).
+
+For exact `docs.yml` syntax, see the official docs linked above.
+
+## Gotchas
+
+- **Folder name is exact and flat.** Not `changelogs`, not nested — files in
+  subfolders are silently dropped with no error.
+- **Slug must be recognized.** `fern check` (`valid-changelog-slug`) errors
+  unless the changelog's effective slug is one of: `changelog`, `changelogs`,
+  `release-notes`, `releasenotes`, `whats-new`, `whatsnew`.
+- **A section changelog can't live inside an `api:` block** in `docs.yml`.
+- **Only `tags` is a supported frontmatter field.** `title`, `date`, `hidden`,
+  etc. are not — the date comes from the filename. Don't add undocumented keys.
+- **The tag filter UI only renders when entries have tags.** No tags, no filter.
+
+## What not to do
+
+- Don't use h1 (`#`) — the date is the title.
+- Don't describe implementation details; describe the user benefit.
+- Don't invent a tag when an existing one fits.
+- Don't write the Button `href` from the file path on disk.
+- Don't use components other than the `<Button>` — prose keeps the entry list clean.
+
+## Checklist
+
+Mechanics to verify before considering an entry done:
+
+- [ ] File is in `fern/changelog/`, named with a supported date format, no subfolder.
+- [ ] `.mdx` extension.
+- [ ] Frontmatter has a `tags` array and no unsupported fields.
+- [ ] Tags reused from the existing set where one fits.
+- [ ] No h1; each feature is an `##`.
+- [ ] Opens with the user capability; 2–6 sentences per feature.
+- [ ] Button present per feature, `href` a docs URL path (not a disk path).
+- [ ] Dashboard/UI changes include the click-path before the Button.
diff --git a/.agents/skills/fern-docs/references/products.md b/.agents/skills/fern-docs/references/products.md
new file mode 100644
index 000000000..c9b21fa18
--- /dev/null
+++ b/.agents/skills/fern-docs/references/products.md
@@ -0,0 +1,121 @@
+# Products and the product switcher
+
+A product switcher lets one docs site host multiple products, each with its own
+`navigation`, `tabs`, `versions`, and API references. Use this when setting up
+product switching, adding a product to an existing switcher, or refactoring a
+single-product site into product format.
+
+**Prerequisite:** products are a Team/Enterprise feature. If the site isn't on
+one of those plans, the switcher won't render — direct the user to
+support@buildwithfern.com rather than debugging config.
+
+Canonical docs: https://buildwithfern.com/learn/docs/configuration/products.md
+(append `.md` to any Fern docs URL for clean markdown to fetch).
+
+## The model
+
+- Each **internal** product is a `.yml` file in `fern/products/` that holds that
+  product's `navigation` (and `tabs`, if used).
+- Each product is registered in the top-level `fern/docs.yml` under a `products:`
+  list.
+- The top-level `docs.yml` holds **no** `navigation:` or `tabs:` of its own once
+  products exist — that config lives in the product files.
+- **External** products link to a URL instead of site content. They're defined
+  entirely in `docs.yml` (no product `.yml`) and support no `navigation`/`tabs`.
+
+Paths inside a YAML file are **relative to that file**. Shared pages are
+referenced across products with `../pages/...`.
+
+## Register products in docs.yml
+
+```yaml
+products:
+  - display-name: Product A          # internal
+    path: ./products/product-a.yml
+    icon: fa-solid fa-leaf
+    slug: product-a                  # optional
+    subtitle: Product A subtitle     # optional
+
+  - display-name: Product C          # external
+    href: https://dashboard.example.com
+    subtitle: Product C subtitle
+    target: _blank                   # optional, opens in new tab
+```
+
+Per-product fields: `display-name` plus `path` (internal) or `href` (external).
+Optional for both: `image`, `icon`, `subtitle`. Internal-only: `slug`,
+`versions`. If both `image` and `icon` are set, `image` wins.
+
+**Icons** take three forms: a Font Awesome name (`fa-solid fa-rocket`), a
+relative image path (resolved against the YAML file it's written in — an icon in
+`fern/products/x.yml` resolves `./assets/i.svg` to `fern/products/assets/i.svg`),
+or an inline `"<svg>...</svg>"` string.
+
+## Product file
+
+Add the schema directive at the top for editor validation:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/product-yml.schema.json
+navigation:
+  - section: Introduction
+    contents:
+      - page: Shared Resource
+        path: ../pages/shared-resource.mdx   # shared across products
+  - api: API Reference
+```
+
+With tabs, declare `tabs:` then a `navigation:` keyed by `tab:` — same shape as a
+single-product `docs.yml`, just moved into the product file.
+
+## Workflows
+
+**New switcher from scratch:** create `fern/products/`, add a `.yml` per product
+with its `navigation`/`tabs`, then add the `products:` list to `docs.yml`.
+
+**Add a product to an existing switcher:** create the new product `.yml`, then
+append one entry to the `products:` list. Existing products are untouched.
+
+**Refactor a single-product site into products** (most error-prone):
+
+1. Create `fern/products/` and a `.yml` per product.
+2. **Move** the existing top-level `navigation:` (and `tabs:`) out of `docs.yml`
+   and into the product file(s), splitting content across products as needed.
+3. Add the `products:` list to `docs.yml`.
+4. Confirm `docs.yml` no longer has a top-level `navigation:` or `tabs:`.
+5. Fix links: a product slug now prefixes every URL in that product (see below).
+
+## Footguns
+
+- **`navigation`/`tabs` must leave `docs.yml`.** Once products exist, top-level
+  `navigation:`/`tabs:` in `docs.yml` is wrong — it belongs in the product files.
+  For versioned products it moves one level deeper, into the *version* files, not
+  the product file.
+- **A product slug changes URLs.** Pages gain a `/<product-slug>/` segment, so
+  published URLs and existing internal links shift. Update internal links per the
+  **Links** section of `SKILL.md`, and set up [redirects](https://buildwithfern.com/learn/docs/seo/redirects.md)
+  for the old paths. A product with no `slug:` contributes no segment.
+- **Paths are relative to their own YAML file**, including icon image paths —
+  a frequent source of broken icons after moving files.
+- **External products** support `href`/`target` only — no `navigation`, `tabs`,
+  `slug`, or `versions`.
+
+## Related options
+
+Each extends the switcher; follow the link when a task needs it.
+
+- **[Versioning](https://buildwithfern.com/learn/docs/configuration/versions.md)** —
+  a `versions/` folder inside a product, one `.yml` per version holding that
+  version's `navigation`/`tabs`, registered under the product's `versions:` list.
+  The first version is the default and uses unversioned paths.
+- **[Site-level landing page](https://buildwithfern.com/learn/docs/configuration/site-level-settings.md)** —
+  a `landing-page:` in `docs.yml` that renders at the site root, independent of
+  any product.
+- **[Instance audiences](https://buildwithfern.com/learn/docs/configuration/site-level-settings.md)** —
+  tag products/versions with `audiences` to include or exclude them per
+  documentation instance.
+- **[Conditional content by product](https://buildwithfern.com/learn/docs/writing-content/components/if.md)** —
+  `<If products={["..."]}>…</If>` renders per current product.
+- **[Search scoping](https://buildwithfern.com/learn/docs/customization/search.md)**
+  and **[selector styling](https://buildwithfern.com/learn/docs/configuration/products.md)**
+  (`fern-product-selector`, `fern-version-selector` CSS classes).
diff --git a/.agents/skills/fern-docs/references/redirects.md b/.agents/skills/fern-docs/references/redirects.md
new file mode 100644
index 000000000..8d7d19f80
--- /dev/null
+++ b/.agents/skills/fern-docs/references/redirects.md
@@ -0,0 +1,98 @@
+# Redirects
+
+Redirects map old URLs to new ones so inbound links and search rankings survive
+when a page moves, is renamed, or is deleted. Read this whenever an edit changes
+a published URL — moving or renaming a page or its file, changing a `slug:`,
+restructuring navigation, adding a product slug, or removing a page.
+
+Canonical docs: https://buildwithfern.com/learn/docs/seo/redirects.md
+(append `.md` to any Fern docs URL for clean markdown to fetch).
+
+## When a URL changes
+
+A redirect is needed whenever the path computed by the **Links** section of
+`SKILL.md` would change for a page that has already been published. Common
+triggers:
+
+- Moving or renaming a page file, or moving it to a different section/folder.
+- Setting, changing, or removing a page's frontmatter `slug:`.
+- Renaming a section, folder, tab, or version **whose slug is auto-derived from
+  its display name** — changing the `title:`/`display-name:` in `docs.yml`
+  changes the auto-slug, and thus every URL beneath it. No URL changes if that
+  item has an explicit `slug:` (the title is then just a label), or if the
+  affected pages set their own absolute frontmatter `slug:`.
+- Adding or changing a product `slug:` (prefixes every URL in that product).
+- Deleting a page that readers or search engines may still reach.
+
+Compute the old path and the new path per `SKILL.md`. If they differ, add a
+redirect from old to new.
+
+## Where redirects go
+
+Default to the top-level `fern/docs.yml`, under a single `redirects:` list — even
+in a multi-product or versioned site where navigation is split across several
+`.yml` files. Redirects are site-wide, so keeping them in one place is easiest to
+reason about.
+
+But check first: if the repo already keeps redirects somewhere else or splits
+them by a clear convention (per product, per version), follow that instead of
+introducing a second pattern. Grep for `redirects:` to see what's already there.
+
+## Configuration
+
+Add entries under a top-level `redirects:` list.
+
+```yaml
+redirects:
+  - source: "/old-path"
+    destination: "/new-path"
+  - source: "/old-folder/path"
+    destination: "https://www.example.com/fern"   # external is allowed
+```
+
+Per-entry fields:
+
+- **`source`** (required) — the relative path to redirect *from*. No absolute
+  URLs, no query parameters.
+- **`destination`** (required) — an internal path or a full external `https` URL.
+- **`permanent`** — defaults to `true` (308). Set `false` for a temporary (307)
+  redirect.
+
+## Pattern matching
+
+Use `:param` to capture a single path segment and `:param*` to capture zero or
+more. This preserves nested paths when a whole folder moves:
+
+```yaml
+redirects:
+  - source: "/old-folder/:slug"      # one segment
+    destination: "/new-folder/:slug"
+  - source: "/old-folder/:slug*"     # any depth below the folder
+    destination: "/new-folder/:slug*"
+```
+
+**Order matters.** Redirects are evaluated top-to-bottom and the first match
+wins, so list specific paths before broad `:slug*` catch-alls.
+
+## Footguns
+
+- **Don't redirect to the homepage** to handle dead URLs — set
+  `hide-404-page: true` instead.
+- **Don't redirect between default and versioned URLs by hand** — Fern handles
+  the default version's unversioned paths automatically; a manual redirect
+  conflicts.
+- **Avoid loops.** `source` must not equal `destination`, and chains must not
+  circle back (A→B→A).
+- **Don't add redirects for paths Fern already resolves.** Only add them for URLs
+  that genuinely changed.
+
+## Verify
+
+`fern check` flags missing redirects via its `missing-redirects` rule —
+previously-published URLs that no longer resolve. Run it twice:
+
+- **Before** you start, to capture a baseline of what's already flagged. Anything
+  it reports now is pre-existing, not something your edit caused.
+- **After** your changes, to confirm you haven't introduced new unresolved URLs.
+  Every `missing-redirects` warning that wasn't in the baseline is a move you
+  made that still needs a redirect.
diff --git a/.agents/skills/fern-docs/references/snippets.md b/.agents/skills/fern-docs/references/snippets.md
new file mode 100644
index 000000000..927da9675
--- /dev/null
+++ b/.agents/skills/fern-docs/references/snippets.md
@@ -0,0 +1,90 @@
+# Reusable snippets
+
+A snippet is an `.mdx` file whose content is included into other pages with the
+`<Markdown src="..." />` component, so one source renders in many places. Reach
+for this reference when you notice either trigger:
+
+- You're **editing the same content across multiple pages** — a sign it should be
+  single-sourced into one snippet instead of maintained in parallel.
+- You're **adding generic or boilerplate content** that likely already exists
+  elsewhere — a "contact support" line, a prerequisites block, a standard
+  warning. Check for an existing snippet to reuse before writing it fresh.
+
+It also covers the reverse: pulling content back inline when a snippet is no
+longer earning its keep.
+
+Canonical docs: https://buildwithfern.com/learn/docs/writing-content/reusable-snippets.md
+(append `.md` to any Fern docs URL for clean markdown to fetch).
+
+## Mechanics
+
+- Snippet files are `.mdx`, conventionally under `fern/snippets/` (any folder in
+  the `fern` project works).
+- Include one with an **absolute** `src` relative to the `fern` folder:
+
+  ```jsx
+  <Markdown src="/snippets/watering-schedule.mdx" />
+  ```
+
+  So `fern/snippets/file.mdx` → `src="/snippets/file.mdx"`, and
+  `fern/docs/guides/snippets/file.mdx` → `src="/docs/guides/snippets/file.mdx"`.
+  The path is the same no matter which page includes it.
+- Parameterize with `{{paramName}}` placeholders in the snippet, passed as props
+  on include:
+
+  ```mdx
+  <Warning>Water your {{plant}} every {{interval}} days.</Warning>
+  ```
+  ```jsx
+  <Markdown src="/snippets/watering.mdx" plant="peace lily" interval="3" />
+  ```
+
+A snippet include is **not** an internal link — leave the `src` path as-is; don't
+rewrite it like a page URL (see the **Links** section of `SKILL.md`).
+
+## When to use a snippet
+
+The test is *single-sourcing*: the same content appears in two or more places and
+must stay identical when it changes. Good fits:
+
+- **Constants** — API limits, prices, version numbers, endpoints.
+- **Repeated warnings or notes** that must read the same everywhere.
+- **Standardized blocks** — a setup prerequisite, a support footer, a boilerplate
+  callout reused across pages.
+
+The win is that one edit propagates everywhere. If editing in one place is
+actually what you want, a snippet is the wrong tool.
+
+## When not to use a snippet
+
+- **Used in only one place.** No single-sourcing benefit — it just hides the
+  content in another file and makes the page harder to read and edit. Keep it
+  inline.
+- **The instances should be able to drift.** If two spots happen to say something
+  similar but may legitimately diverge later, don't couple them.
+- **To avoid scrolling / "tidy up" a long page.** Length isn't a reason to
+  extract; reuse is. Use sections and headings for structure instead.
+- **The content is so parameterized it's mostly `{{props}}`.** If almost
+  everything varies per use, the snippet abstracts nothing — write it inline.
+
+## Moving content out of a snippet
+
+Watch for snippets that have **dropped to a single use** — often the result of an
+edit that removed or merged the other references. A one-use snippet has no reason
+to exist, so inline it:
+
+1. Confirm the real usage count — grep the repo for the `src` path:
+
+   ```bash
+   grep -rn 'src="/snippets/watering.mdx"' fern --include="*.mdx"
+   ```
+
+   (Match on whatever path the snippet uses.)
+2. If exactly one include remains, paste the snippet's content into that page,
+   substituting any `{{params}}` with the literal values from that include's
+   props.
+3. Delete the now-orphaned snippet file.
+
+Conversely, when you find yourself copying the same block onto a second page,
+that's the signal to extract it into a snippet rather than maintaining two copies
+— the same canonical-home principle from `SKILL.md`'s cross-referencing guidance.
diff --git a/.agents/skills/fern-docs/references/translations.md b/.agents/skills/fern-docs/references/translations.md
new file mode 100644
index 000000000..d8ff3fa60
--- /dev/null
+++ b/.agents/skills/fern-docs/references/translations.md
@@ -0,0 +1,246 @@
+# Translations
+
+Fern **hosts** multilingual docs but does **not** translate them. It renders a
+language switcher, serves each locale under its own URL prefix, and falls back to
+the default language for any page a locale hasn't translated yet — so partial
+coverage is safe and you never have to translate everything at once. The actual
+translating is the job here: produce per-locale copies of the source pages and a
+navigation overlay, following the rules below.
+
+Read this whenever you add a language, translate or re-translate pages, or update
+existing translations after the source language changed.
+
+Canonical docs: https://buildwithfern.com/learn/docs/content/localization.md
+(append `.md` to any Fern docs URL for clean markdown to fetch). When a config
+key or behavior here is unclear, query the Fern MCP server rather than guessing.
+
+## How Fern translations work
+
+- **Default (source) language** is authored in place: `fern/docs.yml` plus the
+  `docs/` pages it points to. Exactly one language in the `translations:` list is
+  marked `default: true` — that's the source everything is translated *from*.
+- **Each other locale mirrors the source tree** under `fern/translations/{lang}/`,
+  keeping the **same relative paths**: source `docs/pages/X.mdx` →
+  `translations/{lang}/docs/pages/X.mdx`. A locale folder also carries its own
+  `translations/{lang}/docs.yml` — the **navigation overlay** that supplies
+  translated sidebar/tab labels.
+- **A page's translated title lives in its translated MDX frontmatter**
+  (`title:`, and `sidebar-title:` if the sidebar label differs from the page
+  title), *and* the matching label appears in the overlay `docs.yml`. Translate
+  both; keep them consistent.
+- **Slugs (URLs) are inherited from the source locale**, not re-derived from the
+  translated title. A page titled `Surcharge` → `Zuschlag` keeps the slug
+  `surcharge` in every locale. **Never translate or re-derive a slug** — doing so
+  would fork the URL per language and break cross-locale links and SEO.
+- **Untranslated pages fall back** to the default language automatically. You do
+  not create placeholder files; you simply don't have a locale file yet.
+
+> When the translate recipe invokes you, it hands you a **manifest** produced by a
+> deterministic repo scan — the source language, the target locales, the exact
+> source→locale file map with each page's status (translated / stale / missing),
+> and the glossary path. Trust the manifest; you don't need to rediscover this.
+> The steps below explain how that manifest is derived (and are your fallback if
+> you ever work a repo without one).
+
+## Step 1 — Discover the translation targets
+
+Read the **root `fern/docs.yml`** and find the `translations:` block:
+
+```yaml
+translations:
+  - lang: en
+    default: true      # the source language — translate FROM this
+  - lang: it
+  - lang: de
+  - lang: fr
+  - lang: el
+  - lang: "no"         # MUST be quoted — see the "no" gotcha below
+```
+
+The target locales are every entry without `default: true`. Do not infer
+languages from existing `translations/` folders alone — the `docs.yml` list is
+authoritative, and a folder may exist for a locale that was removed, or be
+missing for a newly added one.
+
+### The `"no"` (Norwegian) gotcha
+
+YAML parses bare `no`, `yes`, `on`, `off`, `true`, `false` as booleans. The
+Norwegian locale code `no` **must be quoted** (`lang: "no"`) anywhere it appears
+as a YAML *value*, or it silently becomes the boolean `false` and the language
+breaks. The `translations/no/` directory name is fine unquoted (it's a path, not
+YAML). When you emit any YAML, quote `"no"` as a value and quote any other value
+that is a bare reserved word.
+
+## Step 2 — Inventory what needs translating
+
+For each target locale, the work is two artifacts:
+
+1. **Page content** — one mirrored MDX file per source page under
+   `translations/{lang}/`. Translate frontmatter `title`, `description`,
+   `sidebar-title`, and the prose/body per the do-not-translate rules below.
+2. **Navigation overlay** — `translations/{lang}/docs.yml` carrying the
+   translated labels for everything the sidebar shows: each `tab` `display-name`,
+   each `section` name, and each `page` label.
+
+Read the root `docs.yml` `navigation:` to enumerate every label that needs an
+overlay translation, and `tabs:` for the tab display names.
+
+## Step 3 — Detect the existing overlay style and coverage
+
+A repo's overlay `docs.yml` files follow **one of two styles**. Detect which the
+repo already uses and match it; do not mix styles within a repo.
+
+**Path-repeating** (robust; preferred for new overlays). Every `page:` repeats
+the source `path:`, so each entry is matched to its source page explicitly:
+
+```yaml
+- section: Integrazione web
+  contents:
+    - page: Panoramica dell'integrazione web
+      path: docs/pages/integration-options/web-integration/web-integration.mdx
+```
+
+**Label-only** (terse). Entries carry only the translated label and **no `path:`**;
+Fern matches each entry to the source page **positionally** (by `pageId`):
+
+```yaml
+- section: Web-Integration
+  contents:
+    - page: Web-Integration im Überblick
+```
+
+Because label-only relies on position, its overlay **must keep the exact same
+navigation structure and order as the source** — same tabs, same sections, same
+page count and sequence. Adding, removing, or reordering an entry silently
+misaligns every page after it. Path-repeating is immune to this, which is why
+it's the safer style to generate when a repo has no established convention.
+
+**Slugs in overlays:** because slugs inherit from source, you do **not** need to
+pin `slug:` in either style (path-repeating overlays here carry none). Some
+hand-authored label-only overlays pin the *source* slug defensively
+(`slug: surcharge`) — that's harmless, but only ever the source slug, never one
+derived from the translated label.
+
+**`viewers:` in overlays:** do **not** repeat `viewers:` / RBAC gating in an
+overlay. Visibility is inherited from the source navigation through the
+structural match. (The "never drop `viewers:`" rule applies to editing *source*
+files, not overlays.)
+
+**Coverage:** compare the set of source pages against the files already present
+under `translations/{lang}/`. Pages missing there are untranslated (they fall
+back to default). When translating after a source change, translate only the
+pages whose source changed plus any not yet covered — don't re-translate
+unchanged pages.
+
+### The mechanical mapping
+
+For every source page and every target locale:
+
+```
+docs/pages/<...>.mdx   →   translations/<lang>/docs/pages/<...>.mdx
+```
+
+The relative path is **identical**; only the `translations/<lang>/` root differs.
+Never rename, re-slug, or restructure on the way across.
+
+## Do-not-translate rules
+
+Translate meaning, preserve mechanics. **Translate:** prose and body text;
+frontmatter `title`, `description`, `sidebar-title`; navigation labels (tab
+`display-name`, `section`, `page`); alt text; and the visible child text and
+human-readable **prop values** of MDX components (e.g. a `<Card title="...">`
+title).
+
+**Preserve verbatim — never translate:**
+
+- Fenced code blocks and inline `` `code` ``, including comments and string
+  literals inside them (translating a code comment is acceptable only if the
+  surrounding pages clearly do so; default to leaving code untouched).
+- API identifiers: endpoints, parameters, fields, enum values, error codes,
+  HTTP methods, status codes.
+- MDX/JSX **component names and prop *names*** — translate prop *values* and child
+  text, never the tag or attribute key. `<Note>` stays `<Note>`; `title=` stays
+  `title=`.
+- UPPERCASE placeholders and template tokens: `<YOUR_API_KEY>`, `{{merchantId}}`,
+  `:param`.
+- URLs, link targets, anchors (`#section`), and image/asset paths.
+- Frontmatter `slug`, `path`, `icon`, `viewers`, and any other non-display key.
+- Numbers, units, currency codes, and dates unless the surrounding locale
+  convention clearly localizes them.
+
+When in doubt whether a token is content or mechanics, preserve it.
+
+## Per-repo glossary
+
+Fern has no native glossary, so for cross-page consistency build one **per repo**:
+a short list of source terms that must render a fixed way in every locale (or
+stay untranslated everywhere). It exists so the same term never comes out three
+different ways across a docs site — most commonly product names, company and
+partner names, and other proper nouns that should stay verbatim.
+
+**Discover it from the repo, don't hardcode it.** Scan the source docs for
+recurring brand/proper nouns and the product's own house terminology; those are
+the glossary. When a preferred rendering for a term isn't obvious, default to
+keeping it verbatim rather than guessing a translation.
+
+**Format** — a YAML list; each entry is a source term plus either `keep: true`
+(never translate, all locales) or explicit per-locale renderings:
+
+```yaml
+terms:
+  - term: "<ProductName>"      # product/brand name — identical in every locale
+    keep: true
+  - term: "<house-term>"       # a term with a fixed agreed translation
+    translations:
+      it: "<it rendering>"
+      de: "<de rendering>"
+```
+
+Keep it in the repo at `fern/translations/glossary.yml` so it lives beside the
+content it governs and is reviewed in the same PRs (follow an existing location
+if the repo already has one). Pass it into **every** page's translation.
+
+## Writing the output
+
+- **Write each translated page** to its locale path — `translations/{locale}/`
+  plus the source page's relative path, unchanged.
+- **Update the navigation overlay** (`translations/{locale}/docs.yml`) for any
+  new or renamed entry, matching that locale's existing overlay style. Keep its
+  structure and order aligned with the source nav, and never add or drop
+  `viewers:` — gating is inherited (a gated page must stay gated in every
+  language).
+- **Remove orphans.** When a source page was deleted or renamed, delete the
+  matching `translations/{locale}/…` file in every locale and its overlay nav
+  entry. The manifest lists these under "remove (source page deleted/renamed)".
+- **Partial coverage is safe.** You don't have to translate everything in one
+  pass — untranslated pages fall back to the default language. Translate what
+  the manifest flags and leave the rest.
+- **Summarize in the PR description** what changed per locale: pages added,
+  updated, and removed, and any locale still missing pages — so a reviewer can
+  see coverage at a glance.
+
+## Footguns
+
+- **Don't translate slugs or paths.** URLs are inherited; re-deriving them per
+  locale forks every link.
+- **Don't reorder or drop nav entries in a label-only overlay** — positional
+  matching breaks silently for every page after the change.
+- **Don't add `viewers:` to overlays** — gating is inherited; repeating it risks
+  drift from the source.
+- **Quote `"no"`** (and other reserved words) as YAML values.
+- **Don't create empty placeholder files** for untranslated pages — let Fern fall
+  back to the default language.
+- **Don't mix overlay styles** within one repo.
+- **Don't re-translate unchanged pages** on an incremental update — only changed
+  or not-yet-covered pages.
+
+## Verify
+
+- Run `fern check` — it validates that overlay paths resolve and the config is
+  well-formed. Capture a baseline before your changes so pre-existing warnings
+  aren't mistaken for new ones.
+- Spot-check that translated page slugs match their source (open the source and
+  translated frontmatter side by side — slugs identical, titles translated).
+- Confirm no glossary term appears untranslated-but-should-be or
+  translated-but-should-be-kept by grepping the new locale files for each
+  `keep: true` term and each source term that has a fixed rendering.
diff --git a/fern/docs.yml b/fern/docs.yml
index 0d78ac0aa..b71c6bb27 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -169,17 +169,10 @@ theme:
 page-actions:
   options:
     skills:
+      path: ../.agents/skills
       title: Install agent skills
       description: Skills for authoring Fern documentation, maintained in our open-source skills repo.
       learn-more-url: https://buildwithfern.com/learn/docs/ai/agent-skills
-      repository: https://github.com/fern-api/skills
-      install-command: npx skills add fern-api/skills
-      skills:
-        - name: fern-docs
-          description: >-
-            Author and edit Fern documentation: MDX pages, navigation, docs.yml
-            config, custom components, landing pages, and changelog entries.
-          url: https://github.com/fern-api/skills/tree/main/skills/fern-docs
 
 settings:
   http-snippets:
diff --git a/fern/products/docs/pages/ai/host-skills.mdx b/fern/products/docs/pages/ai/host-skills.mdx
index 2d2e07774..ae1bf7b44 100644
--- a/fern/products/docs/pages/ai/host-skills.mdx
+++ b/fern/products/docs/pages/ai/host-skills.mdx
@@ -4,19 +4,19 @@ description: Serve author-supplied agent skills from your Fern docs site and con
 availability: beta
 ---
 
-Fern Docs sites can serve your own [Agent Skills](https://www.skills.sh) so your users can discover and install them with the [skills CLI](https://www.skills.sh). You can also add an "Install skills" button to your docs UI that opens a modal with the install command and your skill list. 
+Fern Docs sites can serve your own [Agent Skills](https://www.skills.sh) so your users can discover and install them with the [skills CLI](https://www.skills.sh). Point `page-actions.options.skills.path` at a directory of skills in your docs repo, and Fern validates the bundle, generates the discovery manifest, and publishes it — so anyone can run `npx skills add https://<your-docs-domain>`. You can also add an "Install skills" button to your docs UI that opens a modal with the install command and your skill list.
 
 <Steps toc={true} tocDepth={2}>
-  <Step title="Lay out the bundle">
+  <Step title="Lay out your skills directory">
 
-Place your skills in your `fern/` folder under `.well-known/agent-skills/` (the current v0.2.0 spec) or `.well-known/skills/` (the legacy v0.1.0 layout). Both are supported and can coexist. Each skill is a subdirectory holding at least a `SKILL.md`, with optional supporting files alongside it.
+Put your skills in a single directory, with each skill in its own subdirectory holding at least a `SKILL.md`. Supporting files (references, scripts) live alongside it.
+
+The directory can live anywhere in your repo. A common choice is a repo-root `.agents/skills/` folder, which doubles as the location local coding agents (Claude Code, Cursor, and others) read from:
 
 <Files>
-  <Folder name="fern" defaultOpen>
-    <File name="docs.yml" />
-    <Folder name=".well-known" defaultOpen>
-      <Folder name="agent-skills" defaultOpen>
-        <File name="index.json" comment="discovery manifest (required)" />
+  <Folder name="your-repo" defaultOpen>
+    <Folder name=".agents" defaultOpen>
+      <Folder name="skills" defaultOpen>
         <Folder name="plant-care" defaultOpen>
           <File name="SKILL.md" comment="skill instructions" />
         </Folder>
@@ -28,15 +28,18 @@ Place your skills in your `fern/` folder under `.well-known/agent-skills/` (the
         </Folder>
       </Folder>
     </Folder>
+    <Folder name="fern" defaultOpen>
+      <File name="docs.yml" />
+    </Folder>
   </Folder>
 </Files>
 
   </Step>
   <Step title="Write each SKILL.md">
 
-Each `SKILL.md` needs YAML frontmatter with `name` and `description`, following the [Agent Skills spec](https://agentskills.io):
+Each `SKILL.md` needs YAML frontmatter with `name` and `description`, following the [Agent Skills spec](https://agentskills.io). The `name` must be kebab-case, at most 64 characters, and match its parent directory name:
 
-```markdown title="fern/.well-known/agent-skills/plant-care/SKILL.md"
+```markdown title=".agents/skills/plant-care/SKILL.md"
 ---
 name: plant-care
 description: Guide for diagnosing and treating common plant diseases.
@@ -48,43 +51,36 @@ When diagnosing a plant issue, check for...
 ```
 
   </Step>
-  <Step title="Add the discovery manifest">
-
-The `index.json` at the root of the skills directory is required. It enumerates every skill so clients can discover them in a single request, referencing each by `url` and `digest`:
-
-```json title="fern/.well-known/agent-skills/index.json"
-{
-  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
-  "skills": [
-    {
-      "name": "plant-care",
-      "type": "skill-md",
-      "description": "Guide for diagnosing and treating common plant diseases.",
-      "url": "/.well-known/agent-skills/plant-care/SKILL.md",
-      "digest": "sha256:c4d5e6f7..."
-    }
-  ]
-}
-```
+  <Step title="Declare the skills path in docs.yml">
+
+Point `page-actions.options.skills.path` at your skills directory. The path resolves relative to the folder containing `docs.yml`, and `../` is allowed — so a `docs.yml` in `fern/` can reach a repo-root `.agents/skills/` directory:
 
-The legacy v0.1.0 manifest lists a `files` array per skill instead of `url` and `digest`.
+```yaml title="fern/docs.yml"
+page-actions:
+  options:
+    skills:
+      path: ../.agents/skills
+```
 
   </Step>
   <Step title="Publish">
 
-Fern uploads the bundle during `fern generate --docs` and serves the files as-is — no `docs.yml` configuration is required. `fern check` validates the bundle at upload time, flagging:
+Fern discovers and publishes your skills during `fern generate --docs`. For every subdirectory containing a `SKILL.md`, it generates the `/.well-known/skills/index.json` discovery manifest and uploads the skill's files — nothing is written back to your repo.
 
-- A missing or unparseable `index.json`
+`fern check` validates the bundle at build time and blocks publishing on:
+
+- A declared path that doesn't exist or contains no skills
 - A `SKILL.md` whose `name` isn't kebab-case, exceeds 64 characters, or doesn't match its parent directory name
 - A `SKILL.md` with a missing or empty `description` (max 1,024 characters)
+- Duplicate skill names across the directory
+- A markdown reference that escapes the skill's directory (`../`), which would dangle once the skill is installed
 
-Once published, skills are served at:
+Once published, your skills are served at:
 
-- `https://your-docs-domain.com/.well-known/agent-skills/index.json` (discovery manifest)
-- `https://your-docs-domain.com/.well-known/agent-skills/<skill-name>/SKILL.md` (individual skill)
-- `https://your-docs-domain.com/.well-known/skills/index.json` (legacy v0.1.0 manifest)
+- `https://your-docs-domain.com/.well-known/skills/index.json` (discovery manifest)
+- `https://your-docs-domain.com/.well-known/skills/<skill-name>/SKILL.md` (individual skill)
 
-For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/agent-skills/index.json`).
+For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/skills/index.json`).
 
   </Step>
   <Step title="Install the skills">
@@ -98,25 +94,32 @@ npx skills add https://your-docs-domain.com
 The `https://` scheme is required: a bare domain is treated as a GitHub repository shorthand.
 
   </Step>
-  <Step title="Configure the Install skills button">
+  <Step title="Customize the Install skills button">
 
-Surface your skills in the docs UI by adding an "Install skills" button to the [page action bar](/learn/docs/configuration/site-level-settings#page-actions-configuration). Set `page-actions.options.skills` in `docs.yml` and the button opens a modal with a copyable install command, the list of available skills, and an optional link to the source repository.
+Setting `page-actions.options.skills` already adds an "Install skills" button to the [page action bar](/learn/docs/configuration/site-level-settings#page-actions-configuration). The button opens a modal with a copyable install command and your skill list (read from the generated manifest). Customize the modal with `title`, `description`, and `learn-more-url`:
 
-```yaml docs.yml
+```yaml title="fern/docs.yml"
 page-actions:
   options:
     skills:
+      path: ../.agents/skills
       title: Plant API Skills
       description: Skills for working with the Plant Store API.
-      repository: https://github.com/your-org/plant-api-skills
-      install-command: npx skills add https://your-docs-domain.com
-      skills:
-        - name: plant-care
-          description: Guide for diagnosing and treating common plant diseases.
-          url: https://github.com/your-org/plant-api-skills/tree/main/plant-care
-        - name: garden-planner
-          description: Plan garden layouts and planting schedules.
+      learn-more-url: https://your-docs-domain.com/skills
+```
+
+By default the modal shows `npx skills add https://<your-docs-domain>`. Override it with `install-command` when that command won't work as-is — for example auth-walled docs, a private registry, or a multi-step install:
+
+```yaml title="fern/docs.yml"
+page-actions:
+  options:
+    skills:
+      path: ../.agents/skills
+      install-command:
+        - npm login --registry https://npm.your-org.com
+        - npx skills add https://your-docs-domain.com
 ```
+
 </Step>
 </Steps>
 
diff --git a/fern/products/docs/pages/changelog/2026-06-22.mdx b/fern/products/docs/pages/changelog/2026-06-22.mdx
new file mode 100644
index 000000000..0a24694ec
--- /dev/null
+++ b/fern/products/docs/pages/changelog/2026-06-22.mdx
@@ -0,0 +1,9 @@
+---
+tags: ["ai"]
+---
+
+## Host agent skills from a directory in your repo
+
+The "Install skills" page action now accepts `page-actions.options.skills.path`, pointing at a skills directory in the same repo as your `docs.yml`. The CLI validates the bundle, generates the `/.well-known/skills/index.json` manifest, and publishes it so users can install with `npx skills add https://<your-domain>`.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/ai-features/host-skills">Read the docs</Button>
diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx
index a317d9d76..6267615ab 100644
--- a/fern/products/docs/pages/navigation/site-level-settings.mdx
+++ b/fern/products/docs/pages/navigation/site-level-settings.mdx
@@ -871,19 +871,15 @@ Toggle the built-in actions on or off with a boolean. **Copy Page** (`copy-page`
 
 ### Install skills action
 
-Add an "Install skills" button to the page action bar that opens a modal showing how to install your site's [custom skills](/learn/docs/ai-features/host-skills). The modal displays a copyable install command, the list of available skills, and links to the skill source.
+Add an "Install skills" button to the page action bar that opens a modal showing how to install your site's [custom skills](/learn/docs/ai-features/host-skills). The modal displays a copyable install command and the list of available skills. Point `path` at a directory of skills in your repo and Fern publishes them and reads the modal's skill list from the generated manifest:
 
 ```yaml docs.yml
 page-actions:
   options:
     skills:
+      path: ../.agents/skills
       title: Plant API Skills
       description: Skills for working with the Plant Store API.
-      repository: https://github.com/your-org/plant-api-skills
-      skills:
-        - name: plant-care
-          description: Guide for diagnosing and treating common plant diseases.
-          url: https://github.com/your-org/plant-api-skills/tree/main/plant-care
 ```
 
 <Markdown src="/products/docs/snippets/install-skills-properties.mdx" />
diff --git a/fern/products/docs/snippets/install-skills-properties.mdx b/fern/products/docs/snippets/install-skills-properties.mdx
index 0d71c5682..8377fd167 100644
--- a/fern/products/docs/snippets/install-skills-properties.mdx
+++ b/fern/products/docs/snippets/install-skills-properties.mdx
@@ -2,6 +2,10 @@
   Enables the "Install skills" page action and configures the modal it opens. Omit to hide it.
 </ParamField>
 
+<ParamField path="page-actions.options.skills.path" type="string" required={false} toc={true}>
+  Path to a directory of agent skills in this repo. Resolved relative to the folder containing `docs.yml`; `../` is allowed (e.g. a repo-root `.agents/skills/` directory that also serves local coding agents). Every subdirectory containing a `SKILL.md` is published as one skill: the CLI validates the bundle, generates the `/.well-known/skills/index.json` discovery manifest, and uploads every file so that `npx skills add https://<your-docs-domain>` works. Nothing is written back to your repo.
+</ParamField>
+
 <ParamField path="page-actions.options.skills.title" type="string" required={false} toc={true}>
   Overrides the modal title.
 </ParamField>
@@ -14,14 +18,10 @@
   URL for a "Learn more" link shown alongside the description.
 </ParamField>
 
-<ParamField path="page-actions.options.skills.repository" type="string" required={false} toc={true}>
-  Source repository URL displayed as a "View source" button in the modal.
-</ParamField>
-
 <ParamField path="page-actions.options.skills.install-command" type="string or list of strings" required={false} toc={true}>
-  Command(s) shown as a copyable block in the modal. A single string is shown as-is; an array is joined with newlines for multi-step installs. Defaults to `npx skills add https://<your-docs-domain>` when omitted.
+  Command(s) shown as a copyable block in the modal. A single string is shown as-is; an array is joined with newlines for multi-step installs. Defaults to `npx skills add https://<your-docs-domain>` when omitted. Set this when the generated command won't work as-is — for example auth-walled docs, a private registry, or a multi-step install.
 </ParamField>
 
 <ParamField path="page-actions.options.skills.skills" type="list of objects" required={false} toc={true}>
-  List of skills displayed in the modal. Each entry has a `name` (required), `description` (optional), and `url` (optional link to the skill source). When the site serves a `/.well-known/agent-skills/index.json` or `/.well-known/skills/index.json` manifest, the manifest replaces this list.
+  List of skills displayed in the modal. Each entry has a `name` (required), `description` (optional), and `url` (optional link to the skill source). When `path` is set, or the site serves a `/.well-known/skills/index.json` (or `/.well-known/agent-skills/index.json`) manifest, the generated manifest replaces this hand-listed array.
 </ParamField>