Open specs published: Trust Envelope v1 + MCP-OAuth Bridge v1 at docs.brainstormrouter.com/specs/

2026-05-16

docsspecssdks

What We Built

Two open specifications, published as citable Mintlify pages on the docs site:

Trust Envelope v1 — normative schema for BR's EdDSA-signed agent identity JWT. Defines the six br_* claim blocks (br_principal, br_budget, br_scope, br_trust, br_observability, br_test), the 5-tier reputation enum, JWKS verification rules, and the deny-by-default semantics for empty-array scope fields (closing the ambiguity locked by issue #296).
MCP-OAuth Bridge v1 — bidirectional mapping between Trust Envelope claims and OAuth 2.1 protected resource metadata per RFC 8707 + RFC 9728. Defines how an agent authenticated to BR can call MCP tool servers with claim-bound authorization that survives the agent → gateway → tool-server hop.

Both specs are RFC 2119 normative ("MUST", "SHOULD"), CC BY 4.0 licensed, and versioned (currently v1.0.0-draft-1 — leaves draft once two independent implementations + one third-party adoption land).

Why It Matters

Three model-council assessments in 48 hours converged on the same finding: the spec files lived in the private justinjilg/brainstormrouter repo, which meant no third-party MCP server implementor could reference them, no standards working group could cite them, and the "protocol authority" positioning had no public artifact behind it.

Publishing to docs.brainstormrouter.com/specs/* collapses that gap:

Mintlify auto-indexes them, so they appear in search
Each has a stable URL agent runtimes can paste into their docs
The npm + PyPI READMEs link out to them, so package consumers find them
The concept pages (/concepts/trust-envelope, /concepts/mcp) now link

forward to the normative specs as their authoritative reference

The strategic shift: BR is no longer just an implementation that happens to have docs. It's now an implementation of specifications that anyone can implement compatibly. Same shape as how Stripe's Smart Disputes spec made dispute APIs cite Stripe's terminology even at competitors.

How It Works

The two MDX files live under docs/specs/. The Mintlify docs.json nav includes a new "Specifications" group in the Documentation tab. The ship-log/concept/SDK cross-links route readers from narrative → normative spec → implementation.

For lockstep against the maintainer-facing source (specs/*.md in the private repo):

specs/README.md now flags the docs URL as canonical and lists both v1 specs as live
specs/mcp-oauth-bridge-v1.md is now a one-line stub pointing at the MDX file (no duplicate full-text to keep in sync)

The same source-of-truth pattern as feedback_lockstep_mechanism_not_discipline recommends: don't keep two copies in sync via checklist; pick one canonical location and route the other at it.

Deploy

Mintlify docs site does NOT auto-deploy (per CLAUDE.md). After merge, the canonical URLs become live with one manual command:

cd docs-site && vercel deploy --prod --yes

Lockstep Checklist

[x] Specs published at docs/specs/{index,trust-envelope-v1,mcp-oauth-bridge-v1}.mdx
[x] Mintlify nav updated (docs/docs.json adds "Specifications" group)
[x] Concept pages link forward to normative spec (/concepts/trust-envelope, /concepts/mcp)
[x] Walkthrough guide repointed (/guides/governing-your-first-agent)
[x] SDK READMEs cite specs (packages/sdk-{ts,py}/README.md)
[x] Maintainer-facing source specs/ repointed to docs as canonical
[x] Ship-log entry (this file)
[n/a] API endpoints — pure documentation surface
[n/a] MCP tools — same
[ ] Manual: cd docs-site && vercel deploy --prod --yes after merge