@woodsportal/hubspot-kit 1.0.5 → 1.0.26

package/dist/cli.js

@@ -4,12 +4,13 @@ import {
   WpHsError,
   isWpHsError,
   runCommand,
-  runNodeScript
-} from "./chunk-JDGIAYHX.js";
+  runNodeScript,
+  runNodeScriptLongRunning
+} from "./chunk-GTTIJVAR.js";
 
 // src/cli/program.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { resolve as resolve17 } from "path";
+import { readFileSync as readFileSync14 } from "fs";
+import { resolve as resolve21 } from "path";
 import { Command } from "commander";
 
 // src/lib/config.ts
@@ -94,6 +95,8 @@ var WoodsPortalHsSchema = z.object({
     app: z.string().default("src/cdn/app-entry.ts"),
     vendor: z.string().default("src/cdn/vendor-entry.ts"),
     hubspotBootstrap: z.string().default("src/hubspot/bootstrap.ts"),
+    /** Monolith production IIFE entry (wp build --hubspot-only) */
+    module: z.string().default("src/hubspot/module-entry.tsx"),
     localDev: z.string().default("src/main.tsx")
   }).default({}),
   env: z.object({
@@ -104,7 +107,11 @@ var WoodsPortalHsSchema = z.object({
     adapter: z.string().default("./wphs.adapter.ts"),
     fieldsJson: z.string().default("public/fields.json"),
     themeFieldsJson: z.string().optional()
-  }).default({})
+  }).default({}),
+  scaffold: z.object({
+    /** hash = woodsportal-client-frontend (HubSpot CMS); browser = local clean URLs; none = single page */
+    router: z.enum(["hash", "browser", "none"]).default("hash")
+  }).optional()
 });
 var DEFAULT_WOODSPORTAL_HS = {
   configVersion: CONFIG_VERSION,
@@ -123,6 +130,7 @@ var DEFAULT_WOODSPORTAL_HS = {
     app: "src/cdn/app-entry.ts",
     vendor: "src/cdn/vendor-entry.ts",
     hubspotBootstrap: "src/hubspot/bootstrap.ts",
+    module: "src/hubspot/module-entry.tsx",
     localDev: "src/main.tsx"
   },
   env: {
@@ -285,22 +293,66 @@ function defaultBaselineDir(projectRoot, config) {
 }
 
 // src/cli/commands/doctor.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { join, resolve as resolve5 } from "path";
 
+// src/lib/cli-spinner.ts
+import * as p from "@clack/prompts";
+import pc2 from "picocolors";
+function isInteractiveCli(ctx) {
+  const { json, quiet, ci } = ctx.global;
+  return !json && !quiet && !ci && process.stdout.isTTY === true;
+}
+function shouldShowProgress(ctx, override) {
+  if (override === false) return false;
+  return isInteractiveCli(ctx);
+}
+async function runCliTasks(ctx, tasks2, options = {}) {
+  if (!shouldShowProgress(ctx, options.progress)) {
+    for (const step of tasks2) {
+      await step.task();
+    }
+    return;
+  }
+  await p.tasks(tasks2);
+}
+function printCommandDone(ctx, message) {
+  if (isInteractiveCli(ctx)) {
+    process.stdout.write(`${pc2.green("\u25C6")} ${message}
+`);
+    return;
+  }
+  ctx.logger.success(message);
+}
+
 // src/lib/hubspot-cli-setup.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { resolve as resolve4 } from "path";
 import { spawnSync } from "child_process";
 var HUBSPOT_CONFIG_FILE = "hubspot.config.yml";
 var HUBSPOT_CONFIG_EXAMPLE = "hubspot.config.yml.example";
+var HS_VERSION_TIMEOUT_MS = 5e3;
+var HS_ACCOUNTS_TIMEOUT_MS = 1e4;
 var PLACEHOLDER_PATTERNS = [
   /YOUR_PAT_HERE/i,
   /your-portal-id/i,
   /personalAccessKey:\s*$/m,
   /portalId:\s*12345678\b/
 ];
-function assessHubSpotCliSetup(projectRoot) {
+function spawnHs(args, options = {}) {
+  return spawnSync("hs", args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    timeout: options.timeoutMs ?? HS_ACCOUNTS_TIMEOUT_MS,
+    // Keep HubSpot CLI off the interactive TTY (avoids hangs under @clack spinners)
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+}
+function hsTimedOut(result) {
+  const err = result.error;
+  return err?.code === "ETIMEDOUT";
+}
+function assessHubSpotConfigFiles(projectRoot) {
   const configPath = resolve4(projectRoot, HUBSPOT_CONFIG_FILE);
   const examplePath = resolve4(projectRoot, HUBSPOT_CONFIG_EXAMPLE);
   const configPresent = existsSync3(configPath);
@@ -312,43 +364,47 @@ function assessHubSpotCliSetup(projectRoot) {
   } else {
     looksLikePlaceholder = true;
   }
-  const hsVersion = spawnSync("hs", ["--version"], { encoding: "utf8" });
-  const hsCliInstalled = hsVersion.status === 0;
+  return {
+    configPath,
+    examplePath,
+    configPresent,
+    examplePresent,
+    looksLikePlaceholder
+  };
+}
+function runHubSpotCliChecks(projectRoot, options = {}) {
+  const checkAccounts = options.checkAccounts !== false;
+  const hsVersion = spawnHs(["--version"], { timeoutMs: HS_VERSION_TIMEOUT_MS });
+  const hsCliInstalled = hsVersion.status === 0 && !hsTimedOut(hsVersion);
   const hsCliVersion = hsCliInstalled ? (hsVersion.stdout || hsVersion.stderr || "").trim() : null;
   let authenticated = false;
   let accountsHint = null;
-  if (hsCliInstalled) {
-    const accounts = spawnSync("hs", ["accounts", "list"], {
+  if (hsCliInstalled && checkAccounts) {
+    const accounts = spawnHs(["accounts", "list"], {
       cwd: projectRoot,
-      encoding: "utf8",
-      timeout: 15e3
+      timeoutMs: HS_ACCOUNTS_TIMEOUT_MS
     });
     const output = `${accounts.stdout || ""}
 ${accounts.stderr || ""}`.trim();
-    accountsHint = output || null;
-    authenticated = accounts.status === 0 && /Account:|portalId|portal/i.test(output) && !/No accounts/i.test(output);
+    accountsHint = hsTimedOut(accounts) ? "timed out" : output || null;
+    authenticated = !hsTimedOut(accounts) && accounts.status === 0 && /Account:|portalId|portal/i.test(output) && !/No accounts/i.test(output);
   }
+  return { hsCliInstalled, hsCliVersion, authenticated, accountsHint };
+}
+function assessHubSpotCliSetup(projectRoot, options = {}) {
   return {
-    configPath,
-    examplePath,
-    configPresent,
-    examplePresent,
-    looksLikePlaceholder,
-    hsCliInstalled,
-    hsCliVersion,
-    authenticated,
-    accountsHint
+    ...assessHubSpotConfigFiles(projectRoot),
+    ...runHubSpotCliChecks(projectRoot, options)
   };
 }
-function hubSpotSetupRemediation(projectRoot) {
-  const assessment = assessHubSpotCliSetup(projectRoot);
+function hubSpotSetupRemediation(projectRoot, assessment = assessHubSpotCliSetup(projectRoot)) {
   const steps = [];
   if (!assessment.hsCliInstalled) {
     steps.push("Install HubSpot CLI: npm i -g @hubspot/cli");
   }
   if (!assessment.configPresent) {
     if (assessment.examplePresent) {
-      steps.push(`Copy ${HUBSPOT_CONFIG_EXAMPLE} \u2192 ${HUBSPOT_CONFIG_FILE} and add your portal + PAT`);
+      steps.push(`Run wp setup (copies ${HUBSPOT_CONFIG_EXAMPLE} \u2192 ${HUBSPOT_CONFIG_FILE}) and add portal + PAT`);
     } else {
       steps.push(`Create ${HUBSPOT_CONFIG_FILE} (see docs/HUBSPOT-CLI-SETUP.md)`);
     }
@@ -361,29 +417,67 @@ function hubSpotSetupRemediation(projectRoot) {
   }
   return steps;
 }
+function hubSpotLocalDevRemediation(files) {
+  const steps = [];
+  if (!files.configPresent) {
+    if (files.examplePresent) {
+      steps.push(`Run wp setup (copies ${HUBSPOT_CONFIG_EXAMPLE} \u2192 ${HUBSPOT_CONFIG_FILE}) and add portal + PAT`);
+    } else {
+      steps.push(`Create ${HUBSPOT_CONFIG_FILE} (see docs/HUBSPOT-CLI-SETUP.md)`);
+    }
+    steps.push("Generate a PAT: https://app.hubspot.com/l/personal-access-key");
+  } else if (files.looksLikePlaceholder) {
+    steps.push(`Edit ${HUBSPOT_CONFIG_FILE} \u2014 replace placeholder portalId and personalAccessKey`);
+  }
+  return steps;
+}
+function cmsEnsureAssessment(projectRoot) {
+  return assessHubSpotCliSetup(projectRoot, { checkAccounts: false });
+}
+function throwCmsConfigError(_ctx, files) {
+  const steps = hubSpotLocalDevRemediation(files);
+  throw new WpHsError("HubSpot config is not ready for cms watch/upload in this project.", {
+    exitCode: ExitCode.PREREQUISITE,
+    remediation: steps.join("; ")
+  });
+}
+function ensureHubSpotConfigForCms(ctx) {
+  if (ctx.global.dryRun || ctx.global.json) return;
+  const files = assessHubSpotConfigFiles(ctx.projectRoot);
+  if (files.configPresent && !files.looksLikePlaceholder) return;
+  throwCmsConfigError(ctx, files);
+}
 function ensureHubSpotCliSetup(ctx, mode) {
   if (ctx.global.dryRun || ctx.global.json) return;
-  const assessment = assessHubSpotCliSetup(ctx.projectRoot);
-  const needsSetup = !assessment.hsCliInstalled || !assessment.configPresent || assessment.looksLikePlaceholder || !assessment.authenticated;
-  if (!needsSetup) return;
-  const steps = hubSpotSetupRemediation(ctx.projectRoot);
-  const headline = mode === "local" ? "HubSpot upload/watch is not configured for this project (local preview still works)." : "HubSpot CLI is not ready for cms upload/watch in this project.";
   if (mode === "local") {
-    ctx.logger.warn(headline);
-    for (const step of steps) {
+    const files = assessHubSpotConfigFiles(ctx.projectRoot);
+    if (files.configPresent && !files.looksLikePlaceholder) {
+      return;
+    }
+    const steps2 = hubSpotLocalDevRemediation(files);
+    ctx.logger.warn(
+      "HubSpot upload/watch is not configured for this project (local preview still works)."
+    );
+    for (const step of steps2) {
       ctx.logger.info(`  \u2192 ${step}`);
     }
+    ctx.logger.info("  \u2192 Full HubSpot CLI checks: wp doctor");
     ctx.logger.info("  \u2192 Docs: @woodsportal/hubspot-kit/docs/HUBSPOT-CLI-SETUP.md");
     return;
   }
+  const assessment = cmsEnsureAssessment(ctx.projectRoot);
+  const needsSetup = !assessment.hsCliInstalled || !assessment.configPresent || assessment.looksLikePlaceholder;
+  if (!needsSetup) return;
+  const steps = hubSpotSetupRemediation(ctx.projectRoot, assessment);
+  const headline = "HubSpot CLI is not ready for cms upload/watch in this project.";
   throw new WpHsError(headline, {
     exitCode: ExitCode.PREREQUISITE,
     remediation: steps.join("; ")
   });
 }
 function doctorHubSpotChecks(projectRoot) {
-  const assessment = assessHubSpotCliSetup(projectRoot);
-  const steps = hubSpotSetupRemediation(projectRoot);
+  const assessment = assessHubSpotCliSetup(projectRoot, { checkAccounts: true });
+  const steps = hubSpotSetupRemediation(projectRoot, assessment);
   const remediation = steps.length > 0 ? steps.join(" \xB7 ") : void 0;
   return [
     {
@@ -403,13 +497,42 @@ function doctorHubSpotChecks(projectRoot) {
     {
       name: "hubspot-auth",
       ok: assessment.authenticated,
-      message: assessment.authenticated ? "HubSpot CLI authenticated for this project" : "HubSpot CLI not authenticated (or no portal in hubspot.config.yml)",
+      message: assessment.authenticated ? "HubSpot CLI authenticated for this project" : assessment.accountsHint === "timed out" ? "HubSpot CLI auth check timed out \u2014 run hs accounts list manually" : "HubSpot CLI not authenticated (or no portal in hubspot.config.yml)",
       remediation: assessment.authenticated ? void 0 : "wp auth \xB7 hs accounts list",
       severity: "warn"
     }
   ];
 }
 
+// src/lib/template-dev-deps.ts
+var VITE_DEV_PEER_DEPS = {
+  vite: "^6.1.0",
+  "@vitejs/plugin-react": "^4.3.4",
+  "babel-plugin-react-compiler": "^1.0.0",
+  "@tailwindcss/vite": "^4.0.6",
+  "@tanstack/router-plugin": "^1.121.2",
+  "@tanstack/react-router": "^1.121.2",
+  "@dnd-kit/core": "^6.3.1",
+  "@dnd-kit/sortable": "^10.0.0",
+  "@dnd-kit/utilities": "^3.2.2",
+  react: "^19.0.0",
+  "react-dom": "^19.0.0",
+  tailwindcss: "^4.0.6"
+};
+var KIT_DEV_DEP = "@woodsportal/hubspot-kit";
+var KIT_DEV_DEP_VERSION = "^1.0.26";
+var MODULE_CONFIG_UI_DEPS = [
+  "@dnd-kit/core",
+  "@dnd-kit/sortable",
+  "@dnd-kit/utilities"
+];
+function templateDevDependencies() {
+  return {
+    [KIT_DEV_DEP]: KIT_DEV_DEP_VERSION,
+    ...VITE_DEV_PEER_DEPS
+  };
+}
+
 // src/cli/commands/doctor.ts
 function checkNode() {
   const major = Number(process.versions.node.split(".")[0]);
@@ -476,13 +599,12 @@ function checkEnvFiles(ctx) {
   return ctx.config.env.tiers.map((tier) => {
     const file = tier === "dev" ? ".env.dev" : tier === "stg" ? ".env.stg" : ".env.prod";
     const path = resolve5(ctx.projectRoot, file);
-    const example = resolve5(ctx.projectRoot, `${file}.example`);
     const ok = existsSync4(path);
     return {
       name: `env-${tier}`,
       ok,
       message: ok ? `${file} present` : `${file} missing`,
-      remediation: ok ? void 0 : existsSync4(example) ? `cp ${file}.example ${file}` : `Create ${file}`,
+      remediation: ok ? void 0 : "wp setup (copies from .example templates)",
       severity: "warn"
     };
   });
@@ -495,7 +617,7 @@ function checkBuildId(ctx) {
     name: "build-id",
     ok,
     message: ok ? `${ctx.config.cdn.buildIdFile} present` : `${ctx.config.cdn.buildIdFile} missing`,
-    remediation: ok ? void 0 : `Create ${ctx.config.cdn.buildIdFile} with your release tag (e.g. v0.0.1-dev.1)`,
+    remediation: ok ? void 0 : "wp setup (creates default) or set your release tag (e.g. v0.0.1-dev.1)",
     severity: "warn"
   };
 }
@@ -530,6 +652,21 @@ function checkDevEntry(ctx) {
     remediation: hasEntry ? void 0 : "Re-run wp init or restore src/main.tsx from kit templates",
     severity: "error"
   });
+  if (hasEntry) {
+    try {
+      const source = readFileSync4(localDev, "utf8");
+      const usesKitNodeBootstrap = source.includes("@woodsportal/hubspot-kit/dev/bootstrap-greenfield") || source.includes("@woodsportal/hubspot-kit/dev/bootstrap");
+      const usesWphsShim = source.includes(".wphs/.kit-bootstrap-greenfield") || source.includes(".wphs/.kit-bootstrap") || source.includes("@wphs/bootstrap-greenfield") || source.includes("@wphs/bootstrap");
+      checks.push({
+        name: "local-dev-bootstrap-import",
+        ok: !usesKitNodeBootstrap || usesWphsShim,
+        message: usesKitNodeBootstrap ? `${ctx.config.entries.localDev} imports kit bootstrap via node_modules (breaks React JSX in dev)` : "local dev bootstrap import uses .wphs shim",
+        remediation: usesKitNodeBootstrap ? `Use import from '../.wphs/.kit-bootstrap-greenfield.tsx' (greenfield) or '@wphs/bootstrap' (full portal)` : void 0,
+        severity: "error"
+      });
+    } catch {
+    }
+  }
   return checks;
 }
 function checkKitScripts() {
@@ -603,6 +740,28 @@ function checkAdapter(ctx) {
     severity: "warn"
   };
 }
+function checkModuleConfigUiDeps(ctx) {
+  if (isThemeProject(ctx.config)) return [];
+  const pkgPath = resolve5(ctx.projectRoot, "package.json");
+  if (!existsSync4(pkgPath)) return [];
+  let deps = {};
+  try {
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch {
+    return [];
+  }
+  return MODULE_CONFIG_UI_DEPS.map((name) => {
+    const ok = Boolean(deps[name]);
+    return {
+      name: `module-config-${name.replace(/[@/]/g, "-")}`,
+      ok,
+      message: ok ? `${name} installed` : `${name} missing (module-config overlay)`,
+      remediation: ok ? void 0 : "Run yarn install after wp init, or add @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities to devDependencies",
+      severity: "error"
+    };
+  });
+}
 function checkViteInstalled(ctx) {
   if (isThemeProject(ctx.config) && !existsSync4(resolve5(ctx.projectRoot, "vite.config.dev.mjs"))) {
     return null;
@@ -617,30 +776,80 @@ function checkViteInstalled(ctx) {
     severity: "error"
   };
 }
-async function runDoctor(ctx) {
-  if (!ctx.global.dryRun) {
-    try {
-      runNodeScript(kitPath("scripts/ensure-wphs-workspace.mjs"), [], {
-        cwd: ctx.projectRoot,
-        logger: ctx.logger,
-        dryRun: false
-      });
-    } catch {
+async function gatherDoctorChecks(ctx) {
+  const checks = [];
+  await runCliTasks(ctx, [
+    {
+      title: "Preparing .wphs workspace",
+      task: async () => {
+        if (ctx.global.dryRun) return;
+        try {
+          runNodeScript(kitPath("scripts", "ensure-wphs-workspace.mjs"), [], {
+            cwd: ctx.projectRoot,
+            logger: ctx.logger,
+            dryRun: false
+          });
+        } catch {
+        }
+      }
+    },
+    {
+      title: "Checking Node, Vite, and kit scripts",
+      task: async () => {
+        checks.push(checkNode(), checkKitScripts(), checkDevViteConfig(ctx), ...checkDevEntry(ctx));
+        const viteCheck = checkViteInstalled(ctx);
+        if (viteCheck) checks.push(viteCheck);
+        checks.push(...checkModuleConfigUiDeps(ctx));
+      }
+    },
+    {
+      title: "Checking woodscli.json and project layout",
+      task: async () => {
+        checks.push(...checkConfig(ctx), ...checkWphsWorkspace(ctx));
+        const adapterCheck = checkAdapter(ctx);
+        if (adapterCheck) checks.push(adapterCheck);
+      }
+    },
+    {
+      title: "Checking HubSpot CLI (this can take a few seconds)",
+      task: async () => {
+        checks.push(...doctorHubSpotChecks(ctx.projectRoot));
+      }
+    },
+    {
+      title: "Checking environment and CDN files",
+      task: async () => {
+        const buildIdCheck = checkBuildId(ctx);
+        if (buildIdCheck) checks.push(buildIdCheck);
+        checks.push(...checkEnvFiles(ctx));
+      }
+    }
+  ]);
+  return checks.filter((c) => c !== null);
+}
+function printDoctorResults(ctx, checks) {
+  if (ctx.global.json) return;
+  const interactive = isInteractiveCli(ctx);
+  const verbose = ctx.global.verbose;
+  const showPassing = !interactive || verbose;
+  if (interactive) {
+    process.stdout.write("\n");
+  }
+  for (const check of checks) {
+    if (check.ok && !showPassing) continue;
+    if (check.ok) {
+      ctx.logger.success(check.message);
+    } else if (check.severity === "warn") {
+      ctx.logger.warn(check.message);
+      if (check.remediation) ctx.logger.info(`  \u2192 ${check.remediation}`);
+    } else {
+      ctx.logger.error(check.message);
+      if (check.remediation) ctx.logger.info(`  \u2192 ${check.remediation}`);
     }
   }
-  const checks = [
-    checkNode(),
-    checkKitScripts(),
-    checkDevViteConfig(ctx),
-    ...checkDevEntry(ctx),
-    checkViteInstalled(ctx),
-    ...checkConfig(ctx),
-    ...checkWphsWorkspace(ctx),
-    checkAdapter(ctx),
-    ...doctorHubSpotChecks(ctx.projectRoot),
-    checkBuildId(ctx),
-    ...checkEnvFiles(ctx)
-  ].filter((c) => c !== null);
+}
+async function runDoctor(ctx) {
+  const checks = await gatherDoctorChecks(ctx);
   const failed = checks.filter((c) => !c.ok && (c.severity ?? "error") === "error");
   const warnings = checks.filter((c) => !c.ok && c.severity === "warn");
   if (ctx.global.json) {
@@ -651,16 +860,10 @@ async function runDoctor(ctx) {
       checks
     });
   } else {
-    for (const check of checks) {
-      if (check.ok) {
-        ctx.logger.success(check.message);
-      } else if (check.severity === "warn") {
-        ctx.logger.warn(check.message);
-        if (check.remediation) ctx.logger.info(`  \u2192 ${check.remediation}`);
-      } else {
-        ctx.logger.error(check.message);
-        if (check.remediation) ctx.logger.info(`  \u2192 ${check.remediation}`);
-      }
+    printDoctorResults(ctx, checks);
+    if (!ctx.global.quiet && failed.length === 0) {
+      const summary = warnings.length > 0 ? `${checks.length} checks passed \xB7 ${warnings.length} warning(s)` : `${checks.length} checks passed`;
+      printCommandDone(ctx, summary);
     }
   }
   if (failed.length > 0) {
@@ -698,43 +901,43 @@ async function runConfigValidate(ctx) {
 
 // src/cli/commands/build.ts
 import { resolve as resolve6 } from "path";
+
+// src/lib/build-tier.ts
+var DEFAULT_BUILD_TIER = "dev";
+function parseBuildTier(value) {
+  if (value === "dev" || value === "stg" || value === "prod") return value;
+  return DEFAULT_BUILD_TIER;
+}
+
+// src/cli/commands/build.ts
 function tierToStgFlag(tier) {
   return tier === "dev" || tier === "stg" ? ["--stg"] : [];
 }
-async function runBuild(ctx, options) {
-  const tier = options.tier ?? "prod";
-  const env = { ...process.env, WP_HS_PROJECT_ROOT: ctx.projectRoot };
+function buildTasks(ctx, options, run) {
+  const tier = options.tier ?? DEFAULT_BUILD_TIER;
   const isTheme = isThemeProject(ctx.config);
   const useCdn = usesCdnPipeline(ctx.config) && !isTheme;
-  const execOpts = {
-    cwd: ctx.projectRoot,
-    env,
-    logger: ctx.logger,
-    dryRun: ctx.global.dryRun
-  };
-  const run = (script, args = []) => {
-    runNodeScript(kitPath("scripts", script), args, execOpts);
-  };
-  try {
-    if (isTheme && !options.cdnOnly) {
-      ctx.logger.info("Theme project \u2014 skipping CDN/module.js build (use wp upload for theme assets)");
-      if (ctx.global.json) {
-        ctx.logger.json({ command: "build", tier, ok: true, projectType: ctx.config.projectType });
-      } else {
-        ctx.logger.success("Theme build complete (no-op)");
+  const tasks2 = [];
+  if (isTheme && !options.cdnOnly) {
+    return tasks2;
+  }
+  if (ctx.config.projectType === "module-monolith" && !options.cdnOnly) {
+    tasks2.push({
+      title: `Building monolith module (${tier})`,
+      task: async () => {
+        run("run-vite-build.mjs", [
+          resolve6(ctx.projectRoot, "vite.config.monolith.mjs"),
+          ...tierToStgFlag(tier)
+        ]);
+        run("run-hubspot-module-postbuild.mjs");
       }
-      return ExitCode.SUCCESS;
-    }
-    if (ctx.config.projectType === "module-monolith" && !options.cdnOnly) {
-      ctx.logger.info(`Building monolith module (${tier})\u2026`);
-      run("run-vite-build.mjs", [
-        resolve6(ctx.projectRoot, "vite.config.monolith.mjs"),
-        ...tierToStgFlag(tier)
-      ]);
-      run("run-hubspot-module-postbuild.mjs");
-    } else {
-      if (!options.hubspotOnly && useCdn) {
-        ctx.logger.info(`Building CDN (${tier})\u2026`);
+    });
+    return tasks2;
+  }
+  if (!options.hubspotOnly && useCdn) {
+    tasks2.push({
+      title: `Building CDN (${tier})`,
+      task: async () => {
         if (options.cdnEsm) {
           run("run-vite-build.mjs", [
             resolve6(ctx.projectRoot, "vite.config.cdn-esm.mjs"),
@@ -745,19 +948,64 @@ async function runBuild(ctx, options) {
         }
         run("generate-cdn-manifest.mjs");
       }
-      if (!options.cdnOnly) {
-        ctx.logger.info(`Building HubSpot module (${tier})\u2026`);
+    });
+  }
+  if (!options.cdnOnly) {
+    tasks2.push({
+      title: `Building HubSpot module (${tier})`,
+      task: async () => {
         run("run-vite-build.mjs", [
           resolve6(ctx.projectRoot, "vite.config.hubspot.mjs"),
           ...tierToStgFlag(tier)
         ]);
         run("run-hubspot-module-postbuild.mjs");
       }
+    });
+  }
+  if (!options.cdnOnly && !options.hubspotOnly) {
+    tasks2.push({
+      title: "Running bundle checks",
+      task: async () => {
+        run("check-hubspot-bundle-size.mjs");
+        run("write-audit-artifacts.mjs");
+      }
+    });
+  }
+  return tasks2;
+}
+async function runBuild(ctx, options) {
+  const tier = options.tier ?? DEFAULT_BUILD_TIER;
+  const env = { ...process.env, WP_HS_PROJECT_ROOT: ctx.projectRoot };
+  const isTheme = isThemeProject(ctx.config);
+  const execOpts = {
+    cwd: ctx.projectRoot,
+    env,
+    logger: ctx.logger,
+    dryRun: ctx.global.dryRun
+  };
+  const run = (script, args = []) => {
+    runNodeScript(kitPath("scripts", script), args, execOpts);
+  };
+  try {
+    if (isTheme && !options.cdnOnly) {
+      if (ctx.global.json) {
+        ctx.logger.json({ command: "build", tier, ok: true, projectType: ctx.config.projectType });
+      } else if (!options.progress) {
+        ctx.logger.info("Theme project \u2014 skipping CDN/module.js build (use wp upload for theme assets)");
+        printCommandDone(ctx, "Theme build complete (no-op)");
+      } else {
+        await runCliTasks(
+          ctx,
+          [{ title: "Theme project (no module build)", task: async () => {
+          } }],
+          options
+        );
+        printCommandDone(ctx, "Theme build complete (no-op)");
+      }
+      return ExitCode.SUCCESS;
     }
-    if (!options.cdnOnly && !options.hubspotOnly) {
-      run("check-hubspot-bundle-size.mjs");
-      run("write-audit-artifacts.mjs");
-    }
+    const tasks2 = buildTasks(ctx, options, run);
+    await runCliTasks(ctx, tasks2, options);
     if (ctx.global.json) {
       ctx.logger.json({
         command: "build",
@@ -766,7 +1014,7 @@ async function runBuild(ctx, options) {
         outDir: resolve6(ctx.projectRoot, ctx.config.module.outDir)
       });
     } else {
-      ctx.logger.success("Build complete");
+      printCommandDone(ctx, "Build complete");
     }
     return ExitCode.SUCCESS;
   } catch (error) {
@@ -778,22 +1026,142 @@ async function runBuild(ctx, options) {
 
 // src/cli/commands/dev.ts
 import { existsSync as existsSync6 } from "fs";
-import { resolve as resolve8 } from "path";
+import { resolve as resolve9 } from "path";
 import { spawn } from "child_process";
 
+// src/lib/cli-banner.ts
+import pc3 from "picocolors";
+
+// src/lib/kit-version.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { resolve as resolve7 } from "path";
+var cachedVersion = null;
+function readKitVersion() {
+  if (cachedVersion) {
+    return cachedVersion;
+  }
+  try {
+    const pkg = JSON.parse(readFileSync5(resolve7(getKitRoot(), "package.json"), "utf8"));
+    cachedVersion = pkg.version ?? "0.0.0";
+  } catch {
+    cachedVersion = "0.0.0";
+  }
+  return cachedVersion;
+}
+
+// src/lib/cli-banner.ts
+var WOODSCLI_ASCII_BANNER = `
+ __          __             _      _____ _      _____ 
+ \\ \\        / /            | |    / ____| |    |_   _|
+  \\ \\  /\\  / /__   ___   __| |___| |    | |      | |  
+   \\ \\/  \\/ / _ \\ / _ \\ / _\` / __| |    | |      | |  
+    \\  /\\  / (_) | (_) | (_| \\__ \\ |____| |____ _| |_ 
+     \\/  \\/ \\___/ \\___/ \\__,_|___/\\_____|______|_____|
+`.trimEnd();
+var RULE = "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500";
+function shouldPrintCliBanner(global) {
+  if (global.json || global.quiet || global.ci || global.dryRun) {
+    return false;
+  }
+  return process.stdout.isTTY === true;
+}
+function useCliColor() {
+  if (process.env.NO_COLOR !== void 0) return false;
+  if (process.env.CI === "true") return false;
+  return process.stdout.isTTY === true;
+}
+function formatProjectLabel(config) {
+  if (isThemeProject(config)) {
+    return `${config.theme?.name ?? "theme"} \xB7 theme-starter`;
+  }
+  const router = config.scaffold?.router;
+  const routerNote = router && router !== "hash" ? ` \xB7 router ${router}` : " \xB7 hash router";
+  return `${config.module.name} \xB7 ${config.projectType}${routerNote}`;
+}
+function section(color, title, body) {
+  const bold = (text2) => color ? pc3.bold(text2) : text2;
+  return `  ${bold(title)}
+${body}`;
+}
+function printWoodsCliDevBanner(options) {
+  if (!shouldPrintCliBanner(options.global)) {
+    return;
+  }
+  const color = useCliColor();
+  const cyan = (text2) => color ? pc3.cyan(text2) : text2;
+  const dim = (text2) => color ? pc3.dim(text2) : text2;
+  const bold = (text2) => color ? pc3.bold(text2) : text2;
+  const yellow = (text2) => color ? pc3.yellow(text2) : text2;
+  const version = options.version ?? readKitVersion();
+  const project = formatProjectLabel(options.config);
+  const isTheme = isThemeProject(options.config);
+  const localUrl = `http://localhost:${options.port}/`;
+  const docsRoot = "node_modules/@woodsportal/hubspot-kit/docs";
+  const header = [
+    color ? WOODSCLI_ASCII_BANNER.split("\n").map((line) => cyan(bold(line))).join("\n") : WOODSCLI_ASCII_BANNER,
+    `  ${bold("HubSpot kit")}${dim(`  v${version}`)}  ${yellow("\xB7 dev")}`
+  ].join("\n");
+  const outputLine = isTheme ? "  Vite HMR + theme field overlay (Ctrl+Shift+Z)" : "  Vite HMR + module-config overlay (Ctrl+Shift+Z)";
+  const quickChecks = isTheme ? `    wp doctor              prerequisites + HubSpot CLI
+    wp dev                   alias: wp local
+    wp upload                cms theme upload` : `    wp doctor              prerequisites + HubSpot CLI
+    wp setup                 copy missing config / .env templates
+    wp build                 module.js / CDN (tier defaults dev)
+    wp upload                cms module upload`;
+  const tips = [
+    dim(RULE),
+    section(color, "Output", `       ${outputLine}`),
+    "",
+    section(color, "Project", `      ${project}`),
+    "",
+    section(color, "Preview", `      ${color ? cyan(localUrl) : localUrl}`),
+    "",
+    section(
+      color,
+      "Overlay",
+      `      Ctrl+Shift+Z  ${isTheme ? "theme" : "module"} fields  ${dim("(Mac \u2303\u21E7Z)")}`
+    ),
+    "",
+    section(
+      color,
+      "Workspace",
+      `     ${dim(".wphs/")}  \xB7  ${options.config.dev.fieldsJson}`
+    ),
+    "",
+    section(color, "Quick checks", `
+${quickChecks}`),
+    "",
+    section(
+      color,
+      "Docs",
+      `          ${docsRoot}/CLI-REFERENCE.md \xB7 ${docsRoot}/MODULES.md`
+    ),
+    dim(RULE)
+  ].join("\n");
+  process.stdout.write(`
+${header}
+
+${tips}
+
+`);
+  process.stdout.write(`${dim("Starting Vite dev\u2026")}
+
+`);
+}
+
 // src/vite/resolve-dev-config.ts
 import { existsSync as existsSync5 } from "fs";
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 var CONSUMER_DEV_CONFIG = "vite.config.dev.mjs";
 function resolveDevViteConfigPath(projectRoot) {
-  const consumerConfig = resolve7(projectRoot, CONSUMER_DEV_CONFIG);
+  const consumerConfig = resolve8(projectRoot, CONSUMER_DEV_CONFIG);
   if (existsSync5(consumerConfig)) {
     return consumerConfig;
   }
   return kitPath("vite", "vite.config.dev.mjs");
 }
 function resolveProjectViteBin(projectRoot) {
-  const localBin = resolve7(projectRoot, "node_modules", ".bin", "vite");
+  const localBin = resolve8(projectRoot, "node_modules", ".bin", "vite");
   if (existsSync5(localBin)) {
     return localBin;
   }
@@ -802,7 +1170,6 @@ function resolveProjectViteBin(projectRoot) {
 
 // src/cli/commands/dev.ts
 async function runDev(ctx, options) {
-  ensureHubSpotCliSetup(ctx, "local");
   const port = options.port ?? 3e3;
   const env = {
     ...process.env,
@@ -820,13 +1187,18 @@ async function runDev(ctx, options) {
       remediation: "Run yarn install or npm install. If this is an older wp init project, add vite and peers to devDependencies (run wp init again or see @woodsportal/hubspot-kit templates)."
     });
   }
-  const consumerConfig = resolve8(ctx.projectRoot, "vite.config.dev.mjs");
+  const consumerConfig = resolve9(ctx.projectRoot, "vite.config.dev.mjs");
   if (!existsSync6(consumerConfig)) {
     throw new WpHsError("vite.config.dev.mjs is missing in the project root.", {
       exitCode: ExitCode.USER_ERROR,
       remediation: "Add vite.config.dev.mjs (see @woodsportal/hubspot-kit templates/module-hybrid-cdn)."
     });
   }
+  printWoodsCliDevBanner({
+    config: ctx.config,
+    port,
+    global: ctx.global
+  });
   return new Promise((resolvePromise) => {
     const child = spawn(
       viteBin,
@@ -837,6 +1209,7 @@ async function runDev(ctx, options) {
         stdio: "inherit"
       }
     );
+    setImmediate(() => ensureHubSpotCliSetup(ctx, "local"));
     child.on("exit", (code) => {
       resolvePromise(code ?? ExitCode.USER_ERROR);
     });
@@ -844,11 +1217,17 @@ async function runDev(ctx, options) {
 }
 
 // src/cli/commands/deploy.ts
-import { resolve as resolve10 } from "path";
+import { resolve as resolve11 } from "path";
 
 // src/cli/commands/publish.ts
 async function runPublish(ctx, options) {
-  const tier = options.tier ?? "prod";
+  if (!usesCdnPipeline(ctx.config)) {
+    throw new WpHsError("This project does not use the CDN pipeline.", {
+      exitCode: ExitCode.USER_ERROR,
+      remediation: "module-monolith / cdn.mode none: use wp build && wp upload (or wp deploy without CDN publish)."
+    });
+  }
+  const tier = options.tier ?? DEFAULT_BUILD_TIER;
   const env = { ...process.env, WP_HS_PROJECT_ROOT: ctx.projectRoot };
   const execOpts = {
     cwd: ctx.projectRoot,
@@ -859,16 +1238,32 @@ async function runPublish(ctx, options) {
   const verifyFlag = tier === "prod" ? ["--prod"] : ["--stg"];
   const publishArgs = options.dryRun ? ["--dry-run"] : [];
   try {
-    if (!options.dryRun) {
-      ctx.logger.info(`Verifying CDN API endpoint (${tier})\u2026`);
-      runNodeScript(kitPath("scripts", "verify-cdn-api-endpoint.mjs"), verifyFlag, execOpts);
-    }
-    ctx.logger.info(options.dryRun ? "CDN publish dry-run\u2026" : `Publishing CDN (${tier})\u2026`);
-    runNodeScript(kitPath("scripts", "publish-cdn-github.mjs"), publishArgs, execOpts);
+    await runCliTasks(
+      ctx,
+      [
+        {
+          title: `Verifying CDN API endpoint (${tier})`,
+          task: async () => {
+            if (options.dryRun) return;
+            runNodeScript(kitPath("scripts", "verify-cdn-api-endpoint.mjs"), verifyFlag, execOpts);
+          }
+        },
+        {
+          title: options.dryRun ? `CDN publish dry-run (${tier})` : `Publishing CDN (${tier})`,
+          task: async () => {
+            runNodeScript(kitPath("scripts", "publish-cdn-github.mjs"), publishArgs, execOpts);
+          }
+        }
+      ],
+      options
+    );
     if (ctx.global.json) {
       ctx.logger.json({ command: "publish", tier, dryRun: Boolean(options.dryRun), ok: true });
     } else {
-      ctx.logger.success(options.dryRun ? "CDN publish dry-run complete" : "CDN publish complete");
+      printCommandDone(
+        ctx,
+        options.dryRun ? "CDN publish dry-run complete" : "CDN publish complete"
+      );
     }
     return ExitCode.SUCCESS;
   } catch (error) {
@@ -880,10 +1275,32 @@ async function runPublish(ctx, options) {
 }
 
 // src/cli/commands/upload.ts
-import { resolve as resolve9 } from "path";
+import { resolve as resolve10 } from "path";
+async function uploadModuleOrTheme(ctx) {
+  if (isThemeProject(ctx.config)) {
+    const theme = ctx.config.theme;
+    if (!theme) {
+      throw new WpHsError("theme block missing in woodscli.json", { exitCode: ExitCode.USER_ERROR });
+    }
+    const srcDir = resolve10(ctx.projectRoot, theme.srcDir);
+    runCommand("hs", ["cms", "upload", srcDir, theme.uploadPath], {
+      cwd: ctx.projectRoot,
+      logger: ctx.logger,
+      dryRun: ctx.global.dryRun
+    });
+    return `Uploaded theme ${srcDir} \u2192 ${theme.uploadPath}`;
+  }
+  const outDir = resolve10(ctx.projectRoot, ctx.config.module.outDir);
+  const uploadPath = ctx.config.module.uploadPath;
+  runCommand("hs", ["cms", "upload", outDir, uploadPath], {
+    cwd: ctx.projectRoot,
+    logger: ctx.logger,
+    dryRun: ctx.global.dryRun
+  });
+  return `Uploaded ${outDir} \u2192 ${uploadPath}`;
+}
 async function runUpload(ctx, options = {}) {
-  ensureHubSpotCliSetup(ctx, "cms");
-  const tier = options.tier ?? "prod";
+  const tier = options.tier ?? DEFAULT_BUILD_TIER;
   if (tier === "prod" && !ctx.global.yes && !ctx.global.ci) {
     const confirmed = process.env.WP_HS_CONFIRM_PROD === "1";
     if (!confirmed) {
@@ -893,39 +1310,25 @@ async function runUpload(ctx, options = {}) {
       });
     }
   }
-  if (isThemeProject(ctx.config)) {
-    const theme = ctx.config.theme;
-    if (!theme) {
-      throw new WpHsError("theme block missing in woodscli.json", { exitCode: ExitCode.USER_ERROR });
-    }
-    const srcDir = resolve9(ctx.projectRoot, theme.srcDir);
-    try {
-      runCommand("hs", ["cms", "upload", srcDir, theme.uploadPath], {
-        cwd: ctx.projectRoot,
-        logger: ctx.logger,
-        dryRun: ctx.global.dryRun
-      });
-      if (!ctx.global.json && !ctx.global.quiet) {
-        ctx.logger.success(`Uploaded theme ${srcDir} \u2192 ${theme.uploadPath}`);
-      }
-      return ExitCode.SUCCESS;
-    } catch (error) {
-      throw new WpHsError("HubSpot theme upload failed", {
-        exitCode: ExitCode.PUBLISH_FAILED,
-        cause: error
-      });
-    }
+  if (!options.skipPrereqCheck) {
+    ensureHubSpotCliSetup(ctx, "cms");
   }
-  const outDir = resolve9(ctx.projectRoot, ctx.config.module.outDir);
-  const uploadPath = ctx.config.module.uploadPath;
   try {
-    runCommand("hs", ["cms", "upload", outDir, uploadPath], {
-      cwd: ctx.projectRoot,
-      logger: ctx.logger,
-      dryRun: ctx.global.dryRun
-    });
-    if (!ctx.global.json && !ctx.global.quiet) {
-      ctx.logger.success(`Uploaded ${outDir} \u2192 ${uploadPath}`);
+    let successMessage = "";
+    await runCliTasks(
+      ctx,
+      [
+        {
+          title: isThemeProject(ctx.config) ? "Uploading theme to HubSpot" : "Uploading module to HubSpot",
+          task: async () => {
+            successMessage = await uploadModuleOrTheme(ctx);
+          }
+        }
+      ],
+      options
+    );
+    if (!ctx.global.json && !options.quiet) {
+      printCommandDone(ctx, successMessage);
     }
     return ExitCode.SUCCESS;
   } catch (error) {
@@ -940,7 +1343,7 @@ async function runUpload(ctx, options = {}) {
 // src/cli/commands/deploy.ts
 async function runDeploy(ctx, options) {
   ensureHubSpotCliSetup(ctx, "cms");
-  const tier = options.tier ?? "prod";
+  const tier = options.tier ?? DEFAULT_BUILD_TIER;
   const env = { ...process.env, WP_HS_PROJECT_ROOT: ctx.projectRoot };
   const execOpts = {
     cwd: ctx.projectRoot,
@@ -948,24 +1351,67 @@ async function runDeploy(ctx, options) {
     logger: ctx.logger,
     dryRun: ctx.global.dryRun
   };
-  await runBuild(ctx, { tier, cdnOnly: true });
-  if (!options.skipPublish) {
-    await runPublish(ctx, { tier });
-  }
-  await runBuild(ctx, { tier, hubspotOnly: true });
-  runNodeScript(kitPath("scripts", "check-hubspot-bundle-size.mjs"), [], execOpts);
-  runNodeScript(kitPath("scripts", "write-audit-artifacts.mjs"), [], execOpts);
-  await runUpload(ctx, { tier });
+  const useCdn = usesCdnPipeline(ctx.config) && !isThemeProject(ctx.config);
+  const nested = { progress: false };
+  const tasks2 = [];
+  if (useCdn) {
+    tasks2.push({
+      title: `Building CDN (${tier})`,
+      task: async () => {
+        await runBuild(ctx, { tier, cdnOnly: true, ...nested });
+      }
+    });
+    if (!options.skipPublish) {
+      tasks2.push({
+        title: `Publishing CDN (${tier})`,
+        task: async () => {
+          await runPublish(ctx, { tier, ...nested });
+        }
+      });
+    }
+    tasks2.push({
+      title: `Building HubSpot module (${tier})`,
+      task: async () => {
+        await runBuild(ctx, { tier, hubspotOnly: true, ...nested });
+      }
+    });
+  } else {
+    tasks2.push({
+      title: `Building module (${tier})`,
+      task: async () => {
+        await runBuild(ctx, { tier, ...nested });
+      }
+    });
+  }
+  tasks2.push(
+    {
+      title: "Running bundle checks",
+      task: async () => {
+        runNodeScript(kitPath("scripts", "check-hubspot-bundle-size.mjs"), [], execOpts);
+        runNodeScript(kitPath("scripts", "write-audit-artifacts.mjs"), [], execOpts);
+      }
+    },
+    {
+      title: "Uploading to HubSpot",
+      task: async () => {
+        await runUpload(ctx, { tier, ...nested, quiet: true, skipPrereqCheck: true });
+      }
+    }
+  );
+  await runCliTasks(ctx, tasks2, options);
   if (!ctx.global.json) {
-    ctx.logger.success(`Deploy complete (${resolve10(ctx.projectRoot, ctx.config.module.outDir)} \u2192 ${ctx.config.module.uploadPath})`);
+    printCommandDone(
+      ctx,
+      `Deploy complete (${resolve11(ctx.projectRoot, ctx.config.module.outDir)} \u2192 ${ctx.config.module.uploadPath})`
+    );
   }
   return ExitCode.SUCCESS;
 }
 
 // src/cli/commands/audit.ts
 import { createHash } from "crypto";
-import { cpSync, existsSync as existsSync7, mkdirSync, readFileSync as readFileSync4, readdirSync, rmSync, statSync } from "fs";
-import { resolve as resolve11, join as join2 } from "path";
+import { cpSync, existsSync as existsSync7, mkdirSync, readFileSync as readFileSync6, readdirSync, rmSync, statSync } from "fs";
+import { resolve as resolve12, join as join2 } from "path";
 var FORBIDDEN_SHIP_TOKENS = [
   "ModuleConfigOverlay",
   "module-config-store",
@@ -974,7 +1420,7 @@ var FORBIDDEN_SHIP_TOKENS = [
   "dev.module-config"
 ];
 function hashFile(path) {
-  return createHash("sha256").update(readFileSync4(path)).digest("hex");
+  return createHash("sha256").update(readFileSync6(path)).digest("hex");
 }
 function walkFiles(dir) {
   if (!existsSync7(dir)) return [];
@@ -993,14 +1439,14 @@ function walkFiles(dir) {
 async function runAuditShipBundle(ctx) {
   const root = ctx.projectRoot;
   const targets = [
-    resolve11(root, "dist/cdn"),
-    resolve11(root, ctx.config.module.outDir)
+    resolve12(root, "dist/cdn"),
+    resolve12(root, ctx.config.module.outDir)
   ];
   const violations = [];
   for (const dir of targets) {
     for (const file of walkFiles(dir)) {
       if (!/\.(js|css|html)$/i.test(file)) continue;
-      const content = readFileSync4(file, "utf8");
+      const content = readFileSync6(file, "utf8");
       for (const token of FORBIDDEN_SHIP_TOKENS) {
         if (content.includes(token)) {
           violations.push(`${file}: contains forbidden token "${token}"`);
@@ -1027,8 +1473,8 @@ async function runAuditBaselineCapture(ctx, options) {
   const root = ctx.projectRoot;
   const baseline = options.baselineDir ?? defaultBaselineDir(root, ctx.config);
   const sources = [
-    { label: "cdn", path: resolve11(root, "dist/cdn") },
-    { label: "hubspot", path: resolve11(root, ctx.config.module.outDir) }
+    { label: "cdn", path: resolve12(root, "dist/cdn") },
+    { label: "hubspot", path: resolve12(root, ctx.config.module.outDir) }
   ];
   if (ctx.global.dryRun) {
     ctx.logger.info(`[dry-run] Would capture baseline to ${baseline}`);
@@ -1041,7 +1487,7 @@ async function runAuditBaselineCapture(ctx, options) {
         remediation: "Run wp build before wp audit baseline --capture."
       });
     }
-    const target = resolve11(baseline, label);
+    const target = resolve12(baseline, label);
     rmSync(target, { recursive: true, force: true });
     mkdirSync(baseline, { recursive: true });
     cpSync(path, target, { recursive: true });
@@ -1057,12 +1503,12 @@ async function runAuditParity(ctx, options) {
   const root = ctx.projectRoot;
   const baseline = options.baselineDir ?? defaultBaselineDir(root, ctx.config);
   const currentDirs = [
-    { label: "cdn", path: resolve11(root, "dist/cdn") },
-    { label: "hubspot", path: resolve11(root, ctx.config.module.outDir) }
+    { label: "cdn", path: resolve12(root, "dist/cdn") },
+    { label: "hubspot", path: resolve12(root, ctx.config.module.outDir) }
   ];
   const mismatches = [];
   for (const { label, path } of currentDirs) {
-    const baselinePath = resolve11(baseline, label);
+    const baselinePath = resolve12(baseline, label);
     if (!existsSync7(baselinePath)) {
       ctx.logger.warn(`No baseline at ${baselinePath} \u2014 skipping ${label} parity`);
       continue;
@@ -1078,7 +1524,7 @@ async function runAuditParity(ctx, options) {
     }
     for (const file of baselineFiles) {
       const rel = file.replace(baselinePath, "");
-      const current = resolve11(path, rel.slice(1));
+      const current = resolve12(path, rel.slice(1));
       if (!existsSync7(current)) continue;
       const bh = hashFile(file);
       const ch = hashFile(current);
@@ -1106,13 +1552,13 @@ var SECRET_PATTERNS = [
 ];
 async function runAuditSecrets(ctx) {
   const root = ctx.projectRoot;
-  const scanRoots = ["src", "public", ".wphs/config"].map((d) => resolve11(root, d));
+  const scanRoots = ["src", "public", ".wphs/config"].map((d) => resolve12(root, d));
   const findings = [];
   for (const dir of scanRoots) {
     for (const file of walkFiles(dir)) {
       if (!/\.(ts|tsx|js|jsx|json|env|yml|yaml|html)$/i.test(file)) continue;
       if (file.includes("node_modules")) continue;
-      const content = readFileSync4(file, "utf8");
+      const content = readFileSync6(file, "utf8");
       for (const pattern of SECRET_PATTERNS) {
         pattern.lastIndex = 0;
         if (pattern.test(content)) {
@@ -1138,29 +1584,340 @@ async function runAuditSecrets(ctx) {
 }
 
 // src/cli/commands/init.ts
-import { cpSync as cpSync2, existsSync as existsSync8, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync5, writeFileSync } from "fs";
-import { basename, resolve as resolve12 } from "path";
-import * as p from "@clack/prompts";
+import { cpSync as cpSync2, existsSync as existsSync10, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync8, writeFileSync as writeFileSync3 } from "fs";
+import { basename as basename2, resolve as resolve15 } from "path";
+import * as p2 from "@clack/prompts";
 
-// src/lib/template-dev-deps.ts
-var VITE_DEV_PEER_DEPS = {
-  vite: "^6.1.0",
-  "@vitejs/plugin-react": "^4.3.4",
-  "babel-plugin-react-compiler": "^1.0.0",
-  "@tailwindcss/vite": "^4.0.6",
-  "@tanstack/router-plugin": "^1.121.2",
-  react: "^19.0.0",
-  "react-dom": "^19.0.0",
-  tailwindcss: "^4.0.6"
-};
-var KIT_DEV_DEP = "@woodsportal/hubspot-kit";
-var KIT_DEV_DEP_VERSION = "^1.0.5";
-function templateDevDependencies() {
+// src/lib/init-router-scaffold.ts
+import { existsSync as existsSync8, mkdirSync as mkdirSync2, readFileSync as readFileSync7, rmSync as rmSync2, writeFileSync } from "fs";
+import { resolve as resolve13 } from "path";
+var ROUTER_FILES = [
+  "src/routes",
+  "src/routeTree.gen.ts",
+  "src/integrations/tanstack-router",
+  "src/config/routes.ts",
+  "src/config/router.ts",
+  "src/app.tsx"
+];
+var TANSTACK_DEPS = ["@tanstack/react-router", "@tanstack/router-plugin"];
+function isModuleTemplate(template) {
+  return template === "module-hybrid-cdn" || template === "module-monolith";
+}
+function writeRouterConfig(targetDir, mode) {
+  const configDir = resolve13(targetDir, "src/config");
+  mkdirSync2(configDir, { recursive: true });
+  writeFileSync(
+    resolve13(configDir, "router.ts"),
+    `/** Router history \u2014 set by \`wp init\`. Hash matches woodsportal-client-frontend (HubSpot CMS embeds). */
+export type RouterHistoryMode = 'hash' | 'browser'
+
+export const ROUTER_HISTORY: RouterHistoryMode = '${mode}'
+`
+  );
+}
+function writeMountDevPreviewRouter(targetDir) {
+  writeFileSync(
+    resolve13(targetDir, "src/portal/mount-dev-preview.tsx"),
+    `import { mountGreenfieldDev } from '../../.wphs/.kit-bootstrap-greenfield.tsx'
+
+import { App } from '@/app'
+
+/** Local dev: module-config overlay + routed starter preview. */
+export async function mountDevPreview() {
+  await mountGreenfieldDev({ preview: <App /> })
+}
+`
+  );
+}
+function writeMountDevPreviewSinglePage(targetDir) {
+  writeFileSync(
+    resolve13(targetDir, "src/portal/mount-dev-preview.tsx"),
+    `import { mountGreenfieldDev } from '../../.wphs/.kit-bootstrap-greenfield.tsx'
+
+import { StarterSinglePage } from '@/features/starter'
+
+/** Local dev: module-config overlay + single-page starter (no TanStack Router). */
+export async function mountDevPreview() {
+  await mountGreenfieldDev({ preview: <StarterSinglePage /> })
+}
+`
+  );
+}
+function writeMountPortalRouter(targetDir) {
+  writeFileSync(
+    resolve13(targetDir, "src/portal/mount-portal.tsx"),
+    `import ReactDOM from 'react-dom/client'
+
+import { App } from '@/app'
+
+/** Production mount \u2014 same App shell as woodsportal-client-frontend CDN app chunk. */
+export async function mountPortal() {
+  const root = document.getElementById('app')
+  if (!root) {
+    return
+  }
+  ReactDOM.createRoot(root).render(<App />)
+}
+`
+  );
+}
+function writeMountPortalSinglePage(targetDir) {
+  writeFileSync(
+    resolve13(targetDir, "src/portal/mount-portal.tsx"),
+    `import ReactDOM from 'react-dom/client'
+
+import { StarterSinglePage } from '@/features/starter'
+
+/** Production mount \u2014 single-page starter when router scaffold is \`none\`. */
+export async function mountPortal() {
+  const root = document.getElementById('app')
+  if (!root) {
+    return
+  }
+  ReactDOM.createRoot(root).render(<StarterSinglePage />)
+}
+`
+  );
+}
+function writeStarterSinglePage(targetDir) {
+  const file = resolve13(targetDir, "src/features/starter/components/starter-single-page.tsx");
+  if (existsSync8(file)) {
+    return;
+  }
+  writeFileSync(
+    file,
+    `import { StarterShell } from '@/components/layout/starter-shell'
+
+import { StarterGuidePage } from './starter-guide-page'
+import { StarterHome } from './starter-home'
+
+/** Single-page starter when \`wp init --router none\` (no TanStack Router). */
+export function StarterSinglePage() {
+  return (
+    <StarterShell showNav={false}>
+      <StarterHome />
+      <div className="mx-auto max-w-4xl px-6 sm:px-10">
+        <hr className="my-10 border-[#cbd6e2]" />
+      </div>
+      <StarterGuidePage />
+    </StarterShell>
+  )
+}
+`
+  );
+}
+function removePath(targetDir, relativePath) {
+  const full = resolve13(targetDir, relativePath);
+  if (!existsSync8(full)) {
+    return;
+  }
+  rmSync2(full, { recursive: true, force: true });
+}
+function stripTanStackFromPackage(targetDir) {
+  const pkgPath = resolve13(targetDir, "package.json");
+  if (!existsSync8(pkgPath)) {
+    return;
+  }
+  const pkg = JSON.parse(readFileSync7(pkgPath, "utf8"));
+  if (!pkg.devDependencies) {
+    return;
+  }
+  for (const dep of TANSTACK_DEPS) {
+    delete pkg.devDependencies[dep];
+  }
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`);
+}
+function applyRouterScaffold(targetDir, mode, template) {
+  if (!isModuleTemplate(template)) {
+    return;
+  }
+  if (mode === "none") {
+    for (const relativePath of ROUTER_FILES) {
+      removePath(targetDir, relativePath);
+    }
+    writeStarterSinglePage(targetDir);
+    writeMountDevPreviewSinglePage(targetDir);
+    writeMountPortalSinglePage(targetDir);
+    stripTanStackFromPackage(targetDir);
+    return;
+  }
+  writeRouterConfig(targetDir, mode);
+  writeMountDevPreviewRouter(targetDir);
+  writeMountPortalRouter(targetDir);
+  const featuresIndex = resolve13(targetDir, "src/features/starter/index.ts");
+  if (existsSync8(featuresIndex)) {
+    let content = readFileSync7(featuresIndex, "utf8");
+    if (!content.includes("StarterSinglePage")) {
+      content = content.replace(
+        "export type { StarterPreviewValues } from './hooks/use-starter-preview'\n",
+        "export type { StarterPreviewValues } from './hooks/use-starter-preview'\nexport { StarterSinglePage } from './components/starter-single-page'\n"
+      );
+      writeFileSync(featuresIndex, content);
+    }
+  }
+}
+
+// src/lib/project-setup.ts
+import { copyFileSync, existsSync as existsSync9, writeFileSync as writeFileSync2 } from "fs";
+import { basename, resolve as resolve14 } from "path";
+function envFileForTier(tier) {
+  return tier === "dev" ? ".env.dev" : tier === "stg" ? ".env.stg" : ".env.prod";
+}
+function tiersToSetup(config, tier) {
+  if (tier) return [tier];
+  return config.env.tiers;
+}
+function firstExisting(paths) {
+  for (const path of paths) {
+    if (existsSync9(path)) return path;
+  }
+  return null;
+}
+function copyMissingFile(projectRoot, targetName, sourceCandidates, dryRun) {
+  const target = resolve14(projectRoot, targetName);
+  if (existsSync9(target)) {
+    return { action: "skipped", path: targetName, detail: "already present" };
+  }
+  const source = firstExisting(sourceCandidates);
+  if (!source) {
+    return {
+      action: "manual",
+      path: targetName,
+      detail: `no template found \u2014 create ${targetName} manually`
+    };
+  }
+  if (!dryRun) {
+    copyFileSync(source, target);
+  }
+  const from = basename(source);
   return {
-    [KIT_DEV_DEP]: KIT_DEV_DEP_VERSION,
-    ...VITE_DEV_PEER_DEPS
+    action: "copied",
+    path: targetName,
+    detail: dryRun ? `[dry-run] would copy ${from} \u2192 ${targetName}` : `copied ${from} \u2192 ${targetName}`
+  };
+}
+function writeMissingFile(projectRoot, targetName, content, dryRun) {
+  const target = resolve14(projectRoot, targetName);
+  if (existsSync9(target)) {
+    return { action: "skipped", path: targetName, detail: "already present" };
+  }
+  if (!dryRun) {
+    writeFileSync2(target, content);
+  }
+  return {
+    action: "copied",
+    path: targetName,
+    detail: dryRun ? `[dry-run] would create ${targetName}` : `created ${targetName}`
   };
 }
+function templateViteFiles(config) {
+  if (isThemeProject(config)) return ["vite.config.dev.mjs"];
+  if (config.projectType === "module-monolith") {
+    return ["vite.config.dev.mjs", "vite.config.monolith.mjs"];
+  }
+  return ["vite.config.dev.mjs", "vite.config.hubspot.mjs", "vite.config.monolith.mjs"];
+}
+function kitTemplateDir(config) {
+  return kitPath("templates", config.projectType);
+}
+function applyProjectSetup(ctx, options = {}) {
+  const { projectRoot, config } = ctx;
+  const dryRun = options.dryRun ?? false;
+  const results = [];
+  const sharedDir = kitPath("templates", "shared");
+  const templateDir = kitTemplateDir(config);
+  results.push(
+    copyMissingFile(projectRoot, HUBSPOT_CONFIG_FILE, [
+      resolve14(projectRoot, HUBSPOT_CONFIG_EXAMPLE),
+      resolve14(templateDir, HUBSPOT_CONFIG_EXAMPLE),
+      kitPath("templates", HUBSPOT_CONFIG_EXAMPLE)
+    ], dryRun)
+  );
+  for (const tier of tiersToSetup(config, options.tier)) {
+    const envFile = envFileForTier(tier);
+    const envExample = `${envFile}.example`;
+    results.push(
+      copyMissingFile(projectRoot, envFile, [
+        resolve14(projectRoot, envExample),
+        resolve14(sharedDir, envExample)
+      ], dryRun)
+    );
+  }
+  if (usesCdnPipeline(config) && !isThemeProject(config)) {
+    const mirror = config.cdn.mirror;
+    results.push(
+      copyMissingFile(projectRoot, mirror, [
+        resolve14(projectRoot, `${mirror}.example`),
+        resolve14(sharedDir, "portal.cdn.json.example")
+      ], dryRun)
+    );
+    const buildIdFile = config.cdn.buildIdFile;
+    results.push(
+      writeMissingFile(projectRoot, buildIdFile, "v0.0.1-dev.1\n", dryRun)
+    );
+  }
+  for (const file of templateViteFiles(config)) {
+    results.push(
+      copyMissingFile(projectRoot, file, [resolve14(templateDir, file)], dryRun)
+    );
+  }
+  if (isModuleProject(config) && !isThemeProject(config)) {
+    const adapter = config.dev.adapter;
+    const adapterPath = resolve14(projectRoot, adapter);
+    if (!existsSync9(adapterPath)) {
+      const templateAdapter = resolve14(templateDir, "wphs.adapter.ts");
+      if (existsSync9(templateAdapter)) {
+        results.push(copyMissingFile(projectRoot, adapter, [templateAdapter], dryRun));
+      } else {
+        results.push({
+          action: "manual",
+          path: adapter,
+          detail: "create wphs.adapter.ts (see docs/ADAPTER.md)"
+        });
+      }
+    } else {
+      results.push({ action: "skipped", path: adapter, detail: "already present" });
+    }
+  }
+  return results;
+}
+function copySharedSetupExamples(targetDir) {
+  const sharedDir = kitPath("templates", "shared");
+  if (!existsSync9(sharedDir)) return;
+  for (const name of [
+    ".env.dev.example",
+    ".env.stg.example",
+    ".env.prod.example",
+    "portal.cdn.json.example"
+  ]) {
+    const src = resolve14(sharedDir, name);
+    const dest = resolve14(targetDir, name);
+    if (existsSync9(src) && !existsSync9(dest)) {
+      copyFileSync(src, dest);
+    }
+  }
+  const hubspotExample = firstExisting([
+    resolve14(sharedDir, HUBSPOT_CONFIG_EXAMPLE),
+    kitPath("templates", HUBSPOT_CONFIG_EXAMPLE)
+  ]);
+  if (!hubspotExample) return;
+  const destHubspot = resolve14(targetDir, HUBSPOT_CONFIG_EXAMPLE);
+  if (!existsSync9(destHubspot) && !existsSync9(resolve14(targetDir, HUBSPOT_CONFIG_FILE))) {
+    copyFileSync(hubspotExample, destHubspot);
+  }
+}
+function formatSetupHint(results) {
+  const hubspot = results.find((r) => r.path === HUBSPOT_CONFIG_FILE && r.action === "copied");
+  if (hubspot) {
+    return `Edit ${HUBSPOT_CONFIG_FILE} \u2014 set portalId and personalAccessKey (https://app.hubspot.com/l/personal-access-key)`;
+  }
+  const envCopied = results.some((r) => r.path.startsWith(".env.") && r.action === "copied");
+  if (envCopied) {
+    return "Edit .env.* files \u2014 set VITE_PUBLIC_REST_API_ENDPOINT and portal IDs for your environment";
+  }
+  return void 0;
+}
 
 // src/lib/project-name.ts
 var PROJECT_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -1194,7 +1951,11 @@ var TEMPLATE_SCRIPTS = {
   "module-monolith": {
     dev: "wp dev",
     local: "wp dev",
-    "build:prod": "wp build --tier prod --hubspot-only",
+    "build:dev": "wp build --tier dev",
+    "build:prod": "wp build --tier prod",
+    "deploy:dev": "wp deploy --tier dev --yes",
+    "deploy:prod": "wp deploy --tier prod --yes",
+    watch: "wp watch --rebuild",
     doctor: "wp doctor"
   },
   "theme-starter": {
@@ -1203,7 +1964,7 @@ var TEMPLATE_SCRIPTS = {
     doctor: "wp doctor"
   }
 };
-function buildConfigForProject(template, projectName) {
+function buildConfigForProject(template, projectName, router) {
   const base = { ...DEFAULT_WOODSPORTAL_HS, projectType: template };
   if (template === "theme-starter") {
     return {
@@ -1216,7 +1977,7 @@ function buildConfigForProject(template, projectName) {
       }
     };
   }
-  return {
+  const config = {
     ...base,
     module: {
       name: projectName,
@@ -1228,9 +1989,13 @@ function buildConfigForProject(template, projectName) {
       mode: template === "module-monolith" ? "none" : base.cdn.mode
     }
   };
+  if (isModuleTemplate(template) && router) {
+    config.scaffold = { router };
+  }
+  return config;
 }
 function assertTargetDirIsScaffoldable(targetDir) {
-  if (!existsSync8(targetDir)) return;
+  if (!existsSync10(targetDir)) return;
   const entries = readdirSync2(targetDir).filter((entry) => entry !== ".DS_Store");
   if (entries.length > 0) {
     throw new WpHsError(`Target directory is not empty: ${targetDir}`, {
@@ -1241,7 +2006,7 @@ function assertTargetDirIsScaffoldable(targetDir) {
 }
 function resolveInitTargetDir(options, interactiveName) {
   if (options.directory) {
-    return resolve12(options.directory);
+    return resolve15(options.directory);
   }
   const parentDir = process.cwd();
   const slug = options.name ?? interactiveName;
@@ -1255,15 +2020,16 @@ function resolveInitTargetDir(options, interactiveName) {
   if (error) {
     throw new WpHsError(error, { exitCode: ExitCode.USER_ERROR });
   }
-  return resolve12(parentDir, slug);
+  return resolve15(parentDir, slug);
 }
 async function runInit(ctx, options) {
   const nonInteractive = ctx.global.ci || ctx.global.yes || ctx.global.json;
   let template = options.template;
   let projectName = options.name ? normalizeProjectName(options.name) : void 0;
+  let router = options.router;
   if (!nonInteractive) {
     if (!template) {
-      const type = await p.select({
+      const type = await p2.select({
         message: "Project type",
         options: [
           {
@@ -1275,58 +2041,92 @@ async function runInit(ctx, options) {
           { value: "theme-starter", label: "Theme starter", hint: "CMS theme templates" }
         ]
       });
-      if (p.isCancel(type)) throw new WpHsError("Init cancelled", { exitCode: ExitCode.USER_ERROR });
+      if (p2.isCancel(type)) throw new WpHsError("Init cancelled", { exitCode: ExitCode.USER_ERROR });
       template = type;
     }
     if (!options.directory && !projectName) {
-      const nameAnswer = await p.text({
+      const nameAnswer = await p2.text({
         message: "Project name (folder name)",
         placeholder: "my-portal-module",
         validate: (value) => validateProjectName(normalizeProjectName(value ?? ""))
       });
-      if (p.isCancel(nameAnswer)) {
+      if (p2.isCancel(nameAnswer)) {
         throw new WpHsError("Init cancelled", { exitCode: ExitCode.USER_ERROR });
       }
       projectName = normalizeProjectName(nameAnswer);
     }
+    if (!router && template && isModuleTemplate(template)) {
+      const routerAnswer = await p2.select({
+        message: "Client-side routing",
+        initialValue: "hash",
+        options: [
+          {
+            value: "hash",
+            label: "Hash history (recommended)",
+            hint: "Same as woodsportal-client-frontend \u2014 works in HubSpot CMS embeds"
+          },
+          {
+            value: "browser",
+            label: "Browser history",
+            hint: "Clean /guide URLs for local dev (not for HubSpot iframe embeds)"
+          },
+          {
+            value: "none",
+            label: "No router",
+            hint: "Single-page starter \u2014 add TanStack Router later"
+          }
+        ]
+      });
+      if (p2.isCancel(routerAnswer)) {
+        throw new WpHsError("Init cancelled", { exitCode: ExitCode.USER_ERROR });
+      }
+      router = routerAnswer;
+    }
   }
   if (!template) {
     template = "module-hybrid-cdn";
   }
+  if (!router && isModuleTemplate(template)) {
+    router = "hash";
+  }
   const targetDir = resolveInitTargetDir(options, projectName);
-  const slug = projectName ?? basename(targetDir);
+  const slug = projectName ?? basename2(targetDir);
   assertTargetDirIsScaffoldable(targetDir);
   const templateDir = kitPath("templates", template);
-  if (!existsSync8(templateDir)) {
+  if (!existsSync10(templateDir)) {
     throw new WpHsError(`Template not found: ${template}`, { exitCode: ExitCode.USER_ERROR });
   }
   if (ctx.global.dryRun) {
     ctx.logger.info(`[dry-run] Would scaffold ${template} in ${targetDir}`);
     return ExitCode.SUCCESS;
   }
-  mkdirSync2(targetDir, { recursive: true });
+  mkdirSync3(targetDir, { recursive: true });
   cpSync2(templateDir, targetDir, { recursive: true });
-  const config = buildConfigForProject(template, slug);
-  writeFileSync(resolve12(targetDir, WOODSCLI_CONFIG_FILE), `${JSON.stringify(config, null, 2)}
+  copySharedSetupExamples(targetDir);
+  const config = buildConfigForProject(template, slug, router);
+  writeFileSync3(resolve15(targetDir, WOODSCLI_CONFIG_FILE), `${JSON.stringify(config, null, 2)}
 `);
-  const pkgPath = resolve12(targetDir, "package.json");
-  if (existsSync8(pkgPath)) {
-    const pkg = JSON.parse(readFileSync5(pkgPath, "utf8"));
+  const pkgPath = resolve15(targetDir, "package.json");
+  if (existsSync10(pkgPath)) {
+    const pkg = JSON.parse(readFileSync8(pkgPath, "utf8"));
     pkg.name = slug;
     pkg.scripts = { ...pkg.scripts, ...TEMPLATE_SCRIPTS[template] };
     pkg.devDependencies = {
       ...pkg.devDependencies,
       ...templateDevDependencies()
     };
-    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
+    writeFileSync3(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `);
   }
+  if (router && isModuleTemplate(template)) {
+    applyRouterScaffold(targetDir, router, template);
+  }
   runNodeScript(kitPath("scripts/ensure-wphs-workspace.mjs"), [], {
     cwd: targetDir,
     logger: ctx.logger,
     dryRun: false
   });
-  const gitignorePath = resolve12(targetDir, ".gitignore");
+  const gitignorePath = resolve15(targetDir, ".gitignore");
   const gitignoreExtras = [
     "hubspot.config.yml",
     ".wphs/config/module-config.local.json",
@@ -1336,18 +2136,19 @@ async function runInit(ctx, options) {
     ".wphs/state/",
     ".wphs/fixtures/hubspot-data.json",
     ".wphs/.kit-module-config",
-    ".wphs/.kit-bootstrap.tsx"
+    ".wphs/.kit-bootstrap.tsx",
+    ".wphs/.kit-bootstrap-greenfield.tsx"
   ];
-  const existing = existsSync8(gitignorePath) ? readFileSync5(gitignorePath, "utf8") : "";
+  const existing = existsSync10(gitignorePath) ? readFileSync8(gitignorePath, "utf8") : "";
   const toAppend = gitignoreExtras.filter((line) => !existing.includes(line)).join("\n");
   if (toAppend) {
-    writeFileSync(gitignorePath, `${existing.trimEnd()}
+    writeFileSync3(gitignorePath, `${existing.trimEnd()}
 ${toAppend}
 `);
   }
   if (!nonInteractive) {
-    p.log.success(`Scaffolded ${template} in ${targetDir}`);
-    p.note(`cd ${slug} && yarn install && wp doctor && wp dev`, "Getting started");
+    p2.log.success(`Scaffolded ${template} in ${targetDir}`);
+    p2.note(`cd ${slug} && yarn install && wp setup && wp doctor && wp dev`, "Getting started");
   } else {
     ctx.logger.success(`Scaffolded ${template} in ${targetDir}`);
   }
@@ -1355,10 +2156,10 @@ ${toAppend}
 }
 
 // src/cli/commands/adopt.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
-import { resolve as resolve13 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
+import { resolve as resolve16 } from "path";
 import { pathToFileURL } from "url";
-import * as p2 from "@clack/prompts";
+import * as p3 from "@clack/prompts";
 async function loadDetectLayout() {
   const mod = await import(pathToFileURL(kitPath("scripts", "detect-layout.mjs")).href);
   return mod.detectProjectLayout;
@@ -1366,7 +2167,7 @@ async function loadDetectLayout() {
 async function runAdopt(ctx, _options = {}) {
   const detectProjectLayout = await loadDetectLayout();
   const layout = detectProjectLayout(ctx.projectRoot);
-  const configPath = resolve13(ctx.projectRoot, WOODSCLI_CONFIG_FILE);
+  const configPath = resolve16(ctx.projectRoot, WOODSCLI_CONFIG_FILE);
   if (layout.track === "unknown") {
     throw new WpHsError("Could not detect module or theme layout.", {
       exitCode: ExitCode.USER_ERROR,
@@ -1378,7 +2179,7 @@ async function runAdopt(ctx, _options = {}) {
     projectType = layout.projectType;
   } else if (layout.track === "theme") {
     projectType = "theme-starter";
-  } else if (existsSync9(resolve13(ctx.projectRoot, "vite.config.monolith.mjs"))) {
+  } else if (existsSync11(resolve16(ctx.projectRoot, "vite.config.monolith.mjs"))) {
     projectType = "module-monolith";
   } else {
     projectType = "module-hybrid-cdn";
@@ -1399,13 +2200,13 @@ async function runAdopt(ctx, _options = {}) {
     ctx.logger.info(`[dry-run] Would adopt as ${projectType} (${layout.track})`);
     return ExitCode.SUCCESS;
   }
-  if (!existsSync9(configPath)) {
-    writeFileSync2(configPath, `${JSON.stringify(config, null, 2)}
+  if (!existsSync11(configPath)) {
+    writeFileSync4(configPath, `${JSON.stringify(config, null, 2)}
 `);
     ctx.logger.success(`Created ${WOODSCLI_CONFIG_FILE}`);
   } else if (!layout.projectType) {
-    const existing = JSON.parse(readFileSync6(configPath, "utf8"));
-    writeFileSync2(configPath, `${JSON.stringify({ ...existing, projectType }, null, 2)}
+    const existing = JSON.parse(readFileSync9(configPath, "utf8"));
+    writeFileSync4(configPath, `${JSON.stringify({ ...existing, projectType }, null, 2)}
 `);
     ctx.logger.info(`Set projectType \u2192 ${projectType}`);
   }
@@ -1414,9 +2215,9 @@ async function runAdopt(ctx, _options = {}) {
     logger: ctx.logger,
     dryRun: false
   });
-  const adapterPath = resolve13(ctx.projectRoot, "wphs.adapter.ts");
-  if (!existsSync9(adapterPath) && isModuleProject(config)) {
-    writeFileSync2(
+  const adapterPath = resolve16(ctx.projectRoot, "wphs.adapter.ts");
+  if (!existsSync11(adapterPath) && isModuleProject(config)) {
+    writeFileSync4(
       adapterPath,
       `import type { HubSpotKitAdapter } from '@woodsportal/hubspot-kit'
 
@@ -1432,11 +2233,11 @@ export default adapter
     ctx.logger.info("Created wphs.adapter.ts stub");
   }
   if (!ctx.global.ci && !ctx.global.quiet) {
-    p2.note(
+    p3.note(
       [
         `Review ${WOODSCLI_CONFIG_FILE} upload paths`,
         "Implement wphs.adapter.ts for your app (if module)",
-        "Add vite.config.dev.mjs re-export if missing",
+        "Run wp setup (copies hubspot.config.yml, .env.*, vite shims)",
         "Patch main.dev.css @source to .wphs/.kit-module-config/**"
       ].join("\n"),
       "Manual follow-ups"
@@ -1447,67 +2248,67 @@ export default adapter
 }
 
 // src/cli/commands/migrate.ts
-import { cpSync as cpSync3, existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync7, readdirSync as readdirSync3, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
-import { join as join3, resolve as resolve14 } from "path";
+import { cpSync as cpSync3, existsSync as existsSync12, mkdirSync as mkdirSync4, readFileSync as readFileSync10, readdirSync as readdirSync3, renameSync, rmSync as rmSync3, writeFileSync as writeFileSync5 } from "fs";
+import { join as join3, resolve as resolve17 } from "path";
 var LEGACY_DIRS = [".dev", ".woodsportal"];
 var LEGACY_BASELINE = ".wp-hs-baseline";
 async function runMigrate(ctx, _options = {}) {
   const root = ctx.projectRoot;
-  const wphsRoot = resolve14(root, WPHS_WORKSPACE_DIR);
+  const wphsRoot = resolve17(root, WPHS_WORKSPACE_DIR);
   const actions = [];
   for (const legacy of LEGACY_DIRS) {
-    const legacyPath = resolve14(root, legacy);
-    if (!existsSync10(legacyPath)) continue;
+    const legacyPath = resolve17(root, legacy);
+    if (!existsSync12(legacyPath)) continue;
     actions.push(`Move ${legacy}/ \u2192 .wphs/`);
     if (ctx.global.dryRun) continue;
-    mkdirSync3(join3(wphsRoot, "config"), { recursive: true });
-    mkdirSync3(join3(wphsRoot, "assets", "branding"), { recursive: true });
+    mkdirSync4(join3(wphsRoot, "config"), { recursive: true });
+    mkdirSync4(join3(wphsRoot, "assets", "branding"), { recursive: true });
     const localConfig = join3(legacyPath, "module-config.local.json");
     const exampleConfig = join3(legacyPath, "module-config.example.json");
-    if (existsSync10(localConfig)) {
+    if (existsSync12(localConfig)) {
       cpSync3(localConfig, join3(wphsRoot, "config", "module-config.local.json"));
     }
-    if (existsSync10(exampleConfig)) {
+    if (existsSync12(exampleConfig)) {
       cpSync3(exampleConfig, join3(wphsRoot, "config", "module-config.example.json"));
     }
     const branding = join3(legacyPath, "branding-assets");
-    if (existsSync10(branding)) {
+    if (existsSync12(branding)) {
       for (const file of readdirSync3(branding)) {
         cpSync3(join3(branding, file), join3(wphsRoot, "assets", "branding", file));
       }
     }
-    rmSync2(legacyPath, { recursive: true, force: true });
+    rmSync3(legacyPath, { recursive: true, force: true });
   }
-  const legacyBaseline = resolve14(root, LEGACY_BASELINE);
+  const legacyBaseline = resolve17(root, LEGACY_BASELINE);
   const targetBaseline = join3(wphsRoot, "audit", "baseline");
-  if (existsSync10(legacyBaseline)) {
+  if (existsSync12(legacyBaseline)) {
     actions.push(`Move ${LEGACY_BASELINE}/ \u2192 .wphs/audit/baseline/`);
     if (!ctx.global.dryRun) {
-      mkdirSync3(targetBaseline, { recursive: true });
+      mkdirSync4(targetBaseline, { recursive: true });
       cpSync3(legacyBaseline, targetBaseline, { recursive: true });
-      rmSync2(legacyBaseline, { recursive: true, force: true });
+      rmSync3(legacyBaseline, { recursive: true, force: true });
     }
   }
-  const legacyConfigPath2 = resolve14(root, LEGACY_WOODSPORTAL_HS_FILE);
-  const woodscliPath = resolve14(root, WOODSCLI_CONFIG_FILE);
-  if (existsSync10(legacyConfigPath2) && !existsSync10(woodscliPath)) {
+  const legacyConfigPath2 = resolve17(root, LEGACY_WOODSPORTAL_HS_FILE);
+  const woodscliPath = resolve17(root, WOODSCLI_CONFIG_FILE);
+  if (existsSync12(legacyConfigPath2) && !existsSync12(woodscliPath)) {
     actions.push(`Rename ${LEGACY_WOODSPORTAL_HS_FILE} \u2192 ${WOODSCLI_CONFIG_FILE}`);
     if (!ctx.global.dryRun) {
       renameSync(legacyConfigPath2, woodscliPath);
     }
-  } else if (existsSync10(legacyConfigPath2) && existsSync10(woodscliPath)) {
+  } else if (existsSync12(legacyConfigPath2) && existsSync12(woodscliPath)) {
     actions.push(`Remove duplicate ${LEGACY_WOODSPORTAL_HS_FILE}`);
     if (!ctx.global.dryRun) {
-      rmSync2(legacyConfigPath2, { force: true });
+      rmSync3(legacyConfigPath2, { force: true });
     }
   }
-  if (existsSync10(woodscliPath)) {
-    const raw = JSON.parse(readFileSync7(woodscliPath, "utf8"));
+  if (existsSync12(woodscliPath)) {
+    const raw = JSON.parse(readFileSync10(woodscliPath, "utf8"));
     if (raw?.dev?.moduleConfigDir && raw.dev.moduleConfigDir !== WPHS_WORKSPACE_DIR) {
       actions.push(`Update dev.moduleConfigDir \u2192 .wphs in project config`);
       if (!ctx.global.dryRun) {
         raw.dev.moduleConfigDir = WPHS_WORKSPACE_DIR;
-        writeFileSync3(woodscliPath, `${JSON.stringify(raw, null, 2)}
+        writeFileSync5(woodscliPath, `${JSON.stringify(raw, null, 2)}
 `);
       }
     }
@@ -1536,10 +2337,10 @@ async function runMigrate(ctx, _options = {}) {
 }
 
 // src/cli/commands/examples.ts
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync11 } from "fs";
 function loadManifest() {
   const manifestPath = kitPath("examples", "manifest.json");
-  const raw = JSON.parse(readFileSync8(manifestPath, "utf8"));
+  const raw = JSON.parse(readFileSync11(manifestPath, "utf8"));
   return raw.scenarios;
 }
 async function runExamplesList(ctx, options = {}) {
@@ -1559,7 +2360,7 @@ async function runExamplesSmoke(ctx, options = {}) {
   const tier = options.tier ?? "static";
   const args = ["--tier", tier];
   if (options.scenario) args.push("--scenario", options.scenario);
-  const { runNodeScript: runNodeScript2 } = await import("./exec-K5C6LZP4.js");
+  const { runNodeScript: runNodeScript2 } = await import("./exec-U2OJATR3.js");
   runNodeScript2(kitPath("examples", "smoke", "run-matrix.mjs"), args, {
     cwd: ctx.projectRoot,
     logger: ctx.logger,
@@ -1572,15 +2373,15 @@ async function runExamplesSmoke(ctx, options = {}) {
 }
 
 // src/cli/commands/fields.ts
-import { cpSync as cpSync4, existsSync as existsSync11, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
-import { resolve as resolve15 } from "path";
+import { cpSync as cpSync4, existsSync as existsSync13, readFileSync as readFileSync12, writeFileSync as writeFileSync6 } from "fs";
+import { resolve as resolve18 } from "path";
 async function runFieldsSync(ctx, options = {}) {
   const direction = options.direction ?? "pull";
-  const fieldsPath = resolve15(ctx.projectRoot, ctx.config.dev.fieldsJson);
-  const cacheDir = resolve15(ctx.projectRoot, ctx.config.dev.moduleConfigDir, "cache", "fields-sync");
-  const cachePath = resolve15(cacheDir, "fields.json");
+  const fieldsPath = resolve18(ctx.projectRoot, ctx.config.dev.fieldsJson);
+  const cacheDir = resolve18(ctx.projectRoot, ctx.config.dev.moduleConfigDir, "cache", "fields-sync");
+  const cachePath = resolve18(cacheDir, "fields.json");
   if (direction === "pull") {
-    if (!existsSync11(fieldsPath)) {
+    if (!existsSync13(fieldsPath)) {
       throw new WpHsError(`Missing ${ctx.config.dev.fieldsJson}`, {
         exitCode: ExitCode.USER_ERROR,
         remediation: "Add fields.json or run wp init."
@@ -1590,13 +2391,13 @@ async function runFieldsSync(ctx, options = {}) {
       ctx.logger.info(`[dry-run] Would cache ${fieldsPath} \u2192 ${cachePath}`);
       return ExitCode.SUCCESS;
     }
-    const { mkdirSync: mkdirSync4 } = await import("fs");
-    mkdirSync4(cacheDir, { recursive: true });
+    const { mkdirSync: mkdirSync5 } = await import("fs");
+    mkdirSync5(cacheDir, { recursive: true });
     cpSync4(fieldsPath, cachePath);
     ctx.logger.success(`Cached fields \u2192 ${cachePath}`);
     return ExitCode.SUCCESS;
   }
-  if (!existsSync11(cachePath)) {
+  if (!existsSync13(cachePath)) {
     throw new WpHsError("No cached fields \u2014 run wp fields sync pull first.", {
       exitCode: ExitCode.USER_ERROR
     });
@@ -1605,14 +2406,14 @@ async function runFieldsSync(ctx, options = {}) {
     ctx.logger.info(`[dry-run] Would write ${cachePath} \u2192 ${fieldsPath}`);
     return ExitCode.SUCCESS;
   }
-  writeFileSync4(fieldsPath, readFileSync9(cachePath, "utf8"));
+  writeFileSync6(fieldsPath, readFileSync12(cachePath, "utf8"));
   ctx.logger.success(`Restored fields from cache \u2192 ${fieldsPath}`);
   return ExitCode.SUCCESS;
 }
 
 // src/cli/commands/regression.ts
-import { existsSync as existsSync12 } from "fs";
-import { resolve as resolve16 } from "path";
+import { existsSync as existsSync14 } from "fs";
+import { resolve as resolve19 } from "path";
 var LEGACY_SHIM_SCRIPTS = [
   "build-cdn.mjs",
   "run-vite-build.mjs",
@@ -1635,21 +2436,21 @@ async function runRegressionSmoke(ctx, options = {}) {
   if (!validateOk) failures.push("wp config validate failed");
   if (options.checkLegacyShims !== false) {
     for (const script of LEGACY_SHIM_SCRIPTS) {
-      const shim = resolve16(ctx.projectRoot, "scripts", script);
+      const shim = resolve19(ctx.projectRoot, "scripts", script);
       const kitScript = kitPath("scripts", script);
-      const shimOk = existsSync12(shim) && existsSync12(kitScript);
+      const shimOk = existsSync14(shim) && existsSync14(kitScript);
       checks.push({ name: `shim:${script}`, ok: shimOk });
       if (!shimOk) failures.push(`Missing legacy shim or kit script: ${script}`);
     }
   }
   for (const rel of FORBIDDEN_CONSUMER_PATHS) {
-    const forbidden = resolve16(ctx.projectRoot, rel);
-    const absent = !existsSync12(forbidden);
+    const forbidden = resolve19(ctx.projectRoot, rel);
+    const absent = !existsSync14(forbidden);
     checks.push({ name: `no-${rel}`, ok: absent });
     if (!absent) failures.push(`Forbidden dev path still present: ${rel}`);
   }
-  const woodscliConfig = resolve16(ctx.projectRoot, WOODSCLI_CONFIG_FILE);
-  const configOk = existsSync12(woodscliConfig);
+  const woodscliConfig = resolve19(ctx.projectRoot, WOODSCLI_CONFIG_FILE);
+  const configOk = existsSync14(woodscliConfig);
   checks.push({ name: WOODSCLI_CONFIG_FILE, ok: configOk });
   if (!configOk) failures.push(`${WOODSCLI_CONFIG_FILE} missing`);
   if (ctx.global.json) {
@@ -1673,43 +2474,260 @@ async function runRegressionSmoke(ctx, options = {}) {
   return ExitCode.SUCCESS;
 }
 
+// src/cli/commands/setup.ts
+async function runSetup(ctx, options = {}) {
+  let results = [];
+  await runCliTasks(
+    ctx,
+    [
+      {
+        title: "Preparing .wphs workspace",
+        task: async () => {
+          if (ctx.global.dryRun) return;
+          try {
+            runNodeScript(kitPath("scripts", "ensure-wphs-workspace.mjs"), [], {
+              cwd: ctx.projectRoot,
+              logger: ctx.logger,
+              dryRun: false
+            });
+          } catch {
+          }
+        }
+      },
+      {
+        title: "Copying missing config files",
+        task: async () => {
+          results = applyProjectSetup(ctx, {
+            tier: options.tier,
+            dryRun: ctx.global.dryRun
+          });
+        }
+      }
+    ],
+    options
+  );
+  const copied = results.filter((r) => r.action === "copied");
+  const manual = results.filter((r) => r.action === "manual");
+  if (ctx.global.json) {
+    ctx.logger.json({
+      command: "setup",
+      ok: manual.length === 0,
+      copied: copied.length,
+      skipped: results.filter((r) => r.action === "skipped").length,
+      manual,
+      results
+    });
+  } else {
+    for (const result of results) {
+      if (result.action === "skipped") continue;
+      if (result.action === "copied") {
+        ctx.logger.success(result.detail);
+      } else {
+        ctx.logger.warn(`${result.path}: ${result.detail}`);
+      }
+    }
+    if (copied.length === 0 && manual.length === 0) {
+      printCommandDone(ctx, "Nothing to copy \u2014 required files already present");
+    } else if (copied.length > 0) {
+      printCommandDone(ctx, `Setup complete \u2014 ${copied.length} file(s) copied`);
+    }
+    const hint = formatSetupHint(results);
+    if (hint) {
+      ctx.logger.info(`\u2192 ${hint}`);
+    }
+    if (manual.length > 0) {
+      ctx.logger.info("\u2192 Run wp doctor for the full checklist");
+    }
+  }
+  return ExitCode.SUCCESS;
+}
+
+// src/cli/commands/portal.ts
+import * as p4 from "@clack/prompts";
+
+// src/lib/hubspot-portals.ts
+import { existsSync as existsSync15, readFileSync as readFileSync13 } from "fs";
+import { resolve as resolve20 } from "path";
+function stripYamlScalar(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function parseHubSpotConfigPortals(raw) {
+  const defaultMatch = raw.match(/^defaultPortal:\s*(.+)\s*$/m);
+  const defaultPortal = defaultMatch ? stripYamlScalar(defaultMatch[1]) : null;
+  const portals = [];
+  let current = null;
+  let inPortals = false;
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "portals:") {
+      inPortals = true;
+      continue;
+    }
+    if (!inPortals) continue;
+    const listItemName = line.match(/^\s+-\s+name:\s+(.+)\s*$/);
+    const nestedName = line.match(/^\s+name:\s+(.+)\s*$/);
+    const portalId = line.match(/^\s+portalId:\s+(\d+)\s*$/);
+    if (listItemName || nestedName && !line.match(/^\s+-\s/)) {
+      if (current) portals.push(current);
+      const nameValue = listItemName?.[1] ?? nestedName?.[1];
+      current = nameValue ? { name: stripYamlScalar(nameValue) } : null;
+      continue;
+    }
+    if (portalId && current) {
+      current.portalId = portalId[1];
+    }
+  }
+  if (current) portals.push(current);
+  return { defaultPortal, portals };
+}
+function readHubSpotPortals(projectRoot) {
+  const configPath = resolve20(projectRoot, HUBSPOT_CONFIG_FILE);
+  if (!existsSync15(configPath)) {
+    throw new WpHsError(`${HUBSPOT_CONFIG_FILE} not found in project root.`, {
+      exitCode: ExitCode.USER_ERROR,
+      remediation: "Run wp setup, then add your portal + PAT."
+    });
+  }
+  const raw = readFileSync13(configPath, "utf8");
+  const { defaultPortal, portals } = parseHubSpotConfigPortals(raw);
+  return { configPath, defaultPortal, portals };
+}
+function resolvePortalName(portals, nameOrId) {
+  const needle = nameOrId.trim();
+  return portals.find((p5) => p5.name === needle) ?? portals.find((p5) => p5.portalId === needle) ?? null;
+}
+
+// src/cli/commands/portal.ts
+function formatPortalLine(portal, defaultPortal) {
+  const id = portal.portalId ? `portalId ${portal.portalId}` : "portalId ?";
+  const mark = portal.name === defaultPortal ? " \xB7 default" : "";
+  return `${portal.name} (${id})${mark}`;
+}
+async function runPortalList(ctx, _options = {}) {
+  const data = readHubSpotPortals(ctx.projectRoot);
+  if (ctx.global.json) {
+    ctx.logger.json({
+      command: "portal:list",
+      configPath: data.configPath,
+      defaultPortal: data.defaultPortal,
+      portals: data.portals
+    });
+    return ExitCode.SUCCESS;
+  }
+  if (data.portals.length === 0) {
+    ctx.logger.warn(`No portals[] entries found in ${data.configPath}`);
+    ctx.logger.info("\u2192 Add portals under hubspot.config.yml or run hs auth");
+    return ExitCode.SUCCESS;
+  }
+  if (data.defaultPortal) {
+    ctx.logger.info(`Default: ${data.defaultPortal}`);
+  }
+  for (const portal of data.portals) {
+    ctx.logger.info(formatPortalLine(portal, data.defaultPortal));
+  }
+  return ExitCode.SUCCESS;
+}
+async function runPortalUse(ctx, options = {}) {
+  const data = readHubSpotPortals(ctx.projectRoot);
+  if (data.portals.length === 0) {
+    throw new WpHsError("No portals configured in hubspot.config.yml", {
+      exitCode: ExitCode.USER_ERROR,
+      remediation: "Run wp auth or add portals[] to hubspot.config.yml"
+    });
+  }
+  let targetName = options.name?.trim();
+  if (!targetName) {
+    if (ctx.global.ci || ctx.global.json) {
+      throw new WpHsError("Portal name or id required in non-interactive mode", {
+        exitCode: ExitCode.USER_ERROR,
+        remediation: "wp portal use <name>"
+      });
+    }
+    if (!isInteractiveCli(ctx)) {
+      throw new WpHsError("Portal name or id required", {
+        exitCode: ExitCode.USER_ERROR,
+        remediation: "wp portal use <name>  \xB7  wp portal list"
+      });
+    }
+    const answer = await p4.select({
+      message: "Set default HubSpot portal",
+      options: data.portals.map((portal2) => ({
+        value: portal2.name,
+        label: portal2.name,
+        hint: portal2.name === data.defaultPortal ? `current default \xB7 ${portal2.portalId ?? "no id"}` : portal2.portalId ?? void 0
+      }))
+    });
+    if (p4.isCancel(answer)) {
+      throw new WpHsError("Portal selection cancelled", { exitCode: ExitCode.USER_ERROR });
+    }
+    targetName = answer;
+  }
+  const portal = resolvePortalName(data.portals, targetName);
+  if (!portal) {
+    throw new WpHsError(`Unknown portal: ${targetName}`, {
+      exitCode: ExitCode.USER_ERROR,
+      remediation: "wp portal list"
+    });
+  }
+  if (ctx.global.dryRun) {
+    ctx.logger.info(`[dry-run] hs accounts use ${portal.name}`);
+    return ExitCode.SUCCESS;
+  }
+  runCommand("hs", ["accounts", "use", portal.name], {
+    cwd: ctx.projectRoot,
+    logger: ctx.logger,
+    dryRun: false
+  });
+  if (!ctx.global.json && !ctx.global.quiet) {
+    printCommandDone(ctx, `Default portal \u2192 ${portal.name}`);
+  } else if (ctx.global.json) {
+    ctx.logger.json({
+      command: "portal:use",
+      ok: true,
+      defaultPortal: portal.name,
+      portalId: portal.portalId ?? null
+    });
+  }
+  return ExitCode.SUCCESS;
+}
+
 // src/cli/commands/watch.ts
 async function runWatch(ctx, options) {
-  ensureHubSpotCliSetup(ctx, "cms");
+  ensureHubSpotConfigForCms(ctx);
   const tier = options.tier ?? "dev";
-  const args = [];
-  if (tier === "prod") args.push("--prod");
+  const args = ["--tier", tier];
   if (options.rebuild) args.push("--rebuild");
-  try {
-    runNodeScript(kitPath("scripts", "watch-hubspot.mjs"), args, {
-      cwd: ctx.projectRoot,
-      env: { ...process.env, WP_HS_PROJECT_ROOT: ctx.projectRoot },
-      logger: ctx.logger,
-      dryRun: ctx.global.dryRun
-    });
-    return ExitCode.SUCCESS;
-  } catch (error) {
-    throw new WpHsError("Watch failed", {
+  const code = await runNodeScriptLongRunning(kitPath("scripts", "watch-hubspot.mjs"), args, {
+    cwd: ctx.projectRoot,
+    env: { ...process.env, WP_HS_PROJECT_ROOT: ctx.projectRoot },
+    logger: ctx.logger,
+    dryRun: ctx.global.dryRun
+  });
+  if (code === 130 || code === 143) {
+    return code;
+  }
+  if (code !== ExitCode.SUCCESS) {
+    throw new WpHsError(`Watch exited with code ${code}`, {
       exitCode: ExitCode.BUILD_FAILED,
-      cause: error,
-      remediation: "Ensure HubSpot module is built once before watch, or pass --rebuild."
+      remediation: "Run wp build once, then wp watch. For src/ changes use wp watch --rebuild. Check hubspot.config.yml and hs cms watch output."
     });
   }
+  return ExitCode.SUCCESS;
 }
 
 // src/cli/program.ts
 function readVersion() {
   try {
-    const pkg = JSON.parse(readFileSync10(resolve17(getKitRoot(), "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync14(resolve21(getKitRoot(), "package.json"), "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
-function parseTier(value) {
-  if (value === "dev" || value === "stg" || value === "prod") return value;
-  return "prod";
-}
 function buildContext(global) {
   const logger = createLogger({
     verbose: global.verbose,
@@ -1750,33 +2768,45 @@ function createProgram() {
     const global = program2.opts();
     await handle(() => runDoctor(buildContext(global)));
   });
-  const configCmd = program2.command("config").description("Project configuration");
-  configCmd.command("validate").description("Validate woodscli.json").action(async () => {
-    const global = program2.opts();
-    await handle(() => runConfigValidate(buildContext(global)));
-  });
-  program2.command("init").description("Scaffold a new module or theme project").option("-t, --template <type>", "module-hybrid-cdn | module-monolith | theme-starter").option("-n, --name <slug>", "Project name (creates ./<name>/ under cwd)").option("-d, --directory <path>", "Full target directory (skips name \u2192 folder prompt)").action(async (opts) => {
+  program2.command("setup").description("Copy missing hubspot.config.yml, .env.*, CDN config, and vite shims from kit templates").option("--tier <tier>", "dev | stg | prod \u2014 copy only this .env file (default: all env.tiers)").action(async (opts) => {
     const global = program2.opts();
-    const logger = createLogger({
-      verbose: global.verbose,
-      quiet: global.quiet,
-      json: global.json,
-      ci: global.ci
-    });
-    const ctx = {
-      projectRoot: process.cwd(),
-      config: DEFAULT_WOODSPORTAL_HS,
-      logger,
-      global
-    };
     await handle(
-      () => runInit(ctx, {
-        template: opts.template,
-        name: opts.name,
-        directory: opts.directory
+      () => runSetup(buildContext(global), {
+        tier: opts.tier ? parseBuildTier(opts.tier) : void 0
       })
     );
   });
+  const configCmd = program2.command("config").description("Project configuration");
+  configCmd.command("validate").description("Validate woodscli.json").action(async () => {
+    const global = program2.opts();
+    await handle(() => runConfigValidate(buildContext(global)));
+  });
+  program2.command("init").description("Scaffold a new module or theme project").option("-t, --template <type>", "module-hybrid-cdn | module-monolith | theme-starter").option("-n, --name <slug>", "Project name (creates ./<name>/ under cwd)").option("-d, --directory <path>", "Full target directory (skips name \u2192 folder prompt)").option("--router <mode>", "hash (client-frontend default) | browser | none \u2014 modules only").action(
+    async (opts) => {
+      const global = program2.opts();
+      const logger = createLogger({
+        verbose: global.verbose,
+        quiet: global.quiet,
+        json: global.json,
+        ci: global.ci
+      });
+      const ctx = {
+        projectRoot: process.cwd(),
+        config: DEFAULT_WOODSPORTAL_HS,
+        logger,
+        global
+      };
+      const routerMode = opts.router === "browser" || opts.router === "none" || opts.router === "hash" ? opts.router : void 0;
+      await handle(
+        () => runInit(ctx, {
+          template: opts.template,
+          name: opts.name,
+          directory: opts.directory,
+          router: routerMode
+        })
+      );
+    }
+  );
   program2.command("adopt").description("Detect existing module/theme repo and add WoodsCLI config + .wphs/").action(async () => {
     const global = program2.opts();
     await handle(() => runAdopt(buildContext(global)));
@@ -1789,12 +2819,12 @@ function createProgram() {
     const global = program2.opts();
     await handle(() => runDev(buildContext(global), { port: Number(opts.port) }));
   });
-  program2.command("build").description("Build CDN + HubSpot module (or theme no-op)").option("--tier <tier>", "dev | stg | prod", "prod").option("--cdn-only", "CDN chunks only").option("--hubspot-only", "HubSpot module only").option("--cdn-esm", "Build CDN via ESM preset").action(
+  program2.command("build").description("Build CDN + HubSpot module (or theme no-op)").option("--tier <tier>", "dev | stg | prod", DEFAULT_BUILD_TIER).option("--cdn-only", "CDN chunks only").option("--hubspot-only", "HubSpot module only").option("--cdn-esm", "Build CDN via ESM preset").action(
     async (opts) => {
       const global = program2.opts();
       await handle(
         () => runBuild(buildContext(global), {
-          tier: parseTier(opts.tier),
+          tier: parseBuildTier(opts.tier),
           cdnOnly: opts.cdnOnly,
           hubspotOnly: opts.hubspotOnly,
           cdnEsm: opts.cdnEsm
@@ -1802,20 +2832,20 @@ function createProgram() {
       );
     }
   );
-  program2.command("deploy").description("Build, publish CDN, upload HubSpot module").option("--tier <tier>", "dev | stg | prod", "prod").option("--skip-publish", "Skip CDN publish").action(async (opts) => {
+  program2.command("deploy").description("Build, publish CDN, upload HubSpot module").option("--tier <tier>", "dev | stg | prod", DEFAULT_BUILD_TIER).option("--skip-publish", "Skip CDN publish").action(async (opts) => {
     const global = program2.opts();
     await handle(
       () => runDeploy(buildContext(global), {
-        tier: parseTier(opts.tier),
+        tier: parseBuildTier(opts.tier),
         skipPublish: opts.skipPublish
       })
     );
   });
-  program2.command("publish").description("Publish CDN artifacts to jsDelivr mirror").option("--tier <tier>", "dev | stg | prod", "prod").option("--dry-run", "Print publish plan without pushing").action(async (opts) => {
+  program2.command("publish").description("Publish CDN artifacts to jsDelivr mirror").option("--tier <tier>", "dev | stg | prod", DEFAULT_BUILD_TIER).option("--dry-run", "Print publish plan without pushing").action(async (opts) => {
     const global = program2.opts();
     await handle(
       () => runPublish(buildContext(global), {
-        tier: parseTier(opts.tier),
+        tier: parseBuildTier(opts.tier),
         dryRun: opts.dryRun
       })
     );
@@ -1871,9 +2901,9 @@ function createProgram() {
       () => runRegressionSmoke(buildContext(global), { skipDoctor: opts.skipDoctor })
     );
   });
-  program2.command("watch").description("Watch HubSpot module or theme folder and re-upload on change").option("--tier <tier>", "dev | stg | prod", "dev").option("--rebuild", "Rebuild module before watch").action(async (opts) => {
+  program2.command("watch").description("Watch HubSpot module or theme folder and re-upload on change").option("--tier <tier>", "dev | stg | prod", DEFAULT_BUILD_TIER).option("--rebuild", "Rebuild module before watch").action(async (opts) => {
     const global = program2.opts();
-    const tier = parseTier(opts.tier);
+    const tier = parseBuildTier(opts.tier);
     await handle(
       () => runWatch(buildContext(global), {
         tier: tier === "prod" ? "prod" : tier === "stg" ? "stg" : "dev",
@@ -1881,16 +2911,16 @@ function createProgram() {
       })
     );
   });
-  program2.command("upload").description("Upload built HubSpot module or theme (hs cms upload)").option("--tier <tier>", "dev | stg | prod", "prod").action(async (opts) => {
+  program2.command("upload").description("Upload built HubSpot module or theme (hs cms upload)").option("--tier <tier>", "dev | stg | prod", DEFAULT_BUILD_TIER).action(async (opts) => {
     const global = program2.opts();
     await handle(
-      () => runUpload(buildContext(global), { tier: parseTier(opts.tier) })
+      () => runUpload(buildContext(global), { tier: parseBuildTier(opts.tier) })
     );
   });
   program2.command("auth").description("Authenticate HubSpot CLI (hs auth)").action(async () => {
     const global = program2.opts();
     const ctx = buildContext(global);
-    const { runCommand: runCommand2 } = await import("./exec-K5C6LZP4.js");
+    const { runCommand: runCommand2 } = await import("./exec-U2OJATR3.js");
     runCommand2("hs", ["auth"], {
       cwd: ctx.projectRoot,
       logger: ctx.logger,
@@ -1898,6 +2928,15 @@ function createProgram() {
     });
     process.exit(ExitCode.SUCCESS);
   });
+  const portal = program2.command("portal").description("HubSpot default portal selection");
+  portal.command("list").alias("ls").description("List portals from hubspot.config.yml").action(async () => {
+    const global = program2.opts();
+    await handle(() => runPortalList(buildContext(global)));
+  });
+  portal.command("use [name]").description("Set defaultPortal (hs accounts use)").action(async (name) => {
+    const global = program2.opts();
+    await handle(() => runPortalUse(buildContext(global), { name }));
+  });
   return program2;
 }