docs: keep page URLs aligned with file paths

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

@@ -108,6 +108,7 @@ Write the doc update following the rules in `docs/CONTRIBUTING.mdx`. Key reminde
 - **Use `sidebar-title` for short nav labels**. For explicit navigation entries, keep relative `slug` values in `docs/index.yml` instead of page frontmatter.
 - **Keep explicit `page:` entries in `docs/index.yml`**. Fern still requires them. If the page defines `sidebar-title`, set `page:` to that value. Otherwise set `page:` to the page frontmatter `title`.
 - **Use `skip-slug: true` in `docs/index.yml`** when a child page should live at the parent section path.
+- **Keep each page URL equal to its file path** under `docs/`. Rename the file when you rename a page, add a `fern/docs.yml` redirect for the old URL, and set a relative `slug:` when the nav label does not produce the file name. `mise run docs` runs `docs:nav`, which fails otherwise.
 - **Use `keywords` as a comma-separated string**.
 - **Do not add a duplicate H1**. Fern renders the page title from frontmatter.
 - **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia.

.github/workflows/branch-docs.yml

@@ -7,6 +7,9 @@ on:
       - "fern/**"
       - "mise.toml"
       - "tasks/docs.toml"
+      - "tasks/test.toml"
+      - "tasks/scripts/check_docs_nav.py"
+      - "tasks/scripts/check_docs_nav_test.py"
       - ".github/workflows/branch-docs.yml"
       - ".github/workflows/release-tag.yml"
 
@@ -47,6 +50,18 @@ jobs:
         working-directory: ./fern
         run: fern check
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          version: "0.10.12"
+          python-version: "3.13"
+
+      - name: Test docs navigation check
+        run: uv run --no-project --with pytest --with pytest-asyncio --with pyyaml pytest tasks/scripts/check_docs_nav_test.py
+
+      - name: Check docs navigation matches file paths
+        run: uv run tasks/scripts/check_docs_nav.py
+
       - name: Generate preview URL
         if: ${{ steps.fern-preview.outputs.enabled == 'true' }}
         id: generate-docs

CONTRIBUTING.md

@@ -487,7 +487,7 @@ field design, and schema-evolution rules.
 
 ## Documentation
 
-If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR and adjust `docs/index.yml` if navigation changes. For explicit navigation entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `docs/index.yml`. Reserve frontmatter `slug` for folder-discovered pages or absolute URL overrides.
+If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR and adjust `docs/index.yml` if navigation changes. For explicit navigation entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `docs/index.yml`. Reserve frontmatter `slug` for folder-discovered pages or absolute URL overrides. Keep every page URL equal to its file path under `docs/`; `mise run docs` checks this with `docs:nav`.
 
 To ensure your doc changes follow NVIDIA documentation style, use the `update-docs-from-commits` skill.
 It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `docs/CONTRIBUTING.mdx`.

architecture/build.md

@@ -584,8 +584,10 @@ See `CI.md` for the contributor workflow, labels, and maintainer merge-queue wor
 Published docs live in `docs/`. Navigation lives in `docs/index.yml`. Fern site
 configuration, components, theme assets, and publish settings live in `fern/`.
 
-Use `mise run docs` for strict validation and `mise run docs:serve` for local
-preview. PR previews are produced by `.github/workflows/branch-docs.yml` when
+Use `mise run docs` for Fern validation and navigation-to-file-path consistency,
+and `mise run docs:serve` for local preview. The docs PR workflow also runs the
+navigation check's unit tests (`mise run test:docs-nav`).
+PR previews are produced by `.github/workflows/branch-docs.yml` when
 Fern credentials are available. Production docs publish from the release tag
 workflow.
 

docs/CONTRIBUTING.mdx

@@ -89,6 +89,8 @@ keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing"
 
 For explicit entries in `docs/index.yml`, keep `page:`. Fern still requires it. If the page defines `sidebar-title`, set `page:` to that value. Otherwise set `page:` to the frontmatter `title`.
 
+Keep every page URL equal to its file path under `docs/`, without `.mdx`. Fern builds URLs from nav labels and slugs, not from file paths, so rename the file when you rename a page, and add a redirect in `fern/docs.yml` for the old URL. When a nav label does not produce the file name, for example `TypeScript`, which Fern turns into `type-script`, set a relative `slug:` on the entry in `docs/index.yml`. `mise run docs` runs `mise run docs:nav`, which fails when a page URL differs from its file path, when a nav label differs from the page's sidebar name, when a page is missing from the navigation, or when a redirect points to a page that does not exist.
+
 ### Page Structure
 
 1. Frontmatter `title` and `description`, plus any relevant page metadata.

docs/how-it-works/gateways/authentication.mdx

@@ -2,6 +2,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 title: "Gateway Authentication"
+sidebar-title: "Authentication"
 description: "Gateway resolution, authentication modes, connection flow, OIDC support, and credential file layout."
 keywords: "Generative AI, Cybersecurity, Gateway, Authentication, mTLS, OIDC, OpenID Connect, Edge Authentication, Reference"
 position: 1

docs/index.yml

@@ -9,14 +9,14 @@ navigation:
 - section: "About NVIDIA OpenShell"
   slug: about
   contents:
-  - page: "Why OpenShell"
+  - page: "Overview"
     path: about/overview.mdx
   - page: "Architecture"
     path: about/architecture.mdx
   - page: "Installation"
     path: about/installation.mdx
   - page: "Run Your First Agent"
-    path: about/run-an-agent.mdx
+    path: about/run-your-first-agent.mdx
   - page: "Support Matrix"
     path: about/support-matrix.mdx
 - section: "How It Works"
@@ -102,14 +102,15 @@ navigation:
   title: "Kubernetes"
 - section: "Tutorials"
   slug: tutorials
+  path: tutorials/index.mdx
   contents:
   - page: "Run Pi with OpenRouter"
     path: tutorials/run-pi-with-openrouter.mdx
     slug: run-pi-with-openrouter
   - page: "First Network Policy"
     path: tutorials/first-network-policy.mdx
   - page: "GitHub Push Access"
-    path: tutorials/github-sandbox.mdx
+    path: tutorials/github-push-access.mdx
   - page: "Microsoft Graph Provider Refresh"
     path: tutorials/microsoft-graph-provider-refresh.mdx
 - section: "SDK Reference"
@@ -123,6 +124,7 @@ navigation:
     path: sdk/python.mdx
   - page: "TypeScript"
     path: sdk/typescript.mdx
+    slug: typescript
   - page: "API Errors"
     path: sdk/api-errors.mdx
   - page: "Protobuf Time Types"

docs/sdk/protobuf-time-types.mdx

@@ -1,5 +1,6 @@
 ---
 title: Protobuf time types
+sidebar-title: "Protobuf Time Types"
 description: Timestamp and duration representation in the OpenShell API
 ---
 

fern/docs.yml

@@ -80,15 +80,28 @@ redirects:
   - source: "/openshell/dev/providers/google-vertex-ai"
     destination: "/openshell/dev/how-it-works/providers/google#vertex-ai"
   - source: "/openshell/latest/about/supported-agents"
-    destination: "/openshell/latest/about/run-an-agent"
+    destination: "/openshell/latest/about/run-your-first-agent"
   - source: "/openshell/dev/about/supported-agents"
-    destination: "/openshell/dev/about/run-an-agent"
+    destination: "/openshell/dev/about/run-your-first-agent"
   - source: "/openshell/latest/get-started/quickstart"
-    destination: "/openshell/latest/about/run-an-agent"
+    destination: "/openshell/latest/about/run-your-first-agent"
   - source: "/openshell/dev/get-started/quickstart"
-    destination: "/openshell/dev/about/run-an-agent"
+    destination: "/openshell/dev/about/run-your-first-agent"
   - source: "/openshell/latest/sandboxes/providers-v2"
     destination: "/openshell/latest/how-it-works/providers/profiles"
+  # Preserve published URLs when page names and slugs change.
+  - source: "/openshell/about/why-open-shell"
+    destination: "/openshell/latest/about/overview"
+  - source: "/openshell/sdk/type-script"
+    destination: "/openshell/latest/sdk/typescript"
+  - source: "/openshell/latest/about/why-open-shell"
+    destination: "/openshell/latest/about/overview"
+  - source: "/openshell/dev/about/why-open-shell"
+    destination: "/openshell/dev/about/overview"
+  - source: "/openshell/latest/sdk/type-script"
+    destination: "/openshell/latest/sdk/typescript"
+  - source: "/openshell/dev/sdk/type-script"
+    destination: "/openshell/dev/sdk/typescript"
   # Paths are relative to the site root; subpath prefix matches instances + custom-domain.
   # Legacy HTML URLs used .../path/to/page/index.html; Fern canonical URLs omit index.html.
   # List explicit /index.html routes before :path*/index.html so empty path segments do not

tasks/docs.toml

@@ -5,7 +5,7 @@
 
 ["docs"]
 description = "Validate Fern documentation"
-depends = ["docs:build:strict"]
+depends = ["docs:build:strict", "docs:nav"]
 
 ["docs:deps"]
 description = "Resolve Fern CLI for docs tasks"
@@ -23,6 +23,10 @@ cd fern
 npx --yes "fern-api@${FERN_VERSION}" check
 """
 
+["docs:nav"]
+description = "Check that docs page URLs match their file paths"
+run = "uv run tasks/scripts/check_docs_nav.py"
+
 ["docs:serve"]
 description = "Serve Fern docs locally"
 depends = ["docs:deps"]