fix(init): Include AGENTS guidance in non-interactive JSON

Capture AGENTS guidance outcomes during non-interactive init and embed the status in the emitted JSON report. Include path and error details when AGENTS updates fail so automation can reason about partial success without parsing stderr.

Preserve existing failure behavior by throwing after JSON emission on AGENTS errors, and extend init command tests to cover created, updated, and error statuses in JSON output.

Author: cameroncooke

src/cli/commands/__tests__/init.test.ts

@@ -467,6 +467,10 @@ describe('init command', () => {
       const output = parseJsonOutput(stdoutSpy);
       expect(output.action).toBe('install');
       expect(output.message).toBe('Installed XcodeBuildMCP CLI skill');
+      expect(output.agentsGuidance).toEqual({
+        status: 'created',
+        path: agentsPath,
+      });
 
       stdoutSpy.mockRestore();
     });
@@ -495,6 +499,12 @@ describe('init command', () => {
       const output = parseJsonOutput(stdoutSpy);
       expect(output.action).toBe('install');
       expect(output.message).toBe('Installed XcodeBuildMCP CLI skill');
+      expect(output.agentsGuidance).toEqual({
+        status: 'error',
+        path: join(projectRoot, 'AGENTS.md'),
+        error:
+          'AGENTS.md exists and requires confirmation to update. Re-run with --force to apply the change in non-interactive mode.',
+      });
 
       stdoutSpy.mockRestore();
       Object.defineProperty(process.stdin, 'isTTY', { value: originalIsTTY, configurable: true });
@@ -526,6 +536,10 @@ describe('init command', () => {
       const output = parseJsonOutput(stdoutSpy);
       expect(output.action).toBe('install');
       expect(output.message).toBe('Installed XcodeBuildMCP CLI skill');
+      expect(output.agentsGuidance).toEqual({
+        status: 'updated',
+        path: join(projectRoot, 'AGENTS.md'),
+      });
 
       stdoutSpy.mockRestore();
       Object.defineProperty(process.stdin, 'isTTY', { value: originalIsTTY, configurable: true });
@@ -560,6 +574,14 @@ describe('init command', () => {
         )?.length,
       ).toBe(1);
 
+      const output = parseJsonOutput(stdoutSpy);
+      expect(output.action).toBe('install');
+      expect(output.message).toBe('Installed XcodeBuildMCP CLI skill');
+      expect(output.agentsGuidance).toEqual({
+        status: 'updated',
+        path: join(projectRoot, 'AGENTS.md'),
+      });
+
       stdoutSpy.mockRestore();
     });
   });

src/cli/commands/init.ts

@@ -124,12 +124,19 @@ function formatSkippedClients(skippedClients: Array<{ client: string; reason: st
   return skippedClients.map((skipped) => `${skipped.client}: ${skipped.reason}`).join('; ');
 }
 
+type AgentsGuidanceStatus = 'created' | 'updated' | 'no_change' | 'skipped' | 'error';
+
 interface InitReport {
   action: 'install' | 'uninstall';
   skillType?: SkillType;
   installed?: InstallResult[];
   removed?: Array<{ client: string; variant: string; path: string }>;
   skipped?: Array<{ client: string; reason: string }>;
+  agentsGuidance?: {
+    status: AgentsGuidanceStatus;
+    path: string;
+    error?: string;
+  };
   message: string;
 }
 
@@ -595,11 +602,38 @@ export function registerInitCommand(app: Argv, ctx?: { workspaceRoot: string }):
         results.push(result);
       }
 
+      let agentsGuidanceStatus: AgentsGuidanceStatus | undefined;
+      let agentsGuidancePath: string | undefined;
+      let agentsGuidanceError: string | undefined;
+      if (!isTTY && ctx?.workspaceRoot) {
+        const projectRoot = path.resolve(ctx.workspaceRoot);
+        agentsGuidancePath = path.join(projectRoot, AGENTS_FILE_NAME);
+        try {
+          agentsGuidanceStatus = await ensureAgentsGuidance(
+            projectRoot,
+            argv.force as boolean,
+            false,
+          );
+        } catch (error) {
+          agentsGuidanceStatus = 'error';
+          agentsGuidanceError = error instanceof Error ? error.message : String(error);
+        }
+      }
+
       const report: InitReport = {
         action: 'install',
         skillType: selection.skillType,
         installed: results,
         skipped: policy.skippedClients,
+        ...(agentsGuidanceStatus && agentsGuidancePath
+          ? {
+              agentsGuidance: {
+                status: agentsGuidanceStatus,
+                path: agentsGuidancePath,
+                ...(agentsGuidanceError ? { error: agentsGuidanceError } : {}),
+              },
+            }
+          : {}),
         message: `Installed ${skillDisplayName(selection.skillType)} skill`,
       };
 
@@ -616,9 +650,13 @@ export function registerInitCommand(app: Argv, ctx?: { workspaceRoot: string }):
         process.stdout.write(`${JSON.stringify(report)}\n`);
       }
 
-      if (ctx?.workspaceRoot) {
+      if (agentsGuidanceStatus === 'error' && agentsGuidanceError) {
+        throw new Error(agentsGuidanceError);
+      }
+
+      if (ctx?.workspaceRoot && isTTY) {
         const projectRoot = path.resolve(ctx.workspaceRoot);
-        await ensureAgentsGuidance(projectRoot, argv.force as boolean, isTTY);
+        await ensureAgentsGuidance(projectRoot, argv.force as boolean, true);
       }
     },
   );