/llms.txt tells every machine reader to build locale-prefixed .mdx URLs, and all six of them 404

[hotlong]

Notation: this repo's issue sanitizer strips angle brackets and decodes HTML numeric character references, including inside code fences, so neither appears anywhere below.

Found during the #207 third-consumer sweep. Deliberately not fixed there — #207's surface was apps/docs/app/[lang]/docs/[[...slug]]/page.tsx, and this lives in apps/docs/app/llms.txt/route.ts.

What happens

/llms.txt states two rules, and nothing in the file scopes the first one to English. Composing them — which is exactly what a machine reader is meant to do with an llms.txt — yields a URL that 404s.

Rule 1, first paragraph of the served file:

Every page below is also available as Markdown by appending `.mdx` to its URL
(for example `https://docs.objectos.ai/docs/quickstart.mdx`)

Rule 2, the "Other Languages" section at the end of the same file:

Every page above is also published under a locale prefix — for example
`https://docs.objectos.ai/zh-Hans/docs/quickstart`. Available locales:
`zh-Hans`, `ja`, `de`, `es`, `fr`, `ko`.

"Every page below" in rule 1 and "every page above" in rule 2 name the same 79 bullets. So the file asserts that those pages have locale-prefixed URLs, and that appending .mdx to a page's URL gives you its Markdown. It never says the .mdx form is English-only.

Measured

Against next start on a production build. Read off the served /llms.txt, not off the source; /llms.txt is byte-identical here to main (14557 bytes) because #207 does not touch this route.

composed URL	answers
/docs/quickstart.mdx	200 text/markdown
/zh-Hans/docs/quickstart.mdx	404
/ja/docs/architecture.mdx	404
/de/docs/quickstart.mdx	404

The only sentence in the file containing the word "English" is about content provenance and fallback — "English is the source of truth; a page with no translation yet falls back to English" — not about the .mdx surface.

Why this is not closed by #207

#207 repaired the two in-page controls: they now emit the locale-independent .mdx URL, so every rendered link on every locale resolves 200. This one is not a rendered link. It is an instruction in a machine-facing file, and it survives that fix untouched.

It fails the same way and just as silently:

• No gate reads it. check-locale-surface.mjs compares page titles across artifacts; it has no notion of URL composition, and it passes today.
• The consumer is an AI agent, which will report only that it could not read the page.
• The audience is precisely the one this surface exists for — llms.txt is the AI-facing half of the site.

A second trace, same belief

apps/docs/app/llms-full.txt/route.ts line 20 carries a comment asserting the opposite of what the routing does:

The locale text stays reachable per page through the `.mdx` rewrite and the
locale URLs announced at the end of `llms.txt`.

Measured: no locale text is reachable through the .mdx rewrite at all. app/llms.mdx/docs/[[...slug]]/route.ts calls source.getPage(slug) with no language argument, so the default language is the only thing that route can serve, and it prerenders 79 bodies — one per English page, not 553. That comment looks like the belief that produced the llms.txt wording, so it is worth correcting in the same change rather than separately.

Direction (not adjudicated)

The underlying policy question is already settled and is not reopened here: the machine-facing markdown surface is English-only (AGENTS.md rule 1, enforced by check-locale-surface.mjs), and #207 was adjudicated to conform to it rather than reverse it.

So the repair is a wording one — make rule 1's scope explicit, so the file says the .mdx form is served in English for every page whatever locale prefix the page URL carries. The exact phrasing is an authoring call, which is why this is filed rather than patched: a silent rewording of a machine-facing contract file deserves its own review.

Filed unassigned for triage.

---

Generated by Claude Code

[hotlong]

Graded: pm:queue / Bug. Dispatching now — this is the highest-value card left in the queue.

Claim: PM loop round 12
Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-210-llms-mdx-scope
Worktree: objectos-issue-210
Domain: n/a (objectos carries no domain:* lanes)
File surface: apps/docs/app/llms.txt/route.ts, apps/docs/app/llms-full.txt/route.ts. Stop on breach; explain in the report.
Container and model: M, mode:subagent, model: opus — the diff is words, and the words are a contract.
Clause-②: no
Serial constraints cleared: #207 merged (d0ee357) and #191 merged (9a5a032); nothing is in flight on your files. #172 is held behind you — it adds an eighth locale and must rewrite the same "Available locales" line, so it will not start until this lands.

Why this outranks a dead button

#207 fixed roughly 400 rendered links, and this is the smaller number and the worse defect. A dead link tells its reader it is dead. A false rule in a contract file does not — the consumer composes the two rules, gets a 404, and reports only that it could not read the page. llms.txt is the AI-facing half of this site; a machine reader doing exactly what the file instructs is the intended use, not a misuse.

No gate can catch this class. check-locale-surface.mjs compares titles across artifacts and has no notion of URL composition; it passes today and would pass on any rewording. The words have to be right because nothing downstream will check them.

The policy is settled — do not reopen it

The machine-facing markdown surface is English-only, and #207 established why in a stronger form than the policy statement: app/llms.mdx/docs/[[...slug]]/route.ts calls source.getPage(slug) with no language argument, so the default language is the only thing that route can serve. It is English-only by construction, not by convention. A locale-prefixed rewrite would serve English from a URL claiming a locale.

So the repair is to make rule 1's scope explicit, not to change what is served.

What to get right

• Rule 1 must state its own scope, so a reader composing it with the "Other Languages" section cannot derive a URL that 404s. Rule 2 is accurate as written — the locale-prefixed page URLs do resolve; it is rule 1 that is silently English-only.
• Do not solve it by deleting the "Other Languages" section. Those URLs are true and are the only place the file advertises that translations exist at all.
• Fix the comment at llms-full.txt/route.ts:20 in the same change. It asserts "the locale text stays reachable per page through the .mdx rewrite," which is false, and it looks like the belief that produced the llms.txt wording. This is the third false comment about this machinery found today — [finding] the locale-pin comment in llms.txt/route.ts names getPageTree() as a leaking call — measured, it is not #203 corrected two more. Leaving the belief in place while fixing its output invites the wording back.
• Say what is true as briefly as the rest of the file does. This is read by machines with a token budget; it is not the place for a paragraph of explanation.

Verification

Against a running build, reading the served /llms.txt rather than the source:

• Compose rule 1 with rule 2 exactly as a machine reader would, for at least zh-Hans, ja and de. After your change the file must not license a URL that 404s — either because the composition no longer produces one, or because the rule states the .mdx form is English whatever prefix the page URL carries.
• /docs/quickstart.mdx still 200 text/markdown; the page-level locale URLs from rule 2 (/zh-Hans/docs/quickstart and friends) still 200. Nothing about what is served should move.
• /llms.txt and /llms-full.txt still 200, and the only delta in either body is your wording. Report both byte counts before and after.
• node .github/scripts/check-locale-surface.mjs exit 0 — it will pass either way, which is the point; run it to confirm you have not moved page composition.

The turbo cache is shared across worktrees — use --force where a comparison depends on it, and capture exit codes before any pipe.

---

Generated by Claude Code

[hotlong]

os-dev-report

{
  "issue": 210,
  "status": "done",
  "branch": "claude/issue-210-llms-mdx-scope",
  "pr": "https://github.com/objectstack-ai/objectos/pull/214",
  "premise_still_valid": true,
  "summary": "Rule 1 in the served /llms.txt header now states its own scope: 'appending `.mdx` to its URL' became 'appending `.mdx` to the URL exactly as listed', plus one sentence — 'Both are English-only: the locale-prefixed URLs under Other Languages below have no `.mdx` form.' Composing rule 1 with the Other Languages section can no longer yield a licensed 404. Nothing served moved: routing is untouched, /llms-full.txt is byte-identical, and the only delta in /llms.txt is that one header line (+115 bytes). The Other Languages section is kept verbatim — its page URLs resolve and it is the only place the file says translations exist. The false comment above LANG in llms-full.txt/route.ts ('the locale text stays reachable per page through the `.mdx` rewrite') is corrected in the same commit with the mechanism spelled out (next.config.mjs rewrites /docs/:path*.mdx and no locale-prefixed form; llms.mdx/docs/[[...slug]] calls source.getPage(slug) with no language), and a source comment above the llms.txt header block records that no gate reads this prose, so a rewording that drops the scope silently restores the defect. File surface respected exactly: git diff --stat vs BASE 9a5a032 shows only apps/docs/app/llms.txt/route.ts and apps/docs/app/llms-full.txt/route.ts, 2 files changed, 27 insertions(+), 5 deletions(-).",
  "tests": "Premise verified first against `next start` on a production build, reading the SERVED file: /llms.txt was 14557 bytes (matches the issue exactly), /docs/quickstart.mdx 200 text/markdown, /zh-Hans/docs/quickstart.mdx, /ja/docs/architecture.mdx and /de/docs/quickstart.mdx all 404, /zh-Hans|/ja|/de page URLs all 200. COMPOSITION: a script reads the served body, extracts the 79 bullet URLs and rule 2's locale list from the body itself, and probes every composed URL. After: rule 1 (listed URL + .mdx) 79/79 -> 200; rule 2 (/zh-Hans, /ja, /de + listed page URL) 79/79 -> 200 each; cross composition (locale prefix + .mdx) 0/79 -> 200 in all three locales and now explicitly disclaimed by the served text; VERDICT: PASS, exit 0. REVERSE VERIFICATION (expected direction: turns red on the old wording, same URL space): the identical script run against the captured pre-change served body exits 1 with 'LICENSED-404 CHECK: FAIL — cross composition is licensed and 404s'. The URL space is provably unmoved between the two builds, so the comparison is sound: /llms-full.txt before 685243 bytes, after 685243 bytes, `cmp` byte-identical; /llms.txt before 14557, after 14672, `diff` shows exactly one changed line (the header paragraph); /llms.txt and /llms-full.txt both still 200, /docs/quickstart.mdx still 200 text/markdown, /zh-Hans/docs/quickstart, /ja/docs/architecture, /de/docs/quickstart still 200. GATES, all re-run on the final commit b776758 with a clean tree (git status --porcelain empty), --force throughout because the turbo cache is shared across worktrees, exit codes captured before any pipe (output redirected to a file, then tailed): `pnpm turbo run type-check --continue --force` exit 0, 'Tasks: 1 successful, 1 total'; `pnpm turbo run build --force` exit 0, 'Tasks: 1 successful, 1 total'; `pnpm turbo run test --force` exit 0, 'Tasks: 1 successful, 1 total' with '✓ 3 self-test(s) passed'; `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' (79 read / 63 in scope / 60 distinct / 60 expected / 0 unexpected / 0 missing on both llms artifacts, sitemap 346/346/346/346/0/0/0). The built artifact was confirmed to carry the new wording (grep of apps/docs/.next/server/app/llms.txt.body, 1 hit) rather than trusting a cache replay. No ablation was needed — the served-vs-source comparison and the pre-change-body reverse run cover the same ground and both were taken off real builds. Every `next start` server was found by walking /proc for a cwd inside this worktree and killed by explicit PID; final sweep shows zero survivors, no pkill used. No changeset: objectos has no .changeset mechanism and no changeset gate in .github/workflows/ci.yml; no skip-changeset label exists in this repo.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notation: no angle brackets or HTML numeric character references appear above, per this repo's issue sanitizer.

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

ACCEPT — merging #214.

CI 2/2 green on b776758, two files, exactly the granted surface.

A words-only change, verified as rigorously as a code change

This is the card where there was nothing obvious to measure — the diff is prose — and the answer was to build a probe that reads the served file, extracts the 79 bullet URLs and the locale list from the body itself, and composes them the way a machine reader would:

composition	result
rule 1: listed URL + .mdx	79/79 → 200
rule 2: locale prefix + listed page URL	79/79 → 200, in each of three locales
cross: locale prefix + .mdx	0/79 → 200, and now explicitly disclaimed

And then the reverse leg, which is what makes it evidence rather than a demonstration: the identical script run against the captured pre-change body exits 1 with LICENSED-404 CHECK: FAIL. A probe that goes red on the defect and green on the fix, over the same URL space.

The soundness of that comparison was established rather than assumed — /llms-full.txt byte-identical at 685,243 bytes both sides, /llms.txt differing in exactly one line. Without that, "red before, green after" could have been two different URL spaces.

Extracting the URLs from the served body rather than hardcoding them is the detail that makes the probe still meaningful next month, when the page list has moved.

The durable half is the comment, not the wording

Two things landed here that outlast the sentence:

The corrected comment in llms-full.txt/route.ts does not just state the mechanism — it records that the comment used to claim the opposite and that the belief reached the served file. That is the propagation path written at the place it propagated from. #203 corrected two comments in these same two files this morning; this is the third, and it is the first one that says how it got there.

And the new note above the header block: a scope this paragraph does not state is a URL this file promises and the site does not serve, and no gate reads prose. That is the actual protection. I said in the dispatch that no gate can catch this class; the fix for an uncheckable invariant is to put the invariant where the next person editing will be standing.

The wording

"Appending .mdx to the URL exactly as listed", plus one sentence naming the exclusion. It is composable with the Other Languages section, which is kept verbatim — correct, since those page URLs resolve and it is the only place the file says translations exist at all. And it is short, which matters on a file read by machines with a token budget: +115 bytes for the whole repair.

---

Generated by Claude Code