docs: fix platform-protocol drift from both implementations

[njbrake]

Description

docs/platform-protocol.md had drifted from both the gateway (consumer) and the reference platform (peer). This PR realigns it:

• Wrong peer link. The "default peer implementation" link pointed at this repo (the consumer) instead of the platform. Repointed it at mozilla-ai/otari-ai and reworded "default" to "reference peer implementation".
• Undocumented response fields. Added an Extension policy section taking the issue's preferred approach: the doc describes only the fields the gateway actually reads, responses are open for extension, and consumers must ignore unknown fields. The known extras from GatewayResolveResponse in otari-ai (workspace_id, organization_id, provider_key_id, allowed_models) are listed as the concrete example.
• Missing endpoints. Documented the two resolve endpoints the gateway now consumes (feat(web-search): per-workspace web-search policy via platform resolve #144): mcp-servers/resolve and web-search/resolve, each with request/response shapes, auth headers, and failure mapping. Corrected the Authentication section (was "Both endpoints"; now all four require X-Gateway-Token, the three resolve endpoints add X-User-Token, and usage sends only the gateway token). Added a forward pointer to Consumer-side contract fixtures for platform /gateway/*/resolve responses #146 as the eventual contract of record.

All shapes were verified against the code in src/gateway/api/routes/_platform.py and _pipeline.py.

PR Type

• New Feature
• Bug Fix
• Refactor
• Documentation
• Infrastructure / CI

Relevant issues

Fixes #149

Checklist

• I understand the code I am submitting.
• I have added or updated tests that cover my change (tests/unit, tests/integration). (Docs-only change; no code paths affected.)
• I ran the Definition of Done checks locally (make lint, make typecheck, make test). (Docs-only change; no code, lint, typecheck, or OpenAPI surface touched.)
• Documentation was updated where necessary.
• If the API contract changed, I regenerated the OpenAPI spec (uv run python scripts/generate_openapi.py). (No API contract change.)

AI Usage

• No AI was used.
• AI was used for drafting/refactoring.
• This is fully AI-generated.

AI Model/Tool used:

Claude Code (Opus 4.8)

Any additional AI details you'd like to share:

Claude drafted the doc changes via back-and-forth with @njbrake; the reasoning and decisions are his.

NOTE:
When responding to reviewer questions, please respond yourself rather than copy/pasting reviewer comments into an AI and pasting back its answer. We want to discuss with you, not your AI :)

• I am an AI Agent filling out this form (check box if true)

Overview

This PR corrects and expands the documentation of Otari's platform-mode HTTP API contract in docs/platform-protocol.md, addressing documentation drift between the gateway implementation and its specification.

Key Changes

Updated references and clarifications:

• Fixed the "default peer implementation" link to point to the public reference platform repository
• Added an explicit Extension policy section clarifying that response shapes are open to additional fields and consumers must ignore unknown ones

Documented previously undocumented resolve endpoints:

• Added full documentation for two resolve endpoints the gateway now uses: MCP server ID resolution and web-search policy resolution
• Included request/response payloads, expected behaviors, and field descriptions for each

Clarified authentication requirements:

• Specified that all endpoints require the X-Gateway-Token header
• Noted that resolve endpoints additionally require the X-User-Token header, while the usage endpoint sends only the gateway token

Improved error handling documentation:

• Clarified how the gateway handles different error responses from the platform
• Documented explicit mappings for client-facing forwarding (401/402/403/404/429) and error fallbacks (422/5xx and timeouts → 502 Bad Gateway)

Benefits

This documentation now accurately reflects the gateway's current implementation, reducing confusion for platform integrators and making the API contract clearer and more maintainable.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 25ee6bac-9cf8-4b82-bd93-78c318946b59

📥 Commits

Reviewing files that changed from the base of the PR and between 8cd4f7f and 5dfbea7.

📒 Files selected for processing (1)

• docs/platform-protocol.md

---

Walkthrough

docs/platform-protocol.md is expanded with contracts for two new gateway endpoints—MCP server ID resolution and web-search policy resolution—alongside clarified authentication requirements, a shared response extension policy, and explicit failure-mapping tables covering forwarded status codes and 502 Bad Gateway normalization cases.

Changes

Platform Protocol Documentation Expansion

Layer / File(s)	Summary
Contract preamble, auth rules, and extension policy docs/platform-protocol.md	Replaces prior "default peer implementation" wording to name otari.ai as the reference peer, documents base-URL concatenation and per-endpoint authentication (X-Gateway-Token everywhere; X-User-Token on resolve endpoints), and adds an open extension policy requiring consumers to ignore unknown response fields.
Resolve-endpoint failure-mapping table docs/platform-protocol.md	Adds a shared failure-mapping table specifying which HTTP status codes (401/402/403/404/429) are forwarded to the client, Retry-After preservation on 429, and normalization of 422/5xx and network/timeout cases to 502 Bad Gateway with documented detail strings.
MCP server resolution contract and failure mapping docs/platform-protocol.md	Defines the MCP resolve endpoint: request payload (workspace-scoped server IDs), response shape (inline server configs), which fields Otari reads, treatment of a missing servers key as empty, SSRF/URL-safety constraints, cleartext bearer-token safety rules, and a dedicated failure-mapping table.
Web search resolution contract and failure mapping docs/platform-protocol.md	Defines the web-search resolve endpoint for otari_web_search: empty request body identified by X-User-Token, workspace policy response fields, 403 rejection when enabled is falsy, default fill-in rules when tool entries omit values, shallow-merge semantics for provider_options, endpoint-specific failure mappings, and a note on shared timeout/token headers.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• docs/platform-protocol.md has drifted from both implementations #149: This PR directly resolves the documentation drift concern by adding the previously missing MCP server and web-search resolution endpoint contracts, the extension policy for response shapes, and clarified authentication and error-handling rules for all resolve endpoints.

Possibly related PRs

• mozilla-ai/otari#164: Implements the runtime behavior for forwarding X-Gateway-Token to the web-search backend when the backend URL targets the platform origin—the exact authentication contract this PR now formally documents.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/platform-protocol-drift

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/platform-protocol-drift

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Copilot]

Pull request overview

This PR updates docs/platform-protocol.md to realign the written platform-mode HTTP contract with what the gateway consumes, adding the missing resolve endpoints and clarifying that response shapes are extension-friendly.

Changes:

• Fixes the introductory “reference peer” wording/link and expands the endpoint list to include MCP server and web-search resolve.
• Adds an explicit extension policy (document only what the gateway reads; ignore unknown response fields).
• Documents request/response shapes and failure mapping for mcp-servers/resolve and web-search/resolve, plus updated authentication guidance.