Publishing your brief.md
How to publish a brief.md so AI agents and PR tools can find and consume it. Three publishing patterns: Git-canonical, .well-known/brief.md, and JWS-signed at custom routes.
Operators publishing brief.md want to know where to put the file so the right consumers find it without breaking access controls.
The three publishing patterns
brief.md has three canonical locations a consumer can look. (1) /.well-known/brief.md — the IETF-style well-known URI under your apex domain, suitable for the public scope tier (`public` scope tags only). (2) Git-canonical at a stable repo URL — typically inputs/briefs/brands/{brand}/brand-brief.md or similar; consumers fetch over the Git protocol. (3) Custom route under your control — useful when serving the pitch-shareable scope tier conditionally based on consumer auth or signed verification.
Which pattern to choose
For early adoption: serve the public scope tier at /.well-known/brief.md so any consumer can fetch without setup. For regulated brands or pitch-shareable distribution: serve a JWS-signed file at a custom route gated on the consumer presenting a verified identity. For multi-brand operators: keep the Git-canonical version as the source of truth and have the published location render from Git on each fetch — the database is a cache, not a source of truth.
Scope tier visibility per pattern
The /.well-known location ships only `public`-scoped sections. Custom routes can render `pitch-shareable` to authenticated consumers and `private` only to operator-internal tools. The brief.md spec separates section visibility through frontmatter `sections:` declarations; the publisher is responsible for filtering on output.
Migration considerations
When moving from a closed brand-profile system (Featured, Cision contact card, etc.) to brief.md, the data lives in a markdown file you control. The reference parser will be open-sourced once the spec stabilizes; until then, PRAPI ships the canonical implementation. Ownership stays with the operator regardless.
PRAPI publishes its own brief.md at https://prapi.dev/.well-known/brief.md (proxied from the marketing repo). The same file is canonical at inputs/briefs/brands/prapi/brand-brief.md in the marketing-agent repo.
FAQ
Where should I publish my brief.md?
For the public scope tier, /.well-known/brief.md under your apex domain is the canonical location — it follows IETF RFC 8615 well-known URI conventions and is the location AI consumers (Claude, Perplexity, ChatGPT) increasingly look. For the pitch-shareable scope tier, serve from a custom route gated on consumer auth.
Does brief.md need to be public?
Only the `public`-scoped sections need to be readable without authentication. Sections tagged `pitch-shareable` can be served conditionally to verified consumers (e.g., journalists with a brief.md of their own). Sections tagged `private` should never appear in any output visible outside the operator.
How do AI agents find my brief.md?
AI agents follow the well-known URI convention. A reasonable agent will check /.well-known/brief.md before falling back to scraping marketing pages. The brief.md format gives the agent a deterministic, structured view of brand context that scraping cannot reliably produce.
Can I publish brief.md from a private repo?
Yes — the Git-canonical pattern works regardless of repo visibility, as long as the publishing layer (your website, your custom route) renders the file from Git on each fetch. The repo itself does not need to be public.
Run brief.md in PRAPI.
PRAPI is the canonical brief.md implementation. Every brand in your portfolio gets its own brief.md, voice-validated drafts on every pitch, and Git-canonical authoring.
Sign in →