docs: close RC1 reference gaps for [targets] and switchyard-server options

[eric-liu-nvidia]

Summary

Closes two of the three RC1 public-docs gaps reported in SWITCH-1198 (NvBug SWYD-104). Both were found by a first-time-user pass over the v0.2.0-rc.1 docs.

docs/reference/toml_schema.md — the page described noop as a zero-upstream local smoke test, but a noop-only config is rejected with missing field `targets` . The page now states that schema_version, [targets], and [routes] must all be present even when a route reaches no upstream, that an empty [targets] table satisfies the requirement, and that [llm_clients] defaults to empty and may be omitted. A minimal noop-only example was added to the noop section.

This matches ServerConfig (crates/switchyard-server/src/config.rs), where llm_clients carries #[serde(default)] and targets does not.

docs/cli_reference.md — the switchyard-server options table was missing two shipped options. --routing-log-file PATH is the one the report named; --shutdown-timeout (default 30s) was also absent. Both are added in --help order, since the reported expectation was that the table match --help.

Verification

Against a fresh cargo build --locked -p switchyard-server at this branch:

• Without [targets]: invalid server config …: failed to parse TOML: … missing field targets
• With an empty [targets] and no [llm_clients]: server OK: noop-route
• The noop example as written in the docs loads verbatim: server OK: noop-route
• The rendered options table and --help were diffed in both directions — no option appears in one and not the other.
• mkdocs build --strict passes.

Deliberately not included: the known_issues.md 0.2.0 section

The third item in SWITCH-1198 asks for a 0.2.0 known-issues section covering #180, #200, #202, and #205. Those four are merged pull requests, not open issues — they are the fixes. Checked with git merge-base --is-ancestor: none is an ancestor of v0.2.0-rc.1, and all four are ancestors of main. They were real RC1 defects that landed after the RC was cut.

Adding them to known_issues.md on main would ship 0.2.0 telling users that four already-fixed things are broken. The clearest case is the report's own evidence for #200: /v1/models returning hardcoded capabilities: {context_window: null, tool_calling: null}. On main those fields are wired from route config in model_entry_json, and both are documented route keys in the schema page this PR edits.

A real 0.2.0 known-issues list should be triaged from the currently-open bugs and is left to the docs owner, as the reporter offered in the ticket ("split into separate issues if preferred by the docs owner").

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Documented new switchyard-server options for configuring shutdown timeouts and routing log output.
  • Clarified required deployment configuration sections and valid empty-target deployments.
  • Documented that LLM client configuration is optional.
  • Updated the noop deployment example to reflect the current schema.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-295/
Built to branch gh-pages at 2026-08-05 01:45 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 17a374e0-991b-44e1-97a8-fcde2376c6ed

📥 Commits

Reviewing files that changed from the base of the PR and between c1c1b41 and b65ab36.

📒 Files selected for processing (2)

• docs/cli_reference.md
• docs/reference/toml_schema.md

---

Walkthrough

The documentation adds two server CLI options and clarifies TOML deployment requirements. It also adds a noop deployment example with an empty [targets] table.

Changes

Documentation references

Layer / File(s)	Summary
Server CLI option reference docs/cli_reference.md	Documents --shutdown-timeout and --routing-log-file.
Deployment schema contract and noop example docs/reference/toml_schema.md	Documents required tables, optional [llm_clients], and a valid empty-target noop deployment.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Poem

A rabbit reads the flags with care,
And finds new timeout notes there.
Empty targets hop into view,
While noop routes guide them through.
TOML now tells the truth—
Documentation grows fresh roots.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation updates for required [targets] configuration and missing switchyard-server options.
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.

---

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