The .mdx copy/view links 404 on all six non-default locales — the rewrite only covers the unprefixed path

Found while verifying #180 against a running build. Unrelated to that card and deliberately not fixed there — #180's surface was apps/docs/app/[lang]/layout.tsx, and this lives in next.config.mjs.

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

What happens

Every docs page renders a "Copy Markdown" button and a "View as Markdown" link, both pointing at page.url plus .mdx. On a locale-prefixed page page.url carries the prefix, so the link is /zh-Hans/docs/architecture.mdx.

next.config.mjs rewrites only the unprefixed shape:

async rewrites() {
  return [
    { source: '/docs/:path*.mdx', destination: '/llms.mdx/docs/:path*' },
  ];
}

There is no locale-prefixed variant, so every prefixed .mdx URL falls through to app/[lang]/docs/[[...slug]], where architecture.mdx is not an enumerated slug, and 404s.

Measured

Against next start on a production build of b61f04e:

page	`markdownUrl` it renders	that URL answers
`/docs/architecture`	`/docs/architecture.mdx`	200
`/zh-Hans/docs/architecture`	`/zh-Hans/docs/architecture.mdx`	404
`/ja/docs/architecture`	`/ja/docs/architecture.mdx`	404

The markdownUrl values were read out of the served payload, not off the source.

Six of the seven locales are affected, on every one of the 79 docs pages — so roughly 400 rendered links that 404. English is the only locale where the button works.

Why it is worth fixing

It is a visible, clickable dead end in the UI, not a machine-facing edge case. A reader on any non-English page who clicks "Copy Markdown" gets a 404 page.
The .mdx surface is the AI-facing half of this site (it is what llms.txt and the copy button exist for), so the locales where it silently fails are exactly the ones least likely to be spot-checked by an English-speaking maintainer.

Directions (not adjudicated)

Add a locale-prefixed rewrite alongside the existing one (/:lang/docs/:path*.mdx), and decide what the handler serves for a locale that has no translation — presumably the same English fallback the page itself serves.
Have the page emit the unprefixed .mdx URL regardless of locale, on the grounds that app/llms.mdx/... is default-locale-only by the same reasoning as fix(docs): serve llms-full.txt in the default locale only #183. That makes the link work everywhere but hands a reader on a translated page the English markdown.

These differ in what a translated page's markdown should be, which is a content question, not a routing one.

Filed unassigned for triage.

Generated by Claude Code

Graded: pm:queue / Bug. Direction adjudicated — and it is not the content question it looks like.

Roughly 400 rendered links that 404, on six of seven locales, on every docs page, measured against a running server with the markdownUrl read out of the served payload rather than off the source. English is the only locale where the button works, which is exactly why it survived this long.

The two directions are not symmetric, because the question they turn on is already answered

The card says they "differ in what a translated page's markdown should be, which is a content question, not a routing one." That is the right frame, and it resolves the card: this site already answered that question, deliberately, and enforces the answer with a gate.

The machine-facing markdown surface here is English-only by standing policy (AGENTS.md rule 1), and it is not an aspiration — llms.txt and llms-full.txt were rebuilt to it across #183, #178, #196 and #184, and check-locale-surface.mjs now fails the build if either drifts. /llms.mdx/docs/[[...slug]] prerenders exactly 79 bodies, which is the English page count — #197 measured that independently while investigating something else.

So:

Direction 2 conforms to the existing answer. The .mdx route is default-locale-only; emit the unprefixed URL and the link works everywhere, serving the same English markdown that every other machine-facing artifact on this site already serves.
Direction 1 would reverse that answer — quietly, through a routing change, taking /llms.mdx from 79 bodies to as many as 335 and putting it out of step with the two llms files beside it. That is the decision that belongs to the maintainer, and it should be asked as a question about the whole markdown surface, not smuggled in as a 404 fix.

Take direction 2. It is not choosing a policy; it is stopping ~400 links from contradicting the one already in force.

Scope for whoever takes it

The change is to what the page emits, not to next.config.mjs — leave the rewrite alone. apps/docs/app/[lang]/docs/[[...slug]]/page.tsx builds markdownUrl from page.url; it needs the locale-independent path instead. Note that file has been rewritten four times today (#166, #174, #187, #182) — read the tree, not the issue's description of it.

Verify against a running build, the way this card was found: read markdownUrl out of the served payload on /docs/architecture, /zh-Hans/docs/architecture and /ja/docs/architecture, and confirm all three resolve 200. Confirm /docs/architecture.mdx still 200 with no locale prefix and no redirect — #209 has that row in its direction-1 hazard table; reuse it.

One thing to check rather than assume: whether anything else in the tree derives a .mdx URL from page.url the same way. The copy button and the view link are the two named here; a third would fail identically and silently.

Note

Filed unassigned by the #180 dev, correctly out of that card's surface, with the measurement attached. This is the second card today where a running-server sweep during verification found a live defect that no gate covers — the gates here read build output, and build output is correct in both of these cases.

Generated by Claude Code

Claim: PM loop round 11
Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-207-locale-mdx-links
Worktree: objectos-issue-207
Domain: n/a (objectos carries no domain:* lanes)
File surface: apps/docs/app/[lang]/docs/[[...slug]]/page.tsx. next.config.mjs is read-only — the rewrite stays as it is. Stop on breach; explain in the report.
Container and model: M, mode:subagent, model: opus — the direction is adjudicated but the sweep at the end is judgement.
Clause-②: no
Serial constraints cleared: #180 merged (ffe36c5); nothing is in flight on your file. Note it has been rewritten four times today (#166, #174, #187, #182) — read the tree, not the card's description of it.

Direction is adjudicated in the grading comment above: emit the locale-independent .mdx URL. Do not add a locale-prefixed rewrite. The short version of why: the machine-facing markdown surface on this site is English-only by policy and enforced by check-locale-surface.mjs, so serving English markdown from a translated page conforms to the answer already in force. Making /llms.mdx locale-aware would reverse that policy through a routing change, and that is the maintainer's call, not this card's.

The one part that is genuinely yours to work out

The card names the copy button and the view link. Sweep for a third. Anything else that derives a .mdx URL from page.url fails identically and just as silently, and a fix that repairs two of three is worse than one that names the third and leaves it — because it removes the symptom that would have led someone to it.

Verification

Against a running build, reading markdownUrl out of the served payload rather than off the source — that is how the card was found and it is the only reading that counts here:

/docs/architecture, /zh-Hans/docs/architecture, /ja/docs/architecture: the URL each page renders resolves 200, and the body is markdown (check the first line, not just the status).
Controls from fix(docs): reject a non-locale first segment at the route level #209's direction-1 hazard table, all still 200 with no redirect and no locale prefix: /docs/architecture.mdx, /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt.
The visible page is unchanged apart from the link target.
node .github/scripts/check-locale-surface.mjs exit 0.

Two traps this route has already produced today, both from #192: strip script bodies before any grep (a raw grep reads the RSC payload and will score a healthy page as containing whatever you searched for), and the turbo cache is shared across worktrees, so use --force where a comparison depends on it.

Generated by Claude Code

os-dev-report

{
  "issue": 207,
  "status": "done",
  "branch": "claude/issue-207-locale-mdx-links",
  "pr": "https://github.com/objectstack-ai/objectos/pull/211",
  "premise_still_valid": true,
  "summary": "apps/docs/app/[lang]/docs/[[...slug]]/page.tsx now derives the Copy Markdown button's and the Open popover's target from page.slugs through the existing docsPath helper — `/${docsPath(page.slugs)}.mdx` — instead of `${page.url}.mdx`, and binds it once in the component body so both controls take the same value and a later third control inherits it rather than re-deriving one. next.config.mjs is untouched; the rewrite stays exactly as adjudicated. Diff is one file, +47/-2, most of it the rationale comment. THE THIRD-CONSUMER SWEEP FOUND ONE, OUTSIDE THE FILE SURFACE, AND IT IS FILED RATHER THAN FIXED (#210): the served /llms.txt states 'Every page below is also available as Markdown by appending .mdx to its URL' and then, in Other Languages, 'Every page above is also published under a locale prefix', with nothing in the file scoping the first rule to English — so a machine composing the two rules, which is what an llms.txt is for, builds precisely the 404 URL this PR removes from the page. Measured on the served file: /zh-Hans/docs/quickstart.mdx, /ja/docs/architecture.mdx and /de/docs/quickstart.mdx all 404 while /docs/quickstart.mdx answers 200 text/markdown. A second trace sits at apps/docs/app/llms-full.txt/route.ts line 20, a comment asserting 'The locale text stays reachable per page through the .mdx rewrite' — measured false, since app/llms.mdx/docs/[[...slug]]/route.ts calls source.getPage(slug) with no language and can serve only the default one; that comment looks like the belief that produced the llms.txt wording. Both are wording changes to a machine-facing contract file, so they got their own card rather than a rider here. Two process notes: this repo has no .changeset directory and no changeset mechanism, so no changeset was added; and the pre-filing duplicate scan had to go through MCP list_issues instead of the REST list endpoint, because this session has no usable GITHUB_TOKEN (14 chars, and api.github.com answers 'GitHub access is not enabled for this session') and no gh CLI — 20 open issues scanned, none covering the /llms.txt composition hazard.",
  "tests": "All heavy runs serialised through the container's shared lock (scripts/pm/os-verify-lock.sh, VERDICT command-exit 0 each time, waited 0s). Exit codes captured before any pipe; every verdict quoted below is the gate's own printed line, never a bare $?. GATE UNION RE-RUN AFTER THE FINAL COMMIT, ON 38e5a04: `pnpm turbo run type-check build test --force --concurrency=2` -> 'Tasks: 3 successful, 3 total'; `node .github/scripts/check-locale-surface.mjs` -> exit 0, 'every advertised URL has a source file and every source file is advertised; both llms bodies carry every en-only page title and none from the other locales'. tsc was confirmed to actually contain the edited file — `tsc --noEmit --listFiles` reports app/[lang]/docs/[[...slug]]/page.tsx (1 hit), so 'type-check clean' is a measurement of this change and not a vacuous pass. RUNNING-BUILD VERIFICATION, next start on a forced production build, markdownUrl read OUT OF THE SERVED PAYLOAD: markdownUrl reaches the browser only as a client-component prop inside the RSC flight payload and appears in no rendered markup, so extracting it is a deliberate read of the script bodies, while the visible-page check strips those bodies first. BEFORE, on ffe36c5 (defect reproduced on the current tree, four rewrites past the card's b61f04e): /docs/architecture -> /docs/architecture.mdx -> 200; /zh-Hans/docs/architecture -> /zh-Hans/docs/architecture.mdx -> 404; /ja/docs/architecture -> /ja/docs/architecture.mdx -> 404. AFTER: all three pages emit /docs/architecture.mdx, each 200, redirects=0, content-type text/markdown, first line '# Architecture'. EXHAUSTIVE SWEEP, 79 docs paths enumerated from the served sitemap.xml times 7 locales — 'page renders checked: 553 | distinct .mdx targets: 79 | locale-prefixed target: 0 | english target moved: 0 | two controls disagree: 0 | no markdownUrl in payload: 0 | target non-200/redirected: 0 | target not text/markdown: 0 | target body not markdown: 0', failures file 0 lines. 553 renders collapsing onto 79 distinct targets is the locale-independence claim measured rather than asserted; 'english target moved: 0' is the regression check, since on the default locale the old expression was literally page.url plus .mdx and page.url is the path requested. Docs index edge case included: /docs emits /docs.mdx, which answers 200 text/markdown. CONTROLS all 200, redirects=0, no locale prefix, byte counts identical before and after: /docs/architecture.mdx 12488, /llms.txt 14557, /llms-full.txt 685243, /sitemap.xml 299145, /robots.txt 117. VISIBLE PAGE UNCHANGED, every script body stripped BEFORE any comparison (a raw comparison would read the RSC payload, the one thing that legitimately changed) and content-hashed asset filenames normalised: IDENTICAL on /docs/architecture (54719 bytes), /zh-Hans/docs/architecture (54815), /ja/docs/architecture (54876). The strip was proven to be doing work rather than comparing two empty files — raw HTML contains self.__next_f, the stripped file contains 0 occurrences, and the stripped files are ~54 KB. Both builds also emitted an identical route table (diff exit 0) and the same 310 OG-card font-fetch warnings, a pre-existing sandbox TLS artifact unchanged by this diff. Turbo --force used on every build and gate run, since the cache is shared across worktrees in this container. Servers were found by walking /proc for a cwd inside my own worktree and killed by explicit PID, never by name; 0 survivors after each teardown.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #210: /llms.txt tells machine readers to append .mdx to any page URL and separately announces locale-prefixed URLs for every page, with nothing scoping the first rule to English, so composing them yields 404s on all six non-default locales; includes the false rationale comment at apps/docs/app/llms-full.txt/route.ts:20. Unassigned, unlabelled, left for PM triage. Not fixed here: it is outside this card's declared file surface, and repairing it silently would have removed the symptom that leads someone to it."
  ]
}

Generated by Claude Code

ACCEPT — merging #211.

CI 2/2 green on 38e5a04, base ffe36c5 (current main), one file, next.config.mjs untouched.

The sweep is the deliverable here, not the one-line derivation. 553 page renders — every docs page in every locale — collapsing onto 79 distinct .mdx targets, with locale-prefixed target: 0 and english target moved: 0. Locale-independence measured across the whole surface rather than demonstrated on three pages. And the second counter is the regression proof: on the default locale the old expression was literally page.url plus .mdx, so asserting every English target is unmoved is asserting the fix changed nothing that was working.

/docs emitting /docs.mdx and answering 200 is the edge case that would have been easy to leave out of the enumeration.

Binding the URL once, so a future third control inherits it rather than re-deriving from page.url, is the right shape. The bug was two call sites independently deriving the same thing; fixing it by making them one value removes the class, not the instance.

Filing the third consumer instead of fixing it was the correct call

I asked for the sweep and said a fix repairing two of three is worse than one that names the third. #210 is that third, and it is a better find than the two in the card:

/llms.txt states "append .mdx to its URL" and, further down, "every page above is also published under a locale prefix". Composing those two rules is precisely what a machine reader does with an llms.txt — and the composition 404s. That is a false statement in a machine-facing contract file, which is a worse failure than a dead button: the button's reader sees a 404 and knows; the contract's reader has no way to find out except by trying every URL.

The measurement attached to it (/zh-Hans/docs/quickstart.mdx, /ja/docs/architecture.mdx, /de/docs/quickstart.mdx all 404 while /docs/quickstart.mdx answers 200 text/markdown) is what makes it actionable. So is catching the comment in llms-full.txt/route.ts:20 asserting "the locale text stays reachable per page through the .mdx rewrite" — measured false, and the third false code comment about this machinery found today. That is a pattern worth naming: this area accumulates confident comments that nobody checks, and every one of them has been wrong.

Verification method

Reading markdownUrl out of the RSC flight payload was necessary — it reaches the browser only as a client-component prop and appears in no rendered markup — and then stripping those same script bodies for the opposite check, that the visible page is unchanged. Using the payload as evidence for one claim and excluding it as noise for another, in the same run, with the strip verified to be doing work (self.__next_f present raw, absent stripped, ~54 KB remaining) rather than comparing two empty files.

Confirming tsc --listFiles actually includes the edited file, so "type-check clean" is a statement about this change rather than a vacuous pass, is the same instinct applied to a gate.

Policy note, recorded so it does not have to be re-derived

The PR states the conformance argument better than my adjudication did: /llms.mdx/docs/[[...slug]] calls source.getPage(slug) with no language argument, so it is English-only by construction, not by convention — it can serve nothing else, and prerenders 79 bodies rather than 553. A locale-prefixed rewrite would therefore not deliver translated markdown; it would serve English from a URL claiming a locale. That is a stronger reason than "policy says English-only" and it belongs in the record.

Generated by Claude Code

Navigation Menu

Repository navigation

The .mdx copy/view links 404 on all six non-default locales — the rewrite only covers the unprefixed path #207

What happens

Measured

Why it is worth fixing

Directions (not adjudicated)

The two directions are not symmetric, because the question they turn on is already answered

Scope for whoever takes it

Note

The one part that is genuinely yours to work out

Verification

Filing the third consumer instead of fixing it was the correct call

Verification method

Policy note, recorded so it does not have to be re-derived

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

The .mdx copy/view links 404 on all six non-default locales — the rewrite only covers the unprefixed path #207

Description

What happens

Measured

Why it is worth fixing

Directions (not adjudicated)

Activity

hotlong commented on Aug 26, 2026

The two directions are not symmetric, because the question they turn on is already answered

Scope for whoever takes it

Note

hotlong commented on Aug 26, 2026

The one part that is genuinely yours to work out

Verification

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

Filing the third consumer instead of fixing it was the correct call

Verification method

Policy note, recorded so it does not have to be re-derived

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions