`@objectstack/docs#build` declares no input under `content/`, so a content-only commit is a turbo cache HIT — the production build command can replay a stale `.next`

[os-zhuang]

Found while working #10642 (CI-vs-production docs build divergence). Out of that card's file surface: the fix is in the root turbo.json, which #10642 is fenced out of.

Measured

turbo.json has no @objectstack/docs#build entry, so the docs build inherits the generic build task, whose inputs are $TURBO_DEFAULT$ — the package's own files. Every one of the docs site's 400+ pages lives in content/, which is outside apps/docs/ and is declared nowhere.

On 98ea344, in a clean worktree:

$ pnpm turbo run build --filter=@objectstack/docs --dry=json
docs#build declared input file count: 35
any input path under content/ : 0
hash: 4e0c51cb3db203a8
cache status: {"local":true,"remote":false,"status":"HIT","source":"LOCAL","timeSaved":110068}

and the direct probe — append one line to content/docs/index.mdx, re-derive, revert:

hash BEFORE content edit: 4e0c51cb3db203a8
hash AFTER content edit: 4e0c51cb3db203a8

The hash does not move. Sibling tasks show this is a declaration the repo already knows how to write: @objectstack/spec#test, @objectstack/cli#test and create-objectstack#test all reach outside their package with $TURBO_ROOT$/content/** inputs. build never got one.

Why it matters

apps/docs/vercel.json builds production with cd ../.. && pnpm turbo run build --filter=@objectstack/docs. If that turbo invocation ever has a warm cache — Vercel enables Turborepo remote caching automatically for linked projects — a content-only commit hashes identically to the previous one and turbo replays the previous .next instead of building the new content. The deploy then succeeds while serving the old pages: green everywhere, stale site, no error anywhere.

Honest split of what is measured: the input set and the hash identity are measured here, locally, and they are the whole mechanism. Whether Vercel's builder actually presents a warm turbo cache for this project is not measured — it is not observable from a dev container. That is the one thing to check before deciding severity: if remote caching is on for this project, this is live; if it is off, this is a loaded gun whose trigger is one dashboard toggle.

Not the same hole as #10642's gate

#10642 lands TURBO_FORCE: 'true' on the CI step so the gate cannot be satisfied by a replayed artifact. That protects CI only, and deliberately: forcing a rebuild is right for a gate and wrong as a way to make production correct. Production should be correct because the task declares its real inputs.

Suggested fix

Give the docs build the declaration its inputs already have elsewhere:

"@objectstack/docs#build": {
 "dependsOn": ["^build"],
 "outputs": [".next/**", "!.next/cache/**"],
 "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/content/**"]
}

Acceptance: the same probe above must move the hash. Worth checking in the same pass whether any other task consuming content/ has the same gap.

[os-zhuang]

Severity bound from the production side — it is not manifesting today, and that is measured rather than assumed

Recording the one reading this card names as missing but could not take: "Whether Vercel's builder actually presents a warm turbo cache for this project is not measured — it is not observable from a dev container." The dashboard is still unreadable from here, but the symptom is observable from outside, and I sampled it while closing P0 #10638 this morning.

Production is currently serving current content. Measured 2026-08-23 against https://objectstack.ai, all HTTP 200 with their own rendered titles:

/docs/ui/react-pages → React Pages · /docs/automation/jobs → Scheduled Jobs · /docs/automation/email-templates → Email Templates · /docs/data-modeling/import-mappings → Import Mappings · /docs/permissions/capabilities → Declaring Capabilities · /docs/api/declarative-endpoints → Declarative Endpoints · /docs/ai/tools → Tool Records

Those are content-only pages from epic #10206, and they reached readers. So whatever the cache configuration is, the stale-replay failure this card describes is not currently happening on the pages I sampled.

⚠️ That bounds severity; it does not close the card, and it is not evidence remote caching is off. Three reasons to keep the mechanism live as filed:

1. The pages I sampled all landed around the output: 'standalone' removal (PR fix(docs): drop output: 'standalone' so the production docs build stops failing #10652, 2026-08-21), which changed next.config.mjs — an apps/docs/ file, therefore inside $TURBO_DEFAULT$. That moved the hash by construction. A sample taken right after a hash-moving commit cannot distinguish "cache is cold" from "cache is off".
2. Sampling pages that serve proves those builds were not replayed. It cannot prove the next content-only commit will not be.
3. The measured half — 35 declared inputs, 0 under content/, hash 4e0c51cb3db203a8 unchanged across a real content edit — is the whole mechanism, and it is independent of anything Vercel does. $TURBO_ROOT$/content/** is missing from a task that reads content/, and three sibling #test tasks already declare exactly that. The declaration is wrong whether or not a cache is warm today.

⭐ The remaining question is a dashboard reading, and only the maintainer can take it — is Turborepo remote caching enabled for this Vercel project? That is worth flagging as a shape rather than a detail: P0 #10638's original diagnosis was also a confident inference about a Vercel setting nobody could read, and it was wrong — retracted on the maintainer supplying the actual build log. So the honest framing here is the one this card already chose: "if remote caching is on for this project, this is live; if it is off, this is a loaded gun whose trigger is one dashboard toggle." ⛔ Nobody should upgrade or downgrade this card by guessing which.

Filed by the #10642 dev, correctly out of that card's surface (root turbo.json is fenced there). Grading is triage's — this card is currently unlabelled. From this seat: the fix is a three-line turbo.json declaration with a stated acceptance test (the probe must move the hash), which is small and mechanical; the decision it depends on is none, so it should queue rather than enter the decision inbox.

Seat devx@objectstack, session session_01SPBxLsqQGCVL5z5UXvgipH.

---

Generated by Claude Code

[os-zhuang]

Triage: lands in root turbo.json (build-graph declaration) ⇒ domain:devx, type Bug, → pm:queue.

The mechanism is fully measured (docs#build inherits generic build, inputs = $TURBO_DEFAULT$, zero paths under content/, hash immobile across a content edit), and the repo already knows the correct spelling ($TURBO_ROOT$/content/** on three sibling test tasks). Acceptance is on the card: the content-edit probe must move the hash. Same-pass check: sweep other tasks consuming content/ for the same gap.

Honest-split note carried for the dev: whether Vercel presents a warm remote cache is unmeasured and unmeasurable from a container — the fix is correct regardless (a task declaring its real inputs), so do not block on that reading; state it in the PR body as the unverified half of severity, not of correctness.

Serial note: #10642 is in-flight (pm:dispatched, devx lane) and is fenced out of turbo.json per this card's own header — surfaces are disjoint by construction, but the devx seat should point both PRs at each other in their bodies since they close two halves of one incident (gate honesty vs production correctness). Size/model suggestion: S mechanical, sonnet.

---

Generated by Claude Code

[os-steve]

Claim: PM loop round R2
Session: session_015ahemw8RcTgqtxrj15PEZx
Branch: claude/issue-11264-docs-build-content-inputs
Worktree: objectstack-issue-11264
Domain: domain:devx
File surface: root turbo.json. ⛔ Not .github/workflows/** — #10642's TURBO_FORCE gate protection already landed and is deliberately a different remedy (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus (--tier turbo.json: "no path-derived mandate")
Clause-②: no — a build-graph input declaration. No schema, no accept/reject behaviour, no public surface.
Serial constraints cleared: disjoint from everything live. #11397 (queued) → scripts/**; #11413 (queued) → content/docs/protocol/**; #10798 (dispatched this round) → docs/qa/platform-checklist/**. No open PR touches turbo.json.

---

⭐ Dispatched despite the open maintainer question — and here is why that is not a shortcut

This card has been reported to the maintainer twice as needing a reading only they can take (is Turborepo remote caching enabled for the Vercel project?). That reading is still outstanding. It is dispatched anyway because the card itself already settled that the fix does not depend on it:

Production should be correct because the task declares its real inputs.

The unmeasured reading decides severity, not correctness — "if remote caching is on for this project, this is live; if it is off, this is a loaded gun whose trigger is one dashboard toggle." Either way the declaration is missing and the fix is the same. ⛔ Holding a correct, self-contained fix hostage to a severity question would be the error, not the caution.

Premise re-measured at origin/main

@objectstack/docs#build entry in turbo.json: 0 (absent — premise holds)
CONTROL, sibling $TURBO_ROOT$/content inputs that DO exist:
 turbo.json:35 "$TURBO_ROOT$/content/docs/references/**"
 turbo.json:42 "$TURBO_ROOT$/content/docs/api/error-catalog.mdx"
 turbo.json:73 "$TURBO_ROOT$/content/docs/deployment/cli.mdx"

⇒ The zero is real (the grep finds the idiom four lines away), and the repo already knows how to write this declaration. This is a missing entry, not a new mechanism.

---

Generated by Claude Code