chore: address coderabbit feedback

willkill07 · willkill07 · commit 1ab2cb999003 · 2026-05-26T09:13:46.000-04:00
Signed-off-by: Will Killian &lt;wkillian@nvidia.com&gt;
diff --git a/.agents/skills/contribute-docs/SKILL.md b/.agents/skills/contribute-docs/SKILL.md
@@ -26,13 +26,17 @@ Use this skill for docs-only or example-heavy changes.
 - Keep stable user-facing wrappers at `scripts/` root in docs and examples;
   only point at namespaced helper paths when documenting internal maintenance
   work
+- In MDX files, top-of-file comments must use JSX comment delimiters:
+  `{/*` to open and `*/}` to close. Do not use HTML comments for MDX SPDX
+  headers.
 
 ## Checklist
 
 - [ ] `README.md` or `docs/index.md` updated when entry points changed
 - [ ] Relevant getting-started or reference docs updated
 - [ ] Example commands still match current package names and paths
 - [ ] Relevant package or crate `README.md` files updated when examples or binding guidance changed
+- [ ] New or regenerated MDX files use `{/* ... */}` for top-of-file SPDX comments
 - [ ] Release-policy docs still point to GitHub Releases as the only release-history source of truth
 - [ ] Run `just docs` when the docs site changed; `./scripts/build-docs.sh html` remains the compatibility wrapper
 
diff --git a/.agents/skills/review-doc-style/SKILL.md b/.agents/skills/review-doc-style/SKILL.md
@@ -47,6 +47,8 @@ Treat these as blocking issues:
 - A doc claims support for a binding, feature, or workflow that the repo no longer provides
 - Examples or procedures are likely to fail as written
 - User-facing naming is inconsistent with current repo terminology
+- MDX top-of-file SPDX comments use HTML comment delimiters instead of
+  `{/* ... */}`
 - NVIDIA is not capitalized correctly
 - Code, commands, paths, or filenames are not formatted as inline code where needed
 
@@ -71,6 +73,7 @@ Flag these when they materially improve clarity or consistency:
 - **Voice**: Prefer active voice, present tense, short sentences, and plain English.
 - **Links**: Use descriptive anchor text, not bare URLs or weak labels.
 - **Formatting**: Commands, code elements, expressions, file names, and paths are monospace.
+- **MDX headers**: Top-of-file MDX SPDX comments use `{/*` and `*/}` delimiters.
 - **Procedures**: Steps are easy to scan, imperative, and split into smaller tasks when long.
 - **Examples**: Code blocks are introduced by full sentences and match current APIs and build commands.
 - **Terminology**: Use consistent terms throughout the document.
diff --git a/.github/ci-path-filters.yml b/.github/ci-path-filters.yml
@@ -111,6 +111,7 @@ dependencies:
 docs:
   - 'CONTRIBUTING.md'
   - 'README.md'
+  - 'docs/**'
   - 'Cargo.lock'
   - 'Cargo.toml'
   - 'crates/adaptive/src/**'
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -151,6 +151,8 @@ jobs:
       }}
     permissions:
       contents: read
+    secrets:
+      DOCS_FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }}
 
   ci_rust:
     name: Rust
diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml
@@ -4,7 +4,10 @@
 name: Documentation
 
 on:
-  workflow_call: {}
+  workflow_call:
+    secrets:
+      DOCS_FERN_TOKEN:
+        required: false
 defaults:
   run:
     shell: bash
diff --git a/.github/workflows/fern-docs.yml b/.github/workflows/fern-docs.yml
@@ -276,7 +276,7 @@ jobs:
         working-directory: docs-checkout
         run: |
           set -euo pipefail
-          if git diff --quiet && git diff --cached --quiet; then
+          if [[ -z "$(git status --porcelain --untracked-files=all)" ]]; then
             echo "has_changes=false" >> "$GITHUB_OUTPUT"
           else
             echo "has_changes=true" >> "$GITHUB_OUTPUT"
@@ -321,10 +321,13 @@ jobs:
     steps:
       - name: Determine version tag
         id: version
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_TAG: ${{ inputs.tag }}
         run: |
           set -euo pipefail
-          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            tag="${{ inputs.tag }}"
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            tag="$INPUT_TAG"
           else
             tag="${GITHUB_REF_NAME}"
           fi
diff --git a/RELEASING.md b/RELEASING.md
@@ -164,7 +164,7 @@ Review docs and snippets that mention explicit versions, including:
 
 - [`README.md`](README.md)
 - [`CONTRIBUTING.md`](CONTRIBUTING.md)
-- [`fern/versions/dev/pages/getting-started/installation.mdx`](fern/versions/dev/pages/getting-started/installation.mdx)
+- [`docs/getting-started/installation.mdx`](docs/getting-started/installation.mdx)
 - Any binding README or example that pins a release number
 
 Do not commit a static Python package version into `pyproject.toml` just to cut
diff --git a/docs/about/concepts/subscribers.mdx b/docs/about/concepts/subscribers.mdx
@@ -76,7 +76,7 @@ scopes, LLM calls, tool calls, or marks. NeMo Relay emits the canonical ATOF eve
 stream, and each subscriber chooses whether to consume the native event object,
 the canonical JSON helper, or an exporter-specific translation.
 
-```{mermaid}
+```mermaid
 flowchart
     Host[Host Integration]
 
diff --git a/docs/about/release-notes/known-issues.mdx b/docs/about/release-notes/known-issues.mdx
@@ -17,8 +17,6 @@ These notes apply to the NeMo Relay 0.3 Release.
 - Generated API pages cover Rust, Python, and Node.js. Experimental bindings do not yet have the same generated documentation depth.
 - The NeMo Relay CLI is experimental. Coding agent observability support varies due to capabilities of hooks. Any encountered problems should be filed as bugs.
 
-### Fixed issues from NeMo Relay 0.2:
-
 ### Fixed issues from NeMo Relay 0.1:
 - Enabled TLS support for OTLP HTTP export.
 - Preserved Go scope stacks across OS threads.
diff --git a/docs/build-plugins/plugin-configuration-files.mdx b/docs/build-plugins/plugin-configuration-files.mdx
@@ -264,7 +264,7 @@ Observability exporters through `plugins.toml`.
 
 Use the component guides for field-level configuration:
 
-- [Observability Configuration](/observability-plugin/configuration)
-- [Adaptive Configuration](/adaptive-plugin/configuration)
-- [Adaptive Cache Governor (ACG)](/adaptive-plugin/acg)
-- [Adaptive Hints](/adaptive-plugin/adaptive-hints)
+- [Observability Configuration](/plugins/observability/configuration)
+- [Adaptive Configuration](/plugins/adaptive/configuration)
+- [Adaptive Cache Governor (ACG)](/plugins/adaptive/acg)
+- [Adaptive Hints](/plugins/adaptive/adaptive-hints)
diff --git a/docs/getting-started/agent-runtime-primer.mdx b/docs/getting-started/agent-runtime-primer.mdx
@@ -96,12 +96,12 @@ The following pages help you choose the next step for your integration.
 - Use [Quick Start](/getting-started/quick-start) for the smallest binding-specific example.
 - Use [Instrument Applications](/instrument-applications/about) when you
   own the tool or LLM call site.
-- Use [Integrate into Frameworks](/integrate-into-frameworks/about) when a
+- Use [Integrate into Frameworks](/integrate-frameworks/about) when a
   framework owns invocation, scheduling, retries, callbacks, or provider
   payloads.
 - Use [Build Plugins](/build-plugins/about) when behavior should be
   reusable and activated from configuration.
-- Use [Observability](/observability-plugin/about) when you need to export
+- Use [Observability](/plugins/observability/about) when you need to export
   runtime events to ATIF, OpenTelemetry, or OpenInference.
-- Use [Adaptive](/adaptive-plugin/about) after baseline instrumentation is
+- Use [Adaptive](/plugins/adaptive/about) after baseline instrumentation is
   working and you want to tune behavior from observed runtime signals.
diff --git a/docs/getting-started/quick-start/nodejs.mdx b/docs/getting-started/quick-start/nodejs.mdx
@@ -16,7 +16,7 @@ local checkout.
 
 ### Install from a Package Manager
 
-Use this path when you want the published package for application dev.
+Use this path when you want the published package for application development.
 
 ```bash
 npm install nemo-relay-node
@@ -32,7 +32,7 @@ npm install --ignore-scripts
 npm run build --workspace=nemo-relay-node
 ```
 
-This path is for local source dev when you need to build the binding from the repository checkout.
+This path is for local source development when you need to build the binding from the repository checkout.
 
 ## Run One Scope, One Tool Call, and One LLM Call
 
@@ -119,4 +119,4 @@ Use these links to continue from the quick start into the core runtime concepts.
 
 - [Instrument Applications Code Examples](/instrument-applications/code-examples)
 - [Subscribers](/about-nemo-relay/concepts/subscribers)
-- [Using Codecs](/integrate-into-frameworks/using-codecs)
+- [Using Codecs](/integrate-frameworks/using-codecs)
diff --git a/docs/getting-started/quick-start/python.mdx b/docs/getting-started/quick-start/python.mdx
@@ -17,7 +17,7 @@ local checkout.
 
 ### Install from a Package Manager
 
-Use this path when you want the published package for application dev.
+Use this path when you want the published package for application development.
 
 ```bash
 uv add nemo-relay@0.3.0
diff --git a/scripts/docs/reference_common.py b/scripts/docs/reference_common.py
@@ -11,6 +11,10 @@
 from pathlib import Path
 
 TextNormalizer = Callable[[str], str]
+MDX_SPDX_COMMENT = (
+    "{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.\n"
+    "SPDX-License-Identifier: Apache-2.0 */}\n"
+)
 
 
 def identity(value: str) -> str:
@@ -56,7 +60,7 @@ def frontmatter(
             "---",
         ]
     )
-    return "\n".join(lines) + "\n"
+    return "\n".join(lines) + "\n" + MDX_SPDX_COMMENT + "\n"
 
 
 def display_path(path: Path, *, cwd: Path | None = None, resolve: bool = False) -> str:
diff --git a/scripts/lint/check_copyright.py b/scripts/lint/check_copyright.py
@@ -25,7 +25,6 @@
     "SPDX-FileCopyrightText: Copyright (c) {year}, NVIDIA CORPORATION & AFFILIATES. All rights reserved."
 )
 
-COPYRIGHT_TEXT = COPYRIGHT_TEXT_TEMPLATE.format(year=CURRENT_YEAR)
 LICENSE_TEXT = "SPDX-License-Identifier: Apache-2.0"
 
 # Pattern to match the full SPDX-FileCopyrightText content (after any comment prefix).
@@ -93,11 +92,23 @@
 
 BLOCK_COMMENT_STYLES: dict[str, tuple[str, str, str]] = {
     ".md": ("<!--\n", "\n", "\n-->"),
+    ".mdx": ("{/* ", "\n", " */}"),
     ".html": ("<!--\n", "\n", "\n-->"),
     ".h": ("/* ", "\n * ", "\n */"),
     ".c": ("/* ", "\n * ", "\n */"),
 }
 
+MDX_SPDX_HEADER_RE = re.compile(
+    r"(?P<start>\{/\*\s*|<!--\s*)"
+    r"SPDX-FileCopyrightText: Copyright \(c\) (?P<start_year>\d{4})(?:-(?P<end_year>\d{4}))?, "
+    r"NVIDIA CORPORATION & AFFILIATES\. All rights reserved\.\s*"
+    r"SPDX-License-Identifier: Apache-2\.0"
+    r"\s*(?P<end>\*/\}|-->)",
+    re.MULTILINE,
+)
+
+FRONTMATTER_RE = re.compile(r"\A---\r?\n.*?\r?\n---\r?\n", re.DOTALL)
+
 
 def get_comment_style(filepath: str) -> str | None:
     """Return the file extension key for comment style lookup, or None if unsupported."""
@@ -111,14 +122,15 @@ def get_comment_style(filepath: str) -> str | None:
     return None
 
 
-def make_header(style_key: str) -> str:
+def make_header(style_key: str, year: str | None = None) -> str:
     """Build the full SPDX header string for the given comment style."""
+    copyright_text = COPYRIGHT_TEXT_TEMPLATE.format(year=year or CURRENT_YEAR)
     if style_key in LINE_COMMENT_STYLES:
         prefix = LINE_COMMENT_STYLES[style_key]
-        return f"{prefix}{COPYRIGHT_TEXT}\n{prefix}{LICENSE_TEXT}\n"
+        return f"{prefix}{copyright_text}\n{prefix}{LICENSE_TEXT}\n"
     if style_key in BLOCK_COMMENT_STYLES:
         start, mid, end = BLOCK_COMMENT_STYLES[style_key]
-        return f"{start}{COPYRIGHT_TEXT}{mid}{LICENSE_TEXT}{end}\n"
+        return f"{start}{copyright_text}{mid}{LICENSE_TEXT}{end}\n"
     return ""
 
 
@@ -142,6 +154,15 @@ def compute_year_string(start_year: str, end_year: str | None) -> str:
     return f"{start_year}-{CURRENT_YEAR}"
 
 
+def insertion_index(filepath: str, content: str) -> int:
+    """Return where a missing header should be inserted."""
+    if get_comment_style(filepath) == ".mdx":
+        match = FRONTMATTER_RE.match(content)
+        if match is not None:
+            return match.end()
+    return 0
+
+
 def process_file(filepath: str) -> bool:
     """Check and fix the SPDX header in a single file.
 
@@ -168,6 +189,18 @@ def process_file(filepath: str) -> bool:
     search_lines = lines[:10]
     search_text = "\n".join(search_lines)
 
+    if style_key == ".mdx":
+        match = MDX_SPDX_HEADER_RE.search(search_text)
+        if match:
+            year_str = compute_year_string(match.group("start_year"), match.group("end_year"))
+            header = make_header(style_key, year_str).rstrip("\n")
+            if header == match.group(0):
+                return False
+            new_content = content[: match.start()] + header + content[match.end() :]
+            with open(filepath, "w", encoding="utf-8", newline="") as f:
+                f.write(new_content)
+            return True
+
     match = SPDX_RE.search(search_text)
 
     if match:
@@ -199,7 +232,8 @@ def process_file(filepath: str) -> bool:
         else:
             new_content = shebang + header + "\n" + rest
     else:
-        new_content = header + "\n" + content
+        index = insertion_index(filepath, content)
+        new_content = content[:index] + header + "\n" + content[index:]
 
     with open(filepath, "w", encoding="utf-8", newline="") as f:
         f.write(new_content)
