@microsoft/agentrc 2.0.1-0 → 2.0.1-10

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;
@@ -3050,7 +3052,7 @@ var require_main = __commonJS({
     exports.createMessageConnection = exports.createServerSocketTransport = exports.createClientSocketTransport = exports.createServerPipeTransport = exports.createClientPipeTransport = exports.generateRandomPipeName = exports.StreamMessageWriter = exports.StreamMessageReader = exports.SocketMessageWriter = exports.SocketMessageReader = exports.PortMessageWriter = exports.PortMessageReader = exports.IPCMessageWriter = exports.IPCMessageReader = void 0;
     var ril_1 = require_ril();
     ril_1.default.install();
-    var path21 = __require("path");
+    var path23 = __require("path");
     var os2 = __require("os");
     var crypto_1 = __require("crypto");
     var net_1 = __require("net");
@@ -3186,9 +3188,9 @@ var require_main = __commonJS({
       }
       let result;
       if (XDG_RUNTIME_DIR) {
-        result = path21.join(XDG_RUNTIME_DIR, `vscode-ipc-${randomSuffix}.sock`);
+        result = path23.join(XDG_RUNTIME_DIR, `vscode-ipc-${randomSuffix}.sock`);
       } else {
-        result = path21.join(os2.tmpdir(), `vscode-${randomSuffix}.sock`);
+        result = path23.join(os2.tmpdir(), `vscode-${randomSuffix}.sock`);
       }
       const limit = safeIpcPathLengths.get(process.platform);
       if (limit !== void 0 && result.length > limit) {
@@ -3329,23 +3331,63 @@ function createSessionRpc(connection, sessionId) {
       readFile: async (params) => connection.sendRequest("session.workspace.readFile", { sessionId, ...params }),
       createFile: async (params) => connection.sendRequest("session.workspace.createFile", { sessionId, ...params })
     },
+    /** @experimental */
     fleet: {
       start: async (params) => connection.sendRequest("session.fleet.start", { sessionId, ...params })
     },
+    /** @experimental */
     agent: {
       list: async () => connection.sendRequest("session.agent.list", { sessionId }),
       getCurrent: async () => connection.sendRequest("session.agent.getCurrent", { sessionId }),
       select: async (params) => connection.sendRequest("session.agent.select", { sessionId, ...params }),
-      deselect: async () => connection.sendRequest("session.agent.deselect", { sessionId })
+      deselect: async () => connection.sendRequest("session.agent.deselect", { sessionId }),
+      reload: async () => connection.sendRequest("session.agent.reload", { sessionId })
     },
+    /** @experimental */
+    skills: {
+      list: async () => connection.sendRequest("session.skills.list", { sessionId }),
+      enable: async (params) => connection.sendRequest("session.skills.enable", { sessionId, ...params }),
+      disable: async (params) => connection.sendRequest("session.skills.disable", { sessionId, ...params }),
+      reload: async () => connection.sendRequest("session.skills.reload", { sessionId })
+    },
+    /** @experimental */
+    mcp: {
+      list: async () => connection.sendRequest("session.mcp.list", { sessionId }),
+      enable: async (params) => connection.sendRequest("session.mcp.enable", { sessionId, ...params }),
+      disable: async (params) => connection.sendRequest("session.mcp.disable", { sessionId, ...params }),
+      reload: async () => connection.sendRequest("session.mcp.reload", { sessionId })
+    },
+    /** @experimental */
+    plugins: {
+      list: async () => connection.sendRequest("session.plugins.list", { sessionId })
+    },
+    /** @experimental */
+    extensions: {
+      list: async () => connection.sendRequest("session.extensions.list", { sessionId }),
+      enable: async (params) => connection.sendRequest("session.extensions.enable", { sessionId, ...params }),
+      disable: async (params) => connection.sendRequest("session.extensions.disable", { sessionId, ...params }),
+      reload: async () => connection.sendRequest("session.extensions.reload", { sessionId })
+    },
+    /** @experimental */
     compaction: {
       compact: async () => connection.sendRequest("session.compaction.compact", { sessionId })
     },
     tools: {
       handlePendingToolCall: async (params) => connection.sendRequest("session.tools.handlePendingToolCall", { sessionId, ...params })
     },
+    commands: {
+      handlePendingCommand: async (params) => connection.sendRequest("session.commands.handlePendingCommand", { sessionId, ...params })
+    },
+    ui: {
+      elicitation: async (params) => connection.sendRequest("session.ui.elicitation", { sessionId, ...params })
+    },
     permissions: {
       handlePendingPermissionRequest: async (params) => connection.sendRequest("session.permissions.handlePendingPermissionRequest", { sessionId, ...params })
+    },
+    log: async (params) => connection.sendRequest("session.log", { sessionId, ...params }),
+    shell: {
+      exec: async (params) => connection.sendRequest("session.shell.exec", { sessionId, ...params }),
+      kill: async (params) => connection.sendRequest("session.shell.kill", { sessionId, ...params })
     }
   };
 }
@@ -3367,13 +3409,30 @@ var init_sdkProtocolVersion = __esm({
   }
 });
 
+// node_modules/@github/copilot-sdk/dist/telemetry.js
+async function getTraceContext(provider) {
+  if (!provider) return {};
+  try {
+    return await provider() ?? {};
+  } catch {
+    return {};
+  }
+}
+var init_telemetry = __esm({
+  "node_modules/@github/copilot-sdk/dist/telemetry.js"() {
+    "use strict";
+  }
+});
+
 // node_modules/@github/copilot-sdk/dist/session.js
-var import_node, CopilotSession;
+var import_node, NO_RESULT_PERMISSION_V2_ERROR, CopilotSession;
 var init_session = __esm({
   "node_modules/@github/copilot-sdk/dist/session.js"() {
     "use strict";
     import_node = __toESM(require_node(), 1);
     init_rpc();
+    init_telemetry();
+    NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
     CopilotSession = class {
       /**
        * Creates a new CopilotSession instance.
@@ -3381,12 +3440,14 @@ var init_session = __esm({
        * @param sessionId - The unique identifier for this session
        * @param connection - The JSON-RPC message connection to the Copilot CLI
        * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+       * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
        * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
        */
-      constructor(sessionId, connection, _workspacePath) {
+      constructor(sessionId, connection, _workspacePath, traceContextProvider) {
         this.sessionId = sessionId;
         this.connection = connection;
         this._workspacePath = _workspacePath;
+        this.traceContextProvider = traceContextProvider;
       }
       eventHandlers = /* @__PURE__ */ new Set();
       typedEventHandlers = /* @__PURE__ */ new Map();
@@ -3394,7 +3455,9 @@ var init_session = __esm({
       permissionHandler;
       userInputHandler;
       hooks;
+      transformCallbacks;
       _rpc = null;
+      traceContextProvider;
       /**
        * Typed session-scoped RPC methods.
        */
@@ -3432,6 +3495,7 @@ var init_session = __esm({
        */
       async send(options) {
         const response = await this.connection.sendRequest("session.send", {
+          ...await getTraceContext(this.traceContextProvider),
           sessionId: this.sessionId,
           prompt: options.prompt,
           attachments: options.attachments,
@@ -3561,9 +3625,19 @@ var init_session = __esm({
           const { requestId, toolName } = event.data;
           const args2 = event.data.arguments;
           const toolCallId = event.data.toolCallId;
+          const traceparent = event.data.traceparent;
+          const tracestate = event.data.tracestate;
           const handler = this.toolHandlers.get(toolName);
           if (handler) {
-            void this._executeToolAndRespond(requestId, toolName, toolCallId, args2, handler);
+            void this._executeToolAndRespond(
+              requestId,
+              toolName,
+              toolCallId,
+              args2,
+              handler,
+              traceparent,
+              tracestate
+            );
           }
         } else if (event.type === "permission.requested") {
           const { requestId, permissionRequest } = event.data;
@@ -3576,13 +3650,15 @@ var init_session = __esm({
        * Executes a tool handler and sends the result back via RPC.
        * @internal
        */
-      async _executeToolAndRespond(requestId, toolName, toolCallId, args2, handler) {
+      async _executeToolAndRespond(requestId, toolName, toolCallId, args2, handler, traceparent, tracestate) {
         try {
           const rawResult = await handler(args2, {
             sessionId: this.sessionId,
             toolCallId,
             toolName,
-            arguments: args2
+            arguments: args2,
+            traceparent,
+            tracestate
           });
           let result;
           if (rawResult == null) {
@@ -3613,6 +3689,9 @@ var init_session = __esm({
           const result = await this.permissionHandler(permissionRequest, {
             sessionId: this.sessionId
           });
+          if (result.kind === "no-result") {
+            return;
+          }
           await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
         } catch (_error) {
           try {
@@ -3693,6 +3772,40 @@ var init_session = __esm({
       registerHooks(hooks) {
         this.hooks = hooks;
       }
+      /**
+       * Registers transform callbacks for system message sections.
+       *
+       * @param callbacks - Map of section ID to transform callback, or undefined to clear
+       * @internal This method is typically called internally when creating a session.
+       */
+      registerTransformCallbacks(callbacks) {
+        this.transformCallbacks = callbacks;
+      }
+      /**
+       * Handles a systemMessage.transform request from the runtime.
+       * Dispatches each section to its registered transform callback.
+       *
+       * @param sections - Map of section IDs to their current rendered content
+       * @returns A promise that resolves with the transformed sections
+       * @internal This method is for internal use by the SDK.
+       */
+      async _handleSystemMessageTransform(sections) {
+        const result = {};
+        for (const [sectionId, { content }] of Object.entries(sections)) {
+          const callback = this.transformCallbacks?.get(sectionId);
+          if (callback) {
+            try {
+              const transformed = await callback(content);
+              result[sectionId] = { content: transformed };
+            } catch (_error) {
+              result[sectionId] = { content };
+            }
+          } else {
+            result[sectionId] = { content };
+          }
+        }
+        return { sections: result };
+      }
       /**
        * Handles a permission request in the v2 protocol format (synchronous RPC).
        * Used as a back-compat adapter when connected to a v2 server.
@@ -3709,8 +3822,14 @@ var init_session = __esm({
           const result = await this.permissionHandler(request, {
             sessionId: this.sessionId
           });
+          if (result.kind === "no-result") {
+            throw new Error(NO_RESULT_PERMISSION_V2_ERROR);
+          }
           return result;
-        } catch (_error) {
+        } catch (error) {
+          if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
+            throw error;
+          }
           return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
         }
       }
@@ -3866,14 +3985,35 @@ var init_session = __esm({
        * The new model takes effect for the next message. Conversation history is preserved.
        *
        * @param model - Model ID to switch to
+       * @param options - Optional settings for the new model
        *
        * @example
        * ```typescript
        * await session.setModel("gpt-4.1");
+       * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
        * ```
        */
-      async setModel(model) {
-        await this.rpc.model.switchTo({ modelId: model });
+      async setModel(model, options) {
+        await this.rpc.model.switchTo({ modelId: model, ...options });
+      }
+      /**
+       * Log a message to the session timeline.
+       * The message appears in the session event stream and is visible to SDK consumers
+       * and (for non-ephemeral messages) persisted to the session event log on disk.
+       *
+       * @param message - Human-readable message text
+       * @param options - Optional log level and ephemeral flag
+       *
+       * @example
+       * ```typescript
+       * await session.log("Processing started");
+       * await session.log("Disk usage high", { level: "warning" });
+       * await session.log("Connection failed", { level: "error" });
+       * await session.log("Debug info", { ephemeral: true });
+       * ```
+       */
+      async log(message, options) {
+        await this.rpc.log({ message, ...options });
       }
     };
   }
@@ -3881,7 +4021,9 @@ var init_session = __esm({
 
 // node_modules/@github/copilot-sdk/dist/client.js
 import { spawn } from "child_process";
+import { randomUUID } from "crypto";
 import { existsSync } from "fs";
+import { createRequire } from "module";
 import { Socket } from "net";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -3895,6 +4037,30 @@ function toJsonSchema(parameters) {
   }
   return parameters;
 }
+function extractTransformCallbacks(systemMessage) {
+  if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
+    return { wirePayload: systemMessage, transformCallbacks: void 0 };
+  }
+  const transformCallbacks = /* @__PURE__ */ new Map();
+  const wireSections = {};
+  for (const [sectionId, override] of Object.entries(systemMessage.sections)) {
+    if (!override) continue;
+    if (typeof override.action === "function") {
+      transformCallbacks.set(sectionId, override.action);
+      wireSections[sectionId] = { action: "transform" };
+    } else {
+      wireSections[sectionId] = { action: override.action, content: override.content };
+    }
+  }
+  if (transformCallbacks.size === 0) {
+    return { wirePayload: systemMessage, transformCallbacks: void 0 };
+  }
+  const wirePayload = {
+    ...systemMessage,
+    sections: wireSections
+  };
+  return { wirePayload, transformCallbacks };
+}
 function getNodeExecPath() {
   if (process.versions.bun) {
     return "node";
@@ -3912,6 +4078,7 @@ var init_client = __esm({
     init_rpc();
     init_sdkProtocolVersion();
     init_session();
+    init_telemetry();
     MIN_PROTOCOL_VERSION = 2;
     CopilotClient = class {
       cliProcess = null;
@@ -3926,6 +4093,8 @@ var init_client = __esm({
       options;
       isExternalServer = false;
       forceStopping = false;
+      onListModels;
+      onGetTraceContext;
       modelsCache = null;
       modelsCacheLock = Promise.resolve();
       sessionLifecycleHandlers = /* @__PURE__ */ new Set();
@@ -3991,8 +4160,10 @@ var init_client = __esm({
         if (options.isChildProcess) {
           this.isExternalServer = true;
         }
+        this.onListModels = options.onListModels;
+        this.onGetTraceContext = options.onGetTraceContext;
         this.options = {
-          cliPath: options.cliPath || getBundledCliPath(),
+          cliPath: options.cliUrl ? void 0 : options.cliPath || getBundledCliPath(),
           cliArgs: options.cliArgs ?? [],
           cwd: options.cwd ?? process.cwd(),
           port: options.port || 0,
@@ -4002,11 +4173,12 @@ var init_client = __esm({
           cliUrl: options.cliUrl,
           logLevel: options.logLevel || "debug",
           autoStart: options.autoStart ?? true,
-          autoRestart: options.autoRestart ?? true,
+          autoRestart: false,
           env: options.env ?? process.env,
           githubToken: options.githubToken,
           // Default useLoggedInUser to false when githubToken is provided, otherwise true
-          useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true)
+          useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true),
+          telemetry: options.telemetry
         };
       }
       /**
@@ -4258,36 +4430,13 @@ var init_client = __esm({
             throw new Error("Client not connected. Call start() first.");
           }
         }
-        const response = await this.connection.sendRequest("session.create", {
-          model: config.model,
-          sessionId: config.sessionId,
-          clientName: config.clientName,
-          reasoningEffort: config.reasoningEffort,
-          tools: config.tools?.map((tool) => ({
-            name: tool.name,
-            description: tool.description,
-            parameters: toJsonSchema(tool.parameters),
-            overridesBuiltInTool: tool.overridesBuiltInTool
-          })),
-          systemMessage: config.systemMessage,
-          availableTools: config.availableTools,
-          excludedTools: config.excludedTools,
-          provider: config.provider,
-          requestPermission: true,
-          requestUserInput: !!config.onUserInputRequest,
-          hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
-          workingDirectory: config.workingDirectory,
-          streaming: config.streaming,
-          mcpServers: config.mcpServers,
-          envValueMode: "direct",
-          customAgents: config.customAgents,
-          configDir: config.configDir,
-          skillDirectories: config.skillDirectories,
-          disabledSkills: config.disabledSkills,
-          infiniteSessions: config.infiniteSessions
-        });
-        const { sessionId, workspacePath } = response;
-        const session = new CopilotSession(sessionId, this.connection, workspacePath);
+        const sessionId = config.sessionId ?? randomUUID();
+        const session = new CopilotSession(
+          sessionId,
+          this.connection,
+          void 0,
+          this.onGetTraceContext
+        );
         session.registerTools(config.tools);
         session.registerPermissionHandler(config.onPermissionRequest);
         if (config.onUserInputRequest) {
@@ -4296,7 +4445,54 @@ var init_client = __esm({
         if (config.hooks) {
           session.registerHooks(config.hooks);
         }
+        const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
+          config.systemMessage
+        );
+        if (transformCallbacks) {
+          session.registerTransformCallbacks(transformCallbacks);
+        }
+        if (config.onEvent) {
+          session.on(config.onEvent);
+        }
         this.sessions.set(sessionId, session);
+        try {
+          const response = await this.connection.sendRequest("session.create", {
+            ...await getTraceContext(this.onGetTraceContext),
+            model: config.model,
+            sessionId,
+            clientName: config.clientName,
+            reasoningEffort: config.reasoningEffort,
+            tools: config.tools?.map((tool) => ({
+              name: tool.name,
+              description: tool.description,
+              parameters: toJsonSchema(tool.parameters),
+              overridesBuiltInTool: tool.overridesBuiltInTool,
+              skipPermission: tool.skipPermission
+            })),
+            systemMessage: wireSystemMessage,
+            availableTools: config.availableTools,
+            excludedTools: config.excludedTools,
+            provider: config.provider,
+            requestPermission: true,
+            requestUserInput: !!config.onUserInputRequest,
+            hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
+            workingDirectory: config.workingDirectory,
+            streaming: config.streaming,
+            mcpServers: config.mcpServers,
+            envValueMode: "direct",
+            customAgents: config.customAgents,
+            agent: config.agent,
+            configDir: config.configDir,
+            skillDirectories: config.skillDirectories,
+            disabledSkills: config.disabledSkills,
+            infiniteSessions: config.infiniteSessions
+          });
+          const { workspacePath } = response;
+          session["_workspacePath"] = workspacePath;
+        } catch (e) {
+          this.sessions.delete(sessionId);
+          throw e;
+        }
         return session;
       }
       /**
@@ -4336,37 +4532,12 @@ var init_client = __esm({
             throw new Error("Client not connected. Call start() first.");
           }
         }
-        const response = await this.connection.sendRequest("session.resume", {
+        const session = new CopilotSession(
           sessionId,
-          clientName: config.clientName,
-          model: config.model,
-          reasoningEffort: config.reasoningEffort,
-          systemMessage: config.systemMessage,
-          availableTools: config.availableTools,
-          excludedTools: config.excludedTools,
-          tools: config.tools?.map((tool) => ({
-            name: tool.name,
-            description: tool.description,
-            parameters: toJsonSchema(tool.parameters),
-            overridesBuiltInTool: tool.overridesBuiltInTool
-          })),
-          provider: config.provider,
-          requestPermission: true,
-          requestUserInput: !!config.onUserInputRequest,
-          hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
-          workingDirectory: config.workingDirectory,
-          configDir: config.configDir,
-          streaming: config.streaming,
-          mcpServers: config.mcpServers,
-          envValueMode: "direct",
-          customAgents: config.customAgents,
-          skillDirectories: config.skillDirectories,
-          disabledSkills: config.disabledSkills,
-          infiniteSessions: config.infiniteSessions,
-          disableResume: config.disableResume
-        });
-        const { sessionId: resumedSessionId, workspacePath } = response;
-        const session = new CopilotSession(resumedSessionId, this.connection, workspacePath);
+          this.connection,
+          void 0,
+          this.onGetTraceContext
+        );
         session.registerTools(config.tools);
         session.registerPermissionHandler(config.onPermissionRequest);
         if (config.onUserInputRequest) {
@@ -4375,7 +4546,55 @@ var init_client = __esm({
         if (config.hooks) {
           session.registerHooks(config.hooks);
         }
-        this.sessions.set(resumedSessionId, session);
+        const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
+          config.systemMessage
+        );
+        if (transformCallbacks) {
+          session.registerTransformCallbacks(transformCallbacks);
+        }
+        if (config.onEvent) {
+          session.on(config.onEvent);
+        }
+        this.sessions.set(sessionId, session);
+        try {
+          const response = await this.connection.sendRequest("session.resume", {
+            ...await getTraceContext(this.onGetTraceContext),
+            sessionId,
+            clientName: config.clientName,
+            model: config.model,
+            reasoningEffort: config.reasoningEffort,
+            systemMessage: wireSystemMessage,
+            availableTools: config.availableTools,
+            excludedTools: config.excludedTools,
+            tools: config.tools?.map((tool) => ({
+              name: tool.name,
+              description: tool.description,
+              parameters: toJsonSchema(tool.parameters),
+              overridesBuiltInTool: tool.overridesBuiltInTool,
+              skipPermission: tool.skipPermission
+            })),
+            provider: config.provider,
+            requestPermission: true,
+            requestUserInput: !!config.onUserInputRequest,
+            hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
+            workingDirectory: config.workingDirectory,
+            configDir: config.configDir,
+            streaming: config.streaming,
+            mcpServers: config.mcpServers,
+            envValueMode: "direct",
+            customAgents: config.customAgents,
+            agent: config.agent,
+            skillDirectories: config.skillDirectories,
+            disabledSkills: config.disabledSkills,
+            infiniteSessions: config.infiniteSessions,
+            disableResume: config.disableResume
+          });
+          const { workspacePath } = response;
+          session["_workspacePath"] = workspacePath;
+        } catch (e) {
+          this.sessions.delete(sessionId);
+          throw e;
+        }
         return session;
       }
       /**
@@ -4436,15 +4655,15 @@ var init_client = __esm({
       /**
        * List available models with their metadata.
        *
+       * If an `onListModels` handler was provided in the client options,
+       * it is called instead of querying the CLI server.
+       *
        * Results are cached after the first successful call to avoid rate limiting.
        * The cache is cleared when the client disconnects.
        *
-       * @throws Error if not authenticated
+       * @throws Error if not connected (when no custom handler is set)
        */
       async listModels() {
-        if (!this.connection) {
-          throw new Error("Client not connected");
-        }
         await this.modelsCacheLock;
         let resolveLock;
         this.modelsCacheLock = new Promise((resolve) => {
@@ -4454,10 +4673,18 @@ var init_client = __esm({
           if (this.modelsCache !== null) {
             return [...this.modelsCache];
           }
-          const result = await this.connection.sendRequest("models.list", {});
-          const response = result;
-          const models = response.models;
-          this.modelsCache = models;
+          let models;
+          if (this.onListModels) {
+            models = await this.onListModels();
+          } else {
+            if (!this.connection) {
+              throw new Error("Client not connected");
+            }
+            const result = await this.connection.sendRequest("models.list", {});
+            const response = result;
+            models = response.models;
+          }
+          this.modelsCache = [...models];
           return [...models];
         } finally {
           resolveLock();
@@ -4670,6 +4897,27 @@ var init_client = __esm({
           if (this.options.githubToken) {
             envWithoutNodeDebug.COPILOT_SDK_AUTH_TOKEN = this.options.githubToken;
           }
+          if (!this.options.cliPath) {
+            throw new Error(
+              "Path to Copilot CLI is required. Please provide it via the cliPath option, or use cliUrl to rely on a remote CLI."
+            );
+          }
+          if (this.options.telemetry) {
+            const t = this.options.telemetry;
+            envWithoutNodeDebug.COPILOT_OTEL_ENABLED = "true";
+            if (t.otlpEndpoint !== void 0)
+              envWithoutNodeDebug.OTEL_EXPORTER_OTLP_ENDPOINT = t.otlpEndpoint;
+            if (t.filePath !== void 0)
+              envWithoutNodeDebug.COPILOT_OTEL_FILE_EXPORTER_PATH = t.filePath;
+            if (t.exporterType !== void 0)
+              envWithoutNodeDebug.COPILOT_OTEL_EXPORTER_TYPE = t.exporterType;
+            if (t.sourceName !== void 0)
+              envWithoutNodeDebug.COPILOT_OTEL_SOURCE_NAME = t.sourceName;
+            if (t.captureContent !== void 0)
+              envWithoutNodeDebug.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT = String(
+                t.captureContent
+              );
+          }
           if (!existsSync(this.options.cliPath)) {
             throw new Error(
               `Copilot CLI not found at ${this.options.cliPath}. Ensure @github/copilot is installed.`
@@ -4769,8 +5017,6 @@ stderr: ${stderrOutput}`
               } else {
                 reject(new Error(`CLI server exited with code ${code}`));
               }
-            } else if (this.options.autoRestart && this.state === "connected") {
-              void this.reconnect();
             }
           });
           setTimeout(() => {
@@ -4875,12 +5121,15 @@ stderr: ${stderrOutput}`
           "hooks.invoke",
           async (params) => await this.handleHooksInvoke(params)
         );
+        this.connection.onRequest(
+          "systemMessage.transform",
+          async (params) => await this.handleSystemMessageTransform(params)
+        );
         this.connection.onClose(() => {
-          if (this.state === "connected" && this.options.autoRestart) {
-            void this.reconnect();
-          }
+          this.state = "disconnected";
         });
         this.connection.onError((_error) => {
+          this.state = "disconnected";
         });
       }
       handleSessionEventNotification(notification) {
@@ -4939,6 +5188,16 @@ stderr: ${stderrOutput}`
         const output = await session._handleHooksInvoke(params.hookType, params.input);
         return { output };
       }
+      async handleSystemMessageTransform(params) {
+        if (!params || typeof params.sessionId !== "string" || !params.sections || typeof params.sections !== "object") {
+          throw new Error("Invalid systemMessage.transform payload");
+        }
+        const session = this.sessions.get(params.sessionId);
+        if (!session) {
+          throw new Error(`Session not found: ${params.sessionId}`);
+        }
+        return await session._handleSystemMessageTransform(params.sections);
+      }
       // ========================================================================
       // Protocol v2 backward-compatibility adapters
       // ========================================================================
@@ -4967,11 +5226,15 @@ stderr: ${stderrOutput}`
           };
         }
         try {
+          const traceparent = params.traceparent;
+          const tracestate = params.tracestate;
           const invocation = {
             sessionId: params.sessionId,
             toolCallId: params.toolCallId,
             toolName: params.toolName,
-            arguments: params.arguments
+            arguments: params.arguments,
+            traceparent,
+            tracestate
           };
           const result = await handler(params.arguments, invocation);
           return { result: this.normalizeToolResultV2(result) };
@@ -5001,7 +5264,10 @@ stderr: ${stderrOutput}`
         try {
           const result = await session._handlePermissionRequestV2(params.permissionRequest);
           return { result };
-        } catch (_error) {
+        } catch (error) {
+          if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
+            throw error;
+          }
           return {
             result: {
               kind: "denied-no-approval-rule-and-could-not-request-from-user"
@@ -5031,17 +5297,6 @@ stderr: ${stderrOutput}`
       isToolResultObject(value) {
         return typeof value === "object" && value !== null && "textResultForLlm" in value && typeof value.textResultForLlm === "string" && "resultType" in value;
       }
-      /**
-       * Attempt to reconnect to the server
-       */
-      async reconnect() {
-        this.state = "disconnected";
-        try {
-          await this.stop();
-          await this.start();
-        } catch (_error) {
-        }
-      }
     };
   }
 });
@@ -5050,10 +5305,24 @@ stderr: ${stderrOutput}`
 function defineTool(name, config) {
   return { name, ...config };
 }
-var approveAll;
+var SYSTEM_PROMPT_SECTIONS, approveAll;
 var init_types = __esm({
   "node_modules/@github/copilot-sdk/dist/types.js"() {
     "use strict";
+    SYSTEM_PROMPT_SECTIONS = {
+      identity: { description: "Agent identity preamble and mode statement" },
+      tone: { description: "Response style, conciseness rules, output formatting preferences" },
+      tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
+      environment_context: { description: "CWD, OS, git root, directory listing, available tools" },
+      code_change_rules: { description: "Coding rules, linting/testing, ecosystem tools, style" },
+      guidelines: { description: "Tips, behavioral best practices, behavioral guidelines" },
+      safety: { description: "Environment limitations, prohibited actions, security policies" },
+      tool_instructions: { description: "Per-tool usage instructions" },
+      custom_instructions: { description: "Repository and organization custom instructions" },
+      last_instructions: {
+        description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
+      }
+    };
     approveAll = () => ({ kind: "approved" });
   }
 });
@@ -5063,6 +5332,7 @@ var dist_exports = {};
 __export(dist_exports, {
   CopilotClient: () => CopilotClient,
   CopilotSession: () => CopilotSession,
+  SYSTEM_PROMPT_SECTIONS: () => SYSTEM_PROMPT_SECTIONS,
   approveAll: () => approveAll,
   defineTool: () => defineTool
 });
@@ -5076,7 +5346,7 @@ var init_dist = __esm({
 });
 
 // src/cli.ts
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 
 // packages/core/src/config.ts
 var DEFAULT_MODEL = "claude-sonnet-4.6";
@@ -5332,6 +5602,18 @@ async function fileExists(filePath) {
     return false;
   }
 }
+async function canSafeWrite(filePath, force) {
+  const resolved = path.resolve(filePath);
+  if (await hasSymlinkAncestor(resolved)) return false;
+  try {
+    const stat = await fs.lstat(resolved);
+    if (stat.isSymbolicLink()) return false;
+    return force;
+  } catch (error) {
+    if (error.code === "ENOENT") return true;
+    throw error;
+  }
+}
 async function safeReadDir(dirPath) {
   try {
     return await fs.readdir(dirPath);
@@ -5339,10 +5621,47 @@ async function safeReadDir(dirPath) {
     return [];
   }
 }
+function stripJsonComments(text) {
+  let result = "";
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === '"') {
+      let j = i + 1;
+      while (j < text.length) {
+        if (text[j] === "\\") {
+          j += 2;
+          continue;
+        }
+        if (text[j] === '"') {
+          j++;
+          break;
+        }
+        j++;
+      }
+      result += text.slice(i, j);
+      i = j;
+      continue;
+    }
+    if (text[i] === "/" && text[i + 1] === "/") {
+      i += 2;
+      while (i < text.length && text[i] !== "\n") i++;
+      continue;
+    }
+    if (text[i] === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      if (i < text.length) i += 2;
+      continue;
+    }
+    result += text[i];
+    i++;
+  }
+  return result;
+}
 async function readJson(filePath) {
   try {
     const raw = await fs.readFile(filePath, "utf8");
-    return JSON.parse(raw);
+    return JSON.parse(stripJsonComments(raw));
   } catch {
     return void 0;
   }
@@ -5357,7 +5676,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 +5699,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 +5718,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 +5735,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 +5799,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");
@@ -6626,14 +6991,14 @@ async function checkReposForInstructions(token, repos, onProgress) {
 }
 
 // packages/core/src/services/batch.ts
-import path9 from "path";
+import path10 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 +7010,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 +7029,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 +7043,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 +7053,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*"
@@ -6910,7 +7275,7 @@ async function checkReposForInstructions2(token, repos, onProgress) {
 
 // packages/core/src/services/instructions.ts
 import fs5 from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 
 // packages/core/src/services/copilot.ts
 import fs4 from "fs/promises";
@@ -6953,8 +7318,32 @@ async function assertCopilotCliReady() {
 async function listCopilotModels() {
   const config = await assertCopilotCliReady();
   const [cmd, args2] = buildExecArgs(config, ["--help"]);
-  const { stdout } = await execFileAsync2(cmd, args2, { timeout: 5e3 });
-  return extractModelChoices(stdout);
+  let stdout = "";
+  let stderr = "";
+  let execError = null;
+  try {
+    const result = await execFileAsync2(cmd, args2, { timeout: 5e3 });
+    stdout = result.stdout;
+    stderr = result.stderr;
+  } catch (err) {
+    execError = err;
+    const e = err;
+    stdout = e.stdout ?? "";
+    stderr = e.stderr ?? "";
+  }
+  const fromStdout = extractModelChoices(stdout);
+  if (fromStdout.length > 0) return fromStdout;
+  const fromStderr = extractModelChoices(stderr);
+  if (fromStderr.length > 0) return fromStderr;
+  if (execError) {
+    const e = execError;
+    const details = e.stderr || e.stdout;
+    const detailMsg = details ? `
+Copilot CLI output:
+${details}` : "";
+    throw new Error(`Failed to list Copilot models: ${e.message}${detailMsg}`);
+  }
+  return [];
 }
 function buildExecArgs(config, extraArgs) {
   if (config.cliArgs && config.cliArgs.length > 0) {
@@ -7163,7 +7552,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 +7672,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 {
@@ -7325,6 +7719,25 @@ async function createCopilotClient(cliConfig) {
   }
 }
 
+// packages/core/src/services/skills.ts
+import path6 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var overrideSkillsDir;
+function getBuiltinSkillsDir() {
+  if (overrideSkillsDir) {
+    return overrideSkillsDir;
+  }
+  const thisFile = fileURLToPath2(import.meta.url);
+  const thisDir = path6.dirname(thisFile);
+  if (thisDir.includes(path6.join("packages", "core", "src"))) {
+    return path6.resolve(thisDir, "..", "..", "..", "..", "plugin", "skills");
+  }
+  return path6.resolve(thisDir, "skills");
+}
+function getSkillDirectory(_skillName) {
+  return getBuiltinSkillsDir();
+}
+
 // packages/core/src/services/instructions.ts
 async function detectExistingInstructions(repoPath, detailDirName = ".agents") {
   const { agentsMdFiles, claudeMdFiles } = await findInstructionMarkerFiles(repoPath);
@@ -7348,7 +7761,7 @@ async function findInstructionMarkerFiles(repoPath) {
           claudeMdFiles.push(relPath ? `${relPath}/${entry.name}` : entry.name);
         }
       } else if (entry.isDirectory()) {
-        await walk(path6.join(dir, entry.name), relPath ? `${relPath}/${entry.name}` : entry.name);
+        await walk(path7.join(dir, entry.name), relPath ? `${relPath}/${entry.name}` : entry.name);
       }
     }
   }
@@ -7356,7 +7769,7 @@ async function findInstructionMarkerFiles(repoPath) {
   return { agentsMdFiles: agentsMdFiles.sort(), claudeMdFiles: claudeMdFiles.sort() };
 }
 async function findModularInstructionFiles(repoPath) {
-  const dir = path6.join(repoPath, ".github", "instructions");
+  const dir = path7.join(repoPath, ".github", "instructions");
   const entries = await fs5.readdir(dir, { withFileTypes: true }).catch(() => []);
   return entries.filter((e) => !e.isSymbolicLink() && e.isFile() && e.name.endsWith(".instructions.md")).map((e) => `.github/instructions/${e.name}`).sort();
 }
@@ -7370,7 +7783,7 @@ async function findDetailFiles(repoPath, detailDirName) {
       if (entry.isSymbolicLink()) continue;
       if (entry.isDirectory()) {
         if (entry.name === detailDirName) {
-          const detailDir = path6.join(dir, entry.name);
+          const detailDir = path7.join(dir, entry.name);
           const detailEntries = await fs5.readdir(detailDir, { withFileTypes: true }).catch(() => []);
           for (const de of detailEntries) {
             if (!de.isSymbolicLink() && de.isFile() && de.name.endsWith(".md")) {
@@ -7379,7 +7792,7 @@ async function findDetailFiles(repoPath, detailDirName) {
             }
           }
         } else {
-          await walk(path6.join(dir, entry.name), relPath ? `${relPath}/${entry.name}` : entry.name);
+          await walk(path7.join(dir, entry.name), relPath ? `${relPath}/${entry.name}` : entry.name);
         }
       }
     }
@@ -7461,11 +7874,11 @@ function isCopilotAuthError(error) {
   return error instanceof Error && error.message.includes("Copilot CLI not logged in.");
 }
 function resolveAreaWorkingDirectory(repoPath, area) {
-  const repoRoot = path6.resolve(repoPath);
+  const repoRoot = path7.resolve(repoPath);
   const rawWorkingDirectory = area?.workingDirectory ?? area?.path;
   if (!rawWorkingDirectory) return repoRoot;
-  const resolved = area?.workingDirectory ? path6.resolve(repoRoot, rawWorkingDirectory) : path6.isAbsolute(rawWorkingDirectory) ? path6.resolve(rawWorkingDirectory) : path6.resolve(repoRoot, rawWorkingDirectory);
-  if (resolved !== repoRoot && !resolved.startsWith(repoRoot + path6.sep)) {
+  const resolved = area?.workingDirectory ? path7.resolve(repoRoot, rawWorkingDirectory) : path7.isAbsolute(rawWorkingDirectory) ? path7.resolve(rawWorkingDirectory) : path7.resolve(repoRoot, rawWorkingDirectory);
+  if (resolved !== repoRoot && !resolved.startsWith(repoRoot + path7.sep)) {
     throw new Error(`Invalid workingDirectory "${rawWorkingDirectory}": escapes repo boundary`);
   }
   return resolved;
@@ -7497,6 +7910,7 @@ async function generateCopilotInstructions(options) {
     const preferredModel = options.model ?? DEFAULT_MODEL;
     const systemContent = hasExistingInstructions ? "You are an expert codebase analyst. Your task is to generate a concise .github/copilot-instructions.md that complements existing instruction files. Use the available tools (glob, view, grep) 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 .github/copilot-instructions.md file. Use the available tools (glob, view, grep) to explore the codebase. When done, call the emit_file_content tool with the final markdown.";
     const { tool: emitTool, getContent } = await createEmitTool();
+    const rootSkillDir = getSkillDirectory("root-instructions");
     const session = await client.createSession({
       model: preferredModel,
       streaming: true,
@@ -7507,7 +7921,8 @@ async function generateCopilotInstructions(options) {
       tools: [emitTool],
       excludedTools: INSTRUCTION_GENERATION_EXCLUDED_TOOLS,
       onPermissionRequest: READ_ONLY_PERMISSION_HANDLER,
-      infiniteSessions: { enabled: false }
+      infiniteSessions: { enabled: false },
+      skillDirectories: [rootSkillDir]
     });
     await trySetAutopilot(session);
     let content = "";
@@ -7528,22 +7943,8 @@ async function generateCopilotInstructions(options) {
         sessionError = getSessionError(errorMsg);
       }
     });
-    const prompt = `Analyze this codebase and generate a .github/copilot-instructions.md file.
-
-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.
-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)
-
-Generate concise instructions (~20-50 lines) covering:
-- Tech stack and architecture
-- Build/test commands
-- Project-specific conventions
-- Key files/directories
-- Monorepo structure and per-app layout (if this is a monorepo, describe the workspace organization, how apps relate to each other, and any shared libraries)
-${existingSection}
-When you have the complete markdown content, call the \`emit_file_content\` tool with it. Do NOT output the file content directly in chat.`;
+    const prompt = `/root-instructions Analyze this codebase and generate a .github/copilot-instructions.md file.
+${existingSection}`;
     progress("Analyzing codebase...");
     let sendError;
     try {
@@ -7578,8 +7979,9 @@ 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 areaSkillDir = getSkillDirectory("area-instructions");
     const session = await client.createSession({
       model: preferredModel,
       streaming: true,
@@ -7590,7 +7992,8 @@ async function generateAreaInstructions(options) {
       tools: [emitTool],
       excludedTools: INSTRUCTION_GENERATION_EXCLUDED_TOOLS,
       onPermissionRequest: READ_ONLY_PERMISSION_HANDLER,
-      infiniteSessions: { enabled: false }
+      infiniteSessions: { enabled: false },
+      skillDirectories: [areaSkillDir]
     });
     await trySetAutopilot(session);
     let content = "";
@@ -7611,30 +8014,13 @@ 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 = `/area-instructions 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}` : ""}
-
-Use tools to explore ONLY the files and directories within this area:
-1. List the key files: glob for ${applyToPatterns.map((p) => `"${p}"`).join(", ")}
-2. Identify the tech stack, dependencies, and frameworks used in this area
-3. Look at key source files to understand patterns and conventions specific to this area
-
-Generate concise instructions (~10-30 lines) covering:
-- What this area does and its role in the overall project
-- Area-specific tech stack, dependencies, and frameworks
-- Coding conventions and patterns specific to this area
-- Build/test commands relevant to this area (if different from root)
-- Key files and directory structure within this area
-
-IMPORTANT:
-- Focus ONLY on this specific area, not the whole repo
-- Do NOT repeat repo-wide information (that goes in the root copilot-instructions.md)
-- Keep it complementary to root instructions
-${existingSection ? `- Do NOT duplicate content already covered by existing instruction files
-${existingSection}` : ""}
-- When you have the complete markdown content, call the \`emit_file_content\` tool with it. Do NOT output the file content directly in chat.`;
+${existingSection ? `
+Do NOT duplicate content already covered by existing instruction files
+${existingSection}` : ""}`;
     progress(`Analyzing area "${area.name}"...`);
     let sendError;
     try {
@@ -7671,7 +8057,7 @@ ${body}
 `;
 }
 function areaInstructionPath(repoPath, area) {
-  return path6.join(
+  return path7.join(
     repoPath,
     ".github",
     "instructions",
@@ -7681,7 +8067,7 @@ function areaInstructionPath(repoPath, area) {
 async function writeAreaInstruction(repoPath, area, body, force) {
   const filePath = areaInstructionPath(repoPath, area);
   if (!body.trim()) return { status: "empty", filePath };
-  await ensureDir(path6.dirname(filePath));
+  await ensureDir(path7.dirname(filePath));
   const { wrote, reason } = await safeWriteFile(
     filePath,
     buildAreaInstructionContent(area, body),
@@ -7693,13 +8079,13 @@ async function writeAreaInstruction(repoPath, area, body, force) {
   return { status: "written", filePath };
 }
 async function writeInstructionFile(repoPath, relativePath, content, force) {
-  const resolvedRoot = path6.resolve(repoPath);
-  const filePath = path6.resolve(repoPath, relativePath);
-  if (!filePath.startsWith(resolvedRoot + path6.sep) && filePath !== resolvedRoot) {
+  const resolvedRoot = path7.resolve(repoPath);
+  const filePath = path7.resolve(repoPath, relativePath);
+  if (!filePath.startsWith(resolvedRoot + path7.sep) && filePath !== resolvedRoot) {
     throw new Error(`Invalid path: escapes repository root (${relativePath})`);
   }
   if (!content.trim()) return { status: "empty", filePath };
-  await ensureDir(path6.dirname(filePath));
+  await ensureDir(path7.dirname(filePath));
   const { wrote, reason } = await safeWriteFile(filePath, content, Boolean(force));
   if (!wrote) {
     return { status: reason === "symlink" ? "symlink" : "skipped", filePath };
@@ -7783,6 +8169,7 @@ async function generateNestedHub(client, options) {
   const existingCtx = await detectExistingInstructions(options.repoPath, options.detailDir);
   const existingSection = buildExistingInstructionsSection(existingCtx);
   const { tool: emitTool, getContent } = await createEmitTool();
+  const nestedSkillDir = getSkillDirectory("nested-hub");
   const session = await client.createSession({
     model,
     streaming: true,
@@ -7793,7 +8180,8 @@ async function generateNestedHub(client, options) {
     tools: [emitTool],
     excludedTools: INSTRUCTION_GENERATION_EXCLUDED_TOOLS,
     onPermissionRequest: READ_ONLY_PERMISSION_HANDLER,
-    infiniteSessions: { enabled: false }
+    infiniteSessions: { enabled: false },
+    skillDirectories: [nestedSkillDir]
   });
   await trySetAutopilot(session);
   let content = "";
@@ -7825,29 +8213,14 @@ ${options.childAreas.map((c) => `- ${c.name} (${c.path ?? "unknown path"})`).joi
 Include a "## Sub-Projects" section with links to each child's AGENTS.md.` : "";
   const parentContext = options.area?.parentArea ? `
 This is a sub-project of "${options.area.parentArea}". Include a note linking back to the parent area.` : "";
-  const prompt = `Analyze this codebase and generate a lean AGENTS.md hub file (~90-120 lines).${areaContext}${parentContext}
-
-Use tools to explore the codebase structure, tech stack, and conventions.
+  const prompt = `/nested-hub Generate a lean AGENTS.md hub file (~90-120 lines).${areaContext}${parentContext}
 
-The hub should contain:
-- Project overview and purpose
-- Key concepts and architecture
-- Coding conventions and guardrails
-- A "## Detailed Instructions" section listing links to detail files in \`${options.detailDir}/\`${childContext}
+Detail files go in \`${options.detailDir}/\`.${childContext}
 
-At the END of your output, emit a fenced JSON block with recommended topics for detail files:
-\`\`\`json
-[{"slug":"testing","title":"Testing Guide","description":"How to write and run tests"},{"slug":"architecture","title":"Architecture","description":"Codebase structure and patterns"}]
-\`\`\`
-
-Recommend 3-5 topics that would benefit from deep-dive detail files. Each slug becomes a filename: \`${options.detailDir}/{slug}.md\`.
-
-IMPORTANT:
-- Keep the hub LEAN \u2014 overview and guardrails only, details go in separate files
-- The JSON block will be parsed and removed from the final output
-${existingSection ? `- Do NOT duplicate content from existing instruction files
-${existingSection}` : ""}
-- When you have the complete markdown content (including the trailing JSON topic block), call the \`emit_file_content\` tool with it. Do NOT output the content directly in chat.`;
+Recommend 3-5 topics for deep-dive detail files. Each slug becomes: \`${options.detailDir}/{slug}.md\`.
+${existingSection ? `
+Do NOT duplicate content from existing instruction files
+${existingSection}` : ""}`;
   let sendError;
   try {
     await session.sendAndWait({ prompt }, 18e4);
@@ -7871,6 +8244,7 @@ async function generateNestedDetail(client, options) {
   });
   const model = options.model ?? DEFAULT_MODEL;
   const { tool: emitTool, getContent } = await createEmitTool();
+  const detailSkillDir = getSkillDirectory("nested-detail");
   const session = await client.createSession({
     model,
     streaming: true,
@@ -7881,7 +8255,8 @@ async function generateNestedDetail(client, options) {
     tools: [emitTool],
     excludedTools: INSTRUCTION_GENERATION_EXCLUDED_TOOLS,
     onPermissionRequest: READ_ONLY_PERMISSION_HANDLER,
-    infiniteSessions: { enabled: false }
+    infiniteSessions: { enabled: false },
+    skillDirectories: [detailSkillDir]
   });
   await trySetAutopilot(session);
   let content = "";
@@ -7903,22 +8278,11 @@ async function generateNestedDetail(client, options) {
     }
   });
   const areaContext = options.area ? `Focus on the "${options.area.name}" area (files matching: ${Array.isArray(options.area.applyTo) ? options.area.applyTo.join(", ") : options.area.applyTo}).` : "Focus on the entire repository.";
-  const prompt = `Generate a deep-dive instruction file about "${options.topic.title}" for this codebase.
+  const prompt = `/nested-detail Generate a deep-dive instruction file about "${options.topic.title}" for this codebase.
 ${areaContext}
 
 Topic: ${options.topic.title}
-Description: ${options.topic.description}
-
-Use tools to explore the codebase and understand the specific patterns, APIs, and conventions related to this topic.
-
-The file should:
-- Start with \`# ${options.topic.title}\`
-- Include \`**When to read:** {one-line trigger condition}\` right after the heading
-- Cover ~50-100 lines of practical, actionable guidance
-- Include code patterns and examples found in the actual codebase
-- Be specific to this codebase, not generic advice
-
-When you have the complete markdown content, call the \`emit_file_content\` tool with it. Do NOT output the content directly in chat.`;
+Description: ${options.topic.description}`;
   let sendError;
   try {
     await session.sendAndWait({ prompt }, 18e4);
@@ -7953,7 +8317,7 @@ async function generateNestedInstructions(options) {
       onProgress: options.onProgress
     });
     const basePath = options.area?.path ?? ".";
-    const hubRelativePath = path6.join(basePath, "AGENTS.md");
+    const hubRelativePath = path7.join(basePath, "AGENTS.md");
     let finalHubContent = hubContent;
     if (options.area) {
       finalHubContent = `${buildAreaFrontmatter(options.area)}
@@ -7977,7 +8341,7 @@ ${hubContent}`;
         });
         if (detailContent) {
           result.details.push({
-            relativePath: path6.join(basePath, options.detailDir, `${topic.slug}.md`),
+            relativePath: path7.join(basePath, options.detailDir, `${topic.slug}.md`),
             content: detailContent,
             topic: topic.title
           });
@@ -7992,7 +8356,7 @@ ${hubContent}`;
     }
     if (options.claudeMd) {
       result.claudeMd = {
-        relativePath: path6.join(basePath, "CLAUDE.md"),
+        relativePath: path7.join(basePath, "CLAUDE.md"),
         content: "@AGENTS.md\n"
       };
     }
@@ -8015,11 +8379,11 @@ async function generateNestedAreaInstructions(options) {
 
 // packages/core/src/services/readiness.ts
 import fs7 from "fs/promises";
-import path8 from "path";
+import path9 from "path";
 
 // packages/core/src/services/policy.ts
 import fs6 from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 var DEFAULT_PASS_RATE = 0.8;
 function validatePolicyConfig(obj, source, format = "module") {
   if (typeof obj !== "object" || obj === null) {
@@ -8112,8 +8476,8 @@ function parsePolicySources(raw) {
 }
 async function loadPolicy(source, options) {
   const jsonOnly = options?.jsonOnly ?? false;
-  if (source.startsWith(".") || path7.isAbsolute(source)) {
-    const resolved = path7.resolve(source);
+  if (source.startsWith(".") || path8.isAbsolute(source)) {
+    const resolved = path8.resolve(source);
     if (resolved.endsWith(".json")) {
       const data = await readJson(resolved);
       if (!data) {
@@ -8140,7 +8504,7 @@ async function loadPolicy(source, options) {
     }
     try {
       const raw = await fs6.readFile(resolved, "utf8");
-      const data = JSON.parse(raw);
+      const data = JSON.parse(stripJsonComments(raw));
       return validatePolicyConfig(data, source, "json");
     } catch {
       throw new Error(
@@ -8733,7 +9097,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."
@@ -8744,7 +9108,7 @@ async function runReadinessReport(options) {
   const repoPath = options.repoPath;
   const analysis = await analyzeRepo(repoPath);
   const rootFiles = await safeReadDir(repoPath);
-  const rootPackageJson = await readJson(path8.join(repoPath, "package.json"));
+  const rootPackageJson = await readJson(path9.join(repoPath, "package.json"));
   const apps = analysis.apps?.length ? analysis.apps : [];
   const context = {
     repoPath,
@@ -9053,7 +9417,7 @@ function buildCriteria() {
       impact: "medium",
       effort: "low",
       check: async (context) => {
-        const found = await fileExists(path8.join(context.repoPath, "CONTRIBUTING.md"));
+        const found = await fileExists(path9.join(context.repoPath, "CONTRIBUTING.md"));
         return {
           status: found ? "pass" : "fail",
           reason: found ? void 0 : "Missing CONTRIBUTING.md for contributor workflows."
@@ -9154,7 +9518,7 @@ function buildCriteria() {
       impact: "high",
       effort: "low",
       check: async (context) => {
-        const found = await fileExists(path8.join(context.repoPath, "SECURITY.md"));
+        const found = await fileExists(path9.join(context.repoPath, "SECURITY.md"));
         return {
           status: found ? "pass" : "fail",
           reason: found ? void 0 : "Missing SECURITY.md policy."
@@ -9170,7 +9534,7 @@ function buildCriteria() {
       impact: "medium",
       effort: "medium",
       check: async (context) => {
-        const found = await fileExists(path8.join(context.repoPath, ".github", "dependabot.yml"));
+        const found = await fileExists(path9.join(context.repoPath, ".github", "dependabot.yml"));
         return {
           status: found ? "pass" : "fail",
           reason: found ? void 0 : "Missing .github/dependabot.yml configuration."
@@ -9198,7 +9562,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 +9573,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 +9589,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]
           };
         }
@@ -9376,7 +9740,7 @@ function buildCriteria() {
         if (area?.scripts?.build) {
           return { status: "pass" };
         }
-        const pkgPath = path8.join(context.areaPath, "package.json");
+        const pkgPath = path9.join(context.areaPath, "package.json");
         const pkg = await readJson(pkgPath);
         const scripts = pkg?.scripts ?? {};
         const found = Boolean(scripts.build);
@@ -9401,7 +9765,7 @@ function buildCriteria() {
         if (area?.scripts?.test) {
           return { status: "pass" };
         }
-        const pkgPath = path8.join(context.areaPath, "package.json");
+        const pkgPath = path9.join(context.areaPath, "package.json");
         const pkg = await readJson(pkgPath);
         const scripts = pkg?.scripts ?? {};
         const found = Boolean(scripts.test);
@@ -9424,7 +9788,7 @@ function buildCriteria() {
           return { status: "skip", reason: "No area context." };
         }
         const sanitized = sanitizeAreaName(area.name);
-        const instructionPath = path8.join(
+        const instructionPath = path9.join(
           context.repoPath,
           ".github",
           "instructions",
@@ -9445,7 +9809,7 @@ function buildExtras() {
       id: "agents-doc",
       title: "AGENTS.md present",
       check: async (context) => {
-        const found = await fileExists(path8.join(context.repoPath, "AGENTS.md"));
+        const found = await fileExists(path9.join(context.repoPath, "AGENTS.md"));
         return {
           status: found ? "pass" : "fail",
           reason: found ? void 0 : "Missing AGENTS.md to guide coding agents."
@@ -9610,11 +9974,11 @@ async function hasTypecheckConfig(repoPath) {
   ]);
 }
 async function hasGithubWorkflows(repoPath) {
-  return fileExists(path8.join(repoPath, ".github", "workflows"));
+  return fileExists(path9.join(repoPath, ".github", "workflows"));
 }
 async function hasCodeowners(repoPath) {
-  const root = await fileExists(path8.join(repoPath, "CODEOWNERS"));
-  const github = await fileExists(path8.join(repoPath, ".github", "CODEOWNERS"));
+  const root = await fileExists(path9.join(repoPath, "CODEOWNERS"));
+  const github = await fileExists(path9.join(repoPath, ".github", "CODEOWNERS"));
   return root || github;
 }
 async function hasLicense(repoPath) {
@@ -9622,9 +9986,9 @@ async function hasLicense(repoPath) {
   return files.some((file) => file.toLowerCase().startsWith("license"));
 }
 async function hasPullRequestTemplate(repoPath) {
-  const direct = await fileExists(path8.join(repoPath, ".github", "PULL_REQUEST_TEMPLATE.md"));
+  const direct = await fileExists(path9.join(repoPath, ".github", "PULL_REQUEST_TEMPLATE.md"));
   if (direct) return true;
-  const dir = path8.join(repoPath, ".github", "PULL_REQUEST_TEMPLATE");
+  const dir = path9.join(repoPath, ".github", "PULL_REQUEST_TEMPLATE");
   try {
     const entries = await fs7.readdir(dir);
     return entries.some((entry) => entry.toLowerCase().endsWith(".md"));
@@ -9633,14 +9997,14 @@ async function hasPullRequestTemplate(repoPath) {
   }
 }
 async function hasPrecommitConfig(repoPath) {
-  const precommit = await fileExists(path8.join(repoPath, ".pre-commit-config.yaml"));
+  const precommit = await fileExists(path9.join(repoPath, ".pre-commit-config.yaml"));
   if (precommit) return true;
-  return fileExists(path8.join(repoPath, ".husky"));
+  return fileExists(path9.join(repoPath, ".husky"));
 }
 async function hasArchitectureDoc(repoPath) {
   const files = await safeReadDir(repoPath);
   if (files.some((file) => file.toLowerCase() === "architecture.md")) return true;
-  return fileExists(path8.join(repoPath, "docs", "architecture.md"));
+  return fileExists(path9.join(repoPath, "docs", "architecture.md"));
 }
 async function hasCustomInstructions(repoPath) {
   const found = [];
@@ -9657,14 +10021,14 @@ async function hasCustomInstructions(repoPath) {
     "copilot-instructions.md"
   ];
   for (const candidate of candidates) {
-    if (await fileExists(path8.join(repoPath, candidate))) {
+    if (await fileExists(path9.join(repoPath, candidate))) {
       found.push(candidate);
     }
   }
   return found;
 }
 async function hasFileBasedInstructions(repoPath) {
-  const instructionsDir = path8.join(repoPath, ".github", "instructions");
+  const instructionsDir = path9.join(repoPath, ".github", "instructions");
   try {
     const entries = await fs7.readdir(instructionsDir);
     return entries.filter((e) => e.endsWith(".instructions.md")).map((e) => `.github/instructions/${e}`);
@@ -9692,7 +10056,7 @@ async function checkInstructionConsistency(repoPath, foundFiles) {
   }
   const realPathMap = /* @__PURE__ */ new Map();
   for (const file of foundFiles) {
-    const fullPath = path8.join(repoPath, file);
+    const fullPath = path9.join(repoPath, file);
     try {
       const real = await fs7.realpath(fullPath);
       const group = realPathMap.get(real) ?? [];
@@ -9709,7 +10073,7 @@ async function checkInstructionConsistency(repoPath, foundFiles) {
   const contents = [];
   for (const group of groups) {
     try {
-      contents.push(await fs7.readFile(path8.join(repoPath, group[0]), "utf8"));
+      contents.push(await fs7.readFile(path9.join(repoPath, group[0]), "utf8"));
     } catch {
       contents.push("");
     }
@@ -9728,17 +10092,17 @@ async function checkInstructionConsistency(repoPath, foundFiles) {
 }
 async function hasMcpConfig(repoPath) {
   const found = [];
-  if (await fileExists(path8.join(repoPath, ".vscode", "mcp.json"))) {
+  if (await fileExists(path9.join(repoPath, ".vscode", "mcp.json"))) {
     found.push(".vscode/mcp.json");
   }
-  if (await fileExists(path8.join(repoPath, "mcp.json"))) {
+  if (await fileExists(path9.join(repoPath, "mcp.json"))) {
     found.push("mcp.json");
   }
-  const settings = await readJson(path8.join(repoPath, ".vscode", "settings.json"));
+  const settings = await readJson(path9.join(repoPath, ".vscode", "settings.json"));
   if (settings && (settings["mcp"] || settings["github.copilot.chat.mcp.enabled"])) {
     found.push(".vscode/settings.json (mcp section)");
   }
-  if (await fileExists(path8.join(repoPath, ".claude", "mcp.json"))) {
+  if (await fileExists(path9.join(repoPath, ".claude", "mcp.json"))) {
     found.push(".claude/mcp.json");
   }
   return found;
@@ -9747,13 +10111,13 @@ async function hasCustomAgents(repoPath) {
   const found = [];
   const agentDirs = [".github/agents", ".copilot/agents", ".github/copilot/agents"];
   for (const dir of agentDirs) {
-    if (await fileExists(path8.join(repoPath, dir))) {
+    if (await fileExists(path9.join(repoPath, dir))) {
       found.push(dir);
     }
   }
   const agentFiles = [".github/copilot-agents.yml", ".github/copilot-agents.yaml"];
   for (const agentFile of agentFiles) {
-    if (await fileExists(path8.join(repoPath, agentFile))) {
+    if (await fileExists(path9.join(repoPath, agentFile))) {
       found.push(agentFile);
     }
   }
@@ -9768,7 +10132,7 @@ async function hasCopilotSkills(repoPath) {
     ".github/copilot/skills"
   ];
   for (const dir of skillDirs) {
-    if (await fileExists(path8.join(repoPath, dir))) {
+    if (await fileExists(path9.join(repoPath, dir))) {
       found.push(dir);
     }
   }
@@ -9821,7 +10185,7 @@ async function processRepo(params) {
   } = params;
   try {
     progress?.update(`${label}: Cloning...`);
-    const cacheRoot = path9.join(process.cwd(), ".agentrc-cache");
+    const cacheRoot = path10.join(process.cwd(), ".agentrc-cache");
     const repoPath = validateCachePath(cacheRoot, ...cacheParts);
     await ensureDir(repoPath);
     if (!await isGitRepo(repoPath)) {
@@ -9847,8 +10211,8 @@ async function processRepo(params) {
     if (!instructions.trim()) {
       throw new Error("Generated instructions were empty");
     }
-    const instructionsPath = path9.join(repoPath, ".github", "copilot-instructions.md");
-    await ensureDir(path9.dirname(instructionsPath));
+    const instructionsPath = path10.join(repoPath, ".github", "copilot-instructions.md");
+    await ensureDir(path10.dirname(instructionsPath));
     const { wrote, reason } = await safeWriteFile(instructionsPath, instructions, true);
     if (!wrote) {
       throw new Error(
@@ -9856,7 +10220,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 +10256,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 +10288,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
@@ -9985,7 +10349,7 @@ async function processBatchReadinessRepo(options) {
   try {
     progress(`Cloning ${repo.fullName}...`);
     const authedUrl = buildAuthedUrl(repo.cloneUrl, token, "github");
-    await ensureDir(path9.dirname(repoDir));
+    await ensureDir(path10.dirname(repoDir));
     await cloneRepo(authedUrl, repoDir, { shallow: true });
     await setRemoteUrl(repoDir, repo.cloneUrl).catch(() => {
     });
@@ -11035,15 +11399,11 @@ import { render as render2 } from "ink";
 // src/ui/BatchReadinessTui.tsx
 import fs8 from "fs/promises";
 import os from "os";
-import path10 from "path";
+import path11 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 +11972,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>
@@ -12065,7 +12425,7 @@ function BatchReadinessTui({ token, outputPath, policies }) {
     setStatus("processing");
     const selectedRepos = Array.from(selectedRepoIndices).map((i) => repos[i]);
     const results2 = [];
-    const tmpDir = path10.join(os.tmpdir(), `agentrc-batch-readiness-${Date.now()}`);
+    const tmpDir = path11.join(os.tmpdir(), `agentrc-batch-readiness-${Date.now()}`);
     try {
       await ensureDir(tmpDir);
       for (let i = 0; i < selectedRepos.length; i++) {
@@ -12099,10 +12459,10 @@ 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");
+      const finalOutputPath = outputPath ?? path11.join(process.cwd(), "batch-readiness-report.html");
       const { wrote, reason } = await safeWriteFile(finalOutputPath, html, true);
       if (!wrote) throw new Error(reason === "symlink" ? "Path is a symlink" : "Write failed");
       setStatus("complete");
@@ -12284,7 +12644,7 @@ async function batchReadinessCommand(options) {
 }
 
 // src/commands/eval.ts
-import path12 from "path";
+import path13 from "path";
 
 // packages/core/src/services/evalScaffold.ts
 var EVAL_SCAFFOLD_TIMEOUT_MS = 6e5;
@@ -12306,7 +12666,7 @@ async function generateEvalScaffold(options) {
       streaming: true,
       workingDirectory: repoPath,
       systemMessage: {
-        content: "You are an expert codebase analyst specializing in deep architectural analysis. Generate challenging, cross-cutting eval cases for this repository that require synthesizing information from multiple files and tracing logic across layers. Avoid trivial questions answerable from a single file read or grep. Use tools (glob, view, grep) extensively to inspect the codebase. Output ONLY JSON with keys: instructionFile, cases (array of {id,prompt,expectation})."
+        content: "Generate challenging implementation planning tasks for this repository. Each task should require cross-cutting changes across multiple files. Tasks can range from specific feature additions to broader refactoring plans. Avoid trivial tasks or pure Q&A questions. Output ONLY JSON with keys: instructionFile, cases (array of {id,prompt,expectation})."
       },
       infiniteSessions: { enabled: false }
     });
@@ -12348,32 +12708,37 @@ async function generateEvalScaffold(options) {
       'For areas with a workspace (workingDirectory), include a "workingDirectory" field set to that workspace path so evals run scoped to the correct folder.'
     ].join("\n") : "";
     const prompt = [
-      `Analyze this repository and generate ${count} eval cases.`,
+      `Analyze this repository and generate ${count} implementation planning tasks.`,
+      "",
+      "Each task should represent a REAL developer request \u2014 the kind of thing someone would actually type into a coding agent.",
+      "Tasks should require understanding MULTIPLE files and cross-cutting concerns.",
       "",
-      "IMPORTANT: Generate HARD eval cases that require deep, cross-cutting understanding of the codebase.",
-      "Each case should require synthesizing information from MULTIPLE files or tracing logic across several layers.",
-      "Do NOT generate simple questions that can be answered by reading a single file or running a single grep.",
+      "PROMPT RULES (the prompt field is what the eval agent receives):",
+      "- Write prompts as a developer would naturally phrase them \u2014 short, direct requests.",
+      "- Do NOT describe expected output format or what the response should include.",
+      "- Do NOT add meta-instructions like 'The output should show...' or 'Include in your plan...' or 'Your plan should cover...'",
+      "- Do NOT embed implementation details in the prompt (pillar names, levels, specific output formats) \u2014 those belong in the expectation.",
+      "- Good: 'Add a --dry-run flag to the generate command'",
+      "- Good: 'Add a readiness criterion for CI/CD detection'",
+      "- Bad: 'Add a --dry-run flag that previews what files would be created or modified. The output should show file paths and indicate whether each would be created, updated, or skipped.'",
+      "- Bad: 'Add a readiness criterion that checks for CI/CD and classifies it under a new deployment pillar at level 3'",
       "",
-      "Good eval case examples (adapt to this repo):",
-      "- Questions about how data flows end-to-end through multiple modules (e.g., 'Trace what happens when X is called \u2014 which services, transforms, and side effects are involved?')",
-      "- Questions about implicit conventions or patterns that span many files (e.g., 'What error-handling pattern is used across the service layer, and where does it deviate?')",
-      "- Questions requiring understanding of runtime behavior not obvious from static code (e.g., 'What is the order of initialization and what would break if module X loaded before Y?')",
-      "- Questions about non-obvious interactions between components (e.g., 'How does changing config option X affect the behavior of feature Y?')",
-      "- Questions about edge cases or failure modes that require reading implementation details across files",
-      "- Questions that require understanding the type system, generics, or shared interfaces across module boundaries",
+      "EXPECTATION RULES (the expectation field is checked by an LLM judge \u2014 be extremely specific):",
+      "- MUST cite exact file paths (e.g., 'packages/core/src/services/generator.ts')",
+      "- MUST cite exact function and type names (e.g., 'generateCopilotInstructions()', 'CommandResult<T>')",
+      "- MUST cite specific CLI commands for verification (e.g., 'npm run typecheck', 'npm test')",
+      "- MUST name the specific test file to update (e.g., 'src/services/__tests__/generator.test.ts')",
+      "- Generic expectations like 'identify the generator service' are USELESS \u2014 name the actual function and file.",
       "",
-      "Bad eval case examples (avoid these):",
-      "- 'What does this project do?' (answered by README alone)",
-      "- 'How do I build/test?' (answered by package.json alone)",
-      "- 'What is the entrypoint?' (answered by a single file)",
-      "- Any question answerable by reading one file or searching for one keyword",
+      "Bad task examples (avoid these):",
+      "- 'What does this project do?' (pure Q&A, not a planning task)",
+      "- 'Explain the architecture' (no implementation expected)",
+      "- Tasks with prescriptive output instructions baked into the prompt",
       "",
-      "Use tools extensively to inspect the codebase \u2014 read multiple files, trace imports, follow call chains.",
-      "If this is a monorepo (npm/pnpm/yarn workspaces, Cargo workspace, Go workspace, .NET solution, Gradle/Maven multi-module), generate cases that involve cross-app dependencies, shared libraries, and how changes in one app affect others.",
-      "Ensure cases cover cross-cutting concerns: data flow, error propagation, configuration impact, implicit coupling, architectural invariants.",
-      "Include a systemMessage that keeps answers scoped to this repository (avoid generic Copilot CLI details unless asked).",
+      "Do NOT generate a systemMessage \u2014 the default is used automatically.",
+      "If this is a monorepo, generate tasks that involve cross-app dependencies and shared libraries.",
       "Return JSON ONLY (no markdown, no commentary) in this schema:",
-      '{\n  "instructionFile": ".github/copilot-instructions.md",\n  "systemMessage": "...",\n  "cases": [\n    {"id": "case-1", "prompt": "...", "expectation": "...", "area": "optional-area-name"}\n  ]\n}',
+      options.areas?.length ? '{\n  "instructionFile": ".github/copilot-instructions.md",\n  "cases": [\n    {"id": "case-1", "prompt": "...", "expectation": "...", "area": "optional-area-name"}\n  ]\n}' : '{\n  "instructionFile": ".github/copilot-instructions.md",\n  "cases": [\n    {"id": "case-1", "prompt": "...", "expectation": "..."}\n  ]\n}',
       areaContext
     ].join("\n");
     progress("Analyzing codebase...");
@@ -12419,7 +12784,8 @@ async function generateEvalScaffold(options) {
       }
       throw error;
     }
-    const normalized = normalizeEvalConfig(parsed, count);
+    const hasAreas = Boolean(options.areas?.length);
+    const normalized = normalizeEvalConfig(parsed, count, hasAreas);
     return normalized;
   } finally {
     await client.stop();
@@ -12443,41 +12809,47 @@ function parseEvalConfig(raw) {
   }
   return parsed;
 }
-function normalizeEvalConfig(parsed, count) {
+function normalizeEvalConfig(parsed, count, hasAreas = true) {
   const cases = (parsed.cases ?? []).slice(0, count).map((entry, index) => {
     const id = typeof entry.id === "string" && entry.id.trim() ? entry.id : `case-${index + 1}`;
     return {
       id,
       prompt: String(entry.prompt ?? "").trim(),
-      expectation: String(entry.expectation ?? "").trim(),
-      area: typeof entry.area === "string" && entry.area.trim() ? entry.area.trim() : void 0,
+      expectation: normalizeExpectation(entry.expectation),
+      ...hasAreas && typeof entry.area === "string" && entry.area.trim() ? { area: entry.area.trim() } : {},
       workingDirectory: typeof entry.workingDirectory === "string" && entry.workingDirectory.trim() ? entry.workingDirectory.trim() : void 0
     };
   });
   if (!cases.length) {
     throw new Error("Eval scaffold JSON did not include any usable cases.");
   }
-  const defaultSystemMessage = "You are answering questions about this repository. Use tools to inspect the repo and cite its files. Avoid generic Copilot CLI details unless the prompt explicitly asks for them.";
   return {
     instructionFile: parsed.instructionFile ?? ".github/copilot-instructions.md",
-    systemMessage: parsed.systemMessage ?? defaultSystemMessage,
+    ...parsed.systemMessage ? { systemMessage: parsed.systemMessage } : {},
     cases
   };
 }
+function normalizeExpectation(value) {
+  if (Array.isArray(value)) {
+    const items = value.map((s) => String(s).trim()).filter(Boolean);
+    return items.length === 1 ? items[0] : items;
+  }
+  return String(value ?? "").trim();
+}
 
 // packages/core/src/services/evaluator.ts
 import fs9 from "fs/promises";
-import path11 from "path";
-var DEFAULT_SYSTEM_MESSAGE = "You are answering questions about this repository. Use tools to inspect the repo and cite its files. Avoid generic Copilot CLI details unless the prompt explicitly asks for them.";
+import path12 from "path";
+var DEFAULT_SYSTEM_MESSAGE = "Research using read-only tools and make a plan for the given task, including concrete implementation steps and verification steps.";
 async function runEval(options) {
   const config = await loadConfig(options.configPath);
   const instructionFile = config.instructionFile ?? ".github/copilot-instructions.md";
-  const instructionPath = path11.resolve(options.repoPath, instructionFile);
+  const instructionPath = path12.resolve(options.repoPath, instructionFile);
   const instructionText = await readOptionalFile(instructionPath);
   const baseSystemMessage = config.systemMessage ?? DEFAULT_SYSTEM_MESSAGE;
   const progress = options.onProgress ?? (() => {
   });
-  const defaultOutputPath = path11.resolve(
+  const defaultOutputPath = path12.resolve(
     options.repoPath,
     ".agentrc",
     "evals",
@@ -12497,9 +12869,9 @@ async function runEval(options) {
       const caseStartedAt = Date.now();
       let caseWorkingDir;
       if (testCase.workingDirectory) {
-        const resolved = path11.resolve(options.repoPath, testCase.workingDirectory);
-        const root = path11.resolve(options.repoPath);
-        if (resolved !== root && !resolved.startsWith(root + path11.sep)) {
+        const resolved = path12.resolve(options.repoPath, testCase.workingDirectory);
+        const root = path12.resolve(options.repoPath);
+        if (resolved !== root && !resolved.startsWith(root + path12.sep)) {
           throw new Error(
             `Invalid workingDirectory "${testCase.workingDirectory}": escapes repo boundary`
           );
@@ -12571,7 +12943,7 @@ async function runEval(options) {
     };
     let viewerPath;
     if (outputPath) {
-      await fs9.mkdir(path11.dirname(outputPath), { recursive: true });
+      await fs9.mkdir(path12.dirname(outputPath), { recursive: true });
       await safeWriteFile(outputPath, JSON.stringify(output, null, 2), true);
       viewerPath = buildViewerPath(outputPath);
       await safeWriteFile(viewerPath, buildTrajectoryViewerHtml(output), true);
@@ -12632,10 +13004,11 @@ async function judge(client, options) {
       if (delta) content += delta;
     }
   });
+  const expectationText = Array.isArray(options.expectation) ? options.expectation.join("\n") : options.expectation;
   const prompt = [
     "Evaluate which response best matches the expectation.",
     "",
-    `Expectation: ${options.expectation}`,
+    `Expectation: ${expectationText}`,
     "",
     "Response A (without custom instructions):",
     options.withoutInstructions,
@@ -12679,7 +13052,7 @@ function parseJudge(content) {
 }
 async function loadConfig(configPath) {
   const raw = await fs9.readFile(configPath, "utf8");
-  const parsed = JSON.parse(raw);
+  const parsed = JSON.parse(stripJsonComments(raw));
   if (!parsed || !Array.isArray(parsed.cases)) {
     throw new Error("Eval config must have a 'cases' array.");
   }
@@ -12885,7 +13258,7 @@ function formatTokenUsage(usage) {
 function resolveOutputPath(repoPath, override, configValue) {
   const chosen = override ?? configValue;
   if (!chosen) return void 0;
-  return path11.isAbsolute(chosen) ? chosen : path11.resolve(repoPath, chosen);
+  return path12.isAbsolute(chosen) ? chosen : path12.resolve(repoPath, chosen);
 }
 function buildViewerPath(outputPath) {
   if (outputPath.endsWith(".json")) {
@@ -13240,7 +13613,7 @@ function sanitizeValue(value, depth) {
 
 // src/commands/eval.ts
 async function evalCommand(configPathArg, options) {
-  const repoPath = path12.resolve(options.repo ?? process.cwd());
+  const repoPath = path13.resolve(options.repo ?? process.cwd());
   if (options.listModels) {
     try {
       const models = await listCopilotModels();
@@ -13276,7 +13649,7 @@ async function evalCommand(configPathArg, options) {
     return;
   }
   if (options.init) {
-    const outputPath = path12.join(repoPath, "agentrc.eval.json");
+    const outputPath = path13.join(repoPath, "agentrc.eval.json");
     const desiredCount = Math.max(1, Number.parseInt(options.count ?? "5", 10) || 5);
     try {
       const progress = createProgressReporter(!shouldLog(options));
@@ -13318,7 +13691,7 @@ async function evalCommand(configPathArg, options) {
     }
     return;
   }
-  const configPath = path12.resolve(configPathArg ?? path12.join(repoPath, "agentrc.eval.json"));
+  const configPath = path13.resolve(configPathArg ?? path13.join(repoPath, "agentrc.eval.json"));
   try {
     const progress = createProgressReporter(!shouldLog(options));
     const { summary, results, viewerPath } = await runEval({
@@ -13365,32 +13738,43 @@ async function evalCommand(configPathArg, options) {
 }
 
 // src/commands/generate.ts
-import path15 from "path";
+import path16 from "path";
 
 // packages/core/src/services/generator.ts
-import path13 from "path";
+import path14 from "path";
+async function writeOrPreview(filePath, content, opts) {
+  const relPath = path14.relative(process.cwd(), filePath);
+  if (opts.dryRun) {
+    const wouldWrite = await canSafeWrite(filePath, opts.force);
+    return {
+      path: relPath,
+      action: wouldWrite ? "wrote" : "skipped",
+      bytes: Buffer.byteLength(content, "utf8")
+    };
+  }
+  await ensureDir(path14.dirname(filePath));
+  const { wrote } = await safeWriteFile(filePath, content, opts.force);
+  return { path: relPath, action: wrote ? "wrote" : "skipped" };
+}
 async function generateConfigs(options) {
-  const { repoPath, analysis, selections, force } = options;
+  const { repoPath, analysis, selections, force, dryRun } = options;
   const files = [];
   if (selections.includes("mcp")) {
-    const filePath = path13.join(repoPath, ".vscode", "mcp.json");
-    await ensureDir(path13.dirname(filePath));
-    const content = renderMcp();
-    const { wrote } = await safeWriteFile(filePath, content, force);
-    files.push({
-      path: path13.relative(process.cwd(), filePath),
-      action: wrote ? "wrote" : "skipped"
-    });
+    files.push(
+      await writeOrPreview(path14.join(repoPath, ".vscode", "mcp.json"), renderMcp(), {
+        dryRun,
+        force
+      })
+    );
   }
   if (selections.includes("vscode")) {
-    const filePath = path13.join(repoPath, ".vscode", "settings.json");
-    await ensureDir(path13.dirname(filePath));
-    const content = renderVscodeSettings(analysis);
-    const { wrote } = await safeWriteFile(filePath, content, force);
-    files.push({
-      path: path13.relative(process.cwd(), filePath),
-      action: wrote ? "wrote" : "skipped"
-    });
+    files.push(
+      await writeOrPreview(
+        path14.join(repoPath, ".vscode", "settings.json"),
+        renderVscodeSettings(analysis),
+        { dryRun, force }
+      )
+    );
   }
   return { files };
 }
@@ -13439,16 +13823,16 @@ function renderVscodeSettings(analysis) {
 }
 
 // src/commands/instructions.ts
-import path14 from "path";
+import path15 from "path";
 function skipReason(action) {
   if (action === "symlink") return "symlink";
   if (action === "empty") return "empty content";
   return "exists, use --force";
 }
 async function instructionsCommand(options) {
-  const repoPath = path14.resolve(options.repo ?? process.cwd());
-  const outputPath = path14.resolve(
-    options.output ?? path14.join(repoPath, ".github", "copilot-instructions.md")
+  const repoPath = path15.resolve(options.repo ?? process.cwd());
+  const outputPath = path15.resolve(
+    options.output ?? path15.join(repoPath, ".github", "copilot-instructions.md")
   );
   const progress = createProgressReporter(!shouldLog(options));
   const wantAreas = options.areas || options.areasOnly || options.area;
@@ -13471,6 +13855,7 @@ async function instructionsCommand(options) {
     return;
   }
   try {
+    const dryRunFiles = [];
     if (!options.areasOnly && !options.area) {
       if (strategy === "nested") {
         try {
@@ -13482,25 +13867,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 = path15.relative(process.cwd(), path15.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 = path15.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 +13942,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 = path15.relative(repoPath, outputPath);
+            const displayPath = path15.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(path15.dirname(outputPath));
+            const { wrote, reason } = await safeWriteFile(
+              outputPath,
+              content,
+              Boolean(options.force)
+            );
+            if (!wrote) {
+              const relPath = path15.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 ${path15.relative(process.cwd(), outputPath)}`);
+              }
             }
           }
         }
@@ -13588,7 +14017,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 +14037,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 = path15.relative(process.cwd(), path15.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 = path15.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 +14091,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: path15.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 ${path15.relative(process.cwd(), result.filePath)}`);
               }
-              continue;
-            }
-            if (shouldLog(options)) {
-              progress.succeed(`Wrote ${path14.relative(process.cwd(), result.filePath)}`);
             }
           }
         } catch (error) {
@@ -13659,6 +14133,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");
@@ -13675,9 +14155,21 @@ async function instructionsCommand(options) {
 
 // src/commands/generate.ts
 async function generateCommand(type, repoPathArg, options) {
-  const repoPath = path15.resolve(repoPathArg ?? process.cwd());
+  const repoPath = path16.resolve(repoPathArg ?? process.cwd());
   if (type === "instructions" || type === "agents") {
-    const output = type === "agents" ? path15.join(repoPath, "AGENTS.md") : void 0;
+    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" ? path16.join(repoPath, "AGENTS.md") : void 0;
     await instructionsCommand({
       repo: repoPath,
       output,
@@ -13686,7 +14178,8 @@ async function generateCommand(type, repoPathArg, options) {
       json: options.json,
       quiet: options.quiet,
       areas: options.perApp,
-      strategy: options.strategy
+      strategy: options.strategy,
+      dryRun: options.dryRun
     });
     return;
   }
@@ -13707,7 +14200,8 @@ async function generateCommand(type, repoPathArg, options) {
       repoPath,
       analysis,
       selections,
-      force: Boolean(options.force)
+      force: Boolean(options.force),
+      dryRun: Boolean(options.dryRun)
     });
   } catch (error) {
     outputError(
@@ -13721,14 +14215,16 @@ async function generateCommand(type, repoPathArg, options) {
     const result = {
       ok,
       status,
-      data: { type, files: genResult.files }
+      data: { type, files: genResult.files, dryRun: options.dryRun }
     };
     outputResult(result, true);
     if (!ok) process.exitCode = 1;
   } else {
     for (const file of genResult.files) {
       if (shouldLog(options)) {
-        process.stderr.write(`${file.action === "wrote" ? "Wrote" : "Skipped"} ${file.path}
+        const prefix = options.dryRun ? file.action === "wrote" ? "[dry-run] Would write" : "[dry-run] Would skip" : file.action === "wrote" ? "Wrote" : "Skipped";
+        const suffix = options.dryRun && file.bytes !== void 0 ? ` (${file.bytes} bytes)` : "";
+        process.stderr.write(`${prefix} ${file.path}${suffix}
 `);
       }
     }
@@ -13739,10 +14235,35 @@ async function generateCommand(type, repoPathArg, options) {
 }
 
 // src/commands/init.ts
-import path16 from "path";
+import path18 from "path";
+
+// packages/core/src/services/configScaffold.ts
+import path17 from "path";
+async function scaffoldAgentrcConfig(repoPath, areas, force = false) {
+  const configPath = path17.join(repoPath, "agentrc.config.json");
+  const workspaces = areas.length > 0 ? await detectWorkspaces(repoPath, areas) : [];
+  const workspacePaths = workspaces.map((ws) => ws.path + "/");
+  const standaloneAreas = areas.filter((a) => {
+    if (!a.path) return true;
+    const rel = path17.relative(repoPath, a.path).replace(/\\/gu, "/");
+    return !workspacePaths.some((prefix) => rel.startsWith(prefix));
+  }).map((a) => ({
+    name: a.name,
+    applyTo: a.applyTo,
+    ...a.description ? { description: a.description } : {}
+  }));
+  const agentrcConfig = {};
+  if (workspaces.length > 0) agentrcConfig.workspaces = workspaces;
+  if (standaloneAreas.length > 0) agentrcConfig.areas = standaloneAreas;
+  const configContent = JSON.stringify(agentrcConfig, null, 2) + "\n";
+  const { wrote } = await safeWriteFile(configPath, configContent, force);
+  return { wrote, configPath };
+}
+
+// src/commands/init.ts
 import { checkbox, select } from "@inquirer/prompts";
 async function initCommand(repoPathArg, options) {
-  let repoPath = path16.resolve(repoPathArg ?? process.cwd());
+  let repoPath = path18.resolve(repoPathArg ?? process.cwd());
   const provider = options.provider ?? (options.github ? "github" : void 0);
   if (provider && provider !== "github" && provider !== "azure") {
     outputError("Invalid provider. Use github or azure.", Boolean(options.json));
@@ -13780,7 +14301,7 @@ async function initCommand(repoPathArg, options) {
         value: repo
       }))
     });
-    const cacheRoot = path16.join(process.cwd(), ".agentrc-cache");
+    const cacheRoot = path18.join(process.cwd(), ".agentrc-cache");
     repoPath = validateCachePath(cacheRoot, selection.owner, selection.name);
     await ensureDir(repoPath);
     const hasGit = await isGitRepo(repoPath);
@@ -13833,7 +14354,7 @@ async function initCommand(repoPathArg, options) {
         value: repo
       }))
     });
-    const cacheRoot = path16.join(process.cwd(), ".agentrc-cache");
+    const cacheRoot = path18.join(process.cwd(), ".agentrc-cache");
     repoPath = validateCachePath(
       cacheRoot,
       orgSelection.name,
@@ -13872,17 +14393,17 @@ async function initCommand(repoPathArg, options) {
   });
   const allFiles = [];
   if (selections.includes("instructions")) {
-    const outputPath = path16.join(repoPath, ".github", "copilot-instructions.md");
-    await ensureDir(path16.dirname(outputPath));
+    const outputPath = path18.join(repoPath, ".github", "copilot-instructions.md");
+    await ensureDir(path18.dirname(outputPath));
     try {
       const content = await generateCopilotInstructions({ repoPath, model: options.model });
       const { wrote } = await safeWriteFile(outputPath, content, Boolean(options.force));
       allFiles.push({
-        path: path16.relative(process.cwd(), outputPath),
+        path: path18.relative(process.cwd(), outputPath),
         action: wrote ? "wrote" : "skipped"
       });
       if (shouldLog(options)) {
-        const rel = path16.relative(process.cwd(), outputPath);
+        const rel = path18.relative(process.cwd(), outputPath);
         process.stderr.write((wrote ? `Wrote ${rel}` : `Skipped ${rel} (exists)`) + "\n");
       }
     } catch (error) {
@@ -13909,30 +14430,16 @@ async function initCommand(repoPathArg, options) {
     return;
   }
   allFiles.push(...genResult.files);
-  if (analysis.areas && analysis.areas.length > 0) {
-    const configPath = path16.join(repoPath, "agentrc.config.json");
-    const workspaces = await detectWorkspaces(repoPath, analysis.areas);
-    const workspacePaths = workspaces.map((ws) => ws.path + "/");
-    const standaloneAreas = analysis.areas.filter((a) => {
-      if (!a.path) return true;
-      const rel = path16.relative(repoPath, a.path).replace(/\\/gu, "/");
-      return !workspacePaths.some((prefix) => rel.startsWith(prefix));
-    }).map((a) => ({
-      name: a.name,
-      applyTo: a.applyTo,
-      ...a.description ? { description: a.description } : {}
-    }));
-    const agentrcConfig = {};
-    if (workspaces.length > 0) agentrcConfig.workspaces = workspaces;
-    if (standaloneAreas.length > 0) agentrcConfig.areas = standaloneAreas;
-    if (agentrcConfig.workspaces || agentrcConfig.areas) {
-      const configContent = JSON.stringify(agentrcConfig, null, 2) + "\n";
-      const { wrote } = await safeWriteFile(configPath, configContent, Boolean(options.force));
-      const rel = path16.relative(process.cwd(), configPath);
-      allFiles.push({ path: rel, action: wrote ? "wrote" : "skipped" });
-      if (shouldLog(options)) {
-        process.stderr.write((wrote ? `Wrote ${rel}` : `Skipped ${rel} (exists)`) + "\n");
-      }
+  {
+    const result = await scaffoldAgentrcConfig(
+      repoPath,
+      analysis.areas ?? [],
+      Boolean(options.force)
+    );
+    const rel = path18.relative(process.cwd(), result.configPath);
+    allFiles.push({ path: rel, action: result.wrote ? "wrote" : "skipped" });
+    if (shouldLog(options)) {
+      process.stderr.write((result.wrote ? `Wrote ${rel}` : `Skipped ${rel} (exists)`) + "\n");
     }
   }
   if (options.json) {
@@ -13949,7 +14456,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");
     }
@@ -13958,7 +14465,7 @@ async function initCommand(repoPathArg, options) {
 }
 
 // src/commands/pr.ts
-import path17 from "path";
+import path19 from "path";
 var DEFAULT_PR_BRANCH = "agentrc/add-ai-config";
 async function prCommand(repo, options) {
   const provider = options.provider ?? "github";
@@ -13992,7 +14499,7 @@ async function prCommand(repo, options) {
     try {
       progress.update("Fetching repo info...");
       const repoInfo = await getRepo(token2, organization, project, name2);
-      const cacheRoot = path17.join(process.cwd(), ".agentrc-cache");
+      const cacheRoot = path19.join(process.cwd(), ".agentrc-cache");
       const repoPath = validateCachePath(cacheRoot, organization, project, name2);
       await ensureDir(repoPath);
       if (!await isGitRepo(repoPath)) {
@@ -14006,8 +14513,8 @@ async function prCommand(repo, options) {
       await checkoutBranch(repoPath, branch);
       progress.update("Generating instructions...");
       const instructions = await generateCopilotInstructions({ repoPath, model: options.model });
-      const instructionsPath = path17.join(repoPath, ".github", "copilot-instructions.md");
-      await ensureDir(path17.dirname(instructionsPath));
+      const instructionsPath = path19.join(repoPath, ".github", "copilot-instructions.md");
+      await ensureDir(path19.dirname(instructionsPath));
       const { wrote, reason } = await safeWriteFile(instructionsPath, instructions, true);
       if (!wrote) {
         throw new Error(
@@ -14074,7 +14581,7 @@ async function prCommand(repo, options) {
   try {
     progress.update("Fetching repo info...");
     const repoInfo = await getRepo2(token, owner, name);
-    const cacheRoot = path17.join(process.cwd(), ".agentrc-cache");
+    const cacheRoot = path19.join(process.cwd(), ".agentrc-cache");
     const repoPath = validateCachePath(cacheRoot, owner, name);
     await ensureDir(repoPath);
     if (!await isGitRepo(repoPath)) {
@@ -14086,8 +14593,8 @@ async function prCommand(repo, options) {
     await checkoutBranch(repoPath, branch);
     progress.update("Generating instructions...");
     const instructions = await generateCopilotInstructions({ repoPath, model: options.model });
-    const instructionsPath = path17.join(repoPath, ".github", "copilot-instructions.md");
-    await ensureDir(path17.dirname(instructionsPath));
+    const instructionsPath = path19.join(repoPath, ".github", "copilot-instructions.md");
+    await ensureDir(path19.dirname(instructionsPath));
     const { wrote, reason } = await safeWriteFile(instructionsPath, instructions, true);
     if (!wrote) {
       throw new Error(
@@ -14136,13 +14643,13 @@ async function prCommand(repo, options) {
 }
 
 // src/commands/readiness.ts
-import path18 from "path";
+import path20 from "path";
 import chalk3 from "chalk";
 async function readinessCommand(repoPathArg, options) {
-  const repoPath = path18.resolve(repoPathArg ?? process.cwd());
-  const repoName = path18.basename(repoPath);
-  const resolvedOutputPath = options.output ? path18.resolve(options.output) : "";
-  const outputExt = options.output ? path18.extname(options.output).toLowerCase() : "";
+  const repoPath = path20.resolve(repoPathArg ?? process.cwd());
+  const repoName = path20.basename(repoPath);
+  const resolvedOutputPath = options.output ? path20.resolve(options.output) : "";
+  const outputExt = options.output ? path20.extname(options.output).toLowerCase() : "";
   let failLevelError;
   let report;
   try {
@@ -14201,10 +14708,10 @@ 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");
+    const outputPath = options.output ? resolvedOutputPath : path20.join(repoPath, "readiness-report.html");
     const { wrote, reason } = await safeWriteFile(outputPath, html, Boolean(options.force));
     if (!wrote) {
       const why = reason === "symlink" ? "path is a symlink" : "file exists (use --force)";
@@ -14301,7 +14808,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 +14873,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 +14906,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";
@@ -14439,26 +14946,32 @@ function formatReadinessMarkdown(report, repoName) {
 }
 
 // src/commands/tui.tsx
-import path20 from "path";
+import path22 from "path";
 import { render as render3 } from "ink";
 
 // src/ui/tui.tsx
 import fs10 from "fs/promises";
-import path19 from "path";
+import path21 from "path";
 import { Box as Box5, Text as Text5, useApp as useApp4, useInput as useInput4, useStdout, useIsScreenReaderEnabled as useIsScreenReaderEnabled5 } from "ink";
 import { useEffect as useEffect5, useMemo, useState as useState5 } from "react";
 import { Fragment, jsx as jsx7, jsxs as jsxs4 } from "react/jsx-runtime";
 var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 function useTerminalColumns() {
   const { stdout } = useStdout();
+  const accessible = useIsScreenReaderEnabled5();
   const [columns, setColumns] = useState5(stdout.columns ?? 80);
   useEffect5(() => {
-    const onResize = () => setColumns(stdout.columns ?? 80);
-    stdout.on("resize", onResize);
+    const onResize = () => {
+      if (!accessible) {
+        stdout.write("\x1B[2J\x1B[H");
+      }
+      setColumns(stdout.columns ?? 80);
+    };
+    stdout.prependListener("resize", onResize);
     return () => {
       stdout.off("resize", onResize);
     };
-  }, [stdout]);
+  }, [stdout, accessible]);
   return columns;
 }
 function useSpinner(active) {
@@ -14543,6 +15056,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
   const [modelPickTarget, setModelPickTarget] = useState5("eval");
   const [modelCursor, setModelCursor] = useState5(0);
   const [hasEvalConfig, setHasEvalConfig] = useState5(null);
+  const [hasAgentrcConfig, setHasAgentrcConfig] = useState5(null);
   const [activityLog, setActivityLog] = useState5([]);
   const [generateTarget, setGenerateTarget] = useState5(
     "copilot-instructions"
@@ -14552,9 +15066,9 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
   const [isMonorepo, setIsMonorepo] = useState5(false);
   const [repoAreas, setRepoAreas] = useState5([]);
   const [areaCursor, setAreaCursor] = useState5(0);
-  const repoLabel = useMemo(() => path19.basename(repoPath), [repoPath]);
+  const repoLabel = useMemo(() => path21.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") => {
@@ -14564,14 +15078,24 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
     setStatus("idle");
   };
   useEffect5(() => {
-    const configPath = path19.join(repoPath, "agentrc.eval.json");
+    const configPath = path21.join(repoPath, "agentrc.eval.json");
     fs10.access(configPath).then(() => setHasEvalConfig(true)).catch(() => setHasEvalConfig(false));
+    const agentrcConfigCandidates = [
+      path21.join(repoPath, "agentrc.config.json"),
+      path21.join(repoPath, ".github", "agentrc.config.json")
+    ];
+    Promise.all(
+      agentrcConfigCandidates.map(
+        (p) => fs10.access(p).then(() => true).catch(() => false)
+      )
+    ).then((results) => setHasAgentrcConfig(results.some(Boolean))).catch(() => setHasAgentrcConfig(false));
     analyzeRepo(repoPath).then((analysis) => {
       const apps = analysis.apps ?? [];
       setRepoApps(apps);
       setIsMonorepo(analysis.isMonorepo ?? false);
       setRepoAreas(analysis.areas ?? []);
     }).catch((err) => {
+      setRepoAreas([]);
       addLog(`Repo analysis failed: ${err instanceof Error ? err.message : "unknown"}`, "error");
     });
   }, [repoPath]);
@@ -14579,17 +15103,17 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
     let active = true;
     listCopilotModels().then((models) => {
       if (!active) return;
-      setAvailableModels(models);
-      if (models.length === 0) return;
+      const list = models.length > 0 ? models : PREFERRED_MODELS;
+      setAvailableModels(list);
       setEvalModel(
-        (current) => models.includes(current) ? current : pickBestModel(models, current)
+        (current) => list.includes(current) ? current : pickBestModel(list, current)
       );
       setJudgeModel(
-        (current) => models.includes(current) ? current : pickBestModel(models, current)
+        (current) => list.includes(current) ? current : pickBestModel(list, current)
       );
     }).catch(() => {
       if (!active) return;
-      setAvailableModels([]);
+      setAvailableModels(PREFERRED_MODELS);
     });
     return () => {
       active = false;
@@ -14625,7 +15149,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
   };
   useEffect5(() => {
     let active = true;
-    const configPath = path19.join(repoPath, "agentrc.eval.json");
+    const configPath = path21.join(repoPath, "agentrc.eval.json");
     fs10.readFile(configPath, "utf8").then((raw) => {
       if (!active) return;
       const parsed = JSON.parse(raw);
@@ -14640,7 +15164,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
     };
   }, [repoPath]);
   const bootstrapEvalConfig = async (count, force) => {
-    const configPath = path19.join(repoPath, "agentrc.eval.json");
+    const configPath = path21.join(repoPath, "agentrc.eval.json");
     try {
       setStatus("bootstrapping");
       setMessage("Generating eval cases with Copilot SDK...");
@@ -14679,13 +15203,13 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
           if (status === "preview") {
             if (input.toLowerCase() === "s") {
               try {
-                const outputPath = generateSavePath || path19.join(repoPath, ".github", "copilot-instructions.md");
-                await fs10.mkdir(path19.dirname(outputPath), { recursive: true });
+                const outputPath = generateSavePath || path21.join(repoPath, ".github", "copilot-instructions.md");
+                await fs10.mkdir(path21.dirname(outputPath), { recursive: true });
                 const { wrote, reason } = await safeWriteFile(outputPath, generatedContent, true);
                 if (!wrote)
                   throw new Error(reason === "symlink" ? "Path is a symlink" : "Write failed");
                 setStatus("done");
-                const relPath = path19.relative(repoPath, outputPath);
+                const relPath = path21.relative(repoPath, outputPath);
                 const msg = `Saved to ${relPath}`;
                 setMessage(msg);
                 addLog(msg, "success");
@@ -14719,7 +15243,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
                 setMessage("Enter a positive number of eval cases, then press Enter.");
                 return;
               }
-              const configPath = path19.join(repoPath, "agentrc.eval.json");
+              const configPath = path21.join(repoPath, "agentrc.eval.json");
               setEvalBootstrapCount(count);
               try {
                 await fs10.access(configPath);
@@ -14778,7 +15302,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
                 setStatus("generate-app-pick");
                 setMessage("Generate for root or per-app?");
               } else {
-                const savePath = path19.join(repoPath, ".github", "copilot-instructions.md");
+                const savePath = path21.join(repoPath, ".github", "copilot-instructions.md");
                 setGenerateSavePath(savePath);
                 await doGenerate(repoPath, savePath, "copilot-instructions");
               }
@@ -14790,20 +15314,20 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
                 setStatus("generate-app-pick");
                 setMessage("Generate for root or per-app?");
               } else {
-                const savePath = path19.join(repoPath, "AGENTS.md");
+                const savePath = path21.join(repoPath, "AGENTS.md");
                 setGenerateSavePath(savePath);
                 await doGenerate(repoPath, savePath, "agents-md");
               }
               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) {
@@ -14815,7 +15339,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
           }
           if (status === "generate-app-pick") {
             if (input.toLowerCase() === "r") {
-              const savePath = generateTarget === "copilot-instructions" ? path19.join(repoPath, ".github", "copilot-instructions.md") : path19.join(repoPath, "AGENTS.md");
+              const savePath = generateTarget === "copilot-instructions" ? path21.join(repoPath, ".github", "copilot-instructions.md") : path21.join(repoPath, "AGENTS.md");
               setGenerateSavePath(savePath);
               await doGenerate(repoPath, savePath, generateTarget);
               return;
@@ -14825,7 +15349,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
               addLog(`Generating ${generateTarget} for ${repoApps.length} apps...`, "progress");
               let count = 0;
               for (const app2 of repoApps) {
-                const savePath = generateTarget === "copilot-instructions" ? path19.join(app2.path, ".github", "copilot-instructions.md") : path19.join(app2.path, "AGENTS.md");
+                const savePath = generateTarget === "copilot-instructions" ? path21.join(app2.path, ".github", "copilot-instructions.md") : path21.join(app2.path, "AGENTS.md");
                 setMessage(`Generating for ${app2.name} (${count + 1}/${repoApps.length})...`);
                 try {
                   const content = await generateCopilotInstructions({
@@ -14833,11 +15357,11 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
                     onProgress: (msg) => setMessage(`${app2.name}: ${msg}`)
                   });
                   if (content.trim()) {
-                    await fs10.mkdir(path19.dirname(savePath), { recursive: true });
+                    await fs10.mkdir(path21.dirname(savePath), { recursive: true });
                     const { wrote: saved } = await safeWriteFile(savePath, content, true);
                     if (!saved) continue;
                     count++;
-                    addLog(`${app2.name}: saved ${path19.basename(savePath)}`, "success");
+                    addLog(`${app2.name}: saved ${path21.basename(savePath)}`, "success");
                   }
                 } catch (error) {
                   const msg = error instanceof Error ? error.message : "Failed.";
@@ -14851,7 +15375,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
             const num = Number.parseInt(input, 10);
             if (Number.isFinite(num) && num >= 1 && num <= repoApps.length) {
               const app2 = repoApps[num - 1];
-              const savePath = generateTarget === "copilot-instructions" ? path19.join(app2.path, ".github", "copilot-instructions.md") : path19.join(app2.path, "AGENTS.md");
+              const savePath = generateTarget === "copilot-instructions" ? path21.join(app2.path, ".github", "copilot-instructions.md") : path21.join(app2.path, "AGENTS.md");
               setGenerateSavePath(savePath);
               await doGenerate(app2.path, savePath, generateTarget);
               return;
@@ -14866,10 +15390,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})...`);
@@ -14882,7 +15403,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
                   const result = await writeAreaInstruction(repoPath, area, body);
                   if (result.status === "written") {
                     written++;
-                    addLog(`${area.name}: saved ${path19.basename(result.filePath)}`, "success");
+                    addLog(`${area.name}: saved ${path21.basename(result.filePath)}`, "success");
                   } else if (result.status === "skipped") {
                     addLog(`${area.name}: skipped (file exists)`, "info");
                   }
@@ -14892,9 +15413,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 +15429,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,
@@ -14978,8 +15497,8 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
           }
           if (status === "eval-pick") {
             if (input.toLowerCase() === "r") {
-              const configPath = path19.join(repoPath, "agentrc.eval.json");
-              const outputPath = path19.join(
+              const configPath = path21.join(repoPath, "agentrc.eval.json");
+              const outputPath = path21.join(
                 repoPath,
                 ".agentrc",
                 "evals",
@@ -15083,6 +15602,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.");
@@ -15093,6 +15642,36 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
               setMessage("Select eval action.");
               return;
             }
+            if (input.toLowerCase() === "c") {
+              if (hasAgentrcConfig) {
+                setMessage("agentrc.config.json already exists.");
+                return;
+              }
+              setStatus("generating");
+              setMessage("Creating agentrc.config.json...");
+              addLog("Scaffolding agentrc.config.json...", "progress");
+              try {
+                const result = await scaffoldAgentrcConfig(repoPath, repoAreas);
+                if (result.wrote) {
+                  setHasAgentrcConfig(true);
+                  setStatus("done");
+                  const msg = `Created agentrc.config.json`;
+                  setMessage(msg);
+                  addLog(msg, "success");
+                } else {
+                  setHasAgentrcConfig(true);
+                  setStatus("idle");
+                  setMessage("agentrc.config.json already exists (skipped).");
+                  addLog("agentrc.config.json already exists.", "info");
+                }
+              } catch (error) {
+                setStatus("error");
+                const msg = error instanceof Error ? error.message : "Failed to create config.";
+                setMessage(msg);
+                addLog(msg, "error");
+              }
+              return;
+            }
             if (input.toLowerCase() === "m") {
               if (hideModelPicker) {
                 setMessage(
@@ -15135,7 +15714,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;
@@ -15207,6 +15786,10 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
           /* @__PURE__ */ jsxs4(Text5, { children: [
             /* @__PURE__ */ jsx7(Text5, { color: "gray", children: "Eval " }),
             hasEvalConfig === null ? /* @__PURE__ */ jsx7(Text5, { color: "gray", dimColor: true, children: "checking..." }) : hasEvalConfig ? /* @__PURE__ */ jsx7(Text5, { color: "green", children: "agentrc.eval.json found" }) : /* @__PURE__ */ jsx7(Text5, { color: "yellow", children: "no eval config \u2014 press [I] to create" })
+          ] }),
+          /* @__PURE__ */ jsxs4(Text5, { children: [
+            /* @__PURE__ */ jsx7(Text5, { color: "gray", children: "Config " }),
+            hasAgentrcConfig === null ? /* @__PURE__ */ jsx7(Text5, { color: "gray", dimColor: true, children: "checking..." }) : hasAgentrcConfig ? /* @__PURE__ */ jsx7(Text5, { color: "green", children: "agentrc.config.json found" }) : /* @__PURE__ */ jsx7(Text5, { color: "yellow", children: "no config \u2014 press [C] to create" })
           ] })
         ] }),
         /* @__PURE__ */ jsx7(Divider, { columns: terminalColumns, label: "Activity", accessible }),
@@ -15282,19 +15865,12 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
             /* @__PURE__ */ jsx7(Text5, { color: "white", children: app2.name }),
             /* @__PURE__ */ jsxs4(Text5, { color: "gray", dimColor: true, children: [
               " ",
-              path19.relative(repoPath, app2.path)
+              path21.relative(repoPath, app2.path)
             ] })
           ] }, 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: " " }),
@@ -15323,7 +15899,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
             children: [
               /* @__PURE__ */ jsxs4(Text5, { color: "cyan", bold: true, children: [
                 "Preview (",
-                path19.relative(repoPath, generateSavePath) || generateTarget,
+                path21.relative(repoPath, generateSavePath) || generateTarget,
                 ")"
               ] }),
               /* @__PURE__ */ jsx7(Text5, { color: "gray", children: truncatedPreview })
@@ -15375,9 +15951,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,12 +15989,14 @@ 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" })
           ] }),
           /* @__PURE__ */ jsxs4(Box5, { children: [
             /* @__PURE__ */ jsx7(KeyHint, { k: "M", label: "Model" }),
             /* @__PURE__ */ jsx7(KeyHint, { k: "J", label: "Judge" }),
+            hasAgentrcConfig === false && /* @__PURE__ */ jsx7(KeyHint, { k: "C", label: "Create config" }),
             /* @__PURE__ */ jsx7(KeyHint, { k: "Q", label: "Quit" })
           ] })
         ] }) })
@@ -15430,7 +16008,7 @@ function AgentRCTui({ repoPath, skipAnimation = false }) {
 // src/commands/tui.tsx
 import { jsx as jsx8 } from "react/jsx-runtime";
 async function tuiCommand(options) {
-  const repoPath = path20.resolve(options.repo ?? process.cwd());
+  const repoPath = path22.resolve(options.repo ?? process.cwd());
   const skipAnimation = options.animation === false;
   try {
     const accessible = options.accessible ? true : void 0;
@@ -15445,7 +16023,7 @@ async function tuiCommand(options) {
 }
 
 // src/cli.ts
-var _require = createRequire(import.meta.url);
+var _require = createRequire2(import.meta.url);
 var CLI_VERSION = _require("../package.json").version;
 function withGlobalOpts(fn) {
   return async (...raw) => {
@@ -15466,7 +16044,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 +16053,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)").option("--dry-run", "Preview generated files without writing anything").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);
 }