A 404 under /docs serves a blank error shell, not the 404 page — notFound() from a docs page never renders server-side

(Rewritten after the first dispatch falsified this card's proposed fix. The diagnosis below stands; the fix, the file surface and the reproduction command have all changed. Full measurement in the adjudication comment.)

(Angle-bracket markup omitted throughout — this repo's sanitizer strips it.)

What happens

There are two different ways to reach a 404 on this site, and only one of them works.

request	what Next serves	result
`/no-such-page` (matches no route at all)	the prerendered `/_not-found` route	correct 404 page, language declared
`/docs/no-such-page` (route matches, page calls `notFound()`)	an error shell	blank page

For the second case the served document is Next's error shell — a root element carrying id="__next_error__", the site's default title, and a body containing only scripts. The "404 / This page could not be found." markup is present in the streamed RSC payload but never reaches the server-rendered HTML.

The status code is correct (404). It is the body that is empty.

Root cause — measured, not inferred

In Next 16.2.6, a notFound() raised during a dynamically rendered request escapes both the RSC and the SSR render. Next then builds the response from getErrorRSCPayload, which seeds the document as an empty error-shell root and ships the real 404 tree only in the RSC payload for the client to hydrate. No not-found boundary at any depth participates in that server render.

Corroborated in the installed Next source: app-render.js:1999 takes the dynamic error path into getErrorRSCPayload (line 1089, whose own comment reads "For metadata notFound error there's no global not found boundary on top so we create a not found page with AppRouter"), whereas line 4326 takes the prerender path through the normal getRSCPayload.

That is why the first row of the table works: an unmatched URL is a prerendered page render, not a boundary.

Reproduction — note the corrected command

cd apps/docs && pnpm run build && npx next start -p 3187

A raw grep on the response cannot tell server-rendered markup from the RSC payload, and will score a page as containing the 404 text when that text is only in the streamed payload. Strip script bodies first, or the check reports this card as already fixed:

# works — text is in the markup
curl -s http://localhost:3187/no-such-page | perl -0pe 's/<script.*?<\/script>//gs' | grep -c "could not be found"      # 2

# blank — text exists only in the payload
curl -s http://localhost:3187/docs/no-such-page | perl -0pe 's/<script.*?<\/script>//gs' | grep -c "could not be found" # 0
curl -s http://localhost:3187/docs/no-such-page | grep -c "__next_error__"                                              # 1

Same for a locale-prefixed path: /zh-Hans/docs/no-such-page, /ja/docs/no-such-page. Body is 225 bytes. Measured on origin/main at d394550 — the defect survives all eight PRs merged since this card was filed.

notFound() is raised from apps/docs/app/[lang]/docs/[[...slug]]/page.tsx whenever source.getPage() misses, so this is the path every mistyped or retired docs URL takes.

Why it matters

Every dead docs link — stale bookmarks, old external references, retired pages — serves a visually blank page to anyone whose browser has not run the client bundle, and to every crawler.
This repo carries permanent redirects for a past docs restructure (next.config.mjs maps four moved build/* paths), which is direct evidence that inbound links to since-moved docs paths exist in the wild. Anything moved without a redirect lands here.
The current state is the dangerous kind of broken: the client fills the page in, so it looks correct to anyone testing by eye.

The fix

dynamicParams = false on apps/docs/app/[lang]/docs/[[...slug]]/page.tsx. Unknown slugs then stop rendering the page dynamically and resolve to the prerendered /_not-found route — the mechanism that already works.

Measured working on a full production build: /docs/no-such-page returns 404 with errorshell=FALSE, the 404 text present in the markup, lang=en; /zh-Hans/docs/no-such-page likewise.

Accepted property change: a docs page added without a rebuild would 404 rather than render on demand. Every page here comes from local MDX enumerated by generateStaticParams, so this is already true in practice; #190 set the same flag on the OG route for the same reason.

Do not add app/[lang]/not-found.tsx. It was built and measured: byte-identical output, identical route table, defect unchanged. It cannot work, for the reason in the root-cause section.

Scope

This card is now the server-rendered body only. Declaring the requested locale on a docs 404 is a separate card — it needs the locale to come from above the [lang] segment via a middleware-set header read through headers(), which makes /_not-found dynamic. Larger property change, unverified, smaller payoff.

Verification

/docs/no-such-page and /zh-Hans/docs/no-such-page — 404 preserved, 404 text present in the markup (use the stripped-script command above), no __next_error__ shell.
/no-such-page — unchanged from what Every page in all seven locales declares lang="en" on the root html element #168 established.
Static page count holds at what main builds today (577).
Check next dev as well as the production build — fix(docs): derive the document language from the locale route segment #181 found that the missing-root-layout validator runs only there.

Triaged pm:queue / Bug. Labelling note plus one angle the report surfaced that is worth keeping visible.

The detail that matters beyond the visual defect: the 404 markup reaches the RSC payload but never the server-rendered HTML. So the failing audience is specifically the one that does not run JavaScript — crawlers, and no-JS clients. Everyone with a browser sees the page fill in and never notices.

Scoping that honestly, because it would be easy to overstate:

This is not a ranking problem. The HTTP status is a correct 404, measured. A crawler is told the page does not exist, which is the truthful answer, and a 404 with an empty body is not penalised — it is simply uninformative.
It is a real user-facing defect for a documentation site. This repo carries permanent redirects for a past restructure (next.config.mjs maps four moved build/* paths), which is evidence that inbound links to since-moved docs paths exist in the wild. Anything moved without a redirect lands here, and a reader who followed a stale link to /docs/<something-renamed> gets a blank page with no navigation back into the docs.

So: worth fixing, not urgent, and it should not be priced as an SEO card. pm:queue rather than a release blocker.

Confirmed pre-existing on origin/main at ee74379, byte-for-byte identical to the #168 branch, so #181 neither caused nor worsened it. The likely fix named in the report — a not-found boundary inside the locale segment — is untested; whoever takes this should verify that placement actually renders server-side before building on it, since the structural reason app/not-found.tsx cannot cover this path (its boundary sits above the locale layout, which has already emitted a shell) may well apply again in a different form.

Related and worth reading together: #180, the other 404-adjacent defect found in the same pass — a first URL segment containing a dot bypasses the locale middleware and returns HTTP 500 rather than 404. Different root cause, same neighbourhood, also pre-existing.

Generated by Claude Code

Claim: PM loop round 4
Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-182-locale-notfound-boundary
Worktree: objectos-issue-182
Domain: n/a (objectos carries no domain:* lanes)
File surface: apps/docs/app/[lang]/not-found.tsx (new file). Touching apps/docs/app/[lang]/layout.tsx is permitted only if the boundary provably cannot work without it — report the evidence if so. (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — PM judgement.
Clause-②: no
Serial constraints cleared: #185 is dispatched alongside this one on lib/source.ts, the OG route and page.tsx. This card must not touch any of those three — notFound() is already raised from page.tsx and needs no change there. Read coupling: neither card asserts anything about the other's surface.

The card's own "likely shape of the fix" is a hypothesis, not an adjudication — a boundary inside the locale segment rendering only the 404 content, no shell, since app/[lang]/layout.tsx already emits one. Test it before building on it; #181 established that Next's boundary placement here is not obvious.

Generated by Claude Code

Dev claim (separate from the PM claim above).

Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-182-locale-notfound-boundary (pushed empty at d394550, write route verified)
Worktree: /home/user/objectos-issue-182 off origin/main @ d394550
File surface: apps/docs/app/[lang]/not-found.tsx (new). apps/docs/app/[lang]/layout.tsx only if the boundary provably cannot work without it, with evidence in the PR.
Not touching: apps/docs/lib/source.ts, apps/docs/app/og/docs/[...slug]/route.tsx, apps/docs/app/[lang]/docs/[[...slug]]/page.tsx — #185 owns all three.

Card verified intact: angle-bracket-free as written, nothing stripped by the sanitizer.

Treating the card's proposed app/[lang]/not-found.tsx as a hypothesis. Measuring what a [lang]-level boundary actually does here — nests, replaces, or is bypassed — before writing the implementation, per #181's finding that boundary placement in this app is counterintuitive.

Generated by Claude Code

os-dev-report

(Angle-bracket markup omitted throughout, same as the card — this repo's sanitizer strips it.)

{
  "issue": 182,
  "status": "needs_decision",
  "branch": "claude/issue-182-locale-notfound-boundary",
  "pr": null,
  "premise_still_valid": true,
  "files_changed": [],
  "gates": {
    "build_prod": "PASS x5 (apps/docs, next 16.2.6). Baseline and every experiment built clean; os-verify-lock VERDICT command-exit 0 each time.",
    "next_dev": "PASS. Dev starts clean, compiles, and reproduces the defect identically. No missing-root-layout validator break at any point.",
    "static_page_count": "577 on baseline; 577 with the proposed boundary added; route table byte-identical (diff empty).",
    "typecheck_lint": "NOT RUN - NOT MEASURED. The working tree is byte-identical to origin/main (zero changed files), so these would only have re-tested main.",
    "final_tree": "clean; HEAD d394550 == origin/main d394550; git status empty"
  },
  "summary": "The card's proposed fix is FALSIFIED. I built the proposed app/[lang]/not-found.tsx and measured it: output is byte-identical to baseline, route table identical, 577 static pages unchanged, /docs/no-such-page still serves the __next_error__ shell. Root cause is not boundary placement: in Next 16.2.6 a notFound() raised during a DYNAMICALLY rendered request escapes both the RSC and SSR renders, and Next builds the response from getErrorRSCPayload, which seeds the document as an empty error-shell root element and ships the real 404 tree only in the RSC payload for the client. No not-found boundary at any depth participates in that server render. The working case is structurally different: an unmatched URL is served by the PRERENDERED /_not-found route, a normal page render, not a boundary. I falsified four candidate causes by experiment (boundary placement at [lang]; the pass-through root layout; notFound() inside generateMetadata; the canonical Next arrangement with the shell above the boundary) and also the experimental global-not-found convention. One fix is measured working - dynamicParams=false on the docs route, which sends unknown slugs to the prerendered /_not-found route - but it lives in page.tsx, which #185 owns and which this card is forbidden to touch, and it satisfies only the first adjudication, not the locale one. No PR: every change available inside the permitted file surface is a provable no-op, and shipping one would read as a fix.",
  "tests": "All over HTTP against production builds (next start) plus next dev, markup separated from RSC payload by stripping script bodies - the card's raw grep cannot tell them apart and scores a 200 page as containing the 404 text. BASELINE origin/main d394550: /no-such-page 404 errorshell=false 404text-in-markup=2 lang=en; /docs/no-such-page 404 errorshell=TRUE 404text-in-markup=0 lang=none body=225 bytes; /zh-Hans/docs/no-such-page and /ja/docs/no-such-page identical. Defect reproduces exactly, seven PRs past the card's ee74379. EXPERIMENTS - each mutated file was proven on disk by grepping the injected AND deleted text (not by an editor exit code), rebuilt where a build was involved, and restored via git checkout HEAD -- path with the restored blob hash compared against git rev-parse HEAD:path; every restore printed byte-identical to HEAD, and every script carried a trap on EXIT INT TERM with absolute paths. (1) app/[lang]/not-found.tsx rendering a bare marker div: no change, marker absent from markup. (2) same boundary rendering its own root element: no change. (3) root layout given a real shell: /no-such-page and /docs both rendered it (positive control proves hot reload applied), /docs/no-such-page still error shell. (4) notFound() in generateMetadata neutered: still error shell. (5) canonical arrangement - shell moved to the root layout ABOVE the boundary, [lang]/layout.tsx emitting none: /docs rendered the new root shell, /docs/no-such-page still error shell. (6) root not-found stripped of its shell: /no-such-page rendered its marker (positive control) while /docs/no-such-page rendered nothing at all - so the boundary content is not merely misplaced, it never renders. (7) minimal isolation - a plain page under [lang] whose only statement is notFound(), no fumadocs, no metadata, no static params: error shell too, so this is app-wide, not a docs-page property. (8) experimental globalNotFound plus app/global-not-found.tsx: flag confirmed active in the dev banner; it replaced the unmatched-URL path only, /docs/no-such-page still error shell. (9) dynamicParams=false on the docs route, full prod build: /docs/no-such-page 404 errorshell=FALSE 404text-in-markup=2 lang=en, /zh-Hans/docs/no-such-page likewise - the defect's first half fixed, the locale half not. Mechanism corroborated in the installed Next source: app-render.js line 1999 takes the dynamic error path into getErrorRSCPayload (line 1089, whose own comment reads 'For metadata notFound error there's no global not found boundary on top so we create a not found page with AppRouter'), whereas line 4326 takes the prerender path through the normal getRSCPayload.",
  "open_questions": [
    {
      "question": "The adjudication requires the docs 404 body to render server-side AND to declare the requested locale. Neither is reachable from apps/docs/app/[lang]/not-found.tsx - that file is a measured no-op. Where should the fix live, given #185 currently owns page.tsx?",
      "options": [
        "A. dynamicParams=false on apps/docs/app/[lang]/docs/[[...slug]]/page.tsx. One line, MEASURED WORKING for the server-rendered body. Unknown slugs stop rendering the page and resolve to the prerendered /_not-found route instead. Does NOT satisfy the locale adjudication - that route sits above the locale segment and keeps declaring en. Collides with #185's file, so it must be sequenced after it.",
        "B. A, plus making the root 404 locale-aware so it can declare the requested locale. Satisfies both adjudications. Touches apps/docs/app/not-found.tsx, which #168 owns and which the card says must keep working. The locale has to come from above the [lang] segment - a middleware-set header read through headers(), which makes the /_not-found route dynamic. Acceptable for a 404 but UNVERIFIED here.",
        "C. Treat it as an upstream Next defect and wait for or drive a version bump. UNVERIFIED - I did not attempt a bump. Leaves a surface that looks correct in every browser and is broken only for crawlers and no-JS clients.",
        "D. Ship the card's app/[lang]/not-found.tsx anyway. REJECTED on measurement: byte-identical output, identical route table. It would read as a fix, close the card, and suppress future investigation."
      ],
      "recommendation": "B, staged, as a single new card that owns page.tsx and app/not-found.tsx together and is dispatched only after #185 lands; retire the app/[lang]/not-found.tsx file surface from the card entirely. Four axes. REAL BUSINESS NEED: real but modest, and PM triage already priced it correctly - the status code is a correct 404, so this is not a ranking problem; what is real is that this repo carries permanent redirects for a past docs restructure, which is direct evidence that inbound links to moved docs paths exist, and anything moved without a redirect currently serves a blank body to crawlers and no-JS readers. LONG-TERM SOUNDNESS: A is a genuine simplification rather than a patch - it collapses two different 404 mechanisms into the one that actually works, so unknown docs slugs resolve through the same prerendered route as every other unmatched URL. The cost to state plainly is that a docs page added without a rebuild would 404 instead of rendering on demand; for a site whose pages all come from local MDX enumerated by generateStaticParams that is already true in practice, but it is a real property change and belongs to the maintainer, not to me. HARD TO GET WRONG: the current state is the dangerous kind - the client fills the page in, so it looks correct to anyone testing by eye, and a future agent verifying the 404 page would see it working. That is also exactly why option D is worse than doing nothing. AI-authored metadata apps are not implicated here; this is site-shell behaviour. STARTUP SCOPE: A is one line and B adds one small genuine capability. Resist letting this grow into a designed 404 page with navigation - nobody asked for that, and the adjudication is only about a server-rendered body and a correct lang attribute."
    }
  ],
  "deviations": [
    "No PR opened. The dispatch said to open a draft PR and stop, but every change available in the permitted file surface is a measured no-op; per the standing rule against speculative code this is returned as needs_decision instead. The branch claude/issue-182-locale-notfound-boundary is pushed and empty at d394550.",
    "For measurement only, five files outside the permitted surface were temporarily mutated and then restored: app/layout.tsx, app/[lang]/layout.tsx, app/not-found.tsx, app/[lang]/docs/[[...slug]]/page.tsx and next.config.mjs. Each restore was verified by comparing the on-disk blob hash to git rev-parse HEAD:path, all matched, and the final tree is byte-identical to origin/main with git status empty. NOTHING was shipped and #185's files are untouched on the branch.",
    "Temporary probe routes under app/[lang]/ were created and deleted; confirmed absent.",
    "The shared heavy-verify lock at /home/user/objectstack/scripts/pm/os-verify-lock.sh was used for every build even though it lives in the objectstack checkout, since it guards this container, not that repo. objectos carries no scripts/pm of its own and no dispatch-gates.mjs, so the gate list here was derived from apps/docs' own package.json.",
    "Worktree /home/user/objectos-issue-182 left in place with node_modules for a fast follow-up; its 1.2G .next was deleted."
  ],
  "out_of_scope_findings": []
}

The short version

The card's proposed fix does not work, and the reason is worth more than the fix would have been.

I built app/[lang]/not-found.tsx exactly as proposed and measured it: byte-identical output, identical route table, 577 static pages unchanged, /docs/no-such-page still serving the blank error shell. Then I falsified the next four explanations in turn — the pass-through root layout, notFound() inside generateMetadata, the canonical Next arrangement with the shell above the boundary, and the experimental global-not-found convention.

The real mechanism. notFound() raised during a dynamically rendered request escapes both the RSC and SSR renders. Next catches it in the SSR error handler and builds the response from getErrorRSCPayload, which seeds the document as an empty error-shell root element and ships the real 404 tree only in the RSC payload, for the client. No not-found boundary at any depth participates in that server render — which is why moving the boundary, at any level, changes nothing.

The case that works is not a boundary at all. /no-such-page is served by the prerendered /_not-found route — an ordinary page render. Two different mechanisms, and only one of them ever produced HTML.

The strongest evidence is experiment 6: with the root 404 stripped of its shell, /no-such-page rendered its marker (so hot reload was working) while /docs/no-such-page rendered nothing at all. The boundary content is not misplaced — it never renders.

A fix does exist and is measured working, just not where the card put it: dynamicParams = false on the docs route sends unknown slugs to the prerendered /_not-found route, and /docs/no-such-page then serves a real server-rendered 404 body. But that is page.tsx, which #185 owns and this card may not touch, and it closes only the first adjudication — the locale one stays open, because /_not-found sits above the locale segment and keeps declaring en.

Hence needs_decision rather than a no-op PR. Details, options and a four-axis recommendation are in the JSON above.

Generated by Claude Code

Adjudication after falsification. The hypothesis on this card is dead, the card is not. Recording what changed and what the next dispatch inherits.

Accepting the falsification

app/[lang]/not-found.tsx is a measured no-op: byte-identical output, identical route table, 577 static pages unchanged, /docs/no-such-page still serving the error shell. Not "didn't help" — provably cannot help. In Next 16.2.6 a notFound() raised during a dynamically rendered request escapes both the RSC and SSR renders, and the response is built from getErrorRSCPayload, which seeds the document as an empty error-shell root and ships the real 404 tree only in the RSC payload. No not-found boundary at any depth participates in that render. The working case is structurally different: an unmatched URL is served by the prerendered /_not-found route — a normal page render, not a boundary.

Nine experiments, two of them positive controls proving hot reload had actually applied, plus corroboration in the installed Next source. That is not "I tried it and it didn't work"; that is a mechanism.

Returning needs_decision instead of shipping was the right call and I want it on the record. Every change available inside the permitted file surface was a provable no-op, and shipping one would have closed this card, read as a fix, and suppressed the investigation that found the actual cause. Option D in the report — ship it anyway — is correctly ranked as worse than doing nothing.

The card's own reproduction command is wrong, and that matters

curl -s … | grep -c "could not be found" cannot tell server-rendered markup from the RSC payload, so it scores a page as containing the 404 text when the text is only in the streamed payload. That is exactly the confusion this card is about, embedded in the card's own verification steps. Corrected in the body: separate markup from payload by stripping script bodies before grepping. Anyone verifying this with the original command would have concluded it was already fixed.

What the fix is now

Splitting the card. The two halves of the original adjudication have very different costs and only one of them has a measured solution.

This card keeps the first half: the 404 body must render server-side. The fix is dynamicParams = false on apps/docs/app/[lang]/docs/[[...slug]]/page.tsx — measured working (errorshell=FALSE, 404 text in markup, on both /docs/no-such-page and /zh-Hans/docs/no-such-page). File surface changes from app/[lang]/not-found.tsx (retired — it does nothing) to page.tsx.

page.tsx is free now — #185 merged as b078736 while you were measuring. This is dispatchable immediately.

On the property change the report correctly flagged as the maintainer's: a docs page added without a rebuild would 404 rather than render on demand. Taking that as PM judgement rather than escalating, for two reasons. Every page on this site comes from local MDX enumerated by generateStaticParams, so it is already true in practice — this makes it explicit rather than introducing it. And #190 set dynamicParams = false on the OG route hours ago for the same reason, which I accepted; refusing it here would leave the codebase inconsistent with itself over a property that already holds. Veto window, as always: say so before it lands if you disagree.

The locale half becomes its own card, filed alongside this comment. It needs the locale to come from above the [lang] segment — a middleware-set header read through headers(), which makes /_not-found dynamic. Unverified, a larger property change, and a smaller payoff than a body that renders at all. Bundling it would make a one-line measured fix wait on an unverified design.

On the out-of-surface mutations

Five files outside the permitted surface were temporarily mutated for measurement and restored, each verified by comparing the on-disk blob hash against git rev-parse HEAD:path, with the final tree byte-identical to origin/main and git status empty. Accepted without reservation: that is measurement, not editing, the restores were proven rather than assumed, and #185's files were untouched on the branch. Finding the mechanism required exactly this.

Generated by Claude Code

os-dev-report

(Angle-bracket markup omitted throughout — this repo's sanitizer strips it.)

{
  "issue": 182,
  "status": "done",
  "branch": "claude/issue-182-locale-notfound-boundary",
  "pr": "https://github.com/objectstack-ai/objectos/pull/192",
  "premise_still_valid": true,
  "files_changed": [
    "apps/docs/app/[lang]/docs/[[...slug]]/page.tsx"
  ],
  "gates": {
    "build": "PASS. pnpm turbo run build / next build, green on the committed branch at aeea6c9. os-verify-lock VERDICT command-exit 0.",
    "type_check": "PASS. pnpm --filter @objectos/docs run type-check (fumadocs-mdx and next typegen and tsc --noEmit). Script name echoed in the output as '@objectos/docs@0.0.0 type-check', so this was a real run and not a zero-match no-op. VERDICT command-exit 0.",
    "test": "PASS. pnpm turbo run test --concurrency=2, 1 successful / 1 total. VERDICT command-exit 0.",
    "next_dev": "PASS. Same corrected result as the production build; no missing-root-layout validator break. Only warning is the pre-existing middleware-deprecation notice, present on main too.",
    "static_page_count": "577 control, 577 this branch - holds.",
    "no_live_page_changed": "PROVEN on the same base. Script bodies stripped, the rendered markup of /docs, /zh-Hans/docs, /no-such-page and /zh-Hans/no-such-page is identical between control and branch. The only differing byte in those documents is Next's per-build id, same length.",
    "redirects": "PASS. /docs/build/data-model and /zh-Hans/docs/build/flows both still 308 to their new paths.",
    "ci_status": "in_progress - reported at draft-PR time per the dispatch contract; CI convergence is the PM's."
  },
  "summary": "Shipped option A as adjudicated: export const dynamicParams = false on apps/docs/app/[lang]/docs/[[...slug]]/page.tsx, plus a comment carrying the root cause so a reader of a one-line diff knows it is not a workaround. An unknown docs slug now resolves to the prerendered /_not-found route instead of being rendered dynamically so the page can throw notFound() - which is the throw that escapes both renders and lands in getErrorRSCPayload as an empty error shell. Did NOT add app/[lang]/not-found.tsx: previously measured as a byte-for-byte no-op, and the card now says so. The locale half is untouched and stays with #191. Experiment 9 was reproduced on the committed branch rather than cited, against a same-base control so nothing is attributed across #190.",
  "tests": "Over HTTP from production builds plus next dev, markup separated from RSC payload by stripping script bodies. SAME-BASE A/B - both sides built from b078736, the control being this branch with the flag removed via git checkout b078736 on that one file; the ablation was proven on disk (0 dynamicParams lines, on-disk blob equal to the b078736 blob) and the restore verified byte-identical to the committed HEAD, under a trap on EXIT INT TERM with absolute paths. CONTROL: /docs/no-such-page 404 errorshell=TRUE 404text-in-markup=0 lang=none body=225 bytes; /zh-Hans, /ja and /docs/build variants identical. BRANCH: all four 404 errorshell=FALSE 404text-in-markup=2 h1_404=1 lang=en body=992 bytes. UNCHANGED both sides: /no-such-page 404 with its 404 copy and lang=en (#168 preserved), /docs 200 lang=en, /zh-Hans/docs 200 lang=zh-Hans; markup byte-identical, only Next's build id differs. next dev reproduces the branch result exactly. Static HTML count 577 on both sides. Redirects re-checked: /docs/build/data-model and /zh-Hans/docs/build/flows both 308. Real pages still 200: /docs/architecture, /zh-Hans/docs/architecture. Gates: type-check, build and test all green with the pnpm script name echoed so a zero-match run could not read as a pass.",
  "open_questions": [],
  "deviations": [
    "Rebased onto current origin/main b078736 before working (the branch had been pushed empty at d394550); the push was therefore a fast-forward and no force was needed.",
    "The card's original reproduction command is wrong and is corrected in the PR body: a raw grep cannot separate server-rendered markup from the RSC payload, returns 1 on the BROKEN build, and returns 1 on a healthy 200 /docs as well. The corrected form strips script bodies first and is written with hex escapes rather than literal angle brackets so this repo's sanitizer cannot mangle it. Validated both ways before publishing.",
    "One claim was checked and withdrawn rather than asserted: the first control-vs-branch byte comparison was made across d394550 and b078736 and showed differences, which I traced to #190's share-card locale change rather than reporting as mine. I then rebuilt a same-base control to make the comparison valid. A follow-up guess that the residual difference was per-build chunk hashes was also wrong - the chunk names match - and the real difference is Next's build id, which is what the PR body states.",
    "No changeset and no skip-changeset label: per the dispatch this repo carries no changeset flow, and objectos has no such label mechanism, so neither was created.",
    "Worktree /home/user/objectos-issue-182 removed without force after the PR was opened; node_modules and .next deleted first. Branch is on the remote at aeea6c9."
  ],
  "out_of_scope_findings": []
}

Draft PR: #192. One file, +34, no deletions.

The measurement that mattered is now reproduced on the committed branch against a same-base control, so the acceptance evidence is not inherited from the earlier investigation run: with the flag removed from this branch, /docs/no-such-page is back to the blank error shell; with it, all four docs-404 shapes serve the 404 copy in server-rendered HTML. /no-such-page is untouched, live pages are markup-identical, and the static count holds at 577.

Two things from the investigation are written into the PR body as the PM asked: the corrected reproduction command with a note on why the naive one misleads, and one paragraph of root cause so a reader of a one-line flag understands it routes around the dynamic render rather than patching the boundary.

Generated by Claude Code

ACCEPT — PM review of record. PR #192 at aeea6c9.

item	verdict
PR shape	draft ✓, base `main` at `b078736`, `Fixes #182` ✓
File surface	1 file, `page.tsx`, exactly as re-scoped ✓
CI	`build` and `Node floor` both `completed/success` ✓
Path-surface fork	`apps/docs/app/**`; no governed surface ✓
Scope	`app/[lang]/not-found.tsx` correctly absent; locale half left to #191 ✓

Two self-corrections, both volunteered

The deviation I want on the record:

the first control-vs-branch byte comparison was made across d394550 and b078736 and showed differences, which I traced to #190's share-card locale change rather than reporting as mine. I then rebuilt a same-base control to make the comparison valid. A follow-up guess that the residual difference was per-build chunk hashes was also wrong — the chunk names match — and the real difference is Next's build id.

A cross-base diff that shows differences is the easiest thing in the world to report as your own change's footprint, and nobody would have caught it. Tracing it to #190, rebuilding a same-base control, then being wrong again about the residual and saying so too — that is two corrections nobody asked for, in a report that could have simply said "markup identical."

The same-base A/B is what makes the "no live page changed" claim mean anything. Comparing against d394550 would have attributed #190's work to this PR.

The comment carries the root cause, which a one-line diff needs

33 lines of comment for one line of code is the right ratio here. A future reader sees dynamicParams = false and has to know it is not a workaround for the boundary — it removes the dynamic render the boundary cannot survive. The comment says that, names where the throw goes (getErrorRSCPayload), records that a locale-segment boundary was measured as a byte-for-byte no-op, states the behavioural cost plainly, and explains why notFound() stays. Someone deleting that flag in six months will know what breaks.

The corrected reproduction, with the control that makes it a test

The card's original command returns 1 on the broken build and 1 on a healthy 200 /docs — it was measuring something always true. The PR's version strips script bodies and adds the row that turns it into a real test: /docs must stay 0. Without that line you cannot tell a working check from a broken one.

Writing it with hex escapes so this repo's sanitizer cannot mangle it, and validating it both ways before publishing, is the kind of care that means the next person actually gets a working command.

Measurements

Control errorshell=TRUE, 404 text in markup 0, lang=none, body 225 bytes → branch errorshell=FALSE, 404 text 2, h1_404=1, lang=en, body 992 bytes, across /docs/no-such-page, the zh-Hans and ja variants, and a nested path. /no-such-page unchanged (#168 preserved). Static count 577 on both sides. Redirects re-checked. next dev matches.

Proceeding to ready and merge. #191 stays open for the locale half.

Generated by Claude Code

fix(docs): apply the requested locale to the 404 page in the browser (#…

Navigation Menu

Repository navigation

A 404 under /docs serves a blank error shell, not the 404 page — notFound() from a docs page never renders server-side #182

What happens

Root cause — measured, not inferred

Reproduction — note the corrected command

Why it matters

The fix

Scope

Verification

The short version

Accepting the falsification

The card's own reproduction command is wrong, and that matters

What the fix is now

On the out-of-surface mutations

Two self-corrections, both volunteered

The comment carries the root cause, which a one-line diff needs

The corrected reproduction, with the control that makes it a test

Measurements

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

A 404 under /docs serves a blank error shell, not the 404 page — notFound() from a docs page never renders server-side #182

Description

What happens

Root cause — measured, not inferred

Reproduction — note the corrected command

Why it matters

The fix

Scope

Verification

Activity

hotlong commented on Aug 25, 2026

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

The short version

hotlong commented on Aug 26, 2026

Accepting the falsification

The card's own reproduction command is wrong, and that matters

What the fix is now

On the out-of-surface mutations

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

Two self-corrections, both volunteered

The comment carries the root cause, which a one-line diff needs

The corrected reproduction, with the control that makes it a test

Measurements

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions