fix(docs): scope the llms.txt .mdx rule to the URLs it lists

[hotlong]

Fixes #210

/llms.txt stated two rules over the same 79 bullets, and nothing scoped the first one:

• Rule 1 (header): "Every page below is also available as Markdown by appending .mdx to its URL"
• Rule 2 (Other Languages): "Every page above is also published under a locale prefix"

Composing them — exactly what a machine reader is meant to do with an llms.txt — licensed /zh-Hans/docs/quickstart.mdx, /ja/docs/architecture.mdx and /de/docs/quickstart.mdx. All three 404.

What changed

Rule 1 now states its own scope. The served header goes from:

…by appending .mdx to its URL (for example https://docs.objectos.ai/docs/quickstart.mdx), and https://docs.objectos.ai/llms-full.txt carries the full text of every page in one file.

to:

…by appending .mdx to the URL exactly as listed (for example https://docs.objectos.ai/docs/quickstart.mdx), and https://docs.objectos.ai/llms-full.txt carries the full text of every page in one file. Both are English-only: the locale-prefixed URLs under Other Languages below have no .mdx form.

Two sentences of prose, +115 bytes on a file read by machines with a token budget.

Nothing served moves. The .mdx surface is English-only by construction, not by convention — next.config.mjs rewrites /docs/:path*.mdx and no locale-prefixed form of it, and 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. The repair makes the file say so; it does not change routing.

The Other Languages section is kept as written. Those page URLs resolve (verified below), and it is the only place the file advertises that translations exist at all.

The second trace, same belief

llms-full.txt/route.ts carried a comment asserting "The locale text stays reachable per page through the .mdx rewrite" — measured false, and it reads like the belief that produced the llms.txt wording. Corrected in the same change, with the mechanism spelled out, so fixing the output does not leave the belief behind to invite the wording back. (Third false comment about this machinery; #203 corrected two others.)

A source comment above the llms.txt header block records why the scope clause is load-bearing: no gate reads prose, so a future rewording that drops it silently restores the defect.

Verification

Against next start on a production build, reading the served /llms.txt, not the source. Gate union re-run on the final commit b776758.

Composition, as a machine reader performs it

A script reads the served /llms.txt, extracts the 79 bullet URLs and rule 2's locale list from the body itself, and probes every composed URL:

composition	before	after
rule 1 — listed URL + .mdx	79/79 → 200	79/79 → 200
rule 2 — /zh-Hans + listed page URL	79/79 → 200	79/79 → 200
rule 2 — /ja + listed page URL	79/79 → 200	79/79 → 200
rule 2 — /de + listed page URL	79/79 → 200	79/79 → 200
cross — locale prefix + .mdx (zh-Hans/ja/de)	0/79 → 200, and licensed	0/79 → 200, and disclaimed

The cross composition 404s in both builds — that is the routing, and it is unchanged. What changed is whether the file licenses it. Reverse-verified: the same script, run against the captured pre-change body over the same URL space, exits 1 (LICENSED-404 CHECK: FAIL); against the post-change body it exits 0.

Nothing served moved

artifact	before	after
/llms.txt	14557 bytes, 200	14672 bytes, 200
/llms-full.txt	685243 bytes, 200	685243 bytes, 200 (byte-identical)

diff on the served /llms.txt bodies: one line — the header paragraph. /docs/quickstart.mdx still 200 text/markdown; /zh-Hans/docs/quickstart, /ja/docs/architecture, /de/docs/quickstart still 200.

Gates

Run on b776758 with a clean tree, --force throughout (the turbo cache is shared across worktrees), exit codes captured before any pipe:

gate	result
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, ✓ 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

The locale-surface gate passes on both sides, as expected — it compares page titles across artifacts and has no notion of URL composition. It is run to confirm page composition has not moved, not as evidence about the wording.

Generated by Claude Code

---

Generated by Claude Code