chore(docs): massive docs refactor for QA - #230
Merged
Conversation
Signed-off-by: ayushag <ayushag@nvidia.com>
|
ryan-lempka
reviewed
Jul 31, 2026
ryan-lempka
reviewed
Jul 31, 2026
Signed-off-by: ayushag <ayushag@nvidia.com>
WalkthroughThe PR updates project and documentation pages for native Rust launcher and server workflows. It adds TOML deployment and routing references, revises operational guidance, removes obsolete sticky-routing documentation, updates navigation, and expands documentation drift tests. ChangesNative Rust deployment documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🧹 Nitpick comments (3)
tests/test_cli_reference_docs.py (1)
55-70: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winBound the Cargo subprocess duration.
cargo runcan wait on dependency or toolchain resolution. Without a timeout, a stalled Cargo process can hang the pytest run. Set a CI-appropriate timeout.Proposed fix
text=True, check=False, + timeout=300, )🤖 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 `@tests/test_cli_reference_docs.py` around lines 55 - 70, Set a CI-appropriate timeout on the subprocess.run invocation that executes cargo run in the CLI reference test, while preserving its existing command, working directory, output capture, text mode, and check behavior.tests/getting_started/test_getting_started.py (2)
15-18: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winCover every documented launcher agent.
docs/getting_started.mddocumentsclaude,codex, andopenclawin Lines [46-53], but this test checks only Claude. Add assertions for the Codex and OpenClaw examples.🤖 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 `@tests/getting_started/test_getting_started.py` around lines 15 - 18, Extend the getting-started guide assertions in the test around the existing Claude launcher check to also verify the documented Codex and OpenClaw launcher command examples, preserving the current assertions for Claude and the other setup commands.
10-12: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winMake Markdown decoding deterministic in all drift tests.
Pass
encoding="utf-8"to all sixread_text()calls in the three test files, including lines 47 and 73 oftests/test_cli_reference_docs.py.🤖 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 `@tests/getting_started/test_getting_started.py` around lines 10 - 12, Make Markdown decoding deterministic by passing encoding="utf-8" to every read_text() call in tests/getting_started/test_getting_started.py (lines 10-12), tests/readme/test_readme.py (line 10), and tests/test_cli_reference_docs.py (lines 34, 47, and 73). Update all six calls without changing their existing path or validation behavior.
🤖 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/internal/subagent_override.md`:
- Around line 45-49: Update the trusted-ingress header handling described in the
x-switchyard-is-subagent routing flow so this client-controlled header is
stripped before routing, or honored only when supplied by authenticated trusted
callers. Preserve the existing true-to-subagent_target and
false-to-normal-routing behavior for permitted trusted inputs, while preventing
untrusted inbound requests from influencing routing.
In `@docs/operations/context_window.md`:
- Around line 54-63: Update the “Evictions last for the session” section to
document how clients recover after truncating or resetting context: instruct
them to rotate the session ID, or explicitly state that evictions remain
permanent when the ID is reused. Keep the existing session-header behavior and
no-header behavior unchanged.
In `@docs/reference/toml_schema.md`:
- Around line 88-92: Update the weights entry in the schema table to state that
all weights must be finite and non-negative, with at least one positive value,
and document that invalid weights are rejected during validation.
- Around line 183-224: Clarify the Validation and Errors documentation that
deserialization failures from toml::from_str are prefixed with “failed to parse
TOML:”, while config.build() validation errors are returned with their inner
messages unchanged. Update the error-format description or examples so the two
error classes are explicitly distinguished.
- Around line 80-82: Expand the `noop` section in the TOML schema documentation
to describe its runtime response and intended use, or explicitly label it as an
internal route if it is not supported for external use. Keep the existing
accepted-key definition and ensure the documented behavior matches the
implementation.
In `@docs/routing_algorithms/escalation_router_routing.md`:
- Around line 48-49: Update the ignored-settings list in the escalation routing
documentation to also include message_hash_fallback and the route-level
recent_turn_window, alongside the existing min_confidence,
capability_elevated_floor, and session_affinity entries. Preserve the note that
base_threshold remains required.
In `@docs/routing_algorithms/llm_classifier_routing.md`:
- Around line 39-40: Update the routing example and the message_hash_fallback
documentation to warn that deriving affinity from the first user-message text
can collide across independent sessions with repeated prompts. Prefer adding
explicit session IDs to the primary example; otherwise clearly label
message_hash_fallback as best-effort and unsuitable for repeated prompts.
In `@docs/routing_algorithms/overview.md`:
- Around line 133-134: Update the routing overview’s TOML schema reference link
to point to the public reference page at ../reference/toml_schema.md, making
that generated documentation the authoritative source for the complete schema
and route options.
In `@README.md`:
- Around line 110-111: Update the client-format description in the README to
state that the server accepts OpenAI Chat Completions, OpenAI Responses, and
Anthropic Messages formats, while each configured LLM client selects exactly one
upstream format. Remove wording that implies every upstream client supports all
three formats.
In `@tests/getting_started/test_getting_started.py`:
- Around line 30-31: Remove both future-work TODO comments from
tests/getting_started/test_getting_started.py lines 30-31 and
tests/readme/test_readme.py lines 26-27, unless implementing the requested
Python snippet and TOML schema coverage there. Do not replace them with
additional future-work comments.
---
Nitpick comments:
In `@tests/getting_started/test_getting_started.py`:
- Around line 15-18: Extend the getting-started guide assertions in the test
around the existing Claude launcher check to also verify the documented Codex
and OpenClaw launcher command examples, preserving the current assertions for
Claude and the other setup commands.
- Around line 10-12: Make Markdown decoding deterministic by passing
encoding="utf-8" to every read_text() call in
tests/getting_started/test_getting_started.py (lines 10-12),
tests/readme/test_readme.py (line 10), and tests/test_cli_reference_docs.py
(lines 34, 47, and 73). Update all six calls without changing their existing
path or validation behavior.
In `@tests/test_cli_reference_docs.py`:
- Around line 55-70: Set a CI-appropriate timeout on the subprocess.run
invocation that executes cargo run in the CLI reference test, while preserving
its existing command, working directory, output capture, text mode, and check
behavior.
🪄 Autofix (Beta)
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: 5ccc7f60-7260-4fdb-a991-6db013e2dbf0
📒 Files selected for processing (19)
AGENTS.mdREADME.mddocs/architecture.mddocs/cli_reference.mddocs/core_concepts.mddocs/getting_started.mddocs/index.mddocs/internal/subagent_override.mddocs/operations/context_window.mddocs/reference/toml_schema.mddocs/routing_algorithms/escalation_router_routing.mddocs/routing_algorithms/llm_classifier_routing.mddocs/routing_algorithms/overview.mddocs/routing_algorithms/random_routing.mddocs/routing_algorithms/sticky_routing.mdmkdocs.ymltests/getting_started/test_getting_started.pytests/readme/test_readme.pytests/test_cli_reference_docs.py
💤 Files with no reviewable changes (1)
- docs/routing_algorithms/sticky_routing.md
Contributor
|
docs/routing_algorithms/escalation_router_routing.md — one logical issue in the "When not to use" section:
This implies Everything else I checked (default values, streak reset-on-decline / hold-on-failure, cost at the confirming turn, flowchart) matches the current implementation. |
Signed-off-by: ayushag <ayushag@nvidia.com>
ayushag-nv
enabled auto-merge (squash)
July 31, 2026 19:09
ryan-lempka
approved these changes
Jul 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Reworked docs with libsy and rust server
Why
The motivation — what problem does this solve, or which ticket does it close?
Closes #
How tested
uv run ruff check .cleanuv run mypy switchyardcleanuv run pytest tests/greenChecklist
snake_caseof the primary class.switchyard/__init__.py.__all__if intended for downstream use.--helpupdated if customer-facing surface changed.Signed-off-by: Your Name <email>) per the DCO.Notes for reviewers
Anything reviewers should pay extra attention to — risky paths, follow-up tickets, intentional trade-offs.
Summary by CodeRabbit
Documentation
Tests
Relates to SWITCH-1134