fix(docs): delete the shadowed root route; proxy.ts owns /

[os-zhuang]

Fixes#12255

apps/docs/app/page.tsx contained redirect('/docs') and never ran. proxy.ts
rewrites / to /en before routing, so app/[lang]/page.tsx serves the homepage.
It was code that grep finds and the runtime never executes — AGENTS.md
"Route & surface ownership" rule 1 — and its content was also wrong for today's
site, which no longer forwards / to the docs.

The decision, and what decided it

The card left two honest end states open: delete the file, or keep it as a real
fallback. The deciding question was measurable — with app/page.tsx deleted,
what does / do under a production build, and is there a reachable configuration
where deletion costs something? Four configurations were built and served.

What was measured

Local production build only. Production has not redeployed since ~16:55 on
2026-08-25 (#12333), so the live site is evidence about a two-hour-old build and
was not used. Each row is its own pnpm --filter @objectstack/docs build
(Next 16.3.1, exit 0) followed by next start and curl:

app/page.tsx	proxy.ts	GET /	GET /en	GET /docs
present (main today)	present	200 text/html, 72117 B, homepage, canonical https://objectstack.ai	307 to /	200, 211597 B
absent (this PR)	present	200 text/html, 72117 B, homepage, same canonical	307 to /	200, 211597 B
absent	absent	404, 8686 B, Next default error page	200 homepage	404
present	absent	307 to /docs — and /docs is itself a 404	200 homepage	404

Route table from the same builds: with the file present the build emits a /
entry; without it, / is gone and /en is still prerendered under /[lang].
The proxy line Proxy (Middleware) is present in rows 1–2 and absent in rows 3–4
(counted from the build logs, not assumed).

Byte-level check on row 2 versus row 1: the two / responses are 72117 bytes
each and differ in exactly two spans, both of them the Next build id
(0YebRTq5hijtQuB6iqeqN versus 3CUsAVIGaUla2OR4S-KdV), which changes on every
build. /docs — untouched by this diff — differs in the same way and only that
way, which is the control that identifies the difference as build-id noise rather
than a content change. RSC and prefetch requests to / (RSC: 1,
Next-Router-Prefetch: 1), a query-string request, and HEAD / were probed in
both rows and match status-for-status. /sitemap.xml and /robots.txt are
byte-identical (md5 equal) across the two.

What would have changed the answer

A reachable configuration in which / degrades and the rest of the site does
not — that is what a fallback is for. Row 3 shows there is no such
configuration: when the proxy does not run, every unprefixed path 404s,
/docs included; only /en/** answers. So the file cannot be a partial-
degradation safety net.

Row 4 measures the fallback option on its merits and it loses on its own terms:
with the file present and the proxy not running, / answers 307 to /docs,
which is a 404 in that same configuration. The "fallback" forwards one URL out
of a 404 and into another — and it makes the failure quieter, because /
answers 307 instead of 404 while the site is comprehensively broken. That is
the wrong direction for AGENTS.md rule 3, "absence must be loud". Rewriting the
file to redirect to /en instead would have the same defect: it only matters in
a configuration where nothing else works, and it would still soften the signal.

Had row 3 shown / 404ing while /docs kept working, the fallback would have
won and this PR would have rewritten the file instead of removing it.

proxy.ts is untouched: the measurement says the fix does not belong there. The
proxy handles / correctly, and its matcher is #12233's surface.

Why it is worth doing at all

Epic #12243 has cards adding metadataBase, canonical links and JSON-LD to the
homepage (#12234, #12240). An agent that puts the homepage's canonical in
app/page.tsx ships a green PR that changes nothing served; that trap has had to
be written into three dispatch prompts as a warning. Deleting the file closes it
at the source — grep no longer finds a root page to reason from.

Verification

Gate union re-run after the final commit, at afbe56173:

check	verdict line
pnpm check:docs-locale-catch-all	VERDICT command-exit 0 — "1 top-level dynamic segment(s), 1 guarded; dotted paths bypass proxy.ts: true"
pnpm check:page-declaration-shape	VERDICT command-exit 0 — "34 page entries across 2188 sources … all reach the kernel through a discoverable declaration"
pnpm check:published-files	VERDICT command-exit 0
pnpm check:test-source-alias	VERDICT command-exit 0
pnpm check:type-source-resolution	VERDICT command-exit 0
pnpm check:nul-bytes	VERDICT command-exit 0 — "scanned 6833 text file(s) … no raw ASCII control bytes"
pnpm --filter @objectstack/docs typecheck	VERDICT command-exit 0
pnpm --filter @objectstack/docs build	exit 0 (typescript.ignoreBuildErrors: false, so the build is a type gate too)

The five check:* families are the ones node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
derives for this diff; re-derived after the commit and unchanged.

Declared narrowing — lint.pnpm lint (eslint . --no-inline-config over
the whole repo) was not run; CI runs it. Narrowed to every hand-written source
file in the app this diff touches: eslint apps/docs/app apps/docs/lib apps/docs/components apps/docs/proxy.ts --no-inline-config --format json
→ 24 files linted, 0 errors, 0 warnings (count read from the JSON output, not
from a summary line). The narrowing excludes nothing that this diff could move:
eslint.config.mjs is unchanged and, by its own docblock, "never enables
type-aware linting (no parserOptions.project, no typed
@typescript-eslint rules) for ANY file", so no untouched file's verdict can
depend on a file being deleted. The diff also adds and modifies zero files, so
the set eslint lints after this change is exactly the set before it, minus one.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock (the lock
is Linux-only; a stock macOS does not ship util-linux). Every command above ran
through the entry point, which reported UNLOCKED (declared) each time. No
serialization guarantee held for these runs.

Landing notes

Docs-site only, publishes nothing — no changeset; skip-changeset applied.
Nothing outside apps/docs/app/page.tsx is touched: app/[lang]/** is #12240's
surface right now and proxy.ts is #12233's, and neither is in this diff.

Generated by Claude Code