docs: Document POST /v1/systemone: the native System One API, served by regular HTTP workers

[github-actions]

What this PR does

Does SMG serve the native System One API at POST /v1/systemone — which workers serve it, what does SMG validate before relaying, and what do deployments without a regular HTTP worker answer?

Why we need it

Source change: smg-project/smg@a7e2828

Commit 322 (#2865, a7e28280, 2026-10-07) added the endpoint; its supplied diff was read and every claim re-verified on the current default-branch snapshot. Contract (crates/protocols/src/systemone.rs, module doc :1-7 naming the upstream reference api.typesafe.ai/openapi.json): SystemOneRequest {model required, state as text or structured JSON (object or array), questions as a named map with at least one entry — Validate impl :136-161, which also requires at least one criterion on a score question; unknown fields preserved via #[serde(flatten)] and forwarded}; non-streaming only (is_stream false, :46-48). The response is relayed from the worker: SystemOneResponse {model, answers keyed by the request's question names (noul probability, choice with confidence and probabilities, score with confidence, legend and probabilities), usage {input_tokens, output_tokens}} (:163-209). Route: model_gateway/src/server.rs:1051 registers POST /v1/systemone with ValidatedJson among the protected inference routes (data-plane auth and admission, body-timeout and stream-vs-buffer layers :1052-1064), so a body that fails validation is refused 400 in the public envelope. Backend support the row must state: model_gateway/src/routers/gateway.rs:686-732 — only regular HTTP workers serve it, relayed to the worker's own /v1/systemone (routers/http/router.rs:2257-2275 route_typed_request); an explicit served model is required (unknown or wildcard model answers 404 model_not_found); in IGW mode a model with no regular HTTP worker answers 501 systemone_not_supported ('SystemOne requires a regular HTTP worker for this model'), and a deployment whose router is not the regular HTTP one answers 501 systemone_not_supported via the default trait impl (routers/mod.rs:211-222). Tests pin it: gateway.rs systemone_uses_only_regular_http_workers_in_mixed_fleets (:1181), systemone_respects_single_router_configuration (:1229), systemone_requires_a_registered_regular_http_router (:1248); e2e_test/router/test_systemone.py pins the native contract end to end (named answers in request order, structured state accepted, usage with output_tokens 0). Missing documentation: a repo-wide grep of src/lib/content finds 'systemone' only in reference/metrics.md:828's endpoint-label enumeration; reference/api/extensions.md — the page that declares itself the reference for non-OpenAI extension endpoints (:7) — lists /v1/classify and /v1/interactions in its Protected Utility Endpoints table (:49-60, the Interactions row carrying its backend support and 501 behavior inline) but has no /v1/systemone row. Placement: one row in that table in the /v1/interactions style (backend support and the 501 code inline), on the one page that enumerates these endpoints; openai.md was considered and rejected — System One is not an OpenAI-compatible endpoint and that page is held by open PR #146; a new reference page was considered and rejected because SMG's own surface is a validated relay — the question/answer vocabulary belongs to the upstream System One reference, so the SMG-side contract fits the table row, and no new page is added. Scope limits: the /v1/decisions row missing from this same table belongs to the deferred Decisions concern (its openai.md canonical section is blocked by open PR #146) and must not be added here; the Decisions-on-HTTP-workers upstream route constant (routers/common/decisions.rs:25 UPSTREAM_ROUTE = "/v1/systemone") is that concern's detail too. Version framing: commit 322 is a first-parent ancestor of the v1.12.0 bump (commit 299, #2888, 2026-10-08), and the docs already treat v1.12.0 as a named release, so present the endpoint as available since v1.12.0. One independent concern: one commit added one public endpoint, documented as one row on the one page that enumerates extension endpoints. Dedup: no open or closed PR mentions /v1/systemone or #2865 — the only 'systemone' matches in PR bodies are metric endpoint-label lists (merged #135) — and the pending Decisions concern explicitly deferred System One as a separate concern; no open PR touches extensions.md, and my other selected item touches different files. Edit is one table row plus at most a sentence, far under 1,000 lines.

Scope: api-extensions / systemone-endpoint. Other concerns are deferred.

How to test

• Passed the documentation path and size guard (under 1000 added plus deleted lines; no file-count limit).
• Passed an independent accuracy and single-concern review.
• Passed git diff --check and pnpm check and the production pnpm build.

Checklist

• Tests added/updated (if applicable)
• Docs updated (if applicable)
• Commit includes a DCO sign-off

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: bf505969-336a-4bac-af8c-2dd70127d488

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[github-actions]

Documentation maintenance: working. Unsuccessful content rounds: 0/3. Operational attempts: 1/3.

Head: 388cfa06557c7ab4e89bacd20f484061477bf590; reviewed main: d15d3f25e848323a4ea20cdc63a4533538fd329c.
Reviewed SMG source: dcc5cb0b8f2a64694938c10f02c6caaa0c40d5ef.

Repair/validation in progress; no merge authorization implied.

Workflow evidence

Human review threads and CODEOWNER approval remain under repository policy.