AI & Agent Dev Bug Sandbox logo
AI & Agent Dev Bug Sandbox
Back to Radar

@Next/Codemod Agents-Md Writes Docs `Root` Relative To Cwd Instead Of `--Output` Directory

The @next/codemod agents-md command computes the docs root path relative to the current working directory rather than the directory of the `--output` AGENTS.md file. In monorepos where the output file is at a different location (e.g. repo root) and Next.js is installed only in a workspace package, the generated root path is broken, causing agent tools to read nonexistent documentation paths.

highConfidence 95%Next.jsAffected V16.4.0

Origin Analysis

In `packages/next-codemod/bin/agents-md.ts`, the code calls `getBundledDocsLinkPath(cwd, bundledDocs.docsPath)` using `cwd` as the base directory. This base determines both the bundled-docs shortcut check (which returns `./node_modules/next/dist/docs` if that path exists under the base) and the relative path computation (`path.relative`). When `--output` points outside the current working directory, the resulting relative path is resolved from the wrong directory, producing an incorrect `root` in the generated AGENTS.md.
1. Create a pnpm workspace with `AGENTS.md` at the repo root and `next@16.4.0` as a dependency only of `apps/web`. 2. Run `pnpm install`. 3. From the app directory, execute `cd apps/web && npx @next/codemod@16.4.0 agents-md --output ../../AGENTS.md`. 4. Inspect the generated `AGENTS.md` at the repo root; the `root` field is `./node_modules/next/dist/docs`, but that path does not exist relative to the repo root (it should be `./apps/web/node_modules/next/dist/docs`).

Fixing Code Block

Edge Case Audit

This change only fixes the relative path when the `next` package is visible from the current working directory. If the codemod is run from a directory where `next` is not installed (e.g. repo root in a pnpm workspace), `getBundledDocsInfo(cwd)` will still not find the bundled docs, and the codemod will fall back to downloading `.next-docs`. A future enhancement should add a `--cwd` flag or workspace resolution to locate the installed `next` package. Before rolling out, test in hoisted and isolated `node_modules` layouts. Rollback: revert to using `cwd` as the base parameter for `getBundledDocsLinkPath`.

Ecosystem Topology