fix(js): handle batch ensure-package in tests

Co-authored-by: AgentEnder <AgentEnder@users.noreply.github.com>

.cargo/config.toml

@@ -1,3 +1,6 @@
+[env]
+JEMALLOC_SYS_WITH_MALLOC_CONF = "dirty_decay_ms:1000,muzzy_decay_ms:0"
+
 [build]
 target-dir = 'dist/target'
 

.claude/settings.json

@@ -30,5 +30,18 @@
   "enableAllProjectMcpServers": true,
   "env": {
     "BASH_MAX_TIMEOUT_MS": "1800000"
+  },
+  "extraKnownMarketplaces": {
+    "nx-claude-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "nrwl/nx-ai-agents-config",
+        "ref": "experimental"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "nx@nx-claude-plugins": true,
+    "polygraph@nx-claude-plugins": true
   }
 }

.claude/skills/diagnose-sandbox-report/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: diagnose-sandbox-report
+description: >
+  Diagnose Nx sandbox violations from a sandbox report. Use when asked to
+  "diagnose sandbox", "analyze sandbox report", "investigate sandbox violations",
+  "check violations", when given a sandbox report JSON file or URL to investigate,
+  or when the user pastes a staging.nx.app sandbox-report URL. Also trigger when
+  discussing unexpected reads/writes in Nx task execution. Guides structured
+  investigation of why tasks read/write undeclared files, determines root causes,
+  and recommends fixes.
+argument-hint: '<sandbox-report.json or URL> [--filter <file|pattern|list>]'
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Diagnose Sandbox Report
+
+## Overview
+
+Sandbox violations occur when an Nx task reads files not declared as inputs or writes files not declared as outputs.
+
+**Unexpected reads** are one of:
+
+1. **Missing input** (most likely) — the process legitimately needs this file. Understand what the process does and why the access makes sense, then declare it as an input.
+2. **Potential sandboxing gap** (last resort) — the access is irrelevant to correctness and should be filtered/ignored by the sandbox. Only conclude this after exhausting every possibility for it being a missing input.
+
+**Unexpected writes** follow the same logic:
+
+1. **Missing output** (most likely) — the process legitimately produces this file.
+2. **Potential sandboxing gap** (last resort) — same as above.
+
+The default assumption is that an unexpected access IS a missing declaration. The investigation's job is to understand WHY the process accesses the file — not to find reasons it shouldn't.
+
+## Critical Rules
+
+1. **NEVER read the sandbox report JSON directly** — these files are too large for the Read tool (50K+ tokens). Do NOT use `Read`, `cat`, `head`, `python3`, or `jq` on the raw report. All report parsing is handled by the script.
+2. **ALWAYS run the context-gathering script as the very first step** — no manual parsing, no ad-hoc python/jq on the report file. The script does everything deterministically.
+3. If the script fails, **report the error and stop**. Do not attempt manual parsing as a fallback.
+4. **Identify the inferring plugin BEFORE proposing any fix** — check `inference.plugin` in the script output or run `jq '.targets.<target>.metadata' <detail-file>`. Fixing the wrong plugin wastes entire investigation rounds.
+5. **Verify hypotheses empirically before committing to them** — see Principle 4 and the Phase 2 instrumentation guidance.
+
+## Workflow
+
+### Phase 0: Input
+
+User provides one of:
+
+- Path to a sandbox report JSON file
+- A URL to a sandbox report — pass it directly to the script, it handles downloading
+- A task ID + CIPE URL (fetch report via MCP if available)
+- Inline violation data
+
+If a task ID is provided but no report, ask the user for the report file.
+
+**Filtering**: Most invocations will focus on specific files, not the entire report. The user may specify:
+
+- A single file: `e2e.log`
+- A comma-separated list: `apps/nx-cloud/e2e.log,apps/nx-cloud/build/client/assets/main.js`
+- A glob pattern: `*.tsbuildinfo`, `apps/nx-cloud/build/**`
+- A directory prefix: `apps/nx-cloud/build/client/assets`
+
+When the user specifies files to focus on, pass them via `--filter` to the script. When they don't specify a filter and the report has many violations, summarize the groupings (by directory, extension) and ask which group(s) to investigate first rather than trying to investigate everything at once.
+
+### Phase 1: Deterministic Pre-Processing
+
+Run the context-gathering script **immediately** — this is the first tool call after reading the user's input.
+
+Call it exactly as shown — do NOT append `2>&1` or `2>/dev/null` (the script manages its own stderr internally). Run in the **foreground** (no `run_in_background`) with a **3-minute timeout** — reports can be large and the script runs the task + multiple nx commands:
+
+```bash
+npx tsx ${CLAUDE_SKILL_DIR}/scripts/gather-sandbox-context.ts <report.json or URL> [--filter <pattern>] [--workspace <path>]
+```
+
+Pass `--filter` when the user wants to focus on specific files or patterns. The script filters violations before all downstream processing (grouping, validation, classification), so the output only contains relevant data.
+
+The script produces two outputs:
+
+**stdout** (~3-5KB compact brief) — everything needed to start investigating:
+
+- `summary`: violation counts (total, filtered, confirmed vs undeclared)
+- `undeclaredFiles`: the actual file paths that are true violations
+- `grouping`: violations grouped by directory and extension
+- `commands`: processes with violations (pid, cmd, executable, arguments, counts) — no full file lists
+- `classificationSummary`: counts per category (cross-project, build artifacts, config files, etc.)
+- `crossProjectDependencyCheck`: whether cross-project file owners are in the task's dependency chain
+- `staleDeclarations`: grouped analysis of expectedInputsNotRead / expectedOutputsNotWritten
+- `dependentTasksOutputFiles`: extracted from target inputs config and named inputs — shows what dep output globs are declared (critical for cross-project violations)
+- `executorInfo`: executor name and resolved source path in `node_modules` — read this file to understand how the tool is invoked
+- `checkSample`: results of `--check` on up to 5 undeclared files (catches false positives early)
+- `inference` + `pluginRegistration`: plugin metadata
+- `verificationCommands`: pre-built `--check` commands with the correct task ref
+- `detailFile`: path to the full detail JSON
+
+**detail file** (`/tmp/sandbox-diagnosis-detail-<project>-<target>.json`) — full data for drill-down. Structure:
+
+- `processTree.processTree`: array of `{pid, cmd, parentPid}` entries
+- `processTree.processPidToCmd`: `{ "pid": "command string" }` map
+- `processTree.readsByPid`: `{ "pid": ["file1", "file2"] }` — violated reads grouped by PID
+- `processTree.writesByPid`: `{ "pid": ["file1", "file2"] }` — violated writes grouped by PID
+- `targetConfig`: full target configuration (executor, options, inputs, outputs, dependsOn)
+- `projectConfig`: full project configuration
+- `resolvedInputs`: `{ files: [...], depOutputs: [...], runtime: [...], environment: [...] }`
+- `resolvedOutputs`: `{ outputPaths: [...], expandedOutputs: [...] }`
+- `validation`: `{ reads: { confirmed: [...], undeclared: [...] }, writes: { ... } }`
+- `classification`: `{ reads: { crossProject, buildArtifacts, configFiles, ... }, writes: { ... } }`
+
+Read the brief output — it has everything to start. Use `jq` on the detail file only when you need to drill into specific sections. When querying the detail file, use the structure above — do not guess the schema. Do NOT use Python, ad-hoc scripts, or the Read tool on the detail file — only `jq`.
+
+For reports with many violations, use `--filter` to narrow scope. When investigating without a filter, use the `grouping` data to identify patterns and prioritize — don't try to trace every file individually.
+
+If `summary.undeclaredReads` and `summary.undeclaredWrites` are both 0, all violations were resolved by the script's validation against resolved inputs/outputs. Report this to the user — no further investigation needed.
+
+The `commands` array pre-parses each process — use `executable` and `arguments` to identify the tool without re-parsing `cmd`. When many files share the same root cause, group them under one finding using a glob pattern or count (e.g., "88 `.d.ts` files matching `packages/nx/dist/**/*.d.ts`").
+
+### Phase 2: Command Analysis — the core investigation
+
+**This is the most important phase.** The goal is to determine with 100% certainty why each process reads or writes each violated file. Do not classify violations from file names or paths alone — trace the actual causal chain from command → config → file access.
+
+#### Step 1: Understand the command
+
+The brief's `commands` array pre-parses each process. Use the `executable` and `arguments` fields directly — don't re-parse `cmd`. Identify:
+
+- The tool (from `executable`)
+- The arguments (target files/dirs, config flags, extensions — from `arguments`)
+- The working directory (from executor options or project root)
+
+#### Step 2: Trace why the command accesses each violated file
+
+For each violated file, establish the **exact causal chain** that leads the command to read or write it. The approach is the same regardless of tool:
+
+1. Identify the tool's config file (usually in the project root or workspace root)
+2. Read the config and trace file references: `includes`, `extends`, `presets`, entry points, plugins
+3. Follow the reference chain until you can explain exactly why the violated file is accessed
+
+Common causal patterns:
+
+- **Config chain walk-up**: tool reads config, config extends another, chain reaches the violated file (e.g., tsconfig `extends`, eslint config chain, jest preset chain)
+- **Directory traversal**: tool scans a directory for matching files and reads everything, including files it won't process (e.g., jest-haste-map scanning `.next/`, eslint reading `.d.ts` alongside `.ts`)
+- **Dependency resolution**: tool resolves imports/requires and follows the dependency graph to files outside the project (e.g., esbuild/vite/webpack resolving workspace packages to their dist outputs)
+- **Plugin/transformer loading**: tool loads plugins or transformers that read additional files (e.g., ts-jest loading tsconfig for TypeScript compilation)
+
+For any tool, read its source code in `node_modules` to understand its file discovery behavior. Don't assume — trace the actual code.
+
+**You must be able to explain the full path:** e.g., "eslint loads `.eslintrc.json` → configures `@typescript-eslint/parser` → parser resolves `parserOptions.project` → walks up to find `tsconfig.json` → reads it." If you can't trace the full path, keep investigating — do not guess.
+
+**When theoretical analysis is inconclusive, verify empirically.** For difficult cases, instrument `node_modules` with interceptors to capture real stack traces. For example, patch `fs.readFileSync` in the tool's entry point to log stack traces when the violated file is accessed. A confirmed stack trace is worth more than multiple rounds of code reading.
+
+#### Step 3: Confirm the violation with `--check`
+
+**This step is mandatory — do not skip it.** The script already runs `--check` on a sample of up to 5 undeclared files (see `checkSample` in the brief). Review those results first — if the sample files are confirmed as inputs/outputs, the corresponding violations are false positives.
+
+For files not in the sample, use the pre-generated commands from `verificationCommands` in the brief:
+
+```bash
+npx nx show target inputs <project>:<target> --check <violated-read-files>
+npx nx show target outputs <project>:<target> --check <violated-write-files>
+```
+
+If the commands fail because output files don't exist (e.g., the script's task run timed out), run the task first with `verificationCommands.runTask`.
+
+If `--check` shows the file IS already an input/output, the violation is a false positive from the script's static analysis. If it confirms the file is NOT an input/output, proceed to classification.
+
+#### Step 4: Classify
+
+With the causal chain established and the violation confirmed, classify into one of these categories:
+
+1. **Missing input/output** (most common) — the process legitimately needs this file. Understand why:
+   - **Direct dependency** — the tool needs this file to do its job (e.g., tsc reads referenced tsconfigs, eslint loads config chain)
+   - **Transitive dependency** — a config file references another file that references this one (e.g., jest preset → resolver → module). Trace the full chain.
+   - **Directory traversal side effect** — the tool reads all files in a directory even if it only processes some (e.g., eslint reads `.d.ts` files while linting `.ts`). Still a legitimate access from the tool's perspective.
+
+2. **Bad tool configuration** — the tool accesses a file it shouldn't because its scope is too broad. The fix is fixing the tool's config, NOT adding an input. Investigate:
+   - Is the command targeting too broad a directory? (e.g., `eslint .` instead of `eslint src/`)
+   - Is a config file missing ignore/exclude rules? (e.g., eslint processing a file type it should skip)
+   - Is a plugin inferring a target for a project that doesn't match? (e.g., eslint target on a non-JS project)
+   - Is an env var causing the tool to behave differently?
+
+3. **Potential sandboxing gap** (last resort) — the access is genuinely irrelevant to correctness (PID files, temp sockets, dev server logs that no task consumes). Only conclude this after exhausting categories 1 and 2.
+
+### Phase 3: Deep Investigation
+
+For violations that aren't immediately obvious, investigate further:
+
+#### If the target is inferred by a plugin
+
+1. Identify which plugin from `inference.plugin` in the brief output, or `nx show project --json` metadata
+2. Read the plugin's `createNodesV2` implementation to understand inference logic
+3. Determine if this project should have this target at all
+4. Check if the plugin has `include`/`exclude` patterns in `nx.json` that should filter this project
+5. **Check for input override layers** — `project.json`, `package.json`, or `nx.json` `targetDefaults` may override plugin-inferred inputs, rendering plugin-level fixes invisible. Check all three before concluding a plugin fix is sufficient.
+
+#### If violations come from a subprocess
+
+1. Trace the process tree: which parent spawned the subprocess?
+2. Why does the subprocess exist? (dev server for e2e, worker thread, build tool subprocess)
+3. What environment does the subprocess inherit? (env vars, cwd)
+4. Does the subprocess access files in a different project's directory?
+
+#### If violations involve config file reference chains
+
+1. Read the config file (jest.config, tsconfig, .eslintrc)
+2. Trace all file references: `preset`, `extends`, `references`, `setupFiles`, `resolver`, `moduleNameMapper`, `transform`, etc.
+3. Recursively resolve references (preset → preset → files)
+4. Determine which referenced files are not declared as task inputs
+
+#### If violations involve dependency task outputs
+
+1. Check `dependsOn` to understand task dependency chain
+2. Check `dependentTasksOutputFiles` glob pattern — is it too narrow?
+3. Compare the glob against actual file types the tool reads from dependencies (e.g., `**/*.d.ts` missing `.tsbuildinfo`)
+
+#### Generalizability analysis
+
+After diagnosing the root cause, determine scope:
+
+1. Is this violation specific to this project, or does it affect all projects using this tool/plugin?
+2. What conditions trigger it? (specific config, specific tool version, specific project structure)
+3. Should the fix be per-project (declarative input) or systemic (plugin improvement)?
+4. If the plugin can be made smarter to infer the correct inputs, that's preferable to manual declarations.
+
+### Phase 4: Output
+
+**You MUST present findings using the structured format below before proceeding to any implementation discussion.** Do not use free-form narrative — the structure ensures completeness and makes findings reviewable.
+
+Present findings grouped by category:
+
+```
+=== Sandbox Violation Diagnosis: {project}:{target} ===
+
+## Summary
+Unexpected reads:  N total → M validated as declared → K true violations
+Unexpected writes: N total → M validated as declared → K true violations
+
+## Findings
+
+### [MISSING INPUT] {short description}
+Files: {file list or pattern}
+Process: PID {pid} — {command}
+Why: {why the process legitimately needs this file}
+Scope: {project-specific or affects all projects using this tool/plugin}
+Fix: {where/how to add the input declaration — consider both declarative (add input) and systemic (improve plugin inference) options}
+
+### [MISSING OUTPUT] {short description}
+Files: {file list or pattern}
+Process: PID {pid} — {command}
+Why: {why the process produces this file}
+Scope: {project-specific or affects all projects using this tool/plugin}
+Fix: {where/how to add the output declaration}
+
+### [BAD TOOL CONFIG] {short description}
+Files: {file list or pattern}
+Process: PID {pid} — {command}
+Why: {why the tool accesses files it shouldn't — config too broad, missing ignore, etc.}
+Fix: {specific tool config change}
+
+### [POTENTIAL SANDBOXING GAP] {short description}
+Files: {file list or pattern}
+Process: PID {pid} — {command}
+Why: {why this access is irrelevant to correctness}
+Evidence: {proof that categories 1-2 were exhausted}
+
+### [INVESTIGATE] {short description}
+Files: {file list or pattern}
+Notes: {what's known, what needs more info}
+Question: {what to ask the user or team}
+
+## Stale Declarations
+expectedInputsNotRead: {count and details if relevant}
+expectedOutputsNotWritten: {count and details if relevant}
+
+## Verification Plan
+For each fix, provide the exact commands to verify:
+1. Run the task so output files exist on disk: `npx nx <target> <project> --skip-nx-cache`
+2. Check each violation file is now an input: `npx nx show target <project>:<target> inputs --check <space-separated files>`
+3. For plugin-level fixes: build the plugin, patch node_modules, then verify with steps 1-2
+```
+
+## Principles
+
+1. **Missing declaration is the default.** Most unexpected accesses are legitimate — the process needs the file, it just wasn't declared. Start from this assumption and investigate to understand WHY the access happens.
+2. **The command is the unit of analysis.** Don't classify files in isolation. Understand what the command does and whether each file access makes sense given that command's purpose.
+3. **Trace the full chain.** Plugin inference → target config → executor → command → file access. The root cause is often several layers removed from the symptom.
+4. **Empirical over theoretical.** When code analysis produces a hypothesis, verify it before acting. Instrument `node_modules`, capture stack traces, run with debug flags. Wrong theories waste entire investigation rounds.
+5. **Be thorough.** Read plugin source code, config files, executor implementations. Don't guess based on file names alone.
+6. **Potential sandboxing gaps are last resort.** Only conclude this after exhausting missing declaration and bad tool config. The access must be genuinely irrelevant to correctness.
+7. **Verify claims about Nx behavior in source code.** Any assertion about how Nx works must be traced to the actual implementation. Do not reason from theory or assumptions.
+8. **Prefer systemic fixes over per-project declarations.** If a plugin can be improved to infer correct inputs for all projects, that's better than adding manual input declarations to each project.
+
+## Delegating to Subagents
+
+When the investigation is complex and requires parallel research, you can delegate to subagents. Follow this pattern:
+
+1. **Run the context-gathering script yourself first.** The brief output (~3-5KB) is the shared context all subagents need.
+2. **Include the brief output in each subagent prompt** along with the specific question to investigate. Subagents should NOT run the script again or try to parse the raw report.
+3. **Give subagents the detail file path** so they can `jq` specific sections (process tree, resolved inputs, etc.) without re-running the script.
+4. **Each subagent should answer one focused question**, e.g., "Why does PID 12345 (eslint) read `tsconfig.base.json`? Trace the full causal chain from the eslint config."
+5. **Subagents must still follow the skill principles** — trace full causal chains, verify empirically, use `--check`, don't guess from file names. Include these instructions in the subagent prompt.
+6. **Synthesize subagent results yourself** using the structured Phase 4 output format. Do not delegate the final classification.
+
+## Reference
+
+For the sandbox report data model and field definitions, see `references/data-model.md`.

.claude/skills/diagnose-sandbox-report/references/data-model.md

@@ -0,0 +1,92 @@
+# Sandbox Report Data Model
+
+## Raw Report Structure (JSON)
+
+```typescript
+interface SandboxReport {
+  taskId: string; // "project:target" or "project:target:configuration"
+  sandboxReportId: string;
+  inputs: string[]; // declared input patterns (globs or paths)
+  outputs: string[]; // declared output patterns
+  filesRead: FileAccessEntry[]; // all files actually read
+  filesWritten: FileAccessEntry[]; // all files actually written
+  unexpectedReads?: FileAccessEntry[]; // reads not matching any input pattern
+  unexpectedWrites?: FileAccessEntry[]; // writes not matching any output pattern
+  expectedInputsNotRead?: string[]; // declared inputs never accessed
+  expectedOutputsNotWritten?: string[]; // declared outputs never written
+  processTree?: ProcessTreeEntry[]; // process hierarchy with commands
+}
+
+interface FileAccessEntry {
+  path: string; // workspace-relative file path
+  pid: number; // process ID that accessed the file
+}
+
+interface ProcessTreeEntry {
+  pid: number;
+  cmd: string; // full command string
+  parentPid?: number; // parent process (absent for root)
+}
+```
+
+## Violation Computation
+
+Violations are computed by `findUnexpectedFiles()` using `minimatch`:
+
+- A file is "unexpected" if it does NOT match any declared pattern
+- Patterns without wildcards also match as directory prefixes (`pattern + '/'`)
+- If `unexpectedReads`/`unexpectedWrites` are pre-computed in the report, those are used directly
+
+## Nx CLI Commands for Context
+
+### `nx show target <project:target> --json`
+
+Returns: executor, command, options (merged with configuration), inputs (configured, not resolved), outputs, dependsOn, cache, parallelism, configurations, metadata.
+
+### `nx show target inputs <project:target> --json`
+
+Returns resolved input files (requires files to exist on disk — task must have run):
+
+```json
+{
+  "files": ["workspace-relative paths..."],
+  "runtime": ["node version checks..."],
+  "environment": ["ENV_VAR_NAMES..."],
+  "depOutputs": ["dependency output paths..."],
+  "external": ["external package names..."]
+}
+```
+
+### `nx show target inputs <project:target> --check <files...>`
+
+Validates specific files against declared inputs. Exit code 0 = match, 1 = no match.
+Categories: `files`, `environment`, `runtime`, `external`, `depOutputs`.
+Also detects directory matches (directory containing N input files).
+
+### `nx show target outputs <project:target> --json`
+
+Returns:
+
+```json
+{
+  "outputPaths": ["configured output paths..."],
+  "expandedOutputs": ["glob-expanded actual paths..."],
+  "unresolvedOutputs": ["{options.key} patterns that couldn't resolve..."]
+}
+```
+
+### `nx show target outputs <project:target> --check <files...>`
+
+Validates specific files against declared outputs. Same exit code behavior as inputs.
+
+### `nx show project <project> --json`
+
+Returns full project config. Key fields for sandbox analysis:
+
+- `targets[name].metadata.plugin` — which plugin inferred the target
+- `targets[name].metadata.technologies` — what tech the target uses
+- `root` — project root directory
+
+### `nx graph --view=tasks --targets=<target> --focus=<project> --print --file=stdout`
+
+Returns task dependency graph with task IDs, dependencies, and roots.

.claude/skills/diagnose-sandbox-report/scripts/gather-sandbox-context.ts

@@ -0,0 +1,846 @@
+#!/usr/bin/env npx tsx
+/**
+ * gather-sandbox-context: Parse sandbox report + gather Nx task context
+ * Produces structured JSON for the diagnose-sandbox-report skill
+ *
+ * Usage: npx tsx gather-sandbox-context.ts <report.json or URL> [--filter <pattern>] [--workspace <path>]
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve, basename, extname, dirname } from 'path';
+import { execSync, execFileSync } from 'child_process';
+import { minimatch } from 'minimatch';
+
+// --- CLI argument parsing ---
+
+interface Args {
+  reportFile: string;
+  filter: string | null;
+  workspaceRoot: string;
+}
+
+function parseArgs(): Args {
+  const args = process.argv.slice(2);
+  let reportFile = '';
+  let filter: string | null = null;
+  let workspaceRoot = process.cwd();
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--filter':
+        filter = args[++i];
+        break;
+      case '--workspace':
+        workspaceRoot = args[++i];
+        break;
+      case '--help':
+      case '-h':
+        console.error(
+          'Usage: gather-sandbox-context <report.json or URL> [--filter <pattern>] [--workspace <path>]'
+        );
+        process.exit(1);
+      default:
+        if (args[i].startsWith('-')) {
+          console.error(`Unknown option: ${args[i]}`);
+          process.exit(1);
+        }
+        reportFile = args[i];
+    }
+  }
+
+  if (!reportFile) {
+    console.error(
+      'Usage: gather-sandbox-context <report.json or URL> [--filter <pattern>] [--workspace <path>]'
+    );
+    process.exit(1);
+  }
+
+  return { reportFile, filter, workspaceRoot };
+}
+
+// --- Types ---
+
+interface FileAccessEntry {
+  path: string;
+  pid: number;
+}
+
+interface ProcessTreeEntry {
+  pid: number;
+  cmd: string;
+  parentPid?: number;
+}
+
+interface SandboxReport {
+  taskId: string;
+  unexpectedReads?: FileAccessEntry[];
+  unexpectedWrites?: FileAccessEntry[];
+  expectedInputsNotRead?: string[];
+  expectedOutputsNotWritten?: string[];
+  filesRead?: FileAccessEntry[];
+  filesWritten?: FileAccessEntry[];
+  processTree?: ProcessTreeEntry[];
+}
+
+// --- Helpers ---
+
+function downloadUrl(url: string): string {
+  const tmpPath = `/tmp/sandbox-report-${Date.now()}.json`;
+  try {
+    execFileSync('curl', ['-sL', '-o', tmpPath, url], { stdio: 'pipe' });
+  } catch {
+    console.error(`Error: Failed to download report from URL: ${url}`);
+    process.exit(1);
+  }
+  return tmpPath;
+}
+
+function runNxCommand(
+  args: string[],
+  workspaceRoot: string,
+  timeoutMs = 30000
+): string | null {
+  try {
+    return execFileSync('npx', ['nx', ...args], {
+      cwd: workspaceRoot,
+      timeout: timeoutMs,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+  } catch {
+    return null;
+  }
+}
+
+function safeJsonParse<T>(str: string | null, fallback: T): T {
+  if (!str) return fallback;
+  try {
+    return JSON.parse(str);
+  } catch {
+    return fallback;
+  }
+}
+
+function filterEntries(
+  entries: FileAccessEntry[],
+  filterStr: string | null
+): FileAccessEntry[] {
+  if (!filterStr) return entries;
+
+  const patterns = filterStr.split(',').map((p) => p.trim());
+  return entries.filter((entry) =>
+    patterns.some((pattern) => {
+      if (
+        pattern.includes('*') ||
+        pattern.includes('?') ||
+        pattern.includes('[')
+      ) {
+        // Glob pattern — if no slashes, match against basename
+        if (!pattern.includes('/')) {
+          return minimatch(basename(entry.path), pattern);
+        }
+        return minimatch(entry.path, pattern);
+      }
+      // Literal: exact match or directory prefix
+      return entry.path === pattern || entry.path.startsWith(pattern + '/');
+    })
+  );
+}
+
+function groupByDirPrefix(
+  paths: string[],
+  depth = 3
+): { prefix: string; count: number }[] {
+  const groups: Record<string, number> = {};
+  for (const p of paths) {
+    const prefix = p.split('/').slice(0, depth).join('/');
+    groups[prefix] = (groups[prefix] || 0) + 1;
+  }
+  return Object.entries(groups)
+    .map(([prefix, count]) => ({ prefix, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+function groupByExtension(paths: string[]): { ext: string; count: number }[] {
+  const groups: Record<string, number> = {};
+  for (const p of paths) {
+    const ext = extname(p) || '(no ext)';
+    groups[ext] = (groups[ext] || 0) + 1;
+  }
+  return Object.entries(groups)
+    .map(([ext, count]) => ({ ext, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+function classifyFiles(
+  undeclared: string[],
+  projectRoot: string,
+  projectRoots: Record<string, string>
+) {
+  const projects = Object.entries(projectRoots).map(([project, root]) => ({
+    project,
+    root,
+  }));
+
+  const isBuildArtifact = (f: string) =>
+    f.startsWith('dist/') ||
+    f.startsWith('build/') ||
+    f.startsWith('out-tsc/') ||
+    f.startsWith('.next/') ||
+    f.includes('/node_modules/.cache/') ||
+    f.endsWith('.tsbuildinfo') ||
+    f.includes('/dist/') ||
+    f.includes('/build/output/');
+
+  const configBasenames = new Set(['nx.json', 'project.json', 'package.json']);
+  const configPrefixes = [
+    'tsconfig',
+    'jest.config',
+    'jest.preset',
+    '.eslintrc',
+    'eslint.config',
+    'playwright.config',
+    'webpack.config',
+    'vite.config',
+    'babel.config',
+    '.babelrc',
+    'rollup.config',
+  ];
+  const isConfigFile = (f: string) => {
+    const b = basename(f);
+    return (
+      configBasenames.has(b) ||
+      configPrefixes.some((prefix) => b.startsWith(prefix))
+    );
+  };
+
+  const isEnvFile = (f: string) => {
+    const b = basename(f);
+    return b === '.env' || b.startsWith('.env.');
+  };
+
+  const classified = undeclared.map((f) => {
+    const inProjectRoot = projectRoot !== '' && f.startsWith(projectRoot + '/');
+    const owner = projects.find((p) => f.startsWith(p.root + '/'));
+    return {
+      path: f,
+      inProjectRoot,
+      ownerProject: owner?.project ?? null,
+      isBuildArtifact: isBuildArtifact(f),
+      isConfigFile: isConfigFile(f),
+      isEnvFile: isEnvFile(f),
+    };
+  });
+
+  return {
+    crossProject: classified
+      .filter((c) => !c.inProjectRoot)
+      .map((c) => ({ path: c.path, owner: c.ownerProject })),
+    buildArtifacts: classified
+      .filter((c) => c.isBuildArtifact)
+      .map((c) => c.path),
+    configFiles: classified.filter((c) => c.isConfigFile).map((c) => c.path),
+    envFiles: classified.filter((c) => c.isEnvFile).map((c) => c.path),
+    inProjectRoot: classified.filter((c) => c.inProjectRoot).map((c) => c.path),
+    outsideProjectRoot: classified
+      .filter((c) => !c.inProjectRoot)
+      .map((c) => c.path),
+    total: undeclared.length,
+  };
+}
+
+function validateViolations(
+  violations: string[],
+  resolvedFiles: Set<string>
+): { confirmed: string[]; undeclared: string[] } {
+  const confirmed: string[] = [];
+  const undeclared: string[] = [];
+  const seen = new Set<string>();
+  for (const f of violations) {
+    if (seen.has(f)) continue;
+    seen.add(f);
+    if (resolvedFiles.has(f)) {
+      confirmed.push(f);
+    } else {
+      undeclared.push(f);
+    }
+  }
+  return { confirmed, undeclared };
+}
+
+function validateOutputViolations(
+  violations: string[],
+  resolvedOutputs: string[]
+): { confirmed: string[]; undeclared: string[] } {
+  const outputSet = new Set(resolvedOutputs);
+  const outputDirs = resolvedOutputs.map((o) => o + '/');
+  const confirmed: string[] = [];
+  const undeclared: string[] = [];
+  const seen = new Set<string>();
+  for (const f of violations) {
+    if (seen.has(f)) continue;
+    seen.add(f);
+    if (outputSet.has(f) || outputDirs.some((d) => f.startsWith(d))) {
+      confirmed.push(f);
+    } else {
+      undeclared.push(f);
+    }
+  }
+  return { confirmed, undeclared };
+}
+
+function extractCommands(
+  processTree: ProcessTreeEntry[],
+  readsByPid: Record<string, string[]>,
+  writesByPid: Record<string, string[]>
+) {
+  const pidToCmd: Record<string, string> = {};
+  for (const entry of processTree) {
+    pidToCmd[String(entry.pid)] = entry.cmd;
+  }
+
+  return processTree
+    .filter(
+      (entry) =>
+        (readsByPid[String(entry.pid)]?.length ?? 0) > 0 ||
+        (writesByPid[String(entry.pid)]?.length ?? 0) > 0
+    )
+    .map((entry) => {
+      const parts = entry.cmd.split(' ');
+      const exe = parts[0].split('/').pop() ?? parts[0];
+      return {
+        pid: entry.pid,
+        cmd: entry.cmd,
+        parentPid: entry.parentPid ?? null,
+        parentCmd: entry.parentPid
+          ? (pidToCmd[String(entry.parentPid)] ?? null)
+          : null,
+        unexpectedReadCount: readsByPid[String(entry.pid)]?.length ?? 0,
+        unexpectedWriteCount: writesByPid[String(entry.pid)]?.length ?? 0,
+        unexpectedReads: readsByPid[String(entry.pid)] ?? [],
+        unexpectedWrites: writesByPid[String(entry.pid)] ?? [],
+        executable: exe,
+        arguments: parts.slice(1).join(' '),
+      };
+    })
+    .sort(
+      (a, b) =>
+        b.unexpectedReadCount +
+        b.unexpectedWriteCount -
+        (a.unexpectedReadCount + a.unexpectedWriteCount)
+    );
+}
+
+function resolveExecutorSource(
+  executor: string | undefined,
+  workspaceRoot: string
+): { executor: string; sourcePath: string } {
+  if (
+    !executor ||
+    executor === 'null' ||
+    executor.includes('nx:run-commands')
+  ) {
+    return { executor: executor ?? '', sourcePath: '' };
+  }
+
+  const lastColon = executor.lastIndexOf(':');
+  const pkg = executor.substring(0, lastColon);
+  const name = executor.substring(lastColon + 1);
+
+  try {
+    const result = execFileSync(
+      'node',
+      [
+        '-e',
+        `
+      try {
+        const pkg = require('${pkg}/package.json');
+        const executors = pkg.executors || pkg.builders;
+        if (executors) {
+          const p = require.resolve('${pkg}/' + executors);
+          const dir = require('path').dirname(p);
+          const json = require(p);
+          const impl = json.executors?.['${name}']?.implementation ||
+                       json.builders?.['${name}']?.implementation;
+          if (impl) console.log(require.resolve(dir + '/' + impl));
+        }
+      } catch(e) {}
+    `,
+      ],
+      {
+        cwd: workspaceRoot,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10000,
+      }
+    ).trim();
+    return { executor, sourcePath: result };
+  } catch {
+    return { executor, sourcePath: '' };
+  }
+}
+
+function extractDepTaskOutputFiles(
+  targetConfig: any,
+  workspaceRoot: string
+): { dependentTasksOutputFiles: any[]; namedInputs: string[] } {
+  const inputs: any[] = targetConfig?.inputs ?? [];
+  const depOutputs: any[] = [];
+  const namedInputs: string[] = [];
+
+  for (const input of inputs) {
+    if (
+      typeof input === 'object' &&
+      input !== null &&
+      'dependentTasksOutputFiles' in input
+    ) {
+      depOutputs.push({
+        glob: input.dependentTasksOutputFiles,
+        transitive: input.transitive ?? false,
+      });
+    } else if (
+      typeof input === 'string' &&
+      !input.startsWith('{') &&
+      !input.startsWith('^') &&
+      !input.includes('/') &&
+      !input.includes('.')
+    ) {
+      namedInputs.push(input);
+    }
+  }
+
+  // Resolve named inputs from nx.json
+  const nxJsonPath = resolve(workspaceRoot, 'nx.json');
+  if (existsSync(nxJsonPath) && namedInputs.length > 0) {
+    try {
+      const nxJson = JSON.parse(readFileSync(nxJsonPath, 'utf-8'));
+      for (const name of namedInputs) {
+        const namedDef = nxJson.namedInputs?.[name] ?? [];
+        for (const entry of namedDef) {
+          if (
+            typeof entry === 'object' &&
+            entry !== null &&
+            'dependentTasksOutputFiles' in entry
+          ) {
+            depOutputs.push({
+              glob: entry.dependentTasksOutputFiles,
+              transitive: entry.transitive ?? false,
+              fromNamedInput: name,
+            });
+          }
+        }
+      }
+    } catch {
+      // ignore nx.json parse errors
+    }
+  }
+
+  return { dependentTasksOutputFiles: depOutputs, namedInputs };
+}
+
+function analyzeStaleDeclarations(
+  expectedInputsNotRead: string[],
+  expectedOutputsNotWritten: string[]
+) {
+  const classifyPattern = (value: string) => {
+    if (/[*{]/.test(value)) return 'glob';
+    if (value.startsWith('^')) return 'depOutput';
+    return 'file';
+  };
+
+  const groupByType = (items: string[]) => {
+    const groups: Record<string, string[]> = {};
+    for (const item of items) {
+      const type = classifyPattern(item);
+      (groups[type] ??= []).push(item);
+    }
+    return Object.entries(groups).map(([type, values]) => ({
+      type,
+      count: values.length,
+      samples: values.slice(0, 3),
+    }));
+  };
+
+  return {
+    expectedInputsNotRead: expectedInputsNotRead.length,
+    expectedOutputsNotWritten: expectedOutputsNotWritten.length,
+    staleInputsByType: groupByType(expectedInputsNotRead),
+    staleOutputsByType: groupByType(expectedOutputsNotWritten),
+  };
+}
+
+// --- Main ---
+
+async function main() {
+  const args = parseArgs();
+  let reportPath = args.reportFile;
+
+  // Handle URL inputs
+  if (reportPath.startsWith('http')) {
+    reportPath = downloadUrl(reportPath);
+  }
+
+  if (!existsSync(reportPath)) {
+    console.error(`Error: Report file not found: ${reportPath}`);
+    process.exit(1);
+  }
+
+  reportPath = resolve(reportPath);
+  process.chdir(args.workspaceRoot);
+
+  // Phase 1: Parse report (single read)
+  let report: SandboxReport;
+  try {
+    report = JSON.parse(readFileSync(reportPath, 'utf-8'));
+  } catch {
+    console.error(`Error: Report file is not valid JSON: ${reportPath}`);
+    process.exit(1);
+  }
+
+  if (!report.taskId) {
+    console.error('Error: Report file has no .taskId field');
+    process.exit(1);
+  }
+
+  const [project, target, config] = report.taskId.split(':');
+  const taskRef = config
+    ? `${project}:${target}:${config}`
+    : `${project}:${target}`;
+
+  const unexpectedReads = report.unexpectedReads ?? [];
+  const unexpectedWrites = report.unexpectedWrites ?? [];
+
+  // Apply filter
+  const filteredReads = filterEntries(unexpectedReads, args.filter);
+  const filteredWrites = filterEntries(unexpectedWrites, args.filter);
+
+  const readPaths = filteredReads.map((e) => e.path);
+  const writePaths = filteredWrites.map((e) => e.path);
+
+  // Build pid → files maps
+  const readsByPid: Record<string, string[]> = {};
+  const writesByPid: Record<string, string[]> = {};
+  for (const entry of filteredReads) {
+    (readsByPid[String(entry.pid)] ??= []).push(entry.path);
+  }
+  for (const entry of filteredWrites) {
+    (writesByPid[String(entry.pid)] ??= []).push(entry.path);
+  }
+
+  // Phase 2: Gather Nx task context (run task + parallel nx commands)
+  runNxCommand(['run', taskRef], args.workspaceRoot, 120000);
+
+  const [
+    targetConfigStr,
+    projectConfigStr,
+    resolvedInputsStr,
+    resolvedOutputsStr,
+    graphResult,
+  ] = await Promise.all([
+    runNxCommand(['show', 'target', taskRef, '--json'], args.workspaceRoot),
+    runNxCommand(['show', 'project', project, '--json'], args.workspaceRoot),
+    runNxCommand(
+      ['show', 'target', 'inputs', taskRef, '--json'],
+      args.workspaceRoot
+    ),
+    runNxCommand(
+      ['show', 'target', 'outputs', taskRef, '--json'],
+      args.workspaceRoot
+    ),
+    (() => {
+      const graphPath = `/tmp/sandbox-project-graph-${Date.now()}.json`;
+      runNxCommand(['graph', '--file', graphPath], args.workspaceRoot);
+      try {
+        return readFileSync(graphPath, 'utf-8');
+      } catch {
+        return '{"graph":{"nodes":{}}}';
+      }
+    })(),
+  ]);
+
+  const targetConfig = safeJsonParse(targetConfigStr, {} as any);
+  const projectConfig = safeJsonParse(projectConfigStr, {} as any);
+  const resolvedInputs = safeJsonParse(resolvedInputsStr, {} as any);
+  const resolvedOutputs = safeJsonParse(resolvedOutputsStr, {} as any);
+  const projectGraph = safeJsonParse(graphResult, {
+    graph: { nodes: {} },
+  } as any);
+
+  // Phase 3: Validate violations
+  const resolvedInputFiles = new Set([
+    ...(resolvedInputs.files ?? []),
+    ...(resolvedInputs.depOutputs ?? []),
+  ]);
+  const resolvedOutputFiles = [
+    ...(resolvedOutputs.outputPaths ?? []),
+    ...(resolvedOutputs.expandedOutputs ?? []),
+  ];
+
+  const checkInputs = validateViolations(readPaths, resolvedInputFiles);
+  const checkOutputs = validateOutputViolations(
+    writePaths,
+    resolvedOutputFiles
+  );
+
+  // Phase 3.5: Sample --check verification
+  let checkSampleInputs: any = {};
+  let checkSampleOutputs: any = {};
+  const sampleReadFiles = checkInputs.undeclared.slice(0, 5);
+  if (sampleReadFiles.length > 0) {
+    const result = runNxCommand(
+      [
+        'show',
+        'target',
+        'inputs',
+        taskRef,
+        '--check',
+        ...sampleReadFiles,
+        '--json',
+      ],
+      args.workspaceRoot
+    );
+    checkSampleInputs = safeJsonParse(result, {});
+  }
+  const sampleWriteFiles = checkOutputs.undeclared.slice(0, 5);
+  if (sampleWriteFiles.length > 0) {
+    const result = runNxCommand(
+      [
+        'show',
+        'target',
+        'outputs',
+        taskRef,
+        '--check',
+        ...sampleWriteFiles,
+        '--json',
+      ],
+      args.workspaceRoot
+    );
+    checkSampleOutputs = safeJsonParse(result, {});
+  }
+
+  // Phase 4: File classification
+  const projectRoots: Record<string, string> = {};
+  for (const [name, node] of Object.entries(projectGraph.graph?.nodes ?? {})) {
+    projectRoots[name] = (node as any).data?.root ?? name;
+  }
+  const taskProjectRoot = projectRoots[project] ?? '';
+
+  const readClassification = classifyFiles(
+    checkInputs.undeclared,
+    taskProjectRoot,
+    projectRoots
+  );
+  const writeClassification = classifyFiles(
+    checkOutputs.undeclared,
+    taskProjectRoot,
+    projectRoots
+  );
+
+  // Phase 5: Command extraction
+  const processTree = report.processTree ?? [];
+  const commands = extractCommands(processTree, readsByPid, writesByPid);
+
+  // Phase 6: Inference detection
+  const targetMeta = projectConfig.targets?.[target]?.metadata ?? {};
+  const inference = {
+    isInferred: 'plugin' in targetMeta || 'technologies' in targetMeta,
+    plugin: targetMeta.plugin ?? null,
+    technologies: targetMeta.technologies ?? null,
+    description: targetMeta.description ?? null,
+  };
+
+  let pluginRegistration: any = {};
+  const nxJsonPath = resolve(args.workspaceRoot, 'nx.json');
+  if (inference.plugin && existsSync(nxJsonPath)) {
+    try {
+      const nxJson = JSON.parse(readFileSync(nxJsonPath, 'utf-8'));
+      const plugins = (nxJson.plugins ?? []).map((p: any) =>
+        typeof p === 'string' ? { plugin: p, options: {} } : p
+      );
+      pluginRegistration =
+        plugins.find((p: any) => p.plugin === inference.plugin) ?? {};
+    } catch {
+      // ignore
+    }
+  }
+
+  // Phase 6.5: dependentTasksOutputFiles + executor resolution
+  const depTaskOutputs = extractDepTaskOutputFiles(
+    targetConfig,
+    args.workspaceRoot
+  );
+  const executorInfo = resolveExecutorSource(
+    targetConfig.executor ?? targetConfig.command,
+    args.workspaceRoot
+  );
+
+  // Phase 7: Cross-project dependency check
+  const dependsOn = (targetConfig.dependsOn ?? []).map((d: any) =>
+    typeof d === 'string' ? d : (d.target ?? '')
+  );
+  const checkCrossProject = (classification: typeof readClassification) => {
+    const owners = [
+      ...new Set(
+        classification.crossProject
+          .map((c) => c.owner)
+          .filter((o): o is string => o !== null)
+      ),
+    ];
+    return owners.map((owner) => ({
+      project: owner,
+      isDependency: dependsOn.some(
+        (d: string) =>
+          d === owner ||
+          d === `${owner}:build` ||
+          d === `^${owner}:build` ||
+          d.includes(`^${owner}`)
+      ),
+      files: classification.crossProject
+        .filter((c) => c.owner === owner)
+        .map((c) => c.path),
+    }));
+  };
+
+  const crossProjectDeps = {
+    reads: checkCrossProject(readClassification),
+    writes: checkCrossProject(writeClassification),
+  };
+
+  // Phase 8: Stale declarations
+  const staleDeclarations = analyzeStaleDeclarations(
+    report.expectedInputsNotRead ?? [],
+    report.expectedOutputsNotWritten ?? []
+  );
+
+  // Assemble outputs
+  const detailFile = `/tmp/sandbox-diagnosis-detail-${taskRef.replace(/[/:@]/g, '-')}.json`;
+
+  const detail = {
+    processTree: {
+      processTree,
+      processPidToCmd: Object.fromEntries(
+        processTree.map((e) => [String(e.pid), e.cmd])
+      ),
+      readsByPid,
+      writesByPid,
+    },
+    targetConfig,
+    projectConfig,
+    resolvedInputs,
+    resolvedOutputs,
+    validation: { reads: checkInputs, writes: checkOutputs },
+    classification: { reads: readClassification, writes: writeClassification },
+    report: {
+      taskId: report.taskId,
+      totalFilesRead: report.filesRead?.length ?? 0,
+      totalFilesWritten: report.filesWritten?.length ?? 0,
+      totalUnexpectedReads: unexpectedReads.length,
+      totalUnexpectedWrites: unexpectedWrites.length,
+      expectedInputsNotRead: report.expectedInputsNotRead ?? [],
+      expectedOutputsNotWritten: report.expectedOutputsNotWritten ?? [],
+    },
+    commands,
+    crossProjectDependencyCheck: crossProjectDeps,
+    staleDeclarations,
+    inference,
+    pluginRegistration,
+    dependentTasksOutputFiles: depTaskOutputs,
+    executorInfo,
+  };
+  writeFileSync(detailFile, JSON.stringify(detail, null, 2));
+
+  // Brief to stdout
+  const brief = {
+    task: {
+      ref: taskRef,
+      project,
+      target,
+      configuration: config ?? null,
+      projectRoot: taskProjectRoot,
+    },
+    summary: {
+      unexpectedReads: unexpectedReads.length,
+      unexpectedWrites: unexpectedWrites.length,
+      filteredReads: filteredReads.length,
+      filteredWrites: filteredWrites.length,
+      filterApplied: args.filter !== null,
+      filterPattern: args.filter,
+      confirmedReads: checkInputs.confirmed.length,
+      undeclaredReads: checkInputs.undeclared.length,
+      confirmedWrites: checkOutputs.confirmed.length,
+      undeclaredWrites: checkOutputs.undeclared.length,
+    },
+    undeclaredFiles: {
+      reads: checkInputs.undeclared,
+      writes: checkOutputs.undeclared,
+    },
+    grouping: {
+      readsByDirectory: groupByDirPrefix(readPaths),
+      writesByDirectory: groupByDirPrefix(writePaths),
+      byExtension: {
+        readsByExt: groupByExtension(readPaths),
+        writesByExt: groupByExtension(writePaths),
+      },
+    },
+    commands: commands.map(
+      ({
+        pid,
+        cmd,
+        parentCmd,
+        executable,
+        arguments: args,
+        unexpectedReadCount,
+        unexpectedWriteCount,
+      }) => ({
+        pid,
+        cmd,
+        parentCmd,
+        executable,
+        arguments: args,
+        unexpectedReadCount,
+        unexpectedWriteCount,
+      })
+    ),
+    checkSample: {
+      inputs: checkSampleInputs,
+      outputs: checkSampleOutputs,
+    },
+    classificationSummary: {
+      reads: {
+        crossProject: readClassification.crossProject.length,
+        buildArtifacts: readClassification.buildArtifacts.length,
+        configFiles: readClassification.configFiles.length,
+        envFiles: readClassification.envFiles.length,
+        inProjectRoot: readClassification.inProjectRoot.length,
+        outsideProjectRoot: readClassification.outsideProjectRoot.length,
+      },
+      writes: {
+        crossProject: writeClassification.crossProject.length,
+        buildArtifacts: writeClassification.buildArtifacts.length,
+        configFiles: writeClassification.configFiles.length,
+        envFiles: writeClassification.envFiles.length,
+        inProjectRoot: writeClassification.inProjectRoot.length,
+        outsideProjectRoot: writeClassification.outsideProjectRoot.length,
+      },
+    },
+    crossProjectDependencyCheck: crossProjectDeps,
+    staleDeclarations,
+    dependentTasksOutputFiles: depTaskOutputs.dependentTasksOutputFiles,
+    executorInfo,
+    inference,
+    pluginRegistration,
+    verificationCommands: {
+      checkInputs: `npx nx show target inputs ${taskRef} --check <files...>`,
+      checkOutputs: `npx nx show target outputs ${taskRef} --check <files...>`,
+      runTask: `npx nx run ${taskRef} --skip-nx-cache`,
+    },
+    detailFile,
+  };
+
+  console.log(JSON.stringify(brief, null, 2));
+}
+
+main().catch((err) => {
+  console.error(`Script failed: ${err.message}`);
+  process.exit(1);
+});

.claude/skills/nx-docs-style-check/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: nx-docs-style-check
+description: Check modified Nx documentation pages against the astro-docs style guide. Auto-trigger after writing or editing docs content in the nx repo. Also trigger on "check style", "style guide", "docs review", "validate docs". Should run as a final step whenever docs files are modified. IMPORTANT: anytime astro-docs/**/*.mdoc files are modified, this should always run automatically without being asked.
+allowed-tools: Read, Glob, Grep
+---
+
+# Nx docs style check
+
+You are a documentation editor for Nx. Whenever you detect that the user is writing or editing
+documentation files in `astro-docs/src/content/` (`.mdoc`, `.mdx`, `.md`), automatically run this
+check and fix any issues. Do not wait to be asked.
+
+## Phase 1: Information architecture audit
+
+Read `astro-docs/STYLE_GUIDE.md` (the "Information architecture" section) and
+`astro-docs/sidebar.mts` to understand where the page lives in the sidebar hierarchy.
+
+For every new or moved page, evaluate against ALL FIVE principles. These are non-negotiable:
+
+### 1. Progressive disclosure ("journey" rule)
+
+- Is this for the first 30 minutes (Getting Started), first 30 days (Features), or forever (Reference)?
+- Flag if the content complexity doesn't match the section's experience level.
+
+### 2. Category homogeneity ("scan" rule)
+
+- Look at sibling pages in the same sidebar section.
+- Do they all share the same content type (concepts, tasks, or products)?
+- Flag if this page mixes types that siblings don't.
+
+### 3. Type-based navigation ("intent" rule)
+
+- Is this a learning page (narrative/guide) or a lookup page (reference/API)?
+- Flag if it's in the wrong category (e.g., a reference page in a guides section).
+
+### 4. Pen and paper test ("theory" rule)
+
+- Can the page be explained using only pen and paper (no terminal needed)?
+- YES = belongs in "How Nx Works" (architecture/concepts)
+- NO (needs terminal/code examples) = belongs in "Platform Features" or "Technologies"
+- Flag if a concept page has terminal output, CLI commands, or code-heavy examples.
+
+### 5. Universal vs. specific ("placement" rule)
+
+- Does this feature apply to every Nx user?
+- YES = "Platform Features"
+- NO (only React/Angular/etc. users) = "Technologies"
+- Flag if a technology-specific page is in Platform Features or vice versa.
+
+## Phase 2: Style validation
+
+### Step 1: Run Vale and fix errors
+
+Run `nx run astro-docs:vale` to check the modified files.
+
+- **errors** — fix these automatically. Edit the file to resolve the violation.
+- **warnings** — fix these automatically when the fix is unambiguous (e.g., sentence case headings).
+  For ambiguous cases, suggest the fix and ask.
+- **suggestions** — mention them to the user but do not auto-fix.
+
+### Step 2: Fix issues Vale doesn't catch
+
+Read `astro-docs/STYLE_GUIDE.md` and check for that things that Vale may have missed.
+
+### Handling false positives
+
+Use inline Vale comments to suppress legitimate exceptions:
+
+```markdown
+<!-- vale Nx.Headings = NO -->
+
+## extractLicenses
+
+<!-- vale Nx.Headings = YES -->
+```
+
+Common cases where suppression is appropriate:
+
+- **CLI option headings** (e.g., `## extractLicenses`) — camelCase by design.
+  Prefer wrapping in backticks first (`## \`extractLicenses\``).
+- **Product possessives in historical/migration context** (e.g., "Angular's original schematic system")
+- **Terminology in migration docs** (e.g., explaining what "schematics" were before being renamed)
+
+Do NOT suppress rules just to avoid fixing real violations.
+
+## Output summary
+
+After fixing, report what you did:
+
+```
+## Style check results
+
+### Information architecture: [PASS/FAIL]
+[List any violations or confirm all five principles pass]
+
+### Vale: [X errors fixed, Y warnings fixed, Z suggestions noted]
+[Summary of changes made]
+
+### Manual fixes: [list of additional fixes applied]
+```

.claude/skills/nx-gradle-plugin-version-bump/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: nx-gradle-plugin-version-bump
+description: Bump the dev.nx.gradle.project-graph plugin version. Use when updating the Gradle project graph plugin version across the codebase, creating the migration files, and updating migrations.json.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Gradle Plugin Version Bump
+
+Bumps the `dev.nx.gradle.project-graph` plugin to a new version. This is a recurring task that touches 5 files in an identical pattern every time.
+
+## Required Inputs
+
+Collect these values from the master branch before starting:
+
+1. `NEW_VERSION` - the version we want to bump to
+   Example: OLD_VERSION: 0.1.15 => NEW_VERSION: 0.1.16
+   You can find this value by looking at the `OLD_VERSION` specified in `packages/gradle/project-graph/build.gradle.kts` in the `version` field.  
+   The NEW_VERSION will be the `OLD_VERSION` + 1.
+
+2. `NX_MIGRATION_VERSION` - the version of Nx that will trigger our version bump migration
+   Example: OLD_VERSION: 22.7.0-beta.0 => NEW_VERSION: 22.7.0-beta.1
+   You can find this value by looking at the `nx` version in `package.json` under `devDependencies`. The NEW_VERSION will be the `OLD_VERSION` + 1.
+
+3. `MIGRATION_FOLDER` - the folder name under `packages/gradle/src/migrations/` that will contain our migration files
+   Example: NEW_VERSION: 22.7.0-beta.1 => MIGRATION_FOLDER: 22-7-0
+   Take the version and replace all the dots with hyphens and remove the `beta` or `rc` suffix.
+
+## Steps
+
+### 1. Update the version constant
+
+**File:** `packages/gradle/src/utils/versions.ts`
+
+Change `gradleProjectGraphVersion` to the new version:
+
+```ts
+export const gradleProjectGraphVersion = 'NEW_VERSION';
+```
+
+### 2. Update build.gradle.kts
+
+**File:** `packages/gradle/project-graph/build.gradle.kts`
+
+Update the `version` on line 13:
+
+```kotlin
+version = "NEW_VERSION"
+```
+
+### 3. Create migration TypeScript file
+
+**File:** `packages/gradle/src/migrations/MIGRATION_FOLDER/change-plugin-version-NEW_VERSION.ts`
+
+Determine the previous version by reading the current `gradleProjectGraphVersion` from `packages/gradle/src/utils/versions.ts` before modifying it.
+
+Template:
+
+```ts
+import { Tree, readNxJson } from '@nx/devkit';
+import { hasGradlePlugin } from '../../utils/has-gradle-plugin';
+import { addNxProjectGraphPlugin } from '../../generators/init/gradle-project-graph-plugin-utils';
+import { updateNxPluginVersionInCatalogsAst } from '../../utils/version-catalog-ast-utils';
+
+/* Change the plugin version to NEW_VERSION
+ */
+export default async function update(tree: Tree) {
+  const nxJson = readNxJson(tree);
+  if (!nxJson) {
+    return;
+  }
+  if (!hasGradlePlugin(tree)) {
+    return;
+  }
+
+  const gradlePluginVersionToUpdate = 'NEW_VERSION';
+
+  // Update version in version catalogs using AST-based approach to preserve formatting
+  await updateNxPluginVersionInCatalogsAst(tree, gradlePluginVersionToUpdate);
+
+  // Then update in build.gradle(.kts) files
+  await addNxProjectGraphPlugin(tree, gradlePluginVersionToUpdate);
+}
+```
+
+### 4. Create migration documentation file
+
+**File:** `packages/gradle/src/migrations/MIGRATION_FOLDER/change-plugin-version-NEW_VERSION.md`
+
+Replace `PREV_VERSION` with the version that was current before this bump.
+
+Template:
+
+````md
+#### Change dev.nx.gradle.project-graph to version NEW_VERSION
+
+Change dev.nx.gradle.project-graph to version NEW_VERSION in build file
+
+#### Sample Code Changes
+
+##### Before
+
+\```text title="build.gradle"
+plugins {
+id "dev.nx.gradle.project-graph" version "PREV_VERSION"
+}
+\```
+
+##### After
+
+\```text title="build.gradle"
+plugins {
+id "dev.nx.gradle.project-graph" version "NEW_VERSION"
+}
+\```
+````
+
+### 5. Add migration entry to migrations.json
+
+**File:** `packages/gradle/migrations.json`
+
+Add a new entry at the end of the `generators` object (before the closing `}`), following the existing pattern:
+
+```json
+"change-plugin-version-NEW_VERSION": {
+  "version": "NX_MIGRATION_VERSION",
+  "cli": "nx",
+  "description": "Change dev.nx.gradle.project-graph to version NEW_VERSION in build file",
+  "factory": "./src/migrations/MIGRATION_FOLDER/change-plugin-version-NEW_VERSION"
+}
+```
+
+The migration key uses the version with hyphens replacing dots (e.g., `0-1-16`).
+
+## Verification
+
+Run:
+
+```bash
+nx run-many -t test,build,lint -p gradle
+```
+
+## Commit Convention
+
+```
+chore(gradle): bump gradle project graph plugin version to NEW_VERSION
+```
+
+## Final Verification
+
+Take a look at the most recent Gradle version bump PR and compare your changes to that. You should not be touching more or less files than
+the most recent version bump PR. If you do, ask for more information and stop all changes.

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

@@ -0,0 +1,87 @@
+---
+name: run-nx-generator
+description: Run Nx generators with prioritization for workspace-plugin generators. Use this when generating code, scaffolding new features, or automating repetitive tasks in the monorepo.
+allowed-tools: Bash, Read, Glob, Grep, mcp__nx-mcp__nx_generators, mcp__nx-mcp__nx_generator_schema
+---
+
+# Run Nx Generator
+
+This skill helps you execute Nx generators efficiently, with special focus on workspace-plugin generators from your internal tooling.
+
+## Generator Priority List
+
+Use the `mcp__nx-mcp__nx_generator_schema` tool to get more information about how to use the generator
+
+Choose which generators to run in this priority order:
+
+### 🔥 Workspace-Plugin Generators (High Priority)
+
+These are your custom internal tools in `tools/workspace-plugin/`
+
+### 📦 Core Nx Generators (Standard)
+
+Only use these if workspace-plugin generators don't fit:
+
+- `nx generate @nx/devkit:...` - DevKit utilities
+- `nx generate @nx/node:...` - Node.js libraries
+- `nx generate @nx/react:...` - React components and apps
+- Framework-specific generators
+
+## How to Run Generators
+
+1. **List available generators**:
+
+2. **Get generator schema** (to see available options):
+   Use the `mcp__nx-mcp__nx_generator_schema` tool to get more information about how to use the generator
+
+3. **Run the generator**:
+
+   ```bash
+   nx generate [generator-path] [options]
+   ```
+
+4. **Verify the changes**:
+   - Review generated files
+   - Run tests: `nx affected -t test`
+   - Format code: `npx prettier --write [files]`
+
+## Best Practices
+
+- ✅ Always check workspace-plugin first - it has your custom solutions
+- ✅ Use `--dry-run` flag to preview changes before applying
+- ✅ Format generated code immediately with Prettier
+- ✅ Test affected projects after generation
+- ✅ Commit generator changes separately from manual edits
+
+## Examples
+
+### Bumping Maven Version
+
+When updating the Maven plugin version, use the workspace-plugin generator:
+
+```bash
+nx generate @nx/workspace-plugin:bump-maven-version \
+  --newVersion 0.0.10 \
+  --nxVersion 22.1.0-beta.7
+```
+
+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:
+
+- Generate new code or projects
+- Scaffold new features or libraries
+- Automate repetitive setup tasks
+- Update internal tools and configurations
+- Create migrations or version updates

.cursor/agents/ci-watcher.md

@@ -0,0 +1,480 @@
+---
+name: ci-watcher
+description: Polls Nx Cloud CI pipeline and self-healing status. Returns structured state when actionable. Spawned by /nx-cloud-ci-monitor command to monitor CI Attempt status.
+model: fast
+---
+
+# CI Watcher Subagent
+
+You are a CI monitoring subagent responsible for polling Nx Cloud CI Attempt status and self-healing state. You report status back to the main agent - you do NOT make apply/reject decisions.
+
+## Your Responsibilities
+
+1. Poll CI status using the `ci_information` MCP tool
+2. Implement exponential backoff between polls
+3. Return structured state when an actionable condition is reached
+4. Track iteration count and elapsed time
+5. Output status updates based on verbosity level
+
+## Input Parameters (from Main Agent)
+
+The main agent may provide these optional parameters in the prompt:
+
+| Parameter           | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `branch`            | Branch to monitor (auto-detected if not provided)        |
+| `expectedCommitSha` | Commit SHA that should trigger a new CI Attempt          |
+| `previousCipeUrl`   | CI Attempt URL before the action (to detect change)      |
+| `subagentTimeout`   | Polling timeout in minutes (default: 60)                 |
+| `verbosity`         | Output level: minimal, medium, verbose (default: medium) |
+
+When `expectedCommitSha` or `previousCipeUrl` is provided, you must detect whether a new CI Attempt has spawned.
+
+## MCP Tool Reference
+
+### `ci_information`
+
+**Input:**
+
+```json
+{
+  "branch": "string (optional, defaults to current git branch)",
+  "select": "string (optional, comma-separated field names)",
+  "pageToken": "number (optional, 0-based pagination for long strings)"
+}
+```
+
+**Output:**
+
+```json
+{
+  "cipeStatus": "NOT_STARTED | IN_PROGRESS | SUCCEEDED | FAILED | CANCELED | TIMED_OUT",
+  "cipeUrl": "string",
+  "branch": "string",
+  "commitSha": "string | null",
+  "failedTaskIds": "string[]",
+  "verifiedTaskIds": "string[]",
+  "selfHealingEnabled": "boolean",
+  "selfHealingStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null",
+  "verificationStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null",
+  "userAction": "NONE | APPLIED | REJECTED | APPLIED_LOCALLY | APPLIED_AUTOMATICALLY | null",
+  "failureClassification": "string | null",
+  "taskOutputSummary": "string | null",
+  "suggestedFixReasoning": "string | null",
+  "suggestedFixDescription": "string | null",
+  "suggestedFix": "string | null",
+  "shortLink": "string | null",
+  "couldAutoApplyTasks": "boolean | null",
+  "confidence": "number | null",
+  "confidenceReasoning": "string | null"
+}
+```
+
+**Select Parameter:**
+
+| Usage           | Returns                                                     |
+| --------------- | ----------------------------------------------------------- |
+| No `select`     | Formatted overview (truncated, not recommended for polling) |
+| Single field    | Raw value with pagination for long strings                  |
+| Multiple fields | Object with requested field values                          |
+
+**Field Sets for Efficient Polling:**
+
+```yaml
+WAIT_FIELDS:
+  'cipeUrl,commitSha,cipeStatus'
+  # Minimal fields for detecting new CI Attempt
+
+LIGHT_FIELDS:
+  'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning'
+  # Status fields for determining actionable state
+
+HEAVY_FIELDS:
+  'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription'
+  # Large content fields - fetch only when returning to main agent
+```
+
+## Initial Wait
+
+Before first poll, wait based on context:
+
+- **Fresh start (no expected CIPE):** Wait 60 seconds to allow CI to start
+- **Expecting new CIPE:** Wait 30 seconds (action already triggered)
+
+**IMPORTANT:** Always run sleep in foreground, NOT as background command.
+
+```bash
+sleep 60  # or 30 if expecting new CIPE (FOREGROUND, not background)
+```
+
+## Two-Phase Operation
+
+The subagent operates in one of two modes depending on input:
+
+### Mode 1: Fresh Start (no `expectedCommitSha` or `previousCipeUrl`)
+
+Normal polling - process whatever CIPE is returned by `ci_information`.
+
+### Mode 2: Wait-for-New-CIPE (when `expectedCommitSha` or `previousCipeUrl` provided)
+
+**CRITICAL**: When expecting a new CIPE, the subagent must **completely ignore** the old/stale CIPE. Do NOT process its status, do NOT return actionable states based on it.
+
+#### Phase A: Wait Mode
+
+1. Start a **new-CIPE timeout** timer (default: 30 minutes)
+2. On each poll of `ci_information`:
+   - Check if CIPE is NEW:
+     - `cipeUrl` differs from `previousCipeUrl` → **new CIPE detected**
+     - `commitSha` matches `expectedCommitSha` → **correct CIPE detected**
+   - If still OLD CIPE: **ignore all status fields**, just wait and poll again
+   - Do NOT return `fix_available`, `ci_success`, etc. based on old CIPE!
+3. Output wait status (see below)
+4. If timeout (30 min) reached → return `no_new_cipe`
+
+#### Phase B: Normal Polling (after new CIPE detected)
+
+Once new CIPE is detected:
+
+1. Clear the new-CIPE timeout
+2. Switch to normal polling mode
+3. Process the NEW CIPE's status normally
+4. Return when actionable state reached
+
+### Wait Mode Output
+
+While in wait mode, output clearly that you're waiting (not processing):
+
+```
+[CI Monitor] ═══════════════════════════════════════════════════════
+[CI Monitor] WAIT MODE - Expecting new CI Attempt
+[CI Monitor] Expected SHA: <expectedCommitSha>
+[CI Monitor] Previous CI Attempt: <previousCipeUrl>
+[CI Monitor] ═══════════════════════════════════════════════════════
+
+[CI Monitor] Polling... (elapsed: 0m 30s)
+[CI Monitor] Still seeing previous CI Attempt (ignoring): <oldCipeUrl>
+
+[CI Monitor] Polling... (elapsed: 1m 30s)
+[CI Monitor] Still seeing previous CI Attempt (ignoring): <oldCipeUrl>
+
+[CI Monitor] Polling... (elapsed: 2m 30s)
+[CI Monitor] ✓ New CI Attempt detected! URL: <newCipeUrl>, SHA: <newCommitSha>
+[CI Monitor] Switching to normal polling mode...
+```
+
+### Why This Matters (Context Preservation)
+
+**The problem**: Stale CIPE data can be very large:
+
+- `taskOutputSummary`: potentially thousands of characters of build/test output
+- `suggestedFix`: entire patch files
+- `suggestedFixReasoning`: detailed explanation
+
+If subagent returns stale CIPE data to main agent, it **pollutes main agent's context** with useless information (we already processed that CIPE). This wastes valuable context window.
+
+**Without wait mode:**
+
+1. Poll `ci_information` → get old CIPE with huge data
+2. Return to main agent with all that stale data
+3. Main agent's context gets polluted with useless info
+4. Main agent has to process/ignore it anyway
+
+**With wait mode:**
+
+1. Poll `ci_information` → get old CIPE → **ignore it, don't return**
+2. Keep waiting internally (stale data stays in subagent)
+3. New CIPE appears → switch to normal mode
+4. Return to main agent with only the NEW, relevant CIPE data
+
+## Polling Loop
+
+### Subagent State Management
+
+Maintain internal accumulated state across polls:
+
+```
+accumulated_state = {}
+```
+
+### Call `ci_information` MCP Tool
+
+**Wait Mode (expecting new CI Attempt):**
+
+```
+ci_information({
+  branch: "<branch_name>",
+  select: "cipeUrl,commitSha,cipeStatus"
+})
+```
+
+Only fetch minimal fields needed to detect CI Attempt change. Do NOT fetch heavy fields - stale data wastes context.
+
+**Normal Mode (processing CI Attempt):**
+
+```
+ci_information({
+  branch: "<branch_name>",
+  select: "cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning"
+})
+```
+
+Merge response into `accumulated_state` after each poll.
+
+### Analyze Response
+
+**If in Wait Mode** (expecting new CIPE):
+
+1. Check if CIPE is new (see Two-Phase Operation above)
+2. If old CIPE → **ignore status**, output wait message, poll again
+3. If new CIPE → switch to normal mode, continue below
+
+**If in Normal Mode**:
+Based on the response, decide whether to **keep polling** or **return to main agent**.
+
+### Keep Polling When
+
+Continue polling (with backoff) if ANY of these conditions are true:
+
+| Condition                               | Reason                                   |
+| --------------------------------------- | ---------------------------------------- |
+| `cipeStatus == 'IN_PROGRESS'`           | CI still running                         |
+| `cipeStatus == 'NOT_STARTED'`           | CI hasn't started yet                    |
+| `selfHealingStatus == 'IN_PROGRESS'`    | Self-healing agent working               |
+| `selfHealingStatus == 'NOT_STARTED'`    | Self-healing not started yet             |
+| `failureClassification == 'FLAKY_TASK'` | Auto-rerun in progress                   |
+| `userAction == 'APPLIED_AUTOMATICALLY'` | New CI Attempt spawning after auto-apply |
+
+When `couldAutoApplyTasks == true`:
+
+- `verificationStatus` = `NOT_STARTED`, `IN_PROGRESS` → keep polling (verification still in progress)
+- `verificationStatus` = `COMPLETED` → return `fix_auto_applying` (auto-apply will happen, main agent spawns wait mode subagent)
+- `verificationStatus` = `FAILED`, `NOT_EXECUTABLE` → return `fix_available` (auto-apply won't happen, needs manual action)
+
+### Exponential Backoff
+
+Between polls, wait with exponential backoff:
+
+| Poll Attempt | Wait Time         |
+| ------------ | ----------------- |
+| 1st          | 60 seconds        |
+| 2nd          | 90 seconds        |
+| 3rd+         | 120 seconds (cap) |
+
+Reset to 60 seconds when state changes significantly.
+
+**IMPORTANT:** Run sleep in foreground (NOT as background command). Background sleep causes "What should Claude do?" prompts when completed.
+
+```bash
+# Example backoff - run in FOREGROUND
+sleep 60   # First wait
+sleep 90   # Second wait
+sleep 120  # Third and subsequent waits (capped)
+```
+
+### Fetch Heavy Fields on Actionable State
+
+Before returning to main agent, fetch heavy fields if the status requires them:
+
+| Status              | Heavy Fields Needed                                                            |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `ci_success`        | None                                                                           |
+| `fix_auto_applying` | None                                                                           |
+| `fix_available`     | `taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription` |
+| `fix_failed`        | `taskOutputSummary`                                                            |
+| `no_fix`            | `taskOutputSummary`                                                            |
+| `environment_issue` | None                                                                           |
+| `no_new_cipe`       | None                                                                           |
+| `polling_timeout`   | None                                                                           |
+| `cipe_canceled`     | None                                                                           |
+| `cipe_timed_out`    | None                                                                           |
+
+```
+# Example: fetching heavy fields for fix_available
+ci_information({
+  branch: "<branch_name>",
+  select: "taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription"
+})
+```
+
+Merge response into `accumulated_state`, then return merged state to main agent.
+
+**Pagination:** Heavy string fields return first page only. If `hasMore` indicated, include in return format so main agent knows more content available.
+
+### Return to Main Agent When
+
+Return immediately with structured state if ANY of these conditions are true:
+
+| Status              | Condition                                                                                                                                                 |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | `cipeStatus == 'SUCCEEDED'`                                                                                                                               |
+| `fix_auto_applying` | `selfHealingStatus == 'COMPLETED'` AND `couldAutoApplyTasks == true` AND `verificationStatus == 'COMPLETED'`                                              |
+| `fix_available`     | `selfHealingStatus == 'COMPLETED'` AND `suggestedFix != null` AND (`couldAutoApplyTasks != true` OR `verificationStatus` in (`FAILED`, `NOT_EXECUTABLE`)) |
+| `fix_failed`        | `selfHealingStatus == 'FAILED'`                                                                                                                           |
+| `environment_issue` | `failureClassification == 'ENVIRONMENT_STATE'`                                                                                                            |
+| `no_fix`            | `cipeStatus == 'FAILED'` AND (`selfHealingEnabled == false` OR `selfHealingStatus == 'NOT_EXECUTABLE'`)                                                   |
+| `no_new_cipe`       | `expectedCommitSha` or `previousCipeUrl` provided, but no new CI Attempt detected after 30 min                                                            |
+| `polling_timeout`   | Subagent has been polling for > configured timeout (default 60 min)                                                                                       |
+| `cipe_canceled`     | `cipeStatus == 'CANCELED'`                                                                                                                                |
+| `cipe_timed_out`    | `cipeStatus == 'TIMED_OUT'`                                                                                                                               |
+
+## Subagent Timeout
+
+Track elapsed time. If you have been polling for more than **60 minutes** (configurable via main agent), return with `status: polling_timeout`.
+
+## Return Format
+
+When returning to the main agent, provide a structured response with accumulated state:
+
+```
+## CI Monitor Result
+
+**Status:** <status>
+**Iterations:** <count>
+**Elapsed:** <minutes>m <seconds>s
+
+### CI Attempt Details
+- **Status:** <cipeStatus>
+- **URL:** <cipeUrl>
+- **Branch:** <branch>
+- **Commit:** <commitSha>
+- **Failed Tasks:** <failedTaskIds>
+- **Verified Tasks:** <verifiedTaskIds>
+
+### Self-Healing Details
+- **Enabled:** <selfHealingEnabled>
+- **Status:** <selfHealingStatus>
+- **Verification:** <verificationStatus>
+- **User Action:** <userAction>
+- **Classification:** <failureClassification>
+- **Confidence:** <confidence>
+- **Confidence Reasoning:** <confidenceReasoning>
+
+### Fix Information (if available)
+- **Short Link:** <shortLink>
+- **Description:** <suggestedFixDescription>
+- **Reasoning:** <suggestedFixReasoning>
+
+### Task Output Summary (first page)
+<taskOutputSummary>
+[MORE_CONTENT_AVAILABLE: taskOutputSummary, pageToken: 1]
+
+### Suggested Fix (first page)
+<suggestedFix>
+[MORE_CONTENT_AVAILABLE: suggestedFix, pageToken: 1]
+```
+
+### Pagination Indicators
+
+When a heavy field has more content available, append indicator:
+
+```
+[MORE_CONTENT_AVAILABLE: <fieldName>, pageToken: <nextPage>]
+```
+
+Main agent can fetch additional pages if needed using:
+
+```
+ci_information({ select: "<fieldName>", pageToken: <nextPage> })
+```
+
+Fields that may have pagination:
+
+- `taskOutputSummary` (reverse pagination - page 0 = most recent)
+- `suggestedFix` (forward pagination - page 0 = start)
+- `suggestedFixReasoning`
+
+### Return Format for `no_new_cipe`
+
+When returning with `status: no_new_cipe`, include additional context:
+
+```
+## CI Monitor Result
+
+**Status:** no_new_cipe
+**Iterations:** <count>
+**Elapsed:** <minutes>m <seconds>s
+
+### Expected CI Attempt Not Found
+- **Expected Commit SHA:** <expectedCommitSha>
+- **Previous CI Attempt URL:** <previousCipeUrl>
+- **Last Seen CI Attempt URL:** <cipeUrl>
+- **Last Seen Commit SHA:** <commitSha>
+- **New CI Attempt Timeout:** 30 minutes (exceeded)
+
+### Likely Cause
+CI workflow failed before Nx tasks could run (e.g., install step, checkout, auth).
+Check your CI provider logs for the commit <expectedCommitSha>.
+
+### Last Known CI Attempt State
+- **Status:** <cipeStatus>
+- **Branch:** <branch>
+```
+
+## Status Reporting (Verbosity-Controlled)
+
+Output is controlled by the `verbosity` parameter from the main agent:
+
+| Level     | What to Output                                                    |
+| --------- | ----------------------------------------------------------------- |
+| `minimal` | No intermediate output. Only return final result when actionable. |
+| `medium`  | Output only on significant state changes (not every poll).        |
+| `verbose` | Output detailed phase information after every poll.               |
+
+### Minimal Verbosity
+
+No output during polling. Poll silently and return when done.
+
+### Medium Verbosity (Default)
+
+Output **only when state changes significantly** to save context tokens:
+
+- `cipeStatus` changes (e.g., IN_PROGRESS → FAILED)
+- `selfHealingStatus` changes (e.g., IN_PROGRESS → COMPLETED)
+- New CI Attempt detected (in wait mode)
+
+Format: single line, no decorators:
+
+```
+[CI Monitor] CI: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 4m
+```
+
+### Verbose Verbosity
+
+Output detailed phase box after every poll:
+
+```
+[CI Monitor] ─────────────────────────────────────────────────────
+[CI Monitor] Iteration <N> | Elapsed: <X>m <Y>s
+[CI Monitor]
+[CI Monitor] CI Status:          <cipeStatus>
+[CI Monitor] Self-Healing:       <selfHealingStatus>
+[CI Monitor] Verification:       <verificationStatus>
+[CI Monitor] Classification:     <failureClassification>
+[CI Monitor]
+[CI Monitor] → <human-readable phase description>
+[CI Monitor] ─────────────────────────────────────────────────────
+```
+
+### Phase Descriptions (for verbose output)
+
+| Status Combo                                                                              | Description                                 |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `cipeStatus: IN_PROGRESS`                                                                 | "CI running..."                             |
+| `cipeStatus: NOT_STARTED`                                                                 | "Waiting for CI to start..."                |
+| `cipeStatus: FAILED` + `selfHealingStatus: NOT_STARTED`                                   | "CI failed. Self-healing starting..."       |
+| `cipeStatus: FAILED` + `selfHealingStatus: IN_PROGRESS`                                   | "CI failed. Self-healing generating fix..." |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: IN_PROGRESS` | "Fix generated! Verification running..."    |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: COMPLETED`   | "Fix ready! Verified successfully."         |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: FAILED`      | "Fix generated but verification failed."    |
+| `cipeStatus: FAILED` + `selfHealingStatus: FAILED`                                        | "Self-healing could not generate a fix."    |
+| `cipeStatus: SUCCEEDED`                                                                   | "CI passed!"                                |
+
+## Important Notes
+
+- You do NOT make apply/reject decisions - that's the main agent's job
+- You do NOT perform git operations
+- You only poll and report state
+- Respect the `verbosity` parameter for output (default: medium)
+- If `ci_information` returns an error, wait and retry (count as failed poll)
+- Track consecutive failures - if 5 consecutive failures, return with `status: error`
+- When expecting new CI Attempt, track the 30-minute new-CI-Attempt timeout separately from the main polling timeout

.cursor/commands/ci-monitor.md

@@ -0,0 +1,428 @@
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```

.cursor/skills/ci-monitor/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: ci-monitor
+description: Monitor Nx Cloud CI pipeline and handle self-healing fixes automatically. Checks for Nx Cloud connection before starting.
+---
+
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+$ARGUMENTS
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+Parse any overrides from `$ARGUMENTS` and merge with defaults.
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```

.cursor/skills/nx-generate/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: nx-generate
+description: Generate code using nx generators. USE WHEN scaffolding code or transforming existing code - for example creating libraries or applications, or anything else that is boilerplate code or automates repetitive tasks. ALWAYS use this first when generating code with Nx instead of calling MCP tools or running nx generate immediately.
+---
+
+# Run Nx Generator
+
+Nx generators are powerful tools that scaffold projects, make automated code migrations or automate repetitive tasks in a monorepo. They ensure consistency across the codebase and reduce boilerplate work.
+
+This skill applies when the user wants to:
+
+- Create new projects like libraries or applications
+- Scaffold features or boilerplate code
+- Run workspace-specific or custom generators
+- Do anything else that an nx generator exists for
+
+## Generator Discovery Flow
+
+### Step 1: List Available Generators
+
+Use the Nx CLI to discover available generators:
+
+- List all generators for a plugin: `npx nx list @nx/react`
+- View available plugins: `npx nx list`
+
+This includes:
+
+- Plugin generators (e.g., `@nx/react:library`, `@nx/js:library`)
+- Local workspace generators (defined in the repo's own plugins)
+
+### Step 2: Match Generator to User Request
+
+Based on the user's request, identify which generator(s) could fulfill their needs. Consider:
+
+- What artifact type they want to create (library, application, etc.)
+- Which framework or technology stack is relevant
+- Whether they mentioned specific generator names
+
+**IMPORTANT**: When both a local workspace generator and an external plugin generator could satisfy the request, **always prefer the local workspace generator**. Local generators are customized for the specific repo's patterns and conventions.
+
+It's possible that the user request is something that no Nx generator exists for whatsoever. In this case, you can stop using this skill and try to help the user another way. HOWEVER, the burden of proof for this is high. Before aborting, carefully consider each and every generator that's available. Look into details for any that could be related in any way before making this decision.
+
+## Pre-Execution Checklist
+
+Before running any generator, complete these steps:
+
+### 1. Fetch Generator Schema
+
+Use the `--help` flag to understand all available options:
+
+```bash
+npx nx g @nx/react:library --help
+```
+
+Pay attention to:
+
+- Required options that must be provided
+- Optional options that may be relevant to the user's request
+- Default values that might need to be overridden
+
+### 2. Read Generator Source Code
+
+Understanding what the generator actually does helps you:
+
+- Know what files will be created/modified
+- Understand any side effects (updating configs, installing deps, etc.)
+- Identify options that might not be obvious from the schema
+
+To find generator source code:
+
+- For plugin generators: Use `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"` to find the generators.json, then locate the source from there
+- If that fails, read directly from `node_modules/<plugin>/generators.json`
+- For local generators: They are typically in `tools/generators/` or a local plugin directory. You can search the repo for the generator name to find it.
+
+### 2.5 Reevaluate if the generator is right
+
+Once you have built up an understanding of what the selected generator does, reconsider: Is this the right generator to service the user request?
+If not, it's okay to go back to the Generator Discovery Flow and select a different generator before proceeding. If you do, make sure to go through the entire pre-execution checklist once more.
+
+### 3. Understand Repo Context
+
+Before generating, examine the target area of the codebase:
+
+- Look at similar existing artifacts (other libraries, applications, etc.)
+- Identify patterns and conventions used in the repo
+- Note naming conventions, file structures, and configuration patterns
+- Try to match these patterns when configuring the generator
+
+For example, if similar libraries are using a specific test runner, build tool or linter, try to match that if possible.
+If projects or other artifacts are organized with a specific naming convention, try to match it.
+
+### 4. Validate Required Options
+
+Ensure all required options have values:
+
+- Map the user's request to generator options
+- Infer values from context where possible
+- Ask the user for any critical missing information
+
+## Execution
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally.
+Many generators will behave differently based on where they are executed. For example, first-party nx library generators use the cwd to determine the directory that the library should be placed in. This is highly important.
+
+### Consider Dry-Run (Optional)
+
+Running with `--dry-run` first is strongly encouraged but not mandatory. Use your judgment:
+
+- For complex generators or unfamiliar territory: do a dry-run first
+- For simple, well-understood generators: may proceed directly
+- Dry-run shows file names and created/deleted/modified markers, but not content
+- There are cases where a generator does not support dry-run (for example if it had to install an npm package) - in that case --dry-run might fail. Don't be discouraged but simply move on to running the generator for real and iterating from there.
+
+### Running the Generator
+
+Execute the generator with:
+
+```bash
+nx generate <generator-name> <options> --no-interactive
+```
+
+**CRITICAL**: Always include `--no-interactive` to prevent prompts that would hang the execution.
+
+Example:
+
+```bash
+nx generate @nx/react:library --name=my-utils --no-interactive
+```
+
+### Handling Generator Failures
+
+If the generator fails:
+
+1. **Diagnose the error** - Read the error message carefully
+2. **Identify the cause** - Missing options, invalid values, conflicts, etc.
+3. **Attempt automatic fix** - Adjust options or resolve conflicts
+4. **Retry** - Run the generator again with corrected options
+
+Common failure reasons:
+
+- Missing required options
+- Invalid option values
+- Conflicting with existing files
+- Missing dependencies
+- Generator doesn't support certain flag combinations
+
+## Post-Generation
+
+### 1. Modify Generated Code (If Needed)
+
+Generators provide a starting point, but the output may need adjustment to match the user's specific requirements:
+
+- Add or modify functionality as requested
+- Adjust imports, exports, or configurations
+- Integrate with existing code patterns in the repo
+
+### 2. Format Code
+
+Run formatting on all generated/modified files:
+
+```bash
+nx format --fix
+```
+
+Languages other than javascript/typescript might need other formatting invocations too.
+
+### 3. Run Verification
+
+Verify that the generated code works correctly. What this looks like will vary depending on the type of generator and the targets available.
+If the generator created a new project, run its targets directly
+Use your best judgement to determine what needs to be verified.
+
+Example:
+
+```bash
+nx lint <new-project>
+nx test <new-project>
+nx build <new-project>
+```
+
+### 4. Handle Verification Failures
+
+When verification fails:
+
+**If scope is manageable** (a few lint errors, minor type issues):
+
+- Fix the issues
+- Re-run verification to confirm
+
+**If issues are extensive** (many errors, complex problems):
+
+- Attempt simple, obvious fixes first
+- If still failing, escalate to the user with:
+  - Description of what was generated
+  - What verification is failing
+  - What you've attempted to fix
+  - Remaining issues that need user input
+
+## Error Handling
+
+### Generator Failures
+
+- Check the error message for specific causes
+- Verify all required options are provided
+- Check for conflicts with existing files
+- Ensure the generator name and options are correct
+
+### Missing Options
+
+- Consult the generator schema for required fields
+- Infer values from context when reasonable
+- Ask the user for values that cannot be inferred
+
+## Key Principles
+
+1. **Local generators first** - Always prefer workspace/local generators over external plugin generators when both could work
+
+2. **Understand before running** - Read both the schema AND the source code to fully understand what will happen
+
+3. **No prompts** - Always use `--no-interactive` to prevent hanging
+
+4. **Generators are starting points** - Modify the output as needed to fully satisfy the user's requirements
+
+5. **Verify changes work** - Don't just generate; ensure the code builds, lints, and tests pass
+
+6. **Be proactive about fixes** - Don't just report errors; attempt to resolve them automatically when possible
+
+7. **Match repo patterns** - Study existing similar code in the repo and match its conventions

.cursor/skills/nx-plugins/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: nx-plugins
+description: Find and add Nx plugins. USE WHEN user wants to discover available plugins, install a new plugin, or add support for a specific framework or technology to the workspace.
+---
+
+## Finding and Installing new plugins
+
+- List plugins: `pnpm nx list`
+- Install plugins `pnpm nx add <plugin>`. Example: `pnpm nx add @nx/react`.

.cursor/skills/nx-run-tasks/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: nx-run-tasks
+description: Helps with running tasks in an Nx workspace. USE WHEN the user wants to execute build, test, lint, serve, or run any other tasks defined in the workspace.
+---
+
+You can run tasks with Nx in the following way.
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally. Look at the package.json or lockfile to determine which package manager is in use.
+
+For more details on any command, run it with `--help` (e.g. `nx run-many --help`, `nx affected --help`).
+
+## Understand which tasks can be run
+
+You can check those via `nx show project <projectname> --json`, for example `nx show project myapp --json`. It contains a `targets` section which has information about targets that can be run. You can also just look at the `package.json` scripts or `project.json` targets, but you might miss out on inferred tasks by Nx plugins.
+
+## Run a single task
+
+```
+nx run <project>:<task>
+```
+
+where `project` is the project name defined in `package.json` or `project.json` (if present).
+
+## Run multiple tasks
+
+```
+nx run-many -t build test lint typecheck
+```
+
+You can pass a `-p` flag to filter to specific projects, otherwise it runs on all projects. You can also use `--exclude` to exclude projects, and `--parallel` to control the number of parallel processes (default is 3).
+
+Examples:
+
+- `nx run-many -t test -p proj1 proj2` — test specific projects
+- `nx run-many -t test --projects=*-app --exclude=excluded-app` — test projects matching a pattern
+- `nx run-many -t test --projects=tag:api-*` — test projects by tag
+
+## Run tasks for affected projects
+
+Use `nx affected` to only run tasks on projects that have been changed and projects that depend on changed projects. This is especially useful in CI and for large workspaces.
+
+```
+nx affected -t build test lint
+```
+
+By default it compares against the base branch. You can customize this:
+
+- `nx affected -t test --base=main --head=HEAD` — compare against a specific base and head
+- `nx affected -t test --files=libs/mylib/src/index.ts` — specify changed files directly
+
+## Useful flags
+
+These flags work with `run`, `run-many`, and `affected`:
+
+- `--skipNxCache` — rerun tasks even when results are cached
+- `--verbose` — print additional information such as stack traces
+- `--nxBail` — stop execution after the first failed task
+- `--configuration=<name>` — use a specific configuration (e.g. `production`)

.cursor/skills/nx-workspace/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: nx-workspace
+description: "Explore and understand Nx workspaces. USE WHEN answering any questions about the nx workspace, the projects in it or tasks to run. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What targets can I run?', 'What's affected by my changes?', 'Which projects depend on library Y?', or any questions about Nx workspace structure, project configuration, or available tasks."
+---
+
+# Nx Workspace Exploration
+
+This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.
+
+Keep in mind that you might have to prefix commands with `npx`/`pnpx`/`yarn` if nx isn't installed globally. Check the lockfile to determine the package manager in use.
+
+## Listing Projects
+
+Use `nx show projects` to list projects in the workspace.
+
+```bash
+# List all projects
+nx show projects
+
+# Filter by pattern (glob)
+nx show projects --projects "apps/*"
+nx show projects --projects "shared-*"
+
+# Filter by project type
+nx show projects --type app
+nx show projects --type lib
+nx show projects --type e2e
+
+# Filter by target (projects that have a specific target)
+nx show projects --withTarget build
+nx show projects --withTarget e2e
+
+# Find affected projects (changed since base branch)
+nx show projects --affected
+nx show projects --affected --base=main
+nx show projects --affected --type app
+
+# Combine filters
+nx show projects --type lib --withTarget test
+nx show projects --affected --exclude="*-e2e"
+
+# Output as JSON
+nx show projects --json
+```
+
+## Project Configuration
+
+Use `nx show project <name> --json` to get the full resolved configuration for a project.
+
+**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project` command returns the full resolved config including inferred targets from plugins.
+
+You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options.
+
+```bash
+# Get full project configuration
+nx show project my-app --json
+
+# Extract specific parts from the JSON
+nx show project my-app --json | jq '.targets'
+nx show project my-app --json | jq '.targets.build'
+nx show project my-app --json | jq '.targets | keys'
+
+
+# Check project metadata
+nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'
+```
+
+## Target Information
+
+Targets define what tasks can be run on a project.
+
+```bash
+# List all targets for a project
+nx show project my-app --json | jq '.targets | keys'
+
+# Get full target configuration
+nx show project my-app --json | jq '.targets.build'
+
+# Check target executor/command
+nx show project my-app --json | jq '.targets.build.executor'
+nx show project my-app --json | jq '.targets.build.command'
+
+# View target options
+nx show project my-app --json | jq '.targets.build.options'
+
+# Check target inputs/outputs (for caching)
+nx show project my-app --json | jq '.targets.build.inputs'
+nx show project my-app --json | jq '.targets.build.outputs'
+
+# Find projects with a specific target
+nx show projects --withTarget serve
+nx show projects --withTarget e2e
+```
+
+## Workspace Configuration
+
+Read `nx.json` directly for workspace-level configuration.
+You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options.
+
+```bash
+# Read the full nx.json
+cat nx.json
+
+# Or use jq for specific sections
+cat nx.json | jq '.targetDefaults'
+cat nx.json | jq '.namedInputs'
+cat nx.json | jq '.plugins'
+cat nx.json | jq '.generators'
+```
+
+Key nx.json sections:
+
+- `targetDefaults` - Default configuration applied to all targets of a given name
+- `namedInputs` - Reusable input definitions for caching
+- `plugins` - Nx plugins and their configuration
+- ...and much more, read the schema or nx.json for details
+
+## Affected Projects
+
+Find projects affected by changes in the current branch.
+
+```bash
+# Affected since base branch (auto-detected)
+nx show projects --affected
+
+# Affected with explicit base
+nx show projects --affected --base=main
+nx show projects --affected --base=origin/main
+
+# Affected between two commits
+nx show projects --affected --base=abc123 --head=def456
+
+# Affected apps only
+nx show projects --affected --type app
+
+# Affected excluding e2e projects
+nx show projects --affected --exclude="*-e2e"
+
+# Affected by uncommitted changes
+nx show projects --affected --uncommitted
+
+# Affected by untracked files
+nx show projects --affected --untracked
+```
+
+## Common Exploration Patterns
+
+### "What's in this workspace?"
+
+```bash
+nx show projects
+nx show projects --type app
+nx show projects --type lib
+```
+
+### "How do I build/test/lint project X?"
+
+```bash
+nx show project X --json | jq '.targets | keys'
+nx show project X --json | jq '.targets.build'
+```
+
+### "What depends on library Y?"
+
+```bash
+# Find projects that may depend on Y by searching for imports
+# (Nx doesn't have a direct "dependents" command via CLI)
+grep -r "from '@myorg/Y'" --include="*.ts" --include="*.tsx" apps/ libs/
+```
+
+### "What configuration options are available?"
+
+```bash
+cat node_modules/nx/schemas/nx-schema.json | jq '.properties | keys'
+cat node_modules/nx/schemas/project-schema.json | jq '.properties | keys'
+```
+
+### "Why is project X affected?"
+
+```bash
+# Check what files changed
+git diff --name-only main
+
+# See which project owns those files
+nx show project X --json | jq '.root'
+```

.devcontainer/devcontainer.json

@@ -8,11 +8,11 @@
   // Try a more recent distribution, if your are having build issues related to GLIBC version
   // Here we use 'bookworm', which is based on `Debian-12`, which comes with `GLIBC v2.36`
   // (Nx tools currenlty requires `GLIBC v2.33` or higher)
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:20-bookworm",
+  // Note: Using base debian image instead of typescript-node since mise will manage all tools
+  "image": "mcr.microsoft.com/devcontainers/base:bookworm",
 
-  "features": {
-    "ghcr.io/devcontainers/features/rust:1": {}
-  },
+  // All tools (Node, Java, Rust, Dotnet) are managed by mise via mise.toml
+  "features": {},
 
   // Use 'forwardPorts' to make a list of ports inside the container available locally.
   // 4211 = nx graph port

.devcontainer/postCreateCommand.sh

@@ -1,12 +1,30 @@
-#!/bin/sh
+#!/bin/bash
 
-# Update the underlying (Debian) OS, to make sure we have the latest security patches and libraries like 'GLIBC' 
+# Update the underlying (Debian) OS, to make sure we have the latest security patches and libraries like 'GLIBC'
 echo "⚙️ Updating the underlying OS..."
 sudo apt-get update && sudo apt-get -y upgrade
 
-# Uninstall globally installed PNPM (required version will be reinstalled through corepack)
-echo "❌ Uninstalling globally installed PNPM..."
-npm uninstall -g pnpm
+# Install mise for managing development tools (Node, Java, Rust, Dotnet)
+echo "⚙️ Installing mise..."
+curl https://mise.run | sh
+
+# Add mise to PATH
+export PATH="$HOME/.local/bin:$PATH"
+
+# Trust the mise.toml configuration file
+echo "⚙️ Trusting mise.toml configuration..."
+mise trust
+
+# Install all tools from mise.toml (node, java, rust, dotnet)
+echo "⚙️ Installing tools via mise (node, java, rust, dotnet)..."
+mise install
+
+# Activate mise to make tools available in current shell
+eval "$(mise activate bash)"
+
+# Add mise activation to bashrc for future shell sessions
+echo "⚙️ Configuring mise activation in shell..."
+echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
 
 # Prevent corepack from prompting user before downloading PNPM 
 export COREPACK_ENABLE_DOWNLOAD_PROMPT=0

.eslintrc.json

@@ -4,7 +4,7 @@
   "env": {
     "node": true
   },
-  "ignorePatterns": ["**/*.ts", "**/test-output"],
+  "ignorePatterns": ["**/*.ts", "**/test-output", "**/dist"],
   "plugins": ["@typescript-eslint", "@nx"],
   "extends": ["plugin:storybook/recommended"],
   "rules": {
@@ -76,7 +76,8 @@
             ]
           }
         ],
-        "@nx/workspace/valid-command-object": "error"
+        "@nx/workspace/valid-command-object": "error",
+        "@nx/workspace/require-windows-hide": "error"
       }
     },
     {
@@ -96,6 +97,22 @@
       "rules": {
         "@angular-eslint/prefer-standalone": "off"
       }
+    },
+    {
+      "files": [
+        "*.spec.ts",
+        "*.spec.tsx",
+        "*.spec.js",
+        "*.spec.jsx",
+        "*.test.ts",
+        "*.test.tsx",
+        "*.test.js",
+        "*.test.jsx"
+      ],
+      "plugins": ["jest"],
+      "rules": {
+        "jest/no-disabled-tests": "warn"
+      }
     }
   ]
 }

.gemini/commands/ci-monitor.toml

@@ -0,0 +1,438 @@
+description = "Monitor Nx Cloud CI pipeline and handle self-healing fixes automatically. Checks for Nx Cloud connection before starting."
+prompt = """
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+{{args}}
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+Parse any overrides from `{{args}}` and merge with defaults.
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \\| Elapsed: Xm \\| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```"""

.gemini/skills/ci-monitor/skill.md

@@ -0,0 +1,437 @@
+---
+name: ci-monitor
+description: Monitor Nx Cloud CI pipeline and handle self-healing fixes automatically. Checks for Nx Cloud connection before starting.
+---
+
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+$ARGUMENTS
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+Parse any overrides from `$ARGUMENTS` and merge with defaults.
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```

.gemini/skills/nx-generate/skill.md

@@ -0,0 +1,228 @@
+---
+name: nx-generate
+description: Generate code using nx generators. USE WHEN scaffolding code or transforming existing code - for example creating libraries or applications, or anything else that is boilerplate code or automates repetitive tasks. ALWAYS use this first when generating code with Nx instead of calling MCP tools or running nx generate immediately.
+---
+
+# Run Nx Generator
+
+Nx generators are powerful tools that scaffold projects, make automated code migrations or automate repetitive tasks in a monorepo. They ensure consistency across the codebase and reduce boilerplate work.
+
+This skill applies when the user wants to:
+
+- Create new projects like libraries or applications
+- Scaffold features or boilerplate code
+- Run workspace-specific or custom generators
+- Do anything else that an nx generator exists for
+
+## Generator Discovery Flow
+
+### Step 1: List Available Generators
+
+Use the Nx CLI to discover available generators:
+
+- List all generators for a plugin: `npx nx list @nx/react`
+- View available plugins: `npx nx list`
+
+This includes:
+
+- Plugin generators (e.g., `@nx/react:library`, `@nx/js:library`)
+- Local workspace generators (defined in the repo's own plugins)
+
+### Step 2: Match Generator to User Request
+
+Based on the user's request, identify which generator(s) could fulfill their needs. Consider:
+
+- What artifact type they want to create (library, application, etc.)
+- Which framework or technology stack is relevant
+- Whether they mentioned specific generator names
+
+**IMPORTANT**: When both a local workspace generator and an external plugin generator could satisfy the request, **always prefer the local workspace generator**. Local generators are customized for the specific repo's patterns and conventions.
+
+It's possible that the user request is something that no Nx generator exists for whatsoever. In this case, you can stop using this skill and try to help the user another way. HOWEVER, the burden of proof for this is high. Before aborting, carefully consider each and every generator that's available. Look into details for any that could be related in any way before making this decision.
+
+## Pre-Execution Checklist
+
+Before running any generator, complete these steps:
+
+### 1. Fetch Generator Schema
+
+Use the `--help` flag to understand all available options:
+
+```bash
+npx nx g @nx/react:library --help
+```
+
+Pay attention to:
+
+- Required options that must be provided
+- Optional options that may be relevant to the user's request
+- Default values that might need to be overridden
+
+### 2. Read Generator Source Code
+
+Understanding what the generator actually does helps you:
+
+- Know what files will be created/modified
+- Understand any side effects (updating configs, installing deps, etc.)
+- Identify options that might not be obvious from the schema
+
+To find generator source code:
+
+- For plugin generators: Use `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"` to find the generators.json, then locate the source from there
+- If that fails, read directly from `node_modules/<plugin>/generators.json`
+- For local generators: They are typically in `tools/generators/` or a local plugin directory. You can search the repo for the generator name to find it.
+
+### 2.5 Reevaluate if the generator is right
+
+Once you have built up an understanding of what the selected generator does, reconsider: Is this the right generator to service the user request?
+If not, it's okay to go back to the Generator Discovery Flow and select a different generator before proceeding. If you do, make sure to go through the entire pre-execution checklist once more.
+
+### 3. Understand Repo Context
+
+Before generating, examine the target area of the codebase:
+
+- Look at similar existing artifacts (other libraries, applications, etc.)
+- Identify patterns and conventions used in the repo
+- Note naming conventions, file structures, and configuration patterns
+- Try to match these patterns when configuring the generator
+
+For example, if similar libraries are using a specific test runner, build tool or linter, try to match that if possible.
+If projects or other artifacts are organized with a specific naming convention, try to match it.
+
+### 4. Validate Required Options
+
+Ensure all required options have values:
+
+- Map the user's request to generator options
+- Infer values from context where possible
+- Ask the user for any critical missing information
+
+## Execution
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally.
+Many generators will behave differently based on where they are executed. For example, first-party nx library generators use the cwd to determine the directory that the library should be placed in. This is highly important.
+
+### Consider Dry-Run (Optional)
+
+Running with `--dry-run` first is strongly encouraged but not mandatory. Use your judgment:
+
+- For complex generators or unfamiliar territory: do a dry-run first
+- For simple, well-understood generators: may proceed directly
+- Dry-run shows file names and created/deleted/modified markers, but not content
+- There are cases where a generator does not support dry-run (for example if it had to install an npm package) - in that case --dry-run might fail. Don't be discouraged but simply move on to running the generator for real and iterating from there.
+
+### Running the Generator
+
+Execute the generator with:
+
+```bash
+nx generate <generator-name> <options> --no-interactive
+```
+
+**CRITICAL**: Always include `--no-interactive` to prevent prompts that would hang the execution.
+
+Example:
+
+```bash
+nx generate @nx/react:library --name=my-utils --no-interactive
+```
+
+### Handling Generator Failures
+
+If the generator fails:
+
+1. **Diagnose the error** - Read the error message carefully
+2. **Identify the cause** - Missing options, invalid values, conflicts, etc.
+3. **Attempt automatic fix** - Adjust options or resolve conflicts
+4. **Retry** - Run the generator again with corrected options
+
+Common failure reasons:
+
+- Missing required options
+- Invalid option values
+- Conflicting with existing files
+- Missing dependencies
+- Generator doesn't support certain flag combinations
+
+## Post-Generation
+
+### 1. Modify Generated Code (If Needed)
+
+Generators provide a starting point, but the output may need adjustment to match the user's specific requirements:
+
+- Add or modify functionality as requested
+- Adjust imports, exports, or configurations
+- Integrate with existing code patterns in the repo
+
+### 2. Format Code
+
+Run formatting on all generated/modified files:
+
+```bash
+nx format --fix
+```
+
+Languages other than javascript/typescript might need other formatting invocations too.
+
+### 3. Run Verification
+
+Verify that the generated code works correctly. What this looks like will vary depending on the type of generator and the targets available.
+If the generator created a new project, run its targets directly
+Use your best judgement to determine what needs to be verified.
+
+Example:
+
+```bash
+nx lint <new-project>
+nx test <new-project>
+nx build <new-project>
+```
+
+### 4. Handle Verification Failures
+
+When verification fails:
+
+**If scope is manageable** (a few lint errors, minor type issues):
+
+- Fix the issues
+- Re-run verification to confirm
+
+**If issues are extensive** (many errors, complex problems):
+
+- Attempt simple, obvious fixes first
+- If still failing, escalate to the user with:
+  - Description of what was generated
+  - What verification is failing
+  - What you've attempted to fix
+  - Remaining issues that need user input
+
+## Error Handling
+
+### Generator Failures
+
+- Check the error message for specific causes
+- Verify all required options are provided
+- Check for conflicts with existing files
+- Ensure the generator name and options are correct
+
+### Missing Options
+
+- Consult the generator schema for required fields
+- Infer values from context when reasonable
+- Ask the user for values that cannot be inferred
+
+## Key Principles
+
+1. **Local generators first** - Always prefer workspace/local generators over external plugin generators when both could work
+
+2. **Understand before running** - Read both the schema AND the source code to fully understand what will happen
+
+3. **No prompts** - Always use `--no-interactive` to prevent hanging
+
+4. **Generators are starting points** - Modify the output as needed to fully satisfy the user's requirements
+
+5. **Verify changes work** - Don't just generate; ensure the code builds, lints, and tests pass
+
+6. **Be proactive about fixes** - Don't just report errors; attempt to resolve them automatically when possible
+
+7. **Match repo patterns** - Study existing similar code in the repo and match its conventions

.gemini/skills/nx-plugins/skill.md

@@ -0,0 +1,9 @@
+---
+name: nx-plugins
+description: Find and add Nx plugins. USE WHEN user wants to discover available plugins, install a new plugin, or add support for a specific framework or technology to the workspace.
+---
+
+## Finding and Installing new plugins
+
+- List plugins: `pnpm nx list`
+- Install plugins `pnpm nx add <plugin>`. Example: `pnpm nx add @nx/react`.

.gemini/skills/nx-run-tasks/skill.md

@@ -0,0 +1,58 @@
+---
+name: nx-run-tasks
+description: Helps with running tasks in an Nx workspace. USE WHEN the user wants to execute build, test, lint, serve, or run any other tasks defined in the workspace.
+---
+
+You can run tasks with Nx in the following way.
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally. Look at the package.json or lockfile to determine which package manager is in use.
+
+For more details on any command, run it with `--help` (e.g. `nx run-many --help`, `nx affected --help`).
+
+## Understand which tasks can be run
+
+You can check those via `nx show project <projectname> --json`, for example `nx show project myapp --json`. It contains a `targets` section which has information about targets that can be run. You can also just look at the `package.json` scripts or `project.json` targets, but you might miss out on inferred tasks by Nx plugins.
+
+## Run a single task
+
+```
+nx run <project>:<task>
+```
+
+where `project` is the project name defined in `package.json` or `project.json` (if present).
+
+## Run multiple tasks
+
+```
+nx run-many -t build test lint typecheck
+```
+
+You can pass a `-p` flag to filter to specific projects, otherwise it runs on all projects. You can also use `--exclude` to exclude projects, and `--parallel` to control the number of parallel processes (default is 3).
+
+Examples:
+
+- `nx run-many -t test -p proj1 proj2` — test specific projects
+- `nx run-many -t test --projects=*-app --exclude=excluded-app` — test projects matching a pattern
+- `nx run-many -t test --projects=tag:api-*` — test projects by tag
+
+## Run tasks for affected projects
+
+Use `nx affected` to only run tasks on projects that have been changed and projects that depend on changed projects. This is especially useful in CI and for large workspaces.
+
+```
+nx affected -t build test lint
+```
+
+By default it compares against the base branch. You can customize this:
+
+- `nx affected -t test --base=main --head=HEAD` — compare against a specific base and head
+- `nx affected -t test --files=libs/mylib/src/index.ts` — specify changed files directly
+
+## Useful flags
+
+These flags work with `run`, `run-many`, and `affected`:
+
+- `--skipNxCache` — rerun tasks even when results are cached
+- `--verbose` — print additional information such as stack traces
+- `--nxBail` — stop execution after the first failed task
+- `--configuration=<name>` — use a specific configuration (e.g. `production`)

.gemini/skills/nx-workspace/skill.md

@@ -0,0 +1,186 @@
+---
+name: nx-workspace
+description: "Explore and understand Nx workspaces. USE WHEN answering any questions about the nx workspace, the projects in it or tasks to run. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What targets can I run?', 'What's affected by my changes?', 'Which projects depend on library Y?', or any questions about Nx workspace structure, project configuration, or available tasks."
+---
+
+# Nx Workspace Exploration
+
+This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.
+
+Keep in mind that you might have to prefix commands with `npx`/`pnpx`/`yarn` if nx isn't installed globally. Check the lockfile to determine the package manager in use.
+
+## Listing Projects
+
+Use `nx show projects` to list projects in the workspace.
+
+```bash
+# List all projects
+nx show projects
+
+# Filter by pattern (glob)
+nx show projects --projects "apps/*"
+nx show projects --projects "shared-*"
+
+# Filter by project type
+nx show projects --type app
+nx show projects --type lib
+nx show projects --type e2e
+
+# Filter by target (projects that have a specific target)
+nx show projects --withTarget build
+nx show projects --withTarget e2e
+
+# Find affected projects (changed since base branch)
+nx show projects --affected
+nx show projects --affected --base=main
+nx show projects --affected --type app
+
+# Combine filters
+nx show projects --type lib --withTarget test
+nx show projects --affected --exclude="*-e2e"
+
+# Output as JSON
+nx show projects --json
+```
+
+## Project Configuration
+
+Use `nx show project <name> --json` to get the full resolved configuration for a project.
+
+**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project` command returns the full resolved config including inferred targets from plugins.
+
+You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options.
+
+```bash
+# Get full project configuration
+nx show project my-app --json
+
+# Extract specific parts from the JSON
+nx show project my-app --json | jq '.targets'
+nx show project my-app --json | jq '.targets.build'
+nx show project my-app --json | jq '.targets | keys'
+
+
+# Check project metadata
+nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'
+```
+
+## Target Information
+
+Targets define what tasks can be run on a project.
+
+```bash
+# List all targets for a project
+nx show project my-app --json | jq '.targets | keys'
+
+# Get full target configuration
+nx show project my-app --json | jq '.targets.build'
+
+# Check target executor/command
+nx show project my-app --json | jq '.targets.build.executor'
+nx show project my-app --json | jq '.targets.build.command'
+
+# View target options
+nx show project my-app --json | jq '.targets.build.options'
+
+# Check target inputs/outputs (for caching)
+nx show project my-app --json | jq '.targets.build.inputs'
+nx show project my-app --json | jq '.targets.build.outputs'
+
+# Find projects with a specific target
+nx show projects --withTarget serve
+nx show projects --withTarget e2e
+```
+
+## Workspace Configuration
+
+Read `nx.json` directly for workspace-level configuration.
+You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options.
+
+```bash
+# Read the full nx.json
+cat nx.json
+
+# Or use jq for specific sections
+cat nx.json | jq '.targetDefaults'
+cat nx.json | jq '.namedInputs'
+cat nx.json | jq '.plugins'
+cat nx.json | jq '.generators'
+```
+
+Key nx.json sections:
+
+- `targetDefaults` - Default configuration applied to all targets of a given name
+- `namedInputs` - Reusable input definitions for caching
+- `plugins` - Nx plugins and their configuration
+- ...and much more, read the schema or nx.json for details
+
+## Affected Projects
+
+Find projects affected by changes in the current branch.
+
+```bash
+# Affected since base branch (auto-detected)
+nx show projects --affected
+
+# Affected with explicit base
+nx show projects --affected --base=main
+nx show projects --affected --base=origin/main
+
+# Affected between two commits
+nx show projects --affected --base=abc123 --head=def456
+
+# Affected apps only
+nx show projects --affected --type app
+
+# Affected excluding e2e projects
+nx show projects --affected --exclude="*-e2e"
+
+# Affected by uncommitted changes
+nx show projects --affected --uncommitted
+
+# Affected by untracked files
+nx show projects --affected --untracked
+```
+
+## Common Exploration Patterns
+
+### "What's in this workspace?"
+
+```bash
+nx show projects
+nx show projects --type app
+nx show projects --type lib
+```
+
+### "How do I build/test/lint project X?"
+
+```bash
+nx show project X --json | jq '.targets | keys'
+nx show project X --json | jq '.targets.build'
+```
+
+### "What depends on library Y?"
+
+```bash
+# Find projects that may depend on Y by searching for imports
+# (Nx doesn't have a direct "dependents" command via CLI)
+grep -r "from '@myorg/Y'" --include="*.ts" --include="*.tsx" apps/ libs/
+```
+
+### "What configuration options are available?"
+
+```bash
+cat node_modules/nx/schemas/nx-schema.json | jq '.properties | keys'
+cat node_modules/nx/schemas/project-schema.json | jq '.properties | keys'
+```
+
+### "Why is project X affected?"
+
+```bash
+# Check what files changed
+git diff --name-only main
+
+# See which project owns those files
+nx show project X --json | jq '.root'
+```

.github/agents/ci-watcher.agent.md

@@ -0,0 +1,478 @@
+---
+description: Polls Nx Cloud CI pipeline and self-healing status. Returns structured state when actionable. Spawned by /nx-cloud-ci-monitor command to monitor CI Attempt status.
+---
+
+# CI Watcher Subagent
+
+You are a CI monitoring subagent responsible for polling Nx Cloud CI Attempt status and self-healing state. You report status back to the main agent - you do NOT make apply/reject decisions.
+
+## Your Responsibilities
+
+1. Poll CI status using the `ci_information` MCP tool
+2. Implement exponential backoff between polls
+3. Return structured state when an actionable condition is reached
+4. Track iteration count and elapsed time
+5. Output status updates based on verbosity level
+
+## Input Parameters (from Main Agent)
+
+The main agent may provide these optional parameters in the prompt:
+
+| Parameter           | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `branch`            | Branch to monitor (auto-detected if not provided)        |
+| `expectedCommitSha` | Commit SHA that should trigger a new CI Attempt          |
+| `previousCipeUrl`   | CI Attempt URL before the action (to detect change)      |
+| `subagentTimeout`   | Polling timeout in minutes (default: 60)                 |
+| `verbosity`         | Output level: minimal, medium, verbose (default: medium) |
+
+When `expectedCommitSha` or `previousCipeUrl` is provided, you must detect whether a new CI Attempt has spawned.
+
+## MCP Tool Reference
+
+### `ci_information`
+
+**Input:**
+
+```json
+{
+  "branch": "string (optional, defaults to current git branch)",
+  "select": "string (optional, comma-separated field names)",
+  "pageToken": "number (optional, 0-based pagination for long strings)"
+}
+```
+
+**Output:**
+
+```json
+{
+  "cipeStatus": "NOT_STARTED | IN_PROGRESS | SUCCEEDED | FAILED | CANCELED | TIMED_OUT",
+  "cipeUrl": "string",
+  "branch": "string",
+  "commitSha": "string | null",
+  "failedTaskIds": "string[]",
+  "verifiedTaskIds": "string[]",
+  "selfHealingEnabled": "boolean",
+  "selfHealingStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null",
+  "verificationStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null",
+  "userAction": "NONE | APPLIED | REJECTED | APPLIED_LOCALLY | APPLIED_AUTOMATICALLY | null",
+  "failureClassification": "string | null",
+  "taskOutputSummary": "string | null",
+  "suggestedFixReasoning": "string | null",
+  "suggestedFixDescription": "string | null",
+  "suggestedFix": "string | null",
+  "shortLink": "string | null",
+  "couldAutoApplyTasks": "boolean | null",
+  "confidence": "number | null",
+  "confidenceReasoning": "string | null"
+}
+```
+
+**Select Parameter:**
+
+| Usage           | Returns                                                     |
+| --------------- | ----------------------------------------------------------- |
+| No `select`     | Formatted overview (truncated, not recommended for polling) |
+| Single field    | Raw value with pagination for long strings                  |
+| Multiple fields | Object with requested field values                          |
+
+**Field Sets for Efficient Polling:**
+
+```yaml
+WAIT_FIELDS:
+  'cipeUrl,commitSha,cipeStatus'
+  # Minimal fields for detecting new CI Attempt
+
+LIGHT_FIELDS:
+  'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning'
+  # Status fields for determining actionable state
+
+HEAVY_FIELDS:
+  'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription'
+  # Large content fields - fetch only when returning to main agent
+```
+
+## Initial Wait
+
+Before first poll, wait based on context:
+
+- **Fresh start (no expected CIPE):** Wait 60 seconds to allow CI to start
+- **Expecting new CIPE:** Wait 30 seconds (action already triggered)
+
+**IMPORTANT:** Always run sleep in foreground, NOT as background command.
+
+```bash
+sleep 60  # or 30 if expecting new CIPE (FOREGROUND, not background)
+```
+
+## Two-Phase Operation
+
+The subagent operates in one of two modes depending on input:
+
+### Mode 1: Fresh Start (no `expectedCommitSha` or `previousCipeUrl`)
+
+Normal polling - process whatever CIPE is returned by `ci_information`.
+
+### Mode 2: Wait-for-New-CIPE (when `expectedCommitSha` or `previousCipeUrl` provided)
+
+**CRITICAL**: When expecting a new CIPE, the subagent must **completely ignore** the old/stale CIPE. Do NOT process its status, do NOT return actionable states based on it.
+
+#### Phase A: Wait Mode
+
+1. Start a **new-CIPE timeout** timer (default: 30 minutes)
+2. On each poll of `ci_information`:
+   - Check if CIPE is NEW:
+     - `cipeUrl` differs from `previousCipeUrl` → **new CIPE detected**
+     - `commitSha` matches `expectedCommitSha` → **correct CIPE detected**
+   - If still OLD CIPE: **ignore all status fields**, just wait and poll again
+   - Do NOT return `fix_available`, `ci_success`, etc. based on old CIPE!
+3. Output wait status (see below)
+4. If timeout (30 min) reached → return `no_new_cipe`
+
+#### Phase B: Normal Polling (after new CIPE detected)
+
+Once new CIPE is detected:
+
+1. Clear the new-CIPE timeout
+2. Switch to normal polling mode
+3. Process the NEW CIPE's status normally
+4. Return when actionable state reached
+
+### Wait Mode Output
+
+While in wait mode, output clearly that you're waiting (not processing):
+
+```
+[CI Monitor] ═══════════════════════════════════════════════════════
+[CI Monitor] WAIT MODE - Expecting new CI Attempt
+[CI Monitor] Expected SHA: <expectedCommitSha>
+[CI Monitor] Previous CI Attempt: <previousCipeUrl>
+[CI Monitor] ═══════════════════════════════════════════════════════
+
+[CI Monitor] Polling... (elapsed: 0m 30s)
+[CI Monitor] Still seeing previous CI Attempt (ignoring): <oldCipeUrl>
+
+[CI Monitor] Polling... (elapsed: 1m 30s)
+[CI Monitor] Still seeing previous CI Attempt (ignoring): <oldCipeUrl>
+
+[CI Monitor] Polling... (elapsed: 2m 30s)
+[CI Monitor] ✓ New CI Attempt detected! URL: <newCipeUrl>, SHA: <newCommitSha>
+[CI Monitor] Switching to normal polling mode...
+```
+
+### Why This Matters (Context Preservation)
+
+**The problem**: Stale CIPE data can be very large:
+
+- `taskOutputSummary`: potentially thousands of characters of build/test output
+- `suggestedFix`: entire patch files
+- `suggestedFixReasoning`: detailed explanation
+
+If subagent returns stale CIPE data to main agent, it **pollutes main agent's context** with useless information (we already processed that CIPE). This wastes valuable context window.
+
+**Without wait mode:**
+
+1. Poll `ci_information` → get old CIPE with huge data
+2. Return to main agent with all that stale data
+3. Main agent's context gets polluted with useless info
+4. Main agent has to process/ignore it anyway
+
+**With wait mode:**
+
+1. Poll `ci_information` → get old CIPE → **ignore it, don't return**
+2. Keep waiting internally (stale data stays in subagent)
+3. New CIPE appears → switch to normal mode
+4. Return to main agent with only the NEW, relevant CIPE data
+
+## Polling Loop
+
+### Subagent State Management
+
+Maintain internal accumulated state across polls:
+
+```
+accumulated_state = {}
+```
+
+### Call `ci_information` MCP Tool
+
+**Wait Mode (expecting new CI Attempt):**
+
+```
+ci_information({
+  branch: "<branch_name>",
+  select: "cipeUrl,commitSha,cipeStatus"
+})
+```
+
+Only fetch minimal fields needed to detect CI Attempt change. Do NOT fetch heavy fields - stale data wastes context.
+
+**Normal Mode (processing CI Attempt):**
+
+```
+ci_information({
+  branch: "<branch_name>",
+  select: "cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning"
+})
+```
+
+Merge response into `accumulated_state` after each poll.
+
+### Analyze Response
+
+**If in Wait Mode** (expecting new CIPE):
+
+1. Check if CIPE is new (see Two-Phase Operation above)
+2. If old CIPE → **ignore status**, output wait message, poll again
+3. If new CIPE → switch to normal mode, continue below
+
+**If in Normal Mode**:
+Based on the response, decide whether to **keep polling** or **return to main agent**.
+
+### Keep Polling When
+
+Continue polling (with backoff) if ANY of these conditions are true:
+
+| Condition                               | Reason                                   |
+| --------------------------------------- | ---------------------------------------- |
+| `cipeStatus == 'IN_PROGRESS'`           | CI still running                         |
+| `cipeStatus == 'NOT_STARTED'`           | CI hasn't started yet                    |
+| `selfHealingStatus == 'IN_PROGRESS'`    | Self-healing agent working               |
+| `selfHealingStatus == 'NOT_STARTED'`    | Self-healing not started yet             |
+| `failureClassification == 'FLAKY_TASK'` | Auto-rerun in progress                   |
+| `userAction == 'APPLIED_AUTOMATICALLY'` | New CI Attempt spawning after auto-apply |
+
+When `couldAutoApplyTasks == true`:
+
+- `verificationStatus` = `NOT_STARTED`, `IN_PROGRESS` → keep polling (verification still in progress)
+- `verificationStatus` = `COMPLETED` → return `fix_auto_applying` (auto-apply will happen, main agent spawns wait mode subagent)
+- `verificationStatus` = `FAILED`, `NOT_EXECUTABLE` → return `fix_available` (auto-apply won't happen, needs manual action)
+
+### Exponential Backoff
+
+Between polls, wait with exponential backoff:
+
+| Poll Attempt | Wait Time         |
+| ------------ | ----------------- |
+| 1st          | 60 seconds        |
+| 2nd          | 90 seconds        |
+| 3rd+         | 120 seconds (cap) |
+
+Reset to 60 seconds when state changes significantly.
+
+**IMPORTANT:** Run sleep in foreground (NOT as background command). Background sleep causes "What should Claude do?" prompts when completed.
+
+```bash
+# Example backoff - run in FOREGROUND
+sleep 60   # First wait
+sleep 90   # Second wait
+sleep 120  # Third and subsequent waits (capped)
+```
+
+### Fetch Heavy Fields on Actionable State
+
+Before returning to main agent, fetch heavy fields if the status requires them:
+
+| Status              | Heavy Fields Needed                                                            |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `ci_success`        | None                                                                           |
+| `fix_auto_applying` | None                                                                           |
+| `fix_available`     | `taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription` |
+| `fix_failed`        | `taskOutputSummary`                                                            |
+| `no_fix`            | `taskOutputSummary`                                                            |
+| `environment_issue` | None                                                                           |
+| `no_new_cipe`       | None                                                                           |
+| `polling_timeout`   | None                                                                           |
+| `cipe_canceled`     | None                                                                           |
+| `cipe_timed_out`    | None                                                                           |
+
+```
+# Example: fetching heavy fields for fix_available
+ci_information({
+  branch: "<branch_name>",
+  select: "taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription"
+})
+```
+
+Merge response into `accumulated_state`, then return merged state to main agent.
+
+**Pagination:** Heavy string fields return first page only. If `hasMore` indicated, include in return format so main agent knows more content available.
+
+### Return to Main Agent When
+
+Return immediately with structured state if ANY of these conditions are true:
+
+| Status              | Condition                                                                                                                                                 |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | `cipeStatus == 'SUCCEEDED'`                                                                                                                               |
+| `fix_auto_applying` | `selfHealingStatus == 'COMPLETED'` AND `couldAutoApplyTasks == true` AND `verificationStatus == 'COMPLETED'`                                              |
+| `fix_available`     | `selfHealingStatus == 'COMPLETED'` AND `suggestedFix != null` AND (`couldAutoApplyTasks != true` OR `verificationStatus` in (`FAILED`, `NOT_EXECUTABLE`)) |
+| `fix_failed`        | `selfHealingStatus == 'FAILED'`                                                                                                                           |
+| `environment_issue` | `failureClassification == 'ENVIRONMENT_STATE'`                                                                                                            |
+| `no_fix`            | `cipeStatus == 'FAILED'` AND (`selfHealingEnabled == false` OR `selfHealingStatus == 'NOT_EXECUTABLE'`)                                                   |
+| `no_new_cipe`       | `expectedCommitSha` or `previousCipeUrl` provided, but no new CI Attempt detected after 30 min                                                            |
+| `polling_timeout`   | Subagent has been polling for > configured timeout (default 60 min)                                                                                       |
+| `cipe_canceled`     | `cipeStatus == 'CANCELED'`                                                                                                                                |
+| `cipe_timed_out`    | `cipeStatus == 'TIMED_OUT'`                                                                                                                               |
+
+## Subagent Timeout
+
+Track elapsed time. If you have been polling for more than **60 minutes** (configurable via main agent), return with `status: polling_timeout`.
+
+## Return Format
+
+When returning to the main agent, provide a structured response with accumulated state:
+
+```
+## CI Monitor Result
+
+**Status:** <status>
+**Iterations:** <count>
+**Elapsed:** <minutes>m <seconds>s
+
+### CI Attempt Details
+- **Status:** <cipeStatus>
+- **URL:** <cipeUrl>
+- **Branch:** <branch>
+- **Commit:** <commitSha>
+- **Failed Tasks:** <failedTaskIds>
+- **Verified Tasks:** <verifiedTaskIds>
+
+### Self-Healing Details
+- **Enabled:** <selfHealingEnabled>
+- **Status:** <selfHealingStatus>
+- **Verification:** <verificationStatus>
+- **User Action:** <userAction>
+- **Classification:** <failureClassification>
+- **Confidence:** <confidence>
+- **Confidence Reasoning:** <confidenceReasoning>
+
+### Fix Information (if available)
+- **Short Link:** <shortLink>
+- **Description:** <suggestedFixDescription>
+- **Reasoning:** <suggestedFixReasoning>
+
+### Task Output Summary (first page)
+<taskOutputSummary>
+[MORE_CONTENT_AVAILABLE: taskOutputSummary, pageToken: 1]
+
+### Suggested Fix (first page)
+<suggestedFix>
+[MORE_CONTENT_AVAILABLE: suggestedFix, pageToken: 1]
+```
+
+### Pagination Indicators
+
+When a heavy field has more content available, append indicator:
+
+```
+[MORE_CONTENT_AVAILABLE: <fieldName>, pageToken: <nextPage>]
+```
+
+Main agent can fetch additional pages if needed using:
+
+```
+ci_information({ select: "<fieldName>", pageToken: <nextPage> })
+```
+
+Fields that may have pagination:
+
+- `taskOutputSummary` (reverse pagination - page 0 = most recent)
+- `suggestedFix` (forward pagination - page 0 = start)
+- `suggestedFixReasoning`
+
+### Return Format for `no_new_cipe`
+
+When returning with `status: no_new_cipe`, include additional context:
+
+```
+## CI Monitor Result
+
+**Status:** no_new_cipe
+**Iterations:** <count>
+**Elapsed:** <minutes>m <seconds>s
+
+### Expected CI Attempt Not Found
+- **Expected Commit SHA:** <expectedCommitSha>
+- **Previous CI Attempt URL:** <previousCipeUrl>
+- **Last Seen CI Attempt URL:** <cipeUrl>
+- **Last Seen Commit SHA:** <commitSha>
+- **New CI Attempt Timeout:** 30 minutes (exceeded)
+
+### Likely Cause
+CI workflow failed before Nx tasks could run (e.g., install step, checkout, auth).
+Check your CI provider logs for the commit <expectedCommitSha>.
+
+### Last Known CI Attempt State
+- **Status:** <cipeStatus>
+- **Branch:** <branch>
+```
+
+## Status Reporting (Verbosity-Controlled)
+
+Output is controlled by the `verbosity` parameter from the main agent:
+
+| Level     | What to Output                                                    |
+| --------- | ----------------------------------------------------------------- |
+| `minimal` | No intermediate output. Only return final result when actionable. |
+| `medium`  | Output only on significant state changes (not every poll).        |
+| `verbose` | Output detailed phase information after every poll.               |
+
+### Minimal Verbosity
+
+No output during polling. Poll silently and return when done.
+
+### Medium Verbosity (Default)
+
+Output **only when state changes significantly** to save context tokens:
+
+- `cipeStatus` changes (e.g., IN_PROGRESS → FAILED)
+- `selfHealingStatus` changes (e.g., IN_PROGRESS → COMPLETED)
+- New CI Attempt detected (in wait mode)
+
+Format: single line, no decorators:
+
+```
+[CI Monitor] CI: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 4m
+```
+
+### Verbose Verbosity
+
+Output detailed phase box after every poll:
+
+```
+[CI Monitor] ─────────────────────────────────────────────────────
+[CI Monitor] Iteration <N> | Elapsed: <X>m <Y>s
+[CI Monitor]
+[CI Monitor] CI Status:          <cipeStatus>
+[CI Monitor] Self-Healing:       <selfHealingStatus>
+[CI Monitor] Verification:       <verificationStatus>
+[CI Monitor] Classification:     <failureClassification>
+[CI Monitor]
+[CI Monitor] → <human-readable phase description>
+[CI Monitor] ─────────────────────────────────────────────────────
+```
+
+### Phase Descriptions (for verbose output)
+
+| Status Combo                                                                              | Description                                 |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `cipeStatus: IN_PROGRESS`                                                                 | "CI running..."                             |
+| `cipeStatus: NOT_STARTED`                                                                 | "Waiting for CI to start..."                |
+| `cipeStatus: FAILED` + `selfHealingStatus: NOT_STARTED`                                   | "CI failed. Self-healing starting..."       |
+| `cipeStatus: FAILED` + `selfHealingStatus: IN_PROGRESS`                                   | "CI failed. Self-healing generating fix..." |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: IN_PROGRESS` | "Fix generated! Verification running..."    |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: COMPLETED`   | "Fix ready! Verified successfully."         |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: FAILED`      | "Fix generated but verification failed."    |
+| `cipeStatus: FAILED` + `selfHealingStatus: FAILED`                                        | "Self-healing could not generate a fix."    |
+| `cipeStatus: SUCCEEDED`                                                                   | "CI passed!"                                |
+
+## Important Notes
+
+- You do NOT make apply/reject decisions - that's the main agent's job
+- You do NOT perform git operations
+- You only poll and report state
+- Respect the `verbosity` parameter for output (default: medium)
+- If `ci_information` returns an error, wait and retry (count as failed poll)
+- Track consecutive failures - if 5 consecutive failures, return with `status: error`
+- When expecting new CI Attempt, track the 30-minute new-CI-Attempt timeout separately from the main polling timeout

.github/dependabot.yml

@@ -0,0 +1,18 @@
+# This configuration is here to prevent false positive alerts for __fixtures__.
+# We are intentionally disabling the PR opening feature.
+
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 0
+    exclude-paths:
+      - '**/__fixtures__/**'
+
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 0

.github/prompts/ci-monitor.prompt.md

@@ -0,0 +1,437 @@
+---
+description: Monitor Nx Cloud CI pipeline and handle self-healing fixes automatically. Checks for Nx Cloud connection before starting.
+argument-hint: '[instructions] [--max-cycles N] [--timeout MINUTES] [--verbosity minimal|medium|verbose] [--branch BRANCH] [--fresh] [--auto-fix-workflow] [--new-cipe-timeout MINUTES]'
+---
+
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+${input:args}
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+Parse any overrides from `${input:args}` and merge with defaults.
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```

.github/skills/ci-monitor/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: ci-monitor
+description: Monitor Nx Cloud CI pipeline and handle self-healing fixes automatically. Checks for Nx Cloud connection before starting.
+---
+
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+$ARGUMENTS
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+Parse any overrides from `$ARGUMENTS` and merge with defaults.
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```

.github/skills/nx-generate/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: nx-generate
+description: Generate code using nx generators. USE WHEN scaffolding code or transforming existing code - for example creating libraries or applications, or anything else that is boilerplate code or automates repetitive tasks. ALWAYS use this first when generating code with Nx instead of calling MCP tools or running nx generate immediately.
+---
+
+# Run Nx Generator
+
+Nx generators are powerful tools that scaffold projects, make automated code migrations or automate repetitive tasks in a monorepo. They ensure consistency across the codebase and reduce boilerplate work.
+
+This skill applies when the user wants to:
+
+- Create new projects like libraries or applications
+- Scaffold features or boilerplate code
+- Run workspace-specific or custom generators
+- Do anything else that an nx generator exists for
+
+## Generator Discovery Flow
+
+### Step 1: List Available Generators
+
+Use the Nx CLI to discover available generators:
+
+- List all generators for a plugin: `npx nx list @nx/react`
+- View available plugins: `npx nx list`
+
+This includes:
+
+- Plugin generators (e.g., `@nx/react:library`, `@nx/js:library`)
+- Local workspace generators (defined in the repo's own plugins)
+
+### Step 2: Match Generator to User Request
+
+Based on the user's request, identify which generator(s) could fulfill their needs. Consider:
+
+- What artifact type they want to create (library, application, etc.)
+- Which framework or technology stack is relevant
+- Whether they mentioned specific generator names
+
+**IMPORTANT**: When both a local workspace generator and an external plugin generator could satisfy the request, **always prefer the local workspace generator**. Local generators are customized for the specific repo's patterns and conventions.
+
+It's possible that the user request is something that no Nx generator exists for whatsoever. In this case, you can stop using this skill and try to help the user another way. HOWEVER, the burden of proof for this is high. Before aborting, carefully consider each and every generator that's available. Look into details for any that could be related in any way before making this decision.
+
+## Pre-Execution Checklist
+
+Before running any generator, complete these steps:
+
+### 1. Fetch Generator Schema
+
+Use the `--help` flag to understand all available options:
+
+```bash
+npx nx g @nx/react:library --help
+```
+
+Pay attention to:
+
+- Required options that must be provided
+- Optional options that may be relevant to the user's request
+- Default values that might need to be overridden
+
+### 2. Read Generator Source Code
+
+Understanding what the generator actually does helps you:
+
+- Know what files will be created/modified
+- Understand any side effects (updating configs, installing deps, etc.)
+- Identify options that might not be obvious from the schema
+
+To find generator source code:
+
+- For plugin generators: Use `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"` to find the generators.json, then locate the source from there
+- If that fails, read directly from `node_modules/<plugin>/generators.json`
+- For local generators: They are typically in `tools/generators/` or a local plugin directory. You can search the repo for the generator name to find it.
+
+### 2.5 Reevaluate if the generator is right
+
+Once you have built up an understanding of what the selected generator does, reconsider: Is this the right generator to service the user request?
+If not, it's okay to go back to the Generator Discovery Flow and select a different generator before proceeding. If you do, make sure to go through the entire pre-execution checklist once more.
+
+### 3. Understand Repo Context
+
+Before generating, examine the target area of the codebase:
+
+- Look at similar existing artifacts (other libraries, applications, etc.)
+- Identify patterns and conventions used in the repo
+- Note naming conventions, file structures, and configuration patterns
+- Try to match these patterns when configuring the generator
+
+For example, if similar libraries are using a specific test runner, build tool or linter, try to match that if possible.
+If projects or other artifacts are organized with a specific naming convention, try to match it.
+
+### 4. Validate Required Options
+
+Ensure all required options have values:
+
+- Map the user's request to generator options
+- Infer values from context where possible
+- Ask the user for any critical missing information
+
+## Execution
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally.
+Many generators will behave differently based on where they are executed. For example, first-party nx library generators use the cwd to determine the directory that the library should be placed in. This is highly important.
+
+### Consider Dry-Run (Optional)
+
+Running with `--dry-run` first is strongly encouraged but not mandatory. Use your judgment:
+
+- For complex generators or unfamiliar territory: do a dry-run first
+- For simple, well-understood generators: may proceed directly
+- Dry-run shows file names and created/deleted/modified markers, but not content
+- There are cases where a generator does not support dry-run (for example if it had to install an npm package) - in that case --dry-run might fail. Don't be discouraged but simply move on to running the generator for real and iterating from there.
+
+### Running the Generator
+
+Execute the generator with:
+
+```bash
+nx generate <generator-name> <options> --no-interactive
+```
+
+**CRITICAL**: Always include `--no-interactive` to prevent prompts that would hang the execution.
+
+Example:
+
+```bash
+nx generate @nx/react:library --name=my-utils --no-interactive
+```
+
+### Handling Generator Failures
+
+If the generator fails:
+
+1. **Diagnose the error** - Read the error message carefully
+2. **Identify the cause** - Missing options, invalid values, conflicts, etc.
+3. **Attempt automatic fix** - Adjust options or resolve conflicts
+4. **Retry** - Run the generator again with corrected options
+
+Common failure reasons:
+
+- Missing required options
+- Invalid option values
+- Conflicting with existing files
+- Missing dependencies
+- Generator doesn't support certain flag combinations
+
+## Post-Generation
+
+### 1. Modify Generated Code (If Needed)
+
+Generators provide a starting point, but the output may need adjustment to match the user's specific requirements:
+
+- Add or modify functionality as requested
+- Adjust imports, exports, or configurations
+- Integrate with existing code patterns in the repo
+
+### 2. Format Code
+
+Run formatting on all generated/modified files:
+
+```bash
+nx format --fix
+```
+
+Languages other than javascript/typescript might need other formatting invocations too.
+
+### 3. Run Verification
+
+Verify that the generated code works correctly. What this looks like will vary depending on the type of generator and the targets available.
+If the generator created a new project, run its targets directly
+Use your best judgement to determine what needs to be verified.
+
+Example:
+
+```bash
+nx lint <new-project>
+nx test <new-project>
+nx build <new-project>
+```
+
+### 4. Handle Verification Failures
+
+When verification fails:
+
+**If scope is manageable** (a few lint errors, minor type issues):
+
+- Fix the issues
+- Re-run verification to confirm
+
+**If issues are extensive** (many errors, complex problems):
+
+- Attempt simple, obvious fixes first
+- If still failing, escalate to the user with:
+  - Description of what was generated
+  - What verification is failing
+  - What you've attempted to fix
+  - Remaining issues that need user input
+
+## Error Handling
+
+### Generator Failures
+
+- Check the error message for specific causes
+- Verify all required options are provided
+- Check for conflicts with existing files
+- Ensure the generator name and options are correct
+
+### Missing Options
+
+- Consult the generator schema for required fields
+- Infer values from context when reasonable
+- Ask the user for values that cannot be inferred
+
+## Key Principles
+
+1. **Local generators first** - Always prefer workspace/local generators over external plugin generators when both could work
+
+2. **Understand before running** - Read both the schema AND the source code to fully understand what will happen
+
+3. **No prompts** - Always use `--no-interactive` to prevent hanging
+
+4. **Generators are starting points** - Modify the output as needed to fully satisfy the user's requirements
+
+5. **Verify changes work** - Don't just generate; ensure the code builds, lints, and tests pass
+
+6. **Be proactive about fixes** - Don't just report errors; attempt to resolve them automatically when possible
+
+7. **Match repo patterns** - Study existing similar code in the repo and match its conventions

.github/skills/nx-plugins/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: nx-plugins
+description: Find and add Nx plugins. USE WHEN user wants to discover available plugins, install a new plugin, or add support for a specific framework or technology to the workspace.
+---
+
+## Finding and Installing new plugins
+
+- List plugins: `pnpm nx list`
+- Install plugins `pnpm nx add <plugin>`. Example: `pnpm nx add @nx/react`.

.github/skills/nx-run-tasks/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: nx-run-tasks
+description: Helps with running tasks in an Nx workspace. USE WHEN the user wants to execute build, test, lint, serve, or run any other tasks defined in the workspace.
+---
+
+You can run tasks with Nx in the following way.
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally. Look at the package.json or lockfile to determine which package manager is in use.
+
+For more details on any command, run it with `--help` (e.g. `nx run-many --help`, `nx affected --help`).
+
+## Understand which tasks can be run
+
+You can check those via `nx show project <projectname> --json`, for example `nx show project myapp --json`. It contains a `targets` section which has information about targets that can be run. You can also just look at the `package.json` scripts or `project.json` targets, but you might miss out on inferred tasks by Nx plugins.
+
+## Run a single task
+
+```
+nx run <project>:<task>
+```
+
+where `project` is the project name defined in `package.json` or `project.json` (if present).
+
+## Run multiple tasks
+
+```
+nx run-many -t build test lint typecheck
+```
+
+You can pass a `-p` flag to filter to specific projects, otherwise it runs on all projects. You can also use `--exclude` to exclude projects, and `--parallel` to control the number of parallel processes (default is 3).
+
+Examples:
+
+- `nx run-many -t test -p proj1 proj2` — test specific projects
+- `nx run-many -t test --projects=*-app --exclude=excluded-app` — test projects matching a pattern
+- `nx run-many -t test --projects=tag:api-*` — test projects by tag
+
+## Run tasks for affected projects
+
+Use `nx affected` to only run tasks on projects that have been changed and projects that depend on changed projects. This is especially useful in CI and for large workspaces.
+
+```
+nx affected -t build test lint
+```
+
+By default it compares against the base branch. You can customize this:
+
+- `nx affected -t test --base=main --head=HEAD` — compare against a specific base and head
+- `nx affected -t test --files=libs/mylib/src/index.ts` — specify changed files directly
+
+## Useful flags
+
+These flags work with `run`, `run-many`, and `affected`:
+
+- `--skipNxCache` — rerun tasks even when results are cached
+- `--verbose` — print additional information such as stack traces
+- `--nxBail` — stop execution after the first failed task
+- `--configuration=<name>` — use a specific configuration (e.g. `production`)

.github/skills/nx-workspace/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: nx-workspace
+description: "Explore and understand Nx workspaces. USE WHEN answering any questions about the nx workspace, the projects in it or tasks to run. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What targets can I run?', 'What's affected by my changes?', 'Which projects depend on library Y?', or any questions about Nx workspace structure, project configuration, or available tasks."
+---
+
+# Nx Workspace Exploration
+
+This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.
+
+Keep in mind that you might have to prefix commands with `npx`/`pnpx`/`yarn` if nx isn't installed globally. Check the lockfile to determine the package manager in use.
+
+## Listing Projects
+
+Use `nx show projects` to list projects in the workspace.
+
+```bash
+# List all projects
+nx show projects
+
+# Filter by pattern (glob)
+nx show projects --projects "apps/*"
+nx show projects --projects "shared-*"
+
+# Filter by project type
+nx show projects --type app
+nx show projects --type lib
+nx show projects --type e2e
+
+# Filter by target (projects that have a specific target)
+nx show projects --withTarget build
+nx show projects --withTarget e2e
+
+# Find affected projects (changed since base branch)
+nx show projects --affected
+nx show projects --affected --base=main
+nx show projects --affected --type app
+
+# Combine filters
+nx show projects --type lib --withTarget test
+nx show projects --affected --exclude="*-e2e"
+
+# Output as JSON
+nx show projects --json
+```
+
+## Project Configuration
+
+Use `nx show project <name> --json` to get the full resolved configuration for a project.
+
+**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project` command returns the full resolved config including inferred targets from plugins.
+
+You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options.
+
+```bash
+# Get full project configuration
+nx show project my-app --json
+
+# Extract specific parts from the JSON
+nx show project my-app --json | jq '.targets'
+nx show project my-app --json | jq '.targets.build'
+nx show project my-app --json | jq '.targets | keys'
+
+
+# Check project metadata
+nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'
+```
+
+## Target Information
+
+Targets define what tasks can be run on a project.
+
+```bash
+# List all targets for a project
+nx show project my-app --json | jq '.targets | keys'
+
+# Get full target configuration
+nx show project my-app --json | jq '.targets.build'
+
+# Check target executor/command
+nx show project my-app --json | jq '.targets.build.executor'
+nx show project my-app --json | jq '.targets.build.command'
+
+# View target options
+nx show project my-app --json | jq '.targets.build.options'
+
+# Check target inputs/outputs (for caching)
+nx show project my-app --json | jq '.targets.build.inputs'
+nx show project my-app --json | jq '.targets.build.outputs'
+
+# Find projects with a specific target
+nx show projects --withTarget serve
+nx show projects --withTarget e2e
+```
+
+## Workspace Configuration
+
+Read `nx.json` directly for workspace-level configuration.
+You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options.
+
+```bash
+# Read the full nx.json
+cat nx.json
+
+# Or use jq for specific sections
+cat nx.json | jq '.targetDefaults'
+cat nx.json | jq '.namedInputs'
+cat nx.json | jq '.plugins'
+cat nx.json | jq '.generators'
+```
+
+Key nx.json sections:
+
+- `targetDefaults` - Default configuration applied to all targets of a given name
+- `namedInputs` - Reusable input definitions for caching
+- `plugins` - Nx plugins and their configuration
+- ...and much more, read the schema or nx.json for details
+
+## Affected Projects
+
+Find projects affected by changes in the current branch.
+
+```bash
+# Affected since base branch (auto-detected)
+nx show projects --affected
+
+# Affected with explicit base
+nx show projects --affected --base=main
+nx show projects --affected --base=origin/main
+
+# Affected between two commits
+nx show projects --affected --base=abc123 --head=def456
+
+# Affected apps only
+nx show projects --affected --type app
+
+# Affected excluding e2e projects
+nx show projects --affected --exclude="*-e2e"
+
+# Affected by uncommitted changes
+nx show projects --affected --uncommitted
+
+# Affected by untracked files
+nx show projects --affected --untracked
+```
+
+## Common Exploration Patterns
+
+### "What's in this workspace?"
+
+```bash
+nx show projects
+nx show projects --type app
+nx show projects --type lib
+```
+
+### "How do I build/test/lint project X?"
+
+```bash
+nx show project X --json | jq '.targets | keys'
+nx show project X --json | jq '.targets.build'
+```
+
+### "What depends on library Y?"
+
+```bash
+# Find projects that may depend on Y by searching for imports
+# (Nx doesn't have a direct "dependents" command via CLI)
+grep -r "from '@myorg/Y'" --include="*.ts" --include="*.tsx" apps/ libs/
+```
+
+### "What configuration options are available?"
+
+```bash
+cat node_modules/nx/schemas/nx-schema.json | jq '.properties | keys'
+cat node_modules/nx/schemas/project-schema.json | jq '.properties | keys'
+```
+
+### "Why is project X affected?"
+
+```bash
+# Check what files changed
+git diff --name-only main
+
+# See which project owns those files
+nx show project X --json | jq '.root'
+```

.github/workflows/banner-monitor.yml

@@ -0,0 +1,92 @@
+name: Banner Content Monitor
+
+on:
+  schedule:
+    - cron: '*/15 * * * *'
+  workflow_dispatch: # Allow manual trigger
+
+permissions: {}
+
+env:
+  BANNER_URL: ${{ vars.BANNER_URL }}
+
+jobs:
+  check-and-deploy:
+    if: ${{ github.repository_owner == 'nrwl' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch banner content and compute hash
+        id: banner
+        run: |
+          if [ -z "$BANNER_URL" ]; then
+            echo "BANNER_URL is not set"
+            exit 1
+          fi
+
+          # Fetch content and compute hash
+          CONTENT_HASH=$(curl -sf "$BANNER_URL" | sha256sum | cut -d' ' -f1)
+
+          if [ -z "$CONTENT_HASH" ]; then
+            echo "Failed to fetch banner content"
+            exit 1
+          fi
+
+          echo "current_hash=$CONTENT_HASH" >> $GITHUB_OUTPUT
+          echo "Current banner hash: $CONTENT_HASH"
+
+      - name: Restore cached hash
+        id: cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.0.3
+        with:
+          path: .banner-hash
+          key: banner-content-hash-
+          restore-keys: |
+            banner-content-hash-
+
+      - name: Compare hashes
+        id: compare
+        run: |
+          CURRENT_HASH="${{ steps.banner.outputs.current_hash }}"
+
+          if [ -f .banner-hash ]; then
+            CACHED_HASH=$(cat .banner-hash)
+            echo "Cached hash: $CACHED_HASH"
+          else
+            CACHED_HASH=""
+            echo "No cached hash found"
+          fi
+
+          if [ "$CURRENT_HASH" != "$CACHED_HASH" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "Banner content has changed!"
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+            echo "Banner content unchanged"
+          fi
+
+      - name: Trigger Netlify deploys
+        if: steps.compare.outputs.changed == 'true'
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        run: |
+          npm install -g netlify-cli
+
+          echo "Triggering nx-docs deploy..."
+          netlify deploy --trigger --prod -s nx-docs
+
+          echo "Triggering nx-dev deploy..."
+          netlify deploy --trigger --prod -s nx-dev
+
+          echo "Both deploys triggered successfully"
+
+      - name: Save new hash to cache
+        if: steps.compare.outputs.changed == 'true'
+        run: |
+          echo "${{ steps.banner.outputs.current_hash }}" > .banner-hash
+
+      - name: Update cache
+        if: steps.compare.outputs.changed == 'true'
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.0.3
+        with:
+          path: .banner-hash
+          key: banner-content-hash-${{ github.run_id }}

.github/workflows/ci.yml

@@ -11,12 +11,14 @@ on:
 
 env:
   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+  NX_CLOUD_ENABLE_METRICS_COLLECTION: 'true'
   PNPM_HOME: ~/.pnpm
 
 jobs:
   main-linux:
     runs-on: ubuntu-latest
     env:
+      NX_BATCH_MODE: 'true'
       NX_E2E_CI_CACHE_KEY: e2e-github-linux
       NX_DAEMON: 'true'
       NX_PERF_LOGGING: 'false'
@@ -26,8 +28,9 @@ jobs:
       NX_CI_EXECUTION_ENV: 'linux'
       NX_CLOUD_NO_TIMEOUTS: 'true'
       NX_ALLOW_NON_CACHEABLE_DTE: 'true'
-      NX_CLOUD_USE_NEW_TASK_APIS: 'true'
-      NX_CLOUD_USE_NEW_STREAM_OUTPUT: 'true'
+      NX_CLOUD_EXPERIMENTAL_POLLING: 'true'
+      NX_CLOUD_CONTINUOUS_ASSIGNMENT: 'false'
+      NX_CLOUD_VERBOSE_LOGGING: 'true'
 
     steps:
       - name: Checkout
@@ -36,78 +39,69 @@ jobs:
           fetch-depth: 0
           filter: tree:0
 
+      - name: Set verbose logging from debug mode
+        if: runner.debug == '1'
+        run: echo "NX_VERBOSE_LOGGING=true" >> "$GITHUB_ENV"
+
       - name: Fetch Master
         run: git fetch origin master:master
         if: ${{ github.event_name == 'pull_request' }}
 
       - name: Set SHAs
-        uses: nrwl/nx-set-shas@1859e66a83ac9be0dceecbd9a023702e27ac47f4 # v4.3.3
+        uses: nrwl/nx-set-shas@310288c04d90696f9f1bc27c5e3caea6642b53d4 # v5.0.0
         with:
           main-branch-name: 'master'
 
       - name: Start CI Run
-        run: npx nx-cloud@next start-ci-run --fix-tasks="!*check-commit*" --auto-apply-fixes="*format:check*,*sync:check*,*conformance:check*,*format-native*,*lint-native*,*lint*,*astro-docs:validate-links*" --distribute-on="./.nx/workflows/dynamic-changesets.yaml" --stop-agents-after="e2e"
+        run: npx nx-cloud@next start-ci-run --distribute-on="./.nx/workflows/dynamic-changesets.yaml" --stop-agents-after="e2e"
 
-      - name: Install dependencies
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
+
+      - name: Enable corepack and install pnpm
         run: |
-          sudo apt-get update
-          sudo apt-get install -y ca-certificates lsof libvips-dev libglib2.0-dev libgirepository1.0-dev
+          corepack enable
+          corepack prepare --activate
 
-      - name: Install Chrome
-        uses: browser-actions/setup-chrome@2dbff04819ebbfd5c974947148805a825b8a07fd # v2.1.0
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        run: echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
 
-      - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
-        name: Install pnpm
+      - name: Cache pnpm store
+        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
         with:
-          version: 10.11.1
-          run_install: false
-
-      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: 20
-          cache: 'pnpm'
-
-      - name: Install Rust
-        uses: actions-rust-lang/setup-rust-toolchain@ac90e63697ac2784f4ecfe2964e1a285c304003a # v1
-        with:
-          rustflags: ''
-
-      - name: Setup Java
-        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
-        with:
-          distribution: temurin
-          java-version: 17
-          cache: maven
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
 
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@48b5f213c81028ace310571dc5ec0fbbca0b2947 # v4.4.3
 
       - name: Install project dependencies
-        run: |
-          pnpm install --frozen-lockfile
-          pnpm playwright install --with-deps
+        run: pnpm install --frozen-lockfile
 
       - name: Nx Report
-        run: 
+        run:
           pnpm nx report
 
       - name: Run Checks/Lint/Test/Build
         run: |
           pids=()
 
-          pnpm nx-cloud record -- nx format:check &
+          pnpm nx record -- nx format:check &
           pids+=($!)
 
-          pnpm nx-cloud record -- nx sync:check
+          pnpm nx record -- nx sync:check
           pids+=($!)
 
-          pnpm nx-cloud record -- nx-cloud conformance:check
+          pnpm nx build workspace-plugin && pnpm nx record -- pnpm nx-cloud conformance:check
           pids+=($!)
 
-          pnpm nx run-many -t check-imports check-commit check-lock-files check-codeowners --parallel=1 --no-dte &
+          pnpm nx run-many -t check-imports check-lock-files check-codeowners --parallel=1 --no-dte &
           pids+=($!)
 
-          pnpm nx affected --targets=lint,test,test-kt,build,e2e,e2e-ci,format-native,lint-native &
+          pnpm nx affected --targets=lint,test,build,e2e,e2e-ci,format-native,lint-native,gradle:build-ci,vale,run &
           pids+=($!)
 
           for pid in "${pids[@]}"; do
@@ -115,7 +109,7 @@ jobs:
           done
         timeout-minutes: 100
       - name: Fix CI
-        run: pnpm nx-cloud fix-ci
+        run: pnpm nx fix-ci
         if: failure()
 
   main-macos:
@@ -145,23 +139,24 @@ jobs:
           fetch-depth: 0
           filter: tree:0
 
+      - name: Set verbose logging from debug mode
+        if: runner.debug == '1'
+        run: echo "NX_VERBOSE_LOGGING=true" >> "$GITHUB_ENV"
+
       - name: Fetch Master
         run: git fetch origin master:master
         if: ${{ github.event_name == 'pull_request' }}
 
-      - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
-        name: Install pnpm
-        with:
-          version: 10.11.1
-          run_install: false
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
 
-      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: 20
-          cache: 'pnpm'
+      - name: Enable corepack and install pnpm
+        run: |
+          corepack enable
+          corepack prepare --activate
 
       - name: Set SHAs
-        uses: nrwl/nx-set-shas@1859e66a83ac9be0dceecbd9a023702e27ac47f4 # v4.3.3
+        uses: nrwl/nx-set-shas@310288c04d90696f9f1bc27c5e3caea6642b53d4 # v5.0.0
         with:
           main-branch-name: 'master'
 
@@ -294,11 +289,19 @@ jobs:
             ~/Library/Caches/Homebrew
           key: nrwl-nx-homebrew-packages
 
-      - name: Install Rust
+      - name: Get pnpm store directory
         if: steps.check-changes.outputs.has_changes == 'true'
-        uses: actions-rust-lang/setup-rust-toolchain@ac90e63697ac2784f4ecfe2964e1a285c304003a # v1
+        id: pnpm-cache-macos
+        run: echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+      - name: Cache pnpm store
+        if: steps.check-changes.outputs.has_changes == 'true'
+        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
         with:
-          rustflags: ''
+          path: ${{ steps.pnpm-cache-macos.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
 
       - name: Install project dependencies
         if: steps.check-changes.outputs.has_changes == 'true'

.github/workflows/codeql-master.yml

@@ -51,6 +51,8 @@ jobs:
           build-mode: none
         - language: rust
           build-mode: none
+        - language: csharp
+          build-mode: autobuild
         # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
         # Use `c-cpp` to analyze code written in C, C++ or both
         # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
@@ -63,6 +65,14 @@ jobs:
     - name: Checkout repository
       uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
+    - name: Setup Language Tooling
+      uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
+
+    - name: Enable corepack and install pnpm
+      run: |
+        corepack enable
+        corepack prepare --activate
+
     # Add any setup steps before running the `github/codeql-action/init` action.
     # This includes steps like installing compilers or runtimes (`actions/setup-node`
     # or others). This is typically only required for manual builds.

.github/workflows/codeql-pr.yml

@@ -46,6 +46,8 @@ jobs:
           build-mode: none
         - language: rust
           build-mode: none
+        - language: csharp
+          build-mode: autobuild
         # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
         # Use `c-cpp` to analyze code written in C, C++ or both
         # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
@@ -58,6 +60,14 @@ jobs:
     - name: Checkout repository
       uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
+    - name: Setup Language Tooling
+      uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
+
+    - name: Enable corepack and install pnpm
+      run: |
+        corepack enable
+        corepack prepare --activate
+
     # Add any setup steps before running the `github/codeql-action/init` action.
     # This includes steps like installing compilers or runtimes (`actions/setup-node`
     # or others). This is typically only required for manual builds.

.github/workflows/e2e-matrix.yml

@@ -20,6 +20,8 @@ jobs:
     if: ${{ github.repository_owner == 'nrwl' }}
     runs-on: ${{ matrix.os }}
     timeout-minutes: 20
+    env:
+      NODE_VERSION: ${{ matrix.node_version }}
     strategy:
       matrix:
         os:
@@ -28,19 +30,20 @@ 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
-          # - 23
+          - 24
         exclude:
-          # run just node v20 on macos and windows
+          # run just node v24 on macos and windows
+          - os: macos-latest
+            node_version: 20
           - os: macos-latest
             node_version: 22
-          # - os: macos-latest
-          #   node_version: 23
-          # - os: windows-latest TODO (emily): Windows fails to build gradle wrapper which always runs when we build nx. Re-enable when we fix this.
-          # node_version: 22
-          # - os: windows-latest TODO (emily): Windows fails to build gradle wrapper which always runs when we build nx. Re-enable when we fix this.
-          #   node_version: 23
+          # - 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 }})
     steps:
@@ -50,17 +53,14 @@ jobs:
           fetch-depth: 0
           filter: tree:0
 
-      - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
-        name: Install pnpm
-        with:
-          version: 10.11.1
-          run_install: false
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
 
-      - name: Set node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: ${{ matrix.node_version }}
-          cache: 'pnpm'
+      - name: Enable corepack and install pnpm
+        run: |
+          npm install -g corepack@latest
+          corepack enable
+          corepack prepare --activate
 
       - name: Get pnpm store directory
         id: pnpm-cache
@@ -138,6 +138,8 @@ jobs:
       contents: read
     runs-on: ${{ matrix.os }}
     timeout-minutes: 200 # <- cap each job to 200 minutes
+    env:
+      NODE_VERSION: ${{ matrix.node_version }}
     strategy:
       matrix: ${{fromJson(needs.prepare-matrix.outputs.matrix)}} # Load matrix from previous job
       fail-fast: false
@@ -153,39 +155,14 @@ jobs:
       - name: Prepare dir for output
         run: mkdir -p outputs
 
-      - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
-        name: Install pnpm
-        with:
-          version: 10.11.1
-          run_install: false
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
 
-      - name: Use Node.js ${{ matrix.node_version }}
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: ${{ matrix.node_version }}
-          cache: 'pnpm'
-
-      - name: Install Rust
-        if: ${{ matrix.os != 'windows-latest' }}
+      - name: Enable corepack and install pnpm
         run: |
-          curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y
-          source "$HOME/.cargo/env"
-          rustup toolchain install 1.70.0
-
-      - name: Load Cargo Env
-        if: ${{ matrix.os != 'windows-latest' }}
-        run: echo "PATH=$HOME/.cargo/bin:$PATH" >> $GITHUB_ENV
-
-      - name: Setup .NET 9
-        uses: actions/setup-dotnet@d4c94342e560b34958eacfc5d055d21461ed1c5d # v5.0.0
-        with:
-          dotnet-version: '9.0.x'
-
-      - name: Install bun
-        if: ${{ matrix.os != 'windows-latest' }}
-        uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
-        with:
-          bun-version: latest
+          npm install -g corepack@latest
+          corepack enable
+          corepack prepare --activate
 
       - name: Install packages
         run: |
@@ -420,7 +397,7 @@ jobs:
     if: ${{ always() && github.repository_owner == 'nrwl' && github.event_name != 'workflow_dispatch' }}
     runs-on: ubuntu-latest
     needs: e2e
-    timeout-minutes: 10
+    timeout-minutes: 15
     outputs:
       message: ${{ steps.process-json.outputs.slack_message }}
       proj_duration: ${{ steps.process-json.outputs.slack_proj_duration }}
@@ -448,8 +425,10 @@ jobs:
           combined=$(jq -sc . outputs/*/matrix.json)
           echo "combined=$combined" >> $GITHUB_OUTPUT
 
-      - name: Process results with TypeScript script
+      - name: Process results and collect failure details
         id: process-json
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
           echo '${{ steps.combine-json.outputs.combined }}' | npx tsx .github/workflows/nightly/process-result.ts
 

.github/workflows/generate-embeddings.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: ['20.19.0']
+        node-version: ['24']
 
     steps:
       - name: Checkout
@@ -19,14 +19,14 @@ jobs:
       - name: Install Node.js
         uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
-          node-version: '20.19.0'
+          node-version: '24'
           package-manager-cache: false
 
       - name: Install pnpm
         uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
         id: pnpm-install
         with:
-          version: 10.11.1
+          version: 10.28.2
           run_install: false
 
       - name: Get pnpm store directory

.github/workflows/issue-notifier.yml

@@ -20,12 +20,12 @@ jobs:
 
       - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
         with:
-          version: 10.11.1
+          version: 10.28.2
 
       - name: Use Node.js ${{ matrix.node_version }}
         uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
-          node-version: '20.19.0'
+          node-version: '24'
           cache: 'pnpm'
 
       - name: Cache node_modules
@@ -64,7 +64,6 @@ jobs:
         id: slack
         uses: slackapi/slack-github-action@91efab103c0de0a537f72a35f6b8cda0ee76bf0a # v2.1.1
         with:
+          webhook: ${{ secrets.SLACK_ISSUES_REPORT_URL }}
+          webhook-type: incoming-webhook
           payload: ${{ steps.collect.outputs.SLACK_MESSAGE }}
-        env:
-          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_ISSUES_REPORT_URL }}
-          SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK

.github/workflows/lock-threads.yml

@@ -17,9 +17,10 @@ jobs:
     if: ${{ github.repository_owner == 'nrwl' }}
     runs-on: ubuntu-latest
     steps:
-      - uses: dessant/lock-threads@7de207be1d3ce97a9abe6ff1306222982d1ca9f9 # v5.0.1
+      - uses: dessant/lock-threads@6548363a2d763e3a4a3a0dc04ca4a10481d8e536 # v6.0.0
         id: lockthreads
         with:
+          process-only: 'issues, prs'
           github-token: ${{ github.token }}
           issue-inactive-days: "30" # Lock issues after 30 days of being closed
           pr-inactive-days: "5" # Lock closed PRs after 5 days. This ensures that issues that stem from a PR are opened as issues, rather than comments on the recently merged PR.

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

@@ -0,0 +1,674 @@
+import { exec } from 'child_process';
+import { execSync } from 'child_process';
+
+const MAX_CONCURRENCY = 8;
+
+interface MatrixResult {
+  project: string;
+  codeowners: string;
+  node_version: number | string;
+  package_manager: string;
+  os: string;
+  os_name: string;
+  os_timeout: number;
+  is_golden?: boolean;
+  status: 'success' | 'failure' | 'cancelled';
+  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';
+
+function gh(args: string): string {
+  try {
+    return execSync(`gh ${args}`, {
+      encoding: 'utf-8',
+      timeout: 60_000,
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function ghAsync(args: string): Promise<string> {
+  return new Promise((resolve) => {
+    exec(
+      `gh ${args}`,
+      { encoding: 'utf-8', timeout: 60_000, maxBuffer: 10 * 1024 * 1024 },
+      (err, stdout) => resolve(err ? '' : (stdout || '').trim())
+    );
+  });
+}
+
+async function ghParallel<T>(
+  items: T[],
+  fn: (item: T) => string,
+  concurrency = MAX_CONCURRENCY
+): Promise<Map<T, string>> {
+  const results = new Map<T, string>();
+  const queue = [...items];
+
+  async function worker() {
+    while (queue.length > 0) {
+      const item = queue.shift()!;
+      results.set(item, await ghAsync(fn(item)));
+    }
+  }
+
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, () => worker())
+  );
+  return results;
+}
+
+function extractJestBlocks(raw: string): string {
+  const lines = raw
+    .replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z /gm, '')
+    .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')
+    .split('\n');
+
+  const blocks: string[] = [];
+  let capturing = false;
+  for (const line of lines) {
+    if (line.startsWith(' FAIL ')) capturing = true;
+    if (capturing) blocks.push(line);
+    if (line.startsWith('Ran all test suites')) capturing = false;
+  }
+  return blocks.slice(0, 50).join('\n');
+}
+
+function extractTestFiles(block: string): string[] {
+  const matches = block.match(/FAIL\s+\S+\s+(src\/[^\s]+\.test\.ts)/g) || [];
+  return [...new Set(matches.map((m) => m.replace(/FAIL\s+\S+\s+/, '')))];
+}
+
+// Extract a normalized error signature for a test file from a Jest block.
+// Used to distinguish different root causes for the same test file across runs.
+function extractErrorSignature(block: string, testFile: string): string {
+  const lines = block.split('\n');
+  let afterBullet = false;
+  let inFile = false;
+  for (const l of lines) {
+    if (l.includes('FAIL') && l.includes(testFile)) { inFile = true; continue; }
+    if (inFile && /●/.test(l)) { afterBullet = true; continue; }
+    if (!inFile || !afterBullet) continue;
+    const trimmed = l.trim();
+    if (!trimmed) continue;
+    // Skip generic "Command failed" and warnings — find the actual error
+    if (/^Command failed:|^warning /i.test(trimmed)) continue;
+    // Normalize dynamic parts
+    return trimmed
+      .replace(/\/tmp\/[^\s]+/g, '<tmpdir>')
+      .replace(/\/Users\/[^\s]+/g, '<path>')
+      .replace(/\/home\/[^\s]+/g, '<path>')
+      .replace(/[a-z]+\d{5,}/gi, '<id>')
+      .replace(/\d{4}-\d{2}-\d{2}T[\d:._Z-]+/g, '<ts>')
+      .replace(/\d+\.\d+\.\d+/g, '<ver>')
+      .trim();
+  }
+  return '';
+}
+
+// Extract signatures for all test files in a block
+function extractSignatures(
+  block: string,
+  testFiles: string[]
+): Map<string, string> {
+  const sigs = new Map<string, string>();
+  for (const tf of testFiles) {
+    sigs.set(tf, extractErrorSignature(block, tf));
+  }
+  return sigs;
+}
+
+function extractBlockForFile(fullBlock: string, testFile: string): string {
+  const lines = fullBlock.split('\n');
+  const result: string[] = [];
+  let capturing = false;
+  for (const line of lines) {
+    if (line.includes('FAIL') && line.includes(testFile)) capturing = true;
+    else if (capturing && line.match(/^ FAIL /)) capturing = false;
+    if (capturing) result.push(line);
+  }
+  return result.slice(0, 20).join('\n');
+}
+
+export interface JobLink {
+  combo: string;
+  url: string;
+}
+
+export interface FailureDetailsResult {
+  report: string;
+  goldenJobLinks: Map<string, JobLink[]>; // project -> [{combo, url}]
+}
+
+/**
+ * Collects detailed failure information for golden projects.
+ * Called by process-result.ts when golden failures exist.
+ * Returns Slack mrkdwn report + job links for the summary section.
+ */
+export async function collectFailureDetails(
+  combined: MatrixResult[],
+  failedGoldenProjectNames: string[]
+): Promise<FailureDetailsResult> {
+  const projectNames = failedGoldenProjectNames;
+  if (projectNames.length === 0) {
+    return { report: '', goldenJobLinks: new Map() };
+  }
+
+  // Group failures by project for combo info
+  const failuresByProject = new Map<string, MatrixResult[]>();
+  for (const r of combined) {
+    if (r.is_golden && (r.status === 'failure' || r.status === 'cancelled')) {
+      if (!failuresByProject.has(r.project))
+        failuresByProject.set(r.project, []);
+      failuresByProject.get(r.project)!.push(r);
+    }
+  }
+
+  // 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)
+  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])}]'`
+  );
+  const failedJobs: Array<{
+    id: number;
+    name: string;
+    project: string;
+    combo: string;
+  }> = failedJobsRaw ? JSON.parse(failedJobsRaw) : [];
+
+  const jobsToFetch: Array<{ id: number; project: string }> = [];
+  for (const project of projectNames) {
+    const seen = new Set<string>();
+    for (const job of failedJobs.filter((j) => j.project === project)) {
+      const key = job.combo.split('/').slice(0, 2).join('/');
+      if (!seen.has(key)) {
+        seen.add(key);
+        jobsToFetch.push({ id: job.id, project: job.project });
+      }
+    }
+  }
+
+  const logResults = await ghParallel(
+    jobsToFetch,
+    (job) => `api repos/${REPO}/actions/jobs/${job.id}/logs`
+  );
+
+  // Keep per-combo logs separate AND a merged block per project
+  interface ComboLog {
+    combo: string;
+    block: string;
+    testFiles: string[];
+    signatures: Map<string, string>; // testFile -> error signature
+  }
+  const projectComboLogs = new Map<string, ComboLog[]>();
+  const projectLogs = new Map<string, string>(); // merged block for backwards compat
+
+  for (const [job, raw] of logResults) {
+    if (!raw) continue;
+    const cleaned = raw
+      .replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z /gm, '')
+      .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+    const block = extractJestBlocks(raw);
+    const testFiles = extractTestFiles(cleaned);
+    const sigs = extractSignatures(cleaned, testFiles);
+    const combo =
+      failedJobs.find((j) => j.id === job.id)?.combo || 'unknown';
+
+    if (!projectComboLogs.has(job.project))
+      projectComboLogs.set(job.project, []);
+    projectComboLogs.get(job.project)!.push({
+      combo,
+      block,
+      testFiles,
+      signatures: sigs,
+    });
+
+    projectLogs.set(
+      job.project,
+      (projectLogs.get(job.project) || '') + '\n' + block
+    );
+  }
+
+  // Step 3: Build distinct failures per project — each (testFile, signature, combos) is a "failure"
+  interface DistinctFailure {
+    testFile: string;
+    signature: string;
+    combos: string[];
+    block: string; // the Jest block from the first combo that has this signature
+  }
+
+  const projectDistinctFailures = new Map<string, DistinctFailure[]>();
+  for (const project of projectNames) {
+    const comboLogs = projectComboLogs.get(project) || [];
+    const seen = new Map<string, DistinctFailure>(); // "testFile|signature" -> failure
+
+    for (const cl of comboLogs) {
+      for (const tf of cl.testFiles) {
+        const sig = cl.signatures.get(tf) || '';
+        const key = `${tf}|${sig}`;
+        if (seen.has(key)) {
+          seen.get(key)!.combos.push(cl.combo);
+        } else {
+          seen.set(key, {
+            testFile: tf,
+            signature: sig,
+            combos: [cl.combo],
+            block: extractBlockForFile(cl.block, tf),
+          });
+        }
+      }
+    }
+    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
+  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 ||
+      (failuresByProject.get(b)?.length || 0) -
+        (failuresByProject.get(a)?.length || 0)
+    );
+  });
+
+  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) || '';
+
+    const pms = [...new Set(projResults.map((r) => r.package_manager))];
+    const pattern =
+      pms.length === 1
+        ? `${pms[0]}-only`
+        : pms.length >= 3
+          ? '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)
+      ),
+    ];
+
+    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}`
+        );
+
+        if (failure.block) {
+          lines.push('```');
+          lines.push(failure.block);
+          lines.push('```');
+        }
+      }
+
+      const summaryMatch = block.match(/^Test Suites:.*$/m);
+      if (summaryMatch) lines.push(`_${summaryMatch[0]}_`);
+    } else {
+      // No Jest blocks — find which step failed and extract its error output
+      const firstJob = failedJobs.find((j) => j.project === project);
+      if (firstJob) {
+        // Get the failed step name from the jobs API
+        const stepsRaw = gh(
+          `run view ${RUN_ID} --repo ${REPO} --json jobs --jq '[.jobs[] | select(.databaseId == ${firstJob.id})][0].steps[] | select(.conclusion == "failure") | .name'`
+        );
+        const failedStep = stepsRaw || 'unknown step';
+
+        // Get the log and extract error lines
+        const raw = gh(`api repos/${REPO}/actions/jobs/${firstJob.id}/logs`);
+        const cleaned = raw
+          .split('\n')
+          .map((l) => l.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z /, ''))
+          .map((l) => l.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, ''));
+
+        // Extract the failed Nx task output block (❌ > nx run <task> ... until next ##[group] or NX summary)
+        const failedTaskBlock: string[] = [];
+        let capturingTask = false;
+        for (const l of cleaned) {
+          if (/❌.*> nx run /i.test(l)) {
+            capturingTask = true;
+            failedTaskBlock.push(l);
+            continue;
+          }
+          if (capturingTask) {
+            if (/^##\[group\]|NX.*Running target/i.test(l) || failedTaskBlock.length >= 15) {
+              capturingTask = false;
+            } else {
+              failedTaskBlock.push(l);
+            }
+          }
+        }
+
+        // Extract the Nx failure summary block ("Running target...failed" + "Failed tasks:" + task list)
+        const nxFailureBlock: string[] = [];
+        let capturingNx = false;
+        for (const l of cleaned) {
+          if (/NX.*Running target.*failed/i.test(l)) capturingNx = true;
+          if (capturingNx) {
+            nxFailureBlock.push(l);
+            if (/^Hint:/i.test(l.trim()) || nxFailureBlock.length >= 10) {
+              capturingNx = false;
+            }
+          }
+        }
+
+        // Fallback: if no Nx blocks or task blocks found, extract generic error lines
+        let fallbackErrors: string[] = [];
+        if (nxFailureBlock.length === 0 && failedTaskBlock.length === 0) {
+          fallbackErrors = cleaned.filter((l) => {
+            const t = l.trim();
+            if (t.length < 10) return false;
+            if (/warning|warn\b|deprecated|orphan|Node\.js 20|FORCE_JAVASCRIPT|\* \[new branch\]|\* \[new tag\]/i.test(t)) return false;
+            return (
+              /error TS\d+:|^Error:|^\s*error\b[:\s]|ERR!|ERESOLVE|##\[error\]/i.test(t) ||
+              /Cannot find module|ENOENT|EACCES|permission denied/i.test(t) ||
+              /Segmentation fault|killed|OOM|out of memory/i.test(t) ||
+              /command not found|No such file or directory/i.test(t) ||
+              /Process completed with exit code [^0]/i.test(t)
+            );
+          }).slice(0, 5);
+        }
+
+        // Combine: Nx summary first, then task output, then fallback errors
+        const relevantErrors = [
+          ...nxFailureBlock,
+          ...(failedTaskBlock.length > 0 ? ['', ...failedTaskBlock] : []),
+          ...(fallbackErrors.length > 0 ? ['', ...fallbackErrors] : []),
+        ];
+
+        lines.push(`⚠️ Tests did not run — failed at step: *${failedStep}*`);
+        if (relevantErrors.length > 0) {
+          lines.push('```');
+          lines.push(relevantErrors.join('\n'));
+          lines.push('```');
+        }
+        lines.push(`Failing combos: ${uniqueCombos.join(', ')}`);
+      } else {
+        lines.push('⏱️ No job data available');
+      }
+    }
+    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[]>();
+  for (const project of projectNames) {
+    const projectJobs = failedJobs.filter((j) => j.project === project);
+    goldenJobLinks.set(
+      project,
+      projectJobs.map((j) => ({
+        combo: j.combo,
+        url: `${runUrl}/job/${j.id}`,
+      }))
+    );
+  }
+
+  return { report: lines.join('\n'), goldenJobLinks };
+}

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

@@ -67,6 +67,7 @@ const matrixData: MatrixData = {
     { name: 'e2e-storybook', codeowners: 'S04SVQ8H0G5' },
     { name: 'e2e-nuxt', codeowners: 'S04SJ6PL98X' }
   ],
+  // TODO(v23): remove node 20 - EOL April 2026
   nodeTLS: 20,
   setup: [
     {
@@ -74,12 +75,15 @@ const matrixData: MatrixData = {
       os_name: 'Linux',
       os_timeout: 60,
       package_managers: ['npm', 'pnpm', 'yarn'],
-      node_versions: ['20.19.0', '22.12.0'],
+      node_versions: ['20.19.0', '22.13.0', '24.0.0'],
       excluded: ['e2e-detox', 'e2e-react-native', 'e2e-expo']
     },
-    { os: 'macos-latest', os_name: 'MacOS', os_timeout: 90, package_managers: ['npm'], node_versions: ['20.19.0'] }
-    // TODO (emily): 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: ['20.19.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
+    { 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'] }
   ]
 };
 

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

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import { MatrixItem } from './process-matrix';
+import { collectFailureDetails, JobLink } from './analyze-failures';
 
 interface MatrixResult extends MatrixItem {
   status: 'success' | 'failure' | 'cancelled';
@@ -52,42 +53,31 @@ function processResults(combined: MatrixResult[]): ProcessedResults {
   const otherFailingCount = uniqueFailedOtherProjects.size;
 
   result += `\n🌟 *Golden Projects*`;
-  result += `\n✅ Passing: ${goldenPassingCount}`;
-  result += `\n❌ Failing: ${goldenFailingCount}`;
+  result += `\n✅ Passing: ${goldenPassingCount} | ❌ Failing: ${goldenFailingCount}`;
 
   if (failedGoldenProjects.length > 0) {
-    result += `\n\n🚨 *Failed Golden Projects*\n\`\`\``;
-    result += `\n| Failed project                 |`;
-    result += `\n|--------------------------------|`;
-    let lastProject: string | undefined;
+    result += `\n\n🚨 *Failed Golden Projects*`;
+    // Project names listed here — combo links added later by main() with job data
+    const seenProjects = new Set<string>();
     failedGoldenProjects.forEach(matrix => {
-      const project = matrix.project !== lastProject ? matrix.project : '';
-      if (project) {
-        result += `\n| ${project.padEnd(30)} |`;
-        lastProject = matrix.project;
+      if (!seenProjects.has(matrix.project)) {
+        seenProjects.add(matrix.project);
+        result += `\n\n*${matrix.project}*`;
+        // Placeholder — main() will replace with linked combos
+        result += `\n  {{COMBOS:${matrix.project}}}`;
       }
     });
-    result += `\n\`\`\``;
   }
 
-  result += `\n\n🔧 *Other Projects*`;
-  result += `\n✅ Passing: ${otherPassingCount}`;
-  result += `\n❌ Failing: ${otherFailingCount}`;
-
-  // Failed Other Projects Table (if any)
-  if (failedRegularProjects.length > 0) {
-    result += `\n\n⚠️ *Failed Other Projects*\n\`\`\``;
-    result += `\n| Failed project                 |`;
-    result += `\n|--------------------------------|`;
-    let lastProject: string | undefined;
-    failedRegularProjects.forEach(matrix => {
-      const project = matrix.project !== lastProject ? matrix.project : '';
-      if (project) {
-        result += `\n| ${project.padEnd(30)} |`;
-        lastProject = matrix.project;
-      }
+  if (otherFailingCount > 0) {
+    const otherProjectCounts = new Map<string, number>();
+    failedRegularProjects.forEach(m => {
+      otherProjectCounts.set(m.project, (otherProjectCounts.get(m.project) || 0) + 1);
     });
-    result += `\n\`\`\``;
+    const otherSummary = [...otherProjectCounts.entries()]
+      .map(([p, c]) => `${p} (${c})`)
+      .join(', ');
+    result += `\n\n⚠️ *Failed Other Projects:* ${otherSummary}`;
   }
 
   if (failedProjects.length === 0) {
@@ -180,7 +170,7 @@ function setOutput(key: string, value: string) {
   }
 }
 
-try {
+async function main() {
   const combinedInput = process.argv[2]
     ? process.argv[2]
     : fs.readFileSync(0, 'utf-8').trim();
@@ -188,10 +178,52 @@ try {
   const combined: MatrixResult[] = JSON.parse(combinedInput);
   const results = processResults(combined);
 
+  // Collect detailed failure info if golden failures exist
+  if (results.has_golden_failures === 'true') {
+    try {
+      const failedProjects = [
+        ...new Set(
+          combined
+            .filter((c) => c.is_golden && (c.status === 'failure' || c.status === 'cancelled'))
+            .map((c) => c.project)
+        ),
+      ];
+      const { report, goldenJobLinks } = await collectFailureDetails(combined, failedProjects);
+
+      // Replace combo placeholders in the summary with linked combos
+      for (const [project, links] of goldenJobLinks) {
+        const placeholder = `{{COMBOS:${project}}}`;
+        const linkedCombos =
+          links.length > 0
+            ? links.map((l) => `  · <${l.url}|${l.combo}>`).join('\n')
+            : '  (no job data)';
+        results.slack_message = results.slack_message.replace(
+          placeholder,
+          linkedCombos
+        );
+      }
+
+      // Remove any unreplaced placeholders (if collectFailureDetails didn't have data for a project)
+      results.slack_message = results.slack_message.replace(
+        /  \{\{COMBOS:[^}]+\}\}/g,
+        '  (no job data)'
+      );
+
+      if (report) {
+        results.slack_message += '\n\n' + report;
+      }
+    } catch (e) {
+      console.error('Failed to collect failure details (brief report will still be posted):', e);
+      results.slack_message += '\n\n⚠️ _Failed to collect detailed failure information_';
+    }
+  }
+
   Object.entries(results).forEach(([key, value]) => {
     setOutput(key, value);
   });
-} catch (error) {
+}
+
+main().catch((error) => {
   console.error('Error processing results:', error);
   process.exit(1);
-}
+});

.github/workflows/npm-audit.yml

@@ -18,7 +18,7 @@ jobs:
 
       - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
         with:
-          version: 10.11.1 # Aligned with root package.json (pnpm/action-setup will helpfully error if out of sync)
+          version: 10.28.2 # Aligned with root package.json (pnpm/action-setup will helpfully error if out of sync)
 
       - name: Run a security audit
         run: pnpm dlx audit-ci --critical --report-type summary

.github/workflows/pr-title-validation.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
-          node-version: 20
+          node-version: 24
           package-manager-cache: false
 
       - name: Validate PR title

.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: publish
 on:
   # Automated schedule - canary releases from master
   schedule:
-    - cron: "0 20 * * 1-5" # Monday - Friday, at 20:00 UTC (8pm UTC)
+    - cron: "0 19 * * 1-5" # Monday - Friday, at 19:00 UTC (7pm UTC)
   # Manual trigger - PR releases or dry-runs (based on workflow inputs)
   workflow_dispatch:
     inputs:
@@ -22,7 +22,8 @@ env:
   NX_RUN_GROUP: ${{ github.run_id }}-${{ github.run_attempt }}
   CYPRESS_INSTALL_BINARY: 0
   NODE_VERSION: 22.16.0
-  PNPM_VERSION: 10.11.1 # Aligned with root package.json (pnpm/action-setup will helpfully error if out of sync)
+  PNPM_VERSION: 10.28.2 # Aligned with root package.json (pnpm/action-setup will helpfully error if out of sync)
+  NX_GRADLE_PROJECT_GRAPH_TIMEOUT: 600
 
 jobs:
   # We first need to determine the version we are releasing, and if we need a custom repo or ref to use for the git checkout in subsequent steps.
@@ -120,10 +121,10 @@ jobs:
       fail-fast: false
       matrix:
         settings:
-          - host: macos-13
+          - host: macos-latest
             target: x86_64-apple-darwin
             setup: |-
-              rustup target add aarch64-apple-darwin
+              rustup target add x86_64-apple-darwin
             build: |
               pnpm nx run-many --target=build-native -- --target=x86_64-apple-darwin
           - host: windows-latest
@@ -174,7 +175,7 @@ jobs:
               bash -c "
                 set -e
                 echo 'https://dl-cdn.alpinelinux.org/alpine/edge/community' >> /etc/apk/repositories
-                apk add --no-cache curl xz openjdk21
+                apk add --no-cache curl xz openjdk21 build-base lld
 
                 # Set up Java 21
                 export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
@@ -194,12 +195,16 @@ jobs:
                 npm i -g pnpm@${PNPM_VERSION} --force
                 pnpm --version
 
+                # Help clang find GCC runtime (crtbeginS.o, libgcc) and use lld for jemalloc build
+                GCC_DIR=\$(dirname \$(find /usr/lib/gcc -name crtbeginS.o | head -1))
+                export CFLAGS=\"\${CFLAGS} -fuse-ld=lld --gcc-install-dir=\${GCC_DIR}\"
+
                 # Install deps and run native build
                 pnpm install --frozen-lockfile
                 rustup target add x86_64-unknown-linux-musl
                 pnpm nx run-many --verbose --target=build-native -- --target=x86_64-unknown-linux-musl
               "
-          - host: macos-13
+          - host: macos-latest
             target: aarch64-apple-darwin
             setup: |-
               rustup target add aarch64-apple-darwin
@@ -230,6 +235,9 @@ jobs:
               node --version
               npm --version
 
+              # Help clang find GCC runtime (crtbeginS.o, libgcc) and use lld for jemalloc build
+              export CFLAGS="${CFLAGS} -fuse-ld=lld --gcc-toolchain=/usr/aarch64-unknown-linux-gnu"
+
               npm i -g pnpm@${PNPM_VERSION} --force
               pnpm --version
 
@@ -260,7 +268,7 @@ jobs:
               bash -c "
                 set -e
                 echo 'https://dl-cdn.alpinelinux.org/alpine/edge/community' >> /etc/apk/repositories
-                apk add --no-cache curl xz openjdk21
+                apk add --no-cache curl xz openjdk21 build-base lld
 
                 # Set up Java 21
                 export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
@@ -280,6 +288,10 @@ jobs:
                 npm i -g pnpm@${PNPM_VERSION} --force
                 pnpm --version
 
+                # Help clang find GCC runtime (crtbeginS.o, libgcc) and use lld for jemalloc build
+                GCC_DIR=\$(dirname \$(find /aarch64-linux-musl-cross/lib/gcc -name crtbeginS.o | head -1))
+                export CFLAGS=\"\${CFLAGS} -fuse-ld=lld --gcc-install-dir=\${GCC_DIR}\"
+
                 # Install deps and run native build
                 pnpm install --frozen-lockfile
                 rustup target add aarch64-unknown-linux-musl
@@ -303,24 +315,19 @@ jobs:
           repository: ${{ needs.resolve-required-data.outputs.repo || github.repository }}
           ref: ${{ needs.resolve-required-data.outputs.ref || github.ref }}
 
-      - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
-        with:
-          version: ${{ env.PNPM_VERSION }}
+      - name: Set verbose logging from debug mode
+        if: runner.debug == '1'
+        run: echo "NX_VERBOSE_LOGGING=true" >> "$GITHUB_ENV"
 
-      - name: Setup node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
         if: ${{ !matrix.settings.docker }}
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          check-latest: true
-          cache: 'pnpm'
 
-      - name: Install
-        uses: actions-rust-lang/setup-rust-toolchain@ac90e63697ac2784f4ecfe2964e1a285c304003a # v1
+      - name: Enable corepack and install pnpm
         if: ${{ !matrix.settings.docker }}
-        with:
-          target: ${{ matrix.settings.target }}
-          rustflags: ''
+        run: |
+          corepack enable
+          corepack prepare --activate
 
       - name: Cache cargo
         uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
@@ -363,12 +370,26 @@ jobs:
           architecture: x86
 
       - name: Build in docker
-        uses: addnab/docker-run-action@4f65fabd2431ebc8d299f8e5a018d79a769ae185 # v3
         if: ${{ matrix.settings.docker }}
-        with:
-          image: ${{ matrix.settings.docker }}
-          options: --user 0:0 -v ${{ github.workspace }}/.cargo-cache/git/db:/usr/local/cargo/git/db -v ${{ github.workspace }}/.cargo/registry/cache:/usr/local/cargo/registry/cache -v ${{ github.workspace }}/.cargo/registry/index:/usr/local/cargo/registry/index -v ${{ github.workspace }}:/build -w /build
-          run: ${{ matrix.settings.build }}
+        shell: bash
+        env:
+          BUILD_SCRIPT: ${{ matrix.settings.build }}
+        run: |
+          SCRIPT_FILE=$(mktemp)
+          echo "$BUILD_SCRIPT" > "$SCRIPT_FILE"
+          docker run --rm \
+            --user 0:0 \
+            -e PNPM_VERSION \
+            -e NX_GRADLE_PROJECT_GRAPH_TIMEOUT \
+            -e NX_VERBOSE_LOGGING \
+            -v ${{ github.workspace }}/.cargo-cache/git/db:/usr/local/cargo/git/db \
+            -v ${{ github.workspace }}/.cargo/registry/cache:/usr/local/cargo/registry/cache \
+            -v ${{ github.workspace }}/.cargo/registry/index:/usr/local/cargo/registry/index \
+            -v ${{ github.workspace }}:/build \
+            -v "$SCRIPT_FILE:/build-script.sh" \
+            -w /build \
+            ${{ matrix.settings.docker }} \
+            bash /build-script.sh
 
       - name: Build
         run: ${{ matrix.settings.build }}
@@ -405,21 +426,19 @@ jobs:
           NX_PREFER_TS_NODE: true
           PLAYWRIGHT_BROWSERS_PATH: 0
           NODE_VERSION: 22.16.0
+          NX_GRADLE_DISABLE: 'true'
+          NODE_OPTIONS: '--max-old-space-size=4096'
         with:
           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
+          environment_variables: DEBUG RUSTUP_IO_THREADS CI NX_PREFER_TS_NODE PLAYWRIGHT_BROWSERS_PATH NODE_VERSION NX_GRADLE_DISABLE NODE_OPTIONS
           shell: bash
           run: |
             env
             whoami
-            sudo pkg install -y -f node libnghttp2 www/npm git openjdk17
-            sudo npm install --location=global --ignore-scripts pnpm@10.11.1
-            # Set up Java 17
-            export JAVA_HOME=/usr/local/openjdk17
-            export PATH="$JAVA_HOME/bin:$PATH"
-            java --version
+            sudo pkg install -y -f node libnghttp2 www/npm git ca_root_nss
+            sudo npm install --location=global --ignore-scripts pnpm@10.28.2
             curl https://sh.rustup.rs -sSf --output rustup.sh
             sh rustup.sh -y --profile minimal --default-toolchain stable
             source "$HOME/.cargo/env"
@@ -475,17 +494,46 @@ jobs:
             pnpm store prune || true
             rm -rf ~/.npm || true
             rm -rf ~/.pnpm-store || true
-            # Remove Rust build artifacts if any
-            rm -rf ~/.cargo/registry || true
-            rm -rf ~/.cargo/git || true
+            # Clean Rust extras but keep registry/git (needed for cargo to resolve deps)
             rm -rf ~/.rustup/toolchains/*/share || true
             # Remove other development tool caches
             rm -rf ~/.cache/* || true
+
+            # Remove unnecessary workspace directories
+            rm -rf docs astro-docs nx-dev || true
+
             echo "Checking disk space after cleanup"
             df -h
             
+            # Disable core dumps - OOM'd Node processes write multi-GB core files that fill the disk
+            ulimit -c 0
+
             echo "Building FreeBSD bindings"
-            pnpm nx run-many --verbose --outputStyle stream --target=build-native -- --target=x86_64-unknown-freebsd
+            BUILD_EXIT=0
+            pnpm nx run-many --verbose --outputStyle stream --target=build-native -- --target=x86_64-unknown-freebsd || BUILD_EXIT=$?
+
+            echo "=== Disk usage after build ==="
+            df -h
+
+            if [ "$BUILD_EXIT" -ne 0 ]; then
+              echo "Build failed with exit code $BUILD_EXIT"
+              echo "=== Disk usage by top-level directories ==="
+              du -sh /* 2>/dev/null | sort -rh | head -20
+              echo "=== Disk usage in home directory ==="
+              du -sh ~/* 2>/dev/null | sort -rh | head -20
+              echo "=== Disk usage in workspace ==="
+              du -sh /home/runner/work/nx/nx/* 2>/dev/null | sort -rh | head -20
+              echo "=== Disk usage in .nx ==="
+              du -sh /home/runner/work/nx/nx/.nx/* 2>/dev/null | sort -rh | head -20
+              echo "=== Disk usage in cargo/rustup ==="
+              du -sh ~/.cargo/* ~/.rustup/* 2>/dev/null | sort -rh | head -20
+              echo "=== Core dumps ==="
+              find / -name "*.core" -o -name "core.*" -o -name "core" 2>/dev/null | head -10
+              exit $BUILD_EXIT
+            fi
+
+            echo "Build succeeded"
+            
             echo "Cleaning up"
             pnpm nx reset
             rm -rf node_modules
@@ -523,18 +571,18 @@ jobs:
           repository: ${{ needs.resolve-required-data.outputs.repo || github.repository }}
           ref: ${{ needs.resolve-required-data.outputs.ref || github.ref }}
 
-      - uses: pnpm/action-setup@7088e561eb65bb68695d245aa206f005ef30921d # v4.1.0
-        with:
-          version: ${{ env.PNPM_VERSION }}
+      - name: Set verbose logging from debug mode
+        if: runner.debug == '1'
+        run: echo "NX_VERBOSE_LOGGING=true" >> "$GITHUB_ENV"
+
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
+
+      - name: Enable corepack and install pnpm
+        run: |
+          corepack enable
+          corepack prepare --activate
 
-      - name: Setup node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          registry-url: 'https://registry.npmjs.org'
-          check-latest: true
-          cache: 'pnpm'
-     
       - name: Use npm 11.5.2
         run: npm install -g npm@11.5.2
 
@@ -554,13 +602,13 @@ jobs:
         run: |
           wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-23/wasi-sdk-23.0-x86_64-linux.tar.gz
           tar -xvf wasi-sdk-23.0-x86_64-linux.tar.gz
+          rustup toolchain install nightly-2025-05-09
           pnpm build:wasm
       - name: Publish
         env:
           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 }}
-          NX_VERBOSE_LOGGING: true
         run: |
           echo ""
           # Create and check out the publish branch

.gitignore

@@ -25,7 +25,14 @@ jest.debug.config.js
 /nx-dev/nx-dev/public/documentation
 /nx-dev/nx-dev/public/tutorials
 /nx-dev/nx-dev/public/images/open-graph
-**/tests/temp-db
+/nx-dev/nx-dev/public/robots.txt
+/nx-dev/nx-dev/public/sitemap-0.xml
+/nx-dev/nx-dev/public/sitemap.xml
+
+# Banner JSON files are generated during static builds
+/nx-dev/nx-dev/lib/banner.json
+/astro-docs/src/content/banner.json
+**/tests/temp-db*
 
 # Issues scraper creates these files, stored by github's cache
 /scripts/issues-scraper/cached
@@ -63,10 +70,11 @@ out
 .rustup/
 target
 .flattened-pom.xml
+dependency-reduced-pom.xml
 *.wasm
 /wasi-sdk*
 
-vite.config.*.timestamp*
+*.config.timestamp*
 
 storybook-static
 
@@ -75,10 +83,10 @@ storybook-static
 .kotlin
 
 .claude/settings.local.json
+.claude/scheduled_tasks.lock
+CLAUDE.local.md
 
-.cursor/rules/nx-rules.mdc
 .cursor/mcp.json
-.github/instructions/nx.instructions.md
 
 # Added by Claude Task Master
 # Logs
@@ -110,7 +118,8 @@ node_modules/
 # Upstream docs local configuration (machine-specific)
 .upstreamdocs.local.json
 
-astro-docs/.netlify
+# Netlify build artifacts
+.netlify
 
 coverage
 
@@ -123,6 +132,7 @@ packages/angular-rspack/README.md
 packages/angular-rspack-compiler/README.md
 packages/dotnet/README.md
 packages/maven/README.md
+packages/nx/README.md
 
 test-output
 test-results
@@ -133,3 +143,15 @@ test-results
 # .NET build output
 /packages/dotnet/analyzer/bin
 /packages/dotnet/analyzer/obj
+/*.deb
+.nx/polygraph
+.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
+e2e/**/*.d.ts
+e2e/**/*.d.ts.map

.local.env

@@ -0,0 +1 @@
+NX_USE_V8_SERIALIZER=false

.mcp.json

@@ -1,9 +0,0 @@
-{
-  "mcpServers": {
-    "nx-mcp": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["nx", "mcp"]
-    }
-  }
-}

.mvn/wrapper/maven-wrapper.properties

@@ -1,3 +1,3 @@
 wrapperVersion=3.3.4
 distributionType=only-script
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/4.0.0-rc-5/apache-maven-4.0.0-rc-5-bin.zip

.nx/nx-mcp-config.json

@@ -0,0 +1,3 @@
+{
+  "experimentalPolygraph": true
+}

.nx/workflows/agents.yaml

@@ -1,184 +1,85 @@
+common-env-vars: &common-env-vars
+  GIT_AUTHOR_EMAIL: test@test.com
+  GIT_AUTHOR_NAME: Test
+  GIT_COMMITTER_EMAIL: test@test.com
+  GIT_COMMITTER_NAME: Test
+  SELECTED_PM: 'pnpm'
+  NX_NATIVE_LOGGING: 'nx::native::db'
+  # 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'
+
+common-init-steps: &common-init-steps
+  - name: Checkout
+    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
+
+  - name: Cache restore
+    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
+    inputs:
+      key: 'pnpm-lock.yaml'
+      paths: ~/.local/share/pnpm/store
+      base-branch: 'master'
+
+  # reads mise.toml and installs toolchains needed for repo
+  - name: Setup toolchains
+    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-mise/main.yaml'
+
+  - name: Verify toolchain versions
+    script: |
+      echo "mise:   $(mise --version)"
+      echo "node:   $(node --version)"
+      echo "pnpm:   $(pnpm --version)"
+      echo "bun:    $(bun --version)"
+      echo "rust:   $(rustc --version) - $(cargo --version)"
+      echo "dotnet: $(dotnet --version)"
+      echo "java:   $(javac --version)"
+
+  - name: Install system deps
+    script: |
+      # archive.ubuntu.com periodically serves a Packages.gz that doesn't
+      # match its own InRelease metadata while the canonical mirror is
+      # mid-sync, breaking apt-get update across all agents at once.
+      # Azure's mirror has a better SLA and is what GitHub Actions runners use.
+      sudo sed -i 's|http://archive.ubuntu.com/ubuntu|http://azure.archive.ubuntu.com/ubuntu|g; s|http://security.ubuntu.com/ubuntu|http://azure.archive.ubuntu.com/ubuntu|g' /etc/apt/sources.list
+      sudo apt-get update
+      sudo apt-get install -y ca-certificates lsof libvips-dev libglib2.0-dev libgirepository1.0-dev zip unzip
+
+  - name: Pnpm Install from lockfile
+    script: |
+      pnpm install --frozen-lockfile
+
+  - name: Install browsers
+    script: |
+      pnpm exec cypress install
+      pnpm exec playwright install --with-deps
+
+  - name: Install rust deps
+    script: |
+      cargo fetch
+
+  - name: Install hyperfine
+    script: |
+      cargo install hyperfine
+
+  - name: Setup gradle
+    script: |
+      ./gradlew wrapper
+      ./gradlew --version
+
+  - name: Configure git metadata (needed for lerna smoke tests)
+    script: |
+      git config --global user.email test@test.com
+      git config --global user.name "Test Test"
+
 launch-templates:
   linux-large:
     resource-class: 'docker_linux_amd64/large'
     image: 'us-east1-docker.pkg.dev/nxcloudoperations/nx-cloud/nx-agents-base-images:ubuntu22.04-node20.19-v1'
-    env:
-      GIT_AUTHOR_EMAIL: test@test.com
-      GIT_AUTHOR_NAME: Test
-      GIT_COMMITTER_EMAIL: test@test.com
-      GIT_COMMITTER_NAME: Test
-      SELECTED_PM: 'pnpm'
-      NX_NATIVE_LOGGING: 'nx::native::db'
-      # 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'
-    init-steps:
-      - name: Checkout
-        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
-
-      - name: Check Node Version
-        script: node --version
-
-      - name: Cache restore
-        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
-        inputs:
-          key: 'pnpm-lock.yaml'
-          paths: .pnpm-store
-          base-branch: 'master'
-
-      - name: Install zip and unzip
-        script: sudo apt-get -yqq install zip unzip
-
-      - name: Install bun
-        script: |
-          curl -fsSL https://bun.sh/install | bash
-          echo "BUN_INSTALL=$HOME/.bun" >> $NX_CLOUD_ENV
-          echo "PATH=$HOME/.bun/bin:$PATH" >> $NX_CLOUD_ENV
-
-      - name: Check bun
-        script: |
-          bun --version
-
-      - name: Install e2e deps
-        script: |
-          sudo apt-get update
-          sudo apt-get install -y ca-certificates lsof libvips-dev libglib2.0-dev libgirepository1.0-dev
-
-      - name: Pnpm Install from lockfile
-        script: |
-          pnpm install --frozen-lockfile
-
-      - name: Install Browsers
-        script: |
-          pnpm exec cypress install
-          pnpm exec playwright install --with-deps
-
-      - name: Install Rust
-        script: |
-          curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y
-          source "$HOME/.cargo/env"
-          rustup toolchain install 1.70.0
-
-      - name: Configure git metadata (needed for lerna smoke tests)
-        script: |
-          git config --global user.email test@test.com
-          git config --global user.name "Test Test"
-
-      - name: Load Cargo Env
-        script: echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV
-
-      - name: Install Rust Dependencies
-        script: |
-          cargo fetch
-
-      - name: Setup Java 21
-        script: |
-          sudo apt update
-          sudo apt install -y openjdk-21-jdk
-          sudo update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java
-          java -version
-
-      - name: Setup Gradle
-        script: |
-          ./gradlew wrapper
-          ./gradlew --version
-
-      - name: Setup .NET 9
-        script: |
-          wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
-          sudo dpkg -i packages-microsoft-prod.deb
-          sudo apt-get update
-          sudo apt-get install -y dotnet-sdk-9.0
-          dotnet --version
+    env: *common-env-vars
+    init-steps: *common-init-steps
 
   linux-extra-large:
     resource-class: 'docker_linux_amd64/extra_large'
     image: 'us-east1-docker.pkg.dev/nxcloudoperations/nx-cloud/nx-agents-base-images:ubuntu22.04-node20.19-v1'
-    env:
-      GIT_AUTHOR_EMAIL: test@test.com
-      GIT_AUTHOR_NAME: Test
-      GIT_COMMITTER_EMAIL: test@test.com
-      GIT_COMMITTER_NAME: Test
-      SELECTED_PM: 'pnpm'
-      NX_NATIVE_LOGGING: 'nx::native::db'
-      # 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'
-    init-steps:
-      - name: Checkout
-        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
-
-      - name: Check Node Version
-        script: node --version
-
-      - name: Cache restore
-        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
-        inputs:
-          key: 'pnpm-lock.yaml'
-          paths: .pnpm-store
-          base-branch: 'master'
-
-      - name: Install zip and unzip
-        script: sudo apt-get -yqq install zip unzip
-
-      - name: Install bun
-        script: |
-          curl -fsSL https://bun.sh/install | bash
-          echo "BUN_INSTALL=$HOME/.bun" >> $NX_CLOUD_ENV
-          echo "PATH=$HOME/.bun/bin:$PATH" >> $NX_CLOUD_ENV
-
-      - name: Check bun
-        script: |
-          bun --version
-
-      - name: Install e2e deps
-        script: |
-          sudo apt-get update
-          sudo apt-get install -y ca-certificates lsof libvips-dev libglib2.0-dev libgirepository1.0-dev
-
-      - name: Pnpm Install from lockfile
-        script: |
-          pnpm install --frozen-lockfile
-
-      - name: Install Browsers
-        script: |
-          pnpm exec cypress install
-          pnpm exec playwright install --with-deps
-
-      - name: Install Rust
-        script: |
-          curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y
-          source "$HOME/.cargo/env"
-          rustup toolchain install 1.70.0
-
-      - name: Configure git metadata (needed for lerna smoke tests)
-        script: |
-          git config --global user.email test@test.com
-          git config --global user.name "Test Test"
-
-      - name: Load Cargo Env
-        script: echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV
-
-      - name: Install Rust Dependencies
-        script: |
-          cargo fetch
-
-      - name: Setup Java 21
-        script: |
-          sudo apt update
-          sudo apt install -y openjdk-21-jdk
-          sudo update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java
-          java -version
-
-      - name: Setup Gradle
-        script: |
-          ./gradlew wrapper
-          ./gradlew --version
-
-      - name: Setup .NET 9
-        script: |
-          wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
-          sudo dpkg -i packages-microsoft-prod.deb
-          sudo apt-get update
-          sudo apt-get install -y dotnet-sdk-9.0
-          dotnet --version
+    env: *common-env-vars
+    init-steps: *common-init-steps

.nx/workflows/dynamic-changesets.yaml

@@ -1,28 +1,70 @@
 distribute-on:
-  default: auto linux-large, 3 linux-extra-large
+  extra-small-changeset: 6 linux-large, 3 linux-extra-large
+  small-changeset: 6 linux-large, 4 linux-extra-large
+  medium-changeset: 6 linux-large, 5 linux-extra-large
+  large-changeset: 6 linux-large, 6 linux-extra-large
+  extra-large-changeset: 8 linux-large, 8 linux-extra-large
 assignment-rules:
   - projects:
       - e2e-gradle
-      - e2e-release
-      - e2e-angular
-      - e2e-react
+    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
+      - remix
+      - nx-maven-plugin
+    targets:
+      - install
+      - test
+    run-on:
+      - agent: linux-large
+        parallelism: 1
+      - 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
-      - nx-maven-plugin
+      - e2e-dotnet
+      - e2e-workspace-create
+      - e2e-rollup
     targets:
       - e2e-ci**
-      - install
     run-on:
       - agent: linux-large
         parallelism: 1
       - agent: linux-extra-large
-        parallelism: 1
+        parallelism: 2
 
   # All other e2e tests can run in parallel
   - targets:
@@ -33,9 +75,16 @@ assignment-rules:
       - agent: linux-extra-large
         parallelism: 3
 
+  - targets:
+      - bench:*
+    run-on:
+      - agent: linux-large
+        parallelism: 1
+
   # These projects should not need to be isolated.
   - projects:
       - nx-dev
+      - astro-docs
     targets:
       - build*
     run-on:
@@ -58,6 +107,15 @@ assignment-rules:
       - agent: linux-extra-large
         parallelism: 6
 
+  # TODO(altan): remove when scheduling issue resolved
+  - projects:
+      - nx-dev
+    targets:
+      - prebuild-banner
+    run-on:
+      - agent: linux-extra-large
+        parallelism: 6
+
   - targets:
       - "*"
     run-on:

.nx/workflows/sandboxing-config.yaml

@@ -0,0 +1,21 @@
+exclude-reads:
+  - packages/nx/src/native/*.node
+  - 'dist/target/**'
+exclude-writes:
+  - '**/.swc/**'
+  - 'dist/target/**'
+
+task-exclusions:
+  - target: lint
+    exclude-reads:
+      - '**/dist/**/*.json'
+  # TODO: populate-local-registry-storage is doing too much — it reads all build
+  # outputs and writes version-bumped packages across the entire workspace during
+  # nx-release. We're reworking this task to have more focused I/O and will fix
+  # the inputs/outputs properly after that.
+  - project: '@nx/nx-source'
+    target: populate-local-registry-storage
+    exclude-reads:
+      - '**'
+    exclude-writes:
+      - '**'

.nxignore

@@ -1,3 +1,4 @@
+benchmarks/packages
 nx-dev/**/jest.config.js
 .next
 _files

.opencode/agents/ci-watcher.md

@@ -0,0 +1,479 @@
+---
+description: Polls Nx Cloud CI pipeline and self-healing status. Returns structured state when actionable. Spawned by /nx-cloud-ci-monitor command to monitor CI Attempt status.
+mode: subagent
+---
+
+# CI Watcher Subagent
+
+You are a CI monitoring subagent responsible for polling Nx Cloud CI Attempt status and self-healing state. You report status back to the main agent - you do NOT make apply/reject decisions.
+
+## Your Responsibilities
+
+1. Poll CI status using the `ci_information` MCP tool
+2. Implement exponential backoff between polls
+3. Return structured state when an actionable condition is reached
+4. Track iteration count and elapsed time
+5. Output status updates based on verbosity level
+
+## Input Parameters (from Main Agent)
+
+The main agent may provide these optional parameters in the prompt:
+
+| Parameter           | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `branch`            | Branch to monitor (auto-detected if not provided)        |
+| `expectedCommitSha` | Commit SHA that should trigger a new CI Attempt          |
+| `previousCipeUrl`   | CI Attempt URL before the action (to detect change)      |
+| `subagentTimeout`   | Polling timeout in minutes (default: 60)                 |
+| `verbosity`         | Output level: minimal, medium, verbose (default: medium) |
+
+When `expectedCommitSha` or `previousCipeUrl` is provided, you must detect whether a new CI Attempt has spawned.
+
+## MCP Tool Reference
+
+### `ci_information`
+
+**Input:**
+
+```json
+{
+  "branch": "string (optional, defaults to current git branch)",
+  "select": "string (optional, comma-separated field names)",
+  "pageToken": "number (optional, 0-based pagination for long strings)"
+}
+```
+
+**Output:**
+
+```json
+{
+  "cipeStatus": "NOT_STARTED | IN_PROGRESS | SUCCEEDED | FAILED | CANCELED | TIMED_OUT",
+  "cipeUrl": "string",
+  "branch": "string",
+  "commitSha": "string | null",
+  "failedTaskIds": "string[]",
+  "verifiedTaskIds": "string[]",
+  "selfHealingEnabled": "boolean",
+  "selfHealingStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null",
+  "verificationStatus": "NOT_STARTED | IN_PROGRESS | COMPLETED | FAILED | NOT_EXECUTABLE | null",
+  "userAction": "NONE | APPLIED | REJECTED | APPLIED_LOCALLY | APPLIED_AUTOMATICALLY | null",
+  "failureClassification": "string | null",
+  "taskOutputSummary": "string | null",
+  "suggestedFixReasoning": "string | null",
+  "suggestedFixDescription": "string | null",
+  "suggestedFix": "string | null",
+  "shortLink": "string | null",
+  "couldAutoApplyTasks": "boolean | null",
+  "confidence": "number | null",
+  "confidenceReasoning": "string | null"
+}
+```
+
+**Select Parameter:**
+
+| Usage           | Returns                                                     |
+| --------------- | ----------------------------------------------------------- |
+| No `select`     | Formatted overview (truncated, not recommended for polling) |
+| Single field    | Raw value with pagination for long strings                  |
+| Multiple fields | Object with requested field values                          |
+
+**Field Sets for Efficient Polling:**
+
+```yaml
+WAIT_FIELDS:
+  'cipeUrl,commitSha,cipeStatus'
+  # Minimal fields for detecting new CI Attempt
+
+LIGHT_FIELDS:
+  'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning'
+  # Status fields for determining actionable state
+
+HEAVY_FIELDS:
+  'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription'
+  # Large content fields - fetch only when returning to main agent
+```
+
+## Initial Wait
+
+Before first poll, wait based on context:
+
+- **Fresh start (no expected CIPE):** Wait 60 seconds to allow CI to start
+- **Expecting new CIPE:** Wait 30 seconds (action already triggered)
+
+**IMPORTANT:** Always run sleep in foreground, NOT as background command.
+
+```bash
+sleep 60  # or 30 if expecting new CIPE (FOREGROUND, not background)
+```
+
+## Two-Phase Operation
+
+The subagent operates in one of two modes depending on input:
+
+### Mode 1: Fresh Start (no `expectedCommitSha` or `previousCipeUrl`)
+
+Normal polling - process whatever CIPE is returned by `ci_information`.
+
+### Mode 2: Wait-for-New-CIPE (when `expectedCommitSha` or `previousCipeUrl` provided)
+
+**CRITICAL**: When expecting a new CIPE, the subagent must **completely ignore** the old/stale CIPE. Do NOT process its status, do NOT return actionable states based on it.
+
+#### Phase A: Wait Mode
+
+1. Start a **new-CIPE timeout** timer (default: 30 minutes)
+2. On each poll of `ci_information`:
+   - Check if CIPE is NEW:
+     - `cipeUrl` differs from `previousCipeUrl` → **new CIPE detected**
+     - `commitSha` matches `expectedCommitSha` → **correct CIPE detected**
+   - If still OLD CIPE: **ignore all status fields**, just wait and poll again
+   - Do NOT return `fix_available`, `ci_success`, etc. based on old CIPE!
+3. Output wait status (see below)
+4. If timeout (30 min) reached → return `no_new_cipe`
+
+#### Phase B: Normal Polling (after new CIPE detected)
+
+Once new CIPE is detected:
+
+1. Clear the new-CIPE timeout
+2. Switch to normal polling mode
+3. Process the NEW CIPE's status normally
+4. Return when actionable state reached
+
+### Wait Mode Output
+
+While in wait mode, output clearly that you're waiting (not processing):
+
+```
+[CI Monitor] ═══════════════════════════════════════════════════════
+[CI Monitor] WAIT MODE - Expecting new CI Attempt
+[CI Monitor] Expected SHA: <expectedCommitSha>
+[CI Monitor] Previous CI Attempt: <previousCipeUrl>
+[CI Monitor] ═══════════════════════════════════════════════════════
+
+[CI Monitor] Polling... (elapsed: 0m 30s)
+[CI Monitor] Still seeing previous CI Attempt (ignoring): <oldCipeUrl>
+
+[CI Monitor] Polling... (elapsed: 1m 30s)
+[CI Monitor] Still seeing previous CI Attempt (ignoring): <oldCipeUrl>
+
+[CI Monitor] Polling... (elapsed: 2m 30s)
+[CI Monitor] ✓ New CI Attempt detected! URL: <newCipeUrl>, SHA: <newCommitSha>
+[CI Monitor] Switching to normal polling mode...
+```
+
+### Why This Matters (Context Preservation)
+
+**The problem**: Stale CIPE data can be very large:
+
+- `taskOutputSummary`: potentially thousands of characters of build/test output
+- `suggestedFix`: entire patch files
+- `suggestedFixReasoning`: detailed explanation
+
+If subagent returns stale CIPE data to main agent, it **pollutes main agent's context** with useless information (we already processed that CIPE). This wastes valuable context window.
+
+**Without wait mode:**
+
+1. Poll `ci_information` → get old CIPE with huge data
+2. Return to main agent with all that stale data
+3. Main agent's context gets polluted with useless info
+4. Main agent has to process/ignore it anyway
+
+**With wait mode:**
+
+1. Poll `ci_information` → get old CIPE → **ignore it, don't return**
+2. Keep waiting internally (stale data stays in subagent)
+3. New CIPE appears → switch to normal mode
+4. Return to main agent with only the NEW, relevant CIPE data
+
+## Polling Loop
+
+### Subagent State Management
+
+Maintain internal accumulated state across polls:
+
+```
+accumulated_state = {}
+```
+
+### Call `ci_information` MCP Tool
+
+**Wait Mode (expecting new CI Attempt):**
+
+```
+ci_information({
+  branch: "<branch_name>",
+  select: "cipeUrl,commitSha,cipeStatus"
+})
+```
+
+Only fetch minimal fields needed to detect CI Attempt change. Do NOT fetch heavy fields - stale data wastes context.
+
+**Normal Mode (processing CI Attempt):**
+
+```
+ci_information({
+  branch: "<branch_name>",
+  select: "cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning"
+})
+```
+
+Merge response into `accumulated_state` after each poll.
+
+### Analyze Response
+
+**If in Wait Mode** (expecting new CIPE):
+
+1. Check if CIPE is new (see Two-Phase Operation above)
+2. If old CIPE → **ignore status**, output wait message, poll again
+3. If new CIPE → switch to normal mode, continue below
+
+**If in Normal Mode**:
+Based on the response, decide whether to **keep polling** or **return to main agent**.
+
+### Keep Polling When
+
+Continue polling (with backoff) if ANY of these conditions are true:
+
+| Condition                               | Reason                                   |
+| --------------------------------------- | ---------------------------------------- |
+| `cipeStatus == 'IN_PROGRESS'`           | CI still running                         |
+| `cipeStatus == 'NOT_STARTED'`           | CI hasn't started yet                    |
+| `selfHealingStatus == 'IN_PROGRESS'`    | Self-healing agent working               |
+| `selfHealingStatus == 'NOT_STARTED'`    | Self-healing not started yet             |
+| `failureClassification == 'FLAKY_TASK'` | Auto-rerun in progress                   |
+| `userAction == 'APPLIED_AUTOMATICALLY'` | New CI Attempt spawning after auto-apply |
+
+When `couldAutoApplyTasks == true`:
+
+- `verificationStatus` = `NOT_STARTED`, `IN_PROGRESS` → keep polling (verification still in progress)
+- `verificationStatus` = `COMPLETED` → return `fix_auto_applying` (auto-apply will happen, main agent spawns wait mode subagent)
+- `verificationStatus` = `FAILED`, `NOT_EXECUTABLE` → return `fix_available` (auto-apply won't happen, needs manual action)
+
+### Exponential Backoff
+
+Between polls, wait with exponential backoff:
+
+| Poll Attempt | Wait Time         |
+| ------------ | ----------------- |
+| 1st          | 60 seconds        |
+| 2nd          | 90 seconds        |
+| 3rd+         | 120 seconds (cap) |
+
+Reset to 60 seconds when state changes significantly.
+
+**IMPORTANT:** Run sleep in foreground (NOT as background command). Background sleep causes "What should Claude do?" prompts when completed.
+
+```bash
+# Example backoff - run in FOREGROUND
+sleep 60   # First wait
+sleep 90   # Second wait
+sleep 120  # Third and subsequent waits (capped)
+```
+
+### Fetch Heavy Fields on Actionable State
+
+Before returning to main agent, fetch heavy fields if the status requires them:
+
+| Status              | Heavy Fields Needed                                                            |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `ci_success`        | None                                                                           |
+| `fix_auto_applying` | None                                                                           |
+| `fix_available`     | `taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription` |
+| `fix_failed`        | `taskOutputSummary`                                                            |
+| `no_fix`            | `taskOutputSummary`                                                            |
+| `environment_issue` | None                                                                           |
+| `no_new_cipe`       | None                                                                           |
+| `polling_timeout`   | None                                                                           |
+| `cipe_canceled`     | None                                                                           |
+| `cipe_timed_out`    | None                                                                           |
+
+```
+# Example: fetching heavy fields for fix_available
+ci_information({
+  branch: "<branch_name>",
+  select: "taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription"
+})
+```
+
+Merge response into `accumulated_state`, then return merged state to main agent.
+
+**Pagination:** Heavy string fields return first page only. If `hasMore` indicated, include in return format so main agent knows more content available.
+
+### Return to Main Agent When
+
+Return immediately with structured state if ANY of these conditions are true:
+
+| Status              | Condition                                                                                                                                                 |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | `cipeStatus == 'SUCCEEDED'`                                                                                                                               |
+| `fix_auto_applying` | `selfHealingStatus == 'COMPLETED'` AND `couldAutoApplyTasks == true` AND `verificationStatus == 'COMPLETED'`                                              |
+| `fix_available`     | `selfHealingStatus == 'COMPLETED'` AND `suggestedFix != null` AND (`couldAutoApplyTasks != true` OR `verificationStatus` in (`FAILED`, `NOT_EXECUTABLE`)) |
+| `fix_failed`        | `selfHealingStatus == 'FAILED'`                                                                                                                           |
+| `environment_issue` | `failureClassification == 'ENVIRONMENT_STATE'`                                                                                                            |
+| `no_fix`            | `cipeStatus == 'FAILED'` AND (`selfHealingEnabled == false` OR `selfHealingStatus == 'NOT_EXECUTABLE'`)                                                   |
+| `no_new_cipe`       | `expectedCommitSha` or `previousCipeUrl` provided, but no new CI Attempt detected after 30 min                                                            |
+| `polling_timeout`   | Subagent has been polling for > configured timeout (default 60 min)                                                                                       |
+| `cipe_canceled`     | `cipeStatus == 'CANCELED'`                                                                                                                                |
+| `cipe_timed_out`    | `cipeStatus == 'TIMED_OUT'`                                                                                                                               |
+
+## Subagent Timeout
+
+Track elapsed time. If you have been polling for more than **60 minutes** (configurable via main agent), return with `status: polling_timeout`.
+
+## Return Format
+
+When returning to the main agent, provide a structured response with accumulated state:
+
+```
+## CI Monitor Result
+
+**Status:** <status>
+**Iterations:** <count>
+**Elapsed:** <minutes>m <seconds>s
+
+### CI Attempt Details
+- **Status:** <cipeStatus>
+- **URL:** <cipeUrl>
+- **Branch:** <branch>
+- **Commit:** <commitSha>
+- **Failed Tasks:** <failedTaskIds>
+- **Verified Tasks:** <verifiedTaskIds>
+
+### Self-Healing Details
+- **Enabled:** <selfHealingEnabled>
+- **Status:** <selfHealingStatus>
+- **Verification:** <verificationStatus>
+- **User Action:** <userAction>
+- **Classification:** <failureClassification>
+- **Confidence:** <confidence>
+- **Confidence Reasoning:** <confidenceReasoning>
+
+### Fix Information (if available)
+- **Short Link:** <shortLink>
+- **Description:** <suggestedFixDescription>
+- **Reasoning:** <suggestedFixReasoning>
+
+### Task Output Summary (first page)
+<taskOutputSummary>
+[MORE_CONTENT_AVAILABLE: taskOutputSummary, pageToken: 1]
+
+### Suggested Fix (first page)
+<suggestedFix>
+[MORE_CONTENT_AVAILABLE: suggestedFix, pageToken: 1]
+```
+
+### Pagination Indicators
+
+When a heavy field has more content available, append indicator:
+
+```
+[MORE_CONTENT_AVAILABLE: <fieldName>, pageToken: <nextPage>]
+```
+
+Main agent can fetch additional pages if needed using:
+
+```
+ci_information({ select: "<fieldName>", pageToken: <nextPage> })
+```
+
+Fields that may have pagination:
+
+- `taskOutputSummary` (reverse pagination - page 0 = most recent)
+- `suggestedFix` (forward pagination - page 0 = start)
+- `suggestedFixReasoning`
+
+### Return Format for `no_new_cipe`
+
+When returning with `status: no_new_cipe`, include additional context:
+
+```
+## CI Monitor Result
+
+**Status:** no_new_cipe
+**Iterations:** <count>
+**Elapsed:** <minutes>m <seconds>s
+
+### Expected CI Attempt Not Found
+- **Expected Commit SHA:** <expectedCommitSha>
+- **Previous CI Attempt URL:** <previousCipeUrl>
+- **Last Seen CI Attempt URL:** <cipeUrl>
+- **Last Seen Commit SHA:** <commitSha>
+- **New CI Attempt Timeout:** 30 minutes (exceeded)
+
+### Likely Cause
+CI workflow failed before Nx tasks could run (e.g., install step, checkout, auth).
+Check your CI provider logs for the commit <expectedCommitSha>.
+
+### Last Known CI Attempt State
+- **Status:** <cipeStatus>
+- **Branch:** <branch>
+```
+
+## Status Reporting (Verbosity-Controlled)
+
+Output is controlled by the `verbosity` parameter from the main agent:
+
+| Level     | What to Output                                                    |
+| --------- | ----------------------------------------------------------------- |
+| `minimal` | No intermediate output. Only return final result when actionable. |
+| `medium`  | Output only on significant state changes (not every poll).        |
+| `verbose` | Output detailed phase information after every poll.               |
+
+### Minimal Verbosity
+
+No output during polling. Poll silently and return when done.
+
+### Medium Verbosity (Default)
+
+Output **only when state changes significantly** to save context tokens:
+
+- `cipeStatus` changes (e.g., IN_PROGRESS → FAILED)
+- `selfHealingStatus` changes (e.g., IN_PROGRESS → COMPLETED)
+- New CI Attempt detected (in wait mode)
+
+Format: single line, no decorators:
+
+```
+[CI Monitor] CI: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 4m
+```
+
+### Verbose Verbosity
+
+Output detailed phase box after every poll:
+
+```
+[CI Monitor] ─────────────────────────────────────────────────────
+[CI Monitor] Iteration <N> | Elapsed: <X>m <Y>s
+[CI Monitor]
+[CI Monitor] CI Status:          <cipeStatus>
+[CI Monitor] Self-Healing:       <selfHealingStatus>
+[CI Monitor] Verification:       <verificationStatus>
+[CI Monitor] Classification:     <failureClassification>
+[CI Monitor]
+[CI Monitor] → <human-readable phase description>
+[CI Monitor] ─────────────────────────────────────────────────────
+```
+
+### Phase Descriptions (for verbose output)
+
+| Status Combo                                                                              | Description                                 |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `cipeStatus: IN_PROGRESS`                                                                 | "CI running..."                             |
+| `cipeStatus: NOT_STARTED`                                                                 | "Waiting for CI to start..."                |
+| `cipeStatus: FAILED` + `selfHealingStatus: NOT_STARTED`                                   | "CI failed. Self-healing starting..."       |
+| `cipeStatus: FAILED` + `selfHealingStatus: IN_PROGRESS`                                   | "CI failed. Self-healing generating fix..." |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: IN_PROGRESS` | "Fix generated! Verification running..."    |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: COMPLETED`   | "Fix ready! Verified successfully."         |
+| `cipeStatus: FAILED` + `selfHealingStatus: COMPLETED` + `verificationStatus: FAILED`      | "Fix generated but verification failed."    |
+| `cipeStatus: FAILED` + `selfHealingStatus: FAILED`                                        | "Self-healing could not generate a fix."    |
+| `cipeStatus: SUCCEEDED`                                                                   | "CI passed!"                                |
+
+## Important Notes
+
+- You do NOT make apply/reject decisions - that's the main agent's job
+- You do NOT perform git operations
+- You only poll and report state
+- Respect the `verbosity` parameter for output (default: medium)
+- If `ci_information` returns an error, wait and retry (count as failed poll)
+- Track consecutive failures - if 5 consecutive failures, return with `status: error`
+- When expecting new CI Attempt, track the 30-minute new-CI-Attempt timeout separately from the main polling timeout

.opencode/commands/ci-monitor.md

@@ -0,0 +1,437 @@
+---
+description: Monitor Nx Cloud CI pipeline and handle self-healing fixes automatically. Checks for Nx Cloud connection before starting.
+argument-hint: '[instructions] [--max-cycles N] [--timeout MINUTES] [--verbosity minimal|medium|verbose] [--branch BRANCH] [--fresh] [--auto-fix-workflow] [--new-cipe-timeout MINUTES]'
+---
+
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+$ARGUMENTS
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+Parse any overrides from `$ARGUMENTS` and merge with defaults.
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```

.opencode/skills/ci-monitor/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: ci-monitor
+description: Monitor Nx Cloud CI pipeline and handle self-healing fixes automatically. Checks for Nx Cloud connection before starting.
+---
+
+# CI Monitor Command
+
+You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-watcher` subagent to poll CI status and make decisions based on the results.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+- **Remote Status:** !`git status -sb | head -1`
+
+## User Instructions
+
+$ARGUMENTS
+
+**Important:** If user provides specific instructions, respect them over default behaviors described below.
+
+## Configuration Defaults
+
+| Setting                   | Default       | Description                                                         |
+| ------------------------- | ------------- | ------------------------------------------------------------------- |
+| `--max-cycles`            | 10            | Maximum CIPE cycles before timeout                                  |
+| `--timeout`               | 120           | Maximum duration in minutes                                         |
+| `--verbosity`             | medium        | Output level: minimal, medium, verbose                              |
+| `--branch`                | (auto-detect) | Branch to monitor                                                   |
+| `--subagent-timeout`      | 60            | Subagent polling timeout in minutes                                 |
+| `--fresh`                 | false         | Ignore previous context, start fresh                                |
+| `--auto-fix-workflow`     | false         | Attempt common fixes for pre-CIPE failures (e.g., lockfile updates) |
+| `--new-cipe-timeout`      | 10            | Minutes to wait for new CIPE after action                           |
+| `--local-verify-attempts` | 3             | Max local verification + enhance cycles before pushing to CI        |
+
+Parse any overrides from `$ARGUMENTS` and merge with defaults.
+
+## Nx Cloud Connection Check
+
+**CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud.
+
+### Step 0: Verify Nx Cloud Connection
+
+1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken`
+2. **If `nx.json` missing OR neither property exists** → exit with:
+   ```
+   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
+   ```
+3. **If connected** → continue to main loop
+
+## Session Context Behavior
+
+**Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/ci-monitor`, Claude remembers the previous state and may continue from where it left off.
+
+- **To continue monitoring:** Just re-run `/ci-monitor` (context is preserved)
+- **To start fresh:** Use `/ci-monitor --fresh` to ignore previous context
+- **For a completely clean slate:** Exit Claude Code and restart `claude`
+
+## Default Behaviors by Status
+
+The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these.
+
+| Status              | Default Behavior                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_success`        | Exit with success. Log "CI passed successfully!"                                                                                                                  |
+| `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CIPE.                          |
+| `fix_available`     | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below.                                 |
+| `fix_failed`        | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure.              |
+| `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CIPE spawns automatically. Loop to poll for new CIPE. |
+| `no_fix`            | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure.                                |
+| `no_new_cipe`       | Expected CIPE never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance.               |
+| `polling_timeout`   | Subagent polling timeout reached. Exit with timeout.                                                                                                              |
+| `cipe_canceled`     | CIPE was canceled. Exit with canceled status.                                                                                                                     |
+| `cipe_timed_out`    | CIPE timed out. Exit with timeout status.                                                                                                                         |
+| `error`             | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop.                                                                  |
+
+### Fix Available Decision Logic
+
+When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`:
+
+#### Step 1: Categorize Tasks
+
+1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds`
+2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds`
+3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`)
+4. **Verifiable tasks** = unverified tasks that are NOT e2e
+
+#### Step 2: Determine Path
+
+| Condition                               | Path                                     |
+| --------------------------------------- | ---------------------------------------- |
+| No unverified tasks (all verified)      | Apply via MCP                            |
+| Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) |
+| Verifiable tasks exist                  | Local verification flow                  |
+
+#### Step 3a: Apply via MCP (fully/e2e-only verified)
+
+- Call `update_self_healing_fix({ shortLink, action: "APPLY" })`
+- Record `last_cipe_url`, spawn subagent in wait mode
+
+#### Step 3b: Local Verification Flow
+
+When verifiable (non-e2e) unverified tasks exist:
+
+1. **Detect package manager:**
+   - `pnpm-lock.yaml` exists → `pnpm nx`
+   - `yarn.lock` exists → `yarn nx`
+   - Otherwise → `npx nx`
+
+2. **Run verifiable tasks in parallel:**
+   - Spawn `general` subagents to run each task concurrently
+   - Each subagent runs: `<pm> nx run <taskId>`
+   - Collect pass/fail results from all subagents
+
+3. **Evaluate results:**
+
+| Result                    | Action                       |
+| ------------------------- | ---------------------------- |
+| ALL verifiable tasks pass | Apply via MCP                |
+| ANY verifiable task fails | Apply-locally + enhance flow |
+
+4. **Apply-locally + enhance flow:**
+   - Run `nx apply-locally <shortLink>`
+   - Enhance the code to fix failing tasks
+   - Run failing tasks again to verify fix
+   - If still failing → increment `local_verify_count`, loop back to enhance
+   - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode
+
+5. **Track attempts** (wraps step 4):
+   - Increment `local_verify_count` after each enhance cycle
+   - If `local_verify_count >= local_verify_attempts` (default: 3):
+     - Get code in commit-able state
+     - Commit and push with message indicating local verification failed
+     - Report to user:
+       ```
+       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
+       ```
+     - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge)
+
+#### Commit Message Format
+
+```bash
+git commit -m "fix(<projects>): <brief description>
+
+Failed tasks: <taskId1>, <taskId2>
+Local verification: passed|enhanced|failed-pushing-to-ci"
+```
+
+### Unverified Fix Flow (No Verification Attempted)
+
+When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification:
+
+- Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`)
+- If fix looks correct → apply via MCP
+- If fix needs enhancement → use Apply Locally + Enhance Flow above
+- If fix is wrong → reject via MCP, fix from scratch, commit, push
+
+### Auto-Apply Eligibility
+
+The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application:
+
+- **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails.
+- **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject)
+
+**Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode.
+
+### Apply vs Reject vs Apply Locally
+
+- **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CIPE spawns automatically. No local git operations needed.
+- **Apply Locally**: Runs `nx apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing.
+- **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch.
+
+### Apply Locally + Enhance Flow
+
+When the fix needs enhancement (use `nx apply-locally`, NOT reject):
+
+1. Apply the patch locally: `nx apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`)
+2. Make additional changes as needed
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Reject + Fix From Scratch Flow
+
+When the fix is completely wrong:
+
+1. Call MCP to reject: `update_self_healing_fix({ shortLink, action: "REJECT" })`
+2. Fix the issue from scratch locally
+3. Commit and push:
+   ```bash
+   git add -A
+   git commit -m "fix: resolve <failedTaskIds>"
+   git push origin $(git branch --show-current)
+   ```
+4. Loop to poll for new CIPE
+
+### Environment Issue Handling
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+1. Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`
+2. New CIPE spawns automatically (no local git operations needed)
+3. Loop to poll for new CIPE with `previousCipeUrl` set
+
+### No-New-CIPE Handling
+
+When `status == 'no_new_cipe'`:
+
+This means the expected CIPE was never created - CI likely failed before Nx tasks could run.
+
+1. **Report to user:**
+
+   ```
+   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
+   ```
+
+2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
+   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Run install to update lockfile:
+     ```bash
+     pnpm install   # or npm install / yarn install
+     ```
+   - If lockfile changed:
+     ```bash
+     git add pnpm-lock.yaml  # or appropriate lockfile
+     git commit -m "chore: update lockfile"
+     git push origin $(git branch --show-current)
+     ```
+   - Record new commit SHA, loop to poll with `expectedCommitSha`
+
+3. **Otherwise:** Exit with `no_new_cipe` status, providing guidance for user to investigate
+
+## Exit Conditions
+
+Exit the monitoring loop when ANY of these conditions are met:
+
+| Condition                                   | Exit Type        |
+| ------------------------------------------- | ---------------- |
+| CI passes (`cipeStatus == 'SUCCEEDED'`)     | Success          |
+| Max CIPE cycles reached                     | Timeout          |
+| Max duration reached                        | Timeout          |
+| 3 consecutive no-progress iterations        | Circuit breaker  |
+| No fix available and local fix not possible | Failure          |
+| No new CIPE and auto-fix not configured     | Pre-CIPE failure |
+| User cancels                                | Cancelled        |
+
+## Main Loop
+
+### Step 1: Initialize Tracking
+
+```
+cycle_count = 0
+start_time = now()
+no_progress_count = 0
+local_verify_count = 0
+last_state = null
+last_cipe_url = null
+expected_commit_sha = null
+```
+
+### Step 2: Spawn Subagent
+
+Spawn the `ci-watcher` subagent to poll CI status:
+
+**Fresh start (first spawn, no expected CIPE):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>."
+)
+```
+
+**After action that triggers new CIPE (wait mode):**
+
+```
+Task(
+  agent: "ci-watcher",
+  prompt: "Monitor CI for branch '<branch>'.
+           Subagent timeout: <subagent-timeout> minutes.
+           New-CIPE timeout: <new-cipe-timeout> minutes.
+           Verbosity: <verbosity>.
+
+           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
+           Expected commit SHA: <expected_commit_sha>
+           Previous CIPE URL: <last_cipe_url>"
+)
+```
+
+### Step 3: Handle Subagent Response
+
+When subagent returns:
+
+1. Check the returned status
+2. Look up default behavior in the table above
+3. Check if user instructions override the default
+4. Execute the appropriate action
+5. **If action expects new CIPE**, update tracking (see Step 3a)
+6. If action results in looping, go to Step 2
+
+### Step 3a: Track State for New-CIPE Detection
+
+After actions that should trigger a new CIPE, record state before looping:
+
+| Action                        | What to Track                                 | Subagent Mode |
+| ----------------------------- | --------------------------------------------- | ------------- |
+| Fix auto-applying             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply via MCP                 | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| Apply locally + push          | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Reject + fix + push           | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Fix failed + local fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| No fix + local fix + push     | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+| Environment rerun             | `last_cipe_url = current cipeUrl`             | Wait mode     |
+| No-new-CIPE + auto-fix + push | `expected_commit_sha = $(git rev-parse HEAD)` | Wait mode     |
+
+**CRITICAL**: When passing `expectedCommitSha` or `last_cipe_url` to the subagent, it enters **wait mode**:
+
+- Subagent will **completely ignore** the old/stale CIPE
+- Subagent will only wait for new CIPE to appear
+- Subagent will NOT return to main agent with stale CIPE data
+- Once new CIPE detected, subagent switches to normal polling
+
+**Why wait mode matters for context preservation**: Stale CIPE data can be very large (task output summaries, suggested fix patches, reasoning). If subagent returns this to main agent, it pollutes main agent's context with useless data since we already processed that CIPE. Wait mode keeps stale data in the subagent, never sending it to main agent.
+
+### Step 4: Progress Tracking
+
+After each action:
+
+- If state changed significantly → reset `no_progress_count = 0`
+- If state unchanged → `no_progress_count++`
+- On new CI attempt detected → reset `local_verify_count = 0`
+
+## Status Reporting
+
+Based on verbosity level:
+
+| Level     | What to Report                                                             |
+| --------- | -------------------------------------------------------------------------- |
+| `minimal` | Only final result (success/failure/timeout)                                |
+| `medium`  | State changes + periodic updates ("Cycle N \| Elapsed: Xm \| Status: ...") |
+| `verbose` | All of medium + full subagent responses, git outputs, MCP responses        |
+
+## User Instruction Examples
+
+Users can override default behaviors:
+
+| Instruction                                      | Effect                                        |
+| ------------------------------------------------ | --------------------------------------------- |
+| "never auto-apply"                               | Always prompt before applying any fix         |
+| "always ask before git push"                     | Prompt before each push                       |
+| "reject any fix for e2e tasks"                   | Auto-reject if `failedTaskIds` contains e2e   |
+| "apply all fixes regardless of verification"     | Skip verification check, apply everything     |
+| "if confidence < 70, reject"                     | Check confidence field before applying        |
+| "run 'nx affected -t typecheck' before applying" | Add local verification step                   |
+| "auto-fix workflow failures"                     | Attempt lockfile updates on pre-CIPE failures |
+| "wait 45 min for new CIPE"                       | Override new-CIPE timeout (default: 10 min)   |
+
+## Error Handling
+
+| Error                    | Action                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Git rebase conflict      | Report to user, exit                                                                  |
+| `nx apply-locally` fails | Report to user, attempt manual patch or exit                                          |
+| MCP tool error           | Retry once, if fails report to user                                                   |
+| Subagent spawn failure   | Retry once, if fails exit with error                                                  |
+| No new CIPE detected     | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance |
+| Lockfile auto-fix fails  | Report to user, exit with guidance to check CI logs                                   |
+
+## Example Session
+
+### Example 1: Normal Flow with Self-Healing (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
+[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
+[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m
+
+[ci-monitor] Fix available! Verification: COMPLETED
+[ci-monitor] Applying fix via MCP...
+[ci-monitor] Fix applied in CI. Waiting for new CI attempt...
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 2
+  - Total time: 12m 34s
+  - Fixes applied: 1
+  - Result: SUCCESS
+```
+
+### Example 2: Pre-CI Failure (medium verbosity)
+
+```
+[ci-monitor] Starting CI monitor for branch 'feature/add-products'
+[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m
+
+[ci-monitor] Applying fix locally, enhancing, and pushing...
+[ci-monitor] Committed: abc1234
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
+[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.
+
+[ci-monitor] Status: no_new_cipe
+[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
+[ci-monitor] Lockfile updated. Committed: def5678
+
+[ci-monitor] Spawning subagent to poll CI status...
+[CI Monitor] New CI attempt detected!
+[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m
+
+[ci-monitor] CI passed successfully!
+
+[ci-monitor] Summary:
+  - Total cycles: 3
+  - Total time: 22m 15s
+  - Fixes applied: 1 (self-healing) + 1 (lockfile)
+  - Result: SUCCESS
+```

.opencode/skills/nx-generate/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: nx-generate
+description: Generate code using nx generators. USE WHEN scaffolding code or transforming existing code - for example creating libraries or applications, or anything else that is boilerplate code or automates repetitive tasks. ALWAYS use this first when generating code with Nx instead of calling MCP tools or running nx generate immediately.
+---
+
+# Run Nx Generator
+
+Nx generators are powerful tools that scaffold projects, make automated code migrations or automate repetitive tasks in a monorepo. They ensure consistency across the codebase and reduce boilerplate work.
+
+This skill applies when the user wants to:
+
+- Create new projects like libraries or applications
+- Scaffold features or boilerplate code
+- Run workspace-specific or custom generators
+- Do anything else that an nx generator exists for
+
+## Generator Discovery Flow
+
+### Step 1: List Available Generators
+
+Use the Nx CLI to discover available generators:
+
+- List all generators for a plugin: `npx nx list @nx/react`
+- View available plugins: `npx nx list`
+
+This includes:
+
+- Plugin generators (e.g., `@nx/react:library`, `@nx/js:library`)
+- Local workspace generators (defined in the repo's own plugins)
+
+### Step 2: Match Generator to User Request
+
+Based on the user's request, identify which generator(s) could fulfill their needs. Consider:
+
+- What artifact type they want to create (library, application, etc.)
+- Which framework or technology stack is relevant
+- Whether they mentioned specific generator names
+
+**IMPORTANT**: When both a local workspace generator and an external plugin generator could satisfy the request, **always prefer the local workspace generator**. Local generators are customized for the specific repo's patterns and conventions.
+
+It's possible that the user request is something that no Nx generator exists for whatsoever. In this case, you can stop using this skill and try to help the user another way. HOWEVER, the burden of proof for this is high. Before aborting, carefully consider each and every generator that's available. Look into details for any that could be related in any way before making this decision.
+
+## Pre-Execution Checklist
+
+Before running any generator, complete these steps:
+
+### 1. Fetch Generator Schema
+
+Use the `--help` flag to understand all available options:
+
+```bash
+npx nx g @nx/react:library --help
+```
+
+Pay attention to:
+
+- Required options that must be provided
+- Optional options that may be relevant to the user's request
+- Default values that might need to be overridden
+
+### 2. Read Generator Source Code
+
+Understanding what the generator actually does helps you:
+
+- Know what files will be created/modified
+- Understand any side effects (updating configs, installing deps, etc.)
+- Identify options that might not be obvious from the schema
+
+To find generator source code:
+
+- For plugin generators: Use `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"` to find the generators.json, then locate the source from there
+- If that fails, read directly from `node_modules/<plugin>/generators.json`
+- For local generators: They are typically in `tools/generators/` or a local plugin directory. You can search the repo for the generator name to find it.
+
+### 2.5 Reevaluate if the generator is right
+
+Once you have built up an understanding of what the selected generator does, reconsider: Is this the right generator to service the user request?
+If not, it's okay to go back to the Generator Discovery Flow and select a different generator before proceeding. If you do, make sure to go through the entire pre-execution checklist once more.
+
+### 3. Understand Repo Context
+
+Before generating, examine the target area of the codebase:
+
+- Look at similar existing artifacts (other libraries, applications, etc.)
+- Identify patterns and conventions used in the repo
+- Note naming conventions, file structures, and configuration patterns
+- Try to match these patterns when configuring the generator
+
+For example, if similar libraries are using a specific test runner, build tool or linter, try to match that if possible.
+If projects or other artifacts are organized with a specific naming convention, try to match it.
+
+### 4. Validate Required Options
+
+Ensure all required options have values:
+
+- Map the user's request to generator options
+- Infer values from context where possible
+- Ask the user for any critical missing information
+
+## Execution
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally.
+Many generators will behave differently based on where they are executed. For example, first-party nx library generators use the cwd to determine the directory that the library should be placed in. This is highly important.
+
+### Consider Dry-Run (Optional)
+
+Running with `--dry-run` first is strongly encouraged but not mandatory. Use your judgment:
+
+- For complex generators or unfamiliar territory: do a dry-run first
+- For simple, well-understood generators: may proceed directly
+- Dry-run shows file names and created/deleted/modified markers, but not content
+- There are cases where a generator does not support dry-run (for example if it had to install an npm package) - in that case --dry-run might fail. Don't be discouraged but simply move on to running the generator for real and iterating from there.
+
+### Running the Generator
+
+Execute the generator with:
+
+```bash
+nx generate <generator-name> <options> --no-interactive
+```
+
+**CRITICAL**: Always include `--no-interactive` to prevent prompts that would hang the execution.
+
+Example:
+
+```bash
+nx generate @nx/react:library --name=my-utils --no-interactive
+```
+
+### Handling Generator Failures
+
+If the generator fails:
+
+1. **Diagnose the error** - Read the error message carefully
+2. **Identify the cause** - Missing options, invalid values, conflicts, etc.
+3. **Attempt automatic fix** - Adjust options or resolve conflicts
+4. **Retry** - Run the generator again with corrected options
+
+Common failure reasons:
+
+- Missing required options
+- Invalid option values
+- Conflicting with existing files
+- Missing dependencies
+- Generator doesn't support certain flag combinations
+
+## Post-Generation
+
+### 1. Modify Generated Code (If Needed)
+
+Generators provide a starting point, but the output may need adjustment to match the user's specific requirements:
+
+- Add or modify functionality as requested
+- Adjust imports, exports, or configurations
+- Integrate with existing code patterns in the repo
+
+### 2. Format Code
+
+Run formatting on all generated/modified files:
+
+```bash
+nx format --fix
+```
+
+Languages other than javascript/typescript might need other formatting invocations too.
+
+### 3. Run Verification
+
+Verify that the generated code works correctly. What this looks like will vary depending on the type of generator and the targets available.
+If the generator created a new project, run its targets directly
+Use your best judgement to determine what needs to be verified.
+
+Example:
+
+```bash
+nx lint <new-project>
+nx test <new-project>
+nx build <new-project>
+```
+
+### 4. Handle Verification Failures
+
+When verification fails:
+
+**If scope is manageable** (a few lint errors, minor type issues):
+
+- Fix the issues
+- Re-run verification to confirm
+
+**If issues are extensive** (many errors, complex problems):
+
+- Attempt simple, obvious fixes first
+- If still failing, escalate to the user with:
+  - Description of what was generated
+  - What verification is failing
+  - What you've attempted to fix
+  - Remaining issues that need user input
+
+## Error Handling
+
+### Generator Failures
+
+- Check the error message for specific causes
+- Verify all required options are provided
+- Check for conflicts with existing files
+- Ensure the generator name and options are correct
+
+### Missing Options
+
+- Consult the generator schema for required fields
+- Infer values from context when reasonable
+- Ask the user for values that cannot be inferred
+
+## Key Principles
+
+1. **Local generators first** - Always prefer workspace/local generators over external plugin generators when both could work
+
+2. **Understand before running** - Read both the schema AND the source code to fully understand what will happen
+
+3. **No prompts** - Always use `--no-interactive` to prevent hanging
+
+4. **Generators are starting points** - Modify the output as needed to fully satisfy the user's requirements
+
+5. **Verify changes work** - Don't just generate; ensure the code builds, lints, and tests pass
+
+6. **Be proactive about fixes** - Don't just report errors; attempt to resolve them automatically when possible
+
+7. **Match repo patterns** - Study existing similar code in the repo and match its conventions

.opencode/skills/nx-plugins/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: nx-plugins
+description: Find and add Nx plugins. USE WHEN user wants to discover available plugins, install a new plugin, or add support for a specific framework or technology to the workspace.
+---
+
+## Finding and Installing new plugins
+
+- List plugins: `pnpm nx list`
+- Install plugins `pnpm nx add <plugin>`. Example: `pnpm nx add @nx/react`.

.opencode/skills/nx-run-tasks/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: nx-run-tasks
+description: Helps with running tasks in an Nx workspace. USE WHEN the user wants to execute build, test, lint, serve, or run any other tasks defined in the workspace.
+---
+
+You can run tasks with Nx in the following way.
+
+Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally. Look at the package.json or lockfile to determine which package manager is in use.
+
+For more details on any command, run it with `--help` (e.g. `nx run-many --help`, `nx affected --help`).
+
+## Understand which tasks can be run
+
+You can check those via `nx show project <projectname> --json`, for example `nx show project myapp --json`. It contains a `targets` section which has information about targets that can be run. You can also just look at the `package.json` scripts or `project.json` targets, but you might miss out on inferred tasks by Nx plugins.
+
+## Run a single task
+
+```
+nx run <project>:<task>
+```
+
+where `project` is the project name defined in `package.json` or `project.json` (if present).
+
+## Run multiple tasks
+
+```
+nx run-many -t build test lint typecheck
+```
+
+You can pass a `-p` flag to filter to specific projects, otherwise it runs on all projects. You can also use `--exclude` to exclude projects, and `--parallel` to control the number of parallel processes (default is 3).
+
+Examples:
+
+- `nx run-many -t test -p proj1 proj2` — test specific projects
+- `nx run-many -t test --projects=*-app --exclude=excluded-app` — test projects matching a pattern
+- `nx run-many -t test --projects=tag:api-*` — test projects by tag
+
+## Run tasks for affected projects
+
+Use `nx affected` to only run tasks on projects that have been changed and projects that depend on changed projects. This is especially useful in CI and for large workspaces.
+
+```
+nx affected -t build test lint
+```
+
+By default it compares against the base branch. You can customize this:
+
+- `nx affected -t test --base=main --head=HEAD` — compare against a specific base and head
+- `nx affected -t test --files=libs/mylib/src/index.ts` — specify changed files directly
+
+## Useful flags
+
+These flags work with `run`, `run-many`, and `affected`:
+
+- `--skipNxCache` — rerun tasks even when results are cached
+- `--verbose` — print additional information such as stack traces
+- `--nxBail` — stop execution after the first failed task
+- `--configuration=<name>` — use a specific configuration (e.g. `production`)

.opencode/skills/nx-workspace/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: nx-workspace
+description: "Explore and understand Nx workspaces. USE WHEN answering any questions about the nx workspace, the projects in it or tasks to run. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What targets can I run?', 'What's affected by my changes?', 'Which projects depend on library Y?', or any questions about Nx workspace structure, project configuration, or available tasks."
+---
+
+# Nx Workspace Exploration
+
+This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.
+
+Keep in mind that you might have to prefix commands with `npx`/`pnpx`/`yarn` if nx isn't installed globally. Check the lockfile to determine the package manager in use.
+
+## Listing Projects
+
+Use `nx show projects` to list projects in the workspace.
+
+```bash
+# List all projects
+nx show projects
+
+# Filter by pattern (glob)
+nx show projects --projects "apps/*"
+nx show projects --projects "shared-*"
+
+# Filter by project type
+nx show projects --type app
+nx show projects --type lib
+nx show projects --type e2e
+
+# Filter by target (projects that have a specific target)
+nx show projects --withTarget build
+nx show projects --withTarget e2e
+
+# Find affected projects (changed since base branch)
+nx show projects --affected
+nx show projects --affected --base=main
+nx show projects --affected --type app
+
+# Combine filters
+nx show projects --type lib --withTarget test
+nx show projects --affected --exclude="*-e2e"
+
+# Output as JSON
+nx show projects --json
+```
+
+## Project Configuration
+
+Use `nx show project <name> --json` to get the full resolved configuration for a project.
+
+**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project` command returns the full resolved config including inferred targets from plugins.
+
+You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options.
+
+```bash
+# Get full project configuration
+nx show project my-app --json
+
+# Extract specific parts from the JSON
+nx show project my-app --json | jq '.targets'
+nx show project my-app --json | jq '.targets.build'
+nx show project my-app --json | jq '.targets | keys'
+
+
+# Check project metadata
+nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'
+```
+
+## Target Information
+
+Targets define what tasks can be run on a project.
+
+```bash
+# List all targets for a project
+nx show project my-app --json | jq '.targets | keys'
+
+# Get full target configuration
+nx show project my-app --json | jq '.targets.build'
+
+# Check target executor/command
+nx show project my-app --json | jq '.targets.build.executor'
+nx show project my-app --json | jq '.targets.build.command'
+
+# View target options
+nx show project my-app --json | jq '.targets.build.options'
+
+# Check target inputs/outputs (for caching)
+nx show project my-app --json | jq '.targets.build.inputs'
+nx show project my-app --json | jq '.targets.build.outputs'
+
+# Find projects with a specific target
+nx show projects --withTarget serve
+nx show projects --withTarget e2e
+```
+
+## Workspace Configuration
+
+Read `nx.json` directly for workspace-level configuration.
+You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options.
+
+```bash
+# Read the full nx.json
+cat nx.json
+
+# Or use jq for specific sections
+cat nx.json | jq '.targetDefaults'
+cat nx.json | jq '.namedInputs'
+cat nx.json | jq '.plugins'
+cat nx.json | jq '.generators'
+```
+
+Key nx.json sections:
+
+- `targetDefaults` - Default configuration applied to all targets of a given name
+- `namedInputs` - Reusable input definitions for caching
+- `plugins` - Nx plugins and their configuration
+- ...and much more, read the schema or nx.json for details
+
+## Affected Projects
+
+Find projects affected by changes in the current branch.
+
+```bash
+# Affected since base branch (auto-detected)
+nx show projects --affected
+
+# Affected with explicit base
+nx show projects --affected --base=main
+nx show projects --affected --base=origin/main
+
+# Affected between two commits
+nx show projects --affected --base=abc123 --head=def456
+
+# Affected apps only
+nx show projects --affected --type app
+
+# Affected excluding e2e projects
+nx show projects --affected --exclude="*-e2e"
+
+# Affected by uncommitted changes
+nx show projects --affected --uncommitted
+
+# Affected by untracked files
+nx show projects --affected --untracked
+```
+
+## Common Exploration Patterns
+
+### "What's in this workspace?"
+
+```bash
+nx show projects
+nx show projects --type app
+nx show projects --type lib
+```
+
+### "How do I build/test/lint project X?"
+
+```bash
+nx show project X --json | jq '.targets | keys'
+nx show project X --json | jq '.targets.build'
+```
+
+### "What depends on library Y?"
+
+```bash
+# Find projects that may depend on Y by searching for imports
+# (Nx doesn't have a direct "dependents" command via CLI)
+grep -r "from '@myorg/Y'" --include="*.ts" --include="*.tsx" apps/ libs/
+```
+
+### "What configuration options are available?"
+
+```bash
+cat node_modules/nx/schemas/nx-schema.json | jq '.properties | keys'
+cat node_modules/nx/schemas/project-schema.json | jq '.properties | keys'
+```
+
+### "Why is project X affected?"
+
+```bash
+# Check what files changed
+git diff --name-only main
+
+# See which project owns those files
+nx show project X --json | jq '.root'
+```

.prettierignore

@@ -54,3 +54,8 @@ _solution
 
 # this file uses TS import attributes which the current prettier version does not support
 tools/documentation/create-embeddings/src/main.mts
+
+.nx/self-healing
+
+# Inlined from `@yarnpkg/parser` keep as is
+packages/nx/src/utils/yarn-syml/syml-grammar.js

.prettierrc

@@ -1,6 +1,7 @@
 {
   "singleQuote": true,
   "endOfLine": "lf",
+  "trailingComma": "es5",
   "plugins": ["prettier-plugin-tailwindcss"],
   "overrides": [
     {

AGENTS.md

@@ -9,6 +9,25 @@ When responding to queries about this repository:
 Always strive to provide accurate, helpful responses that align with the best practices and workflows described in this
 file.
 
+## Documentation Contributions
+
+When working on Nx documentation, all documentation content lives in the `astro-docs/` folder. This is the new Astro-based documentation site built with Starlight.
+
+**Important**: Before making any documentation changes, read the `astro-docs/README.md` file for detailed guidance on:
+
+- Project structure and architecture
+- Content types (regular docs, dynamic plugin docs, CLI docs)
+- Available Markdoc tags for rich content
+- Development workflow and commands
+- Sidebar management
+
+### Quick Reference
+
+- Documentation content: `astro-docs/src/content/docs/`
+- Use `.mdoc` (Markdoc) or `.mdx` format for documentation files
+- Run `nx serve astro-docs` to start the local dev server
+- Sidebar structure is defined in `astro-docs/sidebar.mts`
+
 ## GitHub Issue Response Mode
 
 When responding to GitHub issues, determine your approach based on how the request is phrased:
@@ -183,22 +202,23 @@ Fixes #ISSUE_NUMBER
 <!-- nx configuration start-->
 <!-- Leave the start & end comments to automatically receive updates. -->
 
-# General Guidelines for working with Nx
+## General Guidelines for working with Nx
 
+- For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns for querying projects, targets, and dependencies
 - When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly
+- Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`, `npm exec nx test`) - avoids using globally installed CLI
 - You have access to the Nx MCP server and its tools, use them to help the user
-- When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable.
-- When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies
-- For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
-- If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors
+- For Nx plugin best practices, check `node_modules/@nx/<plugin>/PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable.
+- NEVER guess CLI flags - always check nx_docs or `--help` first when unsure
 
-# CI Error Guidelines
+## Scaffolding & Generators
 
-If the user wants help with fixing an error in their CI pipeline, use the following flow:
+- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the `nx-generate` skill FIRST before exploring or calling MCP tools
 
-- Retrieve the list of current CI Pipeline Executions (CIPEs) using the `nx_cloud_cipe_details` tool
-- If there are any errors, use the `nx_cloud_fix_cipe_failure` tool to retrieve the logs for a specific task
-- Use the task logs to see what's wrong and help the user fix their problem. Use the appropriate tools if necessary
-- Make sure that the problem is fixed by running the task that you passed into the `nx_cloud_fix_cipe_failure` tool
+## When to use nx_docs
+
+- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases
+- DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you already know
+- The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look up generator syntax
 
 <!-- nx configuration end-->

CLAUDE.md

@@ -9,6 +9,27 @@ When responding to queries about this repository:
 Always strive to provide accurate, helpful responses that align with the best practices and workflows described in this
 file.
 
+## Documentation Contributions
+
+When working on Nx documentation, all documentation content lives in the `astro-docs/` folder. This is the new Astro-based documentation site built with Starlight.
+
+**Important**: Before making any documentation changes, read the `astro-docs/README.md` file for detailed guidance on:
+
+- Project structure and architecture
+- Content types (regular docs, dynamic plugin docs, CLI docs)
+- Available Markdoc tags for rich content
+- Development workflow and commands
+- Sidebar management
+
+**MANDATORY**: After editing any file in `astro-docs/src/content/`, run the `nx-docs-style-check` skill. No exceptions.
+
+### Quick Reference
+
+- Documentation content: `astro-docs/src/content/docs/`
+- Use `.mdoc` (Markdoc) or `.mdx` format for documentation files
+- Run `nx serve astro-docs` to start the local dev server
+- Sidebar structure is defined in `astro-docs/sidebar.mts`
+
 ## GitHub Issue Response Mode
 
 When responding to GitHub issues, determine your approach based on how the request is phrased:
@@ -183,22 +204,23 @@ Fixes #ISSUE_NUMBER
 <!-- nx configuration start-->
 <!-- Leave the start & end comments to automatically receive updates. -->
 
-# General Guidelines for working with Nx
+## General Guidelines for working with Nx
 
+- For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns for querying projects, targets, and dependencies
 - When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly
+- Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`, `npm exec nx test`) - avoids using globally installed CLI
 - You have access to the Nx MCP server and its tools, use them to help the user
-- When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable.
-- When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies
-- For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
-- If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors
+- For Nx plugin best practices, check `node_modules/@nx/<plugin>/PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable.
+- NEVER guess CLI flags - always check nx_docs or `--help` first when unsure
 
-# CI Error Guidelines
+## Scaffolding & Generators
 
-If the user wants help with fixing an error in their CI pipeline, use the following flow:
+- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the `nx-generate` skill FIRST before exploring or calling MCP tools
 
-- Retrieve the list of current CI Pipeline Executions (CIPEs) using the `nx_cloud_cipe_details` tool
-- If there are any errors, use the `nx_cloud_fix_cipe_failure` tool to retrieve the logs for a specific task
-- Use the task logs to see what's wrong and help the user fix their problem. Use the appropriate tools if necessary
-- Make sure that the problem is fixed by running the task that you passed into the `nx_cloud_fix_cipe_failure` tool
+## When to use nx_docs
+
+- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases
+- DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you already know
+- The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look up generator syntax
 
 <!-- nx configuration end-->

CODEOWNERS

@@ -1,165 +1,2 @@
 # Any file not covered by a rule below, will default to Jason + Victor and a few select others.
-* @FrozenPandaz @vsavkin
-/packages/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry
-/e2e/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry
-/scripts/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry
-/tools/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry
-package.json @nrwl/nx-core-reviewers
-pnpm-lock.yaml @nrwl/nx-core-reviewers
-rust-toolchain.toml @nrwl/nx-native-reviewers
-
-# Docs Site + Graph
-/astro-docs @nrwl/nx-docs-reviewers
-/docs @nrwl/nx-docs-reviewers
-/graph/** @philipjfulcher @FrozenPandaz @bcabanes @MaxKless @Coly010 @jaysoo @nartc
-/images @nrwl/nx-docs-reviewers
-/nx-dev/** @nrwl/nx-docs-reviewers
-/typedoc-theme @nrwl/nx-docs-reviewers
-
-# Plugin Verticals
-
-## Angular
-/packages/angular/** @nrwl/nx-angular-reviewers
-/packages/angular-rspack/** @nrwl/nx-angular-reviewers
-/packages/angular-rspack-compiler/** @nrwl/nx-angular-reviewers
-/examples/angular-rspack/** @nrwl/nx-angular-reviewers
-/e2e/angular/** @nrwl/nx-angular-reviewers
-/packages/angular/plugins/component-testing.ts @nrwl/nx-angular-reviewers @nrwl/nx-testing-tools-reviewers
-/packages/angular/src/generators/cypress-component-configuration/** @nrwl/nx-angular-reviewers @nrwl/nx-testing-tools-reviewers
-/packages/angular/src/generators/component-test/** @nrwl/nx-angular-reviewers @nrwl/nx-testing-tools-reviewers
-
-## React
-/packages/react/** @nrwl/nx-react-reviewers
-/e2e/react/** @nrwl/nx-react-reviewers
-/packages/next/** @nrwl/nx-react-reviewers
-/e2e/next/** @nrwl/nx-react-reviewers
-/packages/react/plugins/component-testing/** @nrwl/nx-react-reviewers @nrwl/nx-testing-tools-reviewers
-/packages/react/src/generators/cypress-component-configuration/** @nrwl/nx-react-reviewers @nrwl/nx-testing-tools-reviewers
-/packages/react/src/generators/component-test/** @nrwl/nx-react-reviewers @nrwl/nx-testing-tools-reviewers
-
-# React Native
-/packages/detox/** @nrwl/nx-react-reviewers
-/e2e/detox/** @nrwl/nx-react-reviewers
-/packages/expo/** @nrwl/nx-react-reviewers
-/e2e/expo/** @nrwl/nx-react-reviewers
-/packages/react-native/** @nrwl/nx-react-reviewers
-/e2e/react-native/** @nrwl/nx-react-reviewers
-
-## remix
-/packages/remix/** @nrwl/nx-react-reviewers @Coly010
-/e2e/remix/** @nrwl/nx-react-reviewers @Coly010
-
-# Vue
-/packages/vue/** @nrwl/nx-vue-reviewers
-/e2e/vue/** @nrwl/nx-vue-reviewers
-/packages/nuxt/** @nrwl/nx-vue-reviewers
-/e2e/nuxt/** @nrwl/nx-vue-reviewers
-
-## Node
-/packages/node/** @nrwl/nx-node-reviewers
-/packages/express/** @nrwl/nx-node-reviewers
-/packages/nest/** @nrwl/nx-node-reviewers
-/e2e/node/** @nrwl/nx-node-reviewers
-
-## JS
-/packages/js/** @nrwl/nx-js-reviewers
-/e2e/js/** @nrwl/nx-js-reviewers
-/packages/web/** @nrwl/nx-js-reviewers
-/e2e/web/** @nrwl/nx-js-reviewers
-/packages/webpack/** @nrwl/nx-js-reviewers
-/e2e/webpack/** @nrwl/nx-js-reviewers
-/packages/rspack/** @nrwl/nx-js-reviewers
-/e2e/rspack/** @nrwl/nx-js-reviewers
-/packages/rsbuild/** @nrwl/nx-js-reviewers
-/packages/esbuild/** @nrwl/nx-js-reviewers
-/e2e/esbuild/** @nrwl/nx-js-reviewers
-/packages/rollup/** @nrwl/nx-js-reviewers
-/e2e/rollup/** @nrwl/nx-js-reviewers
-/packages/vite/** @nrwl/nx-js-reviewers
-/e2e/vite/** @nrwl/nx-js-reviewers
-
-## Module Federation
-/packages/module-federation/** @nrwl/nx-js-reviewers
-
-## Tools
-/packages/cypress/** @nrwl/nx-testing-tools-reviewers
-/e2e/cypress/** @nrwl/nx-testing-tools-reviewers
-/packages/jest/** @nrwl/nx-testing-tools-reviewers
-/e2e/jest/** @nrwl/nx-testing-tools-reviewers
-/packages/playwright/** @nrwl/nx-testing-tools-reviewers
-/e2e/playwright/** @nrwl/nx-testing-tools-reviewers
-
-# Linter
-/packages/eslint-plugin/** @nrwl/nx-linter-reviewers
-/packages/eslint/** @nrwl/nx-linter-reviewers
-/e2e/eslint/** @nrwl/nx-linter-reviewers
-.eslint* @nrwl/nx-linter-reviewers
-
-# Storybook
-/packages/storybook/** @nrwl/nx-storybook-reviewers
-/e2e/storybook/** @nrwl/nx-storybook-reviewers
-
-# Docker
-/packages/docker/** @nrwl/nx-core-reviewers @Coly010
-
-## Devkit
-/packages/devkit/** @nrwl/nx-devkit-reviewers
-/packages/devkit/index.ts @FrozenPandaz @vsavkin
-/packages/devkit/public-api.ts @FrozenPandaz @vsavkin
-
-# Gradle
-/packages/gradle/** @FrozenPandaz @MaxKless @lourw
-/e2e/gradle/** @FrozenPandaz @MaxKless @lourw
-
-# Maven
-/packages/maven/** @FrozenPandaz @MaxKless @lourw
-/e2e/maven/** @FrozenPandaz @MaxKless @lourw
-
-# Nx-Plugin
-/packages/plugin/** @nrwl/nx-devkit-reviewers
-/e2e/plugin/** @nrwl/nx-devkit-reviewers
-
-## Core
-/packages/nx/** @nrwl/nx-core-reviewers
-/packages/nx/src/adapter @nrwl/nx-core-reviewers @leosvelperez
-/packages/nx/src/native @nrwl/nx-core-reviewers @nrwl/nx-native-reviewers
-/packages/nx/src/plugins/js/lock-file @nrwl/nx-core-reviewers @meeroslav
-/packages/nx/src/command-line/init/implementation/angular/** @nrwl/nx-angular-reviewers @nrwl/nx-core-reviewers
-/e2e/nx-init/src/nx-init-angular.test.ts @nrwl/nx-angular-reviewers
-/packages/nx/src/command-line/init/implementation/react/** @nrwl/nx-react-reviewers
-/e2e/nx-init/src/nx-init-react.test.ts @nrwl/nx-react-reviewers
-/e2e/nx-init/src/files/cra/** @nrwl/nx-react-reviewers
-/e2e/nx*/** @nrwl/nx-core-reviewers
-/packages/workspace/** @nrwl/nx-core-reviewers
-/e2e/workspace-create/** @nrwl/nx-core-reviewers
-/e2e/release/** @nrwl/nx-core-reviewers
-
-# Misc
-/e2e/lerna-smoke-tests/** @vsavkin @JamesHenry
-/e2e/utils/** @meeroslav @nrwl/nx-testing-tools-reviewers @vsavkin
-/community @nrwl/nx-docs-reviewers
-/CONTRIBUTING.md @FrozenPandaz
-/CODE_OF_CONDUCT.md @FrozenPandaz
-/CODEOWNERS @FrozenPandaz @AgentEnder
-/packages/nx/src/nx-cloud/utilities/url-shorten.ts @MaxKless
-
-# Scripts
-/scripts/documentation @nrwl/nx-docs-reviewers
-/scripts/angular-support-upgrades @nrwl/nx-angular-reviewers
-
-# CI
-/.nx/workflows/** @nrwl/nx-pipelines-reviewers
-/.github/** @nrwl/nx-pipelines-reviewers
-/.husky/** @nrwl/nx-pipelines-reviewers
-/packages/workspace/src/generators/ci-workflow/** @nrwl/nx-pipelines-reviewers
-
-# Claude AI Integration
-CLAUDE.md @FrozenPandaz
-.claude/** @FrozenPandaz
-.mcp.json @FrozenPandaz
-
-# Global Files
-project.json @FrozenPandaz @vsavkin
-jest.config.ts @nrwl/nx-testing-tools-reviewers @FrozenPandaz
-jest.preset.js @nrwl/nx-testing-tools-reviewers @FrozenPandaz
-
+* @nrwl/nx-cli-reviewers

CONTRIBUTING.md

@@ -2,19 +2,10 @@
 
 We would love for you to contribute to Nx! Read this document to see how to do it.
 
-## How to Get Started Video
-
-Watch this 5-minute video:
-
-<a href="https://www.youtube.com/watch?v=8LCA_4qxc08" target="_blank" rel="noreferrer">
-<p style="text-align: center;"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/how-to-contribute.png" width="600" alt="Nx - How to contribute"></p>
-</a>
-
 ## Got a Question?
 
-We are trying to keep GitHub issues for bug reports and feature requests. Using the `nrwl` tag
-on [Stack Overflow](https://stackoverflow.com/questions/tagged/nrwl) is a much better place to ask general questions
-about how to use Nx.
+We are trying to keep GitHub issues for bug reports and feature requests.
+You can join our [Discord](https://go.nx.dev/community) for general questions and seeking help from others.
 
 ## Found an Issue?
 

LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2017-2025 Narwhal Technologies Inc.
+Copyright (c) 2017-2026 Narwhal Technologies Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -1,74 +1,52 @@
-<p style="text-align: center;">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-dark.svg">
- <img alt="Nx - Smart Repos · Fast Builds" src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-light.svg" width="100%">
- </picture>
-</p>
+<div align="center">
 
-<div style="text-align: center;">
+  <p>
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="images/nx-logo-light.svg">
+      <img src="images/nx-logo.svg" alt="Nx Logo" width="140">
+    </picture>
+  </p>
 
-[![CircleCI](https://circleci.com/gh/nrwl/nx.svg?style=svg)](https://circleci.com/gh/nrwl/nx)
-[![License](https://img.shields.io/npm/l/nx.svg?style=flat-square)]()
-[![NPM Version](https://badge.fury.io/js/nx.svg)](https://www.npmjs.com/package/nx)
-[![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic-release-e10079.svg?style=flat-square)]()
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
-[![Join the chat at https://gitter.im/nrwl-nx/community](https://badges.gitter.im/nrwl-nx/community.svg)](https://gitter.im/nrwl-nx/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Join the Official Nx Discord Server](https://img.shields.io/discord/1143497901675401286?label=discord)](https://go.nx.dev/community)
+  <h1 align="center">Smart Monorepos · Fast Builds</h1>
+
+  <p>
+    <a href="https://www.npmjs.com/package/nx"><img src="https://img.shields.io/npm/v/nx.svg?style=for-the-badge" alt="NPM Version"></a>
+    <a href="https://github.com/nrwl/nx"><img src="https://img.shields.io/github/stars/nrwl/nx?style=for-the-badge&logo=github" alt="GitHub Stars"></a>
+    <a href=""><img src="https://img.shields.io/npm/l/nx.svg?style=for-the-badge" alt="License"></a>
+    <a href="https://go.nx.dev/community"><img src="https://img.shields.io/discord/1143497901675401286?label=discord&style=for-the-badge" alt="Discord"></a>
+    <a href="https://x.com/nxdevtools"><img src="https://img.shields.io/badge/@nxdevtools-555?style=for-the-badge&logo=x" alt="X (Twitter)"></a>
+  </p>
+
+ <br />
+
+[**Docs**](https://nx.dev/docs) &nbsp;&bull;&nbsp; [**Changelog**](https://nx.dev/changelog) &nbsp;&bull;&nbsp; [**Blog**](https://nx.dev/blog) &nbsp;&bull;&nbsp; [**Courses**](https://nx.dev/courses) &nbsp;&bull;&nbsp; [**YouTube**](https://youtube.com/@nxdevtools)
+
+<br />
 
 </div>
 
-<hr>
+Nx is a monorepo solution for TypeScript and polyglot codebases. Built with Rust for performance, extensible via TypeScript. Caches what didn't change, runs only what's affected, and comes with an integrated CI solution. Start simple, scale as you grow.
 
-# Smart Repos · Fast Builds
+## Quick Start
 
-Get to green PRs in half the time. Nx optimizes your builds, scales your CI, and fixes failed PRs. Built for developers and AI agents.
+Visit the [Nx quickstart docs](https://nx.dev/docs/quickstart) to get started.
 
-Create a new Nx workspace with
+## Why Nx?
 
-```shell
-npx create-nx-workspace
-```
+- **Incremental by design -** Run `npx nx init` in any npm/pnpm/yarn workspace. Nx picks up your existing `package.json` scripts, caches their outputs, and runs only what's
+  affected. No changes to your setup required.
+- **AI-native tooling -** The Nx CLI is optimized for autonomous AI agents so they get the context they need and can operate just like a human. [Learn more &raquo;](https://github.com/nrwl/nx-ai-agents-config)
+- **Polyglot plugin system -** Optional plugins auto-discover tasks, configure cache inputs/outputs, and scaffold code based on your actual tooling. Works with Vite, Webpack, Jest, Vitest, ESLint, Gradle, Maven, .NET, Go, and [more](https://nx.dev/technologies).
+- **Integrated CI solution -** [Connect Nx to your CI provider](https://nx.dev/ci/intro/ci-with-nx) (GitHub Actions, GitLab, Azure, etc.) to enable remote caching, task distribution across machines, affected-only runs, and automatic e2e test splitting. [Learn more &raquo;](https://nx.dev/ci/intro/ci-with-nx)
+- **Self-healing CI -** An AI agent on your CI pipeline that detects failures, analyzes root cause, proposes a fix, and verifies it automatically. Local agents connect to CI via MCP to autonomously detect and fix failures. [Learn more &raquo;](https://nx.dev/ci/features/self-healing)
 
-...or run
+## Who uses Nx?
 
-```
-npx nx init
-```
-
-to add Nx to your existing workspace to get faster task scheduling, caching and more. More [in the docs](https://nx.dev/getting-started/intro).
-
-## Learn about CI with Nx Cloud
-
-[Nx Cloud](https://nx.dev/nx-cloud) connects directly to your existing CI setup, helping you scale your monorepos on CI by leveraging [remote caching](https://nx.dev/ci/features/remote-cache?utm_source=nxrepo&utm_medium=readme&utm_campaign=nxrepo), [task distribution across multiple machines](https://nx.dev/ci/features/distribute-task-execution?utm_source=nxrepo&utm_medium=readme&utm_campaign=nxrepo), [automated e2e test splitting](https://nx.dev/ci/features/split-e2e-tasks?utm_source=nxrepo&utm_medium=readme&utm_campaign=nxrepo) and [automated task flakiness detection](https://nx.dev/ci/features/flaky-tasks?utm_source=nxrepo&utm_medium=readme&utm_campaign=nxrepo)
-
-Connect your existing Nx workspace with
-
-```
-npx nx connect
-```
-
-Learn more in the [Nx CI docs &raquo;](https://nx.dev/ci/getting-started/intro?utm_source=nxrepo&utm_medium=readme&utm_campaign=nxrepo)
-
-## Useful links
-
-- [Our docs](https://nx.dev/docs)
-- [Our blog](https://nx.dev/blog)
-- [Our community discord, live stream,...](https://nx.dev/community)
-- [Our YouTube channel](https://www.youtube.com/@NxDevtools)
-- [Our Twitter/X](https://x.com/nxdevtools)
-
-<p style="text-align: center;"><a href="https://www.youtube.com/@nxdevtools/videos" target="_blank" rel="noreferrer"><img src="./images/nx-courses-and-videos.svg" 
-width="100%" alt="Nx - Smart Repos · Fast Builds"></a></p>
+From startups to Fortune 500 companies. [See our Nx success stories &raquo;](https://nx.dev/customers)
 
 ## Want to help?
 
-If you want to file a bug or submit a PR, read up on
-our [guidelines for contributing](https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md) and watch this video that will
-help you get started.
-
-<a href="https://www.youtube.com/watch?v=8LCA_4qxc08" target="_blank" rel="noreferrer">
-<p style="text-align: center;"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/how-to-contribute.png" width="600" alt="Nx - How to contribute video"></p>
-</a>
+If you want to file a bug or submit a PR, read up on our [guidelines for contributing](https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md).
 
 ## Core Team
 

SECURITY.md

@@ -13,3 +13,15 @@ Instead, please report them to the Security Team at security@nrwl.io.
 You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message.
 
 Nx follows the principle of Coordinated Vulnerability Disclosure.
+
+## What Should Be Reported
+
+The security email is for **demonstrable, verified vulnerabilities within the Nx codebase itself**.
+
+**Please do not use the security email for:**
+
+- Reports about outdated dependencies (e.g., "package X has a newer version available")
+- Reports about dependencies with known CVEs that do not directly affect Nx functionality
+- General vulnerability scanner output
+
+If you have a concern about an outdated dependency that you believe impacts Nx users, please open a [GitHub issue](https://github.com/nrwl/nx/issues/new/choose) instead.

astro-docs/.vale.ini

@@ -0,0 +1,162 @@
+StylesPath = .vale/styles
+MinAlertLevel = suggestion
+
+# Treat Markdoc (.mdoc) files as markdown
+[formats]
+mdoc = md
+
+# Ignore Markdoc tag syntax and @-scoped package names to avoid false positives
+TokenIgnores = (\{%.*?%\}), (@\w+/[\w-]+)
+
+[src/content/docs/**/*.{mdoc,mdx,md}]
+BasedOnStyles = Nx
+
+# Disable heading check for config option reference pages (headings are camelCase property names)
+[src/content/docs/technologies/angular/angular-rsbuild/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/angular/angular-rspack/create-config.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/build-tools/webpack/Guides/webpack-plugins.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/Deprecated/affected-graph.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/Deprecated/print-affected.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/react/next/Guides/next-config-setup.mdoc]
+Nx.Headings = NO
+
+# Disable heading check for release notes (timestamps as headings)
+[src/content/docs/reference/Nx Cloud/release-notes.mdoc]
+Nx.Headings = NO
+
+# Disable heading check for nx-cloud-cli (CLI flags as headings)
+[src/content/docs/reference/nx-cloud-cli.mdoc]
+Nx.Headings = NO
+
+# Disable heading check for nx-console-settings (config option headings)
+[src/content/docs/reference/nx-console-settings.mdoc]
+Nx.Headings = NO
+
+# Disable heading check for pages with camelCase API property headings
+[src/content/docs/reference/nx-json.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/project-configuration.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/Deprecated/legacy-cache.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/extending-nx/local-executors.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/guides/Nx Release/programmatic-api.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/node/Guides/wait-for-tasks.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/test-tools/vitest/Guides/testing-without-building-dependencies.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/angular/Guides/nx-and-angular.mdoc]
+Nx.Headings = NO
+
+# Disable heading check for merge-atomized-outputs (warning message as heading)
+[src/content/docs/technologies/test-tools/playwright/Guides/merge-atomized-outputs.mdoc]
+Nx.Headings = NO
+
+# Disable heading check for plugin introduction pages (@nx/ package name headings)
+[src/content/docs/technologies/build-tools/docker/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/build-tools/rspack/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/build-tools/webpack/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/dotnet/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/eslint/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/java/gradle/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/java/maven/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/react/expo/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/react/react-native/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/test-tools/cypress/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/test-tools/detox/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/test-tools/playwright/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/test-tools/storybook/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/vue/nuxt/introduction.mdoc]
+Nx.Headings = NO
+
+# Disable heading check for remaining pages with structural false positives
+# (code identifiers, slashes, quotes, parenthetical words in headings)
+[src/content/docs/extending-nx/create-install-package.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/extending-nx/create-preset.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/getting-started/editor-setup.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/guides/Adopting Nx/from-turborepo.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/guides/Tasks & Caching/reduce-repetitive-configuration.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/guides/Tasks & Caching/workspace-watching.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/Deprecated/custom-tasks-runner.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/Deprecated/rescope.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/Nx Cloud/credits-pricing.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/reference/nx-mcp.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/eslint/Guides/custom-workspace-rules.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/module-federation/Guides/nx-module-federation-plugin.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/module-federation/introduction.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/technologies/react/Guides/react-router.mdoc]
+Nx.Headings = NO
+
+[src/content/docs/troubleshooting/unknown-local-cache.mdoc]
+Nx.Headings = NO

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

@@ -0,0 +1,29 @@
+extends: existence
+message: "Avoid AI-sounding phrase '%s'. Rewrite to be direct."
+level: error
+ignorecase: true
+tokens:
+  - "It's important to note that"
+  - "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"
+  - "Whether you're a beginner or an experienced developer"
+  - "In today's fast-paced development environment"
+  - 'Unlock the power of'
+  - 'Harness the power of'
+  - 'Take your workspace to the next level'
+  - 'Streamline your workflow'
+  - 'This comprehensive guide will'
+  - 'Without further ado'
+  - 'In conclusion'
+  - 'To summarize'
+  - "As we've seen"
+  - 'Needless to say'
+  - 'As a matter of fact'
+  - 'Generally speaking'
+  - 'It is worth mentioning'
+  - 'Game-changer'
+  - 'Cutting-edge'
+  - 'Groundbreaking'

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

@@ -0,0 +1,136 @@
+extends: capitalization
+message: "Use sentence case for headings. '%s' should be '%s'."
+level: error
+scope: heading
+match: $sentence
+indicators:
+  - ':'
+exceptions:
+  - Nx
+  - Nx Cloud
+  - Nx Console
+  - Nx Agents
+  - Nx Replay
+  - AI
+  - CI
+  - CD
+  - API
+  - APIs
+  - URL
+  - URLs
+  - CLI
+  - PR
+  - PRs
+  - IDE
+  - TypeScript
+  - JavaScript
+  - Angular
+  - React
+  - Vue
+  - Nuxt
+  - Vite
+  - Webpack
+  - Rspack
+  - Rollup
+  - ESLint
+  - Prettier
+  - GitHub
+  - GitHub Actions
+  - GitLab
+  - BitBucket
+  - BitBucket Cloud
+  - Azure DevOps
+  - Azure
+  - Docker
+  - Dockerfile
+  - Kubernetes
+  - Gradle
+  - Maven
+  - Node.js
+  - Deno
+  - Bun
+  - pnpm
+  - npm
+  - Yarn
+  - Next.js
+  - Remix
+  - Astro
+  - Storybook
+  - Jest
+  - Vitest
+  - Cypress
+  - Playwright
+  - Express
+  - Fastify
+  - Nest.js
+  - NestJS
+  - Expo
+  - React Native
+  - Module Federation
+  - IntelliJ
+  - VS Code
+  - VSCode
+  - WebStorm
+  - Turborepo
+  - Lerna
+  - Bazel
+  - JSON
+  - YAML
+  - TOML
+  - CSS
+  - HTML
+  - SSR
+  - SSG
+  - MFE
+  - DTE
+  - SWC
+  - Rsbuild
+  - Rolldown
+  # Abbreviations and acronyms
+  - AI
+  - UI
+  - DX
+  - ID
+  - FAQ
+  - SAML
+  - DPE
+  - WSL
+  - EJS
+  - AST
+  - TTG
+  - PATs
+  - IDEs
+  - MCP
+  - HTTP
+  - HTTPS
+  - INI
+  - VCS
+  - LTS
+  - DTS
+  - SVG
+  - SVGs
+  - SVGR
+  - EAS
+  - iOS
+  - AWS
+  - S3
+  - E2E
+  - TL;DR
+  - NuGet
+  - MongoDB
+  - OpenShift
+  - Vercel
+  - Netlify
+  # Proper nouns
+  - RxJS
+  - JetBrains
+  - Neovim
+  - PnP
+  - Self-Healing
+  - AMD64
+  - ARM64
+  # Filenames and env vars
+  - SELF_HEALING.md
+  - CLAUDE.md
+  - NODE_AUTH_TOKEN
+  - NX_REJECT_UNKNOWN_LOCAL_CACHE

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

@@ -0,0 +1,20 @@
+extends: existence
+message: "Avoid marketing language '%s'. Be specific about what the feature does instead."
+level: suggestion
+ignorecase: true
+tokens:
+  - 'effortless'
+  - 'effortlessly'
+  - 'seamless'
+  - 'seamlessly'
+  - 'powerful'
+  - 'robust'
+  - 'comprehensive'
+  - 'leverage'
+  - 'utilize'
+  - 'facilitate'
+  - 'aforementioned'
+  - 'best-in-class'
+  - 'world-class'
+  - 'next-level'
+  - 'supercharge'

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

@@ -0,0 +1,25 @@
+extends: existence
+message: "Prefer active voice. '%s' could be rewritten."
+level: suggestion
+ignorecase: true
+tokens:
+  - 'is cached by'
+  - 'is built by'
+  - 'is run by'
+  - 'is executed by'
+  - 'is generated by'
+  - 'is created by'
+  - 'is managed by'
+  - 'is handled by'
+  - 'is provided by'
+  - 'is configured by'
+  - 'is determined by'
+  - 'is computed by'
+  - 'is resolved by'
+  - 'is stored by'
+  - 'are cached by'
+  - 'are built by'
+  - 'are run by'
+  - 'are executed by'
+  - 'are generated by'
+  - 'are created by'

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

@@ -0,0 +1,9 @@
+extends: substitution
+message: "Use '%s' instead of '%s'. Product names must be capitalized."
+level: error
+ignorecase: false
+swap:
+  '(?:nx cloud|NX Cloud|Nx cloud|NX cloud)': Nx Cloud
+  '(?:nx console|NX Console|Nx console|NX console)': Nx Console
+  '(?:nx agents|NX Agents|Nx agents|NX agents)': Nx Agents
+  '(?:nx replay|NX Replay|Nx replay|NX replay)': Nx Replay

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

@@ -0,0 +1,6 @@
+extends: existence
+message: "Don't use possessives on product names. Use 'the Nx configuration' instead of 'Nx's configuration'."
+level: error
+ignorecase: false
+tokens:
+  - "Nx's"

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

@@ -0,0 +1,26 @@
+extends: existence
+message: "Don't write about the document itself. Get right to the content. Remove '%s'."
+level: error
+ignorecase: true
+tokens:
+  - 'This page explains'
+  - 'This page describes'
+  - 'This page covers'
+  - 'This page shows'
+  - 'This document covers'
+  - 'This document explains'
+  - 'This document describes'
+  - 'In this guide'
+  - 'In this tutorial'
+  - 'In this section'
+  - 'This guide will'
+  - 'This tutorial will'
+  - 'This section will'
+  - "we'll walk through"
+  - 'we will walk through'
+  - "we'll explore"
+  - 'we will explore'
+  - "we'll cover"
+  - 'we will cover'
+  - "we'll look at"
+  - 'we will look at'

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

@@ -0,0 +1,14 @@
+extends: existence
+message: "Rewrite to lead with the reader's action instead of '%s'. For example, 'You can ...' or 'Run ...'."
+level: warning
+ignorecase: true
+tokens:
+  - 'This allows you to'
+  - 'This enables you to'
+  - 'This lets you'
+  - 'This provides you with'
+  - 'This gives you the ability to'
+  - 'Nx allows you to'
+  - 'Nx enables you to'
+  - 'Nx provides the ability to'
+  - 'Nx provides you with'

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

@@ -0,0 +1,7 @@
+extends: existence
+message: "Use the Oxford (serial) comma before 'and' or 'or' in a list of three or more items."
+level: suggestion
+scope: sentence
+tokens:
+  - '\w+,\s\w+\sand\s'
+  - '\w+,\s\w+\sor\s'

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

@@ -0,0 +1,9 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+ignorecase: true
+swap:
+  schematic: generator
+  schematics: generators
+  memoized: cached
+  stored results: cached

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

@@ -0,0 +1,11 @@
+extends: existence
+message: "Avoid '%s'. If something were truly simple, you wouldn't need to document it."
+level: suggestion
+ignorecase: true
+tokens:
+  - 'easily'
+  - 'simply'
+  - 'straightforward'
+  - 'obviously'
+  - 'of course'
+  - 'trivial'

astro-docs/README.md

@@ -22,6 +22,48 @@ This documentation site leverages Astro's static site generation capabilities wi
 - Dynamic API documentation generation from Nx packages and CLI commands
 - Community plugin registry
 
+## Information Architecture Principles
+
+When creating or reorganizing documentation, follow these 5 principles to determine where content belongs.
+
+### 1. Progressive Disclosure (The "Journey" Rule)
+
+- **Concept:** Don't overwhelm the user. Reveal complexity only as they advance in their journey.
+- **The Test:** _Is this for the First 30 Minutes (Getting Started), the First 30 Days (Features), or Forever (Reference)?_
+
+### 2. Category Homogeneity (The "Scan" Rule)
+
+- **Concept:** Items in a list must be of the same "type" (noun, verb, or concept) to reduce cognitive load.
+- **The Test:** _Does this list mix Concepts (Mental Model), Tasks (Update Nx), and Products (React)? If yes, split it._
+
+### 3. Type-Based Navigation (The "Intent" Rule)
+
+- **Concept:** Separate **Learning** (Narrative/Guides) from **Looking Up** (Reference/API).
+- **The Test:** _Is the user here to learn a workflow (Guide) or look up a flag syntax (Reference)?_
+
+### 4. The Pen & Paper Test (The "Theory" Rule)
+
+- **Concept:** Distinguish Architecture from Features to keep "Core Concepts" pure.
+- **The Test:** _Can I explain this using only a pen and paper?_
+- **Yes:** It goes in **How Nx Works** (Architecture).
+- **No (I need a terminal):** It goes in **Platform Features** (Feature).
+
+### 5. Universal vs. Specific (The "Placement" Rule)
+
+- **Concept:** Distinguish Platform features from Ecosystem tools to prevent "Features" from becoming a junk drawer.
+- **The Test:** _Does this feature apply to EVERY user (e.g., Caching, Agents)?_
+- **Yes:** **Platform Features**.
+- **No (Only React users):** **Technologies**.
+
+### Sidebar Structure
+
+The sidebar has 4 top-level sections that follow the user journey:
+
+1. **Getting Started** - Essential setup, tutorials, and core concepts (How Nx Works, Platform Features)
+2. **Technologies** - Framework and tool-specific guides (React, Angular, Node, build tools, test tools)
+3. **Knowledge Base** - Recipes, troubleshooting, and topic-specific guides
+4. **Reference** - Exhaustive facts, no narrative (CLI commands, configuration, API docs)
+
 ## Project Structure
 
 ```
@@ -36,9 +78,9 @@ astro-docs/
 │   │   ├── markdoc/     # Markdoc tag components
 │   │   └── utils/       # Utility functions
 │   ├── content/         # Documentation content
+│   │   ├── banner.json  # Banner collection (generated by prebuild-banner)
 │   │   ├── docs/        # Main documentation files (.mdoc, .mdx)
-│   │   ├── approved-community-plugins.json               # Powers plugin registry
-│   │   └── notifications.json                            # Notifications banners for docs site
+│   │   └── approved-community-plugins.json  # Powers plugin registry
 │   ├── pages/           # Dynamic pages and routes (e.g. devkit)
 │   ├── plugins/         # Content loaders and plugins
 │   │   ├── *.loader.ts  # Dynamic content loaders (e.g. CLI commands and API docs generation)
@@ -66,13 +108,11 @@ The site uses custom content loaders to dynamically generate documentation:
 ### Content Types
 
 1. **Regular Documentation** (`src/content/docs/`)
-
    - Written in `.mdoc` (Markdoc) or `.mdx` (MDX) format
    - Organized by sections: getting-started, concepts, guides, api
    - File-based routing (filename = URL path)
 
 2. **Dynamic Plugin Documentation**
-
    - Auto-generated from Nx packages
    - Includes generators, executors, and migrations
    - Updated during build process
@@ -233,3 +273,96 @@ export const sidebar = [
 - Navigation structure
 - Section organization
 - Dynamic content injection points
+
+## Banner Configuration
+
+The floating banner promotes events/webinars. It's fetched at **build time** from a Framer CMS page and stored as an Astro content collection.
+
+### Setup
+
+Set `BANNER_URL` to point to a Framer page that renders banner JSON:
+
+```
+BANNER_URL=https://your-framer-site.framer.app/api/banners/main
+```
+
+The Framer page should render JSON inside a `<pre>` tag:
+
+```json
+{
+  "title": "Event Title",
+  "description": "Event description",
+  "primaryCtaUrl": "https://...",
+  "primaryCtaText": "Learn More",
+  "secondaryCtaUrl": "",
+  "secondaryCtaText": "",
+  "enabled": true,
+  "activeUntil": "2025-12-31T00:00:00.000Z"
+}
+```
+
+### Schema
+
+| Field              | Type     | Required | Description               |
+| ------------------ | -------- | -------- | ------------------------- |
+| `title`            | string   | Yes      | Banner headline           |
+| `description`      | string   | Yes      | Banner body text          |
+| `primaryCtaUrl`    | string   | Yes      | Primary button URL        |
+| `primaryCtaText`   | string   | Yes      | Primary button text       |
+| `secondaryCtaUrl`  | string   | No       | Secondary button URL      |
+| `secondaryCtaText` | string   | No       | Secondary button text     |
+| `enabled`          | boolean  | Yes      | Show/hide the banner      |
+| `activeUntil`      | ISO 8601 | No       | Auto-hide after this date |
+
+### Behavior
+
+- Banner is fetched during `prebuild-banner` target and saved to `src/content/banner.json` as a collection (array)
+- Uses Astro content collection with `file()` loader and schema validation
+- Requires rebuild/redeploy to update the banner
+- Users can dismiss the banner (stored in localStorage)
+- If `enabled` is `false` or `activeUntil` has passed, the banner won't show
+- If `BANNER_URL` is not set, an empty collection is generated
+
+## Versioned Docs
+
+When a new major Nx version is released (or about to be released), create a versioned snapshot of the docs site so the previous version remains accessible at `{major}.nx.dev` (e.g. `22.nx.dev`).
+
+### Creating a Version Snapshot
+
+```bash
+node ./scripts/create-versioned-docs.mts 22
+```
+
+This will:
+
+1. Fetch tags from origin, find the latest stable release for that major (e.g. `22.6.4`)
+2. Checkout that tag, install deps, and build the docs site
+3. Create an orphan git branch `22` containing only the pre-built static site plus minimal scaffolding (root `package.json`, `nx.json`, `pnpm-lock.yaml`, `netlify.toml`, and a no-op `nx-dev` project) so Netlify's configured build command succeeds instantly
+4. Return to your original branch
+
+If no stable tags exist for that major version, it builds from the current branch.
+
+For Nx 21+, the script builds `astro-docs` (Astro/Starlight). For legacy Nx 18–20, it builds `nx-dev` (Next.js with static export) — this path will be removed once those versions are no longer maintained.
+
+#### Flags
+
+- `--force` — overwrite an existing local/remote `{major}` branch
+- `--redirect-to-prod` — skip the build and produce a branch that 301s every path to `https://nx.dev/docs`. Used to retire an old versioned subdomain (e.g. `16.nx.dev`) without maintaining its docs
+
+```bash
+# Retire an old versioned site
+node ./scripts/create-versioned-docs.mts 16 --redirect-to-prod
+```
+
+### Pushing the Branch
+
+```bash
+git push -f origin 22
+```
+
+### Deployment Setup
+
+Versioned sites are served via Netlify branch deploys of the main `nx-dev` Netlify site, with custom domains managed in Squarespace.
+
+- **Netlify** — each `{major}` branch is deployed as a [branch deploy](https://docs.netlify.com/site-deploys/overview/#branch-deploy-controls) of the `nx-dev` site. The branch's root `netlify.toml` overrides the UI build settings so Netlify serves the pre-built static files (no rebuild, no `@netlify/plugin-nextjs`). Add the branch to the site's branch deploy allowlist, then add `{major}.nx.dev` as a domain alias pointing at the branch deploy
+- **Squarespace** — DNS for `nx.dev` is managed in Squarespace. Add a CNAME for `{major}` pointing at the Netlify branch deploy hostname

astro-docs/STYLE_GUIDE.md

@@ -0,0 +1,424 @@
+# 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.
+
+## Information architecture
+
+When creating or reorganizing documentation, follow these five principles to determine where content belongs.
+
+### 1. Progressive disclosure (the "journey" rule)
+
+Don't overwhelm the user. Reveal complexity only as they advance in their journey.
+
+**The test:** Is this for the first 30 minutes (Getting Started), the first 30 days (Features), or forever (Reference)?
+
+### 2. Category homogeneity (the "scan" rule)
+
+Items in a list must be of the same "type" (noun, verb, or concept) to reduce cognitive load.
+
+**The test:** Does this list mix concepts (mental model), tasks (update Nx), and products (React)? If yes, split it.
+
+### 3. Type-based navigation (the "intent" rule)
+
+Separate learning (narrative/guides) from looking up (reference/API).
+
+**The test:** Is the user here to learn a workflow (guide) or look up a flag syntax (reference)?
+
+### 4. The pen and paper test (the "theory" rule)
+
+Distinguish architecture from features to keep "core concepts" pure.
+
+**The test:** Can I explain this using only a pen and paper?
+
+- Yes: It goes in **How Nx Works** (architecture).
+- No (I need a terminal): It goes in **Platform Features** (feature).
+
+### 5. Universal vs. specific (the "placement" rule)
+
+Distinguish platform features from ecosystem tools to prevent "Features" from becoming a junk drawer.
+
+**The test:** Does this feature apply to every user (e.g., caching, Nx Agents)?
+
+- Yes: **Platform Features**.
+- No (only React users): **Technologies**.
+
+### Sidebar structure
+
+The sidebar has four top-level sections that follow the user journey:
+
+1. **Getting Started** - Essential setup, tutorials, and core concepts (How Nx Works, Platform Features)
+2. **Technologies** - Framework and tool-specific guides (React, Angular, Node, build tools, test tools)
+3. **Knowledge Base** - Recipes, troubleshooting, and topic-specific guides
+4. **Reference** - Exhaustive facts, no narrative (CLI commands, configuration, API docs)
+
+## 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.
+
+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.
+- **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.
+
+### Voice do's and don'ts
+
+| Do                                                                       | Don't                                                                                               |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| "You can speed up builds by enabling remote caching."                    | "Nx allows you to speed up builds."                                                                 |
+| "Run `nx build` to build your project."                                  | "In order to build your project, you can run the `nx build` command."                               |
+| "This works best with fewer than 50 projects."                           | "This feature can easily scale to any number of projects."                                          |
+| "Nx reads your `vite.config.ts` and infers build targets automatically." | "Nx provides a robust and comprehensive mechanism for inferring build targets."                     |
+| "If the cache is stale, delete `.nx/cache` and retry."                   | "Should you encounter issues with caching, you may want to consider clearing your cache directory." |
+
+### 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.
+
+**Never use these phrases:**
+
+- "It's important to note that..."
+- "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..."
+- "Whether you're a beginner or an experienced developer..."
+- "In today's fast-paced development environment..."
+- "Unlock the power of..." / "Harness the power of..."
+- "Take your workspace to the next level"
+- "Streamline your workflow" (as a generic claim without specifics)
+- "This comprehensive guide will..."
+- "Without further ado..."
+- "In conclusion..." / "To summarize..." / "As we've seen..."
+- "Game-changer" / "Cutting-edge" / "Groundbreaking"
+- "Seamless" / "Seamlessly" (unless describing an actual integration)
+
+**Avoid hedging words unless genuinely needed:**
+
+- "Essentially" / "Basically" / "Effectively"
+- "Generally speaking"
+- "It is worth mentioning"
+- "Arguably"
+- "Needless to say"
+- "As a matter of fact"
+
+**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.
+- 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."
+- Lists where every item starts with the same grammatical structure repeated 5+ times with slight variation. Vary your phrasing.
+
+### Self-referential writing
+
+Don't write about the document itself.
+
+Do:
+
+- "Nx uses a project graph to determine task dependencies."
+
+Don't:
+
+- "This page explains how Nx uses a project graph."
+- "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.
+
+### 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 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."
+
+### Customer perspective
+
+Focus on what the reader can do, not what Nx does.
+
+Do:
+
+- "Use `nx affected` to run tasks only for projects impacted by your changes."
+
+Don't:
+
+- "Nx allows you to run affected tasks."
+- "Nx provides the ability to run tasks selectively."
+
+Words like "allow" and "enable" are signals you're writing from the product's perspective instead of the reader's.
+
+## Language
+
+Write in US English.
+
+### Active voice
+
+Use active voice in most cases.
+
+Do: "Nx caches the build output."
+Don't: "The build output is cached by Nx."
+
+Exception: When "Nx" as the subject sounds awkward, passive voice is fine. "The output is stored in `.nx/cache`" is better than "Nx stores the output in `.nx/cache`" if Nx isn't the focus of the sentence.
+
+### Contractions
+
+Use contractions. They make the text feel natural.
+
+- "You'll need to configure..." not "You will need to configure..."
+- "It doesn't support..." not "It does not support..."
+
+Don't contract for emphasis in warnings or error descriptions:
+
+- "**Do not** delete the `nx.json` file."
+- "Requests to localhost **are not** allowed."
+
+Don't contract proper nouns: "the Vite plugin is..." not "Vite's a plugin..."
+
+### Capitalization
+
+Use sentence case for headings. Capitalize proper nouns only.
+
+- `# Use remote caching to speed up CI`
+- `## Configure the Vite plugin`
+
+Feature names are lowercase unless they are a proper product name:
+
+| Correct        | Incorrect      |
+| -------------- | -------------- |
+| remote caching | Remote Caching |
+| project graph  | Project Graph  |
+| Nx Cloud       | nx cloud       |
+| Nx Console     | nx console     |
+| Nx Agents      | nx agents      |
+| Nx Replay      | nx replay      |
+
+### Acronyms
+
+Spell out acronyms on first use per page. Don't spell out widely-known ones: CI, CD, API, URL, CLI, PR, IDE.
+
+Don't make acronyms plural with apostrophes. Use `APIs`, not `API's`.
+
+### Numbers
+
+Spell out zero through nine. Use numerals for 10 and above. Always use numerals with units: "5 minutes", "3 projects."
+
+### Possessives
+
+Don't use possessives on product names. "the Docker CLI", not "Docker's CLI." "the Nx configuration", not "Nx's configuration."
+
+## Text
+
+### Headings
+
+- Don't skip heading levels (e.g., `##` to `####`).
+- Don't use code in headings unless it's essential (like a CLI command).
+- Don't use bold text in headings.
+- Keep headings short and scannable. Lead with keywords.
+
+### Line length
+
+- Wrap lines at approximately 100 characters for readability in diffs.
+- Start each new sentence on a new line.
+- Exception: Don't break links across lines.
+
+### Punctuation
+
+- Use serial (Oxford) commas: "React, Angular, and Vue."
+- Use one space between sentences.
+- Don't use semicolons. Use two sentences instead.
+- Don't use em dashes or en dashes. Use commas or separate sentences.
+
+### Placeholder text
+
+Use `<` and `>` for values the reader must replace:
+
+```shell
+nx run <project-name>:build
+```
+
+If the placeholder is inline, wrap it in a single backtick: `<your-project>`.
+
+### Bold
+
+Use bold for:
+
+- UI elements: "Select **Add Connection**."
+- Navigation paths: "Go to **Settings** > **Workspace**."
+
+Don't use bold for emphasis or keywords. If you need emphasis, rewrite the sentence to be clearer.
+
+### Inline code
+
+Use inline code (single backticks) for:
+
+- Commands and CLI arguments: `nx build`, `--parallel`
+- File names and paths: `nx.json`, `.nx/cache`
+- Configuration keys: `targetDefaults`, `namedInputs`
+- Short outputs and values: `true`, `false`, `success`
+
+### Code blocks
+
+Use triple backticks with a language identifier:
+
+````markdown
+```json
+{
+  "targetDefaults": {
+    "build": {
+      "cache": true
+    }
+  }
+}
+```
+````
+
+- Always specify a syntax language. Use `plaintext` if nothing else fits.
+- Add a blank line before and after code blocks.
+- For long config files, show only the relevant section and use comments to indicate omitted parts:
+
+```json
+{
+  // ... other config
+  "targetDefaults": {
+    "build": {
+      "cache": true
+    }
+  }
+}
+```
+
+## Links
+
+Links help readers find related information, but too many links make text hard to read.
+
+### General rules
+
+- Don't duplicate links. If you link to a page once, don't link to it again on the same page.
+- Don't use links in headings.
+- Avoid more than 15 links to other pages on any single page.
+- Avoid multiple links in a single paragraph when possible.
+
+### Link text
+
+Use descriptive text, not "here" or "this page."
+
+Do:
+
+- "For more information, see [remote caching](/features/cache)."
+- "To configure task pipelines, see [task pipeline configuration](/concepts/task-pipeline-configuration)."
+
+Don't:
+
+- "For more information, see [this page](/features/cache)."
+- "Click [here](/features/cache) to learn more."
+- "For more information, see the [Remote Caching](/features/cache) documentation."
+
+Standard patterns:
+
+- `For more information, see [link text](url).`
+- `To <do this thing>, see [link text](url).`
+
+### External links
+
+Minimize external links. They break over time and are hard to maintain. When you must link externally, prefer official documentation (e.g., Vite docs, Webpack docs) over blog posts or third-party guides.
+
+## Lists
+
+- Use ordered lists for sequences of steps.
+- Use unordered lists when order doesn't matter.
+- Use dashes (`-`) for unordered lists.
+- Start ordered list items with `1.` (Markdown auto-increments).
+- Make list items parallel in structure.
+- Add a colon after the introductory phrase.
+- Don't use list items to complete an introductory sentence.
+
+Do:
+
+```markdown
+You can clear the cache in the following ways:
+
+- Delete the `.nx/cache` directory manually.
+- Run `nx reset` to clear all cached results.
+```
+
+Don't:
+
+```markdown
+You can clear the cache by:
+
+- Deleting the `.nx/cache` directory manually.
+- Running `nx reset`.
+```
+
+## Tables
+
+Use tables for structured data that benefits from a matrix layout. For simple lists of items with descriptions, use a regular list instead.
+
+- Don't leave cells empty. Use "N/A" or "None."
+- Use sentence case for headers.
+- Keep the header and delimiter rows the same length.
+
+## Nx-specific terminology
+
+Use these terms consistently. When writing about Nx concepts, use the exact term from this list.
+
+| Term           | Usage notes                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------ |
+| workspace      | The root directory managed by Nx. Not "repo" or "monorepo" when referring to Nx's context. |
+| project        | An app or library within the workspace.                                                    |
+| target         | A task that can be run for a project (e.g., `build`, `test`, `lint`).                      |
+| executor       | The implementation behind a target. Not "builder."                                         |
+| generator      | Code scaffolding tool. Not "schematic."                                                    |
+| plugin         | An Nx plugin that provides executors, generators, or graph inference.                      |
+| task           | A specific invocation of a target for a project (e.g., `myapp:build`).                     |
+| project graph  | The dependency graph between projects.                                                     |
+| affected       | Projects impacted by a code change.                                                        |
+| cache / cached | Not "memoized" or "stored results."                                                        |
+| remote caching | Sharing cached results across machines. Specific product: "Nx Replay."                     |
+| Nx Cloud       | The hosted CI/CD product. Always capitalized.                                              |
+| Nx Console     | The IDE extension. Always capitalized.                                                     |
+| Nx Agents      | Distributed task execution product. Always capitalized.                                    |
+| Nx Replay      | Remote caching product. Always capitalized.                                                |
+| `nx.json`      | Always in code style.                                                                      |
+| `project.json` | Always in code style.                                                                      |
+
+## Vale configuration
+
+[Vale](https://vale.sh) enforces many of the rules in this style guide 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.
+
+### Running Vale
+
+```shell
+# Via Nx target (recommended)
+nx vale astro-docs
+
+# Directly (from astro-docs/ directory)
+vale src/content/docs/
+```
+
+### Installing Vale
+
+Vale is managed via [mise](https://mise.jdx.dev/). Run `mise install` from the repo root to install it.
+You can also install directly via `brew install vale` (macOS) or `apt-get install vale` (Linux).
+
+### 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                   |
+
+### Adding new rules
+
+Create a new `.yml` file in `.vale/styles/Nx/`.
+Vale supports several [extension points](https://vale.sh/docs/styles): `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, and `metric`.
+
+Set `level` to match the tier: `error` for mechanical rules, `warning` for structural, `suggestion` for voice/judgment.

astro-docs/astro.config.mjs

@@ -5,15 +5,19 @@ import netlify from '@astrojs/netlify';
 import react from '@astrojs/react';
 import markdoc from '@astrojs/markdoc';
 import tailwindcss from '@tailwindcss/vite';
+import sitemap from '@astrojs/sitemap';
 import { sidebar } from './sidebar.mts';
+import rehypeTableOptionLinks from './src/plugins/utils/rehype-table-option-links.ts';
+import { resolveNxDevUrl } from './src/utils/resolve-nx-dev-url.ts';
+
+// Always resolve NX_DEV_URL so downstream consumers (Footer, Header) pick it up.
+// For deploy previews this overrides any site-level env var to point to the matching preview.
+process.env.NX_DEV_URL = resolveNxDevUrl();
 
 const BASE = '/docs';
 
 // This is exposed as window.__CONFIG
 const PUBLIC_CONFIG = {
-  cookiebotDisabled: process.env.COOKIEBOT_DISABLED === 'true',
-  cookiebotId: process.env.COOKIEBOT_ID ?? null,
-  gaMeasurementId: 'UA-88380372-10',
   gtmMeasurementId: 'GTM-KW8423B6',
   isProd: process.env.NODE_ENV === 'production',
 };
@@ -22,7 +26,7 @@ const PUBLIC_CONFIG = {
 export default defineConfig({
   base: BASE,
   vite: { plugins: [tailwindcss()] },
-  // Allow this to be configured per environment
+  // Allow this to be configured per environment for robots.txt detection
   // Note: this happens during build time so we don't use `import.meta.env`
   site: process.env.NX_DEV_URL ?? 'https://nx.dev',
   image: {
@@ -33,6 +37,9 @@ export default defineConfig({
       },
     },
   },
+  markdown: {
+    rehypePlugins: [rehypeTableOptionLinks],
+  },
   trailingSlash: 'never',
   // This adapter doesn't support local previews, so only load it on Netlify.
   adapter: process.env['NETLIFY'] ? netlify() : undefined,
@@ -51,27 +58,12 @@ export default defineConfig({
         replacesTitle: true,
       },
       disable404Route: true,
+      lastUpdated: true,
       head: [
         {
           tag: 'script',
           content: `window.__CONFIG = ${JSON.stringify(PUBLIC_CONFIG)};`,
         },
-        ...(process.env.COOKIEBOT_ID &&
-        process.env.COOKIEBOT_DISABLED !== 'true'
-          ? [
-              {
-                /** @type {"script"} */
-                tag: 'script',
-                attrs: {
-                  id: 'Cookiebot',
-                  src: 'https://consent.cookiebot.com/uc.js',
-                  'data-cbid': process.env.COOKIEBOT_ID,
-                  'data-blockingmode': 'auto',
-                  type: 'text/javascript',
-                },
-              },
-            ]
-          : []),
         {
           tag: 'script',
           attrs: {
@@ -82,20 +74,19 @@ export default defineConfig({
       ],
       plugins: [],
       routeMiddleware: [
-        './src/plugins/banner.middleware.ts',
         // NOTE: this is responsibile for populating the Reference section
         // with generated routes from the nx-reference-packages content collection
         // since the sidebar doesn't auto generate w/ dynamic routes from src/pages/reference
         // only the src/content/docs/reference files
         './src/plugins/sidebar-reference-updater.middleware.ts',
-        './src/plugins/sidebar-icons.middleware.ts',
         './src/plugins/og.middleware.ts',
+        './src/plugins/github-stars.middleware.ts',
+        './src/plugins/raw-content.middleware.ts',
+        './src/plugins/canonical.middleware.ts',
+        './src/plugins/schema.middleware.ts',
       ],
       markdown: {
-        // this breaks the renderMarkdown function in the plugin loader due to starlight path normalization
-        // as to _why_ it has to normalize a path?
-        // idk just working around the issue for now but we'll want to have linked headers so will need to fix
-        headingLinks: false,
+        headingLinks: true,
       },
       social: [
         { icon: 'github', label: 'GitHub', href: 'https://github.com/nrwl/nx' },
@@ -134,15 +125,15 @@ export default defineConfig({
           // frequency of the term relative to document length
           // versus weighted term count.
           // default is 1.0
-          termFrequency: 0.75,
+          termFrequency: 0.65,
           // pageLength changes the way ranking compares page lengths with the average page lengths on your site.
           // default 0.75
-          pageLength: 0.5,
+          pageLength: 0.3,
           // termSaturation controls how quickly a term “saturates” on a page.
           // Once a term has appeared on a page many times,
           // further appearances have a reduced impact on the page rank.
           // default: 1.4
-          // termSaturation: 1.4,
+          termSaturation: 1.2,
           // termSimilarity changes the ranking based on
           // similarity of terms to the search query.
           // Currently this only takes the length of the term into account.
@@ -152,5 +143,8 @@ export default defineConfig({
       },
     }),
     react(),
+    sitemap({
+      lastmod: new Date(),
+    }),
   ],
 });

astro-docs/e2e/cli-subcommand-formatting.spec.ts

@@ -0,0 +1,129 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('CLI sub-command formatting', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/docs/reference/nx-commands');
+    await expect(
+      page.getByRole('heading', { name: 'Nx Commands' })
+    ).toBeVisible();
+  });
+
+  test('parent commands render as h2 and sub-commands as h3', async ({
+    page,
+  }) => {
+    const mainContent = page.getByTestId('main-pane');
+
+    // "nx show" should be an h2 (top-level parent command)
+    const showHeading = mainContent.getByRole('heading', {
+      name: 'nx show',
+      level: 2,
+      exact: true,
+    });
+    await expect(showHeading).toBeVisible();
+
+    // "nx show projects" should be an h3 (sub-command nested under parent)
+    const showProjectsHeading = mainContent.getByRole('heading', {
+      name: 'nx show projects',
+      level: 3,
+      exact: true,
+    });
+    await expect(showProjectsHeading).toBeVisible();
+
+    // "nx show project" should also be an h3
+    const showProjectHeading = mainContent.getByRole('heading', {
+      name: 'nx show project',
+      level: 3,
+      exact: true,
+    });
+    await expect(showProjectHeading).toBeVisible();
+  });
+
+  test('sub-command usage blocks show the full command name', async ({
+    page,
+  }) => {
+    const mainContent = page.getByTestId('main-pane');
+
+    // Find the "nx show projects" section and verify its usage block
+    // The usage code block should contain "nx show projects", not "nx projects"
+    const showProjectsHeading = mainContent.getByRole('heading', {
+      name: 'nx show projects',
+      level: 3,
+      exact: true,
+    });
+    await expect(showProjectsHeading).toBeVisible();
+
+    // Get the section between "nx show projects" heading and the next heading.
+    // We look for a code block containing the correct usage pattern.
+    const codeBlocks = mainContent.locator('pre code');
+    const allCodeTexts = await codeBlocks.allTextContents();
+
+    // There should be a usage block with "nx show projects" (full sub-command name)
+    expect(allCodeTexts.some((text) => text.includes('nx show projects'))).toBe(
+      true
+    );
+
+    // There should NOT be a usage block with just "nx projects" (missing parent)
+    expect(
+      allCodeTexts.some(
+        (text) => text.match(/^nx projects/) || text.match(/\nnx projects/)
+      )
+    ).toBe(false);
+  });
+
+  test('release sub-commands use correct heading and usage format', async ({
+    page,
+  }) => {
+    const mainContent = page.getByTestId('main-pane');
+
+    // "nx release" should be h2
+    const releaseHeading = mainContent.getByRole('heading', {
+      name: 'nx release',
+      level: 2,
+      exact: true,
+    });
+    await expect(releaseHeading).toBeVisible();
+
+    // "nx release version" should be h3
+    const releaseVersionHeading = mainContent.getByRole('heading', {
+      name: 'nx release version',
+      level: 3,
+      exact: true,
+    });
+    await expect(releaseVersionHeading).toBeVisible();
+
+    // Verify usage block includes the full command
+    const codeBlocks = mainContent.locator('pre code');
+    const allCodeTexts = await codeBlocks.allTextContents();
+
+    expect(
+      allCodeTexts.some((text) => text.includes('nx release version'))
+    ).toBe(true);
+  });
+
+  test('options and examples are h4 headings excluded from the TOC', async ({
+    page,
+  }) => {
+    const mainContent = page.getByTestId('main-pane');
+
+    // Options/Examples should be h4 headings — linkable but below the TOC threshold (h2-h3)
+    const sharedOptionsHeading = mainContent.getByRole('heading', {
+      name: 'Shared Options',
+      level: 4,
+    });
+    await expect(sharedOptionsHeading.first()).toBeVisible();
+
+    const optionsHeading = mainContent.getByRole('heading', {
+      name: 'Options',
+      level: 4,
+    });
+    await expect(optionsHeading.first()).toBeVisible();
+
+    // They should NOT appear as h2 or h3 (which would put them in the TOC)
+    await expect(
+      mainContent.getByRole('heading', { name: 'Options', level: 2 })
+    ).toHaveCount(0);
+    await expect(
+      mainContent.getByRole('heading', { name: 'Options', level: 3 })
+    ).toHaveCount(0);
+  });
+});

astro-docs/e2e/devkit-urls-fragments.spec.ts

@@ -11,7 +11,7 @@ test('links in descriptions of properties should correctly link to the same page
 
   await page
     .getByTestId('main-pane')
-    .getByRole('link', { name: 'nxCloudAccessToken' })
+    .getByRole('link', { name: 'nxCloudAccessToken', exact: true })
     .click();
 
   await expect(

astro-docs/markdoc.config.mjs

@@ -4,9 +4,15 @@ import {
   Markdoc,
 } from '@astrojs/markdoc/config';
 import starlightMarkdoc from '@astrojs/starlight-markdoc';
+import { transformOptionsTable } from './src/utils/markdoc-table-option-links';
 
 export default defineMarkdocConfig({
   extends: [starlightMarkdoc()],
+  nodes: {
+    table: {
+      transform: transformOptionsTable,
+    },
+  },
   tags: {
     call_to_action: {
       render: component('./src/components/markdoc/CallToAction.astro'),
@@ -238,6 +244,15 @@ export default defineMarkdocConfig({
         },
       },
     },
+    sidebar_group_cards: {
+      render: component('./src/components/markdoc/SidebarGroupCards.astro'),
+      attributes: {
+        group: {
+          type: 'String',
+          required: true,
+        },
+      },
+    },
     metrics: {
       render: component('./src/components/markdoc/Metrics.astro'),
       attributes: {
@@ -402,6 +417,40 @@ export default defineMarkdocConfig({
         },
       },
     },
+    llm_copy_prompt: {
+      render: component('./src/components/markdoc/LlmCopyPrompt.astro'),
+      attributes: {
+        title: { type: 'String', required: true },
+      },
+      children: ['paragraph', 'tag', 'list'],
+      transform(node, config) {
+        const attributes = node.transformAttributes(config);
+        function extractText(n) {
+          if (typeof n === 'string') return n;
+          if (n.type === 'text' || n.type === 'softbreak')
+            return n.attributes?.content ?? '\n';
+          if (n.type === 'inline')
+            return (n.children || []).map(extractText).join('');
+          if (n.type === 'paragraph')
+            return (n.children || []).map(extractText).join('') + '\n';
+          if (n.type === 'item')
+            return '- ' + (n.children || []).map(extractText).join('');
+          if (n.type === 'list')
+            return (n.children || []).map(extractText).join('\n') + '\n';
+          if (n.children) return n.children.map(extractText).join('');
+          return '';
+        }
+        const promptText = node.children.map(extractText).join('\n').trim();
+        return new Markdoc.Tag(this.render, { ...attributes, promptText }, []);
+      },
+    },
+    llm_only: {
+      attributes: {},
+      children: ['paragraph', 'tag', 'list'],
+      transform() {
+        return null;
+      },
+    },
     youtube: {
       render: component('./src/components/markdoc/Youtube.astro'),
       attributes: {

astro-docs/netlify.toml

@@ -1,4 +1,27 @@
+[[headers]]
+  for = "/*"
+  [headers.values]
+    X-Frame-Options = "DENY"
+    Content-Security-Policy = "frame-ancestors 'none'"
+    Referrer-Policy = "strict-origin-when-cross-origin"
+    Permissions-Policy = "camera=(), microphone=(), geolocation=()"
+
+# Disable gradle and maven plugins on Netlify
+# (Netlify only supports Java 8 but these plugins require Java 17)
+[build.environment]
+NX_GRADLE_DISABLE = "true"
+NX_MAVEN_DISABLE = "true"
+
+# Edge functions are auto-discovered from netlify/edge-functions/
+# Path configuration is in each function's inline `config` export
+
 # Permanent redirects (301 by default)
+
+# Storybook docs consolidation
+[[redirects]]
+from = "/docs/technologies/test-tools/storybook/guides/storybook-9-setup"
+to = "/docs/technologies/test-tools/storybook/guides/upgrading-storybook"
+
 [[redirects]]
 from = "/"
 to = "/docs/getting-started/intro"
@@ -15,6 +38,46 @@ to = "/docs/quickstart"
 from = "/showcase/benchmarks/*"
 to = "/docs/reference/benchmarks/:splat"
 
+# DOC-452: Old framework tutorials redirect to new topic-based tutorials
+[[redirects]]
+from = "/docs/getting-started/tutorials/react-monorepo-tutorial"
+to = "/docs/getting-started/tutorials/crafting-your-workspace"
+
+[[redirects]]
+from = "/docs/getting-started/tutorials/angular-monorepo-tutorial"
+to = "/docs/getting-started/tutorials/crafting-your-workspace"
+
+[[redirects]]
+from = "/docs/getting-started/tutorials/typescript-packages-tutorial"
+to = "/docs/getting-started/tutorials/crafting-your-workspace"
+
+# DOC-452: Learn Nx URLs redirect to Tutorials (in case any were indexed)
+[[redirects]]
+from = "/docs/getting-started/learn-nx/*"
+to = "/docs/getting-started/tutorials/:splat"
+
+# Fix broken /docs/ paths still linked from CLI/Cloud source code (DOC-428)
+[[redirects]]
+from = "/docs/features/ci-features/self-healing"
+to = "/docs/features/ci-features/self-healing-ci"
+
+[[redirects]]
+from = "/docs/extending-nx/recipes/create-preset"
+to = "/docs/extending-nx/create-preset"
+
+[[redirects]]
+from = "/docs/guides/adopting-nx/adding-to-monorepos"
+to = "/docs/guides/adopting-nx/adding-to-monorepo"
+
+# Angular multiple workspace migration page removed (DOC-419)
+[[redirects]]
+from = "/docs/technologies/angular/migration/angular-multiple"
+to = "/docs/technologies/angular/migration/angular"
+
+[[redirects]]
+from = "/docs/getting-started/nx-cloud"
+to = "/docs/features/ci-features"
+
 # Rewrite for base path handling (keeps URL the same)
 [[redirects]]
 from = "/docs/*"

astro-docs/netlify/edge-functions/add-link-headers.ts

@@ -0,0 +1,59 @@
+import type { Context } from 'https://edge.netlify.com';
+
+/**
+ * Content negotiation for LLM-friendly docs access.
+ * See: https://llmstxt.org/
+ */
+export default async function handler(
+  request: Request,
+  context: Context
+): Promise<Response | URL> {
+  const url = new URL(request.url);
+  const pathname = url.pathname;
+
+  const acceptHeader = request.headers.get('accept') || '';
+
+  // Serve markdown for LLM tools that explicitly request it
+  // Or if there are no accept headers passed (e.g. Cursor)
+  if (!acceptHeader || acceptHeader.includes('text/markdown')) {
+    const mdPath = pathname.replace(/\/?$/, '.md');
+    return new URL(mdPath, request.url);
+  }
+
+  const response = await context.next();
+
+  const contentType = response.headers.get('content-type') || '';
+  if (!contentType.includes('text/html')) {
+    return response;
+  }
+
+  const mdPath = pathname.replace(/\/?$/, '.md');
+
+  const linkHeader = [
+    `<${mdPath}>; rel="alternate"; type="text/markdown"`,
+    `</docs/llms.txt>; rel="alternate"; type="text/markdown"; title="LLM Index"`,
+    `</docs/llms-full.txt>; rel="alternate"; type="text/markdown"; title="Full Documentation"`,
+  ].join(', ');
+
+  // Netlify responses are immutable
+  const newHeaders = new Headers(response.headers);
+  newHeaders.set('Link', linkHeader);
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: newHeaders,
+  });
+}
+
+export const config = {
+  path: ['/docs/*'],
+  excludedPath: [
+    '/docs/*.md',
+    '/docs/*.js',
+    '/docs/*.txt',
+    '/docs/images/*',
+    // _astro and other asset paths
+    '/docs/_*',
+  ],
+};

astro-docs/package.json

@@ -7,6 +7,7 @@
     "@astrojs/markdoc": "^0.15.0",
     "@astrojs/netlify": "^6.4.0",
     "@astrojs/react": "^4.3.0",
+    "@astrojs/sitemap": "^3.3.0",
     "@astrojs/starlight": "0.34.6",
     "@astrojs/starlight-markdoc": "^0.4.0",
     "@astrojs/starlight-tailwind": "^4.0.1",
@@ -16,9 +17,11 @@
     "@nx/nx-dev-ui-icons": "workspace:*",
     "@nx/nx-dev-ui-markdoc": "workspace:*",
     "@tailwindcss/vite": "^4.1.11",
+    "@types/hast": "^3.0.4",
     "astro": "^5.10.1",
     "astro-og-canvas": "^0.7.0",
     "canvaskit-wasm": "^0.40.0",
+    "octokit": "^2.0.14",
     "tailwindcss": "4.1.11"
   }
 }

astro-docs/project.json

@@ -3,11 +3,30 @@
   "$schema": "../node_modules/nx/schemas/project-schema.json",
   "comment": "package.json#scripts runs in the project root directory with astro assumes is where the node_modules is. which fails. so run the scripts in project.json#targets with --root command instead",
   "targets": {
+    "prebuild-banner": {
+      "cache": false,
+      "outputs": ["{projectRoot}/src/content/banner.json"],
+      "command": "node ../scripts/documentation/prebuild-banner.mjs",
+      "options": {
+        "cwd": "astro-docs",
+        "env": {
+          "BANNER_OUTPUT_PATH": "src/content/banner.json",
+          "BANNER_ENV_VAR": "BANNER_URL"
+        }
+      }
+    },
     "serve": {
       "continuous": true,
       "dependsOn": [
+        "prebuild-banner",
         {
-          "projects": ["devkit", "create-nx-workspace", "dotnet", "maven"],
+          "projects": [
+            "nx",
+            "devkit",
+            "create-nx-workspace",
+            "dotnet",
+            "maven"
+          ],
           "target": "build"
         }
       ],
@@ -18,11 +37,24 @@
     },
     "build": {
       "dependsOn": [
+        "prebuild-banner",
         {
-          "projects": ["devkit", "create-nx-workspace", "dotnet", "maven"],
+          "projects": [
+            "nx",
+            "devkit",
+            "create-nx-workspace",
+            "dotnet",
+            "maven"
+          ],
           "target": "build"
         }
       ],
+      "inputs": [
+        "production",
+        "^production",
+        "{projectRoot}/src/content/banner.json",
+        { "env": "NX_DEV_URL" }
+      ],
       "outputs": [
         "{projectRoot}/dist",
         "{projectRoot}/.astro",
@@ -49,7 +81,7 @@
     },
     "test": {
       "executor": "nx:noop",
-      "dependsOn": ["vite:test", "validate-links", "format"]
+      "dependsOn": ["validate-links", "format"]
     },
     "pw-e2e": {
       "dependsOn": ["serve"],
@@ -69,6 +101,8 @@
       "dependsOn": ["build"],
       "cache": true,
       "inputs": [
+        "{projectRoot}/validate-links.ts",
+        { "dependentTasksOutputFiles": "**/sitemap*.xml" },
         "{projectRoot}/src/**/*",
         "{projectRoot}/astro.config.mjs",
         "{projectRoot}/sidebar.mts",
@@ -81,10 +115,44 @@
         "cwd": "astro-docs"
       }
     },
+    "vale": {
+      "command": "node scripts/vale-changed.mjs",
+      "options": {
+        "cwd": "{projectRoot}"
+      },
+      "cache": true,
+      "inputs": [
+        "{projectRoot}/src/content/docs/**/*.mdoc",
+        "{projectRoot}/src/content/docs/**/*.mdx",
+        "{projectRoot}/src/content/docs/**/*.md",
+        "{projectRoot}/.vale.ini",
+        "{projectRoot}/.vale/styles/**/*",
+        "{projectRoot}/scripts/vale-changed.mjs"
+      ]
+    },
+    "vale:all": {
+      "command": "node scripts/vale-changed.mjs --all",
+      "options": {
+        "cwd": "{projectRoot}"
+      },
+      "inputs": [
+        "{projectRoot}/src/content/docs/**/*.mdoc",
+        "{projectRoot}/src/content/docs/**/*.mdx",
+        "{projectRoot}/src/content/docs/**/*.md",
+        "{projectRoot}/.vale.ini",
+        "{projectRoot}/.vale/styles/**/*",
+        "{projectRoot}/scripts/vale-changed.mjs"
+      ]
+    },
     "format": {
       "cache": true,
       "//": "nx format doesn't respect overrides, so we manually run prettier for mdoc files",
-      "command": "prettier **/*.mdoc --check"
+      "command": "prettier **/*.mdoc --check",
+      "inputs": [
+        "{projectRoot}/**/*.mdoc",
+        "{workspaceRoot}/.prettierrc",
+        "{workspaceRoot}/.prettierignore"
+      ]
     },
     "format:write": {
       "command": "prettier **/*.mdoc --write"

astro-docs/public/global-scripts.js

@@ -1,32 +1,46 @@
 (function () {
+  // Open search modal if signaled via sessionStorage (e.g., from Cmd+K on non-docs pages)
+  var SEARCH_STORAGE_KEY = 'nx-open-search';
+  var SEARCH_EXPIRY_MS = 30000; // 30 seconds
+
+  function openSearchFromStorage() {
+    var timestamp = sessionStorage.getItem(SEARCH_STORAGE_KEY);
+    if (!timestamp) return;
+
+    // Clear immediately to prevent re-triggering
+    sessionStorage.removeItem(SEARCH_STORAGE_KEY);
+
+    // Check if expired (older than 30 seconds)
+    var age = Date.now() - parseInt(timestamp, 10);
+    if (age > SEARCH_EXPIRY_MS) return;
+
+    var openSearchBtn = document.querySelector('button[data-open-modal]');
+    if (openSearchBtn) {
+      openSearchBtn.click();
+      // Focus the search input after modal opens
+      setTimeout(function () {
+        var searchInput = document.querySelector('dialog[open] input');
+        if (searchInput) {
+          searchInput.focus();
+        }
+      }, 100);
+    }
+  }
+
+  // Check on load
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', openSearchFromStorage);
+  } else {
+    // Small delay to ensure search component is initialized
+    setTimeout(openSearchFromStorage, 100);
+  }
+
   const config = window.__CONFIG || {};
   if (!config.isProd) return;
 
-  const isCookiebotDisabled = config.cookiebotDisabled ?? false;
-  const gaMeasurementId = config.gaMeasurementId ?? 'UA-88380372-10';
   const gtmMeasurementId = config.gtmMeasurementId ?? 'GTM-KW8423B6';
 
-  // Initialize global objects
-  window.Cookiebot = window.Cookiebot || {};
   window.dataLayer = window.dataLayer || [];
-  window.gtag =
-    window.gtag ||
-    function () {
-      window.dataLayer.push(arguments);
-    };
-
-  const loadGoogleAnalytics = () => {
-    const script = document.createElement('script');
-    script.src = `https://www.googletagmanager.com/gtag/js?id=${gaMeasurementId}`;
-    script.async = true;
-    document.head.appendChild(script);
-
-    // Initialize gtag
-    window.gtag('js', new Date());
-    window.gtag('config', gaMeasurementId, {
-      page_path: window.location.pathname,
-    });
-  };
 
   const loadGTM = () => {
     if (!gtmMeasurementId) return;
@@ -43,80 +57,92 @@
     })(window, document, 'script', 'dataLayer', gtmMeasurementId);
   };
 
-  const loadHubSpot = () => {
-    const hsScript = document.createElement('script');
-    hsScript.src = 'https://js.hs-scripts.com/2757427.js';
-    hsScript.async = true;
-    hsScript.defer = true;
-    document.head.appendChild(hsScript);
-
-    // Load HubSpot Forms
-    const hsFormsScript = document.createElement('script');
-    hsFormsScript.src = '//js.hsforms.net/forms/v2.js';
-    hsFormsScript.async = true;
-    hsFormsScript.defer = true;
-    document.head.appendChild(hsFormsScript);
+  // GA4 events are dispatched via GTM dataLayer.
+  const pushGtmEvent = (eventName, payload) => {
+    window.dataLayer.push({ event: eventName, ...payload });
   };
 
-  const loadApollo = () => {
-    const n = Math.random().toString(36).substring(7);
-    const script = document.createElement('script');
-    script.src = `https://assets.apollo.io/micro/website-tracker/tracker.iife.js?nocache=${n}`;
-    script.async = true;
-    script.defer = true;
-    script.onload = function () {
-      if (window.trackingFunctions?.onLoad) {
-        window.trackingFunctions.onLoad({
-          appId: '65e1db2f1976f30300fd8b26',
+  // Scroll depth tracking
+  const SCROLL_THRESHOLDS = [10, 25, 50, 75, 90];
+  let firedThresholds = new Set();
+  let scrollTrackingEnabled = false;
+  let scrollRafId = null;
+
+  function getScrollPercentage() {
+    const scrollTop = window.scrollY || document.documentElement.scrollTop;
+    const scrollHeight = document.documentElement.scrollHeight;
+    const clientHeight = window.innerHeight;
+    return (scrollTop + clientHeight) / scrollHeight;
+  }
+
+  function handleScrollTracking() {
+    if (!scrollTrackingEnabled) return;
+
+    const scrollPercentage = getScrollPercentage() * 100;
+
+    // Fire events for all thresholds we've passed but haven't fired yet
+    for (const threshold of SCROLL_THRESHOLDS) {
+      if (scrollPercentage >= threshold && !firedThresholds.has(threshold)) {
+        firedThresholds.add(threshold);
+        sendSearchEvent(`scroll_${threshold}`, {
+          event_category: 'scroll',
+          event_label: window.location.pathname,
         });
       }
-    };
-    document.head.appendChild(script);
-  };
+    }
+  }
 
-  const loadHotjar = () => {
-    (function (h, o, t, j, a, r) {
-      h.hj =
-        h.hj ||
-        function () {
-          (h.hj.q = h.hj.q || []).push(arguments);
-        };
-      h._hjSettings = { hjid: 2774127, hjsv: 6 };
-      a = o.getElementsByTagName('head')[0];
-      r = o.createElement('script');
-      r.async = 1;
-      r.src = t + h._hjSettings.hjid + j + h._hjSettings.hjsv;
-      a.appendChild(r);
-    })(window, document, 'https://static.hotjar.com/c/hotjar-', '.js?sv=');
-  };
+  function throttledScrollHandler() {
+    if (scrollRafId !== null) return;
 
-  const loadTwitterPixel = () => {
-    !(function (e, t, n, s, u, a) {
-      e.twq ||
-        ((s = e.twq =
-          function () {
-            s.exe ? s.exe.apply(s, arguments) : s.queue.push(arguments);
-          }),
-        (s.version = '1.1'),
-        (s.queue = []),
-        (u = t.createElement(n)),
-        (u.async = !0),
-        (u.src = 'https://static.ads-twitter.com/uwt.js'),
-        (a = t.getElementsByTagName(n)[0]),
-        a.parentNode.insertBefore(u, a));
-    })(window, document, 'script');
-    window.twq('config', 'obtp4');
-  };
+    scrollRafId = requestAnimationFrame(() => {
+      handleScrollTracking();
+      scrollRafId = null;
+    });
+  }
+
+  function attachScrollListener() {
+    window.addEventListener('scroll', throttledScrollHandler, {
+      passive: true,
+    });
+  }
+
+  function setupScrollTracking() {
+    // Reset scroll depth on navigation (for SPA-like behavior via View Transitions)
+    firedThresholds = new Set();
+    scrollTrackingEnabled = false;
+
+    // Delay tracking start to avoid false triggers during navigation
+    setTimeout(() => {
+      scrollTrackingEnabled = true;
+      // Immediately check current scroll position to capture thresholds
+      // that may have been passed during the delay
+      handleScrollTracking();
+    }, 500);
+
+    attachScrollListener();
+
+    // Handle Astro View Transitions - reset on navigation
+    document.addEventListener('astro:after-swap', () => {
+      firedThresholds = new Set();
+      scrollTrackingEnabled = false;
+      setTimeout(() => {
+        scrollTrackingEnabled = true;
+        // Immediately check current scroll position after navigation
+        handleScrollTracking();
+      }, 500);
+    });
+  }
 
   const SEARCH_DEBOUNCE_MS = 1000;
   let searchDebounceTimer;
   let lastSearchQuery = '';
   let currentSearchInput = null;
   let inputHandler = null;
+  let resultClickHandler = null;
 
   function sendSearchEvent(eventType, data) {
-    if (typeof window.gtag !== 'undefined')
-      window.gtag('event', eventType, data);
+    pushGtmEvent(eventType, data);
   }
 
   function trackSearchQuery(query) {
@@ -125,8 +151,8 @@
     clearTimeout(searchDebounceTimer);
     searchDebounceTimer = setTimeout(() => {
       lastSearchQuery = query;
-      sendSearchEvent('search_query', {
-        query: query,
+      sendSearchEvent('search', {
+        search_term: query,
       });
     }, SEARCH_DEBOUNCE_MS);
   }
@@ -150,12 +176,30 @@
           searchInput.addEventListener('input', inputHandler);
           currentSearchInput = searchInput;
         }
+
+        // Track search result clicks via event delegation
+        if (!resultClickHandler) {
+          resultClickHandler = (e) => {
+            const link = e.target.closest('a[href]');
+            if (!link) return;
+            const query = currentSearchInput
+              ? currentSearchInput.value.trim()
+              : '';
+            pushGtmEvent('select_content', {
+              content_type: 'search_result',
+              item_id: link.getAttribute('href'),
+              search_term: query,
+            });
+          };
+          searchDialog.addEventListener('click', resultClickHandler);
+        }
       }
       // If dialog is not found but we have handler, etc. then it must be closed and we should clean up
       else if (currentSearchInput && inputHandler) {
         currentSearchInput.removeEventListener('input', inputHandler);
         currentSearchInput = null;
         inputHandler = null;
+        resultClickHandler = null;
       }
     });
 
@@ -167,31 +211,11 @@
     });
   }
 
-  const checkAndLoadScripts = () => {
-    if (isCookiebotDisabled) {
-      loadGoogleAnalytics();
-      loadGTM();
-      loadHubSpot();
-      setupSearchTracking();
-    } else if (window.Cookiebot && window.Cookiebot.consent) {
-      // Statistics cookies (Google Analytics, GTM, Search Tracking)
-      if (window.Cookiebot.consent.statistics) {
-        loadGoogleAnalytics();
-        loadGTM();
-        setupSearchTracking();
-      }
-
-      // Marketing cookies (HubSpot, Apollo, Hotjar, Twitter)
-      if (window.Cookiebot.consent.marketing) {
-        loadHubSpot();
-        loadApollo();
-        loadHotjar();
-        loadTwitterPixel();
-      }
-    } else {
-      // Wait for Cookiebot to load
-      setTimeout(checkAndLoadScripts, 100);
-    }
+  const initializeAnalytics = () => {
+    if (!gtmMeasurementId) return;
+    loadGTM();
+    setupSearchTracking();
+    setupScrollTracking();
   };
 
   // Add GTM noscript iframe to body
@@ -208,11 +232,8 @@
     document.body.insertBefore(noscript, document.body.firstChild);
   };
 
-  // Listen for user consent to cookies
-  window.addEventListener('CookiebotOnAccept', checkAndLoadScripts);
-
   // Initial check
-  checkAndLoadScripts();
+  initializeAnalytics();
 
   // Add GTM noscript on DOM ready
   if (document.readyState === 'loading') {

astro-docs/public/images/icons/java.svg

@@ -1,9 +1 @@
-<svg
-  role="img"
-  viewBox="0 0 24 24"
-  xmlns="http://www.w3.org/2000/svg"
-  fill="currentColor"
->
-    <title>Java</title>
-    <path d="m16.5093 4.9869-.0607-.0347c-1.1014.369-4.4915 1.707-4.4915 4.202 0 1.411 1.378 2.1925 1.378 3.5158 0 .472-.2666.9146-.4836 1.1791l.1091.063c.5735-.3728 1.589-1.18 1.589-2.2222 0-.8825-1.2216-1.943-1.2216-3.0774 0-1.7875 2.357-3.1899 3.1813-3.6256zm-1.6642-3.27c0 3.6925-5.0604 5.1055-5.0604 7.7309 0 1.843 1.2222 2.9987 1.8983 3.7293l-.055.0317c-.8536-.534-3.0995-1.876-3.0995-4.0927 0-3.112 5.8123-4.599 5.8123-8.134 0-.435-.0644-.7683-.1095-.9482L14.2901 0c.1842.2315.555.8102.555 1.7168m.514 14.9392c-.5962.1688-1.9389.4441-3.859.4441-1.8844 0-3.424-.3226-3.4289-.7024-.0032-.2527.3024-.3628.3024-.3628l-.0544-.0316c-.9023.1595-1.7406.406-1.7357.7752.0084.6698 2.5697 1.1728 4.9129 1.1728 1.992 0 3.9053-.3343 4.7684-.7722zm-6.368 2.0708c-.4185.0832-1.3305.2926-1.3305.7361 0 .6144 1.9513 1.085 3.835 1.085 2.5922 0 3.6539-.667 3.702-.7016l-1.078-.6235c-.4583.1092-1.2306.2808-2.6214.2808-1.5521 0-2.5634-.2658-2.5634-.5569 0-.0617.0386-.135.1106-.1886zm10.5923-4.1337c-.0725 1.3911-1.3577 2.2573-2.6423 2.9893l.1164.067c1.3708-.3855 3.8166-1.5085 3.6144-3.2346-.1007-.8608-.8875-1.4758-1.9133-1.4758-.3194 0-.6036.0563-.834.1265l-.0007.0022-.0486.1224c.9175-.1796 1.7558.4904 1.7082 1.403zm-8.1232 8.1638c3.6058-.0313 7.6402-.737 7.6298-1.9232-.0019-.215-.1418-.3622-.2635-.4513l-.0592.034c-.3333.9188-3.1508 1.5977-7.3132 1.634-2.6859.0234-6.4063-.62-6.4128-1.3636-.0065-.7455 1.7625-1.1552 1.7625-1.1552l-.125-.0714c-1.1854.1632-3.3697.731-3.3625 1.5506.0104 1.185 5.0304 1.7734 8.1439 1.7461zm-.375.847c-1.4333.0126-3.1833-.1061-4.6555-.3535l-.1363.0784c1.4664.43 3.508.6896 5.7514.6702 4.4059-.0386 7.9779-1.1311 8.0485-2.446l-.051-.0297c-.2953.3604-2.2009 2.0216-8.9572 2.0806zm-5.5195-9.328c0-.6646 2.521-1.0374 3.6947-1.1277l.112.0647c-.451.082-2.26.401-2.26.8172 0 .4532 2.7747.7501 4.3853.7501 2.7355 0 4.595-.414 5.095-.5505l.6997.4072c-.4792.2346-2.5362.8495-5.7945.8495-3.6214 0-5.9322-.7086-5.9322-1.2105" />
-</svg>
+<svg fill="#000000" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M 16.921875 2.25 C 16.71679725 2.26171875 16.4970705 2.3408205 16.2890625 2.5078125 C 15.40722675 3.2138669999999996 15.541992 3.5771482499999996 15.1171875 4.4296875 C 14.973633 4.9248045 14.736328499999999 4.962891 14.53125 4.5234375 C 14.28515625 4.08691425 14.16503925 3.5419919999999996 13.78125 3.2109375 C 13.16308575 2.67773475 12.4658205 3.0791017500000004 12.84375 3.6796875 C 13.2216795 4.28027325 13.376953499999999 4.91308575 13.5234375 5.90625 C 13.74316425 7.3857420000000005 13.125 9.03222675 12.3046875 9.8203125 C 10.822266 6.7880857500000005 8.885742 4.53808575 7.5234375 3.84375 C 7.1103517499999995 3.6328125 6.984375 3.80859375 6.984375 4.0078125 C 7.2421875 6.978516000000001 7.3359375 9.02929725 7.171875 10.546875 C 7.0986329999999995 11.2265625 5.49609375 13.734375 5.578125 14.3203125 C 5.66015625 14.9033205 6.12890625 15.817383 6.4453125 16.2890625 C 6.31640625 16.1953125 5.99121075 16.4091795 6.0703125 16.7109375 C 5.49902325 17.03027325 5.551758 17.51953125 6.140625 17.6484375 C 6.29296875 18.0439455 6.3251954999999995 18.24023475 6.75 18.421875 C 6.66796875 19.25683575 6.580078500000001 20.11523475 6.4921875 21.046875 C 6.873047250000001 22.921875 9.776367 19.67871075 10.1484375 19.40625 C 12.161133 17.9296875 12.46875 21.15234375 13.875 21.65625 C 16.2421875 22.5029295 15.474609749999999 17.52246075 13.5703125 12.6328125 C 13.34472675 9.489258 14.40234375 8.59277325 15.421875 8.1796875 C 15.958008 8.00390625 16.3564455 7.96875 17.0859375 8.1796875 C 18.33984375 8.54003925 18.60058575 7.11328125 17.484375 6.9375 C 17.0595705 6.8701170000000005 16.7519535 6.8759767499999995 16.359375 6.703125 C 16.5175785 6.0732420000000005 17.14453125 6.041016000000001 17.765625 5.953125 C 19.17773475 5.75390625 19.0546875 4.23046875 17.484375 4.59375 C 16.7988285 4.754883 16.49121075 5.16210975 16.2421875 5.15625 C 16.56152325 4.573242 17.10058575 4.072266 17.625 3.328125 C 18.0175785 2.7685545 17.5341795 2.21484375 16.921875 2.25 Z M 9.6328125 7.734375 C 9.817383 7.7109375 9.978516 7.72265625 10.1484375 7.78125 C 10.8251955 8.009766 11.05371075 8.87109375 10.640625 9.6796875 C 10.22753925 10.48828125 9.3251955 10.9394535 8.6484375 10.7109375 C 7.9716795000000005 10.48242225 7.7666017499999995 9.64453125 8.1796875 8.8359375 C 8.49023475 8.229492 9.07910175 7.8076170000000005 9.6328125 7.734375 Z M 8.90625 8.8359375 C 8.80371075 8.838867 8.698242 8.89746075 8.6015625 9 C 8.4082035 9.208008 8.34375 9.55078125 8.4609375 9.75 C 8.5810545 9.94921875 8.8300785 9.9345705 9.0234375 9.7265625 C 9.21679725 9.5185545 9.2841795 9.17578125 9.1640625 8.9765625 C 9.10546875 8.8769535 9.00878925 8.833008 8.90625 8.8359375 Z M 11.390625 10.7578125 C 12.521484749999999 12.919922249999999 13.587890999999999 15.48046875 13.8046875 18.3984375 C 13.90722675 19.78710975 12.791015999999999 18.28710975 12.65625 18.046875 C 10.359375 13.91015625 7.4091795000000005 22.40625 7.9921875 17.0859375 C 8.2939455 14.89453125 8.4404295 14.604492 8.5078125 12.046875 C 8.5078125 12.046875 10.265625 12.963867 11.390625 10.7578125 Z M 7.21875 13.2890625 C 7.1630857500000005 14.0126955 7.1484375 14.490234749999999 7.078125 15.234375 C 6.9228517499999995 14.830078499999999 6.7177732500000005 14.7890625 6.609375 14.4140625 C 6.8349607500000005 14.16796875 6.990234750000001 13.6875 7.21875 13.2890625 Z"/></svg>

astro-docs/public/robots.txt

@@ -1,9 +0,0 @@
-# *
-User-agent: *
-Allow: /
-
-# Host
-Host: https://nx.dev
-
-# Sitemaps
-Sitemap: https://nx.dev/sitemap-index.xml

astro-docs/scripts/vale-changed.mjs

@@ -0,0 +1,19 @@
+/**
+ * Run Vale on all docs files.
+ *
+ * Exit codes mirror Vale: 1 = errors found (fail CI), 0 = warnings/suggestions only or clean.
+ */
+import { execSync } from 'child_process';
+
+try {
+  execSync('vale src/content/docs/', { stdio: 'inherit' });
+} catch (err) {
+  if (err.status === 1) {
+    console.log(
+      '\nVale found errors. Fix all error-level violations before committing.'
+    );
+    process.exit(1);
+  }
+  // Exit code 2 = warnings/suggestions only — don't fail
+  process.exit(0);
+}

astro-docs/src/assets/concepts/synthetic-monorepo.svg

@@ -0,0 +1,122 @@
+<svg width="980" height="720" viewBox="0 0 980 720" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Defs: arrow markers -->
+  <defs>
+    <marker id="arrowBlue" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto" markerUnits="strokeWidth">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#476088"/>
+    </marker>
+    <marker id="arrowGreen" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto" markerUnits="strokeWidth">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#70AF40"/>
+    </marker>
+  </defs>
+
+  <!-- Outer dotted border: Synthetic Monorepo boundary -->
+  <rect x="40" y="40" width="900" height="590" rx="24" ry="24"
+        stroke="#94A3B8" stroke-width="3" stroke-dasharray="12 6" fill="none"/>
+
+  <!-- "Synthetic Monorepo" label at bottom inside box -->
+  <text x="490" y="665" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="26" font-weight="700" fill="#94A3B8">Synthetic Monorepo</text>
+
+  <!-- ============================================ -->
+  <!-- Monorepo A (top-left): a rounded rect with 3 internal projects -->
+  <!-- ============================================ -->
+  <rect x="80" y="70" width="260" height="200" rx="16" ry="16"
+        stroke="#9CA3AF" stroke-width="2" fill="none"/>
+  <text x="210" y="100" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="600" fill="#9CA3AF">Monorepo A</text>
+
+  <!-- App 1 (blue) -->
+  <circle cx="140" cy="165" r="38" fill="#476088"/>
+  <text x="140" y="161" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">App 1</text>
+  <text x="140" y="178" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#CBD5E1">frontend</text>
+
+  <!-- Lib A (green) -->
+  <circle cx="270" cy="145" r="32" fill="#70AF40"/>
+  <text x="270" y="141" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">Lib A</text>
+  <text x="270" y="157" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#E8F5E9">utils</text>
+
+  <!-- Lib B (green) -->
+  <circle cx="248" cy="222" r="28" fill="#70AF40"/>
+  <text x="248" y="218" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="12" font-weight="600" fill="white">Lib B</text>
+  <text x="248" y="233" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="10" fill="#E8F5E9">ui</text>
+
+  <!-- Internal arrows within Monorepo A -->
+  <line x1="175" y1="155" x2="238" y2="143" stroke="#9CA3AF" stroke-width="1.5" marker-end="url(#arrowBlue)" opacity="0.4"/>
+  <line x1="165" y1="190" x2="225" y2="212" stroke="#9CA3AF" stroke-width="1.5" marker-end="url(#arrowBlue)" opacity="0.4"/>
+
+  <!-- ============================================ -->
+  <!-- Monorepo B (right): a rounded rect with 2 internal projects -->
+  <!-- ============================================ -->
+  <rect x="640" y="70" width="260" height="200" rx="16" ry="16"
+        stroke="#9CA3AF" stroke-width="2" fill="none"/>
+  <text x="770" y="100" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="600" fill="#9CA3AF">Monorepo B</text>
+
+  <!-- App 2 (blue) -->
+  <circle cx="710" cy="170" r="38" fill="#476088"/>
+  <text x="710" y="166" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">App 2</text>
+  <text x="710" y="183" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#CBD5E1">backend</text>
+
+  <!-- Lib C (green) -->
+  <circle cx="840" cy="185" r="32" fill="#70AF40"/>
+  <text x="840" y="181" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">Lib C</text>
+  <text x="840" y="197" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#E8F5E9">auth</text>
+
+  <!-- Internal arrow within Monorepo B -->
+  <line x1="745" y1="175" x2="808" y2="182" stroke="#9CA3AF" stroke-width="1.5" marker-end="url(#arrowBlue)" opacity="0.4"/>
+
+  <!-- ============================================ -->
+  <!-- Standalone repos -->
+  <!-- ============================================ -->
+
+  <!-- Lib D (green, standalone, CENTER - pushed down to middle row) -->
+  <circle cx="490" cy="340" r="38" fill="#70AF40"/>
+  <text x="490" y="336" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">Lib D</text>
+  <text x="490" y="352" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#E8F5E9">shared</text>
+  <text x="490" y="390" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" font-weight="500" fill="#9CA3AF">standalone repo</text>
+
+  <!-- App 3 (blue, standalone, bottom-left) -->
+  <circle cx="200" cy="500" r="42" fill="#476088"/>
+  <text x="200" y="496" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">App 3</text>
+  <text x="200" y="513" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#CBD5E1">mobile</text>
+  <text x="200" y="554" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" font-weight="500" fill="#9CA3AF">standalone repo</text>
+
+  <!-- Lib E (green, standalone, bottom-center) -->
+  <circle cx="490" cy="520" r="32" fill="#70AF40"/>
+  <text x="490" y="516" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">Lib E</text>
+  <text x="490" y="532" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#E8F5E9">design</text>
+  <text x="490" y="564" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" font-weight="500" fill="#9CA3AF">standalone repo</text>
+
+  <!-- App 4 (blue, standalone, bottom-right) -->
+  <circle cx="770" cy="500" r="42" fill="#476088"/>
+  <text x="770" y="496" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="white">App 4</text>
+  <text x="770" y="513" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#CBD5E1">API</text>
+  <text x="770" y="554" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" font-weight="500" fill="#9CA3AF">standalone repo</text>
+
+  <!-- ============================================ -->
+  <!-- Cross-repo dependency arrows -->
+  <!-- ============================================ -->
+
+  <!-- App 2 → Lib D (shared): curve down-left -->
+  <path d="M 675 185 C 620 240, 560 280, 525 325" stroke="#476088" stroke-width="2.5" fill="none" marker-end="url(#arrowBlue)"/>
+
+  <!-- Lib A → Lib D: gentle arc down -->
+  <path d="M 300 155 C 370 200, 420 260, 458 322" stroke="#70AF40" stroke-width="2" fill="none" marker-end="url(#arrowGreen)"/>
+
+  <!-- App 3 → Lib B (in Monorepo A): straight up -->
+  <path d="M 210 458 C 220 380, 230 320, 242 252" stroke="#476088" stroke-width="2.5" fill="none" marker-end="url(#arrowBlue)"/>
+
+  <!-- App 3 → Lib E (design): horizontal -->
+  <path d="M 242 500 C 320 490, 400 500, 458 515" stroke="#476088" stroke-width="2.5" fill="none" marker-end="url(#arrowBlue)"/>
+
+  <!-- App 4 → Lib C (in Monorepo B): straight up -->
+  <path d="M 790 458 C 805 380, 820 310, 835 217" stroke="#476088" stroke-width="2.5" fill="none" marker-end="url(#arrowBlue)"/>
+
+  <!-- App 4 → Lib D (shared): arc up-left -->
+  <path d="M 730 490 C 650 460, 570 410, 525 358" stroke="#476088" stroke-width="2.5" fill="none" marker-end="url(#arrowBlue)"/>
+
+  <!-- App 4 → Lib E (design): horizontal left -->
+  <path d="M 728 505 C 660 510, 580 515, 522 518" stroke="#476088" stroke-width="2" fill="none" marker-end="url(#arrowBlue)"/>
+
+  <!-- Lib D → Lib C (cross-repo lib dependency): arc up-right -->
+  <path d="M 525 330 C 620 300, 740 260, 812 200" stroke="#70AF40" stroke-width="2" fill="none" marker-end="url(#arrowGreen)"/>
+
+
+</svg>