convex 1.34.0 → 1.35.0

package/src/cli/dev.ts

@@ -1,4 +1,5 @@
 import { Command, Option } from "@commander-js/extra-typings";
+import { chalkStderr } from "chalk";
 import { oneoffContext } from "../bundler/context.js";
 import { logVerbose } from "../bundler/log.js";
 import { deploymentCredentialsOrConfigure } from "./configure.js";
@@ -9,8 +10,11 @@ import {
   CONVEX_DEPLOYMENT_ENV_VAR_NAME,
   CONVEX_SELF_HOSTED_URL_VAR_NAME,
 } from "./lib/utils/utils.js";
-import { getDeploymentSelection } from "./lib/deploymentSelection.js";
-import { checkVersion } from "./lib/updates.js";
+import {
+  getDeploymentSelection,
+  type DeploymentSelection,
+} from "./lib/deploymentSelection.js";
+import { checkVersionAndAiFilesStaleness } from "./lib/updates.js";
 
 export const dev = new Command("dev")
   .summary("Develop against a dev deployment, watching for changes")
@@ -18,7 +22,7 @@ export const dev = new Command("dev")
     "Develop against a dev deployment, watching for changes\n\n" +
       "  1. Configures a new or existing project (if needed)\n" +
       "  2. Updates generated types and pushes code to the configured dev deployment\n" +
-      "  3. Runs the provided command (if `--run` or `--run-sh` is used)\n" +
+      "  3. Runs the provided command (if `--start` or `--run` is used)\n" +
       "  4. Watches for file changes, and repeats step 2\n",
   )
   .allowExcessArguments(false)
@@ -59,25 +63,31 @@ export const dev = new Command("dev")
     "Execute only the first 3 steps, on failure watch for local and remote changes and retry steps 2 and 3",
     false,
   )
+  .addOption(
+    new Option(
+      "--start <command>",
+      "Start a long-running command alongside `convex dev`, like a frontend " +
+        "dev server. The command inherits stdin/stdout so you can interact " +
+        "with it directly. Example: npx convex dev --start 'vite --open'",
+    ).conflicts(["--run", "--run-sh"]),
+  )
+  .addOption(
+    new Option("--run-sh <command>", "Deprecated: use --start instead.")
+      .conflicts(["--start", "--run"])
+      .hideHelp(),
+  )
   .addOption(
     new Option(
       "--run <functionName>",
       "The identifier of the function to run in step 3, " +
         "like `api.init.createData` or `myDir/myFile:myFunction`",
-    ).conflicts(["--run-sh"]),
+    ).conflicts(["--start"]),
   )
   .option(
     "--run-component <functionName>",
     "If --run is used and the function is in a component, the path the component tree defined in convex.config.ts. " +
       "Components are a beta feature. This flag is unstable and may change in subsequent releases.",
   )
-  .addOption(
-    new Option(
-      "--run-sh <command>",
-      "A shell command to run in step 3, like `node myScript.js`. " +
-        "If you just want to run a Convex function, use `--run` instead.",
-    ).conflicts(["--run"]),
-  )
   .addOption(
     new Option(
       "--tail-logs [mode]",
@@ -96,7 +106,7 @@ export const dev = new Command("dev")
       "Ignore existing configuration and configure new or existing project, interactively or set by --team <team_slug>, --project <project_slug>, and --dev-deployment local|cloud",
     )
       .choices(["new", "existing"] as const)
-      .conflicts(["--local", "--cloud"]),
+      .conflicts(["--local", "--cloud", "--url", "--admin-key", "--env-file"]),
   )
   .addOption(
     new Option(
@@ -147,6 +157,7 @@ Same format as .env.local or .env files, and overrides them.`,
   .addOption(new Option("--local-site-port <port>").hideHelp())
   .addOption(new Option("--local-backend-version <version>").hideHelp())
   .addOption(new Option("--local-force-upgrade").default(false).hideHelp())
+  .addOption(new Option("--deployment <deployment>").hideHelp())
   .addOption(
     new Option(
       "--local",
@@ -173,6 +184,20 @@ Same format as .env.local or .env files, and overrides them.`,
       await ctx.flushAndExit(-2);
     });
 
+    if (cmdOptions.deployment !== undefined) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage:
+          "`--deployment` can’t be used with `npx convex dev`. \n\n" +
+          "  To select this deployment for development, run: \n" +
+          chalkStderr.bold(
+            `      npx convex deployment select ${cmdOptions.deployment}\n`,
+          ) +
+          "  Then, run `npx convex dev` again.",
+      });
+    }
+
     const devOptions = await normalizeDevOptions(ctx, cmdOptions);
 
     if (cmdOptions.configure === undefined) {
@@ -225,7 +250,17 @@ Same format as .env.local or .env files, and overrides them.`,
 
     const configure =
       cmdOptions.configure === true ? "ask" : (cmdOptions.configure ?? null);
-    const deploymentSelection = await getDeploymentSelection(ctx, cmdOptions);
+    // --configure means "pick a project" — skip deployment selection entirely
+    const deploymentSelection =
+      configure !== null
+        ? ({
+            kind: "chooseProject",
+            selectionWithinProject: {
+              // For backwards compatibility, allow `--configure --prod`
+              kind: cmdOptions.prod ? "prod" : "unspecified",
+            },
+          } satisfies DeploymentSelection)
+        : await getDeploymentSelection(ctx, cmdOptions);
     const credentials = await deploymentCredentialsOrConfigure(
       ctx,
       deploymentSelection,
@@ -260,7 +295,7 @@ Same format as .env.local or .env files, and overrides them.`,
       ...(credentials.deploymentFields !== null
         ? [
             usageStateWarning(ctx, credentials.deploymentFields.deploymentName),
-            checkVersion(ctx),
+            checkVersionAndAiFilesStaleness(ctx),
           ]
         : []),
     ]);

package/src/cli/docs.ts

@@ -38,7 +38,7 @@ export const docs = new Command("docs")
       `get_cookie/${configuredDeployment}`,
       BIG_BRAIN_URL,
     );
-    const fetch = await bigBrainFetch(ctx);
+    const fetch = bigBrainFetch(ctx);
     try {
       const res = await fetch(getCookieUrl);
       deprecationCheckWarning(ctx, res);

package/src/cli/init.ts

@@ -3,7 +3,7 @@ import { oneoffContext } from "../bundler/context.js";
 import { logVerbose } from "../bundler/log.js";
 import { deploymentCredentialsOrConfigure } from "./configure.js";
 import { getDeploymentSelection } from "./lib/deploymentSelection.js";
-import { checkVersion } from "./lib/updates.js";
+import { checkVersionAndAiFilesStaleness } from "./lib/updates.js";
 import { usageStateWarning } from "./lib/usage.js";
 
 // Equivalent to `npx convex dev --once --skip-push`.
@@ -37,7 +37,7 @@ export const init = new Command("init")
     if (credentials.deploymentFields !== null) {
       await Promise.all([
         usageStateWarning(ctx, credentials.deploymentFields.deploymentName),
-        checkVersion(ctx),
+        checkVersionAndAiFilesStaleness(ctx),
       ]);
     }
 

package/src/cli/lib/{ai → aiFiles}/MANUAL_TESTING.md

@@ -27,8 +27,12 @@ After `npx convex ai-files install` (or `update`) verify:
 - `.cursor/skills/` (Cursor symlinks)
 - `.claude/skills/` (Claude Code symlinks)
 
-Expected skill set: `auth-setup`, `components-guide`, `convex-helpers-guide`,
-`convex-quickstart`, `function-creator`, `migration-helper`, `schema-builder`.
+Expected skill set (as of Mar 2026): `convex-create-component`,
+`convex-migration-helper`, `convex-performance-audit`, `convex-quickstart`,
+`convex-setup-auth`.
+
+Note: the live skill set is fetched remotely and may change. Check the current
+list against what `npx convex ai-files status` reports after install.
 
 **Why manual:** these paths and symlink behaviors are environment-dependent and
 are mocked in automated tests.

package/src/cli/lib/aiFiles/agentsmd.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { injectAgentsMdSection, hasAgentsMdInstalled } from "./agentsmd.js";
+import {
+  AGENTS_MD_START_MARKER,
+  AGENTS_MD_END_MARKER,
+} from "../../codegen_templates/agentsmd.js";
+
+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, projectDir: 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, projectDir: 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({ section: newSection, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
+    expect(content).toContain("New content.");
+    expect(content).not.toContain("Old content.");
+    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, projectDir: 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 result = await injectAgentsMdSection({ section, projectDir: tmpDir });
+    expect(typeof result.sectionHash).toBe("string");
+    expect(result.sectionHash.length).toBeGreaterThan(0);
+    expect(result.didWrite).toBe(true);
+  });
+
+  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 result = await injectAgentsMdSection({ section, projectDir: tmpDir });
+
+    const { hashSha256 } = await import("../utils/hash.js");
+    expect(result.sectionHash).toBe(hashSha256(section));
+  });
+
+  test("does not write when content is unchanged", async () => {
+    await injectAgentsMdSection({ section, projectDir: tmpDir });
+    const result = await injectAgentsMdSection({ section, projectDir: tmpDir });
+    expect(result.didWrite).toBe(false);
+  });
+});
+
+describe("hasAgentsMdInstalled", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns false when AGENTS.md does not exist", async () => {
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns false when AGENTS.md exists but has no managed markers", async () => {
+    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), "User content only\n");
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns false when only the start marker is present", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "AGENTS.md"),
+      `${AGENTS_MD_START_MARKER}\npartial content\n`,
+    );
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns true when both markers are present", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "AGENTS.md"),
+      `# Project\n\n${AGENTS_MD_START_MARKER}\n## Convex\n${AGENTS_MD_END_MARKER}\n`,
+    );
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(true);
+  });
+});

package/src/cli/lib/aiFiles/agentsmd.ts

@@ -0,0 +1,81 @@
+import {
+  AGENTS_MD_START_MARKER,
+  AGENTS_MD_END_MARKER,
+  agentsMdConvexSection,
+} from "../../codegen_templates/agentsmd.js";
+import { agentsMdPath } from "./paths.js";
+import { type AiFilesState } from "./state.js";
+import {
+  type ManagedSectionTarget,
+  type InjectResult,
+  type StripResult,
+  injectManagedSection,
+  attemptToStripManagedSection,
+  hasManagedSection,
+  attemptToRemoveMarkdownSection,
+} from "./utils.js";
+import { logMessage } from "../../../bundler/log.js";
+import { chalkStderr } from "chalk";
+
+function target(projectDir?: string): ManagedSectionTarget {
+  return {
+    filePath: agentsMdPath(projectDir),
+    startMarker: AGENTS_MD_START_MARKER,
+    endMarker: AGENTS_MD_END_MARKER,
+  };
+}
+
+export async function injectAgentsMdSection({
+  section,
+  projectDir,
+}: {
+  section: string;
+  projectDir?: string;
+}): Promise<InjectResult> {
+  return injectManagedSection({ ...target(projectDir), section });
+}
+
+export async function attemptToStripAgentsMdSection(
+  projectDir: string,
+): Promise<StripResult> {
+  return attemptToStripManagedSection(target(projectDir));
+}
+
+export async function attemptToRemoveAgentsMdSection(
+  projectDir: string,
+): Promise<boolean> {
+  return attemptToRemoveMarkdownSection({
+    projectDir,
+    strip: attemptToStripAgentsMdSection,
+    fileName: "AGENTS.md",
+  });
+}
+
+export async function hasAgentsMdInstalled(
+  projectDir: string,
+): Promise<boolean> {
+  return hasManagedSection(target(projectDir));
+}
+
+/**
+ * Inject (or update) the Convex section in AGENTS.md and record the hash.
+ * Returns true if the file was actually written.
+ */
+export async function applyAgentsMdSection({
+  projectDir,
+  state,
+  convexDirName,
+}: {
+  projectDir: string;
+  state: AiFilesState;
+  convexDirName: string;
+}): Promise<boolean> {
+  const result = await injectAgentsMdSection({
+    section: agentsMdConvexSection(convexDirName),
+    projectDir,
+  });
+  if (result.didWrite)
+    logMessage(`${chalkStderr.green("✔")} AGENTS.md written`);
+  state.agentsMdSectionHash = result.sectionHash;
+  return result.didWrite;
+}

package/src/cli/lib/aiFiles/claudemd.test.ts

@@ -0,0 +1,92 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { injectClaudeMdSection, hasClaudeMdInstalled } from "./claudemd.js";
+import {
+  CLAUDE_MD_START_MARKER,
+  CLAUDE_MD_END_MARKER,
+} from "../../codegen_templates/claudemd.js";
+
+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, projectDir: 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, projectDir: 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, projectDir: 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");
+  });
+});
+
+describe("hasClaudeMdInstalled", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns false when CLAUDE.md does not exist", async () => {
+    expect(await hasClaudeMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns false when CLAUDE.md exists but has no managed markers", async () => {
+    fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), "User content only\n");
+    expect(await hasClaudeMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns true when both markers are present", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "CLAUDE.md"),
+      `${CLAUDE_MD_START_MARKER}\n## Convex\n${CLAUDE_MD_END_MARKER}\n`,
+    );
+    expect(await hasClaudeMdInstalled(tmpDir)).toBe(true);
+  });
+});

package/src/cli/lib/aiFiles/claudemd.ts

@@ -0,0 +1,81 @@
+import {
+  CLAUDE_MD_END_MARKER,
+  CLAUDE_MD_START_MARKER,
+  claudeMdConvexSection,
+} from "../../codegen_templates/claudemd.js";
+import { claudeMdPath } from "./paths.js";
+import { type AiFilesState } from "./state.js";
+import {
+  type ManagedSectionTarget,
+  type InjectResult,
+  type StripResult,
+  injectManagedSection,
+  attemptToStripManagedSection,
+  hasManagedSection,
+  attemptToRemoveMarkdownSection,
+} from "./utils.js";
+import { logMessage } from "../../../bundler/log.js";
+import { chalkStderr } from "chalk";
+
+function target(projectDir?: string): ManagedSectionTarget {
+  return {
+    filePath: claudeMdPath(projectDir),
+    startMarker: CLAUDE_MD_START_MARKER,
+    endMarker: CLAUDE_MD_END_MARKER,
+  };
+}
+
+export async function injectClaudeMdSection({
+  section,
+  projectDir,
+}: {
+  section: string;
+  projectDir?: string;
+}): Promise<InjectResult> {
+  return injectManagedSection({ ...target(projectDir), section });
+}
+
+export async function attemptToStripClaudeMdSection(
+  projectDir: string,
+): Promise<StripResult> {
+  return attemptToStripManagedSection(target(projectDir));
+}
+
+export async function attemptToRemoveClaudeMdSection(
+  projectDir: string,
+): Promise<boolean> {
+  return attemptToRemoveMarkdownSection({
+    projectDir,
+    strip: attemptToStripClaudeMdSection,
+    fileName: "CLAUDE.md",
+  });
+}
+
+export async function hasClaudeMdInstalled(
+  projectDir: string,
+): Promise<boolean> {
+  return hasManagedSection(target(projectDir));
+}
+
+/**
+ * Inject (or update) the Convex section in CLAUDE.md and record the hash.
+ * Returns true if the file was actually written.
+ */
+export async function applyClaudeMdSection({
+  projectDir,
+  state,
+  convexDirName,
+}: {
+  projectDir: string;
+  state: AiFilesState;
+  convexDirName: string;
+}): Promise<boolean> {
+  const result = await injectClaudeMdSection({
+    section: claudeMdConvexSection(convexDirName),
+    projectDir,
+  });
+  if (result.didWrite)
+    logMessage(`${chalkStderr.green("✔")} CLAUDE.md written`);
+  state.claudeMdHash = result.sectionHash;
+  return result.didWrite;
+}

package/src/cli/lib/aiFiles/cursorrules.ts

@@ -0,0 +1,25 @@
+import path from "path";
+import { chalkStderr } from "chalk";
+import { logMessage } from "../../../bundler/log.js";
+import { safelyDeleteFile } from "./utils.js";
+
+/**
+ * Remove the legacy `.cursor/rules/convex_rules.mdc` file if it exists.
+ * This file was written by the old cursor rules auto-update feature (removed
+ * in favour of the AI files system). We clean it up unconditionally
+ * during `writeAiFiles`, `convex ai-files update`, and `convex ai-files remove`
+ * since it was always auto-managed and is now superseded by
+ * `convex/_generated/ai/guidelines.md`.
+ */
+export async function removeLegacyCursorRulesFile(
+  projectDir: string,
+): Promise<boolean> {
+  const removed = await safelyDeleteFile(
+    path.join(projectDir, ".cursor", "rules", "convex_rules.mdc"),
+  );
+  if (removed)
+    logMessage(
+      `${chalkStderr.green("✔")} Removed legacy .cursor/rules/convex_rules.mdc (superseded by convex/_generated/ai/guidelines.md).`,
+    );
+  return removed;
+}

package/src/cli/lib/aiFiles/guidelinesmd.test.ts

@@ -0,0 +1,50 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { hasGuidelinesInstalled } from "./guidelinesmd.js";
+
+describe("hasGuidelinesInstalled", () => {
+  let tmpDir: string;
+  let convexDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+    convexDir = path.join(tmpDir, "convex");
+    fs.mkdirSync(path.join(convexDir, "_generated", "ai"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns false when guidelines.md does not exist", async () => {
+    expect(await hasGuidelinesInstalled(convexDir)).toBe(false);
+  });
+
+  test("returns true when guidelines.md exists", async () => {
+    fs.writeFileSync(
+      path.join(convexDir, "_generated", "ai", "guidelines.md"),
+      "some content",
+    );
+    expect(await hasGuidelinesInstalled(convexDir)).toBe(true);
+  });
+
+  test("returns false when guidelines.md is empty", async () => {
+    fs.writeFileSync(
+      path.join(convexDir, "_generated", "ai", "guidelines.md"),
+      "",
+    );
+    expect(await hasGuidelinesInstalled(convexDir)).toBe(false);
+  });
+
+  test("throws when guidelines.md cannot be read", async () => {
+    fs.rmSync(path.join(convexDir, "_generated", "ai", "guidelines.md"), {
+      force: true,
+      recursive: true,
+    });
+    fs.mkdirSync(path.join(convexDir, "_generated", "ai", "guidelines.md"));
+
+    await expect(hasGuidelinesInstalled(convexDir)).rejects.toThrow();
+  });
+});