docs(nx-plugin): add guide on writing performant createNodes v2 plugins

Document practical patterns and caveats for keeping createNodesV2 plugins
fast: prefer the batched v2 API, cache results to disk with a content hash,
hoist shared work out of the per-file loop, load configs in parallel, keep
globs narrow and output deterministic, and avoid per-file process spawning.
Also covers daemon/cache dev overrides and diagnosing slow graph creation
with NX_PERF_LOGGING and nx report.

Generated with [Linear](https://linear.app/nxdev/issue/DOC-516/document-performant-createnodes-v2-plugin-patterns#agent-session-07d2f00a)

Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>

.circleci/config.yml

@@ -1,37 +0,0 @@
-version: 2.1
-
-# -------------------------
-#        EXECUTORS
-# -------------------------
-
-defaults: &defaults
-  working_directory: ~/repo
-
-executors:
-  linux:
-    <<: *defaults
-    docker:
-      - image: cimg/rust:1.84.0-browsers
-    resource_class: small
-
-# -------------------------
-#          JOBS
-# -------------------------
-jobs:
-  # -------------------------
-  #     JOBS: Main Linux
-  # -------------------------
-  main-linux:
-    executor: linux
-    steps:
-      - run: echo "We are in the process of transitioning from Circle CI to GitHub Actions. For details about your build results, consult github actions build logs."
-
-# -------------------------
-#        WORKFLOWS(JOBS)
-# -------------------------
-workflows:
-  version: 2
-
-  build:
-    jobs:
-      - main-linux

.claude/disabled-skills/diagnose-sandbox-report/DISABLED.md

@@ -0,0 +1,3 @@
+This skill is disabled to encourage use of the AI prompt from the nx cloud sandboxing dashboard.
+
+If you still need the original skill, you can reference it with @./claude/disabled-skills/diagnose-sandbox-report/SKILL.md directly.

.claude/skills/dist-build-migration/SKILL.md

@@ -0,0 +1,590 @@
+---
+name: dist-build-migration
+description: Migrate an Nx package to build to a local dist/ directory with nodenext module resolution, exports map, and @nx/nx-source condition.
+allowed-tools: Bash, Read, Glob, Grep, Agent, Edit, Write
+---
+
+# Migrate Package to Local Dist Build
+
+You are migrating an Nx monorepo package from building to `../../dist/packages/<name>` to building locally to `packages/<name>/dist/`. This matches the pattern already used by `nx` and `devkit`.
+
+## Argument
+
+The user provides a package name (e.g., `js`, `webpack`, `angular`). The package lives at `packages/<name>/`.
+
+## Steps
+
+### 0. Preflight: check `workspace:*` deps for unmigrated packages
+
+Read `packages/<name>/package.json` and list every `workspace:*` dep (in `dependencies`, `devDependencies`, `peerDependencies`).
+
+For each such dep, look at the target package's `project.json`. If it does **not** override `release.version.manifestRootsToUpdate` to `["packages/{projectName}"]`, that target package is still on the old layout. You **must** migrate those packages too (apply this skill to each), in the same PR.
+
+**Why:** With `preserveLocalDependencyProtocols: true` (the new pattern), `nx release version` does not substitute `workspace:*` in your manifest. At publish time, pnpm resolves `workspace:*` by reading the target's _source_ `packages/<dep>/package.json`. The default `manifestRootsToUpdate: ["dist/packages/{projectName}"]` only bumps the dist copy, so pnpm picks up the unbumped source `0.0.1` and publishes your package with a dep on a version that does not exist in the registry. Local registry installs then fail with `ERR_PNPM_NO_MATCHING_VERSION`.
+
+A `workspace:*` dep on a still-on-old-layout package is a hard blocker — migrate it before continuing.
+
+### 1. Read current state
+
+Read these files for the target package:
+
+- `packages/<name>/package.json`
+- `packages/<name>/project.json`
+- `packages/<name>/tsconfig.lib.json`
+- `packages/<name>/tsconfig.spec.json` (if exists)
+- `packages/<name>/.eslintrc.json` (if exists)
+- `packages/<name>/assets.json` (if exists)
+- `packages/<name>/.npmignore` (if exists)
+- `packages/<name>/.gitignore` (if exists)
+
+Also read the reference implementations:
+
+- `packages/devkit/tsconfig.lib.json`
+- `packages/devkit/package.json`
+- `packages/devkit/project.json`
+- `packages/devkit/.npmignore`
+
+Run `pnpm nx show target <name>:build-base` to see the inferred build target.
+Run `pnpm nx show target <name>:build` to see the full build target.
+
+### 2. Identify entry points
+
+Look at the package's root `.ts` files and any existing `exports` field. Common entry points:
+
+- `index.ts` (main)
+- `testing.ts`
+- `internal.ts`
+- `ngcli-adapter.ts`
+- Any other `.ts` files at the package root that re-export from `src/`
+
+Also check for `migrations.json` and `generators.json`/`executors.json` — these need exports entries too.
+
+### 3. Update `tsconfig.lib.json`
+
+Transform from the old pattern to the new pattern:
+
+**Before:**
+
+```json
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "outDir": "../../dist/packages/<name>",
+    "tsBuildInfoFile": "../../dist/packages/<name>/tsconfig.tsbuildinfo"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": ".",
+    "declarationDir": "dist",
+    "declarationMap": false,
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo",
+    "types": ["node"],
+    "composite": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "exclude": ["node_modules", "dist", ...existing excludes, ".eslintrc.json"],
+  "include": ["*.ts", "src/**/*.ts"]
+}
+```
+
+**Important**: Adjust `include` based on the package's actual structure. If the package has directories like `bin/`, `plugins/`, etc. at the root level (like `nx` does), include those too.
+
+### 4. Update `tsconfig.spec.json` (if exists)
+
+Change `outDir` from `../../dist/packages/<name>/spec` to `dist/spec`.
+
+### 5. Update `package.json`
+
+Key changes:
+
+- Add `"type": "commonjs"` near the top (after `private`)
+- Change `"main"` to `"./dist/index.js"`
+- Change `"types"` to `"./dist/index.d.ts"`
+- Add `"typesVersions"` for backwards compatibility with `moduleResolution: "node"` consumers
+- Add `"exports"` map with entries for each entry point
+
+Each export entry follows this pattern:
+
+```json
+"./entry-name": {
+  "@nx/nx-source": "./entry-name.ts",
+  "types": "./entry-name.d.ts",
+  "default": "./dist/entry-name.js"
+}
+```
+
+The main entry (`.`) uses `./index.ts`, `./index.d.ts`, `./dist/index.js`.
+
+Always include:
+
+```json
+"./package.json": "./package.json"
+```
+
+Include `"./migrations.json": "./migrations.json"` if the package has migrations.
+
+**Note**: The `@nx/nx-source` condition is a custom condition used for source-level resolution within the workspace (so other packages import from source, not dist).
+
+Add a `typesVersions` field for consumers using `moduleResolution: "node"` (which doesn't read `exports`):
+
+```json
+"typesVersions": {
+  "*": {
+    "testing": ["dist/testing.d.ts"],
+    "ngcli-adapter": ["dist/ngcli-adapter.d.ts"]
+  }
+}
+```
+
+Add an entry for each subpath export (excluding `.`, `./package.json`, and `./migrations.json`).
+
+### 6. Update `project.json`
+
+Add these sections:
+
+```json
+{
+  "release": {
+    "version": {
+      "generator": "@nx/js:release-version",
+      "preserveLocalDependencyProtocols": true,
+      "manifestRootsToUpdate": ["packages/{projectName}"]
+    }
+  },
+  "targets": {
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "packages/{projectName}"
+      }
+    }
+  }
+}
+```
+
+Do **not** override `build-base.outputs` in `project.json`. The `@nx/js/typescript` plugin reads `outDir` and `tsBuildInfoFile` from `tsconfig.lib.json` and infers the correct outputs (including the tsbuildinfo and the full set of file extensions). A hand-written override is almost always less complete than the inferred set.
+
+If the package already has a hand-written `build-base.outputs` array, **delete it** — don't try to patch it. An incomplete override that omits `dist/tsconfig.tsbuildinfo` causes a sandbox violation in _every consumer_ that has a TypeScript project reference to this package: their `tsc --build` reads the referenced project's `.tsbuildinfo`, but `dependentTasksOutputFiles` can only collect it if this package declares it as an output.
+
+Verify the inferred outputs include the tsbuildinfo:
+
+```bash
+pnpm nx show project <name> --json | jq '.targets["build-base"].outputs'
+# Must include "{projectRoot}/dist/tsconfig.tsbuildinfo"
+```
+
+Update the existing `build` target's `outputs` if they reference `{workspaceRoot}/dist/packages/<name>` — they should now reference `{projectRoot}/dist/`.
+
+Also update `dependsOn` in the `build` target: replace `"^build"` with `"^build"` if it isn't already, and make sure `"build-base"` is listed.
+
+### 7. Update eslint config
+
+Add `dist` to the ignores. For flat config (`eslint.config.mjs`):
+
+```js
+{ ignores: ['**/__fixtures__/**', 'dist'] },
+```
+
+For legacy `.eslintrc.json`:
+
+```json
+"ignorePatterns": ["!**/*", "node_modules", "dist"]
+```
+
+Do **not** add `*.d.ts` or `**/*.d.ts` — the base config already ignores `**/dist`, and `tsconfig.lib.json` (Step 4) sends all generated `.d.ts` files into `dist`, so they're already out of scope. Hand-authored `.d.ts` files in `src/` (e.g. `schema.d.ts`) generally don't need ignoring.
+
+### 8. Update `assets.json` (if exists)
+
+Change `outDir` from `"dist/packages/<name>"` to `"packages/<name>/dist"`.
+
+### 9. Add `files` field to `package.json`
+
+Instead of using `.npmignore`, add a `"files"` field to `package.json` (matching the `nx` package pattern). Remove `.npmignore` if it exists.
+
+```json
+"files": [
+  "dist",
+  "!dist/tsconfig.tsbuildinfo",
+  "migrations.json"
+]
+```
+
+Adjust based on the package's needs:
+
+- Add `"executors.json"` and/or `"generators.json"` if the package has them
+- Add any other non-TS files that need to be published
+- npm always includes `package.json` and `README.md` automatically — no need to list them
+
+### 10. Rename README.md and update build command
+
+If the package has a `README.md` at its root and uses the `copy-readme.js` script in its build target:
+
+1. Rename `README.md` to `readme-template.md` (`git mv`)
+2. Update the build command to pass explicit paths:
+   ```
+   node ./scripts/copy-readme.js <name> packages/<name>/readme-template.md packages/<name>/README.md
+   ```
+3. Update the build target `outputs` to `["{projectRoot}/README.md"]`
+
+The script's default behavior reads `packages/<name>/README.md` and writes to `dist/packages/<name>/README.md` — both wrong for the new layout. Passing explicit args fixes both.
+
+### 11. Update root `.gitignore`
+
+Under the section that lists generated README files (look for `packages/nx/README.md`), add:
+
+```
+packages/<name>/README.md
+```
+
+The generated README is written next to source (not into `dist/`), so it needs its own ignore.
+
+Do **not** add a `packages/<name>/**/*.d.ts` rule. The root `.gitignore` already has a top-level `dist` entry that ignores every `dist/` directory in the repo — and `tsconfig.lib.json` (Step 4) sets `declarationDir: "dist"`, so all generated `.d.ts` files land there. Adding a package-wide `**/*.d.ts` rule plus `!` re-includes for hand-authored `.d.ts` files (like committed `schema.d.ts` source files) is redundant defense-in-depth.
+
+### 12. Update docs generation paths
+
+Check `astro-docs/src/plugins/utils/` for any code that references `.d.ts` files from the package. The docs generation reads `.d.ts` entry points to build API reference pages. Paths that previously pointed to `dist/packages/<name>/foo.d.ts` (workspace root dist) or `packages/<name>/foo.d.ts` (package root) now need to point to `packages/<name>/dist/foo.d.ts`.
+
+For example, `devkit-generation.ts` had to be updated to look for `packages/devkit/dist/index.d.ts` instead of `packages/devkit/index.d.ts`.
+
+### 13. Update `scripts/nx-release.ts`
+
+Two things to do here:
+
+1. **Add the package to `packagesToReset`.** That array (around `scripts/nx-release.ts:76`) is the snapshot/restore list — every package whose source `package.json` gets mutated by `nx release` (because it now publishes from `packages/<name>/` directly, not `dist/packages/<name>/`) must be in this list. Otherwise the release will leave `packages/<name>/package.json` dirty in the working tree after running. **Easy to forget — and there is no test that catches it.**
+
+2. **Update any package-specific paths.** If the package has special release handling (like devkit's `hackFixForDevkitPeerDependencies`), update any paths from `./dist/packages/<name>/` to `./packages/<name>/`.
+
+### 14. Update imports across the workspace
+
+Search for imports from `@nx/<name>/src/` across all other packages. These internal imports need to be updated:
+
+- If the imported thing is re-exported through a public entry point (index.ts, internal.ts, etc.), update the import to use that entry point
+- If not, consider adding it to `internal.ts` or the appropriate entry point
+
+Use: `grep -r "from '@nx/<name>/src/" packages/ --include="*.ts" -l` to find affected files.
+
+Also check for imports in:
+
+- `e2e/` tests
+- `scripts/`
+- `tools/workspace-plugin/`
+- `astro-docs/`
+- `examples/`
+
+### 14b. (Optional) Lock down `./src/*` and route internal consumers through `./internal`
+
+When you ship the migration, the package's `exports` map exposes everything under `./src/*` if you keep the wildcard. That's a 100s-of-symbols-wide semi-private surface that pins the implementation layout forever — consumers (first-party and external) can reach into any source file. The cleaner long-term shape, matching `@nx/devkit`/`@nx/workspace`, is to drop the wildcard and route internal consumers through a single curated `./internal` entry. Skip this step if you'd rather defer (e.g. the package has very heavy internal usage and you'd prefer a smaller PR), but plan a follow-up.
+
+#### When to lock down vs defer
+
+- **Lock down in the same PR** if internal subpath imports number in the low hundreds AND the package isn't `workspace:*`-pinned by other not-yet-migrated packages whose dist code would crash at runtime against the older published version (see "Published-version mismatch" below).
+- **Defer to a follow-up PR** if the inventory is huge OR if dist-output code in other workspace packages depends on the OLD `./src/*` paths and those packages can't be migrated to local-dist yet. Lock down only once the immediate runtime-resolution surface is contained.
+
+#### Step-by-step
+
+**1. Inventory the subpath imports.** Scan for `from '@nx/<name>/src/...'`, plus runtime `require()`, dynamic `import()`, and `jest`/`vi.mock`-family calls:
+
+```bash
+grep -rEln "from ['\"]@nx/<name>/src/" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.mjs" packages/ e2e/ scripts/
+grep -rEln "(require|jest\.mock|jest\.requireActual)\(['\"]@nx/<name>/src/" packages/ e2e/ scripts/
+```
+
+Compile a `subpath → set-of-imported-symbols` map. About 30 distinct subpaths and 60 symbols is typical for a package the size of `@nx/js`.
+
+**2. Identify runtime-string-resolved subpaths.** Some subpaths are referenced by _string default values_ the nx runtime resolves later (not static imports). The classic example: `packages/nx/src/command-line/release/config/config.ts` has `DEFAULT_VERSION_ACTIONS_PATH = '@nx/js/src/release/version-actions'`. These strings are also baked into pre-existing user `nx.json` files and you cannot rewrite them via a migration. **Keep those exact subpaths as explicit non-wildcard entries in the exports map** (not under `./internal`), and have the migration skip rewriting them.
+
+```bash
+# Search for string-default usages of the subpath in nx core
+grep -rEn "['\"]@nx/<name>/src/[^'\"]+['\"]" packages/nx/src/ --include="*.ts"
+```
+
+**3. Build `packages/<name>/internal.ts` at the package ROOT** (not inside `src/`, to mirror `@nx/devkit/internal`). Re-export every symbol callers reach for via `@nx/<name>/src/*`, BUT only symbols not already exported from `packages/<name>/src/index.ts`. Anything already public stays public — the migration sends those callers to `@nx/<name>`, not `@nx/<name>/internal`.
+
+To compute the public set:
+
+```bash
+grep -E "^export " packages/<name>/src/index.ts
+```
+
+…and recursively expand any `export *` lines. The "public-export reachability" calculation is fiddly enough that a small Python script with a recursive expand is worth it (see PR #35538 commit history for an example).
+
+Curate the new file:
+
+```ts
+// Semi-private surface for first-party Nx packages.
+//
+// External plugins should NOT import from here — this entry is curated for
+// internal consumers and may change without semver protection. Mirrors
+// `@nx/devkit/internal`.
+
+// Re-exports of nx-source internals (need `no-restricted-imports` overrides).
+// eslint-disable-next-line @typescript-eslint/no-restricted-imports
+export { ... } from 'nx/src/plugins/.../something';
+
+export { walkTsconfigExtendsChain, type RawTsconfigJsonCache } from './src/utils/typescript/raw-tsconfig';
+// ... and so on, grouping by area.
+```
+
+Delete any pre-existing `packages/<name>/src/internal.ts` once its exports have been folded in.
+
+**4. Update `packages/<name>/package.json`.** Drop wildcards, add `./internal`, keep runtime-string subpaths as explicit entries:
+
+```jsonc
+{
+  "exports": {
+    ".": {
+      "@nx/nx-source": "./src/index.ts",
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js",
+    },
+    "./package.json": "./package.json",
+    "./migrations.json": "./migrations.json",
+    "./generators.json": "./generators.json",
+    "./executors.json": "./executors.json",
+    // Public side-channels (whatever you already had).
+    "./babel": {
+      "@nx/nx-source": "./babel.ts",
+      "types": "./dist/babel.d.ts",
+      "default": "./dist/babel.js",
+    },
+    // The new curated entry.
+    "./internal": {
+      "@nx/nx-source": "./internal.ts",
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js",
+    },
+    // Runtime-string-resolved subpath kept for back-compat.
+    "./src/release/version-actions": {
+      "@nx/nx-source": "./src/release/version-actions.ts",
+      "types": "./dist/src/release/version-actions.d.ts",
+      "default": "./dist/src/release/version-actions.js",
+    },
+    // DROPPED: "./src/*", "./src/*.js", "./src/*/schema", "./src/*/schema.json"
+  },
+}
+```
+
+Also strip `src/*` glob entries from `typesVersions`. Replace with explicit non-wildcard entries that mirror the kept exports.
+
+**5. Codemod consumers in two passes.** Mechanical sed-style first, then a smarter split:
+
+```bash
+# Pass 1: every `from '@nx/<name>/src/...'` → `from '@nx/<name>/internal'`,
+# except the preserved subpaths from step 2.
+# (Use a Python/TS script — sed is fine for the simple cases too.)
+```
+
+```bash
+# Pass 2: split mixed imports. Any line like
+#   import { libraryGenerator, ensureTypescript } from '@nx/<name>/internal';
+# where `libraryGenerator` is publicly exported from `src/index.ts` becomes:
+#   import { libraryGenerator } from '@nx/<name>';
+#   import { ensureTypescript } from '@nx/<name>/internal';
+```
+
+Also handle these non-static cases:
+
+- `jest.mock('@nx/<name>/src/...', ...)` and `jest.requireActual(...)` — same rewrite. The whole mock surface is now `@nx/<name>/internal`, so `...jest.requireActual('@nx/<name>/internal')` spreads more than the original site mocked, but that's fine in practice.
+- Runtime `require('@nx/<name>/src/...')` — same rewrite.
+- Template-string fixtures inside `.spec.ts` files — careful! Don't let your codemod rewrite literal `from "@nx/<name>/internal"` substrings that _test_ the migration (it'll flip quote style and break the test). Either skip `*.spec.ts` files containing fixtures, or operate at AST level.
+
+**6. Collapse duplicate imports.** After the two-pass codemod, many files end up with two `import { ... } from '@nx/<name>/internal'` lines (or two `from '@nx/<name>'`). Run a third pass to merge same-source-same-`type`-prefix imports:
+
+```python
+# Match lines (anchored): `^import [type ]{ ... } from '@nx/<name>[/internal]';$`
+# Group by (is_type_only, source). For each group with >1 entry: keep the first
+# occurrence's position, merge the named bindings (dedupe), delete the others.
+# Don't merge across type/non-type — the semantics differ.
+```
+
+**7. Public-symbol audit.** After splitting, `internal.ts` must not re-export anything already exported from `src/index.ts`. If it does, namespace consumers (`import * as shared from '@nx/<name>/internal'`) will see only the curated set and `shared.publiclyExportedSymbol` becomes `undefined`. Cross-check:
+
+```bash
+# Symbols in internal.ts that are ALSO in the recursive index.ts export set
+# are a bug. Remove them from internal.ts. The codemod from step 5 should
+# have already routed their callers to `@nx/<name>`, but verify nothing is
+# left pointing at `@nx/<name>/internal` for these.
+```
+
+The three load-bearing patterns to verify:
+
+- `import * as shared from '@nx/<name>/internal'` followed by `shared.publicSymbol` — fix by changing source to `@nx/<name>`.
+- Runtime `const shared = require('@nx/<name>/internal')` followed by `shared.publicSymbol` — same fix.
+- Named imports of public symbols from `@nx/<name>/internal` — already split by step 5; verify nothing slipped through.
+
+**8. Ship a migration.** Add `packages/<name>/src/migrations/update-<version>/rewrite-<name>-internal-subpath-imports.ts` based on the workspace `move-typescript-compilation-import` template. It needs to handle:
+
+- Static `import [type] { ... } from '@nx/<name>/src/<anything>'`
+- `export [type] { ... } from '@nx/<name>/src/<anything>'`
+- Dynamic `import('@nx/<name>/src/<anything>')`
+- `require('@nx/<name>/src/<anything>')`
+- `jest.mock|unmock|doMock|dontMock|requireActual|requireMock|importActual|importMock(...)` and the `vi.` equivalents
+
+**Route by symbol, not blindly to `./internal`.** Some symbols reachable via `@nx/<name>/src/*` are _public_ — they're exported from `packages/<name>/src/index.ts` and ship on the main `@nx/<name>` entry. A migration that rewrites every `@nx/<name>/src/*` import to `@nx/<name>/internal` silently breaks any consumer importing a public symbol that way, because `internal.ts` deliberately does **not** re-export public symbols (step 7). Instead:
+
+- Hard-code the public symbol set (the recursively-expanded `export`s of `src/index.ts`) in the migration.
+- For a **named** `import`/`export` declaration, partition the named bindings: public symbols go to `@nx/<name>`, the rest to `@nx/<name>/internal`. Classify an `orig as alias` binding by `orig`. If both groups are non-empty, replace the single declaration with two — one per target — preserving any `import type` / `export type` modifier.
+- A **namespace** import (`import * as ns`), a **default** import, `export *`, every **call expression** (`require`, dynamic `import`, `jest.mock` family), and `typeof import('...')` **type queries** (`ImportTypeNode`) reference the module as a whole and can't be symbol-split — route them to `@nx/<name>/internal`.
+
+Skip the preserved subpaths from step 2 (e.g. `@nx/<name>/src/release/version-actions`). Use `ts.createSourceFile` for AST-based detection so you don't rewrite literals inside comments or template strings.
+
+**Don't forget `typeof import('...')`.** It parses as an `ImportTypeNode`, not a `CallExpression`, so it's a separate AST branch from the `require`/dynamic-`import` handling. Real-world consumers use the idiom `const m = require('@nx/<name>/src/x') as typeof import('@nx/<name>/src/x')` to get a typed runtime `require` — if the codemod only rewrites the runtime arg, the type arg stays pointing at the now-removed `./src/*` wildcard and the consumer fails to type-check. Handle it explicitly: walk `ImportTypeNode`s and rewrite `node.argument.literal` when the string starts with `@nx/<name>/src/`.
+
+Register in `packages/<name>/migrations.json` with `version: <current beta>`. The description should state the routing rule: named public-symbol imports/exports go to `@nx/<name>`, everything else to `@nx/<name>/internal`.
+
+Add a spec covering: public-symbol import (→ `@nx/<name>`), internal-symbol import (→ `@nx/<name>/internal`), mixed import split into two, aliased bindings classified by original name, type-only split, `export { ... } from` (public / internal / mixed), `export *`, namespace import, **default import**, single-quoted, double-quoted, deep subpath, `.js` extension, `require()`, dynamic `import()`, **`typeof import()` type queries (→ `/internal`)**, **a `<typeof import()>require()` cast in tandem** (catches the regression where the runtime arg gets rewritten but the type arg doesn't), the **full** jest mock family (`it.each` over `MOCK_HELPER_METHODS`), the **full** vi mock family, **`jest.mock('...', factory)` with a factory argument**, a non-mock `jest.*` call left alone, an import + `jest.mock` in the same file, preserved subpaths, non-`@nx/<name>` imports, unrelated string literals inside comments. Make sure every entry in `PUBLIC_SYMBOLS` and every entry in `MOCK_HELPER_METHODS` is exercised at least once — drift from hardcoded sets is the most likely silent regression.
+
+**9. Watch for the published-version-mismatch gotcha in example/test builds.**
+
+The workspace's root `node_modules/@nx/<name>` is the _published_ version (root `package.json` pins it to a real release tag, not `workspace:*`). When code at `dist/packages/<X>/...` does `require('@nx/<name>/internal')` at runtime, Node walks up from `dist/` and finds workspace-root `node_modules/@nx/<name>` — the published copy. If that version was released BEFORE this PR, it has no `internal.js` and resolution fails.
+
+Symptom:
+
+```
+Error: Cannot find module '@nx/<name>/internal'
+  requireStack: [
+    '/path/to/workspace/dist/packages/<X>/src/utils/foo.js',
+    ...
+  ]
+}
+```
+
+This bites specifically for examples or e2e flows that load `dist/packages/<other-package>/...` artifacts (e.g. an angular-rspack module-federation example that monkey-patches `Module._resolveFilename` to redirect `@nx/<other-package>` to dist). If the other-package's dist code does `require('@nx/<name>/internal')`, you'll hit this.
+
+Two fixes:
+
+- **(Preferred, if applicable.)** Migrate the _other_ package to local-dist too. Then its built code lives at `packages/<other>/dist/...`, walks up to `packages/<other>/node_modules/@nx/<name>` (a workspace symlink to source), and resolution finds the new `internal.js` because workspace source has it.
+- **(Band-aid for the in-between window.)** If migrating the other package is out of scope, extend the example's existing request-path patch to also redirect `@nx/<name>/internal` to the workspace source `packages/<name>/dist/internal`. Document it as a temporary measure tied to the same TODO that exists for the other-package redirect.
+
+Search aggressively for this pattern after step 8:
+
+```bash
+grep -rln "patchModuleFederationRequestPath\|Module._resolveFilename" examples/ e2e/ packages/
+```
+
+Any file that monkeypatches resolution is a candidate for needing the redirect.
+
+#### Validation
+
+After steps 1–9:
+
+```bash
+# Build the package (emits dist/internal.{js,d.ts})
+pnpm nx run <name>:build-base
+
+# Lint the package — @nx/dependency-checks may complain that the package
+# "uses itself" because of the dynamic self-reference in versions.ts. Add
+# `@nx/<name>` to `ignoredDependencies` in the dependency-checks rule config
+# (with a comment explaining: self-reference for require(join('@nx/<name>', 'package.json'))).
+pnpm nx run <name>:lint
+
+# Spec the migration
+pnpm nx test <name> -- --testPathPatterns=rewrite-<name>-internal-subpath-imports
+
+# Full affected — catches consumers, example monkey-patches, and any
+# missed split-mixed-imports.
+pnpm nx affected -t build,lint --base=<base-sha-before-migration>
+```
+
+If `nx affected` fails on a single example test with `Cannot find module '@nx/<name>/internal'`, that's step 9 — extend the example's request-path patch.
+
+If `nx affected` fails on a package with `TS2339: Property 'foo' does not exist on type 'typeof import(".../internal")'`, that's step 7 — a `shared.publicSymbol` call survived. Find it (`grep -rn 'shared\.<symbol>' packages/`) and rewrite the namespace source to `@nx/<name>`.
+
+### 15. Audit `require('../../package.json')` (or similar relative paths to the package.json)
+
+Search for `require\(['"]\.\..*package\.json` inside `packages/<name>/src/`. Any TS source file that reads the package's own `package.json` via a relative path is a **layout-fragility bug** that this migration triggers:
+
+- Before migration: source `packages/<name>/src/utils/versions.ts` → built `dist/packages/<name>/src/utils/versions.js`. `'../../package.json'` resolves to `dist/packages/<name>/package.json` (which the old build path copied there).
+- After migration: source unchanged → built `packages/<name>/dist/src/utils/versions.js`. `'../../package.json'` now resolves to `packages/<name>/dist/package.json` — **doesn't exist**. Every consumer that pulls in `nxVersion`/`NX_VERSION`/etc. crashes at module-load time with `Cannot find module '../../package.json'`. This breaks e2e tests broadly because most generators load `versions.ts`.
+
+**Fix**: replace the relative path with a **package-name self-reference**, using the dynamic `join()` form so eslint's `@nx/enforce-module-boundaries` doesn't trip on it:
+
+```ts
+// Before
+export const nxVersion = require('../../package.json').version;
+
+// After
+import { join } from 'path';
+export const nxVersion = require(join('@nx/<name>', 'package.json')).version;
+```
+
+A literal `require('@nx/<name>/package.json')` works at runtime but trips `enforce-module-boundaries`'s `noSelfCircularDependencies` check — the rule statically pattern-matches self-imports and fires before checking whether the import resolves to a non-main entry. The dynamic `join()` form is opaque to the static check, matches `@nx/devkit`'s established pattern, and resolves to the same path at runtime.
+
+Node resolves `@nx/<name>/package.json` via `node_modules` (workspace symlink in dev, real install in published), and the package.json's `exports` map already declares `./package.json` (you ensured this in Step 5). Works identically in source and dist contexts.
+
+Reference implementations:
+
+- `packages/nx/src/utils/versions.ts` — `require('nx/package.json').version` (works because `nx` is the project's own name; the static rule's entry-point check is lenient for the top-level `nx` package specifically)
+- `packages/devkit/src/utils/package-json.ts` — `NX_VERSION = require(join('nx', 'package.json')).version` (dynamic form)
+
+This was the source of the workspace-migration e2e regressions (PR #35643) and is one of the most-failure-prone steps to forget. Audit aggressively.
+
+### 15b. Audit `ensurePackage` + `await import(...)` pairs
+
+Search for `ensurePackage\(['"]@nx/` inside `packages/<name>/src/`. For every match, look at the next 5–20 lines for a `await import('@nx/<other>/...')` pulling from the same package. This pattern is **broken** under `nodenext`:
+
+- Before migration: `module: commonjs` made TypeScript downlevel `await import('@nx/<other>')` to `Promise.resolve(require('@nx/<other>'))`. The synchronous `require()` honors `Module._initPaths`, which is exactly where `ensurePackage` registers the on-demand temp install. Resolution succeeds.
+- After migration: `module: nodenext` preserves `import()` as a true ESM dynamic import. ESM resolution **ignores** `Module._initPaths` — it walks up `node_modules` from the importing file's location only. The temp install lives in a different temp dir, so the import fails with `Cannot find package '@nx/<other>'`.
+
+**Fix**: replace the dynamic import with a synchronous `require()`. The `ensurePackage` side effect makes it findable via `_initPaths`, and `require()` honors that:
+
+```ts
+// Before
+ensurePackage('@nx/eslint', nxVersion);
+const { foo, bar } = await import('@nx/eslint/internal');
+
+// After
+ensurePackage('@nx/eslint', nxVersion);
+// `require()` honors Module._initPaths (which ensurePackage updates); ESM
+// dynamic `import()` doesn't, so it can't see the temp install.
+const {
+  foo,
+  bar,
+}: typeof import('@nx/eslint/internal') = require('@nx/eslint/internal');
+```
+
+Collapse multiple successive `await import()`s of the same module into one `require()` destructuring while you're at it.
+
+This was the source of the M2 e2e regressions (Playwright/Web/React generators crashed at `Cannot find package '@nx/eslint'` from `ignore-vite-temp-files.js` and `ignore-vitest-temp-files.js`). One-line failure mode, but it can sit hidden in any code path that the unit-test suite doesn't exercise — only the published-then-installed flow exposes it. Audit every `ensurePackage` callsite.
+
+### 16. Preserve `add-extra-dependencies` if the package has one
+
+`scripts/add-dependency-to-build.js` is a release-time hack that injects an extra dep into the **published** `package.json` (e.g., it adds `nx` to `@nx/workspace`'s `dependencies`). It is **not dead code** — without it the transitive resolution chain breaks for downstream consumers.
+
+Concretely: created workspaces depend on `@nx/js`, which transitively depends on `@nx/workspace`. When the fork in `generate-preset.ts` runs `nx g @nx/workspace:preset`, Node's `require.resolve('@nx/workspace/package.json')` only finds the transitively-installed package because pnpm hoists `nx` along with `@nx/workspace` into `.pnpm/node_modules/` — and `nx` is hoisted there only because the **published** `@nx/workspace/package.json` declares it as a regular dependency. Drop that injection and the fork in the new workspace fails with `Unable to resolve @nx/workspace:preset` → `unable to find tsconfig.base.json`.
+
+When migrating a package that has the `add-extra-dependencies` target:
+
+1. **Keep** the target in `packages/<name>/project.json`.
+2. **Update** `scripts/add-dependency-to-build.js`: change the `pkgPath` from `../dist/packages/<package>/package.json` to `../packages/<package>/package.json` (the source manifest is now the published manifest under the local-dist layout).
+3. **Keep** the `pnpm nx run-many -t add-extra-dependencies --parallel 8` invocations in `scripts/nx-release.ts` (both the GitHub-release path and the local-publish path) — they fire between `runNxReleaseVersion` and `nx run nx:expand-deps`.
+4. Confirm the snapshot/reset list (`packagesToReset`) covers this package so the injection is undone after publish.
+
+If the package does not have the target, leave the script and the run-many calls alone — they no-op for any project without the target.
+
+### 17. Verify
+
+Run:
+
+```bash
+pnpm nx run-many -t test,build,lint -p <name>
+```
+
+Then:
+
+```bash
+pnpm nx affected -t build,test,lint
+```
+
+### Summary of the pattern
+
+The core idea is simple: instead of building to a shared `dist/packages/<name>/` at the workspace root, each package builds to its own `packages/<name>/dist/`. The `exports` map with `@nx/nx-source` condition lets workspace packages resolve to `.ts` source files during development, while external consumers get the built `.js` from `dist/`. This is like giving each package its own "output mailbox" instead of sharing one big mailbox.

.claude/skills/multi-version-compliance/references/anti-patterns.md

@@ -10,12 +10,26 @@ Patterns to reject in your own work and flag in reviews. Each entry: what it loo
 - `function cleanVersion(v) { return clean(v) ?? coerce(v)?.version ?? undefined; }` — duplicates `normalizeSemver`.
 - `getInstalledRsbuildVersionRuntime` / `getInstalled<X>FromFs` reading `require('<pkg>/package.json')` directly — duplicates `getInstalledPackageVersion`.
 - Inline `clean(declared) ?? coerce(declared)` chain at a generator entry point — duplicates `getDeclaredPackageVersion`.
+- Open-coded tree-branch in `getInstalled<Pkg>Version(tree?)`: `getDependencyVersionFromPackageJson(tree, pkg)` + an `installedVersion === 'latest' || installedVersion === 'next'` check + a `clean(...) ?? coerce(...)?.version ?? null` chain. The dist-tag list and the normalization chain are both centralized in `getDeclaredPackageVersion` (via `NON_SEMVER_DIST_TAGS` / `normalizeSemver`). A local copy silently misses new entries if `NON_SEMVER_DIST_TAGS` grows.
 
 **Why wrong:** The shared helpers in `@nx/devkit/internal` and `@nx/devkit/internal-testing-utils` already exist. Duplicates create drift — one will get the `latest`/`next` handling, the other won't; one will use `getNxRequirePaths()` for pnpm-strict resolution, the other won't.
 
 **Do instead:** Call `assertSupportedPackageVersion(tree, pkg, floor)` via the per-plugin wrapper (`assertSupportedXVersion`). For executor-side reads: `getInstalledPackageVersion(pkg)`. For tree-side normalization: `getDeclaredPackageVersion(tree, pkg, latestKnown)`. For raw semver cleaning: `normalizeSemver(v)`.
 
-**Reference:** Compliant — `packages/cypress/src/utils/assert-supported-cypress-version.ts` (7 lines). Concrete anti-pattern — PR `#35676` introduces `function cleanVersion` (`packages/rsbuild/src/utils/versions.ts`) and `getInstalledRsbuildVersionRuntime` reading `require('@rsbuild/core/package.json')`. Both should call the shared helpers instead.
+For the `getInstalled<Pkg>Version(tree?)` wrapper specifically:
+
+```ts
+export function getInstalledCypressVersion(tree?: Tree): string | null {
+  if (!tree) {
+    return getInstalledPackageVersion('cypress');
+  }
+  return getDeclaredPackageVersion(tree, 'cypress');
+}
+```
+
+**Omit the third arg by default.** It conflates "missing" with "dist tag" — both fall back to the supplied fresh-install constant. That's almost never what the caller wants; consumers that need a `?? latest` fallback should encode it at the call site, not globally in the helper (rspack/rsbuild precedent). See `canonical-shape.md` §"Dist-tag semantics — third arg".
+
+**Reference:** Compliant — `packages/cypress/src/utils/assert-supported-cypress-version.ts` (7 lines); `packages/cypress/src/utils/versions.ts` `getInstalledCypressVersion` (no third arg); `packages/rspack/src/utils/version-utils.ts` and `packages/rsbuild/src/utils/version-utils.ts` (same shape). Concrete anti-pattern — PR `#35676` introduces `function cleanVersion` (`packages/rsbuild/src/utils/versions.ts`) and `getInstalledRsbuildVersionRuntime` reading `require('@rsbuild/core/package.json')`. Both should call the shared helpers instead.
 
 ## 2. Above-ceiling throw or warn
 

.claude/skills/multi-version-compliance/references/canonical-shape.md

@@ -227,22 +227,23 @@ export function versions(tree: Tree): VitestVersions {
 
 ### The `getInstalled<Pkg>Version(tree?)` helper
 
-Optional `tree` parameter — with tree, reads declared from `package.json` (normalizing `latest`/`next` to the fresh-install constant); without tree, routes through the shared `getInstalledPackageVersion` from `@nx/devkit/internal` (FS resolution via `getNxRequirePaths()`).
+Optional `tree` parameter — with tree, reads declared from `package.json` via `getDeclaredPackageVersion` (handles dist-tag normalization, semver cleaning); without tree, routes through `getInstalledPackageVersion` from `@nx/devkit/internal` (FS resolution via `getNxRequirePaths()`).
+
+**Do not open-code the tree-branch.** `getDeclaredPackageVersion` already centralizes the dist-tag list (`isNonSemverDistTag`) and the `clean(v) ?? coerce(v)?.version ?? null` chain (`normalizeSemver`). Local re-implementations drift when devkit's constants change. See `anti-patterns.md` §1.
 
 ```ts
+import { type Tree } from '@nx/devkit';
+import {
+  getDeclaredPackageVersion,
+  getInstalledPackageVersion,
+} from '@nx/devkit/internal';
+import { major } from 'semver';
+
 export function getInstalledVitestVersion(tree?: Tree): string | null {
   if (!tree) {
     return getInstalledPackageVersion('vitest');
   }
-
-  const installedVersion = getDependencyVersionFromPackageJson(tree, 'vitest');
-  if (!installedVersion) {
-    return null;
-  }
-  if (installedVersion === 'latest' || installedVersion === 'next') {
-    return clean(vitestVersion) ?? coerce(vitestVersion)?.version ?? null;
-  }
-  return clean(installedVersion) ?? coerce(installedVersion)?.version ?? null;
+  return getDeclaredPackageVersion(tree, 'vitest');
 }
 
 export function getInstalledVitestMajorVersion(tree?: Tree): number | null {
@@ -251,7 +252,15 @@ export function getInstalledVitestMajorVersion(tree?: Tree): number | null {
 }
 ```
 
-This is the cypress/playwright/vitest pattern. Reference: `packages/cypress/src/utils/versions.ts`.
+Reference: `packages/cypress/src/utils/versions.ts`, `packages/rspack/src/utils/version-utils.ts`, `packages/rsbuild/src/utils/version-utils.ts`.
+
+#### Dist-tag semantics — third arg (`latestKnownVersion`)
+
+`getDeclaredPackageVersion(tree, pkg, latestKnownVersion?)`'s third arg falls back to `normalizeSemver(latestKnownVersion)` whenever the declared range can't be normalized to semver — both "package missing from `package.json`" AND "package declared as a dist tag (`latest` / `next`)". The helper does not distinguish the two cases.
+
+**Default to omitting the third arg.** The wrapper returns `null` for both "missing" and "dist tag"; consumers that want `?? latestVersions` semantics should encode it at the call site (rspack/rsbuild precedent), not globally in the helper. Passing the third arg makes the helper claim the package is "installed at the fresh-install constant" even when nothing is declared — which silently disables init generators' "add the package" branches.
+
+When a consumer specifically needs to distinguish "missing" from "dist tag", use `getDependencyVersionFromPackageJson` from `@nx/devkit` to inspect the raw declared string.
 
 ## Generator entry points
 

.claude/skills/run-nx-generator/SKILL.md

@@ -67,15 +67,6 @@ nx generate @nx/workspace-plugin:bump-maven-version \
 
 This automates all the version bumping instead of manual file edits.
 
-### Creating a New Plugin
-
-For creating a new create-nodes plugin:
-
-```bash
-nx generate @nx/workspace-plugin:create-nodes-plugin \
-  --name my-custom-plugin
-```
-
 ## When to Use This Skill
 
 Use this skill when you need to:

.github/workflows/e2e-matrix.yml

@@ -34,19 +34,14 @@ jobs:
           # - windows-latest Windows fails to build gradle wrapper which always runs when we build nx.
           ## https://staging.nx.app/runs/LgD4vxGn8w?utm_source=pull-request&utm_medium=comment
         node_version:
-          # TODO(v23): remove node 20 - EOL April 2026
-          - 20
           - 22
           - 24
+          - 26
         exclude:
-          # run just node v24 on macos and windows
-          - os: macos-latest
-            node_version: 20
+          # macos skips the oldest node to keep the macos matrix slim
           - os: macos-latest
             node_version: 22
           # - os: windows-latest TODO(Jack): Windows fails to build gradle wrapper which always runs when we build nx. Re-enable when we fix this.
-          #   node_version: 20
-          # - os: windows-latest TODO (Jack): Windows fails to build gradle wrapper which always runs when we build nx. Re-enable when we fix this.
           #   node_version: 22
 
     name: Cache install (${{ matrix.os }}, node v${{ matrix.node_version }})

.github/workflows/nightly/analyze-failures.ts

@@ -16,23 +16,6 @@ interface MatrixResult {
   duration: number;
 }
 
-interface Streak {
-  consecutive_failures: number;
-  failing_since: string | null;
-  last_passing: string | null;
-}
-
-interface HistoryEntry {
-  date: string;
-  failed: string[];
-}
-
-interface ErrorDate {
-  testFile: string;
-  startDate: string;
-  days: number;
-}
-
 const REPO = process.env.GITHUB_REPOSITORY || 'nrwl/nx';
 const RUN_ID = process.env.GITHUB_RUN_ID || '0';
 
@@ -186,53 +169,7 @@ export async function collectFailureDetails(
     }
   }
 
-  // Step 1: 30-day failure history
-  const histRunsRaw = gh(
-    `run list --workflow=e2e-matrix.yml --repo ${REPO} --limit 40 --json databaseId,createdAt,event --jq '[.[] | select(.event == "schedule" and .databaseId != ${RUN_ID})] | .[0:30]'`
-  );
-  const histRuns: Array<{ databaseId: number; createdAt: string }> =
-    histRunsRaw ? JSON.parse(histRunsRaw) : [];
-
-  const histResults = await ghParallel(
-    histRuns.map((r) => r.databaseId),
-    (rid) =>
-      `run view ${rid} --repo ${REPO} --json jobs --jq '[.jobs[] | select(.conclusion == "failure") | .name | split(" ") | last] | unique'`
-  );
-
-  const history: HistoryEntry[] = histRuns.map((run) => {
-    const raw = histResults.get(run.databaseId) || '[]';
-    try {
-      return { date: run.createdAt, failed: JSON.parse(raw) };
-    } catch {
-      return { date: run.createdAt, failed: [] };
-    }
-  });
-
-  // Compute streaks
-  const streaks = new Map<string, Streak>();
-  for (const project of projectNames) {
-    let streak = 0,
-      firstSeen: string | null = null,
-      lastPassing: string | null = null,
-      broken = false;
-    for (const entry of history) {
-      if (broken) break;
-      if (entry.failed.includes(project)) {
-        streak++;
-        firstSeen = entry.date;
-      } else {
-        broken = true;
-        lastPassing = entry.date;
-      }
-    }
-    streaks.set(project, {
-      consecutive_failures: streak,
-      failing_since: firstSeen ? firstSeen.split('T')[0] : null,
-      last_passing: lastPassing ? lastPassing.split('T')[0] : null,
-    });
-  }
-
-  // Step 2: Fetch failure logs (one per OS/PM combo per project)
+  // Step 1: Fetch failure logs (one per OS/PM combo per project)
   const failedJobsRaw = gh(
     `run view ${RUN_ID} --repo ${REPO} --json jobs --jq '[.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name: .name, project: (.name | split(" ") | last), combo: (.name | split(" ")[0])}]'`
   );
@@ -296,7 +233,7 @@ export async function collectFailureDetails(
     );
   }
 
-  // Step 3: Build distinct failures per project — each (testFile, signature, combos) is a "failure"
+  // Step 2: Build distinct failures per project — each (testFile, signature, combos) is a "failure"
   interface DistinctFailure {
     testFile: string;
     signature: string;
@@ -328,183 +265,16 @@ export async function collectFailureDetails(
     projectDistinctFailures.set(project, [...seen.values()]);
   }
 
-  // Step 3b: Validate each distinct failure against the first-failing run
-  interface FailureValidation {
-    status: 'new' | 'confirmed' | 'different' | 'unknown';
-    startDate?: string;
-    days?: number;
-  }
-
-  // Key: "project|testFile|signature"
-  const failureValidations = new Map<string, FailureValidation>();
-
-  for (const project of projectNames) {
-    const streak = streaks.get(project)!;
-    const failures = projectDistinctFailures.get(project) || [];
-
-    if (streak.consecutive_failures <= 1 || !streak.failing_since) {
-      for (const f of failures) {
-        failureValidations.set(`${project}|${f.testFile}|${f.signature}`, {
-          status: 'new',
-          startDate: streak.failing_since || undefined,
-          days: streak.consecutive_failures || 1,
-        });
-      }
-      continue;
-    }
-
-    // Fetch first-failing run's signatures across all combos
-    const firstRun = histRuns.find(
-      (r) => r.createdAt.split('T')[0] === streak.failing_since
-    );
-    if (!firstRun) {
-      for (const f of failures) {
-        failureValidations.set(`${project}|${f.testFile}|${f.signature}`, {
-          status: 'unknown',
-        });
-      }
-      continue;
-    }
-
-    const firstJobIdsRaw = gh(
-      `run view ${firstRun.databaseId} --repo ${REPO} --json jobs --jq '[.jobs[] | select(.conclusion == "failure" and (.name | split(" ") | last) == "${project}")] | group_by(.name | split("/")[0:2] | join("/")) | map(.[0].databaseId) | .[]'`
-    );
-    const firstJobIds = firstJobIdsRaw
-      .split('\n')
-      .filter((id) => id && id !== 'null');
-
-    // Collect ALL signatures from the first run
-    const firstRunSigs = new Set<string>(); // "testFile|signature"
-    for (const jobId of firstJobIds) {
-      const log = gh(`api repos/${REPO}/actions/jobs/${jobId}/logs`);
-      if (!log) continue;
-      const cleanedLog = log
-        .replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z /gm, '')
-        .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
-      const files = extractTestFiles(cleanedLog);
-      for (const f of files) {
-        const sig = extractErrorSignature(cleanedLog, f);
-        firstRunSigs.add(`${f}|${sig}`);
-      }
-    }
-
-    // Validate each current failure
-    for (const f of failures) {
-      const key = `${f.testFile}|${f.signature}`;
-      const fullKey = `${project}|${key}`;
-      if (firstRunSigs.has(key)) {
-        failureValidations.set(fullKey, {
-          status: 'confirmed',
-          startDate: streak.failing_since!,
-          days: streak.consecutive_failures,
-        });
-      } else {
-        failureValidations.set(fullKey, {
-          status: 'different',
-        });
-      }
-    }
-  }
-
-  // Step 4: Binary search for start date of each "different" failure
-  for (const project of projectNames) {
-    const streak = streaks.get(project)!;
-    const failures = projectDistinctFailures.get(project) || [];
-    const different = failures.filter((f) => {
-      const v = failureValidations.get(
-        `${project}|${f.testFile}|${f.signature}`
-      );
-      return v?.status === 'different';
-    });
-    if (!different.length) continue;
-
-    const projRunIds = histRuns
-      .slice(0, streak.consecutive_failures)
-      .map((r) => r.databaseId);
-    if (projRunIds.length <= 1) continue;
-
-    for (const failure of different) {
-      const targetSig = failure.signature;
-      if (!targetSig) continue;
-
-      function runHasSignature(runId: number): boolean {
-        const jobIdsRaw = gh(
-          `run view ${runId} --repo ${REPO} --json jobs --jq '[.jobs[] | select(.conclusion == "failure" and (.name | split(" ") | last) == "${project}")] | group_by(.name | split("/")[0:2] | join("/")) | map(.[0].databaseId) | .[]'`
-        );
-        for (const jid of jobIdsRaw.split('\n').filter(Boolean)) {
-          const log = gh(`api repos/${REPO}/actions/jobs/${jid}/logs`);
-          if (!log) continue;
-          const cleaned = log
-            .replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z /gm, '')
-            .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
-          const sig = extractErrorSignature(cleaned, failure.testFile);
-          if (sig === targetSig) return true;
-        }
-        return false;
-      }
-
-      let low = 0,
-        high = projRunIds.length - 1;
-
-      // Check oldest run
-      const fullKey = `${project}|${failure.testFile}|${failure.signature}`;
-
-      const oldestHas = runHasSignature(projRunIds[high]);
-      if (oldestHas) {
-        const run = histRuns.find((r) => r.databaseId === projRunIds[high]);
-        failureValidations.set(fullKey, {
-          status: 'different',
-          startDate: run?.createdAt.split('T')[0] || 'unknown',
-          days: projRunIds.length,
-        });
-        continue;
-      }
-
-      // Binary search
-      while (high - low > 1) {
-        const mid = Math.floor((low + high) / 2);
-        if (runHasSignature(projRunIds[mid])) low = mid;
-        else high = mid;
-      }
-
-      const foundRun = histRuns.find((r) => r.databaseId === projRunIds[low]);
-      failureValidations.set(fullKey, {
-        status: 'different',
-        startDate: foundRun?.createdAt.split('T')[0] || 'unknown',
-        days: low + 1,
-      });
-    }
-  }
-
-  // Step 5: Recent commits
-  let commitCount = 0;
-  if (histRuns[0]?.createdAt) {
-    try {
-      const commits = execSync(
-        `git log origin/master --after="${histRuns[0].createdAt}" --format="%h" --no-merges 2>/dev/null | head -30`,
-        { encoding: 'utf-8', timeout: 10_000 }
-      ).trim();
-      commitCount = commits ? commits.split('\n').length : 0;
-    } catch {
-      /* git not available */
-    }
-  }
-
-  // Step 6: Format report
+  // Step 3: Format report
   const lines: string[] = ['', '🔍 *Failure Details*', ''];
 
-  const sorted = [...projectNames].sort((a, b) => {
-    const sa = streaks.get(a)?.consecutive_failures || 0;
-    const sb = streaks.get(b)?.consecutive_failures || 0;
-    return (
-      sa - sb ||
+  const sorted = [...projectNames].sort(
+    (a, b) =>
       (failuresByProject.get(b)?.length || 0) -
-        (failuresByProject.get(a)?.length || 0)
-    );
-  });
+        (failuresByProject.get(a)?.length || 0) || a.localeCompare(b)
+  );
 
   for (const project of sorted) {
-    const streak = streaks.get(project)!;
     const projResults = failuresByProject.get(project) || [];
     const distinctFailures = projectDistinctFailures.get(project) || [];
     const block = projectLogs.get(project) || '';
@@ -517,8 +287,6 @@ export async function collectFailureDetails(
           ? 'all PMs'
           : pms.join('+');
 
-    const since = streak.failing_since || 'today (new)';
-    const lastPass = streak.last_passing || '—';
     const uniqueCombos = [
       ...new Set(
         failedJobs.filter((j) => j.project === project).map((j) => j.combo)
@@ -527,35 +295,12 @@ export async function collectFailureDetails(
 
     lines.push('———————————————————————————');
     lines.push(`*${project}* — ${projResults.length} combos (${pattern})`);
-    lines.push(
-      `Project failing since ${since} | Last fully passing: ${lastPass}`
-    );
     lines.push('');
 
     if (distinctFailures.length > 0) {
       for (const failure of distinctFailures) {
-        const fullKey = `${project}|${failure.testFile}|${failure.signature}`;
-        const val = failureValidations.get(fullKey);
-
-        let errorDate = since;
-        let errorDays: number | string = streak.consecutive_failures || 1;
-        let label = '';
-
-        if (val?.startDate) {
-          errorDate = val.startDate;
-          errorDays = val.days || 1;
-        }
-        if (val?.status === 'different') {
-          label = ' ⚠️ error changed mid-streak';
-        }
-        if (errorDays === 1 || errorDays === '1') {
-          label = ' 🆕 NEW';
-        }
-
         const comboStr = failure.combos.join(', ');
-        lines.push(
-          `📋 \`${failure.testFile}\` (${comboStr}) — failing since ${errorDate} (${errorDays} ${errorDays === 1 || errorDays === '1' ? 'day' : 'days'})${label}`
-        );
+        lines.push(`📋 \`${failure.testFile}\` (${comboStr})`);
 
         if (failure.block) {
           lines.push('```');
@@ -652,10 +397,6 @@ export async function collectFailureDetails(
     lines.push('');
   }
 
-  if (commitCount > 0) {
-    lines.push(`_${commitCount} commits since last nightly_`);
-  }
-
   // Build job links for the summary section
   const runUrl = `https://github.com/${REPO}/actions/runs/${RUN_ID}`;
   const goldenJobLinks = new Map<string, JobLink[]>();

.github/workflows/nightly/process-matrix.ts

@@ -16,7 +16,7 @@ type MatrixDataOS = {
 type MatrixData = {
   coreProjects: MatrixDataProject[],
   projects: MatrixDataProject[],
-  nodeTLS: number,
+  lowestNodeLTS: number,
   setup: MatrixDataOS[],
 }
 
@@ -67,20 +67,25 @@ const matrixData: MatrixData = {
     { name: 'e2e-storybook', codeowners: 'S04SVQ8H0G5' },
     { name: 'e2e-nuxt', codeowners: 'S04SJ6PL98X' }
   ],
-  // TODO(v23): remove node 20 - EOL April 2026
-  nodeTLS: 20,
+  // Non-core plugins only run on the lowest LTS. Plugin-level changes are
+  // less Node-version-sensitive than core, so single-version coverage is enough.
+  lowestNodeLTS: 22,
   setup: [
     {
       os: 'ubuntu-latest',
       os_name: 'Linux',
       os_timeout: 60,
       package_managers: ['npm', 'pnpm', 'yarn'],
-      node_versions: ['20.19.0', '22.13.0', '24.0.0'],
+      // TODO: re-add '26.0.0' once playwright ships the yauzl fix for node 26 extract hang.
+      // See https://github.com/microsoft/playwright/issues/40724
+      node_versions: ['22.13.0', '24.0.0'],
       excluded: ['e2e-detox', 'e2e-react-native', 'e2e-expo']
     },
     // Docker is not supported on ARM-based macOS runners (no nested virtualization)
     // See: https://github.com/docker/setup-docker-action and https://github.com/douglascamata/setup-docker-macos-action
     // We may want to look into adding intel only for this docker case, at least until vm-in-vm works on latest macos
+    // TODO: re-add '26.0.0' once playwright ships the yauzl fix for node 26 extract hang.
+    // See https://github.com/microsoft/playwright/issues/40724
     { os: 'macos-latest', os_name: 'MacOS', os_timeout: 90, package_managers: ['npm'], node_versions: ['24.0.0'], excluded: ['e2e-docker'] }
     // TODO (Jack): Fix Windows support as gradle fails when running nx build https://staging.nx.app/runs/LgD4vxGn8w?utm_source=pull-request&utm_medium=comment
     // { os: 'windows-latest', os_name: 'WinOS', os_timeout: 180, package_managers: ['npm'], node_versions: ['24.0.0'], excluded: ['e2e-detox', 'e2e-react-native', 'e2e-expo'] }
@@ -124,7 +129,7 @@ for (let p = 0; p < matrixData.coreProjects.length; p++) {
 }
 // process other projects
 for (let p = 0; p < matrixData.projects.length; p++) {
-  processProject(matrixData.projects[p], matrixData.nodeTLS);
+  processProject(matrixData.projects[p], matrixData.lowestNodeLTS);
 }
 
 if (matrix.length > 256) {

.github/workflows/publish.yml

@@ -21,7 +21,7 @@ env:
   DEBUG: napi:*
   NX_RUN_GROUP: ${{ github.run_id }}-${{ github.run_attempt }}
   CYPRESS_INSTALL_BINARY: 0
-  NODE_VERSION: 22.16.0
+  NODE_VERSION: 26.3.0
   PNPM_VERSION: 11.2.2 # Aligned with root package.json (pnpm/action-setup will helpfully error if out of sync)
   NX_GRADLE_PROJECT_GRAPH_TIMEOUT: 600
 
@@ -190,9 +190,9 @@ jobs:
                 dotnet --version
 
                 # Node.js musl build from unofficial-builds.nodejs.org
-                curl -fsSL https://unofficial-builds.nodejs.org/download/release/v22.16.0/node-v22.16.0-linux-x64-musl.tar.xz -o node.tar.xz
+                curl -fsSL https://unofficial-builds.nodejs.org/download/release/v\${NODE_VERSION}/node-v\${NODE_VERSION}-linux-x64-musl.tar.xz -o node.tar.xz
                 tar -xJf node.tar.xz
-                mv node-v22.16.0-linux-x64-musl /usr/local/node
+                mv node-v\${NODE_VERSION}-linux-x64-musl /usr/local/node
                 export PATH=\"/usr/local/node/bin:\$PATH\"
                 node --version
 
@@ -290,9 +290,9 @@ jobs:
                 # Node.js musl build from unofficial-builds.nodejs.org. Container is x64;
                 # rust cross-compiles to aarch64-unknown-linux-musl, so the host node binary
                 # is x64-musl regardless of the build target.
-                curl -fsSL https://unofficial-builds.nodejs.org/download/release/v22.16.0/node-v22.16.0-linux-x64-musl.tar.xz -o node.tar.xz
+                curl -fsSL https://unofficial-builds.nodejs.org/download/release/v\${NODE_VERSION}/node-v\${NODE_VERSION}-linux-x64-musl.tar.xz -o node.tar.xz
                 tar -xJf node.tar.xz
-                mv node-v22.16.0-linux-x64-musl /usr/local/node
+                mv node-v\${NODE_VERSION}-linux-x64-musl /usr/local/node
                 export PATH=\"/usr/local/node/bin:\$PATH\"
                 node --version
 
@@ -321,7 +321,7 @@ jobs:
               export PATH="$JAVA_HOME\bin:$PATH"
               java -version
               pnpm nx run-many --target=build-native -- --target=aarch64-pc-windows-msvc
-    name: stable - ${{ matrix.settings.target }} - node@22.16.0
+    name: stable - ${{ matrix.settings.target }} - node@26.3.0
     runs-on: ${{ matrix.settings.host }}
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
@@ -433,9 +433,8 @@ jobs:
         env:
           DEBUG: napi:*
           RUSTUP_IO_THREADS: 1
-          NX_PREFER_TS_NODE: true
           PLAYWRIGHT_BROWSERS_PATH: 0
-          NODE_VERSION: 22.16.0
+          NODE_VERSION: 26.3.0
           NX_GRADLE_DISABLE: 'true'
           NX_DOTNET_DISABLE: 'true'
           NODE_OPTIONS: '--max-old-space-size=4096'
@@ -443,7 +442,7 @@ jobs:
           operating_system: freebsd
           version: '14.0'
           architecture: x86-64
-          environment_variables: DEBUG RUSTUP_IO_THREADS CI NX_PREFER_TS_NODE PLAYWRIGHT_BROWSERS_PATH NODE_VERSION NX_GRADLE_DISABLE NX_DOTNET_DISABLE NODE_OPTIONS
+          environment_variables: DEBUG RUSTUP_IO_THREADS CI PLAYWRIGHT_BROWSERS_PATH NODE_VERSION NX_GRADLE_DISABLE NX_DOTNET_DISABLE NODE_OPTIONS
           shell: bash
           run: |
             env
@@ -620,7 +619,8 @@ jobs:
           pnpm build:wasm
       - name: Publish
         env:
-          VERSION: ${{ needs.resolve-required-data.outputs.version }}
+          # Not named `VERSION` to avoid MSBuild adopting it as $(Version).
+          NX_PUBLISH_VERSION: ${{ needs.resolve-required-data.outputs.version }}
           DRY_RUN: ${{ needs.resolve-required-data.outputs.dry_run_flag }}
           PUBLISH_BRANCH: ${{ needs.resolve-required-data.outputs.publish_branch }}
         run: |
@@ -628,10 +628,10 @@ jobs:
           # Create and check out the publish branch
           git checkout -b $PUBLISH_BRANCH
           echo ""
-          echo "Version set to: $VERSION"
+          echo "Version set to: $NX_PUBLISH_VERSION"
           echo "DRY_RUN set to: $DRY_RUN"
           echo ""
-          pnpm nx-release --local=false $VERSION $DRY_RUN
+          pnpm nx-release --local=false $NX_PUBLISH_VERSION $DRY_RUN
 
       - name: (Stable Release Only) Trigger Docs Release
         # Publish docs only on a full release

.gitignore

@@ -134,6 +134,41 @@ packages/angular-rspack-compiler/README.md
 packages/dotnet/README.md
 packages/maven/README.md
 packages/nx/README.md
+packages/devkit/README.md
+packages/workspace/README.md
+packages/js/README.md
+packages/jest/README.md
+packages/eslint/README.md
+packages/eslint-plugin/README.md
+packages/vitest/README.md
+packages/cypress/README.md
+packages/playwright/README.md
+packages/vite/README.md
+packages/webpack/README.md
+packages/rollup/README.md
+packages/docker/README.md
+packages/gradle/README.md
+packages/rsbuild/README.md
+packages/web/README.md
+packages/node/README.md
+packages/module-federation/README.md
+packages/nest/README.md
+packages/rspack/README.md
+packages/storybook/README.md
+packages/react/README.md
+packages/vue/README.md
+packages/esbuild/README.md
+packages/angular/README.md
+packages/express/README.md
+packages/plugin/README.md
+packages/react-native/README.md
+packages/next/README.md
+packages/remix/README.md
+packages/detox/README.md
+packages/expo/README.md
+packages/nuxt/README.md
+packages/create-nx-workspace/README.md
+packages/create-nx-plugin/README.md
 
 test-output
 test-results
@@ -151,11 +186,7 @@ test-results
 .claude/worktrees
 
 .nx/self-healing
-# Nx Typings Output
-packages/nx/**/*.d.ts
-!packages/nx/src/utils/perf-hooks.d.ts
-!packages/nx/src/ai/set-up-ai-agents/schema.d.ts
-!packages/nx/src/native/index.d.ts
-!packages/nx/src/native/dts-header.d.ts
 e2e/**/*.d.ts
 e2e/**/*.d.ts.map
+
+.nx/migrate-runs

.nx/workflows/agents.yaml

@@ -5,6 +5,11 @@ common-env-vars: &common-env-vars
   GIT_COMMITTER_NAME: Test
   SELECTED_PM: 'pnpm'
   NX_NATIVE_LOGGING: 'nx::native::db'
+  # Pin corepack to the pnpm version from packageManager. Without this, corepack
+  # falls back to "latest" in directories that have no packageManager field
+  # (e.g. e2e temp dirs created by create-nx-workspace), pulling pnpm 11 and
+  # breaking install. Same treatment as .github/workflows/{ci,e2e-matrix}.yml.
+  COREPACK_DEFAULT_TO_LATEST: '0'
   # These are need for build and link validation for next.js and astro apps
   NEXT_PUBLIC_ASTRO_URL: 'https://master--nx-docs.netlify.app'
   NX_DEV_URL: 'https://canary.nx.dev'

.nx/workflows/dynamic-changesets.yaml

@@ -5,31 +5,6 @@ distribute-on:
   large-changeset: 6 linux-large, 6 linux-extra-large
   extra-large-changeset: 8 linux-large, 8 linux-extra-large
 assignment-rules:
-  - projects:
-      - e2e-gradle
-    targets:
-      - e2e-ci**
-    run-on:
-      - agent: linux-extra-large
-        parallelism: 1
-  - projects:
-      - e2e-next
-      - e2e-plugin
-    targets:
-      - e2e-ci**
-    run-on:
-      - agent: linux-extra-large
-        parallelism: 2
-  - projects:
-      - e2e-angular
-      - e2e-node
-      - e2e-react
-    targets:
-      - e2e-ci**
-    run-on:
-      - agent: linux-extra-large
-        parallelism: 1
-
   - projects:
       - nx
       - workspace
@@ -44,36 +19,22 @@ assignment-rules:
       - agent: linux-extra-large
         parallelism: 1
 
-  - projects:
-      - e2e-release
-      - e2e-nuxt
-      - e2e-web
-      - e2e-eslint
-      - e2e-remix
-      - e2e-cypress
-      - e2e-docker
-      - e2e-js
-      - e2e-nx
-      - e2e-nx-init
-      - e2e-dotnet
-      - e2e-workspace-create
-      - e2e-rollup
-    targets:
-      - e2e-ci**
+  # Module federation e2e tests build + serve a host and its remotes (several
+  # webpack/rspack builds at once) — each one saturates ~7 cores. Pin them to
+  # the larger extra-large agents, one per machine. Must precede e2e-ci**.
+  - targets:
+      - e2e-ci--src/module-federation**
     run-on:
-      - agent: linux-large
-        parallelism: 1
       - agent: linux-extra-large
-        parallelism: 2
+        parallelism: 1
 
-  # All other e2e tests can run in parallel
   - targets:
       - e2e-ci**
     run-on:
       - agent: linux-large
-        parallelism: 2
-      - agent: linux-extra-large
         parallelism: 3
+      - agent: linux-extra-large
+        parallelism: 6
 
   - targets:
       - bench:*

.nx/workflows/sandboxing-config.yaml

@@ -20,3 +20,9 @@ task-exclusions:
       - '**'
     exclude-writes:
       - '**'
+
+  - project: graph-client
+    target: build-client
+    exclude-reads:
+      - '**/*.stories.{js,jsx,ts,tsx,mdx}'
+      - '**/*.{spec,test}.{js,jsx,ts,tsx}'

AGENTS.md

@@ -86,6 +86,16 @@ If the prepush validation suite fails, please fix the issues before proceeding w
 code adheres to the project's standards and passes all tests. DO NOT make a new commit to fix these issues. Instead,
 amend the current commit.
 
+### Testing Changes in Other Repos
+
+To test a locally built Nx package in another repository (e.g., to verify a fix end-to-end):
+
+```bash
+pnpm copy-built-package --package nx --repo ../path/to/test-repo
+```
+
+This builds the package and copies it into the target repo's `node_modules`. It works for all packages including native Rust code.
+
 ### Testing Changes
 
 After code changes are made, first test the specific project where the changes were made:

Cargo.lock

@@ -158,15 +158,6 @@ dependencies = [
  "syn 2.0.114",
 ]
 
-[[package]]
-name = "async-priority-channel"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "acde96f444d31031f760c5c43dc786b97d3e1cb2ee49dd06898383fe9a999758"
-dependencies = [
- "event-listener",
-]
-
 [[package]]
 name = "async-trait"
 version = "0.1.89"
@@ -187,12 +178,6 @@ dependencies = [
  "bytemuck",
 ]
 
-[[package]]
-name = "atomic-take"
-version = "1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a8ab6b55fe97976e46f91ddbed8d147d966475dc29b2032757ba47e02376fbc3"
-
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -217,7 +202,7 @@ dependencies = [
  "miniz_oxide",
  "object",
  "rustc-demangle",
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]
@@ -396,7 +381,7 @@ dependencies = [
  "js-sys",
  "num-traits",
  "wasm-bindgen",
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]
@@ -469,15 +454,6 @@ dependencies = [
  "static_assertions",
 ]
 
-[[package]]
-name = "concurrent-queue"
-version = "2.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
-dependencies = [
- "crossbeam-utils",
-]
-
 [[package]]
 name = "console"
 version = "0.15.11"
@@ -876,17 +852,6 @@ dependencies = [
  "num-traits",
 ]
 
-[[package]]
-name = "event-listener"
-version = "4.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67b215c49b2b248c855fb73579eb1f4f26c38ffdc12973e20e07b91d78d5646e"
-dependencies = [
- "concurrent-queue",
- "parking",
- "pin-project-lite",
-]
-
 [[package]]
 name = "eyre"
 version = "0.6.12"
@@ -1201,7 +1166,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8"
 dependencies = [
  "rustix 1.1.3",
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]
@@ -1467,7 +1432,7 @@ dependencies = [
  "js-sys",
  "log",
  "wasm-bindgen",
- "windows-core 0.62.2",
+ "windows-core",
 ]
 
 [[package]]
@@ -1976,9 +1941,9 @@ checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
 [[package]]
 name = "libc"
-version = "0.2.186"
+version = "0.2.180"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+checksum = "bcc35a38544a891a5f7c865aca548a982ccb3b8650a5b06d0fd33a10283c56fc"
 
 [[package]]
 name = "libloading"
@@ -1987,7 +1952,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "754ca22de805bb5744484a5b151a9e1a8e837d5dc232c2d7d8c2e3492edc8b60"
 dependencies = [
  "cfg-if",
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]
@@ -2135,28 +2100,6 @@ dependencies = [
  "autocfg",
 ]
 
-[[package]]
-name = "miette"
-version = "7.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5f98efec8807c63c752b5bd61f862c165c115b0a35685bdcfd9238c7aeb592b7"
-dependencies = [
- "cfg-if",
- "miette-derive",
- "unicode-width 0.1.14",
-]
-
-[[package]]
-name = "miette-derive"
-version = "7.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "db5b29714e950dbb20d5e6f74f9dcec4edbcc1067bb7f8ed198c097b8c1a818b"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.114",
-]
-
 [[package]]
 name = "minimal-lexical"
 version = "0.2.1"
@@ -2210,6 +2153,8 @@ dependencies = [
  "napi-sys",
  "nohash-hasher",
  "rustc-hash 2.1.1",
+ "serde",
+ "serde_json",
  "tokio",
 ]
 
@@ -2300,18 +2245,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "nix"
-version = "0.31.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
-dependencies = [
- "bitflags 2.10.0",
- "cfg-if",
- "cfg_aliases",
- "libc",
-]
-
 [[package]]
 name = "nohash-hasher"
 version = "0.2.0"
@@ -2337,12 +2270,6 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "normalize-path"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f5438dd2b2ff4c6df6e1ce22d825ed2fa93ee2922235cc45186991717f0a892d"
-
 [[package]]
 name = "notify"
 version = "8.2.0"
@@ -2469,6 +2396,7 @@ dependencies = [
  "itertools 0.10.5",
  "jsonc-parser",
  "jsonrpsee",
+ "libc",
  "machine-uid",
  "mio",
  "napi",
@@ -2476,6 +2404,7 @@ dependencies = [
  "napi-derive",
  "nix 0.30.1",
  "nom 7.1.3",
+ "notify",
  "once_cell",
  "parking_lot",
  "portable-pty",
@@ -2512,9 +2441,6 @@ dependencies = [
  "uuid",
  "vt100-ctt",
  "walkdir",
- "watchexec",
- "watchexec-events",
- "watchexec-signals",
  "winapi",
  "winres",
  "wrap-ansi",
@@ -2604,6 +2530,17 @@ dependencies = [
  "objc2-core-foundation",
 ]
 
+[[package]]
+name = "objc2-open-directory"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb82bed227edf5201dfedf072bba4015a33d3d4a98519837295a90f0a23f676d"
+dependencies = [
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "object"
 version = "0.37.3"
@@ -2650,12 +2587,6 @@ version = "4.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9c6901729fa79e91a0913333229e9ca5dc725089d1c363b2f4b4760709dc4a52"
 
-[[package]]
-name = "parking"
-version = "2.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba"
-
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -2676,7 +2607,7 @@ dependencies = [
  "libc",
  "redox_syscall 0.5.18",
  "smallvec",
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]
@@ -2952,20 +2883,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "process-wrap"
-version = "9.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e842efad9119158434d193c6682e2ebee4b44d6ad801d7b349623b3f57cdf55"
-dependencies = [
- "futures",
- "indexmap",
- "nix 0.31.3",
- "tokio",
- "tracing",
- "windows 0.62.2",
-]
-
 [[package]]
 name = "psm"
 version = "0.1.29"
@@ -4142,16 +4059,17 @@ dependencies = [
 
 [[package]]
 name = "sysinfo"
-version = "0.37.2"
+version = "0.39.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "16607d5caffd1c07ce073528f9ed972d88db15dd44023fa57142963be3feb11f"
+checksum = "a4deba334e1190ba7cb498327affa11e5ece10d26a30ab2f27fcf09504b8d8b6"
 dependencies = [
  "libc",
  "memchr",
  "ntapi",
  "objc2-core-foundation",
  "objc2-io-kit",
- "windows 0.61.3",
+ "objc2-open-directory",
+ "windows",
 ]
 
 [[package]]
@@ -4439,7 +4357,6 @@ dependencies = [
  "libc",
  "mio",
  "pin-project-lite",
- "signal-hook-registry",
  "socket2",
  "tokio-macros",
  "windows-sys 0.61.2",
@@ -4980,63 +4897,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "watchexec"
-version = "8.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3de3c4a47a75176b13fc7b3f421a80a55b13cab5b3200547774f9b25d43a79a0"
-dependencies = [
- "async-priority-channel",
- "atomic-take",
- "futures",
- "libc",
- "miette",
- "normalize-path",
- "notify",
- "thiserror 2.0.18",
- "tokio",
- "tracing",
- "watchexec-events",
- "watchexec-signals",
- "watchexec-supervisor",
- "windows-sys 0.61.2",
-]
-
-[[package]]
-name = "watchexec-events"
-version = "6.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ad87c046fa1050d22100e7d234db2cbf6ffd020b0ae2deff4bef6faa8f71ac44"
-dependencies = [
- "notify-types",
- "watchexec-signals",
-]
-
-[[package]]
-name = "watchexec-signals"
-version = "5.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3fd4537617a323437550d34c73a6aeeb1b489bbcc526e63f044ca3e59347101f"
-dependencies = [
- "miette",
- "nix 0.30.1",
- "thiserror 2.0.18",
-]
-
-[[package]]
-name = "watchexec-supervisor"
-version = "5.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a710aaac2dfcfb8a2e117c2f5e926bf10c533345f468f2017160c5f0e9ee0c53"
-dependencies = [
- "futures",
- "process-wrap",
- "tokio",
- "tracing",
- "watchexec-events",
- "watchexec-signals",
-]
-
 [[package]]
 name = "wayland-backend"
 version = "0.3.12"
@@ -5260,38 +5120,16 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
-[[package]]
-name = "windows"
-version = "0.61.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9babd3a767a4c1aef6900409f85f5d53ce2544ccdfaa86dad48c91782c6d6893"
-dependencies = [
- "windows-collections 0.2.0",
- "windows-core 0.61.2",
- "windows-future 0.2.1",
- "windows-link 0.1.3",
- "windows-numerics 0.2.0",
-]
-
 [[package]]
 name = "windows"
 version = "0.62.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
 dependencies = [
- "windows-collections 0.3.2",
- "windows-core 0.62.2",
- "windows-future 0.3.2",
- "windows-numerics 0.3.1",
-]
-
-[[package]]
-name = "windows-collections"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3beeceb5e5cfd9eb1d76b381630e82c4241ccd0d27f1a39ed41b2760b255c5e8"
-dependencies = [
- "windows-core 0.61.2",
+ "windows-collections",
+ "windows-core",
+ "windows-future",
+ "windows-numerics",
 ]
 
 [[package]]
@@ -5300,20 +5138,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
 dependencies = [
- "windows-core 0.62.2",
-]
-
-[[package]]
-name = "windows-core"
-version = "0.61.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c0fdd3ddb90610c7638aa2b3a3ab2904fb9e5cdbecc643ddb3647212781c4ae3"
-dependencies = [
- "windows-implement",
- "windows-interface",
- "windows-link 0.1.3",
- "windows-result 0.3.4",
- "windows-strings 0.4.2",
+ "windows-core",
 ]
 
 [[package]]
@@ -5324,20 +5149,9 @@ checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
 dependencies = [
  "windows-implement",
  "windows-interface",
- "windows-link 0.2.1",
- "windows-result 0.4.1",
- "windows-strings 0.5.1",
-]
-
-[[package]]
-name = "windows-future"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc6a41e98427b19fe4b73c550f060b59fa592d7d686537eebf9385621bfbad8e"
-dependencies = [
- "windows-core 0.61.2",
- "windows-link 0.1.3",
- "windows-threading 0.1.0",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
 ]
 
 [[package]]
@@ -5346,9 +5160,9 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
 dependencies = [
- "windows-core 0.62.2",
- "windows-link 0.2.1",
- "windows-threading 0.2.1",
+ "windows-core",
+ "windows-link",
+ "windows-threading",
 ]
 
 [[package]]
@@ -5373,36 +5187,20 @@ dependencies = [
  "syn 2.0.114",
 ]
 
-[[package]]
-name = "windows-link"
-version = "0.1.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5e6ad25900d524eaabdbbb96d20b4311e1e7ae1699af4fb28c17ae66c80d798a"
-
 [[package]]
 name = "windows-link"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
-[[package]]
-name = "windows-numerics"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9150af68066c4c5c07ddc0ce30421554771e528bde427614c61038bc2c92c2b1"
-dependencies = [
- "windows-core 0.61.2",
- "windows-link 0.1.3",
-]
-
 [[package]]
 name = "windows-numerics"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
 dependencies = [
- "windows-core 0.62.2",
- "windows-link 0.2.1",
+ "windows-core",
+ "windows-link",
 ]
 
 [[package]]
@@ -5411,18 +5209,9 @@ version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720"
 dependencies = [
- "windows-link 0.2.1",
- "windows-result 0.4.1",
- "windows-strings 0.5.1",
-]
-
-[[package]]
-name = "windows-result"
-version = "0.3.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "56f42bd332cc6c8eac5af113fc0c1fd6a8fd2aa08a0119358686e5160d0586c6"
-dependencies = [
- "windows-link 0.1.3",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
 ]
 
 [[package]]
@@ -5431,16 +5220,7 @@ version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
 dependencies = [
- "windows-link 0.2.1",
-]
-
-[[package]]
-name = "windows-strings"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "56e6c93f3a0c3b36176cb1327a4958a0353d5d166c2a35cb268ace15e91d3b57"
-dependencies = [
- "windows-link 0.1.3",
+ "windows-link",
 ]
 
 [[package]]
@@ -5449,7 +5229,7 @@ version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
 dependencies = [
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]
@@ -5494,7 +5274,7 @@ version = "0.61.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]
@@ -5534,7 +5314,7 @@ version = "0.53.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
 dependencies = [
- "windows-link 0.2.1",
+ "windows-link",
  "windows_aarch64_gnullvm 0.53.1",
  "windows_aarch64_msvc 0.53.1",
  "windows_i686_gnu 0.53.1",
@@ -5545,22 +5325,13 @@ dependencies = [
  "windows_x86_64_msvc 0.53.1",
 ]
 
-[[package]]
-name = "windows-threading"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b66463ad2e0ea3bbf808b7f1d371311c80e115c0b71d60efc142cafbcfb057a6"
-dependencies = [
- "windows-link 0.1.3",
-]
-
 [[package]]
 name = "windows-threading"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
 dependencies = [
- "windows-link 0.2.1",
+ "windows-link",
 ]
 
 [[package]]

astro-docs/.vale/styles/Nx/BannedPhrases.yml

@@ -27,3 +27,15 @@ tokens:
   - 'Game-changer'
   - 'Cutting-edge'
   - 'Groundbreaking'
+  - 'delve into'
+  - 'delving into'
+  - 'embark on a journey'
+  - 'embark on'
+  - 'navigate the realm of'
+  - 'in the realm of'
+  - 'in the world of'
+  - 'rich tapestry'
+  - 'tapestry of'
+  - 'at its core'
+  - 'a testament to'
+  - 'plays a (vital|crucial|pivotal|key) role'

astro-docs/.vale/styles/Nx/Closers.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Possible restatement closer '%s'. Check whether this sentence adds new info or just summarizes."
+level: warning
+ignorecase: true
+tokens:
+  - 'This is (why|how|what|the reason)'
+  - 'In short'
+  - 'In summary'
+  - 'Ultimately'
+  - 'All in all'
+  - 'At the end of the day'
+  - 'The (key|main) takeaway'
+  - 'This (is|was) the gap'

astro-docs/.vale/styles/Nx/Headings.yml

@@ -67,6 +67,8 @@ exceptions:
   - Expo
   - React Native
   - Module Federation
+  - TanStack
+  - TanStack Router
   - IntelliJ
   - VS Code
   - VSCode

astro-docs/.vale/styles/Nx/MarketingLanguage.yml

@@ -18,3 +18,15 @@ tokens:
   - 'world-class'
   - 'next-level'
   - 'supercharge'
+  - 'delve'
+  - 'underscore'
+  - 'underscores'
+  - 'foster'
+  - 'empower'
+  - 'meticulous'
+  - 'meticulously'
+  - 'crucial'
+  - 'pivotal'
+  - 'paramount'
+  - 'intricate'
+  - 'multifaceted'

astro-docs/STYLE_GUIDE.md

@@ -1,8 +1,7 @@
 # Nx Documentation Style Guide
 
-This document defines the standards for Nx documentation on nx.dev, including voice, grammar, formatting, and terminology.
-
-For automated enforcement, see the [Vale configuration](#vale-configuration) section below.
+These rules apply to all content under `astro-docs/src/content/docs/`.
+[Vale](#vale-configuration) enforces the mechanical ones automatically.
 
 ## Information architecture
 
@@ -53,14 +52,55 @@ The sidebar has four top-level sections that follow the user journey:
 3. **Knowledge Base** - Recipes, troubleshooting, and topic-specific guides
 4. **Reference** - Exhaustive facts, no narrative (CLI commands, configuration, API docs)
 
+## Structural anti-AI rules (longform)
+
+Sentence-level edits don't fix AI voice in longform pieces. The structural tells matter more.
+
+### One canonical home per point
+
+Each substantive point lives in exactly one section. Other sections link or reference it in one phrase. They don't re-explain.
+
+### No drama-beat echoes
+
+A short sentence (under ~10 words) immediately after a long one, restating the long one for emphasis, is an AI tic.
+Cover the short sentence with your thumb. If nothing is lost, cut it.
+
+### No restatement closers
+
+Read the last sentence of each paragraph alone.
+If it summarizes what the paragraph said rather than adding a fact, judgment, or turn, cut it.
+
+### Match claims to evidence
+
+Every quantifier ("always", "never", "all", "completely", "fully", "rarely") and every counterfactual ("would have prevented", "would have caught") should be checked against the evidence actually in the doc.
+
+Two failure modes:
+
+- **Over-generalization**: one observed instance written as a broad pattern. If the doc has one data point, don't write "users frequently" or "this always happens."
+- **Under-calibration**: softening a true absolute, or absolutizing a partial fix. "Would have prevented" is fine when the fix categorically closes the outcome. It's wrong when the fix closes one path of several.
+
+Ask of each strong claim: "what in this doc supports the strength of this word?" If nothing, weaken or cite.
+
+### Pre-publish pass order
+
+Run passes in this order. Structural first, vocabulary last.
+
+1. Canonical-home audit: where does each substantive point live?
+2. Repetition count: grep your two or three core findings. If a finding appears more than twice in prose, the third is probably redundant.
+3. Drama-beat sweep.
+4. Closer pass.
+5. Claim audit: for each absolute and each counterfactual, check what evidence in the doc supports that strength. Weaken or cite.
+6. End-to-end consistency read.
+7. Vocabulary grep (cheapest, lowest value).
+
 ## The Nx voice
 
-Nx documentation is **direct, practical, and confident**. We write like a knowledgeable colleague pairing with you — not like a textbook, not like a marketing page, and not like a chatbot.
+Nx documentation is **direct, practical, and confident**. We write like a knowledgeable colleague pairing with you, not like a textbook, not like a marketing page, and not like a chatbot.
 
 The voice should be:
 
 - **Conversational but efficient.** Use contractions. Get to the point. Don't pad sentences.
-- **Second person.** Write "you" — address the reader directly.
+- **Second person.** Write "you". Address the reader directly.
 - **Action-oriented.** Lead with what the reader can _do_, not what Nx _is_.
 - **Honest about tradeoffs.** Don't oversell. If something has limitations, say so.
 
@@ -76,7 +116,7 @@ The voice should be:
 
 ### Anti-AI language
 
-Documentation must not read like it was generated by an AI assistant. Even when AI tools are used in the writing process, the output must be edited to sound like a human wrote it.
+Edit AI-assisted drafts so they don't read like AI wrote them. Phrase-level passes alone won't do it. Apply the structural rules above first.
 
 **Never use these phrases:**
 
@@ -84,6 +124,13 @@ Documentation must not read like it was generated by an AI assistant. Even when
 - "It's worth noting that..." / "It should be noted that..."
 - "In this section, we will explore..."
 - "Let's dive into..." / "Let's take a closer look at..."
+- "Delve into..." / "Delving into..."
+- "Embark on a journey..." / "Embark on..."
+- "Navigate the realm of..." / "In the realm of..." / "In the world of..."
+- "At its core..."
+- "A testament to..."
+- "Rich tapestry" / "Tapestry of..."
+- "Plays a vital/crucial/pivotal/key role"
 - "Whether you're a beginner or an experienced developer..."
 - "In today's fast-paced development environment..."
 - "Unlock the power of..." / "Harness the power of..."
@@ -95,7 +142,7 @@ Documentation must not read like it was generated by an AI assistant. Even when
 - "Game-changer" / "Cutting-edge" / "Groundbreaking"
 - "Seamless" / "Seamlessly" (unless describing an actual integration)
 
-**Avoid hedging words unless genuinely needed:**
+**Avoid hedging words:**
 
 - "Essentially" / "Basically" / "Effectively"
 - "Generally speaking"
@@ -106,9 +153,11 @@ Documentation must not read like it was generated by an AI assistant. Even when
 
 **Watch for AI-style sentence patterns:**
 
-- Sentences that start with "This allows you to..." or "This enables you to..." — rewrite to lead with the reader's action.
+- Sentences that start with "This allows you to..." or "This enables you to...". Rewrite to lead with the reader's action.
 - Paragraphs that start with a general claim and then restate it slightly differently. Say it once.
 - Excessive use of "robust", "leverage", "utilize", "facilitate", "comprehensive", "aforementioned."
+- TED-talk verbs: "delve", "underscore" (as verb), "foster", "empower", "embark", "unlock", "harness". Replace with the concrete action.
+- Filler adjectives: "meticulous", "crucial", "pivotal", "paramount", "intricate", "multifaceted".
 - Lists where every item starts with the same grammatical structure repeated 5+ times with slight variation. Vary your phrasing.
 
 ### Self-referential writing
@@ -125,13 +174,13 @@ Don't:
 - "In this guide, we'll walk through..."
 - "This document covers..."
 
-Get right to the point. The reader already knows they're on a page — they want the information.
+Get right to the point. The reader already knows they're on a page.
 
 ### Building trust
 
 Don't use filler words that undermine the reader's trust.
 
-- Don't use "easily", "simply", "just", or "straightforward" — if something were truly simple, you wouldn't need to document it. These words also make readers feel bad when they struggle.
+- Don't use "easily", "simply", "just", or "straightforward". If something were truly simple, you wouldn't need to document it. These words also make readers feel bad when they struggle.
 - Don't use marketing language: "This feature will save you hours" or "Nx makes CI effortless."
 - Be specific instead: "Remote caching can reduce CI times from 45 minutes to under 5 minutes for cache-hit builds."
 
@@ -387,11 +436,10 @@ Use these terms consistently. When writing about Nx concepts, use the exact term
 
 ## Vale configuration
 
-[Vale](https://vale.sh) enforces many of the rules in this style guide automatically.
-Configuration lives in `astro-docs/`:
+[Vale](https://vale.sh) enforces the mechanical rules automatically. Configuration lives in `astro-docs/`:
 
-- `.vale.ini` — Main config. Scopes rules to `src/content/docs/**/*.{mdoc,mdx,md}`.
-- `.vale/styles/Nx/` — Custom rules for Nx documentation.
+- `.vale.ini`: main config. Scopes rules to `src/content/docs/**/*.{mdoc,mdx,md}`.
+- `.vale/styles/Nx/`: custom rules for Nx documentation.
 
 ### Running Vale
 
@@ -410,11 +458,11 @@ You can also install directly via `brew install vale` (macOS) or `apt-get instal
 
 ### Rule tiers
 
-| Tier           | Severity     | Rules                                                                                       |
-| -------------- | ------------ | ------------------------------------------------------------------------------------------- |
-| 1 - Mechanical | `error`      | Banned phrases, product capitalization                                                      |
-| 2 - Structural | `warning`    | Heading case, terminology, product possessives, self-referential writing, sentence patterns |
-| 3 - Voice      | `suggestion` | Trust-undermining words, marketing language, passive voice, serial commas                   |
+| Tier           | Severity     | Rules                                                                                                            |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- |
+| 1 - Mechanical | `error`      | Banned phrases, product capitalization                                                                           |
+| 2 - Structural | `warning`    | Heading case, terminology, product possessives, self-referential writing, sentence patterns, restatement closers |
+| 3 - Voice      | `suggestion` | Trust-undermining words, marketing language, passive voice, serial commas                                        |
 
 ### Adding new rules
 

astro-docs/astro.config.mjs

@@ -42,6 +42,10 @@ export default defineConfig({
   },
   trailingSlash: 'never',
   redirects: {
+    '/knowledge-base/installation':
+      '/docs/knowledge-base/installation-and-updates',
+    '/guides/nx-cloud/ci-resource-usage':
+      '/docs/features/ci-features/resource-usage',
     '/reference/remote-cache-plugins':
       '/docs/reference/deprecated/self-hosted-cache-packages',
     '/reference/remote-cache-plugins/s3-cache':

astro-docs/netlify.toml

@@ -67,6 +67,11 @@ to = "/docs/getting-started/tutorials/:splat"
 from = "/docs/features/ci-features/self-healing"
 to = "/docs/features/ci-features/self-healing-ci"
 
+# DOC-513: Manual DTE guide renamed to Bring Your Own Compute
+[[redirects]]
+from = "/docs/guides/nx-cloud/manual-dte"
+to = "/docs/guides/nx-cloud/bring-your-own-compute"
+
 [[redirects]]
 from = "/docs/extending-nx/recipes/create-preset"
 to = "/docs/extending-nx/create-preset"
@@ -125,6 +130,42 @@ to = "/docs/reference/deprecated/self-hosted-cache-packages"
 from = "/docs/reference/remote-cache-plugins/shared-fs-cache/generators"
 to = "/docs/reference/deprecated/self-hosted-cache-packages"
 
+# DOC-503: CI page moved out of tutorials to top-level Getting Started
+[[redirects]]
+from = "/docs/getting-started/tutorials/self-healing-ci-tutorial"
+to = "/docs/getting-started/setup-ci"
+
+# Resource usage consolidated into the Nx Cloud add-ons platform feature pages
+[[redirects]]
+from = "/docs/guides/nx-cloud/ci-resource-usage"
+to = "/docs/features/ci-features/resource-usage"
+
+# NXC-4453: Knowledge Base "Installation" section renamed to "Installation and updates"
+[[redirects]]
+from = "/docs/knowledge-base/installation"
+to = "/docs/knowledge-base/installation-and-updates"
+
+# DOC-522: Polygraph is a standalone product, no longer part of Nx Cloud.
+# Reroute the Polygraph-specific docs pages to the standalone landing page.
+# force = true so these win over the catch-all rewrite below.
+[[redirects]]
+from = "/docs/enterprise/polygraph"
+to = "https://trypolygraph.com"
+status = 301
+force = true
+
+[[redirects]]
+from = "/docs/concepts/synthetic-monorepos"
+to = "https://trypolygraph.com"
+status = 301
+force = true
+
+[[redirects]]
+from = "/docs/enterprise/metadata-only-workspace"
+to = "https://trypolygraph.com"
+status = 301
+force = true
+
 # Rewrite for base path handling (keeps URL the same)
 [[redirects]]
 from = "/docs/*"

astro-docs/project.json

@@ -25,7 +25,13 @@
             "devkit",
             "create-nx-workspace",
             "dotnet",
-            "maven"
+            "maven",
+            "esbuild",
+            "gradle",
+            "nuxt",
+            "plugin",
+            "react-native",
+            "remix"
           ],
           "target": "build"
         }
@@ -44,7 +50,13 @@
             "devkit",
             "create-nx-workspace",
             "dotnet",
-            "maven"
+            "maven",
+            "esbuild",
+            "gradle",
+            "nuxt",
+            "plugin",
+            "react-native",
+            "remix"
           ],
           "target": "build"
         }

astro-docs/sidebar.mts

@@ -34,6 +34,7 @@ const learnGroups: SidebarItems = [
         link: 'getting-started/start-with-existing-project',
       },
       { label: 'AI integrations', link: 'getting-started/ai-setup' },
+      { label: 'CI setup', link: 'getting-started/setup-ci' },
       { label: 'Editor setup', link: 'getting-started/editor-setup' },
       {
         label: 'Tutorials',
@@ -67,10 +68,6 @@ const learnGroups: SidebarItems = [
             label: 'Reducing boilerplate',
             link: 'getting-started/tutorials/reducing-configuration-boilerplate',
           },
-          {
-            label: 'Setting up CI',
-            link: 'getting-started/tutorials/self-healing-ci-tutorial',
-          },
           {
             label: 'Gradle monorepo',
             link: 'getting-started/tutorials/gradle-tutorial',
@@ -109,10 +106,6 @@ const learnGroups: SidebarItems = [
         link: 'concepts/ci-concepts/parallelization-distribution',
       },
       { label: 'Nx Daemon', link: 'concepts/nx-daemon' },
-      {
-        label: 'Synthetic monorepos',
-        link: 'concepts/synthetic-monorepos',
-      },
     ],
   },
   {
@@ -190,10 +183,6 @@ const learnGroups: SidebarItems = [
             label: 'Dynamically allocate agents',
             link: 'features/ci-features/dynamic-agents',
           },
-          {
-            label: 'CI resource usage',
-            link: 'guides/nx-cloud/ci-resource-usage',
-          },
           {
             label: 'Optimize your TTG',
             link: 'guides/nx-cloud/optimize-your-ttg',
@@ -206,17 +195,36 @@ const learnGroups: SidebarItems = [
             label: 'GitHub integration',
             link: 'features/ci-features/github-integration',
           },
-          {
-            label: 'Sandboxing',
-            link: 'features/ci-features/sandboxing',
-            badge: 'New',
-          },
           {
             label: 'CIPE affected project graph',
             link: 'guides/nx-cloud/cipe-affected-project-graph',
           },
           { label: 'Encryption', link: 'guides/nx-cloud/encryption' },
           { label: 'Google auth', link: 'guides/nx-cloud/google-auth' },
+          {
+            label: 'Resource usage',
+            link: 'features/ci-features/resource-usage',
+          },
+          {
+            label: 'Dedicated compute cluster',
+            link: 'features/ci-features/dedicated-compute-cluster',
+          },
+          {
+            label: 'Sandboxing',
+            link: 'features/ci-features/sandboxing',
+          },
+          {
+            label: 'Docker layer caching',
+            link: 'features/ci-features/docker-layer-caching',
+          },
+          {
+            label: 'Docker read-through cache',
+            link: 'features/ci-features/docker-read-through-cache',
+          },
+          {
+            label: 'npm read-through cache',
+            link: 'features/ci-features/npm-read-through-cache',
+          },
         ],
       },
       {
@@ -287,8 +295,8 @@ const learnGroups: SidebarItems = [
         collapsed: true,
         items: [
           {
-            label: 'Nx Console migration assistance',
-            link: 'guides/nx-console/console-migrate-ui',
+            label: 'Automate updating dependencies',
+            link: 'features/automate-updating-dependencies',
           },
           {
             label: 'Advanced update process',
@@ -330,12 +338,7 @@ const learnGroups: SidebarItems = [
             link: 'enterprise/publish-conformance-rules-to-nx-cloud',
           },
           { label: 'Owners', link: 'enterprise/owners' },
-          { label: 'Polygraph', link: 'enterprise/polygraph' },
           { label: 'Custom workflows', link: 'enterprise/custom-workflows' },
-          {
-            label: 'Metadata only workspace',
-            link: 'enterprise/metadata-only-workspace',
-          },
           { label: 'Activate license', link: 'enterprise/activate-license' },
           {
             label: 'Single tenant',
@@ -449,12 +452,29 @@ const technologiesGroups: SidebarItems = [
           { label: 'Expo', link: 'technologies/react/expo/introduction' },
           { label: 'Vue', link: 'technologies/vue/introduction' },
           { label: 'Nuxt', link: 'technologies/vue/nuxt/introduction' },
+          {
+            label: 'Module Federation',
+            link: 'technologies/module-federation/introduction',
+          },
+          { label: 'ESLint', link: 'technologies/eslint/introduction' },
+        ],
+      },
+      {
+        label: 'Node',
+        collapsed: false,
+        items: [
           { label: 'Node.js', link: 'technologies/node/introduction' },
           {
             label: 'Express',
             link: 'technologies/node/express/introduction',
           },
           { label: 'Nest', link: 'technologies/node/nest/introduction' },
+        ],
+      },
+      {
+        label: 'Java (JVM)',
+        collapsed: false,
+        items: [
           { label: 'Java', link: 'technologies/java/introduction' },
           {
             label: 'Gradle',
@@ -464,14 +484,13 @@ const technologiesGroups: SidebarItems = [
             label: 'Maven',
             link: 'technologies/java/maven/introduction',
           },
-          { label: '.NET', link: 'technologies/dotnet/introduction' },
-          {
-            label: 'Module Federation',
-            link: 'technologies/module-federation/introduction',
-          },
-          { label: 'ESLint', link: 'technologies/eslint/introduction' },
         ],
       },
+      {
+        label: '.NET',
+        collapsed: false,
+        items: [{ label: '.NET', link: 'technologies/dotnet/introduction' }],
+      },
       {
         label: 'Build tools',
         collapsed: false,
@@ -694,7 +713,7 @@ const knowledgeBaseGroups: SidebarItems = [
         ],
       },
       {
-        label: 'Installation',
+        label: 'Installation and updates',
         collapsed: true,
         items: [
           {
@@ -705,6 +724,10 @@ const knowledgeBaseGroups: SidebarItems = [
             label: 'Update global installation',
             link: 'guides/installation/update-global-installation',
           },
+          {
+            label: 'Nx Console migration assistance',
+            link: 'guides/nx-console/console-migrate-ui',
+          },
         ],
       },
       {
@@ -784,6 +807,10 @@ const knowledgeBaseGroups: SidebarItems = [
             label: 'CreateNodes compatibility',
             link: 'extending-nx/createnodes-compatibility',
           },
+          {
+            label: 'Performant project graph plugins',
+            link: 'extending-nx/performant-project-graph-plugins',
+          },
           {
             label: 'Organization-specific plugin',
             link: 'extending-nx/organization-specific-plugin',
@@ -816,7 +843,10 @@ const knowledgeBaseGroups: SidebarItems = [
             label: 'Personal access tokens',
             link: 'guides/nx-cloud/personal-access-tokens',
           },
-          { label: 'Manual DTE', link: 'guides/nx-cloud/manual-dte' },
+          {
+            label: 'Bring Your Own Compute',
+            link: 'guides/nx-cloud/bring-your-own-compute',
+          },
           {
             label: 'Source control integration',
             link: 'guides/nx-cloud/source-control-integration',

astro-docs/src/components/layout/ConfBanner.astro

@@ -0,0 +1,111 @@
+---
+import { confBanner, isConfBannerActive } from './conf-banner';
+
+const active = isConfBannerActive();
+---
+
+{
+  active && (
+    <a
+      class="conf-banner"
+      href={confBanner.url}
+      target="_blank"
+      rel="noopener noreferrer"
+      id="conf-banner-link"
+    >
+      <span class="conf-banner__text">
+        <span class="conf-banner__brand">
+          AI <span class="conf-banner__heart">&#9829;</span> Monorepos
+        </span>
+        <span class="conf-banner__desc">Free online conference &middot; June 23</span>
+      </span>
+      <span class="conf-banner__cta">
+        Join us!
+        <svg
+          class="conf-banner__arrow"
+          viewBox="0 0 20 20"
+          fill="currentColor"
+          aria-hidden="true"
+        >
+          <path
+            fill-rule="evenodd"
+            d="M5 10a.75.75 0 0 1 .75-.75h6.638L9.96 7.046a.75.75 0 0 1 1.08-1.04l3.75 3.75a.75.75 0 0 1 0 1.04l-3.75 3.75a.75.75 0 1 1-1.08-1.04l2.428-2.206H5.75A.75.75 0 0 1 5 10Z"
+            clip-rule="evenodd"
+          />
+        </svg>
+      </span>
+    </a>
+  )
+}
+
+<style>
+  .conf-banner {
+    position: fixed;
+    inset-block-start: 0;
+    inset-inline: 0;
+    z-index: calc(var(--sl-z-index-navbar) + 1);
+    height: var(--conf-banner-h, 2.5rem);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.625rem;
+    padding-inline: 1rem;
+    /* Theme-aware: light strip in light mode, dark strip in dark mode. */
+    background-color: var(--sl-color-bg-nav);
+    color: var(--sl-color-gray-2);
+    font-size: 0.875rem;
+    line-height: 1.2;
+    text-decoration: none;
+    border-bottom: 1px solid var(--sl-color-hairline-shade);
+  }
+
+  .conf-banner__text {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 500;
+  }
+
+  .conf-banner__brand {
+    font-weight: 700;
+    color: var(--sl-color-gray-1);
+    white-space: nowrap;
+  }
+
+  .conf-banner__heart {
+    color: #f43f5e;
+  }
+
+  .conf-banner__desc {
+    color: var(--sl-color-gray-3);
+    white-space: nowrap;
+  }
+
+  .conf-banner__cta {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.125rem;
+    font-weight: 600;
+    color: var(--sl-color-text-accent);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    white-space: nowrap;
+    transition: color 0.15s ease;
+  }
+
+  .conf-banner:hover .conf-banner__cta {
+    color: var(--sl-color-accent-high);
+  }
+
+  .conf-banner__arrow {
+    width: 1rem;
+    height: 1rem;
+  }
+
+  /* Tight viewports: drop the descriptor so the bar stays one line at 2.5rem. */
+  @media (max-width: 30rem) {
+    .conf-banner__desc {
+      display: none;
+    }
+  }
+</style>

astro-docs/src/components/layout/Header.astro

@@ -19,7 +19,8 @@ const nxDevUrl = import.meta.env.SITE || 'https://nx.dev';
 
 // Version options
 const versions = [
-  { version: 'v22', href: '/docs/getting-started/intro', current: true },
+  { version: 'v23', href: '/docs/getting-started/intro', current: true },
+  { version: 'v22', href: 'https://22.nx.dev/docs' },
   { version: 'v21', href: 'https://21.nx.dev/docs' },
   { version: 'v20', href: 'https://20.nx.dev/docs' },
   { version: 'v19', href: 'https://19.nx.dev/docs' },

astro-docs/src/components/layout/PageFrame.astro

@@ -5,9 +5,12 @@ import { Footer } from '@nx/nx-dev-ui-common/src/lib/footer';
 import { GitHubStarWidget } from '@nx/nx-dev-ui-common/src/lib/github-star-widget';
 import { WebinarNotifier } from '@nx/nx-dev-ui-common/src/lib/webinar-notifier';
 import { getCollection } from 'astro:content';
+import ConfBanner from './ConfBanner.astro';
+import { isConfBannerActive } from './conf-banner';
 
 const { hasSidebar } = Astro.locals.starlightRoute;
 const githubStarsCount = Astro.locals.githubStarsCount ?? 0;
+const showConfBanner = isConfBannerActive();
 
 // Get banner from collection
 const bannerCollection = await getCollection('banner');
@@ -23,7 +26,8 @@ const showBanner = isBannerActive(bannerConfig);
 const bannerId = bannerConfig ? `${bannerConfig.title}-${bannerConfig.activeUntil || 'no-expiry'}` : '';
 ---
 
-<div class="page sl-flex">
+<div class:list={['page', 'sl-flex', { 'has-conf-banner': showConfBanner }]}>
+  <ConfBanner />
   <header class="header"><slot name="header" /></header>
   {
     hasSidebar && (
@@ -85,6 +89,11 @@ const bannerId = bannerConfig ? `${bannerConfig.title}-${bannerConfig.activeUnti
       min-height: 100vh;
     }
 
+    /* Height of the conference promo strip; reused to offset everything below it. */
+    .page.has-conf-banner {
+      --conf-banner-h: 2.5rem;
+    }
+
     .header {
       z-index: var(--sl-z-index-navbar);
       position: fixed;
@@ -98,6 +107,11 @@ const bannerId = bannerConfig ? `${bannerConfig.title}-${bannerConfig.activeUnti
       background-color: var(--sl-color-bg-nav);
     }
 
+    /* Push the fixed header below the banner. */
+    .page.has-conf-banner .header {
+      inset-block-start: var(--conf-banner-h);
+    }
+
     :global([data-has-sidebar]) .header {
       padding-inline-end: calc(
         var(--sl-nav-gap) + var(--sl-nav-pad-x) + var(--sl-menu-button-size)
@@ -115,6 +129,10 @@ const bannerId = bannerConfig ? `${bannerConfig.title}-${bannerConfig.activeUnti
       overflow-y: auto;
     }
 
+    .page.has-conf-banner .sidebar-pane {
+      inset-block-start: calc(var(--sl-nav-height) + var(--conf-banner-h));
+    }
+
     :global([aria-expanded='true']) ~ .sidebar-pane {
       --sl-sidebar-visibility: visible;
     }
@@ -145,6 +163,18 @@ const bannerId = bannerConfig ? `${bannerConfig.title}-${bannerConfig.activeUnti
       padding-inline-start: var(--sl-content-inline-start);
     }
 
+    .page.has-conf-banner .main-frame {
+      padding-top: calc(
+        var(--sl-nav-height) + var(--sl-mobile-toc-height) +
+          var(--conf-banner-h)
+      );
+    }
+
+    /* Starlight's mobile on-this-page bar is fixed at the nav height; shift it too. */
+    .page.has-conf-banner :global(mobile-starlight-toc > nav) {
+      top: calc(var(--sl-nav-height) + var(--conf-banner-h));
+    }
+
     @media (min-width: 50rem) {
       :global([data-has-sidebar]) .header {
         padding-inline-end: var(--sl-nav-pad-x);

astro-docs/src/components/layout/conf-banner.ts

@@ -0,0 +1,11 @@
+// Time-boxed promo bar for the "AI <3 Monorepos" online conference.
+// Build-time gated: the next rebuild after `activeUntil` drops the banner.
+export const confBanner = {
+  url: 'https://monorepo.tools/conf?utm_campaign=2026%20Conferences&utm_source=nx-docs&utm_medium=banner',
+  // End of June 23 2026, ET (UTC-4).
+  activeUntil: '2026-06-24T04:00:00Z',
+};
+
+export function isConfBannerActive(now: Date = new Date()): boolean {
+  return now < new Date(confBanner.activeUntil);
+}

astro-docs/src/components/markdoc/LlmCopyPrompt.astro

@@ -126,6 +126,7 @@ const promptLines = finalPrompt.split('\n').filter((l) => l.length > 0);
     border: 1px solid var(--sl-color-hairline);
     border-radius: 0.75rem;
     background: var(--sl-color-gray-6);
+    padding: 0;
     margin-bottom: 1.5rem;
   }
 
@@ -133,7 +134,6 @@ const promptLines = finalPrompt.split('\n').filter((l) => l.length > 0);
     list-style: none;
     list-style-type: none;
     cursor: pointer;
-    padding: 1rem 1.25rem;
   }
 
   .llm-prompt-card > summary::-webkit-details-marker {
@@ -155,6 +155,8 @@ const promptLines = finalPrompt.split('\n').filter((l) => l.length > 0);
     display: flex;
     align-items: center;
     gap: 0.5rem;
+    padding: 0.5rem;
+    border-bottom: 1px solid var(--sl-color-hairline);
   }
 
   .llm-prompt-icon {
@@ -213,6 +215,7 @@ const promptLines = finalPrompt.split('\n').filter((l) => l.length > 0);
   .llm-prompt-preview {
     position: relative;
     margin-top: 0.5rem;
+    padding: 0.5rem 1rem;
     color: var(--sl-color-gray-3);
     font-size: var(--sl-text-sm);
     line-height: 1.5;
@@ -240,6 +243,7 @@ const promptLines = finalPrompt.split('\n').filter((l) => l.length > 0);
     display: flex;
     justify-content: center;
     margin-top: 0.5rem;
+    padding-bottom: 0.5rem;
   }
 
   .llm-prompt-caret-expanded {
@@ -262,7 +266,7 @@ const promptLines = finalPrompt.split('\n').filter((l) => l.length > 0);
   }
 
   .llm-prompt-body {
-    padding: 0 1.25rem 1rem;
+    padding: 0 1rem 0.5rem;
     color: var(--sl-color-gray-2);
     font-size: var(--sl-text-sm);
     line-height: 1.6;
@@ -275,7 +279,7 @@ const promptLines = finalPrompt.split('\n').filter((l) => l.length > 0);
   .llm-prompt-body :global(ol),
   .llm-prompt-body :global(ul) {
     margin: 0 0 0.5rem;
-    padding-left: 1.25rem;
+    padding-left: 0.5rem;
   }
 
   .llm-prompt-body :global(li) {

astro-docs/src/content/docs/concepts/inferred-tasks.mdoc

@@ -43,10 +43,15 @@ Nx plugins infer the following properties by analyzing the tool configuration.
 
 A typical workspace will have many plugins inferring tasks. Nx processes all the plugins registered in `nx.json` to create project configuration for individual projects and a project and task graph that shows the connections between them all.
 
-### Plugin order matters
+### Order matters
 
 Plugins are processed in the order that they appear in the `plugins` array in `nx.json`. So, if multiple plugins create a task with the same name, the plugin listed last will win. If, for some reason, you have a project with both a `vite.config.js` file and a `webpack.config.js` file, both the `@nx/vite` plugin and the `@nx/webpack` plugin will try to create a `build` task. The `build` task that is executed will be the task that belongs to the plugin listed lower in the `plugins` array.
 
+Nx hashes the project graph node produced by each plugin to determine whether cached task results can be reused. If your plugin's `createNodes`/`createNodesV2` function returns different output on different runs or machines, Nx will compute a different hash and treat unchanged code as a cache miss. Keep output stable by following two rules:
+
+- **Sort arrays deterministically.** The order of `targets`, `inputs`, `outputs`, `dependsOn`, and `metadata.targetGroups` entries must be the same every time—sort them explicitly before returning.
+- **Avoid machine-specific or run-specific values.** Do not leak `process.env` variables, absolute paths, timestamps, or random IDs into target configuration. Prefer workspace-relative tokens (e.g. `{workspaceRoot}`) over absolute paths.
+
 ### Scope plugins to specific projects
 
 Plugins use config files to infer tasks for projects. You can specify which config files are processed by Nx plugins using the `include` and `exclude` properties in the plugin configuration object.

astro-docs/src/content/docs/concepts/synthetic-monorepos.mdoc

@@ -1,48 +0,0 @@
----
-title: Synthetic Monorepos
-description: Learn how synthetic monorepos connect separate repositories into a unified dependency graph, giving you monorepo intelligence without moving code.
----
-
-Most organizations don't have a single giant monorepo. They have a handful of monorepos per team or domain, plus dozens of standalone repos. Consolidating everything into one repository is not just a technical challenge. The organizational side (bringing teams along, changing workflows, ensuring adoption) is often harder than the code migration itself.
-
-Synthetic monorepos let you get monorepo benefits without that consolidation.
-
-## What is a synthetic monorepo?
-
-A synthetic monorepo connects separate repositories into a unified dependency graph without moving any code. Which repo depends on which, what a change affects downstream, how projects relate across teams: all of that becomes visible automatically.
-
-![A synthetic monorepo connecting multiple monorepos and standalone repos into a unified dependency graph](../../../assets/concepts/synthetic-monorepo.svg)
-
-Unlike a traditional monorepo where all code lives in one repository, a synthetic monorepo leaves each repository where it is. Instead, it builds a cross-repo graph that tooling can reason about, just as if the code were in one place.
-
-## What synthetic monorepos enable
-
-A synthetic monorepo addresses several downsides of a polyrepo setup:
-
-**Visibility** — An automatic cross-repo dependency graph shows which repo depends on which and what a change affects downstream. Always up to date, discovered from actual code — not a manually maintained spreadsheet or catalog. Nx implements this through the [Workspace Graph](/docs/enterprise/polygraph).
-
-**Coordination** — Cross-repo changes no longer require manually sequencing PRs, managing compatibility, and coordinating release order. Tooling on top of the graph enables impact analysis, coordinated changes, and conformance checking across repo boundaries.
-
-**Governance** — Organizational standards apply across every connected repo through [conformance rules](/docs/enterprise/conformance). Scheduled [custom workflows](/docs/enterprise/custom-workflows) check repos continuously — even ones nobody has touched in months. Detection and enforcement happen automatically, not through tickets and follow-ups.
-
-**CI intelligence** — [Affected detection](/docs/concepts/mental-model#affected-commands), [remote caching](/docs/concepts/how-caching-works), and [distributed task execution](/docs/concepts/ci-concepts/parallelization-distribution) work across the full graph, not just within a single repo.
-
-**AI agents** — AI coding agents are [dramatically less effective in polyrepos](https://youtu.be/alIto5fqrfk) — they can only see one repo at a time, so cross-repo features require you to manually shuttle context between sessions. A synthetic monorepo gives agents cross-repo visibility, enabling coordinated changes, parallel execution, and automatic PR creation across boundaries. [Self-healing CI](/docs/features/ci-features/self-healing-ci) catches failures automatically.
-
-## When to use a synthetic monorepo vs. a real monorepo
-
-A real monorepo is the best option when you can consolidate. It gives you atomic commits, a single toolchain, and the simplest mental model.
-
-A synthetic monorepo is the better starting point when:
-
-- **Consolidation isn't feasible yet:** team autonomy concerns, divergent CI setups, or hundreds of repos make migration impractical.
-- **You need cross-repo visibility now:** you can't wait months for a migration to see how projects relate across teams.
-- **Teams need to stay autonomous:** each team keeps their repo, workflow, and release cadence while still participating in a unified graph.
-
-The two aren't mutually exclusive. Start synthetic for org-wide visibility, then consolidate tightly coupled teams into real monorepos where it makes sense.
-
-## Synthetic monorepos with Nx Polygraph
-
-Nx implements synthetic monorepos through [Nx Polygraph](/docs/enterprise/polygraph). Polygraph connects existing repositories into a unified, intelligent graph that powers the visibility, coordination, and CI features described above. It works with any repo, even those that don't use Nx, and requires zero changes to target repos.
-
-Learn more about [getting started with Nx Polygraph](/docs/enterprise/polygraph).

astro-docs/src/content/docs/enterprise/custom-workflows.mdoc

@@ -28,25 +28,18 @@ Custom Workflows are available as part of Nx Enterprise and [consume compute cre
 
 ## Access custom workflows
 
-Navigate to your organization's Custom Workflows page in Nx Cloud. You'll see an overview of all the current workflows. Polygraph and Conformance based workflows are currently available. In a future release of Nx Cloud, custom workflow creation will be released.
+Navigate to your organization's Custom Workflows page in Nx Cloud. You'll see an overview of all the current workflows. Conformance based workflows are currently available. In a future release of Nx Cloud, custom workflow creation will be released.
 
 ![Org Overview](../../../assets/enterprise/custom-workflows/org-overview.avif)
 
 ## Apply a workflow
 
-{% tabs %}
-{% tabitem label="Polygraph workflows" %}
-Polygraph workflows are designed to grab the latest graph information from Nx to keep the Workspace graph up to date for your organization.
-{% /tabitem %}
-{% tabitem label="Conformance workflows" %}
 Conformance based workflows allow running the pre-defined conformance rules for a given workspace. Once setup you can also force a rerun of these conformance rules as desired.
-{% /tabitem %}
-{% /tabs %}
 
-1. Click **Polygraph** or **Conformance** for your repeating workflows provided by Nx Cloud
+1. Click **Conformance** for your repeating workflows provided by Nx Cloud
 
 - if using **Conformance** action, then make sure you've already configured and [published a conformance rule](/docs/enterprise/publish-conformance-rules-to-nx-cloud)
-  ![Polygraph overview](../../../assets/enterprise/custom-workflows/org-polygraph-overview.avif)
+  ![Org workflows overview](../../../assets/enterprise/custom-workflows/org-workflows-overview.avif)
 
 2. Click **Apply workflow** and select the workspace you wish to use for the custom workflow.
    ![Apply Workflow](../../../assets/enterprise/custom-workflows/apply-workflow.avif)
@@ -64,7 +57,7 @@ You can also upload your own custom launch template by clicking **Configure temp
 ## Perform first run
 
 Back in the custom workflow action page, you can manually trigger a run via clicking **Force**
-![Polygraph overview](../../../assets/enterprise/custom-workflows/org-polygraph-overview.avif)
+![Org workflows overview](../../../assets/enterprise/custom-workflows/org-workflows-overview.avif)
 
 Once your workflow has run, you can view its most recent execution via clicking **View Latest Execution**. If you've used with [Nx Agents](/docs/features/ci-features/distribute-task-execution), then this interface will be familiar. The execution shows each step taken by the workflow and the logs associated with each step.
 

astro-docs/src/content/docs/enterprise/metadata-only-workspace.mdoc

@@ -1,67 +0,0 @@
----
-title: Metadata-Only Workspaces
-description: 'Include non-Nx repositories in Polygraph features without requiring full Nx adoption. Enable zero-friction onboarding for legacy and existing repositories.'
-sidebar:
-  order: 2
-filter: 'type:Features'
----
-
-Metadata-only workspaces are a way to connect repositories to Nx Cloud that don't have Nx installed or configured. Unlike traditional Nx Cloud workspaces that require Nx to be set up in the repository, metadata-only workspaces can be connected with minimal configuration, allowing you to:
-
-- Include any repository in the Workspace Graph
-- Run Conformance rules across all repositories
-- Use Custom Workflows for automated compliance checking
-- Track dependencies and relationships between repositories
-
-The key benefit is **zero changes required to existing repositories** - you can start using [Polygraph features](/docs/enterprise/polygraph) immediately without requiring team buy-in or significant migration effort.
-
-## When to use metadata-Only workspaces
-
-Metadata-only workspaces are ideal for:
-
-1. **Legacy Repository Integration**
-   - Gain visibility into previously "dark" areas of your codebase
-   - Enforce organizational standards across all repositories, not just new ones
-2. **Mixed Technology Stacks**
-   - Organizations using multiple frameworks and build tools
-   - Teams that prefer their existing tooling but want organizational oversight
-3. **Gradual Nx Adoption Strategy**
-   - Start with organizational visibility before full Nx migration
-   - Allow teams to see the benefits of Nx tooling without immediate commitment
-4. **Large-Scale Organizations**
-   - Companies with hundreds of repositories across different teams
-   - Situations where immediate value is needed without waiting for complete migration
-
-## Connecting
-
-{% aside type="note" title="Onboarding Assistance" %}
-Reach out to your assigned developer productivity engineer, if you need any assistance in getting set up with polygraph and metadata-only workspaces.
-{%/aside %}
-
-{% tabs %}
-{% tabitem label="GitHub Integration" %}
-
-When using the [GitHub VCS Integration](/docs/features/ci-features/github-integration#access-control), you can easily bulk onboard your existing repositories into polygraph.
-
-1. Start with visiting your organization overview in Nx Cloud
-2. Click the **Connect a repository** button
-3. Click **Connect repositories to polygraph**
-4. Follow the prompts to onboard your repositories
-   ![Bulk onboard GitHub repositories](../../../assets/enterprise/polygraph/connect-polygraph-to-repos.avif)
-5. Click **Connect repositories** to finish
-
-{% /tabitem %}
-{% tabitem label="Manual" %}
-
-Manual onboarding is done via the normal workspace onboarding process inside Nx Cloud and enable **polygraph features** before finishing the connection.
-
-1. Start with visiting your organization overview in Nx Cloud
-2. Click the **Connect a repository** button
-3. Follow the prompts to connect your workspace
-4. Enable polygraph features as metadata-only workspace
-5. Click **Connect workspace** to finish
-
-Repeat process for each workspace you want to connect as metadata-only workspace.
-
-{% /tabitem %}
-{% /tabs %}

astro-docs/src/content/docs/enterprise/polygraph.mdoc

@@ -1,117 +0,0 @@
----
-title: Nx Enterprise - What is Polygraph?
-description: 'Scale development practices across multiple repositories with cross-repository visibility, automated standards enforcement, and zero-friction adoption for existing codebases.'
-sidebar:
-  order: 1
-  label: Polygraph
-filter: 'type:Features'
----
-
-No longer needing to choose between monorepo or poly-repo.
-Polygraph is Nx Cloud's suite of enterprise features designed to help organizations scale their development practices across multiple repositories. These features extend the powerful benefits of an Nx workspace to multi-workspace environments and take Nx Cloud beyond CI.
-
-## Features
-
-- **Cross-repository visibility** through the [Workspace Graph](#workspace-graph)
-- **Organizational standards enforcement** via [Conformance](#conformance) rules
-- **Automated compliance checking** across all repositories powered by [Custom Workflows](#custom-workflows)
-
-All of this can be enabled with **Zero-friction adoption** for existing repositories without requiring teams to adopt Nx or modify their workflows. With these tools, a platform engineering team is able to affect positive change across 100+ repos quickly in automated fashion, instead of being stuck with manual processes taking multiple months.
-
-{% aside type="note" title="Nx Enterprise" %}
-Polygraph features require an Nx Enterprise license. [Reach out to the team](https://nx.dev/contact/sales?utm_source=nx.dev&utm_campaign=polygraph) if you're interested in exploring enterprise!
-{%/aside %}
-
-## Use cases
-
-- **🔍 See the Big Picture**: Visualize dependencies across your entire organization, not just within individual repos. Understand organizational structure at a glance and make informed decisions about architecture and team boundaries.
-
-- **📋 Enforce Standards at Scale**: Define and automatically enforce coding standards, tooling requirements, and best practices across 10s or 100s of repositories. Eliminate manual audits and spreadsheet tracking, saving platform teams hundreds of hours per quarter.
-
-- **🛡️ Proactive Auditing and Monitoring**: Run your security tools, or any tool you prefer, on regular intervals to detect and address vulnerabilities quickly, even in repositories that haven't been touched in months.
-
-## Workspace graph
-
-Visualizes dependencies between all repositories in your organization, providing visibility into what repos depend on other repos within the organization.
-
-- **Identify consumers of shared libraries**: Enable confident API changes and deprecations by knowing exactly who will be affected
-- **Understand organizational code structure at a glance**: Help leadership make informed decisions about architecture and team boundaries
-- **Impact analysis before breaking changes**: See the blast radius of changes across your entire tech stack
-
-![Polygraph Workspace Graph](../../../assets/enterprise/polygraph/workspace-graph.avif)
-
-Quickly onboard new workspaces with the [GitHub VCS integration](/docs/features/ci-features/github-integration#access-control)
-
-![GitHub VCS onboarding](../../../assets/enterprise/polygraph/connect-polygraph-to-repos.avif)
-
-## Conformance
-
-Define and enforce consistency, maintainability, reliability and security standards across your organization.
-
-- **Gradual rule rollout**: Give teams time to fix issues, at a scheduled time, change a rule from _evaluated_ to _enforced_ automatically.
-- **Workspace coverage**: Understand which repositories and teams are subject to which rules
-- **Compliance control**: Make sure teams are keeping up with organization wide standards that they can't disable when using Nx Cloud as the registry for rules.
-
-![CIPE conformance table view](../../../assets/enterprise/polygraph/cipe-conformance-report.avif)
-
-See an overview of all rules set for the workspace and their current status
-
-![Conformance rules run Table](../../../assets/enterprise/polygraph/conformance-rule-results-table.avif)
-![Conformance rules meta table](../../../assets/enterprise/polygraph/conformance-rules-table-run-meta.avif)
-
-You can setup notifications for teams, so they're always kept in the loop
-
-![Conformance notifications](../../../assets/enterprise/polygraph/conformance-notifications.avif)
-
-Ready to write your first conformance rule? [See our conformance guide](/docs/enterprise/conformance) to start.
-
-## Custom workflows
-
-Run scheduled tasks for your needs across all or a selection of repositories.
-
-- **Scheduled execution**: Run checks on your schedule, not just when code changes—especially valuable for rarely updated repositories
-- **Notifications for failures**: Keeps responsible parties informed without requiring them to constantly check dashboards
-- **Regular compliance monitoring**: Keep security audits current even for repositories with infrequent changes
-- **Automated data collection**: Ensures your dashboards and reports always reflect current state without manual intervention
-
-Custom workflows enable proactive monitoring and automated compliance checking, ensuring your dashboards always reflect the current state without manual intervention.
-
-![custom workflows page](../../../assets/enterprise/polygraph/custom-workflow-repeating-workflows.avif)
-
-## Metadata only workspaces
-
-Gain quick visibility across your organization's repositories without needing to migrate each repository as an Nx Workspace.
-Easily onboard any repository as a **metadata-only** to immediately start contributing to the [Workspace Graph](#workspace-graph).
-Metadata-only workspaces can still leverage [custom workflows](/docs/enterprise/polygraph#custom-workflows) and [conformance rules](/docs/enterprise/conformance).
-
-Read more about [onboarding a workspace as metadata-only](/docs/enterprise/metadata-only-workspace).
-
-## FAQ
-
-**Q: Do I need to migrate other teams to Nx to use Polygraph?**
-
-No, Polygraph works with any repository through [metadata-only workspaces](/docs/enterprise/metadata-only-workspace).
-
-**Q: How does pricing work?**
-
-Existing Nx Cloud Enterprise workspaces include Polygraph at no extra cost. Additional fees apply only for metadata-only workspaces and when consuming compute credits.
-
-**Q: Can I enforce rules gradually?**
-
-Yes, rules can be set to _evaluate_ mode before enforcement, and you can schedule future enforcement dates or outright disable the rule.
-
-**Q: What are the different conformance rule statuses?**
-
-- **Evaluated**: Rule runs and reports violations in dashboards and notifications, but won't fail CI builds; therefore, it's perfect for introducing new standards gradually or giving teams time to prepare for upcoming changes.
-
-- **Enforced**: Rule runs and creates errors that will fail CI builds when violations are found, ensuring immediate compliance. You can schedule rules to automatically transition from evaluated to enforced on a specific date.
-
-- **Disabled**: Rule is turned off and won't run in any workspaces.
-
-**Q: Can I use Conformance with Nx Cloud?**
-
-Yes! Nx Enterprise plan enable conformance rules within individual workspaces. Polygraph extends this by publishing rules across your entire organization, configuring them across multiple workspaces, and tracking results at the organizational level. An Nx Cloud Enterprise license is required for Polygraph features.
-
-{% aside type="tip" title="Ready to start using Polygraph? " %}
-Existing enterprise customers should contact their assigned developer productivity engineer to get setup. Otherwise, reach out to us about [Nx Enterprise](https://nx.dev/enterprise) to unlock Polygraph's organizational scaling features.
-{%/aside %}

astro-docs/src/content/docs/extending-nx/create-preset.mdoc

@@ -14,7 +14,7 @@ This preset option is pointing to a special generator function (remember, a gene
 
 ## What is a preset?
 
-At its core, a preset is a special [generator](/docs/features/generate-code) that is shipped as part of an Nx Plugin package.
+A preset is a special [generator](/docs/features/generate-code) shipped as part of an Nx Plugin package.
 
 All first-party Nx presets are built into Nx itself, but you can [create your own plugin](/docs/extending-nx/intro) and create a generator with the magic name: `preset`. Once you've [published your plugin](/docs/extending-nx/tooling-plugin) on npm, you can now run the `create-nx-workspace` command with the preset option set to the name of your published package.
 

astro-docs/src/content/docs/extending-nx/createnodes-compatibility.mdoc

@@ -10,12 +10,13 @@ This is a reference for knowing how Nx versions and the `createNodes`/`createNod
 
 The following table shows which export Nx will call based on the Nx version:
 
-| Nx Version    | Calls `createNodes` | Calls `createNodesV2` | Nx Call Preference           |
-| ------------- | ------------------- | --------------------- | ---------------------------- |
-| 17.x - 19.1.x | Yes                 | No                    | Only v1 supported            |
-| 19.2.x - 20.x | Yes (fallback)      | Yes (preferred)       | Prefers v2, falls back to v1 |
-| 21.x          | No                  | Yes                   | Only v2 supported            |
-| 22.x+         | Yes (v2 signature)  | Yes                   | Both use v2 signature        |
+| Nx Version    | Calls `createNodes` | Calls `createNodesV2` | Nx Call Preference                                           |
+| ------------- | ------------------- | --------------------- | ------------------------------------------------------------ |
+| 17.x - 19.1.x | Yes                 | No                    | Only v1 supported                                            |
+| 19.2.x - 20.x | Yes (fallback)      | Yes (preferred)       | Prefers v2, falls back to v1                                 |
+| 21.x          | No                  | Yes                   | Only v2 supported                                            |
+| 22.x          | Yes (v2 signature)  | Yes                   | Both use v2 signature                                        |
+| 23.x+         | Yes (v2 signature)  | Yes (fallback)        | Prefers `createNodes`; `createNodesV2` is a deprecated alias |
 
 ## Which Nx versions does my plugin support?
 

astro-docs/src/content/docs/extending-nx/performant-project-graph-plugins.mdoc

@@ -0,0 +1,230 @@
+---
+title: Write a Performant Project Graph Plugin
+description: Practical patterns and caveats for writing fast createNodes plugins, including disk caching, work hoisting, and parallel config loading.
+filter: 'type:Guides'
+---
+
+Your plugin's `createNodes` function runs every time Nx computes the project graph, which happens before _any_ task is restored from cache. If it does expensive work for every matching file, that cost is paid on every command (`nx build`, `nx graph`, even editor integrations), and it is paid by every developer and every CI machine. A plugin that recomputes everything from scratch is a common cause of slow graph creation, and the cost is magnified on Windows, where filesystem and process-spawn operations are significantly more expensive than on Linux or macOS.
+
+The patterns below are the ones the first-party Nx plugins use to keep graph creation fast. They assume you're already familiar with the [project graph plugin API](/docs/extending-nx/project-graph-plugins) and have written a basic [tooling plugin](/docs/extending-nx/tooling-plugin).
+
+{% aside type="note" title="Internal helpers" %}
+Some helpers shown below (`PluginCache`, `calculateHashesForCreateNodes`) are exported from `@nx/devkit/internal`, and `workspaceDataDirectory` comes from `nx/src/utils/cache-directory`. These are lower-stability surfaces than the main `@nx/devkit` entry point, so they can change between major versions. They are the same helpers first-party plugins rely on, but if you need to support a wide range of Nx versions you can implement the equivalent behavior yourself (a content hash plus a JSON file on disk).
+{% /aside %}
+
+## Set up shared state once per batch
+
+`createNodes` hands you _all_ matching files in a single call, which lets you set up shared state once and amortize expensive work across every project. Every other pattern here depends on processing the batch together rather than file by file.
+
+Wrap your per-file logic with `createNodesFromFiles`, which fans the files out and processes them in parallel while keeping the returned results in a deterministic order:
+
+```ts
+// src/index.ts
+import {
+  CreateNodes,
+  CreateNodesContext,
+  createNodesFromFiles,
+} from '@nx/devkit';
+
+const configGlob = '**/my-tool.config.{js,ts}';
+
+export const createNodes: CreateNodes<MyPluginOptions> = [
+  configGlob,
+  async (configFiles, options, context) => {
+    // Set up shared state here, once for the whole batch (see below).
+    return await createNodesFromFiles(
+      (configFile, options, context, idx) =>
+        createNodesInternal(configFile, options, context, idx),
+      configFiles,
+      options,
+      context
+    );
+  },
+];
+```
+
+{% aside type="note" title="Export name by Nx version" %}
+On Nx 23+, `createNodes` carries this batched signature and is the export to use for new plugins. On Nx 21 and 22 the equivalent export is named `createNodesV2`. To support both, export `createNodes` and add `export const createNodesV2 = createNodes`. See the [CreateNodes API Compatibility](/docs/extending-nx/createnodes-compatibility) guide.
+{% /aside %}
+
+## Cache results to disk
+
+Most of a plugin's cost is recomputing target configuration that hasn't changed. Cache the result of processing each config file on disk, keyed by a hash of everything that can affect the output. On the next run, unchanged projects are read straight from the cache instead of being reprocessed.
+
+The hash must include every input that affects the result: the project's files, the plugin options, and any external files the config references (for example, a lockfile or a shared base config). `calculateHashesForCreateNodes` batches the workspace-context hashing for all project roots into a single call, much faster than hashing each root individually.
+
+```ts
+import { createNodesFromFiles } from '@nx/devkit';
+import {
+  PluginCache,
+  calculateHashesForCreateNodes,
+} from '@nx/devkit/internal';
+import { hashObject } from 'nx/src/devkit-internals';
+import { workspaceDataDirectory } from 'nx/src/utils/cache-directory';
+import { dirname, join } from 'node:path';
+
+export const createNodes: CreateNodes<MyPluginOptions> = [
+  configGlob,
+  async (configFiles, options, context) => {
+    // One cache file per unique set of options so different plugin
+    // configurations don't collide.
+    const optionsHash = hashObject(options);
+    const cachePath = join(
+      workspaceDataDirectory,
+      `my-plugin-${optionsHash}.hash`
+    );
+    const targetsCache = new PluginCache<MyTargets>(cachePath);
+
+    const projectRoots = configFiles.map((f) => dirname(f));
+    const hashes = await calculateHashesForCreateNodes(
+      projectRoots,
+      options,
+      context
+    );
+
+    try {
+      return await createNodesFromFiles(
+        async (configFile, options, context, idx) => {
+          const hash = hashes[idx];
+
+          if (!targetsCache.has(hash)) {
+            // Only the expensive work runs on a cache miss.
+            targetsCache.set(
+              hash,
+              await buildTargets(configFile, options, context)
+            );
+          }
+
+          return {
+            projects: {
+              [projectRoots[idx]]: { targets: targetsCache.get(hash) },
+            },
+          };
+        },
+        configFiles,
+        options,
+        context
+      );
+    } finally {
+      // Always persist, even if one file throws, so the work already
+      // done isn't lost.
+      targetsCache.writeToDisk();
+    }
+  },
+];
+```
+
+A few things to get right:
+
+- **Write the cache in a `finally` block** so a failure processing one file doesn't discard the entries computed for the others.
+- **Include referenced files in the hash.** If your config `extends` a base file or your targets depend on a lockfile, pass those paths through the `additionalGlobs` argument of `calculateHashesForCreateNodes` so a change to them invalidates the cache:
+
+  ```ts
+  const hashes = await calculateHashesForCreateNodes(
+    projectRoots,
+    options,
+    context,
+    projectRoots.map(() => [lockFileName, ...referencedConfigFiles])
+  );
+  ```
+
+- **Respect `NX_CACHE_PROJECT_GRAPH=false`.** `PluginCache` already does this: it returns an empty cache when the variable is set, which is what makes the [development overrides](#develop-and-debug-your-plugin) below work.
+
+## Hoist shared work out of the per-file loop
+
+Even with a disk cache, the first run (and any run after a change) processes files. Anything that's identical across files should be computed once per batch, not once per file. Set up in-memory caches in the `createNodes` body and pass them into your per-file function:
+
+```ts
+async (configFiles, options, context) => {
+  // Detected once for the whole workspace, not per project.
+  const packageManager = detectPackageManager(context.workspaceRoot);
+
+  // Shared across files: many projects extend the same base tsconfig or
+  // use the same preset, so read and resolve each one only once.
+  const tsconfigCache = new Map<string, RawTsconfig>();
+  const presetCache: Record<string, unknown> = {};
+
+  return await createNodesFromFiles(
+    (configFile, options, context, idx) =>
+      buildTargets(configFile, options, context, {
+        packageManager,
+        tsconfigCache,
+        presetCache,
+      }),
+    configFiles,
+    options,
+    context
+  );
+};
+```
+
+Common things worth hoisting: package-manager detection, lockfile name resolution, shared base configs, and tool presets. The `@nx/jest` plugin, for example, caches resolved presets and the tsconfig `extends` chain this way because most projects in a workspace share them.
+
+## Load configuration files in parallel
+
+When you must read or evaluate config files, do it concurrently with `Promise.all` rather than in a sequential loop. Reading config off disk is I/O-bound, and transpiling and evaluating TypeScript configs is CPU-bound. Both parallelize well:
+
+```ts
+const loadedConfigs = await Promise.all(
+  configFiles.map((configFile) =>
+    loadConfigFile(join(context.workspaceRoot, configFile))
+  )
+);
+```
+
+This matters most on Windows, where each `readFileSync`/`readdirSync` call carries more overhead, so collapsing serial I/O into parallel batches has an outsized effect.
+
+## Keep your file glob narrow
+
+The first element of the `createNodes` tuple is a glob Nx matches against the whole workspace. A broad pattern like `**/*.json` forces Nx to consider far more files and calls your function with files you'll only discard. Match the most specific filename you can:
+
+```ts
+// Prefer this
+const configGlob = '**/vite.config.{js,ts,mjs,mts,cjs,cts}';
+
+// Over a catch-all you have to filter down yourself
+const configGlob = '**/*.config.*';
+```
+
+If you can only decide whether a file is relevant after looking at its siblings (for example, requiring a `package.json` or `project.json` next to it), do that check early and `return {}` before doing any expensive work. A precise glob is still cheaper than a broad glob plus a filter.
+
+## Keep output deterministic
+
+Nx hashes the graph node your plugin produces to decide whether cached task results can be reused. If your function returns different output across runs or machines, because of array ordering, absolute paths, or environment values, Nx computes a different hash and treats unchanged code as a cache miss, defeating both your plugin cache and task caching downstream.
+
+Sort arrays (`targets`, `inputs`, `outputs`, `dependsOn`) explicitly before returning, and avoid leaking `process.env` values, absolute paths, timestamps, or random IDs into target configuration. Prefer workspace-relative tokens like `{workspaceRoot}` and `{projectRoot}`. See [Inferred Tasks](/docs/concepts/inferred-tasks) for the full set of determinism rules.
+
+## Avoid per-file process spawning and heavy top-level imports
+
+Two patterns quietly dominate graph-creation time:
+
+- **Spawning a child process per file.** If your plugin shells out to a tool to read configuration, the process-startup cost is paid for every project and is especially expensive on Windows. Batch the work into a single invocation where possible, or read the configuration directly instead of shelling out.
+- **Heavy imports at module load.** Everything imported at the top of your plugin entry point is loaded every time Nx loads the plugin, even on a full cache hit. Keep top-level imports light and `await import(...)` heavy or rarely-used dependencies inside the code path that actually needs them.
+
+## Develop and debug your plugin
+
+While iterating, disable the caching layers that would otherwise hide your changes:
+
+```shell
+# The daemon caches your plugin code, so changes won't take effect until it restarts.
+NX_DAEMON=false nx graph
+
+# Bypass the project graph cache so your createNodes logic always re-runs.
+NX_CACHE_PROJECT_GRAPH=false nx graph
+```
+
+To find where graph-creation time is actually going, turn on performance logging. Nx prints the duration of each internal step, including project-graph construction:
+
+```shell
+NX_PERF_LOGGING=true NX_DAEMON=false nx graph
+```
+
+If a user reports slow graph creation, ask them for this output along with `nx report`. The per-step timings make it clear whether the cost is in your plugin (`createNodes`) versus elsewhere, and `nx report` confirms the Nx and plugin versions in play.
+
+## Related documentation
+
+- [Extending the Project Graph](/docs/extending-nx/project-graph-plugins) - The full project graph plugin API
+- [Integrate a New Tool with a Tooling Plugin](/docs/extending-nx/tooling-plugin) - End-to-end tutorial for building a plugin
+- [CreateNodes API Compatibility](/docs/extending-nx/createnodes-compatibility) - Supporting multiple Nx versions
+- [Inferred Tasks](/docs/concepts/inferred-tasks) - How Nx builds the graph from plugins
+- [CreateNodesV2 API Reference](/docs/reference/devkit/CreateNodesV2) - Detailed API documentation

astro-docs/src/content/docs/extending-nx/project-graph-plugins.mdoc

@@ -17,6 +17,10 @@ Project graph plugins are able to add new nodes or dependencies to the project g
 When developing project graph plugins, disable the [Nx Daemon](/docs/concepts/nx-daemon) by setting `NX_DAEMON=false`. The daemon caches your plugin code, so changes to your plugin won't be reflected until the daemon restarts.
 {% /aside %}
 
+{% aside type="note" title="Writing a fast plugin" %}
+`createNodesV2` runs on every graph computation, so its cost is paid on every command. Once your plugin works, see [Write a Performant Project Graph Plugin](/docs/extending-nx/performant-project-graph-plugins) for caching and other patterns that keep graph creation fast.
+{% /aside %}
+
 ## Adding plugins to workspace
 
 You can register a plugin by adding it to the plugins array in `nx.json`:

astro-docs/src/content/docs/extending-nx/tooling-plugin.mdoc

@@ -448,6 +448,7 @@ it('should infer tasks', () => {
 
 Now that you have a working plugin, here are a few other topics you may want to investigate:
 
+- [Write a performant project graph plugin](/docs/extending-nx/performant-project-graph-plugins) with caching so graph creation stays fast
 - [Publish your Nx plugin](/docs/extending-nx/publish-plugin) to npm and the Nx plugin registry
 - [Write migration generators](/docs/extending-nx/migration-generators) to automatically account for breaking changes
 - [Create a preset](/docs/extending-nx/create-preset) to scaffold out an entire new repository

astro-docs/src/content/docs/features/CI Features/affected.mdoc

@@ -269,7 +269,7 @@ Nx provides two methods to exclude glob patterns (files and folders) from `affec
 
 ## Marking projects affected by dependency updates
 
-By default, Nx will mark all projects as affected whenever your package manager's lock file changes. This behavior is a failsafe in case Nx misses a project that should be affected by a dependency update. If you'd like to opt into smarter behavior, you can configure Nx to only mark projects as affected if they actually depend on the updated packages.
+By default, Nx will mark **all** projects as affected whenever your package manager's lock file changes. This behavior is a failsafe in case Nx misses a project that should be affected by a dependency update. You can configure this behavior with the `projectsAffectedByDependencyUpdates` option in `nx.json`:
 
 ```json
 // nx.json
@@ -282,7 +282,21 @@ By default, Nx will mark all projects as affected whenever your package manager'
 }
 ```
 
-The flag `projectsAffectedByDependencyUpdates` can be set to `auto`, `all`, or an array that contains project specifiers. The default value is `all`.
+The `projectsAffectedByDependencyUpdates` option accepts the following values:
+
+| Value      | Description                                                                                                                                                                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"all"`    | **(default)** Every project in the workspace is marked as affected when the lock file changes. This is the safest option but may result in unnecessary CI work.                                                                              |
+| `"auto"`   | Only projects whose dependencies actually changed in the lock file are marked as affected. Nx inspects the lock file structure to determine which workspace projects had their resolved dependencies change. See the note below for details. |
+| `string[]` | An array of project names or glob patterns (e.g., `["app-*", "shared-lib"]`). Only the matching projects are marked as affected when the lock file changes.                                                                                  |
+
+{% aside type="note" title="How 'auto' works per package manager" %}
+In `"auto"` mode, Nx parses both the base and head revisions of your lock file using the same parsers it uses to build the project graph, diffs the resolved package metadata to find which dependencies changed, then maps those packages back to the workspace projects that depend on them.
+
+Nx supports the following lock files: `pnpm-lock.yaml`, `pnpm-lock.yml`, `package-lock.json`, `yarn.lock`, `bun.lock`, and `bun.lockb`.
+
+For binary Bun lockfiles (`bun.lockb`), Nx asks Bun to render the lockfile before diffing it, so Bun needs to be available in the environment that runs `nx affected`.
+{% /aside %}
 
 ## Not using git
 

astro-docs/src/content/docs/features/CI Features/dedicated-compute-cluster.mdoc

@@ -0,0 +1,73 @@
+---
+title: 'Dedicated Compute Cluster'
+description: 'Reserve an isolated Nx Cloud compute environment for your organization and unlock Docker-in-Docker, sandboxing, and read-through caches.'
+keywords:
+  [
+    dedicated compute,
+    single-tenant,
+    docker-in-docker,
+    nx agents,
+    add-on,
+    nx cloud,
+  ]
+sidebar:
+  label: Dedicated compute cluster
+  order: 20
+  badge: new!
+filter: 'type:Features'
+---
+
+A **dedicated compute cluster** reserves an isolated Nx Cloud compute environment for your
+organization, so your [Nx Agents](/docs/features/ci-features/distribute-task-execution) run in a
+cluster provisioned just for your org instead of on the shared multi-tenant pool.
+
+The dedicated cluster lets agents run Docker-in-Docker (DinD) and unlocks additional Nx Cloud
+add-ons that require isolation in order to run with elevated capabilities.
+
+{% aside type="note" title="Nx Cloud add-on" %}
+The **dedicated compute cluster** is an Nx Cloud add-on. Manage it under
+**Settings > Add-ons** for your organization. Nx Enterprise customers on
+[single-tenant](/docs/enterprise/single-tenant/overview) deployments already run in a dedicated
+environment and get these capabilities through their deployment.
+{% /aside %}
+
+## What it unlocks
+
+A dedicated compute cluster unlocks the following:
+
+- [**Docker-in-Docker**](#docker-in-docker-on-agents) - build and push container images, run
+  Testcontainers, and run any task that needs a Docker daemon, directly on Nx Agents.
+- [**Sandboxing**](/docs/features/ci-features/sandboxing) - confine each task to its declared
+  [`inputs`](/docs/reference/project-configuration#inputs-and-named-inputs) and [`outputs`](/docs/reference/project-configuration#outputs), and catch any read or write outside them.
+- [**Docker layer caching**](/docs/features/ci-features/docker-layer-caching) - reuse Docker build
+  layers across CI runs.
+- [**Docker read-through cache**](/docs/features/ci-features/docker-read-through-cache) - serve
+  repeated image pulls from a cache close to your agents.
+- [**npm read-through cache**](/docs/features/ci-features/npm-read-through-cache) - serve repeated
+  npm installs from a cache close to your agents.
+
+DinD is available on every agent in the cluster automatically. The four add-ons are enabled
+individually once the cluster is active, and are cancelled if you cancel the dedicated compute
+cluster.
+
+## Docker-in-Docker on agents
+
+Every agent in a dedicated compute cluster can run DinD. This lets your tasks build and push
+container images, run [Testcontainers](https://testcontainers.com), and execute any workflow that
+needs a Docker daemon, directly on Nx Agents.
+
+On the shared multi-tenant pool, agents run a fixed set of approved images and cannot run privileged
+containers. The dedicated cluster lifts that restriction for your organization, so you can run
+custom agent images and DinD workloads.
+
+## Enabling dedicated compute cluster
+
+A dedicated compute cluster is provisioned through your organization settings:
+
+1. Open **Settings > Add-ons** for your organization.
+2. On the **Dedicated compute cluster** card, click **Request add-on** and confirm.
+3. You will be notified via email when the cluster is ready to use.
+
+Once the cluster is active, the dependent add-ons (sandboxing, Docker layer caching, and the
+read-through caches) become available to enable on the same page. If you request one of them before
+the cluster is ready, it is queued and activates automatically when the cluster comes online.

astro-docs/src/content/docs/features/CI Features/docker-layer-caching.mdoc

@@ -0,0 +1,87 @@
+---
+title: 'Docker Layer Caching'
+description: 'Cache Docker build layers across CI runs on Nx Agents to speed up image builds.'
+keywords: [docker, layer caching, buildkit, nx agents, nx cloud, add-on]
+sidebar:
+  label: Docker layer caching
+  order: 21
+  badge: new!
+filter: 'type:Features'
+---
+
+Docker layer caching reuses the intermediate layers produced by `docker build` (the result of each
+`RUN`, `COPY`, and `ADD` instruction) across CI runs. When a layer's inputs haven't changed, the
+build pulls it from a registry cache instead of rebuilding it, cutting image build times on
+[Nx Agents](/docs/features/ci-features/distribute-task-execution).
+
+## How to enable it
+
+{% aside type="note" title="Requires a dedicated compute cluster" %}
+Docker layer caching is an Nx Cloud add-on that runs on a
+[dedicated compute cluster](/docs/features/ci-features/dedicated-compute-cluster). Request the
+cluster, then enable this add-on under **Settings > Add-ons**.
+{% /aside %}
+
+You can enable Docker layer caching through your organization settings:
+
+1. Open **Settings > Add-ons** for your organization.
+2. Under **Dedicated compute cluster** card, find **Docker layer caching** and click **Request add-on** and confirm.
+
+When the add-on is enabled, Nx Cloud runs a registry cache inside your dedicated cluster and injects
+its address into every agent as the `NX_DOCKER_CACHE_REGISTRY` environment variable. You point your
+Docker builds at that registry using BuildKit's `--cache-to` and `--cache-from` flags. Cached layers
+are written to and read from the in-cluster registry, so they persist across CI runs.
+
+## Setup
+
+### 1. Set up Docker Buildx
+
+Layer caching requires BuildKit. Add the Buildx setup step to the `init-steps` of the launch
+template that runs your Docker builds, so it runs before any `docker build` command:
+
+```yaml
+- name: Setup Docker Buildx
+  uses: 'nrwl/nx-cloud-workflows/main/workflow-steps/setup-docker-buildx/main.yaml'
+```
+
+### 2. Add cache flags to your build commands
+
+Update your `docker build` commands to export and import layers from the cache registry:
+
+```bash
+docker build \
+  --push \
+  -t my-registry.example.com/my-app:1.2.3 \
+  --cache-to type=registry,ref=${NX_DOCKER_CACHE_REGISTRY}/my-app:main,mode=max \
+  --cache-from type=registry,ref=${NX_DOCKER_CACHE_REGISTRY}/my-app:main \
+  .
+```
+
+- **`-t my-registry.example.com/my-app:1.2.3`** - your image, tag, and destination registry. Your
+  agents must be authenticated to that registry to push images. That setup is outside the scope of
+  this guide.
+- **`${NX_DOCKER_CACHE_REGISTRY}`** - provided by Nx Cloud. It points at the in-cluster cache
+  registry, which is separate from your final image registry. Don't push your application images
+  there.
+- **`/my-app:main`** - the cache reference and tag. Use the `main` tag so subsequent builds reuse
+  the cached layers.
+- **`--cache-to mode=max`** - exports all layers for maximum reuse. `mode=min` exports fewer layers;
+  see the [Docker registry cache docs](https://docs.docker.com/build/cache/backends/registry).
+- **`--cache-from`** - imports cached layers when available.
+
+{% aside type="note" title="Use stable cache image " %}
+Use the stable tag `main` for `--cache-to` and `--cache-from`. Layers stored under the `main` tag are
+kept permanently. Other tags are removed periodically, so non-`main` tags won't persist as long-lived cache.
+
+Use distinct names per cache image (e.g. `my-app:main` and `my-api:main`) so different builds don't
+overwrite each other's layers.
+{% /aside %}
+
+See the [Docker registry cache docs](https://docs.docker.com/build/cache/backends/registry) for more details.
+
+### 3. Verify it's working
+
+After the cache is warm, subsequent builds should show:
+
+- `[CACHED]` markers in the `docker build` logs where layers were reused.
+- Shorter build times for unchanged layers.

astro-docs/src/content/docs/features/CI Features/docker-read-through-cache.mdoc

@@ -0,0 +1,42 @@
+---
+title: 'Docker Read-Through Cache'
+description: 'Serve repeated Docker image pulls from a cache close to your Nx Agents instead of the upstream registry.'
+keywords:
+  [
+    docker,
+    read-through cache,
+    registry mirror,
+    pull-through,
+    nx agents,
+    nx cloud,
+    add-on,
+  ]
+sidebar:
+  label: Docker read-through cache
+  order: 22
+  badge: new!
+filter: 'type:Features'
+---
+
+The Docker read-through cache puts a registry mirror close to your [Nx Agents](/docs/features/ci-features/distribute-task-execution).
+The first time an image is pulled, it is fetched from the upstream registry (for example Docker Hub)
+and stored in the cache. Repeated pulls of the same image are then served from the cache instead of
+the upstream registry, cutting image download time and reducing dependence on external registries.
+
+It also protects your organization from Docker registry outages.
+
+## How to enable it
+
+{% aside type="note" title="Requires a dedicated compute cluster" %}
+The Docker read-through cache is an Nx Cloud add-on that runs on a
+[dedicated compute cluster](/docs/features/ci-features/dedicated-compute-cluster). Request the
+cluster, then enable this add-on under **Settings > Add-ons**.
+{% /aside %}
+
+You can enable Docker read-through cache through your organization settings:
+
+1. Open **Settings > Add-ons** for your organization.
+2. Under **Dedicated compute cluster** card, find **Docker read-through cache** and click **Request add-on** and confirm.
+
+Once enabled, it works automatically. You don't change your Dockerfiles, `docker pull` commands, or
+image references. Repeated image pulls are served from the cache instead of the upstream registry.

astro-docs/src/content/docs/features/CI Features/npm-read-through-cache.mdoc

@@ -0,0 +1,65 @@
+---
+title: 'npm Read-Through Cache'
+description: 'Serve repeated npm installs from a cache close to your Nx Agents instead of the public npm registry.'
+keywords:
+  [npm, read-through cache, registry proxy, nx agents, nx cloud, add-on, npmrc]
+sidebar:
+  label: npm read-through cache
+  order: 23
+  badge: new!
+filter: 'type:Features'
+---
+
+The npm read-through cache puts a package registry proxy close to your
+[Nx Agents](/docs/features/ci-features/distribute-task-execution). The first time a package is
+requested, it is fetched from the public npm registry and stored in the cache. Repeated installs of
+the same package are then served from the cache instead of the upstream registry, cutting install
+time and external network usage. Once the cache is warm, packages often install faster than restoring
+them from `node_modules` caching.
+
+It also protects your organization from npm registry outages.
+
+## How to enable it
+
+{% aside type="note" title="Requires a dedicated compute cluster" %}
+The npm read-through cache is an Nx Cloud add-on that runs on a
+[dedicated compute cluster](/docs/features/ci-features/dedicated-compute-cluster). Request the
+cluster, then enable this add-on under **Settings > Add-ons**.
+{% /aside %}
+
+You can enable npm read-through cache through your organization settings:
+
+1. Open **Settings > Add-ons** for your organization.
+2. Under **Dedicated compute cluster** card, find **npm read-through cache** and click **Request add-on** and confirm.
+
+When the add-on is enabled, Nx Cloud runs a caching proxy in your dedicated cluster that sits in
+front of the public npm registry. You point your package manager at the proxy through an `.npmrc`
+file. Installs then flow through the cache.
+
+The cache works with **npm**, **yarn**, and **pnpm**, since they all read the `registry` setting
+from `.npmrc`.
+
+## Scope
+
+- **Public npm packages only.** The cache proxies the public npm registry.
+- **Private and scoped packages that require authentication are not cached.** Keep their existing
+  registry entries in your `.npmrc`. Those requests bypass the cache and go straight to your private
+  registry.
+
+## Configuration
+
+Point your package manager at the cache by setting the registry in an `.npmrc`. Place it in the
+project root (simplest) or in the agent's home directory (`~/.npmrc`):
+
+```ini
+# .npmrc
+registry=http://npm:4873/
+```
+
+The cache is always reachable from within your cluster at the address above.
+
+{% aside type="note" title="If you publish packages" %}
+If your CI publishes npm packages, set a publish registry so `npm publish` targets your real
+registry instead of the cache. Add `publishConfig.registry` to the package's `package.json`, or
+pass `npm publish --registry <url>`.
+{% /aside %}

astro-docs/src/content/docs/features/CI Features/resource-usage.mdoc

@@ -0,0 +1,145 @@
+---
+title: 'Resource Usage'
+description: 'Upload and view per-agent CPU and memory metrics for distributed task execution to find bottlenecks, debug out-of-memory errors, and right-size your agents.'
+keywords:
+  [
+    resource usage,
+    resource profiling,
+    CPU,
+    memory,
+    out of memory,
+    nx agents,
+    nx cloud,
+    add-on,
+  ]
+sidebar:
+  label: Resource usage
+  order: 14
+  badge: new!
+filter: 'type:Features'
+---
+
+The resource usage add-on records per-agent CPU and memory metrics during distributed task
+execution and surfaces them in Nx Cloud. Use this data to find resource bottlenecks, debug
+out-of-memory (OOM) errors, and pick the right agent size for your workload, all the way down to
+which task caused a spike.
+
+{% aside type="note" title="Nx Cloud add-on" %}
+Resource usage is a standalone Nx Cloud add-on. Enable it under **Settings > Add-ons** for your
+organization.
+{% /aside %}
+
+{% aside type="caution" title="Nx 22.1+ Required" %}
+Resource usage requires Nx 22.1 or later.
+{% /aside %}
+
+## Enabling resource usage
+
+Enable the add-on under **Settings > Add-ons**, or from the **Enable resource profiling** prompt on
+the **Analysis** tab of any CI pipeline execution.
+
+Once the add-on is active:
+
+- **With [Nx Agents](/docs/features/ci-features/distribute-task-execution) on Nx Cloud compute**, metrics are collected
+  and uploaded automatically for every agent and task. There's nothing else to configure.
+- **When you [bring your own compute](/docs/guides/nx-cloud/bring-your-own-compute)** (running the agents on your own CI),
+  add a single CLI step per agent job to upload metrics. See
+  [the section below](#resource-metrics-when-you-bring-your-own-compute).
+
+When a CI pipeline execution doesn't yet have the add-on, Nx Cloud shows a preview with sample data
+and a prompt to enable it, including a note on the
+[Self-healing CI](/docs/features/ci-features/self-healing-ci) PR comment when a run hits memory or
+CPU issues.
+
+## Viewing resource usage
+
+Open any CI pipeline execution and go to the **Analysis** tab.
+
+### Agent resource usage summary
+
+The **Agent resource usage** table lists every agent in the run with its average and maximum CPU and
+memory, plus the machine specs (cores and RAM) of its resource class. It's the fastest way to spot an
+agent that ran hot.
+
+![Agent resource usage table showing per-agent average and maximum CPU and memory](../../../../assets/guides/nx-cloud/agent-resource-usage-table.png)
+
+### Resource usage over time
+
+Click an agent to open its **Resource usage over time** view. Separate memory and CPU charts plot
+utilization across the agent's lifetime, with reference lines for the machine's capacity and peak
+usage. When a task exceeds available memory and is killed, the chart marks the out-of-memory point so
+you can trace the failure back to the task that caused it.
+
+![Resource usage over time showing memory and CPU charts by task](../../../../assets/guides/nx-cloud/resource-chart-details.png)
+
+The detail view has a few controls for digging in:
+
+- **View mode** - switch between **Individual** (each task or process plotted separately) and
+  **Stacked** (total usage at any point in time).
+
+  ![Stacked view showing total resource usage](../../../../assets/guides/nx-cloud/resource-stacked-chart-view.png)
+
+- **Reference lines** - toggle the capacity and peak-usage lines on or off.
+- **Snap to max** - zoom the axis to the peak memory or CPU value.
+- **Legend** - click items to focus on specific tasks or processes (for example a single
+  `nx build`, the Nx daemon, or CLI overhead).
+
+  ![Using the legend to focus on specific tasks](../../../../assets/guides/nx-cloud/resource-chart-legend.png)
+
+- **Timeline scrubber** - jump to a point in time or zoom in on a spike.
+
+  ![Timeline scrubber for navigating resource usage over time](../../../../assets/guides/nx-cloud/resource-chart-scrubber.jpg)
+
+- **Download CSV** - export the raw per-process data for deeper analysis.
+
+## Common use cases
+
+- **Find memory-hungry tasks** - figure out which project eats the most memory when running in
+  parallel, then lower its parallelism instead of slowing everything down.
+- **Debug OOM kills** - trace an out-of-memory failure to the exact task that caused it.
+- **Spot misconfigured tooling** - catch a bundler or build tool pulling in more files than it
+  should.
+- **Right-size agents** - pick the correct agent resource class when moving to Nx Agents from
+  GitHub Actions or another CI provider.
+- **Detect memory leaks** - look for tasks where memory keeps climbing over time.
+- **Compare before and after upgrades** - check whether a dependency upgrade spiked resource usage.
+
+## Resource metrics when you bring your own compute
+
+{% aside type="note" title="Enterprise Feature" %}
+Bringing your own compute requires the [Nx Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=bring-your-own-compute). [Nx Agents](/docs/features/ci-features/distribute-task-execution) distributes your tasks on all plans.
+{% /aside %}
+
+If you run the agents on your own CI compute, Nx Cloud can still collect per-agent CPU and
+memory metrics. Opt in by adding a single CLI step to each agent job.
+
+### What to add
+
+At the end of each agent job, run `npx nx-cloud upload-agent-metrics`. Use your provider's
+always-run mechanism so the step runs even when the agent is killed mid-task, which is precisely the
+scenario where the metrics matter most.
+
+Here's the GitHub Actions step:
+
+```yaml
+- name: Upload agent metrics
+  if: always()
+  run: npx nx-cloud upload-agent-metrics
+  env:
+    NX_AGENT_NAME: ${{ matrix.agent }}
+```
+
+The `if: always()` condition is important: if an agent is OOM-killed mid-run, the normal step
+sequence stops, but the upload still needs to happen so you can see which task caused the kill.
+
+The [bring your own compute guide](/docs/guides/nx-cloud/bring-your-own-compute) shows the equivalent step for CircleCI,
+Azure Pipelines, Bitbucket Pipelines, GitLab CI, and Jenkins.
+
+## Configuration
+
+Metric collection is controlled by these environment variables:
+
+| Variable                              | Description                                                                      |
+| ------------------------------------- | -------------------------------------------------------------------------------- |
+| `NX_CLOUD_DISABLE_METRICS_COLLECTION` | Set to `true` to disable CPU and memory metric collection during task execution. |
+| `NX_CLOUD_METRICS_DIRECTORY`          | Directory where Nx writes resource metrics during task execution.                |

astro-docs/src/content/docs/features/CI Features/sandboxing.mdoc

@@ -1,24 +1,27 @@
 ---
 title: 'Task Sandboxing'
-description: 'Hermetic task execution with IO tracing to catch undeclared dependencies and ensure correct caching.'
-keywords: [sandboxing, CI, hermeticity, IO tracing, caching]
+description: 'Confine each task to its declared inputs and outputs to catch undeclared dependencies and keep caching correct.'
+keywords: [sandboxing, CI, hermeticity, inputs, outputs, caching]
 sidebar:
-  label: Sandboxing
+  label: Task sandboxing
   order: 15
   badge: new!
 filter: 'type:Features'
 ---
 
-Task sandboxing monitors file system access during task execution and flags any reads or writes
-that fall outside the declared `inputs` and `outputs` in your
+Task sandboxing confines each task to the files it declares as `inputs` and `outputs` in your
 [project configuration](/docs/reference/project-configuration)
 (whether explicit or [inferred](/docs/concepts/inferred-tasks)).
-It doesn't block access to the rest of the file system, but undeclared dependencies have direct
-implications on [caching](/docs/features/cache-task-results) correctness, from false cache hits
-serving stale results to missing output files after a cache restore.
+Reading a file the task didn't declare, or writing outside its declared outputs, is a sandbox
+violation.
+Undeclared dependencies have direct implications on [caching](/docs/features/cache-task-results)
+correctness, from false cache hits serving stale results to missing output files after a cache
+restore.
 
-{% aside type="note" title="Enterprise Feature" %}
-Sandboxing is currently available on the [Nx Enterprise plan](https://nx.dev/enterprise). We're working on rolling it out to other Nx Cloud plans starting June 1st. If you'd like to use it sooner, [reach out to learn more](https://nx.dev/enterprise).
+{% aside type="note" title="Nx Cloud add-on" %}
+Sandboxing is an Nx Cloud add-on that runs on a
+[dedicated compute cluster](/docs/features/ci-features/dedicated-compute-cluster). Request the
+cluster, then enable sandboxing under **Settings > Add-ons**.
 {% /aside %}
 
 {% aside type="caution" title="Nx 22.6+ Required" %}
@@ -101,14 +104,10 @@ Include both directories in `outputs` so they can be replayed from cache:
 
 ## How sandboxing works
 
-Sandboxing runs each task in a monitored environment where all file system reads and writes are
-tracked.
-When a task accesses a file outside its declared inputs or writes to a path outside its declared
-outputs, Nx Cloud flags it.
-
+Sandboxing runs each task in an isolated environment scoped to its declared `inputs` and `outputs`.
 You get an audit trail of every file each task touched during execution, warnings when tasks have
-undeclared dependencies, and confidence that your cache configuration is correct rather than just
-"working so far."
+undeclared dependencies, and confidence that your cache configuration is correct rather than only
+appearing to work.
 
 In **Warning** mode (recommended when getting started), violations are reported in the Nx Cloud UI
 but tasks continue to completion.
@@ -138,7 +137,7 @@ Files flagged as "unexpected read" or "unexpected write" are the ones not covere
 
 ![Sandbox analysis tab showing process tree with unexpected reads and writes highlighted](../../../../assets/features/sandboxing-analysis.png)
 
-To export the raw trace data for further analysis, click **View raw sandbox report** to download
+To export the raw report data for further analysis, click **View raw sandbox report** to download
 the JSON report.
 
 ![View raw sandbox report button](../../../../assets/features/sandboxing-raw-report.png)
@@ -147,6 +146,21 @@ Once you have identified the violating tasks, follow
 [Fix sandbox violations](/docs/guides/nx-cloud/fix-sandbox-violations)
 to download every report on a branch, classify each violation, and update your project configuration in a structured loop.
 
+## Sandbox violations dashboard
+
+For an organization-wide view, open **Analytics > Sandbox violations** for your workspace.
+It summarizes the most recent report for each task over a time window (the last 7 days by default)
+with two tiles, **Tasks with violations** and **Clean tasks**, and a table of every task showing its
+count of unexpected reads and writes and when it was last seen.
+Filter by branch or task to narrow it down.
+
+The **How to fix these violations** panel offers two paths.
+**Fix with AI** copies a ready-made prompt for your coding agent that downloads the reports, edits
+the task config, and validates before stopping.
+The manual path gives you the equivalent command sequence.
+Either way, [Fix sandbox violations](/docs/guides/nx-cloud/fix-sandbox-violations) walks through the
+full loop.
+
 ## Inspecting inputs and outputs
 
 Check what your tasks currently declare before enabling sandboxing.
@@ -225,11 +239,18 @@ and reports discrepancies.
 
 ## Enabling sandboxing
 
-Sandboxing is available for [Nx Enterprise](https://nx.dev/enterprise) customers on
-[single-tenant](/docs/enterprise/single-tenant/overview) deployments using
+Sandboxing requires a
+[dedicated compute cluster](/docs/features/ci-features/dedicated-compute-cluster) and runs on
 [Nx Agents](/docs/features/ci-features/distribute-task-execution).
-It is not supported with [manual distributed task execution](/docs/guides/nx-cloud/manual-dte).
-Contact your Nx Enterprise representative to enable sandboxing for your deployment.
+It is not supported when you [bring your own compute](/docs/guides/nx-cloud/bring-your-own-compute).
+
+1. Request a dedicated compute cluster under **Settings > Add-ons**, if you don't already have one.
+2. Enable **Sandboxing** on the same page. If the cluster is still being provisioned, sandboxing is
+   queued and activates automatically once the cluster is ready.
+
+Nx Enterprise [single-tenant](/docs/enterprise/single-tenant/overview) customers already run on a
+dedicated environment.
+Contact your Nx representative to turn on sandboxing for your deployment.
 
 ### Excluding paths
 
@@ -259,22 +280,15 @@ Patterns use glob syntax relative to the workspace root.
 
 ## Cloud settings
 
-Enterprise customers with sandboxing enabled can configure the enforcement mode in the Nx Cloud
-workspace settings under **Settings > General**.
+Once sandboxing is enabled, configure the enforcement mode in the Nx Cloud workspace settings under
+**Settings > General**.
 
 ![Nx Cloud settings sidebar showing General settings](../../../../assets/features/sandboxing-settings-sidebar.png)
 
 Three enforcement modes are available:
 
-- **Strict** — tasks that violate sandbox isolation fail immediately.
-- **Warning** — tasks complete but violations are reported in the Nx Cloud UI.
-- **Off** — sandboxing is disabled.
+- **Strict** - tasks that violate sandbox isolation fail immediately.
+- **Warning** - tasks complete but violations are reported in the Nx Cloud UI.
+- **Off** - sandboxing is disabled.
 
 ![Sandboxing enforcement mode setting with Strict, Warning, and Off options](../../../../assets/features/sandboxing-settings.png)
-
-## Learn more
-
-- [Cache task results](/docs/features/cache-task-results)
-- [Remote cache](/docs/features/ci-features/remote-cache)
-- [Project configuration reference](/docs/reference/project-configuration)
-- [Nx Enterprise](https://nx.dev/enterprise)

astro-docs/src/content/docs/features/CI Features/self-healing-ci.mdoc

@@ -153,8 +153,8 @@ pipelines:
 
 > NOTE: If all tasks succeed then the `fix-ci` command becomes a no-op automatically, so that is why "always" is recommended.
 
-{% aside type="note" title="Using manual DTE?" %}
-If you use [manual distributed task execution](/docs/guides/nx-cloud/manual-dte) instead of the Nx Agents, Self-Healing CI works the same way. Add `nx fix-ci` to both the **main job** (the orchestrator) and each **agent job** with the appropriate "always run" condition. See the [manual DTE guide](/docs/guides/nx-cloud/manual-dte) for complete examples.
+{% aside type="note" title="Bringing your own compute?" %}
+Bringing your own compute requires the [Nx Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=bring-your-own-compute). When you run the agents on your own CI, Self-Healing CI works the same way. Add `nx fix-ci` to both the **main job** (the orchestrator) and each **agent job** with the appropriate "always run" condition. See the [bring your own compute guide](/docs/guides/nx-cloud/bring-your-own-compute) for complete examples.
 {% /aside %}
 
 ## Configuring self-healing CI

astro-docs/src/content/docs/features/automate-updating-dependencies.mdoc

@@ -12,91 +12,129 @@ src="https://youtu.be/A0FjwsTlZ8A"
 title="How Automated Code Migrations Work"
 /%}
 
-Keeping your tooling up to date is crucial for the health of your project. Tooling maintenance work can be tedious and time consuming, though. The **Nx migrate** functionality provides a way for you to
+Keeping your tooling up to date is a tedious and time-consuming part of maintaining any project. The `nx migrate` command automates that work by:
 
-- automatically update your **`package.json` dependencies**
-- migrate your **configuration files** (e.g. Jest, ESLint, Nx config)
-- **adjust your source code** to match the new versions of packages (e.g., migrating across breaking changes)
+- Updating your `package.json` dependencies.
+- Updating your configuration files (e.g. Vite, Playwright, Nx config).
+- Updating your source code to match the new versions of packages (e.g., migrating across breaking changes).
 
-To update your workspace, run:
+The command guides you through the update interactively:
 
 ```shell
-npx nx@latest migrate latest
+nx migrate
 ```
 
-{% aside type="note" title="Visual migration tool from Nx Console" %}
-Want a more visual and guided way to migrate? Check out the [Migrate UI](/docs/guides/nx-console/console-migrate-ui) that comes with the [Nx Console extension](/docs/getting-started/editor-setup).
-{% /aside %}
+## How Nx migrate works
 
-## How does it work?
+Nx knows where its configuration files are located and ensures they match the expected format. This automated update process is commonly referred to as "migration." Each [Nx plugin](/docs/plugin-registry) can provide migrations for its area of competency. For example, the Vite plugin ships migrations that update Vite configuration files across breaking changes. When you run `nx migrate`, Nx collects the pending migrations from all the plugins you have installed and applies the necessary changes to your workspace.
 
-Nx knows where its configuration files are located and ensures they match the expected format. This automated update process, commonly referred to as "migration," becomes even **more powerful when you leverage [Nx plugins](/docs/plugin-registry)**. Each plugin can provide migrations for its area of competency.
+## Migration steps
 
-For example, the [Nx React plugin](/docs/technologies/react/introduction) knows where to look for React and Nx specific configuration files and knows how to apply certain changes when updating to a given version of React.
+Updating your Nx workspace happens in two phases:
 
-In the example below, the React plugin defines a migration script (`./src/migrations/.../add-babel-core`) that runs when upgrading to Nx `16.7.0-beta.2` (or higher).
+1. **Generate** - `nx migrate` applies the package version updates to your `package.json` and writes a `migrations.json` file. No source code is touched yet.
+2. **Run** - `nx migrate --run-migrations` runs the generated migrations to update your configuration files and source code.
 
-```json {% meta="{7,8}" %}
-// migrations.json
-{
-  "generators": {
-    ...
-    "add-babel-core": {
-       ...
-      "version": "16.7.0-beta.2",
-      "implementation": "./src/migrations/update-16-7-0/add-babel-core"
-    },
-  },
-}
-```
+You can intervene between the phases and make adjustments as needed for your specific workspaces. This is especially important in large codebases where you might want to control the changes more granularly.
 
-When running `nx migrate latest`, Nx parses all the available plugins and their migration files and applies the necessary changes to your workspace.
+### Step 1: Generate migrations
 
-## How do i upgrade my Nx workspace?
-
-Updating your Nx workspace happens in three steps:
-
-1. The **installed dependencies**, including the `package.json` and `node_modules`, are updated.
-2. Nx produces a `migrations.json` file containing the **migrations to be run** based on your workspace configuration. You can inspect and adjust the file. Run the migrations to update your configuration files and source code.
-3. Optionally, you can remove the `migrations.json` file or keep it to re-run the migration in different Git branches.
-
-You can intervene at each step and make adjustments as needed for your specific workspaces. This is especially important in large codebases where you might want to control the changes more granularly.
-
-### Step 1: update dependencies and generate migrations
-
-First, run the `migrate` command:
+Run the `migrate` command and follow the prompts:
 
 ```shell
-nx migrate latest
+nx migrate
 ```
 
-Note you can also specify an exact version by replacing `latest` with `nx@<version>`.
+Nx resolves the latest version and, when the update crosses more than one major version, asks how far to jump. Updating [one major version at a time](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps) is the safest path and is what Nx recommends.
 
-{% aside title="Update One Major Version at a Time" %}
-To avoid potential issues, it is [recommended to update one major version of Nx at a time](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps).
-{% /aside %}
+Nx also asks which package versions to migrate. The answer maps to the `--include` flag:
+
+- `required` - the target package and the packages it ships with. For example, Nx itself and its plugins such as `@nx/vite`.
+- `optional` - the dependency updates those packages recommend. For example, `vite` itself rather than `@nx/vite`.
+- `all` - both of the above.
+
+When unsure, choose `required`. Updating only Nx and its plugins keeps the PR scope small and has less chance of introducing issues, which matters most in large workspaces. Follow up with `nx migrate --include=optional` to catch up on the rest. If you're okay with doing everything in one PR, use `--include=all`.
+
+In some cases you can scope the optional catch-up to a single plugin's dependencies, such as `nx migrate @nx/vite --include=optional` - see [choosing which packages to migrate](/docs/guides/tips-n-tricks/advanced-update#choosing-which-packages-to-migrate) for the caveat.
 
 This results in:
 
-- The `package.json` being updated
+- The `package.json` being updated with the new package versions
 - A `migrations.json` being generated if there are pending migrations.
 
 At this point, no packages have been installed, and no other files have been touched.
 
-Now, you can **inspect `package.json` to see if the changes make sense**. Sometimes the migration can update a package to a version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments. Also look at the `migrations.json` for the type of migrations that are going to be applied.
+Now, inspect `package.json` to see if the changes make sense. Sometimes the migration can update a package to a version that is either not allowed or conflicts with another package. You are free to adjust versions before running install.
+
+{% tabs syncKey="install-type" %}
+{% tabitem label="npm" %}
+
+```shell
+npm install
+```
+
+{% /tabitem %}
+{% tabitem label="yarn" %}
+
+```shell
+yarn install
+```
+
+{% /tabitem %}
+{% tabitem label="pnpm" %}
+
+```shell
+pnpm install
+```
+
+{% /tabitem %}
+{% tabitem label="bun" %}
+
+```shell
+bun install
+```
+
+{% /tabitem %}
+{% /tabs %}
+
+Also, look at the `migrations.json` file for the type of migrations that are going to be applied. If this file does not exist, then there are no migrations to run.
 
 ### Step 2: Run migrations
 
-You can now run the actual code migrations that were generated in the `migrations.json` in the previous step.
+Run the migrations that were generated in the previous step (`migrations.json`):
 
 ```shell
 nx migrate --run-migrations
 ```
 
-Depending on the migrations that ran, this might **update your source code** and **configuration files** in your workspace. All the changes will be unstaged ready for you to review and commit yourself.
+#### What's in a migration?
+
+Migrations run one at a time and contain two types of changes:
+
+1. **Generator-based** ("script-based"): programmatic config or code changes (e.g. `rollupOptions` becomes `rolldownOptions` in `vite.config.ts` for Vite 8).
+2. **Prompt-based**: AI-aided changes that can't be expressed deterministically and need judgment about your specific code.
+
+A migration can be **generator-only**, **prompt-only**, or a **hybrid** (a generator followed by AI-aided changes).
+
+#### Running the migrations
+
+Generator-only migrations run automatically. All the changes are unstaged ready for you to review.
+
+When prompt-only or hybrid migrations are queued and a supported AI agent is installed (Claude Code, OpenAI Codex, or OpenCode), Nx asks whether to continue with an agentic flow. You can answer for this run only, or have Nx remember your choice in `nx.json`. With the agentic flow enabled:
+
+- Generator-based changes run first, and the agent validates the results.
+- The agent then applies the prompt-based changes as instructed in the prompt.
+
+Nx creates a commit for each migration while the agentic flow is enabled, so the agent reviews each migration's changes in isolation.
+
+Without an agent, generator-only migrations and the generator half of hybrid migrations still run. The skipped prompt files are listed in the next-steps output, in order, so you can apply them yourself.
+
+{% aside type="note" title="Running inside an AI agent" %}
+If you run `nx migrate --run-migrations` from within an AI agent's terminal, Nx defers the prompt-based migrations to that agent instead of spawning another one.
+{% /aside %}
 
 {% aside type="tip" title="Migrations are version specific" %}
-Note that each Nx plugin is able to provide a set of migrations which are relevant to particular versions of the package. Hence `migrations.json` will only contain migrations which are appropriate for the update you are currently applying.
+Each Nx plugin provides migrations that are relevant to particular versions of the package. The generated `migrations.json` only contains the migrations appropriate for the update you are currently applying.
 {% /aside %}
 
 ### Step 3: Clean up
@@ -119,14 +157,31 @@ For a list of all the plugins you currently have installed, run:
 nx report
 ```
 
+## Configure migrate defaults
+
+Set workspace-wide defaults for `nx migrate` in the `migrate` section of `nx.json` instead of passing the same flags on every run. You can control commit behavior, package selection, multi-major version handling, and the agentic flow:
+
+```json
+// nx.json
+{
+  "migrate": {
+    "agentic": "claude-code",
+    "createCommits": true,
+    "commitPrefix": "chore(repo): apply nx migration "
+  }
+}
+```
+
+For all available options, see the [`migrate` section of the `nx.json` reference](/docs/reference/nx-json#migrate).
+
 ## Keep Nx packages on the same version
 
 When you run `nx migrate`, the `nx` package and all the `@nx/` packages get updated to the same version. It is important to [keep these versions in sync](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync) to have Nx work properly.
 
 As long as you run `nx migrate` instead of manually changing the version numbers, you shouldn't have to worry about it. Also, when you add a new plugin, use `nx add <plugin>` to automatically install the version that matches your repository's version of Nx.
 
-## Need to opt-out of some migrations?
+## Need more control?
 
-Sometimes you need to temporarily opt-out from some migrations because your workspace is not ready yet. You can manually adjust the `migrations.json` or run the update with the `--interactive` flag to choose which migrations you accept.
+Sometimes you need to deviate from the defaults: skip optional package updates and catch them up later, pin a specific AI agent or disable the agentic flow, run migrations one at a time, or opt out of specific migrations by adjusting `migrations.json`.
 
-Find more details in our [Advanced Update Process](/docs/guides/tips-n-tricks/advanced-update) guide.
+Find all of these in our [Advanced Update Process](/docs/guides/tips-n-tricks/advanced-update) guide.

astro-docs/src/content/docs/getting-started/Tutorials/angular-monorepo-tutorial.mdoc

@@ -516,7 +516,7 @@ Not all tasks might be cacheable though. You can configure the `cache` settings
 
 Here are some things you can dive into next:
 
-- [Set up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial) with remote caching and self-healing
+- [Set up CI](/docs/getting-started/setup-ci) with remote caching and self-healing
 - Read more about [how Nx compares to the Angular CLI](/docs/technologies/angular/guides/nx-and-angular)
 - Learn more about the [underlying mental model of Nx](/docs/concepts/mental-model)
 - Learn about popular generators such as [how to setup Tailwind](/docs/technologies/angular/guides/using-tailwind-css-with-angular-projects)

astro-docs/src/content/docs/getting-started/Tutorials/caching.mdoc

@@ -5,7 +5,7 @@ sidebar:
   order: 5
 ---
 
-{% llm_copy_prompt title="Tutorial 5/8: Enable and configure caching" %}
+{% llm_copy_prompt title="Tutorial 5/7: Enable and configure caching" %}
 Help me set up caching in my Nx workspace.
 Use my existing workspace and projects for hands-on examples.
 
@@ -31,7 +31,6 @@ The examples below use Vite and Vitest, but the concepts apply to any tool. Subs
 5. **Caching** (you are here)
 6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
 7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
-8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)
 
 {% /aside %}
 
@@ -54,7 +53,7 @@ Caching is opt-in per task. The recommended approach is to set `cache: true` in
 
 You can also enable caching per-project in `package.json` or `project.json`:
 
-{% tabs %}
+{% tabs syncKey="project-config-file" %}
 {% tabitem label="package.json" %}
 
 ```jsonc
@@ -156,6 +155,45 @@ Local cache is stored in `.nx/cache` by default. Run `nx reset` to clear all loc
 }
 ```
 
+When a single project needs an extra input on top of the shared defaults, add it per project with the spread token (`"..."`):
+
+{% tabs syncKey="project-config-file" %}
+{% tabitem label="package.json" %}
+
+```jsonc
+// apps/my-app/package.json
+{
+  "nx": {
+    "targets": {
+      "build": {
+        "inputs": ["...", "{projectRoot}/src/**/*.json"],
+        "outputs": ["{projectRoot}/dist"],
+      },
+    },
+  },
+}
+```
+
+{% /tabitem %}
+{% tabitem label="project.json" %}
+
+```jsonc
+// apps/my-app/project.json
+{
+  "targets": {
+    "build": {
+      "inputs": ["...", "{projectRoot}/src/**/*.json"],
+      "outputs": ["{projectRoot}/dist"],
+    },
+  },
+}
+```
+
+{% /tabitem %}
+{% /tabs %}
+
+The `"..."` in `inputs` expands to the inputs already set in `targetDefaults`, so this project keeps `{projectRoot}/src/**/*` and `{projectRoot}/tsconfig.json` and adds `{projectRoot}/src/**/*.json`. The `outputs` array has no spread token, so it replaces the default. For the full reference, see [spread token](/docs/reference/project-configuration#spread-token).
+
 ### Smart defaults
 
 Nx provides sensible defaults out of the box. For example, test specification files (like `*.spec.ts`) are typically excluded from build inputs because changing a test shouldn't invalidate the build cache. This is configured through [named inputs](/docs/reference/inputs):
@@ -220,7 +258,7 @@ This command guides you through creating a free Nx Cloud account and stores an a
 
 When a teammate or CI pipeline has already run a task with the same inputs, you get the cached result instantly, even on a fresh checkout.
 
-For more on how remote caching works, see [remote cache (Nx Replay)](/docs/features/ci-features/remote-cache). To set up CI with Nx Cloud, see [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial).
+For more on how remote caching works, see [remote cache (Nx Replay)](/docs/features/ci-features/remote-cache). To set up CI with Nx Cloud, see [Setting up CI](/docs/getting-started/setup-ci).
 
 ## Learn more
 

astro-docs/src/content/docs/getting-started/Tutorials/configuring-tasks.mdoc

@@ -5,7 +5,7 @@ sidebar:
   order: 3
 ---
 
-{% llm_copy_prompt title="Tutorial 3/8: Configure tasks for your projects" %}
+{% llm_copy_prompt title="Tutorial 3/7: Configure tasks for your projects" %}
 Help me configure tasks (build, test, lint, serve) for my Nx workspace projects.
 Use my existing workspace and projects for hands-on examples.
 
@@ -29,7 +29,6 @@ The examples below use Vite and Vitest, but the concepts apply to any tool. Subs
 5. [Caching](/docs/getting-started/tutorials/caching)
 6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
 7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
-8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)
 
 {% /aside %}
 
@@ -114,7 +113,7 @@ The `^` prefix means "the same task on projects this project depends on." So `nx
 
 You can also define dependencies without `^` for tasks within the same project:
 
-{% tabs %}
+{% tabs syncKey="project-config-file" %}
 {% tabitem label="package.json" %}
 
 ```jsonc
@@ -161,7 +160,7 @@ Here, `build` always runs `generate-api-types` first within the same project.
 
 Some tasks, like development servers, never exit. If another task depends on a long-running process, it would wait forever. Mark these tasks as `continuous` so Nx starts them alongside their dependents instead of waiting for them to finish:
 
-{% tabs %}
+{% tabs syncKey="project-config-file" %}
 {% tabitem label="package.json" %}
 
 ```jsonc
@@ -229,6 +228,47 @@ When many projects share the same task configuration, defining it in every `proj
 
 Individual projects can still override these defaults when needed. The cascade order is: project-level config > target defaults > defaults.
 
+### Extending target defaults for a project
+
+By default, when a project redefines a property it replaces the target default entirely. So if `build` defaults to `dependsOn: ["^build"]` and a project sets its own `dependsOn`, the `^build` entry is lost.
+
+Use the spread token (`"..."`) to extend that configuration rather than replace it:
+
+{% tabs syncKey="project-config-file" %}
+{% tabitem label="package.json" %}
+
+```jsonc
+// apps/my-app/package.json
+{
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": ["...", "generate-api-types"],
+      },
+    },
+  },
+}
+```
+
+{% /tabitem %}
+{% tabitem label="project.json" %}
+
+```jsonc
+// apps/my-app/project.json
+{
+  "targets": {
+    "build": {
+      "dependsOn": ["...", "generate-api-types"],
+    },
+  },
+}
+```
+
+{% /tabitem %}
+{% /tabs %}
+
+The `"..."` expands to whatever configuration the target already has, so here `my-app`'s `build` keeps `^build` and adds `generate-api-types`. That existing configuration can come from `targetDefaults` or a plugin's inferred task, not only from target defaults. The token also works in objects and configurations. For the full reference, see [spread token](/docs/reference/project-configuration#spread-token).
+
 For more on reducing configuration, see [Reducing Configuration Boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate).
 
 ## Learn more

astro-docs/src/content/docs/getting-started/Tutorials/crafting-your-workspace.mdoc

@@ -5,7 +5,7 @@ sidebar:
   order: 1
 ---
 
-{% llm_copy_prompt title="Tutorial 1/8: Set up an Nx workspace" %}
+{% llm_copy_prompt title="Tutorial 1/7: Set up an Nx workspace" %}
 Help me learn Nx step by step using this tutorial series.
 
 If my current directory already has nx.json, skip setup and teach me using my existing workspace.
@@ -32,7 +32,6 @@ Nx works with any repo structure and plays well with tools you already use: pnpm
 5. [Caching](/docs/getting-started/tutorials/caching)
 6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
 7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
-8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)
 
 {% /aside %}
 

astro-docs/src/content/docs/getting-started/Tutorials/managing-dependencies.mdoc

@@ -5,7 +5,7 @@ sidebar:
   order: 2
 ---
 
-{% llm_copy_prompt title="Tutorial 2/8: Understand project dependencies" %}
+{% llm_copy_prompt title="Tutorial 2/7: Understand project dependencies" %}
 Help me understand how my Nx workspace tracks dependencies between projects.
 Use my existing workspace and projects for hands-on examples.
 
@@ -29,7 +29,6 @@ As your workspace grows, projects start depending on each other and on external
 5. [Caching](/docs/getting-started/tutorials/caching)
 6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
 7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
-8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)
 
 {% /aside %}
 

astro-docs/src/content/docs/getting-started/Tutorials/react-monorepo-tutorial.mdoc

@@ -479,7 +479,7 @@ Not all tasks might be cacheable though. You can configure the `cache` settings
 
 Here are some things you can dive into next:
 
-- [Set up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial) with remote caching and self-healing
+- [Set up CI](/docs/getting-started/setup-ci) with remote caching and self-healing
 - Learn more about the [underlying mental model of Nx](/docs/concepts/mental-model)
 - Learn how to [migrate your existing project to Nx](/docs/guides/adopting-nx/adding-to-existing-project)
 - [Setup Storybook for our shared UI library](/docs/technologies/test-tools/storybook/guides/overview-react)

astro-docs/src/content/docs/getting-started/Tutorials/reducing-configuration-boilerplate.mdoc

@@ -5,7 +5,7 @@ sidebar:
   order: 7
 ---
 
-{% llm_copy_prompt title="Tutorial 7/8: Reduce configuration with plugins" %}
+{% llm_copy_prompt title="Tutorial 7/7: Reduce configuration with plugins" %}
 Help me reduce configuration boilerplate in my Nx workspace.
 Use my existing workspace and projects for hands-on examples.
 
@@ -31,7 +31,6 @@ The examples below use Vite and Vitest, but the concepts apply to any tool. Subs
 5. [Caching](/docs/getting-started/tutorials/caching)
 6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
 7. **Reducing boilerplate** (you are here)
-8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)
 
 {% /aside %}
 
@@ -41,7 +40,7 @@ This tutorial assumes you have an Nx workspace with configured tasks. If you're
 
 Consider a workspace with 20 libraries, each with verbose task configuration:
 
-{% tabs %}
+{% tabs syncKey="project-config-file" %}
 {% tabitem label="package.json" %}
 
 ```jsonc
@@ -127,7 +126,7 @@ Move shared configuration to `nx.json` so projects inherit defaults:
 
 Now each project only needs to specify what's unique:
 
-{% tabs %}
+{% tabs syncKey="project-config-file" %}
 {% tabitem label="package.json" %}
 
 ```jsonc
@@ -357,6 +356,43 @@ Task configuration can come from three sources, applied in this order:
 
 Each layer can override the previous one. This means you can use plugins for sensible defaults and only add project-level config when a project needs something different.
 
+Overriding replaces the inherited value. When a project needs to add to that configuration instead, whether it comes from `targetDefaults` or an inferred plugin task, use the spread token (`"..."`):
+
+{% tabs syncKey="project-config-file" %}
+{% tabitem label="package.json" %}
+
+```jsonc
+// packages/my-lib/package.json
+{
+  "nx": {
+    "targets": {
+      "build": {
+        "inputs": ["...", "{projectRoot}/extra.config.ts"],
+      },
+    },
+  },
+}
+```
+
+{% /tabitem %}
+{% tabitem label="project.json" %}
+
+```jsonc
+// packages/my-lib/project.json
+{
+  "targets": {
+    "build": {
+      "inputs": ["...", "{projectRoot}/extra.config.ts"],
+    },
+  },
+}
+```
+
+{% /tabitem %}
+{% /tabs %}
+
+Here `"..."` expands to the `inputs` already inferred for `build`, so the project keeps them and adds `{projectRoot}/extra.config.ts`. For the full reference, see [spread token](/docs/reference/project-configuration#spread-token).
+
 ## This is optional
 
 Plugins are optional. The explicit task configuration from [Configuring Tasks](/docs/getting-started/tutorials/configuring-tasks) works perfectly well. Use plugins when:
@@ -380,5 +416,5 @@ Stick with explicit configuration when:
 
 {% cards cols=2 %}
 {% card title="Previous: Understanding Your Workspace" description="Explore projects, graphs, and debug issues" url="/docs/getting-started/tutorials/understanding-your-workspace" /%}
-{% card title="Next: Setting Up CI" description="Configure CI with remote caching and self-healing" url="/docs/getting-started/tutorials/self-healing-ci-tutorial" /%}
+{% card title="Set Up CI" description="Connect Nx Cloud for remote caching and self-healing CI" url="/docs/getting-started/setup-ci" /%}
 {% /cards %}

astro-docs/src/content/docs/getting-started/Tutorials/running-tasks.mdoc

@@ -5,7 +5,7 @@ sidebar:
   order: 4
 ---
 
-{% llm_copy_prompt title="Tutorial 4/8: Run tasks across your workspace" %}
+{% llm_copy_prompt title="Tutorial 4/7: Run tasks across your workspace" %}
 Help me run tasks in my Nx workspace efficiently.
 Use my existing workspace and projects for hands-on examples.
 
@@ -29,7 +29,6 @@ The examples below use Vite and Vitest, but the concepts apply to any tool. Subs
 5. [Caching](/docs/getting-started/tutorials/caching)
 6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
 7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
-8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)
 
 {% /aside %}
 

astro-docs/src/content/docs/getting-started/Tutorials/self-healing-ci-tutorial.mdoc

@@ -1,174 +0,0 @@
----
-title: 'Setting Up CI'
-description: Configure CI for your Nx workspace with remote caching, affected commands, distributed task execution, and self-healing to keep your pipeline fast and reliable.
-sidebar:
-  label: 'Setting Up CI'
-filter: 'type:Guides'
----
-
-{% llm_copy_prompt title="Tutorial 8/8: Set up CI with Nx Cloud" %}
-Help me set up CI for my Nx workspace.
-
-Connect to Nx Cloud with `nx connect`, generate a CI workflow with `nx g @nx/workspace:ci-workflow`, and walk me through remote caching, affected commands, and self-healing CI.
-
-Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.
-
-Tutorial: {pageUrl}
-{% /llm_copy_prompt %}
-
-Connect your workspace to Nx Cloud, generate a CI workflow, and enable remote caching, affected commands, distributed task execution, and self-healing to keep your pipeline fast and reliable.
-
-{% aside type="note" title="Tutorial Series" %}
-
-1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
-2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
-3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
-4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
-5. [Caching](/docs/getting-started/tutorials/caching)
-6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
-7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
-8. **Setting up CI** (you are here)
-
-{% /aside %}
-
-This tutorial assumes you have a [GitHub account](https://github.com) and [Node.js](https://nodejs.org) v20.19 or later.
-
-## Connect to Nx Cloud
-
-### Don't have a workspace yet?
-
-Learn how to create a new workspace and connect it to Nx Cloud:
-
-{% call_to_action variant="default" title="Set up a new Nx workspace" url="https://cloud.nx.app/get-started?utm_source=nx-dev&utm_medium=ci-tutorial&utm_campaign=try-nx-cloud" description="Setup takes less than 5 minutes" /%}
-
-This also generates a CI workflow, so you can skip ahead to [Remote caching](#remote-caching).
-
-### Connect an existing workspace
-
-If you already have an Nx workspace, connect it to Nx Cloud:
-
-{% aside type="note" title="Prerequisites for nx connect" %}
-Your workspace must be pushed to a Git provider (GitHub, GitLab, Bitbucket, or Azure DevOps) before running `nx connect`. After connecting, Nx Cloud opens a PR that adds `nxCloudId` to `nx.json`. Merge this PR before proceeding so CI runs appear on the Nx Cloud dashboard.
-{% /aside %}
-
-```shell
-nx connect
-```
-
-This creates an Nx Cloud account (if you don't have one) and connects your workspace. Once connected, you can see your workspace in your [Nx Cloud organization](https://cloud.nx.app/orgs).
-
-The access token is stored in `nx.json` and should be committed to your repository. It only grants cache read/write access, not admin access to your Nx Cloud organization.
-
-## Generate a CI workflow
-
-If your workspace already has a CI workflow (e.g., `.github/workflows/ci.yml`), skip to [Remote caching](#remote-caching).
-
-Generate a CI workflow for GitHub Actions:
-
-```shell
-nx add @nx/workspace
-nx g @nx/workspace:ci-workflow --ci=github
-```
-
-The `@nx/workspace` package provides the CI workflow generator. Once installed, the generator creates a `.github/workflows/ci.yml` file. It also supports CircleCI, GitLab CI, Azure Pipelines, and Bitbucket Pipelines. Pass a different `--ci` value or run `nx g @nx/workspace:ci-workflow --help` to see all options.
-
-{% aside type="note" title="Generated output may differ" %}
-The generated workflow may differ from the example below depending on your workspace setup and Nx version. The key elements (affected command, remote caching, fix-ci) will be present.
-{% /aside %}
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-permissions:
-  actions: read
-  contents: read
-
-jobs:
-  main:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          filter: tree:0
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'npm'
-
-      - run: npm ci
-
-      - run: npx nx affected -t lint test build
-
-      - run: npx nx fix-ci
-        if: always()
-```
-
-This workflow includes several Nx CI features out of the box. The sections below explain each one.
-
-## Remote caching
-
-When Nx Cloud is connected, task results are cached remotely. If a task has already run with the same inputs (on any machine or CI run), the result is replayed instantly instead of running again.
-
-This means:
-
-- The second CI run on a PR is faster because unchanged tasks hit the cache
-- Developers pulling the latest `main` get cached results from CI
-- Build artifacts like `dist/` and test coverage are restored from cache, not recomputed
-
-For more details, see [remote cache (Nx Replay)](/docs/features/ci-features/remote-cache).
-
-## Running only affected tasks
-
-The generated workflow uses `nx affected` instead of `nx run-many`. This compares the PR's changes against the base branch and only runs tasks for projects that could be impacted:
-
-```shell
-nx affected -t lint test build
-```
-
-Nx determines the base and head commits using `NX_BASE` and `NX_HEAD` environment variables. The generated CI workflow configures these automatically through the `fetch-depth: 0` checkout, which gives Nx access to the full git history for comparison.
-
-On a PR, Nx compares the PR branch against `main` (or whatever `defaultBase` is set to in `nx.json`). On a push to `main`, it compares against the previous commit.
-
-For more details, see [affected](/docs/features/ci-features/affected).
-
-## Distributing tasks across machines
-
-For larger workspaces, you can distribute task execution across multiple machines using Nx Agents. Instead of running all tasks on a single CI runner, Nx Cloud coordinates the work across a fleet of agents:
-
-```yaml
-# Add to your CI workflow
-- run: npx nx start-ci-run --distribute-on="3 linux-medium-js"
-```
-
-Nx Agents automatically split tasks across the available agents, respecting task dependencies and maximizing parallelism. No configuration changes to your tasks are needed.
-
-For more details, see [distribute task execution (Nx Agents)](/docs/features/ci-features/distribute-task-execution).
-
-## Self-healing CI
-
-The `npx nx fix-ci` command at the end of the workflow enables self-healing CI. When a task fails, Nx Cloud analyzes the failure and suggests a fix that you can apply directly from your editor (via [Nx Console](/docs/getting-started/editor-setup)).
-
-This is useful for catching flaky tests, configuration drift, and other issues that can be auto-remediated without manual debugging.
-
-For more details, see [self-healing CI](/docs/features/ci-features/self-healing-ci).
-
-## Next steps
-
-- [Remote cache (Nx Replay)](/docs/features/ci-features/remote-cache): how remote caching works
-- [Affected](/docs/features/ci-features/affected): how Nx determines what changed
-- [Distribute task execution (Nx Agents)](/docs/features/ci-features/distribute-task-execution): run tasks across multiple machines
-- [Self-healing CI](/docs/features/ci-features/self-healing-ci): automatic failure detection and fixes
-- [AI integration](/docs/getting-started/ai-setup): enhance CI with AI-powered workflows
-
-{% cards cols=2 %}
-{% card title="Previous: Reducing Configuration Boilerplate" description="Automate task configuration with plugins" url="/docs/getting-started/tutorials/reducing-configuration-boilerplate" /%}
-{% /cards %}

astro-docs/src/content/docs/getting-started/Tutorials/typescript-packages-tutorial.mdoc

@@ -624,7 +624,7 @@ After this first release, you can remove the `--first-release` flag and just run
 
 Here are some things you can dive into next:
 
-- [Set up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial) with remote caching and self-healing
+- [Set up CI](/docs/getting-started/setup-ci) with remote caching and self-healing
 - Learn more about the [underlying mental model of Nx](/docs/concepts/mental-model)
 - Learn how to [migrate your existing project to Nx](/docs/guides/adopting-nx/adding-to-existing-project)
 - [Learn more about Nx release for publishing packages](/docs/features/manage-releases)

astro-docs/src/content/docs/getting-started/Tutorials/understanding-your-workspace.mdoc

@@ -5,7 +5,7 @@ sidebar:
   order: 6
 ---
 
-{% llm_copy_prompt title="Tutorial 6/8: Explore and debug your workspace" %}
+{% llm_copy_prompt title="Tutorial 6/7: Explore and debug your workspace" %}
 Help me explore and debug my Nx workspace.
 Use my existing workspace and projects for hands-on examples.
 
@@ -29,7 +29,6 @@ As your workspace grows to dozens or hundreds of projects, you need tools to exp
 5. [Caching](/docs/getting-started/tutorials/caching)
 6. **Understanding your workspace** (you are here)
 7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
-8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)
 
 {% /aside %}
 

astro-docs/src/content/docs/getting-started/installation.mdoc

@@ -109,10 +109,12 @@ You can also manually install the [`nx` NPM package](https://www.npmjs.com/packa
 
 ### Update Nx in your repository
 
-When you update Nx in your repository, it will also [automatically update your dependencies](/docs/features/automate-updating-dependencies) if you have an [Nx plugin](/docs/concepts/nx-plugins) installed for that dependency. To update Nx, run:
+When you update Nx in your repository, it will also [automatically update your dependencies](/docs/features/automate-updating-dependencies) if you have an [Nx plugin](/docs/concepts/nx-plugins) installed for that dependency.
+
+To update Nx, run `nx migrate`. It guides you through the update interactively:
 
 ```shell
-nx migrate latest
+nx migrate
 ```
 
 This creates a `migrations.json` file with any update scripts that need to be run. Run them with:
@@ -121,6 +123,8 @@ This creates a `migrations.json` file with any update scripts that need to be ru
 nx migrate --run-migrations
 ```
 
+For the full walkthrough, including the AI-assisted agentic flow, see [Automate Updating Dependencies](/docs/features/automate-updating-dependencies).
+
 {% aside type="note" title="Update One Major Version at a Time" %}
 To avoid potential issues, it is [recommended to update one major version of Nx at a time](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps).
 {% /aside %}

astro-docs/src/content/docs/getting-started/intro.mdoc

@@ -24,7 +24,7 @@ Monorepos have many advantages and are especially powerful for AI-assisted devel
 
 **Nx reduces friction across your entire development cycle** with intelligent caching, task orchestration, and deep understanding of your codebase structure.
 
-At its core, Nx:
+Nx:
 
 1. **Runs tasks fast** - [Caches results](/docs/features/cache-task-results) so you never rebuild the same code twice.
 2. **Understands your codebase** - Builds [project and task graphs](/docs/features/explore-graph) showing how everything connects.
@@ -40,7 +40,7 @@ nx run-many -t build test # Run across all projects
 
 {% callout type="deepdive" title="How does Nx run tasks?" %}
 
-At its core, Nx is a fast, intelligent task runner. Take the example of an NPM workspace. This could be a project's `package.json`:
+Nx is a fast, intelligent task runner. Take the example of an NPM workspace. This could be a project's `package.json`:
 
 ```json
 // package.json

astro-docs/src/content/docs/getting-started/setup-ci.mdoc

@@ -0,0 +1,136 @@
+---
+title: 'Setting Up CI'
+description: Configure CI for your Nx workspace with remote caching, affected, distributed task execution, and self-healing.
+sidebar:
+  order: 7
+  label: 'Setting Up CI'
+filter: 'type:Guides'
+---
+
+{% llm_copy_prompt title="Let an AI agent set it up for you" %}
+Help me set up CI for my Nx workspace with remote caching.
+
+Before touching anything, verify the workspace state:
+
+**A. Is Nx installed?**
+
+- Check for `nx.json` and `nx` in `package.json` devDeps.
+- Confirm `node_modules` exists. If not, install deps using the package manager that matches my lockfile (`pnpm install`, `npm install`, or `yarn`).
+- If `nx.json` is missing entirely, ask me before running `npx nx@latest init`.
+
+**B. Is there an existing CI workflow?**
+
+- **Yes, and it already calls `nx run` or `nx run-many`**: likely already set up. Confirm with me before changing anything.
+- **Yes, but it calls raw tooling directly** (`jest`, `tsc`, `eslint`, etc.): work with me to update it. Propose minimal edits swapping the raw calls for `nx run-many -t <task>` or `nx run <project>:<task>`, and add a final `npx nx fix-ci` step. Show me the diff and wait for approval before writing.
+- **No**: run `nx g @nx/workspace:ci-workflow --ci=<provider>`. Detect the provider from `git remote -v` (github.com -> `github`, gitlab.com -> `gitlab`, etc.). Ask me if it's ambiguous.
+
+Then connect to Nx Cloud:
+
+1. Run `npx nx-cloud onboard connect-workspace` and parse the JSON.
+2. If the response includes an `actionRequired` payload (typically GitHub authorization), surface the message and any URLs to me and stop. Do not retry blindly.
+3. Confirm `nxCloudId` is written to `nx.json`. If it is not, surface the JSON error to me instead of retrying.
+
+Stage the generated or edited files but do not commit on my behalf. Stay on topic: getting remote cache running in CI. For deeper coverage link to {pageUrl} and to [/docs/features/ci-features/remote-cache](/docs/features/ci-features/remote-cache).
+
+Page: {pageUrl}
+{% /llm_copy_prompt %}
+
+Connect your workspace to Nx Cloud and run your CI tasks through `nx`. That turns on remote caching, affected, distribution, and self-healing CI.
+
+## Make sure you have Nx
+
+If you don't have Nx in your repo yet, add it first.
+
+For existing repos, run the init command and follow the prompts:
+
+```shell
+npx nx@latest init
+```
+
+Or, start fresh with a new repo:
+
+```shell
+npx create-nx-workspace@latest
+```
+
+## Make sure CI invokes Nx CLI
+
+Remote caching, affected, distribution, and self-healing only kick in when `nx` runs your tasks. `nx test` is fine, and so is `npm test` if it wraps `nx test`. Direct calls to `jest`, `tsc`, or `eslint` bypass Nx Cloud.
+
+If you have a workflow file, swap raw tool invocations for `nx run-many` or `nx affected`:
+
+```yaml
+# .github/workflows/ci.yml
+- run: npx nx run-many -t lint test build
+```
+
+Use `nx run-many -t <task>` for multiple projects or `nx run <project>:<task>` for a single project.
+
+{% aside type="note" title="No CI workflow yet?" %}
+Generate one:
+
+```shell
+nx add @nx/workspace
+nx g @nx/workspace:ci-workflow --ci=github
+```
+
+Supported `--ci` values: `github`, `circleci`, `gitlab`, `azure`, `bitbucket-pipelines`. The generator wires up the CI task runner, remote caching, and `nx fix-ci`.
+{% /aside %}
+
+## Remote caching
+
+Remote cache allows your CI runs to benefit from previous runs. It takes less than 5 minutes to set up and is free for small teams.
+
+{% call_to_action variant="default" title="Connect your workspace" url="https://cloud.nx.app/setup/connect-workspace/guide?utm_source=nx-dev&utm_medium=ci-tutorial&utm_campaign=try-nx-cloud" description="Setup takes less than 5 minutes" /%}
+
+See [Remote Caching](/docs/features/ci-features/remote-cache) for details on the security model and eviction. For more granular control in CI, with separate read-only and read-write tokens and branch-scoped permissions, see [CI access tokens](/docs/guides/nx-cloud/access-tokens).
+
+## Running only affected tasks
+
+Use `nx affected` to run tasks only for projects impacted by the PR's changes:
+
+```yaml {% meta="{5}" %}
+# .github/workflows/ci.yml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- run: npx nx affected -t lint test build
+```
+
+Nx uses `NX_BASE` and `NX_HEAD` to determine the comparison range. `fetch-depth: 0` gives Nx access to the full git history. On a PR, Nx compares the branch against `main` (or whatever `defaultBase` is set to in `nx.json`). On a push to `main`, it compares against the previous commit.
+
+See [Affected](/docs/features/ci-features/affected) for more information.
+
+## Distributing tasks across machines
+
+With [Nx Agents](/docs/features/ci-features/distribute-task-execution), you can distribute tasks across multiple machines with a single line of code in your CI workflow. No complicated configuration required.
+
+```yaml {% meta="{2}" %}
+# .github/workflows/ci.yml
+- run: npx nx start-ci-run --distribute-on="3 linux-medium-js"
+- run: npx nx affected -t lint test build
+```
+
+It works seamlessly with [remote caching](#remote-caching) and enables [task splitting](/docs/features/ci-features/split-e2e-tasks) for Playwright, Vitest, etc. across machines.
+
+## Self-healing CI
+
+Add `npx nx fix-ci` as the final step in your workflow. When a task fails, Nx Cloud analyzes the failure and proposes a fix you can apply from GitHub or the Nx Cloud UI.
+
+```yaml {% meta="{3-4}" %}
+# .github/workflows/ci.yml
+- run: npx nx affected -t lint test build
+- run: npx nx fix-ci
+  if: always()
+```
+
+The `if: always()` ensures `fix-ci` runs even when prior steps fail. It catches flaky tests, configuration drift, and other issues Nx Cloud can fix without manual debugging.
+
+See [Self-healing CI](/docs/features/ci-features/self-healing-ci) for the trigger model.
+
+## Resources
+
+- [Remote cache (Nx Replay)](/docs/features/ci-features/remote-cache): how remote caching works
+- [Affected](/docs/features/ci-features/affected): how Nx determines what changed
+- [Distribute task execution (Nx Agents)](/docs/features/ci-features/distribute-task-execution): run tasks across multiple machines
+- [Self-healing CI](/docs/features/ci-features/self-healing-ci): automatic failure detection and fixes

astro-docs/src/content/docs/guides/Adopting Nx/nx-vs-turborepo.mdoc

@@ -16,21 +16,20 @@ All benchmarks on this page use the same [pnpm workspace](https://github.com/mee
 
 This page starts with the basics, like onboarding, and progressively moves into more advanced capabilities.
 
-| Topic                                               | Nx                                                                | Turborepo                                                 |
-| --------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
-| [Onboarding](#onboarding)                           | Zero-config or guided `nx init` (+3 lines)                        | Manual `turbo.json` (+144 lines)                          |
-| [Running tasks](#running-tasks)                     | Runs `package.json` scripts, optional plugin-based task inference | Runs `package.json` scripts, requires `turbo.json` config |
-| [Caching](#caching)                                 | Explicit opt-in, composable `namedInputs`                         | Cached by default, flat input lists                       |
-| [Task sandboxing](#task-sandboxing)                 | IO tracing + cache poisoning protection                           | Not available                                             |
-| [Code generation](#code-generation)                 | Programmatic generators with AST transforms and graph awareness   | Template-based file scaffolding (Plop)                    |
-| [Module boundary rules](#module-boundary-rules)     | Tag-based lint rule + conformance rules (polyglot)                | Experimental `turbo boundaries` (since 2024)              |
-| [Polyglot support](#polyglot-support)               | Native support for JS/TS, Java, .NET, Python, Rust                | Any CLI via `package.json` scripts, no native graph       |
-| [AI integration](#ai-integration)                   | Agent skills, MCP, `configure-ai-agents`, self-healing CI         | Official skill, no MCP or CI integration                  |
-| [CI solution](#running-nx-vs-turbo-on-ci)           | Nx Cloud: distribution (9m 20s), self-healing, flaky detection    | No CI solution (19m 18s with manual binning)              |
-| [Cross-repo coordination](#cross-repo-coordination) | Polygraph (synthetic monorepo)                                    | Not available                                             |
-| [Release management](#release-management)           | Built-in versioning, changelogs, and publishing                   | Requires manual setup or 3rd party tools                  |
-| [Observability](#observability)                     | Integrated dashboards and AI-powered run analysis                 | Experimental OpenTelemetry (OTLP) export                  |
-| [Developer experience](#developer-experience)       | TUI, IDE extensions, and interactive project graph                | Basic TUI and LSP support                                 |
+| Topic                                           | Nx                                                                | Turborepo                                                 |
+| ----------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
+| [Onboarding](#onboarding)                       | Zero-config or guided `nx init` (+3 lines)                        | Manual `turbo.json` (+144 lines)                          |
+| [Running tasks](#running-tasks)                 | Runs `package.json` scripts, optional plugin-based task inference | Runs `package.json` scripts, requires `turbo.json` config |
+| [Caching](#caching)                             | Explicit opt-in, composable `namedInputs`                         | Cached by default, flat input lists                       |
+| [Task sandboxing](#task-sandboxing)             | IO tracing + cache poisoning protection                           | Not available                                             |
+| [Code generation](#code-generation)             | Programmatic generators with AST transforms and graph awareness   | Template-based file scaffolding (Plop)                    |
+| [Module boundary rules](#module-boundary-rules) | Tag-based lint rule + conformance rules (polyglot)                | Experimental `turbo boundaries` (since 2024)              |
+| [Polyglot support](#polyglot-support)           | Native support for JS/TS, Java, .NET, Python, Rust                | Any CLI via `package.json` scripts, no native graph       |
+| [AI integration](#ai-integration)               | Agent skills, MCP, `configure-ai-agents`, self-healing CI         | Official skill, no MCP or CI integration                  |
+| [CI solution](#running-nx-vs-turbo-on-ci)       | Nx Cloud: distribution (9m 20s), self-healing, flaky detection    | No CI solution (19m 18s with manual binning)              |
+| [Release management](#release-management)       | Built-in versioning, changelogs, and publishing                   | Requires manual setup or 3rd party tools                  |
+| [Observability](#observability)                 | Integrated dashboards and AI-powered run analysis                 | Experimental OpenTelemetry (OTLP) export                  |
+| [Developer experience](#developer-experience)   | TUI, IDE extensions, and interactive project graph                | Basic TUI and LSP support                                 |
 
 ## Onboarding
 
@@ -346,18 +345,10 @@ Both tools offer visibility into your pipelines, but through different models.
 
 _Nx Agent utilization chart, showing even distribution across CI runners._
 
-For deep dives into resource utilization, see [CI Resource Usage](/docs/guides/nx-cloud/ci-resource-usage).
+For deep dives into resource utilization, see [Resource Usage](/docs/features/ci-features/resource-usage).
 
 **Turborepo** exposes run metrics via experimental **OpenTelemetry (OTLP)**. This is useful if you already have a mature observability stack (like Datadog or Grafana) and want to route build metrics into it, though it requires significant manual setup and maintenance of your own collector and visualization layer.
 
-## Cross-repo coordination
-
-Most organizations don't have a single monorepo. They have several monorepos plus standalone repos across teams.
-
-Nx Cloud's [Polygraph](/docs/enterprise/polygraph) creates a [synthetic monorepo](/docs/concepts/synthetic-monorepos): a unified dependency graph across separate repositories without moving any code. AI agents can read the cross-repo graph, coordinate changes across repos, and manage PRs across repo boundaries.
-
-Turborepo has no cross-repo coordination.
-
 ## Release management
 
 Versioning and publishing libraries in a monorepo is a complex orchestration task. You need to identify what changed, determine the next version for each package, update internal dependencies, generate changelogs, and publish to registries.

astro-docs/src/content/docs/guides/Nx Cloud/Source Control Integration/github-app-permissions.mdoc

@@ -6,11 +6,14 @@ filter: 'type:References'
 
 The Nx Cloud GitHub App requires the following permissions to provide CI/CD integration and setup experiences. Most information is used transiently during operations and not stored in our systems.
 
+{% callout type="note" title="Administration (read & write) permission removed." %}
+The Nx Cloud GitHub App no longer requests the `Administration` (read & write) permission. It was previously required to generate new workspaces from the browser; that feature has since been removed, so we've dropped the permission to reduce the access we request.
+{% /callout %}
+
 ## Required permissions
 
 Repository permissions:
 
-- `Administration: Read & Write`
 - `Checks: Read & Write`
 - `Contents: Read & Write`
 - `Commit Statuses: Read`
@@ -27,12 +30,6 @@ Organization permissions:
 
 ## Permission details
 
-### Administration (write)
-
-**Used for:** Creating new repositories with a pre-configured Nx workspace during initial onboarding.
-
-**When it's used:** Only when you explicitly choose to create a new workspace through Nx Cloud's setup flow. [Single tenant instances](/docs/enterprise/single-tenant/overview) can safely forego this scope and will only lose the ability to create new workspaces through the app.
-
 ### Checks (write)
 
 **Used for:** Updating CI run statuses so you can see the progress and results of your Nx Cloud pipeline executions directly in GitHub. Also used for Self-Healing CI status check runs in PRs.
@@ -81,9 +78,9 @@ Organization permissions:
 
 ### Actions (read)
 
-**Used for:** Retrieving GitHub Action logs so that they can be surfaced on Nx Cloud to help resolve failures before Nx Cloud had a chance to run tasks, and for Polygraph support.
+**Used for:** Retrieving GitHub Action logs so that they can be surfaced on Nx Cloud to help resolve failures before Nx Cloud had a chance to run tasks.
 
-**When it's used:** Only when using Polygraph, and Nx Cloud MCP tools to get CI information.
+**When it's used:** Only when using Nx Cloud MCP tools to get CI information.
 
 ## Your data and security
 

astro-docs/src/content/docs/guides/Nx Cloud/access-tokens.mdoc

@@ -11,7 +11,11 @@ filter: 'type:Guides'
 The permissions and membership define what developers can access on [nx.app](https://cloud.nx.app?utm_source=nx.dev&utm_medium=docs&utm_campaign=nx-cloud-security), but they don't affect what happens when you run Nx commands in CI. To manage that, you need to provision CI access tokens in your workspace settings, under the `Access Control` tab.
 Learn more about [cache security best practices](/docs/concepts/ci-concepts/cache-security).
 
-![Access Control Settings Page](../../../../assets/nx-cloud/access-control-settings.avif)
+{% aside type="tip" title="Quickest path: use recommended settings" %}
+The **Access Control** tab in your Nx Cloud workspace has a **Use recommended settings** button that generates the right CI access tokens, requires developer logins for cache reads, etc.
+
+![](../../../../assets/nx-cloud/access-control-settings.avif)
+{% /aside %}
 
 ## Access types
 

astro-docs/src/content/docs/guides/Nx Cloud/bring-your-own-compute.mdoc

@@ -1,10 +1,10 @@
 ---
-title: 'Manual Distributed Task Execution'
-description: 'Learn how to set up manual distributed task execution on various CI providers'
+title: 'Bring Your Own Compute'
+description: 'Learn how to run Nx Agents on your own CI compute across various CI providers'
 filter: 'type:Guides'
 ---
 
-Using [Nx Agents](/docs/features/ci-features/distribute-task-execution) is the easiest way to distribute task execution, but your organization may not be able to use hosted Nx Agents. You can set up distributed task execution on your own CI provider using the recipes below.
+[Nx Agents](/docs/features/ci-features/distribute-task-execution) distributes your tasks across multiple machines on every Nx Cloud plan. On the [Nx Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=bring-your-own-compute) you can also bring your own compute, running the agents on your own CI provider instead of Nx Cloud-hosted machines. The recipes below show how to set that up.
 
 {% tabs syncKey="ci-provider" %}
 
@@ -106,7 +106,7 @@ jobs:
         env:
           NX_AGENT_NAME: ${{ matrix.agent }}
 
-      # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+      # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
       - name: Upload agent metrics
         if: always()
         run: npx nx-cloud upload-agent-metrics
@@ -167,7 +167,7 @@ jobs:
           no_output_timeout: 60m
           environment:
             NX_AGENT_NAME: << parameters.ordinal >>
-      # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+      # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
       - run:
           command: npx nx-cloud upload-agent-metrics
           environment:
@@ -237,7 +237,7 @@ jobs:
         env:
           NX_AGENT_NAME: $(System.JobPositionInPhase)
 
-      # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+      # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
       - script: npx nx-cloud upload-agent-metrics
         condition: always()
         env:
@@ -311,7 +311,7 @@ definitions:
           - npx nx start-agent
         after-script:
           - export NX_AGENT_NAME=$BITBUCKET_STEP_UUID
-          # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+          # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
           - npx nx-cloud upload-agent-metrics
           # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
           - npx nx fix-ci
@@ -368,7 +368,7 @@ image: node:18
     - yarn nx start-agent
   after_script:
     - export NX_AGENT_NAME=$CI_JOB_ID
-    # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+    # Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
     - yarn nx-cloud upload-agent-metrics
     # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
     - yarn nx fix-ci
@@ -490,7 +490,7 @@ pipeline {
                    }
                    post {
                         always {
-                            // Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+                            // Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
                             sh "npx nx-cloud upload-agent-metrics"
                             // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                             sh "npx nx fix-ci"
@@ -508,7 +508,7 @@ pipeline {
                    }
                    post {
                         always {
-                            // Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+                            // Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
                             sh "npx nx-cloud upload-agent-metrics"
                             // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                             sh "npx nx fix-ci"
@@ -526,7 +526,7 @@ pipeline {
                    }
                    post {
                         always {
-                            // Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/guides/nx-cloud/ci-resource-usage
+                            // Upload agent resource metrics (Requires Nx 22.1 or higher.) — https://nx.dev/docs/features/ci-features/resource-usage
                             sh "npx nx-cloud upload-agent-metrics"
                             // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                             sh "npx nx fix-ci"

astro-docs/src/content/docs/guides/Nx Cloud/ci-resource-usage.mdoc

@@ -1,97 +0,0 @@
----
-title: Track CI Resource Usage
-description: Track CPU and memory usage for each task in your CI pipeline to find resource bottlenecks, debug out-of-memory errors, and optimize your CI agent configuration.
-sidebar:
-  label: View Resource Usage
-  badge: new!
-filter: 'type:Guides'
----
-
-Nx Cloud tracks CPU and memory usage for each task in your CI pipeline. Use this data to find resource bottlenecks, debug out-of-memory errors, and pick the right agent size for your workload.
-
-{% aside type="note" title="Requirements" %}
-Requires Nx 22.1 or higher.
-
-The CI resource usage feature with Nx Cloud requires an [Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=documentation-guide&utm_campaign=nx-cloud-task-metrics).
-{% /aside %}
-
-## Resource usage with Nx Agents
-
-With [Nx Agents](/docs/features/ci-features/distribute-task-execution), resource metrics are collected automatically. You can view this data in the Nx Cloud dashboard for any CI pipeline execution.
-
-### Viewing the analysis summary
-
-Open any CI pipeline execution in Nx Cloud and go to the analysis section. You'll see a list of agents used for the run, along with:
-
-- Average and maximum CPU usage
-- Average and maximum memory usage
-- Machine specs for that resource class
-
-This gives you a quick look at how resources were used across all agents.
-
-![Resource usage summary showing agents with CPU and memory stats](../../../../assets/guides/nx-cloud/agent-resource-usage-table.png)
-
-### Viewing usage details
-
-Click on any agent to see a breakdown of resource usage over time. The detail view shows:
-
-- Memory usage by process
-- CPU usage by process
-- Resource consumption for each task
-- Nx CLI overhead
-
-This view helps you find exactly which task is using the most resources, not just that "something" in your pipeline is the problem.
-
-![Resource usage details showing memory and CPU by process](../../../../assets/guides/nx-cloud/resource-chart-details.png)
-
-### Using the detail view
-
-The detail view has a few features to help you dig into resource usage:
-
-- **Legend**: Click items in the legend to focus on specific tasks or processes
-  ![Using the legend to focus on specific tasks](../../../../assets/guides/nx-cloud/resource-chart-legend.png)
-
-- **Timeline scrubber**: Use the scrubber at the bottom to jump to specific points in time or zoom in on peak usage
-  ![Timeline scrubber for navigating resource usage over time](../../../../assets/guides/nx-cloud/resource-chart-scrubber.jpg)
-
-- **View modes**: Switch between "stacked" view (total usage at any time) and "individual" view (each process separately)
-  ![Stacked view showing total resource usage](../../../../assets/guides/nx-cloud/resource-stacked-chart-view.png)
-
-- **CSV export**: Download the raw data if you need to dig into sub-process details
-
-## Common use cases
-
-- **Finding memory-hungry tasks**: Figure out which project eats the most memory when running tasks in parallel. You can then run just that project with lower parallelism instead of slowing down everything.
-- **Spotting misconfigured tooling**: See when a bundler or build tool is pulling in more files than it should.
-- **Debugging E2E bottlenecks**: Find out if the slow part is the tests themselves or something in the dependency chain.
-- **Comparing before and after upgrades**: Check if a dependency upgrade caused a spike in resource usage.
-- **Detecting memory leaks**: Look for tasks where memory keeps climbing over time.
-- **Picking the right resource class**: Figure out the right agent size when moving to Nx Agents from GitHub Actions or other CI providers.
-
-## Resource metrics with manual DTE
-
-If you're running your own CI agents instead of Nx Agents, Nx Cloud can still collect per-agent CPU and memory metrics so you can debug slow tasks and OOM kills in the run timeline. Opt in by adding a single CLI step to each agent job.
-
-{% aside type="note" title="Nx Enterprise Required" %}
-This feature is available on Nx Cloud Enterprise plans only. [Reach out to learn more about Nx Enterprise](https://nx.dev/enterprise).
-{% /aside %}
-
-### What to add
-
-At the end of each agent job, run `npx nx-cloud upload-agent-metrics`. Use your provider's always-run mechanism so the step runs even when the agent is killed mid-task — that's precisely the scenario where metrics are most useful.
-
-Here's the GitHub Actions step:
-
-```yaml
-- name: Upload agent metrics
-  if: always()
-  run: npx nx-cloud upload-agent-metrics
-  env:
-    NX_AGENT_NAME: ${{ matrix.agent }}
-```
-
-The `if: always()` condition is important: if an agent is OOM-killed mid-run, the normal step sequence stops — but the upload still needs to happen so you can see which task caused the kill.
-
-### Other CI providers
-
-The [Manual DTE guide](/docs/guides/nx-cloud/manual-dte) shows the equivalent step for Circle CI, Azure Pipelines, Bitbucket Pipelines, GitLab CI, and Jenkins.

astro-docs/src/content/docs/guides/Nx Cloud/enable-ai-features.mdoc

@@ -56,9 +56,11 @@ Then, enable AI features in the [organization settings](https://cloud.nx.app/go/
 
 If using DTE agents, the self-healing CI step will be automatically added when the setting is enabled in the workspace settings.
 
-#### Manual DTE
+#### Bring your own compute
 
-For manual DTE configurations, the `nx fix-ci` command must be included in the agent configuration after running nx tasks.
+Bringing your own compute requires the [Nx Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=bring-your-own-compute).
+
+When you bring your own compute, the `nx fix-ci` command must be included in the agent configuration after running nx tasks.
 
 **Important:** This command must run **always**, meaning that even when previous nx tasks fail, the `fix-ci` command should still execute.
 

astro-docs/src/content/docs/guides/Nx Console/console-migrate-ui.mdoc

@@ -16,7 +16,7 @@ When an update to Nx is available, a badge will appear on the Nx Console icon in
 
 ![](../../../../assets/guides/nx-console/console-migrate-1-start.avif)
 
-By default, clicking the migration button starts the migration process by upgrading to the recommended Nx version — the latest version of the next major release. This method ensures you upgrade one major version at a time in order to [avoid breakages](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps). To customize the version, click the pencil icon to provide a specific version to update to. You may also provide additional CLI options such as `--to` or `--from`.
+By default, clicking the migration button starts the migration process by upgrading to the recommended Nx version — the latest version of the next major release. This method ensures you upgrade one major version at a time in order to [avoid breakages](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps). To customize the version, click the pencil icon to provide a specific version to update to. You may also provide additional CLI options such as `--include`.
 
 ![](../../../../assets/guides/nx-console/console-migrate-2-customize-version.avif)
 
@@ -42,6 +42,19 @@ You can click through to view the migration source code, giving you the opportun
 
 Alternatively, you may choose to skip a problematic migration.
 
+### Migrations that use an AI prompt
+
+Some migrations ship an AI prompt instead of (or in addition to) a deterministic script - see [what's in a migration](/docs/features/automate-updating-dependencies#whats-in-a-migration). The Migrate UI marks these with an **AI** badge and handles them without running an agent itself:
+
+- **Prompt-only** migrations can't run automatically. The card shows **"AI prompt pending"** with a hint pointing at the prompt file, and **View Source** opens that prompt. Apply the prompt yourself - for example, with your AI agent - then click **Mark as Run** to record it and move on.
+- **Hybrid** migrations run their generator automatically, then the card shows **Generator complete** alongside **AI prompt pending**. Click **Approve Changes** to accept the generator's edits and advance, or **Mark as Run** if the generator made no changes.
+
+Your acknowledgment is remembered across editor reloads, so reopening a session brings you back to any prompt migrations you still need to finish.
+
+{% aside type="note" title="Requires a recent Nx and Nx Console" %}
+The AI badge and prompt handling require Nx 23.0.0-beta.24 or later and an up-to-date Nx Console extension. On older versions the Migrate UI still works without these controls.
+{% /aside %}
+
 ## Finalizing the migration
 
 When all migrations are done, or you don't want to run further migrations, you can finish the process by clicking the Finish button. By default, this will squash all commits created during the migration together, but you can opt into preserving them.

astro-docs/src/content/docs/guides/Tasks & Caching/workspace-watching.mdoc

@@ -155,22 +155,22 @@ To watch for specific projects and echo the changed files, run this command:
 nx watch --projects=app1,app2 -- echo \$NX_FILE_CHANGES
 ```
 
-### Watching for dependent projects
+### Watching a project and its dependencies
 
-To watch for a project and it's dependencies, run this command:
+To watch a project and the projects it depends on, run this command:
 
 ```shell
-nx watch --projects=app1 --includeDependentProjects -- echo \$NX_PROJECT_NAME
+nx watch --projects=app1 --includeDependencies -- echo \$NX_PROJECT_NAME
 ```
 
-### Rebuilding dependent projects while developing an application
+### Rebuilding an application's dependencies while developing it
 
 In a monorepo setup, your application might rely on several libraries that need to be built before they can be used in the application. While the [task pipeline](/docs/guides/tasks--caching/defining-task-pipeline) automatically handles this during builds, you'd want the same behavior during development when serving your application with a dev server.
 
-To watch and rebuild the dependent libraries of an application, use the following command:
+To watch and rebuild the libraries an application depends on, use the following command:
 
 ```shell
-nx watch --projects=my-app --includeDependentProjects -- nx run-many -t build -p \$NX_PROJECT_NAME --exclude=my-app
+nx watch --projects=my-app --includeDependencies -- nx run-many -t build -p \$NX_PROJECT_NAME --exclude=my-app
 ```
 
-`--includeDependentProjects` ensures that any changes to projects your application depends on trigger a rebuild, while `--exclude=my-app` skips rebuilding the app itself since it's already being served by the development server.
+`--includeDependencies` ensures that any changes to projects your application depends on trigger a rebuild, while `--exclude=my-app` skips rebuilding the app itself since it's already being served by the development server.

astro-docs/src/content/docs/guides/Tips-n-Tricks/advanced-update.mdoc

@@ -15,7 +15,7 @@ The following steps are a summary of the [standard update process](/docs/feature
 First, run the `migrate` command:
 
 ```shell
-nx migrate latest # same as nx migrate nx@latest
+nx migrate
 ```
 
 This performs the following changes:
@@ -43,17 +43,64 @@ After you run all the migrations, you can remove `migrations.json` and commit an
 
 Migrating Jest, Cypress, ESLint, React, Angular, Next, and more is a difficult task. All the tools change at different rates, and they can conflict with each other. In addition, every workspace is different. Even though our goal is for you to update any version of Nx to a newer version of Nx in a single go, sometimes it doesn't work. The recommended process is to update, at most, one major version at a time.
 
-Say you want to migrate from Nx 17.1.0 to Nx 18.2.4. The following steps are more likely to work comparing to `nx migrate 18.2.4`.
+Say you want to migrate from Nx 22.1.0 to Nx 23.0.0. The following steps are more likely to work comparing to `nx migrate 23.0.0`.
 
-- Run `nx migrate 17.3.2` to update the latest version in the 17.x branch.
+- Run `nx migrate 22.7.5` to update the latest version in the 22.x branch.
 - Run `nx migrate --run-migrations`.
-- Next, run `nx migrate 18.2.4`.
+- Next, run `nx migrate 23.0.0`.
 - Run `nx migrate --run-migrations`.
 
 {% aside type="caution" title="Angular updates" %}
 If your workspace uses Angular, this becomes a requirement rather than a recommendation. The Angular packages maintain migrations for a single major version at a time. If you try to update over multiple major versions, only the migrations for the latest major version will be applied. This can lead to issues in your workspace.
 {% /aside %}
 
+## Crossing multiple major versions
+
+When the target is more than one major version ahead of your installed version, `nx migrate` prompts you to choose how far to jump: migrate to the latest in your current major (recommended), step into the next major, or go directly to the target. To skip the prompt, use `--multi-major-mode`:
+
+- `--multi-major-mode=gradual` migrates to the smallest recommended step (typically the latest in your current major), then tells you to re-run to continue.
+- `--multi-major-mode=direct` migrates straight to the target.
+
+The `NX_MULTI_MAJOR_MODE` environment variable is equivalent and takes precedence over a `multiMajorMode` value set in `nx.json`. In non-interactive environments there is no prompt - Nx warns that updating one major at a time is recommended and proceeds directly to the target.
+
+## Choosing which packages to migrate
+
+While in most cases you want to be up to date with Nx and the dependencies it manages, sometimes you might need to stay on an older version of such a dependency. For example, you might want to update Nx to the latest version but keep Angular on **v21.x.x** and not update it to **v22.x.x**.
+
+The `--include` flag controls which packages are updated: `required` (the target package and the packages it ships with), `optional` (the dependency updates those packages recommend), or `all` (the default). The interactive `nx migrate` flow prompts for this. Pass `--include` to set it ahead of time.
+
+`--include` applies only when the target package opts into package selection. Nx and its official plugins do starting in Nx 23, and other plugin authors can opt in as well. For targets that don't, Nx uses `all` without prompting, and passing `--include` explicitly errors. Non-interactive runs also default to `all`.
+
+When unsure, prefer `--include=required` and follow up with `--include=optional`. Updating only Nx and its plugins keeps the PR scope small and has less chance of introducing issues, which matters most in large workspaces. Use `--include=all` when you're okay with doing everything in one PR.
+
+{% aside type="note" title="Optional package updates" %}
+You can't choose to skip any arbitrary package update. To ensure that a plugin works well with older versions of a given package, the plugin must support it. Therefore, Nx plugin authors define what package updates are optional.
+{% /aside %}
+
+{% aside type="caution" title="Taking control of package updates" %}
+While opting out of applying some package updates is supported by Nx, please keep in mind that you are effectively taking control of those package updates and opting out of Nx managing them. This means you'll need to keep up with the version requirements for those packages and those that depend on them. You'll also need to consider more things when updating them at some point [as explained later](#updating-dependencies-that-are-behind-the-versions-nx-manages).
+{% /aside %}
+
+### Skipping optional package updates
+
+To skip the optional package updates, generate the migration with `--include=required`:
+
+```shell
+nx migrate --include=required
+```
+
+Only the target package and the packages it ships with are updated. The `package.json` and the `migrations.json` are generated without the optional dependency updates, and you can catch up on those later.
+
+### Updating dependencies that are behind the versions Nx manages
+
+Once you have skipped some optional updates, there'll come a time when you'll want to update those packages. Run `nx migrate --include=optional` to collect the optional dependency updates recommended for your installed version. It anchors to your installed version, so the target package must be installed and you can't migrate to a version higher than what's installed.
+
+The catch-up can be scoped to a single plugin by naming it as the target. For example, `nx migrate @nx/vite --include=optional` collects only the optional updates `@nx/vite` recommends, such as `vite` itself.
+
+{% aside type="caution" title="Scoping to a single plugin" %}
+Some plugin updates depend on other plugins running their updates too. For example, `@nx/angular` sometimes requires the `@nx/js` updates for TypeScript. Scoping the catch-up to a single plugin skips those, so prefer the full `nx migrate --include=optional` when unsure.
+{% /aside %}
+
 ## Managing migration steps
 
 When you run into problems running the `nx migrate --run-migrations` command, here are some solutions to break the process down into manageable steps.
@@ -129,107 +176,20 @@ You can even provide a custom location for the migrations file if you wish, you
 nx migrate --run-migrations=migrations.json
 ```
 
-## Choosing optional package updates to apply
+## Using an AI agent to apply migrations
 
-While in most cases you want to be up to date with Nx and the dependencies it manages, sometimes you might need to stay on an older version of such a dependency. For example, you might want to update Nx to the latest version but keep Angular on **v15.x.x** and not update it to **v16.x.x**. For such scenarios, `nx migrate` allows you to choose what to update using the `--interactive` flag.
+Some migrations ship an AI prompt that an installed agent applies for you. The [agentic flow](/docs/features/automate-updating-dependencies#step-2-run-migrations) is interactive by default, but you can control it with flags:
 
-{% aside type="note" title="Optional package updates" %}
-You can't choose to skip any arbitrary package update. To ensure that a plugin works well with older versions of a given package, the plugin must support it. Therefore, Nx plugin authors define what package updates are optional.
-{% /aside %}
+- `--agentic` enables it and resolves the installed agent. Use `--agentic=claude-code` (or `codex`, `opencode`) to pin one, or `--no-agentic` to disable it.
+- `--validate` / `--no-validate` toggles agent validation of generator-only migrations - on by default when the agentic flow is enabled.
 
-{% aside type="caution" title="Taking control of package updates" %}
-While opting out of applying some package updates is supported by Nx, please keep in mind that you are effectively taking control of those package updates and opting out of Nx managing them. This means you'll need to keep up with the version requirements for those packages and those that depend on them. You'll also need to consider more things when updating them at some point [as explained later](#updating-dependencies-that-are-behind-the-versions-nx-manages).
-{% /aside %}
+A non-interactive `--agentic` run warns and continues without the agent, since the flow requires an interactive terminal. When the flow is enabled, Nx commits each migration separately by default so the agent can review an isolated diff.
 
-### Interactively opting out of package updates
+To always use the agentic flow (or a specific agent) without passing the flag, set the `agentic` and `validate` options in the [`migrate` section of `nx.json`](/docs/reference/nx-json#migrate).
 
-To opt out of package updates, you need to run the migration in interactive mode:
+## Workspace-wide migrate defaults
 
-```shell
-nx migrate latest --interactive
-```
-
-As the migration runs and collects the package updates, you'll be prompted to apply optional package updates, and you can choose what to do based on your needs. The `package.json` will be updated and the `migrations.json` will be generated considering your responses to those prompts.
-
-### Updating dependencies that are behind the versions Nx manages
-
-Once you have skipped some optional updates, there'll come a time when you'll want to update those packages. To do so, you'll need to generate the package updates and migrations from the Nx version that contained those skipped updates.
-
-Say you skipped updating Angular to **v16.x.x**. That package update was meant to happen as part of the `@nx/angular@16.1.0` update, but you decided to skip it at the time. The recommended way to collect the migrations from such an older version is to run the following:
-
-```shell
-nx migrate latest --from=nx@16.0.0 --exclude-applied-migrations
-```
-
-A couple of things are happening there:
-
-- The `--from=nx@16.0.0` flag tells the `migrate` command to use the version **16.0.0** as the installed version for the `nx` package and all the first-party Nx plugins. Note we use a version lower than the one where the update was meant to happen. This is to account for the fact that the update is normally targeted to a prerelease version for testing it before the final release.
-- The `--exclude-applied-migrations` flag tells the `migrate` command not to collect migrations that should have been applied on previous updates.
-
-So, the above command will effectively collect any package update and migration meant to run if your workspace had `nx@16.0.0` installed while excluding those that should have been applied before. You can provide a different older version to collect migrations from.
-
-{% aside type="caution" title="Automatically excluding previously applied migrations" %}
-Automatically excluding previously applied migrations doesn't consider migrations manually removed from the `migrations.json` in previous updates. If you've manually removed migrations in the past and want to run them, don't pass the `--exclude-applied-migrations` and collect all previous migrations.
-{% /aside %}
-
-### Identifying the Nx version to migrate from to collect previously skipped updates
-
-After running the migrations in interactive mode and opting-out of some package updates, a message is printed to the terminal with the command to run later to collect and apply those skipped updates. For example, if you skipped updating Angular to **v16.0.0**, this is the output you'll see (simplified for brevity):
-
-```shell
-nx migrate latest --interactive
-Fetching meta data about packages.
-It may take a few minutes.
-...
-✔ Do you want to update to TypeScript v5.0? (Y/n) · false
-✔ Do you want to update the Angular version to v16? (Y/n) · false
-
-NX   The migrate command has run successfully.
-
-- package.json has been updated.
-- migrations.json has been generated.
-
-NX   Next steps:
-
-- Make sure package.json changes make sense and then run 'pnpm install --no-frozen-lockfile',
-- Run 'pnpm exec nx migrate --run-migrations'
-- You opted out of some migrations for now. Write the following command down somewhere to apply these migrations later:
-- nx migrate 16.5.3 --from nx@16.1.0-beta.0 --exclude-applied-migrations
-- To learn more go to https://nx.dev/recipes/other/advanced-update
-```
-
-You can see in the "Next steps" section a suggested command to run to apply the skipped package updates. Make sure to store that information somewhere so you can later remember from which version you need to run the migration to apply the skipped package updates.
-
-Please note the suggested command is only based on a particular run of the `nx migrate` command. If you've skipped package updates in previous runs, you'll need to use the oldest version you've stored that you haven't yet run the migration from.
-
-If you don't have the command and need to find out from which version to run the migration, you can take a look at the `migrations.json` file of the relevant package. For example, if you skipped updating Angular to **v16.0.0**, you can take a look at the `migrations.json` file of the `@nx/angular` package and you'll find the following:
-
-```jsonc
-// node_modules/@nx/angular/migrations.json
-{
-  // ...
-  "packageJsonUpdates": {
-    // ...
-    "16.1.0": {
-      "version": "16.1.0-beta.1",
-      "x-prompt": "Do you want to update the Angular version to v16?",
-      "requires": {
-        "@angular/core": ">=15.2.0 <16.0.0",
-      },
-      "packages": {
-        "@angular/core": {
-          "version": "~16.0.0",
-          "alwaysAddToPackageJson": true,
-        },
-        // ...
-      },
-    },
-    // ...
-  },
-}
-```
-
-You can see the `16.1.0-beta.1` version is the one that contains the update for `@angular/core` to **~16.0.0**. That's the version you need to run the migration from to apply the package update.
+To avoid passing the same flags on every run, set defaults in the [`migrate` section of `nx.json`](/docs/reference/nx-json#migrate) - `createCommits`, `commitPrefix`, `include`, `multiMajorMode`, `agentic`, and `validate`. A command-line flag always overrides the `nx.json` value, which in turn overrides the built-in Nx defaults.
 
 ## Other advanced capabilities
 
@@ -238,13 +198,13 @@ You can see the `16.1.0-beta.1` version is the one that contains the update for
 Sometimes, you may want to use a different version of a package than what Nx recommends. To do that, specify the package and version:
 
 ```shell
-nx migrate latest --to="jest@22.0.0,cypress@3.4.0"
+nx migrate --to="jest@22.0.0,cypress@3.4.0"
 ```
 
 By default, Nx uses currently installed packages to calculate what migrations need to run. To override them, override the version:
 
 ```shell
-nx migrate latest --to="@nx/jest@12.0.0"
+nx migrate --to="@nx/jest@12.0.0"
 ```
 
 {% aside type="caution" title="Overriding versions" %}

astro-docs/src/content/docs/how-nx-works/index.mdoc

@@ -6,4 +6,4 @@ sidebar:
 pagefind: false
 ---
 
-{% sidebar_group_cards group="How Nx Works" /%}
+{% sidebar_group_cards group="How Nx works" /%}

astro-docs/src/content/docs/knowledge-base/installation-and-updates/index.mdoc

@@ -0,0 +1,9 @@
+---
+title: Installation and updates
+description: Installation and update guides for Nx
+sidebar:
+  hidden: true
+pagefind: false
+---
+
+{% sidebar_group_cards group="Knowledge Base/Installation and updates" /%}

astro-docs/src/content/docs/knowledge-base/installation/index.mdoc

@@ -1,9 +0,0 @@
----
-title: Installation
-description: Installation guides for Nx
-sidebar:
-  hidden: true
-pagefind: false
----
-
-{% sidebar_group_cards group="Knowledge Base/Installation" /%}

astro-docs/src/content/docs/reference/Nx Cloud/assignment-rules.mdoc

@@ -1,12 +1,12 @@
 ---
 title: Assignment Rules
-description: Control which tasks run on which agents using assignment rules with Nx Agents or manual DTE
+description: Control which tasks run on which agents using assignment rules with Nx Agents
 filter: 'type:References'
 ---
 
 Assignment rules allow you to control which tasks can run on which agents. Save on agent costs by provisioning different sizes of agents to suite the individual needs of your tasks. Ensure resource intensive targets like `e2e-ci` and `build` have what they need by using larger agents and with a specified parallelism. Lighter tasks like `lint` and `test` can run on smaller agents.
 
-Assignment rules are defined in `yaml` files within your workspace's `.nx/workflows` directory. You can use assignment rules with [Manual Distributed Task Execution (DTE)](/docs/guides/nx-cloud/manual-dte) or with [dynamic Nx Agents](/docs/features/ci-features/dynamic-agents). Note that additional configuration is required when using Manual DTE.
+Assignment rules are defined in `yaml` files within your workspace's `.nx/workflows` directory. You can use assignment rules with [Nx Agents](/docs/features/ci-features/distribute-task-execution).
 
 ## How to define an assignment rule
 
@@ -40,7 +40,7 @@ assignment-rules:
 ```
 
 {% /tabitem %}
-{% tabitem label="Assignment rules with manual DTE" %}
+{% tabitem label="Assignment rules when you bring your own compute" %}
 
 ```yaml
 // .nx/workflows/assignment-rules.yaml
@@ -73,9 +73,9 @@ You can mix and match any of the criteria in an assignment rule provided that yo
 - There is at least one [agent type](/docs/reference/nx-cloud/launch-templates) specified in the `run-on` field. If no parallelism is specified, the parallelism of the executed command will be used instead. If that is not specified, then the parallelism will default to `1`
 - For assignment rules with Nx Agents, every changeset in your `distribute-on` field must include at **least one agent** that matches each agent type specified in the `run-on` field across all assignment rules. For example, if your rules distribute tasks on `linux-small-js`, `linux-medium-js`, and `linux-large-js`, then at least one agent of each type must be available; otherwise, tasks associated with those rules cannot be executed.
 
-{% aside type="note" title="If you are using Manual DTE, you must define your own agent types" %}
+{% aside type="note" title="If you bring your own compute, you must define your own agent types" %}
 You must define your own agent types and attach them to your agents using the `NX_AGENT_LAUNCH_TEMPLATE` environment variable. Ensure that for each `run-on` field in your assignment rules, you have corresponding agents in your agent pool that have the same agent type.
-See below for an [example](#using-assignment-rules-with-manual-dte) of how to define your own agent types when using Manual DTE.
+See below for an [example](#using-assignment-rules-when-you-bring-your-own-compute) of how to define your own agent types.
 {% /aside %}
 
 ### Assignment rule property reference
@@ -296,7 +296,11 @@ assignment-rules:
         parallelism: 5
 ```
 
-## Using assignment rules with manual DTE
+## Using assignment rules when you bring your own compute
+
+{% aside type="note" title="Enterprise Feature" %}
+Bringing your own compute requires the [Nx Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=bring-your-own-compute). [Nx Agents](/docs/features/ci-features/distribute-task-execution) distributes your tasks on all plans.
+{% /aside %}
 
 A typical `assignment-rules.yaml` file might look like this:
 

astro-docs/src/content/docs/reference/Nx Cloud/launch-templates.mdoc

@@ -56,11 +56,8 @@ The following resource classes are available:
 
 - `docker_linux_amd64/small`
 - `docker_linux_amd64/medium`
-- `docker_linux_amd64/medium+`
 - `docker_linux_amd64/large`
-- `docker_linux_amd64/large+`
 - `docker_linux_amd64/extra_large`
-- `docker_linux_amd64/extra_large+`
 - `docker_linux_arm64/medium`
 - `docker_linux_arm64/large`
 - `docker_linux_arm64/extra_large`
@@ -74,9 +71,13 @@ A launch template's `image` defines the available base software for the agent ma
 
 {% aside type="tip" title="Looking for Docker in Docker support?" %}
 
-Docker in Docker support (DinD) is currently limited to Organizations on the enterprise plan.
+Docker-in-Docker (DinD) runs on a
+[dedicated compute cluster](/docs/features/ci-features/dedicated-compute-cluster). Every agent in
+the cluster can run DinD, so your tasks can build and push container images or run Testcontainers.
+Request the add-on under **Settings > Add-ons**.
 
-If you're interested in our [Enterprise plan please reach out!](/contact/sales)
+Nx Enterprise [single-tenant](/docs/enterprise/single-tenant/overview) customers get DinD through
+their dedicated deployment.
 {% /aside %}
 
 ```yaml

astro-docs/src/content/docs/reference/Nx Cloud/release-notes.mdoc

@@ -251,7 +251,7 @@ nxApi:
 
 ##### Updates
 
-- Feat: [Polygraph availability](/docs/enterprise/polygraph) (Conformance, Workspace Graph, Custom Workflows)
+- Feat: Conformance, Workspace Graph, and Custom Workflows availability
 - Feat: Nx 21 [continuous tasks](https://nx.dev/blog/nx-21-continuous-tasks) support
 - Feat: Download artifacts button
   - When you view a task that just ran in CI on the NxCloud UI, there is now a button to download any artifacts that task produced directly from your browser

astro-docs/src/content/docs/reference/environment-variables.mdoc

@@ -44,42 +44,47 @@ The following environment variables are ones that you can set to change the beha
 
 ### Advanced
 
-| Property                                   | Type    | Description                                                                                                                                                                                                                                                                                          |
-| ------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `NX_ADD_PLUGINS`                           | boolean | If set to `false`, Nx will not add plugins to infer tasks. This is `true` by default.                                                                                                                                                                                                                |
-| `NX_CACHE_PROJECT_GRAPH`                   | boolean | If set to `false`, disables the project graph cache. Most useful when developing a plugin that modifies the project graph.                                                                                                                                                                           |
-| `NX_COMPILE_CACHE`                         | boolean | If set to `false`, disables Node's built-in V8 bytecode compile cache for Nx processes (CLI, daemon, plugin workers). The cache is enabled by default on Node 22.8+ and speeds up repeated invocations by reusing compiled bytecode. Has no effect on older Node versions.                           |
-| `NX_DAEMON_SOCKET_DIR`                     | string  | Alias of `NX_SOCKET_DIR`, used only when `NX_SOCKET_DIR` is not set. Despite the name, it controls all Nx socket placements, not just the daemon socket. Prefer `NX_SOCKET_DIR` in new setups.                                                                                                       |
-| `NX_FORCE_REUSE_CACHED_GRAPH`              | boolean | If set to `true`, Nx will reuse an existing cached project graph when available and skip recomputing it. Useful in short-lived CI steps that run immediately after a step which already computed the graph.                                                                                          |
-| `NX_FORMAT_SORT_TSCONFIG_PATHS`            | boolean | If set to `true`, generators will sort the TypeScript path mappings in the root tsconfig file.                                                                                                                                                                                                       |
-| `NX_GENERATE_QUIET`                        | boolean | If set to `true`, will prevent Nx logging file operations during generate                                                                                                                                                                                                                            |
-| `NX_ISOLATE_PLUGINS`                       | boolean | Forces plugin isolation on or off, overriding the automatic detection. Set to `true` to always run inference plugins in isolated workers, or `false` to always run them in-process.                                                                                                                  |
-| `NX_MIGRATE_INSTALL_CONCURRENCY`           | number  | Limits the number of concurrent package installs when fetching migration metadata. Useful for avoiding package manager cache conflicts on Windows with private registries. If not set, installs run with no concurrency limit.                                                                       |
-| `NX_MIGRATE_SKIP_REGISTRY_FETCH`           | boolean | If set to `true`, will skip fetching metadata from the registry and instead use the installation method directly.                                                                                                                                                                                    |
-| `NX_NATIVE_COMMAND_RUNNER`                 | boolean | If set to `false`, disables the native pseudo-terminal command runner and falls back to the standard Node.js child process. Enabled by default.                                                                                                                                                      |
-| `NX_NATIVE_FILE_CACHE_DIRECTORY`           | string  | The cache for native `.node` files is stored under a global temp directory by default. Set this variable to use a different directory. This is interpreted as an absolute path.                                                                                                                      |
-| `NX_NATIVE_FILE_LOGGING`                   | string  | Enables the native (Rust) tracing logger and writes logs to `.nx/workspace-data/nx.log`. Accepts the same filter directives as `NX_NATIVE_LOGGING` (e.g. `debug`, `info`, `[{project_name=myapp}]`). Useful for debugging native code paths.                                                         |
-| `NX_NATIVE_LOGGING`                        | string  | Filter directive for the native (Rust) tracing logger. Defaults to `nx::native=info`. Set to a log level (`trace`, `debug`, `info`, `warn`, `error`, `off`) to control all native logs, or scope by crate or module (e.g. `nx=trace`, `nx::native::tasks::hashers=debug`, `[{project_name=myapp}]`). |
-| `NX_PERF_LOGGING`                          | boolean | If set to `true`, will print debug information useful for profiling executors and Nx itself                                                                                                                                                                                                          |
-| `NX_PLUGIN_NO_TIMEOUTS`                    | boolean | If set to `true`, plugin operations will not timeout                                                                                                                                                                                                                                                 |
-| `NX_PREFER_NODE_STRIP_TYPES`               | boolean | If set to `true` and running on Node.js 22.6+, Nx will use Node.js native TypeScript type stripping instead of `@swc-node/register` or `ts-node` when loading TypeScript configuration files. This improves performance.                                                                             |
-| `NX_PREFER_TS_NODE`                        | boolean | If set to `true`, Nx will use `ts-node` for local execution of plugins even if `@swc-node/register` is installed.                                                                                                                                                                                    |
-| `NX_PROFILE`                               | string  | Prepend `NX_PROFILE=profile.json` before running targets with Nx to generate a file that be [loaded in Chrome dev tools](/docs/troubleshooting/performance-profiling) to visualize the performance of Nx across multiple processes.                                                                  |
-| `NX_REJECT_UNKNOWN_LOCAL_CACHE`            | boolean | Legacy cache safety toggle. Set to `0` or `false` to allow reading a local cache that wasn't populated by the current machine. Not supported with the new database cache. See [legacy cache](/docs/reference/deprecated/legacy-cache#nxrejectunknownlocalcache).                                     |
-| `NX_RUNNER`                                | string  | The name of task runner from the config to use. Can be overridden on the command line with `--runner`. Not read if `NX_TASKS_RUNNER` is set.                                                                                                                                                         |
-| `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN` | string  | Bearer token passed as the `Authorization` header when contacting the self-hosted remote cache server configured via `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`.                                                                                                                                           |
-| `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`       | string  | URL of a self-hosted remote cache server. When set, Nx uses this endpoint for remote cache reads and writes instead of Nx Cloud.                                                                                                                                                                     |
-| `NX_SKIP_ATOMIZER_VALIDATION`              | boolean | If set to `true`, suppresses the atomizer warning Nx shows when Nx Cloud isn't configured.                                                                                                                                                                                                           |
-| `NX_SKIP_FORMAT`                           | boolean | If set to `true`, skips Prettier formatting in generators and migrations. Useful for repositories that use alternative formatters like Biome, dprint, or have custom formatting requirements.                                                                                                        |
-| `NX_SKIP_LOG_GROUPING`                     | boolean | If set to `true`, Nx will not group command's logs on CI.                                                                                                                                                                                                                                            |
-| `NX_SKIP_NATIVE_FILE_CACHE`                | boolean | If set to `true`, disables the native `.node` file cache. Nx otherwise copies native bindings to a cache directory to avoid file-locking issues when multiple processes load them.                                                                                                                   |
-| `NX_SKIP_PROVENANCE_CHECK`                 | boolean | If set to `true`, skips `npm` provenance verification when installing packages during `nx migrate`. This is a security-sensitive check. Only disable it if you understand the implications.                                                                                                          |
-| `NX_SKIP_VSCODE_EXTENSION_INSTALL`         | boolean | If set to `true`, skips the automatic installation of the Nx Console extension for supported editors. Set this in environments where the temp file that we store this information in otherwise isn't accessible.                                                                                     |
-| `NX_SOCKET_DIR`                            | string  | Directory for all Nx sockets (daemon, forked process, and plugin). Set this to a shorter path when the default temp directory produces a socket path that exceeds the OS limit. Takes precedence over `NX_DAEMON_SOCKET_DIR`.                                                                        |
-| `NX_TASKS_RUNNER`                          | string  | The name of task runner from the config to use. Can be overridden on the command line with `--runner`. Preferred over `NX_RUNNER`.                                                                                                                                                                   |
-| `NX_TASKS_RUNNER_DYNAMIC_OUTPUT`           | boolean | If set to `false`, will use non-dynamic terminal output strategy (what you see in CI), even when you terminal can support the dynamic version                                                                                                                                                        |
-| `NX_USE_V8_SERIALIZER`                     | boolean | If set to `true`, Nx will use v8 serialization in the pseudo-IPC channel between the daemon and task processes instead of JSON. Improves throughput for workspaces with large task payloads.                                                                                                         |
-| `NX_WRAPPER_SKIP_INSTALL`                  | boolean | If set to `true`, the `.nx/nxw.js` wrapper skips verifying and self-installing the pinned Nx version before each command.                                                                                                                                                                            |
+| Property                                   | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NX_ADD_PLUGINS`                           | boolean | If set to `false`, Nx will not add plugins to infer tasks. This is `true` by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `NX_CACHE_PROJECT_GRAPH`                   | boolean | If set to `false`, disables the project graph cache. Most useful when developing a plugin that modifies the project graph.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `NX_COMPILE_CACHE`                         | boolean | If set to `false`, disables Node's built-in V8 bytecode compile cache for Nx processes (CLI, daemon, plugin workers). The cache is enabled by default on Node 22.8+ and speeds up repeated invocations by reusing compiled bytecode. Has no effect on older Node versions.                                                                                                                                                                                                                                                                                                                                                   |
+| `NX_COMPLETE`                              | string  | Internal. Set by the shell completion wrapper scripts (generated by `nx completion <shell>`) to put Nx in tab-completion mode. The value is the shell name (`bash`, `zsh`, `fish`, or `powershell`). Do not set this manually.                                                                                                                                                                                                                                                                                                                                                                                               |
+| `NX_DAEMON_SOCKET_DIR`                     | string  | Alias of `NX_SOCKET_DIR`, used only when `NX_SOCKET_DIR` is not set. Despite the name, it controls all Nx socket placements, not just the daemon socket. Prefer `NX_SOCKET_DIR` in new setups.                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `NX_FORCE_REUSE_CACHED_GRAPH`              | boolean | If set to `true`, Nx will reuse an existing cached project graph when available and skip recomputing it. Useful in short-lived CI steps that run immediately after a step which already computed the graph.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `NX_FORMAT_SORT_TSCONFIG_PATHS`            | boolean | If set to `true`, generators will sort the TypeScript path mappings in the root tsconfig file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `NX_GENERATE_QUIET`                        | boolean | If set to `true`, will prevent Nx logging file operations during generate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `NX_INVOCATION_ROOT_PID`                   | number  | Internal. Set by Nx to the PID of the root Nx process. Used to detect recursive task invocation loops across nested Nx processes. Do not set this manually.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `NX_ISOLATE_PLUGINS`                       | boolean | Forces plugin isolation on or off, overriding the automatic detection. Set to `true` to always run inference plugins in isolated workers, or `false` to always run them in-process.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `NX_MIGRATE_INSTALL_CONCURRENCY`           | number  | Limits the number of concurrent package installs when fetching migration metadata. Useful for avoiding package manager cache conflicts on Windows with private registries. If not set, installs run with no concurrency limit.                                                                                                                                                                                                                                                                                                                                                                                               |
+| `NX_MIGRATE_SKIP_REGISTRY_FETCH`           | boolean | **Deprecated, will be removed in Nx 24** - use `NX_MIGRATE_USE_REGISTRY_RESOLUTION` (set to `false`) instead. If set to `true`, will skip fetching metadata from the registry and instead use the installation method directly. Legacy alias for setting `NX_MIGRATE_USE_REGISTRY_RESOLUTION` to `false`; the newer variable takes precedence when both are set.                                                                                                                                                                                                                                                             |
+| `NX_MIGRATE_USE_REGISTRY_RESOLUTION`       | boolean | Whether `nx migrate` resolves package versions and migration metadata via the npm registry (faster) instead of a package-manager install. Set to `false` to always resolve through your package manager. Takes precedence over the legacy `NX_MIGRATE_SKIP_REGISTRY_FETCH` variable and the `migrate.useRegistryResolution` setting in `nx.json`. Defaults to `true`.                                                                                                                                                                                                                                                        |
+| `NX_NATIVE_COMMAND_RUNNER`                 | boolean | If set to `false`, disables the native pseudo-terminal command runner and falls back to the standard Node.js child process. Enabled by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `NX_NATIVE_FILE_CACHE_DIRECTORY`           | string  | The cache for native `.node` files is stored under a global temp directory by default. Set this variable to use a different directory. This is interpreted as an absolute path.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `NX_NATIVE_FILE_LOGGING`                   | string  | Enables the native (Rust) tracing logger and writes logs to `.nx/workspace-data/nx.log`. Accepts the same filter directives as `NX_NATIVE_LOGGING` (e.g. `debug`, `info`, `[{project_name=myapp}]`). Useful for debugging native code paths.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `NX_NATIVE_LOGGING`                        | string  | Filter directive for the native (Rust) tracing logger. Defaults to `nx::native=info`. Set to a log level (`trace`, `debug`, `info`, `warn`, `error`, `off`) to control all native logs, or scope by crate or module (e.g. `nx=trace`, `nx::native::tasks::hashers=debug`, `[{project_name=myapp}]`).                                                                                                                                                                                                                                                                                                                         |
+| `NX_PERF_LOGGING`                          | boolean | If set to `true`, will print debug information useful for profiling executors and Nx itself                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `NX_PLUGIN_NO_TIMEOUTS`                    | boolean | If set to `true`, plugin operations will not timeout                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `NX_PREFER_NODE_STRIP_TYPES`               | boolean | When the Node.js runtime exposes native TypeScript stripping (`process.features.typescript` - Node 23.6+ unflagged, 22.18+ LTS unflagged, or 22.6+ with `--experimental-strip-types`), Nx loads TypeScript configuration files via Node directly (faster, no `@swc-node/register`/`ts-node` registration). Set to `false` to opt out and force `@swc-node/register` or `ts-node`. When native stripping fails on an unsupported construct (e.g. `enum`, runtime `namespace`), Nx falls back to `@swc-node/register`/`ts-node` + `tsconfig-paths` automatically; set `NX_VERBOSE_LOGGING=true` to see when fallback triggers. |
+| `NX_DISABLE_TSCONFIG_PATHS`                | boolean | Skip `tsconfig-paths` registration on the `@swc-node/register`/`ts-node` fallback path. Set to `true` when relying on package manager workspaces (pnpm/yarn/npm) for project linking and `tsconfig` path aliases aren't needed.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `NX_PREFER_TS_NODE`                        | boolean | If set to `true`, Nx will use `ts-node` for local execution of plugins even if `@swc-node/register` is installed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `NX_PROCESS_KILL_GRACE_PERIOD`             | number  | Time in milliseconds to wait for child processes to exit gracefully before force-killing them. Defaults to `5000`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `NX_PROFILE`                               | string  | Prepend `NX_PROFILE=profile.json` before running targets with Nx to generate a file that be [loaded in Chrome dev tools](/docs/troubleshooting/performance-profiling) to visualize the performance of Nx across multiple processes.                                                                                                                                                                                                                                                                                                                                                                                          |
+| `NX_REJECT_UNKNOWN_LOCAL_CACHE`            | boolean | Legacy cache safety toggle. Set to `0` or `false` to allow reading a local cache that wasn't populated by the current machine. Not supported with the new database cache. See [legacy cache](/docs/reference/deprecated/legacy-cache#nxrejectunknownlocalcache).                                                                                                                                                                                                                                                                                                                                                             |
+| `NX_RUNNER`                                | string  | The name of task runner from the config to use. Can be overridden on the command line with `--runner`. Not read if `NX_TASKS_RUNNER` is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN` | string  | Bearer token passed as the `Authorization` header when contacting the self-hosted remote cache server configured via `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`       | string  | URL of a self-hosted remote cache server. When set, Nx uses this endpoint for remote cache reads and writes instead of Nx Cloud.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `NX_SKIP_ATOMIZER_VALIDATION`              | boolean | If set to `true`, suppresses the atomizer warning Nx shows when Nx Cloud isn't configured.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `NX_SKIP_FORMAT`                           | boolean | If set to `true`, skips Prettier formatting in generators and migrations. Useful for repositories that use alternative formatters like Biome, dprint, or have custom formatting requirements.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `NX_SKIP_LOG_GROUPING`                     | boolean | If set to `true`, Nx will not group command's logs on CI.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `NX_SKIP_NATIVE_FILE_CACHE`                | boolean | If set to `true`, disables the native `.node` file cache. Nx otherwise copies native bindings to a cache directory to avoid file-locking issues when multiple processes load them.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `NX_SKIP_PROVENANCE_CHECK`                 | boolean | If set to `true`, skips `npm` provenance verification when installing packages during `nx migrate`. This is a security-sensitive check. Only disable it if you understand the implications.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `NX_SKIP_VSCODE_EXTENSION_INSTALL`         | boolean | If set to `true`, skips the automatic installation of the Nx Console extension for supported editors. Set this in environments where the temp file that we store this information in otherwise isn't accessible.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `NX_SOCKET_DIR`                            | string  | Directory for all Nx sockets (daemon, forked process, and plugin). Set this to a shorter path when the default temp directory produces a socket path that exceeds the OS limit. Takes precedence over `NX_DAEMON_SOCKET_DIR`.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `NX_TASKS_RUNNER`                          | string  | The name of task runner from the config to use. Can be overridden on the command line with `--runner`. Preferred over `NX_RUNNER`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `NX_TASKS_RUNNER_DYNAMIC_OUTPUT`           | boolean | If set to `false`, will use non-dynamic terminal output strategy (what you see in CI), even when you terminal can support the dynamic version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `NX_USE_V8_SERIALIZER`                     | boolean | If set to `true`, Nx will use v8 serialization in the pseudo-IPC channel between the daemon and task processes instead of JSON. Improves throughput for workspaces with large task payloads.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `NX_WRAPPER_SKIP_INSTALL`                  | boolean | If set to `true`, the `.nx/nxw.js` wrapper skips verifying and self-installing the pinned Nx version before each command.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 ## Plugin environment variables
 
@@ -116,11 +121,11 @@ Similar to the Nx CLI, Nx Cloud also uses the `NX_VERBOSE_LOGGING` environment v
 | Property                              | Type    | Description                                                                                                                                                                                                                |
 | ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `NX_BRANCH`                           | string  | The current branch name. For most CI providers, `nx-cloud` determines this automatically. Must be set to the PR number for GitHub, BitBucket and GitLab integrations to work properly.                                     |
-| `NX_CLOUD_DISABLE_METRICS_COLLECTION` | boolean | Disables collection of CPU and memory metrics during task execution (enabled by default for enterprise users on Nx 22.1+). See [Task Resource Usage](/docs/guides/nx-cloud/ci-resource-usage).                             |
-| `NX_CLOUD_METRICS_DIRECTORY`          | string  | Directory where Nx writes resource metrics during task execution. See [Task Resource Usage](/docs/guides/nx-cloud/ci-resource-usage).                                                                                      |
+| `NX_CLOUD_DISABLE_METRICS_COLLECTION` | boolean | Disables collection of CPU and memory metrics during task execution (enabled by default for enterprise users on Nx 22.1+). See [Resource Usage](/docs/features/ci-features/resource-usage).                                |
+| `NX_CLOUD_METRICS_DIRECTORY`          | string  | Directory where Nx writes resource metrics during task execution. See [Resource Usage](/docs/features/ci-features/resource-usage).                                                                                         |
 | `NX_CI_EXECUTION_ID`                  | string  | A unique identifier for the current CI run or job. For most CI providers, `nx-cloud` determines this automatically. The value on the main job must match the value on all agents.                                          |
 | `NX_CI_EXECUTION_ENV`                 | string  | Used when you have multiple main jobs (e.g., running CI on both Linux and Windows). The main job with this env variable will connect to agents with the same env name.                                                     |
-| `NX_AGENT_LAUNCH_TEMPLATE`            | string  | Should only be used when running agents with Manual DTE. Attaches a launch template type to your agents to leverage assignment rules for task distribution.                                                                |
+| `NX_AGENT_LAUNCH_TEMPLATE`            | string  | Should only be used when you bring your own compute. Attaches a launch template type to your agents to leverage assignment rules for task distribution.                                                                    |
 | `NX_CLOUD_ACCESS_TOKEN`               | string  | Configure the Nx Cloud access token. Takes precedence over the `accessToken` property in `nx.json`. Common to have a read-only token in `nx.json` and a read-write token set via this environment variable in CI.          |
 | `NX_CLOUD_API`                        | string  | The URL of the Nx Cloud instance to connect to. Overrides `nxCloudUrl` in `nx.json`.                                                                                                                                       |
 | `NX_CLOUD_ENCRYPTION_KEY`             | string  | Enable end-to-end encryption of artifacts. Artifacts will be encrypted/decrypted on your machine. Can also be set via the `encryptionKey` property in `nx.json`.                                                           |

astro-docs/src/content/docs/reference/nx-cloud-cli.mdoc

@@ -373,7 +373,7 @@ If you accidentally run this command locally, remove all generated marker files
 | Option                          | Type    | Description                                                                                                                                                                               | Default |
 | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
 | `--distribute-on`               | string  | Configure the number of agents, [launch templates](/docs/reference/nx-cloud/launch-templates) and [assignment rules](/docs/reference/nx-cloud/assignment-rules) for distributed execution |         |
-| `--assignment-rules`            | string  | Path to the [assignment rules configuration](/docs/reference/nx-cloud/assignment-rules#using-assignment-rules-with-manual-dte) for manual distribution.                                   |         |
+| `--assignment-rules`            | string  | Path to the [assignment rules configuration](/docs/reference/nx-cloud/assignment-rules#using-assignment-rules-when-you-bring-your-own-compute) for manual distribution.                   |         |
 | `--require-explicit-completion` | boolean | Disable automatic completion monitoring and require explicit `nx complete-ci-run`                                                                                                         | `false` |
 | `--stop-agents-after`           | string  | Comma-separated list of targets after which agents should terminate                                                                                                                       |         |
 | `--stop-agents-on-failure`      | boolean | Terminate all agents when a command fails. This flag does not interrupt the command itself. To cancel the command on failure use [nxBail](/docs/reference/nx-commands)                    | `true`  |
@@ -575,7 +575,7 @@ nx affected -t build --no-dte
 
 ### `nx-cloud start-agent`
 
-Starts an agent process for [manual distributed task execution](/docs/guides/nx-cloud/manual-dte). The agent waits for Nx Cloud to assign tasks that have been distributed by the main CI job via `start-ci-run`. For automatic agent management, use [Nx Agents](/docs/features/ci-features/distribute-task-execution) instead.
+Starts an agent process when you [bring your own compute](/docs/guides/nx-cloud/bring-your-own-compute). The agent waits for Nx Cloud to assign tasks that have been distributed by the main CI job via `start-ci-run`. To have Nx Cloud provision and manage the agents for you, see [Nx Agents](/docs/features/ci-features/distribute-task-execution).
 
 This command is the same as running `nx start-agent`.
 
@@ -599,7 +599,7 @@ Use the `NX_AGENT_NAME` environment variable to assign a name to the agent for i
 NX_AGENT_NAME=agent-1 npx nx-cloud start-agent
 ```
 
-For complete examples across different CI providers, see the [Manual Distributed Task Execution guide](/docs/guides/nx-cloud/manual-dte).
+For complete examples across different CI providers, see the [bring your own compute guide](/docs/guides/nx-cloud/bring-your-own-compute).
 
 ### `nx-cloud stop-all-agents`