diff --git a/.agents/skills/update-docs/SKILL.md b/.agents/skills/update-docs/SKILL.md index 5b68a298f..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 `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/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) | `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/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,16 +88,22 @@ 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/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`, `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. - **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 +118,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/pages/CONTRIBUTING.mdx`. +- Add the page to the appropriate section in `fern/versions/latest.yml`. ## Step 6: Present the Results @@ -123,8 +129,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/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). @@ -136,23 +142,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 +177,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..d49ee4c99 --- /dev/null +++ b/.github/workflows/branch-docs.yml @@ -0,0 +1,81 @@ +name: Branch Docs Preview + +on: + pull_request: + paths: + - "fern/**" + - ".github/workflows/branch-docs.yml" + +permissions: + contents: read + pull-requests: write + +jobs: + preview: + 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: "24" + + - 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 }} + 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 + if: ${{ steps.fern-preview.outputs.enabled == 'true' }} + 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..3535dd204 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: "24" + + - 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..a2cb194a9 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/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/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. ## Security diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ebf71df2..7adb3cc4e 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/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 `docs/CONTRIBUTING.md`. +It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `fern/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/pages/CONTRIBUTING.mdx](fern/pages/CONTRIBUTING.mdx) for the current docs authoring guide. ## Pull Requests diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 11167f48a..b77caedc7 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: + +```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: ```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,46 @@ 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`, `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" +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. +- `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. 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 +128,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 +159,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 +182,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/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/main.css b/fern/main.css index eff5dd495..aa20a6263 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; @@ -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/versions/latest/pages/CONTRIBUTING.mdx b/fern/pages/CONTRIBUTING.mdx similarity index 63% rename from fern/versions/latest/pages/CONTRIBUTING.mdx rename to fern/pages/CONTRIBUTING.mdx index cd4f2a8f1..b3eb06cbc 100644 --- a/fern/versions/latest/pages/CONTRIBUTING.mdx +++ b/fern/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/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,44 @@ 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/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: ``` {/* 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" +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. +- `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`. + ### 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 +128,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 +159,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 +182,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/pages/about/architecture.mdx similarity index 95% rename from fern/versions/latest/pages/about/architecture.mdx rename to fern/pages/about/architecture.mdx index 8f2c7bb39..4158e117f 100644 --- a/fern/versions/latest/pages/about/architecture.mdx +++ b/fern/pages/about/architecture.mdx @@ -1,6 +1,13 @@ --- title: "How OpenShell Works" +sidebar-title: "How It Works" 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/pages/about/overview.mdx similarity index 94% rename from fern/versions/latest/pages/about/overview.mdx rename to fern/pages/about/overview.mdx index c8a668d7f..9bdbf0c05 100644 --- a/fern/versions/latest/pages/about/overview.mdx +++ b/fern/pages/about/overview.mdx @@ -1,6 +1,14 @@ --- title: "Overview of NVIDIA OpenShell" +sidebar-title: "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/pages/about/release-notes.mdx similarity index 84% rename from fern/versions/latest/pages/about/release-notes.mdx rename to fern/pages/about/release-notes.mdx index 516336201..9830c28e0 100644 --- a/fern/versions/latest/pages/about/release-notes.mdx +++ b/fern/pages/about/release-notes.mdx @@ -1,6 +1,12 @@ --- title: "NVIDIA OpenShell Release Notes" +sidebar-title: "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/pages/about/supported-agents.mdx similarity index 91% rename from fern/versions/latest/pages/about/supported-agents.mdx rename to fern/pages/about/supported-agents.mdx index 0aa06e3be..10c7063fe 100644 --- a/fern/versions/latest/pages/about/supported-agents.mdx +++ b/fern/pages/about/supported-agents.mdx @@ -1,6 +1,10 @@ --- title: "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/pages/get-started/quickstart.mdx similarity index 96% rename from fern/versions/latest/pages/get-started/quickstart.mdx rename to fern/pages/get-started/quickstart.mdx index c53f1ddf0..f21390dec 100644 --- a/fern/versions/latest/pages/get-started/quickstart.mdx +++ b/fern/pages/get-started/quickstart.mdx @@ -1,6 +1,12 @@ --- title: "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/pages/index.mdx similarity index 87% rename from fern/versions/latest/pages/index.mdx rename to fern/pages/index.mdx index 2ce01eb37..1570bcae3 100644 --- a/fern/versions/latest/pages/index.mdx +++ b/fern/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 --- @@ -82,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/pages/inference/index.mdx b/fern/pages/inference/about.mdx similarity index 94% rename from fern/versions/latest/pages/inference/index.mdx rename to fern/pages/inference/about.mdx index f1e12ded8..5d2ceb390 100644 --- a/fern/versions/latest/pages/inference/index.mdx +++ b/fern/pages/inference/about.mdx @@ -1,6 +1,13 @@ --- title: "About Inference Routing" +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: + - 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/inference/configure.mdx b/fern/pages/inference/configure.mdx similarity index 97% rename from fern/versions/latest/pages/inference/configure.mdx rename to fern/pages/inference/configure.mdx index 769ff3a21..abdb5167e 100644 --- a/fern/versions/latest/pages/inference/configure.mdx +++ b/fern/pages/inference/configure.mdx @@ -1,6 +1,14 @@ --- title: "Configure Inference Routing" +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: + - 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/observability/accessing-logs.mdx b/fern/pages/observability/accessing-logs.mdx similarity index 96% rename from fern/versions/latest/pages/observability/accessing-logs.mdx rename to fern/pages/observability/accessing-logs.mdx index c0a46ecef..baadc8c92 100644 --- a/fern/versions/latest/pages/observability/accessing-logs.mdx +++ b/fern/pages/observability/accessing-logs.mdx @@ -1,6 +1,12 @@ --- title: "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/logging.mdx b/fern/pages/observability/logging.mdx similarity index 97% rename from fern/versions/latest/pages/observability/logging.mdx rename to fern/pages/observability/logging.mdx index 28c393555..abdcdfb56 100644 --- a/fern/versions/latest/pages/observability/logging.mdx +++ b/fern/pages/observability/logging.mdx @@ -1,6 +1,12 @@ --- title: "Sandbox Logging" +sidebar-title: "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/pages/observability/ocsf-json-export.mdx similarity index 96% rename from fern/versions/latest/pages/observability/ocsf-json-export.mdx rename to fern/pages/observability/ocsf-json-export.mdx index a4cec7f3d..92e85730d 100644 --- a/fern/versions/latest/pages/observability/ocsf-json-export.mdx +++ b/fern/pages/observability/ocsf-json-export.mdx @@ -1,6 +1,14 @@ --- 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: + - 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/observability/index.mdx b/fern/pages/observability/overview.mdx similarity index 82% rename from fern/versions/latest/pages/observability/index.mdx rename to fern/pages/observability/overview.mdx index 3af778a21..0cef114b9 100644 --- a/fern/versions/latest/pages/observability/index.mdx +++ b/fern/pages/observability/overview.mdx @@ -1,6 +1,14 @@ --- title: "Observability" +sidebar-title: "Overview" 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 +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/reference/default-policy.mdx b/fern/pages/reference/default-policy.mdx similarity index 88% rename from fern/versions/latest/pages/reference/default-policy.mdx rename to fern/pages/reference/default-policy.mdx index 6d23946a1..d995b9b01 100644 --- a/fern/versions/latest/pages/reference/default-policy.mdx +++ b/fern/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/pages/reference/gateway-auth.mdx similarity index 95% rename from fern/versions/latest/pages/reference/gateway-auth.mdx rename to fern/pages/reference/gateway-auth.mdx index 65422e9f4..85d72b552 100644 --- a/fern/versions/latest/pages/reference/gateway-auth.mdx +++ b/fern/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/pages/reference/policy-schema.mdx similarity index 98% rename from fern/versions/latest/pages/reference/policy-schema.mdx rename to fern/pages/reference/policy-schema.mdx index ce06984fe..e958b99f9 100644 --- a/fern/versions/latest/pages/reference/policy-schema.mdx +++ b/fern/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/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 99% rename from fern/versions/latest/pages/resources/license.mdx rename to fern/pages/resources/license.mdx index ab3ca66cb..5db1228aa 100644 --- a/fern/versions/latest/pages/resources/license.mdx +++ b/fern/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/index.mdx b/fern/pages/sandboxes/about.mdx similarity index 94% rename from fern/versions/latest/pages/sandboxes/index.mdx rename to fern/pages/sandboxes/about.mdx index a2b9dc102..1f4a21923 100644 --- a/fern/versions/latest/pages/sandboxes/index.mdx +++ b/fern/pages/sandboxes/about.mdx @@ -1,6 +1,15 @@ --- title: "About Gateways and Sandboxes" +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: + - 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/community-sandboxes.mdx b/fern/pages/sandboxes/community-sandboxes.mdx similarity index 95% rename from fern/versions/latest/pages/sandboxes/community-sandboxes.mdx rename to fern/pages/sandboxes/community-sandboxes.mdx index e743082fa..68e0398e0 100644 --- a/fern/versions/latest/pages/sandboxes/community-sandboxes.mdx +++ b/fern/pages/sandboxes/community-sandboxes.mdx @@ -1,6 +1,12 @@ --- title: "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/manage-gateways.mdx b/fern/pages/sandboxes/manage-gateways.mdx similarity index 97% rename from fern/versions/latest/pages/sandboxes/manage-gateways.mdx rename to fern/pages/sandboxes/manage-gateways.mdx index 18fb0c928..ab2eebfa9 100644 --- a/fern/versions/latest/pages/sandboxes/manage-gateways.mdx +++ b/fern/pages/sandboxes/manage-gateways.mdx @@ -1,6 +1,13 @@ --- title: "Deploy and Manage Gateways" +sidebar-title: "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/pages/sandboxes/manage-providers.mdx similarity index 97% rename from fern/versions/latest/pages/sandboxes/manage-providers.mdx rename to fern/pages/sandboxes/manage-providers.mdx index 58e67d423..9fee45794 100644 --- a/fern/versions/latest/pages/sandboxes/manage-providers.mdx +++ b/fern/pages/sandboxes/manage-providers.mdx @@ -1,6 +1,14 @@ --- title: "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: + - 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/pages/sandboxes/manage-sandboxes.mdx similarity index 96% rename from fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx rename to fern/pages/sandboxes/manage-sandboxes.mdx index fe0912d7a..42c1ff237 100644 --- a/fern/versions/latest/pages/sandboxes/manage-sandboxes.mdx +++ b/fern/pages/sandboxes/manage-sandboxes.mdx @@ -1,6 +1,14 @@ --- title: "Manage Sandboxes" +sidebar-title: "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/pages/sandboxes/policies.mdx similarity index 98% rename from fern/versions/latest/pages/sandboxes/policies.mdx rename to fern/pages/sandboxes/policies.mdx index bbff8a338..2cf585457 100644 --- a/fern/versions/latest/pages/sandboxes/policies.mdx +++ b/fern/pages/sandboxes/policies.mdx @@ -1,6 +1,14 @@ --- title: "Customize Sandbox Policies" +sidebar-title: "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/pages/security/best-practices.mdx similarity index 98% rename from fern/versions/latest/pages/security/best-practices.mdx rename to fern/pages/security/best-practices.mdx index 057c740f0..36aef6e8c 100644 --- a/fern/versions/latest/pages/security/best-practices.mdx +++ b/fern/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/pages/tutorials/first-network-policy.mdx similarity index 97% rename from fern/versions/latest/pages/tutorials/first-network-policy.mdx rename to fern/pages/tutorials/first-network-policy.mdx index 4c4b6ca7f..7f8357a29 100644 --- a/fern/versions/latest/pages/tutorials/first-network-policy.mdx +++ b/fern/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/pages/tutorials/github-sandbox.mdx similarity index 98% rename from fern/versions/latest/pages/tutorials/github-sandbox.mdx rename to fern/pages/tutorials/github-sandbox.mdx index 1e3722e67..c08bbdfab 100644 --- a/fern/versions/latest/pages/tutorials/github-sandbox.mdx +++ b/fern/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/pages/tutorials/index.mdx similarity index 90% rename from fern/versions/latest/pages/tutorials/index.mdx rename to fern/pages/tutorials/index.mdx index ebfdb1739..e523f46f6 100644 --- a/fern/versions/latest/pages/tutorials/index.mdx +++ b/fern/pages/tutorials/index.mdx @@ -1,7 +1,13 @@ --- title: "Tutorials" +slug: "tutorials" description: "Step-by-step walkthroughs for OpenShell, from first sandbox to production-ready policies." -position: 2 +keywords: "Generative AI, Cybersecurity, Tutorial, Sandbox, Policy" +tags: + - Tutorial + - Sandbox + - Policy +position: 1 --- {/* 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/inference-ollama.mdx b/fern/pages/tutorials/inference-ollama.mdx similarity index 95% rename from fern/versions/latest/pages/tutorials/inference-ollama.mdx rename to fern/pages/tutorials/inference-ollama.mdx index 6806d6741..6d83bb4f8 100644 --- a/fern/versions/latest/pages/tutorials/inference-ollama.mdx +++ b/fern/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/pages/tutorials/local-inference-lmstudio.mdx similarity index 95% rename from fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx rename to fern/pages/tutorials/local-inference-lmstudio.mdx index cb86b9b68..bea4e8cad 100644 --- a/fern/versions/latest/pages/tutorials/local-inference-lmstudio.mdx +++ b/fern/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 */} 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 1b62c64b4..b1058b771 100644 --- a/fern/versions/latest.yml +++ b/fern/versions/latest.yml @@ -1,102 +1,25 @@ # 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 - 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 - 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 - - 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/resources - title: "Resources" - title-source: frontmatter +- section: "Get Started" + slug: get-started + contents: + - page: "Home" + 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/sandboxes +- folder: ../pages/inference + title: "Inference Routing" +- folder: ../pages/observability + title: "Observability" +- folder: ../pages/reference + title: "Reference" +- folder: ../pages/security + title: "Security" +- folder: ../pages/resources + title: "Resources"