@next/codemod 16.5.0-canary.3 → 16.5.0-canary.30

package/bin/agents-md.js

@@ -58,18 +58,22 @@ async function runAgentsMd(options) {
         nextjsVersion = promptedOptions.nextVersion;
         targetFile = promptedOptions.targetFile;
     }
-    const agentsMdPath = path_1.default.join(cwd, targetFile);
-    // Next.js >= 16.2.0 ships its docs inside the published package. When the
-    // installed version matches the requested one, index the bundled docs
-    // directly instead of downloading a copy into .next-docs.
-    const bundledDocs = (0, agents_md_1.getBundledDocsInfo)(cwd);
-    const useBundledDocs = bundledDocs !== null && bundledDocs.version === nextjsVersion;
+    const agentsMdPath = path_1.default.resolve(cwd, targetFile);
+    // Agents resolve paths in the index from the directory of the output file,
+    // so every link written into it is relative to that directory, not the cwd.
+    const outputDir = path_1.default.dirname(agentsMdPath);
+    // Next.js >= 16.2.0 ships its docs inside the published package. When an
+    // installed version (from the cwd or, in a monorepo, a workspace package)
+    // matches the requested one, index the bundled docs directly instead of
+    // downloading a copy into .next-docs.
+    const bundledDocs = (0, agents_md_1.getBundledDocsInfo)(cwd, nextjsVersion);
+    const useBundledDocs = bundledDocs !== null;
     const docsPath = useBundledDocs
         ? bundledDocs.docsPath
         : path_1.default.join(cwd, DOCS_DIR_NAME);
     const docsLinkPath = useBundledDocs
-        ? (0, agents_md_1.getBundledDocsLinkPath)(cwd, bundledDocs.docsPath)
-        : `./${DOCS_DIR_NAME}`;
+        ? (0, agents_md_1.getBundledDocsLinkPath)(outputDir, bundledDocs.docsPath, bundledDocs.resolvedFrom)
+        : (0, agents_md_1.getRelativeLinkPath)(outputDir, docsPath);
     let sizeBefore = 0;
     let isNewFile = true;
     let existingContent = '';
@@ -79,7 +83,10 @@ async function runAgentsMd(options) {
         isNewFile = false;
     }
     if (useBundledDocs) {
-        console.log(`\nUsing the docs bundled with Next.js ${picocolors_1.default.cyan(nextjsVersion)} at ${picocolors_1.default.cyan(docsLinkPath)} (no download needed).`);
+        const fromWorkspacePackage = path_1.default.resolve(bundledDocs.resolvedFrom) !== path_1.default.resolve(cwd)
+            ? ` from workspace package ${picocolors_1.default.cyan(path_1.default.relative(cwd, bundledDocs.resolvedFrom).replace(/\\/g, '/'))}`
+            : '';
+        console.log(`\nUsing the docs bundled with Next.js ${picocolors_1.default.cyan(nextjsVersion)}${fromWorkspacePackage} at ${picocolors_1.default.cyan(docsLinkPath)} (no download needed).`);
     }
     else {
         console.log(`\nDownloading Next.js ${picocolors_1.default.cyan(nextjsVersion)} documentation to ${picocolors_1.default.cyan(DOCS_DIR_NAME)}...`);
@@ -97,7 +104,8 @@ async function runAgentsMd(options) {
     const indexContent = (0, agents_md_1.generateAgentsMdIndex)({
         docsPath: docsLinkPath,
         sections,
-        outputFile: targetFile,
+        // The regeneration hint is run from the output file's directory.
+        outputFile: path_1.default.relative(outputDir, agentsMdPath).replace(/\\/g, '/'),
     });
     const newContent = (0, agents_md_1.injectIntoAgentsMd)(existingContent, indexContent);
     fs_1.default.writeFileSync(agentsMdPath, newContent, 'utf-8');

package/lib/__tests__/agents-md-e2e.test.js

@@ -4,9 +4,22 @@ jest.autoMockOff()
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
+const { execFileSync } = require('child_process')
 const { runAgentsMd } = require('../../bin/agents-md')
 const { getNextjsVersion } = require('../../lib/agents-md')
 
+function execNodeWithoutNodePath(script, options = {}) {
+  // pnpm 12's Jest launcher exposes hoisted dependencies through NODE_PATH.
+  // A fresh Node process must omit it to resolve only the fixture's dependencies.
+  const env = { ...process.env, ...options.env }
+  delete env.NODE_PATH
+  return execFileSync(process.execPath, ['-e', script], {
+    ...options,
+    env,
+    encoding: 'utf8',
+  })
+}
+
 /**
  * TRUE E2E TESTS
  * These tests invoke the actual CLI entry point (runAgentsMd),
@@ -406,6 +419,432 @@ This is my project documentation.
     }, 30000) // Increase timeout for git clone
   })
 
+  // The index `root` is resolved by agents from the directory of the output
+  // file, so it must be relative to that directory, not to the cwd.
+  describe('paths relative to the output file', () => {
+    const agentsMdLib = require('../../lib/agents-md')
+    let originalCwd
+    let pullDocsSpy
+
+    // Install `next` the way pnpm's isolated linker does: the real package
+    // lives in the root `node_modules/.pnpm` store and is only symlinked into
+    // the package that depends on it.
+    function installNextIsolated(projectDir, pkgDir, version) {
+      const storeDir = path.join(
+        projectDir,
+        'node_modules',
+        '.pnpm',
+        `next@${version}`,
+        'node_modules',
+        'next'
+      )
+      writeBundledNextPackage(storeDir, version)
+      const linkDir = path.join(pkgDir, 'node_modules')
+      fs.mkdirSync(linkDir, { recursive: true })
+      fs.symlinkSync(storeDir, path.join(linkDir, 'next'), 'junction')
+    }
+
+    function writeBundledNextPackage(nextDir, version) {
+      const docsDir = path.join(nextDir, 'dist', 'docs', '01-app')
+      fs.mkdirSync(docsDir, { recursive: true })
+      fs.writeFileSync(
+        path.join(nextDir, 'package.json'),
+        JSON.stringify({ name: 'next', version })
+      )
+      fs.writeFileSync(path.join(docsDir, `docs-${version}.md`), '# Docs')
+    }
+
+    function readIndex(agentsMdPath) {
+      const content = fs.readFileSync(agentsMdPath, 'utf-8')
+      return {
+        content,
+        root: content.match(/\|root: ([^|]+)\|/)[1],
+      }
+    }
+
+    // Returns the absolute path `root` points at, resolved the way an agent
+    // reading the output file would resolve it.
+    function resolveRoot(agentsMdPath) {
+      return path.resolve(path.dirname(agentsMdPath), readIndex(agentsMdPath).root)
+    }
+
+    beforeEach(() => {
+      originalCwd = process.cwd()
+      // Stub the download so the `.next-docs` branch is testable offline.
+      pullDocsSpy = jest
+        .spyOn(agentsMdLib, 'pullDocs')
+        .mockImplementation(async ({ docsDir }) => {
+          const sectionDir = path.join(docsDir, '01-app')
+          fs.mkdirSync(sectionDir, { recursive: true })
+          fs.writeFileSync(path.join(sectionDir, 'downloaded.md'), '# Docs')
+          return { success: true, docsPath: docsDir }
+        })
+    })
+
+    afterEach(() => {
+      process.chdir(originalCwd)
+      pullDocsSpy.mockRestore()
+    })
+
+    it('links bundled docs relative to an output file outside the cwd', async () => {
+      const appDir = path.join(testProjectDir, 'apps', 'web')
+      installNextIsolated(testProjectDir, appDir, '16.4.0')
+      process.chdir(appDir)
+
+      await runAgentsMd({ output: '../../AGENTS.md' })
+
+      const agentsMdPath = path.join(testProjectDir, 'AGENTS.md')
+      expect(readIndex(agentsMdPath).root).toBe(
+        './apps/web/node_modules/next/dist/docs'
+      )
+      expect(
+        fs.existsSync(path.join(resolveRoot(agentsMdPath), '01-app'))
+      ).toBe(true)
+      expect(pullDocsSpy).not.toHaveBeenCalled()
+    })
+
+    it('links downloaded docs relative to an output file outside the cwd', async () => {
+      const appDir = path.join(testProjectDir, 'apps', 'web')
+      fs.mkdirSync(appDir, { recursive: true })
+      process.chdir(appDir)
+
+      await runAgentsMd({ version: '15.0.0', output: '../../AGENTS.md' })
+
+      const agentsMdPath = path.join(testProjectDir, 'AGENTS.md')
+      expect(readIndex(agentsMdPath).root).toBe('./apps/web/.next-docs')
+      expect(fs.realpathSync(resolveRoot(agentsMdPath))).toBe(
+        fs.realpathSync(path.join(appDir, '.next-docs'))
+      )
+    })
+
+    it('keeps the ./ prefix for the .next-docs dot-directory', async () => {
+      process.chdir(testProjectDir)
+
+      await runAgentsMd({ version: '15.0.0', output: 'AGENTS.md' })
+
+      expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
+        './.next-docs'
+      )
+    })
+
+    it('links the indexed install when the output dir resolves a different next', async () => {
+      // Root has a hoisted next@16.3.0; the app has its own next@16.4.0.
+      writeBundledNextPackage(
+        path.join(testProjectDir, 'node_modules', 'next'),
+        '16.3.0'
+      )
+      const appDir = path.join(testProjectDir, 'apps', 'web')
+      installNextIsolated(testProjectDir, appDir, '16.4.0')
+      process.chdir(appDir)
+
+      await runAgentsMd({ output: '../../AGENTS.md' })
+
+      const agentsMdPath = path.join(testProjectDir, 'AGENTS.md')
+      const linkedPkg = JSON.parse(
+        fs.readFileSync(
+          path.join(resolveRoot(agentsMdPath), '..', '..', 'package.json'),
+          'utf-8'
+        )
+      )
+      expect(linkedPkg.version).toBe('16.4.0')
+      expect(readIndex(agentsMdPath).content).toContain('docs-16.4.0.md')
+    })
+
+    it('writes a regeneration hint that is relative to the output file', async () => {
+      const appDir = path.join(testProjectDir, 'apps', 'web')
+      installNextIsolated(testProjectDir, appDir, '16.4.0')
+      process.chdir(appDir)
+
+      await runAgentsMd({ output: '../../AGENTS.md' })
+
+      const { content } = readIndex(path.join(testProjectDir, 'AGENTS.md'))
+      expect(content).toContain(
+        "If docs missing, run this command from this file's directory: npx @next/codemod agents-md --output AGENTS.md|"
+      )
+      expect(content).not.toContain('--output ../../AGENTS.md')
+    })
+
+    it('supports an absolute --output path', async () => {
+      const appDir = path.join(testProjectDir, 'apps', 'web')
+      installNextIsolated(testProjectDir, appDir, '16.4.0')
+      const outputDir = path.join(testProjectDir, 'docs-out')
+      fs.mkdirSync(outputDir)
+      const agentsMdPath = path.join(outputDir, 'CLAUDE.md')
+      process.chdir(appDir)
+
+      await runAgentsMd({ output: agentsMdPath })
+
+      expect(fs.existsSync(agentsMdPath)).toBe(true)
+      const { root, content } = readIndex(agentsMdPath)
+      expect(root).toBe('../apps/web/node_modules/next/dist/docs')
+      expect(
+        fs.existsSync(path.join(resolveRoot(agentsMdPath), '01-app'))
+      ).toBe(true)
+      expect(content).toContain('--output CLAUDE.md|')
+    })
+
+    // The cwd/output path and the path `next` resolves to can be spelled
+    // differently for the same directory: a symlinked alias, or an 8.3 short
+    // name like `C:\Users\RUNNER~1\...` on Windows, where `process.cwd()`
+    // keeps the short name while module resolution returns the long one.
+    // Links must still be computed between consistent spellings.
+    describe('when the cwd is spelled differently than the realpath', () => {
+      let aliasBase
+      let aliasDir
+      let cwdSpy
+
+      // Run from `dir` (inside the real project) while `process.cwd()`
+      // reports it through the alias, like a non-canonical cwd on Windows.
+      function chdirViaAlias(dir) {
+        process.chdir(dir)
+        const aliased = path.join(
+          aliasDir,
+          path.relative(fs.realpathSync(testProjectDir), fs.realpathSync(dir))
+        )
+        cwdSpy = jest.spyOn(process, 'cwd').mockReturnValue(aliased)
+      }
+
+      beforeEach(() => {
+        aliasBase = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-md-alias-'))
+        aliasDir = path.join(aliasBase, 'project')
+        fs.symlinkSync(testProjectDir, aliasDir, 'junction')
+      })
+
+      afterEach(() => {
+        cwdSpy?.mockRestore()
+        cwdSpy = undefined
+        fs.rmSync(aliasBase, { recursive: true, force: true })
+      })
+
+      it('links the conventional path through a symlinked cwd', async () => {
+        writeBundledNextPackage(
+          path.join(testProjectDir, 'node_modules', 'next'),
+          '16.4.0'
+        )
+        chdirViaAlias(testProjectDir)
+
+        await runAgentsMd({ output: 'AGENTS.md' })
+
+        const agentsMdPath = path.join(testProjectDir, 'AGENTS.md')
+        expect(readIndex(agentsMdPath).root).toBe(
+          './node_modules/next/dist/docs'
+        )
+      })
+
+      it('links a hoisted install canonically through a symlinked cwd', async () => {
+        writeBundledNextPackage(
+          path.join(testProjectDir, 'node_modules', 'next'),
+          '16.4.0'
+        )
+        const appDir = path.join(testProjectDir, 'apps', 'web')
+        fs.mkdirSync(appDir, { recursive: true })
+        chdirViaAlias(appDir)
+
+        await runAgentsMd({ output: 'AGENTS.md' })
+
+        const agentsMdPath = path.join(testProjectDir, 'apps', 'web', 'AGENTS.md')
+        expect(readIndex(agentsMdPath).root).toBe(
+          '../../node_modules/next/dist/docs'
+        )
+        expect(
+          fs.existsSync(path.join(resolveRoot(agentsMdPath), '01-app'))
+        ).toBe(true)
+      })
+
+      it('detects the same install when only the native realpath canonicalizes', async () => {
+        // Simulate Windows 8.3 short names: the JS `fs.realpathSync` leaves
+        // the alias spelling as-is, while `fs.realpathSync.native` expands it.
+        writeBundledNextPackage(
+          path.join(testProjectDir, 'node_modules', 'next'),
+          '16.4.0'
+        )
+        chdirViaAlias(testProjectDir)
+        const nativeRealpath = fs.realpathSync.native
+        const realpathSpy = jest
+          .spyOn(fs, 'realpathSync')
+          .mockImplementation((p) => path.resolve(String(p)))
+        fs.realpathSync.native = nativeRealpath
+
+        try {
+          await runAgentsMd({ output: 'AGENTS.md' })
+        } finally {
+          realpathSpy.mockRestore()
+        }
+
+        expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
+          './node_modules/next/dist/docs'
+        )
+      })
+    })
+
+    it('always prefixes relative links with ./ or ../', () => {
+      const { getRelativeLinkPath } = agentsMdLib
+      const base = path.join(testProjectDir, 'a', 'b')
+
+      expect(getRelativeLinkPath(base, base)).toBe('./')
+      expect(getRelativeLinkPath(base, path.join(testProjectDir, 'a'))).toBe(
+        '../'
+      )
+      expect(getRelativeLinkPath(base, path.join(base, '.next-docs'))).toBe(
+        './.next-docs'
+      )
+      expect(
+        getRelativeLinkPath(base, path.join(testProjectDir, 'a', 'docs'))
+      ).toBe('../docs')
+      expect(getRelativeLinkPath(base, path.join(base, '..docs'))).toBe(
+        './..docs'
+      )
+    })
+
+    // In a pnpm monorepo `next` is usually not resolvable from the repo root,
+    // so the bundled docs have to be found through the workspace packages.
+    describe('bundled docs from workspace packages', () => {
+      function setupWorkspace(patterns, packages) {
+        fs.writeFileSync(
+          path.join(testProjectDir, 'package.json'),
+          JSON.stringify({ name: 'root', private: true })
+        )
+        fs.writeFileSync(
+          path.join(testProjectDir, 'pnpm-workspace.yaml'),
+          `packages:\n${patterns.map((p) => `  - '${p}'`).join('\n')}\n`
+        )
+        for (const [pkg, version] of Object.entries(packages)) {
+          const pkgDir = path.join(testProjectDir, pkg)
+          fs.mkdirSync(pkgDir, { recursive: true })
+          fs.writeFileSync(
+            path.join(pkgDir, 'package.json'),
+            JSON.stringify({ name: path.basename(pkg) })
+          )
+          if (version) installNextIsolated(testProjectDir, pkgDir, version)
+        }
+      }
+
+      function output() {
+        // Package names are colored; strip ANSI so FORCE_COLOR doesn't matter.
+        return require('strip-ansi')(consoleOutput.join('\n'))
+      }
+
+      function runFromWorkspaceRoot() {
+        return require('strip-ansi')(
+          execNodeWithoutNodePath(
+            `const { runAgentsMd } = require(${JSON.stringify(
+              path.join(__dirname, '../../bin/agents-md.js')
+            )})
+              runAgentsMd({ output: 'AGENTS.md' }).catch((error) => {
+                console.error(error)
+                process.exitCode = 1
+              })`,
+            { cwd: testProjectDir }
+          )
+        )
+      }
+
+      it('uses the bundled docs of a workspace package when run from the root', () => {
+        setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
+
+        const cliOutput = runFromWorkspaceRoot()
+
+        const agentsMdPath = path.join(testProjectDir, 'AGENTS.md')
+        expect(readIndex(agentsMdPath).root).toBe(
+          './apps/web/node_modules/next/dist/docs'
+        )
+        expect(
+          fs.existsSync(path.join(resolveRoot(agentsMdPath), '01-app'))
+        ).toBe(true)
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          false
+        )
+        expect(fs.existsSync(path.join(testProjectDir, '.gitignore'))).toBe(
+          false
+        )
+        expect(cliOutput).toContain('workspace package apps/web')
+      })
+
+      it('indexes the package with the highest Next.js version', () => {
+        setupWorkspace(['apps/a', 'apps/b'], {
+          'apps/a': '16.3.0',
+          'apps/b': '16.4.0',
+        })
+
+        const cliOutput = runFromWorkspaceRoot()
+
+        const { root, content } = readIndex(
+          path.join(testProjectDir, 'AGENTS.md')
+        )
+        expect(root).toBe('./apps/b/node_modules/next/dist/docs')
+        expect(content).toContain('docs-16.4.0.md')
+        expect(cliOutput).not.toContain('Downloading')
+        expect(fs.existsSync(path.join(testProjectDir, '.next-docs'))).toBe(
+          false
+        )
+      })
+
+      it('picks the first matching package in workspace order and logs it', () => {
+        // Listed b before a, so the choice follows the workspace patterns
+        // rather than alphabetical order.
+        setupWorkspace(['apps/b', 'apps/a'], {
+          'apps/a': '16.4.0',
+          'apps/b': '16.4.0',
+        })
+
+        const cliOutput = runFromWorkspaceRoot()
+
+        expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
+          './apps/b/node_modules/next/dist/docs'
+        )
+        expect(cliOutput).toContain('workspace package apps/b')
+        expect(cliOutput).not.toContain('workspace package apps/a')
+      })
+
+      it('prefers a matching install resolved from the cwd', async () => {
+        setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
+        writeBundledNextPackage(
+          path.join(testProjectDir, 'node_modules', 'next'),
+          '16.4.0'
+        )
+        process.chdir(testProjectDir)
+
+        await runAgentsMd({ output: 'AGENTS.md' })
+
+        expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
+          './node_modules/next/dist/docs'
+        )
+        expect(output()).not.toContain('workspace package')
+      })
+
+      it('uses a workspace package matching --version when the cwd resolves another version', async () => {
+        setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
+        writeBundledNextPackage(
+          path.join(testProjectDir, 'node_modules', 'next'),
+          '16.3.0'
+        )
+        process.chdir(testProjectDir)
+
+        await runAgentsMd({ version: '16.4.0', output: 'AGENTS.md' })
+
+        const { root, content } = readIndex(
+          path.join(testProjectDir, 'AGENTS.md')
+        )
+        expect(root).toBe('./apps/web/node_modules/next/dist/docs')
+        expect(content).toContain('docs-16.4.0.md')
+        expect(pullDocsSpy).not.toHaveBeenCalled()
+      })
+
+      it('still downloads when no workspace package has matching bundled docs', async () => {
+        setupWorkspace(['apps/*'], { 'apps/web': '16.4.0' })
+        process.chdir(testProjectDir)
+
+        await runAgentsMd({ version: '15.0.0', output: 'AGENTS.md' })
+
+        expect(pullDocsSpy).toHaveBeenCalled()
+        expect(readIndex(path.join(testProjectDir, 'AGENTS.md')).root).toBe(
+          './.next-docs'
+        )
+        expect(output()).not.toContain('workspace package')
+      })
+    })
+  })
+
   describe('getNextjsVersion', () => {
     const fixturesDir = path.join(__dirname, 'fixtures/agents-md')
 
@@ -428,9 +867,15 @@ This is my project documentation.
     })
 
     it('returns error when Next.js is not installed', () => {
-      // Use a directory where next is not installed
-      const nonNextDir = '/tmp'
-      const result = getNextjsVersion(nonNextDir)
+      const result = JSON.parse(
+        execNodeWithoutNodePath(
+          `const { getNextjsVersion } = require(${JSON.stringify(
+            path.join(__dirname, '../agents-md.js')
+          )})
+          console.log(JSON.stringify(getNextjsVersion(process.cwd())))`,
+          { cwd: testProjectDir }
+        )
+      )
 
       expect(result.version).toBeNull()
       expect(result.error).toBe('Next.js is not installed in this project.')

package/lib/agents-md.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.refreshAgentRulesBlock = refreshAgentRulesBlock;
 exports.getNextjsVersion = getNextjsVersion;
 exports.getBundledDocsInfo = getBundledDocsInfo;
+exports.getRelativeLinkPath = getRelativeLinkPath;
 exports.getBundledDocsLinkPath = getBundledDocsLinkPath;
 exports.pullDocs = pullDocs;
 exports.collectDocFiles = collectDocFiles;
@@ -87,33 +88,98 @@ function getNextjsVersion(cwd) {
 }
 /**
  * Next.js ships its documentation inside the published package (at
- * `dist/docs`) since 16.2.0. When the install resolved from `cwd` has
- * bundled docs, the index can point at them directly instead of
- * downloading a copy into `.next-docs`.
+ * `dist/docs`) since 16.2.0. When an installed `next` of the requested
+ * `version` has bundled docs, the index can point at them directly instead
+ * of downloading a copy into `.next-docs`.
+ *
+ * The install resolved from `cwd` wins; otherwise the workspace packages are
+ * searched.
  */
-function getBundledDocsInfo(cwd) {
+function getBundledDocsInfo(cwd, version) {
+    const fromCwd = getBundledDocsInfoFrom(cwd);
+    if (fromCwd?.version === version) {
+        return fromCwd;
+    }
+    // Mirror getNextjsVersion: with isolated installs (pnpm), `next` is often
+    // only resolvable from the workspace package that depends on it, not from
+    // the repo root. Use the first package, in workspace order, that ships
+    // bundled docs for the requested version.
+    const workspace = detectWorkspace(cwd);
+    if (workspace.isMonorepo) {
+        for (const pkgPath of expandWorkspacePatterns(cwd, workspace.packages)) {
+            const info = getBundledDocsInfoFrom(pkgPath);
+            if (info?.version === version) {
+                return info;
+            }
+        }
+    }
+    return null;
+}
+function getBundledDocsInfoFrom(dir) {
     try {
-        const nextPkgPath = require.resolve('next/package.json', { paths: [cwd] });
+        const nextPkgPath = require.resolve('next/package.json', { paths: [dir] });
         const pkg = JSON.parse(fs_1.default.readFileSync(nextPkgPath, 'utf-8'));
         const docsPath = path_1.default.join(path_1.default.dirname(nextPkgPath), 'dist', 'docs');
         if (!pkg.version || collectDocFiles(docsPath).length === 0) {
             return null;
         }
-        return { docsPath, version: pkg.version };
+        return { docsPath, version: pkg.version, resolvedFrom: dir };
     }
     catch {
         return null;
     }
 }
-function getBundledDocsLinkPath(cwd, docsPath) {
-    // Prefer the conventional path when it resolves from the project
-    // (covers hoisted installs; pnpm exposes next via a node_modules symlink).
-    const conventional = path_1.default.join(cwd, 'node_modules', 'next', 'dist', 'docs');
-    if (fs_1.default.existsSync(conventional)) {
-        return './node_modules/next/dist/docs';
-    }
-    const relative = path_1.default.relative(cwd, docsPath).replace(/\\/g, '/');
-    return relative.startsWith('.') ? relative : `./${relative}`;
+/**
+ * Returns `target` as a `./`- or `../`-prefixed, forward-slash path relative
+ * to `fromDir`. Agents resolve paths in the index from the directory of the
+ * output file, so `fromDir` must be that directory, not the cwd.
+ */
+function getRelativeLinkPath(fromDir, target) {
+    const relative = path_1.default.relative(fromDir, target).replace(/\\/g, '/');
+    if (relative === '')
+        return './';
+    if (relative === '..')
+        return '../';
+    // A dot-directory such as `.next-docs` still needs the `./` prefix.
+    return relative.startsWith('../') ? relative : `./${relative}`;
+}
+/**
+ * Canonical spelling of `p`: symlinks resolved and, on Windows, 8.3 short
+ * names (e.g. `C:\Users\RUNNER~1`) expanded. `process.cwd()` can keep a
+ * non-canonical spelling while module resolution returns the canonical one,
+ * so compare and relate paths only in this form. Falls back to the resolved
+ * path when `p` cannot be canonicalized (e.g. it does not exist).
+ */
+function canonicalPath(p) {
+    try {
+        return fs_1.default.realpathSync.native(p);
+    }
+    catch {
+        return path_1.default.resolve(p);
+    }
+}
+/**
+ * Link to the bundled docs of the install resolved from `resolvedFrom`,
+ * relative to `fromDir` (the directory of the output file).
+ */
+function getBundledDocsLinkPath(fromDir, docsPath, resolvedFrom) {
+    // Prefer the conventional path of the resolved install over its realpath:
+    // pnpm's `.pnpm/next@x.y.z/...` realpath changes on every upgrade, while
+    // the `node_modules/next` symlink stays stable. Check it under the
+    // directory `next` was resolved from, not under `fromDir`, which may see a
+    // different `next` install.
+    //
+    // Paths are related in canonical form (see canonicalPath) so a cwd or
+    // --output spelled differently than the resolved install still produces a
+    // clean link. Only the parent of the `node_modules/next` symlink is
+    // canonicalized, never the symlink itself, so the stable path is kept.
+    const outputDir = canonicalPath(fromDir);
+    const conventional = path_1.default.join(canonicalPath(resolvedFrom), 'node_modules', 'next', 'dist', 'docs');
+    if (fs_1.default.existsSync(conventional) &&
+        canonicalPath(conventional) === canonicalPath(docsPath)) {
+        return getRelativeLinkPath(outputDir, conventional);
+    }
+    return getRelativeLinkPath(outputDir, canonicalPath(docsPath));
 }
 function versionToGitHubTag(version) {
     return version.startsWith('v') ? version : `v${version}`;
@@ -264,7 +330,7 @@ function generateAgentsMdIndex(data) {
     parts.push(`root: ${docsPath}`);
     parts.push('STOP. What you remember about Next.js is WRONG for this project. Always search docs and read before any task.');
     const targetFile = outputFile || 'AGENTS.md';
-    parts.push(`If docs missing, run this command first: npx @next/codemod agents-md --output ${targetFile}`);
+    parts.push(`If docs missing, run this command from this file's directory: npx @next/codemod agents-md --output ${targetFile}`);
     const allFiles = collectAllFilesFromSections(sections);
     const grouped = groupByDirectory(allFiles);
     for (const [dir, files] of grouped) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/codemod",
-  "version": "16.5.0-canary.3",
+  "version": "16.5.0-canary.30",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,9 @@
     "lib/**/*.js",
     "lib/cra-to-next/gitignore"
   ],
-  "bin": "./bin/next-codemod.js",
+  "bin": {
+    "codemod": "./bin/next-codemod.js"
+  },
   "devDependencies": {
     "@types/find-up": "4.0.0",
     "@types/js-yaml": "4.0.9",