Jude Gao

This commit **upgrades the `@vercel/agent-eval` dependency** to version 0.9.5, addressing a breaking change in environment file loading. The `run-evals.js` script now correctly symlinks root `.env` files into the `evals/` directory, and `evals/.env` is added to `.gitignore` to maintain security. Concurrently, two **new evaluation tests** are introduced to assess the agent's knowledge of **Partial Prerendering (PPR)**. These new evals, `agent-041-optimize-ppr-shell` and `agent-042-enable-ppr`, verify the agent's ability to optimize `loading.tsx` for PPR and correctly identify the `cacheComponents: true` flag for enabling PPR, significantly enhancing the **agent evaluation suite's** coverage of modern Next.js features.

This commit **updates the documentation for AI agents** by revising the `AGENTS.md` snippet within the `docs/01-app/02-guides/ai-agents.mdx` file. This **documentation update** specifically **aligns the agent rules** to match the more precise wording found in the bundled documentation located at `node_modules/next/dist/docs/`. The previous version used softer language, and this **maintenance** change ensures AI agents receive consistent and accurate instructions. It emphasizes the importance of consulting the official bundled documentation, particularly concerning breaking changes, regardless of where they access the guidelines.

This commit introduces a **new feature** to the **`create-next-app` CLI** that significantly enhances its usability for automated environments and agents. When any explicit CLI flags are provided (e.g., `--typescript`, `--tailwind`), the tool will now **skip all remaining interactive prompts** and automatically apply recommended defaults for unspecified options. This **non-interactive behavior** ensures consistent and up-to-date project scaffolding, preventing agents from getting stuck or falling back to outdated methods. To maintain transparency, the **assumed defaults are explicitly printed to stdout**, informing users and scripts of the chosen configurations, thereby improving the **developer experience for automation and agents**.

This commit **introduces comprehensive documentation and an evaluation suite** for the `unstable_instant` feature, which aims to provide instant client-side navigations. It significantly expands the **App Router documentation** with a new dedicated guide, API reference for `unstable_instant`, and various AI agent hints across existing guides like data fetching, caching, and streaming. Concurrently, a new **agent-based evaluation** (`evals/agent-040-unstable-instant`) is added to verify the correct export and functionality of `unstable_instant` within a simulated application. This work ensures developers have the necessary resources to understand and utilize this performance-enhancing capability, while also providing automated checks for its behavior.

This commit provides a **maintenance fix** to prevent **out-of-memory (OOM) errors** encountered in the **CI `lint` job**, specifically during the execution of `lint-eslint` within the `lint-no-typescript` script. It addresses the issue where type-aware ESLint rules, which are memory-intensive, were exceeding Node's default heap limit. By increasing the `NODE_OPTIONS` `--max-old-space-size` to 8192MB for the `lint-no-typescript` script in `package.json`, the `lint-eslint` process now has sufficient memory. This ensures the **CI pipeline remains stable** and the comprehensive type-checked linting can complete successfully without crashing.

This commit introduces a **standardized evaluation system** for Next.js, centralizing **agent evaluation fixtures** within the main repository under `evals/`. This significant **refactoring** and **new capability** provides a consistent and streamlined way to run agent-based tests via a new `pnpm eval <name>` command. The system automatically packs the local Next.js build, generates experiment configurations, and executes them in a sandbox, enabling easy comparison of agent behavior with and without documentation changes. This setup greatly simplifies the evaluation process for both internal and external contributors, with the `next-evals-oss` benchmark runner now leveraging these co-located fixtures.

This commit **enhances** the guidance provided to AI agents by updating the prompt wording within the `AGENTS.md` file generated by **`create-next-app`**. Specifically, it modifies the `agentsMdContent` string in `packages/create-next-app/helpers/generate-agent-files.ts` to deliver a more emphatic warning about potential breaking changes and outdated training data. This **improves the clarity and effectiveness** of instructions for AI models, directing them to the correct documentation and deprecation notices before generating code. The updated prompt, determined through continuous evaluations, aims to prevent regressions and ensure AI-generated code aligns with the current Next.js version.

This commit **introduces a new documentation guide** (`ai-agents.mdx`) to assist users in configuring **AI coding agents** to utilize **version-matched Next.js documentation**. The guide explains how agents can access the up-to-date bundled docs located in `node_modules/next/dist/docs/`, preventing reliance on stale training data. It further details the purpose of `AGENTS.md` and `CLAUDE.md` files generated by `create-next-app --agents-md`, and provides instructions for adding project-specific agent rules. This **enhances the developer experience** by ensuring AI tools provide more accurate and relevant assistance based on the current Next.js version.

This commit introduces a **new capability** to enhance AI agent interaction with Next.js projects by providing up-to-date, version-matched documentation. It modifies the **`next` package build process** to bundle documentation into `node_modules/next/dist/docs/` and extends **`create-next-app`** with a new `--agents-md` flag. This flag, enabled by default, generates `AGENTS.md` and `CLAUDE.md` files that instruct AI agents to reference the shipped documentation, thereby mitigating issues caused by outdated training data. This **maintenance** effort ensures AI agents have access to accurate API information, significantly improving their reliability when working with Next.js.

This commit provides a **bug fix** for the `agents-md` codemod within the `next-codemod` package, resolving its failure on Windows due to incorrect path handling that led to empty `AGENTS.md` files. It updates `packages/next-codemod/lib/agents-md.ts` to use regex patterns like `/[/\\]/` for path separators and normalizes all paths to forward slashes, ensuring the doc tree builder functions correctly on Windows. Additionally, it **refactors** the git command execution from `execSync` to `execa` for improved robustness and consistency with other codemods. New end-to-end tests, including cross-platform path normalization scenarios, were added to validate the fix and ensure reliable operation of the `agents-md` codemod across different operating systems.

This commit introduces a **critical prompt engineering fix** within the `agents-md` module, specifically updating the instruction for **Claude LLMs** when handling Next.js tasks. The change modifies the prompt from a weak preference for retrieval-led reasoning to a strong, assertive command: "STOP. What you remember about Next.js is WRONG for this project. Always search docs and read before any task." This **maintenance improvement** directly addresses a discovered issue where agents were relying on outdated pre-training knowledge, leading to incorrect solutions like using `middleware.ts` instead of the current `proxy.ts` convention. The updated prompt significantly enhances the **reliability and accuracy** of the LLM agents by psychologically compelling them to prioritize current documentation over potentially stale internal knowledge, ensuring they produce up-to-date and correct Next.js implementations.

This commit introduces a **new capability** to the `@next/codemod` package by adding an `agents-md` subcommand. This command generates a Next.js documentation index specifically for AI coding agents, such as Claude or Copilot, by downloading version-specific docs and creating a compact, injectible index. This significantly improves the accuracy and relevance of AI agent responses by enabling them to prefer local, up-to-date documentation over potentially outdated pre-trained knowledge. The **`agents-md` subcommand** is implemented in `packages/next-codemod/lib/agents-md.ts`, with new tests in `agents-md.test.js` and an update to `.gitignore`.

This commit provides a **bug fix** for **Node.js proxy/middleware** on **Vercel deployments** when configured with both `basePath` and a custom `matcher`. Previously, this setup would fail on Vercel due to a double `basePath` prefixing issue in the `getRouteMatchers()` function, which incorrectly re-added the `basePath` to already-prefixed matchers. The fix modifies `packages/next/src/utils.ts` to pass `page: '/'` to `getRouteMatchers()` for Node.js middleware, aligning its behavior with edge middleware and preventing the redundant `basePath` addition. This ensures correct routing and functionality for these specific middleware configurations on Vercel, resolving a critical deployment issue.

This commit **fixes a critical build failure** in **Next.js's TypeScript integration** where `next build` would fail with type errors if stale development type definitions (`.next/dev/types/`) from a previous `next dev` session referenced routes that have since been deleted. The **bug fix** programmatically filters out these stale development types during the build's type check, ensuring that only relevant production types are considered without modifying the user's `tsconfig.json`. This improves the **robustness and reliability of the build system**, preventing unexpected errors and providing a smoother developer experience, especially when `isolatedDevBuild` is enabled. New **end-to-end tests** have been added to prevent regressions and validate the fix.

This commit **fixes an e2e test for typed routes** by updating its expectations to align with the current test fixture. Previously, the `test/e2e/app-dir/typed-routes/typed-routes.test.ts` expected a non-existent `/project/[slug]` route in the `RedirectRoutes` type, leading to incorrect test failures. This change removes the outdated expectation, ensuring the test accurately validates the **Next.js typed routes generation** based on existing project routes. Additionally, a minor **formatting fix** was applied to `apps/bundle-analyzer/next-env.d.ts` to maintain consistent code style.

This commit addresses a **race condition** within the **webpack worker** that impacted **telemetry event detection** for `@vercel/og` usage. This **bug fix** ensures more reliable and accurate data collection for this specific feature, preventing potential missed or incorrect telemetry events. The change also includes a clarifying comment in `test/integration/telemetry/test/config.test.ts` to explain the purpose of the test for `@vercel/og` telemetry tracking, improving test maintainability and understanding for future development.

This commit **fixes critical telemetry event loss** across several scenarios, significantly improving the reliability of data collection. It addresses issues where events were not flushed during **dev server shutdown** by reusing the correct telemetry instance in `next-dev-server.ts`, prevents data loss during **process exit timeouts** by implementing a `flushDetached()` mechanism in `start-server.ts` and `telemetry/storage.ts`, and ensures telemetry is captured even when **build errors** occur by replacing `process.exit()` calls with error throws and adding `finally` blocks with `await telemetry.flush()` in critical build paths. These changes impact the **core telemetry system**, **dev server lifecycle**, and **build error handling**, ensuring more complete and accurate telemetry data without blocking user processes.

This commit **updates the documentation** for the **Module Customization Protocol (MCP)** by simplifying the guide located at `docs/01-app/02-guides/mcp.mdx`. The revised content now **focuses exclusively on the `next-devtools-mcp` package**, providing clearer explanations of its capabilities and usage. This **documentation improvement** ensures that developers have a more streamlined and accurate resource for understanding and implementing MCP customizations, specifically through the recommended `next-devtools-mcp` tool.

This commit provides a **bug fix** for the `experimental.inlineCss` feature, resolving a critical issue where **CSS `url()` references to assets (like fonts) would break** when CSS was inlined into `<style>` tags. The fix involves modifying the **Webpack and Turbopack bundlers** to detect when CSS is being prepared for inlining and automatically convert relative asset URLs to absolute URLs. This ensures that asset references resolve correctly regardless of whether the CSS is inlined or external, **enhancing the reliability** of the `experimental.inlineCss` feature. The change primarily affects the **asset resolution logic** within the `next-api`, `next-core`, and various `turbopack` crates, making the feature transparently functional for users without requiring application code changes.

This commit delivers a **bug fix** for the **MCP `get_page_metadata` tool**, resolving an issue where browser sessions were incorrectly deduped by URL. Previously, the tool would report only one session even if multiple browser tabs were open to the same URL, leading to inaccurate session counts. The change modifies the `get_page_metadata` tool (`packages/next/src/server/mcp/tools/get-page-metadata.ts`) to store and process each browser session's metadata individually, ensuring correct and distinct session tracking. A new test case (`test/development/mcp-server/mcp-server-get-page-metadata.test.ts`) has been added to validate this behavior, significantly improving the accuracy of session reporting within the **Managed Cloud Platform**.