docs: sync /docs with changes merged 2026-05-28 – 2026-05-29

[aheritier]

Summary

Catch-up documentation updates for code changes merged in the last 36 hours.

Most doc updates for the same batch of PRs were already landed in #2927 ("docs: sync CLI flags and hook payload docs with recent changes"). This PR covers the remaining gaps.

---

Commits

docs: document /api/mcp-oauth/callback endpoint and --mcp-oauth-redirect-uri flag (refs #2896, #2921)

File: docs/features/api-server/index.md

Added a new ### OAuth subsection documenting POST /api/mcp-oauth/callback (query parameters, error responses 400/404) and added --mcp-oauth-redirect-uri to the API-server CLI flags table.

---

docs: clarify docker-agent/authorize_url prose in unmanaged OAuth section (refs #2921)

File: docs/features/remote-mcp/index.md

Fixed ambiguous prose: "opens the browser at docker-agent/authorize_url" → "at the URL provided in the docker-agent/authorize_url meta field".

---

docs: document full elicitation meta for client-driven unmanaged OAuth flow (refs #2896)

File: docs/features/remote-mcp/index.md

The client-driven (flag-not-set) case previously said it "emits only auth_server_metadata + resource_metadata", which was inaccurate. The code emits five keys for both sub-behaviors. Replaced the prose description with a proper table showing all five keys (docker-agent/type, docker-agent/server_url, auth_server, auth_server_metadata, resource_metadata).

---

docs: add --app-name example to TUI launch section (refs #2914)

File: docs/features/tui/index.md

--app-name was added to the CLI flags table by #2927 but was absent from the TUI launch examples block. Added the example.

---

docs: fix /api/mcp-oauth/callback 400 condition and add error-path params (refs #2896)

File: docs/features/api-server/index.md

The original endpoint description said "Returns 400 if state or code is missing" — incorrect per the handler (mcpOAuthCallback in pkg/server/server.go). The handler accepts ?error=<error> as a valid alternative to ?code, per the OAuth error-response path (RFC 6749 §4.1.2.1), and returns 400 only if both code and error are absent. Fixed the 400 condition and documented the full query-string contract including ?error and ?error_description. Also aligned the --mcp-oauth-redirect-uri flag description with the fuller version in docs/features/cli/index.md (adds "and sends the full authorize URL to the client via elicitation").

---

PRs covered

Source PR	Title	Doc impact
#2896	Extend unmanaged OAuth flow to drive code exchange in-process	POST /api/mcp-oauth/callback endpoint docs (accurate 400 condition, full query params); full elicitation meta table for client-driven path; --mcp-oauth-redirect-uri flag description aligned
#2914	Add --app-name flag	--app-name example added to TUI launch docs
#2915	Rename OAuth elicitation meta keys from cagent/ to docker-agent/	All cagent/* meta key refs removed (verified complete)
#2917	Add --sidebar flag	Already covered by #2927 — no further gaps
#2913	Add --disable-commands flag	Already covered by #2927 — no further gaps
#2911	Populate ModelID in after_llm_call hook payload	Already covered by #2927 — both hooks have model_id documented
#2921	Address review feedback on #2896	Prose clarification (this PR)
#2920	fix: rune-safe truncation and dead-code cleanup	Internal only — no user-facing doc changes needed
#2926, #2918	Dependency bumps	No docs needed
#2905	Test cleanup	No docs needed
#2919	CHANGELOG update	Already done

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION