docs site is not deploying: `output: 'standalone'` + Next 16 Turbopack build → ENOENT on next-server.js.nft.json

[os-elon]

Reported by the maintainer, 2026-08-21: https://objectstack.ai/docs/ui does not show the React Pages entry. Confirmed by the maintainer that https://objectstack.ai is this repo's canonical docs site.

The content is on main and has been for hours

Fact	Evidence
content/docs/ui/react-pages.mdx exists on main	git ls-tree origin/main content/docs/ui/
It landed at 2026-08-20 17:27:49Z	commit 0bfbeb70c, docs(ui): document the html and react page authoring tiers (#10281)
react-pages is in the sidebar config	content/docs/ui/meta.json on main, entry 4, immediately after pages
Seven more new pages landed the same way overnight	epic #10206 — automation/jobs, automation/email-templates, data-modeling/import-mappings, data-modeling/object-extensions, permissions/capabilities, api/declarative-endpoints, ai/tools, plus the root nav fix adding the whole references tree

So this is not an authoring or a nav-config problem. The source is correct and merged; the site is not serving it.

Hypothesis — stated as a hypothesis, NOT verified

Every PR in this repo tonight carried a Vercel commit status reading:

"context": "Vercel", "description": "Canceled by Ignored Build Step"

The docs app lives at apps/docs/, but its content lives at content/docs/, outside that directory (source.config.ts resolves dir: path.resolve(process.cwd(), '../../content/docs')). A Vercel project rooted at apps/docs with the conventional "skip the build if this directory did not change" ignore step would therefore skip every content-only commit — which is exactly the observed symptom: pages merge, the site does not change.

I could not confirm this: there is no ignoreCommand in apps/docs/vercel.json and no ignore script under apps/docs/, so the rule is configured in the Vercel dashboard, which is not readable from an agent seat. Whoever takes this card should check the dashboard's Ignored Build Step first — if it is path-scoped to apps/docs, widening it to include content/** (and packages/spec/**, since build runs gen:schema && gen:docs before next build) is the fix.

Alternative causes worth ruling out in the same pass: a production deploy pinned to a branch or tag rather than main; a build that succeeded but served from cache; or the site being a separate deployment that syncs content on its own schedule.

Second defect, independent of the above: three canonical hosts in the tree

The maintainer's ruling is that objectstack.ai is canonical. Two repo artifacts disagree, and one of them is a gate that instructs authors:

Where	What it says	Effect
content/docs.site.json:5	"url": "https://protocol.objectstack.ai"	The site's own declared canonical URL — feeds metadata/OG/sitemap
scripts/check-published-readme-links.mjs	treats docs.objectstack.ai/docs/... as the docs site, and its remedy text tells authors to write https://docs.objectstack.ai/docs/<path>	A gate actively steering every published README toward a non-canonical host
maintainer, 2026-08-21	「这个仓的文档站规范 URL 是 https://objectstack.ai」	the actual answer

This is its own class of defect — a canonical URL that three places in one repo answer three ways cannot all be right, and the one with the loudest voice is the gate. It also plausibly contributed to this report: a reader following the repo's own configuration would look at protocol.objectstack.ai, and a reader following the link gate would look at docs.objectstack.ai.

Splitting note: the deploy problem and the host-name drift are separable and could be two cards. They are filed together because whoever fixes the deploy has to decide the host question to test the fix, and fixing the host strings without fixing the deploy would leave the docs equally invisible.

Why it matters now

Epic #10206 delivered eight merged PRs of new customer-facing documentation overnight — the React page guide, seven authorable-metadata guides, and the restoration of the entire 199-page generated Reference tree to the sidebar. If content-only commits do not deploy, none of it is reaching a single reader, and the same is true of every docs PR that has merged since the ignore rule was set.

[os-elon]

⛔ Retraction — my hypothesis in the body is WRONG. The build is not being skipped; it runs and fails.

The maintainer supplied the Vercel log. The Ignored-Build-Step theory is dead: the build executes and dies at the end of next build.

@objectstack/docs:build: > Build error occurred
@objectstack/docs:build: Error: ENOENT: no such file or directory, open
  '/vercel/path0/apps/docs/.next/next-server.js.nft.json'
@objectstack/docs:build:   errno: -2, code: 'ENOENT', syscall: 'open'
ERROR  command (/vercel/path0/apps/docs) pnpm run build exited (1)
Error: Command "cd ../.. && pnpm turbo run build --filter=@objectstack/docs" exited with 1

The Canceled by Ignored Build Step statuses I built that theory on are PR preview deploys, which are legitimately skipped. Production is a different deployment, and it is failing, not skipping. I inferred a cause from an adjacent signal instead of from the failing build's own log — the log was always the reading that mattered.

The actual mechanism

.nft.json files are Next's output file tracing artifacts. next-server.js.nft.json is what the output: 'standalone' assembly step reads to decide which node_modules files to copy into the standalone bundle. It is absent, so the step throws ENOENT.

Three measured facts from origin/main:

Fact	Evidence
The app requests standalone output	apps/docs/next.config.mjs:9 — output: 'standalone'
It builds with Turbopack	next is 16.3.1 (apps/docs/package.json:22), where Turbopack is the default build engine; next.config.mjs also carries a turbopack: { resolveAlias: … } block, so it is definitely the active engine
Nothing consumes the standalone output	apps/docs/.next/standalone has zero references across Dockerfiles, workflows, scripts and configs; docker/Dockerfile does not build apps/docs at all (its only "docs" matches are doc URLs in comments)

Turbopack builds do not emit the node-file-trace .nft.json set that the standalone packer expects. output: 'standalone' + a Turbopack build is therefore a contradiction inside one config, and the ENOENT is that contradiction surfacing.

Likely fix: delete output: 'standalone'. It exists for self-hosted/Docker deployment, nothing in this repo consumes it, and Vercel does its own serverless packaging — so on this deployment target it is not merely unnecessary, it is the thing breaking the build. The alternative, forcing the Webpack builder so tracing is emitted, keeps a setting that still serves no consumer.

⚠️ Whoever takes this should confirm the "no consumer" reading on a full clone before deleting. My clone is shallow (git rev-parse --is-shallow-repository → true, 158 commits), so I could not date when output: 'standalone' or Next 16 arrived, and therefore cannot say how long the site has been stale or which change introduced the contradiction. That window is worth establishing — it bounds how much merged documentation has never reached a reader.

The bigger finding: Build Docs is green while production is red

CI runs a Build Docs job, and it passes — it went red-then-green on #10333 earlier tonight and has been green on every epic PR since. Yet the production build of the same app fails. A gate named after the thing it protects, passing while that thing is broken, is worth more attention than this deploy incident: it means no PR in this repo can be trusted to have proven the docs site still builds as deployed.

Establishing why the two diverge — different command, different Next flags, cached .next, or Vercel-injected build config — is part of this card, not a footnote. ci.yml caches apps/docs/.next/cache across runs, which is one candidate: a warm cache can hide a cold-build failure.

Unchanged from the body

The canonical-host drift stands and gains a fourth site: docker/Dockerfile also points readers at https://docs.objectstack.ai/docs/.... So objectstack.ai (the maintainer's ruling), protocol.objectstack.ai (docs.site.json), and docs.objectstack.ai (the link gate and the Dockerfile) are all live in one tree.

---

Generated by Claude Code

[os-elon]

Claim: PM loop (post-epic #10206), P0
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10638-docs-standalone-build
Worktree: objectstack-issue-10638
Domain: domain:devx
File surface: apps/docs/next.config.mjs primarily; apps/docs/package.json / apps/docs/vercel.json only if the reproduction proves they are part of the fix (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — dispatch-gates.mjs --tier derives no path-based mandate; not a contract surface; PM judgment call, raised from the mechanical floor because the fix rests on an unproven hypothesis
Clause-②: no
Serial constraints cleared: no other open PR touches apps/docs/next.config.mjs. #10641 is dispatched in parallel and owns content/docs.site.json, scripts/check-published-readme-links.mjs and docker/Dockerfile — disjoint. #10642 is pm:blocked behind this card and touches nothing until it closes.

P0 because the docs site is dark. Epic #10206 merged eight PRs of customer-facing documentation to main yesterday and none of it is reachable. Every docs PR that merges while this stands is also invisible.

---

Generated by Claude Code