Skip to main content

​
Political Comms Docs - Claude Instructions

This is the public-facing documentation site for the Political Comms P2P texting platform, hosted on Mintlify at https://docs.politicalcomms.com.

​
Style rules

​
Never use em-dashes

Em-dashes (Unicode U+2014, the long horizontal dash) are prohibited everywhere in this repository: MDX files, JSON, code samples, comments, commit messages. Use one of these instead:
  • A regular hyphen (-) with spaces around it: foo - bar
  • A comma, period, or parentheses, depending on what reads best
  • Restructure the sentence to avoid the dash entirely
This applies to NEW content AND to anything Claude generates here. If you’re tempted to write an em-dash mid-sentence for “rhythm” or emphasis, stop and pick a different punctuation mark. En-dashes (–, U+2013) are still acceptable for numeric ranges (8 AM - 10 PM, 2-3 days) - but prefer a regular hyphen there too for consistency.

​
Other conventions

  • Sentence case for headings, not Title Case.
  • Code identifiers (endpoint paths, variable names, header names) go in inline code.
  • Pricing references go through the <Snippet file="/snippets/pricing.mdx" /> component so prices have a single source of truth.
  • Internal links never include the .mdx extension: /api-reference/introduction, not /api-reference/introduction.mdx.

​
Repo layout

  • docs.json - Mintlify site config (navigation, branding, footer, OpenAPI ref). Never put content here.
  • introduction.mdx - Landing page.
  • help/ - Help Center FAQ pages.
  • onboarding/ - 5-step onboarding guide.
  • compliance/ - TCPA, FCC, CTIA, 10DLC, Campaign Verify reference.
  • api-reference/ - Conceptual API pages + openapi.json for endpoint auto-generation.
  • api-reference/webhooks/ - Webhook setup, signature validation, events, retry policy.
  • legal/ - Terms of Use and Privacy Policy.
  • snippets/ - Reusable MDX fragments (pricing block).
  • favicon.svg - Site favicon.

​
Common commands

​
Deployment

Pushes to main auto-deploy via the Mintlify GitHub App (project 6a03f47abee46be88e3dae86). To force a rebuild via API:

​
When updating endpoint docs

The canonical source for the public API is api-reference/openapi.json in this repo — it is hand-maintained (the old generator source, apiDocSchema.ts in the app repo, no longer exists). When endpoints change in the app repo, update the spec here to match. Conceptual MDX pages (authentication, errors, rate-limits, best-practices) and webhook pages are also authored by hand and must be updated explicitly. The marketing site serves a checked-in copy of the spec at politicalcomms.com/openapi.json. Whenever api-reference/openapi.json changes here, run node scripts/sync-openapi.mjs in the political-comms-site repo and commit the result so the apex copy does not drift (the site’s deploy workflow warns on drift but does not block).