docs: clarify git-ref version constraints in docs.yml

[devin-ai-integration]

Summary

Git-ref-based docs versioning lets a versions: entry in docs.yml name a git branch, tag, or commit SHA instead of a path into the working tree. Customers can keep an older docs version in git history rather than copying its content into the current tree, and it still publishes with the current site's theme, shell, and version dropdown. This PR fills the remaining gaps in the existing versioning docs: the ref/path mutual exclusion, what the CLI needs at the ref, and how missing SDK reference output is handled.

Implements docs for: feat(cli): add git-ref-based docs versioning (fern-api/fern#17288)

Changes

fern/products/docs/pages/navigation/versions.mdx — the "Build a version from a git ref" accordion already covered the ref field, branch-vs-tag behavior, dev-preview exclusion, and content-root precedence. Added:

• A version entry sets either ref or path, never both; fern check reports an entry that sets both.
• Publishing a ref-backed version requires a fern folder at the same path at that ref.
• Library reference sections are skipped with a warning when their generated MDX is missing at the ref.
• Spelled out what is composed from the ref (pages, navigation, assets, API references) versus the current branch (theme, shell, versions metadata).

No changelog entry: the feature was already announced in fern/products/docs/pages/changelog/2026-08-06.mdx ("Build a docs version from a git ref"), and these are clarifications to that same feature rather than new capability.

Validation: pre-commit run --files ... (0 errors) and fern check --warnings (0 errors).

Link to Devin session: https://app.devin.ai/sessions/83da6c6e72644cb9830d77d87596b053

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

🌿 Preview your docs: https://fern-preview-devin-1786208887-git-ref-versions.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

• learn/docs/configuration/versions