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. Keeping it in step is a MANUAL step and part of every spec change: run node scripts/sync-openapi.mjs in the political-comms-site repo, then commit the updated public/openapi.json there. The script reads a sibling political-comms-docs checkout when one exists, otherwise the GitHub API at political-comms-docs@main (needs GITHUB_TOKEN/GH_TOKEN; this repo is private). Never trust the docs CDN as the source: docs.politicalcomms.com caches the spec for 30 minutes, so for half an hour after a deploy it serves the previous version, and a sync that reads it will overwrite the checked-in copy with stale content while reporting success. The site’s deploy workflow warns on drift against main, but does not block - the warning is the backstop for a forgotten sync. (A sync-openapi-to-site.yml workflow briefly automated this in July 2026; it was removed 2026-07-29 because it required a cross-repo SITE_SYNC_TOKEN PAT the owner does not want to maintain. Do not re-add it without asking.) Note that main is the branch Mintlify publishes and the branch the sync script pins to. It is not this repo’s default branch, which is dev.