docs(rails): document rail manifests and action-backed surfaces

[Pouyanpi]

Documents rail manifests and their action-backed execution surfaces.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guidance for Rail Outcomes, including allow, block, and transform decisions, evidence fields, streaming behavior, and migration from output_mapping.
  • Clarified how ordinary actions and rail-manifest actions return values.
  • Added a Rail Manifest reference covering structure, metadata, actions, flows, configuration, validation, privacy, and authoring guidance.
  • Updated documentation navigation with links to the new references.

[coderabbitai]

📝 Walkthrough

Walkthrough

This change adds documentation for RailOutcome decisions and rail manifests. It removes output_mapping guidance, documents migration to explicit outcomes, adds manifest-backed action requirements, and updates documentation navigation.

Changes

Rail documentation

Layer / File(s)	Summary
RailOutcome contract and migration docs/configure-rails/actions/rail-outcomes.mdx, docs/configure-rails/actions/creating-actions.mdx, docs/configure-rails/actions/index.mdx, docs/index.yml	Documents allow, block, and transform outcomes; evidence; validation; Colang consumption; streaming behavior; and migration from output_mapping. Ordinary actions retain explicit value handling, while manifest-backed rail actions must return RailOutcome.
Rail manifest reference docs/reference/rail-manifests.mdx, docs/index.yml	Documents manifest structure, discovery, actions, flows, surfaces, typed configuration, requirements, privacy metadata, validation, public catalog APIs, and authoring guidance.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• NVIDIA-NeMo/Guardrails#2150: Introduces the RailOutcome contract documented here.
• NVIDIA-NeMo/Guardrails#2157: Introduces the rail manifest contract documented here.
• NVIDIA-NeMo/Guardrails#2189: Enforces the RailOutcome contract for manifest-backed rail actions.

Suggested reviewers: miyoungc

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main documentation changes for rail manifests and action-backed surfaces.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes	✅ Passed	The PR changes only five documentation/navigation files; no code or test files changed, so this is a minor documentation change and test-result details are not required.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/rail-manifests.mdx`:
- Line 68: Remove the docs_url entry from the minimal rail manifest example,
since it references a source file rather than a published documentation route.
Do not add a replacement unless a corresponding rendered Fern route exists in
docs/index.yml.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9d0af288-19a8-4760-9f24-1421d8711933

📥 Commits

Reviewing files that changed from the base of the PR and between aee16a8 and 2e40996.

📒 Files selected for processing (5)

• docs/configure-rails/actions/creating-actions.mdx
• docs/configure-rails/actions/index.mdx
• docs/configure-rails/actions/rail-outcomes.mdx
• docs/index.yml
• docs/reference/rail-manifests.mdx

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Remove the source file path from docs_url.

This value points to a source file path. It does not identify a published documentation route. The referenced navigation does not contain example-rail.

Remove docs_url from this minimal example. Add a rendered Fern route only when the example has a published page.

Proposed fix

-        docs_url="docs/configure-rails/guardrail-catalog/community/example-rail.mdx",

As per path instructions, derive internal documentation routes from docs/index.yml and do not use source-path-style links.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

docs_url="docs/configure-rails/guardrail-catalog/community/example-rail.mdx",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/reference/rail-manifests.mdx` at line 68, Remove the docs_url entry from
the minimal rail manifest example, since it references a source file rather than
a published documentation route. Do not add a replacement unless a corresponding
rendered Fern route exists in docs/index.yml.

Sources: Coding guidelines, Path instructions

[Pouyanpi]

this is part of the manifest's contract, it is an example

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '=== Candidate manifest implementation files ==='
fd -t f -a 'manifest|manifests' . | sed -n '1,160p'

printf '%s\n' '=== docs_url declarations, validation, and consumers ==='
rg -n -C 4 '\bdocs_url\b' . -g '!**/.git/**' | sed -n '1,360p'

printf '%s\n' '=== Target page ==='
cat -n docs/reference/rail-manifests.mdx | sed -n '1,280p'

printf '%s\n' '=== Documentation navigation entries ==='
rg -n -C 3 'rail-manifests|example-rail|guardrail-catalog' docs/index.yml docs -g 'index.yml' -g '*.mdx' | sed -n '1,260p'

Length of output: 60496

---

@Pouyanpi, verification confirms this.

RailMetadata.docs_url uses a repository-relative documentation source path. Built-in rail manifests use the same format. tests/rails/llm/test_builtin_rail_manifests.py verifies that each non-HTTP docs_url value resolves to a repository file.

The docs_url value on Line 68 is correct for the manifest contract. The original finding is withdrawn.

---

✏️ Learnings added

Learnt from: Pouyanpi
Repo: NVIDIA-NeMo/Guardrails PR: 2259
File: docs/reference/rail-manifests.mdx:68-68
Timestamp: 2026-08-07T12:37:47.643Z
Learning: In the NVIDIA NeMo Guardrails library, `RailMetadata.docs_url` is a manifest-contract field that uses a repository-relative documentation source path, such as `docs/configure-rails/guardrail-catalog/community/guardrails-ai.mdx`. This field is validated as a repository file path by `tests/rails/llm/test_builtin_rail_manifests.py`. The Fern-route requirement applies to links in `docs/**/*.mdx`, not to `RailMetadata.docs_url` values in Python manifest examples.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

_{You are interacting with an AI system.}