docs: add Dynamo Docs Guide and Claude Code skills (#6684)

Signed-off-by: Dan Gil <dagil@nvidia.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.claude/skills/add-dynamo-docs/SKILL.md

+---
+name: add-dynamo-docs
+description: Add a new page to the Dynamo Fern docs site. Use when creating new documentation pages.
+---
+
+# Add a Dynamo Docs Page
+
+Claude Code skill for adding a new page to the Dynamo Fern documentation site.
+
+## Related Skills
+
+| Skill | Use When |
+|-------|----------|
+| [rm-dynamo-docs](../rm-dynamo-docs/SKILL.md) | Removing an existing docs page |
+| [update-dynamo-docs](../update-dynamo-docs/SKILL.md) | Editing an existing docs page |
+
+---
+
+## Branch Rule
+
+**ALL edits happen on `main` (or a feature branch based on `main`).**
+The `docs-website` branch is CI-managed and must **never** be edited by hand.
+
+## Working Directory
+
+Must be in the `dynamo` repo (not `dynamo-tpm`). Architecture details: `docs/README.md`.
+
+## When Invoked
+
+### 1. Gather Information
+
+Ask for:
+- **Page title** — appears in the sidebar and as the H1
+- **Target section** — which sidebar section (e.g., `Getting Started`, `User Guides`, `Components`)
+- **Filename** — kebab-case `.md` file (e.g., `my-new-feature.md`)
+- **Subdirectory** — which `docs/pages/` subdirectory (e.g., `getting-started`, `features`, `components`)
+
+### 2. Create the Page
+
+Create `docs/pages/<subdirectory>/<filename>.md` with SPDX header and Fern frontmatter:
+
+```markdown
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: <Page Title>
+---
+
+# <Page Title>
+
+<!-- Content goes here -->
+```
+
+### 3. Add Navigation Entry
+
+Edit `docs/versions/dev.yml` and add the page under the correct section:
+
+```yaml
+- page: <Page Title>
+  path: ../pages/<subdirectory>/<filename>.md
+```
+
+**Section locations in `dev.yml`** (search for the comment banner):
+- `# ==================== Getting Started ====================`
+- `# ==================== Kubernetes Deployment ====================`
+- `# ==================== User Guides ====================`
+- `# ==================== Backends ====================`
+- `# ==================== Components ====================`
+- `# ==================== Integrations ====================`
+- `# ==================== Documentation ====================`
+- `# ==================== Design Docs ====================`
+- `# ==================== Blog ====================`
+- `# ==================== Hidden Pages ====================`
+
+### 4. Write Content
+
+Use standard **GitHub-flavored markdown**. For callouts, use GitHub's native syntax — CI auto-converts to Fern format:
+
+```markdown
+> [!NOTE]
+> Helpful context for the reader.
+
+> [!WARNING]
+> Something the reader should be careful about.
+
+> [!TIP]
+> A useful suggestion.
+```
+
+**Callout mapping** (GitHub → Fern):
+
+| GitHub Syntax | Fern Component |
+|---|---|
+| `> [!NOTE]` | `<Note>` |
+| `> [!TIP]` | `<Tip>` |
+| `> [!IMPORTANT]` | `<Info>` |
+| `> [!WARNING]` | `<Warning>` |
+| `> [!CAUTION]` | `<Error>` |
+
+Reference images from `docs/assets/`:
+```markdown
+![Diagram](../assets/my-diagram.png)
+```
+
+### 5. Validate
+
+```bash
+cd docs
+ln -sf . fern  # symlink required by Fern CLI
+fern check
+fern docs broken-links
+```
+
+### 6. Preview Locally (Optional)
+
+```bash
+cd docs
+fern docs dev
+```
+
+Opens a local preview at `http://localhost:3000` with hot reload. No token required.
+
+### 7. Commit
+
+```bash
+git add docs/pages/<subdirectory>/<filename>.md docs/versions/dev.yml
+git commit -s -m "docs: add <page-title> page"
+```
+
+## Debugging
+
+### `fern check` fails
+
+- **Invalid YAML in `dev.yml`:** Check indentation — nav entries use 2-space indent. A `- page:` must be inside a `contents:` block.
+- **Missing file:** The `path:` in `dev.yml` must match the actual file location. Paths are relative to `docs/versions/` (e.g., `../pages/getting-started/quickstart.md`).
+
+### `fern docs broken-links` reports errors
+
+- **Broken internal link:** A markdown link reference points to a file that doesn't exist. Fix the path or remove the link.
+- **Anchor not found:** A `#section-heading` link doesn't match any heading in the target page.
+
+### CI fails after merge
+
+- **MDX parse error:** Angle-bracket URLs like `<https://example.com>` break MDX parsing. Use `[text](https://example.com)` instead.
+- **Broken links check:** The `detect_broken_links.py` job checks relative links across all docs. If your new page links to a file that doesn't exist yet, CI will fail.
+- **Fern publish error:** Check the Actions tab for the `Fern Docs` workflow. Common causes: expired `FERN_TOKEN`, invalid `docs.yml` syntax, or a file referenced in `dev.yml` that wasn't synced to `docs-website`.
+
+### Page doesn't appear on the live site
+
+- **Missing nav entry:** The page exists but isn't in `docs/versions/dev.yml`. Add it.
+- **Hidden section:** The page is inside a `hidden: true` section. It's accessible by direct URL but won't appear in the sidebar.
+- **Sync delay:** After merge to `main`, the sync-dev workflow takes a few minutes to publish.
+
+## Key References
+
+| File | Purpose |
+|------|---------|
+| `docs/versions/dev.yml` | Navigation tree — add entries here |
+| `docs/pages/` | Content directory — create pages here |
+| `docs/assets/` | Images, SVGs, fonts |
+| `docs/convert_callouts.py` | Callout conversion rules (GitHub → Fern) |
+| `docs/README.md` | Full architecture guide |

.claude/skills/rm-dynamo-docs/SKILL.md

+---
+name: rm-dynamo-docs
+description: Remove a page from the Dynamo Fern docs site. Use when deleting documentation pages.
+---
+
+# Remove a Dynamo Docs Page
+
+Claude Code skill for removing a page from the Dynamo Fern documentation site.
+
+## Related Skills
+
+| Skill | Use When |
+|-------|----------|
+| [add-dynamo-docs](../add-dynamo-docs/SKILL.md) | Adding a new docs page |
+| [update-dynamo-docs](../update-dynamo-docs/SKILL.md) | Editing an existing docs page |
+
+---
+
+## Branch Rule
+
+**ALL edits happen on `main` (or a feature branch based on `main`).**
+The `docs-website` branch is CI-managed and must **never** be edited by hand.
+
+## Working Directory
+
+Must be in the `dynamo` repo (not `dynamo-tpm`). Architecture details: `docs/README.md`.
+
+## When Invoked
+
+### 1. Identify the Page
+
+Ask for the page to remove (accepts any of):
+- File path (e.g., `docs/pages/guides/old-page.md`)
+- Page title (e.g., "Old Page")
+- Topic keyword to search for
+
+If given a title or keyword, search for the page:
+```bash
+# Search by title in navigation
+grep -n "<title>" docs/versions/dev.yml
+
+# Search by keyword in content
+grep -rl "<keyword>" docs/pages/
+```
+
+### 2. Find the Navigation Entry
+
+Locate the page's entry in `docs/versions/dev.yml`:
+
+```bash
+grep -n "<filename>" docs/versions/dev.yml
+```
+
+Note the exact `- page:` block and its indentation level. If the page is the
+sole entry in a `- section:` block, the entire section should be removed.
+
+### 3. Check for Incoming Links
+
+Search for references to this page from other docs:
+
+```bash
+# Search for the filename across all docs pages
+grep -r "<filename>" docs/pages/ --include="*.md"
+
+# Also check the navigation file for any cross-references
+grep -r "<filename>" docs/versions/
+```
+
+Report any files that link to the page being removed — these links will break
+and need updating.
+
+### 4. Remove the Markdown File
+
+```bash
+git rm docs/pages/<subdirectory>/<filename>.md
+```
+
+### 5. Remove the Navigation Entry
+
+Edit `docs/versions/dev.yml` and delete the `- page:` block (and its `path:`
+line). If this was the last page in a section, remove the entire `- section:`
+block.
+
+### 6. Fix Broken Incoming Links
+
+For each file that linked to the removed page:
+- Remove the link, or
+- Redirect to a replacement page, or
+- Leave a note about the removal
+
+### 7. Validate
+
+```bash
+cd docs
+ln -sf . fern  # symlink required by Fern CLI
+fern check
+fern docs broken-links
+```
+
+### 8. Preview Locally (Optional)
+
+```bash
+cd docs
+fern docs dev
+```
+
+Opens a local preview at `http://localhost:3000` with hot reload. No token required.
+
+### 9. Commit
+
+```bash
+git add -u docs/
+git commit -s -m "docs: remove <page-title> page"
+```
+
+## Debugging
+
+### `fern check` fails
+
+- **Orphaned nav entry:** You deleted the file but left the `- page:` entry in `dev.yml`. Remove it.
+- **Empty section:** If the removed page was the only entry in a section, delete the entire `- section:` block from `dev.yml`.
+
+### `fern docs broken-links` reports errors
+
+- **Incoming links to removed page:** Other pages still link to the deleted file. Search with `grep -r "<filename>" docs/pages/` and update or remove those links.
+
+### CI fails after merge
+
+- **MDX parse error:** Angle-bracket URLs like `<https://example.com>` break MDX parsing. Use `[text](https://example.com)` instead.
+- **Broken links check:** The `detect_broken_links.py` job found pages that still reference the removed file. Fix all incoming links before merging.
+- **Fern publish error:** Check the Actions tab for the `Fern Docs` workflow. Common causes: expired `FERN_TOKEN`, invalid `docs.yml` syntax.
+
+### Page still appears on the live site
+
+- **Sync delay:** After merge to `main`, the sync-dev workflow takes a few minutes to publish.
+- **Cached version:** Fern CDN may cache the old page briefly. Hard-refresh or wait a few minutes.
+
+## Key References
+
+| File | Purpose |
+|------|---------|
+| `docs/versions/dev.yml` | Navigation tree — remove entries here |
+| `docs/pages/` | Content directory — delete pages here |
+| `docs/README.md` | Full architecture guide |

.claude/skills/update-dynamo-docs/SKILL.md

+---
+name: update-dynamo-docs
+description: Update an existing page in the Dynamo Fern docs site. Use when editing content, titles, or moving pages between sections.
+---
+
+# Update a Dynamo Docs Page
+
+Claude Code skill for updating an existing page in the Dynamo Fern documentation site.
+
+## Related Skills
+
+| Skill | Use When |
+|-------|----------|
+| [add-dynamo-docs](../add-dynamo-docs/SKILL.md) | Adding a new docs page |
+| [rm-dynamo-docs](../rm-dynamo-docs/SKILL.md) | Removing an existing docs page |
+
+---
+
+## Branch Rule
+
+**ALL edits happen on `main` (or a feature branch based on `main`).**
+The `docs-website` branch is CI-managed and must **never** be edited by hand.
+
+## Working Directory
+
+Must be in the `dynamo` repo (not `dynamo-tpm`). Architecture details: `docs/README.md`.
+
+## When Invoked
+
+### 1. Locate the Page
+
+Ask for the page to update (accepts any of):
+- File path (e.g., `docs/pages/guides/quickstart.md`)
+- Page title (e.g., "Quickstart")
+- Topic keyword to search for
+
+If given a title or keyword, find the page:
+```bash
+# Search by title in navigation
+grep -n "<title>" docs/versions/dev.yml
+
+# Search by keyword in content
+grep -rl "<keyword>" docs/pages/
+```
+
+### 2. Read Current Content
+
+Read the page and its navigation entry:
+- The markdown file in `docs/pages/`
+- The corresponding entry in `docs/versions/dev.yml`
+
+Note the current:
+- **Title** (from frontmatter `title:` field)
+- **Section** (which sidebar section it belongs to)
+- **Path** (relative path in `dev.yml`)
+
+### 3. Apply Edits
+
+Handle three types of changes:
+
+#### Content Only
+
+Edit the markdown file directly. No navigation changes needed.
+
+#### Title Change
+
+1. Update the `title:` field in the markdown frontmatter
+2. Update the `- page:` display name in `docs/versions/dev.yml`
+
+#### Section Move
+
+1. Move the markdown file to the new subdirectory:
+   ```bash
+   git mv docs/pages/<old-subdir>/<file>.md docs/pages/<new-subdir>/<file>.md
+   ```
+2. Remove the old `- page:` entry from `dev.yml`
+3. Add a new `- page:` entry under the target section in `dev.yml`
+4. Update the `path:` to reflect the new location
+
+### 4. Check Incoming Links (If Path Changed)
+
+If the file was moved, search for references that need updating:
+
+```bash
+# Search for the old path across all docs
+grep -r "<old-filename>" docs/pages/ --include="*.md"
+grep -r "<old-filename>" docs/versions/
+```
+
+Update all references to point to the new path.
+
+### 5. Content Guidelines
+
+Use standard **GitHub-flavored markdown**. For callouts, use GitHub's native syntax — CI auto-converts to Fern format:
+
+```markdown
+> [!NOTE]
+> Helpful context for the reader.
+
+> [!WARNING]
+> Something the reader should be careful about.
+```
+
+**Callout mapping** (GitHub → Fern):
+
+| GitHub Syntax | Fern Component |
+|---|---|
+| `> [!NOTE]` | `<Note>` |
+| `> [!TIP]` | `<Tip>` |
+| `> [!IMPORTANT]` | `<Info>` |
+| `> [!WARNING]` | `<Warning>` |
+| `> [!CAUTION]` | `<Error>` |
+
+### 6. Validate
+
+```bash
+cd docs
+ln -sf . fern  # symlink required by Fern CLI
+fern check
+fern docs broken-links
+```
+
+### 7. Preview Locally (Optional)
+
+```bash
+cd docs
+fern docs dev
+```
+
+Opens a local preview at `http://localhost:3000` with hot reload. No token required.
+
+### 8. Commit
+
+```bash
+git add docs/pages/ docs/versions/dev.yml
+git commit -s -m "docs: update <page-title>"
+```
+
+## Debugging
+
+### `fern check` fails
+
+- **Invalid YAML in `dev.yml`:** Check indentation — nav entries use 2-space indent. A `- page:` must be inside a `contents:` block.
+- **Missing file:** If you moved a page, the `path:` in `dev.yml` must match the new location.
+- **Duplicate entry:** The same page appears twice in `dev.yml`. Remove the old entry after a section move.
+
+### `fern docs broken-links` reports errors
+
+- **Stale internal links:** After moving or renaming a page, other pages may still link to the old path. Search with `grep -r "<old-filename>" docs/pages/` and update references.
+- **Anchor not found:** A `#section-heading` link doesn't match any heading in the target page. Check if the heading text changed.
+
+### CI fails after merge
+
+- **MDX parse error:** Angle-bracket URLs like `<https://example.com>` break MDX parsing. Use `[text](https://example.com)` instead.
+- **Broken links check:** The `detect_broken_links.py` job found stale references to the old path. Fix all incoming links before merging.
+- **Fern publish error:** Check the Actions tab for the `Fern Docs` workflow. Common causes: expired `FERN_TOKEN`, invalid `docs.yml` syntax, or a moved file that wasn't synced to `docs-website`.
+
+### Changes don't appear on the live site
+
+- **Title mismatch:** You updated the frontmatter `title:` but not the `- page:` name in `dev.yml` (or vice versa). Keep them in sync.
+- **Sync delay:** After merge to `main`, the sync-dev workflow takes a few minutes to publish.
+
+## Key References
+
+| File | Purpose |
+|------|---------|
+| `docs/versions/dev.yml` | Navigation tree — update entries here if title/path changes |
+| `docs/pages/` | Content directory — edit pages here |
+| `docs/assets/` | Images, SVGs, fonts |
+| `docs/convert_callouts.py` | Callout conversion rules (GitHub → Fern) |
+| `docs/README.md` | Full architecture guide |

.github/workflows/fern-docs.yml

@@ -196,6 +196,11 @@ jobs:
           echo "Syncing fern.config.json to docs-website branch..."
           cp source-checkout/docs/fern.config.json docs-checkout/fern/fern.config.json
 
+          # Sync docs/README.md (developer guide, referenced from dev.yml)
+          if [ -f source-checkout/docs/README.md ]; then
+            cp source-checkout/docs/README.md docs-checkout/fern/README.md
+          fi
+
           # Sync .gitignore if it exists
           if [ -f source-checkout/docs/.gitignore ]; then
             cp source-checkout/docs/.gitignore docs-checkout/fern/.gitignore

docs/pages/README.md

----
-# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-title: Building Documentation
----
-
-This directory contains the documentation source files for NVIDIA Dynamo.
-
-## Prerequisites
-
-- Python 3.11 or later
-- [uv](https://docs.astral.sh/uv/) package manager
-
-## Build Instructions
-
-### Option 1: Dedicated Docs Environment (Recommended)
-
-This approach builds the docs without requiring the full project dependencies (including `ai-dynamo-runtime`):
-
-```bash
-# One-time setup: Create docs environment and install dependencies
-uv venv .venv-docs
-uv pip install --python .venv-docs --group docs
-
-# Generate documentation
-uv run --python .venv-docs --no-project docs/generate_docs.py
-```
-
-The generated HTML will be available in `docs/build/html/`.
-
-### Option 2: Using Full Development Environment
-
-If you already have the full project dependencies installed (i.e., you're actively developing the codebase), you can use `uv run` directly:
-
-```bash
-uv run --group docs docs/generate_docs.py
-```
-
-This will use your existing project environment and add the docs dependencies.
-
-### Option 3: Using Docker
-
-Build the docs in a Docker container with all dependencies isolated:
-
-```bash
-docker build -f container/Dockerfile.docs -t dynamo-docs .
-```
-
-The documentation will be built inside the container. To extract the built docs:
-
-```bash
-# Run the container and copy the output
-docker run --rm -v $(pwd)/docs/build:/workspace/dynamo/docs/build dynamo-docs
-
-# Or create a container to copy files from
-docker create --name temp-docs dynamo-docs
-docker cp temp-docs:/workspace/dynamo/docs/build ./docs/build
-docker rm temp-docs
-```
-
-This approach is ideal for CI/CD pipelines or when you want complete isolation from your local environment.
-
-## Directory Structure
-
-- `docs/` - Documentation source files (Markdown and reStructuredText)
-- `docs/conf.py` - Sphinx configuration
-- `docs/_static/` - Static assets (CSS, JS, images)
-- `docs/_extensions/` - Custom Sphinx extensions
-- `docs/build/` - Generated documentation output (not tracked in git)
-
-## Redirect Creation
-
-When moving or renaming files a redirect must be created.
-
-Redirect entries should be added to the `redirects` dictionary in `conf.py`. For detailed information on redirect syntax, see the [sphinx-reredirects usage documentation](https://documatt.com/sphinx-reredirects/usage/#introduction).
-
-## Dependency Management
-
-Documentation dependencies are defined in `pyproject.toml` under the `[dependency-groups]` section:
-
-```toml
-[dependency-groups]
-docs = [
-    "sphinx>=8.1",
-    "nvidia-sphinx-theme>=0.0.8",
-    # ... other doc dependencies
-]
-```
-
-## Troubleshooting
-
-### Build Warnings
-
-The build process treats warnings as errors. Common issues:
-
-- **Missing toctree entries**: Documents must be referenced in a table of contents
-- **Non-consecutive headers**: Don't skip header levels (e.g., H1 → H3)
-- **Broken links**: Ensure all internal and external links are valid
-
-### Missing Dependencies
-
-If you encounter import errors, ensure the docs dependencies are installed:
-
-```bash
-uv pip install --python .venv-docs --group docs
-```
-
-## Viewing the Documentation
-
-After building, open `docs/build/html/index.html` in your, or use Python's built-in HTTP server:
-
-```bash
-cd docs/build/html
-python -m http.server 8000
-# Then visit http://localhost:8000 in your browser
-```

docs/pages/templates/README.md

@@ -175,4 +175,4 @@ After adding new documentation:
 1. **Sphinx (current):** Update `docs/index.rst` or the appropriate `_sections/*.rst` file to include your new docs in the navigation
 2. **Fern (future):** Update `fern/docs.yml` with your new pages
 
-See [docs/README.md](../README.md) for documentation build instructions.
+See [docs/README.md](../../README.md) for documentation build instructions.

docs/versions/dev.yml

@@ -224,6 +224,7 @@ navigation:
 
   # ==================== Blog ====================
   - section: Blog
+    hidden: true
     path: ../blogs/index.mdx
     slug: blog
     contents:
@@ -231,6 +232,12 @@ navigation:
         path: ../blogs/flash-indexer/flash-indexer.md
         slug: flash-indexer
 
+  # ==================== Documentation ====================
+  - section: Documentation
+    contents:
+      - page: Dynamo Docs Guide
+        path: ../README.md
+
   # ==================== Hidden Pages ====================
   # Pages accessible via direct URL but not shown in main navigation.
   # Matches Sphinx hidden_toctree.rst -- pages linked from within content
@@ -322,9 +329,6 @@ navigation:
       # -- Mocker --
       - page: Mocker
         path: ../pages/mocker/mocker.md
-      # -- Docs README --
-      - page: Building Documentation
-        path: ../pages/README.md
       # -- Templates --
       - section: Templates
         path: ../pages/templates/README.md