climaybe 3.2.0 → 3.4.0

package/README.md

@@ -94,7 +94,11 @@ Switch your local dev environment to a specific store (multi-store only).
 npx climaybe switch voldt-norway
 ```
 
-Copies `stores/<alias>/` JSON files to the repo root so you can preview that store locally, and sets `default_store` in `climaybe.config.json` so `climaybe serve` / `shopify theme dev` targets that store. If your current git branch is `staging-<alias>` or `live-<alias>`, `climaybe serve` uses that store’s domain from config (even if `default_store` differs), matching CI preview behavior.
+Copies `stores/<alias>/` JSON files to the repo root so you can preview that store locally, and sets `default_store` in `climaybe.config.json` so `climaybe serve` / `shopify theme dev` targets that store. If your current git branch is `staging-<alias>` or `live-<alias>`, `climaybe serve` still passes that branch’s store to Shopify for `--store` (even if `default_store` differs), matching CI preview behavior.
+
+### `climaybe serve` / `climaybe theme serve`
+
+Runs Tailwind/scripts/schema watchers and `shopify theme dev` (see the theme dev kit section for flags). In **multi-store** mode, the first step asks **which store to serve** (interactive terminal); the default choice is the store matching `default_store` (same as after `climaybe switch`). If you pick a **different** store, the CLI saves the current root `config/`, `templates/`, and `sections/` JSON files into `stores/<previous-alias>/` (same paths as `climaybe sync`), then copies the selected store’s JSONs to the root and updates `default_store`, so work in progress is not lost. In **CI** or when **stdin is not a TTY**, there is no prompt: it uses `default_store` unless you set **`CLIMAYBE_SERVE_STORE=<alias>`** to a configured alias.
 
 ### `climaybe sync [alias]` / `climaybe theme sync`
 
@@ -227,12 +231,14 @@ Enabled via `climaybe init` prompt (`Enable preview + cleanup workflows?`; defau
 
 | Workflow | Trigger | What it does |
 |----------|---------|-------------|
-| `pr-update.yml` | PR opened/synchronize/reopened (base: main, staging, develop, staging-*, live-*) | Shares draft theme, renames with `-PR<number>`, comments preview + customize URLs; uses default store for main/staging/develop, or the store for staging-&lt;alias&gt;/live-&lt;alias&gt;. **Path filter:** runs only when the PR changes theme paths (`assets/`, `blocks/`, `config/`, `layout/`, `locales/`, `sections/`, `snippets/`, `templates/`, `_scripts/`, `_styles/`, `shopify.theme.toml`, `stores/**`); docs-only or tooling-only PRs skip preview work. |
-| `pr-close.yml` | PR closed (same branch set) | Deletes matching preview themes and comments deleted count + names |
-| `reusable-share-theme.yml` | workflow_call | Shares Shopify draft theme and returns `theme_id` |
-| `reusable-rename-theme.yml` | workflow_call | Renames shared theme to include `PR<number>` (fails job on rename failure) |
-| `reusable-comment-on-pr.yml` | workflow_call | Posts preview comment including Customize URL |
-| `reusable-cleanup-themes.yml` | workflow_call | Deletes preview themes by PR number and exposes cleanup outputs |
+| `pr-update.yml` | PR opened/synchronize/reopened (base: main, staging, develop, staging-*, live-*) | Shares draft theme, renames with `-PR<number>`, comments preview + customize URLs. **Multi-store + base not** `staging-<alias>` **or** `live-<alias>`**:** publishes to **every** configured store (matrix) and posts **all** links in one PR comment. For `staging-<alias>` / `live-<alias>` bases, only that store is used. **Path filter:** theme paths only (`assets/`, `blocks/`, `config/`, `layout/`, `locales/`, `sections/`, `snippets/`, `templates/`, `_scripts/`, `_styles/`, `shopify.theme.toml`, `stores/**`). |
+| `pr-close.yml` | PR closed (same branch set) | Deletes this PR’s preview themes using the **same store matrix rule** as `pr-update`; PR comment shows **total** deleted count across stores. |
+| `cleanup-orphan-preview-themes.yml` | Weekly (Mon 06:00 UTC) + `workflow_dispatch` | Per store: deletes themes ending with `-PR<n>` when PR `#n` is **not** open (merged/closed without cleanup). Uses `gh pr list` (limit 1000 open PRs). |
+| `reusable-publish-pr-preview-store.yml` | workflow_call | Share + rename + upload comment fragment for **one** store (matrix leg in `pr-update`). |
+| `reusable-share-theme.yml` | workflow_call | Shares Shopify draft theme and returns `theme_id` (still available if you call it elsewhere) |
+| `reusable-rename-theme.yml` | workflow_call | Renames shared theme to include `PR<number>` (still available for custom flows) |
+| `reusable-comment-on-pr.yml` | workflow_call | Posts preview comment; aggregates `preview-fragment-*` artifacts when `use_preview_fragments` is true |
+| `reusable-cleanup-themes.yml` | workflow_call | `cleanup_mode: by_pr` deletes names ending with `-PR{padded}`; `orphan_pr` deletes `-PR<n>` when PR `n` is not open. Optional `result_artifact_prefix` for matrix fan-in on `pr-close` |
 | `reusable-extract-pr-number.yml` | workflow_call | Extracts padded/unpadded PR number outputs for naming and API-safe usage |
 
 ### Optional build + Lighthouse package
@@ -244,6 +250,8 @@ When enabled, builds are **resilient**:
 - `init` may offer to create entrypoints; **default answer is No**.
 - Script bundling preserves comments/spacing and emits bundles only for root entry files (files imported by other top-level `_scripts/*.js` are inlined, not emitted separately).
 - Script bundles are written to `assets/*.js` (readable by default; use `climaybe build-scripts --minify` if you want minified output).
+- `assets/*.js`, `assets/style.css`, and the injected `{% schema %}` blocks are **generated outputs** — edit the source in `_scripts/`, `_styles/`, and `_schemas/` instead, since the watcher/build regenerate (and overwrite) the outputs on save and in CI.
+- **Orphan cleanup:** when `_scripts/` is in use, a full build (`climaybe build`, `climaybe build-scripts`, and the `serve` watcher) deletes any `assets/*.js` that no longer has a matching `_scripts/` source. Add new JS via a top-level `_scripts/<name>.js` entry, not by hand-editing `assets/`. Liquid-processed `*.js.liquid` assets and non-JS files are left untouched; targeted single-entry builds (`build-scripts <entry>`) skip pruning.
 - Live minified `assets/*` changes are intentionally excluded from hotfix backports to `main` (no branch-specific `.gitignore` split required).
 
 Build workflows install deps with `npm ci` and run `npx --no-install climaybe build-scripts` plus `npx --no-install climaybe build`, so CI uses lockfile-pinned versions (no `@latest` drift).
@@ -374,7 +382,7 @@ Add the following secrets to your GitHub repository (or use **GitLab CI/CD varia
 
 **Store URL:** During `climaybe init` (or `add-store`), store URL secret(s) are set from your configured store domain(s); theme tokens are optional prompts.
 
-**Multi-store:** Per-store secrets `SHOPIFY_STORE_URL_<ALIAS>` and `SHOPIFY_THEME_ACCESS_TOKEN_<ALIAS>` — the URL is set from config; you must provide the theme token per store. `<ALIAS>` is uppercase with hyphens as underscores (e.g. `voldt-norway` → `SHOPIFY_STORE_URL_VOLDT_NORWAY`). Preview and cleanup: for PRs targeting **main**, **staging**, or **develop** the workflows use the **default store** (from `config.default_store` or first in `config.stores`); for PRs targeting **staging-&lt;alias&gt;** or **live-&lt;alias&gt;** they use that store’s credentials. Set either the plain `SHOPIFY_*` secrets or the `_<ALIAS>` pair for each store you use in preview.
+**Multi-store:** Per-store secrets `SHOPIFY_STORE_URL_<ALIAS>` and `SHOPIFY_THEME_ACCESS_TOKEN_<ALIAS>` — the URL is set from config; you must provide the theme token per store. `<ALIAS>` is uppercase with hyphens as underscores (e.g. `voldt-norway` → `SHOPIFY_STORE_URL_VOLDT_NORWAY`). **Preview:** for PRs targeting **staging-&lt;alias&gt;** or **live-&lt;alias&gt;** only that store is used. For **main**, **staging**, **develop**, or other bases with **multiple** stores in `climaybe.config.json`, **pr-update** publishes the preview theme to **every** store (each must have secrets); **pr-close** cleans that PR’s preview themes on **all** stores. For a **single** store in config, behavior matches the default-store case. Optional **cleanup-orphan-preview-themes** (weekly + manual) removes stale `-PR<n>` themes when PR `n` is no longer open.
 
 ## Directory Structure (Multi-store)
 

package/bin/version.txt

@@ -1 +1 @@
-3.2.0
+3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "climaybe",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Shopify CLI by Electric Maybe for theme CI/CD workflows, branch orchestration, app setup, and dev tooling",
   "type": "module",
   "bin": {

package/src/commands/build-scripts.js

@@ -9,7 +9,7 @@ export async function buildScriptsCommand(opts = {}) {
   try {
     const minify = opts.minify === true;
     if (global.gc) global.gc();
-    const { bundles } = buildScripts({ cwd: process.cwd(), minify });
+    const { bundles, removed } = buildScripts({ cwd: process.cwd(), minify });
     if (!bundles || bundles.length === 0) {
       console.log(pc.yellow('  No _scripts/*.js entrypoints found; nothing to build.'));
       return;
@@ -20,6 +20,12 @@ export async function buildScriptsCommand(opts = {}) {
     for (const b of bundles) {
       console.log(pc.dim(`  - ${b.entryFile} → ${b.outputPath}`));
     }
+    if (removed && removed.length > 0) {
+      console.log(pc.yellow(`  Removed ${removed.length} orphan asset(s) with no _scripts source:`));
+      for (const name of removed) {
+        console.log(pc.dim(`  - assets/${name}`));
+      }
+    }
     if (global.gc) global.gc();
   } catch (err) {
     console.log(pc.red(`  Build error: ${err.message}`));

package/src/cursor/rules/00-rule-index.mdc

@@ -8,6 +8,7 @@ alwaysApply: true
 
 When you perform any of the following, **read and apply** the corresponding rule file from `.cursor/rules/`:
 
+- **Editing `assets/*.js` or `assets/style.css`, build outputs vs source, where to edit JS/CSS** → `project-overview.mdc` (Build Outputs vs Source — edit `_scripts/`/`_styles/`, never the generated `assets/` files)
 - **Git commits, commit messages** → `commit-rules.mdc`
 - **Accessibility, a11y, focus, WCAG, UI behavior** → `accessibility-rules.mdc`
 - **JavaScript, web components, _scripts/, *.js** → `javascript-standards.mdc`

package/src/cursor/rules/javascript-standards.mdc

@@ -1,7 +1,7 @@
 ---
 description: Professional JavaScript standards for Electric Maybe Shopify Theme. All JavaScript files must follow these patterns for consistency, performance, and maintainability.
 globs:
-  - "**/*.js"
+  - "_scripts/**/*.js"
   - "sections/*.liquid"
   - "snippets/*.liquid"
 alwaysApply: false
@@ -9,6 +9,8 @@ alwaysApply: false
 
 # JavaScript Development Standards
 
+> **Source vs build output:** Edit JavaScript in `_scripts/`. The CLI bundles `_scripts/*.js` into `assets/*.js` (`main.js` → `assets/index.js`) on every save and in CI, so `assets/*.js` is a **generated artifact** — never edit it directly, your changes will be overwritten. See `project-overview.mdc` (Build Outputs vs Source).
+
 ## Core Principles
 
 - **Zero external dependencies** - Use native browser APIs

package/src/cursor/rules/js-refactor-tasks.mdc

@@ -1,7 +1,7 @@
 ---
 description: JavaScript component refactor tasks and improvement tracking
 globs:
-  - "**/*.js"
+  - "_scripts/**/*.js"
 alwaysApply: false
 ---
 # JavaScript Component Refactor Tasks

package/src/cursor/rules/project-overview.mdc

@@ -55,8 +55,10 @@ Use `_scripts/electric-modal.js` as the gold standard for all web components.
 
 ## File Organization
 ```
-_scripts/        # Web components and utilities
-assets/          # Compiled CSS/JS and static assets
+_scripts/        # Source: web components and JS utilities (edit here)
+_styles/         # Source: Tailwind/CSS entrypoint (_styles/main.css)
+_schemas/        # Source: section/block schema definitions
+assets/          # GENERATED build outputs + static assets (do not hand-edit generated files)
 sections/        # Liquid section files
 snippets/        # Reusable Liquid snippets
 templates/       # Page templates
@@ -64,6 +66,22 @@ locales/         # Translation files
 config/          # Theme settings
 ```
 
+## Build Outputs vs Source
+
+`assets/` contains both static assets and **generated** build outputs. The CLI (`climaybe serve` / `climaybe build`) compiles sources into `assets/` and regenerates them on every save and in CI. Always edit the **source**, never the generated output:
+
+| Source (edit this) | Generated output (do NOT edit) |
+| --- | --- |
+| `_scripts/main.js` | `assets/index.js` |
+| `_scripts/<name>.js` (top-level entry) | `assets/<name>.js` |
+| `_styles/main.css` | `assets/style.css` |
+| `_schemas/<name>.js` / `.json` | injected `{% schema %}` block in `sections/*.liquid` & `blocks/*.liquid` |
+
+Notes:
+- JS bundling follows `import` statements: files imported by a top-level `_scripts/*.js` entry are **inlined** into that bundle, not emitted separately.
+- Any manual edit to `assets/index.js`, `assets/*.js`, or `assets/style.css` is **overwritten** on the next save (watcher) or build. Make JS changes in `_scripts/`, CSS in `_styles/`, and schema changes in `_schemas/`.
+- **Orphan cleanup:** on a full build (`climaybe build` / `climaybe build-scripts`, and the `serve` watcher), any `assets/*.js` that the current `_scripts/` build does not produce is **deleted** as a stale artifact. To add a new JS asset, create a top-level `_scripts/<name>.js` entry — do not drop a hand-written `.js` into `assets/` (it will be removed). Liquid-processed assets (`*.js.liquid`) and non-JS files are never touched.
+
 ## Code Review Requirements
 All code must pass the checklist in `javascript-standards.mdc` before merge.
 

package/src/cursor/rules/tailwindcss-rules.mdc

@@ -3,13 +3,14 @@ description: Tailwind CSS and theme token standards for Liquid and theme styles.
 globs:
   - "**/*.liquid"
   - "_styles/**/*.css"
-  - "assets/*.css"
 alwaysApply: false
 ---
 # Tailwind CSS Development Rules
 
 Apply when editing Liquid templates or theme CSS that use Tailwind classes or theme tokens. Use semantic tokens (surface, subtle, emphasis, accent, text-primary, border-secondary) from this project's `@theme`; see `_styles/02_base/02.02_colors.css`.
 
+> **Source vs build output:** Edit CSS in `_styles/` (entrypoint `_styles/main.css`). The CLI compiles it into `assets/style.css` on every save and in CI, so `assets/style.css` is a **generated artifact** — never edit it directly, your changes will be overwritten. See `project-overview.mdc` (Build Outputs vs Source).
+
 ## Core Principles
 
 ### 1. Static Class Generation

package/src/index.js

@@ -64,8 +64,12 @@ function registerThemeCommands(cmd) {
     .command('serve')
     .description('Run local theme dev (Shopify + assets; Theme Check off by default)')
     .option('--theme-check', 'Enable Theme Check watcher')
-    .action((opts) => serveAll({ includeThemeCheck: opts.themeCheck === true }));
-  cmd.command('serve:shopify').description('Run Shopify theme dev server').action(() => serveShopify());
+    .action(async (opts) => {
+      await serveAll({ includeThemeCheck: opts.themeCheck === true });
+    });
+  cmd.command('serve:shopify').description('Run Shopify theme dev server').action(async () => {
+    await serveShopify();
+  });
   cmd
     .command('serve:assets')
     .description('Run assets watch (Tailwind + scripts; Theme Check off by default)')

package/src/lib/build-scripts.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join, basename, dirname, normalize } from 'node:path';
 
 function extractImportRecords(content) {
@@ -161,6 +161,30 @@ function collectFilesToIsolate({ scriptsDir, entryFile }) {
   return isolateFiles;
 }
 
+function removeOrphanScriptAssets({ cwd, keepNames }) {
+  // Delete assets/*.js that this build did not produce. The Electric Maybe build
+  // model treats assets/*.js as generated output of _scripts/, so any *.js without
+  // a matching bundle output is stale and should be removed. Only plain *.js files
+  // are considered — Liquid-processed assets (e.g. *.js.liquid) are left untouched.
+  const assetsDir = join(cwd, 'assets');
+  if (!existsSync(assetsDir)) return [];
+
+  const removed = [];
+  for (const dirent of readdirSync(assetsDir, { withFileTypes: true })) {
+    if (!dirent.isFile()) continue;
+    const name = dirent.name;
+    if (!name.endsWith('.js')) continue;
+    if (keepNames.has(name)) continue;
+    try {
+      unlinkSync(join(assetsDir, name));
+      removed.push(name);
+    } catch {
+      // Best effort: a failed unlink shouldn't break the build.
+    }
+  }
+  return removed;
+}
+
 function listTopLevelEntrypoints(scriptsDir) {
   if (!existsSync(scriptsDir)) return [];
   return readdirSync(scriptsDir, { withFileTypes: true })
@@ -234,9 +258,18 @@ export function buildScripts({ cwd = process.cwd(), entry = null, minify = false
     }
   }
   if (entrypoints.length === 0) {
-    return { bundles: [] };
+    return { bundles: [], removed: [] };
   }
   const bundles = entrypoints.map((entryFile) => buildSingleEntrypoint({ cwd, entryFile, minify }));
-  return { bundles };
+
+  // Only prune orphans on a full build (no explicit entry). A targeted single-entry
+  // build must not delete the other bundles' outputs.
+  let removed = [];
+  if (!entry) {
+    const keepNames = new Set(bundles.map((b) => basename(b.outputPath)));
+    removed = removeOrphanScriptAssets({ cwd, keepNames });
+  }
+
+  return { bundles, removed };
 }
 

package/src/lib/config.js

@@ -180,6 +180,23 @@ export function getStoreAliases(cwd = process.cwd()) {
   return Object.keys(config.stores);
 }
 
+/**
+ * Resolve the store alias for `default_store` (the domain last set by `climaybe switch` or serve).
+ * @param {string} [cwd]
+ * @returns {string | null}
+ */
+export function getAliasForDefaultStore(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  const domain = config?.default_store;
+  const stores = config?.stores;
+  if (!domain || !stores || typeof stores !== 'object') return null;
+  const normalized = String(domain).trim();
+  for (const [alias, storeDomain] of Object.entries(stores)) {
+    if (String(storeDomain).trim() === normalized) return alias;
+  }
+  return null;
+}
+
 /**
  * Determine the current mode: 'single' or 'multi'.
  */

package/src/lib/dev-runtime.js

@@ -4,6 +4,7 @@ import { watchTree } from './watch.js';
 import { isAbsolute, join, relative } from 'node:path';
 import pc from 'picocolors';
 import { readConfig, getStoreDomainFromBranch } from './config.js';
+import { prepareMultiStoreForServe } from './serve-multi-store.js';
 import { buildScripts } from './build-scripts.js';
 import { buildSchemas } from './schema-builder.js';
 import { runShopify } from './shopify-cli.js';
@@ -209,7 +210,15 @@ function runThemeCheckFiltered({ cwd = process.cwd() } = {}) {
   return child;
 }
 
-export function serveShopify({ cwd = process.cwd() } = {}) {
+/**
+ * @param {{ cwd?: string; skipMultiStorePrep?: boolean }} [opts]
+ * @returns {Promise<import('node:child_process').ChildProcess | null>} Null when multi-store prep failed or was cancelled.
+ */
+export async function serveShopify({ cwd = process.cwd(), skipMultiStorePrep = false } = {}) {
+  if (!skipMultiStorePrep) {
+    const ok = await prepareMultiStoreForServe(cwd);
+    if (!ok) return null;
+  }
   const config = readConfig(cwd) || {};
   const branchStore = getStoreDomainFromBranch(cwd);
   const store = branchStore || config.default_store || config.store || '';
@@ -244,8 +253,11 @@ export function serveAssets({ cwd = process.cwd(), includeThemeCheck = false } =
   const scriptsDir = join(cwd, '_scripts');
   if (existsSync(scriptsDir)) {
     try {
-      buildScripts({ cwd });
+      const { removed } = buildScripts({ cwd });
       writeTaggedLine('scripts', pc.yellow, 'built (initial)');
+      if (removed?.length) {
+        writeTaggedLine('scripts', pc.yellow, `removed ${removed.length} orphan asset(s): ${removed.join(', ')}`);
+      }
     } catch (err) {
       writeTaggedLine('scripts', pc.yellow, `initial build failed: ${err.message}`, process.stderr);
     }
@@ -259,8 +271,11 @@ export function serveAssets({ cwd = process.cwd(), includeThemeCheck = false } =
         debounceMs: 300,
         onChange: () => {
           try {
-            buildScripts({ cwd });
+            const { removed } = buildScripts({ cwd });
             writeTaggedLine('scripts', pc.yellow, 'rebuilt');
+            if (removed?.length) {
+              writeTaggedLine('scripts', pc.yellow, `removed ${removed.length} orphan asset(s): ${removed.join(', ')}`);
+            }
           } catch (err) {
             writeTaggedLine('scripts', pc.yellow, `build failed: ${err.message}`, process.stderr);
           }
@@ -365,16 +380,28 @@ export function serveAssets({ cwd = process.cwd(), includeThemeCheck = false } =
   return { tailwind, devMcp, scriptsWatch, schemasWatch, themeCheckWatch, cleanup };
 }
 
-export function serveAll({ cwd = process.cwd(), includeThemeCheck = false } = {}) {
+export async function serveAll({ cwd = process.cwd(), includeThemeCheck = false } = {}) {
+  const prepOk = await prepareMultiStoreForServe(cwd);
+  if (!prepOk) {
+    const noop = () => {};
+    return { cleanup: noop };
+  }
+
   // Start assets first, then bring up Shopify after a short delay.
   const assets = serveAssets({ cwd, includeThemeCheck });
   let shopify = null;
   const shopifyStartDelayMs = 2500;
   const shopifyTimer = setTimeout(() => {
-    shopify = serveShopify({ cwd });
-    shopify.on('exit', () => {
-      cleanup();
-    });
+    void (async () => {
+      shopify = await serveShopify({ cwd, skipMultiStorePrep: true });
+      if (shopify) {
+        shopify.on('exit', () => {
+          cleanup();
+        });
+      } else {
+        cleanup();
+      }
+    })();
   }, shopifyStartDelayMs);
   console.log(pc.dim(`  Waiting ${shopifyStartDelayMs}ms before starting Shopify...`));
 
@@ -428,7 +455,10 @@ export function buildAll({ cwd = process.cwd() } = {}) {
 
   let scriptsOk = true;
   try {
-    buildScripts({ cwd });
+    const { removed } = buildScripts({ cwd });
+    if (removed?.length) {
+      writeTaggedLine('scripts', pc.yellow, `removed ${removed.length} orphan asset(s): ${removed.join(', ')}`);
+    }
   } catch (err) {
     console.log(pc.red(`\n  build-scripts failed: ${err.message}\n`));
     scriptsOk = false;

package/src/lib/prompts.js

@@ -229,6 +229,28 @@ export async function promptProjectName(cwd = process.cwd()) {
   return String(projectName || '').trim();
 }
 
+/**
+ * Ask which store to use for local theme dev (multi-store `climaybe serve`).
+ * @param {{ aliases: string[]; stores: Record<string, string>; suggestedAlias: string }} opts
+ * @returns {Promise<string | null>} Selected alias, or null if cancelled.
+ */
+export async function promptServeStore({ aliases, stores, suggestedAlias }) {
+  const sorted = [...aliases].sort();
+  const choices = sorted.map((alias) => ({
+    title: `${alias} (${stores[alias]})`,
+    value: alias,
+  }));
+  const initialIndex = sorted.indexOf(suggestedAlias);
+  const { alias } = await prompts({
+    type: 'select',
+    name: 'alias',
+    message: 'Which store should we serve?',
+    choices,
+    initial: initialIndex >= 0 ? initialIndex : 0,
+  });
+  return alias ?? null;
+}
+
 /**
  * Prompt for a single new store (used by add-store command).
  * Takes existing aliases to prevent duplicates.

package/src/lib/serve-multi-store.js

@@ -0,0 +1,81 @@
+import pc from 'picocolors';
+import { readConfig, getMode, getProjectType, getStoreAliases, writeConfig, getAliasForDefaultStore } from './config.js';
+import { rootToStores, storesToRoot } from './store-sync.js';
+import { promptServeStore } from './prompts.js';
+
+function readExplicitServeAlias(cwd) {
+  const raw = process.env.CLIMAYBE_SERVE_STORE?.trim();
+  if (!raw) return { ok: true, alias: null };
+  const aliases = getStoreAliases(cwd);
+  if (aliases.includes(raw)) return { ok: true, alias: raw };
+  console.log(pc.red(`  CLIMAYBE_SERVE_STORE="${raw}" is not a known store alias.`));
+  console.log(pc.dim(`  Available: ${aliases.join(', ')}\n`));
+  return { ok: false, alias: null };
+}
+
+function isNonInteractiveServe() {
+  if (process.env.CLIMAYBE_SERVE_STORE?.trim()) return true;
+  if (process.env.CI === 'true') return true;
+  return process.stdin.isTTY !== true;
+}
+
+/**
+ * In multi-store theme repos, ensure root JSONs and `default_store` match the store
+ * the user wants to serve. If the choice differs from the previous switch target,
+ * saves current root → `stores/<previous>/` then loads `stores/<selected>/` → root.
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<boolean>} False if the user cancelled or `CLIMAYBE_SERVE_STORE` is invalid.
+ */
+export async function prepareMultiStoreForServe(cwd = process.cwd()) {
+  if (getProjectType(cwd) === 'app') return true;
+  if (getMode(cwd) !== 'multi') return true;
+
+  const config = readConfig(cwd);
+  if (!config?.stores || typeof config.stores !== 'object') return true;
+
+  const aliases = getStoreAliases(cwd);
+  if (aliases.length < 2) return true;
+
+  const stores = config.stores;
+  const suggestedAlias = getAliasForDefaultStore(cwd) ?? aliases[0];
+
+  const explicit = readExplicitServeAlias(cwd);
+  if (!explicit.ok) return false;
+
+  let selected = explicit.alias;
+  if (!selected) {
+    if (isNonInteractiveServe()) {
+      selected = suggestedAlias;
+    } else {
+      console.log(pc.bold('\n  climaybe — serve (store)\n'));
+      selected = await promptServeStore({ aliases, stores, suggestedAlias });
+      if (!selected) {
+        console.log(pc.dim('  Cancelled.\n'));
+        return false;
+      }
+    }
+  }
+
+  const previousAlias = getAliasForDefaultStore(cwd);
+
+  if (selected === previousAlias) return true;
+
+  if (previousAlias) {
+    rootToStores(previousAlias, cwd);
+  } else {
+    console.log(
+      pc.yellow(
+        '  Warning: default_store did not match any store alias; current root JSONs are not auto-saved to a store folder.'
+      )
+    );
+  }
+
+  const ok = storesToRoot(selected, cwd);
+  if (!ok) return false;
+
+  const domain = stores[selected];
+  if (domain) writeConfig({ default_store: domain }, cwd);
+
+  return true;
+}

package/src/workflows/preview/cleanup-orphan-preview-themes.yml

@@ -0,0 +1,59 @@
+# climaybe — Cleanup orphan preview themes (optional)
+# Weekly (and manual): on each configured store, delete themes whose name ends with -PR<n>
+# when PR #n is not open in this repo (merged/closed without theme cleanup).
+
+name: Cleanup orphan preview themes
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  configure:
+    runs-on: ubuntu-latest
+    outputs:
+      preview_targets_json: ${{ steps.cfg.outputs.preview_targets_json }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build store matrix from climaybe.config.json
+        id: cfg
+        run: |
+          if [ ! -f climaybe.config.json ]; then
+            {
+              echo 'preview_targets_json<<PT_JSON'
+              echo '[]'
+              echo 'PT_JSON'
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          node <<'NODE' >>"$GITHUB_OUTPUT"
+          const fs = require('fs');
+          const cfg = JSON.parse(fs.readFileSync('climaybe.config.json', 'utf8'));
+          const stores = cfg?.stores || {};
+          const keys = Object.keys(stores);
+          const aliasToSecret = (a) => String(a).toUpperCase().replace(/-/g, '_');
+          const targets = keys.map((alias) => ({ alias, alias_secret: aliasToSecret(alias) }));
+          console.log('preview_targets_json<<PT_JSON');
+          console.log(JSON.stringify(targets));
+          console.log('PT_JSON');
+          NODE
+
+  cleanup-orphans:
+    needs: [configure]
+    if: needs.configure.outputs.preview_targets_json != '[]'
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJson(needs.configure.outputs.preview_targets_json) }}
+    uses: ./.github/workflows/reusable-cleanup-themes.yml
+    with:
+      cleanup_mode: orphan_pr
+      pr_number: ''
+      store_alias_secret: ${{ matrix.alias_secret }}
+    secrets: inherit