docs deploy: every push to main rebuilds the docs site — 98.6% of the team's build time, $171/mo, and a 92-deep queue; turbo-ignore alone would silently stop publishing docs #12743

The docs project rebuilds on every push to main, and almost none of those pushes change what the site renders. Measured over the last 7 days across the whole team:

Three consequences, all measured:

1. Head-of-line blocking. The team has concurrentBuilds: 1. An 18-second objectui build queues behind a 12–46 minute docs build. At the time of writing the team queue held 92 deployments, the oldest 34 hours old.
2. Cost. ~977 docs builds/month at 4 vCPU ≈ $171/month against a $20 included allowance — and in the last 7 days 168 of 228 were failures, so most of it bought nothing.
3. Risk. Every unnecessary build is another chance to hit the memory ceiling measured in docs deploy: production builds are OOM-failing now — the peak is the Turbopack compile phase, not the prerender; turbopackSourceMaps is a free knob #12683's option set missed #12711.

The project's Ignored Build Step is currently if [ "$VERCEL_ENV" == "production" ]; then exit 1; else exit 0; fi — production always builds, preview always skips. The preview half is right. The production half is the waste.

⚠️ The obvious fix is wrong, and would silently stop publishing docs

#12698 suggests npx turbo-ignore @objectstack/docs. Measured: that alone loses documentation updates.

turbo --filter=<pkg>...[range] decides which packages changed by package directory. This repo's MDX lives at the repo root in content/docs/**, outside the apps/docs package boundary. turbo.json does declare "$TURBO_ROOT$/content/**" in @objectstack/docs#build's inputs — but inputs only feeds the cache hash, it does not widen the affected-package calculation.

Verified against real commits on main:

So turbo-ignore must be combined with an explicit path check, not used on its own.

Proposed shape

apps/docs/vercel.json gains an ignoreCommand (which per Vercel docs overrides the dashboard Ignored Build Step, so this moves the rule into version control where it can be reviewed and reverted):

1. non-production → exit 0 (skip) — preserves today's behaviour exactly
2. content/** or apps/docs/** changed since the last successful deploy → exit 1 (build)
3. otherwise → hand off to turbo-ignore for the dependency-graph verdict (catches packages/spec etc.)
4. anything indeterminate (no previous SHA, shallow clone, git object missing) → build, never skip

Rule 4 matters: Vercel builds from a shallow clone, so the previous-SHA comparison can legitimately fail. The failure mode of this whole change must be "build unnecessarily", never "silently skip".

Relationship to #12698

Opposite direction, so it is filed separately rather than as a comment there. #12698 argues the ignore step skips too much (it read a PR's Preview being skipped as production being skipped — corrected in #12711). This card argues production skips too little. #12698's suggested command is adopted here only as one branch of the rule, with the content/** gap above closed.

Refs: #12711 (memory ceiling — every avoided build is one less chance to hit it) · #12698 (correction) · #12683.