Skip to content

AGENTS.md

Latest commit

 

History

History
48 lines (33 loc) · 3.76 KB

AGENTS.md

File metadata and controls

48 lines (33 loc) · 3.76 KB
Raw

AGENTS.md

Documentation site for the Z²ᴱ framework. Next.js 16 + Fumadocs MDX, managed with Bun.

Commands

  • Install: bun install (must be Bun — patchedDependencies in package.json and bun.lock are Bun-only; npm/yarn will not apply patches)
  • Dev: bun run dev (uses next dev --turbo, i.e. Turbopack)
  • Build: bun run build
  • Lint: bun run lint (flat ESLint config, no args — runs eslint with no path globs by default)
  • ESLint is pinned to ^9.39.4, not ^10. ESLint 10 is blocked upstream by eslint-plugin-react (via eslint-config-next) which crashes on the ESLint 10 context.getFilename API removal — no ESLint 10 release exists yet (see vercel/next.js#91702). Do not bump to eslint@10 without first verifying eslint-plugin-react peer compatibility.
  • Release: bun run release (bumpp)
  • No test suite exists.

CI / commit flow

  • CI (.github/workflows/ci.yml): bun install --frozen-lockfile → bun run build → bun run lint. Keep lockfile in sync.
  • prepare installs Husky; .husky/pre-commit runs bun run build on every commit — expect a slow commit and ensure the build passes before committing.
  • Default branch is master (not main).

Generated code (do not edit)

  • .source/ is generated by fumadocs-mdx via the postinstall hook (and during dev/build). It is gitignored and regenerated — never hand-edit, never commit.
  • Import docs collections via the fumadocs-mdx:collections/* TS path alias (maps to ./.source/*, see tsconfig.json), e.g. fumadocs-mdx:collections/server in src/lib/source.ts.
  • If imports from fumadocs-mdx:collections/* fail to resolve, run bun install (triggers postinstall) or bun run build to regenerate.

Content & docs structure

  • MDX docs live in content/docs/. Each directory can have a meta.json that controls page order/sidebar (Fumadocs convention).
  • Frontmatter schema is defined in source.config.ts via frontmatterSchema / metaSchema from fumadocs-mdx/config. Don't invent custom frontmatter fields without extending the schema there.
  • src/app/docs/[[...slug]]/page.tsx renders MDX pages; src/lib/source.ts wires the Fumadocs loader with baseUrl: '/docs'.
  • LLM-friendly full text route: src/app/llms-full.txt/route.ts. OG images per doc: src/app/og/docs/[...slug]/route.tsx.

Path aliases

  • @/* → ./src/*
  • fumadocs-mdx:collections/* → ./.source/* (generated)

Patches

None. Earlier patches/ for fumadocs-mdx and @tailwindcss/node (swapping module.register → registerHooks) were dropped after upgrading to fumadocs-mdx@^15.2.2 / @tailwindcss/node@4.3.3, which fixed the issue upstream. If a Node module.register deprecation error resurfaces in MDX/Tailwind, that's the code path to re-patch.

Toolchain notes

  • Tailwind CSS 4 via @tailwindcss/postcss (see postcss.config.mjs); no tailwind.config.* file — Tailwind 4 config-less setup.
  • ESLint flat config (eslint.config.mjs) extends eslint-config-next/core-web-vitals + eslint-config-next/typescript. Ignores: node_modules, .next, out, build, .source, next-env.d.ts.
  • TypeScript is pinned to ^6.0.3, not ^7. TS 7 (the native port) is latest but Next 16.2.12's generated route types (.next/dev/types/validator.ts) don't type-check clean under it, and next dev/build reject it ("TypeScript 7.x does not provide the compiler API required by Next.js"). Stay on TS 6 until Next ships TS-7-clean generated types. next.config.mjs's experimental.useTypeScriptCli gets past the compiler-API error but not the generated-type errors — don't rely on it.
  • Deployment target is ambiguous: @opennextjs/cloudflare dependency indicates Cloudflare (OpenNext adapter), but README.md says Vercel. Confirm the deploy target before changing build/runtime config.