create-vexcms 0.0.20 → 0.1.0-alpha.3

package/dist/index.js

@@ -4,8 +4,8 @@
 import { Command } from "commander";
 import chalk2 from "chalk";
 import { input, select, confirm, checkbox } from "@inquirer/prompts";
-import path2 from "path";
-import fs5 from "fs-extra";
+import path3 from "path";
+import fs6 from "fs-extra";
 
 // src/utils/validation.ts
 import validateNpmPackageName from "validate-npm-package-name";
@@ -32,11 +32,11 @@ async function isDirectoryEmpty(dirPath) {
     const files = await fs.readdir(dirPath);
     const visibleFiles = files.filter((file) => !file.startsWith("."));
     return visibleFiles.length === 0;
-  } catch (error) {
+  } catch {
     return true;
   }
 }
-function resolveProjectName(input2, cwd) {
+function resolveProjectName(input2, _cwd) {
   return input2;
 }
 
@@ -75,15 +75,60 @@ function displaySuccessMessage(projectName, targetPath, isCurrentDir) {
   console.log();
 }
 
+// src/helpers/monorepo.ts
+import fs2 from "fs-extra";
+import path from "path";
+import { parse as parseYaml } from "yaml";
+import sortPackageJson from "sort-package-json";
+async function findWorkspaceRoot(props) {
+  const { cwd } = props;
+  let dir = path.resolve(cwd);
+  while (true) {
+    if (await fs2.pathExists(path.join(dir, "pnpm-workspace.yaml"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function readWorkspaceCatalog(props) {
+  const { workspaceRoot } = props;
+  const raw = await fs2.readFile(path.join(workspaceRoot, "pnpm-workspace.yaml"), "utf-8");
+  const parsed = parseYaml(raw);
+  return parsed.catalog ?? {};
+}
+var MONOREPO_DEPENDENCY_FIELDS = ["dependencies", "devDependencies"];
+function rewriteManifestForMonorepo(props) {
+  const { manifest, catalog } = props;
+  const rewritten = { ...manifest };
+  for (const field of MONOREPO_DEPENDENCY_FIELDS) {
+    const deps = manifest[field];
+    if (!deps) continue;
+    const rewrittenDeps = {};
+    for (const [name, version] of Object.entries(deps)) {
+      if (name.startsWith("@vexcms/")) {
+        rewrittenDeps[name] = "workspace:*";
+      } else if (name in catalog) {
+        rewrittenDeps[name] = "catalog:";
+      } else {
+        rewrittenDeps[name] = version;
+      }
+    }
+    rewritten[field] = rewrittenDeps;
+  }
+  return sortPackageJson(rewritten);
+}
+
 // src/installers/base.ts
-import fs3 from "fs-extra";
+import fs5 from "fs-extra";
 import { execa } from "execa";
 import ora from "ora";
 import crypto from "crypto";
-import path from "path";
+import path2 from "path";
 
 // src/helpers/fileOperations.ts
-import fs2 from "fs-extra";
+import fs3 from "fs-extra";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 async function copyTemplate(framework, targetPath) {
@@ -91,10 +136,10 @@ async function copyTemplate(framework, targetPath) {
   const __dirname = dirname(__filename);
   const templateDir = framework === "tanstack" ? "base-tanstack" : "base-nextjs";
   let templatePath = join(__dirname, "../../templates", templateDir);
-  if (!fs2.existsSync(templatePath)) {
+  if (!fs3.existsSync(templatePath)) {
     templatePath = join(__dirname, "../templates", templateDir);
   }
-  await fs2.copy(templatePath, targetPath, {
+  await fs3.copy(templatePath, targetPath, {
     overwrite: false,
     errorOnExist: false,
     filter: (src) => {
@@ -105,8 +150,8 @@ async function copyTemplate(framework, targetPath) {
   });
   const sourceGitignore = join(templatePath, "_gitignore");
   const targetGitignore = join(targetPath, ".gitignore");
-  if (await fs2.pathExists(sourceGitignore)) {
-    await fs2.copy(sourceGitignore, targetGitignore, {
+  if (await fs3.pathExists(sourceGitignore)) {
+    await fs3.copy(sourceGitignore, targetGitignore, {
       overwrite: false,
       errorOnExist: false
     });
@@ -119,521 +164,196 @@ async function copyTemplate(framework, targetPath) {
   for (const [from, to] of dotfileRenames) {
     const source = join(templatePath, from);
     const target = join(targetPath, to);
-    if (await fs2.pathExists(source)) {
-      await fs2.copy(source, target, { overwrite: false, errorOnExist: false });
+    if (await fs3.pathExists(source)) {
+      await fs3.copy(source, target, { overwrite: false, errorOnExist: false });
     }
   }
 }
 async function overlayTemplate({ overlayDir, targetDir }) {
-  await fs2.copy(overlayDir, targetDir, { overwrite: true });
+  await fs3.copy(overlayDir, targetDir, { overwrite: true });
 }
 
-// src/installers/base.ts
-var VexFrameworkInstaller = class {
-  constructor(targetPath, projectName) {
-    this.targetPath = targetPath;
-    this.projectName = projectName;
-  }
-  /**
-   * Copy base template files to target directory
-   */
-  async copyBaseFiles() {
-    await copyTemplate(this.frameworkName, this.targetPath);
-  }
-  /**
-   * Apply a template overlay on top of the base template.
-   * Merges overlay files onto the already-copied base — existing files
-   * not in the overlay are left untouched.
-   */
-  async applyTemplateOverlay(overlay) {
-    const { dirname: dirname2 } = await import("path");
-    const { fileURLToPath: fileURLToPath2 } = await import("url");
-    const __filename = fileURLToPath2(import.meta.url);
-    const __dirname = dirname2(__filename);
-    let overlayDir = path.join(__dirname, "../../templates", overlay);
-    if (!await fs3.pathExists(overlayDir)) {
-      overlayDir = path.join(__dirname, "../templates", overlay);
-    }
-    await overlayTemplate({ overlayDir, targetDir: this.targetPath });
-  }
-  /**
-   * Update the package.json name field and vex:update script
-   * to match the detected package manager.
-   */
-  async updatePackageName(name) {
-    const pkgPath = path.join(this.targetPath, "package.json");
-    const pkg = await fs3.readJson(pkgPath);
-    pkg.name = name;
-    const pm = this.detectPackageManager();
-    if (pkg.scripts?.["vex:update"] && pm !== "pnpm") {
-      const addCmd = pm === "yarn" ? "yarn add" : pm === "bun" ? "bun add" : "npm install";
-      pkg.scripts["vex:update"] = pkg.scripts["vex:update"].replace(/^pnpm add/, addCmd);
-    }
-    await fs3.writeJson(pkgPath, pkg, { spaces: 2 });
-  }
-  /**
-   * Configure the dev server port.
-   * Updates package.json dev script and creates .env.local with NEXT_PUBLIC_SITE_URL.
-   */
-  async configurePort(port) {
-    const pkgPath = path.join(this.targetPath, "package.json");
-    const pkg = await fs3.readJson(pkgPath);
-    if (pkg.scripts?.dev) {
-      if (pkg.scripts.dev.includes("--port")) {
-        pkg.scripts.dev = pkg.scripts.dev.replace(/--port[= ]\d+/, `--port=${port}`);
-      } else {
-        pkg.scripts.dev = `${pkg.scripts.dev} --port=${port}`;
+// src/installers/string-utils.ts
+import fs4 from "fs-extra";
+
+// src/installers/providers.ts
+var OAUTH_PROVIDERS = {
+  // ========================================
+  // POPULAR PROVIDERS (10)
+  // ========================================
+  google: {
+    id: "google",
+    name: "Google",
+    envPrefix: "GOOGLE",
+    clientIdVar: "GOOGLE_CLIENT_ID",
+    clientSecretVar: "GOOGLE_CLIENT_SECRET",
+    popular: true,
+    betterAuthConfig: {
+      import: "",
+      clientSideProvider: '"google"',
+      socialProvider: `google({
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    })`,
+      scopes: []
+    },
+    env: [
+      {
+        name: "GOOGLE_CLIENT_ID",
+        type: "server",
+        description: "Google OAuth Client ID"
+      },
+      {
+        name: "GOOGLE_CLIENT_SECRET",
+        type: "server",
+        description: "Google OAuth Client Secret"
       }
+    ],
+    docs: {
+      provider: "https://console.cloud.google.com/apis/credentials",
+      betterAuth: "https://www.better-auth.com/docs/authentication/social"
+    },
+    requiresExtraConfig: false,
+    extraConfigNotes: "",
+    readme: {
+      title: "Google OAuth Setup",
+      content: `## Google OAuth Setup
+
+1. Create OAuth credentials at https://console.cloud.google.com/apis/credentials
+2. Set the Authorized redirect URI to: \`http://localhost:3000/api/auth/callback/google\` (update for production)
+3. Copy the Client ID and Client Secret to your \`.env\` file
+
+For more details, see the [Better Auth documentation](https://www.better-auth.com/docs/authentication/social).`
     }
-    await fs3.writeJson(pkgPath, pkg, { spaces: 2 });
-    const envLocalPath = path.join(this.targetPath, ".env.local");
-    const envContent = `NEXT_PUBLIC_SITE_URL=http://localhost:${port}
-BETTER_AUTH_SECRET=""
-`;
-    await fs3.writeFile(envLocalPath, envContent);
-  }
-  /**
-   * Detect the package manager used to invoke the CLI
-   */
-  detectPackageManager() {
-    const userAgent = process.env.npm_config_user_agent;
-    if (userAgent) {
-      if (userAgent.includes("pnpm")) return "pnpm";
-      if (userAgent.includes("yarn")) return "yarn";
-      if (userAgent.includes("bun")) return "bun";
-    }
-    return "npm";
-  }
-  /**
-   * Install project dependencies using detected package manager
-   */
-  async installDependencies() {
-    const packageManager = this.detectPackageManager();
-    const spinner = ora(`Installing dependencies with ${packageManager}...`).start();
-    try {
-      await execa(packageManager, ["install"], {
-        cwd: this.targetPath,
-        stdio: "pipe"
-      });
-      spinner.succeed("Dependencies installed successfully");
-    } catch (error) {
-      spinner.fail("Failed to install dependencies");
-      throw new Error(
-        `Dependency installation failed: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Format code using project's formatter
-   */
-  async formatCode() {
-    const packageManager = this.detectPackageManager();
-    const spinner = ora("Formatting code...").start();
-    try {
-      const result = await execa(packageManager, ["run", "format"], {
-        cwd: this.targetPath,
-        stdio: "pipe",
-        reject: false
-      });
-      if (result.exitCode === 0) {
-        spinner.succeed("Code formatted successfully");
-      } else {
-        spinner.warn("Formatting completed with warnings");
+  },
+  github: {
+    id: "github",
+    name: "GitHub",
+    envPrefix: "GITHUB",
+    clientIdVar: "GITHUB_CLIENT_ID",
+    clientSecretVar: "GITHUB_CLIENT_SECRET",
+    popular: true,
+    betterAuthConfig: {
+      import: "",
+      clientSideProvider: '"github"',
+      socialProvider: `github({
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    })`,
+      scopes: ["user:email"]
+    },
+    env: [
+      {
+        name: "GITHUB_CLIENT_ID",
+        type: "server",
+        description: "GitHub OAuth App Client ID"
+      },
+      {
+        name: "GITHUB_CLIENT_SECRET",
+        type: "server",
+        description: "GitHub OAuth App Client Secret"
       }
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      spinner.warn(`Failed to format code: ${errorMessage}`);
+    ],
+    docs: {
+      provider: "https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app",
+      betterAuth: "https://www.better-auth.com/docs/authentication/social"
+    },
+    requiresExtraConfig: true,
+    extraConfigNotes: "You MUST include the user:email scope in your GitHub app. For GitHub Apps, enable Read-Only access to Email Addresses in Permissions.",
+    readme: {
+      title: "GitHub OAuth Setup",
+      content: `## GitHub OAuth Setup
+
+1. Create a GitHub OAuth App at https://github.com/settings/developers
+2. Set the Authorization callback URL to: \`http://localhost:3000/api/auth/callback/github\` (update for production)
+3. Copy the Client ID and Client Secret to your \`.env\` file
+4. **Important**: Include the \`user:email\` scope in your GitHub app permissions
+
+For more details, see the [Better Auth documentation](https://www.better-auth.com/docs/authentication/social).`
     }
-  }
-  /**
-   * Lint and fix code using project's ESLint configuration
-   */
-  async lintCode() {
-    const packageManager = this.detectPackageManager();
-    const spinner = ora("Linting and fixing code...").start();
-    try {
-      const args2 = packageManager === "pnpm" ? ["lint", "--fix"] : ["run", "lint", "--", "--fix"];
-      const result = await execa(packageManager, args2, {
-        cwd: this.targetPath,
-        stdio: "pipe",
-        reject: false
-      });
-      if (result.exitCode === 0) {
-        spinner.succeed("Code linted and fixed successfully");
-      } else {
-        spinner.warn("Linting completed with warnings");
-      }
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      spinner.warn(`Failed to lint code: ${errorMessage}`);
-    }
-  }
-  /**
-   * Initialize Git repository in target directory
-   */
-  async initGitRepo() {
-    const spinner = ora("Initializing Git repository...").start();
-    try {
-      try {
-        await execa("git", ["--version"], { stdio: "pipe" });
-      } catch {
-        spinner.fail("Git is not installed");
-        throw new Error("Git is not installed. Please install Git to initialize a repository.");
-      }
-      await execa("git", ["init"], { cwd: this.targetPath, stdio: "pipe" });
-      await execa("git", ["add", "."], { cwd: this.targetPath, stdio: "pipe" });
-      await execa(
-        "git",
-        ["commit", "-m", "Initial commit from create-vexcms"],
-        { cwd: this.targetPath, stdio: "pipe" }
-      );
-      spinner.succeed("Git repository initialized");
-    } catch (error) {
-      spinner.fail("Failed to initialize Git repository");
-      throw new Error(
-        `Git initialization failed: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Generate a secure random secret for Better Auth
-   */
-  generateAuthSecret() {
-    return crypto.randomBytes(32).toString("hex");
-  }
-  /**
-   * Write the generated auth secret to .env.example
-   */
-  async writeAuthSecret() {
-    const envPath = path.join(this.targetPath, ".env.example");
-    const secret = this.generateAuthSecret();
-    if (await fs3.pathExists(envPath)) {
-      let content = await fs3.readFile(envPath, "utf-8");
-      content = content.replace(
-        /BETTER_AUTH_SECRET=.*/,
-        `BETTER_AUTH_SECRET=${secret}`
-      );
-      await fs3.writeFile(envPath, content);
-    }
-  }
-  /**
-   * Configure the Better Auth organizations plugin.
-   * When enabled, replaces placeholders with organization import and plugin.
-   * When disabled, removes the placeholder lines.
-   */
-  async configureOrganizations(enabled) {
-    const pluginsPath = path.join(this.targetPath, "convex/auth/plugins/index.ts");
-    if (!await fs3.pathExists(pluginsPath)) return;
-    let content = await fs3.readFile(pluginsPath, "utf-8");
-    if (enabled) {
-      content = content.replace(
-        "// {{ORGANIZATIONS_IMPORT}}",
-        'import { organization } from "better-auth/plugins"'
-      );
-      content = content.replace(
-        "  // {{ORGANIZATIONS_PLUGIN}}",
-        "  organization(),"
-      );
-    } else {
-      content = content.replace(/.*\/\/ \{\{ORGANIZATIONS_IMPORT\}\}\n?/, "");
-      content = content.replace(/.*\/\/ \{\{ORGANIZATIONS_PLUGIN\}\}\n?/, "");
-    }
-    await fs3.writeFile(pluginsPath, content);
-  }
-  /**
-   * Main orchestration method for project initialization
-   */
-  async initProject(options) {
-    const copySpinner = ora("Copying template files...").start();
-    try {
-      await this.copyBaseFiles();
-      copySpinner.succeed("Template files copied");
-    } catch (error) {
-      copySpinner.fail("Failed to copy template files");
-      throw error;
-    }
-    if (!options.bare) {
-      const overlaySpinner = ora("Applying marketing site template...").start();
-      try {
-        await this.applyTemplateOverlay("marketing-site");
-        overlaySpinner.succeed("Marketing site template applied");
-      } catch (error) {
-        overlaySpinner.fail("Failed to apply template overlay");
-        throw error;
-      }
-    }
-    const nameSpinner = ora("Configuring project...").start();
-    try {
-      await this.updatePackageName(options.projectName);
-      await this.configurePort(options.port);
-      nameSpinner.succeed("Project configured");
-    } catch (error) {
-      nameSpinner.fail("Failed to configure project");
-      throw error;
-    }
-    const authSpinner = ora("Configuring authentication...").start();
-    try {
-      await this.updateOAuthConfig(options.oauthProviders, options.emailPasswordAuth);
-      authSpinner.succeed(
-        options.emailPasswordAuth || options.oauthProviders.length > 0 ? "Authentication configuration updated" : "Authentication placeholders cleaned up"
-      );
-    } catch (error) {
-      authSpinner.fail("Failed to configure authentication");
-      throw error;
-    }
-    const oauthUISpinner = ora("Configuring OAuth UI...").start();
-    try {
-      await this.updateOAuthUIConfig(options.oauthProviders, options.emailPasswordAuth);
-      oauthUISpinner.succeed(
-        options.oauthProviders.length > 0 ? "OAuth UI configuration updated" : "OAuth UI placeholders cleaned up"
-      );
-    } catch (error) {
-      oauthUISpinner.fail("Failed to configure OAuth UI");
-      throw error;
-    }
-    const envSpinner = ora("Updating .env.example...").start();
-    try {
-      await this.updateEnvExample(options.oauthProviders);
-      envSpinner.succeed(
-        options.oauthProviders.length > 0 ? ".env.example updated" : ".env.example placeholders cleaned up"
-      );
-    } catch (error) {
-      envSpinner.fail("Failed to update .env.example");
-      throw error;
-    }
-    const envTsSpinner = ora("Updating typed env configuration...").start();
-    try {
-      await this.updateEnvTs(options.oauthProviders);
-      envTsSpinner.succeed(
-        options.oauthProviders.length > 0 ? "Typed env configuration updated" : "Typed env placeholders cleaned up"
-      );
-    } catch (error) {
-      envTsSpinner.fail("Failed to update typed env configuration");
-      throw error;
-    }
-    const readmeSpinner = ora("Updating README...").start();
-    try {
-      await this.updateReadme(options.oauthProviders);
-      readmeSpinner.succeed(
-        options.oauthProviders.length > 0 ? "README updated" : "README placeholders cleaned up"
-      );
-    } catch (error) {
-      readmeSpinner.fail("Failed to update README");
-      throw error;
-    }
-    const orgsSpinner = ora("Configuring organizations...").start();
-    try {
-      await this.configureOrganizations(options.orgs);
-      orgsSpinner.succeed(
-        options.orgs ? "Organizations plugin enabled" : "Organizations placeholders cleaned up"
-      );
-    } catch (error) {
-      orgsSpinner.fail("Failed to configure organizations");
-      throw error;
-    }
-    const secretSpinner = ora("Generating auth secret...").start();
-    try {
-      await this.writeAuthSecret();
-      secretSpinner.succeed("Auth secret generated");
-    } catch (error) {
-      secretSpinner.fail("Failed to generate auth secret");
-      throw error;
-    }
-    if (options.initGit) {
-      await this.initGitRepo();
-    }
-    if (options.installDependencies) {
-      await this.installDependencies();
-      await this.lintCode();
-      await this.formatCode();
-    }
-  }
-};
-
-// src/installers/nextjs.ts
-import { join as join2 } from "path";
-
-// src/installers/string-utils.ts
-import fs4 from "fs-extra";
-
-// src/installers/providers.ts
-var OAUTH_PROVIDERS = {
-  // ========================================
-  // POPULAR PROVIDERS (10)
-  // ========================================
-  google: {
-    id: "google",
-    name: "Google",
-    envPrefix: "GOOGLE",
-    clientIdVar: "GOOGLE_CLIENT_ID",
-    clientSecretVar: "GOOGLE_CLIENT_SECRET",
-    popular: true,
-    betterAuthConfig: {
-      import: "",
-      clientSideProvider: '"google"',
-      socialProvider: `google({
-      clientId: process.env.GOOGLE_CLIENT_ID!,
-      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-    })`,
-      scopes: []
-    },
-    env: [
-      {
-        name: "GOOGLE_CLIENT_ID",
-        type: "server",
-        description: "Google OAuth Client ID"
-      },
-      {
-        name: "GOOGLE_CLIENT_SECRET",
-        type: "server",
-        description: "Google OAuth Client Secret"
+  },
+  discord: {
+    id: "discord",
+    name: "Discord",
+    envPrefix: "DISCORD",
+    clientIdVar: "DISCORD_CLIENT_ID",
+    clientSecretVar: "DISCORD_CLIENT_SECRET",
+    popular: true,
+    betterAuthConfig: {
+      import: "",
+      clientSideProvider: '"discord"',
+      socialProvider: `discord({
+      clientId: process.env.DISCORD_CLIENT_ID!,
+      clientSecret: process.env.DISCORD_CLIENT_SECRET!,
+    })`,
+      scopes: []
+    },
+    env: [
+      {
+        name: "DISCORD_CLIENT_ID",
+        type: "server",
+        description: "Discord OAuth Application Client ID"
+      },
+      {
+        name: "DISCORD_CLIENT_SECRET",
+        type: "server",
+        description: "Discord OAuth Application Client Secret"
       }
     ],
     docs: {
-      provider: "https://console.cloud.google.com/apis/credentials",
+      provider: "https://discord.com/developers/applications",
       betterAuth: "https://www.better-auth.com/docs/authentication/social"
     },
     requiresExtraConfig: false,
-    extraConfigNotes: "",
+    extraConfigNotes: "You can optionally add a permissions field to request additional Discord permissions.",
     readme: {
-      title: "Google OAuth Setup",
-      content: `## Google OAuth Setup
+      title: "Discord OAuth Setup",
+      content: `## Discord OAuth Setup
 
-1. Create OAuth credentials at https://console.cloud.google.com/apis/credentials
-2. Set the Authorized redirect URI to: \`http://localhost:3000/api/auth/callback/google\` (update for production)
+1. Create an application at https://discord.com/developers/applications
+2. Add a redirect URL: \`http://localhost:3000/api/auth/callback/discord\` (update for production)
 3. Copy the Client ID and Client Secret to your \`.env\` file
 
 For more details, see the [Better Auth documentation](https://www.better-auth.com/docs/authentication/social).`
     }
   },
-  github: {
-    id: "github",
-    name: "GitHub",
-    envPrefix: "GITHUB",
-    clientIdVar: "GITHUB_CLIENT_ID",
-    clientSecretVar: "GITHUB_CLIENT_SECRET",
+  apple: {
+    id: "apple",
+    name: "Apple",
+    envPrefix: "APPLE",
+    clientIdVar: "APPLE_CLIENT_ID",
+    clientSecretVar: "APPLE_CLIENT_SECRET",
     popular: true,
     betterAuthConfig: {
       import: "",
-      clientSideProvider: '"github"',
-      socialProvider: `github({
-      clientId: process.env.GITHUB_CLIENT_ID!,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      clientSideProvider: '"apple"',
+      socialProvider: `apple({
+      clientId: process.env.APPLE_CLIENT_ID!,
+      clientSecret: process.env.APPLE_CLIENT_SECRET!,
     })`,
-      scopes: ["user:email"]
+      scopes: []
     },
     env: [
       {
-        name: "GITHUB_CLIENT_ID",
+        name: "APPLE_CLIENT_ID",
         type: "server",
-        description: "GitHub OAuth App Client ID"
+        description: "Apple Sign In Service ID"
       },
       {
-        name: "GITHUB_CLIENT_SECRET",
+        name: "APPLE_CLIENT_SECRET",
         type: "server",
-        description: "GitHub OAuth App Client Secret"
+        description: "Apple Sign In Client Secret (JWT token)"
       }
     ],
     docs: {
-      provider: "https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app",
+      provider: "https://developer.apple.com/sign-in-with-apple/get-started/",
       betterAuth: "https://www.better-auth.com/docs/authentication/social"
     },
     requiresExtraConfig: true,
-    extraConfigNotes: "You MUST include the user:email scope in your GitHub app. For GitHub Apps, enable Read-Only access to Email Addresses in Permissions.",
+    extraConfigNotes: "Apple requires additional configuration: clientId is your Service ID, clientSecret must be a JWT token generated from your Team ID, Key ID, and Private Key. You may also need to provide appBundleIdentifier for iOS apps.",
     readme: {
-      title: "GitHub OAuth Setup",
-      content: `## GitHub OAuth Setup
-
-1. Create a GitHub OAuth App at https://github.com/settings/developers
-2. Set the Authorization callback URL to: \`http://localhost:3000/api/auth/callback/github\` (update for production)
-3. Copy the Client ID and Client Secret to your \`.env\` file
-4. **Important**: Include the \`user:email\` scope in your GitHub app permissions
-
-For more details, see the [Better Auth documentation](https://www.better-auth.com/docs/authentication/social).`
-    }
-  },
-  discord: {
-    id: "discord",
-    name: "Discord",
-    envPrefix: "DISCORD",
-    clientIdVar: "DISCORD_CLIENT_ID",
-    clientSecretVar: "DISCORD_CLIENT_SECRET",
-    popular: true,
-    betterAuthConfig: {
-      import: "",
-      clientSideProvider: '"discord"',
-      socialProvider: `discord({
-      clientId: process.env.DISCORD_CLIENT_ID!,
-      clientSecret: process.env.DISCORD_CLIENT_SECRET!,
-    })`,
-      scopes: []
-    },
-    env: [
-      {
-        name: "DISCORD_CLIENT_ID",
-        type: "server",
-        description: "Discord OAuth Application Client ID"
-      },
-      {
-        name: "DISCORD_CLIENT_SECRET",
-        type: "server",
-        description: "Discord OAuth Application Client Secret"
-      }
-    ],
-    docs: {
-      provider: "https://discord.com/developers/applications",
-      betterAuth: "https://www.better-auth.com/docs/authentication/social"
-    },
-    requiresExtraConfig: false,
-    extraConfigNotes: "You can optionally add a permissions field to request additional Discord permissions.",
-    readme: {
-      title: "Discord OAuth Setup",
-      content: `## Discord OAuth Setup
-
-1. Create an application at https://discord.com/developers/applications
-2. Add a redirect URL: \`http://localhost:3000/api/auth/callback/discord\` (update for production)
-3. Copy the Client ID and Client Secret to your \`.env\` file
-
-For more details, see the [Better Auth documentation](https://www.better-auth.com/docs/authentication/social).`
-    }
-  },
-  apple: {
-    id: "apple",
-    name: "Apple",
-    envPrefix: "APPLE",
-    clientIdVar: "APPLE_CLIENT_ID",
-    clientSecretVar: "APPLE_CLIENT_SECRET",
-    popular: true,
-    betterAuthConfig: {
-      import: "",
-      clientSideProvider: '"apple"',
-      socialProvider: `apple({
-      clientId: process.env.APPLE_CLIENT_ID!,
-      clientSecret: process.env.APPLE_CLIENT_SECRET!,
-    })`,
-      scopes: []
-    },
-    env: [
-      {
-        name: "APPLE_CLIENT_ID",
-        type: "server",
-        description: "Apple Sign In Service ID"
-      },
-      {
-        name: "APPLE_CLIENT_SECRET",
-        type: "server",
-        description: "Apple Sign In Client Secret (JWT token)"
-      }
-    ],
-    docs: {
-      provider: "https://developer.apple.com/sign-in-with-apple/get-started/",
-      betterAuth: "https://www.better-auth.com/docs/authentication/social"
-    },
-    requiresExtraConfig: true,
-    extraConfigNotes: "Apple requires additional configuration: clientId is your Service ID, clientSecret must be a JWT token generated from your Team ID, Key ID, and Private Key. You may also need to provide appBundleIdentifier for iOS apps.",
-    readme: {
-      title: "Apple Sign In Setup",
-      content: `## Apple Sign In Setup
+      title: "Apple Sign In Setup",
+      content: `## Apple Sign In Setup
 
 1. Create a Sign In with Apple service at https://developer.apple.com
 2. Configure your Service ID and return URLs
@@ -2093,145 +1813,712 @@ async function replacePlaceholder(filePath, placeholder, content, options) {
       updatedLines.push(line);
     }
   }
-  await fs4.writeFile(filePath, updatedLines.join("\n"), "utf-8");
-}
-function generateCredentialsValue(enabled) {
-  return `credentials={${enabled}}`;
-}
-function generateAuthProvidersBlock(oauthProviders, emailPasswordEnabled) {
-  const parts = [];
-  parts.push(`emailAndPassword: {
-      enabled: ${emailPasswordEnabled}
-    },`);
-  if (oauthProviders.length > 0) {
-    const providersObject = oauthProviders.map((providerId) => {
-      const provider = getProvider(providerId);
-      if (!provider) {
-        throw new Error(`Unknown OAuth provider: ${providerId}`);
-      }
-      const configLines = [
-        `clientId: process.env.${provider.envPrefix}_CLIENT_ID!,`,
-        `clientSecret: process.env.${provider.envPrefix}_CLIENT_SECRET!,`
-      ];
-      if (providerId === "figma") {
-        configLines.push(`clientKey: process.env.FIGMA_CLIENT_KEY!,`);
+  await fs4.writeFile(filePath, updatedLines.join("\n"), "utf-8");
+}
+function generateCredentialsValue(enabled) {
+  return `credentials={${enabled}}`;
+}
+function generateAuthProvidersBlock(oauthProviders, emailPasswordEnabled) {
+  const parts = [];
+  parts.push(`emailAndPassword: {
+      enabled: ${emailPasswordEnabled}
+    },`);
+  if (oauthProviders.length > 0) {
+    const providersObject = oauthProviders.map((providerId) => {
+      const provider = getProvider(providerId);
+      if (!provider) {
+        throw new Error(`Unknown OAuth provider: ${providerId}`);
+      }
+      const configLines = [
+        `clientId: process.env.${provider.envPrefix}_CLIENT_ID!,`,
+        `clientSecret: process.env.${provider.envPrefix}_CLIENT_SECRET!,`
+      ];
+      if (providerId === "figma") {
+        configLines.push(`clientKey: process.env.FIGMA_CLIENT_KEY!,`);
+      }
+      return `${providerId}: {
+        ${configLines.join("\n        ")}
+      }`;
+    }).join(",\n      ");
+    parts.push(`socialProviders: {
+      ${providersObject}
+    },`);
+  }
+  return parts.join("\n    ");
+}
+function generateEnvTsServerSchema(providers) {
+  if (providers.length === 0) {
+    return "";
+  }
+  const schemas = providers.map((providerId) => {
+    const provider = getProvider(providerId);
+    if (!provider) {
+      throw new Error(`Unknown OAuth provider: ${providerId}`);
+    }
+    const lines = [];
+    lines.push(`${provider.envPrefix}_CLIENT_ID: z.string(),`);
+    lines.push(`${provider.envPrefix}_CLIENT_SECRET: z.string(),`);
+    if (providerId === "figma") {
+      lines.push(`FIGMA_CLIENT_KEY: z.string(),`);
+    }
+    return lines.join("\n    ");
+  }).join("\n    ");
+  return schemas;
+}
+function generateEnvTsRuntimeMapping(providers) {
+  if (providers.length === 0) {
+    return "";
+  }
+  const mappings = providers.map((providerId) => {
+    const provider = getProvider(providerId);
+    if (!provider) {
+      throw new Error(`Unknown OAuth provider: ${providerId}`);
+    }
+    const lines = [];
+    lines.push(`${provider.envPrefix}_CLIENT_ID: process.env.${provider.envPrefix}_CLIENT_ID,`);
+    lines.push(`${provider.envPrefix}_CLIENT_SECRET: process.env.${provider.envPrefix}_CLIENT_SECRET,`);
+    if (providerId === "figma") {
+      lines.push(`FIGMA_CLIENT_KEY: process.env.FIGMA_CLIENT_KEY,`);
+    }
+    return lines.join("\n    ");
+  }).join("\n    ");
+  return mappings;
+}
+function generateOAuthUIProvidersBlock(providers) {
+  if (providers.length === 0) {
+    return "";
+  }
+  const providerList = providers.map((id) => `"${id}"`).join(", ");
+  return `social={{
+  providers: [${providerList}]
+}}`;
+}
+function generateEnvVarsBlock(providers, framework) {
+  if (providers.length === 0) {
+    return "";
+  }
+  const envVars = providers.flatMap((providerId) => {
+    const provider = getProvider(providerId);
+    if (!provider) {
+      throw new Error(`Unknown OAuth provider: ${providerId}`);
+    }
+    if (provider.env && provider.env.length > 0) {
+      return provider.env.map((envVar) => {
+        let prefix = "";
+        if (envVar.type === "client") {
+          prefix = framework === "nextjs" ? "NEXT_PUBLIC_" : "VITE_";
+        }
+        return `# ${envVar.description}
+${prefix}${envVar.name}=`;
+      });
+    } else {
+      return [
+        `${provider.clientIdVar}=`,
+        `${provider.clientSecretVar}=`
+      ];
+    }
+  });
+  return envVars.join("\n");
+}
+function generateReadmeSection(providers) {
+  if (providers.length === 0) {
+    return "";
+  }
+  const sections = providers.map((providerId) => {
+    const provider = getProvider(providerId);
+    if (!provider) {
+      throw new Error(`Unknown OAuth provider: ${providerId}`);
+    }
+    if (!provider.readme) {
+      throw new Error(
+        `Provider ${providerId} missing readme metadata`
+      );
+    }
+    return provider.readme.content;
+  }).filter(Boolean);
+  if (sections.length === 0) {
+    return "";
+  }
+  return `# OAuth Provider Setup
+
+${sections.join("\n\n---\n\n")}`;
+}
+function assertAndReplace(filePath, content, oldBlock, newBlock, label) {
+  if (!content.includes(oldBlock)) {
+    throw new Error(
+      `configureOrganizations: expected pattern "${label}" not found in ${filePath} \u2014 template drift?`
+    );
+  }
+  return content.replace(oldBlock, newBlock);
+}
+function stripOrgFromGetAuthCall(filePath, content) {
+  const importPattern = /import \{ TABLE_SLUG_ORGANIZATIONS, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS \} from "~\/db\/constants";?/;
+  const importMatch = content.match(importPattern);
+  if (!importMatch) {
+    throw new Error(
+      `configureOrganizations: expected the TABLE_SLUG_ORGANIZATIONS db/constants import in ${filePath} \u2014 template drift?`
+    );
+  }
+  let result = assertAndReplace(
+    filePath,
+    content,
+    importMatch[0],
+    importMatch[0].replace("TABLE_SLUG_ORGANIZATIONS, ", ""),
+    "TABLE_SLUG_ORGANIZATIONS db/constants import"
+  );
+  const orgPropPattern = /\n[ \t]*orgCollectionSlug: TABLE_SLUG_ORGANIZATIONS,/;
+  const orgPropMatch = result.match(orgPropPattern);
+  if (!orgPropMatch) {
+    throw new Error(
+      `configureOrganizations: expected an "orgCollectionSlug: TABLE_SLUG_ORGANIZATIONS," line in ${filePath} \u2014 template drift?`
+    );
+  }
+  result = assertAndReplace(filePath, result, orgPropMatch[0], "", "orgCollectionSlug prop");
+  result = assertAndReplace(
+    filePath,
+    result,
+    "resolveOrgs: true,",
+    "resolveOrgs: false,",
+    "resolveOrgs: true"
+  );
+  return result;
+}
+function stripOrgFromAuthApi(filePath, content) {
+  let result = assertAndReplace(
+    filePath,
+    content,
+    'import { get } from "@vexcms/core/server";\nimport { v } from "convex/values";\n\nimport {\n  type OrganizationID,\n  type SessionID,\n  TABLE_SLUG_ORGANIZATIONS,\n  TABLE_SLUG_SESSIONS,\n  TABLE_SLUG_USERS,\n  type UserID,\n} from "~/db/constants";',
+    'import { get } from "@vexcms/core/server";\n\nimport { type SessionID, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS, type UserID } from "~/db/constants";',
+    "auth/api.ts imports"
+  );
+  result = assertAndReplace(
+    filePath,
+    result,
+    "export const getUserOrg = query({\n  args: {\n    noOrgs: v.optional(v.boolean()),\n  },\n  handler: async (ctx, args) => {\n    const empty = { user: null, organization: undefined };\n    const identity = await ctx.auth.getUserIdentity();\n    if (!identity) {\n      return empty;\n    }\n    const session = await get({\n      ctx,\n      id: identity.sessionId as SessionID,\n      collection: TABLE_SLUG_SESSIONS,\n    });\n    if (!session) {\n      return empty;\n    }\n    const user = await get({ ctx, id: identity.subject as UserID, collection: TABLE_SLUG_USERS });\n    if (!user) {\n      return empty;\n    }\n    if (!session.activeOrganizationId || args.noOrgs) {\n      return { user, organization: undefined };\n    }\n    const organization = await get({\n      ctx,\n      id: session.activeOrganizationId as OrganizationID,\n      collection: TABLE_SLUG_ORGANIZATIONS,\n    });\n    return { user, organization: organization ?? undefined };\n  },\n});",
+    "export const getUserOrg = query({\n  args: {},\n  handler: async (ctx) => {\n    const empty = { user: null, organization: undefined };\n    const identity = await ctx.auth.getUserIdentity();\n    if (!identity) {\n      return empty;\n    }\n    const session = await get({\n      ctx,\n      id: identity.sessionId as SessionID,\n      collection: TABLE_SLUG_SESSIONS,\n    });\n    if (!session) {\n      return empty;\n    }\n    const user = await get({ ctx, id: identity.subject as UserID, collection: TABLE_SLUG_USERS });\n    if (!user) {\n      return empty;\n    }\n    return { user, organization: undefined };\n  },\n});",
+    "auth/api.ts getUserOrg body"
+  );
+  return result;
+}
+function stripOrgFromAccess(filePath, content) {
+  let result = assertAndReplace(
+    filePath,
+    content,
+    'import {\n  TABLE_SLUG_ORGANIZATIONS,\n  TABLE_SLUG_USERS,\n  USER_ROLES,\n} from "~/db/constants"',
+    'import { TABLE_SLUG_USERS, USER_ROLES } from "~/db/constants"',
+    "access.ts db/constants import"
+  );
+  result = assertAndReplace(
+    filePath,
+    result,
+    "\n  orgCollectionSlug: TABLE_SLUG_ORGANIZATIONS,",
+    "",
+    "access.ts orgCollectionSlug prop"
+  );
+  return result;
+}
+function stripOrgFromAuthContext(filePath, content) {
+  let result = assertAndReplace(
+    filePath,
+    content,
+    'import { type OrganizationDoc, type UserDoc } from "~/db/constants";',
+    'import { type UserDoc } from "~/db/constants";',
+    "AuthContext.tsx db/constants import"
+  );
+  result = assertAndReplace(
+    filePath,
+    result,
+    "export interface CurrentAuth {\n  organization?: OrganizationDoc;\n  user: null | UserDoc; // null \u2192 unauthenticated \u2192 no roles \u2192 deny\n}",
+    "export interface CurrentAuth {\n  user: null | UserDoc; // null \u2192 unauthenticated \u2192 no roles \u2192 deny\n}",
+    "AuthContext.tsx CurrentAuth interface"
+  );
+  result = assertAndReplace(
+    filePath,
+    result,
+    "  value: {\n    organization?: OrganizationDoc;\n    user: null | UserDoc; // null \u2192 unauthenticated \u2192 no roles \u2192 deny\n  };",
+    "  value: {\n    user: null | UserDoc; // null \u2192 unauthenticated \u2192 no roles \u2192 deny\n  };",
+    "AuthContext.tsx AuthProvider value prop"
+  );
+  result = assertAndReplace(
+    filePath,
+    result,
+    "/** @returns the current caller `{ user, organization }` from the server layout. */",
+    "/** @returns the current caller `{ user }` from the server layout. */",
+    "AuthContext.tsx useAuth JSDoc"
+  );
+  return result;
+}
+function stripOrgFromHasPermission(filePath, content) {
+  return assertAndReplace(
+    filePath,
+    content,
+    "  const { user, organization } = useAuth();\n  return hasPermissionCore({\n    access,\n    user,\n    organization,\n    ...props,\n  });",
+    "  const { user } = useAuth();\n  return hasPermissionCore({\n    access,\n    user,\n    ...props,\n  });",
+    "hasPermission.ts useAuth destructure + hasPermissionCore call"
+  );
+}
+function stripOrgFromDbConstants(filePath, content) {
+  return assertAndReplace(
+    filePath,
+    content,
+    '\nexport const TABLE_SLUG_ORGANIZATIONS = "organization" as const\nexport type OrganizationDoc = Doc<typeof TABLE_SLUG_ORGANIZATIONS>\nexport type OrganizationID = Id<typeof TABLE_SLUG_ORGANIZATIONS>\n',
+    "",
+    "db/constants/index.ts organization table block"
+  );
+}
+
+// src/installers/base.ts
+var VexFrameworkInstaller = class {
+  /**
+   * Binds this installer to the destination directory and package name used
+   * throughout scaffolding (template copy target, package.json, README, etc).
+   *
+   * @param targetPath - Absolute path of the directory the project is created in.
+   * @param projectName - npm package name recorded for subclasses; not read directly by the base class.
+   */
+  constructor(targetPath, projectName) {
+    this.targetPath = targetPath;
+    this.projectName = projectName;
+  }
+  targetPath;
+  projectName;
+  /**
+   * Copy base template files to target directory
+   */
+  async copyBaseFiles() {
+    await copyTemplate(this.frameworkName, this.targetPath);
+  }
+  /**
+   * Apply a template overlay on top of the base template.
+   * Merges overlay files onto the already-copied base — existing files
+   * not in the overlay are left untouched.
+   *
+   * @param overlay - Name of the overlay template directory under `templates/` (e.g. `"marketing-site"`).
+   */
+  async applyTemplateOverlay(overlay) {
+    const { dirname: dirname2 } = await import("path");
+    const { fileURLToPath: fileURLToPath2 } = await import("url");
+    const __filename = fileURLToPath2(import.meta.url);
+    const __dirname = dirname2(__filename);
+    let overlayDir = path2.join(__dirname, "../../templates", overlay);
+    if (!await fs5.pathExists(overlayDir)) {
+      overlayDir = path2.join(__dirname, "../templates", overlay);
+    }
+    await overlayTemplate({ overlayDir, targetDir: this.targetPath });
+  }
+  /**
+   * Update the package.json name field, the vex:update script (to match the
+   * detected package manager), and README.md's `{{PROJECT_NAME}}` heading.
+   *
+   * @param name - npm package name to write into `package.json`'s `name` field
+   *   and to substitute for `{{PROJECT_NAME}}` in `README.md`.
+   */
+  async updatePackageName(name) {
+    const pkgPath = path2.join(this.targetPath, "package.json");
+    const pkg = await fs5.readJson(pkgPath);
+    pkg.name = name;
+    const pm = this.detectPackageManager();
+    if (pkg.scripts?.["vex:update"] && pm !== "pnpm") {
+      const addCmd = pm === "yarn" ? "yarn add" : pm === "bun" ? "bun add" : "npm install";
+      pkg.scripts["vex:update"] = pkg.scripts["vex:update"].replace(/^pnpm add/, addCmd);
+    }
+    await fs5.writeJson(pkgPath, pkg, { spaces: 2 });
+    const readmePath = path2.join(this.targetPath, "README.md");
+    if (await fs5.pathExists(readmePath)) {
+      const readme = await fs5.readFile(readmePath, "utf-8");
+      await fs5.writeFile(readmePath, readme.replace("{{PROJECT_NAME}}", name));
+    }
+  }
+  /**
+   * Configure the dev server port.
+   * Updates package.json dev script and creates .env.local with NEXT_PUBLIC_SITE_URL.
+   *
+   * @param port - Dev server port number to write into the `dev` script and `.env.local`.
+   */
+  async configurePort(port) {
+    const pkgPath = path2.join(this.targetPath, "package.json");
+    const pkg = await fs5.readJson(pkgPath);
+    if (pkg.scripts?.dev) {
+      if (pkg.scripts.dev.includes("--port")) {
+        pkg.scripts.dev = pkg.scripts.dev.replace(/--port[= ]\d+/, `--port=${port}`);
+      } else {
+        pkg.scripts.dev = `${pkg.scripts.dev} --port=${port}`;
+      }
+    }
+    await fs5.writeJson(pkgPath, pkg, { spaces: 2 });
+    const siteUrl = `http://localhost:${port}`;
+    const envLocalPath = path2.join(this.targetPath, ".env.local");
+    const envContent = [
+      `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
+      `SITE_URL=${siteUrl}`,
+      `BETTER_AUTH_SECRET=${this.generateAuthSecret()}`,
+      `NEXT_PUBLIC_CONVEX_URL=https://placeholder.convex.cloud`,
+      `NEXT_PUBLIC_CONVEX_SITE_URL=https://placeholder.convex.site`,
+      `CONVEX_DEPLOYMENT=`,
+      ""
+    ].join("\n");
+    await fs5.writeFile(envLocalPath, envContent);
+  }
+  /**
+   * Rewrites the scaffolded `package.json` for life inside a host pnpm
+   * workspace (`--monorepo`). `@vexcms/*` dependencies become
+   * `workspace:*`; any other dependency the host's `pnpm-workspace.yaml`
+   * catalog also pins becomes `catalog:`; everything else keeps its
+   * literal, catalog-resolved version. No-op when `options.monorepo` is
+   * false or `options.workspaceRoot` is unset.
+   *
+   * @param options - Resolved project options; only `monorepo`/`workspaceRoot` are consulted.
+   */
+  async applyMonorepoRewrite(options) {
+    if (!options.monorepo || !options.workspaceRoot) return;
+    const pkgPath = path2.join(this.targetPath, "package.json");
+    const manifest = await fs5.readJson(pkgPath);
+    const catalog = await readWorkspaceCatalog({ workspaceRoot: options.workspaceRoot });
+    const rewritten = rewriteManifestForMonorepo({ manifest, catalog });
+    await fs5.writeJson(pkgPath, rewritten, { spaces: 2 });
+  }
+  /**
+   * Detect the package manager used to invoke the CLI
+   *
+   * @returns The package manager inferred from `npm_config_user_agent`, defaulting to `"npm"` when it can't be determined.
+   */
+  detectPackageManager() {
+    const userAgent = process.env.npm_config_user_agent;
+    if (userAgent) {
+      if (userAgent.includes("pnpm")) return "pnpm";
+      if (userAgent.includes("yarn")) return "yarn";
+      if (userAgent.includes("bun")) return "bun";
+    }
+    return "npm";
+  }
+  /**
+   * Install project dependencies using detected package manager
+   */
+  async installDependencies() {
+    const packageManager = this.detectPackageManager();
+    const spinner = ora(`Installing dependencies with ${packageManager}...`).start();
+    try {
+      await execa(packageManager, ["install"], {
+        cwd: this.targetPath,
+        stdio: "pipe"
+      });
+      spinner.succeed("Dependencies installed successfully");
+    } catch (error) {
+      spinner.fail("Failed to install dependencies");
+      throw new Error(
+        `Dependency installation failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Format code using project's formatter
+   */
+  async formatCode() {
+    const packageManager = this.detectPackageManager();
+    const spinner = ora("Formatting code...").start();
+    try {
+      const result = await execa(packageManager, ["run", "format"], {
+        cwd: this.targetPath,
+        stdio: "pipe",
+        reject: false
+      });
+      if (result.exitCode === 0) {
+        spinner.succeed("Code formatted successfully");
+      } else {
+        spinner.warn("Formatting completed with warnings");
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      spinner.warn(`Failed to format code: ${errorMessage}`);
+    }
+  }
+  /**
+   * Lint and fix code using project's ESLint configuration
+   */
+  async lintCode() {
+    const packageManager = this.detectPackageManager();
+    const spinner = ora("Linting and fixing code...").start();
+    try {
+      const args2 = packageManager === "pnpm" ? ["lint", "--fix"] : ["run", "lint", "--", "--fix"];
+      const result = await execa(packageManager, args2, {
+        cwd: this.targetPath,
+        stdio: "pipe",
+        reject: false
+      });
+      if (result.exitCode === 0) {
+        spinner.succeed("Code linted and fixed successfully");
+      } else {
+        spinner.warn("Linting completed with warnings");
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      spinner.warn(`Failed to lint code: ${errorMessage}`);
+    }
+  }
+  /**
+   * Initialize Git repository in target directory
+   */
+  async initGitRepo() {
+    const spinner = ora("Initializing Git repository...").start();
+    try {
+      try {
+        await execa("git", ["--version"], { stdio: "pipe" });
+      } catch {
+        spinner.fail("Git is not installed");
+        throw new Error("Git is not installed. Please install Git to initialize a repository.");
+      }
+      await execa("git", ["init"], { cwd: this.targetPath, stdio: "pipe" });
+      await execa("git", ["add", "."], { cwd: this.targetPath, stdio: "pipe" });
+      await execa(
+        "git",
+        ["commit", "-m", "Initial commit from create-vexcms"],
+        { cwd: this.targetPath, stdio: "pipe" }
+      );
+      spinner.succeed("Git repository initialized");
+    } catch (error) {
+      spinner.fail("Failed to initialize Git repository");
+      throw new Error(
+        `Git initialization failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Generate a secure random secret for Better Auth
+   *
+   * @returns A 64-character hex string (32 random bytes) suitable for `BETTER_AUTH_SECRET`.
+   */
+  generateAuthSecret() {
+    return crypto.randomBytes(32).toString("hex");
+  }
+  /**
+   * Write the generated auth secret to .env.example
+   */
+  async writeAuthSecret() {
+    const envPath = path2.join(this.targetPath, ".env.example");
+    const secret = this.generateAuthSecret();
+    if (await fs5.pathExists(envPath)) {
+      let content = await fs5.readFile(envPath, "utf-8");
+      content = content.replace(
+        /BETTER_AUTH_SECRET=.*/,
+        `BETTER_AUTH_SECRET=${secret}`
+      );
+      await fs5.writeFile(envPath, content);
+    }
+  }
+  /**
+   * Configure the Better Auth organizations plugin.
+   * When enabled, replaces placeholders with organization import and plugin,
+   * and leaves every org-aware file (`createGetAuth` call sites, `access.ts`,
+   * `AuthContext.tsx`, `hasPermission.ts`, `convex/auth/api.ts`,
+   * `db/constants/index.ts`) untouched.
+   * When disabled, removes the placeholder lines AND strips organization
+   * wiring from those same files down to the org-free shape — the
+   * templates ship org-enabled by default (so `--orgs` needs no surgery),
+   * so the default (orgs-declined) path has to actively cut it.
+   *
+   * @param enabled - Whether the organizations (multi-tenant) plugin should stay wired.
+   */
+  async configureOrganizations(enabled) {
+    const pluginsPath = path2.join(this.targetPath, "convex/auth/plugins/index.ts");
+    if (await fs5.pathExists(pluginsPath)) {
+      let content = await fs5.readFile(pluginsPath, "utf-8");
+      if (enabled) {
+        content = content.replace(
+          "// {{ORGANIZATIONS_IMPORT}}",
+          'import { organization } from "better-auth/plugins"'
+        );
+        content = content.replace(
+          "  // {{ORGANIZATIONS_PLUGIN}}",
+          "  organization(),"
+        );
+      } else {
+        content = content.replace(/.*\/\/ \{\{ORGANIZATIONS_IMPORT\}\}\n?/, "");
+        content = content.replace(/.*\/\/ \{\{ORGANIZATIONS_PLUGIN\}\}\n?/, "");
       }
-      return `${providerId}: {
-        ${configLines.join("\n        ")}
-      }`;
-    }).join(",\n      ");
-    parts.push(`socialProviders: {
-      ${providersObject}
-    },`);
-  }
-  return parts.join("\n    ");
-}
-function generateEnvTsServerSchema(providers) {
-  if (providers.length === 0) {
-    return "";
-  }
-  const schemas = providers.map((providerId) => {
-    const provider = getProvider(providerId);
-    if (!provider) {
-      throw new Error(`Unknown OAuth provider: ${providerId}`);
+      await fs5.writeFile(pluginsPath, content);
     }
-    const lines = [];
-    lines.push(`${provider.envPrefix}_CLIENT_ID: z.string(),`);
-    lines.push(`${provider.envPrefix}_CLIENT_SECRET: z.string(),`);
-    if (providerId === "figma") {
-      lines.push(`FIGMA_CLIENT_KEY: z.string(),`);
+    if (!enabled) {
+      await this.stripOrganizationWiring();
     }
-    return lines.join("\n    ");
-  }).join("\n    ");
-  return schemas;
-}
-function generateEnvTsRuntimeMapping(providers) {
-  if (providers.length === 0) {
-    return "";
   }
-  const mappings = providers.map((providerId) => {
-    const provider = getProvider(providerId);
-    if (!provider) {
-      throw new Error(`Unknown OAuth provider: ${providerId}`);
+  /**
+   * Rewrites every scaffolded file that references organizations down to
+   * its org-free shape. Called by `configureOrganizations(false)` — the
+   * `--orgs`-declined default. Templates ship org-ENABLED (so `--orgs`
+   * requires no surgery); this is what makes the default scaffold buildable
+   * once the generated registry drops org tables on the first `vex dev`
+   * regen. Every transform throws loudly when its expected pattern is
+   * missing (template drift), rather than silently no-opping.
+   *
+   * `src/vexcms/api.ts` only exists in full (marketing-site overlay)
+   * scaffolds — skipped, not required, for `--bare`.
+   */
+  async stripOrganizationWiring() {
+    const requiredFiles = [
+      { rel: "convex/vex.ts", transform: stripOrgFromGetAuthCall },
+      { rel: "convex/vex/globals.ts", transform: stripOrgFromGetAuthCall },
+      { rel: "convex/vex/media.ts", transform: stripOrgFromGetAuthCall },
+      { rel: "convex/auth/api.ts", transform: stripOrgFromAuthApi },
+      { rel: "src/auth/access.ts", transform: stripOrgFromAccess },
+      { rel: "src/context/AuthContext.tsx", transform: stripOrgFromAuthContext },
+      { rel: "src/auth/hasPermission.ts", transform: stripOrgFromHasPermission },
+      { rel: "src/db/constants/index.ts", transform: stripOrgFromDbConstants }
+    ];
+    for (const file of requiredFiles) {
+      const filePath = path2.join(this.targetPath, file.rel);
+      if (!await fs5.pathExists(filePath)) {
+        throw new Error(
+          `configureOrganizations: required file "${file.rel}" is missing from the scaffold \u2014 template drift?`
+        );
+      }
+      const content = await fs5.readFile(filePath, "utf-8");
+      await fs5.writeFile(filePath, file.transform(filePath, content));
     }
-    const lines = [];
-    lines.push(`${provider.envPrefix}_CLIENT_ID: process.env.${provider.envPrefix}_CLIENT_ID,`);
-    lines.push(`${provider.envPrefix}_CLIENT_SECRET: process.env.${provider.envPrefix}_CLIENT_SECRET,`);
-    if (providerId === "figma") {
-      lines.push(`FIGMA_CLIENT_KEY: process.env.FIGMA_CLIENT_KEY,`);
+    const apiPath = path2.join(this.targetPath, "src/vexcms/api.ts");
+    if (await fs5.pathExists(apiPath)) {
+      const content = await fs5.readFile(apiPath, "utf-8");
+      await fs5.writeFile(apiPath, stripOrgFromGetAuthCall(apiPath, content));
     }
-    return lines.join("\n    ");
-  }).join("\n    ");
-  return mappings;
-}
-function generateOAuthUIProvidersBlock(providers) {
-  if (providers.length === 0) {
-    return "";
-  }
-  const providerList = providers.map((id) => `"${id}"`).join(", ");
-  return `social={{
-  providers: [${providerList}]
-}}`;
-}
-function generateEnvVarsBlock(providers, framework) {
-  if (providers.length === 0) {
-    return "";
   }
-  const envVars = providers.flatMap((providerId) => {
-    const provider = getProvider(providerId);
-    if (!provider) {
-      throw new Error(`Unknown OAuth provider: ${providerId}`);
+  /**
+   * Main orchestration method for project initialization
+   *
+   * @param options - Resolved project options from CLI flags and prompts, driving every scaffolding step (template copy, overlay, port, auth, README, git, install).
+   */
+  async initProject(options) {
+    const copySpinner = ora("Copying template files...").start();
+    try {
+      await this.copyBaseFiles();
+      copySpinner.succeed("Template files copied");
+    } catch (error) {
+      copySpinner.fail("Failed to copy template files");
+      throw error;
     }
-    if (provider.env && provider.env.length > 0) {
-      return provider.env.map((envVar) => {
-        let prefix = "";
-        if (envVar.type === "client") {
-          prefix = framework === "nextjs" ? "NEXT_PUBLIC_" : "VITE_";
-        }
-        return `# ${envVar.description}
-${prefix}${envVar.name}=`;
-      });
-    } else {
-      return [
-        `${provider.clientIdVar}=`,
-        `${provider.clientSecretVar}=`
-      ];
+    if (!options.bare) {
+      const overlaySpinner = ora("Applying marketing site template...").start();
+      try {
+        await this.applyTemplateOverlay("marketing-site");
+        overlaySpinner.succeed("Marketing site template applied");
+      } catch (error) {
+        overlaySpinner.fail("Failed to apply template overlay");
+        throw error;
+      }
     }
-  });
-  return envVars.join("\n");
-}
-function generateReadmeSection(providers) {
-  if (providers.length === 0) {
-    return "";
-  }
-  const sections = providers.map((providerId) => {
-    const provider = getProvider(providerId);
-    if (!provider) {
-      throw new Error(`Unknown OAuth provider: ${providerId}`);
+    const nameSpinner = ora("Configuring project...").start();
+    try {
+      await this.updatePackageName(options.projectName);
+      await this.configurePort(options.port);
+      nameSpinner.succeed("Project configured");
+    } catch (error) {
+      nameSpinner.fail("Failed to configure project");
+      throw error;
     }
-    if (!provider.readme) {
-      throw new Error(
-        `Provider ${providerId} missing readme metadata`
+    const authSpinner = ora("Configuring authentication...").start();
+    try {
+      await this.updateOAuthConfig(options.oauthProviders, options.emailPasswordAuth);
+      authSpinner.succeed(
+        options.emailPasswordAuth || options.oauthProviders.length > 0 ? "Authentication configuration updated" : "Authentication placeholders cleaned up"
       );
+    } catch (error) {
+      authSpinner.fail("Failed to configure authentication");
+      throw error;
+    }
+    const oauthUISpinner = ora("Configuring OAuth UI...").start();
+    try {
+      await this.updateOAuthUIConfig(options.oauthProviders, options.emailPasswordAuth);
+      oauthUISpinner.succeed(
+        options.oauthProviders.length > 0 ? "OAuth UI configuration updated" : "OAuth UI placeholders cleaned up"
+      );
+    } catch (error) {
+      oauthUISpinner.fail("Failed to configure OAuth UI");
+      throw error;
+    }
+    const envSpinner = ora("Updating .env.example...").start();
+    try {
+      await this.updateEnvExample(options.oauthProviders);
+      envSpinner.succeed(
+        options.oauthProviders.length > 0 ? ".env.example updated" : ".env.example placeholders cleaned up"
+      );
+    } catch (error) {
+      envSpinner.fail("Failed to update .env.example");
+      throw error;
+    }
+    const envTsSpinner = ora("Updating typed env configuration...").start();
+    try {
+      await this.updateEnvTs(options.oauthProviders);
+      envTsSpinner.succeed(
+        options.oauthProviders.length > 0 ? "Typed env configuration updated" : "Typed env placeholders cleaned up"
+      );
+    } catch (error) {
+      envTsSpinner.fail("Failed to update typed env configuration");
+      throw error;
+    }
+    const readmeSpinner = ora("Updating README...").start();
+    try {
+      await this.updateReadme(options.oauthProviders);
+      readmeSpinner.succeed(
+        options.oauthProviders.length > 0 ? "README updated" : "README placeholders cleaned up"
+      );
+    } catch (error) {
+      readmeSpinner.fail("Failed to update README");
+      throw error;
+    }
+    const orgsSpinner = ora("Configuring organizations...").start();
+    try {
+      await this.configureOrganizations(options.orgs);
+      orgsSpinner.succeed(
+        options.orgs ? "Organizations plugin enabled" : "Organizations placeholders cleaned up"
+      );
+    } catch (error) {
+      orgsSpinner.fail("Failed to configure organizations");
+      throw error;
+    }
+    const secretSpinner = ora("Generating auth secret...").start();
+    try {
+      await this.writeAuthSecret();
+      secretSpinner.succeed("Auth secret generated");
+    } catch (error) {
+      secretSpinner.fail("Failed to generate auth secret");
+      throw error;
+    }
+    if (options.monorepo) {
+      const monorepoSpinner = ora("Rewriting dependencies for the host workspace...").start();
+      try {
+        await this.applyMonorepoRewrite(options);
+        monorepoSpinner.succeed("Dependencies rewritten for the host workspace");
+      } catch (error) {
+        monorepoSpinner.fail("Failed to rewrite dependencies for the host workspace");
+        throw error;
+      }
+    }
+    if (options.initGit && !options.monorepo) {
+      await this.initGitRepo();
+    }
+    if (options.installDependencies && !options.monorepo) {
+      await this.installDependencies();
+      await this.lintCode();
+      await this.formatCode();
     }
-    return provider.readme.content;
-  }).filter(Boolean);
-  if (sections.length === 0) {
-    return "";
   }
-  return `# OAuth Provider Setup
-
-${sections.join("\n\n---\n\n")}`;
-}
+};
 
 // src/installers/nextjs.ts
+import { join as join2 } from "path";
 var VexNextJSInstaller = class extends VexFrameworkInstaller {
+  /**
+   * Framework identifier used for template selection and logging.
+   *
+   * @returns The literal string `"nextjs"`.
+   */
   get frameworkName() {
     return "nextjs";
   }
   /**
    * Update OAuth configuration in Convex auth options file
    * Target file: convex/auth/options.ts
+   *
+   * @param selectedProviders - IDs of the OAuth providers chosen for the project (e.g. `["google", "github"]`).
+   * @param emailPasswordEnabled - Whether email/password authentication is also enabled.
    */
   async updateOAuthConfig(selectedProviders, emailPasswordEnabled) {
     const authFilePath = join2(this.targetPath, "convex/auth/options.ts");
@@ -2254,6 +2541,9 @@ var VexNextJSInstaller = class extends VexFrameworkInstaller {
   /**
    * Update OAuth UI configuration in auth client file
    * Target file: src/auth/client.tsx
+   *
+   * @param selectedProviders - IDs of the OAuth providers chosen for the project (e.g. `["google", "github"]`).
+   * @param emailPasswordEnabled - Whether email/password authentication is also enabled.
    */
   async updateOAuthUIConfig(selectedProviders, emailPasswordEnabled) {
     const providersFilePath = join2(this.targetPath, "src/auth/client.tsx");
@@ -2273,6 +2563,8 @@ var VexNextJSInstaller = class extends VexFrameworkInstaller {
   /**
    * Update .env.example with OAuth environment variables
    * Target file: .env.example
+   *
+   * @param selectedProviders - IDs of the OAuth providers chosen for the project (e.g. `["google", "github"]`).
    */
   async updateEnvExample(selectedProviders) {
     const envFilePath = join2(this.targetPath, ".env.example");
@@ -2286,6 +2578,8 @@ var VexNextJSInstaller = class extends VexFrameworkInstaller {
   /**
    * Update README with OAuth provider setup guides
    * Target file: README.md
+   *
+   * @param selectedProviders - IDs of the OAuth providers chosen for the project (e.g. `["google", "github"]`).
    */
   async updateReadme(selectedProviders) {
     const readmeFilePath = join2(this.targetPath, "README.md");
@@ -2300,6 +2594,8 @@ var VexNextJSInstaller = class extends VexFrameworkInstaller {
   /**
    * Update env.mjs with OAuth provider environment variables
    * Target file: src/env.mjs
+   *
+   * @param selectedProviders - IDs of the OAuth providers chosen for the project (e.g. `["google", "github"]`).
    */
   async updateEnvTs(selectedProviders) {
     const envFilePath = join2(this.targetPath, "src/env.mjs");
@@ -2331,7 +2627,7 @@ function createInstaller(props) {
 }
 
 // src/index.ts
-var program = new Command().name("create-vexcms").description("Scaffold a new VEX CMS project").argument("[project-name]", "Project directory name").option("--bare", "Skip marketing site collections, scaffold empty project").option("--orgs", "Enable multi-tenant organizations").version("0.0.2").parse();
+var program = new Command().name("create-vexcms").description("Scaffold a new VEX CMS project").argument("[project-name]", "Project directory name").option("--bare", "Skip marketing site collections, scaffold empty project").option("--orgs", "Enable multi-tenant organizations").option("--monorepo", "Scaffold into apps/<name> under the detected pnpm workspace root, rewriting dependencies to workspace/catalog protocols").option("--yes", "Accept every prompt default without rendering (for automation)").version("0.0.2").parse();
 var args = program.args;
 var opts = program.opts();
 async function main() {
@@ -2339,15 +2635,19 @@ async function main() {
   console.log(chalk2.bold("  create-vexcms"));
   console.log();
   const bare = opts.bare ?? false;
+  const yes = opts.yes ?? false;
+  const monorepo = opts.monorepo ?? false;
   let inputArg;
   if (args[0]) {
     inputArg = args[0];
+  } else if (yes) {
+    inputArg = "my-vexcms-app";
   } else {
     inputArg = await input({
       message: "(1/8) What is your project named?",
       default: "my-vexcms-app",
       validate: (value) => {
-        const name = value.includes("/") ? path2.basename(value) : value;
+        const name = value.includes("/") ? path3.basename(value) : value;
         if (name === ".") return true;
         const result = validateProjectName(name);
         if (result.valid) return true;
@@ -2356,52 +2656,80 @@ async function main() {
     });
   }
   inputArg = resolveProjectName(inputArg, process.cwd());
-  const projectName = inputArg === "." ? path2.basename(process.cwd()) : path2.basename(inputArg);
+  const projectName = inputArg === "." ? path3.basename(process.cwd()) : path3.basename(inputArg);
   const validation = validateProjectName(projectName);
   if (!validation.valid) {
     displayInvalidNameError(projectName, validation.errors);
     process.exit(1);
   }
-  const targetDir = inputArg === "." ? process.cwd() : path2.resolve(process.cwd(), inputArg);
-  if (await checkDirectoryExists(targetDir)) {
-    if (!await isDirectoryEmpty(targetDir)) {
-      displayDirectoryNotEmptyError();
+  let targetDir;
+  let workspaceRoot = null;
+  if (monorepo) {
+    workspaceRoot = await findWorkspaceRoot({ cwd: process.cwd() });
+    if (!workspaceRoot) {
+      console.error(chalk2.red("\nError: --monorepo requires a pnpm workspace."));
+      console.error(chalk2.yellow(`No pnpm-workspace.yaml was found walking up from ${process.cwd()}.`));
+      console.error(chalk2.yellow("Run this command from inside a pnpm workspace, or drop --monorepo."));
       process.exit(1);
     }
+    targetDir = path3.join(workspaceRoot, "apps", projectName);
+    if (await checkDirectoryExists(targetDir)) {
+      console.error(chalk2.red(`
+Error: 'apps/${projectName}' already exists under ${workspaceRoot}.`));
+      console.error(chalk2.yellow("--monorepo refuses to scaffold over an existing directory."));
+      process.exit(1);
+    }
+  } else {
+    targetDir = inputArg === "." ? process.cwd() : path3.resolve(process.cwd(), inputArg);
+    if (await checkDirectoryExists(targetDir)) {
+      if (!await isDirectoryEmpty(targetDir)) {
+        displayDirectoryNotEmptyError();
+        process.exit(1);
+      }
+    }
   }
   let framework;
-  while (true) {
-    framework = await select({
-      message: "(2/8) Select a framework:",
-      choices: [
-        { name: "Next.js (Recommended)", value: "nextjs" },
-        { name: "TanStack Start (Coming Soon)", value: "tanstack" }
-      ]
-    });
-    if (framework === "tanstack") {
-      console.log(chalk2.yellow("\n  TanStack Start support is coming soon! Please select Next.js for now.\n"));
-      continue;
+  if (yes) {
+    framework = "nextjs";
+  } else {
+    while (true) {
+      framework = await select({
+        message: "(2/8) Select a framework:",
+        choices: [
+          { name: "Next.js (Recommended)", value: "nextjs" },
+          { name: "TanStack Start (Coming Soon)", value: "tanstack" }
+        ]
+      });
+      if (framework === "tanstack") {
+        console.log(chalk2.yellow("\n  TanStack Start support is coming soon! Please select Next.js for now.\n"));
+        continue;
+      }
+      break;
     }
-    break;
   }
-  const portInput = await input({
-    message: "(3/8) Dev server port:",
-    default: "3010",
-    validate: (value) => {
-      const num = parseInt(value, 10);
-      if (isNaN(num) || num < 1 || num > 65535) return "Must be a valid port number (1-65535)";
-      return true;
-    }
-  });
-  const port = parseInt(portInput, 10);
-  const emailPasswordAuth = await confirm({
+  let port;
+  if (yes) {
+    port = 3010;
+  } else {
+    const portInput = await input({
+      message: "(3/8) Dev server port:",
+      default: "3010",
+      validate: (value) => {
+        const num = parseInt(value, 10);
+        if (isNaN(num) || num < 1 || num > 65535) return "Must be a valid port number (1-65535)";
+        return true;
+      }
+    });
+    port = parseInt(portInput, 10);
+  }
+  const emailPasswordAuth = yes ? true : await confirm({
     message: "(4/8) Enable email/password authentication?",
     default: true
   });
-  const orgs = opts.orgs ?? await confirm({
+  const orgs = opts.orgs ?? (yes ? false : await confirm({
     message: "(5/8) Enable multi-tenant (organizations)?",
     default: false
-  });
+  }));
   const popularProviders = getPopularProviders();
   const additionalProviders = getAdditionalProviders();
   const allProviderChoices = [
@@ -2415,15 +2743,15 @@ async function main() {
       value: p.id
     }))
   ];
-  const oauthProviders = await checkbox({
+  const oauthProviders = yes ? [] : await checkbox({
     message: "(6/8) Select OAuth providers (space to toggle, enter to confirm):",
     choices: allProviderChoices
   });
-  const initGit = await confirm({
+  const initGit = yes ? true : await confirm({
     message: "(7/8) Initialize a Git repository?",
     default: true
   });
-  const installDependencies = await confirm({
+  const installDependencies = yes ? false : await confirm({
     message: "(8/8) Install dependencies?",
     default: false
   });
@@ -2437,9 +2765,12 @@ async function main() {
     emailPasswordAuth,
     oauthProviders,
     initGit,
-    installDependencies
+    installDependencies,
+    monorepo,
+    workspaceRoot,
+    yes
   };
-  await fs5.ensureDir(targetDir);
+  await fs6.ensureDir(targetDir);
   const installer = createInstaller({
     framework,
     projectDir: targetDir,
@@ -2449,6 +2780,10 @@ async function main() {
   await installer.initProject(options);
   console.log();
   displaySuccessMessage(options.projectName, targetDir, inputArg === ".");
+  if (monorepo && workspaceRoot) {
+    console.log(chalk2.cyan(`  Run 'pnpm install' from ${workspaceRoot} to link the new workspace member.`));
+    console.log();
+  }
 }
 main().catch((error) => {
   console.error(chalk2.red("\nAn error occurred:"), error.message);