docs: add how to edit

Author: qwerzl

README.md

@@ -1,44 +1,44 @@
-Photon Docs
+# Photon Docs
 
-AI-assisted writing
+The documentation site at [photon.codes](https://photon.codes/), built with [Mintlify](https://mintlify.com/) and driven by [vellum](https://github.com/photon-hq/vellum). Vellum extracts type information from installed npm packages and renders `.mdx.vel` templates into the `.mdx` files Mintlify ships.
 
-Set up your AI coding tool to work with Mintlify:
+## How to edit
 
-```bash
-npx skills add https://mintlify.com/docs
-```
+1. **Edit the source, not the output.** Sources live in [`docs-src/`](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.
 
-This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance.
+2. **Render and preview locally:**
 
-See the [AI tools guides](/ai-tools) for tool-specific setup.
+   ```bash
+   pnpm install
+   pnpm docs:generate         # vellum: .mdx.vel -> .mdx
+   mint dev                   # preview at http://localhost:3000
+   ```
 
-Development
+   If you don't have the Mintlify CLI: `npm i -g mint`.
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
+3. **Verify before opening a PR:**
 
-```
-npm i -g mint
-```
+   ```bash
+   pnpm lint
+   pnpm typecheck:docs
+   ```
 
-Run the following command at the root of your documentation, where your `docs.json` is located:
+4. **Open the PR against `main`.** Don't commit rendered `.mdx` files — they're regenerated by CI.
 
-```
-mint dev
-```
+## How deployment works
 
-View your local preview at `http://localhost:3000`.
+Push to `main` → [.github/workflows/deploy-dist.yml](.github/workflows/deploy-dist.yml) runs `pnpm docs:generate` and force-pushes the rendered tree to the `dist` branch → Mintlify rebuilds from `dist`.
 
-Publishing changes
+The Spectrum API reference is generated from a remote OpenAPI spec configured in [docs.json](docs.json), fetched at build time, so every rebuild picks up the latest API surface without a docs commit.
 
-Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
+## Auto-updates from SDK releases
 
-Need help?
+When a connected SDK ships a release (e.g., [`spectrum-ts`](https://github.com/photon-hq/spectrum-ts), [`advanced-imessage-ts`](https://github.com/photon-hq/advanced-imessage-ts)), its release workflow calls [`photon-hq/buildspace/.github/workflows/update-docs.yaml`](https://github.com/photon-hq/buildspace/blob/main/.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](.github/workflows/close-stale-version-prs.yml).
 
-Troubleshooting
+To enroll a new SDK, add `.github/workflows/update-docs.yaml` to its repo following the pattern in [advanced-imessage-ts](https://github.com/photon-hq/advanced-imessage-ts/blob/main/.github/workflows/update-docs.yaml).
 
-If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
-If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+## Troubleshooting
 
-Resources
-
-Mintlify documentation](https://mintlify.com/docs)
+- **`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.