brief.md scope tags — public, pitch-shareable, private
brief.md sections are tagged with one of three visibility scopes. The scope determines which sections each consumer sees, and which sections never leave the operator's control.
Operators authoring brief.md need to know how to mark sections so the right data is exposed to the right consumer.
The three scope tiers
`public` — section is visible to anyone, indexable by search engines, citable by AI consumers. Includes brand identity, voice rules, positioning, and category framing. `pitch-shareable` — section is visible to verified pitch consumers (journalists with a brief.md, PR tools holding a credential). Includes assets, product context, brand story. `private` — section is operator-internal only. Includes strategic priorities, customer-insight notes, internal scoring weights.
How scope is declared
Scope is declared in frontmatter under the `sections:` key. Each section name maps to a scope. When a consumer requests the brief.md, the publisher's output filter checks the consumer's privilege and renders only the sections at or below that consumer's clearance. The Markdown body itself stays in canonical form; filtering is applied at render time.
Defaults and discipline
A section without an explicit scope tag defaults to `private` — the conservative default protects against accidental disclosure. Operators authoring a brief should explicitly tag `public` and `pitch-shareable` sections; anything not tagged stays internal. The PRAPI canonical implementation enforces this default at parse time.
Scope tier examples from the portfolio
PRAPI's brief.md tags Identity, Voice Overrides, Brand Context, and Positioning as `public` — anything a journalist or AI consumer needs to evaluate fit. Visual Identity, Available Assets, Product Context, and Brand Story are `pitch-shareable` — assets a journalist would request when responding to a pitch. Strategic Priorities, Customer Insight Notes, and Internal Scoring Weights are `private` — operator-internal only.
Hireposture's brief.md tags `Identity` and `Voice Overrides` as `public` (so any consumer sees the brand frame) and `Strategic Priorities` as `private` (the legal positioning around Lori's Gifts settlement is operator-internal).
FAQ
What does "pitch-shareable" mean exactly?
A section visible to consumers who have authenticated as a verified pitch recipient — typically a journalist with their own brief.md, or a PR tool holding a credential. The section is not public (not indexable by search engines, not visible to anonymous consumers) but is reliably available to the verified pitch flow.
What if I don't tag a section?
Untagged sections default to `private`. This is deliberate — accidental public disclosure of strategic context (pricing strategy, customer notes, scoring weights) is more damaging than accidental hiding. Operators must explicitly tag `public` and `pitch-shareable` to make sections visible.
Can a single section have mixed scope?
No. Scope is at the section level. If a section contains both public and private content, split it into two sections with different scopes. The mental model: scope = audience, and a section is one continuous communication to one audience.
How do AI agents respect scope?
A well-behaved AI consumer fetches only the public scope unless it has authenticated as a higher-privilege consumer. Reference implementations (PRAPI's parser, brief-cli, brief-core npm package) filter at fetch time. Bad-actor consumers can ignore scope tags, but the scope is the operator's authoritative declaration of intent.
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 →