Zhenghan Songandwyuc
ca3d785221
Why: - The root Node 20.9 contract predates direct runtime dependencies whose declared minimums now reach Node 22.19. - README, contributor, localized docs, and the OpenMAIC extension skill repeated the stale supported-version claim. What: - Raise the root Node minimum to 22.19 and align every operator, contributor, locale, and skill prerequisite. - Add a check that compares the root minimum with installed direct production dependency engine minimums. - Run the new contract check in CI after the frozen dependency install. Risk: - This changes the declared minimum only; no upper bound is added and Node 24 compatibility remains a separate concern. - The localized docs build was validated with the independent #1306 boundary fix from PR #1307, which is not included here. Tests: - RED on the base: engine check reported pi-agent-core, pi-ai, svg-pathdata, and undici floors - GREEN: root minimum 22.19 satisfies 35 engine-constrained direct dependencies - Node 20 lockfile-only install reports the root unsupported-engine warning - Node 22 frozen install and postinstall - Docs build with PR #1307 boundary: 34 pages and all locale postexport checks; docs types:check - Root Prettier, ESLint, TypeScript, i18n, package-version, and internal-dependency gates - Root pnpm test: 7137 passed, 81 skipped Live Docs: - GitHub issue #1304 tracks the Node contract; #1306 / PR #1307 tracks the separate docs-build prerequisite. Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
This is a Next.js application generated with Create Fumadocs.
Run development server:
npm run dev
# or
pnpm dev
# or
yarn dev
The site is mounted under the /docs basePath, so open
http://localhost:3000/docs in your browser.
Build the static site (next build + static export, output in out/):
pnpm build
Explore
In the project, you can see:
lib/locales.mjs: Single source of truth for locales — language list, default locale, per-locale search tokenizer, RTL set, labels, and the/docsbasePath. Plain JS so thescripts/postexport.mjsbuild step can import it too.lib/source.ts: Content source adapter,loader()wires the MDX content with i18n.lib/layout.shared.tsx: Shared layout options (nav, GitHub link, Live Demo link).
| Route | Description |
|---|---|
app/(en) |
English (default locale), served unprefixed at /docs/<slug>. |
app/(intl)/[lang] |
Other locales, served at /docs/<lang>/<slug>. |
app/static.json/route.ts |
Build-time Orama static search index (served at /docs/static.json). |
scripts/postexport.mjs |
Post-build step: per-locale index redirects + English alias stubs. |
Fumadocs MDX
A source.config.ts config file has been included, you can customise different options like frontmatter schema.
Read the Introduction for further details.
Known limitations
English supports only top-level docs pages
The default locale (en) is served unprefixed (/docs/getting-started). To keep
it unprefixed without the hydration conflict that a catch-all two-route-group
split causes, the English route app/(en)/[slug] is a single (non-catch-all)
segment. As a result, nested English pages would 404 — e.g.
content/docs/guides/intro.mdx resolves for every other locale (their routes are
catch-all under app/(intl)/[lang]/[...slug]) but not for English.
Only top-level English docs pages work today. Adding nested English docs requires
revisiting the (en) route group (and resolving the hydration conflict that the
current split avoids); this is deliberately deferred.
Learn More
To learn more about Next.js and Fumadocs, take a look at the following resources:
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
- Fumadocs - learn about Fumadocs