Clarify link behavior, link checking, and redirects validation

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

@@ -276,12 +276,14 @@ hideOnThisPage: true
 
     <Warning>
     The `--broken-links` and `--strict-broken-links` flags are deprecated. Use the [`broken-links` validation rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` instead.
-
-    You can also use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to validate both internal and external links on your live published site.
     </Warning>
 
     Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output.
 
+     Most `fern check` rules — including [`broken-links`](/learn/docs/configuration/site-level-settings#check-configuration) — validate against the navigation tree built from your **local** config and do not crawl your live deployed site or follow external URLs. The exception is the [`missing-redirects` rule](/learn/docs/seo/redirects#catching-missing-redirects), which compares your local navigation against the previously published state and therefore requires `fern login` or `FERN_TOKEN`.
+
+    To check links on a published site, use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. When all checks pass, the command produces no output.
+
     <CodeBlock title="terminal">
     ```bash
     fern check [--api <api>] [--warnings]

fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx

@@ -55,14 +55,27 @@ Because the `<h1>` is generated automatically, you should begin your page conten
 ## Links in Markdown
 
 ### Link format
-Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows:
 
-<CodeBlock title='Relative link example'>
-```mdx
-Read the [Introduction](/learn/sdks/overview/introduction).
+To link to another page on your docs site, write the destination's **published site path**, starting with a `/`. Fern builds this path from the slugs in your [`docs.yml` and product YAML files](/learn/docs/configuration/navigation), not from the file's location on disk. To link to a heading on another page, append `#anchor` to the path. 
+
+<Info>
+  File-relative paths like `./` and `../` aren't supported for inter-page links — use the published site path instead. (File-relative paths are still correct for [images and other media](/learn/docs/writing-content/markdown-media) and for `path:` references inside YAML config.)
+</Info>
+
+<CodeBlock title='Internal link example'>
+```mdx wordWrap
+Learn about [how Fern SDKs work](/learn/sdks/overview/how-it-works).
+
+Configure [sidebar icons](/learn/docs/configuration/navigation#sidebar-icons) to add visual cues to your navigation.
 ```
 </CodeBlock>
 
+In [versioned docs](/learn/docs/configuration/versions), the same path lands on a different version depending on whether you write the unversioned form (default version) or the versioned form (e.g. `/learn/docs/v2/getting-started`). For inline version-specific content within a single page, use [`<If versions=…>`](/learn/docs/writing-content/components/if#by-version) or [`<Versions>`](/learn/docs/writing-content/components/versions).
+
+### Validating links
+
+The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. It does not crawl your deployed site or follow external URLs. To check links on a published site, use the [Fern Dashboard](https://dashboard.buildwithfern.com/).
+
 ### API link syntax
 
 <Markdown src="/products/docs/snippets/api-link-syntax.mdx" />

fern/products/docs/pages/seo/redirects.mdx

@@ -14,7 +14,9 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir
 
 ## Catching missing redirects
 
-You can use [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) to automatically detect pages that were removed or moved without a redirect. Configure the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` to control its severity.
+The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. This catches pages you've moved or removed before they start returning 404s for existing inbound links.
+
+Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`.
 
 <llms-only>
 ## Common errors

fern/products/docs/snippets/redirects.mdx

@@ -66,14 +66,14 @@ settings:
 </Accordion>
 <Accordion title="Versioning and redirects">
 
-If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/getting-started/v2`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs.
+If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/v2/getting-started`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs.
 
 Avoid redirecting from unversioned to versioned URLs:
 
 ```yaml title="docs.yml"
 redirects:
   - source: /docs/event-notifications
-    destination: /docs/event-notifications/v2 # Don't do this
+    destination: /docs/v2/event-notifications # Don't do this
 ```
 
 Manually overriding the default versioning behavior can lead to unexpected redirect patterns.