convex 1.34.0 → 1.35.0

package/src/cli/lib/{ai → aiFiles}/index.test.ts

@@ -1,11 +1,10 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import * as Sentry from "@sentry/node";
 import { logMessage } from "../../../bundler/log.js";
 import {
-  readAiConfig,
-  writeAiConfig,
-  writeAiDisabledToProjectConfig,
-} from "./config.js";
+  attemptReadAiState,
+  readAiStateOrDefault,
+  writeAiState,
+} from "./state.js";
 import {
   downloadGuidelines,
   fetchAgentSkillsSha,
@@ -15,14 +14,11 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import {
-  injectAgentsMdSection,
-  injectClaudeMdSection,
-  checkAiFilesStaleness,
-  updateAiFiles,
+  checkAiFilesStalenessAndLog,
+  installAiFiles,
   removeAiFiles,
-  disableAiFiles,
-  statusAiFiles,
 } from "./index.js";
+import { statusAiFiles } from "./status.js";
 import {
   AGENTS_MD_START_MARKER,
   AGENTS_MD_END_MARKER,
@@ -33,147 +29,7 @@ import {
 } from "../../codegen_templates/claudemd.js";
 
 // ---------------------------------------------------------------------------
-// injectAgentsMdSection — tested with real temp directories to exercise the
-// actual file I/O and string-surgery logic without complex mock wiring.
-// ---------------------------------------------------------------------------
-
-describe("injectAgentsMdSection", () => {
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  const section = `${AGENTS_MD_START_MARKER}\n## Convex\nRead guidelines.\n${AGENTS_MD_END_MARKER}`;
-
-  test("creates AGENTS.md when it does not exist", async () => {
-    await injectAgentsMdSection(section, tmpDir);
-
-    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
-    expect(content).toContain(AGENTS_MD_START_MARKER);
-    expect(content).toContain(AGENTS_MD_END_MARKER);
-    expect(content).toContain("## Convex");
-  });
-
-  test("appends to an existing AGENTS.md that has no Convex section", async () => {
-    const existing = "# My project\n\nSome existing content.\n";
-    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), existing);
-
-    await injectAgentsMdSection(section, tmpDir);
-
-    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
-    expect(content).toContain("# My project");
-    expect(content).toContain("Some existing content.");
-    expect(content).toContain(AGENTS_MD_START_MARKER);
-    expect(content).toContain("## Convex");
-  });
-
-  test("replaces an existing Convex section when markers are present", async () => {
-    const oldSection = `${AGENTS_MD_START_MARKER}\n## Convex\nOld content.\n${AGENTS_MD_END_MARKER}`;
-    const existing = `# My project\n\n${oldSection}\n`;
-    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), existing);
-
-    const newSection = `${AGENTS_MD_START_MARKER}\n## Convex\nNew content.\n${AGENTS_MD_END_MARKER}`;
-    await injectAgentsMdSection(newSection, tmpDir);
-
-    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
-    expect(content).toContain("New content.");
-    expect(content).not.toContain("Old content.");
-    // Only one occurrence of the start marker
-    expect(content.split(AGENTS_MD_START_MARKER).length - 1).toBe(1);
-  });
-
-  test("preserves content before and after an existing Convex section", async () => {
-    const oldSection = `${AGENTS_MD_START_MARKER}\n## Convex\nOld.\n${AGENTS_MD_END_MARKER}`;
-    const existing = `# Before\n\n${oldSection}\n\n# After\n`;
-    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), existing);
-
-    await injectAgentsMdSection(section, tmpDir);
-
-    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
-    expect(content).toContain("# Before");
-    expect(content).toContain("# After");
-  });
-
-  test("returns a non-null hash of the written content", async () => {
-    const hash = await injectAgentsMdSection(section, tmpDir);
-    expect(typeof hash).toBe("string");
-    expect(hash!.length).toBeGreaterThan(0);
-  });
-
-  test("returns hash of the section content, not the entire file", async () => {
-    fs.writeFileSync(
-      path.join(tmpDir, "AGENTS.md"),
-      "# My project\n\nExisting content.\n",
-    );
-
-    const hash = await injectAgentsMdSection(section, tmpDir);
-
-    const { hashSha256 } = await import("../utils/hash.js");
-    expect(hash).toBe(hashSha256(section));
-  });
-});
-
-describe("injectClaudeMdSection", () => {
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  const section = `${CLAUDE_MD_START_MARKER}\n## Convex\nRead guidelines.\n${CLAUDE_MD_END_MARKER}`;
-
-  test("creates CLAUDE.md when it does not exist", async () => {
-    const result = await injectClaudeMdSection(section, tmpDir);
-
-    const content = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8");
-    expect(content).toContain(CLAUDE_MD_START_MARKER);
-    expect(content).toContain(CLAUDE_MD_END_MARKER);
-    expect(result.didWrite).toBe(true);
-  });
-
-  test("appends managed section to existing CLAUDE.md content", async () => {
-    fs.writeFileSync(
-      path.join(tmpDir, "CLAUDE.md"),
-      "My custom instructions\n",
-    );
-
-    const result = await injectClaudeMdSection(section, tmpDir);
-
-    const content = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8");
-    expect(content).toContain("My custom instructions");
-    expect(content).toContain(CLAUDE_MD_START_MARKER);
-    expect(result.didWrite).toBe(true);
-  });
-
-  test("replaces managed section without touching user content", async () => {
-    const oldSection = `${CLAUDE_MD_START_MARKER}\nOld\n${CLAUDE_MD_END_MARKER}`;
-    fs.writeFileSync(
-      path.join(tmpDir, "CLAUDE.md"),
-      `# Header\n\n${oldSection}\n\n# Footer\n`,
-      "utf8",
-    );
-
-    await injectClaudeMdSection(section, tmpDir);
-
-    const content = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8");
-    expect(content).toContain("# Header");
-    expect(content).toContain("# Footer");
-    expect(content).toContain("## Convex");
-    expect(content).not.toContain("Old");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkAiFilesStaleness — mock-based: logic only, no real I/O needed.
+// Mocks
 // ---------------------------------------------------------------------------
 
 vi.mock("@sentry/node", () => ({
@@ -185,10 +41,11 @@ vi.mock("../../../bundler/log.js", () => ({
   logMessage: vi.fn(),
 }));
 
-vi.mock("./config.js", () => ({
-  readAiConfig: vi.fn(),
-  writeAiConfig: vi.fn(),
-  writeAiDisabledToProjectConfig: vi.fn(),
+vi.mock("./state.js", () => ({
+  attemptReadAiState: vi.fn(),
+  readAiStateOrDefault: vi.fn(),
+  writeAiState: vi.fn(),
+  hasAiState: vi.fn().mockResolvedValue(false),
 }));
 
 vi.mock("../versionApi.js", () => ({
@@ -201,7 +58,6 @@ vi.mock("child_process", () => ({
   default: {
     spawn: vi.fn(() => {
       const emitter = { on: vi.fn() };
-      // Immediately simulate a successful exit.
       emitter.on.mockImplementation(
         (event: string, cb: (arg: number) => void) => {
           if (event === "close") cb(0);
@@ -213,28 +69,30 @@ vi.mock("child_process", () => ({
 }));
 
 const mockLogMessage = vi.mocked(logMessage);
-const mockReadAiConfig = vi.mocked(readAiConfig);
-const mockWriteAiConfig = vi.mocked(writeAiConfig);
-const mockWriteAiDisabledToProjectConfig = vi.mocked(
-  writeAiDisabledToProjectConfig,
-);
+const mockAttemptReadAiState = vi.mocked(attemptReadAiState);
+const mockReadAiStateOrDefault = vi.mocked(readAiStateOrDefault);
+const mockWriteAiState = vi.mocked(writeAiState);
 const mockDownloadGuidelines = vi.mocked(downloadGuidelines);
 const mockFetchAgentSkillsSha = vi.mocked(fetchAgentSkillsSha);
 const mockGetVersion = vi.mocked(getVersion);
-const mockCaptureException = vi.mocked(Sentry.captureException);
 
-/** Minimal valid config used across tests; includes all required fields. */
-const baseConfig = {
+/** Minimal valid state used across tests; includes all required fields. */
+const baseState = {
   guidelinesHash: null,
   agentsMdSectionHash: null,
   claudeMdHash: null,
   agentSkillsSha: null,
   installedSkillNames: [] as string[],
-  disableStalenessMessage: false,
 };
 
+// ---------------------------------------------------------------------------
+// checkAiFilesStaleness
+// ---------------------------------------------------------------------------
+
 describe("checkAiFilesStaleness", () => {
-  beforeEach(() => vi.clearAllMocks());
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
   afterEach(() => {
     vi.unstubAllEnvs();
     vi.resetAllMocks();
@@ -244,11 +102,16 @@ describe("checkAiFilesStaleness", () => {
   const dummyConvexDir = "/tmp/test-project/convex";
 
   test("logs install nudge when no state file exists, even with null canonical values", async () => {
-    mockReadAiConfig.mockResolvedValue(null);
+    mockAttemptReadAiState.mockResolvedValue({ kind: "no-file" });
 
-    await checkAiFilesStaleness(null, null, dummyProjectDir, dummyConvexDir);
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: null,
+      canonicalAgentSkillsSha: null,
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
-    expect(mockReadAiConfig).toHaveBeenCalled();
+    expect(mockAttemptReadAiState).toHaveBeenCalled();
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("npx convex ai-files install"),
     );
@@ -257,26 +120,31 @@ describe("checkAiFilesStaleness", () => {
     );
   });
 
-  test("does nothing when both canonical values are null but config exists (version server unavailable)", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      guidelinesHash: "some-hash",
+  test("does nothing when both canonical values are null but state exists (version server unavailable)", async () => {
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, guidelinesHash: "some-hash" },
     });
 
-    await checkAiFilesStaleness(null, null, dummyProjectDir, dummyConvexDir);
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: null,
+      canonicalAgentSkillsSha: null,
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).not.toHaveBeenCalled();
   });
 
   test("logs install nudge when no state file exists, even if canonical hashes are available", async () => {
-    mockReadAiConfig.mockResolvedValue(null);
+    mockAttemptReadAiState.mockResolvedValue({ kind: "no-file" });
 
-    await checkAiFilesStaleness(
-      "canonical-hash",
-      null,
-      dummyProjectDir,
-      dummyConvexDir,
-    );
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: "canonical-hash",
+      canonicalAgentSkillsSha: null,
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("npx convex ai-files install"),
@@ -289,72 +157,48 @@ describe("checkAiFilesStaleness", () => {
     );
   });
 
-  test("adds agent-specific guidance when in agent mode", async () => {
-    vi.stubEnv("CONVEX_AGENT_MODE", "anonymous");
-    mockReadAiConfig.mockResolvedValue(null);
-
-    await checkAiFilesStaleness(
-      "canonical-hash",
-      null,
-      dummyProjectDir,
-      dummyConvexDir,
-    );
-
-    expect(mockLogMessage).toHaveBeenCalledWith(
-      expect.stringContaining("If you are an agent tell the human to run"),
-    );
-    expect(mockLogMessage).toHaveBeenCalledWith(
-      expect.stringContaining("npx convex ai-files install"),
-    );
-    expect(mockLogMessage).toHaveBeenCalledWith(
-      expect.stringContaining("npx convex ai-files disable"),
-    );
-  });
+  test("does nothing when config has enabled=false (user opted out)", async () => {
+    mockAttemptReadAiState.mockResolvedValue({ kind: "no-file" });
 
-  test("does nothing when config has disableStalenessMessage=true (user opted out)", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      disableStalenessMessage: true,
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: "canonical-hash",
+      canonicalAgentSkillsSha: null,
+      aiFilesConfig: { enabled: false },
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
     });
 
-    await checkAiFilesStaleness(
-      "canonical-hash",
-      null,
-      dummyProjectDir,
-      dummyConvexDir,
-    );
-
     expect(mockLogMessage).not.toHaveBeenCalled();
   });
 
   test("does nothing when stored guidelines hash matches canonical", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      guidelinesHash: "same-hash",
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, guidelinesHash: "same-hash" },
     });
 
-    await checkAiFilesStaleness(
-      "same-hash",
-      null,
-      dummyProjectDir,
-      dummyConvexDir,
-    );
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: "same-hash",
+      canonicalAgentSkillsSha: null,
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).not.toHaveBeenCalled();
   });
 
   test("logs nag message when guidelines hash is stale", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      guidelinesHash: "old-hash",
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, guidelinesHash: "old-hash" },
     });
 
-    await checkAiFilesStaleness(
-      "new-canonical-hash",
-      null,
-      dummyProjectDir,
-      dummyConvexDir,
-    );
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: "new-canonical-hash",
+      canonicalAgentSkillsSha: null,
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("npx convex ai-files update"),
@@ -362,18 +206,21 @@ describe("checkAiFilesStaleness", () => {
   });
 
   test("logs nag message when agent skills SHA is stale", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      guidelinesHash: "current-hash",
-      agentSkillsSha: "old-sha",
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: {
+        ...baseState,
+        guidelinesHash: "current-hash",
+        agentSkillsSha: "old-sha",
+      },
     });
 
-    await checkAiFilesStaleness(
-      "current-hash",
-      "new-sha",
-      dummyProjectDir,
-      dummyConvexDir,
-    );
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: "current-hash",
+      canonicalAgentSkillsSha: "new-sha",
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("npx convex ai-files update"),
@@ -381,38 +228,44 @@ describe("checkAiFilesStaleness", () => {
   });
 
   test("does nothing when stored guidelinesHash is null (never written)", async () => {
-    mockReadAiConfig.mockResolvedValue(baseConfig);
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
 
-    await checkAiFilesStaleness(
-      "some-hash",
-      "some-sha",
-      dummyProjectDir,
-      dummyConvexDir,
-    );
+    await checkAiFilesStalenessAndLog({
+      canonicalGuidelinesHash: "some-hash",
+      canonicalAgentSkillsSha: "some-sha",
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).not.toHaveBeenCalled();
   });
 });
 
 // ---------------------------------------------------------------------------
-// updateAiFiles — mock-based.
+// installAiFiles
 // ---------------------------------------------------------------------------
 
-describe("updateAiFiles", () => {
+describe("installAiFiles", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockFetchAgentSkillsSha.mockResolvedValue("canonical-sha-abc123");
     mockGetVersion.mockResolvedValue({
-      message: null,
-      guidelinesHash: null,
-      agentSkillsSha: "canonical-sha-abc123",
-      disableSkillsCli: false,
+      kind: "ok",
+      data: {
+        message: null,
+        guidelinesHash: null,
+        agentSkillsSha: "canonical-sha-abc123",
+        disableSkillsCli: false,
+      },
     });
   });
   afterEach(() => vi.resetAllMocks());
 
-  test("runs full init and installs skills when no config exists", async () => {
-    mockReadAiConfig.mockResolvedValue(null);
+  test("runs full init and installs skills when no state exists", async () => {
+    mockReadAiStateOrDefault.mockResolvedValue(baseState);
 
     const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
     const convexDir = path.join(tmpDir, "convex");
@@ -422,7 +275,7 @@ describe("updateAiFiles", () => {
 
       mockDownloadGuidelines.mockResolvedValue("guidelines content");
 
-      await updateAiFiles(tmpDir, convexDir);
+      await installAiFiles({ projectDir: tmpDir, convexDir });
 
       expect(
         fs.existsSync(
@@ -441,32 +294,6 @@ describe("updateAiFiles", () => {
     }
   });
 
-  test("reports up to date when guidelines hash already matches", async () => {
-    mockDownloadGuidelines.mockResolvedValue("guidelines content");
-    const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
-    const convexDir = path.join(tmpDir, "convex");
-
-    const { hashSha256 } = await import("../utils/hash.js");
-    const realHash = hashSha256("guidelines content");
-
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      guidelinesHash: realHash,
-      agentSkillsSha: "canonical-sha-abc123",
-    });
-
-    try {
-      await updateAiFiles(tmpDir, convexDir);
-
-      expect(mockLogMessage).toHaveBeenCalledWith(
-        expect.stringContaining("already up to date"),
-      );
-      expect(mockCaptureException).not.toHaveBeenCalled();
-    } finally {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
-
   test("stores canonical agentSkillsSha and skill names after successful install", async () => {
     const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
     const convexDir = path.join(tmpDir, "convex");
@@ -485,79 +312,20 @@ describe("updateAiFiles", () => {
       }
 
       mockDownloadGuidelines.mockResolvedValue(null);
-      mockReadAiConfig.mockResolvedValue({
-        ...baseConfig,
+      mockReadAiStateOrDefault.mockResolvedValue({
+        ...baseState,
         agentSkillsSha: "old-sha",
       });
 
-      await updateAiFiles(tmpDir, convexDir);
-
-      expect(mockWriteAiConfig).toHaveBeenCalledWith(
-        expect.objectContaining({
-          agentSkillsSha: "canonical-sha-abc123",
-          installedSkillNames: ["migration-helper", "schema-builder"],
-        }),
-        expect.anything(),
-        expect.anything(),
-      );
-    } finally {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  test("update does not clear disableStalenessMessage when set true", async () => {
-    const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
-    const convexDir = path.join(tmpDir, "convex");
-    try {
-      mockReadAiConfig.mockResolvedValue({
-        ...baseConfig,
-        disableStalenessMessage: true,
-      });
-      mockDownloadGuidelines.mockResolvedValue(null);
-
-      await updateAiFiles(tmpDir, convexDir);
-
-      expect(mockWriteAiConfig).toHaveBeenCalledWith(
-        expect.objectContaining({ disableStalenessMessage: true }),
-        expect.anything(),
-        expect.anything(),
-      );
-    } finally {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  test("update recreates convex/_generated/ai when only disable config exists", async () => {
-    const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
-    const convexDir = path.join(tmpDir, "convex");
-    try {
-      fs.mkdirSync(convexDir, { recursive: true });
-      fs.writeFileSync(path.join(convexDir, "schema.ts"), "");
-      fs.writeFileSync(path.join(tmpDir, "convex.json"), "{}");
-      mockReadAiConfig.mockResolvedValue({
-        ...baseConfig,
-        disableStalenessMessage: true,
-        guidelinesHash: null,
-      });
-      mockDownloadGuidelines.mockResolvedValue("fresh guidelines");
-
-      await updateAiFiles(tmpDir, convexDir);
+      await installAiFiles({ projectDir: tmpDir, convexDir });
 
-      expect(fs.existsSync(path.join(convexDir, "_generated", "ai"))).toBe(
-        true,
-      );
-      expect(
-        fs.existsSync(
-          path.join(convexDir, "_generated", "ai", "guidelines.md"),
-        ),
-      ).toBe(true);
-      expect(mockWriteAiConfig).toHaveBeenCalledWith(
+      expect(mockWriteAiState).toHaveBeenCalledWith(
         expect.objectContaining({
-          disableStalenessMessage: true,
-          guidelinesHash: expect.any(String),
+          state: expect.objectContaining({
+            agentSkillsSha: "canonical-sha-abc123",
+            installedSkillNames: ["migration-helper", "schema-builder"],
+          }),
         }),
-        tmpDir,
-        expect.anything(),
       );
     } finally {
       fs.rmSync(tmpDir, { recursive: true, force: true });
@@ -568,10 +336,10 @@ describe("updateAiFiles", () => {
     const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
     const convexDir = path.join(tmpDir, "convex");
     try {
-      mockReadAiConfig.mockResolvedValue(baseConfig);
+      mockReadAiStateOrDefault.mockResolvedValue(baseState);
       mockDownloadGuidelines.mockResolvedValue(null);
 
-      await updateAiFiles(tmpDir, convexDir);
+      await installAiFiles({ projectDir: tmpDir, convexDir });
 
       expect(mockLogMessage).toHaveBeenCalledWith(
         expect.stringContaining("Could not download Convex AI guidelines"),
@@ -585,16 +353,19 @@ describe("updateAiFiles", () => {
     const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
     const convexDir = path.join(tmpDir, "convex");
     try {
-      mockReadAiConfig.mockResolvedValue(baseConfig);
+      mockReadAiStateOrDefault.mockResolvedValue(baseState);
       mockDownloadGuidelines.mockResolvedValue("guidelines content");
       mockGetVersion.mockResolvedValue({
-        message: null,
-        guidelinesHash: null,
-        agentSkillsSha: null,
-        disableSkillsCli: true,
+        kind: "ok",
+        data: {
+          message: null,
+          guidelinesHash: null,
+          agentSkillsSha: null,
+          disableSkillsCli: true,
+        },
       });
 
-      await updateAiFiles(tmpDir, convexDir);
+      await installAiFiles({ projectDir: tmpDir, convexDir });
 
       const { default: cp } = await import("child_process");
       const spawnCalls = vi.mocked(cp.spawn).mock.calls;
@@ -612,7 +383,7 @@ describe("updateAiFiles", () => {
 });
 
 // ---------------------------------------------------------------------------
-// removeAiFiles — tested with real temp directories.
+// removeAiFiles
 // ---------------------------------------------------------------------------
 
 describe("removeAiFiles", () => {
@@ -622,10 +393,13 @@ describe("removeAiFiles", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockGetVersion.mockResolvedValue({
-      message: null,
-      guidelinesHash: null,
-      agentSkillsSha: "canonical-sha-abc123",
-      disableSkillsCli: false,
+      kind: "ok",
+      data: {
+        message: null,
+        guidelinesHash: null,
+        agentSkillsSha: "canonical-sha-abc123",
+        disableSkillsCli: false,
+      },
     });
     tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
     convexDir = path.join(tmpDir, "convex");
@@ -639,41 +413,47 @@ describe("removeAiFiles", () => {
     vi.resetAllMocks();
   });
 
-  function writeConfig(override: Partial<typeof baseConfig> = {}) {
-    const config = { ...baseConfig, ...override };
-    fs.writeFileSync(
-      path.join(tmpDir, "convex", "_generated", "ai", "ai-files.state.json"),
-      JSON.stringify(config, null, 2) + "\n",
-      "utf8",
+  test("logs nothing-to-remove when no state and no artifacts exist", async () => {
+    mockAttemptReadAiState.mockResolvedValue({ kind: "no-file" });
+    fs.rmSync(path.join(convexDir, "_generated", "ai"), { recursive: true });
+
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
+
+    expect(mockLogMessage).toHaveBeenCalledWith(
+      expect.stringContaining("nothing to remove"),
     );
-  }
+  });
 
-  test("logs nothing-to-remove when no config exists", async () => {
-    // No config file written — readAiConfig returns null.
-    mockReadAiConfig.mockResolvedValue(null);
+  test("removes ai dir even when no state file exists", async () => {
+    mockAttemptReadAiState.mockResolvedValue({ kind: "no-file" });
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
-      expect.stringContaining("nothing to remove"),
+      expect.stringContaining("Convex AI files removed"),
     );
+    expect(fs.existsSync(path.join(convexDir, "_generated", "ai"))).toBe(false);
   });
 
   test("deletes AGENTS.md if stripping the Convex section leaves it empty", async () => {
-    writeConfig();
-    mockReadAiConfig.mockResolvedValue(baseConfig);
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
 
     const agentsMdContent = `${AGENTS_MD_START_MARKER}\n## Convex\nGuidelines.\n${AGENTS_MD_END_MARKER}\n`;
     fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), agentsMdContent, "utf8");
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     expect(fs.existsSync(path.join(tmpDir, "AGENTS.md"))).toBe(false);
   });
 
   test("strips Convex section from AGENTS.md", async () => {
-    writeConfig();
-    mockReadAiConfig.mockResolvedValue(baseConfig);
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
 
     const agentsMdContent =
       `# My project\n\n` +
@@ -681,7 +461,7 @@ describe("removeAiFiles", () => {
       `# After\n`;
     fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), agentsMdContent, "utf8");
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     const result = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
     expect(result).toContain("# My project");
@@ -691,30 +471,36 @@ describe("removeAiFiles", () => {
   });
 
   test("deletes CLAUDE.md when it only contains the managed section", async () => {
-    writeConfig();
-    mockReadAiConfig.mockResolvedValue(baseConfig);
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
     const managed = `${CLAUDE_MD_START_MARKER}\n## Convex\nRead guidelines.\n${CLAUDE_MD_END_MARKER}\n`;
     fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), managed, "utf8");
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     expect(fs.existsSync(path.join(tmpDir, "CLAUDE.md"))).toBe(false);
   });
 
   test("leaves CLAUDE.md when it has no managed markers", async () => {
-    writeConfig();
-    mockReadAiConfig.mockResolvedValue(baseConfig);
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
 
     fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), "User content\n", "utf8");
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     expect(fs.existsSync(path.join(tmpDir, "CLAUDE.md"))).toBe(true);
   });
 
   test("strips only the Convex section from CLAUDE.md", async () => {
-    writeConfig();
-    mockReadAiConfig.mockResolvedValue(baseConfig);
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
     const managed = `${CLAUDE_MD_START_MARKER}\n## Convex\nRead guidelines.\n${CLAUDE_MD_END_MARKER}`;
     fs.writeFileSync(
       path.join(tmpDir, "CLAUDE.md"),
@@ -722,7 +508,7 @@ describe("removeAiFiles", () => {
       "utf8",
     );
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     const content = fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8");
     expect(content).toContain("# User header");
@@ -732,9 +518,9 @@ describe("removeAiFiles", () => {
   });
 
   test("leaves CLAUDE.md alone when it has no managed markers (legacy)", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      claudeMdHash: "some-hash",
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, claudeMdHash: "some-hash" },
     });
 
     fs.writeFileSync(
@@ -743,7 +529,7 @@ describe("removeAiFiles", () => {
       "utf8",
     );
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     expect(fs.existsSync(path.join(tmpDir, "CLAUDE.md"))).toBe(true);
     expect(fs.readFileSync(path.join(tmpDir, "CLAUDE.md"), "utf8")).toBe(
@@ -753,14 +539,13 @@ describe("removeAiFiles", () => {
 
   test("calls skills remove for each tracked skill name", async () => {
     const skillNames = ["migration-helper", "schema-builder"];
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      installedSkillNames: skillNames,
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, installedSkillNames: skillNames },
     });
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
-    // child_process.spawn should have been called with the skill names.
     const { default: cp } = await import("child_process");
     const spawnCalls = vi.mocked(cp.spawn).mock.calls;
     const removeCall = spawnCalls.find(
@@ -773,10 +558,9 @@ describe("removeAiFiles", () => {
 
   test("deletes skills-lock.json if it becomes empty after removing our skills", async () => {
     const skillNames = ["migration-helper"];
-    writeConfig({ installedSkillNames: skillNames });
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      installedSkillNames: skillNames,
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, installedSkillNames: skillNames },
     });
 
     const lockfileContent = {
@@ -791,17 +575,16 @@ describe("removeAiFiles", () => {
       "utf8",
     );
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     expect(fs.existsSync(path.join(tmpDir, "skills-lock.json"))).toBe(false);
   });
 
   test("preserves skills-lock.json if it contains other skills", async () => {
     const skillNames = ["migration-helper"];
-    writeConfig({ installedSkillNames: skillNames });
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      installedSkillNames: skillNames,
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, installedSkillNames: skillNames },
     });
 
     const lockfileContent = {
@@ -817,25 +600,28 @@ describe("removeAiFiles", () => {
       "utf8",
     );
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     expect(fs.existsSync(path.join(tmpDir, "skills-lock.json"))).toBe(true);
   });
 
   test("skips skills remove when server kill switch is enabled", async () => {
     const skillNames = ["migration-helper"];
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      installedSkillNames: skillNames,
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: { ...baseState, installedSkillNames: skillNames },
     });
     mockGetVersion.mockResolvedValue({
-      message: null,
-      guidelinesHash: null,
-      agentSkillsSha: null,
-      disableSkillsCli: true,
+      kind: "ok",
+      data: {
+        message: null,
+        guidelinesHash: null,
+        agentSkillsSha: null,
+        disableSkillsCli: true,
+      },
     });
 
-    await removeAiFiles(tmpDir, convexDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
     const { default: cp } = await import("child_process");
     const spawnCalls = vi.mocked(cp.spawn).mock.calls;
@@ -848,51 +634,20 @@ describe("removeAiFiles", () => {
     );
   });
 
-  test("does NOT write a disabled config after plain remove", async () => {
-    writeConfig();
-    mockReadAiConfig.mockResolvedValue(baseConfig);
-
-    await removeAiFiles(tmpDir, convexDir);
-
-    // removeAiFiles should not call writeAiConfig — that is disableAiFiles's job.
-    expect(mockWriteAiConfig).not.toHaveBeenCalled();
-  });
-
-  test("disableAiFiles writes disableStalenessMessage=true without removing files", async () => {
-    writeConfig({ guidelinesHash: null });
-    mockReadAiConfig.mockResolvedValue(baseConfig);
-
-    fs.writeFileSync(
-      path.join(convexDir, "_generated", "ai", "guidelines.md"),
-      "guidelines content",
-      "utf8",
-    );
-
-    await disableAiFiles(tmpDir);
-
-    expect(mockWriteAiDisabledToProjectConfig).toHaveBeenCalledWith(
-      true,
-      tmpDir,
-    );
-    expect(
-      fs.existsSync(path.join(convexDir, "_generated", "ai", "guidelines.md")),
-    ).toBe(true);
-  });
-
-  test("disableAiFiles writes config to project root, not convex dir", async () => {
-    mockReadAiConfig.mockResolvedValue(null);
+  test("does NOT write state after plain remove", async () => {
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
 
-    await disableAiFiles(tmpDir);
+    await removeAiFiles({ projectDir: tmpDir, convexDir });
 
-    expect(mockWriteAiDisabledToProjectConfig).toHaveBeenCalledWith(
-      true,
-      tmpDir,
-    );
+    expect(mockWriteAiState).not.toHaveBeenCalled();
   });
 });
 
 // ---------------------------------------------------------------------------
-// statusAiFiles — mock-based.
+// statusAiFiles
 // ---------------------------------------------------------------------------
 
 describe("statusAiFiles", () => {
@@ -902,18 +657,24 @@ describe("statusAiFiles", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockGetVersion.mockResolvedValue({
-      message: null,
-      guidelinesHash: "canonical-guidelines-hash",
-      agentSkillsSha: "canonical-skills-sha",
-      disableSkillsCli: false,
+      kind: "ok",
+      data: {
+        message: null,
+        guidelinesHash: "canonical-guidelines-hash",
+        agentSkillsSha: "canonical-skills-sha",
+        disableSkillsCli: false,
+      },
     });
   });
   afterEach(() => vi.resetAllMocks());
 
-  test("reports not installed when config is null", async () => {
-    mockReadAiConfig.mockResolvedValue(null);
+  test("reports not installed when state is missing", async () => {
+    mockAttemptReadAiState.mockResolvedValue({ kind: "no-file" });
 
-    await statusAiFiles(dummyProjectDir, dummyConvexDir);
+    await statusAiFiles({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("not installed"),
@@ -923,14 +684,13 @@ describe("statusAiFiles", () => {
     );
   });
 
-  test("reports disabled when config has disableStalenessMessage=true", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      disableStalenessMessage: true,
+  test("reports disabled when config has enabled=false", async () => {
+    await statusAiFiles({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+      aiFilesConfig: { enabled: false },
     });
 
-    await statusAiFiles(dummyProjectDir, dummyConvexDir);
-
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("disabled"),
     );
@@ -939,10 +699,16 @@ describe("statusAiFiles", () => {
     );
   });
 
-  test("reports enabled when config exists and disableStalenessMessage=false", async () => {
-    mockReadAiConfig.mockResolvedValue(baseConfig);
+  test("reports enabled when state exists and messages are not disabled", async () => {
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: baseState,
+    });
 
-    await statusAiFiles(dummyProjectDir, dummyConvexDir);
+    await statusAiFiles({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("enabled"),
@@ -966,18 +732,21 @@ describe("statusAiFiles", () => {
         "utf8",
       );
 
-      mockReadAiConfig.mockResolvedValue({
-        ...baseConfig,
-        guidelinesHash: hash,
+      mockAttemptReadAiState.mockResolvedValue({
+        kind: "ok",
+        state: { ...baseState, guidelinesHash: hash },
       });
       mockGetVersion.mockResolvedValue({
-        message: null,
-        guidelinesHash: hash,
-        agentSkillsSha: null,
-        disableSkillsCli: false,
+        kind: "ok",
+        data: {
+          message: null,
+          guidelinesHash: hash,
+          agentSkillsSha: null,
+          disableSkillsCli: false,
+        },
       });
 
-      await statusAiFiles(tmpDir, convexDir);
+      await statusAiFiles({ projectDir: tmpDir, convexDir });
 
       const calls = mockLogMessage.mock.calls.map((c) => c[0]);
       expect(calls.some((m) => /guidelines\.md.*up to date/.test(m))).toBe(
@@ -1004,18 +773,21 @@ describe("statusAiFiles", () => {
         "utf8",
       );
 
-      mockReadAiConfig.mockResolvedValue({
-        ...baseConfig,
-        guidelinesHash: hashSha256(content),
+      mockAttemptReadAiState.mockResolvedValue({
+        kind: "ok",
+        state: { ...baseState, guidelinesHash: hashSha256(content) },
       });
       mockGetVersion.mockResolvedValue({
-        message: null,
-        guidelinesHash: "new-canonical-hash",
-        agentSkillsSha: null,
-        disableSkillsCli: false,
+        kind: "ok",
+        data: {
+          message: null,
+          guidelinesHash: "new-canonical-hash",
+          agentSkillsSha: null,
+          disableSkillsCli: false,
+        },
       });
 
-      await statusAiFiles(tmpDir, convexDir);
+      await statusAiFiles({ projectDir: tmpDir, convexDir });
 
       expect(mockLogMessage).toHaveBeenCalledWith(
         expect.stringContaining("out of date"),
@@ -1043,12 +815,15 @@ describe("statusAiFiles", () => {
         "utf8",
       );
 
-      mockReadAiConfig.mockResolvedValue({
-        ...baseConfig,
-        guidelinesHash: hashSha256("original content"),
+      mockAttemptReadAiState.mockResolvedValue({
+        kind: "ok",
+        state: {
+          ...baseState,
+          guidelinesHash: hashSha256("original content"),
+        },
       });
 
-      await statusAiFiles(tmpDir, convexDir);
+      await statusAiFiles({ projectDir: tmpDir, convexDir });
 
       expect(mockLogMessage).toHaveBeenCalledWith(
         expect.stringContaining("modified locally"),
@@ -1058,20 +833,57 @@ describe("statusAiFiles", () => {
     }
   });
 
+  test("reports guidelines as missing when guidelines.md is empty", async () => {
+    const tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+    const convexDir = path.join(tmpDir, "convex");
+    try {
+      fs.mkdirSync(path.join(convexDir, "_generated", "ai"), {
+        recursive: true,
+      });
+      fs.writeFileSync(
+        path.join(convexDir, "_generated", "ai", "guidelines.md"),
+        "",
+        "utf8",
+      );
+
+      mockAttemptReadAiState.mockResolvedValue({
+        kind: "ok",
+        state: baseState,
+      });
+
+      await statusAiFiles({ projectDir: tmpDir, convexDir });
+
+      expect(mockLogMessage).toHaveBeenCalledWith(
+        expect.stringContaining("guidelines.md: not on disk"),
+      );
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   test("reports agent skills as out of date when SHA differs from canonical", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      installedSkillNames: ["migration-helper"],
-      agentSkillsSha: "old-sha",
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: {
+        ...baseState,
+        installedSkillNames: ["migration-helper"],
+        agentSkillsSha: "old-sha",
+      },
     });
     mockGetVersion.mockResolvedValue({
-      message: null,
-      guidelinesHash: null,
-      agentSkillsSha: "new-sha",
-      disableSkillsCli: false,
+      kind: "ok",
+      data: {
+        message: null,
+        guidelinesHash: null,
+        agentSkillsSha: "new-sha",
+        disableSkillsCli: false,
+      },
     });
 
-    await statusAiFiles(dummyProjectDir, dummyConvexDir);
+    await statusAiFiles({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("out of date"),
@@ -1082,28 +894,40 @@ describe("statusAiFiles", () => {
   });
 
   test("skips staleness check when network is unavailable", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      guidelinesHash: "old-hash",
-      agentSkillsSha: "old-sha",
-      installedSkillNames: ["migration-helper"],
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: {
+        ...baseState,
+        guidelinesHash: "old-hash",
+        agentSkillsSha: "old-sha",
+        installedSkillNames: ["migration-helper"],
+      },
     });
-    mockGetVersion.mockResolvedValue(null);
+    mockGetVersion.mockResolvedValue({ kind: "error" });
 
-    await statusAiFiles(dummyProjectDir, dummyConvexDir);
+    await statusAiFiles({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     const calls = mockLogMessage.mock.calls.map((c) => c[0]);
     expect(calls.some((m) => /out of date/.test(m))).toBe(false);
   });
 
   test("reports skills with names when installed", async () => {
-    mockReadAiConfig.mockResolvedValue({
-      ...baseConfig,
-      installedSkillNames: ["migration-helper", "schema-builder"],
-      agentSkillsSha: "canonical-skills-sha",
+    mockAttemptReadAiState.mockResolvedValue({
+      kind: "ok",
+      state: {
+        ...baseState,
+        installedSkillNames: ["migration-helper", "schema-builder"],
+        agentSkillsSha: "canonical-skills-sha",
+      },
     });
 
-    await statusAiFiles(dummyProjectDir, dummyConvexDir);
+    await statusAiFiles({
+      projectDir: dummyProjectDir,
+      convexDir: dummyConvexDir,
+    });
 
     expect(mockLogMessage).toHaveBeenCalledWith(
       expect.stringContaining("migration-helper"),
@@ -1122,9 +946,12 @@ describe("statusAiFiles", () => {
         "User content\n",
         "utf8",
       );
-      mockReadAiConfig.mockResolvedValue(baseConfig);
+      mockAttemptReadAiState.mockResolvedValue({
+        kind: "ok",
+        state: baseState,
+      });
 
-      await statusAiFiles(tmpDir, convexDir);
+      await statusAiFiles({ projectDir: tmpDir, convexDir });
 
       expect(mockLogMessage).toHaveBeenCalledWith(
         expect.stringContaining("CLAUDE.md: no Convex section present"),