docs(fern): migrate documentation to Fern

Signed-off-by: Lawrence Lane <llane@nvidia.com>

Author: lbliii

.agents/skills/switchyard-docs/SKILL.md

@@ -24,7 +24,7 @@ use `cargo test --workspace` before calling a broad Rust MR ready.
 
 | Situation | Command |
 |---|---|
-| Pick gates from the current diff | `python .agents/skills/switchyard-testing-ci/scripts/select_validation.py --changed` |
+| Map the current diff | `git status -sb && git diff --stat && git diff --name-only` |
 | Pre-PR hermetic gate (default) | `uv run ruff check . && uv run mypy switchyard && env -u OPENROUTER_API_KEY -u NVIDIA_API_KEY -u OPENAI_API_KEY -u ANTHROPIC_API_KEY uv run pytest tests/ -v -m "not integration"` |
 | Mirror CI pytest with no live creds | `env -u OPENROUTER_API_KEY -u NVIDIA_API_KEY -u OPENAI_API_KEY -u ANTHROPIC_API_KEY uv run pytest tests/ -v -m "not integration"` |
 | Rust component crate change | `cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test -p switchyard-components` |
@@ -34,26 +34,18 @@ use `cargo test --workspace` before calling a broad Rust MR ready.
 | Live e2e (only on explicit user request) | `NVIDIA_API_KEY=… uv run pytest tests/e2e/ -v -m integration -o addopts= --maxfail=10` |
 | Skill/docs change only | YAML frontmatter check + `git diff --check` (see [Skill/docs-only gate](#skilldocs-only-gate)) |
 
-## Dynamic Selection First
+## Diff-Based Selection First
 
-From the repo root, inspect the diff and let the selector propose focused gates:
+From the repo root, inspect the diff and map each changed area to the focused gates below:
 
 ```bash
 cd "$(git rev-parse --show-toplevel)"
 git status -sb
 git diff --stat
-python .agents/skills/switchyard-testing-ci/scripts/select_validation.py --changed
 ```
 
-For a not-yet-edited area, pass likely owners explicitly:
-
-```bash
-python .agents/skills/switchyard-testing-ci/scripts/select_validation.py \
-  --path switchyard/lib/translation/request_engine.py \
-  --path tests/test_request_translation_engine.py
-```
-
-Use the output as the starting plan, then add any tests revealed by code search or by the failure.
+Use the current diff as the starting plan, then add any tests revealed by code search or by the
+failure map in this skill.
 
 ## CI Gates and Local Equivalence
 
@@ -303,7 +295,6 @@ uv run pytest tests/test_cli_stale_names.py tests/test_no_stale_module_paths.py
 | Running `uv run pytest tests/ -v` with `OPENROUTER_API_KEY`/`NVIDIA_API_KEY`/`OPENAI_API_KEY`/`ANTHROPIC_API_KEY` set in your shell | Tests that mock providers can accidentally hit live endpoints. Default to `-m "not integration"`, or strip credentials with `env -u`. |
 | Treating mypy as optional because CI marks it `continue-on-error` | Mypy still catches real bugs in `switchyard/` typed code. Run it for any change to profiles, route bundles, backends, request/response models, or translation. |
 | Skipping the slim-install smoke gate after a dependency or top-level import change | This is the *actual* hard CI gate that catches `torch`/`transformers`/`routellm` accidentally landing in the default install. |
-| Claiming validation from `scripts/select_validation.py` without rerunning it after committing changes | The script diffs against `HEAD` plus untracked files; if your changes are already committed, `--changed` returns "no diff". Pass `--path` explicitly, or diff against the branch base. |
 | Adding `# noqa` or per-line ignores to make ruff green | Ruff is a hard CI gate. Fix the code or, if the rule is wrong here, lift the ignore to the file or project level with a one-line justification. |
 | Editing a generated artifact (e.g., `docs/.venv-docs/...`) because ruff complained about it | Delete the artifact instead. CI does not have it; you should not either. |
 

.agents/skills/switchyard-testing-ci/SKILL.md

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Validates Fern docs configuration on pull requests.
+
+name: Fern docs (check)
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/fern-docs-*.yml"
+      - ".github/workflows/publish-fern-docs.yml"
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/fern-docs-*.yml"
+      - ".github/workflows/publish-fern-docs.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+
+      - name: Install Fern CLI
+        run: npm install -g fern-api@$(jq -r .version docs/fern/fern.config.json)
+
+      - name: Validate Fern configuration
+        working-directory: ./docs/fern
+        run: fern check

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Workflow 1 of 2 for Fern doc previews.
+#
+# Collects the docs sources and PR metadata from the possibly untrusted PR
+# branch. No secrets are used here, so this is safe to run on fork PRs.
+# The companion workflow builds the preview and posts the PR comment.
+
+name: "Preview Fern Docs: Build"
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/fern-docs-preview-build.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  collect:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Save PR metadata
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          mkdir -p .preview-metadata
+          echo "$PR_NUMBER" > .preview-metadata/pr_number
+          echo "$HEAD_REF" > .preview-metadata/head_ref
+          git diff --name-only "origin/${BASE_REF}...HEAD" -- '*.mdx' > .preview-metadata/changed_mdx_files 2>/dev/null || true
+
+      # The nightly navigation reaches from docs/fern/ into docs/**/*.mdx,
+      # so the artifact must preserve the complete docs tree.
+      - name: Upload docs sources and metadata
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: fern-preview
+          path: |
+            docs/
+            .preview-metadata/
+          include-hidden-files: true
+          retention-days: 1