@microsoft/agentrc 2.0.1-1 → 2.0.1-3

package/dist/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createRequire as __bannerCreateRequire } from "node:module";
+const require = __bannerCreateRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -5357,7 +5359,8 @@ var PACKAGE_MANAGERS = [
   { file: "pnpm-lock.yaml", name: "pnpm" },
   { file: "yarn.lock", name: "yarn" },
   { file: "package-lock.json", name: "npm" },
-  { file: "bun.lockb", name: "bun" }
+  { file: "bun.lockb", name: "bun" },
+  { file: "packages.lock.json", name: "nuget" }
 ];
 async function analyzeRepo(repoPath) {
   const files = await safeReadDir(repoPath);
@@ -5379,9 +5382,11 @@ async function analyzeRepo(repoPath) {
   const hasRequirements = files.includes("requirements.txt");
   const hasGoMod = files.includes("go.mod");
   const hasCargo = files.includes("Cargo.toml");
-  const hasCsproj = files.some(
-    (f) => f.endsWith(".csproj") || f.endsWith(".sln") || f.endsWith(".slnx")
+  const hasDotnet = files.some(
+    (f) => f.endsWith(".csproj") || f.endsWith(".fsproj") || f.endsWith(".sln") || f.endsWith(".slnx") || f === "global.json" || f === "Directory.Build.props"
   );
+  const hasCsproj = hasDotnet && files.some((f) => f.endsWith(".csproj"));
+  const hasFsproj = files.some((f) => f.endsWith(".fsproj"));
   const hasPomXml = files.includes("pom.xml");
   const hasBuildGradle = files.includes("build.gradle") || files.includes("build.gradle.kts");
   const hasGemfile = files.includes("Gemfile");
@@ -5396,7 +5401,8 @@ async function analyzeRepo(repoPath) {
   if (hasPyProject || hasRequirements) analysis.languages.push("Python");
   if (hasGoMod) analysis.languages.push("Go");
   if (hasCargo) analysis.languages.push("Rust");
-  if (hasCsproj) analysis.languages.push("C#");
+  if (hasCsproj || hasDotnet && !hasFsproj) analysis.languages.push("C#");
+  if (hasFsproj) analysis.languages.push("F#");
   if (hasPomXml || hasBuildGradle) analysis.languages.push("Java");
   if (hasGemfile) analysis.languages.push("Ruby");
   if (hasComposerJson) analysis.languages.push("PHP");
@@ -5412,6 +5418,10 @@ async function analyzeRepo(repoPath) {
     });
     analysis.frameworks.push(...detectFrameworks(deps, files));
   }
+  if (hasDotnet) {
+    const dotnetFrameworks = await detectDotnetFrameworks(repoPath);
+    analysis.frameworks.push(...dotnetFrameworks);
+  }
   const workspace = await detectWorkspace(repoPath, files, rootPackageJson);
   if (workspace) {
     analysis.workspaceType = workspace.type;
@@ -5472,6 +5482,44 @@ function detectFrameworks(deps, files) {
   if (deps.includes("fastify")) frameworks.push("Fastify");
   return frameworks;
 }
+async function detectDotnetFrameworks(repoPath) {
+  const projectFiles = await fg("**/*.{csproj,fsproj}", {
+    cwd: repoPath,
+    onlyFiles: true,
+    ignore: ["**/node_modules/**", "**/bin/**", "**/obj/**"]
+  });
+  const frameworks = [];
+  for (const projFile of projectFiles) {
+    try {
+      const content = await fs2.readFile(path2.join(repoPath, projFile), "utf8");
+      frameworks.push(...parseDotnetProject(content));
+    } catch {
+    }
+  }
+  return frameworks;
+}
+function parseDotnetProject(content) {
+  const frameworks = [];
+  const hasPackage = (pkg) => content.includes(`Include="${pkg}"`);
+  if (content.includes('Sdk="Microsoft.NET.Sdk.Web"')) frameworks.push("ASP.NET Core");
+  if (content.includes('Sdk="Microsoft.NET.Sdk.BlazorWebAssembly"'))
+    frameworks.push("Blazor WebAssembly");
+  if (hasPackage("Microsoft.AspNetCore") || hasPackage("Microsoft.AspNetCore.App"))
+    frameworks.push("ASP.NET Core");
+  if (hasPackage("Microsoft.AspNetCore.Components")) frameworks.push("Blazor");
+  if (hasPackage("Microsoft.EntityFrameworkCore")) frameworks.push("Entity Framework");
+  if (hasPackage("Microsoft.Maui.Controls")) frameworks.push(".NET MAUI");
+  if (hasPackage("Xamarin.Forms") || hasPackage("Xamarin.Essentials")) frameworks.push("Xamarin");
+  if (content.includes("<UseWPF>true</UseWPF>")) frameworks.push("WPF");
+  if (content.includes("<UseWindowsForms>true</UseWindowsForms>")) frameworks.push("Windows Forms");
+  if (hasPackage("xunit") || hasPackage("xunit.core")) frameworks.push("xUnit");
+  if (hasPackage("NUnit") || hasPackage("nunit.framework")) frameworks.push("NUnit");
+  if (hasPackage("MSTest.TestFramework")) frameworks.push("MSTest");
+  if (frameworks.length === 0 && content.includes("<OutputType>Exe</OutputType>") && content.includes('Sdk="Microsoft.NET.Sdk"')) {
+    frameworks.push("Console");
+  }
+  return frameworks;
+}
 async function safeReadFile(filePath) {
   try {
     return await fs2.readFile(filePath, "utf8");
@@ -6631,9 +6679,9 @@ import path9 from "path";
 // packages/core/src/utils/pr.ts
 function buildInstructionsPrBody() {
   return [
-    "## \u{1F916} Copilot Instructions Added",
+    "## \u{1F916} Instructions Added",
     "",
-    "This PR adds a `.github/copilot-instructions.md` file to help GitHub Copilot understand this codebase better.",
+    "This PR adds a `.github/copilot-instructions.md` file to help AI coding assistants understand this codebase better.",
     "",
     "### What's Included",
     "",
@@ -6645,7 +6693,7 @@ function buildInstructionsPrBody() {
     "",
     "### Benefits",
     "",
-    "With these instructions, Copilot will:",
+    "With these instructions, AI coding assistants will:",
     "- Generate more contextually-aware code suggestions",
     "- Follow project-specific patterns and conventions",
     "- Understand the codebase structure",
@@ -6664,7 +6712,7 @@ function buildFullPrBody() {
     "",
     "| File | Purpose |",
     "|------|---------|",
-    "| `.github/copilot-instructions.md` | Custom instructions for GitHub Copilot |",
+    "| `.github/copilot-instructions.md` | Custom instructions for AI coding assistants |",
     "| `.vscode/settings.json` | VS Code settings for optimal AI assistance |",
     "| `.vscode/mcp.json` | Model Context Protocol server configuration |",
     "",
@@ -6678,7 +6726,7 @@ function buildFullPrBody() {
     "",
     "### Benefits",
     "",
-    "With these configurations, Copilot will:",
+    "With these configurations, AI coding assistants will:",
     "- Generate more contextually-aware code suggestions",
     "- Follow project-specific patterns and conventions",
     "- Understand the codebase structure",
@@ -6688,7 +6736,7 @@ function buildFullPrBody() {
     "",
     "1. Merge this PR",
     "2. Open the project in VS Code",
-    "3. Start chatting with Copilot \u2014 it now understands your project!",
+    "3. Start using AI assistants \u2014 they now understand your project!",
     "",
     "---",
     "*Generated by [AgentRC](https://github.com/microsoft/agentrc) - Prime your repos for AI*"
@@ -7163,7 +7211,9 @@ function normalizeError(error) {
 }
 function shouldFallbackToExternalServer(error) {
   const message = normalizeError(error).message.toLowerCase();
-  return message.includes("unknown option '--headless'") || message.includes("unknown option '--no-auto-update'") || message.includes("copilot cli not found");
+  return message.includes("unknown option '--headless'") || message.includes("unknown option '--no-auto-update'") || // SDK's internal CLI resolution couldn't find the binary
+  message.includes("copilot cli not found") || // Node's spawn() can't execute .bat/.cmd directly on Windows
+  message.includes("spawn einval");
 }
 async function startExternalServer(cliConfig) {
   const [cmd, args2] = buildExecArgs(cliConfig, ["--headless", "--log-level", "debug"]);
@@ -7281,8 +7331,11 @@ async function createCopilotClient(cliConfig) {
   const desc = cliConfig.cliArgs ? `${cliConfig.cliPath} ${cliConfig.cliArgs.join(" ")}` : cliConfig.cliPath;
   logCopilotDebug(`creating SDK client with cliPath=${desc} useStdio=false`);
   const isNpx = /\bnpx(?:\.cmd)?$/iu.test(cliConfig.cliPath);
-  if (isNpx) {
-    logCopilotDebug("npx wrapper detected; using external server mode");
+  const isBatShim = process.platform === "win32" && /\.(?:bat|cmd)$/iu.test(cliConfig.cliPath);
+  if (isNpx || isBatShim) {
+    logCopilotDebug(
+      `${isNpx ? "npx wrapper" : ".bat/.cmd shim"} detected; using external server mode directly`
+    );
     const external = await startExternalServer(cliConfig);
     const client = new sdk.CopilotClient({ cliUrl: external.cliUrl });
     try {
@@ -7532,7 +7585,7 @@ async function generateCopilotInstructions(options) {
 
 Fan out multiple Explore subagents to map out the codebase in parallel:
 1. Check for existing instruction files: glob for **/{.github/copilot-instructions.md,AGENT.md,CLAUDE.md,.cursorrules,README.md}
-2. Identify the tech stack: look at package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, *.csproj, *.sln, build.gradle, pom.xml, etc.
+2. Identify the tech stack: look at package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, *.csproj, *.fsproj, *.sln, global.json, build.gradle, pom.xml, etc.
 3. Understand the structure: list key directories
 4. Detect monorepo structures: check for workspace configs (npm/pnpm/yarn workspaces, Cargo.toml [workspace], go.work, .sln solution files, settings.gradle include directives, pom.xml modules)
 
@@ -7578,7 +7631,7 @@ async function generateAreaInstructions(options) {
     const applyToStr = applyToPatterns.join(", ");
     progress(`Creating session for area "${area.name}"...`);
     const preferredModel = options.model ?? DEFAULT_MODEL;
-    const areaSystemContent = hasExistingInstructions ? `You are an expert codebase analyst. Your task is to generate a concise .instructions.md file for a specific area of a codebase. This file will be used as a file-based custom instruction in VS Code Copilot, automatically applied when working on files matching certain patterns. This file should complement, not duplicate, existing instruction files. Use the Explore subagents and read-only tools to explore the codebase. When done, call the emit_file_content tool with the final markdown.` : `You are an expert codebase analyst. Your task is to generate a concise .instructions.md file for a specific area of a codebase. This file will be used as a file-based custom instruction in VS Code Copilot, automatically applied when working on files matching certain patterns. Use the Explore subagents and read-only tools to explore the codebase. When done, call the emit_file_content tool with the final markdown.`;
+    const areaSystemContent = hasExistingInstructions ? `You are an expert codebase analyst. Your task is to generate a concise .instructions.md file for a specific area of a codebase. This file will be used as an area instruction in VS Code, automatically applied when working on files matching certain patterns. This file should complement, not duplicate, existing instruction files. Use the Explore subagents and read-only tools to explore the codebase. When done, call the emit_file_content tool with the final markdown.` : `You are an expert codebase analyst. Your task is to generate a concise .instructions.md file for a specific area of a codebase. This file will be used as an area instruction in VS Code, automatically applied when working on files matching certain patterns. Use the Explore subagents and read-only tools to explore the codebase. When done, call the emit_file_content tool with the final markdown.`;
     const { tool: emitTool, getContent } = await createEmitTool();
     const session = await client.createSession({
       model: preferredModel,
@@ -7611,7 +7664,7 @@ async function generateAreaInstructions(options) {
         sessionError = getSessionError(errorMsg);
       }
     });
-    const prompt = `Analyze the "${area.name}" area of this codebase and generate a file-based instruction file.
+    const prompt = `Analyze the "${area.name}" area of this codebase and generate an area instruction file.
 
 This area covers files matching: ${applyToStr}
 ${area.description ? `Description: ${area.description}` : ""}
@@ -8733,7 +8786,7 @@ function getLevelName(level) {
 function getLevelDescription(level) {
   const descriptions = {
     1: "Repo builds, tests run, and basic tooling (linter, lockfile) is in place. AI agents can clone and get started.",
-    2: "README, CONTRIBUTING guide, and custom AI instructions exist. Agents understand project context and conventions.",
+    2: "README, CONTRIBUTING guide, and custom instructions exist. Agents understand project context and conventions.",
     3: "CI/CD, security policies, CODEOWNERS, and observability are configured. Agents operate within well-defined guardrails.",
     4: "MCP servers, custom agents, and AI skills are set up. Agents have deep integration with project-specific tools and workflows.",
     5: "Full AI-native development: agents can independently plan, implement, test, and ship changes with minimal human oversight."
@@ -9198,7 +9251,7 @@ function buildCriteria() {
     },
     {
       id: "custom-instructions",
-      title: "Custom AI instructions or agent guidance",
+      title: "Custom instructions or agent guidance",
       pillar: "ai-tooling",
       level: 1,
       scope: "repo",
@@ -9209,7 +9262,7 @@ function buildCriteria() {
         if (rootFound.length === 0) {
           return {
             status: "fail",
-            reason: "Missing custom AI instructions (e.g. copilot-instructions.md, CLAUDE.md, AGENTS.md, .cursorrules).",
+            reason: "Missing custom instructions (e.g. copilot-instructions.md, CLAUDE.md, AGENTS.md, .cursorrules).",
             evidence: [
               "copilot-instructions.md",
               "CLAUDE.md",
@@ -9225,13 +9278,13 @@ function buildCriteria() {
           if (fileBasedInstructions.length === 0) {
             return {
               status: "pass",
-              reason: `Root instructions found, but no file-based instructions for ${areas.length} detected areas. Run \`agentrc instructions --areas\` to generate.`,
+              reason: `Root instructions found, but no area instructions for ${areas.length} detected areas. Run \`agentrc instructions --areas\` to generate.`,
               evidence: [...rootFound, ...areas.map((a) => `${a.name}: missing .instructions.md`)]
             };
           }
           return {
             status: "pass",
-            reason: `Root + ${fileBasedInstructions.length} file-based instruction(s) found.`,
+            reason: `Root + ${fileBasedInstructions.length} area instruction(s) found.`,
             evidence: [...rootFound, ...fileBasedInstructions]
           };
         }
@@ -9856,7 +9909,7 @@ async function processRepo(params) {
       );
     }
     progress?.update(`${label}: Committing...`);
-    await commitAll(repoPath, "chore: add copilot instructions via AgentRC");
+    await commitAll(repoPath, "chore: add instructions via AgentRC");
     progress?.update(`${label}: Pushing...`);
     await pushBranch(repoPath, branch, token, provider);
     progress?.update(`${label}: Creating PR...`);
@@ -9892,7 +9945,7 @@ async function processGitHubRepo(options) {
       token,
       owner: repo.owner,
       repo: repo.name,
-      title: "\u{1F916} Add Copilot instructions via AgentRC",
+      title: "\u{1F916} Add instructions via AgentRC",
       body: buildInstructionsPrBody(),
       head: branchName,
       base: repo.defaultBranch
@@ -9924,7 +9977,7 @@ async function processAzureRepo(options) {
       project: repo.project,
       repoId: repo.id,
       repoName: repo.name,
-      title: "\u{1F916} Add Copilot instructions via AgentRC",
+      title: "\u{1F916} Add instructions via AgentRC",
       body: buildInstructionsPrBody(),
       sourceBranch: branchName,
       targetBranch: repo.defaultBranch
@@ -11039,11 +11092,7 @@ import path10 from "path";
 
 // packages/core/src/services/visualReport.ts
 function generateVisualReport(options) {
-  const {
-    reports,
-    title = "AI Readiness Report",
-    generatedAt = (/* @__PURE__ */ new Date()).toISOString()
-  } = options;
+  const { reports, title = "Readiness Report", generatedAt = (/* @__PURE__ */ new Date()).toISOString() } = options;
   const successfulReports = reports.filter((r) => !r.error);
   const failedReports = reports.filter((r) => r.error);
   const totalRepos = reports.length;
@@ -11612,7 +11661,7 @@ function generateVisualReport(options) {
     ` : ""}
 
     <div class="footer">
-      <p>Generated with <a href="https://github.com/microsoft/agentrc">AgentRC</a> &middot; AI Readiness Tool</p>
+      <p>Generated with <a href="https://github.com/microsoft/agentrc">AgentRC</a> &middot; Readiness Tool</p>
     </div>
   </div>
   <script>
@@ -12099,7 +12148,7 @@ function BatchReadinessTui({ token, outputPath, policies }) {
           },
           error: r.error
         })),
-        title: "Batch AI Readiness Report",
+        title: "Batch Readiness Report",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString()
       });
       const finalOutputPath = outputPath ?? path10.join(process.cwd(), "batch-readiness-report.html");
@@ -13471,6 +13520,7 @@ async function instructionsCommand(options) {
     return;
   }
   try {
+    const dryRunFiles = [];
     if (!options.areasOnly && !options.area) {
       if (strategy === "nested") {
         try {
@@ -13482,25 +13532,57 @@ async function instructionsCommand(options) {
             detailDir,
             claudeMd
           });
-          const actions = await writeNestedInstructions(repoPath, nestedResult, options.force);
-          for (const action of actions) {
-            const relPath = path14.relative(process.cwd(), action.path);
-            if (action.action === "wrote") {
-              if (shouldLog(options)) progress.succeed(`Wrote ${relPath}`);
-            } else if (shouldLog(options)) {
-              progress.update(`Skipped ${relPath} (${skipReason(action.action)})`);
+          if (options.dryRun) {
+            const dryFiles = [
+              { path: nestedResult.hub.relativePath, content: nestedResult.hub.content },
+              ...nestedResult.details.map((d) => ({ path: d.relativePath, content: d.content })),
+              ...nestedResult.claudeMd ? [
+                {
+                  path: nestedResult.claudeMd.relativePath,
+                  content: nestedResult.claudeMd.content
+                }
+              ] : []
+            ];
+            for (const file of dryFiles) {
+              const relPath = path14.relative(process.cwd(), path14.join(repoPath, file.path));
+              if (shouldLog(options)) {
+                progress.update(
+                  `[dry-run] Would write ${relPath} (${Buffer.byteLength(file.content, "utf8")} bytes)`
+                );
+              }
+            }
+            if (options.json) {
+              dryRunFiles.push(
+                ...dryFiles.map((f) => ({
+                  path: f.path,
+                  bytes: Buffer.byteLength(f.content, "utf8")
+                }))
+              );
+            }
+            for (const warning of nestedResult.warnings) {
+              if (shouldLog(options)) progress.update(`Warning: ${warning}`);
+            }
+          } else {
+            const actions = await writeNestedInstructions(repoPath, nestedResult, options.force);
+            for (const action of actions) {
+              const relPath = path14.relative(process.cwd(), action.path);
+              if (action.action === "wrote") {
+                if (shouldLog(options)) progress.succeed(`Wrote ${relPath}`);
+              } else if (shouldLog(options)) {
+                progress.update(`Skipped ${relPath} (${skipReason(action.action)})`);
+              }
+            }
+            for (const warning of nestedResult.warnings) {
+              if (shouldLog(options)) progress.update(`Warning: ${warning}`);
+            }
+            if (options.json) {
+              const result = {
+                ok: true,
+                status: "success",
+                data: { files: actions }
+              };
+              outputResult(result, true);
             }
-          }
-          for (const warning of nestedResult.warnings) {
-            if (shouldLog(options)) progress.update(`Warning: ${warning}`);
-          }
-          if (options.json) {
-            const result = {
-              ok: true,
-              status: "success",
-              data: { files: actions }
-            };
-            outputResult(result, true);
           }
         } catch (error) {
           const msg = "Failed to generate nested instructions. " + (error instanceof Error ? error.message : String(error));
@@ -13525,36 +13607,48 @@ async function instructionsCommand(options) {
           return;
         }
         if (content) {
-          await ensureDir(path14.dirname(outputPath));
-          const { wrote, reason } = await safeWriteFile(
-            outputPath,
-            content,
-            Boolean(options.force)
-          );
-          if (!wrote) {
-            const relPath = path14.relative(process.cwd(), outputPath);
-            const why = reason === "symlink" ? "path is a symlink" : "file exists (use --force)";
+          if (options.dryRun) {
+            const relPath = path14.relative(repoPath, outputPath);
+            const displayPath = path14.relative(process.cwd(), outputPath);
+            const byteCount = Buffer.byteLength(content, "utf8");
+            if (shouldLog(options)) {
+              progress.update(`[dry-run] Would write ${displayPath} (${byteCount} bytes)`);
+            }
             if (options.json) {
-              const result = {
-                ok: true,
-                status: "noop",
-                data: { outputPath, skipped: true, reason: why }
-              };
-              outputResult(result, true);
-            } else if (shouldLog(options)) {
-              progress.update(`Skipped ${relPath}: ${why}`);
+              dryRunFiles.push({ path: relPath, bytes: byteCount });
             }
           } else {
-            const byteCount = Buffer.byteLength(content, "utf8");
-            if (options.json) {
-              const result = {
-                ok: true,
-                status: "success",
-                data: { outputPath, model: options.model ?? "default", byteCount }
-              };
-              outputResult(result, true);
-            } else if (shouldLog(options)) {
-              progress.succeed(`Updated ${path14.relative(process.cwd(), outputPath)}`);
+            await ensureDir(path14.dirname(outputPath));
+            const { wrote, reason } = await safeWriteFile(
+              outputPath,
+              content,
+              Boolean(options.force)
+            );
+            if (!wrote) {
+              const relPath = path14.relative(process.cwd(), outputPath);
+              const why = reason === "symlink" ? "path is a symlink" : "file exists (use --force)";
+              if (options.json) {
+                const result = {
+                  ok: true,
+                  status: "noop",
+                  data: { outputPath, skipped: true, reason: why }
+                };
+                outputResult(result, true);
+              } else if (shouldLog(options)) {
+                progress.update(`Skipped ${relPath}: ${why}`);
+              }
+            } else {
+              const byteCount = Buffer.byteLength(content, "utf8");
+              if (options.json) {
+                const result = {
+                  ok: true,
+                  status: "success",
+                  data: { outputPath, model: options.model ?? "default", byteCount }
+                };
+                outputResult(result, true);
+              } else if (shouldLog(options)) {
+                progress.succeed(`Updated ${path14.relative(process.cwd(), outputPath)}`);
+              }
             }
           }
         }
@@ -13588,7 +13682,7 @@ async function instructionsCommand(options) {
         return;
       }
       if (shouldLog(options)) {
-        progress.update(`Generating file-based instructions for ${targetAreas.length} area(s)...`);
+        progress.update(`Generating instructions for ${targetAreas.length} area(s)...`);
       }
       for (const area of targetAreas) {
         try {
@@ -13608,17 +13702,46 @@ async function instructionsCommand(options) {
               detailDir,
               claudeMd
             });
-            const actions = await writeNestedInstructions(repoPath, nestedResult, options.force);
-            for (const action of actions) {
-              const relPath = path14.relative(process.cwd(), action.path);
-              if (action.action === "wrote") {
-                if (shouldLog(options)) progress.succeed(`Wrote ${relPath}`);
-              } else if (shouldLog(options)) {
-                progress.update(`Skipped ${relPath} (${skipReason(action.action)})`);
+            if (options.dryRun) {
+              const dryFiles = [
+                { path: nestedResult.hub.relativePath, content: nestedResult.hub.content },
+                ...nestedResult.details.map((d) => ({ path: d.relativePath, content: d.content })),
+                ...nestedResult.claudeMd ? [
+                  {
+                    path: nestedResult.claudeMd.relativePath,
+                    content: nestedResult.claudeMd.content
+                  }
+                ] : []
+              ];
+              for (const file of dryFiles) {
+                const relPath = path14.relative(process.cwd(), path14.join(repoPath, file.path));
+                if (shouldLog(options)) {
+                  progress.update(
+                    `[dry-run] Would write ${relPath} (${Buffer.byteLength(file.content, "utf8")} bytes)`
+                  );
+                }
+              }
+              if (options.json) {
+                dryRunFiles.push(
+                  ...dryFiles.map((f) => ({
+                    path: f.path,
+                    bytes: Buffer.byteLength(f.content, "utf8")
+                  }))
+                );
+              }
+            } else {
+              const actions = await writeNestedInstructions(repoPath, nestedResult, options.force);
+              for (const action of actions) {
+                const relPath = path14.relative(process.cwd(), action.path);
+                if (action.action === "wrote") {
+                  if (shouldLog(options)) progress.succeed(`Wrote ${relPath}`);
+                } else if (shouldLog(options)) {
+                  progress.update(`Skipped ${relPath} (${skipReason(action.action)})`);
+                }
+              }
+              for (const warning of nestedResult.warnings) {
+                if (shouldLog(options)) progress.update(`Warning: ${warning}`);
               }
-            }
-            for (const warning of nestedResult.warnings) {
-              if (shouldLog(options)) progress.update(`Warning: ${warning}`);
             }
           } else {
             const body = await generateAreaInstructions({
@@ -13633,21 +13756,37 @@ async function instructionsCommand(options) {
               }
               continue;
             }
-            const result = await writeAreaInstruction(repoPath, area, body, options.force);
-            if (result.status === "skipped") {
+            if (options.dryRun) {
               if (shouldLog(options)) {
-                progress.update(`Skipped "${area.name}" \u2014 file exists (use --force to overwrite).`);
+                progress.update(
+                  `[dry-run] Would write area "${area.name}" (${Buffer.byteLength(body, "utf8")} bytes)`
+                );
+              }
+              if (options.json) {
+                dryRunFiles.push({
+                  path: path14.relative(repoPath, areaInstructionPath(repoPath, area)),
+                  bytes: Buffer.byteLength(body, "utf8")
+                });
+              }
+            } else {
+              const result = await writeAreaInstruction(repoPath, area, body, options.force);
+              if (result.status === "skipped") {
+                if (shouldLog(options)) {
+                  progress.update(
+                    `Skipped "${area.name}" \u2014 file exists (use --force to overwrite).`
+                  );
+                }
+                continue;
+              }
+              if (result.status === "symlink") {
+                if (shouldLog(options)) {
+                  progress.update(`Skipped "${area.name}" \u2014 path is a symlink.`);
+                }
+                continue;
               }
-              continue;
-            }
-            if (result.status === "symlink") {
               if (shouldLog(options)) {
-                progress.update(`Skipped "${area.name}" \u2014 path is a symlink.`);
+                progress.succeed(`Wrote ${path14.relative(process.cwd(), result.filePath)}`);
               }
-              continue;
-            }
-            if (shouldLog(options)) {
-              progress.succeed(`Wrote ${path14.relative(process.cwd(), result.filePath)}`);
             }
           }
         } catch (error) {
@@ -13659,6 +13798,12 @@ async function instructionsCommand(options) {
         }
       }
     }
+    if (options.dryRun && options.json) {
+      outputResult(
+        { ok: true, status: "noop", data: { dryRun: true, files: dryRunFiles } },
+        true
+      );
+    }
     if (!wantAreas && shouldLog(options) && !options.json) {
       process.stderr.write("\nNext steps:\n");
       process.stderr.write("  agentrc eval --init      Scaffold evaluation test cases\n");
@@ -13677,6 +13822,18 @@ async function instructionsCommand(options) {
 async function generateCommand(type, repoPathArg, options) {
   const repoPath = path15.resolve(repoPathArg ?? process.cwd());
   if (type === "instructions" || type === "agents") {
+    if (!options.quiet) {
+      process.stderr.write(
+        `\u26A0 \`generate ${type}\` is deprecated \u2014 use \`agentrc instructions\` directly.
+`
+      );
+    }
+    if (options.perApp && !options.quiet) {
+      process.stderr.write(
+        `\u26A0 --per-app is deprecated \u2014 use \`agentrc instructions --areas\` instead.
+`
+      );
+    }
     const output = type === "agents" ? path15.join(repoPath, "AGENTS.md") : void 0;
     await instructionsCommand({
       repo: repoPath,
@@ -13949,7 +14106,7 @@ async function initCommand(repoPathArg, options) {
 `);
     }
     process.stderr.write("\nNext steps:\n");
-    process.stderr.write("  agentrc readiness             Check AI readiness across 9 pillars\n");
+    process.stderr.write("  agentrc readiness             Run readiness report across 9 pillars\n");
     if (analysis.areas && analysis.areas.length > 0) {
       process.stderr.write("  agentrc instructions --areas   Generate per-area instructions\n");
     }
@@ -14201,7 +14358,7 @@ async function readinessCommand(repoPathArg, options) {
   if (options.visual || outputExt === ".html") {
     const html = generateVisualReport({
       reports: [{ repo: repoName, report }],
-      title: `AI Readiness Report: ${repoName}`,
+      title: `Readiness Report: ${repoName}`,
       generatedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
     const outputPath = options.output ? resolvedOutputPath : path18.join(repoPath, "readiness-report.html");
@@ -14301,7 +14458,7 @@ ${label}`));
     }
   }
   if (report.extras.length) {
-    log(chalk3.bold("\nAI readiness extras"));
+    log(chalk3.bold("\nReadiness extras"));
     for (const extra of report.extras) {
       const icon = extra.status === "pass" ? chalk3.green("\u2714") : chalk3.red("\u2716");
       log(`${icon} ${extra.title}`);
@@ -14366,7 +14523,7 @@ function printAreaBreakdown(areaReports) {
 }
 function formatReadinessMarkdown(report, repoName) {
   const lines = [];
-  lines.push(`# AI Readiness Report: ${repoName}`);
+  lines.push(`# Readiness Report: ${repoName}`);
   lines.push("");
   lines.push(`**Level ${report.achievedLevel}** \u2014 ${levelName(report.achievedLevel)}`);
   lines.push("");
@@ -14399,7 +14556,7 @@ function formatReadinessMarkdown(report, repoName) {
     lines.push("");
   }
   if (report.extras.length > 0) {
-    lines.push("## AI Readiness Extras");
+    lines.push("## Readiness Extras");
     lines.push("");
     for (const extra of report.extras) {
       const icon = extra.status === "pass" ? "\u2705" : "\u274C";
@@ -14554,7 +14711,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
   const [areaCursor, setAreaCursor] = useState5(0);
   const repoLabel = useMemo(() => path19.basename(repoPath), [repoPath]);
   const repoFull = useMemo(() => repoPath, [repoPath]);
-  const isLoading = status === "generating" || status === "bootstrapping" || status === "evaluating" || status === "generating-areas";
+  const isLoading = status === "generating" || status === "bootstrapping" || status === "evaluating" || status === "generating-areas" || status === "readiness-running";
   const isMenu = status === "model-pick" || status === "eval-pick" || status === "batch-pick" || status === "generate-pick" || status === "generate-app-pick" || status === "generate-area-pick";
   const spinner = useSpinner(isLoading);
   const addLog = (text, type = "info") => {
@@ -14796,14 +14953,14 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
               }
               return;
             }
-            if (input.toLowerCase() === "f") {
+            if (input.toLowerCase() === "n") {
               if (repoAreas.length === 0) {
                 setMessage("No areas detected. Add agentrc.config.json to define areas.");
                 return;
               }
               setAreaCursor(0);
               setStatus("generate-area-pick");
-              setMessage("Generate file-based instructions for areas.");
+              setMessage("Generate nested instructions for areas.");
               return;
             }
             if (key.escape) {
@@ -14866,10 +15023,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
           if (status === "generate-area-pick") {
             if (input.toLowerCase() === "a") {
               setStatus("generating-areas");
-              addLog(
-                `Generating file-based instructions for ${repoAreas.length} areas...`,
-                "progress"
-              );
+              addLog(`Generating nested instructions for ${repoAreas.length} areas...`, "progress");
               let written = 0;
               for (const [i, area] of repoAreas.entries()) {
                 setMessage(`Generating for "${area.name}" (${i + 1}/${repoAreas.length})...`);
@@ -14892,9 +15046,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
                 }
               }
               setStatus("done");
-              setMessage(
-                `Generated file-based instructions for ${written}/${repoAreas.length} areas.`
-              );
+              setMessage(`Generated nested instructions for ${written}/${repoAreas.length} areas.`);
               return;
             }
             if (key.upArrow) {
@@ -14910,7 +15062,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
               if (!area) return;
               setStatus("generating-areas");
               setMessage(`Generating for "${area.name}"...`);
-              addLog(`Generating file-based instructions for "${area.name}"...`, "progress");
+              addLog(`Generating nested instructions for "${area.name}"...`, "progress");
               try {
                 const body = await generateAreaInstructions({
                   repoPath,
@@ -15083,6 +15235,36 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
               setMessage("Select what to generate.");
               return;
             }
+            if (input.toLowerCase() === "r") {
+              setStatus("readiness-running");
+              setMessage("Running readiness report\u2026");
+              addLog("Running readiness report\u2026", "progress");
+              try {
+                let policies;
+                try {
+                  const config = await loadAgentrcConfig(repoPath);
+                  policies = config?.policies;
+                } catch {
+                }
+                const report = await runReadinessReport({ repoPath, policies });
+                const levelName2 = getLevelName(report.achievedLevel);
+                const failCount = report.criteria.filter((c) => c.status === "fail").length;
+                addLog(
+                  `Level ${report.achievedLevel} (${levelName2}) \u2014 ${failCount} item(s) to fix`,
+                  "success"
+                );
+                setStatus("done");
+                setMessage(
+                  `Readiness: Level ${report.achievedLevel} (${levelName2}). ${failCount} improvement(s) available.`
+                );
+              } catch (error) {
+                const msg = error instanceof Error ? error.message : "Failed.";
+                addLog(`Readiness failed: ${msg}`, "error");
+                setStatus("error");
+                setMessage(`Readiness failed: ${msg}`);
+              }
+              return;
+            }
             if (input.toLowerCase() === "b") {
               setStatus("batch-pick");
               setMessage("Select batch provider.");
@@ -15135,7 +15317,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
     { isActive: inputActive }
   );
   const statusIcon = status === "error" ? accessible ? "ERROR" : "\u2717" : status === "done" ? accessible ? "OK" : "\u2713" : isLoading ? spinner : accessible ? "*" : "\u25CF";
-  const statusLabel = status === "intro" ? "starting" : status === "idle" ? "ready" : status === "bootstrapEvalCount" ? "input" : status === "bootstrapEvalConfirm" ? "confirm" : status === "eval-pick" ? "eval" : status === "batch-pick" ? "batch" : status === "model-pick" ? "models" : status;
+  const statusLabel = status === "intro" ? "starting" : status === "idle" ? "ready" : status === "bootstrapEvalCount" ? "input" : status === "bootstrapEvalConfirm" ? "confirm" : status === "eval-pick" ? "eval" : status === "batch-pick" ? "batch" : status === "model-pick" ? "models" : status === "readiness-running" ? "readiness" : status;
   const statusColor = status === "error" ? "red" : status === "done" ? "green" : isLoading ? "yellow" : isMenu ? "magentaBright" : "cyanBright";
   const formatTokens = (result) => {
     const withUsage = result.metrics?.withInstructions?.tokenUsage;
@@ -15287,14 +15469,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
           ] }, app2.name)) })
         ] }),
         status === "generate-area-pick" && repoAreas.length > 0 && /* @__PURE__ */ jsxs4(Fragment, { children: [
-          /* @__PURE__ */ jsx7(
-            Divider,
-            {
-              columns: terminalColumns,
-              label: "File-based instructions",
-              accessible
-            }
-          ),
+          /* @__PURE__ */ jsx7(Divider, { columns: terminalColumns, label: "Nested instructions", accessible }),
           /* @__PURE__ */ jsx7(Box5, { flexDirection: "column", paddingLeft: 1, children: repoAreas.map((area, i) => /* @__PURE__ */ jsxs4(Text5, { children: [
             /* @__PURE__ */ jsx7(Text5, { color: i === areaCursor ? "cyanBright" : "gray", children: i === areaCursor ? accessible ? ">" : "\u25B6" : " " }),
             /* @__PURE__ */ jsx7(Text5, { color: "gray", children: " " }),
@@ -15375,9 +15550,9 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
           /* @__PURE__ */ jsx7(Text5, { color: "cyan", children: " to select " }),
           /* @__PURE__ */ jsx7(KeyHint, { k: "Esc", label: "Back" })
         ] }) : status === "generate-pick" ? /* @__PURE__ */ jsxs4(Box5, { children: [
-          /* @__PURE__ */ jsx7(KeyHint, { k: "C", label: "Copilot instructions" }),
-          /* @__PURE__ */ jsx7(KeyHint, { k: "A", label: "AGENTS.md" }),
-          repoAreas.length > 0 && /* @__PURE__ */ jsx7(KeyHint, { k: "F", label: "File-based (areas)" }),
+          /* @__PURE__ */ jsx7(KeyHint, { k: "C", label: "Instructions" }),
+          /* @__PURE__ */ jsx7(KeyHint, { k: "A", label: "Agents" }),
+          repoAreas.length > 0 && /* @__PURE__ */ jsx7(KeyHint, { k: "N", label: "Nested (areas)" }),
           /* @__PURE__ */ jsx7(KeyHint, { k: "Esc", label: "Back" })
         ] }) : status === "generate-app-pick" ? /* @__PURE__ */ jsxs4(Box5, { children: [
           /* @__PURE__ */ jsx7(KeyHint, { k: "R", label: "Root only" }),
@@ -15413,6 +15588,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
         ] }) : isLoading ? /* @__PURE__ */ jsx7(Box5, { children: /* @__PURE__ */ jsx7(KeyHint, { k: "Q", label: "Quit" }) }) : /* @__PURE__ */ jsxs4(Box5, { flexDirection: "column", children: [
           /* @__PURE__ */ jsxs4(Box5, { children: [
             /* @__PURE__ */ jsx7(KeyHint, { k: "G", label: "Generate" }),
+            /* @__PURE__ */ jsx7(KeyHint, { k: "R", label: "Readiness" }),
             /* @__PURE__ */ jsx7(KeyHint, { k: "E", label: "Eval" }),
             /* @__PURE__ */ jsx7(KeyHint, { k: "B", label: "Batch" })
           ] }),
@@ -15466,7 +15642,7 @@ function withGlobalOpts(fn) {
 function runCli(argv) {
   const program = new Command();
   program.name("agentrc").description("Set up repositories for AI-assisted development").version(CLI_VERSION).option("--json", "Output machine-readable JSON to stdout").option("--quiet", "Suppress stderr progress output").option("--accessible", "Enable screen reader friendly output");
-  program.command("init").description("Interactive repo setup \u2014 analyze, generate instructions and configs").argument("[path]", "Path to a local repository").option("--github", "Use a GitHub repository").option("--provider <provider>", "Repo provider (github|azure)").option("--yes", "Accept defaults (generates instructions, MCP, and VS Code configs)").option("--force", "Overwrite existing files").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).action(withGlobalOpts(initCommand));
+  program.command("init").description("Init repository \u2014 analyze & generate instructions").argument("[path]", "Path to a local repository").option("--github", "Use a GitHub repository").option("--provider <provider>", "Repo provider (github|azure)").option("--yes", "Accept defaults (generates instructions, MCP, and VS Code configs)").option("--force", "Overwrite existing files").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).action(withGlobalOpts(initCommand));
   program.command("analyze").description("Detect languages, frameworks, monorepo structure, and areas").argument("[path]", "Path to a local repository").option("--output <path>", "Write report to file (.json or .md)").option("--force", "Overwrite existing output file").action(withGlobalOpts(analyzeCommand));
   program.command("generate").description("Generate instructions, agents, MCP, or VS Code configs").addArgument(
     new Argument("<type>", "Config type to generate").choices([
@@ -15475,14 +15651,14 @@ function runCli(argv) {
       "mcp",
       "vscode"
     ])
-  ).argument("[path]", "Path to a local repository").option("--force", "Overwrite existing files").option("--per-app", "Generate per-app in monorepos").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).option("--strategy <mode>", "Instruction strategy (flat or nested)").action(withGlobalOpts(generateCommand));
+  ).argument("[path]", "Path to a local repository").option("--force", "Overwrite existing files").option("--per-app", "(deprecated) Use `agentrc instructions --areas` instead").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).option("--strategy <mode>", "Instruction strategy (flat or nested)").action(withGlobalOpts(generateCommand));
   program.command("pr").description("Create a PR with generated configs on GitHub or Azure DevOps").argument("[repo]", "Repo identifier (github: owner/name, azure: org/project/repo)").option("--branch <name>", "Branch name").option("--provider <provider>", "Repo provider (github|azure)").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).action(withGlobalOpts(prCommand));
   program.command("eval").description("Compare AI responses with and without instructions").argument("[path]", "Path to eval config JSON").option("--repo <path>", "Repository path", process.cwd()).option("--model <name>", "Model for responses", DEFAULT_MODEL).option("--judge-model <name>", "Model for judging", DEFAULT_JUDGE_MODEL).option("--list-models", "List Copilot CLI models and exit").option("--output <path>", "Write results JSON to file").option("--init", "Create a starter agentrc.eval.json file").option("--count <number>", "Number of eval cases to generate (with --init)").option("--fail-level <number>", "Exit with error if pass rate (%) falls below threshold").action(withGlobalOpts(evalCommand));
   program.command("tui").description("Interactive terminal UI for generation, evaluation, and batch workflows").option("--repo <path>", "Repository path", process.cwd()).option("--no-animation", "Skip the animated banner intro").action(withGlobalOpts(tuiCommand));
-  program.command("instructions").description("Generate root and per-area AI instruction files").option("--repo <path>", "Repository path", process.cwd()).option("--output <path>", "Output path for copilot instructions").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).option("--force", "Overwrite existing area instruction files").option("--areas", "Also generate file-based instructions for detected areas").option("--areas-only", "Generate only file-based area instructions (skip root)").option("--area <name>", "Generate file-based instructions for a specific area").option("--strategy <mode>", "Instruction strategy (flat or nested)").option("--claude-md", "Generate CLAUDE.md files alongside AGENTS.md (nested strategy)").action(withGlobalOpts(instructionsCommand));
-  program.command("readiness").description("AI readiness assessment across 9 maturity pillars").argument("[path]", "Path to a local repository").option("--output <path>", "Write report to file (.json, .md, or .html)").option("--force", "Overwrite existing output file").option("--visual", "Generate visual HTML report").option("--per-area", "Show per-area readiness breakdown").option("--policy <sources>", "Policy sources (comma-separated: paths, npm packages)").option("--fail-level <number>", "Exit with error if readiness level is below threshold (1\u20135)").action(withGlobalOpts(readinessCommand));
+  program.command("instructions").description("Generate instructions for the repository").option("--repo <path>", "Repository path", process.cwd()).option("--output <path>", "Output path for instructions").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).option("--force", "Overwrite existing area instruction files").option("--areas", "Also generate instructions for detected areas").option("--areas-only", "Generate only area instructions (skip root)").option("--area <name>", "Generate instructions for a specific area").option("--strategy <mode>", "Instruction strategy (flat or nested)").option("--claude-md", "Generate CLAUDE.md files alongside AGENTS.md (nested strategy)").option("--dry-run", "Preview generated files without writing anything").action(withGlobalOpts(instructionsCommand));
+  program.command("readiness").description("Run readiness report across 9 maturity pillars").argument("[path]", "Path to a local repository").option("--output <path>", "Write report to file (.json, .md, or .html)").option("--force", "Overwrite existing output file").option("--visual", "Generate visual HTML report").option("--per-area", "Show per-area readiness breakdown").option("--policy <sources>", "Policy sources (comma-separated: paths, npm packages)").option("--fail-level <number>", "Exit with error if readiness level is below threshold (1\u20135)").action(withGlobalOpts(readinessCommand));
   program.command("batch").description("Batch process multiple repos across orgs").argument("[repos...]", "Repos in owner/name form (GitHub) or org/project/repo (Azure)").option("--output <path>", "Write results JSON to file").option("--provider <provider>", "Repo provider (github|azure)", "github").option("--model <name>", "Model for instructions generation", DEFAULT_MODEL).option("--branch <name>", "Branch name for PRs").action(withGlobalOpts(batchCommand));
-  program.command("batch-readiness").description("Generate batch AI readiness report for multiple repos").option("--output <path>", "Write HTML report to file").option("--policy <sources>", "Policy sources (comma-separated: paths, npm packages)").action(withGlobalOpts(batchReadinessCommand));
+  program.command("batch-readiness").description("Run batch readiness report for multiple repos").option("--output <path>", "Write HTML report to file").option("--policy <sources>", "Policy sources (comma-separated: paths, npm packages)").action(withGlobalOpts(batchReadinessCommand));
   program.parse(argv);
 }