> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# 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](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

```bash theme={null}
npx mint@latest dev          # local preview at http://localhost:3000
npx mint@latest validate     # strict build validation (run before push)
npx mint@latest broken-links # check internal link integrity
```

## Deployment

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

```bash theme={null}
curl -X POST https://api.mintlify.com/v1/project/update/6a03f47abee46be88e3dae86 \
  -H "Authorization: Bearer $MINTLIFY_ADMIN_KEY"
```

## 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 automated: pushing a change to `api-reference/openapi.json` on `main` runs `.github/workflows/sync-openapi-to-site.yml`, which opens a PR on political-comms-site with the updated `public/openapi.json`. Merge that PR and the apex copy follows. It needs a `SITE_SYNC_TOKEN` secret with `contents: write` + `pull_requests: write` on the site repo, since the default `GITHUB_TOKEN` cannot push cross-repo.

To sync by hand (before pushing, or if the workflow is down), run `node scripts/sync-openapi.mjs` in the political-comms-site repo. It 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.

Note that `main` is the branch Mintlify publishes and the branch both the workflow and the sync script pin to. It is **not** this repo's default branch, which is `dev`.