fix(docs): source Spectrum docs from main (#108)

Refs ENG-1881

Author: qwerzl

.github/workflows/deploy-dist.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main]
   repository_dispatch:
-    types: [spectrum-cloud-release]
+    types: [spectrum-cloud-release, spectrum-ts-docs]
 
 jobs:
   deploy:
@@ -23,7 +23,9 @@ jobs:
           app-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           owner: ${{ steps.parse-repo.outputs.owner }}
-          repositories: ${{ steps.parse-repo.outputs.name }}
+          repositories: |
+            ${{ steps.parse-repo.outputs.name }}
+            spectrum-ts
 
       - uses: actions/checkout@v4
         with:
@@ -40,11 +42,10 @@ jobs:
 
       - name: Generate docs from Vellum templates
         run: pnpm docs:generate
-        # sync-docs pulls per-source docs at the tag matching the installed
-        # package version. While a source still has a `local` fallback it stays
-        # offline; once a source is git-only, widen the app token's
-        # `repositories:` above to include that source repo so the clone can auth.
+        # sync-docs pulls per-source authored docs from the configured git ref
+        # while Vellum extracts types from the installed package versions.
         env:
+          DOCS_SOURCE_MODE: git
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
 
       - name: Push to dist branch

.github/workflows/typecheck-docs.yml

@@ -41,6 +41,8 @@ jobs:
 
       - name: Generate docs from Vellum templates
         run: pnpm docs:generate
+        env:
+          DOCS_SOURCE_MODE: git
 
       - name: Typecheck documentation code blocks
         run: pnpm typecheck:docs

README.md

@@ -9,13 +9,13 @@ This repo is an **aggregator**: some doc areas are authored here in [`docs-src/`
 `scripts/sync-docs` assembles a single template tree (`.vellum-src/`, gitignored) before vellum runs, from two places:
 
 - **Local** — most areas still live in [`docs-src/`](docs-src/) in this repo.
-- **Source repos** — areas listed in [`scripts/sources.json`](scripts/sources.json) are pulled from their SDK repo's `docs-site/` directory, at the git tag matching the installed package version (so prose stays aligned with the types vellum extracts). Edit those in the SDK repo, not here. Until a source repo has its `docs-site/`, sync falls back to the `local` path in the manifest, so the pilot keeps building offline.
+- **Source repos** — areas listed in [`scripts/sources.json`](scripts/sources.json) are pulled from their SDK repo's configured docs directory, at the configured git ref. For Spectrum, that is `photon-hq/spectrum-ts` `main` and the `docs/` directory, so prose fixes can ship without an SDK release. Vellum still extracts types from the installed package versions in this repo, so source-repo docs must stay compatible with the released package. Edit those docs in the SDK repo, not here. Local builds can use the `local` fallback in the manifest, but CI and deploy use `DOCS_SOURCE_MODE=git`.
 
 Navigation works the same way: [`docs.json`](docs.json) is **generated** by `scripts/build-nav` from [`docs.base.json`](docs.base.json) (the site skeleton) plus a `nav.json` fragment contributed by each source. Don't edit `docs.json` directly — edit `docs.base.json` or the fragment.
 
 ## How to edit
 
-1. **Edit the source, not the output.** Sources are `.mdx.vel` files in [`docs-src/`](docs-src/) (this repo) or a source repo's `docs-site/`. The rendered `.mdx` files and `docs.json` 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.
+1. **Edit the source, not the output.** Sources are `.mdx.vel` files in [`docs-src/`](docs-src/) (this repo) or the source repo docs directory configured in [`scripts/sources.json`](scripts/sources.json). The rendered `.mdx` files and `docs.json` 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:**
 
@@ -42,9 +42,13 @@ Push to `main` → [.github/workflows/deploy-dist.yml](.github/workflows/deploy-
 
 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.
 
+Source-repo doc updates can also trigger deploy through `repository_dispatch` type `spectrum-ts-docs`. Use that when `photon-hq/spectrum-ts` changes `docs/**` without a package release.
+
 ## Auto-updates from SDK releases
 
-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).
+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 so Vellum extracts the new released types. Older PRs for the same SDK are auto-closed by [.github/workflows/close-stale-version-prs.yml](.github/workflows/close-stale-version-prs.yml).
+
+For docs-only edits in a source repo, merge the change to the source repo's `main` branch and dispatch `spectrum-ts-docs` here. Do not cut a package release just to fix prose.
 
 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).
 

scripts/sources.json

@@ -1,14 +1,13 @@
 {
-  "$comment": "Doc sources aggregated into .vellum-src before `vellum build`. Each source mounts under .vellum-src/<mount>/ (mount == page-slug prefix). `docsDir` is the source repo's Mintlify-templates directory; we use `docs-site/` (NOT `docs/`, which several repos already use for internal dev notes). `package` is the installed npm package whose version selects the git tag (`<tagPrefix><version>`) to pull docs from, keeping prose aligned with the types vellum extracts. `local` is a path under this repo used as a fallback when the repo has no docs at that ref yet (transitional) or when forced via DOCS_SOURCE_MODE=local. Per-source ref override: DOCS_REF_<name> env (dots/dashes -> underscores).",
+  "$comment": "Doc sources aggregated into .vellum-src before `vellum build`. Each source mounts under .vellum-src/<mount>/ (mount == page-slug prefix). `docsDir` is the source repo's Mintlify-template directory. `ref` selects the source repo revision for authored docs; use main so prose fixes can ship without package releases. `package` records the installed npm package tied to the source; Vellum still extracts types from package.json dependencies. `local` is a path under this repo used as a fallback for offline local builds or when forced via DOCS_SOURCE_MODE=local. Per-source ref override: DOCS_REF_<name> env (dots/dashes -> underscores).",
   "sources": [
     {
       "name": "spectrum-ts",
       "mount": "spectrum-ts",
       "package": "spectrum-ts",
       "repo": "photon-hq/spectrum-ts",
-      "docsDir": "docs-site",
-      "tagPrefix": "v",
-      "ref": null,
+      "docsDir": "docs",
+      "ref": "main",
       "nav": "nav.json",
       "local": "docs-src/spectrum-ts"
     }

scripts/sync-docs/index.ts

@@ -8,8 +8,8 @@ import process from 'node:process'
 //   1. local templates in docs-src/ (areas not yet migrated + site-owned prose),
 //      minus any subtree owned by a source mount, and
 //   2. each source in scripts/sources.json, pulled from its repo via git
-//      (sparse checkout of <docsDir> at the tag matching the installed package
-//      version) or copied from a local fallback path.
+//      (sparse checkout of <docsDir> at the configured ref, usually main)
+//      or copied from a local fallback path.
 //
 // Each source's nav fragment is copied to .vellum-src/.nav/<mount>.json for
 // build-nav to merge. See ENG-1742.
@@ -86,8 +86,9 @@ function gitFetch(src: Source, ref: string): string | null {
   return existsSync(dir) ? dir : null
 }
 
-// Resolve a source to its on-disk docs directory, honoring DOCS_SOURCE_MODE and
-// falling back from git to local when a repo has no docs at the ref yet.
+// Resolve a source to its on-disk docs directory, honoring DOCS_SOURCE_MODE.
+// In strict git mode, failures are fatal. Without an explicit mode, local
+// fallbacks keep development offline while source repos finish migrating.
 function resolveContentDir(src: Source): string {
   const mode = process.env.DOCS_SOURCE_MODE as Mode | undefined
   const localDir = src.local ? resolve(ROOT, src.local) : null
@@ -100,10 +101,19 @@ function resolveContentDir(src: Source): string {
     return localDir!
   }
 
-  const wantGit = mode === 'git' || !hasLocal
-  if (wantGit) {
+  if (mode === 'git') {
     if (!src.repo)
-      throw new Error(`source "${src.name}": git mode requested but no "repo" configured`)
+      throw new Error(`source "${src.name}": DOCS_SOURCE_MODE=git but no "repo" configured`)
+    const ref = resolveRef(src)
+    const dir = gitFetch(src, ref)
+    if (!dir)
+      throw new Error(`source "${src.name}": repo has no ${src.docsDir ?? 'docs'}/ at ${ref}`)
+    return dir
+  }
+
+  if (!hasLocal) {
+    if (!src.repo)
+      throw new Error(`source "${src.name}": no local fallback and no "repo" configured`)
     try {
       const dir = gitFetch(src, resolveRef(src))
       if (dir)