Photon Docs

The documentation site at photon.codes, built with Mintlify and driven by vellum. Vellum extracts type information from installed npm packages and renders .mdx.vel templates into the .mdx files Mintlify ships.

How to edit

1. Edit the source, not the output. Sources live in docs-src/ as .mdx.vel files. The rendered .mdx files at the repo root are build artifacts — gitignored on main, only present on the dist branch. Don't edit them directly; they get overwritten on every deploy.

2. Render and preview locally:

   pnpm install
   pnpm docs:generate         # vellum: .mdx.vel -> .mdx
   mint dev                   # preview at http://localhost:3000

   If you don't have the Mintlify CLI: npm i -g mint.

3. Verify before opening a PR:

   pnpm lint
   pnpm typecheck:docs

4. Open the PR against main. Don't commit rendered .mdx files — they're regenerated by CI.

How deployment works

Push to main → .github/workflows/deploy-dist.yml runs pnpm docs:generate and force-pushes the rendered tree to the dist branch → Mintlify rebuilds from dist.

The Spectrum API reference is generated from a remote OpenAPI spec configured in docs.json, fetched at build time, so every rebuild picks up the latest API surface without a docs commit.

Auto-updates from SDK releases

When a connected SDK ships a release (e.g., spectrum-ts, advanced-imessage-ts), its release workflow calls photon-hq/buildspace/.github/workflows/update-docs.yaml. That workflow uses Claude Code to draft a docs/update-{sdk}-v{version} PR here, bumping the package and updating any prose or types that drifted. Older PRs for the same SDK are auto-closed by .github/workflows/close-stale-version-prs.yml.

To enroll a new SDK, add .github/workflows/update-docs.yaml to its repo following the pattern in advanced-imessage-ts.

Troubleshooting

• mint dev shows 404s: make sure you're running it at the repo root where docs.json lives, and that pnpm docs:generate completed without errors first.
• CLI behaves oddly: mint update.
• OpenAPI looks stale on the live site: trigger the docs rebuild so Mintlify re-fetches the spec — push any commit to main, or fire the repository_dispatch from the relevant backend release.