Skip to main content

​
CLAUDE.md

Working notes for anyone (human or AI) editing the brew.new docs repo.

​
What this repo is

Mintlify docs site for brew.new. Source of truth for navigation, redirects, SEO, tabs, and appearance is docs.json at the repo root (schema: mintlify.com/docs.json). Only .mdx files listed in docs.json.navigation get published. snippets/ are reusable components, not standalone pages. The OpenAPI spec at api-reference/openapi-public-v1.yaml generates the “Public API v1” group at build time. Content lives in top-level topic folders: analytics/, api-reference/, audience/, brand/, changelog/, create-emails/, get-started/, integrations/, legal/, recipes/, sdks/, settings/. Assets in images/, logo/, favicon.svg.

​
Terminology — most important rule

The brew.new platform renamed the product type “Campaigns” → “Emails”. Current phrasing is “Emails and Automations”, not “Campaigns and Automations.” As of 2026-07-08 the rename is applied across all product-facing copy (Guides, Integrations, Changelog body text). What intentionally still says “campaign”:
  • API surface identifiers (kind: campaign, /v1/analytics/campaigns, MCP tool get_campaign_analytics, OpenAPI operationId getCampaignAnalytics, schema CampaignAnalyticsResponse, etc.) are unchanged pending confirmation from the API team. Do NOT change these.
  • create-emails/emails.mdx keeps deliberate bridging language (“sometimes called campaigns”) for SEO and users coming from other ESPs.
  • Generic marketing English (“re-engagement campaign”, analytics glossary) and legal/third-party ESP docs are fine as is.
When editing, still flag any stale “Campaigns” product-surface language you notice. Do not touch the API identifiers without asking.

​
Style conventions

  • Tone: write like a human. No em/en-dashes anywhere (period, comma, colon, or parentheses instead), straight quotes, no AI vocabulary (leverage, seamless, robust, delve, additionally, …), no negative parallelism or punchline staccato. Applied repo-wide 2026-07-08.
  • Casing: page title: fields and markdown headings use Title Case with short prepositions/articles lowercase. Applied to Guides, Changelog, and Integrations; API Reference and SDKs are intentionally still sentence case (pending pass).
  • Exceptions: legal/ untouched; API response example strings stay verbatim (one em-dash lives in api-reference/api/errors.mdx on purpose); filenames like email-design.md stay lowercase in headings.

​
Editing guardrails

  • Do not edit content without an explicit ask. If you spot a fix while doing something else, mention it in the response — don’t apply it.
  • The changelog (changelog/posts/* and changelog/api.mdx) has the most drift and reflects multiple eras of the product. Extra care there.
  • Redirects in docs.json are load-bearing — do not remove one without checking what still links to the source path.
  • Prefer linking to canonical paths, not redirect sources. Example: link /create-emails/campaigns directly, not /create-emails/emails (which resolves via redirect).

​
Publication status

Everything in docs.json.navigation publishes to production. Intentionally unpublished: snippets/need-help.mdx (reusable snippet), plus recipes/qa-before-a-big-send.mdx and recipes/run-brew-from-an-ai-agent.mdx (pulled from nav 2026-07-08 because the accessibility audit they mention is not fully set up; restore by re-adding them to docs.json). CLAUDE.md and DOCS_AUDIT_REFERENCE.md are .md (not .mdx) and are not in nav. Mintlify does not process them, and it generates llms.txt from docs.json at build time, so nav accuracy is what keeps agent-facing output accurate.

​
Open questions

  1. Was the API kind: campaign enum renamed on the backend? Still open; determines whether the API-surface “campaign” identifiers should be updated.
Answered 2026-07-08: the product UI shows “Emails” (not “Campaigns”) as the tab inside the Emails sidebar item, and the changelog is a public top-nav tab.