From 87a45c6f9ca5637f6f0c6de29c84ab807b5c2c00 Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 13:59:59 -0700 Subject: [PATCH 1/8] docs(fern): align metadata and preview workflow Move migrated page metadata into Fern frontmatter and update navigation, preview, and publishing guidance so the Fern workflow stays consistent across docs and skills. --- .agents/skills/update-docs/SKILL.md | 61 +++++++------ .github/workflows/branch-docs.yml | 66 ++++++++++++++ .github/workflows/release-tag.yml | 24 +++++ AGENTS.md | 8 +- CONTRIBUTING.md | 28 ++++-- docs/CONTRIBUTING.md | 88 +++++++++++-------- fern/versions/latest.yml | 55 ++---------- fern/versions/latest/pages/CONTRIBUTING.mdx | 77 ++++++++++------ .../latest/pages/about/architecture.mdx | 8 ++ fern/versions/latest/pages/about/overview.mdx | 9 ++ .../latest/pages/about/release-notes.mdx | 7 ++ .../latest/pages/about/supported-agents.mdx | 1 + .../latest/pages/get-started/quickstart.mdx | 7 ++ fern/versions/latest/pages/index.mdx | 9 ++ .../latest/pages/inference/configure.mdx | 8 ++ .../versions/latest/pages/inference/index.mdx | 7 ++ .../pages/observability/accessing-logs.mdx | 7 ++ .../latest/pages/observability/index.mdx | 8 ++ .../latest/pages/observability/logging.mdx | 7 ++ .../pages/observability/ocsf-json-export.mdx | 8 ++ .../latest/pages/reference/default-policy.mdx | 7 ++ .../latest/pages/reference/gateway-auth.mdx | 7 ++ .../latest/pages/reference/policy-schema.mdx | 8 ++ .../latest/pages/resources/license.mdx | 4 + .../pages/sandboxes/community-sandboxes.mdx | 7 ++ .../versions/latest/pages/sandboxes/index.mdx | 10 +++ .../pages/sandboxes/manage-gateways.mdx | 8 ++ .../pages/sandboxes/manage-providers.mdx | 8 ++ .../pages/sandboxes/manage-sandboxes.mdx | 9 ++ .../latest/pages/sandboxes/policies.mdx | 9 ++ .../latest/pages/security/best-practices.mdx | 9 ++ .../pages/tutorials/first-network-policy.mdx | 9 ++ .../latest/pages/tutorials/github-sandbox.mdx | 9 ++ .../versions/latest/pages/tutorials/index.mdx | 6 ++ .../pages/tutorials/inference-ollama.mdx | 9 ++ .../tutorials/local-inference-lmstudio.mdx | 9 ++ 36 files changed, 476 insertions(+), 145 deletions(-) create mode 100644 .github/workflows/branch-docs.yml diff --git a/.agents/skills/update-docs/SKILL.md b/.agents/skills/update-docs/SKILL.md index 5b68a298f..1a44061cd 100644 --- a/.agents/skills/update-docs/SKILL.md +++ b/.agents/skills/update-docs/SKILL.md @@ -10,8 +10,8 @@ Scan recent git history for commits that affect user-facing behavior and draft d ## Prerequisites - You must be in the OpenShell git repository. -- The `docs/` directory must exist with the current doc set. -- Read `docs/CONTRIBUTING.md` before writing any content. It contains the style guide and formatting rules. +- The published docs tree must exist under `fern/versions/latest/pages/`. +- Read `fern/versions/latest/pages/CONTRIBUTING.mdx` before writing any content. It contains the current style guide and formatting rules. ## When to Use @@ -48,16 +48,16 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi | Code area | Likely doc page(s) | |---|---| -| `crates/openshell-cli/` (gateway commands) | `docs/sandboxes/manage-gateways.md` | -| `crates/openshell-cli/` (sandbox commands) | `docs/sandboxes/manage-sandboxes.md` | -| `crates/openshell-cli/` (provider commands) | `docs/sandboxes/manage-providers.md` | -| `crates/openshell-cli/` (new top-level command) | May need a new page or `docs/reference/` entry | -| `crates/openshell-proxy/` or policy code | `docs/sandboxes/policies.md`, `docs/reference/policy-schema.md` | -| `crates/openshell-inference/` | `docs/inference/configure.md` | -| `python/` (SDK changes) | `docs/reference/` or `docs/get-started/quickstart.md` | -| `proto/` (API changes) | `docs/reference/` | -| `deploy/` (Dockerfile, Helm) | `docs/sandboxes/manage-gateways.md`, `docs/about/architecture.md` | -| Community sandbox definitions | `docs/sandboxes/community-sandboxes.md` | +| `crates/openshell-cli/` (gateway commands) | `fern/versions/latest/pages/sandboxes/manage-gateways.mdx` | +| `crates/openshell-cli/` (sandbox commands) | `fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx` | +| `crates/openshell-cli/` (provider commands) | `fern/versions/latest/pages/sandboxes/manage-providers.mdx` | +| `crates/openshell-cli/` (new top-level command) | May need a new page or `fern/versions/latest/pages/reference/` entry | +| Proxy or policy code | `fern/versions/latest/pages/sandboxes/policies.mdx`, `fern/versions/latest/pages/reference/policy-schema.mdx` | +| Inference code | `fern/versions/latest/pages/inference/configure.mdx` | +| `python/` (SDK changes) | `fern/versions/latest/pages/reference/` or `fern/versions/latest/pages/get-started/quickstart.mdx` | +| `proto/` (API changes) | `fern/versions/latest/pages/reference/` | +| `deploy/` (Dockerfile, Helm) | `fern/versions/latest/pages/sandboxes/manage-gateways.mdx`, `fern/versions/latest/pages/about/architecture.mdx` | +| Community sandbox definitions | `fern/versions/latest/pages/sandboxes/community-sandboxes.mdx` | If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page. @@ -88,16 +88,21 @@ Identify where the new content should go. Follow the page's existing structure. ## Step 5: Draft the Update -Write the doc update following the rules in `docs/CONTRIBUTING.md`. Key reminders: +Write the doc update following the rules in `fern/versions/latest/pages/CONTRIBUTING.mdx`. Key reminders: - **Active voice, present tense, second person.** - **No unnecessary bold.** Reserve bold for UI labels and parameter names. - **No em dashes** unless used sparingly. Prefer commas or separate sentences. - **Start sections with an introductory sentence** that orients the reader. - **No superlatives.** Say what the feature does, not how great it is. -- **Code examples use `console` language** with `$` prompt prefix. +- **Code examples use `shell` language** for copyable commands, with no `$` prompt prefix. +- **Use `text` fences** for transcripts, logs, or shell sessions that should not be copied verbatim. - **Include the SPDX header** if creating a new page. -- **Match existing frontmatter format** if creating a new page. +- **Match existing Fern frontmatter format** if creating a new page, including `sidebar-title`, `slug`, `keywords`, `tags`, and `position` when they are relevant. +- **Use `sidebar-title` for short nav labels** and `slug` for stable page URLs instead of keeping that metadata only in `fern/versions/latest.yml`. +- **Keep explicit `page:` entries in `fern/versions/latest.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 `keywords` as a comma-separated string**. When migrating a page from `docs/`, combine the legacy `topics` and `tags` into `keywords` and preserve the legacy `tags` array when it is still useful. +- **Do not add a duplicate H1**. Fern renders the page title from frontmatter. - **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia. - **Always capitalize OpenShell correctly.** Wrong: openshell, Openshell, openShell. - **Do not number section titles.** Wrong: "Section 1: Deploy a Gateway" or "Step 3: Verify." Use plain descriptive titles. @@ -112,8 +117,8 @@ When updating an existing page: When creating a new page: -- Follow the frontmatter template from `docs/CONTRIBUTING.md`. -- Add the page to the appropriate `toctree` in `docs/index.md`. +- Follow the frontmatter template from `fern/versions/latest/pages/CONTRIBUTING.mdx`. +- Add the page to the appropriate section in `fern/versions/latest.yml`. ## Step 6: Present the Results @@ -123,8 +128,8 @@ After drafting all updates, present a summary to the user: ## Doc Updates from Commits ### Updated pages -- `docs/sandboxes/manage-gateways.md`: Added `--gpu` flag documentation (from commit abc1234). -- `docs/reference/policy-schema.md`: Updated network policy schema for new `tls_inspect` field (from commit def5678). +- `fern/versions/latest/pages/sandboxes/manage-gateways.mdx`: Added `--gpu` flag documentation (from commit abc1234). +- `fern/versions/latest/pages/reference/policy-schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678). ### New pages needed - None (or list any new pages created). @@ -136,23 +141,29 @@ After drafting all updates, present a summary to the user: ## Step 7: Build and Verify -After making changes, build the docs locally: +After making changes, validate the Fern docs locally: ```bash -mise run docs +fern check +``` + +If a human needs to inspect rendering while iterating, they can also run: + +```bash +fern docs dev ``` Check for: -- Build warnings or errors. +- Validation warnings or errors. - Broken cross-references. -- Correct rendering of new content. +- Correct rendering of new content in the PR preview when available. ## Tips - When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior. - Group related commits that touch the same doc page into a single update rather than making multiple small edits. -- If a commit is a breaking change, add a note at the top of the relevant section using a `:::{warning}` admonition. +- If a commit is a breaking change, add a note at the top of the relevant section using a Fern `` callout. - PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories. ## Example Usage @@ -165,4 +176,4 @@ User says: "Catch up the docs for everything merged since v0.2.0." 4. Read the commit diffs and current doc pages. 5. Draft updates following the style guide. 6. Present the summary. -7. Build with `mise run docs` to verify. +7. Run `fern check` to verify. diff --git a/.github/workflows/branch-docs.yml b/.github/workflows/branch-docs.yml new file mode 100644 index 000000000..f824f2e8c --- /dev/null +++ b/.github/workflows/branch-docs.yml @@ -0,0 +1,66 @@ +name: Branch docs preview + +on: + pull_request: + paths: + - "fern/**" + - ".github/workflows/branch-docs.yml" + +permissions: + contents: read + pull-requests: write + +jobs: + preview: + if: ${{ secrets.FERN_TOKEN != '' }} + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: "20" + + - name: Install Fern CLI + run: npm install -g fern-api + + - name: Generate preview URL + id: generate-docs + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + PREVIEW_ID: pr-${{ github.event.pull_request.number }} + working-directory: ./fern + run: | + OUTPUT=$(fern generate --docs --preview --id "$PREVIEW_ID" 2>&1) + echo "$OUTPUT" + URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') + if [ -z "$URL" ]; then + echo "::error::Failed to generate preview URL. See fern output above." + exit 1 + fi + echo "preview_url=$URL" >> "$GITHUB_OUTPUT" + + - name: Post or update PR comment + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number }} + PREVIEW_URL: ${{ steps.generate-docs.outputs.preview_url }} + run: | + BODY=":herb: **Preview your docs:** <${PREVIEW_URL}>" + MARKER="" + BODY="${BODY} + + ${MARKER}" + + COMMENT_ID=$(gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \ + --jq ".[] | select(.body | contains(\"${MARKER}\")) | .id" | head -1) + + if [ -n "$COMMENT_ID" ]; then + gh api "repos/${{ github.repository }}/issues/comments/${COMMENT_ID}" \ + -X PATCH -f body="$BODY" + else + gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \ + -f body="$BODY" + fi diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml index 44a0b6fe0..12e5bde5c 100644 --- a/.github/workflows/release-tag.yml +++ b/.github/workflows/release-tag.yml @@ -383,6 +383,30 @@ jobs: release/*.whl release/openshell-checksums-sha256.txt + publish-fern-docs: + name: Publish Fern Docs + needs: [release] + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ inputs.tag || github.ref }} + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: "20" + + - name: Install Fern CLI + run: npm install -g fern-api + + - name: Publish Fern docs + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + working-directory: ./fern + run: fern generate --docs + trigger-wheel-publish: name: Trigger Wheel Publish needs: [compute-versions, build-python-wheels, release] diff --git a/AGENTS.md b/AGENTS.md index 979965941..b2a986756 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,8 @@ These pipelines connect skills into end-to-end workflows. Individual skill files | `python/openshell/` | Python SDK | Python bindings and CLI packaging | | `proto/` | Protobuf definitions | gRPC service contracts | | `deploy/` | Docker, Helm, K8s | Dockerfiles, Helm chart, manifests | +| `fern/` | Published docs | Fern site config, navigation, components, and MDX pages | +| `docs/` | Legacy docs source | Sphinx/MyST source retained for migration, comparison, and legacy build tasks | | `.agents/skills/` | Agent skills | Workflow automation for development | | `.agents/agents/` | Agent personas | Sub-agent definitions (e.g., reviewer, doc writer) | | `architecture/` | Architecture docs | Design decisions and component documentation | @@ -184,8 +186,10 @@ ocsf_emit!(event); ## Documentation - When making changes, update the relevant documentation in the `architecture/` directory. -- When changes affect user-facing behavior, also update the relevant pages under `docs/`. -- Follow the style guide in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md): active voice, no unnecessary bold, no em dash overuse, no filler introductions. +- When changes affect user-facing behavior, update the relevant published docs pages under `fern/versions/latest/pages/` and navigation in `fern/versions/latest.yml`. +- `docs/` is retained for legacy Sphinx build tasks and migration/reference work. Do not update it unless the user explicitly asks. +- Follow the docs style guide in [fern/versions/latest/pages/CONTRIBUTING.mdx](fern/versions/latest/pages/CONTRIBUTING.mdx): active voice, minimal formatting, no filler introductions, `shell` fences for copyable commands, and no duplicate body H1. +- Fern PR previews run through `.github/workflows/branch-docs.yml`, and production publish runs through the `publish-fern-docs` job in `.github/workflows/release-tag.yml`. - Use the `update-docs` skill to scan recent commits and draft doc updates. ## Security diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ebf71df2..3a3d142c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -173,7 +173,7 @@ These are the primary `mise` tasks for day-to-day development: | `mise run test` | Default test suite | | `mise run e2e` | Default end-to-end test lane | | `mise run ci` | Full local CI checks (lint, compile/type checks, tests) | -| `mise run docs` | Build and serve documentation locally | +| `mise run docs` | Build legacy Sphinx docs locally | | `mise run clean` | Clean build artifacts | ## Project Structure @@ -185,9 +185,10 @@ These are the primary `mise` tasks for day-to-day development: | `proto/` | Protocol buffer definitions | | `tasks/` | `mise` task definitions and build scripts | | `deploy/` | Dockerfiles, Helm chart, Kubernetes manifests | +| `fern/` | Published Fern docs site and MDX pages | +| `docs/` | Legacy Sphinx/MyST docs retained during transition | | `architecture/` | Architecture docs and plans | | `rfc/` | Request for Comments proposals | -| `docs/` | User-facing documentation (Sphinx/MyST) | | `.agents/` | Agent skills and persona definitions | ## RFCs @@ -196,19 +197,30 @@ For cross-cutting architectural decisions, API contract changes, or process prop ## 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. +If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `fern/versions/latest/pages/` in the same PR and adjust `fern/versions/latest.yml` if navigation changes. For explicit page entries, keep `page:` and align it with `sidebar-title` when present, otherwise with the page frontmatter `title`. To ensure your doc changes follow NVIDIA documentation style, use the `update-docs` skill. -It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `docs/CONTRIBUTING.md`. +It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `fern/versions/latest/pages/CONTRIBUTING.mdx`. -To build and preview docs locally: +To preview Fern docs locally: ```bash -mise run docs # to build the docs locally -mise run docs:serve # to serve locally and automatically rebuild on changes +fern docs dev ``` -See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for more details. +To run non-interactive validation: + +```bash +fern check +``` + +PRs that touch `fern/**` also get a preview from `.github/workflows/branch-docs.yml` when `FERN_TOKEN` is available to the workflow. + +Fern docs publishing is handled by the `publish-fern-docs` job in `.github/workflows/release-tag.yml` when a release tag is created. + +`docs/` and `mise run docs` / `mise run docs:serve` are still kept for the legacy Sphinx build during the transition, but they are no longer the primary published docs workflow. + +See [fern/versions/latest/pages/CONTRIBUTING.mdx](fern/versions/latest/pages/CONTRIBUTING.mdx) for the current docs authoring guide. ## Pull Requests diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 11167f48a..c22242fde 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,6 +2,8 @@ This guide covers how to write, edit, and review documentation for NVIDIA OpenShell. If you change code that affects user-facing behavior, update the relevant docs in the same PR. +The published docs now live in `fern/versions/latest/pages/`, and navigation is defined in `fern/versions/latest.yml`. The `docs/` tree is kept for legacy Sphinx builds and migration/reference work. Do not update `docs/` unless you are explicitly asked to do so. + ## Use the Agent Skills If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes skills that automate doc work. Use them before writing from scratch. @@ -25,15 +27,29 @@ Update documentation when your change: ## Building Docs Locally -Verify the docs are built correctly by building them and checking the output. +Preview Fern docs first, then use the legacy Sphinx build only if you explicitly need it for comparison. + +To preview Fern docs locally, run: + +```bash +fern docs dev +``` + +To run non-interactive validation, run: -To build the docs, run: +```bash +fern check +``` + +PRs that touch `fern/**` also get a preview from `.github/workflows/branch-docs.yml` when `FERN_TOKEN` is available to the workflow. + +If you need the legacy Sphinx build during the transition, use: ```bash mise run docs ``` -To serve the docs locally and automatically rebuild on changes, run: +To serve the legacy docs locally with automatic rebuilds, run: ```bash mise run docs:serve @@ -43,45 +59,45 @@ mise run docs:serve ### Format -- Docs use [MyST Markdown](https://myst-parser.readthedocs.io/), a Sphinx-compatible superset of CommonMark. -- Every page starts with YAML frontmatter (title, description, topics, tags, content type). +- Published docs use Fern MDX under `fern/versions/latest/pages/`. +- Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `slug`, `keywords`, `tags`, and `position` when the page needs them. - Include the SPDX license header after frontmatter: ``` - + {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} ``` +- Do not repeat the page title as a body H1. Fern renders the title from frontmatter. ### Frontmatter Template ```yaml --- -title: - page: Page Title - nav: Short Nav Title -description: One-sentence summary of the page. -topics: -- Generative AI -- Cybersecurity +title: "Page Title" +sidebar-title: "Short Nav Title" +slug: "section/page-slug" +description: "One-sentence summary of the page." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing" tags: -- Relevant -- Tags -content: - type: concept | how_to | get_started | tutorial | reference - difficulty: technical_beginner | technical_intermediate | technical_advanced - audience: - - engineer - - data_scientist + - AI Agents + - Sandboxing --- ``` +- `title` sets the page heading and browser title. +- `sidebar-title` sets the shorter label in the sidebar when the full page title is too long. +- `slug` sets the full path from the docs root. Use it to preserve stable URLs when you move slug metadata out of `fern/versions/latest.yml`. +- `keywords` is a comma-separated string for page metadata. When migrating from `docs/`, combine the legacy `topics` and `tags` into `keywords`. +- `tags` is an optional array for preserving legacy doc taxonomy or changelog tags. Fern does not treat `tags` as SEO metadata on ordinary pages, so still populate `keywords`. +- `position` controls ordering for pages discovered through a `folder:` entry. + +For explicit entries in `fern/versions/latest.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`. + ### Page Structure -1. H1 heading matching the `title.page` value. +1. Frontmatter `title` and `description`, plus any relevant page metadata. 2. A one- or two-sentence introduction stating what the page covers. 3. Sections organized by task or concept, using H2 and H3. Start each section with an introductory sentence that orients the reader. -4. A "Next Steps" section at the bottom linking to related pages. +4. A "Next Steps" section at the bottom linking to related pages when it helps the reader continue. ## Style Guide @@ -111,13 +127,14 @@ These patterns are common in LLM-generated text and erode trust with technical r - End every sentence with a period. - Use `code` formatting for CLI commands, file paths, flags, parameter names, and values. -- Use code blocks with the `console` language for CLI examples. Prefix commands with `$`: - ```console - $ openshell gateway start +- Use `shell` code blocks for copyable CLI examples. Do not prefix commands with `$`: + ```shell + openshell gateway start ``` +- Use `text` code blocks for transcripts, log output, and examples that should not be copied verbatim. - Use tables for structured comparisons. Keep tables simple (no nested formatting). -- Use MyST admonitions (`:::{tip}`, `:::{note}`, `:::{warning}`) for callouts, not bold text. -- Avoid nested admonitions. +- Use Fern components like ``, ``, and `` for callouts, not bold text. +- Use Fern components like `` and `` when the page clearly benefits from them. - Do not number section titles. Write "Deploy a Gateway" not "Section 1: Deploy a Gateway" or "Step 3: Verify." - Do not use colons in titles. Write "Deploy and Manage Gateways" not "Gateways: Deploy and Manage." - Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses. @@ -141,9 +158,10 @@ Use these consistently: 1. Create a branch following the project convention: `docs/-/`. 2. Make your changes. -3. Build locally with `mise run docs` and verify the output. -4. Run `mise run pre-commit` to catch formatting issues. -5. Open a PR with `docs:` as the conventional commit type. +3. Preview locally with `fern docs dev`. +4. Run `fern check`. +5. Run `mise run pre-commit` to catch formatting issues. +6. Open a PR with `docs:` as the conventional commit type. ``` docs: update gateway deployment instructions @@ -163,4 +181,4 @@ When reviewing documentation: - Watch for LLM-generated patterns (excessive bold, em dashes, filler). - Verify code examples are accurate and runnable. - Confirm cross-references and links are not broken. -- Build locally to check rendering. +- Preview the page with `fern docs dev`, run `fern check`, and, if available, review the PR preview from `branch-docs.yml`. diff --git a/fern/versions/latest.yml b/fern/versions/latest.yml index 1b62c64b4..9d82c81a2 100644 --- a/fern/versions/latest.yml +++ b/fern/versions/latest.yml @@ -1,102 +1,63 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 navigation: - - section: "Getting Started" - slug: get-started + - section: "Documentation" contents: - page: "Home" path: ./latest/pages/index.mdx - - page: "Quickstart" - slug: quickstart - path: ./latest/pages/get-started/quickstart.mdx - section: "About NVIDIA OpenShell" slug: about contents: - page: "Overview" - slug: overview path: ./latest/pages/about/overview.mdx - page: "How It Works" - slug: architecture path: ./latest/pages/about/architecture.mdx - page: "Supported Agents" - slug: supported-agents path: ./latest/pages/about/supported-agents.mdx - page: "Release Notes" - slug: release-notes path: ./latest/pages/about/release-notes.mdx - - section: "Tutorials" - slug: tutorials + - section: "Get Started" contents: - - page: "Tutorials" - slug: index - hidden: true - path: ./latest/pages/tutorials/index.mdx - - page: "First Network Policy" - slug: first-network-policy - path: ./latest/pages/tutorials/first-network-policy.mdx - - page: "GitHub Push Access" - slug: github-sandbox - path: ./latest/pages/tutorials/github-sandbox.mdx - - page: "Inference with Ollama" - slug: inference-ollama - path: ./latest/pages/tutorials/inference-ollama.mdx - - page: "Local Inference with LM Studio" - slug: local-inference-lmstudio - path: ./latest/pages/tutorials/local-inference-lmstudio.mdx + - page: "Quickstart" + path: ./latest/pages/get-started/quickstart.mdx + - folder: ./latest/pages/tutorials + collapsed: open-by-default - section: "Gateways and Sandboxes" slug: sandboxes contents: - page: "About Gateways and Sandboxes" - slug: about path: ./latest/pages/sandboxes/index.mdx - page: "Sandboxes" - slug: manage-sandboxes path: ./latest/pages/sandboxes/manage-sandboxes.mdx - page: "Gateways" - slug: manage-gateways path: ./latest/pages/sandboxes/manage-gateways.mdx - page: "Providers" - slug: manage-providers path: ./latest/pages/sandboxes/manage-providers.mdx - page: "Policies" - slug: policies path: ./latest/pages/sandboxes/policies.mdx - page: "Community Sandboxes" - slug: community-sandboxes path: ./latest/pages/sandboxes/community-sandboxes.mdx - section: "Inference Routing" slug: inference contents: - page: "About Inference Routing" - slug: about path: ./latest/pages/inference/index.mdx - page: "Configure Inference Routing" - slug: configure path: ./latest/pages/inference/configure.mdx - section: "Observability" slug: observability contents: - page: "Overview" - slug: index path: ./latest/pages/observability/index.mdx - page: "Logging" - slug: logging path: ./latest/pages/observability/logging.mdx - page: "Accessing Logs" - slug: accessing-logs path: ./latest/pages/observability/accessing-logs.mdx - page: "OCSF JSON Export" - slug: ocsf-json-export path: ./latest/pages/observability/ocsf-json-export.mdx - folder: ./latest/pages/reference title: "Reference" - title-source: frontmatter - - section: "Security" - slug: security - contents: - - page: "Security Best Practices" - slug: best-practices - path: ./latest/pages/security/best-practices.mdx + - folder: ./latest/pages/security + title: "Security" - folder: ./latest/pages/resources title: "Resources" - title-source: frontmatter diff --git a/fern/versions/latest/pages/CONTRIBUTING.mdx b/fern/versions/latest/pages/CONTRIBUTING.mdx index cd4f2a8f1..fa969002b 100644 --- a/fern/versions/latest/pages/CONTRIBUTING.mdx +++ b/fern/versions/latest/pages/CONTRIBUTING.mdx @@ -4,6 +4,8 @@ description: "" --- This guide covers how to write, edit, and review documentation for NVIDIA OpenShell. If you change code that affects user-facing behavior, update the relevant docs in the same PR. +The published docs live in `fern/versions/latest/pages/`, and navigation is defined in `fern/versions/latest.yml`. The `docs/` tree is kept for legacy Sphinx builds and migration/reference work. Do not update `docs/` unless you are explicitly asked to do so. + ## Use the Agent Skills If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes skills that automate doc work. Use them before writing from scratch. @@ -27,15 +29,29 @@ Update documentation when your change: ## Building Docs Locally -Verify the docs are built correctly by building them and checking the output. +Preview Fern docs first, then use the legacy Sphinx build only if you explicitly need it for comparison. + +To preview Fern docs locally, run: + +```shell +fern docs dev +``` + +To run non-interactive validation, run: -To build the docs, run: +```shell +fern check +``` + +PRs that touch `fern/**` also get a preview from `.github/workflows/branch-docs.yml` when `FERN_TOKEN` is available to the workflow. + +If you need the legacy Sphinx build during the transition, use: ```shell mise run docs ``` -To serve the docs locally and automatically rebuild on changes, run: +To serve the legacy docs locally and automatically rebuild on changes, run: ```shell mise run docs:serve @@ -45,42 +61,45 @@ mise run docs:serve ### Format -- Docs use [MyST Markdown](https://myst-parser.readthedocs.io/), a Sphinx-compatible superset of CommonMark. -- Every page starts with YAML frontmatter (title, description, topics, tags, content type). +- Published docs use Fern MDX under `fern/versions/latest/pages/`. +- Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `slug`, `keywords`, `tags`, and `position` when the page needs them. - Include the SPDX license header after frontmatter: ``` {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */} ``` +- Do not repeat the page title as a body H1. Fern renders the title from frontmatter. ### Frontmatter Template ```yaml --- -title: "page: Page Title" - nav: Short Nav Title -description: One-sentence summary of the page. -topics: -- Generative AI -- Cybersecurity +title: "Page Title" +sidebar-title: "Short Nav Title" +slug: "section/page-slug" +description: "One-sentence summary of the page." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing" tags: -- Relevant -- Tags -content: - type: concept | how_to | get_started | tutorial | reference - difficulty: technical_beginner | technical_intermediate | technical_advanced - audience: - - engineer - - data_scientist + - AI Agents + - Sandboxing --- ``` +- `title` sets the page heading and browser title. +- `sidebar-title` sets the shorter label in the sidebar when the full page title is too long. +- `slug` sets the full path from the docs root. Use it to preserve stable URLs when you move slug metadata out of `fern/versions/latest.yml`. +- `keywords` is a comma-separated string for page metadata. When migrating from `docs/`, combine the legacy `topics` and `tags` into `keywords`. +- `tags` is an optional array for preserving legacy doc taxonomy or changelog tags. Fern does not treat `tags` as SEO metadata on ordinary pages, so still populate `keywords`. +- `position` controls ordering for pages discovered through a `folder:` entry. + +For explicit entries in `fern/versions/latest.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`. + ### Page Structure -1. H1 heading matching the `title.page` value. +1. Frontmatter `title` and `description`, plus any relevant page metadata. 2. A one- or two-sentence introduction stating what the page covers. 3. Sections organized by task or concept, using H2 and H3. Start each section with an introductory sentence that orients the reader. -4. A "Next Steps" section at the bottom linking to related pages. +4. A "Next Steps" section at the bottom linking to related pages when it helps the reader continue. ## Style Guide @@ -110,13 +129,14 @@ These patterns are common in LLM-generated text and erode trust with technical r - End every sentence with a period. - Use `code` formatting for CLI commands, file paths, flags, parameter names, and values. -- Use code blocks with the `console` language for CLI examples. Prefix commands with `$`: +- Use `shell` code blocks for copyable CLI examples. Do not prefix commands with `$`: ```shell openshell gateway start ``` +- Use `text` code blocks for transcripts, log output, and examples that should not be copied verbatim. - Use tables for structured comparisons. Keep tables simple (no nested formatting). -- Use MyST admonitions (`:::{tip}`, `:::{note}`, `:::{warning}`) for callouts, not bold text. -- Avoid nested admonitions. +- Use Fern components like ``, ``, and `` for callouts, not bold text. +- Use Fern components like `` and `` when the page clearly benefits from them. - Do not number section titles. Write "Deploy a Gateway" not "Section 1: Deploy a Gateway" or "Step 3: Verify." - Do not use colons in titles. Write "Deploy and Manage Gateways" not "Gateways: Deploy and Manage." - Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses. @@ -140,9 +160,10 @@ Use these consistently: 1. Create a branch following the project convention: `docs/-/`. 2. Make your changes. -3. Build locally with `mise run docs` and verify the output. -4. Run `mise run pre-commit` to catch formatting issues. -5. Open a PR with `docs:` as the conventional commit type. +3. Preview locally with `fern docs dev`. +4. Run `fern check`. +5. Run `mise run pre-commit` to catch formatting issues. +6. Open a PR with `docs:` as the conventional commit type. ``` docs: update gateway deployment instructions @@ -162,4 +183,4 @@ When reviewing documentation: - Watch for LLM-generated patterns (excessive bold, em dashes, filler). - Verify code examples are accurate and runnable. - Confirm cross-references and links are not broken. -- Build locally to check rendering. +- Preview the page with `fern docs dev`, run `fern check`, and, if available, review the PR preview from `branch-docs.yml`. diff --git a/fern/versions/latest/pages/about/architecture.mdx b/fern/versions/latest/pages/about/architecture.mdx index 8f2c7bb39..17f608a05 100644 --- a/fern/versions/latest/pages/about/architecture.mdx +++ b/fern/versions/latest/pages/about/architecture.mdx @@ -1,6 +1,14 @@ --- title: "How OpenShell Works" +sidebar-title: "How It Works" +slug: "about/architecture" description: "OpenShell architecture overview covering the gateway, sandbox, policy engine, and privacy router." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Architecture" +tags: + - AI Agents + - Sandboxing + - Security + - Architecture position: 2 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/about/overview.mdx b/fern/versions/latest/pages/about/overview.mdx index c8a668d7f..83c2818ab 100644 --- a/fern/versions/latest/pages/about/overview.mdx +++ b/fern/versions/latest/pages/about/overview.mdx @@ -1,6 +1,15 @@ --- title: "Overview of NVIDIA OpenShell" +sidebar-title: "Overview" +slug: "about/overview" description: "OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Privacy, Inference Routing" +tags: + - AI Agents + - Sandboxing + - Security + - Privacy + - Inference Routing position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/about/release-notes.mdx b/fern/versions/latest/pages/about/release-notes.mdx index 516336201..b4d8adb87 100644 --- a/fern/versions/latest/pages/about/release-notes.mdx +++ b/fern/versions/latest/pages/about/release-notes.mdx @@ -1,6 +1,13 @@ --- title: "NVIDIA OpenShell Release Notes" +sidebar-title: "Release Notes" +slug: "about/release-notes" description: "Track the latest changes and improvements to NVIDIA OpenShell." +keywords: "Generative AI, Cybersecurity, Release Notes, Changelog, AI Agents" +tags: + - Release Notes + - Changelog + - AI Agents position: 4 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/about/supported-agents.mdx b/fern/versions/latest/pages/about/supported-agents.mdx index 0aa06e3be..190496cc0 100644 --- a/fern/versions/latest/pages/about/supported-agents.mdx +++ b/fern/versions/latest/pages/about/supported-agents.mdx @@ -1,5 +1,6 @@ --- title: "Supported Agents" +slug: "about/supported-agents" description: "" position: 3 --- diff --git a/fern/versions/latest/pages/get-started/quickstart.mdx b/fern/versions/latest/pages/get-started/quickstart.mdx index c53f1ddf0..9adc91500 100644 --- a/fern/versions/latest/pages/get-started/quickstart.mdx +++ b/fern/versions/latest/pages/get-started/quickstart.mdx @@ -1,6 +1,13 @@ --- title: "Quickstart" +slug: "get-started/quickstart" description: "Install the OpenShell CLI and create your first sandboxed AI agent in two commands." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Quickstart" +tags: + - AI Agents + - Sandboxing + - Installation + - Quickstart position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/index.mdx b/fern/versions/latest/pages/index.mdx index 2ce01eb37..ca0e4fb65 100644 --- a/fern/versions/latest/pages/index.mdx +++ b/fern/versions/latest/pages/index.mdx @@ -1,6 +1,15 @@ --- title: "NVIDIA OpenShell Developer Guide" +sidebar-title: "Home" +slug: "get-started" description: "OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Privacy, Inference Routing" +tags: + - AI Agents + - Sandboxing + - Security + - Privacy + - Inference Routing position: 1 --- diff --git a/fern/versions/latest/pages/inference/configure.mdx b/fern/versions/latest/pages/inference/configure.mdx index 769ff3a21..1815cb095 100644 --- a/fern/versions/latest/pages/inference/configure.mdx +++ b/fern/versions/latest/pages/inference/configure.mdx @@ -1,6 +1,14 @@ --- title: "Configure Inference Routing" +slug: "inference/configure" description: "Set up the managed local inference endpoint with provider credentials and model configuration." +keywords: "Generative AI, Cybersecurity, Inference Routing, Configuration, Privacy, LLM, Provider" +tags: + - Inference Routing + - Configuration + - Privacy + - LLM + - Provider position: 2 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/inference/index.mdx b/fern/versions/latest/pages/inference/index.mdx index f1e12ded8..f4fcce7a5 100644 --- a/fern/versions/latest/pages/inference/index.mdx +++ b/fern/versions/latest/pages/inference/index.mdx @@ -1,6 +1,13 @@ --- title: "About Inference Routing" +slug: "inference/index" description: "Understand how OpenShell routes inference traffic through external endpoints and the local privacy router." +keywords: "Generative AI, Cybersecurity, Inference Routing, Privacy, AI Agents, LLM" +tags: + - Inference Routing + - Privacy + - AI Agents + - LLM position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/observability/accessing-logs.mdx b/fern/versions/latest/pages/observability/accessing-logs.mdx index c0a46ecef..9dbd93283 100644 --- a/fern/versions/latest/pages/observability/accessing-logs.mdx +++ b/fern/versions/latest/pages/observability/accessing-logs.mdx @@ -1,6 +1,13 @@ --- title: "Accessing Logs" +slug: "observability/accessing-logs" description: "How to view sandbox logs through the CLI, TUI, and directly on the sandbox filesystem." +keywords: "Generative AI, Cybersecurity, Logging, CLI, TUI, Observability" +tags: + - Logging + - CLI + - TUI + - Observability --- OpenShell provides three ways to access sandbox logs: the CLI, the TUI, and direct filesystem access inside the sandbox. diff --git a/fern/versions/latest/pages/observability/index.mdx b/fern/versions/latest/pages/observability/index.mdx index 3af778a21..52ac6a912 100644 --- a/fern/versions/latest/pages/observability/index.mdx +++ b/fern/versions/latest/pages/observability/index.mdx @@ -1,6 +1,14 @@ --- title: "Observability" +sidebar-title: "Overview" +slug: "observability/index" description: "Understand how OpenShell logs sandbox activity, how to access logs, and how to export structured OCSF records." +keywords: "Generative AI, Cybersecurity, Logging, OCSF, Observability, Monitoring" +tags: + - Logging + - OCSF + - Observability + - Monitoring --- OpenShell provides structured logging for every sandbox. Every network connection, process lifecycle event, filesystem policy decision, and configuration change is recorded so you can understand exactly what happened inside a sandbox. diff --git a/fern/versions/latest/pages/observability/logging.mdx b/fern/versions/latest/pages/observability/logging.mdx index 28c393555..6783f29ed 100644 --- a/fern/versions/latest/pages/observability/logging.mdx +++ b/fern/versions/latest/pages/observability/logging.mdx @@ -1,6 +1,13 @@ --- title: "Sandbox Logging" +sidebar-title: "Logging" +slug: "observability/logging" description: "How OpenShell logs sandbox activity using standard tracing and OCSF structured events." +keywords: "Generative AI, Cybersecurity, Logging, OCSF, Observability" +tags: + - Logging + - OCSF + - Observability --- Every OpenShell sandbox produces a log that records network connections, process lifecycle events, filesystem policy decisions, and configuration changes. The log uses two formats depending on the type of event. diff --git a/fern/versions/latest/pages/observability/ocsf-json-export.mdx b/fern/versions/latest/pages/observability/ocsf-json-export.mdx index a4cec7f3d..caad70e07 100644 --- a/fern/versions/latest/pages/observability/ocsf-json-export.mdx +++ b/fern/versions/latest/pages/observability/ocsf-json-export.mdx @@ -1,6 +1,14 @@ --- title: "OCSF JSON Export" +slug: "observability/ocsf-json-export" description: "How to enable full OCSF JSON logging for SIEM integration, compliance, and structured analysis." +keywords: "Generative AI, Cybersecurity, OCSF, JSON, SIEM, Compliance, Observability" +tags: + - OCSF + - JSON + - SIEM + - Compliance + - Observability --- The [shorthand log format](/observability/logging) is optimized for humans and agents reading logs in real time. For machine consumption, compliance archival, or SIEM integration, you can enable full OCSF JSON export. This writes every OCSF event as a complete JSON record in JSONL format, one JSON object per line. diff --git a/fern/versions/latest/pages/reference/default-policy.mdx b/fern/versions/latest/pages/reference/default-policy.mdx index 6d23946a1..d995b9b01 100644 --- a/fern/versions/latest/pages/reference/default-policy.mdx +++ b/fern/versions/latest/pages/reference/default-policy.mdx @@ -1,6 +1,13 @@ --- title: "Default Policy Reference" +sidebar-title: "Default Policy" description: "Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Policy" +tags: + - AI Agents + - Sandboxing + - Security + - Policy position: 2 --- The default policy is the policy applied when you create an OpenShell sandbox without `--policy`. It is baked into the community base image ([`ghcr.io/nvidia/openshell-community/sandboxes/base`](https://github.com/nvidia/openshell-community)) and defined in the community repo's `dev-sandbox-policy.yaml`. diff --git a/fern/versions/latest/pages/reference/gateway-auth.mdx b/fern/versions/latest/pages/reference/gateway-auth.mdx index 65422e9f4..85d72b552 100644 --- a/fern/versions/latest/pages/reference/gateway-auth.mdx +++ b/fern/versions/latest/pages/reference/gateway-auth.mdx @@ -1,6 +1,13 @@ --- title: "Gateway Authentication" description: "Gateway resolution, authentication modes, connection flow, and credential file layout." +keywords: "Generative AI, Cybersecurity, Gateway, Authentication, mTLS, Edge Authentication, Reference" +tags: + - Gateway + - Authentication + - mTLS + - Edge Authentication + - Reference position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/reference/policy-schema.mdx b/fern/versions/latest/pages/reference/policy-schema.mdx index ce06984fe..e958b99f9 100644 --- a/fern/versions/latest/pages/reference/policy-schema.mdx +++ b/fern/versions/latest/pages/reference/policy-schema.mdx @@ -1,6 +1,14 @@ --- title: "Policy Schema Reference" +sidebar-title: "Policy Schema" description: "Complete field reference for the sandbox policy YAML including static and dynamic sections." +keywords: "Generative AI, Cybersecurity, Policy, Schema, YAML, Reference, Security" +tags: + - Policy + - Schema + - YAML + - Reference + - Security position: 3 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/resources/license.mdx b/fern/versions/latest/pages/resources/license.mdx index ab3ca66cb..5db1228aa 100644 --- a/fern/versions/latest/pages/resources/license.mdx +++ b/fern/versions/latest/pages/resources/license.mdx @@ -1,6 +1,10 @@ --- title: "License" description: "NVIDIA OpenShell is licensed under the Apache License, Version 2.0." +keywords: "Legal, License, Apache 2.0" +tags: + - License + - Apache 2.0 position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx b/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx index e743082fa..e3114469f 100644 --- a/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx +++ b/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx @@ -1,6 +1,13 @@ --- title: "Community Sandboxes" +slug: "sandboxes/community-sandboxes" description: "Use pre-built sandboxes from the OpenShell Community catalog or contribute your own." +keywords: "Generative AI, Cybersecurity, Community, Sandbox, Container Image, Open Source" +tags: + - Community + - Sandbox + - Container Image + - Open Source position: 6 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/sandboxes/index.mdx b/fern/versions/latest/pages/sandboxes/index.mdx index a2b9dc102..583be0184 100644 --- a/fern/versions/latest/pages/sandboxes/index.mdx +++ b/fern/versions/latest/pages/sandboxes/index.mdx @@ -1,6 +1,16 @@ --- title: "About Gateways and Sandboxes" +sidebar-title: "Gateways and Sandboxes" +slug: "sandboxes/index" description: "Understand gateways, gateway types, sandbox lifecycle, supported agents, built-in default policy, and network access rules in OpenShell." +keywords: "Generative AI, Cybersecurity, Gateway, Sandboxing, AI Agents, Security, Policy, Isolation" +tags: + - Gateway + - Sandboxing + - AI Agents + - Security + - Policy + - Isolation position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/sandboxes/manage-gateways.mdx b/fern/versions/latest/pages/sandboxes/manage-gateways.mdx index 18fb0c928..b8700478a 100644 --- a/fern/versions/latest/pages/sandboxes/manage-gateways.mdx +++ b/fern/versions/latest/pages/sandboxes/manage-gateways.mdx @@ -1,6 +1,14 @@ --- title: "Deploy and Manage Gateways" +sidebar-title: "Gateways" +slug: "sandboxes/manage-gateways" description: "Deploy local and remote gateways, register cloud gateways, and manage multiple gateway environments." +keywords: "Generative AI, Cybersecurity, Gateway, Deployment, Remote Gateway, CLI" +tags: + - Gateway + - Deployment + - Remote Gateway + - CLI position: 3 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/sandboxes/manage-providers.mdx b/fern/versions/latest/pages/sandboxes/manage-providers.mdx index 58e67d423..f560aa9b4 100644 --- a/fern/versions/latest/pages/sandboxes/manage-providers.mdx +++ b/fern/versions/latest/pages/sandboxes/manage-providers.mdx @@ -1,6 +1,14 @@ --- title: "Providers" +slug: "sandboxes/manage-providers" description: "Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes." +keywords: "Generative AI, Cybersecurity, Providers, Credentials, API Keys, Sandbox, Security" +tags: + - Providers + - Credentials + - API Keys + - Sandbox + - Security position: 4 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx b/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx index fe0912d7a..09bba87a4 100644 --- a/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx +++ b/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx @@ -1,6 +1,15 @@ --- title: "Manage Sandboxes" +sidebar-title: "Sandboxes" +slug: "sandboxes/manage-sandboxes" description: "Set up gateways, create sandboxes, and manage the full sandbox lifecycle." +keywords: "Generative AI, Cybersecurity, Gateway, Sandboxing, AI Agents, Sandbox Management, CLI" +tags: + - Gateway + - Sandboxing + - AI Agents + - Sandbox Management + - CLI position: 2 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/sandboxes/policies.mdx b/fern/versions/latest/pages/sandboxes/policies.mdx index bbff8a338..60302242a 100644 --- a/fern/versions/latest/pages/sandboxes/policies.mdx +++ b/fern/versions/latest/pages/sandboxes/policies.mdx @@ -1,6 +1,15 @@ --- title: "Customize Sandbox Policies" +sidebar-title: "Policies" +slug: "sandboxes/policies" description: "Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes." +keywords: "Generative AI, Cybersecurity, Policy, Network Policy, Sandbox, Security, Hot Reload" +tags: + - Policy + - Network Policy + - Sandbox + - Security + - Hot Reload position: 5 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/security/best-practices.mdx b/fern/versions/latest/pages/security/best-practices.mdx index 057c740f0..36aef6e8c 100644 --- a/fern/versions/latest/pages/security/best-practices.mdx +++ b/fern/versions/latest/pages/security/best-practices.mdx @@ -1,6 +1,15 @@ --- title: "OpenShell Security Best Practices — Controls, Risks, and Configuration Guidance" +sidebar-title: "Security Best Practices" +slug: "security/best-practices" description: "A guide to every configurable security control in OpenShell: defaults, what you can change, and the risks of each choice." +keywords: "Generative AI, Cybersecurity, Security, Policy, Sandbox, Landlock, Seccomp" +tags: + - Security + - Policy + - Sandbox + - Landlock + - Seccomp position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/tutorials/first-network-policy.mdx b/fern/versions/latest/pages/tutorials/first-network-policy.mdx index 4c4b6ca7f..7f8357a29 100644 --- a/fern/versions/latest/pages/tutorials/first-network-policy.mdx +++ b/fern/versions/latest/pages/tutorials/first-network-policy.mdx @@ -1,6 +1,15 @@ --- title: "Write Your First Sandbox Network Policy" +sidebar-title: "First Network Policy" +slug: "tutorials/first-network-policy" description: "See how OpenShell network policies work by creating a sandbox, observing default-deny in action, and applying a fine-grained L7 read-only rule." +keywords: "Generative AI, Cybersecurity, Tutorial, Policy, Network Policy, Sandbox, Security" +tags: + - Tutorial + - Policy + - Network Policy + - Sandbox + - Security --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */} diff --git a/fern/versions/latest/pages/tutorials/github-sandbox.mdx b/fern/versions/latest/pages/tutorials/github-sandbox.mdx index 1e3722e67..c08bbdfab 100644 --- a/fern/versions/latest/pages/tutorials/github-sandbox.mdx +++ b/fern/versions/latest/pages/tutorials/github-sandbox.mdx @@ -1,6 +1,15 @@ --- title: "Grant GitHub Push Access to a Sandboxed Agent" +sidebar-title: "GitHub Push Access" +slug: "tutorials/github-sandbox" description: "Learn the iterative policy workflow by launching a sandbox, diagnosing a GitHub access denial, and applying a custom policy to fix it." +keywords: "Generative AI, Cybersecurity, Tutorial, GitHub, Sandbox, Policy, Claude Code" +tags: + - Tutorial + - GitHub + - Sandbox + - Policy + - Claude Code --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */} diff --git a/fern/versions/latest/pages/tutorials/index.mdx b/fern/versions/latest/pages/tutorials/index.mdx index ebfdb1739..50ec3a559 100644 --- a/fern/versions/latest/pages/tutorials/index.mdx +++ b/fern/versions/latest/pages/tutorials/index.mdx @@ -1,6 +1,12 @@ --- title: "Tutorials" +slug: "tutorials/index" description: "Step-by-step walkthroughs for OpenShell, from first sandbox to production-ready policies." +keywords: "Generative AI, Cybersecurity, Tutorial, Sandbox, Policy" +tags: + - Tutorial + - Sandbox + - Policy position: 2 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. diff --git a/fern/versions/latest/pages/tutorials/inference-ollama.mdx b/fern/versions/latest/pages/tutorials/inference-ollama.mdx index 6806d6741..6d83bb4f8 100644 --- a/fern/versions/latest/pages/tutorials/inference-ollama.mdx +++ b/fern/versions/latest/pages/tutorials/inference-ollama.mdx @@ -1,6 +1,15 @@ --- title: "Run Local Inference with Ollama" +sidebar-title: "Inference with Ollama" +slug: "tutorials/inference-ollama" description: "Run local and cloud models inside an OpenShell sandbox using the Ollama community sandbox, or route sandbox requests to a host-level Ollama server." +keywords: "Generative AI, Cybersecurity, Tutorial, Inference Routing, Ollama, Local Inference, Sandbox" +tags: + - Tutorial + - Inference Routing + - Ollama + - Local Inference + - Sandbox --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */} diff --git a/fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx b/fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx index cb86b9b68..bea4e8cad 100644 --- a/fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx +++ b/fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx @@ -1,6 +1,15 @@ --- title: "Route Local Inference Requests to LM Studio" +sidebar-title: "Local Inference with LM Studio" +slug: "tutorials/local-inference-lmstudio" description: "Configure inference.local to route sandbox requests to a local LM Studio server running on the gateway host." +keywords: "Generative AI, Cybersecurity, Tutorial, Inference Routing, LM Studio, Local Inference, Sandbox" +tags: + - Tutorial + - Inference Routing + - LM Studio + - Local Inference + - Sandbox --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */} From 176cb9e70fd0574f10e1e0e38ffb2843ec7a5172 Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 14:34:24 -0700 Subject: [PATCH 2/8] docs(fern): refine nav structure and slug ownership Keep explicit navbar slugs in the version navigation and simplify frontmatter so migrated pages follow Fern's sidebar and routing behavior more predictably. --- .agents/skills/update-docs/SKILL.md | 5 +- .github/workflows/branch-docs.yml | 2 + CONTRIBUTING.md | 2 +- docs/CONTRIBUTING.md | 11 +-- fern/versions/_nav_order.yml | 28 ------- fern/versions/latest.yml | 81 +++++-------------- fern/versions/latest/pages/CONTRIBUTING.mdx | 5 +- .../latest/pages/about/architecture.mdx | 1 - fern/versions/latest/pages/about/overview.mdx | 1 - .../latest/pages/about/release-notes.mdx | 1 - .../latest/pages/about/supported-agents.mdx | 7 +- .../latest/pages/get-started/quickstart.mdx | 1 - .../pages/inference/{index.mdx => about.mdx} | 2 +- .../latest/pages/inference/configure.mdx | 2 +- .../pages/observability/accessing-logs.mdx | 1 - .../latest/pages/observability/logging.mdx | 1 - .../pages/observability/ocsf-json-export.mdx | 1 - .../observability/{index.mdx => overview.mdx} | 2 +- .../pages/sandboxes/{index.mdx => about.mdx} | 3 +- .../pages/sandboxes/community-sandboxes.mdx | 1 - .../pages/sandboxes/manage-gateways.mdx | 1 - .../pages/sandboxes/manage-providers.mdx | 2 +- .../pages/sandboxes/manage-sandboxes.mdx | 1 - .../latest/pages/sandboxes/policies.mdx | 1 - .../versions/latest/pages/tutorials/index.mdx | 3 +- 25 files changed, 46 insertions(+), 120 deletions(-) delete mode 100644 fern/versions/_nav_order.yml rename fern/versions/latest/pages/inference/{index.mdx => about.mdx} (98%) rename fern/versions/latest/pages/observability/{index.mdx => overview.mdx} (97%) rename fern/versions/latest/pages/sandboxes/{index.mdx => about.mdx} (98%) diff --git a/.agents/skills/update-docs/SKILL.md b/.agents/skills/update-docs/SKILL.md index 1a44061cd..1013c0771 100644 --- a/.agents/skills/update-docs/SKILL.md +++ b/.agents/skills/update-docs/SKILL.md @@ -98,9 +98,10 @@ Write the doc update following the rules in `fern/versions/latest/pages/CONTRIBU - **Code examples use `shell` language** for copyable commands, with no `$` prompt prefix. - **Use `text` fences** for transcripts, logs, or shell sessions that should not be copied verbatim. - **Include the SPDX header** if creating a new page. -- **Match existing Fern frontmatter format** if creating a new page, including `sidebar-title`, `slug`, `keywords`, `tags`, and `position` when they are relevant. -- **Use `sidebar-title` for short nav labels** and `slug` for stable page URLs instead of keeping that metadata only in `fern/versions/latest.yml`. +- **Match existing Fern frontmatter format** if creating a new page, including `sidebar-title`, `keywords`, `tags`, and `position` when they are relevant. Use frontmatter `slug` only for folder-discovered pages or absolute URL overrides. +- **Use `sidebar-title` for short nav labels**. For explicit navbar entries, keep relative `slug` values in `fern/versions/latest.yml` instead of page frontmatter. - **Keep explicit `page:` entries in `fern/versions/latest.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 `fern/versions/latest.yml`** when a child page should live at the parent section path. - **Use `keywords` as a comma-separated string**. When migrating a page from `docs/`, combine the legacy `topics` and `tags` into `keywords` and preserve the legacy `tags` array when it is still useful. - **Do not add a duplicate H1**. Fern renders the page title from frontmatter. - **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia. diff --git a/.github/workflows/branch-docs.yml b/.github/workflows/branch-docs.yml index f824f2e8c..70ce336fd 100644 --- a/.github/workflows/branch-docs.yml +++ b/.github/workflows/branch-docs.yml @@ -12,6 +12,8 @@ permissions: jobs: preview: + # secrets is empty for fork PRs and when FERN_TOKEN is not configured, + # so this job is silently skipped in both cases — that is intentional. if: ${{ secrets.FERN_TOKEN != '' }} runs-on: ubuntu-latest steps: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a3d142c1..40eb847ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -197,7 +197,7 @@ For cross-cutting architectural decisions, API contract changes, or process prop ## 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 `fern/versions/latest/pages/` in the same PR and adjust `fern/versions/latest.yml` if navigation changes. For explicit page entries, keep `page:` and align it with `sidebar-title` when present, otherwise with the page frontmatter `title`. +If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `fern/versions/latest/pages/` in the same PR and adjust `fern/versions/latest.yml` if navigation changes. For explicit navbar entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `fern/versions/latest.yml`. Reserve frontmatter `slug` for folder-discovered pages or absolute URL overrides. To ensure your doc changes follow NVIDIA documentation style, use the `update-docs` skill. It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `fern/versions/latest/pages/CONTRIBUTING.mdx`. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index c22242fde..b77caedc7 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -31,13 +31,13 @@ Preview Fern docs first, then use the legacy Sphinx build only if you explicitly To preview Fern docs locally, run: -```bash +```shell fern docs dev ``` To run non-interactive validation, run: -```bash +```shell fern check ``` @@ -60,7 +60,7 @@ mise run docs:serve ### Format - Published docs use Fern MDX under `fern/versions/latest/pages/`. -- Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `slug`, `keywords`, `tags`, and `position` when the page needs them. +- Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `keywords`, `tags`, and `position` when the page needs them. - Include the SPDX license header after frontmatter: ``` {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. @@ -74,7 +74,6 @@ mise run docs:serve --- title: "Page Title" sidebar-title: "Short Nav Title" -slug: "section/page-slug" description: "One-sentence summary of the page." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing" tags: @@ -85,13 +84,15 @@ tags: - `title` sets the page heading and browser title. - `sidebar-title` sets the shorter label in the sidebar when the full page title is too long. -- `slug` sets the full path from the docs root. Use it to preserve stable URLs when you move slug metadata out of `fern/versions/latest.yml`. - `keywords` is a comma-separated string for page metadata. When migrating from `docs/`, combine the legacy `topics` and `tags` into `keywords`. - `tags` is an optional array for preserving legacy doc taxonomy or changelog tags. Fern does not treat `tags` as SEO metadata on ordinary pages, so still populate `keywords`. - `position` controls ordering for pages discovered through a `folder:` entry. +- `slug` optionally overrides the page URL with a full path from the docs root. For explicit entries in `fern/versions/latest.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`. +For explicit page and folder entries in `fern/versions/latest.yml`, put the relative `slug:` there instead of in frontmatter. Use `skip-slug: true` when a child page should live at the parent section path. + ### Page Structure 1. Frontmatter `title` and `description`, plus any relevant page metadata. diff --git a/fern/versions/_nav_order.yml b/fern/versions/_nav_order.yml deleted file mode 100644 index 5207b5bc7..000000000 --- a/fern/versions/_nav_order.yml +++ /dev/null @@ -1,28 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -# Page ordering derived from toctree (use with add_frontmatter.py --nav-order) -"./versions/latest/pages/about/overview.mdx": 1 -"./versions/latest/pages/get-started/quickstart.mdx": 1 -"./versions/latest/pages/index.mdx": 1 -"./versions/latest/pages/inference/index.mdx": 1 -"./versions/latest/pages/observability/index.mdx": 1 -"./versions/latest/pages/reference/gateway-auth.mdx": 1 -"./versions/latest/pages/resources/license.mdx": 1 -"./versions/latest/pages/sandboxes/index.mdx": 1 -"./versions/latest/pages/security/best-practices.mdx": 1 -"./versions/latest/pages/about/architecture.mdx": 2 -"./versions/latest/pages/inference/configure.mdx": 2 -"./versions/latest/pages/observability/logging.mdx": 2 -"./versions/latest/pages/reference/default-policy.mdx": 2 -"./versions/latest/pages/sandboxes/manage-sandboxes.mdx": 2 -"./versions/latest/pages/tutorials/index.mdx": 2 -"./versions/latest/pages/about/supported-agents.mdx": 3 -"./versions/latest/pages/reference/policy-schema.mdx": 3 -"./versions/latest/pages/observability/accessing-logs.mdx": 3 -"./versions/latest/pages/sandboxes/manage-gateways.mdx": 3 -"./versions/latest/pages/about/release-notes.mdx": 4 -"./versions/latest/pages/reference/support-matrix.mdx": 4 -"./versions/latest/pages/observability/ocsf-json-export.mdx": 4 -"./versions/latest/pages/sandboxes/manage-providers.mdx": 4 -"./versions/latest/pages/sandboxes/policies.mdx": 5 -"./versions/latest/pages/sandboxes/community-sandboxes.mdx": 6 diff --git a/fern/versions/latest.yml b/fern/versions/latest.yml index 9d82c81a2..bcd35731f 100644 --- a/fern/versions/latest.yml +++ b/fern/versions/latest.yml @@ -1,63 +1,24 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 navigation: - - section: "Documentation" - contents: - - page: "Home" - path: ./latest/pages/index.mdx - - section: "About NVIDIA OpenShell" - slug: about - contents: - - page: "Overview" - path: ./latest/pages/about/overview.mdx - - page: "How It Works" - path: ./latest/pages/about/architecture.mdx - - page: "Supported Agents" - path: ./latest/pages/about/supported-agents.mdx - - page: "Release Notes" - path: ./latest/pages/about/release-notes.mdx - - section: "Get Started" - contents: - - page: "Quickstart" - path: ./latest/pages/get-started/quickstart.mdx - - folder: ./latest/pages/tutorials - collapsed: open-by-default - - section: "Gateways and Sandboxes" - slug: sandboxes - contents: - - page: "About Gateways and Sandboxes" - path: ./latest/pages/sandboxes/index.mdx - - page: "Sandboxes" - path: ./latest/pages/sandboxes/manage-sandboxes.mdx - - page: "Gateways" - path: ./latest/pages/sandboxes/manage-gateways.mdx - - page: "Providers" - path: ./latest/pages/sandboxes/manage-providers.mdx - - page: "Policies" - path: ./latest/pages/sandboxes/policies.mdx - - page: "Community Sandboxes" - path: ./latest/pages/sandboxes/community-sandboxes.mdx - - section: "Inference Routing" - slug: inference - contents: - - page: "About Inference Routing" - path: ./latest/pages/inference/index.mdx - - page: "Configure Inference Routing" - path: ./latest/pages/inference/configure.mdx - - section: "Observability" - slug: observability - contents: - - page: "Overview" - path: ./latest/pages/observability/index.mdx - - page: "Logging" - path: ./latest/pages/observability/logging.mdx - - page: "Accessing Logs" - path: ./latest/pages/observability/accessing-logs.mdx - - page: "OCSF JSON Export" - path: ./latest/pages/observability/ocsf-json-export.mdx - - folder: ./latest/pages/reference - title: "Reference" - - folder: ./latest/pages/security - title: "Security" - - folder: ./latest/pages/resources - title: "Resources" +- section: "Get Started" + slug: get-started + contents: + - page: "Home" + path: ./latest/pages/index.mdx + - page: "Quickstart" + path: ./latest/pages/get-started/quickstart.mdx +- folder: ./latest/pages/about + title: "About NVIDIA OpenShell" +- folder: ./latest/pages/tutorials +- folder: ./latest/pages/sandboxes +- folder: ./latest/pages/inference + title: "Inference Routing" +- folder: ./latest/pages/observability + title: "Observability" +- folder: ./latest/pages/reference + title: "Reference" +- folder: ./latest/pages/security + title: "Security" +- folder: ./latest/pages/resources + title: "Resources" diff --git a/fern/versions/latest/pages/CONTRIBUTING.mdx b/fern/versions/latest/pages/CONTRIBUTING.mdx index fa969002b..d06bdfe44 100644 --- a/fern/versions/latest/pages/CONTRIBUTING.mdx +++ b/fern/versions/latest/pages/CONTRIBUTING.mdx @@ -62,7 +62,7 @@ mise run docs:serve ### Format - Published docs use Fern MDX under `fern/versions/latest/pages/`. -- Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `slug`, `keywords`, `tags`, and `position` when the page needs them. +- Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `keywords`, `tags`, and `position` when the page needs them. - Include the SPDX license header after frontmatter: ``` {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. @@ -76,7 +76,6 @@ mise run docs:serve --- title: "Page Title" sidebar-title: "Short Nav Title" -slug: "section/page-slug" description: "One-sentence summary of the page." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing" tags: @@ -87,10 +86,10 @@ tags: - `title` sets the page heading and browser title. - `sidebar-title` sets the shorter label in the sidebar when the full page title is too long. -- `slug` sets the full path from the docs root. Use it to preserve stable URLs when you move slug metadata out of `fern/versions/latest.yml`. - `keywords` is a comma-separated string for page metadata. When migrating from `docs/`, combine the legacy `topics` and `tags` into `keywords`. - `tags` is an optional array for preserving legacy doc taxonomy or changelog tags. Fern does not treat `tags` as SEO metadata on ordinary pages, so still populate `keywords`. - `position` controls ordering for pages discovered through a `folder:` entry. +- `slug` optionally overrides the page URL with a full path from the docs root. For explicit entries in `fern/versions/latest.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`. diff --git a/fern/versions/latest/pages/about/architecture.mdx b/fern/versions/latest/pages/about/architecture.mdx index 17f608a05..4158e117f 100644 --- a/fern/versions/latest/pages/about/architecture.mdx +++ b/fern/versions/latest/pages/about/architecture.mdx @@ -1,7 +1,6 @@ --- title: "How OpenShell Works" sidebar-title: "How It Works" -slug: "about/architecture" description: "OpenShell architecture overview covering the gateway, sandbox, policy engine, and privacy router." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Architecture" tags: diff --git a/fern/versions/latest/pages/about/overview.mdx b/fern/versions/latest/pages/about/overview.mdx index 83c2818ab..9bdbf0c05 100644 --- a/fern/versions/latest/pages/about/overview.mdx +++ b/fern/versions/latest/pages/about/overview.mdx @@ -1,7 +1,6 @@ --- title: "Overview of NVIDIA OpenShell" sidebar-title: "Overview" -slug: "about/overview" description: "OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Privacy, Inference Routing" tags: diff --git a/fern/versions/latest/pages/about/release-notes.mdx b/fern/versions/latest/pages/about/release-notes.mdx index b4d8adb87..9830c28e0 100644 --- a/fern/versions/latest/pages/about/release-notes.mdx +++ b/fern/versions/latest/pages/about/release-notes.mdx @@ -1,7 +1,6 @@ --- title: "NVIDIA OpenShell Release Notes" sidebar-title: "Release Notes" -slug: "about/release-notes" description: "Track the latest changes and improvements to NVIDIA OpenShell." keywords: "Generative AI, Cybersecurity, Release Notes, Changelog, AI Agents" tags: diff --git a/fern/versions/latest/pages/about/supported-agents.mdx b/fern/versions/latest/pages/about/supported-agents.mdx index 190496cc0..10c7063fe 100644 --- a/fern/versions/latest/pages/about/supported-agents.mdx +++ b/fern/versions/latest/pages/about/supported-agents.mdx @@ -1,7 +1,10 @@ --- title: "Supported Agents" -slug: "about/supported-agents" -description: "" +description: "AI agent frameworks and runtimes compatible with OpenShell sandboxes." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Claude, Codex, Cursor" +tags: + - AI Agents + - Sandboxing position: 3 --- The following table summarizes the agents that run in OpenShell sandboxes. All agent sandbox images are maintained in the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) repository. Agents in the base image are auto-configured when passed as the trailing command to `openshell sandbox create`. diff --git a/fern/versions/latest/pages/get-started/quickstart.mdx b/fern/versions/latest/pages/get-started/quickstart.mdx index 9adc91500..f21390dec 100644 --- a/fern/versions/latest/pages/get-started/quickstart.mdx +++ b/fern/versions/latest/pages/get-started/quickstart.mdx @@ -1,6 +1,5 @@ --- title: "Quickstart" -slug: "get-started/quickstart" description: "Install the OpenShell CLI and create your first sandboxed AI agent in two commands." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Quickstart" tags: diff --git a/fern/versions/latest/pages/inference/index.mdx b/fern/versions/latest/pages/inference/about.mdx similarity index 98% rename from fern/versions/latest/pages/inference/index.mdx rename to fern/versions/latest/pages/inference/about.mdx index f4fcce7a5..5d2ceb390 100644 --- a/fern/versions/latest/pages/inference/index.mdx +++ b/fern/versions/latest/pages/inference/about.mdx @@ -1,6 +1,6 @@ --- title: "About Inference Routing" -slug: "inference/index" +sidebar-title: "About Inference Routing" description: "Understand how OpenShell routes inference traffic through external endpoints and the local privacy router." keywords: "Generative AI, Cybersecurity, Inference Routing, Privacy, AI Agents, LLM" tags: diff --git a/fern/versions/latest/pages/inference/configure.mdx b/fern/versions/latest/pages/inference/configure.mdx index 1815cb095..abdb5167e 100644 --- a/fern/versions/latest/pages/inference/configure.mdx +++ b/fern/versions/latest/pages/inference/configure.mdx @@ -1,6 +1,6 @@ --- title: "Configure Inference Routing" -slug: "inference/configure" +sidebar-title: "Configure Inference Routing" description: "Set up the managed local inference endpoint with provider credentials and model configuration." keywords: "Generative AI, Cybersecurity, Inference Routing, Configuration, Privacy, LLM, Provider" tags: diff --git a/fern/versions/latest/pages/observability/accessing-logs.mdx b/fern/versions/latest/pages/observability/accessing-logs.mdx index 9dbd93283..baadc8c92 100644 --- a/fern/versions/latest/pages/observability/accessing-logs.mdx +++ b/fern/versions/latest/pages/observability/accessing-logs.mdx @@ -1,6 +1,5 @@ --- title: "Accessing Logs" -slug: "observability/accessing-logs" description: "How to view sandbox logs through the CLI, TUI, and directly on the sandbox filesystem." keywords: "Generative AI, Cybersecurity, Logging, CLI, TUI, Observability" tags: diff --git a/fern/versions/latest/pages/observability/logging.mdx b/fern/versions/latest/pages/observability/logging.mdx index 6783f29ed..abdcdfb56 100644 --- a/fern/versions/latest/pages/observability/logging.mdx +++ b/fern/versions/latest/pages/observability/logging.mdx @@ -1,7 +1,6 @@ --- title: "Sandbox Logging" sidebar-title: "Logging" -slug: "observability/logging" description: "How OpenShell logs sandbox activity using standard tracing and OCSF structured events." keywords: "Generative AI, Cybersecurity, Logging, OCSF, Observability" tags: diff --git a/fern/versions/latest/pages/observability/ocsf-json-export.mdx b/fern/versions/latest/pages/observability/ocsf-json-export.mdx index caad70e07..a8e93373a 100644 --- a/fern/versions/latest/pages/observability/ocsf-json-export.mdx +++ b/fern/versions/latest/pages/observability/ocsf-json-export.mdx @@ -1,6 +1,5 @@ --- title: "OCSF JSON Export" -slug: "observability/ocsf-json-export" description: "How to enable full OCSF JSON logging for SIEM integration, compliance, and structured analysis." keywords: "Generative AI, Cybersecurity, OCSF, JSON, SIEM, Compliance, Observability" tags: diff --git a/fern/versions/latest/pages/observability/index.mdx b/fern/versions/latest/pages/observability/overview.mdx similarity index 97% rename from fern/versions/latest/pages/observability/index.mdx rename to fern/versions/latest/pages/observability/overview.mdx index 52ac6a912..0cef114b9 100644 --- a/fern/versions/latest/pages/observability/index.mdx +++ b/fern/versions/latest/pages/observability/overview.mdx @@ -1,7 +1,6 @@ --- title: "Observability" sidebar-title: "Overview" -slug: "observability/index" description: "Understand how OpenShell logs sandbox activity, how to access logs, and how to export structured OCSF records." keywords: "Generative AI, Cybersecurity, Logging, OCSF, Observability, Monitoring" tags: @@ -9,6 +8,7 @@ tags: - OCSF - Observability - Monitoring +position: 1 --- OpenShell provides structured logging for every sandbox. Every network connection, process lifecycle event, filesystem policy decision, and configuration change is recorded so you can understand exactly what happened inside a sandbox. diff --git a/fern/versions/latest/pages/sandboxes/index.mdx b/fern/versions/latest/pages/sandboxes/about.mdx similarity index 98% rename from fern/versions/latest/pages/sandboxes/index.mdx rename to fern/versions/latest/pages/sandboxes/about.mdx index 583be0184..1f4a21923 100644 --- a/fern/versions/latest/pages/sandboxes/index.mdx +++ b/fern/versions/latest/pages/sandboxes/about.mdx @@ -1,7 +1,6 @@ --- title: "About Gateways and Sandboxes" -sidebar-title: "Gateways and Sandboxes" -slug: "sandboxes/index" +sidebar-title: "About Gateways and Sandboxes" description: "Understand gateways, gateway types, sandbox lifecycle, supported agents, built-in default policy, and network access rules in OpenShell." keywords: "Generative AI, Cybersecurity, Gateway, Sandboxing, AI Agents, Security, Policy, Isolation" tags: diff --git a/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx b/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx index e3114469f..68e0398e0 100644 --- a/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx +++ b/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx @@ -1,6 +1,5 @@ --- title: "Community Sandboxes" -slug: "sandboxes/community-sandboxes" description: "Use pre-built sandboxes from the OpenShell Community catalog or contribute your own." keywords: "Generative AI, Cybersecurity, Community, Sandbox, Container Image, Open Source" tags: diff --git a/fern/versions/latest/pages/sandboxes/manage-gateways.mdx b/fern/versions/latest/pages/sandboxes/manage-gateways.mdx index b8700478a..ab2eebfa9 100644 --- a/fern/versions/latest/pages/sandboxes/manage-gateways.mdx +++ b/fern/versions/latest/pages/sandboxes/manage-gateways.mdx @@ -1,7 +1,6 @@ --- title: "Deploy and Manage Gateways" sidebar-title: "Gateways" -slug: "sandboxes/manage-gateways" description: "Deploy local and remote gateways, register cloud gateways, and manage multiple gateway environments." keywords: "Generative AI, Cybersecurity, Gateway, Deployment, Remote Gateway, CLI" tags: diff --git a/fern/versions/latest/pages/sandboxes/manage-providers.mdx b/fern/versions/latest/pages/sandboxes/manage-providers.mdx index f560aa9b4..9fee45794 100644 --- a/fern/versions/latest/pages/sandboxes/manage-providers.mdx +++ b/fern/versions/latest/pages/sandboxes/manage-providers.mdx @@ -1,6 +1,6 @@ --- title: "Providers" -slug: "sandboxes/manage-providers" +sidebar-title: "Providers" description: "Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes." keywords: "Generative AI, Cybersecurity, Providers, Credentials, API Keys, Sandbox, Security" tags: diff --git a/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx b/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx index 09bba87a4..42c1ff237 100644 --- a/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx +++ b/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx @@ -1,7 +1,6 @@ --- title: "Manage Sandboxes" sidebar-title: "Sandboxes" -slug: "sandboxes/manage-sandboxes" description: "Set up gateways, create sandboxes, and manage the full sandbox lifecycle." keywords: "Generative AI, Cybersecurity, Gateway, Sandboxing, AI Agents, Sandbox Management, CLI" tags: diff --git a/fern/versions/latest/pages/sandboxes/policies.mdx b/fern/versions/latest/pages/sandboxes/policies.mdx index 60302242a..2cf585457 100644 --- a/fern/versions/latest/pages/sandboxes/policies.mdx +++ b/fern/versions/latest/pages/sandboxes/policies.mdx @@ -1,7 +1,6 @@ --- title: "Customize Sandbox Policies" sidebar-title: "Policies" -slug: "sandboxes/policies" description: "Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes." keywords: "Generative AI, Cybersecurity, Policy, Network Policy, Sandbox, Security, Hot Reload" tags: diff --git a/fern/versions/latest/pages/tutorials/index.mdx b/fern/versions/latest/pages/tutorials/index.mdx index 50ec3a559..bb873251a 100644 --- a/fern/versions/latest/pages/tutorials/index.mdx +++ b/fern/versions/latest/pages/tutorials/index.mdx @@ -1,13 +1,12 @@ --- title: "Tutorials" -slug: "tutorials/index" description: "Step-by-step walkthroughs for OpenShell, from first sandbox to production-ready policies." keywords: "Generative AI, Cybersecurity, Tutorial, Sandbox, Policy" tags: - Tutorial - Sandbox - Policy -position: 2 +position: 1 --- {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */} From 2c745fb720798b8f456460f404895b1f0028509a Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 14:48:30 -0700 Subject: [PATCH 3/8] fix(fern): prevent sidebar nav clipping Keep the desktop sidebar height within the visible viewport so the last navigation items remain reachable below the header and announcement bar. --- fern/main.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/main.css b/fern/main.css index eff5dd495..138be499d 100644 --- a/fern/main.css +++ b/fern/main.css @@ -245,7 +245,7 @@ html[data-theme=dark] { /* Sidebar styling */ #fern-sidebar { border-right: 1px solid var(--border, var(--grayscale-a5)) !important; - height: 100vh !important; + height: calc(100vh - var(--header-height)) !important; } .fern-sidebar-link:not(:hover){ background-color: transparent !important; From 75f79fa501a429e4de69265e9d11f481d907f9f7 Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 15:49:14 -0700 Subject: [PATCH 4/8] ci(fern): gate preview steps on token availability Use a workflow step output to decide whether to run the Fern preview steps so pull requests without Fern credentials skip cleanly with an explicit notice. --- .github/workflows/branch-docs.yml | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/.github/workflows/branch-docs.yml b/.github/workflows/branch-docs.yml index 70ce336fd..710b9910e 100644 --- a/.github/workflows/branch-docs.yml +++ b/.github/workflows/branch-docs.yml @@ -12,23 +12,35 @@ permissions: jobs: preview: - # secrets is empty for fork PRs and when FERN_TOKEN is not configured, - # so this job is silently skipped in both cases — that is intentional. - if: ${{ secrets.FERN_TOKEN != '' }} runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 + - name: Check Fern preview availability + id: fern-preview + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + run: | + if [ -n "$FERN_TOKEN" ]; then + echo "enabled=true" >> "$GITHUB_OUTPUT" + else + echo "enabled=false" >> "$GITHUB_OUTPUT" + echo "::notice::Skipping Fern docs preview because FERN_TOKEN is unavailable. This is expected for fork PRs and repos without Fern preview credentials configured." + fi + - name: Setup Node.js + if: ${{ steps.fern-preview.outputs.enabled == 'true' }} uses: actions/setup-node@v6 with: node-version: "20" - name: Install Fern CLI + if: ${{ steps.fern-preview.outputs.enabled == 'true' }} run: npm install -g fern-api - name: Generate preview URL + if: ${{ steps.fern-preview.outputs.enabled == 'true' }} id: generate-docs env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} @@ -45,6 +57,7 @@ jobs: echo "preview_url=$URL" >> "$GITHUB_OUTPUT" - name: Post or update PR comment + if: ${{ steps.fern-preview.outputs.enabled == 'true' }} env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_NUMBER: ${{ github.event.pull_request.number }} From f6bc3e1c36474290a7410e18778c1083165de63a Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 16:06:12 -0700 Subject: [PATCH 5/8] docs(fern): move latest pages into root tree Flatten the latest Fern content into fern/pages and update navigation and internal authoring references to match the new layout without changing the published docs behavior. --- .agents/skills/update-docs/SKILL.md | 32 +++++++++---------- AGENTS.md | 4 +-- CONTRIBUTING.md | 6 ++-- .../latest => }/pages/CONTRIBUTING.mdx | 4 +-- .../latest => }/pages/about/architecture.mdx | 0 .../latest => }/pages/about/overview.mdx | 0 .../latest => }/pages/about/release-notes.mdx | 0 .../pages/about/supported-agents.mdx | 0 .../pages/get-started/quickstart.mdx | 0 fern/{versions/latest => }/pages/index.mdx | 0 .../latest => }/pages/inference/about.mdx | 0 .../latest => }/pages/inference/configure.mdx | 0 .../pages/observability/accessing-logs.mdx | 0 .../pages/observability/logging.mdx | 0 .../pages/observability/ocsf-json-export.mdx | 1 + .../pages/observability/overview.mdx | 0 .../pages/reference/default-policy.mdx | 0 .../pages/reference/gateway-auth.mdx | 0 .../pages/reference/policy-schema.mdx | 0 .../pages/reference/support-matrix.mdx | 0 .../latest => }/pages/resources/license.mdx | 0 .../latest => }/pages/sandboxes/about.mdx | 0 .../pages/sandboxes/community-sandboxes.mdx | 0 .../pages/sandboxes/manage-gateways.mdx | 0 .../pages/sandboxes/manage-providers.mdx | 0 .../pages/sandboxes/manage-sandboxes.mdx | 0 .../latest => }/pages/sandboxes/policies.mdx | 0 .../pages/security/best-practices.mdx | 0 .../pages/tutorials/first-network-policy.mdx | 0 .../pages/tutorials/github-sandbox.mdx | 0 .../latest => }/pages/tutorials/index.mdx | 0 .../pages/tutorials/inference-ollama.mdx | 0 .../tutorials/local-inference-lmstudio.mdx | 0 fern/versions/latest.yml | 20 ++++++------ 34 files changed, 34 insertions(+), 33 deletions(-) rename fern/{versions/latest => }/pages/CONTRIBUTING.mdx (95%) rename fern/{versions/latest => }/pages/about/architecture.mdx (100%) rename fern/{versions/latest => }/pages/about/overview.mdx (100%) rename fern/{versions/latest => }/pages/about/release-notes.mdx (100%) rename fern/{versions/latest => }/pages/about/supported-agents.mdx (100%) rename fern/{versions/latest => }/pages/get-started/quickstart.mdx (100%) rename fern/{versions/latest => }/pages/index.mdx (100%) rename fern/{versions/latest => }/pages/inference/about.mdx (100%) rename fern/{versions/latest => }/pages/inference/configure.mdx (100%) rename fern/{versions/latest => }/pages/observability/accessing-logs.mdx (100%) rename fern/{versions/latest => }/pages/observability/logging.mdx (100%) rename fern/{versions/latest => }/pages/observability/ocsf-json-export.mdx (99%) rename fern/{versions/latest => }/pages/observability/overview.mdx (100%) rename fern/{versions/latest => }/pages/reference/default-policy.mdx (100%) rename fern/{versions/latest => }/pages/reference/gateway-auth.mdx (100%) rename fern/{versions/latest => }/pages/reference/policy-schema.mdx (100%) rename fern/{versions/latest => }/pages/reference/support-matrix.mdx (100%) rename fern/{versions/latest => }/pages/resources/license.mdx (100%) rename fern/{versions/latest => }/pages/sandboxes/about.mdx (100%) rename fern/{versions/latest => }/pages/sandboxes/community-sandboxes.mdx (100%) rename fern/{versions/latest => }/pages/sandboxes/manage-gateways.mdx (100%) rename fern/{versions/latest => }/pages/sandboxes/manage-providers.mdx (100%) rename fern/{versions/latest => }/pages/sandboxes/manage-sandboxes.mdx (100%) rename fern/{versions/latest => }/pages/sandboxes/policies.mdx (100%) rename fern/{versions/latest => }/pages/security/best-practices.mdx (100%) rename fern/{versions/latest => }/pages/tutorials/first-network-policy.mdx (100%) rename fern/{versions/latest => }/pages/tutorials/github-sandbox.mdx (100%) rename fern/{versions/latest => }/pages/tutorials/index.mdx (100%) rename fern/{versions/latest => }/pages/tutorials/inference-ollama.mdx (100%) rename fern/{versions/latest => }/pages/tutorials/local-inference-lmstudio.mdx (100%) diff --git a/.agents/skills/update-docs/SKILL.md b/.agents/skills/update-docs/SKILL.md index 1013c0771..e88247bac 100644 --- a/.agents/skills/update-docs/SKILL.md +++ b/.agents/skills/update-docs/SKILL.md @@ -10,8 +10,8 @@ Scan recent git history for commits that affect user-facing behavior and draft d ## Prerequisites - You must be in the OpenShell git repository. -- The published docs tree must exist under `fern/versions/latest/pages/`. -- Read `fern/versions/latest/pages/CONTRIBUTING.mdx` before writing any content. It contains the current style guide and formatting rules. +- The published docs tree must exist under `fern/pages/`. +- Read `fern/pages/CONTRIBUTING.mdx` before writing any content. It contains the current style guide and formatting rules. ## When to Use @@ -48,16 +48,16 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi | Code area | Likely doc page(s) | |---|---| -| `crates/openshell-cli/` (gateway commands) | `fern/versions/latest/pages/sandboxes/manage-gateways.mdx` | -| `crates/openshell-cli/` (sandbox commands) | `fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx` | -| `crates/openshell-cli/` (provider commands) | `fern/versions/latest/pages/sandboxes/manage-providers.mdx` | -| `crates/openshell-cli/` (new top-level command) | May need a new page or `fern/versions/latest/pages/reference/` entry | -| Proxy or policy code | `fern/versions/latest/pages/sandboxes/policies.mdx`, `fern/versions/latest/pages/reference/policy-schema.mdx` | -| Inference code | `fern/versions/latest/pages/inference/configure.mdx` | -| `python/` (SDK changes) | `fern/versions/latest/pages/reference/` or `fern/versions/latest/pages/get-started/quickstart.mdx` | -| `proto/` (API changes) | `fern/versions/latest/pages/reference/` | -| `deploy/` (Dockerfile, Helm) | `fern/versions/latest/pages/sandboxes/manage-gateways.mdx`, `fern/versions/latest/pages/about/architecture.mdx` | -| Community sandbox definitions | `fern/versions/latest/pages/sandboxes/community-sandboxes.mdx` | +| `crates/openshell-cli/` (gateway commands) | `fern/pages/sandboxes/manage-gateways.mdx` | +| `crates/openshell-cli/` (sandbox commands) | `fern/pages/sandboxes/manage-sandboxes.mdx` | +| `crates/openshell-cli/` (provider commands) | `fern/pages/sandboxes/manage-providers.mdx` | +| `crates/openshell-cli/` (new top-level command) | May need a new page or `fern/pages/reference/` entry | +| Proxy or policy code | `fern/pages/sandboxes/policies.mdx`, `fern/pages/reference/policy-schema.mdx` | +| Inference code | `fern/pages/inference/configure.mdx` | +| `python/` (SDK changes) | `fern/pages/reference/` or `fern/pages/get-started/quickstart.mdx` | +| `proto/` (API changes) | `fern/pages/reference/` | +| `deploy/` (Dockerfile, Helm) | `fern/pages/sandboxes/manage-gateways.mdx`, `fern/pages/about/architecture.mdx` | +| Community sandbox definitions | `fern/pages/sandboxes/community-sandboxes.mdx` | If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page. @@ -88,7 +88,7 @@ Identify where the new content should go. Follow the page's existing structure. ## Step 5: Draft the Update -Write the doc update following the rules in `fern/versions/latest/pages/CONTRIBUTING.mdx`. Key reminders: +Write the doc update following the rules in `fern/pages/CONTRIBUTING.mdx`. Key reminders: - **Active voice, present tense, second person.** - **No unnecessary bold.** Reserve bold for UI labels and parameter names. @@ -118,7 +118,7 @@ When updating an existing page: When creating a new page: -- Follow the frontmatter template from `fern/versions/latest/pages/CONTRIBUTING.mdx`. +- Follow the frontmatter template from `fern/pages/CONTRIBUTING.mdx`. - Add the page to the appropriate section in `fern/versions/latest.yml`. ## Step 6: Present the Results @@ -129,8 +129,8 @@ After drafting all updates, present a summary to the user: ## Doc Updates from Commits ### Updated pages -- `fern/versions/latest/pages/sandboxes/manage-gateways.mdx`: Added `--gpu` flag documentation (from commit abc1234). -- `fern/versions/latest/pages/reference/policy-schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678). +- `fern/pages/sandboxes/manage-gateways.mdx`: Added `--gpu` flag documentation (from commit abc1234). +- `fern/pages/reference/policy-schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678). ### New pages needed - None (or list any new pages created). diff --git a/AGENTS.md b/AGENTS.md index b2a986756..a2cb194a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -186,9 +186,9 @@ ocsf_emit!(event); ## Documentation - When making changes, update the relevant documentation in the `architecture/` directory. -- When changes affect user-facing behavior, update the relevant published docs pages under `fern/versions/latest/pages/` and navigation in `fern/versions/latest.yml`. +- When changes affect user-facing behavior, update the relevant published docs pages under `fern/pages/` and navigation in `fern/versions/latest.yml`. - `docs/` is retained for legacy Sphinx build tasks and migration/reference work. Do not update it unless the user explicitly asks. -- Follow the docs style guide in [fern/versions/latest/pages/CONTRIBUTING.mdx](fern/versions/latest/pages/CONTRIBUTING.mdx): active voice, minimal formatting, no filler introductions, `shell` fences for copyable commands, and no duplicate body H1. +- Follow the docs style guide in [fern/pages/CONTRIBUTING.mdx](fern/pages/CONTRIBUTING.mdx): active voice, minimal formatting, no filler introductions, `shell` fences for copyable commands, and no duplicate body H1. - Fern PR previews run through `.github/workflows/branch-docs.yml`, and production publish runs through the `publish-fern-docs` job in `.github/workflows/release-tag.yml`. - Use the `update-docs` skill to scan recent commits and draft doc updates. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40eb847ad..7adb3cc4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -197,10 +197,10 @@ For cross-cutting architectural decisions, API contract changes, or process prop ## 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 `fern/versions/latest/pages/` in the same PR and adjust `fern/versions/latest.yml` if navigation changes. For explicit navbar entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `fern/versions/latest.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 `fern/pages/` in the same PR and adjust `fern/versions/latest.yml` if navigation changes. For explicit navbar entries, keep `page:` aligned with `sidebar-title` when present and put relative `slug:` values in `fern/versions/latest.yml`. Reserve frontmatter `slug` for folder-discovered pages or absolute URL overrides. To ensure your doc changes follow NVIDIA documentation style, use the `update-docs` skill. -It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `fern/versions/latest/pages/CONTRIBUTING.mdx`. +It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `fern/pages/CONTRIBUTING.mdx`. To preview Fern docs locally: @@ -220,7 +220,7 @@ Fern docs publishing is handled by the `publish-fern-docs` job in `.github/workf `docs/` and `mise run docs` / `mise run docs:serve` are still kept for the legacy Sphinx build during the transition, but they are no longer the primary published docs workflow. -See [fern/versions/latest/pages/CONTRIBUTING.mdx](fern/versions/latest/pages/CONTRIBUTING.mdx) for the current docs authoring guide. +See [fern/pages/CONTRIBUTING.mdx](fern/pages/CONTRIBUTING.mdx) for the current docs authoring guide. ## Pull Requests diff --git a/fern/versions/latest/pages/CONTRIBUTING.mdx b/fern/pages/CONTRIBUTING.mdx similarity index 95% rename from fern/versions/latest/pages/CONTRIBUTING.mdx rename to fern/pages/CONTRIBUTING.mdx index d06bdfe44..b3eb06cbc 100644 --- a/fern/versions/latest/pages/CONTRIBUTING.mdx +++ b/fern/pages/CONTRIBUTING.mdx @@ -4,7 +4,7 @@ description: "" --- This guide covers how to write, edit, and review documentation for NVIDIA OpenShell. If you change code that affects user-facing behavior, update the relevant docs in the same PR. -The published docs live in `fern/versions/latest/pages/`, and navigation is defined in `fern/versions/latest.yml`. The `docs/` tree is kept for legacy Sphinx builds and migration/reference work. Do not update `docs/` unless you are explicitly asked to do so. +The published docs live in `fern/pages/`, and navigation is defined in `fern/versions/latest.yml`. The `docs/` tree is kept for legacy Sphinx builds and migration/reference work. Do not update `docs/` unless you are explicitly asked to do so. ## Use the Agent Skills @@ -61,7 +61,7 @@ mise run docs:serve ### Format -- Published docs use Fern MDX under `fern/versions/latest/pages/`. +- Published docs use Fern MDX under `fern/pages/`. - Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `keywords`, `tags`, and `position` when the page needs them. - Include the SPDX license header after frontmatter: ``` diff --git a/fern/versions/latest/pages/about/architecture.mdx b/fern/pages/about/architecture.mdx similarity index 100% rename from fern/versions/latest/pages/about/architecture.mdx rename to fern/pages/about/architecture.mdx diff --git a/fern/versions/latest/pages/about/overview.mdx b/fern/pages/about/overview.mdx similarity index 100% rename from fern/versions/latest/pages/about/overview.mdx rename to fern/pages/about/overview.mdx diff --git a/fern/versions/latest/pages/about/release-notes.mdx b/fern/pages/about/release-notes.mdx similarity index 100% rename from fern/versions/latest/pages/about/release-notes.mdx rename to fern/pages/about/release-notes.mdx diff --git a/fern/versions/latest/pages/about/supported-agents.mdx b/fern/pages/about/supported-agents.mdx similarity index 100% rename from fern/versions/latest/pages/about/supported-agents.mdx rename to fern/pages/about/supported-agents.mdx diff --git a/fern/versions/latest/pages/get-started/quickstart.mdx b/fern/pages/get-started/quickstart.mdx similarity index 100% rename from fern/versions/latest/pages/get-started/quickstart.mdx rename to fern/pages/get-started/quickstart.mdx diff --git a/fern/versions/latest/pages/index.mdx b/fern/pages/index.mdx similarity index 100% rename from fern/versions/latest/pages/index.mdx rename to fern/pages/index.mdx diff --git a/fern/versions/latest/pages/inference/about.mdx b/fern/pages/inference/about.mdx similarity index 100% rename from fern/versions/latest/pages/inference/about.mdx rename to fern/pages/inference/about.mdx diff --git a/fern/versions/latest/pages/inference/configure.mdx b/fern/pages/inference/configure.mdx similarity index 100% rename from fern/versions/latest/pages/inference/configure.mdx rename to fern/pages/inference/configure.mdx diff --git a/fern/versions/latest/pages/observability/accessing-logs.mdx b/fern/pages/observability/accessing-logs.mdx similarity index 100% rename from fern/versions/latest/pages/observability/accessing-logs.mdx rename to fern/pages/observability/accessing-logs.mdx diff --git a/fern/versions/latest/pages/observability/logging.mdx b/fern/pages/observability/logging.mdx similarity index 100% rename from fern/versions/latest/pages/observability/logging.mdx rename to fern/pages/observability/logging.mdx diff --git a/fern/versions/latest/pages/observability/ocsf-json-export.mdx b/fern/pages/observability/ocsf-json-export.mdx similarity index 99% rename from fern/versions/latest/pages/observability/ocsf-json-export.mdx rename to fern/pages/observability/ocsf-json-export.mdx index a8e93373a..92e85730d 100644 --- a/fern/versions/latest/pages/observability/ocsf-json-export.mdx +++ b/fern/pages/observability/ocsf-json-export.mdx @@ -1,5 +1,6 @@ --- title: "OCSF JSON Export" +sidebar-title: "OCSF JSON Export" description: "How to enable full OCSF JSON logging for SIEM integration, compliance, and structured analysis." keywords: "Generative AI, Cybersecurity, OCSF, JSON, SIEM, Compliance, Observability" tags: diff --git a/fern/versions/latest/pages/observability/overview.mdx b/fern/pages/observability/overview.mdx similarity index 100% rename from fern/versions/latest/pages/observability/overview.mdx rename to fern/pages/observability/overview.mdx diff --git a/fern/versions/latest/pages/reference/default-policy.mdx b/fern/pages/reference/default-policy.mdx similarity index 100% rename from fern/versions/latest/pages/reference/default-policy.mdx rename to fern/pages/reference/default-policy.mdx diff --git a/fern/versions/latest/pages/reference/gateway-auth.mdx b/fern/pages/reference/gateway-auth.mdx similarity index 100% rename from fern/versions/latest/pages/reference/gateway-auth.mdx rename to fern/pages/reference/gateway-auth.mdx diff --git a/fern/versions/latest/pages/reference/policy-schema.mdx b/fern/pages/reference/policy-schema.mdx similarity index 100% rename from fern/versions/latest/pages/reference/policy-schema.mdx rename to fern/pages/reference/policy-schema.mdx diff --git a/fern/versions/latest/pages/reference/support-matrix.mdx b/fern/pages/reference/support-matrix.mdx similarity index 100% rename from fern/versions/latest/pages/reference/support-matrix.mdx rename to fern/pages/reference/support-matrix.mdx diff --git a/fern/versions/latest/pages/resources/license.mdx b/fern/pages/resources/license.mdx similarity index 100% rename from fern/versions/latest/pages/resources/license.mdx rename to fern/pages/resources/license.mdx diff --git a/fern/versions/latest/pages/sandboxes/about.mdx b/fern/pages/sandboxes/about.mdx similarity index 100% rename from fern/versions/latest/pages/sandboxes/about.mdx rename to fern/pages/sandboxes/about.mdx diff --git a/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx b/fern/pages/sandboxes/community-sandboxes.mdx similarity index 100% rename from fern/versions/latest/pages/sandboxes/community-sandboxes.mdx rename to fern/pages/sandboxes/community-sandboxes.mdx diff --git a/fern/versions/latest/pages/sandboxes/manage-gateways.mdx b/fern/pages/sandboxes/manage-gateways.mdx similarity index 100% rename from fern/versions/latest/pages/sandboxes/manage-gateways.mdx rename to fern/pages/sandboxes/manage-gateways.mdx diff --git a/fern/versions/latest/pages/sandboxes/manage-providers.mdx b/fern/pages/sandboxes/manage-providers.mdx similarity index 100% rename from fern/versions/latest/pages/sandboxes/manage-providers.mdx rename to fern/pages/sandboxes/manage-providers.mdx diff --git a/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx b/fern/pages/sandboxes/manage-sandboxes.mdx similarity index 100% rename from fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx rename to fern/pages/sandboxes/manage-sandboxes.mdx diff --git a/fern/versions/latest/pages/sandboxes/policies.mdx b/fern/pages/sandboxes/policies.mdx similarity index 100% rename from fern/versions/latest/pages/sandboxes/policies.mdx rename to fern/pages/sandboxes/policies.mdx diff --git a/fern/versions/latest/pages/security/best-practices.mdx b/fern/pages/security/best-practices.mdx similarity index 100% rename from fern/versions/latest/pages/security/best-practices.mdx rename to fern/pages/security/best-practices.mdx diff --git a/fern/versions/latest/pages/tutorials/first-network-policy.mdx b/fern/pages/tutorials/first-network-policy.mdx similarity index 100% rename from fern/versions/latest/pages/tutorials/first-network-policy.mdx rename to fern/pages/tutorials/first-network-policy.mdx diff --git a/fern/versions/latest/pages/tutorials/github-sandbox.mdx b/fern/pages/tutorials/github-sandbox.mdx similarity index 100% rename from fern/versions/latest/pages/tutorials/github-sandbox.mdx rename to fern/pages/tutorials/github-sandbox.mdx diff --git a/fern/versions/latest/pages/tutorials/index.mdx b/fern/pages/tutorials/index.mdx similarity index 100% rename from fern/versions/latest/pages/tutorials/index.mdx rename to fern/pages/tutorials/index.mdx diff --git a/fern/versions/latest/pages/tutorials/inference-ollama.mdx b/fern/pages/tutorials/inference-ollama.mdx similarity index 100% rename from fern/versions/latest/pages/tutorials/inference-ollama.mdx rename to fern/pages/tutorials/inference-ollama.mdx diff --git a/fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx b/fern/pages/tutorials/local-inference-lmstudio.mdx similarity index 100% rename from fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx rename to fern/pages/tutorials/local-inference-lmstudio.mdx diff --git a/fern/versions/latest.yml b/fern/versions/latest.yml index bcd35731f..52870a581 100644 --- a/fern/versions/latest.yml +++ b/fern/versions/latest.yml @@ -5,20 +5,20 @@ navigation: slug: get-started contents: - page: "Home" - path: ./latest/pages/index.mdx + path: ../pages/index.mdx - page: "Quickstart" - path: ./latest/pages/get-started/quickstart.mdx -- folder: ./latest/pages/about + path: ../pages/get-started/quickstart.mdx +- folder: ../pages/about title: "About NVIDIA OpenShell" -- folder: ./latest/pages/tutorials -- folder: ./latest/pages/sandboxes -- folder: ./latest/pages/inference +- folder: ../pages/tutorials +- folder: ../pages/sandboxes +- folder: ../pages/inference title: "Inference Routing" -- folder: ./latest/pages/observability +- folder: ../pages/observability title: "Observability" -- folder: ./latest/pages/reference +- folder: ../pages/reference title: "Reference" -- folder: ./latest/pages/security +- folder: ../pages/security title: "Security" -- folder: ./latest/pages/resources +- folder: ../pages/resources title: "Resources" From 2ef670664e32e26704e52d90fcb4afeca68aa861 Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 16:12:29 -0700 Subject: [PATCH 6/8] use node 24 (LTS) --- .github/workflows/branch-docs.yml | 2 +- .github/workflows/release-tag.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/branch-docs.yml b/.github/workflows/branch-docs.yml index 710b9910e..7d58af83d 100644 --- a/.github/workflows/branch-docs.yml +++ b/.github/workflows/branch-docs.yml @@ -33,7 +33,7 @@ jobs: if: ${{ steps.fern-preview.outputs.enabled == 'true' }} uses: actions/setup-node@v6 with: - node-version: "20" + node-version: "24" - name: Install Fern CLI if: ${{ steps.fern-preview.outputs.enabled == 'true' }} diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml index 12e5bde5c..3535dd204 100644 --- a/.github/workflows/release-tag.yml +++ b/.github/workflows/release-tag.yml @@ -396,7 +396,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v6 with: - node-version: "20" + node-version: "24" - name: Install Fern CLI run: npm install -g fern-api From 1d9dec12db091310a15f3aca44a180ddd2cc622d Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 16:51:33 -0700 Subject: [PATCH 7/8] docs(fern): clarify getting started navigation Group tutorials under Get Started and label the homepage explore cards so readers can scan learning paths and reference material more quickly. --- fern/main.css | 27 +++++++++++++++++++++++++++ fern/pages/index.mdx | 10 ++++++++++ fern/versions/latest.yml | 3 ++- 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/fern/main.css b/fern/main.css index 138be499d..aa20a6263 100644 --- a/fern/main.css +++ b/fern/main.css @@ -552,6 +552,33 @@ svg.card-icon{ .fern-docs-badge{ border-radius: var(--rounded); } + +.explore-cards .fern-card { + display: flex; + height: 100%; +} + +.explore-cards .fern-card > div, +.explore-cards .fern-card > div > div { + display: flex; + flex: 1 1 auto; + flex-direction: column; + width: 100%; +} + +.explore-cards .fern-card p { + margin-bottom: 0.75rem; +} + +.explore-cards .fern-card .fern-docs-badge { + align-self: flex-start; + margin-top: auto; +} + +.explore-cards .fern-card br { + display: none; +} + .fern-page-actions button:hover{ background-color: transparent !important; } diff --git a/fern/pages/index.mdx b/fern/pages/index.mdx index ca0e4fb65..1570bcae3 100644 --- a/fern/pages/index.mdx +++ b/fern/pages/index.mdx @@ -91,57 +91,67 @@ Refer to the [Quickstart](/get-started/quickstart) for more details. ## Explore +
Learn about OpenShell and its capabilities. +Concept Install the CLI and create your first sandbox in two commands. +Tutorial Hands-on walkthroughs from first sandbox to custom policies. +Concept Deploy gateways, create sandboxes, configure policies, providers, and community images for your AI agents. +Concept Keep inference traffic private by routing API calls to local or self-hosted backends. +Concept Understand sandbox logs, access them via CLI and TUI, and export OCSF JSON records. +How-To Policy schema, environment variables, and system architecture. +Reference Every configurable security control, its default, and the risk of changing it. +Concept +
--- diff --git a/fern/versions/latest.yml b/fern/versions/latest.yml index 52870a581..b1058b771 100644 --- a/fern/versions/latest.yml +++ b/fern/versions/latest.yml @@ -8,9 +8,10 @@ navigation: path: ../pages/index.mdx - page: "Quickstart" path: ../pages/get-started/quickstart.mdx + - folder: ../pages/tutorials + skip-slug: true - folder: ../pages/about title: "About NVIDIA OpenShell" -- folder: ../pages/tutorials - folder: ../pages/sandboxes - folder: ../pages/inference title: "Inference Routing" From 53890891a31c7fa6b4563b8005dc040300e6c656 Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Wed, 8 Apr 2026 16:57:45 -0700 Subject: [PATCH 8/8] tweaks --- .github/workflows/branch-docs.yml | 2 +- fern/docs.yml | 4 ---- fern/pages/tutorials/index.mdx | 1 + 3 files changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/branch-docs.yml b/.github/workflows/branch-docs.yml index 7d58af83d..d49ee4c99 100644 --- a/.github/workflows/branch-docs.yml +++ b/.github/workflows/branch-docs.yml @@ -1,4 +1,4 @@ -name: Branch docs preview +name: Branch Docs Preview on: pull_request: diff --git a/fern/docs.yml b/fern/docs.yml index 46710cc4f..1bead58cb 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -71,12 +71,8 @@ redirects: destination: "/openshell/latest" - source: "/openshell/index" destination: "/openshell/latest" - - source: "/openshell/observability" - destination: "/openshell/observability/index" - source: "/openshell/latest/:path*/index.html" destination: "/openshell/latest/:path*" - - source: "/openshell/latest/observability" - destination: "/openshell/latest/observability/index" - source: "/openshell/:path*/index.html" destination: "/openshell/:path*" - source: "/openshell/:path*.html" diff --git a/fern/pages/tutorials/index.mdx b/fern/pages/tutorials/index.mdx index bb873251a..e523f46f6 100644 --- a/fern/pages/tutorials/index.mdx +++ b/fern/pages/tutorials/index.mdx @@ -1,5 +1,6 @@ --- title: "Tutorials" +slug: "tutorials" description: "Step-by-step walkthroughs for OpenShell, from first sandbox to production-ready policies." keywords: "Generative AI, Cybersecurity, Tutorial, Sandbox, Policy" tags: