show copilot instructions prompt at startup

vscode/src/createProject.ts

@@ -65,7 +65,7 @@ export async function initProjectCreator(context: vscode.ExtensionContext) {
         }
 
         // Call updateCopilotInstructions to update the Copilot instructions file
-        await updateCopilotInstructions(folderUri);
+        await updateCopilotInstructions(folderUri, true);
       },
     ),
   );

vscode/src/gh-copilot/instructions.ts

@@ -174,7 +174,7 @@ async function hasQSharpCopilotInstructions(
  * Command to update or create the Copilot instructions file for Q#.
  * Shows a prompt to the user and updates the file if confirmed.
  */
-async function updateGhCopilotInstructionsCommand() {
+async function updateGhCopilotInstructionsCommand(userInvoked: boolean) {
   const workspaceFolders = vscode.workspace.workspaceFolders;
   if (!workspaceFolders || workspaceFolders.length === 0) {
     vscode.window.showErrorMessage("No workspace folder is open");
@@ -191,10 +191,13 @@ async function updateGhCopilotInstructionsCommand() {
     resourceUri = currentDoc ?? workspaceFolders[0].uri;
   }
 
-  return await updateCopilotInstructions(resourceUri);
+  return await updateCopilotInstructions(resourceUri, userInvoked);
 }
 
-export async function updateCopilotInstructions(resource: vscode.Uri) {
+export async function updateCopilotInstructions(
+  resource: vscode.Uri,
+  userInvoked: boolean,
+): Promise<vscode.MessageItem | undefined> {
   // Always add copilot instructions in the workspace root
   const workspaceFolder = vscode.workspace.getWorkspaceFolder(resource)?.uri;
   if (!workspaceFolder) {
@@ -206,24 +209,46 @@ export async function updateCopilotInstructions(resource: vscode.Uri) {
     return;
   }
 
-  sendTelemetryEvent(EventType.UpdateCopilotInstructionsStart, {}, {});
+  sendTelemetryEvent(
+    EventType.UpdateCopilotInstructionsStart,
+    {
+      trigger: userInvoked ? "user" : "startup",
+    },
+    {},
+  );
+
+  const buttons = [{ title: "Yes" }, { title: "No", isCloseAffordance: true }];
+  if (!userInvoked) {
+    buttons.push({ title: "Don't show again" });
+  }
+
+  const modal = userInvoked;
 
-  // Show a yes/no prompt to the user
   const response = await vscode.window.showInformationMessage(
-    "We're about to update your `copilot-instructions.md` file.\n\n" +
-      "This file helps GitHub Copilot understand and work better with Q# files and features provided by the Quantum Development Kit extension.\n\n" +
-      "Would you like to proceed with updating `copilot-instructions.md`?",
-    { modal: true },
-    { title: "Yes" },
-    { title: "No", isCloseAffordance: true },
+    "Add Q# guidance to copilot-instructions.md?\n\n" +
+      "Updating this file will help GitHub Copilot understand and work better with Q# files and other Quantum Development Kit features.\n\n" +
+      "Learn more at " +
+      (modal
+        ? "https://aka.ms/qdk.copilot" // links don't render in modal dialogs
+        : "[https://aka.ms/qdk.copilot](https://aka.ms/qdk.copilot)"),
+    {
+      modal,
+    },
+    ...buttons,
   );
 
   if (response?.title !== "Yes") {
     sendTelemetryEvent(EventType.UpdateCopilotInstructionsEnd, {
       reason: "User canceled",
       flowStatus: UserFlowStatus.Aborted,
     });
-    return; // User canceled or dismissed the dialog
+
+    vscode.window.showInformationMessage(
+      "To add Q# guidance to copilot-instructions.md at any time, " +
+        'run the command "Q#: Update Copilot instructions file for Q#".',
+    );
+
+    return response; // User dismissed the dialog
   }
 
   try {
@@ -274,7 +299,8 @@ export async function updateCopilotInstructions(resource: vscode.Uri) {
       { flowStatus: UserFlowStatus.Failed, reason: "Error" },
       {},
     );
-    return;
+
+    return response;
   }
 
   // Send telemetry event for successful completion
@@ -292,7 +318,24 @@ export function registerGhCopilotInstructionsCommand(
   context.subscriptions.push(
     vscode.commands.registerCommand(
       "qsharp-vscode.updateCopilotInstructions",
-      updateGhCopilotInstructionsCommand,
+      () => updateGhCopilotInstructionsCommand(true),
     ),
   );
+
+  // Also do a one-time prompt at startup
+  if (
+    context.globalState.get<boolean>(
+      "showUpdateCopilotInstructionsPromptAtStartup",
+      true,
+    )
+  ) {
+    updateGhCopilotInstructionsCommand(false).then((response) => {
+      if (response?.title === "Don't show again") {
+        context.globalState.update(
+          "showUpdateCopilotInstructionsPromptAtStartup",
+          false,
+        );
+      }
+    });
+  }
 }

vscode/src/telemetry.ts

@@ -282,7 +282,9 @@ type EventTypes = {
     };
   };
   [EventType.UpdateCopilotInstructionsStart]: {
-    properties: Empty;
+    properties: {
+      trigger: "user" | "startup";
+    };
     measurements: Empty;
   };
   [EventType.UpdateCopilotInstructionsEnd]: {