docs: fix docs build and add migration skill (#148)

#### Overview

Fix the documentation build configuration and add a migration skill for updating NeMo Flow references and APIs to NeMo Relay.

- [x] I confirm this contribution is my own work, or I have the right to submit it under this project's license.
- [x] I searched existing issues and open pull requests, and this does not duplicate existing work.

#### Details

- Adds blame-ignore entries for repository-wide rename and migration revisions.
- Updates `docs/conf.py` so generated API docs build cleanly with the renamed package surfaces.
- Registers the new migration skill in `skills/README.md`.
- Adds `skills/nemo-relay-migrate-from-flow/` with workflow guidance and a helper script for migrating NeMo Flow names, imports, package references, and docs text to NeMo Relay.
- Validation: `just docs` passed.
- Breaking changes: none.

#### Where should the reviewer start?

Start with `docs/conf.py` for the docs-build behavior, then review `skills/nemo-relay-migrate-from-flow/SKILL.md` and `skills/nemo-relay-migrate-from-flow/scripts/migrate_from_nemo_flow.py` for the migration workflow and helper implementation.

#### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

- Relates to: none




## Summary by CodeRabbit

## Release Notes

* **New Features**
  * Added an automated migration tool to help transition NeMo Flow codebases to NeMo Relay, supporting identifier renaming, file path restructuring, and verification workflows.

* **Documentation**
  * Added comprehensive migration skill documentation with step-by-step instructions, language-specific cleanup guidance, and best practices for upgrading from NeMo Flow to NeMo Relay.



[![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NeMo-Relay/pull/148?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

Authors:
  - Will Killian (https://github.com/willkill07)

Approvers:
  - David Gardner (https://github.com/dagardner-nv)

URL: #148

Author: willkill07

.git-blame-ignore-revs

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# refactor: rename to NeMo Relay (#141)
+8f096e7f7aac9a7bcad069bae310c37a7499a802

docs/conf.py

@@ -10,11 +10,38 @@
 import shutil
 import subprocess
 from pathlib import Path
+from typing import NamedTuple
 
 import sphinx_js
 from packaging.version import InvalidVersion, Version
 
-project = "NVIDIA NeMo Relay"
+
+class _RuntimeDocsProfile(NamedTuple):
+    project_title: str
+    github_url: str
+    python_module: str
+    rust_core_crate: str
+    rust_adaptive_crate: str
+
+
+_RELAY_RUNTIME_DOCS_PROFILE = _RuntimeDocsProfile(
+    project_title="NVIDIA NeMo Relay",
+    github_url="https://github.com/NVIDIA/NeMo-Relay",
+    python_module="nemo_relay",
+    rust_core_crate="nemo-relay",
+    rust_adaptive_crate="nemo-relay-adaptive",
+)
+_FLOW_RUNTIME_DOCS_PROFILE = _RuntimeDocsProfile(
+    project_title="NVIDIA NeMo Flow",
+    github_url="https://github.com/NVIDIA/NeMo-Flow",
+    python_module="nemo_flow",
+    rust_core_crate="nemo-flow",
+    rust_adaptive_crate="nemo-flow-adaptive",
+)
+_DEFAULT_RUNTIME_DOCS_PROFILE = _RELAY_RUNTIME_DOCS_PROFILE
+
+
+project = _DEFAULT_RUNTIME_DOCS_PROFILE.project_title
 copyright = "Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved."
 author = "NVIDIA CORPORATION & AFFILIATES"
 
@@ -112,7 +139,7 @@
 rust_generate_mode = "always"
 
 html_theme = "nvidia_sphinx_theme"
-html_title = "NVIDIA NeMo Relay"
+html_title = _DEFAULT_RUNTIME_DOCS_PROFILE.project_title
 html_static_path = ["_static"]
 html_css_files = ["extra.css"]
 html_js_files = ["version-switcher.js"]
@@ -129,7 +156,7 @@
     "icon_links": [
         {
             "name": "GitHub",
-            "url": "https://github.com/NVIDIA/NeMo-Relay",
+            "url": _DEFAULT_RUNTIME_DOCS_PROFILE.github_url,
             "icon": "fa-brands fa-github",
         }
     ],
@@ -363,11 +390,41 @@ def _resolve_runtime_paths(source_docs_dir: Path) -> None:
     SPHINX_JS_WORK_DIR = DOCS_DIR / "_build" / ".tooling" / "sphinx-js"
 
 
+def _detect_runtime_docs_profile(repo_root: Path) -> _RuntimeDocsProfile:
+    # sphinx-multiversion runs the current conf.py against historical source
+    # trees, so API package names must come from the source tree being built.
+    if (repo_root / "python" / _RELAY_RUNTIME_DOCS_PROFILE.python_module).is_dir():
+        return _RELAY_RUNTIME_DOCS_PROFILE
+    if (repo_root / "python" / _FLOW_RUNTIME_DOCS_PROFILE.python_module).is_dir():
+        return _FLOW_RUNTIME_DOCS_PROFILE
+
+    raise RuntimeError(
+        "Unable to locate a Python package for docs generation. "
+        f"Expected {repo_root / 'python' / _RELAY_RUNTIME_DOCS_PROFILE.python_module} "
+        f"or {repo_root / 'python' / _FLOW_RUNTIME_DOCS_PROFILE.python_module}."
+    )
+
+
+def _with_runtime_github_url(theme_options, github_url: str):
+    updated_options = dict(theme_options)
+    icon_links = [dict(link) for link in updated_options.get("icon_links", [])]
+    for link in icon_links:
+        if link.get("name") == "GitHub":
+            link["url"] = github_url
+            break
+    updated_options["icon_links"] = icon_links
+    return updated_options
+
+
 def _wire_runtime_config(config) -> None:
-    config.autoapi_dirs = [str(REPO_ROOT / "python" / "nemo_relay")]
+    profile = _detect_runtime_docs_profile(REPO_ROOT)
+    config.project = profile.project_title
+    config.html_title = profile.project_title
+    config.html_theme_options = _with_runtime_github_url(config.html_theme_options, profile.github_url)
+    config.autoapi_dirs = [str(REPO_ROOT / "python" / profile.python_module)]
     config.rust_crates = {
-        "nemo-relay": str(RUST_API_SOURCE_DIR / "core"),
-        "nemo-relay-adaptive": str(RUST_API_SOURCE_DIR / "adaptive"),
+        profile.rust_core_crate: str(RUST_API_SOURCE_DIR / "core"),
+        profile.rust_adaptive_crate: str(RUST_API_SOURCE_DIR / "adaptive"),
     }
     config.rust_doc_dir = str(RUST_API_GENERATED_DIR)
 
@@ -465,7 +522,7 @@ def _nemo_relay_mangle_signature(sig: str, *args, **kwargs) -> str:
 
 
 def _skip_imported_type_aliases(_app, what, _name, obj, skip, _options):
-    if what == "module" and getattr(obj, "id", None) == "nemo_relay._native":
+    if what == "module" and getattr(obj, "id", None) in {"nemo_relay._native", "nemo_flow._native"}:
         return False
 
     if skip:

skills/README.md

@@ -19,6 +19,7 @@ documentation, embed those details directly in the skill.
 Use these skills for tasks such as:
 
 - Getting started with a binding
+- Migrating NeMo Flow codebases to NeMo Relay
 - Instrumenting tool and LLM calls
 - Choosing the current primary documentation track: Rust, Python, or Node.js
 - Tuning performance with adaptive features

skills/nemo-relay-migrate-from-flow/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: nemo-relay-migrate-from-flow
+description: Migrate applications, examples, integrations, documentation, package manifests, and repository code from NeMo Flow naming and packages to NeMo Relay across Python, Rust, Node.js, Go, WebAssembly, C FFI, CLI, config, and observability surfaces; use when a user asks to rename nemo_flow/nemo-flow/NeMo Flow APIs, automate a migration, update imports or dependencies, or validate a Flow-to-Relay conversion
+license: Apache-2.0
+---
+
+# Migrate From NeMo Flow To NeMo Relay
+
+Use this skill when a user has existing NeMo Flow code or documentation and
+wants it converted to NeMo Relay. Treat the migration as a mechanical rename
+plus language-specific validation, not a behavior rewrite.
+
+## Default Workflow
+
+1. Inspect the working tree and identify touched surfaces: Rust, Python,
+   Node.js, Go, WebAssembly, C FFI, CLI/config, docs, or integration patches.
+2. Run the bundled helper in dry-run mode before editing:
+   `python skills/nemo-relay-migrate-from-flow/scripts/migrate_from_nemo_flow.py <path> --rename-paths`
+3. Review the reported text edits and path renames. If the scope is correct,
+   rerun with `--write --rename-paths`.
+4. Apply language-specific cleanup for package manager lockfiles, generated
+   artifacts, and public API examples.
+5. Search for remaining Flow names and verify the affected language surfaces.
+
+## Mechanical Rename Map
+
+- Brand and repository: `NeMo Flow` -> `NeMo Relay`,
+  `NeMo-Flow` -> `NeMo-Relay`
+- Python: `nemo-flow` -> `nemo-relay`, `nemo_flow` -> `nemo_relay`,
+  `python/nemo_flow` -> `python/nemo_relay`
+- Rust: `nemo-flow` -> `nemo-relay`, `nemo-flow-adaptive` ->
+  `nemo-relay-adaptive`, `nemo_flow::` -> `nemo_relay::`
+- Node.js and WebAssembly: `nemo-flow-node` -> `nemo-relay-node`,
+  `nemo-flow-wasm` -> `nemo-relay-wasm`, and related entry points such as
+  `/typed`, `/plugin`, `/adaptive`, and `/observability`
+- Go: `github.com/NVIDIA/NeMo-Flow/go/nemo_flow` ->
+  `github.com/NVIDIA/NeMo-Relay/go/nemo_relay`, package aliases
+  `nemo_flow` -> `nemo_relay`, and source directories `go/nemo_flow` ->
+  `go/nemo_relay`
+- C FFI: `nemo_flow.h` -> `nemo_relay.h`, `nemo_flow_*` ->
+  `nemo_relay_*`, `NemoFlow*` -> `NemoRelay*`, and `NEMO_FLOW_*` ->
+  `NEMO_RELAY_*`
+- CLI/config: `nemo-flow` -> `nemo-relay`, `.nemo-flow` -> `.nemo-relay`,
+  `~/.config/nemo-flow` -> `~/.config/nemo-relay`, `NEMO_FLOW_*` ->
+  `NEMO_RELAY_*`, and `x-nemo-flow-*` -> `x-nemo-relay-*`
+
+Do not replace bare `flow`, `Flow`, or `FlowError`. Those can be domain words
+or intentional compatibility names.
+
+## Language Cleanup
+
+- **Python**: update `pyproject.toml`, imports, type stubs, integration
+  package paths, extras, and native module names. Regenerate or refresh lockfiles
+  with the user's package workflow after source edits.
+- **Rust**: update `Cargo.toml` crate names, workspace dependencies, package
+  references, and `use nemo_relay::...` imports. Let Cargo regenerate
+  `Cargo.lock` when dependencies changed.
+- **Node.js**: update `package.json`, workspace names, package-lock entries,
+  native addon artifact names, and imports from `nemo-relay-node` or
+  `nemo-relay-wasm`. Run the package manager to refresh locks.
+- **Go**: update `go.mod`, import paths, package declarations, aliases, and any
+  local directory layout under `go/nemo_relay`.
+- **C FFI**: update header includes, exported symbol names, status and callback
+  type names, macro constants, loader paths, and downstream bindings.
+- **Docs and examples**: update badges, package install commands, repository
+  links, hosted docs URLs, CLI commands, config paths, and integration patch
+  names.
+
+## Automation Helper
+
+Use `scripts/migrate_from_nemo_flow.py` for first-pass edits. It:
+
+- runs as a dry run unless `--write` is passed
+- skips common vendor, build, cache, and generated directories
+- skips lockfiles unless `--include-lockfiles` is passed
+- can report or perform path renames with `--rename-paths`
+- rewrites only explicit NeMo Flow identifiers, package names, repository names,
+  config paths, headers, environment variables, and FFI type prefixes
+
+Run it from either the source repository or the user's target project:
+
+```bash
+python skills/nemo-relay-migrate-from-flow/scripts/migrate_from_nemo_flow.py . --rename-paths
+python skills/nemo-relay-migrate-from-flow/scripts/migrate_from_nemo_flow.py . --write --rename-paths
+```
+
+Use `--include-lockfiles` only when the user wants lockfiles edited directly;
+otherwise regenerate them with Cargo, uv/pip, npm, or Go tooling.
+
+## Verification
+
+- Search for remaining explicit Flow identifiers:
+  `rg -n "NeMo Flow|NeMo-Flow|nemo_flow|nemo-flow|NEMO_FLOW|NemoFlow|nemo_flow\\.h|nemo_flow_"`
+- Run targeted tests for every affected language surface.
+- For Rust changes, run `cargo test` or the repository's Rust test recipe.
+- For Python changes, run the relevant import check and tests in the target
+  environment.
+- For Node.js or WebAssembly changes, run package install, type checks, and
+  package tests.
+- For Go changes, run `go test ./...` from the updated module.
+- For docs-only migrations, build or link-check docs if the site navigation,
+  install commands, or API references changed.
+
+## Related Skills
+
+- `nemo-relay-start`
+- `nemo-relay-instrument-calls`
+- `nemo-relay-debug-runtime-integration`